mirror of
https://github.com/stablyai/orca.git
synced 2026-10-31 17:17:38 +00:00
Jinjing
5b505a6e94
* Support conflict-safe private storage in plugin panels * Update frame and worker tests for host API 1.1 * Use required braces in storage conflict guard * Update renderer handshake expectation for panel storage API * Clarify null comparisons and exclude inherited storage keys
157 lines
6.8 KiB
Markdown
157 lines
6.8 KiB
Markdown
# Orca plugin host API reference
|
|
|
|
<!-- Generated by `pnpm generate:plugin-schemas` from src/shared/plugins. Do not edit. -->
|
|
|
|
Host API 1.1 (`"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, panel, editor | no | 1.0 | Reads a JSON value from the plugin's private store; null when absent. |
|
|
| [`storage.compareAndSet`](#storagecompareandset) | `storage:own` | worker, panel, editor | yes | 1.1 | Atomically writes a private JSON value only if it still matches expected; absent keys compare as null. |
|
|
| [`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.compareAndSet`
|
|
|
|
Atomically writes a private JSON value only if it still matches expected; absent keys compare as null.
|
|
|
|
```ts
|
|
(params: { key: string; expected: JSON; value: JSON }) => { swapped: boolean }
|
|
```
|
|
|
|
### `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`.
|