mirror of
https://github.com/stablyai/orca.git
synced 2026-11-19 04:23:57 +00:00
* 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.
181 lines
12 KiB
TypeScript
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
|
|
}
|