Files
archived-orca/src/shared/plugins/capabilities/plugin-capabilities.ts
T
Neil 7b41b92062 feat(plugins): host API 1.7 — workspace ids, project/terminal list, terminal focus/close
Plugins that track workspaces and terminals across Orca had to read the private runtime
token or shell out to the CLI. Host API 1.7 gives them the same through consented methods:

- workspace.readContext (and workspace.changed) carry `workspaceId`, the id workspace.list
  gives; workspace.created/removed and agent.status.changed add `workspaceListId` beside
  their existing raw `workspaceId`, which keeps its meaning.
- workspace.list rows name their `projectId`; opt-in `includeStatus` joins each row's agent
  state, unread flag, live terminal count and last activity from worktree.ps.
- project.list (workspace:read), terminal.list (workspace:read), terminal.focus
  (workspace:write, desktop only, steers only this window) and terminal.close
  (terminal:send, reports whether the process is known to have stopped).
- Runtime refusals (unknown or ambiguous workspace, stale or exited terminal) reach plugins
  as fixed messages instead of runtime wording.
- Consent copy for workspace:read, workspace:write and terminal:send says what they now
  allow; terminal.focus and terminal.close are audited by terminal id.
- PLUGIN_SCHEMA_NEWEST_SINCE covers the editor typography and theme video floors it missed,
  and the provisional 1.7 floor, so development builds accept plugins requiring them.
2026-11-12 02:56:40 -08:00

100 lines
4.3 KiB
TypeScript

import { z } from 'zod'
import { PLUGIN_ENUM_SINCE_KEY } from '../manifest/plugin-engine-floor-keys'
import { PLUGIN_APPEARANCE_SINCE } from '../workers/plugin-host-api-appearance'
import {
pluginFieldDoc,
PLUGIN_HOST_ACTIONS_SINCE,
PLUGIN_MANIFEST_V2_SINCE,
PLUGIN_SCHEMA_SINCE_V1
} from '../manifest/plugin-schema-field-docs'
/** Closed v0 capabilities fail unknown kinds instead of silently granting nothing. Consent binds capabilities and worker trust;
* host boundaries enforce them across desktop, headless serve and relay. Scoped kinds remain future work. */
export const PLUGIN_CAPABILITY_KINDS = [
'workspace:read',
'workspace:write',
'agent:read',
'agent:launch',
'terminal:send',
'terminal:read',
'notifications:show',
'storage:own',
'secrets:own',
'settings:own',
'appearance:write'
] as const
export type PluginCapabilityKind = (typeof PLUGIN_CAPABILITY_KINDS)[number]
/** The release each capability arrived in; engines.orca must cover every one a plugin asks for. */
export const PLUGIN_CAPABILITY_SINCE: Record<PluginCapabilityKind, string> = {
'workspace:read': PLUGIN_SCHEMA_SINCE_V1,
'workspace:write': PLUGIN_HOST_ACTIONS_SINCE,
'agent:read': PLUGIN_MANIFEST_V2_SINCE,
'agent:launch': PLUGIN_HOST_ACTIONS_SINCE,
'terminal:send': PLUGIN_SCHEMA_SINCE_V1,
'terminal:read': PLUGIN_HOST_ACTIONS_SINCE,
'notifications:show': PLUGIN_SCHEMA_SINCE_V1,
'storage:own': PLUGIN_MANIFEST_V2_SINCE,
'secrets:own': PLUGIN_MANIFEST_V2_SINCE,
'settings:own': PLUGIN_SCHEMA_SINCE_V1,
'appearance:write': PLUGIN_APPEARANCE_SINCE
}
/** Format 1 capability names and what each now grants. `events:subscribe` split by event domain. */
export const PLUGIN_V1_CAPABILITY_ALIASES: ReadonlyMap<string, readonly PluginCapabilityKind[]> =
new Map([
['storage', ['storage:own']],
['secrets', ['secrets:own']],
['events:subscribe', ['workspace:read', 'agent:read']]
])
// Strict object (not a bare enum) so scoped fields can be added per-kind later
// without changing the manifest shape.
export const pluginCapabilitySchema = z
.object({
kind: z.enum(PLUGIN_CAPABILITY_KINDS).meta({
...pluginFieldDoc('Capability granted on user consent.', PLUGIN_SCHEMA_SINCE_V1),
[PLUGIN_ENUM_SINCE_KEY]: PLUGIN_CAPABILITY_SINCE
})
})
.strict()
.meta({ id: 'Capability', description: 'A host API the plugin may call once the user consents.' })
export type PluginCapability = z.infer<typeof pluginCapabilitySchema>
/** Consent copy shown verbatim; describe only what the host actually enforces. */
export const PLUGIN_CAPABILITY_DESCRIPTIONS: Record<PluginCapabilityKind, string> = {
'workspace:read':
'Read your projects and workspaces (names, branches, paths and agent status) and the terminals in them, and get notified when they change',
'workspace:write':
'Open and rename your workspaces, focus their terminals, open their files in Orca, and run its built-in commands',
'agent:read': 'Get notified when agent status changes',
'agent:launch': 'Start agents in your workspaces, local and SSH',
'terminal:send':
'Open and close your terminals, and type and run commands in them, local and SSH',
'terminal:read': 'Read the output of your terminals, local and SSH',
'notifications:show': 'Show desktop notifications labeled with the plugin name',
'storage:own': "Store data in the plugin's own storage folder",
'secrets:own': "Store and read secrets in the plugin's own encrypted file",
'settings:own': "Read and change the plugin's own settings",
'appearance:write': 'Publish and select desktop application, editor and terminal colors'
}
/** Canonicalize order, duplicates and field order so equivalent grants preserve consent across manifest formatting changes. */
export function canonicalizeCapabilitySet(capabilities: readonly PluginCapability[]): string {
return JSON.stringify([...new Set(capabilities.map(canonicalizeCapability))].sort())
}
/** One grant, key-sorted, so a scoped field such as hosts counts as part of what is granted. */
export function canonicalizeCapability(capability: PluginCapability): string {
return JSON.stringify(
Object.fromEntries(Object.entries(capability).sort(([a], [b]) => a.localeCompare(b)))
)
}
export function capabilityKinds(capabilities: readonly PluginCapability[]): PluginCapabilityKind[] {
return [...new Set(capabilities.map((capability) => capability.kind))]
}