mirror of
https://github.com/stablyai/orca.git
synced 2026-11-16 02:47:34 +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>
76 lines
3.2 KiB
TypeScript
76 lines
3.2 KiB
TypeScript
import { PLUGIN_HOOKS_SINCE } from '../../shared/plugins/manifest/plugin-schema-field-docs'
|
|
import {
|
|
COMMON_FILES,
|
|
json,
|
|
manifest,
|
|
readme,
|
|
type PluginTemplate,
|
|
type PluginTemplateInput
|
|
} from './plugin-template-files'
|
|
import { PLUGIN_TYPES_DIR } from './plugin-type-files'
|
|
|
|
const WORKER_TS = `// A guard: Orca asks this worker before it types text into a terminal (terminal.send).
|
|
// Orca transpiles this file when it loads: no build step.
|
|
import type { OrcaWorkerApi } from 'orca/worker'
|
|
|
|
const BLOCKED = [/\\brm\\s+-rf\\s+\\/(?:\\s|$)/, /\\bmkfs\\b/]
|
|
|
|
export default function activate(orca: OrcaWorkerApi): void {
|
|
orca.hooks.on('terminal.send', (event) => {
|
|
// Decide first: an awaited call before returning could fail or time out and let it through.
|
|
if (BLOCKED.some((pattern) => pattern.test(event.text))) {
|
|
orca.log(\`blocked in \${event.terminalId}: \${event.text}\`)
|
|
return { deny: 'blocked by the guard plugin' }
|
|
}
|
|
// Returning nothing passes the send on unchanged.
|
|
return undefined
|
|
})
|
|
}
|
|
`
|
|
|
|
const WORKER_TEST_TS = `// Runs the hook as Orca would, with this worker as the only plugin in the chain.
|
|
import { assert, mountWorker, test } from 'orca/testing'
|
|
import * as main from './worker'
|
|
|
|
const send = (text: string) => ({ terminalId: 't1', text, enter: true, inputKind: 'driving' as const })
|
|
|
|
test('refuses a dangerous command and passes everything else unchanged', async () => {
|
|
const worker = await mountWorker(main)
|
|
assert.deepEqual(await worker.hooks.fire('terminal.send', send('rm -rf /')), {
|
|
kind: 'deny',
|
|
reason: 'blocked by the guard plugin'
|
|
})
|
|
assert.deepEqual(await worker.hooks.fire('terminal.send', send('ls -la ')), {
|
|
kind: 'continue',
|
|
event: send('ls -la ')
|
|
})
|
|
await worker.deactivate()
|
|
})
|
|
`
|
|
|
|
/** A worker-only guard on `terminal.send`, failing closed, with its test. */
|
|
export function hook(input: PluginTemplateInput): PluginTemplate {
|
|
return {
|
|
description:
|
|
'Worker-only hook that refuses dangerous terminal commands, with a test (needs --approve to load)',
|
|
files: {
|
|
'orca-plugin.json': manifest(input, 'Refuses dangerous commands sent to terminals.', {
|
|
engines: { orca: `>=${PLUGIN_HOOKS_SINCE}` },
|
|
execution: 'trusted-worker',
|
|
pluginApi: 1,
|
|
main: 'src/worker.ts',
|
|
// Why deny: a guard that crashes or times out must not let the command through.
|
|
contributes: { hooks: [{ event: 'terminal.send', onError: 'deny' }] }
|
|
}),
|
|
'src/worker.ts': WORKER_TS,
|
|
'src/worker.test.ts': WORKER_TEST_TS,
|
|
'tsconfig.json': json({ extends: `./${PLUGIN_TYPES_DIR}/tsconfig.json`, include: ['src'] }),
|
|
'README.md': readme(
|
|
input,
|
|
`A guard (\`src/worker.ts\`) on the \`terminal.send\` hook: before Orca, the CLI or a plugin types text into a terminal, the worker can refuse it with \`{ deny }\` or pass it on. \`"onError": "deny"\` in \`orca-plugin.json\` makes a crash or timeout refuse the send too. \`orca plugin test .\` runs \`src/worker.test.ts\` with \`orca/testing\`; with the folder loaded, \`orca plugin dev hook . terminal.send --data '{"terminalId":"t1","text":"rm -rf /","enter":true,"inputKind":"driving"}'\` prints what the chain decides.`
|
|
),
|
|
...COMMON_FILES
|
|
}
|
|
}
|
|
}
|