Files
archived-orca/resources/plugins/declarative/orca.d.ts
T
Neil 255b5c22c1 feat(plugins): host API 1.8 — create workspaces, resume agents, automations (#41528)
* feat(plugins): proposed tier for host methods not yet frozen

A method spec may set `proposed: true`: only development plugins may call
it (others get not_permitted), and the minor, frame/worker method lists,
typings and skill references omit it. The reference renders such methods
in a separate Proposed section; dev workers' host.has answers for them.

* feat(plugins): param capabilities, host confirmations, automation provenance

- PluginHostMethodSpec.paramCapabilities: a passed param can require a
  second capability; executePluginHostCall and the mock host refuse it with
  capability_denied before any audit or effect, and the reference shows it.
- confirmPluginAction generalizes the external-open prompt into a host-owned
  confirmation, exposed as PluginHostServices.confirm (desktop only; absent
  in headless serve). It re-checks the plugin's approval after the answer.
- Automations record createdBy { kind: 'plugin', pluginKey, name }, set by
  the runtime from the in-process plugin caller (RpcContext.plugin), never
  from params; the Automations detail shows "Created by <plugin>".

* feat(plugins): workspace:create, automation:read and automation:write capabilities

New closed-enum kinds (older Orcas refuse such manifests with the engines
message), worker-only, with consent copy that names what each allows;
release floor PLUGIN_HOST_API_1_8_SINCE (1.4.259) joins
PLUGIN_SCHEMA_NEWEST_SINCE. agent:launch copy now says it also resumes.

* feat(plugins): host API 1.8 methods: workspace.create, agent.resume, automation.*

- workspace.create (workspace:create; agent also needs agent:launch): a
  worktree in a Git project, as orca worktree create does; with agent, the
  CLI's agent.launch create-worktree path, so the agent starts after setup.
  Setup is skipped or follows the project's settings; never run, an
  approved hash or a startup command.
- agent.resume (agent:launch): terminal.ensureAgentSession by session id;
  started is false when a terminal already ran it. agents.list rows and
  agent.status.changed carry sessionId.
- automation.list/create/update/delete (automation:read/write): create
  forwards only name, prompt, agent, target, schedule, time zone and
  enabled; update/delete of automations another plugin or the person made
  ask the person first and report cancelled or consent-unavailable.

* test(plugins): host API 1.8 coverage; regenerate plugin artifacts

Covers param capabilities (host and mock host), workspace.create payloads
and refusals, agent.resume keys and adoption, sessionId on agents.list,
automation projection, forbidden create fields, confirmation outcomes,
runtime-set provenance and capability access growth. Regenerates the
reference, schemas, typings, declarative runtime and skill references.

* fix(plugins): host API 1.8 review fixes

- Confirmations spend the frame dialog budget, allow one question per
  plugin at a time and pause after a refusal (rate_limited); a worker's
  question shows in the focused window, else the first visible one.
- Changing what an automation with extra agent settings runs (prompt,
  schedule, resuming) asks first even for its creator, showing the prompt.
- Removing, disabling or blocking a plugin pauses its automations and ends
  its ownership (createdBy.endedAt), so neither re-enabling nor a reinstall
  under the key resumes or edits them silently; the remove dialog says so.
- workspace.create and agent.resume record the terminals they return as
  the plugin's own; a launch that fails after its worktree exists names it.
- Setup-decision refusals are told by the runtime's error class (kept as
  the in-process RPC error's cause); generated names see every worktree
  of the project; resume transcripts match the workspace and host.
- Created by shows the plugin id beside its name.

* fix(plugins): end automation ownership only on uninstall, disable or block

- The ownership sweep no longer reads discovery: only an uninstall
  (announced by the removal path), the disabled list, the kill list or
  the plugin-system switch end it, and only once the service is ready,
  so an unreadable plugins folder pauses nothing. An install under the
  same key after a removal keeps what it creates.
- A new time zone on an automation with extra agent settings asks first.
- A failed launch names only a new worktree made from the requested name.
- Settings' plugins-off state and the CLI's plugin system off and plugin
  disable say that plugin-created automations are paused and stay so.

* fix(plugins): address host API 1.8 review threads

- Confirmations close when the worker's call ends, freeing the plugin's
  turn; they name the automation (short id, project, workspace,
  schedule), show any new prompt, and are refused as `changed` when the
  automation was edited while the person was asked.
- automation.create takes hostId (through the project's setup on that
  host) and a creationKey scoped to the plugin; the runtime rechecks the
  plugin's approval right before the write.
- agent.resume records only terminals it started; both it and
  workspace.create recheck approval before recording.
- automation.list never cuts a schedule (null when too long) or fails on
  an id too long to show.
- The Automations detail says when a creator plugin was removed or
  disabled.
2026-11-12 05:28:13 -08:00

181 lines
12 KiB
TypeScript

// Author typings for Orca components panels (`"ui": "components"`): the runtime API.
// `orca plugin types` joins this file with orca-components*.d.ts (the catalog) and installs
// types/orca-services.d.ts, which adds `shell`, `files`, `on`, `plugin`, `storage`, `settings` and
// `secrets` to this module. Mirrors src/shared/plugins/declarative/ (checked by
// plugin-declarative-typings.test.ts); host methods are generated from the host API.
declare module 'orca' {
export type OrcaElement = { readonly $$typeof: symbol }
export type OrcaNode =
| OrcaElement
| string
| number
| boolean
| null
| undefined
| readonly OrcaNode[]
/** Catalog tags are JSX-only: write `<Stack>`, never call `Stack()`. */
export type OrcaComponent<P> = (props: P) => OrcaNode
/** Read with `read()`; reading while rendering re-renders when it changes. */
export type ReadonlyAtom<T> = { readonly __orcaAtom: T }
/** Changed with `set()` or `update()`. */
export type Atom<T> = ReadonlyAtom<T> & { readonly __orcaWritable: true }
export type Disposable = { dispose(): void }
export type Theme = { colorScheme: 'light' | 'dark' }
export type JsonValue =
| string
| number
| boolean
| null
| JsonValue[]
| { [key: string]: JsonValue }
export const Fragment: unique symbol
export function h(type: unknown, props: object | null, ...children: OrcaNode[]): OrcaElement
/**
* Where a keyed atom survives: this panel run, every run of the plugin, per workspace, or the
* plugin's own storage under the atom's key (`storage:own`), shared with its worker and other
* panels and kept current when they change it.
*/
export type PersistScope = 'memory' | 'plugin' | 'workspace' | 'storage'
export type AtomOptions<T> = {
/** Persisted values must be plain JSON; they load before the first render. `storage` values
* are stored as they are, so `version` and `migrate` do not apply to them. */
persist?: PersistScope
/** Bump when the stored shape changes; `migrate` then receives the older value. */
version?: number
migrate?: (stored: JsonValue, fromVersion: number) => T
}
/** State for this panel run. */
export function atom<T>(initial: T): Atom<T>
/** Named state, unique per plugin, optionally persisted. */
export function atom<T>(key: string, initial: T, options?: AtomOptions<T>): Atom<T>
/** Computed from other atoms; reading it while rendering subscribes to what it reads. */
export function derived<T>(compute: () => T): ReadonlyAtom<T>
export function read<T>(atom: ReadonlyAtom<T>): T
/** Stores `value` as is (functions included). Batched; throws while rendering. */
export function set<T>(atom: Atom<T>, value: T): void
/** Replaces the value with `updater(previous)`. Batched; throws while rendering. */
export function update<T>(atom: Atom<T>, updater: (previous: T) => T): void
/** Optional: the module's default export is mounted automatically. */
export function mount(component: () => OrcaNode): void
/** Passed to the module's optional `export function setup(ctx)`. */
export type PanelContext = {
/** Disposed when the panel closes or reloads. */
subscriptions: Disposable[]
/** Aborts when the panel closes or reloads. */
signal: AbortSignal
/** True while the person can see the panel. */
visible: ReadonlyAtom<boolean>
panel: { id: string }
}
/** Runs once, after persisted atoms load and before the first render. */
export type PanelSetup = (ctx: PanelContext) => void | (() => void)
export type HostCallOptions = { signal?: AbortSignal; timeoutMs?: number }
/** Rejections carry a `code` (`not_permitted`, `capability_denied`, `timeout`, ...). */
export type HostError = Error & { code: string; retryable: boolean; retryAfterMs?: number }
// <generated: host methods, from plugin-host-api.ts>
export type HostMethods = {
/** Id, branch, name and terminal ids of the focused workspace, or null when none is focused. */
"workspace.readContext": { params: Record<string, never> | undefined; result: { workspaceId?: string; branch: string; displayName: string; terminals: { id: string; title?: string }[] } | null }
/** Shows a desktop notification. */
"notifications.show": { params: { title: string; body?: string }; result: { delivered: boolean } }
/** Reads a JSON value from the plugin's private store; null when absent. */
"storage.get": { params: { key: string }; result: { value: JsonValue } }
/** Writes a JSON value to the plugin's private store. */
"storage.set": { params: { key: string; value: JsonValue }; result: { ok: true } }
/** Removes a key from the plugin's private store. */
"storage.delete": { params: { key: string }; result: { ok: true } }
/** Lists the keys in the plugin's private store. */
"storage.keys": { params: Record<string, never> | undefined; result: { keys: string[] } }
/** Reads a secret from the plugin's encrypted secrets file; null when absent. */
"secrets.get": { params: { key: string }; result: { value: string | null } }
/** Stores a secret in the plugin's encrypted secrets file. */
"secrets.set": { params: { key: string; value: string }; result: { ok: true } }
/** Removes a secret from the plugin's encrypted secrets file. */
"secrets.delete": { params: { key: string }; result: { ok: true } }
/** How secrets are protected at rest: `os-keyring`, or `unavailable` (no OS key store, or Linux `basic_text`), where `secrets.set` fails. */
"secrets.protection": { params: Record<string, never> | undefined; result: { status: "os-keyring" | "unavailable" } }
/** Reads every setting the plugin owns. */
"settings.get": { params: Record<string, never> | undefined; result: { settings: Record<string, JsonValue> } }
/** Writes one setting the plugin owns. */
"settings.set": { params: { key: string; value: JsonValue }; result: { ok: true } }
/** Opens an http:, https: or mailto: URL in the default browser. Needs a click or key press in the frame; desktop app only. Orca asks the person before an http(s) host the plugin was not allowed; `opened` is false if they cancel. */
"shell.openExternal": { params: { url: string }; result: { opened: boolean; reason?: "cancelled" | "consent-unavailable" } }
/** Offers data (a string or ArrayBuffer, up to 64 MiB) in Orca's save dialog; the plugin never learns the path. Needs a click or key press in the frame; desktop app only. */
"files.saveAs": { params: { suggestedName?: string; mimeType?: string; data: string | ArrayBuffer }; result: { status: "saved" | "cancelled" } }
/** Asks the plugin's own worker to run the handler it registered with `orca.panels.handle(name)`, starting the worker if needed; resolves with what the handler returned. `unknown_method` when no handler has that name. */
"plugin.request": { params: { name: string; input?: JsonValue; timeoutMs?: number }; result: { output: JsonValue } }
/** The agents in the focused workspace: their terminal, title, agent kind and status. `agent.status.changed` reports each change after. */
"agents.list": { params: Record<string, never> | undefined; result: { agents: { terminalId: string | null; title: string | null; agent: string | null; state: "working" | "blocked" | "waiting" | "done"; stateStartedAt: number; sessionId?: string | null }[] } }
/** Delivers a workspace, agent or editor event to this panel as `orca.on(event)`; needs the event's read capability, when it has one. The frame APIs call it for you. */
"events.subscribe": { params: { event: "workspace.created" | "workspace.removed" | "agent.status.changed" | "workspace.changed" | "editor.typography.changed" }; result: { ok: true } }
/** The font family, size, weight, line height, ligatures, word wrap and minimap Orca's file editor uses now, editor zoom included. `editor.typography.changed` reports each change after. */
"editor.readTypography": { params: Record<string, never> | undefined; result: { fontFamily: string; cssFontFamily: string; fontSize: number; fontWeight: string; lineHeight: number; fontLigatures: boolean; wordWrap: "on" | "off"; minimap: boolean } }
}
/** Workspace and agent events `on(event)` delivers, with the read capability of their domain. */
export type PluginEvents = {
/** A worktree workspace was created; `workspaceListId` (host API 1.7) is the id `workspace.list` gives it. */
"workspace.created": { workspaceId: string; workspaceListId?: string; kind: "worktree" | "folder"; path: string; branch: string }
/** A worktree workspace was removed; `workspaceListId` (host API 1.7) is the id `workspace.list` gave it. */
"workspace.removed": { workspaceId: string; workspaceListId?: string; kind: "worktree" | "folder"; path: string }
/** An agent in a terminal pane changed status; `workspaceId` is null when Orca cannot tie the pane to a workspace, `workspaceListId` (host API 1.7) is the id `workspace.list` gives that workspace, `terminalId` names its terminal when Orca lists it, and `sessionId` (host API 1.8) is what `agent.resume` takes. */
"agent.status.changed": { workspaceId: string | null; workspaceListId?: string; paneKey: string; terminalId?: string; title?: string; state: "working" | "blocked" | "waiting" | "done"; receivedAt: number; mainAgent?: { state: "working" | "blocked" | "waiting" | "done"; outcome?: "success" | "failure" | "cancellation" | "superseded" | "interruption" | "unconfirmed"; stateStartedAt: number }; sessionId?: string }
/** The focused workspace changed, or its terminals were opened, closed or renamed; `context` is what `workspace.readContext` now answers, its `workspaceId` included. Each new subscriber first gets the current context. */
"workspace.changed": { context: { workspaceId?: string; branch: string; displayName: string; terminals: { id: string; title?: string }[] } | null }
/** What Orca's file editor uses changed (a setting or the editor zoom); the payload is what `editor.readTypography` now answers. Needs no capability. */
"editor.typography.changed": { fontFamily: string; cssFontFamily: string; fontSize: number; fontWeight: string; lineHeight: number; fontLigatures: boolean; wordWrap: "on" | "off"; minimap: boolean }
}
// </generated>
export type HostMethod = keyof HostMethods
export const host: {
call<K extends HostMethod>(
method: K,
...args: Record<string, never> extends HostMethods[K]['params']
? [params?: HostMethods[K]['params'], options?: HostCallOptions]
: [params: HostMethods[K]['params'], options?: HostCallOptions]
): Promise<HostMethods[K]['result']>
/** Whether this Orca offers `method` to this panel. */
has(method: string): boolean
}
/** The host API this Orca implements. */
export const api: { readonly major: number; readonly minor: number }
export const env: {
/** Orca's UI language (BCP-47). */
readonly locale: string
/** Reading it while rendering re-renders on light/dark switches. */
readonly theme: Theme
readonly client: 'desktop'
}
export const ui: {
/** Grows with the component catalog. */
readonly catalog: number
/** Whether this Orca draws `component` (and accepts `prop` on it, when given). */
has(component: string, prop?: string): boolean
}
}
declare module 'orca/jsx-runtime' {
import type { OrcaElement, OrcaNode } from 'orca'
export { Fragment } from 'orca'
export function jsx(type: unknown, props: object, key?: string | number): OrcaElement
export function jsxs(type: unknown, props: object, key?: string | number): OrcaElement
export namespace JSX {
type Element = OrcaElement
type ElementType = (props: never) => OrcaNode
type ElementChildrenAttribute = { children: unknown }
type IntrinsicAttributes = { key?: string | number }
// No lowercase tags: panels never render DOM.
type IntrinsicElements = {}
}
}
declare module 'orca/jsx-dev-runtime' {
import type { OrcaElement } from 'orca'
export { Fragment, JSX } from 'orca/jsx-runtime'
export function jsxDEV(type: unknown, props: object, key?: string | number): OrcaElement
}