Plugin platform
Orca's plugin platform lets trusted extensions add product features while keeping their authority narrow and reviewable. It turns plugin sources into checked identities, stores the exact reviewed content, activates only approved contributions, and exposes shared host contracts across the desktop app, headless runtime, WSL, workers, and plugin panels.
Platform boundary
The platform separates declaration, approval, execution, and host access. The desktop app and headless orca serve runtime use the same service model. WSL receives bounded plugin data for a guest agent instead of becoming a second desktop plugin host.
This diagram shows how a plugin moves from source to an active contribution.
flowchart LR
A[Bundled, local, Git, development, or catalog source] --> B[Discover and validate identity]
B --> C[Preview and verify exact content]
C --> D[Store reviewed content and provenance]
D --> E[Review approval and policy]
E --> F[Reconcile contributions and workers]
F --> G[Content and declarative features]
F --> H[Panel or editor session]
F --> I[Supervised worker]
I --> J[Versioned host API]
H --> J
E --> K[Bounded WSL delivery]
K --> L[Guest-owned agent overlay]
Desktop and headless hosts
The desktop app and headless orca serve runtime share the plugin service boundary. Both discover plugins, apply approval and policy, reconcile content, and start approved runtime work. Host options provide only the services available in that runtime, so a headless host can use the same contract without pretending to have desktop UI services.
References: src/…/plugin-service.ts• L50-123 src/…/plugin-service.ts• L142-212 src/…/plugin-service-options.ts• L9-31
WSL guest boundary
WSL is a guest delivery path, not a desktop plugin host. Orca sends selected plugin sources across a bounded boundary. The Linux guest owns the copied files and agent configuration, which keeps Windows paths and Electron services out of guest sessions.
References: src/…/wsl-install-plugins-handler.ts• L34-67 src/…/plugin-overlay.ts• L104-127 src/…/plugin-overlay.ts• L149-183
Discovery and identity
Discovery turns bundled, local, Git, development, and catalog sources into plugin entries that can be reviewed and managed. Invalid entries retain their error so one bad source does not hide other plugins.
Source identity
The stable plugin key is <publisher>.<id>. Catalog and Git sources keep their source details and resolved commit with the key. This provenance stops a different catalog from silently taking ownership of an installed plugin.
References: src/…/plugin-manifest.ts• L81-96 src/…/plugin-install.ts• L105-223 src/…/plugin-marketplace-installer.test.ts• L187-225
Installed and development entries
Installed content has a checked content identity and a current version. Development folders remain mutable and may take precedence for the same key, but identity conflicts fail. Before activation, discovery checks the manifest, host range, declared files, publisher, and content state.
References: src/…/plugin-discovery.ts• L35-63 src/…/plugin-discovery.ts• L110-173 src/…/plugin-content-integrity.ts• L17-35
Manifest and contribution model
The manifest is the shared contract for plugin identity, host compatibility, execution profile, capabilities, and product contributions. It limits what a plugin can offer before any worker or panel starts.
Execution profiles and capabilities
Execution profiles set the maximum kind of work a plugin may perform:
dataprovides content such as themes, syntax, icons, or translations.declarativeprovides fixed commands, keybindings, recipes, or status items.sandboxed-uiprovides panels and custom editors.trusted-workerruns plugin code and can use worker host actions after approval.
Capabilities describe the host actions that approval grants. Manifest validation rejects contributions that need authority outside the selected profile or declared capability set. Event subscriptions also name the read capability for their domain.
References: src/…/plugin-capabilities.ts• L11-43 src/…/plugin-capability-reach.ts• L4-26 src/…/plugin-manifest-contribution-validation.ts• L199-241 src/…/plugin-event-contribution.ts• L40-70
Product contributions
Contribution points connect a plugin to focused product features. They include content packs, declarative UI, runtime panels and editors, worker commands and events, hooks, settings, status items, and appearance. Orca validates each declared family before it publishes that family's entries. A failed family contributes no partial entries.
References: src/…/plugin-content-pack-registry.ts• L29-115 src/…/plugin-artifact-pack-registry.ts• L15-78 src/…/plugin-manifest-contribution-validation.ts• L62-243
Appearance and editor typography
Appearance contributions let an approved plugin own a controlled set of app, editor, and terminal colors. Runtime appearance submissions use a plugin-owned app and terminal theme pair. Orca bounds and strictly checks both artifacts, rejects unsupported backgrounds and mismatched modes, and derives the app, editor, terminal, and terminal-palette selections from the accepted pair. Orca restores safe prior or built-in appearance when an update cannot be committed. The shared host contract also exposes the current file-editor typography as read-only data. Plugins can subscribe to a matching change event without receiving remote host settings.
References: src/…/plugin-appearance-service.ts• L44-203 src/…/plugin-appearance-colors.ts• L22-75 src/…/plugin-editor-typography.ts• L28-95 src/…/plugin-host-api-editor-typography.ts• L14-71 src/…/protected-copy-keys.json• L803-806
Catalogs and installation
Catalogs make Git repositories into reviewable plugin sources. Installation treats source material as untrusted and publishes only the content that the person previewed and Orca checked.
Catalog sources
People add a catalog with a Git URL and ref. Orca reads a bounded catalog index at a resolved commit and supports both the current and older catalog formats. A catalog entry may point to one plugin or a safe subdirectory in a shared repository.
References: src/…/PluginMarketplaceSourceDialog.tsx• L51-121 src/…/plugin-marketplace-fetch.ts• L20-95 src/…/plugin-catalog.test.ts• L41-82
Source and artifact checks
The install flow previews the source, pins its Git commit, checks the manifest against the host, confirms the expected identity, verifies declared artifacts, and hashes the complete plugin tree. The stored hash is checked again before code starts, so a changed installed tree cannot use an earlier review.
References: src/…/plugin-install.ts• L105-229 src/…/plugin-content-integrity.ts• L17-64 src/…/plugin-worker-controller.ts• L71-103 src/…/plugin-theme-artifact.test.ts• L8-50
Immutable publication and updates
After verification, Orca stores an immutable content tree with provenance, approval data, and a current version pointer. Writes are serialized so concurrent installs do not publish partial state. A failed publication leaves the prior usable pointer. Catalog updates preserve source ownership and pause when they add access, change execution authority, or move the source until the person reviews them.
References: src/…/plugin-install-staging.ts• L90-137 src/…/plugin-install-staging.ts• L201-295 src/…/plugin-auto-updater.ts• L158-231
Consent and activation
Installation makes checked content available. Approval makes it active. Orca ties approval to the plugin's declared access, execution authority, contribution reach, and the exact content that can execute or affect product behavior.
Approval identity
The approval fingerprint changes when capabilities, trust level, or sensitive contribution reach changes. Executable or instruction-bearing content changes also require review. This prevents a plugin from keeping old consent after its authority or reviewed bytes change.
References: src/…/plugin-capabilities.ts• L67-85 src/…/plugin-command-replaces.test.ts• L24-55 src/…/plugin-custom-editor-contribution.test.ts• L139-160 src/…/plugin-discovery.ts• L140-169
Activation reconciliation
The plugin service serializes refresh, removal, enablement, and policy changes. Live policy fails closed when the plugin system is disabled, when consent no longer matches the current plugin, or when Orca blocks the plugin. The service publishes the new plugin identity set before it stops old work, reconciles approved content, then reconciles workers and notifies clients. This order prevents removed, changed, disabled, or blocked plugins from starting new work during a refresh.
References: src/…/plugin-activation-policy.ts• L9-59 src/…/plugin-service.ts• L153-212 src/…/plugin-service.ts• L315-333 src/…/plugin-worker-controller.ts• L135-163
Host surfaces and isolation
Plugins use explicit host surfaces instead of direct Electron or runtime access. A host call carries a method contract, surface, capability, scope, and caller identity. The same shared contract serves workers, panels, custom editors, the desktop app, and headless hosts while each surface receives only its allowed methods.
Versioned host API
The host API is a versioned shared facade with strict parameter and result contracts. It covers scoped workspace and terminal access, private storage and secrets, settings, notifications, panels, status items, appearance, editor typography, and selected desktop actions. Mutations are audited, and desktop-only actions stay unavailable on headless hosts.
References: src/…/plugin-host-api.ts• L18-33 src/…/plugin-host-api.ts• L135-305 src/…/plugin-host-method-bindings.ts• L42-109 src/…/plugin-host-method-bindings.ts• L120-241
Live call scope
The host checks approval when a call begins and checks it again while protected work runs. The call becomes invalid if the plugin is removed, disabled, blocked, moved to different content, or changes manifest. Workspace and terminal actions also confirm that the target remains in the active workspace before they act.
References: src/…/plugin-service-host-call.ts• L37-63 src/…/plugin-service-host-call.ts• L65-107 src/…/plugin-host-method-bindings.ts• L164-177
Worker supervision
Trusted worker code runs outside the main process under host supervision. The controller verifies the content before each spawn, checks approval during startup, rejects undeclared commands, and stops or restarts workers when their approved specification changes. Idle cleanup and bounded capacity keep one plugin from consuming all worker slots.
References: src/…/plugin-worker-controller.ts• L37-126 src/…/plugin-worker-controller.ts• L135-177 src/…/plugin-worker-controller.test.ts• L90-149
Panel and editor sessions
Panels and custom editors run in plugin-specific guest sessions. A panel session forwards requests to the plugin's own worker and sends pushes only to its open channel. Event subscriptions require the plugin's current approval and any domain read grant. Message size, rate, JSON shape, session lifetime, and stale workspace replay are checked at the bridge.
References: src/…/plugin-panel-bridge.ts• L60-136 src/…/plugin-panel-bridge.ts• L144-240 src/…/plugin-panel-bridge.test.ts• L43-101
Event projections
Events give plugins bounded views of product state rather than raw runtime objects. Orca validates each payload before delivery, sends events only to declared and approved listeners, and starts a worker on demand when an approved worker subscribes. Workspace and agent events use the current runtime delegate, while editor typography reports the local Orca editor settings.
References: src/…/plugin-events.ts• L12-18 src/…/plugin-event-delivery.ts• L66-101 src/…/plugin-runtime-binding.ts• L81-140 src/…/plugin-editor-typography.ts• L37-91
Cross-host runtime flow
The runtime binding connects the plugin service to workspace, terminal, agent-status, notification, and hook services. It sends only projected data across the boundary and does work only while an approved listener exists.
When Orca processes a runtime event, it follows this sequence:
- The runtime binding checks whether an approved worker or open panel wants the event.
- It projects the source state into the shared event schema.
- It enriches the projection with bounded workspace or terminal data when needed.
- The service delivers it to matching workers and subscribed panels.
- It drops malformed payloads and stops queued work when the last listener closes.
References: src/…/plugin-runtime-binding.ts• L32-60 src/…/plugin-runtime-binding.ts• L81-140 src/…/plugin-service.ts• L283-304 src/…/plugin-events.ts• L47-83
Related pages
- Plugin lifecycle and contributions explains the detailed lifecycle stages and the contribution surfaces available to plugin authors.
- Desktop app platform explains the desktop host that supplies plugin services and product integration points.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep manifest profiles, capability reach, event grants, host method surfaces, and approval fingerprints aligned.
- When adding a host method or event, update its shared schema, runtime binding, surface rule, capability rule, generated reference, and revocation path together.
- When changing content publication or worker startup, preserve the reviewed tree hash, provenance, current pointer, and pre-spawn integrity check.
- When changing panels or runtime projections, keep session identity, approval checks, payload schemas, message budgets, replay behavior, and listener backpressure aligned.
- When changing editor typography or appearance, keep local-source semantics, safe fallback, protected product copy, and change-event payloads consistent.
- When changing WSL delivery, keep source bounds and guest-owned paths separate from desktop host services.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A manifest contribution needs authority outside its profile or capability set | Discovery rejects the plugin or its contribution | Profile reach and contribution validation |
| Reviewed plugin bytes change before a worker starts | The worker does not start | Current tree hash verification |
| Approval changes during worker start or a protected host call | The old code or action is stopped | Live approval, manifest, root, and revision checks |
| A panel sends an oversized, malformed, or stale message | The host refuses or drops the message | Strict schemas, size and rate budgets, and session checks |
| An event payload cannot satisfy its shared schema | No plugin receives that payload | Bounded projection and delivery validation |
| A worker registers a command not declared in its manifest | Activation fails and the worker is stopped | Registered-command check |
| A headless host lacks a desktop service | The desktop-only call returns unavailable | Host-specific service binding |
| An appearance update fails safety or commit checks | Unsafe colors are dropped or the prior appearance remains | Theme filtering and conditional publication |
| A WSL overlay exceeds bounds or cannot be written | The guest starts without that optional integration | Per-source bounds and guest fallback |
Key files
| File | Why to read it |
|---|---|
| src/…/plugin-service.ts | Central owner for discovery refresh, approval, content reconciliation, workers, panels, and events. |
| src/…/plugin-activation-policy.ts | Defines the live consent and safety policy that allows or blocks plugin activation. |
| src/…/plugin-discovery.ts | Shows how installed and development sources become valid or invalid entries. |
| src/…/plugin-install.ts | Shows source selection, provenance, current content, and rollback entry points. |
| src/…/plugin-install-staging.ts | Shows preview, verification, immutable publication, and provenance. |
| src/…/plugin-manifest.ts | Defines the shared plugin identity and manifest contract. |
| src/…/plugin-manifest-contribution-validation.ts | Defines cross-field rules for product contributions. |
| src/…/plugin-host-api.ts | Defines the versioned host contract, surfaces, scopes, and schemas. |
| src/…/plugin-service-host-call.ts | Defines per-call policy, caller binding, and live revocation. |
| src/…/plugin-worker-controller.ts | Shows worker approval, integrity checks, activation, and reconciliation. |
| src/…/plugin-panel-bridge.ts | Shows panel sessions, worker requests, event subscriptions, and budgets. |
| src/…/plugin-event-delivery.ts | Shows event filtering, projection, and on-demand worker delivery. |
| src/…/plugin-runtime-binding.ts | Connects plugin events and host services to the active runtime. |
| src/…/plugin-appearance-colors.ts | Shows validation and selection of runtime app and terminal appearance artifacts. |
| src/…/plugin-editor-typography.ts | Defines the local editor typography source and change event. |
| src/…/wsl-install-plugins-handler.ts | Shows how bounded plugin sources cross into WSL. |