Introducing a new way to review your PRs.

Read the announcement

stablyai / orca

Orca lets you run a fleet of bots with your own subscription (e.g. Claude Code, Grok, Agy, Codex). Available on desktop, mobile and remote runtime.

View on GitHub

34 documents · Updated Nov 20, 2026

docs / plugin-lifecycle-and-contributions

Plugin lifecycle and contributions

Plugins extend Orca through a reviewed manifest, bounded files, catalog policy, and a small host API. The platform discovers each plugin, checks that its declared behavior is safe for the host, asks for consent when needed, and then exposes its panels, commands, files, themes, or worker code through the correct host surface. See the plugin platform page for the wider platform model.

Lifecycle overview

The plugin lifecycle moves from source identity to validation, review, activation, and supervised use. A refresh serializes discovery and reconciliation so a plugin cannot remain active after its enablement, consent, safety status, or content changes.

This diagram shows how a source becomes an approved plugin and how later changes cause reconciliation.

flowchart LR
  A[Catalog or local source] --> B[Resolve source identity]
  B --> C[Discover manifest and artifacts]
  C --> D[Check catalog, safety, and consent policy]
  D --> E[Register data and declarative contributions]
  D --> F[Start worker or panel]
  F --> G[Host API calls and events]
  G --> H[Reconcile, stop, or restart]

The main service keeps discovery, content-pack reconciliation, worker reconciliation, and panel invalidation in one ordered refresh. An unapproved, blocked, or invalid plugin remains visible as a problem but cannot open a frame, receive a worker, or obtain host capabilities. (src/…/plugin-service.ts• L142-211, src/…/plugin-service.ts• L229-272)

References: src/…/plugin-service.ts• L142-211 src/…/plugin-service.ts• L229-272

Manifest and artifact validation

The manifest is the plugin's contract with Orca. orca-plugin.json declares the plugin identity, supported Orca version, execution profile, requested capabilities, entry points, and contribution lists; format 2 makes the execution tier explicit and rejects unknown fields. (src/…/plugin-manifest.ts• L37-44, src/…/plugin-manifest.ts• L79-145, src/…/plugin-manifest.ts• L155-221)

Manifest identity and compatibility

Orca installs a plugin under the qualified key <publisher>.<id>. For format 2, Orca derives the publisher from the repository owner or uses local for a local folder, which prevents a manifest from claiming a different publisher. The host also checks engines.orca before it offers the plugin for activation. (src/…/plugin-manifest.ts• L79-95, src/…/plugin-manifest.ts• L173-182, src/…/plugin-manifest.ts• L248-254, src/…/plugin-discovery.ts• L104-123)

Authoring validation is stricter than runtime reading. Development folders and catalog checks reject unsafe display text and schema errors. Installed plugins use a host schema that can read compatible manifests, then still require the declared host version to match. (src/…/plugin-manifest.ts• L217-285, src/…/plugin-discovery.ts• L104-116)

References: src/…/plugin-manifest.ts• L79-95 src/…/plugin-manifest.ts• L155-221 src/…/plugin-discovery.ts• L104-123

Contribution validation

Manifest validation checks relationships between contribution points rather than only checking field types. It rejects duplicate ids and scopes, empty custom-editor matches, conflicting keybindings, keybindings for missing commands, mismatched command contexts, unsupported built-in actions, and event subscriptions without their required capability. Worker commands and event subscriptions also require a main entry. (src/…/plugin-manifest-contribution-validation.ts• L53-191)

References: src/…/plugin-manifest-contribution-validation.ts• L53-191

Artifact trust boundary

Every path declared by a manifest must resolve to a regular file or directory inside the plugin root. Orca applies limits to code, panel and editor pages, images, language packs, themes, syntaxes, templates, and recipes. Install validation then parses content that has meaning beyond the manifest, such as VM recipes and new-file templates. (src/…/plugin-artifact-validation.ts• L29-112, src/…/plugin-artifact-validation.ts• L137-246)

Installed content is copied into a hash-addressed tree and checked again before publication. The copy is rehashed so a source that changes during install cannot become the reviewed tree. A later load of code or a panel checks the installed tree again; mutable development folders use a revision for restart and still bind declarative content to a reviewed identity. (src/…/plugin-install-staging.ts• L90-135, src/…/plugin-install-staging.ts• L201-270, src/…/plugin-content-hash.ts• L7-20, src/…/plugin-content-integrity.ts• L15-62)

References: src/…/plugin-artifact-validation.ts• L29-112 src/…/plugin-artifact-validation.ts• L137-246 src/…/plugin-install-staging.ts• L90-135 src/…/plugin-install-staging.ts• L201-270 src/…/plugin-content-integrity.ts• L15-62

Catalog and enablement policy

The catalog is a discoverable list, not a trust grant. A catalog release points to a Git repository and named ref while recording an exact commit for installation; the host selects the newest release whose minimum Orca version it supports. The install path validates the fetched manifest and bytes again. (src/…/plugin-marketplace.ts• L47-102, src/…/plugin-catalog.ts• L76-89, src/…/plugin-catalog.ts• L163-177)

Catalog trust and source identity

Catalog identity is tied to the repository owner and plugin id. Reserved publishers and official id prefixes are limited to the official catalog, and marketplace entries with unsupported categories are hidden rather than offered for a dead install path. Strict catalog validation catches malformed entries, duplicate ids, bad releases, and image files whose hashes or dimensions do not match the listing. (src/…/plugin-marketplace.ts• L21-33, src/…/plugin-file-validation.ts• L37-59, src/…/plugin-file-validation.ts• L79-163)

The runtime catalog reader is tolerant so one bad listing does not remove other plugins from the marketplace. Catalog CI and authoring validation are strict because repairs must happen before publication. A catalog contribution summary is compared with the installed manifest so a listing cannot describe different behavior from the release it offers. (src/…/plugin-catalog.ts• L19-24, src/…/plugin-catalog.ts• L127-149, src/…/plugin-contribution-summary.ts• L54-93)

Source resolution turns a safe Git URL and ref into the exact commit shown to the user. The install then refuses a moved ref or a source that differs from the preview. An installed marketplace source cannot be silently replaced by another catalog, a direct Git URL, or a local folder because that would change the source used for future updates. (src/…/plugin-git-ref-resolution.ts• L48-117, src/…/plugin-install.ts• L105-159, src/…/plugin-catalog-install-guard.ts• L4-21)

References: src/…/plugin-marketplace.ts• L21-33 src/…/plugin-file-validation.ts• L79-163 src/…/plugin-git-ref-resolution.ts• L48-117 src/…/plugin-catalog-install-guard.ts• L4-21

Orca treats the plugin feature flag, user consent, explicit disablement, content integrity, and the safety list as separate gates. A plugin is usable only when all gates pass. Consent is bound to the plugin key and reviewed fingerprint; an approval for changed capabilities, worker authority, or reviewed declarative bytes does not silently carry forward. (src/…/plugin-activation-policy.ts• L19-59, src/…/plugin-enablement.ts• L12-49, src/…/plugin-service.ts• L243-253)

Enabling a plugin changes settings and then triggers activation reconciliation. Approval also rechecks declarative bytes in the main process, so a renderer or headless caller cannot enable content that changed after review. Bundled data plugins can receive the same approval path from Orca's release, but a user-disabled plugin stays disabled and code still requires review. (src/…/plugin-enablement.ts• L20-49, src/…/plugin-bundled-approval.ts• L11-47, src/…/plugin-declarative-content-integrity.ts• L6-21)

The safety list is a remote block list that is cached before network refresh, checked for schema, time, and ordering errors, and refreshed while plugins are enabled. Failed refreshes retry with bounded backoff so a long session can recover without waiting for the next full interval. A newly blocked plugin loses activation and live frames; its frame storage is also cleared so old local data does not remain available. (src/…/plugin-kill-list-service.ts• L23-151, src/…/plugin-kill-list-service.test.ts• L29-138, src/…/plugin-frame-guest-sessions.ts• L277-313)

References: src/…/plugin-activation-policy.ts• L19-59 src/…/plugin-enablement.ts• L12-49 src/…/plugin-bundled-approval.ts• L11-47 src/…/plugin-kill-list-service.ts• L23-151 src/…/plugin-kill-list-service.test.ts• L29-138 src/…/plugin-frame-guest-sessions.ts• L277-313

Automatic updates

Automatic updates apply only to enabled and approved plugins. The updater previews the exact release, checks its commit and content hash, refreshes the safety list before install, and leaves the current version running when the update needs new access or comes from a moved repository. (src/…/plugin-auto-updater.ts• L41-55, src/…/plugin-auto-updater.ts• L158-230)

Community releases remain listed for a hold period before an automatic install. Updates held for review are surfaced once per plugin version, so a headless host and a later desktop session can both learn that approval is needed without repeatedly showing the same notice. (src/…/plugin-auto-updater.ts• L23-26, src/…/plugin-auto-updater.ts• L187-214, src/…/plugin-update-review-notices.ts• L23-72)

References: src/…/plugin-auto-updater.ts• L41-55 src/…/plugin-auto-updater.ts• L158-230 src/…/plugin-update-review-notices.ts• L23-72

Worker supervision and host API

Worker plugins run out of process and reach Orca through a versioned host API. The worker manager admits only approved specifications, limits concurrent workers, verifies content before spawn, and treats each activation generation as distinct so an old worker cannot revive after a refresh or revocation.

Worker activation and supervision

Worker activation follows a controlled sequence:

  1. The service builds a worker specification from the approved manifest.
  2. The manager waits for a worker slot and repeats the approval and content checks before spawn.
  3. The worker imports its entry and calls the default activate export.
  4. The worker reports its registered commands as ready.
  5. The manager invokes commands and delivers events only while the approval and generation remain current.

The default pool allows five active workers. A worker that exits unexpectedly can restart up to three times with increasing delays. Repeated failure marks it errored, while a clean exit becomes inactive; an idle worker is reaped after five minutes and starts fresh on its next use. (src/…/plugin-host-protocol.ts• L87-92, src/…/plugin-worker-startup.ts• L25-30, src/…/plugin-worker-manager.ts• L91-183, src/…/plugin-supervisor.ts• L20-76, src/…/plugin-worker-manager.ts• L248-271)

Refresh and removal cancel pending activation as well as running work. A crash restart must pass the current approval and content checks, and a worker that reports an undeclared command is stopped instead of being registered. (src/…/plugin-worker-controller.ts• L71-125, src/…/plugin-worker-manager.ts• L230-246, src/…/plugin-worker-manager.ts• L314-326)

References: src/…/plugin-worker-startup.ts• L25-30 src/…/plugin-worker-manager.ts• L91-183 src/…/plugin-worker-controller.ts• L71-125 src/…/plugin-worker-manager.ts• L230-246

Worker host contract

The worker contract has two layers. The lifecycle channel carries initialization, readiness, logs, fatal errors, command invocation, event delivery, cancellation, and shutdown. The public orca object gives worker code command registration, event subscriptions, host calls, capability information, and logging. (src/…/plugin-host-protocol.ts• L11-61, src/…/plugin-host-runtime.ts• L87-160)

The host API table is the stable contract for all plugin surfaces. Each method has strict parameter and result schemas, a host API version, a required capability, a resource scope, a mutation flag, and an allowed surface. The host checks these rules for every call, records mutation intent, and rechecks that the plugin is still active before the side effect. (src/…/plugin-host-api.ts• L17-32, src/…/plugin-host-api.ts• L135-305, src/…/plugin-host-methods.ts• L41-129)

Workers can use runtime-backed workspace actions such as listing workspaces, opening a workspace, reading or creating terminals, launching an agent, opening an editor, and running an Orca action. These actions carry explicit workspace or terminal targets and are refused if approval is lost while a call waits. Panel-only requests use the panel bridge and cannot be called by a worker without an open panel. (src/…/plugin-host-workspace-method-bindings.ts• L107-226, src/…/plugin-host-panel-method-bindings.ts• L13-62, src/…/plugin-host-call-scope.ts• L4-23)

References: src/…/plugin-host-runtime.ts• L87-160 src/…/plugin-host-api.ts• L17-32 src/…/plugin-host-methods.ts• L41-129 src/…/plugin-host-workspace-method-bindings.ts• L107-226 src/…/plugin-host-call-scope.ts• L4-23

Contribution surfaces

Contribution points let a plugin add user-facing behavior without giving every plugin the same authority. Each point has a minimum execution profile: data contributions are inert files, declarative contributions describe host actions, sandboxed UI contributions render plugin pages inside controlled frames, and trusted-worker contributions run code in a worker. (src/…/plugin-contribution-points.ts• L215-244, src/…/plugin-manifest.ts• L166-171)

Panels and custom editors

Panels add entries to the sidebar and render a plugin page in a panel frame. Custom editors use the same frame model to open matching files beside Source; they receive document text or bytes through the editor surface and send edits through the frame API. Both surfaces require sandboxed UI authority or higher. (src/…/plugin-panel-contribution.ts• L94-151, src/…/plugin-custom-editor-contribution.ts• L18-98)

The desktop frame runs in a plugin-specific session. The session serves only the approved plugin origin, blocks network and navigation outside the allowed frame URLs, denies popups and permissions, and closes guests when approval is lost. A bearer session token is tied to the owner, plugin root, manifest revision, and contribution, so an old frame cannot select a new plugin identity. (src/…/plugin-frame-guest-sessions.ts• L30-34, src/…/plugin-frame-guest-sessions.ts• L117-145, src/…/plugin-frame-guest-policies.ts• L8-31, src/…/plugin-panel-sessions.ts• L33-75)

Host calls from a panel or editor are limited by the frame surface and, for desktop-only actions, by a user gesture. The host verifies the session again before each call, and a stale root or manifest revision makes the session unavailable. (src/…/plugin-panel-controller.ts• L132-191, src/…/plugin-host-api.ts• L84-125)

References: src/…/plugin-panel-contribution.ts• L94-151 src/…/plugin-custom-editor-contribution.ts• L18-98 src/…/plugin-frame-guest-sessions.ts• L30-34 src/…/plugin-panel-controller.ts• L132-191 src/…/plugin-panel-sessions.ts• L33-75

Commands and keybindings

Commands place named actions in the command palette. A command with a built-in action stays declarative and does not start a worker; a command without an action is handled by the plugin worker and therefore needs main. Keybindings refer to contributed command ids and must use the same global or workspace context as their command. (src/…/plugin-command-contribution.ts• L32-76, src/…/plugin-manifest-contribution-validation.ts• L160-199)

Orca previews command registrations before approval, then activates only approved commands. Keybinding conflicts between approved plugins block the conflicting plugin's command registrations. A worker command may replace a built-in action, but only the plugin installed first owns that replacement; later contenders remain visible as replaced commands and do not silently take over. (src/…/plugin-command-registry.ts• L56-112, src/…/plugin-command-replacement-owners.ts• L8-53)

Worker command invocation checks that the plugin is approved, that the command is worker-owned, and that the worker registered the same command. A built-in action alias cannot be used to start worker code through direct IPC. (src/…/plugin-command-invocation.ts• L4-36)

References: src/…/plugin-command-contribution.ts• L32-76 src/…/plugin-manifest-contribution-validation.ts• L160-199 src/…/plugin-command-registry.ts• L56-112 src/…/plugin-command-replacement-owners.ts• L8-53 src/…/plugin-command-invocation.ts• L4-36

Files and editor matching

New-file contributions add a named file type to the tab-bar plus menu and command palette. Orca creates the file in the active workspace with the declared extension and optional UTF-8 template; the file then uses the syntax or custom editor that matches that extension. (src/…/plugin-new-file-contribution.ts• L16-63, src/…/plugin-artifact-validation.ts• L223-263)

Syntax contributions map extensions or exact file names to a language grammar and optional language configuration. Custom editors use the same matching model but take ownership of the file view. File suggestions use only supported last extensions, and a file that Orca already opens as text receives editor suggestions rather than syntax suggestions. (src/…/plugin-content-pack-contributions.ts• L149-189, src/…/plugin-file-type.ts• L16-41)

An editor can receive text or raw bytes. An editor marked as isolated needs the desktop app's isolated frame; browser clients and unsupported desktop frame modes fail closed and keep the file in Source. (src/…/plugin-custom-editor-contribution.ts• L18-98, src/…/PluginCustomEditorFrame.tsx• L1-200)

References: src/…/plugin-new-file-contribution.ts• L16-63 src/…/plugin-artifact-validation.ts• L223-263 src/…/plugin-content-pack-contributions.ts• L149-189 src/…/PluginCustomEditorFrame.tsx• L1-200

Themes and content packs

Theme contributions add app color themes, terminal palettes, icon themes, translations, and other data packs through bounded JSON or locale artifacts. These contributions use the data profile and are loaded as content rather than executed as plugin code. Approved plugins can also publish a runtime app and terminal appearance pair through the host API. Orca validates both artifacts, requires matching light or dark modes, rejects runtime backgrounds, persists the owner's selection, and overlays it only while that owner remains approved. (src/…/plugin-contribution-points.ts• L147-187, src/…/plugin-content-pack-contributions.ts• L45-70, src/…/plugin-content-pack-contributions.ts• L122-142, src/…/plugin-appearance-colors.ts• L22-75, src/…/plugin-appearance-service.ts• L111-169, src/…/plugin-appearance-service.ts• L205-251)

Runtime appearance changes use a conditional revision. A stale revision is rejected, and a settings failure restores the previous owner state so the saved appearance and active settings do not drift apart. (src/…/plugin-appearance-service.ts• L61-109, src/…/plugin-appearance-service.ts• L111-169)

The content-pack registry reconciles approved declarations before the service starts worker code. Theme and language data is parsed when it is loaded; icon SVGs and theme background images are checked when selected or served, so unused packs do not add work at startup. This separation lets Orca disable or roll back content contributions without leaving worker or panel state active. (src/…/plugin-service.ts• L176-211, src/…/plugin-theme-registries.ts• L20-82, src/…/plugin-icon-theme-registry.ts• L29-99, src/…/plugin-language-pack-registry.ts• L37-69)

Declarative settings and status-bar items extend the same model. Settings belong to the plugin and require its settings capability; a status-bar item names a command and can be changed by the worker through statusBar.update. Hooks and event subscriptions require a trusted worker because they can affect Orca actions or receive runtime events. (src/…/plugin-contribution-points.ts• L148-159, src/…/plugin-contribution-points.ts• L214-224, src/…/plugin-host-status-bar-method-bindings.ts• L6-27, src/…/plugin-manifest-contribution-validation.ts• L201-231)

References: src/…/plugin-contribution-points.ts• L147-187 src/…/plugin-service.ts• L176-211 src/…/plugin-theme-registries.ts• L20-92 src/…/plugin-icon-theme-registry.ts• L29-99 src/…/plugin-appearance-colors.ts• L22-75 src/…/plugin-appearance-service.ts• L61-169 src/…/plugin-appearance-service.ts• L205-261 src/…/plugin-host-status-bar-method-bindings.ts• L6-27

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the manifest schema, contribution execution policy, artifact path list, and catalog contribution summary aligned. A new contribution can otherwise validate in one layer but be omitted from install checks or marketplace review.
  • Keep Git ref resolution, catalog release commits, install lock sources, and update preview identity aligned. A source change must not reuse an old install or update hold.
  • Keep the host API method table aligned with worker, panel, editor, and runtime bindings. The table controls schemas, capability gates, surface access, generated reference data, and host.has results.
  • Preserve consent identity when changing capabilities, execution tiers, or reviewed declarative bytes. A weaker fingerprint can enable changed behavior without a new review.
  • Keep worker generation, approval, and content checks on every restart path. A refresh, safety-list block, or revocation must cancel pending activation and prevent an old worker from returning to the active set.
  • Keep panel frame admission, session bindings, guest network policy, and renderer fallbacks aligned. A stale frame must fail closed after refresh, update, removal, or disablement.
  • Keep command replacement ownership tied to install order and command registration state. A new replacement path must not silently displace the current owner.
  • Keep runtime appearance revisions, persisted owner snapshots, artifact validation, and settings updates aligned. A stale or failed update must not replace the selected appearance with unapproved or partial state.

Important failure modes

TriggerConsequenceGuard
A manifest declares a file outside the plugin root, uses a wrong path case, or exceeds an artifact limitDiscovery or install rejects the plugin before activationReal-path containment checks, exact path checks, and per-artifact limits
Plugin content changes while it is copied or after its installed hash is recordedThe reviewed source and the runnable tree no longer matchRehash before publication and integrity checks before code or panel use
A catalog install is replaced by another sourceFuture updates can follow a different source than the one the user approvedInstall lock provenance and catalog takeover refusal
A safety-list refresh receives a future or older snapshot, or fails during a long sessionThe invalid snapshot is refused while the last valid revocation stays active; a failed refresh retries with bounded backoffSchema, time, and ordering checks with cached state and retry scheduling
A safety-list refresh blocks a pluginWorkers stop, frames close, and frame storage is clearedCached validated list with ordered refresh and live policy checks
An automatic update needs more access or its repository movedThe current version keeps running and the update waits for reviewPreview comparison, access-growth check, and persisted review notice
A worker crashes repeatedly or registers an undeclared commandThe worker becomes errored and its commands are not exposedBounded restart policy and command registration check
A worker or frame calls a method outside its surface or capabilityThe host rejects the call; pending effects are cancelled when approval is lostShared method metadata, strict schemas, and active-call scope checks
A runtime appearance update uses an old revision or its owner is no longer approvedThe update is rejected and the prior appearance remains selectedConditional revisions and approval checks before persistence
A runtime appearance pair is too large, has a runtime background, or mixes light and dark modesThe appearance is rejected before it can change app, editor, or terminal selectionBounded strict artifact parsing with mode and background checks
Two approved plugins claim the same keybinding or replacementConflicting commands are withheld, or the later replacement is marked as replacedRegistry conflict detection and install-order ownership
A panel uses an old session after plugin state changesThe frame cannot continue to call the hostSession binding checks for owner, root, manifest revision, and contribution

Key files

FileWhy to read it
src/…/plugin-service.tsShows the ordered refresh, approval gates, contribution reconciliation, and worker coordination.
src/…/plugin-manifest.tsDefines the manifest contract, identity, execution profiles, and host/runtime parsing split.
src/…/plugin-discovery.tsShows how installed and development plugins become valid or invalid discovered entries.
src/…/plugin-artifact-validation.tsDefines the artifact trust boundary and content checks for declared files.
src/…/plugin-install-staging.tsShows preview, hashing, staged publication, and install-time revalidation.
src/…/plugin-auto-updater.tsExplains automatic update holds, review gates, and exact-release checks.
src/…/plugin-kill-list-service.tsShows how remote plugin blocks are cached, refreshed, retried, and applied.
src/…/plugin-appearance-colors.tsDefines the shared validation and slot mapping for runtime app and terminal appearance pairs.
src/…/plugin-appearance-service.tsShows how approved plugins publish and persist runtime app and terminal appearance.
src/…/plugin-enablement.tsShows how consent and explicit enablement update policy state and trigger reconciliation.
src/…/plugin-worker-controller.tsCoordinates worker admission, content checks, command registration, and reconciliation.
src/…/plugin-worker-manager.tsCoordinates worker generations, slots, idle cleanup, and restart handling.
src/…/plugin-host-methods.tsProvides the shared host-call gate, validation, audit, and active-call checks.
src/…/plugin-host-api.tsServes as the public host API source of truth for schemas, capabilities, scopes, and surfaces.
src/…/plugin-panel-controller.tsShows how panel and editor frames are loaded, bound, and revoked.
src/…/plugin-frame-guest-sessions.tsDefines the isolated frame session, origin boundary, and revocation behavior.
src/…/plugin-command-registry.tsShows command preview, approval filtering, and keybinding conflict handling.
src/…/plugin-contribution-points.tsMaps contribution types to execution profiles, catalog types, and content review behavior.
src/…/plugin-theme-registries.tsShows how app and terminal theme artifacts become content registrations.