# Orca plugin host API reference

<!-- Generated by `pnpm generate:plugin-schemas` from src/shared/plugins. Do not edit. -->

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](./plugin-authoring.md) 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`](#workspacereadcontext) | `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`](#terminalsendtext) | `terminal:send` | worker | yes | 1.0 | Types text into one terminal named by id, optionally pressing Enter. |
| [`notifications.show`](#notificationsshow) | `notifications:show` | worker, panel, editor | yes | 1.0 | Shows a desktop notification. |
| [`storage.get`](#storageget) | `storage:own` | worker | no | 1.0 | Reads a JSON value from the plugin's private store; null when absent. |
| [`storage.set`](#storageset) | `storage:own` | worker | yes | 1.0 | Writes a JSON value to the plugin's private store. |
| [`storage.delete`](#storagedelete) | `storage:own` | worker | yes | 1.0 | Removes a key from the plugin's private store. |
| [`storage.keys`](#storagekeys) | `storage:own` | worker | no | 1.0 | Lists the keys in the plugin's private store. |
| [`secrets.get`](#secretsget) | `secrets:own` | worker | no | 1.0 | Reads a secret from the plugin's encrypted secrets file; null when absent. |
| [`secrets.set`](#secretsset) | `secrets:own` | worker | yes | 1.0 | Stores a secret in the plugin's encrypted secrets file. |
| [`secrets.delete`](#secretsdelete) | `secrets:own` | worker | yes | 1.0 | Removes a secret from the plugin's encrypted secrets file. |
| [`settings.get`](#settingsget) | `settings:own` | worker | no | 1.0 | Reads every setting the plugin owns. |
| [`settings.set`](#settingsset) | `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.

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

### `terminal.sendText`

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

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

### `notifications.show`

Shows a desktop notification.

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

### `storage.get`

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

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

### `storage.set`

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

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

### `storage.delete`

Removes a key from the plugin's private store.

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

### `storage.keys`

Lists the keys in the plugin's private store.

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

### `secrets.get`

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

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

### `secrets.set`

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

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

### `secrets.delete`

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

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

### `settings.get`

Reads every setting the plugin owns.

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

### `settings.set`

Writes one setting the plugin owns.

```ts
(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](./plugin-authoring.md#stability) 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`.