rterm-backend 2.9.8 → 2.9.10

package/plugins/agentspan-bridge/index.mjs

@@ -0,0 +1,389 @@
+/**
+ * agentspan-bridge plugin — run durable, crash-resilient agents + workflows on
+ * an AgentSpan (Netflix Conductor) server from RTerm.
+ *
+ * What this adds that RTerm doesn't already have:
+ *   - Durable agent execution: a crashed/restarted run resumes from the last
+ *     completed step (Conductor engine), not just a ledger entry.
+ *   - Plan-execute determinism (LLM plans once → immutable sub-workflow).
+ *   - Enterprise event triggers (Kafka/SQS/AMQP/DB) via the Conductor server.
+ *   - A live visual execution UI (served by the AgentSpan server).
+ *
+ * Config (Settings → agentspan block, resolved here from the RTerm settings
+ * service via ctx.settings if present, else env):
+ *   serverUrl   — e.g. http://localhost:6767 (default)
+ *   authSecretRef — vault key holding "AUTH_KEY=...\nAUTH_SECRET=..." (optional;
+ *                   only needed when the AgentSpan server has standalone auth on)
+ *
+ * The client is dependency-free (conductorClient.mjs) and the plugin never
+ * crashes RTerm when the AgentSpan server is down — every tool returns a clear
+ * "server unreachable" result instead of throwing.
+ */
+
+import { ConductorClient, DEFAULT_BASE_URL, joinUrl } from './conductorClient.mjs'
+import { playbookToWorkflowDef } from './playbookToWorkflowDef.mjs'
+
+// ─── config resolution ──────────────────────────────────────────────────────
+
+/** Read the agentspan config block from RTerm settings (ctx.settings) or env. */
+export function resolveConfig(ctx = {}, env = process.env) {
+  const s = (typeof ctx.getSettings === 'function' ? ctx.getSettings() : ctx.settings) || {}
+  const block = s.agentspan || {}
+  return {
+    serverUrl: (block.serverUrl || env.AGENTSPAN_SERVER_URL || DEFAULT_BASE_URL).replace(/\/+$/, ''),
+    authSecretRef: block.authSecretRef || env.AGENTSPAN_AUTH_SECRET_REF || undefined,
+    enabled: block.enabled !== false,
+  }
+}
+
+/** Parse a vault "KEY=VAL" blob into an {key, secret} auth object. */
+export function parseAuthBlob(blob) {
+  if (!blob || typeof blob !== 'string') return undefined
+  const out = {}
+  for (const line of blob.split(/\r?\n/)) {
+    const m = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line)
+    if (m) out[m[1]] = m[2].trim()
+  }
+  const key = out.AGENTSPAN_AUTH_KEY || out.AUTH_KEY || out.KEY
+  const secret = out.AGENTSPAN_AUTH_SECRET || out.AUTH_SECRET || out.SECRET
+  return key && secret ? { key, secret } : undefined
+}
+
+/** Real fetch adapter (matches conductorClient's expected {ok,status,text}). */
+async function realFetch(url, init) {
+  const res = await fetch(url, { method: init.method, headers: init.headers, body: init.body })
+  return { ok: res.ok, status: res.status, text: () => res.text() }
+}
+
+/** Build a configured ConductorClient from ctx (settings + vault). */
+export function buildClient(ctx = {}, fetchImpl = realFetch) {
+  const cfg = resolveConfig(ctx)
+  let auth
+  if (cfg.authSecretRef && typeof ctx.getSecret === 'function') {
+    try {
+      const blob = ctx.getSecret(cfg.authSecretRef)
+      auth = parseAuthBlob(blob)
+    } catch { auth = undefined }
+  }
+  return { client: new ConductorClient({ baseUrl: cfg.serverUrl, auth, fetchImpl }), config: cfg }
+}
+
+// ─── formatting helpers (pure) ─────────────────────────────────────────────
+
+/** Normalize an execution/workflow status payload into a compact summary. */
+export function summarizeStatus(payload) {
+  if (!payload || typeof payload !== 'object') return { status: 'UNKNOWN' }
+  const status = payload.status ?? payload.workflowStatus ?? payload.state ?? 'UNKNOWN'
+  const name = payload.workflowName ?? payload.name ?? payload.agentName ?? payload.workflowType
+  const id = payload.workflowId ?? payload.executionId ?? payload.id
+  const tasks = Array.isArray(payload.tasks) ? payload.tasks : []
+  const failed = tasks.filter((t) => String(t.status).toUpperCase().includes('FAIL')).length
+  const done = tasks.filter((t) => String(t.status).toUpperCase() === 'COMPLETED').length
+  return {
+    id,
+    name,
+    status: String(status).toUpperCase(),
+    taskCount: tasks.length,
+    completedTasks: done,
+    failedTasks: failed,
+    startTime: payload.startTime ?? payload.createTime,
+    endTime: payload.endTime ?? payload.updateTime,
+    reason: payload.reasonForIncompletion ?? payload.failedReason,
+  }
+}
+
+/** Normalize a search/list result into rows for the panel + agentspan_list. */
+export function toExecutionRows(payload) {
+  const results = payload?.results ?? payload?.workflows ?? (Array.isArray(payload) ? payload : [])
+  if (!Array.isArray(results)) return []
+  return results.map((w) => ({
+    id: w.workflowId ?? w.executionId ?? w.id,
+    name: w.workflowName ?? w.name ?? w.workflowType,
+    status: String(w.status ?? w.workflowStatus ?? '').toUpperCase(),
+    startTime: w.startTime ?? w.createTime,
+    endTime: w.endTime ?? w.updateTime,
+  }))
+}
+
+/** Map an execution status to a trigger event (fires on FAILED). */
+export function isFailedExecution(status) {
+  const s = String(status || '').toUpperCase()
+  return s === 'FAILED' || s === 'TERMINATED' || s === 'TIMED_OUT'
+}
+
+// ─── unreachable-server helper ─────────────────────────────────────────────
+
+async function guarded(fn, log) {
+  try {
+    return await fn()
+  } catch (e) {
+    const msg = e?.message ?? String(e)
+    log?.(`[agentspan] ${msg}`)
+    return { error: msg, hint: 'Is the AgentSpan server running? (agentspan server start, default http://localhost:6767). Configure the URL in Settings → agentspan.' }
+  }
+}
+
+// ─── 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) {
+  const { registerTool, registerTrigger, registerPanel, log } = ctx
+  const { client, config } = buildClient(ctx)
+
+  // Tool: agentspan_health — check the server is reachable + its status.
+  registerTool({
+    name: 'agentspan_health',
+    description: 'Check whether the AgentSpan/Conductor server is reachable and healthy. Returns the server URL, health status, and whether auth is configured.',
+    params: {},
+    handler: async () => guarded(async () => {
+      const h = await client.health()
+      if (!h.ok) {
+        return {
+          serverUrl: config.serverUrl,
+          authConfigured: Boolean(config.authSecretRef),
+          ...h,
+          hint: 'Is the AgentSpan server running? (agentspan server start, default http://localhost:6767). Configure the URL in Settings → agentspan.',
+        }
+      }
+      return { serverUrl: config.serverUrl, authConfigured: Boolean(config.authSecretRef), ...h }
+    }, log),
+  })
+
+  // Tool: agentspan_run — run a durable agent (AgentConfig) or named workflow.
+  registerTool({
+    name: 'agentspan_run',
+    description: 'Start a durable, crash-resilient agent or workflow on the AgentSpan server. Pass either an `agentConfig` (compiled+started via /api/agent/start) or a `workflow` name (Conductor /api/workflow/{name}). Returns the executionId/workflowId — the run survives process restarts and resumes from the last completed step.',
+    params: {
+      agentConfig: { type: 'object', description: 'An AgentConfig JSON (agent tree) to compile+run durably', optional: true },
+      workflow: { type: 'string', description: 'Name of a registered Conductor workflow to start', optional: true },
+      input: { type: 'object', description: 'Input payload for the agent/workflow', optional: true },
+      prompt: { type: 'string', description: 'Natural-language prompt for the agent', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      if (p?.agentConfig) {
+        const r = await client.runAgent(p.agentConfig, p.prompt ?? p.input)
+        return { kind: 'agent', executionId: r.executionId, serverUrl: config.serverUrl, uiUrl: joinUrl(config.serverUrl, `/execution/${r.executionId}`), raw: r.raw }
+      }
+      if (p?.workflow) {
+        const id = await client.startWorkflow(p.workflow, p.input ?? {})
+        return { kind: 'workflow', workflowId: id, serverUrl: config.serverUrl, uiUrl: joinUrl(config.serverUrl, `/execution/${id}`) }
+      }
+      return { error: 'agentspan_run needs either agentConfig or workflow' }
+    }, log),
+  })
+
+  // Tool: agentspan_status — detailed status of an execution/workflow.
+  registerTool({
+    name: 'agentspan_status',
+    description: 'Get the detailed status of a durable execution (agent or workflow) by id — current status, per-task progress, failed tasks, and failure reason if any.',
+    params: { executionId: { type: 'string', description: 'The executionId or workflowId' } },
+    handler: async (p) => guarded(async () => {
+      if (!p?.executionId) return { error: 'agentspan_status needs executionId' }
+      // Try the agent lifecycle surface first, fall back to the workflow engine.
+      try {
+        const a = await client.agentStatus(p.executionId)
+        return { kind: 'agent', ...summarizeStatus(a), raw: a }
+      } catch {
+        const w = await client.getWorkflow(p.executionId)
+        return { kind: 'workflow', ...summarizeStatus(w) }
+      }
+    }, log),
+  })
+
+  // Tool: agentspan_approve — human-in-the-loop respond to a paused HUMAN task.
+  registerTool({
+    name: 'agentspan_approve',
+    description: 'Respond to a paused human-in-the-loop task in a durable execution (completes the HUMAN task and resumes the run). Pass the executionId and an `output` object (e.g. {approved:true, comment:"..."}).',
+    params: {
+      executionId: { type: 'string', description: 'The executionId with a paused HUMAN task' },
+      output: { type: 'object', description: 'The response output map (e.g. {approved:true})' },
+    },
+    handler: async (p) => guarded(async () => {
+      if (!p?.executionId) return { error: 'agentspan_approve needs executionId' }
+      await client.agentRespond(p.executionId, p.output ?? {})
+      const s = await client.agentStatus(p.executionId).catch(() => null)
+      return { responded: true, executionId: p.executionId, ...(s ? summarizeStatus(s) : {}) }
+    }, log),
+  })
+
+  // Tool: agentspan_list — list recent executions (optionally filtered).
+  registerTool({
+    name: 'agentspan_list',
+    description: 'List recent durable executions on the AgentSpan server. Optional `query` (Conductor freeText, e.g. "status:FAILED" or "workflowName:cleanup") and `size`. Returns id/name/status/start/end rows.',
+    params: {
+      query: { type: 'string', description: 'Conductor freeText query (default *)', optional: true },
+      size: { type: 'number', description: 'Max results (default 20)', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      const r = await client.searchWorkflows(p?.query ?? '*', p?.size ?? 20)
+      const rows = toExecutionRows(r)
+      return { count: rows.length, executions: rows }
+    }, log),
+  })
+
+  // Tool: agentspan_stop — terminate a running execution.
+  registerTool({
+    name: 'agentspan_stop',
+    description: 'Stop (terminate) a running durable execution by id. Optionally pass a `reason`.',
+    params: {
+      executionId: { type: 'string', description: 'The executionId/workflowId to stop' },
+      reason: { type: 'string', description: 'Optional termination reason', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      if (!p?.executionId) return { error: 'agentspan_stop needs executionId' }
+      try {
+        await client.agentStop(p.executionId)
+      } catch {
+        await client.terminateWorkflow(p.executionId, p.reason)
+      }
+      return { stopped: true, executionId: p.executionId }
+    }, 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',
+    description: 'Fires when an AgentSpan/Conductor durable execution transitions to FAILED/TERMINATED/TIMED_OUT. Use for auto-remediation or re-run playbooks.',
+    match: (event) => {
+      if (event?.source !== 'agentspan') return false
+      return isFailedExecution(event.status)
+    },
+    action: 'propose-change',
+  })
+
+  // Panel: agentspan-executions — live feed of durable executions.
+  registerPanel({
+    name: 'agentspan-executions',
+    title: 'AgentSpan Executions',
+    render: (data) => {
+      const rows = (Array.isArray(data) ? data : []).map((e) =>
+        `<tr><td>${e.name ?? ''}</td><td>${e.id ?? ''}</td><td>${e.status ?? ''}</td><td>${e.startTime ?? ''}</td></tr>`
+      ).join('')
+      return `<div class="agentspan-executions"><h3>AgentSpan Durable Executions</h3><p>Server: ${config.serverUrl}</p><table><thead><tr><th>Name</th><th>Execution</th><th>Status</th><th>Started</th></tr></thead><tbody>${rows}</tbody></table></div>`
+    },
+  })
+
+  log(`[agentspan] agentspan-bridge registered: 6 tools, 1 trigger, 1 panel (server=${config.serverUrl})`)
+}
+
+export default {
+  register,
+  resolveConfig,
+  parseAuthBlob,
+  buildClient,
+  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

@@ -0,0 +1,27 @@
+{
+  "name": "agentspan-bridge",
+  "version": "1.0.0",
+  "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_export_playbook",
+    "agentspan_register_playbook",
+    "agentspan_delegate"
+  ],
+  "triggers": [
+    "agentspan_execution_failed"
+  ],
+  "panels": [
+    "agentspan-executions"
+  ],
+  "permissions": [
+    "exec",
+    "readLedger:metrics"
+  ]
+}