CLI and MCP interfaces
Paperclip exposes its control plane through two machine-facing interfaces. The paperclipai CLI helps an operator install, configure, run, and inspect a local instance or call the Paperclip API. The MCP server gives an agent typed tools for reading and changing Paperclip work through the same API. This page complements Extensibility platform, Plugin platform, and External app connections.
CLI client
The paperclipai CLI is the operator entry point for the Paperclip lifecycle. It combines local instance management with API commands for companies, agents, issues, workspaces, runs, adapters, assets, skills, plugins, and related work controls. It also provides an isolated test drive and commands for MCP and agent runtime setup. (cli/…/index.ts• L64-73, cli/…/index.ts• L105-130.)
Command lifecycle
Each invocation resolves its data scope, loads the selected environment, starts telemetry, and then runs a local action or an API request. The test-drive command establishes its isolated environment before the normal configuration hook runs. Errors produce a non-zero exit status, and telemetry is flushed before exit. (cli/…/index.ts• L105-127, cli/…/index.ts• L285-303.)
The CLI has three related command groups:
- Local instance commands set up, configure, diagnose, run, and supervise Paperclip.
- Client commands call the Paperclip API with shared context and authentication rules.
- Integration commands connect an assistant through MCP or install a selected agent runtime.
Client commands share a context resolver. It combines command options, environment values, the active profile, stored credentials, company scope, and optional heartbeat-run scope. (cli/…/common.ts• L30-109.)
References: cli/…/index.ts• L105-130 cli/…/index.ts• L200-303 cli/…/common.ts• L30-109
Installation and update lifecycle
The install and update commands manage the CLI before it manages a Paperclip instance. A managed install keeps versioned payloads in a private store and exposes the active payload through a user-level paperclipai shim. Install can use a release, canary, exact version, or approved Git reference. (cli/…/install.ts• L87-139, cli/…/install.ts• L162-182, cli/…/install-store.ts• L70-114.)
Managed updates normally back up the database, activate the new payload, restart an active service, and validate health. If validation fails, the CLI restores the previous payload and tries to restart it. Payload rollback does not reverse database migrations. Git-based changes require consent because they can download and run repository code. (cli/…/update.ts• L167-273, cli/…/install-store.ts• L147-202.)
References: cli/…/install.ts• L87-139 cli/…/install.ts• L162-182 cli/…/install.ts• L247-307 cli/…/update.ts• L78-139 cli/…/update.ts• L167-273 cli/…/install-store.ts• L70-114 cli/…/install-store.ts• L147-202
Onboarding path
Onboarding turns an empty local home into a usable Paperclip instance. Quickstart uses trusted loopback access by default. Advanced setup lets the operator choose the database, model provider, server reach, storage, backup, and secret settings. (cli/…/onboard.ts• L173-361, cli/…/onboard.ts• L519-579.)
The first-run path moves through these stages:
flowchart LR
A[No local config] --> B[Quickstart or advanced choices]
B --> C[Create auth and signing secrets]
C --> D[Save validated config and local key]
D --> E[Optional bootstrap admin invite]
E --> F[Background service or foreground run]
The saved configuration becomes the default for later commands. The run command can repeat this path by onboarding when needed, completing deferred worktree setup, repairing local state, starting the server, and creating an initial admin invite when required. (cli/…/run.ts• L49-142, cli/…/onboard.ts• L760-797.)
Onboarding does not silently install a background service in a non-interactive --yes run. An operator must use --install-service. Interactive setup can offer the choice, while --no-install-service disables it. (cli/…/onboard-service.ts• L227-290.)
References: cli/…/onboard.ts• L173-361 cli/…/onboard.ts• L519-579 cli/…/onboard.ts• L687-797 cli/…/run.ts• L49-142 cli/…/onboard-service.ts• L227-290
Test-drive path
The test-drive command starts a local Paperclip instance for manual agent testing. It uses a retained temporary or selected data directory, private loopback access, an embedded database, and a usable local port. It clears inherited Paperclip routing before normal CLI configuration so the test does not silently attach to another instance. (cli/…/test-drive.ts• L134-232, cli/…/index.ts• L105-126.)
The command can create or reuse one test company and one CEO agent. It validates the selected harness, model, provider credential, and OpenCode model before the first database mutation. Literal credentials are removed from visible arguments and redacted from startup errors. (cli/…/test-drive.ts• L234-285, cli/…/test-drive.ts• L330-407.)
In a linked Git worktree, test drive arms the instance setting that permits tasks to run there. It verifies that the setting belongs to the current instance. The browser opens after initialization unless --no-browser is used. (cli/…/test-drive.ts• L287-327, cli/…/test-drive.ts• L409-490.)
References: cli/…/test-drive.ts• L134-232 cli/…/test-drive.ts• L234-285 cli/…/test-drive.ts• L287-327 cli/…/test-drive.ts• L330-490
Configuration model
The CLI treats configuration as a validated description of one Paperclip instance. It can select a path from an explicit option, an environment value, a repository-local .paperclip/config.json, or the default instance home. Writes preserve unknown settings and use safe replacement rules. (cli/…/store.ts• L16-38, cli/…/store.ts• L48-100, cli/…/store.ts• L186-228.)
configure changes one settings area without rebuilding the instance. Onboarding and worktree setup also maintain an adjacent environment file for local values such as agent authentication and tool-action signing. Doctor can repair selected resources and check the repaired state again. (cli/…/onboard.ts• L687-726, cli/…/env.ts• L44-145, cli/…/doctor.ts• L184-199.)
Secrets use either a local encrypted provider or AWS Secrets Manager. The local provider needs a validated key. AWS uses deployment, region, and KMS settings while credentials come from the AWS SDK default chain. (cli/…/secrets-check.ts• L32-200.)
References: cli/…/store.ts• L16-100 cli/…/store.ts• L186-228 cli/…/onboard.ts• L687-726 cli/…/env.ts• L44-145 cli/…/doctor.ts• L184-199 cli/…/secrets-check.ts• L32-200
Client context and access
A client context is a named profile for an API base, company, persona, agent, and API-key environment variable. The active profile supplies defaults, while command options and environment values can override them. This lets one CLI address several Paperclip instances or identities. (cli/…/context.ts• L8-24, cli/…/context.ts• L30-129.)
connect guides a board operator or agent through health checks, company or agent selection, API-key creation, profile storage, and shell export output. The shared HTTP client sends bearer authentication and can carry an active heartbeat run through X-Paperclip-Run-Id. (cli/…/connect.ts• L37-156, cli/…/common.ts• L48-99.)
Board authentication uses a browser approval challenge when a board-level identity is needed. The CLI polls until approval, honors server retry delay without extending the challenge deadline, verifies the resulting identity, and stores the credential per API base. (cli/…/board-auth.ts• L208-305.)
References: cli/…/context.ts• L8-24 cli/…/context.ts• L126-215 cli/…/context.ts• L30-129 cli/…/connect.ts• L37-156 cli/…/common.ts• L30-99 cli/…/board-auth.ts• L68-145 cli/…/board-auth.ts• L208-305
Agent lifecycle
The agent command group manages an agent from creation or hiring through approval, pause, resume, heartbeat, termination, and removal. It also exposes permission controls, configuration history, runtime sessions, skills, and instruction bundles so an operator can manage execution state and agent guidance together. (cli/…/agent.ts• L229-449, cli/…/agent.ts• L451-735, cli/…/agent.ts• L794-827.)
local-cli prepares an agent for local tool use. It creates an agent API key, can link Paperclip skills into local assistant directories, and prints shell exports for the API URL, company, agent, and key. Destructive instruction-file deletion requires explicit confirmation. (cli/…/agent.ts• L730-927.)
References: cli/…/agent.ts• L229-449 cli/…/agent.ts• L451-735 cli/…/agent.ts• L794-927
Company scope
Company commands keep API work inside the company allowed by the current identity. current uses an explicit company when supplied or resolves the company through the authenticated agent. Creating a company needs board or instance-admin authentication. (cli/…/company.ts• L1346-1500, cli/…/company.ts• L2010-2030.)
Company deletion resolves a target by ID or issue prefix. Automatic resolution rejects an ambiguous match, and the destructive request requires both --yes and a confirmation value that matches the target ID or prefix. (cli/…/company.ts• L1273-1333, cli/…/company.ts• L1915-1997, cli/…/company-delete.test.ts• L34-98.)
Company portability supports export and import. Export writes a package that can be read from a directory or archive. Import previews changes, supports new or existing company targets, lets an operator choose packaged entities and files, and applies collision rules. Explicit confirmation is required for JSON or non-interactive apply. (cli/…/company.ts• L263-405, cli/…/company.ts• L774-816.)
Large imports use a resumable transfer instead of placing the full package in one request. The CLI declares archive size and hashes, uploads only missing parts with retries, then sends preview and apply requests that refer to the server-side transfer. (cli/…/company-import-transfer.test.ts• L47-67, cli/…/company-import-transfer.test.ts• L108-335.)
References: cli/…/company.ts• L263-405 cli/…/company.ts• L774-816 cli/…/company.ts• L1273-1333 cli/…/company.ts• L1346-1500 cli/…/company.ts• L1915-1997 cli/…/company.ts• L2010-2030 cli/…/zip.ts• L3-107 cli/…/company-delete.test.ts• L34-98 cli/…/company-import-export-e2e.test.ts• L356-642 cli/…/company-import-transfer.test.ts• L47-335
Issue work loop
The issue command group gives operators and agents a direct API surface for the work record that coordinates execution. It covers discovery and change, comments, documents, work products, approvals, feedback, attachments, interactions, recovery actions, and checkout or release. Inputs are checked before requests are sent, and results can use compact terminal output or JSON. (cli/…/issue.ts• L172-365, cli/…/issue.ts• L722-935, cli/…/issue.ts• L1170-1335.)
Checkout claims work for an agent. Release clears execution locks for every issue, but clears the assignee only for unfinished work. Done and Cancelled issues keep their final assignee visible. (cli/…/issue.ts• L722-935, cli/…/issue.ts• L1296-1335.)
References: cli/…/issue.ts• L172-365 cli/…/issue.ts• L722-935 cli/…/issue.ts• L938-1017 cli/…/issue.ts• L1170-1335
Service management
The service layer keeps a local Paperclip instance running outside an open terminal. The CLI uses launchd on macOS and a user-level systemd manager on supported Linux sessions. Other environments use paperclipai run in the foreground. (cli/…/service-manager.ts• L289-303.)
Supervisor lifecycle
service install checks that the managed paperclipai command shim exists, creates an instance-specific supervisor definition, and can start it at once. start, stop, restart, status, and logs then manage or inspect that instance. Status combines supervisor state with a local health check. (cli/…/service.ts• L166-233, cli/…/onboard-service.ts• L141-201.)
The supervisor starts the same paperclipai run --instance <id> path used by foreground operation. A validated runtime record identifies the process and dashboard address. Readiness checks verify process ownership and local health. (cli/…/service-manager.ts• L74-107, cli/…/runtime-info.ts• L5-81, cli/…/run.ts• L49-142.)
References: cli/…/service-manager.ts• L23-37 cli/…/service-manager.ts• L74-107 cli/…/service-manager.ts• L180-203 cli/…/service-manager.ts• L289-311 cli/…/service.ts• L166-233 cli/…/onboard-service.ts• L141-201 cli/…/runtime-info.ts• L5-81 cli/…/run.ts• L49-142
Hot restart behavior
A managed restart records the old process, takes an instance restart lock, restarts the supervisor, and waits for health. It can adopt active agent runs or wait for them to drain. The foreground safety check prevents two processes from owning one instance unless the operator explicitly bypasses it. (cli/…/service.ts• L57-161, cli/…/service-manager.ts• L305-311.)
References: cli/…/service.ts• L57-161 cli/…/service-manager.ts• L305-311
Worktree and runtime commands
Worktree commands give a Git checkout its own Paperclip instance. Runtime commands let an operator inspect and control the workspaces and heartbeat runs used for agent work. Together they support parallel development without mixing instance data, ports, or active work.
Worktree isolation
The CLI identifies primary checkouts and linked worktrees, then gives each managed checkout local Paperclip configuration, environment values, an instance home, and reserved server and database ports. worktree:make creates a Git worktree and initializes it. worktree init initializes an existing checkout. (cli/…/git-workspace.ts• L15-50, cli/…/worktree.ts• L755-793.)
Seeding copies selected data from a source instance into the isolated database. Minimal mode omits live execution history. Normal seeding pauses scheduled work, removes copied agent ownership, blocks copied in-progress agent issues, stops copied workspace runtimes, and rebinds repository workspace paths. (cli/…/worktree.ts• L1182-1415.)
An explicitly empty worktree skips copying. Seed manifests record progress and results. Locks serialize concurrent seed attempts, failed phases remain visible for retry, and a lock owned by an exited process fails closed. Authenticated sources require a credential-backed instance administrator. (cli/…/worktree.ts• L1423-1501, cli/…/worktree.ts• L1503-1590.)
The worktree lifecycle is:
flowchart LR
A[Git branch or checkout] --> B[Repo-local config, env, and hooks]
B --> C[Separate instance home and reserved ports]
C --> D[Minimal or full database seed]
D --> E[Quarantine copied live state]
E --> F[Rebind workspace paths]
F --> G[Run Paperclip in the worktree]
G --> H[Reseed, merge history, repair, or clean up]
worktree:list shows Git worktrees and Paperclip metadata. worktree:merge-history previews or imports selected issue history. Cleanup removes the Git worktree, branch, and instance data only after checks for uncommitted changes and unique commits unless forced. (cli/…/worktree.ts• L4480-4590.)
References: cli/…/git-workspace.ts• L15-50 cli/…/worktree.ts• L504-547 cli/…/worktree.ts• L755-793 cli/…/worktree.ts• L1056-1103 cli/…/worktree.ts• L1182-1415 cli/…/worktree.ts• L1423-1590 cli/…/worktree.ts• L2215-2529 cli/…/worktree.ts• L4480-4590
Runtime and run controls
The API-facing workspace commands operate on execution workspaces. They list and inspect workspaces, check close readiness, update workspace state, control runtime services, and run runtime commands. Heartbeat-run commands provide the operator view of live execution through run inspection, cancellation, logs, events, linked issues, workspace operations, and watchdog decisions. (cli/…/workspace.ts• L27-104, cli/…/run.ts• L46-274.)
Most resource and runtime commands accept --json. The default output stays compact for a person at a terminal, while JSON supports scripts and automation. (cli/…/common.ts• L193-229.)
References: cli/…/workspace.ts• L27-104 cli/…/run.ts• L46-274 cli/…/common.ts• L193-229
Agent runtime setup
The runtime setup command installs an explicitly selected agent runtime on the local host. Public paths include Pi, Cursor, Kimi, and Antigravity. They resolve a provisioner inside the installed Paperclip server package and run public setup only. (cli/…/runtime.ts• L7-19, cli/…/runtime.ts• L61-164.)
Setup passes only approved runtime settings to child processes. It stops on interruption or child failure. runtime import-remote imports a verified Linux Pi companion only when the caller supplies its trusted SHA-256 digest. (cli/…/runtime.ts• L22-59, cli/…/runtime.ts• L76-164.)
References: cli/…/runtime.ts• L7-19 cli/…/runtime.ts• L22-59 cli/…/runtime.ts• L61-164 cli/…/runtime.test.ts• L18-58 cli/…/runtime-setup.test.ts• L21-61
Native runtime bridges
Native runtime bridges keep a provider session behind a bounded process protocol. The ACPX sidecar opens one qualified provider session, attaches it to a Paperclip run, starts and controls turns, and returns bounded events for text, tools, permissions, input, usage, goals, and terminal state. It verifies the session profile and run attachment before provider work starts. (packages/…/acpx-runtime-sidecar.ts• L202-435, packages/…/acpx-runtime-sidecar.ts• L436-705.)
The sidecar serializes input and shutdown work. A first bootstrap failure blocks dependent session commands, while ordinary turn failures remain ordinary turn results. Pending tool, permission, and input requests stay bound to their turn and are cancelled or rejected when that turn or session closes. Semantic completion input is admitted only after the runner accepts the correlated tool call. (packages/…/acpx-runtime-sidecar.ts• L517-581, packages/…/acpx-runtime-sidecar.ts• L830-947, packages/…/acpx-runtime-sidecar.ts• L1086-1103.)
Session snapshots report live provider state before they list pending request identities. They expose counts and turn-bound IDs rather than private forms or permission data. (packages/…/acpx-runtime-sidecar.ts• L600-630, packages/…/acpx-runtime-sidecar.test.ts• L29-83.)
The sidecar boundary limits provider display data before it crosses the process boundary. Tool details remove credentials and observability values. Workspace locations are emitted only after they pass workspace checks. (packages/…/acpx-tool-detail-redaction.ts• L11-57, packages/…/acpx-runtime-sidecar.ts• L1124-1195.)
Output backpressure causes orderly provider cleanup instead of an unbounded event backlog. Shutdown records bounded private evidence and still queues cleanup when diagnostic writing fails. Cost and token data uses bounded non-negative values, while missing accounting stays unknown. Optional usage or goal diagnostics cannot replace the provider's authoritative terminal result. (packages/…/acpx-runtime-sidecar.ts• L119-249, packages/…/acpx-runtime-sidecar.ts• L777-844, packages/…/acpx-runtime-sidecar.ts• L1396-1425, packages/…/acpx-sidecar-shutdown.ts• L3-39.)
References: packages/…/acpx-runtime-sidecar.ts• L202-435 packages/…/acpx-runtime-sidecar.ts• L436-705 packages/…/acpx-runtime-sidecar.ts• L711-1122 packages/…/acpx-runtime-sidecar.ts• L1124-1195 packages/…/acpx-runtime-sidecar.ts• L1396-1425 packages/…/acpx-sidecar-shutdown.ts• L3-39 packages/…/acpx-tool-detail-redaction.ts• L11-57 packages/…/acpx-runtime-sidecar.test.ts• L29-83 packages/…/acpx-runtime-sidecar.test.ts• L608-704
OpenCode proxy
The OpenCode app-server proxy gives runnerd a line-based JSON-RPC facade over an OpenCode session. It supports session start and resume, run attachment, turns, interruption, runtime requests, usage, diagnostics, and a bounded thread read. (packages/…/opencode-app-server-proxy.ts• L42-190, packages/…/opencode-app-server-proxy.ts• L346-440.)
The proxy forwards bounded tool activity and assistant progress while preserving the provider's turn identity. Controller requests remain withdrawable while frames wait behind output pressure. A response to a controller request bypasses the serial command queue so interruption and completion cannot deadlock behind the command that is waiting for it. (packages/…/opencode-app-server-proxy.ts• L208-343, packages/…/opencode-app-server-proxy.ts• L443-517.)
Finish-input diagnostics use the warning path only after the proxy binds them to the active session. The forwarder accepts versioned offered, rejected, and tool-delivery records. It rejects arbitrary fields and private diagnostic text. (packages/…/opencode-proxy-finish-diagnostics.ts• L1-59, packages/…/opencode-proxy-finish-diagnostics.test.ts• L10-116.)
Usage frames carry the current turn total and the session total. The ledger replaces repeated cumulative snapshots for one message, adds completed turns once, folds reasoning tokens into output for the shared budget shape, and resets when a session attaches to a new run. It forwards the named upstream provider and request ID when OpenCode supplies them. (packages/…/opencode-proxy-usage.ts• L1-148, packages/…/opencode-proxy-usage.test.ts• L9-146, packages/…/opencode-app-server-proxy.ts• L244-261, packages/…/opencode-app-server-proxy.ts• L299-303.)
References: packages/…/opencode-app-server-proxy.ts• L42-190 packages/…/opencode-app-server-proxy.ts• L208-343 packages/…/opencode-app-server-proxy.ts• L346-520 packages/…/opencode-proxy-events.ts• L1-163 packages/…/opencode-proxy-finish-diagnostics.ts• L1-59 packages/…/opencode-proxy-finish-diagnostics.test.ts• L10-116 packages/…/opencode-proxy-usage.ts• L1-148 packages/…/opencode-proxy-usage.test.ts• L9-146 packages/…/opencode-proxy-controller.ts• L17-71 packages/…/opencode-proxy-output.ts• L1-154
MCP server interface
The Paperclip MCP server is a bridge from the Model Context Protocol to the Paperclip REST API. It does not access the database or copy business rules. An MCP host starts the server, discovers its tools, and receives text results from API calls. The CLI can also expose an approved remote Paperclip connection through local MCP standard input and output.
CLI MCP connection
mcp login --device --url <url> connects a human's CLI to the canonical Paperclip MCP resource. It discovers the resource and authorization server, registers a public device client, opens a browser approval path, and verifies the approved organization before storing the credential. (cli/…/mcp.ts• L5-12, cli/…/mcp-auth.ts• L148-179.)
Credentials are stored per MCP resource. The CLI can refresh an expired token and serializes login or refresh work across processes. mcp proxy --url <url> forwards remote tool listing and calls over local MCP standard input and output while handling initialization and ping locally. (cli/…/mcp-auth.ts• L16-20, cli/…/mcp-auth.ts• L22-95, cli/…/mcp-auth.ts• L182-209, cli/…/mcp.ts• L13-37.)
References: cli/…/mcp.ts• L5-37 cli/…/mcp-auth.ts• L16-20 cli/…/mcp-auth.ts• L98-179 cli/…/mcp-auth.ts• L182-209
Server transport
The published paperclip-mcp-server command uses standard input and standard output as its MCP transport. It creates a paperclip endpoint, registers Paperclip tools, and connects the endpoint to the standard-I/O transport. Startup errors go to standard error and end the process. (packages/…/index.ts• L7-30, packages/…/stdio.ts• L1-7.)
Paperclip can also act as a client of remote MCP servers through Streamable HTTP. It accepts direct JSON-RPC and server-sent events responses. Sessions are cached by connection scope and effective credentials, shared by concurrent requests, and invalidated only when the cached session still matches the failed session. (server/…/mcp-http.ts• L1-27, server/…/mcp-http.ts• L52-283.)
References: packages/…/index.ts• L7-30 packages/…/stdio.ts• L1-7 server/…/mcp-http.ts• L1-283 server/…/mcp-connection-failure.ts• L12-63
MCP configuration
The MCP server needs PAPERCLIP_API_URL and PAPERCLIP_API_KEY. It normalizes the URL to the Paperclip /api base and can take default company, agent, and heartbeat-run IDs from the environment. Tools can override company or agent context when their schemas allow it. (packages/…/config.ts• L1-38, packages/…/README.md• L8-17.)
The MCP API client sends bearer authentication on every request. It forwards X-Paperclip-Run-Id on writes when a run ID is present. It requires company context for company-scoped tools and agent context for checkout helpers. (packages/…/client.ts• L25-113.)
References: packages/…/config.ts• L1-38 packages/…/README.md• L8-17 packages/…/client.ts• L25-113
MCP tool interface
Each MCP tool has a name, description, input schema, and executor. The executor validates input before it calls the API, then returns JSON or a structured error as MCP text. This makes the tool surface discoverable while keeping each action's input rules explicit. (packages/…/tools.ts• L23-50, packages/…/format.ts• L3-30.)
The tool set follows the Paperclip work loop:
- Read work: inspect actors, inboxes, agents, issues, comments, documents, projects, goals, approvals, and heartbeat context.
- Change work: create or update issues, check out or release work, add comments, and write issue documents.
- Request attention: suggest tasks, ask user questions, request confirmation, and create or decide approvals.
- Control execution: inspect workspaces, control runtime services, wait for service URLs, and use active-run service connections.
- Use an API escape hatch: call an existing relative
/apiendpoint with a JSON body when no dedicated tool exists.
Dedicated tools are preferred because their schemas describe the business action and required context. The escape hatch rejects absolute paths and path traversal. Connection tools use the active heartbeat run's runtime environment instead of the normal API client. (packages/…/tools.ts• L58-85, packages/…/tools.ts• L270-288, packages/…/tools.ts• L423-464, packages/…/tools.ts• L677-689.)
References: packages/…/tools.ts• L23-50 packages/…/format.ts• L3-30 packages/…/tools.ts• L58-85 packages/…/tools.ts• L270-288 packages/…/tools.ts• L423-464 packages/…/tools.ts• L677-689
Assigned app tools
Native runtime sessions can receive server-owned tools from an assigned app connection through the existing runtime tool channel. The interface either publishes a bounded direct catalog or exposes search and call tools that discover names and schemas on demand. Large schemas are paged as JSON text chunks. (server/…/assigned-mcp-tools.ts• L8-39, server/…/assigned-mcp-tools.ts• L83-185.)
Discovery does not grant new authority. The session keeps a pinned tool set, intersects it with fresh gateway grants, applies the current work mode, and sends every execution back through the configured gateway for policy, approval, refresh, and audit. Tool names and results omit gateway secrets and provider metadata. (server/…/assigned-mcp-tools.ts• L52-71, server/…/assigned-mcp-tools.ts• L127-219.)
References: server/…/assigned-mcp-tools.ts• L8-39 server/…/assigned-mcp-tools.ts• L41-81 server/…/assigned-mcp-tools.ts• L83-185 server/…/assigned-mcp-tools.ts• L189-219
Change checklist
When these files or sections are changed, remember to consider these:
- Keep CLI context precedence aligned across command options, environment values, profiles, stored credentials, and inferred local config.
- Keep company deletion selector precedence, ambiguity errors, board-scope lookup fallback, and dual confirmation checks aligned with the destructive API request.
- Keep
PAPERCLIP_RUN_ID,X-Paperclip-Run-Id, and active-run runtime tokens aligned for CLI and MCP writes. - Keep company import size estimates, part hashes, missing-part resume, retries, and server-side preview/apply state aligned.
- Keep instance IDs, config paths, environment secrets, service names, supervisor start arguments, and runtime-record ownership aligned.
- Keep Git worktree detection, port registration, seed source authority, manifests, locks, migration checks, secret copying, path rebinding, and execution quarantine aligned.
- Keep runtime setup provider names, package boundaries, child-process environment, digest checks, and failure handling aligned.
- Keep native runtime session, run, turn, permission, input, tool, terminal, and shutdown contracts aligned with runnerd.
- Keep sidecar snapshots live and private, semantic tool input admitted only after runner acceptance, and cleanup queued after diagnostic failure.
- Keep ACPX display redaction, workspace locations, event frame bounds, output backpressure, and turn-bound request settlement aligned.
- Keep OpenCode JSON-RPC frame bounds, run attachment, resume reads, controller correlation, abandoned-call withdrawal, and EOF ordering aligned.
- Keep OpenCode usage replacement, turn settlement, run reset, reasoning-token mapping, upstream attribution, and bound finish-diagnostic forwarding aligned.
- Keep MCP device discovery, exact resource URL checks, consent scope, organization verification, credential locking, and proxy forwarding aligned.
- Keep MCP tool names, input schemas, API paths, company or agent defaults, and active-run connection rules aligned.
- Preserve both JSON and server-sent events response handling when changing remote MCP HTTP requests.
- Keep remote MCP session cache keys aligned with connection scope, effective credentials, session replacement, and targeted invalidation.
- Keep assigned app-tool catalogs aligned with pinned names, fresh revocation, work-mode restrictions, schema paging, gateway execution, and result error handling.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A company delete selector matches both an ID and another company's prefix. | The CLI could target the wrong company. | Automatic resolution rejects ambiguity and asks for an explicit selector mode. |
| A company delete confirmation does not match the resolved target. | A destructive request could follow unclear operator intent. | Deletion requires --yes and the target ID or issue prefix in --confirm. |
A foreground run starts while the same instance is active under its supervisor. | Two processes can compete for one instance's ports and data. | The CLI checks service status and requires --force to bypass it. |
| A worktree seed copies active ownership or runtime state. | The isolated instance can run work owned by the source instance. | Seed quarantine disables schedules and runtimes and clears copied execution state. |
| An ACPX response targets a stale run or turn. | A permission, input, or tool result can settle the wrong provider action. | The sidecar binds pending requests to the active run and turn and rejects stale identities. |
| A native tool write is accepted by the pipe but not by runnerd. | A completion receipt can claim a result that the controller did not admit. | Semantic input is committed only after the correlated tool.resolve succeeds. |
| An ACPX snapshot is built from stale provider state or includes private request data. | A controller can act on an old view or receive sensitive input. | The sidecar reads live status first and returns only bounded identity summaries. |
| ACPX output remains blocked until its buffer grows without bound. | The provider can continue while runnerd cannot receive terminal state. | The sidecar caps buffered output, stops owned provider work, and drains before exit. |
| OpenCode thread history exceeds the runnerd frame limit during resume. | thread/read can block restore with an oversized stdout frame. | The proxy returns bounded thread and turn metadata instead of provider history. |
| OpenCode sends repeated cumulative usage snapshots or retains totals across a new run attachment. | Token and cost totals can be double-counted or assigned to the wrong run. | The ledger keys snapshots by turn and message, settles each turn once, and resets on run attachment. |
| OpenCode finish diagnostics contain arbitrary fields or arrive before session binding. | Private provider data can reach the outer protocol or a failure can be misattributed. | The forwarder accepts only bound versioned diagnostic shapes and bounded counts. |
| An MCP tool omits required company, agent, or run context. | The request fails or can target the wrong scope. | The MCP client and tool schemas require the needed context. |
| A remote MCP server returns SSE while the client expects only JSON. | A compliant response cannot be read. | The HTTP client handles both JSON and server-sent events. |
| An assigned app tool is discovered after its grant is revoked or work mode becomes read-only. | The runtime could expose stale authority or perform a forbidden write. | Discovery intersects fresh grants and execution rechecks mode and gateway authorization. |
Key files
| File | Why to read it |
|---|---|
| cli/…/index.ts | Defines the top-level CLI lifecycle and command registration. |
| cli/…/onboard.ts | Shows first-run setup, configuration, secrets, and startup choices. |
| cli/…/run.ts | Shows repeatable startup, worktree setup, health checks, and runtime identity. |
| cli/…/test-drive.ts | Defines isolated manual testing and harness bootstrap. |
| cli/…/store.ts | Defines configuration selection, validation, and safe writes. |
| cli/…/common.ts | Defines shared API context, authentication, run context, and output behavior. |
| cli/…/board-auth.ts | Defines browser-based board authentication and credential storage. |
| cli/…/agent.ts | Defines agent lifecycle, runtime state, skills, and instruction setup. |
| cli/…/company.ts | Defines company scope, deletion safeguards, and portability. |
| cli/…/company-delete.test.ts | Shows ID and prefix resolution plus destructive confirmation. |
| cli/…/issue.ts | Defines the issue work loop and checkout or release behavior. |
| cli/…/service-manager.ts | Defines supported supervisors and the managed instance lifecycle. |
| cli/…/service.ts | Connects service commands to shim, health, and restart behavior. |
| cli/…/worktree.ts | Defines worktree creation, seeding, quarantine, repair, and cleanup. |
| cli/…/workspace.ts | Exposes workspace and runtime-service controls. |
| cli/…/run.ts | Exposes heartbeat-run inspection, cancellation, logs, and watchdog actions. |
| cli/…/runtime.ts | Defines explicit agent runtime setup and remote companion checks. |
| packages/…/acpx-runtime-sidecar.ts | Defines the ACPX session, run, turn, tool, request, event, usage, and shutdown boundary. |
| packages/…/acpx-sidecar-shutdown.ts | Defines bounded shutdown evidence and cleanup ordering. |
| packages/…/acpx-runtime-sidecar.test.ts | Verifies sidecar identity, settlement, snapshots, accounting, cleanup, and output pressure. |
| packages/…/opencode-app-server-proxy.ts | Defines the OpenCode JSON-RPC facade, event forwarding, run attachment, resume, and shutdown. |
| packages/…/opencode-proxy-finish-diagnostics.ts | Defines safe forwarding of bound finish-input and delivery diagnostics. |
| packages/…/opencode-proxy-usage.ts | Defines OpenCode usage normalization and per-message, per-turn accounting. |
| packages/…/opencode-proxy-controller.ts | Defines controller request correlation and withdrawal of abandoned calls. |
| packages/…/opencode-proxy-output.ts | Defines ordered batching and backpressure handling for OpenCode output. |
| cli/…/mcp.ts | Defines device login and the local MCP standard-I/O proxy. |
| cli/…/mcp-auth.ts | Defines MCP resource validation, authorization, credential storage, and refresh. |
| packages/…/index.ts | Creates the MCP endpoint and connects its standard-I/O transport. |
| packages/…/config.ts | Defines required MCP environment settings and URL normalization. |
| packages/…/client.ts | Sends authenticated API requests and carries run context. |
| packages/…/tools.ts | Defines the typed Paperclip and active-run connection tool surface. |
| server/…/mcp-http.ts | Defines remote Streamable HTTP responses, sessions, and invalidation. |
| server/…/assigned-mcp-tools.ts | Projects assigned app tools into native runtime discovery and execution. |