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-platform

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:

  • data provides content such as themes, syntax, icons, or translations.
  • declarative provides fixed commands, keybindings, recipes, or status items.
  • sandboxed-ui provides panels and custom editors.
  • trusted-worker runs 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

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:

  1. The runtime binding checks whether an approved worker or open panel wants the event.
  2. It projects the source state into the shared event schema.
  3. It enriches the projection with bounded workspace or terminal data when needed.
  4. The service delivers it to matching workers and subscribed panels.
  5. 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

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

TriggerConsequenceGuard
A manifest contribution needs authority outside its profile or capability setDiscovery rejects the plugin or its contributionProfile reach and contribution validation
Reviewed plugin bytes change before a worker startsThe worker does not startCurrent tree hash verification
Approval changes during worker start or a protected host callThe old code or action is stoppedLive approval, manifest, root, and revision checks
A panel sends an oversized, malformed, or stale messageThe host refuses or drops the messageStrict schemas, size and rate budgets, and session checks
An event payload cannot satisfy its shared schemaNo plugin receives that payloadBounded projection and delivery validation
A worker registers a command not declared in its manifestActivation fails and the worker is stoppedRegistered-command check
A headless host lacks a desktop serviceThe desktop-only call returns unavailableHost-specific service binding
An appearance update fails safety or commit checksUnsafe colors are dropped or the prior appearance remainsTheme filtering and conditional publication
A WSL overlay exceeds bounds or cannot be writtenThe guest starts without that optional integrationPer-source bounds and guest fallback

Key files

FileWhy to read it
src/…/plugin-service.tsCentral owner for discovery refresh, approval, content reconciliation, workers, panels, and events.
src/…/plugin-activation-policy.tsDefines the live consent and safety policy that allows or blocks plugin activation.
src/…/plugin-discovery.tsShows how installed and development sources become valid or invalid entries.
src/…/plugin-install.tsShows source selection, provenance, current content, and rollback entry points.
src/…/plugin-install-staging.tsShows preview, verification, immutable publication, and provenance.
src/…/plugin-manifest.tsDefines the shared plugin identity and manifest contract.
src/…/plugin-manifest-contribution-validation.tsDefines cross-field rules for product contributions.
src/…/plugin-host-api.tsDefines the versioned host contract, surfaces, scopes, and schemas.
src/…/plugin-service-host-call.tsDefines per-call policy, caller binding, and live revocation.
src/…/plugin-worker-controller.tsShows worker approval, integrity checks, activation, and reconciliation.
src/…/plugin-panel-bridge.tsShows panel sessions, worker requests, event subscriptions, and budgets.
src/…/plugin-event-delivery.tsShows event filtering, projection, and on-demand worker delivery.
src/…/plugin-runtime-binding.tsConnects plugin events and host services to the active runtime.
src/…/plugin-appearance-colors.tsShows validation and selection of runtime app and terminal appearance artifacts.
src/…/plugin-editor-typography.tsDefines the local editor typography source and change event.
src/…/wsl-install-plugins-handler.tsShows how bounded plugin sources cross into WSL.