Skip to content

armgit / orca

Public Imported from GitHub
0

Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

6.4 KB
Raw Blame

Orca plugin host API reference

Host API 1.0 ("pluginApi": 1). Workers call a method with await orca.host.call(name, params); panels and custom editors call the same methods through window.orca.host.call(name, params). Each method lists the surfaces allowed to call it; any other surface gets not_permitted. orca.host.has(name) answers synchronously whether this Orca offers a method on the current surface, and orca.api is { major, minor }. See Plugin authoring for the frame API.

Every call is checked against the capabilities the user approved, and params are validated before Orca runs anything: params are strict, so a field this Orca does not know is refused with invalid_params instead of being dropped. Mutations are recorded in the audit log as plugin:<publisher>.<id>.

Methods

Method Capability Surfaces Mutation Since Summary
workspace.readContext workspace:read worker, panel, editor no 1.0 Branch, name and terminal ids of the focused workspace, or null when none is focused.
terminal.sendText terminal:send worker yes 1.0 Types text into one terminal named by id, optionally pressing Enter.
notifications.show notifications:show worker, panel, editor yes 1.0 Shows a desktop notification.
storage.get storage:own worker no 1.0 Reads a JSON value from the plugin's private store; null when absent.
storage.set storage:own worker yes 1.0 Writes a JSON value to the plugin's private store.
storage.delete storage:own worker yes 1.0 Removes a key from the plugin's private store.
storage.keys storage:own worker no 1.0 Lists the keys in the plugin's private store.
secrets.get secrets:own worker no 1.0 Reads a secret from the plugin's encrypted secrets file; null when absent.
secrets.set secrets:own worker yes 1.0 Stores a secret in the plugin's encrypted secrets file.
secrets.delete secrets:own worker yes 1.0 Removes a secret from the plugin's encrypted secrets file.
settings.get settings:own worker no 1.0 Reads every setting the plugin owns.
settings.set settings:own worker yes 1.0 Writes one setting the plugin owns.

workspace.readContext

Branch, name and terminal ids of the focused workspace, or null when none is focused.

(params: {}) => { branch: string; displayName: string; terminals: { id: string }[] } | null

terminal.sendText

Types text into one terminal named by id, optionally pressing Enter.

(params: { terminalId: string; text: string; enter?: boolean }) => { accepted: boolean }

notifications.show

Shows a desktop notification.

(params: { title: string; body?: string }) => { delivered: boolean }

storage.get

Reads a JSON value from the plugin's private store; null when absent.

(params: { key: string }) => { value: JSON }

storage.set

Writes a JSON value to the plugin's private store.

(params: { key: string; value: JSON }) => { ok: true }

storage.delete

Removes a key from the plugin's private store.

(params: { key: string }) => { ok: true }

storage.keys

Lists the keys in the plugin's private store.

(params: {}) => { keys: string[] }

secrets.get

Reads a secret from the plugin's encrypted secrets file; null when absent.

(params: { key: string }) => { value: string | null }

secrets.set

Stores a secret in the plugin's encrypted secrets file.

(params: { key: string; value: string }) => { ok: true }

secrets.delete

Removes a secret from the plugin's encrypted secrets file.

(params: { key: string }) => { ok: true }

settings.get

Reads every setting the plugin owns.

(params: {}) => { settings: Record<string, JSON> }

settings.set

Writes one setting the plugin owns.

(params: { key: string; value: JSON }) => { ok: true }

Errors

A failed call rejects with an Error carrying code, message, retryable and, for rate_limited, retryAfterMs. Treat a code not listed here as action_failed:

  • invalid_request: the call itself is malformed.
  • invalid_params: params do not match the method, including a field this Orca does not know; the message names it.
  • unknown_method: the method does not exist in this Orca.
  • capability_denied: the manifest does not declare the capability.
  • consent_required: the plugin is disabled or the user has not approved this version.
  • not_permitted: the method or document is not available here, e.g. a worker-only method from a panel.
  • rate_limited: calls arrive faster than the budget; retryAfterMs says when to try again.
  • unavailable: the service behind the method is not running yet.
  • action_failed: the method ran and failed.
  • cancelled: the caller aborted the call through its signal.
  • timeout: Orca gave up waiting.
  • conflict: the call was made against a stale version, e.g. an editor edit after an outside change.
  • too_large: the message is larger than Orca accepts.

Stability and deprecation

Plugins are in Alpha: the manifest v2 format and catalog format are stable contracts; items listed as experimental in Plugin authoring may change.

  • Host API 1 is frozen. Within pluginApi 1, methods, params and results only grow: a new method or a new optional param arrives with a higher Since minor, and nothing listed here is removed, renamed or narrowed.
  • Deprecation. A method to be retired is marked deprecated in this table and keeps working for the rest of the major.
  • New majors. A breaking change ships as a new pluginApi major beside the old one. Orca refuses a manifest whose pluginApi names a major it does not implement, with "update Orca", instead of loading it against the wrong API.
  • Detect, do not assume. Check orca.host.has(name) or orca.api.minor before calling a method newer than the oldest Orca you support; a call that slips through fails with unknown_method.