Plugin platform
The plugin platform lets Paperclip add trusted extensions without placing their product logic in the host. A plugin declares its identity and access needs, runs behind a host-controlled worker boundary, and connects Paperclip data, agent work, scheduled work, external systems, storage, and UI surfaces. It is the plugin-specific part of the extensibility platform; CLI and MCP interfaces and external app connections are related extension paths.
Plugin lifecycle
The lifecycle moves a package from discovery to a stored install and then to an active worker. The host owns the install record, status, configuration, and runtime registrations. The loader links a ready worker to events, jobs, tools, environment services, connectors, and UI.
flowchart LR
A[Discover package] --> B[Validate manifest]
B --> C[Check capabilities and host version]
C --> D[Persist install]
D --> E[Start worker]
E --> F[Register jobs events tools connectors UI]
F --> G[Ready]
G --> H[Disable or error]
G --> I[Upgrade]
G --> J[Uninstall]
I --> B
Published plugins install as npm packages. Local paths and bundled source trees support development and trusted first-party deployment flows. Bundled local plugins can be built when their declared runtime files or dependencies are missing.
An upgrade that adds capabilities waits for operator approval before the new access becomes active. Disabled, failed, or pending plugins stay offline. A soft uninstall can retain the stable record and data, so a later install can reconnect existing references. Bundled registration is idempotent when the installed package and manifest match the approved catalog.
When a worker starts after an upgrade or restart, connector tool catalogs are refreshed so saved tool risk and names match the running manifest. When a plugin is disabled, its connector apps and connections become unavailable without deleting their saved settings or grants. Uninstall archives those connections and removes their connector-owned credentials through the normal connection removal path.
References: server/…/plugin-loader.ts• L1201-1357 server/…/plugin-loader.ts• L931-1004 server/…/plugin-registry.ts• L148-213 server/…/plugin-lifecycle.ts• L304-328 server/…/plugin-lifecycle.ts• L542-605
Plugin manifests
The manifest is the contract between a plugin and the host. It names the plugin and version, defines compatibility and entrypoints, lists capabilities, and declares the features that the host must expose.
| Manifest area | System role |
|---|---|
| Identity and version | Gives the install a stable key and compatibility rule. |
| Entrypoints | Points to the worker and optional UI bundle. |
| Capabilities | States which host operations the plugin needs. |
| Runtime declarations | Describes jobs, webhooks, tools, routes, providers, connectors, and workspace services. |
| Managed resources | Describes company-scoped agents, projects, routines, and skills. |
| Persistence | Requests scoped state or a restricted database namespace. |
| UI declarations | Describes slots and launchers that the host can mount. |
The host rejects duplicate keys, unsafe paths, unsupported routes, invalid schedules, incompatible UI declarations, and unmatched references. A declared feature must have the capability that permits it. The host also checks the minimum host version and rejects page-route collisions with installed plugins.
Plugin instance settings use the manifest's JSON Schema. Secret fields store a Paperclip secret binding while the schema describes a string; validation checks the binding's secret ID and keeps the secret value out of plugin configuration. Provider settings follow the same model and are normalized before the worker validates them.
References: server/…/plugin-loader.ts• L1253-1279 server/…/plugin-loader.ts• L1286-1300 server/…/plugin-registry.ts• L218-258 server/…/plugin-secrets-handler.ts• L80-124
Capability gates
Capabilities are least-privilege claims for host services. Install checks confirm that manifest features have their required capabilities. Runtime checks apply the same rule to each worker-to-host operation, and unknown operations fail closed.
The host also checks the company scope of a worker call. A worker can use only the company authorized for the active host invocation. Proactive work outside an invocation uses a bounded set of configured company scopes. It cannot replace either scope with a company ID in its own request.
Plugin calls that act for an agent run retain the originating company, agent, and run context while they pass through host services. This lets downstream agent policy, authorization, audit, and wakeup behavior use the real origin instead of treating nested plugin work as an unowned system action.
These gates protect host APIs and extension points. They do not make trusted worker code or same-origin plugin UI safe for untrusted marketplace use.
References: server/…/plugin-capability-validator.ts• L44-218 packages/…/host-client-factory.ts• L386-715 server/…/plugin-worker-manager.ts• L1082-1105
Worker boundary
Each installed plugin has one worker process. The host and worker exchange typed JSON-RPC messages over standard input and output. The worker receives initialization data and a plugin context; the host sends events, configuration changes, jobs, and UI bridge calls back to it.
sequenceDiagram
participant Host as Paperclip host
participant Worker as Plugin worker
participant UI as Plugin UI
Host->>Worker: initialize(manifest, config, host info)
Worker-->>Host: ready and supported methods
UI->>Host: data or action bridge call
Host->>Worker: getData or performAction
Worker->>Host: state, event, HTTP, or domain call
Host-->>Worker: result or denial
Worker-->>Host: stream or duplex notification
Host-->>UI: SSE event or bridge result
The worker manager isolates crashes from the host. It supports graceful shutdown, bounded calls, and restart with backoff. A call made while the worker is stopped is reported as a retryable worker-unavailable condition; no request is sent to a missing worker. During initialization the worker advertises optional methods, so the host can choose only the provider features that the live worker supports.
The same boundary carries live login terminals and generic duplex channels. The host creates the route identity, binds notifications to the exact host and worker session pair, and closes the route when time, size, pending-work, or protocol limits are exceeded. A worker crash closes its stream routes. These controls limit damage from faulty workers but do not turn the worker process into a complete security boundary for arbitrary code.
Worker configuration is also scope-aware. A plugin that does not opt into multi-company configuration fails closed when a second distinct company's configuration would replace the first company's state. A plugin that opts in receives the company scope and must keep its own per-company state. The host replays configured company settings to a new worker in a stable order, so proactive plugins can restore their connections after restart.
Workers can also take a temporary idle hold. The hold is allowed only after active host calls, notifications, timers, and plugin work drain. An uncertain or incomplete drain keeps the worker active, and a lost release expires rather than leaving the worker held forever.
References: server/…/plugin-worker-manager.ts• L81-160 server/…/plugin-worker-manager.ts• L1020-1137 server/…/plugin-worker-manager.ts• L3618-3648 packages/…/worker-rpc-host.ts• L343-489 packages/…/worker-rpc-host.ts• L1960-1995 server/…/plugin-registry.ts• L341-369
Host services and SDKs
The worker SDK is the author-facing interface. A plugin defines setup and optional lifecycle handlers, then uses its context to register events, jobs, UI data and actions, tools, connectors, managed resources, provider hooks, and environment tasks.
| SDK surface | Purpose |
|---|---|
@paperclipai/plugin-sdk | Worker definition, context, lifecycle, and host types. |
@paperclipai/plugin-sdk/ui | React hooks, slot props, navigation, UI parts, and streams. |
@paperclipai/plugin-sdk/testing | In-memory host and provider contract checks. |
@paperclipai/plugin-sdk/bundlers | Worker, manifest, and UI build presets. |
@paperclipai/plugin-sdk/dev-server | Local UI serving and reload support. |
@paperclipai/plugin-sdk/protocol | Typed JSON-RPC contracts. |
The host builds a capability-gated handler set for each plugin. These handlers add company checks, audit records, secret handling, redaction, and trace limits. The host also protects plugin HTTP fetches from unsafe protocols, private network targets, DNS rebinding, and oversized responses.
Provider and workspace contracts use typed inputs and results. The SDK rejects a result that names the wrong project, source revision, execution workspace, branch, task, or operation. Environment task replies must match the requested task and operation kind. The SDK testing harness mirrors these checks in memory so plugin tests can cover host contracts without starting the full server.
The SDK exposes bounded diagnostic envelopes for provider failures. These envelopes carry only approved status or error-code values across the worker boundary. They describe retry or cleanup evidence but do not grant authority to replace, release, or destroy an environment.
The SDK also provides the worker runner, UI helpers, an in-memory host for contract checks, build presets, and a local UI development server. The current deployment model treats worker and same-origin UI code as trusted. npm package installation is the supported deployed path; local paths and repository examples are development flows, and runtime installation expects a writable host with npm and registry access.
References: packages/…/README.md• L1-53 packages/…/index.ts• L48-92 packages/…/define-plugin.ts• L223-415 packages/…/worker-rpc-host.ts• L164-209 packages/…/testing.ts• L84-169 packages/…/environment-resume-error.ts• L7-85 server/…/plugin-host-services.ts• L501-511 server/…/plugin-host-services.ts• L177-240
Plugin connectors
Plugin connectors let a plugin provide tools through the same connection model as built-in external apps. The manifest contributes an app definition, while the host keeps ownership of connection grants, policy, approval, credential resolution, and audit.
An enabled plugin does not automatically give every agent its tools. An operator installs a connection for an agent or company. The gateway then passes the selected connection and run context to the plugin worker for each tool call. Tool arguments cannot change the connection, company, agent, or run that the host selected.
Static connectors declare their tools in the manifest. Dynamic connectors ask the worker for a tool list for one connection. The host filters dynamic entries and keeps static catalog entries only while their current name and risk still match the manifest. Legacy top-level plugin tools remain available through an implicit connector; migration creates company-wide connections only for plugins that had those tools before the connector model.
The catalog reads only ready plugins. Disabling a plugin hides its apps and saved connections without deleting them. Uninstall retires the connections and their credentials. A stopped worker makes a plugin connector unavailable for execution, while static catalog data can still be read for discovery. Connector calls use a declared method or tool timeout within the host's limit, and the gateway remains responsible for grant, approval, credential, policy, and audit decisions.
References: server/…/plugin-app-catalog.ts• L37-73 server/…/plugin-app-catalog.ts• L105-155 server/…/plugin-connector-runtime.ts• L76-208 server/…/plugin-connector-legacy-access.ts• L27-97 packages/…/README.md• L118-157 packages/…/types.ts• L267-327
State and entity persistence
Plugin state is JSON key-value data owned by one plugin and partitioned by scope. Scopes include the instance, company, project, workspace, agent, issue, goal, and run. A namespace groups keys and prevents collisions between plugin subsystems.
| Data need | Platform choice |
|---|---|
| Cursor, flag, or checkpoint | State with the narrowest scope. |
| External record mapping | Plugin entity storage. |
| Relational data and migrations | Restricted plugin database namespace. |
| Operator settings | Company-scoped plugin configuration. |
The host enforces plugin ownership and gates reads and writes separately. Resolved secret values do not belong in persistent plugin data. Plugins store references and resolve them when needed.
References: packages/…/types.ts• L745-830 server/…/plugin-registry.ts• L551-672 server/…/plugin-host-services.ts• L1659-1680
Event and stream buses
The event bus carries Paperclip domain events to subscribed workers and namespaced events between plugins. The host applies company, project, and agent filters before delivery. Plugin-emitted events receive the sender's plugin.<pluginId>. namespace automatically.
The stream bus carries short-lived ordered data from a worker to a UI. A worker opens a company channel and emits events. The host matches the plugin, channel, and company, then exposes the stream through an SSE bridge.
flowchart LR
D[Paperclip domain event] --> E[Event bus]
E -->|scope filters| W[Plugin worker]
W -->|stream notification| S[Plugin stream bus]
S -->|plugin + channel + company| U[UI SSE client]
Durable resource lifecycle delivery is separate from both buses. It delivers committed company-scoped changes at least once and accepts an acknowledgment, retry, or deferral. The inbox keeps progress per resource and preserves creation-before-transition order. A failed or deferred resource does not block independent resource streams, and plugins must re-read current state and make external effects safe to repeat.
References: packages/…/types.ts• L525-604 server/…/plugin-event-bus.ts• L4-205 server/…/plugin-stream-bus.ts• L1-45 server/…/plugin-worker-manager.ts• L1126-1129
Scheduled jobs and webhooks
Jobs turn a manifest declaration into a durable schedule and worker callback. When a plugin becomes ready, the coordinator syncs its declarations with the job store and scheduler. Removed declarations are paused so their run history remains available.
The scheduler checks due jobs, prevents overlap, limits concurrent work, calls the worker, records the run, and advances the next schedule time. Operators can trigger a job or retry a failed run. A job change also wakes the scheduler so durable state and in-memory timing do not drift.
Webhooks use the same worker boundary. A manifest names an endpoint, the host records each delivery, and the worker receives the payload when the route is enabled. The plugin checks the external signature with a resolved secret.
References: server/…/plugin-job-coordinator.ts• L4-24 server/…/plugin-job-store.ts• L128-208 server/…/plugin-job-scheduler.ts• L80-199 server/…/plugin-registry.ts• L688-893 packages/…/define-plugin.ts• L329-342
Managed agents, routines, and skills
Managed resources let a plugin describe company-scoped Paperclip objects that it owns by stable keys. The host turns declarations into normal agents, projects, routines, and company skills, then stores bindings so later calls resolve the same objects.
Reconciliation resolves an existing binding, relinks a matching resource, or creates the resource. Reset applies declaration defaults again. A managed agent can carry instructions and lifecycle ownership. A routine connects an agent and project with variables, triggers, and run policy. A managed skill installs SKILL.md and its declared files into the company skill library.
Stable plugin-qualified keys prevent replacement installs from creating duplicates. Routine references must resolve to resources owned by the declaring plugin. Operators can change defaults, so reconciliation reports drift instead of silently hiding it.
Agent runtime state is a separate synchronization view for a managed agent. The owning plugin must be ready, enabled for the company, and authorized for agent lifecycle work. The host returns a revision with instructions, instance secrets, selected environment skills, and connection assignments. It checks the revision again before returning, so a concurrent change causes a retry rather than stale runtime input.
References: server/…/plugin-managed-agents.ts• L184-357 server/…/plugin-managed-routines.ts• L1-220 server/…/plugin-managed-skills.ts• L82-159 server/…/plugin-agent-runtime-state.ts• L16-97 server/…/plugin-host-services.ts• L778-815
Plugin UI assets
Plugin UI is a built ESM bundle served from the plugin package. A manifest maps named exports to host slots and may add launchers for pages, buttons, menus, drawers, modals, popovers, and actions. The host returns contributions only for ready plugins.
UI components receive read-only host context with the active company and optional project or entity. The UI SDK provides navigation and bridge hooks for data and actions. A stream hook receives worker events through SSE. The static asset route checks the plugin state and keeps requested paths inside the package, including when symlinks are present.
Runtime activity can activate a declared task side panel. The host matches a bounded namespace and activity key from authenticated runner activity. This ties the panel to runtime facts rather than a caller-supplied display value.
UI bundles run as same-origin JavaScript. Manifest capabilities protect bridge calls, not the frontend itself. Hashed assets use immutable caching; other assets use revalidation and ETags.
References: packages/…/plugin.ts• L463-579 packages/…/types.ts• L80-510 server/…/plugin-task-panels.ts• L4-34 server/…/plugin-ui-static.ts• L198-229
Environment provider lifecycle
Environment provider plugins connect Paperclip execution to external compute. The host validates configuration, checks reachability, leases compute, realizes a workspace, runs commands, transfers files, and releases, stops, inspects, or destroys provider state.
The provider advertises optional hooks during initialization. The host enables an operation only when the manifest and live worker both support it. Reusable leases require the full resume, release, and destroy lifecycle. Inspection is read-only. Stop preserves the allocation and its files until the provider confirms termination.
Provider configuration is checked by the worker after the host normalizes secret bindings. The host selects a provider by its exact plugin identity when a lease is being resumed or destroyed. This prevents a same-named driver in another install from receiving an old lease. Login terminals use the same exact lease binding and a closed command identity; callers do not choose an arbitrary command.
Task operations use exact durable identities and closed result kinds. A release result proves release, while a resume result reports only resumed or unavailable. A generic acceptance or queued stop is not proof that the old execution ended. Resume can return the relaunch details and archived state only when the request asks for them, so the host can bind a new execution to the claimant's identity.
Failed acquisition can carry a bounded observation of the first failed step and provider state. If cleanup is uncertain, the worker preserves a non-secret ownership envelope so the host can reconcile the provisional allocation. Provider error text, private identifiers, and credentials do not cross the worker boundary. Stop failures use closed reasons for unrecoverable, recovery-failed, or incomplete recovery states; terminal failures escalate but remain in cleanup until resolved.
References: server/…/plugin-environment-driver.ts• L86-147 server/…/plugin-environment-driver.ts• L197-216 server/…/plugin-environment-driver.ts• L288-336 server/…/plugin-environment-driver.ts• L417-505 packages/…/README.md• L55-83 packages/…/environment-acquire-error.ts• L15-62 packages/…/environment-creation-cleanup.ts• L1-126 packages/…/environment-tasks.ts• L90-241 packages/…/environment-resume-error.ts• L19-84 packages/…/protocol.ts• L716-757
Workspace providers
Workspace providers own durable project-backed storage. The host selects a provider from project policy, reserves an execution workspace, and passes an operation to prepare, inspect, finalize, or remove it. The provider returns an opaque binding tied to the project, source revision, and execution workspace.
Preparation is repeat-safe. The host records ownership, operation identity, placement, and lifecycle generation before an external call, then checks them again before saving the result. Providers may complete preparation at once or return a bounded pending receipt for later polling. A failed or ambiguous call can be reconciled from the reservation, including through a replay context that authorizes the same workspace and provider without the original task still running. An abandoned reservation can be retired only when its task and run no longer need it.
Fresh retry preparation creates new storage while keeping the failed workspace intact. It carries a stable attempt identity, the failed source run, an optional prior workspace, and verified recovery descriptors. Workspace storage remains separate from temporary or reusable environment leases.
Removal requires a clean inspection and a durable removal intent. The host records that intent before the provider call and marks the workspace removed only after confirmed removal. Restoration follows the recorded recipe and a new lifecycle generation.
References: packages/…/workspace-provider.ts• L4-200 server/…/plugin-workspace-preparation.ts• L23-177 server/…/plugin-workspace-replay-context.ts• L1-22 server/…/plugin-workspaces.ts• L260-347 server/…/plugin-workspaces.ts• L506-581 server/…/plugin-workspaces.ts• L753-882
Runner task providers
Runner task providers host an agent task inside an external environment. The host sends a versioned launch contract with durable task identity, selected provider, model and policy data, and any transient credential. The provider prepares or resumes the task, reports status, exposes a protected connection, and confirms completion or stop. The SDK validates that each operation receives the matching task and result kind, so a response from another task or lifecycle step cannot be accepted.
A plugin Runner environment requires a managed AI connection. An account installed on the provider machine is not a supported credential source. A preconfigured Runner home also cannot use the managed connection, so setup and run admission fail until the agent uses an isolated Runner home.
Warm-task resume is allowed only within the same authorized company, agent, issue, environment, workspace, plugin, driver, and session identity. The old task must be retained or inspected as allowed, and its remote execution must be stopped before the new task uses it. When a retained task moves between leases, the host first creates an ownership claim, asks the provider to attest the target generation, and admits the new task only after that claim is ready. This prevents two runs from owning the same remote session.
Release and resume are explicit task operations. A release result confirms the provider task was released, while a resume result reports whether the retained task was resumed or unavailable. The host does not treat a generic acceptance or a queued stop as proof that the old execution ended.
Credential writeback stores authority to refresh a managed connection, not credential bytes or a controller-local path. The handoff settles only after task termination is confirmed and rechecks the grant, secret, session epoch, and lease before rotating the secret. A plugin login credential can be read only from the exact durable login allocation, only when the worker advertises the fixed credential-read method, and only as a bounded typed artifact.
References: packages/…/environment-tasks.ts• L90-294 server/…/plugin-task-resume.ts• L5-93 server/…/plugin-task-ownership.ts• L75-203 server/…/plugin-task-credential-writeback.ts• L16-119 packages/…/environment-task-release-resume.test.ts• L55-193
Bundled sandbox providers
Bundled sandbox providers adapt different compute systems to the same environment contract. They keep lease, workspace, command, file transfer, and termination behavior behind the provider boundary, so Paperclip can select a provider without changing agent execution flows.
The boxd, Daytona, and Kubernetes packages are provider choices behind one host contract. Provider-specific limits still apply, such as auto-stop and quota rules, ownership labels, safe file transfer, and confirmed remote cleanup. Archive and link checks prevent provider data from escaping its intended destination.
References: packages/…/README.md• L3-84 packages/…/manifest.ts• L20-200 packages/…/plugin.ts• L963-1103 packages/…/package.json• L1-61
Configuration and secrets
Plugin configuration stores operator choices and references to secrets. The host resolves a secret only for a company-scoped worker request after it confirms that the reference is bound to that plugin and configuration path.
Secret values do not cross into stored plugin configuration or persistent plugin state. Resolution rejects legacy bare UUID references, rejects ambiguous bindings without a configuration path, records the plugin and actor context, and applies a per-plugin rate limit. Plugins must use the value for the current operation and must not cache or log it.
References: server/…/plugin-secrets-handler.ts• L43-64 server/…/plugin-secrets-handler.ts• L175-260 packages/…/types.ts• L726-753
Bundled plugin administration
Bundled plugins are first-party or example packages shipped with the application. A positive catalog maps approved keys to package paths. Self-hosted startup keeps built-in provider behavior; managed startup receives an allowlist from control-plane configuration.
Startup resolves the allowlist before the server listens. An unknown key or path outside the catalog stops startup. A missing bundle or install failure leaves the server running in a degraded state after it has been logged. Existing operator-disabled plugins are not silently re-enabled.
The administration API lists installed and bundled plugins, installs from npm or local paths where allowed, enables or disables plugins, upgrades and uninstalls them, reports health, and exposes jobs, tools, connectors, UI contributions, configuration, bridge calls, and streams. Instance-admin checks protect lifecycle changes. Cloud-managed instances cannot install arbitrary npm packages or local paths.
References: server/…/bundled-plugins.ts• L5-187 server/…/plugin-loader.ts• L1221-1335 server/…/plugins.ts• L2378-2557
Change checklist
When these files or sections are changed, remember to consider these:
- Keep manifest declarations, capability mappings, shared types, config schemas, and worker SDK methods aligned.
- Preserve stable plugin keys, managed-resource keys, workspace bindings, task identities, connector source slugs, and driver identities. They link declarations to durable records and external resources.
- When changing an RPC method or payload, update the protocol map, worker dispatch, host handler, validation, and caller together.
- When changing worker availability or route handling, preserve retryable worker refusal, company scope, route pairing, bounded buffers, and synthetic close behavior after worker failure.
- When changing configuration callbacks, preserve company scope, the single-company fail-closed rule, stable startup replay, and the explicit multi-company opt-in.
- When changing config or secret references, keep API validation, persisted bindings, provider normalization, path selection, rate limits, and runtime secret resolution consistent.
- When changing connector declarations or tool risk, update the app catalog, saved connection catalog, worker handler registration, legacy migration, and uninstall cleanup together.
- When changing lifecycle delivery, preserve enablement checks, ownership filters, journal replay, per-resource ordering, retry or deferral results, and idle-drain inspection.
- When changing managed-agent runtime inputs, preserve lifecycle ownership, selected environment skills, connection assignments, instance-secret scope, and revision checks.
- When changing workspace providers, preserve reservation-before-call, operation identity, lifecycle generation, source revision, owner checks, pending preparation deadlines, replay authorization, fresh-retry records, and confirmed removal.
- When changing Runner tasks or login flows, preserve managed AI connection admission, warm-task identity checks, ownership claims, exact login lease binding, fixed command identity, termination receipts, credential handoff authority, and session-epoch checks.
- When changing environment acquisition or stop errors, preserve the closed diagnostic fields, non-secret cleanup ownership envelope, first-failure observation, and the rule that diagnostics do not authorize cleanup or retry by themselves.
- When changing connector catalogs or runtime calls, preserve current static tool and risk matching, dynamic tool bounds, declared timeout limits, and retryable worker-unavailable behavior.
- When changing UI slots or static assets, update capability mapping, contribution discovery, task-panel activation checks, route collision checks, and path containment together.
- When changing bundled administration, preserve catalog-root containment, managed install policy, startup behavior, connector retirement, and the rule that disabled plugins stay disabled.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Manifest feature has no matching capability | Install or activation is rejected. | Cross-field manifest and capability validation. |
| Worker is stopped or restarting | No provider or connector request is sent and the run can retry. | Worker-unavailable error and bounded recovery handling. |
| Worker sends a call for an unauthorized company | The host denies the call. | Invocation scope and bounded proactive company scopes. |
| A single-company worker receives distinct configuration for another company | The new configuration is rejected instead of replacing the first company's state. | Multi-company opt-in and cross-tenant RPC error. |
| Secret binding is missing, ambiguous, or uses a legacy bare UUID | Configuration or runtime use is rejected. | Typed secret references, plugin/path binding checks, and rate limiting. |
| Lifecycle event is delivered twice or after a failure | External state may be applied more than once. | Durable inbox, per-resource cursor, replay, acknowledgment states, and idempotent plugin effects. |
| Lifecycle transition is acknowledged before its creation or earlier transition | Progress is rejected and the event stays pending. | Ordered inbox acknowledgment. |
| Agent runtime changes while inputs are assembled | The worker could receive stale instructions or connections. | Revision recheck and conflict on concurrent change. |
| Connector tool risk or name changes during an upgrade | A saved tool can be hidden until its catalog is refreshed. | Post-activation catalog refresh and current static declaration check. |
| Plugin connector worker is unavailable | Discovery may work but tool execution fails as retryable unavailable. | Ready-state and live-worker checks. |
| Workspace provider returns a binding for another project, revision, or workspace | Durable state can point to the wrong storage. | Typed result checks and post-call ownership checks. |
| Workspace preparation reply is lost or its reservation changes | The host does not attach an unknown checkout to durable state. | Reservation replay, operation identity, generation checks, and post-call ownership checks. |
| Workspace removal is uncertain or the workspace has local changes | Storage is retained instead of being deleted. | Inspection, recorded removal intent, and confirmed removal. |
| Runner task lacks a managed AI connection | Setup or run admission fails before lease acquisition. | Explicit connection check and failure code. |
| Warm-task identity, ownership claim, or termination proof does not match | Resume is denied. | Same-scope identity checks, target-generation attestation, and remote termination receipts. |
| Credential handoff is pending while execution may still run | Credential refresh is refused. | Confirmed stop, lease lock, grant checks, and session epoch. |
| Login credential request is not tied to a ready worker and exact login allocation | No credential artifact is returned. | Durable lease checks, method discovery, fixed result kind, and size bound. |
| Environment acquisition fails and cleanup cannot be confirmed | The provisional allocation remains subject to reconciliation instead of being treated as absent. | Structured cleanup ownership envelope and bounded acquisition diagnostic without provider text. |
| Provider returns a result for another task or lifecycle operation | The response is rejected at the worker boundary. | Exact durable identity and closed operation-to-result matching. |
| A connector's static tool name or risk changes during an upgrade | The old catalog entry is hidden until the catalog reflects the new declaration. | Current manifest comparison before policy uses the entry. |
| A connector is cataloged but its worker stops before execution | The tool call fails as retryable unavailable. | Live-worker health check and bounded RPC timeout. |
| UI requests an escaping or unavailable asset | The asset is not served. | Ready-state and real-path containment checks. |
| Duplex or stream route becomes ambiguous or unbounded | The route is closed and the worker may be retired. | Host-minted route identity, exact pairing, time and flood bounds, and synthetic close behavior. |
| Managed startup receives an unknown catalog key or path | Startup refuses to listen. | Positive catalog and catalog-root containment. |
Key files
| File | Why to read it |
|---|---|
| server/…/plugin-loader.ts | Main discovery, install, validation, activation, configuration replay, and bundled build flow. |
| server/…/plugin-lifecycle.ts | Plugin status transitions, worker coordination, connector refresh, and connector retirement. |
| server/…/plugin-worker-manager.ts | Worker process, JSON-RPC, scope, recovery, idle holds, login routes, duplex routes, streams, and task calls. |
| server/…/plugin-host-services.ts | Capability-gated host bridge, company checks, issue access, HTTP protection, workspace metadata, and tracing. |
| server/…/plugin-capability-validator.ts | Manifest feature checks and runtime operation-to-capability rules. |
| server/…/plugin-app-catalog.ts | Ready-plugin connector catalog, availability, catalog refresh, and connection retirement. |
| server/…/plugin-connector-runtime.ts | Routing of plugin connector tool lists and calls to live workers. |
| server/…/plugin-registry.ts | Durable plugin records, company configuration, entity mappings, jobs, webhooks, and workspace-provider change notifications. |
| packages/…/plugin.ts | Shared manifest, lifecycle, state, job, UI, connector, and managed-resource contracts. |
| packages/…/plugin.ts | Manifest shape and cross-field validation. |
| server/…/plugin-secrets-handler.ts | Plugin secret binding validation, scoped resolution, and access limits. |
| packages/…/index.ts | Public worker SDK exports and author-facing contracts. |
| packages/…/README.md | Supported SDK surfaces, deployment posture, connector behavior, and environment error contracts. |
| packages/…/types.ts | Worker context, state, events, connectors, tools, and managed-resource types. |
| packages/…/protocol.ts | Host-worker messages, invocation scope, login, duplex, and provider contracts. |
| packages/…/environment-tasks.ts | Runner task operations, exact identities, release and resume results, ownership claims, and credentials. |
| packages/…/environment-acquire-error.ts | Bounded acquisition diagnostics and cleanup evidence crossing the worker boundary. |
| packages/…/environment-creation-cleanup.ts | Non-secret ownership evidence for failed environment creation and cleanup reconciliation. |
| packages/…/worker-rpc-host.ts | Worker-side dispatch, host calls, optional methods, lifecycle hooks, idle holds, and stream or channel notifications. |
| packages/…/testing.ts | In-memory host and environment-provider contract checks. |
| server/…/plugin-agent-runtime-state.ts | Revision-safe managed-agent runtime inputs. |
| server/…/plugin-environment-driver.ts | Provider resolution, live method checks, configuration validation, optional hooks, and lease calls. |
| server/…/plugin-ui-static.ts | Ready-plugin UI asset serving and path containment. |
| server/…/bundled-plugins.ts | Bundled catalog resolution and startup provisioning. |
| server/…/plugins.ts | Plugin administration and bridge routes. |