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