rterm-backend 2.9.8 → 2.9.9

package/bin/gybackend.cjs

@@ -368394,6 +368394,10 @@ var DEFAULT_BACKEND_SETTINGS = {
   cloud: {
     accounts: []
   },
+  agentspan: {
+    serverUrl: "",
+    enabled: true
+  },
   gateway: {
     ws: {
       access: "localhost",
@@ -368449,6 +368453,7 @@ function pickBackendSnapshot(raw) {
     alerts: raw.alerts,
     oncall: raw.oncall,
     cloud: raw.cloud,
+    agentspan: raw.agentspan,
     gateway: raw.gateway,
     layout: raw.layout,
     recursionLimit: raw.recursionLimit,
@@ -368527,6 +368532,7 @@ function normalizeBackendSettings(settings) {
   next.alerts = normalizeAlertsSettings(next.alerts);
   next.oncall = normalizeOncallSettings(next.oncall);
   next.cloud = normalizeCloudSettings(next.cloud);
+  next.agentspan = normalizeAgentspanSettings(next.agentspan);
   next.schemaVersion = BACKEND_SETTINGS_SCHEMA_VERSION;
   return next;
 }
@@ -368689,6 +368695,16 @@ function normalizeCloudSettings(raw) {
   }
   return { accounts };
 }
+function normalizeAgentspanSettings(raw) {
+  const src = isObject5(raw) ? raw : {};
+  const serverUrl = typeof src.serverUrl === "string" ? src.serverUrl.trim() : "";
+  const authSecretRef = typeof src.authSecretRef === "string" && src.authSecretRef.trim() ? src.authSecretRef.trim() : void 0;
+  return {
+    ...serverUrl ? { serverUrl } : {},
+    ...authSecretRef ? { authSecretRef } : {},
+    enabled: src.enabled !== false
+  };
+}
 function migrateBackendToV3(settings) {
   const next = { ...settings };
   delete next.language;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rterm-backend",
-  "version": "2.9.8",
-  "description": "rterm-backend \u2014 the headless AI-native backend for RTerm (dual-published as neuralOS). 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). The RTerm desktop app stays RTerm; neuralOS is the standalone backend daemon. Dual-published as rterm-backend. v2.9.8: backend typecheck fully green (ESM-safe native loaders for node-pty/ssh2) + release notes generated from CHANGELOG.",
+  "version": "2.9.9",
+  "description": "rterm-backend \u2014 the headless AI-native backend for RTerm (dual-published as neuralOS). 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 \u2014 durable, crash-resilient agent execution (agentspan-bridge plugin, 7 plugins total).",
   "main": "bin/gybackend.cjs",
   "bin": {
     "gybackend": "bin/gybackend.cjs",
@@ -64,6 +64,9 @@
     "apm",
     "dem",
     "etw",
+    "agentspan",
+    "conductor",
+    "durable-agents",
     "monitoring"
   ]
 }

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 6 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(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/conductorClient.mjs

@@ -0,0 +1,166 @@
+/**
+ * conductorClient.mjs — a minimal, dependency-free HTTP client for the
+ * AgentSpan / Netflix-Conductor REST API.
+ *
+ * AgentSpan server runs on Conductor (default http://localhost:6767) and
+ * exposes both its own `/api/agent/*` lifecycle surface and Conductor's
+ * `/api/workflow/*` engine surface. This client is pure + injectable (a
+ * `fetchImpl` is passed in) so it is fully unit-testable offline and has no
+ * runtime network dependency baked in — the plugin wires the real `fetch`.
+ *
+ * Auth: AgentSpan standalone auth uses X-Auth-Key / X-Auth-Secret headers
+ * (AGENTSPAN_AUTH_KEY / AGENTSPAN_AUTH_SECRET). Conductor OSS uses no auth by
+ * default. The client sends the headers only when both are provided.
+ */
+
+export const DEFAULT_BASE_URL = 'http://localhost:6767'
+
+/** Build the auth headers for a request (only when both key+secret are set). */
+export function authHeaders(auth) {
+  const h = { 'content-type': 'application/json', accept: 'application/json' }
+  if (auth && auth.key && auth.secret) {
+    h['X-Auth-Key'] = auth.key
+    h['X-Auth-Secret'] = auth.secret
+  }
+  return h
+}
+
+/** Join a base URL + path safely (single slash). */
+export function joinUrl(base, path) {
+  const b = String(base || DEFAULT_BASE_URL).replace(/\/+$/, '')
+  const p = String(path || '').startsWith('/') ? String(path) : `/${path}`
+  return `${b}${p}`
+}
+
+/** Parse a response body as JSON when possible, else return raw text. */
+async function parseBody(res) {
+  const text = await res.text()
+  if (!text) return null
+  try { return JSON.parse(text) } catch { return text }
+}
+
+export class ConductorApiError extends Error {
+  constructor(status, path, body) {
+    super(`conductor ${status} ${path}: ${typeof body === 'string' ? body.slice(0, 300) : JSON.stringify(body)?.slice(0, 300)}`)
+    this.status = status
+    this.path = path
+    this.body = body
+  }
+}
+
+export class ConductorClient {
+  /**
+   * @param {{ baseUrl?: string, auth?: {key?:string, secret?:string}, fetchImpl: Function }} opts
+   *   fetchImpl(url, {method, headers, body}) -> Promise<{ok,status,text:()=>Promise<string>}>
+   */
+  constructor(opts = {}) {
+    if (typeof opts.fetchImpl !== 'function') throw new Error('ConductorClient needs a fetchImpl')
+    this.baseUrl = opts.baseUrl || DEFAULT_BASE_URL
+    this.auth = opts.auth
+    this.fetchImpl = opts.fetchImpl
+  }
+
+  async request(method, path, body) {
+    const url = joinUrl(this.baseUrl, path)
+    const res = await this.fetchImpl(url, {
+      method,
+      headers: authHeaders(this.auth),
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    })
+    const parsed = await parseBody(res)
+    if (!res.ok) throw new ConductorApiError(res.status, `${method} ${path}`, parsed)
+    return parsed
+  }
+
+  // ── Health ────────────────────────────────────────────────────────────────
+  /** AgentSpan/Conductor health (Spring Actuator). */
+  async health() {
+    try {
+      const r = await this.request('GET', '/actuator/health')
+      return { ok: true, status: r?.status ?? 'UP', raw: r }
+    } catch (e) {
+      return { ok: false, status: 'DOWN', error: e.message }
+    }
+  }
+
+  // ── Agent lifecycle (AgentSpan /api/agent) ───────────────────────────────
+  /** Compile + register + start an agent from an AgentConfig; returns { executionId }. */
+  async runAgent(agentConfig, prompt) {
+    const body = prompt !== undefined ? { agent: agentConfig, input: prompt } : agentConfig
+    const r = await this.request('POST', '/api/agent/start', body)
+    return { executionId: r?.executionId ?? r?.workflowId ?? r?.id ?? null, raw: r }
+  }
+
+  /** Compile only (returns the WorkflowDef without executing). */
+  async compileAgent(agentConfig) {
+    return this.request('POST', '/api/agent/compile', agentConfig)
+  }
+
+  /** Detailed status of a running/finished execution. */
+  async agentStatus(executionId) {
+    if (!executionId) throw new Error('agentStatus needs an executionId')
+    return this.request('GET', `/api/agent/${encodeURIComponent(executionId)}`)
+  }
+
+  /** Human-in-the-loop respond: complete a paused HUMAN task + resume. */
+  async agentRespond(executionId, output) {
+    if (!executionId) throw new Error('agentRespond needs an executionId')
+    return this.request('POST', `/api/agent/${encodeURIComponent(executionId)}/respond`, output ?? {})
+  }
+
+  /** Stop (cancel) an execution. */
+  async agentStop(executionId) {
+    if (!executionId) throw new Error('agentStop needs an executionId')
+    return this.request('POST', `/api/agent/${encodeURIComponent(executionId)}/stop`, {})
+  }
+
+  /** Server-sent event log for an execution. */
+  async agentEvents(executionId) {
+    if (!executionId) throw new Error('agentEvents needs an executionId')
+    return this.request('GET', `/api/agent/events/${encodeURIComponent(executionId)}`)
+  }
+
+  /** List agent definitions registered on the server. */
+  async listAgentDefinitions() {
+    return this.request('GET', '/api/agent/definitions')
+  }
+
+  // ── Workflow engine (Conductor /api/workflow) ────────────────────────────
+  /** Start a named Conductor workflow; returns the workflowId string. */
+  async startWorkflow(name, input, opts = {}) {
+    if (!name) throw new Error('startWorkflow needs a workflow name')
+    const q = new URLSearchParams()
+    if (opts.version !== undefined) q.set('version', String(opts.version))
+    if (opts.correlationId) q.set('correlationId', String(opts.correlationId))
+    const path = `/api/workflow/${encodeURIComponent(name)}${q.size ? `?${q}` : ''}`
+    const r = await this.request('POST', path, input ?? {})
+    return typeof r === 'string' ? r : (r?.workflowId ?? r?.id ?? null)
+  }
+
+  /** Get a workflow execution (status + tasks). */
+  async getWorkflow(workflowId, includeTasks = true) {
+    if (!workflowId) throw new Error('getWorkflow needs a workflowId')
+    return this.request('GET', `/api/workflow/${encodeURIComponent(workflowId)}?includeTasks=${includeTasks}`)
+  }
+
+  /** Terminate a workflow execution. */
+  async terminateWorkflow(workflowId, reason) {
+    if (!workflowId) throw new Error('terminateWorkflow needs a workflowId')
+    const q = reason ? `?reason=${encodeURIComponent(reason)}` : ''
+    return this.request('DELETE', `/api/workflow/${encodeURIComponent(workflowId)}${q}`)
+  }
+
+  /** Retry a failed workflow from the last failed task (durable resume). */
+  async retryWorkflow(workflowId) {
+    if (!workflowId) throw new Error('retryWorkflow needs a workflowId')
+    return this.request('POST', `/api/workflow/${encodeURIComponent(workflowId)}/retry`, {})
+  }
+
+  /** Search workflow executions (freeText query, e.g. status:FAILED). */
+  async searchWorkflows(query = '*', size = 20) {
+    const q = new URLSearchParams({ freeText: query, size: String(size), sort: 'startTime:DESC' })
+    return this.request('GET', `/api/workflow/search?${q}`)
+  }
+}
+
+export default ConductorClient

package/plugins/agentspan-bridge/index.mjs

@@ -0,0 +1,275 @@
+/**
+ * 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'
+
+// ─── 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.' }
+  }
+}
+
+// ─── 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),
+  })
+
+  // 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,
+}

package/plugins/agentspan-bridge/plugin.json

@@ -0,0 +1,24 @@
+{
+  "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_run",
+    "agentspan_status",
+    "agentspan_approve",
+    "agentspan_list",
+    "agentspan_stop",
+    "agentspan_health"
+  ],
+  "triggers": [
+    "agentspan_execution_failed"
+  ],
+  "panels": [
+    "agentspan-executions"
+  ],
+  "permissions": [
+    "exec",
+    "readLedger:metrics"
+  ]
+}