rterm-backend 3.1.0 → 3.1.2

package/package.json

@@ -1,9 +1,20 @@
 {
   "name": "rterm-backend",
-  "version": "3.1.0",
-  "description": "Headless AI-native backend for RTerm / neuralOS — v3.1.0: systematic bug-hunt audit, all 12 candidates confirmed-not-a-bug.",
+  "version": "3.1.2",
+  "description": "Headless AI-native backend for RTerm / neuralOS — v3.1.2: comprehensive NATS event mesh (token/user-pass/NKey/JWT/creds/TLS auth, JetStream streams+consumers, Key-Value, request/reply, queue groups, headers, lifecycle). Transports (SSH/serial/local) and SQLite install automatically.",
   "main": "bin/gybackend.cjs",
   "bin": { "gybackend": "bin/gybackend.cjs" },
   "license": "MIT",
-  "engines": { "node": ">=18" }
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "@nats-io/jetstream": "^3.4.0",
+    "@nats-io/kv": "^3.4.0",
+    "@nats-io/transport-node": "^3.4.0",
+    "better-sqlite3": "^12.11.1"
+  },
+  "optionalDependencies": {
+    "serialport": "^12.0.0",
+    "ssh2": "^1.17.0",
+    "node-pty": "1.2.0-beta.3"
+  }
 }

package/plugins/agentspan-bridge/agentspan-bridge.extreme.spec.ts

@@ -0,0 +1,328 @@
+/**
+ * agentspan-bridge.extreme.spec.ts — exhaustive offline tests for the
+ * AgentSpan/Conductor bridge: the dependency-free HTTP client (URL building,
+ * auth headers, error mapping, every endpoint) and the plugin glue (config
+ * resolution, auth blob parsing, status/row normalization, tool wiring,
+ * unreachable-server resilience, trigger match). No network — fetch is mocked.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { ConductorClient, ConductorApiError, authHeaders, joinUrl, DEFAULT_BASE_URL } from './conductorClient.mjs'
+import {
+  register,
+  resolveConfig,
+  parseAuthBlob,
+  buildClient,
+  summarizeStatus,
+  toExecutionRows,
+  isFailedExecution,
+} from './index.mjs'
+
+// ─── mock fetch ─────────────────────────────────────────────────────────────
+/** A scriptable fetch mock: records calls, returns queued/mapped responses. */
+function mockFetch(respond) {
+  const calls = []
+  const fn = async (url, init) => {
+    calls.push({ url, init })
+    const r = typeof respond === 'function' ? respond(url, init, calls.length) : respond
+    return { ok: r.ok !== false && (r.status ?? 200) < 400, status: r.status ?? 200, text: async () => r.text ?? (r.json !== undefined ? JSON.stringify(r.json) : '') }
+  }
+  fn.calls = calls
+  return fn
+}
+
+// ─── conductorClient: URL + auth header building ───────────────────────────
+test('joinUrl joins base+path with a single slash', () => {
+  assert.equal(joinUrl('http://h:6767/', '/api/agent/start'), 'http://h:6767/api/agent/start')
+  assert.equal(joinUrl('http://h:6767', 'api/agent/start'), 'http://h:6767/api/agent/start')
+  assert.equal(joinUrl(undefined, '/x'), `${DEFAULT_BASE_URL}/x`)
+})
+
+test('authHeaders only sends X-Auth-* when both key+secret present', () => {
+  assert.deepEqual(authHeaders(undefined), { 'content-type': 'application/json', accept: 'application/json' })
+  assert.deepEqual(authHeaders({ key: 'k' }), { 'content-type': 'application/json', accept: 'application/json' })
+  const h = authHeaders({ key: 'k', secret: 's' })
+  assert.equal(h['X-Auth-Key'], 'k')
+  assert.equal(h['X-Auth-Secret'], 's')
+})
+
+test('ConductorClient requires a fetchImpl', () => {
+  assert.throws(() => new ConductorClient({}), /fetchImpl/)
+})
+
+// ─── conductorClient: endpoints ────────────────────────────────────────────
+test('health() maps actuator health to {ok,status} and never throws', async () => {
+  const up = new ConductorClient({ fetchImpl: mockFetch({ json: { status: 'UP' } }) })
+  assert.deepEqual(await up.health(), { ok: true, status: 'UP', raw: { status: 'UP' } })
+  const down = new ConductorClient({ fetchImpl: mockFetch(() => { throw new Error('ECONNREFUSED') }) })
+  const h = await down.health()
+  assert.equal(h.ok, false)
+  assert.equal(h.status, 'DOWN')
+  assert.match(h.error, /ECONNREFUSED/)
+})
+
+test('runAgent posts to /api/agent/start and extracts executionId', async () => {
+  const f = mockFetch({ json: { executionId: 'exec-123' } })
+  const c = new ConductorClient({ fetchImpl: f })
+  const r = await c.runAgent({ name: 'a' }, 'hello')
+  assert.equal(r.executionId, 'exec-123')
+  const call = f.calls[0]
+  assert.equal(call.url, `${DEFAULT_BASE_URL}/api/agent/start`)
+  assert.equal(call.init.method, 'POST')
+  const body = JSON.parse(call.init.body)
+  assert.deepEqual(body.agent, { name: 'a' })
+  assert.equal(body.input, 'hello')
+})
+
+test('runAgent falls back to workflowId/id when executionId absent', async () => {
+  const c = new ConductorClient({ fetchImpl: mockFetch({ json: { workflowId: 'wf-9' } }) })
+  assert.equal((await c.runAgent({ name: 'a' })).executionId, 'wf-9')
+})
+
+test('agentStatus/Respond/Stop hit the lifecycle endpoints + require id', async () => {
+  const f = mockFetch({ json: { status: 'RUNNING' } })
+  const c = new ConductorClient({ fetchImpl: f })
+  await assert.rejects(() => c.agentStatus(), /executionId/)
+  await c.agentStatus('e1')
+  await c.agentRespond('e1', { approved: true })
+  await c.agentStop('e1')
+  const urls = f.calls.map((x) => `${x.init.method} ${x.url}`)
+  assert.ok(urls.includes(`GET ${DEFAULT_BASE_URL}/api/agent/e1`))
+  assert.ok(urls.includes(`POST ${DEFAULT_BASE_URL}/api/agent/e1/respond`))
+  assert.ok(urls.includes(`POST ${DEFAULT_BASE_URL}/api/agent/e1/stop`))
+})
+
+test('startWorkflow builds the right path + returns the id string', async () => {
+  const f = mockFetch({ text: 'wf-abc' })
+  const c = new ConductorClient({ fetchImpl: f })
+  const id = await c.startWorkflow('cleanup', { host: 'web-1' }, { version: 3 })
+  assert.equal(id, 'wf-abc')
+  assert.match(f.calls[0].url, /\/api\/workflow\/cleanup\?version=3$/)
+})
+
+test('getWorkflow/terminate/retry/search hit the engine surface', async () => {
+  const f = mockFetch({ json: { results: [] } })
+  const c = new ConductorClient({ fetchImpl: f })
+  await c.getWorkflow('w1')
+  await c.terminateWorkflow('w1', 'done')
+  await c.retryWorkflow('w1')
+  await c.searchWorkflows('status:FAILED', 5)
+  const urls = f.calls.map((x) => `${x.init.method} ${x.url}`)
+  assert.ok(urls.some((u) => u.startsWith(`GET ${DEFAULT_BASE_URL}/api/workflow/w1?includeTasks=`)))
+  assert.ok(urls.some((u) => u.startsWith(`DELETE ${DEFAULT_BASE_URL}/api/workflow/w1?reason=done`)))
+  assert.ok(urls.includes(`POST ${DEFAULT_BASE_URL}/api/workflow/w1/retry`))
+  assert.ok(urls.some((u) => u.includes('/api/workflow/search?') && u.includes('status%3AFAILED')))
+})
+
+test('non-2xx responses raise ConductorApiError with status + body', async () => {
+  // health() swallows errors into {ok:false}; other methods raise ConductorApiError.
+  const up = new ConductorClient({ fetchImpl: mockFetch({ ok: false, status: 500, text: 'boom' }) })
+  const h = await up.health()
+  assert.equal(h.ok, false)
+  const c2 = new ConductorClient({ fetchImpl: mockFetch({ ok: false, status: 500, text: 'boom' }) })
+  await assert.rejects(() => c2.getWorkflow('w1'), ConductorApiError)
+  const c3 = new ConductorClient({ fetchImpl: mockFetch({ ok: false, status: 404, text: 'nope' }) })
+  await assert.rejects(() => c3.agentStatus('x'), ConductorApiError)
+})
+
+// ─── plugin glue: config + auth ────────────────────────────────────────────
+test('resolveConfig prefers settings, falls back to env, strips trailing slash', () => {
+  const c = resolveConfig({ settings: { agentspan: { serverUrl: 'http://srv:6767/', authSecretRef: 'as-auth' } } }, {})
+  assert.equal(c.serverUrl, 'http://srv:6767')
+  assert.equal(c.authSecretRef, 'as-auth')
+  const env = resolveConfig({}, { AGENTSPAN_SERVER_URL: 'http://env:6767/' })
+  assert.equal(env.serverUrl, 'http://env:6767')
+  assert.equal(resolveConfig({}, {}).serverUrl, DEFAULT_BASE_URL)
+})
+
+test('parseAuthBlob parses KEY=VAL lines into {key,secret}', () => {
+  assert.deepEqual(parseAuthBlob('AGENTSPAN_AUTH_KEY=k\nAGENTSPAN_AUTH_SECRET=s'), { key: 'k', secret: 's' })
+  assert.deepEqual(parseAuthBlob('AUTH_KEY=a\nAUTH_SECRET=b'), { key: 'a', secret: 'b' })
+  assert.equal(parseAuthBlob('AGENTSPAN_AUTH_KEY=only'), undefined)
+  assert.equal(parseAuthBlob(''), undefined)
+  assert.equal(parseAuthBlob(undefined), undefined)
+})
+
+test('buildClient wires auth from ctx.getSecret + configures baseUrl', () => {
+  const ctx = {
+    settings: { agentspan: { serverUrl: 'http://srv:6767', authSecretRef: 'as-auth' } },
+    getSecret: (k) => (k === 'as-auth' ? 'AGENTSPAN_AUTH_KEY=k\nAGENTSPAN_AUTH_SECRET=s' : undefined),
+  }
+  const { client, config } = buildClient(ctx, mockFetch({ json: {} }))
+  assert.equal(config.serverUrl, 'http://srv:6767')
+  assert.equal(client.auth.key, 'k')
+  // missing secret → no auth, no crash
+  const noSecret = buildClient({ settings: { agentspan: { authSecretRef: 'nope' } }, getSecret: () => undefined }, mockFetch({ json: {} }))
+  assert.equal(noSecret.client.auth, undefined)
+})
+
+// ─── plugin glue: normalization helpers ────────────────────────────────────
+test('summarizeStatus normalizes agent + workflow payloads', () => {
+  const a = summarizeStatus({ executionId: 'e1', agentName: 'bot', status: 'RUNNING', tasks: [{ status: 'COMPLETED' }, { status: 'FAILED' }] })
+  assert.equal(a.status, 'RUNNING')
+  assert.equal(a.taskCount, 2)
+  assert.equal(a.completedTasks, 1)
+  assert.equal(a.failedTasks, 1)
+  const w = summarizeStatus({ workflowId: 'w1', workflowName: 'cleanup', status: 'COMPLETED', reasonForIncompletion: undefined })
+  assert.equal(w.name, 'cleanup')
+  assert.equal(w.status, 'COMPLETED')
+  assert.deepEqual(summarizeStatus(null), { status: 'UNKNOWN' })
+})
+
+test('toExecutionRows handles results/workflows/array shapes', () => {
+  assert.equal(toExecutionRows({ results: [{ workflowId: 'a', workflowName: 'x', status: 'RUNNING' }] }).length, 1)
+  assert.equal(toExecutionRows({ workflows: [{ id: 'b', name: 'y', status: 'FAILED' }] })[0].status, 'FAILED')
+  assert.equal(toExecutionRows([{ workflowId: 'c' }]).length, 1)
+  assert.deepEqual(toExecutionRows({}), [])
+})
+
+test('isFailedExecution matches terminal-failure statuses only', () => {
+  assert.ok(isFailedExecution('FAILED'))
+  assert.ok(isFailedExecution('terminated'))
+  assert.ok(isFailedExecution('TIMED_OUT'))
+  assert.ok(!isFailedExecution('RUNNING'))
+  assert.ok(!isFailedExecution('COMPLETED'))
+})
+
+// ─── plugin registration + tool behavior (mocked server) ──────────────────
+/** Build a ctx with register* capture + a mocked client injected. */
+function makeCtx(fetchImpl, settings = {}) {
+  const tools = new Map()
+  const triggers = []
+  const panels = []
+  const logs = []
+  const ctx = {
+    settings: { agentspan: settings },
+    registerTool: (t) => tools.set(t.name, t),
+    registerTrigger: (t) => triggers.push(t),
+    registerPanel: (p) => panels.push(p),
+    log: (l) => logs.push(l),
+  }
+  // inject the mocked fetch by overriding buildClient's realFetch via a hack:
+  // we re-register with a patched client below.
+  return { tools, triggers, panels, logs, ctx }
+}
+
+test('register wires 9 tools, 1 trigger, 1 panel', () => {
+  const { tools, triggers, panels, ctx } = makeCtx(null, { serverUrl: 'http://x:6767' })
+  register(ctx)
+  assert.equal(tools.size, 9)
+  for (const n of ['agentspan_health', 'agentspan_run', 'agentspan_status', 'agentspan_approve', 'agentspan_list', 'agentspan_stop', 'agentspan_export_playbook', 'agentspan_register_playbook', 'agentspan_delegate']) assert.ok(tools.has(n), `missing ${n}`)
+  assert.equal(triggers.length, 1)
+  assert.equal(panels.length, 1)
+})
+
+test('agentspan_health returns error+hint when server unreachable (no throw)', async () => {
+  const { tools, ctx } = makeCtx(null, { serverUrl: 'http://down:6767' })
+  // force a failing fetch by monkey-patching global fetch
+  const realFetch = globalThis.fetch
+  globalThis.fetch = async () => { throw new Error('ECONNREFUSED') }
+  register(ctx)
+  const r = await tools.get('agentspan_health').handler({})
+  assert.equal(r.error && true, true)
+  assert.match(r.hint, /AgentSpan server running/)
+  globalThis.fetch = realFetch
+})
+
+test('agentspan_run (agentConfig) returns executionId + uiUrl from a live mock server', async () => {
+  const { tools, ctx } = makeCtx(null, { serverUrl: DEFAULT_BASE_URL })
+  const realFetch = globalThis.fetch
+  globalThis.fetch = async (url, init) => ({
+    ok: true, status: 200,
+    text: async () => JSON.stringify({ executionId: 'exec-42' }),
+  })
+  register(ctx)
+  const r = await tools.get('agentspan_run').handler({ agentConfig: { name: 'a' }, prompt: 'hi' })
+  assert.equal(r.executionId, 'exec-42')
+  assert.match(r.uiUrl, /\/execution\/exec-42$/)
+  globalThis.fetch = realFetch
+})
+
+test('agentspan_run (workflow) returns workflowId; needs agentConfig-or-workflow', async () => {
+  const { tools, ctx } = makeCtx(null, { serverUrl: DEFAULT_BASE_URL })
+  const realFetch = globalThis.fetch
+  globalThis.fetch = async () => ({ ok: true, status: 200, text: async () => 'wf-7' })
+  register(ctx)
+  const r = await tools.get('agentspan_run').handler({ workflow: 'cleanup', input: { h: 1 } })
+  assert.equal(r.workflowId, 'wf-7')
+  const bad = await tools.get('agentspan_run').handler({})
+  assert.match(bad.error, /agentConfig or workflow/)
+  globalThis.fetch = realFetch
+})
+
+test('agentspan_status falls back to workflow engine when agent surface 404s', async () => {
+  const { tools, ctx } = makeCtx(null, { serverUrl: DEFAULT_BASE_URL })
+  const realFetch = globalThis.fetch
+  globalThis.fetch = async (url) => {
+    if (url.includes('/api/agent/')) return { ok: false, status: 404, text: async () => 'not an agent' }
+    return { ok: true, status: 200, text: async () => JSON.stringify({ workflowId: 'w1', workflowName: 'cleanup', status: 'COMPLETED', tasks: [] }) }
+  }
+  register(ctx)
+  const r = await tools.get('agentspan_status').handler({ executionId: 'w1' })
+  assert.equal(r.kind, 'workflow')
+  assert.equal(r.status, 'COMPLETED')
+  globalThis.fetch = realFetch
+})
+
+test('agentspan_approve responds + reports new status; requires id', async () => {
+  const { tools, ctx } = makeCtx(null, { serverUrl: DEFAULT_BASE_URL })
+  const realFetch = globalThis.fetch
+  const posted = []
+  globalThis.fetch = async (url, init) => {
+    if (init.method === 'POST' && url.includes('/respond')) { posted.push(url); return { ok: true, status: 200, text: async () => '' } }
+    return { ok: true, status: 200, text: async () => JSON.stringify({ executionId: 'e1', status: 'RUNNING' }) }
+  }
+  register(ctx)
+  const bad = await tools.get('agentspan_approve').handler({})
+  assert.match(bad.error, /executionId/)
+  const r = await tools.get('agentspan_approve').handler({ executionId: 'e1', output: { approved: true } })
+  assert.equal(r.responded, true)
+  assert.ok(posted[0].includes('/api/agent/e1/respond'))
+  globalThis.fetch = realFetch
+})
+
+test('agentspan_list returns normalized execution rows', async () => {
+  const { tools, ctx } = makeCtx(null, { serverUrl: DEFAULT_BASE_URL })
+  const realFetch = globalThis.fetch
+  globalThis.fetch = async () => ({ ok: true, status: 200, text: async () => JSON.stringify({ results: [{ workflowId: 'a', workflowName: 'x', status: 'RUNNING' }, { workflowId: 'b', workflowName: 'y', status: 'FAILED' }] }) })
+  register(ctx)
+  const r = await tools.get('agentspan_list').handler({})
+  assert.equal(r.count, 2)
+  assert.equal(r.executions[1].status, 'FAILED')
+  globalThis.fetch = realFetch
+})
+
+test('agentspan_stop tries agent stop then terminates workflow; requires id', async () => {
+  const { tools, ctx } = makeCtx(null, { serverUrl: DEFAULT_BASE_URL })
+  const realFetch = globalThis.fetch
+  const calls = []
+  globalThis.fetch = async (url, init) => {
+    calls.push(`${init.method} ${url}`)
+    if (url.includes('/api/agent/') && url.includes('/stop')) return { ok: false, status: 404, text: async () => 'no' }
+    return { ok: true, status: 200, text: async () => '' }
+  }
+  register(ctx)
+  const bad = await tools.get('agentspan_stop').handler({})
+  assert.match(bad.error, /executionId/)
+  const r = await tools.get('agentspan_stop').handler({ executionId: 'w1' })
+  assert.equal(r.stopped, true)
+  assert.ok(calls.some((c) => c.startsWith(`DELETE ${DEFAULT_BASE_URL}/api/workflow/w1`)))
+  globalThis.fetch = realFetch
+})
+
+test('trigger fires only for agentspan FAILED events', () => {
+  const { triggers, ctx } = makeCtx(null, {})
+  register(ctx)
+  const t = triggers[0]
+  assert.ok(t.match({ source: 'agentspan', status: 'FAILED' }))
+  assert.ok(!t.match({ source: 'agentspan', status: 'RUNNING' }))
+  assert.ok(!t.match({ source: 'netdata', status: 'FAILED' }))
+})
+
+test('panel renders an executions table', () => {
+  const { panels, ctx } = makeCtx(null, { serverUrl: 'http://x:6767' })
+  register(ctx)
+  const html = panels[0].render([{ name: 'cleanup', id: 'e1', status: 'RUNNING', startTime: 'now' }])
+  assert.match(html, /cleanup/)
+  assert.match(html, /http:\/\/x:6767/)
+})

package/plugins/agentspan-bridge/agentspan-bridge.phase2.extreme.spec.ts

@@ -0,0 +1,282 @@
+/**
+ * agentspan-bridge.phase2.extreme.spec.ts — exhaustive offline tests for the
+ * Phase-2 additions: playbookToWorkflowDef mapper (step→task mapping, DAG
+ * edges, wait/rollback, retries), the conductorClient registerWorkflowDef /
+ * getWorkflowDef methods, and the new tools (agentspan_export_playbook,
+ * agentspan_register_playbook, agentspan_delegate) with mocked fetch. No network.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { ConductorClient, DEFAULT_BASE_URL } from './conductorClient.mjs'
+import {
+  playbookToWorkflowDef,
+  stepToTask,
+  rollbackToTask,
+  taskRef,
+} from './playbookToWorkflowDef.mjs'
+import { register, findPlaybook, buildDelegateAgentConfig } from './index.mjs'
+
+// ─── mock fetch ─────────────────────────────────────────────────────────────
+function mockFetch(respond) {
+  const calls = []
+  const fn = async (url, init) => {
+    calls.push({ url, init })
+    const r = typeof respond === 'function' ? respond(url, init) : respond
+    return { ok: r.ok !== false && (r.status ?? 200) < 400, status: r.status ?? 200, text: async () => r.text ?? (r.json !== undefined ? JSON.stringify(r.json) : '') }
+  }
+  fn.calls = calls
+  return fn
+}
+
+const samplePlaybook = {
+  id: 'pb-1',
+  name: 'nightly backup',
+  description: 'backup the core switch',
+  steps: [
+    { id: 'st-1', name: 'prep', kind: 'command', command: 'term length 0' },
+    { id: 'st-2', name: 'collect', kind: 'script', scriptId: 'scr-9' },
+    { id: 'st-3', name: 'settle', kind: 'wait', waitSeconds: 5 },
+    { id: 'st-4', name: 'apply', kind: 'command', command: 'apply acl', rollback: { kind: 'command', command: 'no acl' }, dependsOn: ['st-1', 'st-2'] },
+  ],
+}
+
+// ─── taskRef ────────────────────────────────────────────────────────────────
+test('taskRef sanitizes to Conductor-safe refs', () => {
+  assert.equal(taskRef('st-1'), 'st_1')
+  assert.equal(taskRef('apply acl!'), 'apply_acl_')
+  assert.equal(taskRef(undefined, 'fallback'), 'fallback')
+  assert.equal(taskRef(''), 'step')
+})
+
+// ─── stepToTask ─────────────────────────────────────────────────────────────
+test('command step → HTTP run_command task with command + validate', () => {
+  const t = stepToTask({ id: 'st-1', kind: 'command', command: 'show run', validate: { expect: 'ok' } }, 0, {})
+  assert.equal(t.type, 'HTTP')
+  assert.equal(t.taskReferenceName, 'st_1')
+  const req = t.inputParameters.http_request
+  assert.equal(req.method, 'POST')
+  assert.equal(req.body.kind, 'run_command')
+  assert.equal(req.body.command, 'show run')
+  assert.deepEqual(req.body.validate, { expect: 'ok' })
+})
+
+test('script step → SIMPLE script-reference task (scriptId, no inline body)', () => {
+  const t = stepToTask({ id: 'st-2', kind: 'script', scriptId: 'scr-9', name: 'collect' }, 1, {})
+  assert.equal(t.type, 'SIMPLE')
+  assert.equal(t.inputParameters.kind, 'rterm_script')
+  assert.equal(t.inputParameters.scriptId, 'scr-9')
+  assert.equal(t.inputParameters.name, 'collect')
+})
+
+test('wait step → Conductor WAIT task with duration', () => {
+  const t = stepToTask({ id: 'st-3', kind: 'wait', waitSeconds: 7 }, 2, {})
+  assert.equal(t.type, 'WAIT')
+  assert.equal(t.inputParameters.duration, 7)
+})
+
+test('onError=continue sets retryCount; stop (default) is 0', () => {
+  const cont = stepToTask({ id: 'a', kind: 'command', command: 'x', onError: 'continue' }, 0, { continueRetryCount: 3 })
+  assert.equal(cont.retryCount, 3)
+  const stop = stepToTask({ id: 'b', kind: 'command', command: 'x' }, 1, {})
+  assert.equal(stop.retryCount, 0)
+})
+
+// ─── rollbackToTask ─────────────────────────────────────────────────────────
+test('rollback command → optional compensating HTTP task', () => {
+  const t = rollbackToTask({ kind: 'command', command: 'no acl' }, 'st_4', 0)
+  assert.equal(t.type, 'HTTP')
+  assert.equal(t.optional, true)
+  assert.equal(t.inputParameters.http_request.body.compensating, true)
+  assert.match(t.taskReferenceName, /^rollback_st_4_/)
+})
+
+test('rollback script → optional compensating SIMPLE task', () => {
+  const t = rollbackToTask({ kind: 'script', scriptId: 'undo' }, 'st_1', 1)
+  assert.equal(t.type, 'SIMPLE')
+  assert.equal(t.inputParameters.scriptId, 'undo')
+  assert.equal(t.optional, true)
+})
+
+// ─── playbookToWorkflowDef: full mapping ────────────────────────────────────
+test('maps all 4 steps + rollback compensating task in order', () => {
+  const def = playbookToWorkflowDef(samplePlaybook, { execUri: 'http://gw:17888/rpc/exec' })
+  assert.equal(def.name, 'nightly_backup')
+  assert.equal(def.version, 1)
+  assert.equal(def.schemaVersion, 2)
+  assert.equal(def.restartable, true)
+  // 4 step tasks + 1 JOIN (st-4 has 2 deps) + 1 rollback = 6
+  const types = def.tasks.map((t) => t.type)
+  assert.equal(types.filter((x) => x === 'JOIN').length, 1, 'one JOIN for the 2-dep step')
+  assert.equal(types.filter((x) => x === 'WAIT').length, 1, 'one WAIT')
+  const rollback = def.tasks[def.tasks.length - 1]
+  assert.equal(rollback.optional, true, 'last task is the compensating rollback')
+  assert.equal(rollback.inputParameters.http_request.body.command, 'no acl')
+})
+
+test('JOIN carries the dependsOn edges (fan-in)', () => {
+  const def = playbookToWorkflowDef(samplePlaybook, {})
+  const join = def.tasks.find((t) => t.type === 'JOIN')
+  assert.deepEqual(join.joinOn, ['st_1', 'st_2'])
+  // the dependent task (st-4) appears after the JOIN in order
+  const joinIdx = def.tasks.indexOf(join)
+  const st4 = def.tasks.find((t) => t.taskReferenceName === 'st_4')
+  assert.ok(def.tasks.indexOf(st4) > joinIdx, 'dependent task comes after its JOIN')
+})
+
+test('linear playbook (no dependsOn) emits no JOINs', () => {
+  const pb = { name: 'linear', steps: [
+    { id: 'a', kind: 'command', command: '1' },
+    { id: 'b', kind: 'command', command: '2' },
+    { id: 'c', kind: 'wait', waitSeconds: 1 },
+  ] }
+  const def = playbookToWorkflowDef(pb, {})
+  assert.equal(def.tasks.filter((t) => t.type === 'JOIN').length, 0)
+  assert.equal(def.tasks.length, 3)
+})
+
+test('multiple rollbacks run in reverse step order (undo newest first)', () => {
+  const pb = { name: 'multi', steps: [
+    { id: 'a', kind: 'command', command: 'a1', rollback: { kind: 'command', command: 'undo-a' } },
+    { id: 'b', kind: 'command', command: 'b1', rollback: { kind: 'command', command: 'undo-b' } },
+  ] }
+  const def = playbookToWorkflowDef(pb, {})
+  const rbs = def.tasks.filter((t) => t.optional)
+  assert.equal(rbs.length, 2)
+  assert.equal(rbs[0].inputParameters.http_request.body.command, 'undo-b', 'newest rollback first')
+  assert.equal(rbs[1].inputParameters.http_request.body.command, 'undo-a')
+})
+
+test('execUri flows into the command tasks + inputTemplate', () => {
+  const def = playbookToWorkflowDef(samplePlaybook, { execUri: 'http://gw:9000/exec' })
+  const cmdTask = def.tasks.find((t) => t.type === 'HTTP')
+  assert.equal(cmdTask.inputParameters.http_request.uri, 'http://gw:9000/exec')
+  assert.equal(def.inputTemplate.rtermExecUri, 'http://gw:9000/exec')
+})
+
+test('rejects a playbook without steps', () => {
+  assert.throws(() => playbookToWorkflowDef({ name: 'x' }), /steps array/)
+  assert.throws(() => playbookToWorkflowDef(null), /steps array/)
+})
+
+// ─── conductorClient: registerWorkflowDef / getWorkflowDef ─────────────────
+test('registerWorkflowDef POSTs an array to /api/metadata/workflow', async () => {
+  const f = mockFetch({ json: {} })
+  const c = new ConductorClient({ fetchImpl: f })
+  const def = playbookToWorkflowDef(samplePlaybook, {})
+  await c.registerWorkflowDef(def)
+  const call = f.calls[0]
+  assert.equal(call.url, `${DEFAULT_BASE_URL}/api/metadata/workflow`)
+  assert.equal(call.init.method, 'POST')
+  const body = JSON.parse(call.init.body)
+  assert.ok(Array.isArray(body), 'body is an array of defs')
+  assert.equal(body[0].name, 'nightly_backup')
+})
+
+test('registerWorkflowDef accepts an array + rejects empty', async () => {
+  const c = new ConductorClient({ fetchImpl: mockFetch({ json: {} }) })
+  await assert.rejects(() => c.registerWorkflowDef(), /WorkflowDef/)
+})
+
+test('getWorkflowDef GETs by name (+version)', async () => {
+  const f = mockFetch({ json: { name: 'x', version: 2 } })
+  const c = new ConductorClient({ fetchImpl: f })
+  await c.getWorkflowDef('nightly_backup', 2)
+  assert.match(f.calls[0].url, /\/api\/metadata\/workflow\/nightly_backup\?version=2$/)
+  await assert.rejects(() => c.getWorkflowDef(), /name/)
+})
+
+// ─── index helpers: findPlaybook / buildDelegateAgentConfig ────────────────
+test('findPlaybook resolves from AutomationManager then settings, by id or name', () => {
+  const pb = { id: 'pb-1', name: 'nightly' }
+  const viaAm = findPlaybook({ automationManager: { getPlaybook: (x) => (x === 'pb-1' ? pb : undefined) } }, 'pb-1')
+  assert.equal(viaAm.name, 'nightly')
+  const viaSettings = findPlaybook({ settings: { automation: { playbooks: [pb] } } }, 'nightly')
+  assert.equal(viaSettings.id, 'pb-1')
+  assert.equal(findPlaybook({ settings: { automation: { playbooks: [] } } }, 'ghost'), undefined)
+  assert.equal(findPlaybook({}, undefined), undefined)
+})
+
+test('buildDelegateAgentConfig builds a valid durable AgentConfig', () => {
+  const c = buildDelegateAgentConfig('mybot', 'do the thing', { model: 'anthropic/claude-sonnet-4.6' })
+  assert.equal(c.name, 'mybot')
+  assert.equal(c.model, 'anthropic/claude-sonnet-4.6')
+  assert.equal(c.input, 'do the thing')
+  const def = buildDelegateAgentConfig(undefined, 't')
+  assert.equal(def.name, 'rterm_delegate')
+  assert.equal(def.model, 'openai/gpt-4o')
+})
+
+// ─── new tools (mocked server) ─────────────────────────────────────────────
+function makeCtx(playbooks, fetchImpl) {
+  const tools = new Map()
+  const triggers = []
+  const panels = []
+  const ctx = {
+    settings: { agentspan: { serverUrl: DEFAULT_BASE_URL }, automation: { playbooks } },
+    registerTool: (t) => tools.set(t.name, t),
+    registerTrigger: (t) => triggers.push(t),
+    registerPanel: (p) => panels.push(p),
+    log: () => {},
+  }
+  return { tools, ctx, fetchImpl }
+}
+
+test('registers 9 tools now (6 phase-1 + 3 phase-2)', () => {
+  const { tools, ctx } = makeCtx([], null)
+  register(ctx)
+  assert.equal(tools.size, 9)
+  for (const n of ['agentspan_export_playbook', 'agentspan_register_playbook', 'agentspan_delegate']) assert.ok(tools.has(n), `missing ${n}`)
+})
+
+test('agentspan_export_playbook returns the mapped def without registering', async () => {
+  const posted = []
+  const realFetch = globalThis.fetch
+  globalThis.fetch = async (url, init) => { posted.push(url); return { ok: true, status: 200, text: async () => '{}' } }
+  const { tools, ctx } = makeCtx([samplePlaybook], null)
+  register(ctx)
+  const r = await tools.get('agentspan_export_playbook').handler({ playbook: 'nightly backup' })
+  assert.equal(r.name, 'nightly_backup')
+  assert.ok(r.taskCount >= 5)
+  assert.ok(r.def.tasks.some((t) => t.type === 'WAIT'))
+  assert.equal(posted.length, 0, 'export is pure — no HTTP calls')
+  const missing = await tools.get('agentspan_export_playbook').handler({ playbook: 'ghost' })
+  assert.match(missing.error, /not found/)
+  globalThis.fetch = realFetch
+})
+
+test('agentspan_register_playbook registers the def on the server', async () => {
+  const calls = []
+  const realFetch = globalThis.fetch
+  globalThis.fetch = async (url, init) => {
+    calls.push({ url, method: init.method })
+    return { ok: true, status: 200, text: async () => '{}' }
+  }
+  const { tools, ctx } = makeCtx([samplePlaybook], null)
+  register(ctx)
+  const r = await tools.get('agentspan_register_playbook').handler({ playbook: 'nightly backup' })
+  assert.equal(r.registered, true)
+  assert.equal(r.name, 'nightly_backup')
+  assert.equal(r.runWith.args.workflow, 'nightly_backup')
+  assert.ok(calls.some((c) => c.url.endsWith('/api/metadata/workflow') && c.method === 'POST'))
+  globalThis.fetch = realFetch
+})
+
+test('agentspan_delegate builds an AgentConfig and returns executionId + followUp', async () => {
+  const realFetch = globalThis.fetch
+  let postedBody
+  globalThis.fetch = async (url, init) => {
+    if (init.method === 'POST') postedBody = JSON.parse(init.body)
+    return { ok: true, status: 200, text: async () => JSON.stringify({ executionId: 'exec-del-1' }) }
+  }
+  const { tools, ctx } = makeCtx([], null)
+  register(ctx)
+  const bad = await tools.get('agentspan_delegate').handler({})
+  assert.match(bad.error, /prompt/)
+  const r = await tools.get('agentspan_delegate').handler({ prompt: 'investigate the disk-full on web-01', model: 'openai/gpt-5.6-sol' })
+  assert.equal(r.delegated, true)
+  assert.equal(r.executionId, 'exec-del-1')
+  assert.match(r.uiUrl, /\/execution\/exec-del-1$/)
+  assert.equal(postedBody.model, 'openai/gpt-5.6-sol')
+  assert.equal(postedBody.input, 'investigate the disk-full on web-01')
+  globalThis.fetch = realFetch
+})