Files
archived-orca/src/shared/plugins/workers/plugin-worker-orca-api.ts
T
NeilandClaude ac8c1125f0 feat(plugins): hooks that can change or block terminal sends and workspace creation (#37287)
* plugins: contributes.hooks runtime with terminal.send and workspace.create hooks

Workers register orca.hooks.on(hook, (event, next) => ...). Orca runs listed
plugins in order before it acts: next(event) continues with allowed fields
changed, { deny } stops, nothing passes. A plugin past its 2 s deadline, or
one that throws, crashes or is disabled, counts as passing and is logged with
plugin, hook and duration. First hooks: terminal.send (runtime sendTerminal),
workspace.create.before (IPC and runtime creates, folders included) and
observe-only workspace.create.after. orca/testing mountWorker gains
hooks.fire. Needs main + trusted-worker and engines.orca >=1.4.248.

Co-Authored-By: Claude <noreply@anthropic.com>

* plugins: keep hook plugins' workers started; bound start-up separately from the hook deadline

Workers of enabled plugins that list hooks start as soon as they are approved
and are never idle-reaped; crash restarts follow the manager's policy. A hook
waits up to the worker ready timeout for start-up, then gives the handler its
full 2 s, so a cold worker no longer lets the first hooked action through.

Co-Authored-By: Claude <noreply@anthropic.com>

* plugins: give hook workers their own soft cap instead of the active-worker cap

Always-running hook workers no longer hold slots of the shared 5-worker cap, so
many hook plugins cannot starve the rest. They have a soft cap of 16; past it a
hook worker waits for another to stop, logged once.

Co-Authored-By: Claude <noreply@anthropic.com>

* test(plugins): type the hook warmer's ensureWorker mock

* plugins: address hook review: ordering, human input, overflow, revalidation, folder creates

- Hook workers past the soft cap start as overflow (logged once) instead of
  waiting, so reconciliation, disable and uninstall never hang.
- Writes to one terminal stay in order while terminal.send decides, so a later
  Enter cannot submit the previous line.
- terminal.send runs only for programmatic sends (main, plugins, the CLI);
  desktop, mobile and legacy client input is a person's typing.
- Text a hook rewrote passes the AI Vault resume check again.
- Project-group folder workspace creates (RPC, agent launch, window) run the
  workspace.create hooks through one boundary.
- A decision from a plugin disabled or changed while it ran is discarded.

Co-Authored-By: Claude <noreply@anthropic.com>

* test(plugins): drive hook start-up timing with fake-timer deferreds, no real sleeps

Co-Authored-By: Claude <noreply@anthropic.com>

* plugins: only the hook decision holds a terminal's write order

A delivery that waits (a permission prompt, the launch composer) no longer
blocks later writes, and a person's input, interrupts and query replies never
wait behind a pending decision.

Co-Authored-By: Claude <noreply@anthropic.com>

* plugins: hook DX: onError deny, denied_by_plugin, a Hooks reference, --template hook

- contributes.hooks[].onError: "deny" makes a throw, timeout, crash or bad
  answer refuse the action, naming the plugin; the default still passes.
  orca/testing mountWorker honours it, and mockHost answers fire-and-forget
  methods (result { ok: true }) with success by default.
- A plugin denial reaches RPC clients as denied_by_plugin with the plugin and
  reason, and the CLI no longer suggests a retry for it.
- The skill's host-api reference gains a generated Hooks section (event, what
  next may change, stop result); the recipe passes sends through unchanged and
  warns against awaiting other calls before deciding.
- orca plugin create --template hook: a worker-only terminal.send guard that
  fails closed, with a test.

Co-Authored-By: Claude <noreply@anthropic.com>

* plugins: regenerate hook docs on main; bind the plugin runtime and its hook runner in one call

Keeps main-process-plugins.ts under 300 lines now that status bar items landed.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-11-01 21:12:57 -08:00

237 lines
8.9 KiB
TypeScript

/** The `orca` object a worker's `activate(orca)` receives; shared so orca/testing hands tests the same one. */
import type { PluginEventName } from '../manifest/plugin-manifest'
import { PLUGIN_V1_EVENT_ALIASES } from '../contributions/plugin-event-contribution'
import { isPluginHookName, type PluginHookName } from '../contributions/plugin-hook-contribution'
import type { PluginHookHandler } from './plugin-worker-hooks'
import { PLUGIN_HOST_API_MINOR, pluginHostMethodsFor } from './plugin-host-api'
import { PLUGIN_HOST_API_MAJOR } from './plugin-host-api-major'
import {
pluginBridgeNameSchema,
type PluginDataChanged,
type PluginPanelCaller,
type PluginWorkerPanelPost
} from './plugin-panel-bridge-protocol'
export type PluginDisposable = { dispose(): void }
export type PluginPanelRequestHandler = (
input: unknown,
context: { panel: PluginPanelCaller; signal: AbortSignal }
) => unknown
type HostCall = (
method: string,
params?: unknown,
options?: { signal?: AbortSignal }
) => Promise<unknown>
type DataListener = (change: { key: string }) => void
/** API surface handed to a plugin's `activate(orca)` export (host API 1). */
export type PluginWorkerOrcaApi = {
api: { readonly major: number; readonly minor: number }
commands: {
register(
commandId: string,
handler: (args: unknown, context: { signal: AbortSignal }) => unknown
): PluginDisposable
}
events: {
on(
event: PluginEventName,
handler: (payload: unknown) => void | Promise<void>
): PluginDisposable
}
hooks: {
on(event: PluginHookName, handler: PluginHookHandler): PluginDisposable
}
host: {
call: HostCall
/** Whether this host implements `method` for workers. */
has(method: string): boolean
}
/** The plugin's own panels and custom editors. */
panels: {
handle(name: string, handler: PluginPanelRequestHandler): PluginDisposable
post(event: string, payload?: unknown, options?: { panel?: string }): void
}
storage: {
get(key: string): Promise<unknown>
set(key: string, value: unknown): Promise<void>
delete(key: string): Promise<void>
keys(): Promise<string[]>
onDidChange(listener: DataListener): PluginDisposable
}
settings: {
/** Every setting, or one; declared settings read as their default until set. */
get(key?: string): Promise<unknown>
set(key: string, value: unknown): Promise<void>
onDidChange(listener: DataListener): PluginDisposable
}
secrets: {
get(key: string): Promise<string | null>
set(key: string, value: string): Promise<void>
delete(key: string): Promise<void>
}
/** Consented capability kinds (informational — the host re-gates). */
grantedCapabilities: readonly string[]
log(message: string): void
}
// Why: format 1 handlers read `worktreeId`; newer payloads name it `workspaceId`.
function withV1WorktreeId(payload: unknown): unknown {
if (typeof payload !== 'object' || payload === null || !('workspaceId' in payload)) {
return payload
}
return 'worktreeId' in payload ? payload : { ...payload, worktreeId: payload.workspaceId }
}
function field(result: unknown, name: string): unknown {
return typeof result === 'object' && result !== null && name in result
? Object.getOwnPropertyDescriptor(result, name)?.value
: undefined
}
function addTo<T>(set: Set<T>, entry: T): PluginDisposable {
set.add(entry)
return { dispose: () => void set.delete(entry) }
}
const WORKER_METHOD_NAMES: ReadonlySet<string> = new Set(pluginHostMethodsFor('worker'))
/** The tables the runtime dispatches from; this module only fills them. */
export type PluginWorkerApiTables = {
commands: Map<string, (args: unknown, context: { signal: AbortSignal }) => unknown>
events: Map<string, Set<(payload: unknown) => void | Promise<void>>>
hooks: Map<PluginHookName, Set<PluginHookHandler>>
panelRequests: Map<string, PluginPanelRequestHandler>
dataListeners: Record<PluginDataChanged['area'], Set<DataListener>>
}
export function createPluginWorkerApiTables(): PluginWorkerApiTables {
return {
commands: new Map(),
events: new Map(),
hooks: new Map(),
panelRequests: new Map(),
dataListeners: { storage: new Set(), settings: new Set() }
}
}
export function createPluginWorkerOrcaApi(input: {
tables: PluginWorkerApiTables
hostCall: HostCall
postToPanels: (post: PluginWorkerPanelPost) => void
log: (message: string) => void
grantedCapabilities: readonly string[]
}): PluginWorkerOrcaApi {
const { tables, hostCall } = input
const ok = async (method: string, params: unknown): Promise<void> => {
await hostCall(method, params)
}
return Object.freeze({
api: Object.freeze({ major: PLUGIN_HOST_API_MAJOR, minor: PLUGIN_HOST_API_MINOR }),
commands: Object.freeze({
register(
commandId: string,
handler: Parameters<PluginWorkerOrcaApi['commands']['register']>[1]
) {
tables.commands.set(commandId, handler)
return { dispose: () => void tables.commands.delete(commandId) }
}
}),
events: Object.freeze({
on(event: PluginEventName, handler: (payload: unknown) => void | Promise<void>) {
// Why: format 1 workers still listen under the old worktree.* names.
const name = PLUGIN_V1_EVENT_ALIASES.get(event) ?? event
const handlers = tables.events.get(name) ?? new Set()
tables.events.set(name, handlers)
const v1Payload = name !== event || event === 'agent.status.changed'
const subscription = addTo(handlers, (payload: unknown) =>
handler(v1Payload ? withV1WorktreeId(payload) : payload)
)
if (event !== 'workspace.changed') {
return subscription
}
// Replay on subscribe: the handler starts from the context as it is now.
let active = true
void hostCall('workspace.readContext')
.then((context) => active && handler({ context }))
.catch(() => undefined)
return {
dispose: () => {
active = false
subscription.dispose()
}
}
}
}),
hooks: Object.freeze({
on(event: PluginHookName, handler: PluginHookHandler) {
if (!isPluginHookName(event)) {
throw new TypeError(`orca.hooks.on: unknown hook ${String(event)}`)
}
if (typeof handler !== 'function') {
throw new TypeError('orca.hooks.on needs a handler function')
}
const handlers = tables.hooks.get(event) ?? new Set()
tables.hooks.set(event, handlers)
return addTo(handlers, handler)
}
}),
host: Object.freeze({
call: (method: string, params?: unknown, options?: { signal?: AbortSignal }) =>
hostCall(method, params, options),
has: (method: string) => WORKER_METHOD_NAMES.has(method)
}),
panels: Object.freeze({
handle(name: string, handler: PluginPanelRequestHandler) {
pluginBridgeNameSchema.parse(name)
if (typeof handler !== 'function') {
throw new TypeError('orca.panels.handle needs a handler function')
}
tables.panelRequests.set(name, handler)
return {
dispose: () => {
if (tables.panelRequests.get(name) === handler) {
tables.panelRequests.delete(name)
}
}
}
},
post(event: string, payload?: unknown, options?: { panel?: string }) {
pluginBridgeNameSchema.parse(event)
input.postToPanels({ event, payload, ...(options?.panel ? { panel: options.panel } : {}) })
}
}),
storage: Object.freeze({
get: async (key: string) => field(await hostCall('storage.get', { key }), 'value') ?? null,
set: (key: string, value: unknown) => ok('storage.set', { key, value }),
delete: (key: string) => ok('storage.delete', { key }),
keys: async () => {
const keys = field(await hostCall('storage.keys'), 'keys')
return Array.isArray(keys) ? keys.filter((key) => typeof key === 'string') : []
},
onDidChange: (listener: DataListener) => addTo(tables.dataListeners.storage, listener)
}),
settings: Object.freeze({
get: async (key?: string) => {
const raw = field(await hostCall('settings.get'), 'settings')
const settings = typeof raw === 'object' && raw !== null ? { ...raw } : {}
return key === undefined ? settings : field(settings, key)
},
set: (key: string, value: unknown) => ok('settings.set', { key, value }),
onDidChange: (listener: DataListener) => addTo(tables.dataListeners.settings, listener)
}),
secrets: Object.freeze({
get: async (key: string) => {
const value = field(await hostCall('secrets.get', { key }), 'value')
return typeof value === 'string' ? value : null
},
set: (key: string, value: string) => ok('secrets.set', { key, value }),
delete: (key: string) => ok('secrets.delete', { key })
}),
grantedCapabilities: Object.freeze([...input.grantedCapabilities]),
log: (message: string) => input.log(String(message))
})
}