Files
archived-orca/src/shared/plugins/workers/plugin-host-api.ts
T
Jinjing 5b505a6e94 Allow conflict-safe private storage from plugin panels (#36273)
* 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
2026-10-30 01:02:21 -07:00

288 lines
10 KiB
TypeScript

import { z } from 'zod'
import type { PluginCapabilityKind } from '../capabilities/plugin-capabilities'
import type { PluginSurface } from '../frames/plugin-protocol'
/**
* Host API 1 (`pluginApi: 1`) — the separately-versioned public facade plugins call. Every
* method carries params AND result schemas plus capability/mutation metadata;
* handlers (bound in main) delegate to runtime services. The raw runtime-RPC
* registry is never exposed: its methods have no result schemas and evolve at
* internal velocity.
*
* This table is the single source of truth for the capability gate, which surfaces
* (worker, panel, editor) may call what, the generated reference and the plugin SDK.
* Every params schema is strict: an older host refuses a newer flag with `invalid_params`
* instead of running the call without it. Electron-free by design: desktop
* main, headless serve, the relay conformance path, and tests all import it.
*
* Frozen within major 1: additive only. The policy that binds this
* table is in docs/reference/plugin-host-api.md, generated from it.
*/
export const PANEL_ACTION_TEXT_MAX_LENGTH = 4096
export const PLUGIN_WORKSPACE_TERMINAL_LIMIT = 50
export const PLUGIN_WORKSPACE_LABEL_MAX_LENGTH = 512
export const PLUGIN_TERMINAL_ID_MAX_LENGTH = 1024
const workspaceReadContextParams = z.strictObject({}).optional()
const workspaceReadContextResult = z
.object({
branch: z.string().max(PLUGIN_WORKSPACE_LABEL_MAX_LENGTH),
displayName: z.string().max(PLUGIN_WORKSPACE_LABEL_MAX_LENGTH),
/** Terminals of the focused workspace, so callers can address a specific
* terminal id — the API has no "active terminal" write target. */
terminals: z
.array(
z
.object({
id: z.string().min(1).max(PLUGIN_TERMINAL_ID_MAX_LENGTH)
})
.strict()
)
.max(PLUGIN_WORKSPACE_TERMINAL_LIMIT)
})
.strict()
.nullable()
const terminalSendTextParams = z.strictObject({
/** Explicit target prevents delayed writes following focus changes into another pane. */
terminalId: z.string().min(1).max(PLUGIN_TERMINAL_ID_MAX_LENGTH),
text: z.string().min(1).max(PANEL_ACTION_TEXT_MAX_LENGTH),
enter: z.boolean().default(false)
})
const terminalSendTextResult = z.object({ accepted: z.boolean() })
const notificationsShowParams = z.strictObject({
title: z.string().min(1).max(120),
body: z.string().max(1000).optional()
})
const notificationsShowResult = z.object({ delivered: z.boolean() })
const RESERVED_STORAGE_KEYS = new Set(['__proto__', 'prototype', 'constructor'])
const storageKeySchema = z
.string()
.min(1)
.max(256)
.refine((key) => !RESERVED_STORAGE_KEYS.has(key), 'reserved storage key')
const pluginJsonValueSchema = z.json()
export type PluginJsonValue = z.infer<typeof pluginJsonValueSchema>
/** Caps keep per-plugin storage an honest key-value store, not a database. */
export const PLUGIN_STORAGE_VALUE_MAX_BYTES = 256 * 1024
export const PLUGIN_STORAGE_TOTAL_MAX_BYTES = 5 * 1024 * 1024
export const PLUGIN_STORAGE_KEY_LIMIT = 1024
const storageGetParams = z.strictObject({ key: storageKeySchema })
const storageGetResult = z.object({ value: pluginJsonValueSchema })
const storageSetParams = z.strictObject({ key: storageKeySchema, value: pluginJsonValueSchema })
const storageSetResult = z.object({ ok: z.literal(true) })
const storageDeleteParams = z.strictObject({ key: storageKeySchema })
const storageDeleteResult = z.object({ ok: z.literal(true) })
const storageKeysParams = z.strictObject({}).optional()
const storageKeysResult = z.object({ keys: z.array(z.string()).max(PLUGIN_STORAGE_KEY_LIMIT) })
const secretsGetParams = z.strictObject({ key: storageKeySchema })
const secretsGetResult = z.object({ value: z.string().nullable() })
const secretsSetParams = z.strictObject({ key: storageKeySchema, value: z.string().max(64 * 1024) })
const secretsSetResult = z.object({ ok: z.literal(true) })
const secretsDeleteParams = z.strictObject({ key: storageKeySchema })
const secretsDeleteResult = z.object({ ok: z.literal(true) })
const settingsGetParams = z.strictObject({}).optional()
const settingsGetResult = z.object({ settings: z.record(z.string(), pluginJsonValueSchema) })
const settingsSetParams = z.strictObject({ key: storageKeySchema, value: pluginJsonValueSchema })
const settingsSetResult = z.object({ ok: z.literal(true) })
export type PluginHostMethodSpec<
P extends z.ZodType = z.ZodType,
R extends z.ZodType = z.ZodType
> = {
/** One line for the generated reference. */
summary: string
/** Host API minor the method appeared in (`0` for the first set); `api.minor` is the highest. */
since: number
/** Minor that deprecated it; it keeps working until the next major. */
deprecatedSince?: number
/** Machine-readable resource boundary enforced by the host binding. */
scope: 'active-workspace' | 'explicit-terminal' | 'plugin-private' | 'desktop'
capability: PluginCapabilityKind
/** Mutations are audit-logged with actor `plugin:<id>`. */
mutation: boolean
/** Where plugin code may call it; any other surface gets `not_permitted`. */
surfaces: readonly PluginSurface[]
params: P
result: R
}
const ALL_SURFACES = ['worker', 'panel', 'editor'] as const
const WORKER_ONLY = ['worker'] as const
const spec = <P extends z.ZodType, R extends z.ZodType>(
entry: PluginHostMethodSpec<P, R>
): PluginHostMethodSpec<P, R> => entry
export const PLUGIN_HOST_API = {
'workspace.readContext': spec({
summary:
'Branch, name and terminal ids of the focused workspace, or null when none is focused.',
since: 0,
scope: 'active-workspace',
capability: 'workspace:read',
mutation: false,
surfaces: ALL_SURFACES,
params: workspaceReadContextParams,
result: workspaceReadContextResult
}),
'terminal.sendText': spec({
summary: 'Types text into one terminal named by id, optionally pressing Enter.',
since: 0,
scope: 'explicit-terminal',
capability: 'terminal:send',
mutation: true,
// Why: text plus Enter runs shell commands (local or SSH), so only full-access workers get it.
surfaces: WORKER_ONLY,
params: terminalSendTextParams,
result: terminalSendTextResult
}),
'notifications.show': spec({
summary: 'Shows a desktop notification.',
since: 0,
scope: 'desktop',
capability: 'notifications:show',
mutation: true,
surfaces: ALL_SURFACES,
params: notificationsShowParams,
result: notificationsShowResult
}),
'storage.get': spec({
summary: "Reads a JSON value from the plugin's private store; null when absent.",
since: 0,
scope: 'plugin-private',
capability: 'storage:own',
mutation: false,
surfaces: ALL_SURFACES,
params: storageGetParams,
result: storageGetResult
}),
'storage.compareAndSet': spec({
summary:
'Atomically writes a private JSON value only if it still matches expected; absent keys compare as null.',
since: 1,
scope: 'plugin-private',
capability: 'storage:own',
mutation: true,
surfaces: ALL_SURFACES,
params: z.strictObject({
key: storageKeySchema,
expected: pluginJsonValueSchema,
value: pluginJsonValueSchema
}),
result: z.object({ swapped: z.boolean() })
}),
'storage.set': spec({
summary: "Writes a JSON value to the plugin's private store.",
since: 0,
scope: 'plugin-private',
capability: 'storage:own',
mutation: true,
surfaces: WORKER_ONLY,
params: storageSetParams,
result: storageSetResult
}),
'storage.delete': spec({
summary: "Removes a key from the plugin's private store.",
since: 0,
scope: 'plugin-private',
capability: 'storage:own',
mutation: true,
surfaces: WORKER_ONLY,
params: storageDeleteParams,
result: storageDeleteResult
}),
'storage.keys': spec({
summary: "Lists the keys in the plugin's private store.",
since: 0,
scope: 'plugin-private',
capability: 'storage:own',
mutation: false,
surfaces: WORKER_ONLY,
params: storageKeysParams,
result: storageKeysResult
}),
'secrets.get': spec({
summary: "Reads a secret from the plugin's encrypted secrets file; null when absent.",
since: 0,
scope: 'plugin-private',
capability: 'secrets:own',
mutation: false,
surfaces: WORKER_ONLY,
params: secretsGetParams,
result: secretsGetResult
}),
'secrets.set': spec({
summary: "Stores a secret in the plugin's encrypted secrets file.",
since: 0,
scope: 'plugin-private',
capability: 'secrets:own',
mutation: true,
surfaces: WORKER_ONLY,
params: secretsSetParams,
result: secretsSetResult
}),
'secrets.delete': spec({
summary: "Removes a secret from the plugin's encrypted secrets file.",
since: 0,
scope: 'plugin-private',
capability: 'secrets:own',
mutation: true,
surfaces: WORKER_ONLY,
params: secretsDeleteParams,
result: secretsDeleteResult
}),
'settings.get': spec({
summary: 'Reads every setting the plugin owns.',
since: 0,
scope: 'plugin-private',
capability: 'settings:own',
mutation: false,
surfaces: WORKER_ONLY,
params: settingsGetParams,
result: settingsGetResult
}),
'settings.set': spec({
summary: 'Writes one setting the plugin owns.',
since: 0,
scope: 'plugin-private',
capability: 'settings:own',
mutation: true,
surfaces: WORKER_ONLY,
params: settingsSetParams,
result: settingsSetResult
})
}
export type PluginHostApi = typeof PLUGIN_HOST_API
export type PluginHostMethodName = keyof PluginHostApi
/** What a plugin passes; what a handler receives is `z.output` of the same schema. */
export type PluginHostParams<M extends PluginHostMethodName> = z.input<PluginHostApi[M]['params']>
export type PluginHostResult<M extends PluginHostMethodName> = z.output<PluginHostApi[M]['result']>
export const PLUGIN_HOST_METHOD_NAMES = Object.keys(PLUGIN_HOST_API).filter(isPluginHostMethodName)
export function isPluginHostMethodName(name: string): name is PluginHostMethodName {
return Object.hasOwn(PLUGIN_HOST_API, name)
}
export function getPluginHostMethodSpec(name: string): PluginHostMethodSpec | null {
return isPluginHostMethodName(name) ? PLUGIN_HOST_API[name] : null
}
/** The minor this host implements: the newest `since` in the table. */
export const PLUGIN_HOST_API_MINOR = Math.max(
...PLUGIN_HOST_METHOD_NAMES.map((name) => PLUGIN_HOST_API[name].since)
)
/** Methods a surface may call, for `hello` and `host.has`. */
export function pluginHostMethodsFor(surface: PluginSurface): PluginHostMethodName[] {
return PLUGIN_HOST_METHOD_NAMES.filter((name) => PLUGIN_HOST_API[name].surfaces.includes(surface))
}