Files
archived-orca/src/main/plugins/workers/host-api/plugin-host-automations.test.ts
T
Neil 255b5c22c1 feat(plugins): host API 1.8 — create workspaces, resume agents, automations (#41528)
* feat(plugins): proposed tier for host methods not yet frozen

A method spec may set `proposed: true`: only development plugins may call
it (others get not_permitted), and the minor, frame/worker method lists,
typings and skill references omit it. The reference renders such methods
in a separate Proposed section; dev workers' host.has answers for them.

* feat(plugins): param capabilities, host confirmations, automation provenance

- PluginHostMethodSpec.paramCapabilities: a passed param can require a
  second capability; executePluginHostCall and the mock host refuse it with
  capability_denied before any audit or effect, and the reference shows it.
- confirmPluginAction generalizes the external-open prompt into a host-owned
  confirmation, exposed as PluginHostServices.confirm (desktop only; absent
  in headless serve). It re-checks the plugin's approval after the answer.
- Automations record createdBy { kind: 'plugin', pluginKey, name }, set by
  the runtime from the in-process plugin caller (RpcContext.plugin), never
  from params; the Automations detail shows "Created by <plugin>".

* feat(plugins): workspace:create, automation:read and automation:write capabilities

New closed-enum kinds (older Orcas refuse such manifests with the engines
message), worker-only, with consent copy that names what each allows;
release floor PLUGIN_HOST_API_1_8_SINCE (1.4.259) joins
PLUGIN_SCHEMA_NEWEST_SINCE. agent:launch copy now says it also resumes.

* feat(plugins): host API 1.8 methods: workspace.create, agent.resume, automation.*

- workspace.create (workspace:create; agent also needs agent:launch): a
  worktree in a Git project, as orca worktree create does; with agent, the
  CLI's agent.launch create-worktree path, so the agent starts after setup.
  Setup is skipped or follows the project's settings; never run, an
  approved hash or a startup command.
- agent.resume (agent:launch): terminal.ensureAgentSession by session id;
  started is false when a terminal already ran it. agents.list rows and
  agent.status.changed carry sessionId.
- automation.list/create/update/delete (automation:read/write): create
  forwards only name, prompt, agent, target, schedule, time zone and
  enabled; update/delete of automations another plugin or the person made
  ask the person first and report cancelled or consent-unavailable.

* test(plugins): host API 1.8 coverage; regenerate plugin artifacts

Covers param capabilities (host and mock host), workspace.create payloads
and refusals, agent.resume keys and adoption, sessionId on agents.list,
automation projection, forbidden create fields, confirmation outcomes,
runtime-set provenance and capability access growth. Regenerates the
reference, schemas, typings, declarative runtime and skill references.

* fix(plugins): host API 1.8 review fixes

- Confirmations spend the frame dialog budget, allow one question per
  plugin at a time and pause after a refusal (rate_limited); a worker's
  question shows in the focused window, else the first visible one.
- Changing what an automation with extra agent settings runs (prompt,
  schedule, resuming) asks first even for its creator, showing the prompt.
- Removing, disabling or blocking a plugin pauses its automations and ends
  its ownership (createdBy.endedAt), so neither re-enabling nor a reinstall
  under the key resumes or edits them silently; the remove dialog says so.
- workspace.create and agent.resume record the terminals they return as
  the plugin's own; a launch that fails after its worktree exists names it.
- Setup-decision refusals are told by the runtime's error class (kept as
  the in-process RPC error's cause); generated names see every worktree
  of the project; resume transcripts match the workspace and host.
- Created by shows the plugin id beside its name.

* fix(plugins): end automation ownership only on uninstall, disable or block

- The ownership sweep no longer reads discovery: only an uninstall
  (announced by the removal path), the disabled list, the kill list or
  the plugin-system switch end it, and only once the service is ready,
  so an unreadable plugins folder pauses nothing. An install under the
  same key after a removal keeps what it creates.
- A new time zone on an automation with extra agent settings asks first.
- A failed launch names only a new worktree made from the requested name.
- Settings' plugins-off state and the CLI's plugin system off and plugin
  disable say that plugin-created automations are paused and stay so.

* fix(plugins): address host API 1.8 review threads

- Confirmations close when the worker's call ends, freeing the plugin's
  turn; they name the automation (short id, project, workspace,
  schedule), show any new prompt, and are refused as `changed` when the
  automation was edited while the person was asked.
- automation.create takes hostId (through the project's setup on that
  host) and a creationKey scoped to the plugin; the runtime rechecks the
  plugin's approval right before the write.
- agent.resume records only terminals it started; both it and
  workspace.create recheck approval before recording.
- automation.list never cuts a schedule (null when too long) or fails on
  an id too long to show.
- The Automations detail says when a creator plugin was removed or
  disabled.
2026-11-12 05:28:13 -08:00

346 lines
12 KiB
TypeScript

import { describe, expect, it, vi } from 'vitest'
import type { PluginRuntimeRpc } from './plugin-host-runtime-call'
import type { PluginHostServices } from './plugin-host-method-bindings'
import { callPluginHost, pluginHostTestServices } from './__mocks__/plugin-host-services-fixture'
const AUTOMATION = {
id: 'a1',
name: 'Nightly sweep',
prompt: 'p'.repeat(5000),
agentId: 'claude',
projectId: 'r1',
runContext: { repoId: 'r1', hostId: 'local', projectId: 'p1', path: '/src/r1' },
workspaceMode: 'existing',
workspaceId: 'r1::/src/r1',
rrule: 'FREQ=DAILY;BYHOUR=9;BYMINUTE=0',
timezone: 'UTC',
enabled: true,
nextRunAt: 10,
updatedAt: 3,
precheck: { command: 'secret-check', timeoutSeconds: 30 },
extraAgentArgs: '--dangerously-skip-permissions'
}
const OWN = {
...AUTOMATION,
id: 'a2',
createdBy: { kind: 'plugin', pluginKey: 'samples.demo', name: 'Demo' }
}
const OWN_ELEVATED = { ...OWN, id: 'a3', launchPreferences: { permissionMode: 'bypass' } }
const ENDED = {
...AUTOMATION,
id: 'a4',
createdBy: { kind: 'plugin', pluginKey: 'samples.demo', name: 'Demo', endedAt: 5 }
}
const BY_ID: Record<string, unknown> = { a2: OWN, a3: OWN_ELEVATED, a4: ENDED }
function runtime(overrides: Record<string, unknown> = {}, shows: unknown[] = []) {
const answers: Record<string, unknown> = {
'repo.list': {
repos: [
{ id: 'r1', displayName: 'App', executionHostId: 'local' },
{ id: 'twin', displayName: 'Twin', executionHostId: 'local' },
{ id: 'twin', displayName: 'Twin', connectionId: 'box' }
]
},
'projectHostSetup.list': {
setups: [
{
id: 's-box',
projectId: 'p-twin',
hostId: 'ssh:box',
repoId: 'twin',
path: '/srv/twin',
setupState: 'ready'
}
]
},
'automation.list': { automations: [AUTOMATION, OWN, ENDED] },
'worktree.list': { worktrees: [{ id: 'r1::/src/r1', identity: { key: 'wt2:local:i1' } }] },
'automation.create': { automation: { id: 'new' } },
'automation.update': { automation: AUTOMATION },
'automation.delete': { removed: true, id: 'a1' },
...overrides
}
return vi.fn<PluginRuntimeRpc>(async (method, params) => {
if (method === 'automation.show' && shows.length > 0) {
return { automation: shows.shift() }
}
if (method === 'automation.show') {
const id = typeof params === 'object' && params !== null && 'id' in params ? params.id : ''
return { automation: BY_ID[String(id)] ?? AUTOMATION }
}
return answers[method]
})
}
const methods = (rpc: ReturnType<typeof runtime>) => rpc.mock.calls.map(([method]) => method)
const call = (
method: string,
params: unknown,
rpc: PluginRuntimeRpc,
overrides: Partial<PluginHostServices> = {}
) =>
callPluginHost({
method,
params,
granted: ['automation:read', 'automation:write'],
services: pluginHostTestServices(rpc, overrides)
})
describe('automation.list', () => {
it('shows what an automation does, never its precheck or agent arguments', async () => {
const outcome = await call('automation.list', {}, runtime())
expect(outcome.ok && outcome.value).toEqual({
automations: [
{
id: 'a1',
name: 'Nightly sweep',
agent: 'claude',
prompt: 'p'.repeat(4096),
promptTruncated: true,
projectId: 'r1',
hostId: 'local',
workspaceId: 'identity:wt2:local:i1',
workspaceMode: 'existing',
schedule: 'FREQ=DAILY;BYHOUR=9;BYMINUTE=0',
timezone: 'UTC',
enabled: true,
nextRunAt: 10,
lastRunAt: null,
createdByThisPlugin: false
},
expect.objectContaining({ id: 'a2', createdByThisPlugin: true }),
// Its plugin was removed or disabled since: the plugin no longer owns it.
expect.objectContaining({ id: 'a4', createdByThisPlugin: false })
],
truncated: false
})
})
})
describe('automation.create', () => {
it('forwards only what a plugin may set, and names the plugin as its creator', async () => {
const rpc = runtime()
expect(
await call(
'automation.create',
{
name: 'Deps',
prompt: 'Check dependencies',
agent: 'codex',
projectId: 'r1',
schedule: '0 9 * * 1-5'
},
rpc
)
).toEqual({ ok: true, value: { automationId: 'new' } })
const [, params, options] =
rpc.mock.calls.find(([method]) => method === 'automation.create') ?? []
expect(params).toEqual({
name: 'Deps',
prompt: 'Check dependencies',
agentId: 'codex',
repo: 'id:r1',
workspaceMode: 'new_per_run',
rrule: '0 9 * * 1-5',
dtstart: expect.any(Number),
enabled: true
})
expect(options?.plugin).toEqual({ key: 'samples.demo', name: 'samples.demo' })
})
it('refuses a precheck, agent arguments, launch setup and setup choices', async () => {
const rpc = runtime()
const base = { name: 'x', prompt: 'y', agent: 'claude', projectId: 'r1', schedule: '0 9 * * *' }
const outcomes = await Promise.all(
[
{ precheck: { command: 'rm -rf ~', timeoutSeconds: 1 } },
{ agentArgs: '--yolo' },
{ extraAgentArgs: '--yolo' },
{ launchSetupPatch: { choices: {} } },
{ setupDecision: 'run' },
{ createdBy: { kind: 'plugin', pluginKey: 'other.plugin' } }
].map((extra) => call('automation.create', { ...base, ...extra }, rpc))
)
for (const outcome of outcomes) {
expect(outcome).toMatchObject({ ok: false, code: 'invalid_params' })
}
expect(rpc).not.toHaveBeenCalled()
})
})
describe('automation.update and automation.delete', () => {
it("change the plugin's own automations without asking", async () => {
const rpc = runtime()
const confirm = vi.fn()
expect(
await call('automation.update', { automationId: 'a2', enabled: false }, rpc, { confirm })
).toEqual({ ok: true, value: { updated: true } })
expect(confirm).not.toHaveBeenCalled()
expect(rpc.mock.calls.find(([method]) => method === 'automation.update')?.[1]).toEqual({
id: 'a2',
updates: { enabled: false }
})
})
it("ask before touching another's, and change nothing when refused or nobody can answer", async () => {
const cancelled = runtime()
const confirm = vi.fn().mockResolvedValue('cancelled')
expect(await call('automation.delete', { automationId: 'a1' }, cancelled, { confirm })).toEqual(
{ ok: true, value: { deleted: false, reason: 'cancelled' } }
)
expect(confirm).toHaveBeenCalledWith(
'samples.demo',
{
kind: 'automation.delete',
// Names repeat: the question says which one, where and when it runs.
automation: {
id: 'a1',
name: 'Nightly sweep',
project: 'App',
workspace: 'r1',
schedule: 'FREQ=DAILY;BYHOUR=9;BYMINUTE=0'
}
},
expect.anything()
)
expect(methods(cancelled)).not.toContain('automation.delete')
// Headless serve has no window to ask in.
const headless = runtime()
expect(
await call('automation.update', { automationId: 'a1', prompt: 'new' }, headless)
).toEqual({ ok: true, value: { updated: false, reason: 'consent-unavailable' } })
expect(methods(headless)).not.toContain('automation.update')
const allowed = runtime()
const allow = vi.fn().mockResolvedValue('allowed')
expect(
await call('automation.delete', { automationId: 'a1' }, allowed, { confirm: allow })
).toEqual({
ok: true,
value: { deleted: true }
})
})
it("ask before a new prompt or resuming for one that runs with extra agent settings, even the plugin's own", async () => {
const confirm = vi.fn().mockResolvedValue('allowed')
const rpc = runtime()
await call('automation.update', { automationId: 'a3', prompt: 'Do more' }, rpc, { confirm })
expect(confirm).toHaveBeenCalledWith(
'samples.demo',
{
kind: 'automation.update',
automation: expect.objectContaining({ id: 'a3', name: 'Nightly sweep' }),
fields: ['prompt'],
elevated: true,
prompt: 'Do more'
},
expect.anything()
)
confirm.mockClear()
// A new time zone moves when it runs.
await call('automation.update', { automationId: 'a3', timezone: 'Asia/Tokyo' }, rpc, {
confirm
})
expect(confirm).toHaveBeenCalledWith(
'samples.demo',
expect.objectContaining({ elevated: true, fields: ['timezone'] }),
expect.anything()
)
confirm.mockClear()
// A rename runs nothing new.
await call('automation.update', { automationId: 'a3', name: 'Renamed' }, rpc, { confirm })
expect(confirm).not.toHaveBeenCalled()
})
it('ask once the plugin that made it was removed or disabled', async () => {
const confirm = vi.fn().mockResolvedValue('cancelled')
const rpc = runtime()
expect(await call('automation.delete', { automationId: 'a4' }, rpc, { confirm })).toEqual({
ok: true,
value: { deleted: false, reason: 'cancelled' }
})
})
it("show the new prompt for another's automation too", async () => {
const confirm = vi.fn().mockResolvedValue('allowed')
await call('automation.update', { automationId: 'a1', prompt: 'Delete the repo' }, runtime(), {
confirm
})
expect(confirm).toHaveBeenCalledWith(
'samples.demo',
expect.objectContaining({ prompt: 'Delete the repo' }),
expect.anything()
)
})
it('change nothing when the automation changed while the person was asked', async () => {
const rpc = runtime({}, [AUTOMATION, { ...AUTOMATION, name: 'Repurposed', updatedAt: 4 }])
const confirm = vi.fn().mockResolvedValue('allowed')
expect(await call('automation.delete', { automationId: 'a1' }, rpc, { confirm })).toEqual({
ok: true,
value: { deleted: false, reason: 'changed' }
})
expect(methods(rpc)).not.toContain('automation.delete')
})
})
describe('automation.create targets', () => {
const base = { name: 'x', prompt: 'y', agent: 'claude', schedule: '0 9 * * *' }
const sent = (rpc: ReturnType<typeof runtime>) =>
rpc.mock.calls.find(([method]) => method === 'automation.create')?.[1]
it("runs on the host hostId names, through that host's project setup", async () => {
expect(await call('automation.create', { ...base, projectId: 'twin' }, runtime())).toEqual({
ok: false,
code: 'action_failed',
error: 'two hosts have this project; pass the hostId project.list gives'
})
const rpc = runtime()
await call('automation.create', { ...base, projectId: 'twin', hostId: 'ssh:box' }, rpc)
expect(sent(rpc)).toMatchObject({
repo: 'id:twin',
workspaceMode: 'new_per_run',
runContext: {
kind: 'workspace-run',
projectId: 'p-twin',
hostId: 'ssh:box',
projectHostSetupId: 's-box',
repoId: 'twin',
path: '/srv/twin'
}
})
expect(
await call('automation.create', { ...base, projectId: 'twin', hostId: 'local' }, runtime())
).toMatchObject({ ok: false, error: 'this project is not set up on that host' })
})
it("keeps a plugin's creation keys its own", async () => {
const rpc = runtime()
await call('automation.create', { ...base, projectId: 'r1', creationKey: 'nightly' }, rpc)
expect(sent(rpc)).toMatchObject({ creationKey: 'plugin:samples.demo:nightly' })
})
})
describe('automation.list bounds', () => {
it('never cuts a schedule or fails the list on an id too long to show', async () => {
const odd = {
...AUTOMATION,
id: 'a9',
rrule: '0 '.repeat(1500),
workspaceId: `r1::/${'deep/'.repeat(300)}`
}
const outcome = await call(
'automation.list',
{},
runtime({ 'automation.list': { automations: [odd] }, 'worktree.list': { worktrees: [] } })
)
expect(outcome).toMatchObject({
ok: true,
value: { automations: [{ id: 'a9', schedule: null, workspaceId: null }] }
})
})
})