neuralos 2.9.9 → 2.9.11

package/bin/gybackend.cjs

@@ -347146,13 +347146,23 @@ async function manageRecording(args, context2) {
       if (!args.terminalId) {
         out = "start requires terminalId.";
       } else {
-        out = `Recording started: ${r.start(args.terminalId, { title: args.title })}`;
+        const ts = context2.terminalService;
+        const id = ts && typeof ts.startRecording === "function" ? ts.startRecording(args.terminalId, { title: args.title }) : r.start(args.terminalId, { title: args.title });
+        out = `Recording started: ${id}`;
       }
     } else if (args.action === "stop") {
       if (!args.recordingId) {
         out = "stop requires recordingId.";
       } else {
         const rec = r.stop(args.recordingId);
+        try {
+          const ts = context2.terminalService;
+          const termId = rec.terminalId ?? args.terminalId;
+          if (termId && ts?.activeRecordings instanceof Map) {
+            if (ts.activeRecordings.get(termId) === args.recordingId) ts.activeRecordings.delete(termId);
+          }
+        } catch {
+        }
         out = `Recording ${args.recordingId} stopped (${rec.events.length} events).`;
       }
     } else if (args.action === "replay") {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "neuralos",
-  "version": "2.9.9",
-  "description": "neuralOS — the headless AI-native backend for RTerm. run RTerm-as-a-service (AI agent, SSH/WinRM/Serial/local terminals, fleet orchestration, advanced automation, SRE observability, Netdata, AWS APerf, plugin system, governance/audit, Prometheus/OTel metrics export, secrets vault, on-call paging, AI cost budgets, GitOps, cloud inventory, APM/DEM/Infra/ETW ingestion, AgentSpan/Conductor durable-agent bridge). The RTerm desktop app stays RTerm; neuralOS is the standalone backend daemon. Dual-published as rterm-backend. v2.9.9: AgentSpan/Conductor integration — durable, crash-resilient agent execution (agentspan-bridge plugin, 7 plugins total).",
+  "version": "2.9.11",
+  "description": "neuralOS — the headless AI-native backend for RTerm. run RTerm-as-a-service (AI agent, SSH/WinRM/Serial/local terminals, fleet orchestration, advanced automation, SRE observability, Netdata, AWS APerf, plugin system, governance/audit, Prometheus/OTel metrics export, secrets vault, on-call paging, AI cost budgets, GitOps, cloud inventory, APM/DEM/Infra/ETW ingestion, AgentSpan/Conductor durable-agent bridge). The RTerm desktop app stays RTerm; neuralOS is the standalone backend daemon. Dual-published as rterm-backend. v2.9.11: fix — agent-tool session recording now captures (start routed via TerminalService).",
   "main": "bin/gybackend.cjs",
   "bin": {
     "neuralos": "bin/gybackend.cjs",
@@ -63,9 +63,6 @@
     "apm",
     "dem",
     "etw",
-    "agentspan",
-    "conductor",
-    "durable-agents",
     "monitoring"
   ]
 }

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

@@ -203,11 +203,11 @@ function makeCtx(fetchImpl, settings = {}) {
   return { tools, triggers, panels, logs, ctx }
 }
 
-test('register wires 6 tools, 1 trigger, 1 panel', () => {
+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, 6)
-  for (const n of ['agentspan_health', 'agentspan_run', 'agentspan_status', 'agentspan_approve', 'agentspan_list', 'agentspan_stop']) assert.ok(tools.has(n), `missing ${n}`)
+  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)
 })

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
+})

package/plugins/agentspan-bridge/conductorClient.mjs

@@ -161,6 +161,22 @@ export class ConductorClient {
     const q = new URLSearchParams({ freeText: query, size: String(size), sort: 'startTime:DESC' })
     return this.request('GET', `/api/workflow/search?${q}`)
   }
+
+  // ── Metadata (WorkflowDef registration) ──────────────────────────────────
+  /** Register (create/update) a WorkflowDef on the server (POST /api/metadata/workflow).
+   * Accepts a single def or an array (Conductor accepts a JSON array of defs). */
+  async registerWorkflowDef(defOrDefs) {
+    if (!defOrDefs) throw new Error('registerWorkflowDef needs a WorkflowDef')
+    const body = Array.isArray(defOrDefs) ? defOrDefs : [defOrDefs]
+    return this.request('POST', '/api/metadata/workflow', body)
+  }
+
+  /** Get a registered WorkflowDef by name (+ optional version). */
+  async getWorkflowDef(name, version) {
+    if (!name) throw new Error('getWorkflowDef needs a name')
+    const q = version !== undefined ? `?version=${version}` : ''
+    return this.request('GET', `/api/metadata/workflow/${encodeURIComponent(name)}${q}`)
+  }
 }
 
 export default ConductorClient

package/plugins/agentspan-bridge/index.mjs

@@ -21,6 +21,7 @@
  */
 
 import { ConductorClient, DEFAULT_BASE_URL, joinUrl } from './conductorClient.mjs'
+import { playbookToWorkflowDef } from './playbookToWorkflowDef.mjs'
 
 // ─── config resolution ──────────────────────────────────────────────────────
 
@@ -122,6 +123,48 @@ async function guarded(fn, log) {
   }
 }
 
+// ─── playbook resolution (from RTerm AutomationManager / settings) ─────────
+
+/** Find a named RTerm playbook from the plugin context (AutomationManager or
+ * settings.automation.playbooks), by id or name. */
+export function findPlaybook(ctx = {}, nameOrId) {
+  if (!nameOrId) return undefined
+  const want = String(nameOrId)
+  // 1) AutomationManager (runtime handle)
+  try {
+    const am = ctx.automationManager
+    if (am) {
+      if (typeof am.getPlaybook === 'function') {
+        const p = am.getPlaybook(want)
+        if (p) return p
+      }
+      if (typeof am.listPlaybooks === 'function') {
+        const found = (am.listPlaybooks() || []).find((x) => x.id === want || x.name === want)
+        if (found) return found
+      }
+    }
+  } catch { /* fall through to settings */ }
+  // 2) settings.automation.playbooks
+  try {
+    const s = (typeof ctx.getSettings === 'function' ? ctx.getSettings() : ctx.settings) || {}
+    const list = s.automation?.playbooks || []
+    return list.find((x) => x.id === want || x.name === want)
+  } catch {
+    return undefined
+  }
+}
+
+/** Build a default durable AgentConfig for `agentspan_delegate` (a simple
+ * tool-using ReAct agent compiled + started on the server). */
+export function buildDelegateAgentConfig(name, prompt, opts = {}) {
+  return {
+    name: name || 'rterm_delegate',
+    model: opts.model || 'openai/gpt-4o',
+    instructions: opts.instructions || 'You are a durable RTerm delegate agent. Complete the task, calling tools as needed.',
+    input: prompt,
+  }
+}
+
 // ─── plugin entry ───────────────────────────────────────────────────────────
 
 export function register(ctx) {
@@ -238,6 +281,75 @@ export function register(ctx) {
     }, log),
   })
 
+  // Tool: agentspan_export_playbook — map a named RTerm playbook to a Conductor
+  // WorkflowDef (returns the def; does NOT register it). Pure/dry-run preview.
+  registerTool({
+    name: 'agentspan_export_playbook',
+    description: 'Map an RTerm playbook (by id or name) to a Conductor WorkflowDef and return it — a dry-run preview of what agentspan_register_playbook would register. command steps → HTTP run_command tasks, script steps → script-reference tasks, wait steps → WAIT tasks; sequential + dependsOn DAG + retries + rollback compensating tasks.',
+    params: {
+      playbook: { type: 'string', description: 'RTerm playbook id or name' },
+      execUri: { type: 'string', description: 'Override the RTerm exec URI tasks call (default from settings)', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      const pb = findPlaybook(ctx, p?.playbook)
+      if (!pb) return { error: `playbook not found: ${p?.playbook ?? '(none given)'}` }
+      const execUri = p?.execUri || `${config.gatewayUrl ?? 'http://localhost:17888'}/rpc/exec`
+      const def = playbookToWorkflowDef(pb, { execUri })
+      return { name: def.name, taskCount: def.tasks.length, def }
+    }, log),
+  })
+
+  // Tool: agentspan_register_playbook — register an RTerm playbook on the
+  // AgentSpan server as a Conductor WorkflowDef (so agentspan_run {workflow:<name>}
+  // and AgentSpan SUB_WORKFLOW steps can invoke it).
+  registerTool({
+    name: 'agentspan_register_playbook',
+    description: 'Export an RTerm playbook to a Conductor WorkflowDef AND register it on the AgentSpan server (POST /api/metadata/workflow), so it can be run durably via agentspan_run {workflow:<name>} or invoked by AgentSpan agents as a SUB_WORKFLOW step.',
+    params: {
+      playbook: { type: 'string', description: 'RTerm playbook id or name' },
+      execUri: { type: 'string', description: 'Override the RTerm exec URI tasks call (default from settings)', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      const pb = findPlaybook(ctx, p?.playbook)
+      if (!pb) return { error: `playbook not found: ${p?.playbook ?? '(none given)'}` }
+      const execUri = p?.execUri || `${config.gatewayUrl ?? 'http://localhost:17888'}/rpc/exec`
+      const def = playbookToWorkflowDef(pb, { execUri })
+      await client.registerWorkflowDef(def)
+      return {
+        registered: true,
+        name: def.name,
+        taskCount: def.tasks.length,
+        runWith: { tool: 'agentspan_run', args: { workflow: def.name } },
+        uiUrl: joinUrl(config.serverUrl, `/workflowDef/${def.name}`),
+      }
+    }, log),
+  })
+
+  // Tool: agentspan_delegate — run a prompt/task as a durable AgentSpan agent
+  // (AgentConfig), returning an executionId that survives RTerm/host restart.
+  registerTool({
+    name: 'agentspan_delegate',
+    description: 'Delegate a long-running task to AgentSpan: runs the prompt as a durable agent on the Conductor server (compiles + starts an AgentConfig) and returns an executionId that survives restarts. Follow up with agentspan_status / agentspan_approve / agentspan_stop.',
+    params: {
+      prompt: { type: 'string', description: 'The task/prompt for the durable agent' },
+      name: { type: 'string', description: 'Agent name (default rterm_delegate)', optional: true },
+      model: { type: 'string', description: 'Model id (default openai/gpt-4o)', optional: true },
+      instructions: { type: 'string', description: 'Override system instructions', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      if (!p?.prompt) return { error: 'agentspan_delegate needs a prompt' }
+      const cfg = buildDelegateAgentConfig(p.name, p.prompt, { model: p.model, instructions: p.instructions })
+      const r = await client.runAgent(cfg)
+      return {
+        delegated: true,
+        executionId: r.executionId,
+        serverUrl: config.serverUrl,
+        uiUrl: joinUrl(config.serverUrl, `/execution/${r.executionId}`),
+        followUp: { status: 'agentspan_status', approve: 'agentspan_approve', stop: 'agentspan_stop' },
+      }
+    }, log),
+  })
+
   // Trigger: agentspan_execution_failed — fires when a durable execution fails.
   registerTrigger({
     name: 'agentspan_execution_failed',
@@ -272,4 +384,6 @@ export default {
   summarizeStatus,
   toExecutionRows,
   isFailedExecution,
+  findPlaybook,
+  buildDelegateAgentConfig,
 }

package/plugins/agentspan-bridge/playbookToWorkflowDef.mjs

@@ -0,0 +1,209 @@
+/**
+ * playbookToWorkflowDef.mjs — map an RTerm playbook (PlaybookEntry) to a
+ * Netflix-Conductor WorkflowDef so AgentSpan agents can invoke it as a step
+ * (SUB_WORKFLOW) or RTerm can register + run it durably on the Conductor server.
+ *
+ * Pure mapping (no I/O):
+ *   - command step → a run_command-style HTTP task carrying the command + target
+ *   - script step  → an HTTP task that references the saved script id (the
+ *                    Conductor worker resolves the script body by id)
+ *   - wait step    → a Conductor WAIT task (durationSeconds)
+ *   - sequential + dependsOn DAG ordering → Conductor task `taskReferenceName`
+ *     graph with JOIN on multiple dependencies
+ *   - retries (onError=continue → retry, else fail-fast) → Conductor `retryCount`
+ *   - rollback steps → compensating tasks appended after the main flow
+ *
+ * The emitted WorkflowDef is valid for `POST /api/metadata/workflow` on any
+ * Conductor OSS / AgentSpan server.
+ */
+
+/** Sanitize a string into a Conductor-safe taskReferenceName ([A-Za-z0-9_]). */
+export function taskRef(id, fallback) {
+  const s = String(id ?? fallback ?? 'step').replace(/[^A-Za-z0-9_]/g, '_')
+  return s.length > 0 ? s : 'step'
+}
+
+/** Map a single RTerm playbook step to a Conductor task (no edges yet). */
+export function stepToTask(step, index, opts = {}) {
+  const ref = taskRef(step.id ?? `step_${index}`)
+  const name = step.name || ref
+  const base = {
+    name,
+    taskReferenceName: ref,
+    retryCount: step.onError === 'continue' ? (opts.continueRetryCount ?? 0) : 0,
+    startDelay: 0,
+    optional: false,
+    asyncComplete: false,
+  }
+
+  if (step.kind === 'wait') {
+    return {
+      ...base,
+      type: 'WAIT',
+      inputParameters: { duration: step.waitSeconds ?? 0 },
+    }
+  }
+
+  if (step.kind === 'script') {
+    // Reference the saved script by id; the Conductor-side worker resolves the
+    // script body (kept out of the def so it stays compact + secret-free).
+    return {
+      ...base,
+      type: 'SIMPLE',
+      inputParameters: {
+        kind: 'rterm_script',
+        scriptId: step.scriptId,
+        name,
+      },
+    }
+  }
+
+  // kind === 'command' (default): an HTTP task that invokes RTerm's command
+  // execution surface with the command + target scope.
+  return {
+    ...base,
+    type: 'HTTP',
+    inputParameters: {
+      http_request: {
+        uri: opts.execUri ?? '${workflow.input.rtermExecUri}',
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: {
+          kind: 'run_command',
+          command: step.command ?? '',
+          ...(step.validate ? { validate: step.validate } : {}),
+        },
+        connectionTimeOut: opts.connectionTimeOut ?? 5000,
+        readTimeOut: opts.readTimeOut ?? 300000,
+      },
+    },
+  }
+}
+
+/** Map a rollback action to a compensating Conductor task. */
+export function rollbackToTask(rollback, stepRef, index) {
+  const ref = taskRef(`rollback_${stepRef}_${index}`)
+  if (rollback.kind === 'script') {
+    return {
+      name: ref,
+      taskReferenceName: ref,
+      type: 'SIMPLE',
+      inputParameters: { kind: 'rterm_script', scriptId: rollback.scriptId, compensating: true },
+      retryCount: 0,
+      optional: true, // a failing rollback never blocks the workflow result
+      asyncComplete: false,
+    }
+  }
+  return {
+    name: ref,
+    taskReferenceName: ref,
+    type: 'HTTP',
+    inputParameters: {
+      http_request: {
+        uri: '${workflow.input.rtermExecUri}',
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: { kind: 'run_command', command: rollback.command ?? '', compensating: true },
+      },
+    },
+    retryCount: 0,
+    optional: true,
+    asyncComplete: false,
+  }
+}
+
+/**
+ * Build the ordered task list with DAG edges from dependsOn.
+ * Returns { tasks, order } where order is the topological order of step refs.
+ * Steps with no dependsOn depend on the previous step (linear chain). Steps
+ * with multiple dependsOn get a JOIN task.
+ */
+export function buildDag(steps) {
+  const refs = steps.map((s, i) => taskRef(s.id ?? `step_${i}`))
+  const tasks = []
+  const joins = []
+  steps.forEach((s, i) => {
+    const ref = refs[i]
+    const deps = Array.isArray(s.dependsOn) && s.dependsOn.length > 0
+      ? s.dependsOn.map((d) => taskRef(d))
+      : (i === 0 ? [] : [refs[i - 1]])
+    if (deps.length > 1) {
+      const joinRef = taskRef(`join_${ref}`)
+      joins.push({ ref: joinRef, type: 'JOIN', joinOn: deps, taskReferenceName: joinRef, name: joinRef })
+    }
+  })
+  return { refs, joins }
+}
+
+/**
+ * Map a full RTerm playbook to a Conductor WorkflowDef.
+ * @param {object} playbook PlaybookEntry
+ * @param {object} [opts] { execUri, connectionTimeOut, readTimeOut, continueRetryCount }
+ * @returns {object} a Conductor WorkflowDef (POST /api/metadata/workflow)
+ */
+export function playbookToWorkflowDef(playbook, opts = {}) {
+  if (!playbook || !Array.isArray(playbook.steps)) {
+    throw new Error('playbookToWorkflowDef needs a playbook with a steps array')
+  }
+  const name = String(playbook.name || playbook.id || 'rterm_playbook').replace(/\s+/g, '_')
+  const steps = playbook.steps
+  const tasks = []
+  const rollbackTasks = []
+
+  // Main flow: map each step, then wire sequential/DAG ordering by emitting
+  // tasks in dependency order (Conductor executes top-down; dependsOn edges are
+  // expressed via JOINs for fan-in).
+  const refs = steps.map((s, i) => taskRef(s.id ?? `step_${i}`))
+  const emittedJoins = new Set()
+
+  steps.forEach((step, i) => {
+    const ref = refs[i]
+    const task = stepToTask(step, i, opts)
+    // Wire dependency: Conductor's default is sequential task order, but we
+    // explicitly model dependsOn fan-in as a JOIN before this task when the
+    // step has multiple dependencies.
+    const deps = Array.isArray(step.dependsOn) && step.dependsOn.length > 0
+      ? step.dependsOn.map((d) => taskRef(d))
+      : []
+    if (deps.length > 1 && !emittedJoins.has(ref)) {
+      const joinRef = taskRef(`join_${ref}`)
+      tasks.push({
+        name: joinRef,
+        taskReferenceName: joinRef,
+        type: 'JOIN',
+        joinOn: deps,
+      })
+      emittedJoins.add(ref)
+    }
+    tasks.push(task)
+    if (step.rollback) {
+      rollbackTasks.push(rollbackToTask(step.rollback, ref, rollbackTasks.length))
+    }
+  })
+
+  // Compensating (rollback) tasks run after the main flow, in reverse step
+  // order (undo the most recent change first) — marked optional so they never
+  // mask the workflow's real result.
+  const orderedRollback = [...rollbackTasks].reverse()
+
+  return {
+    name,
+    description: playbook.description || `RTerm playbook: ${playbook.name ?? name}`,
+    version: 1,
+    tasks: [...tasks, ...orderedRollback],
+    inputParameters: [],
+    outputParameters: {},
+    schemaVersion: 2,
+    restartable: true,
+    workflowStatusListenerEnabled: false,
+    ownerEmail: 'rterm@hyperspace.ng',
+    timeoutPolicy: 'ALERT_ONLY',
+    timeoutSeconds: 0,
+    variables: {},
+    inputTemplate: {
+      rtermExecUri: opts.execUri ?? 'http://localhost:17888/rpc/exec',
+    },
+  }
+}
+
+export default { playbookToWorkflowDef, stepToTask, rollbackToTask, taskRef, buildDag }

package/plugins/agentspan-bridge/plugin.json

@@ -4,12 +4,15 @@
   "description": "AgentSpan/Conductor bridge for RTerm — run durable, crash-resilient agents and workflows on an AgentSpan (Conductor) server from RTerm. Adds durable agent execution (resume-from-step on crash), plan-execute determinism, enterprise event triggers, and a live execution feed to RTerm's agent + dashboard. Server URL + optional auth are configured in Settings (agentspan block); secrets via the vault.",
   "entry": "index.mjs",
   "tools": [
+    "agentspan_health",
     "agentspan_run",
     "agentspan_status",
     "agentspan_approve",
     "agentspan_list",
     "agentspan_stop",
-    "agentspan_health"
+    "agentspan_export_playbook",
+    "agentspan_register_playbook",
+    "agentspan_delegate"
   ],
   "triggers": [
     "agentspan_execution_failed"