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
Consent and enablement
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:
- The service builds a worker specification from the approved manifest.
- The manager waits for a worker slot and repeats the approval and content checks before spawn.
- The worker imports its entry and calls the default
activateexport. - The worker reports its registered commands as ready.
- 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.hasresults. - 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
| Trigger | Consequence | Guard |
|---|---|---|
| A manifest declares a file outside the plugin root, uses a wrong path case, or exceeds an artifact limit | Discovery or install rejects the plugin before activation | Real-path containment checks, exact path checks, and per-artifact limits |
| Plugin content changes while it is copied or after its installed hash is recorded | The reviewed source and the runnable tree no longer match | Rehash before publication and integrity checks before code or panel use |
| A catalog install is replaced by another source | Future updates can follow a different source than the one the user approved | Install lock provenance and catalog takeover refusal |
| A safety-list refresh receives a future or older snapshot, or fails during a long session | The invalid snapshot is refused while the last valid revocation stays active; a failed refresh retries with bounded backoff | Schema, time, and ordering checks with cached state and retry scheduling |
| A safety-list refresh blocks a plugin | Workers stop, frames close, and frame storage is cleared | Cached validated list with ordered refresh and live policy checks |
| An automatic update needs more access or its repository moved | The current version keeps running and the update waits for review | Preview comparison, access-growth check, and persisted review notice |
| A worker crashes repeatedly or registers an undeclared command | The worker becomes errored and its commands are not exposed | Bounded restart policy and command registration check |
| A worker or frame calls a method outside its surface or capability | The host rejects the call; pending effects are cancelled when approval is lost | Shared method metadata, strict schemas, and active-call scope checks |
| A runtime appearance update uses an old revision or its owner is no longer approved | The update is rejected and the prior appearance remains selected | Conditional revisions and approval checks before persistence |
| A runtime appearance pair is too large, has a runtime background, or mixes light and dark modes | The appearance is rejected before it can change app, editor, or terminal selection | Bounded strict artifact parsing with mode and background checks |
| Two approved plugins claim the same keybinding or replacement | Conflicting commands are withheld, or the later replacement is marked as replaced | Registry conflict detection and install-order ownership |
| A panel uses an old session after plugin state changes | The frame cannot continue to call the host | Session binding checks for owner, root, manifest revision, and contribution |
Key files
| File | Why to read it |
|---|---|
| src/…/plugin-service.ts | Shows the ordered refresh, approval gates, contribution reconciliation, and worker coordination. |
| src/…/plugin-manifest.ts | Defines the manifest contract, identity, execution profiles, and host/runtime parsing split. |
| src/…/plugin-discovery.ts | Shows how installed and development plugins become valid or invalid discovered entries. |
| src/…/plugin-artifact-validation.ts | Defines the artifact trust boundary and content checks for declared files. |
| src/…/plugin-install-staging.ts | Shows preview, hashing, staged publication, and install-time revalidation. |
| src/…/plugin-auto-updater.ts | Explains automatic update holds, review gates, and exact-release checks. |
| src/…/plugin-kill-list-service.ts | Shows how remote plugin blocks are cached, refreshed, retried, and applied. |
| src/…/plugin-appearance-colors.ts | Defines the shared validation and slot mapping for runtime app and terminal appearance pairs. |
| src/…/plugin-appearance-service.ts | Shows how approved plugins publish and persist runtime app and terminal appearance. |
| src/…/plugin-enablement.ts | Shows how consent and explicit enablement update policy state and trigger reconciliation. |
| src/…/plugin-worker-controller.ts | Coordinates worker admission, content checks, command registration, and reconciliation. |
| src/…/plugin-worker-manager.ts | Coordinates worker generations, slots, idle cleanup, and restart handling. |
| src/…/plugin-host-methods.ts | Provides the shared host-call gate, validation, audit, and active-call checks. |
| src/…/plugin-host-api.ts | Serves as the public host API source of truth for schemas, capabilities, scopes, and surfaces. |
| src/…/plugin-panel-controller.ts | Shows how panel and editor frames are loaded, bound, and revoked. |
| src/…/plugin-frame-guest-sessions.ts | Defines the isolated frame session, origin boundary, and revocation behavior. |
| src/…/plugin-command-registry.ts | Shows command preview, approval filtering, and keybinding conflict handling. |
| src/…/plugin-contribution-points.ts | Maps contribution types to execution profiles, catalog types, and content review behavior. |
| src/…/plugin-theme-registries.ts | Shows how app and terminal theme artifacts become content registrations. |