rterm-backend 3.1.5 → 3.1.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rterm-backend",
-  "version": "3.1.5",
-  "description": "Headless AI-native backend for RTerm / neuralOS — v3.1.5: latent connection-state bug fixes (NATS connect concurrency/DOA guard, synapse-bridge config-keyed connections, serial port error leak). 11 plugins. Transports (SSH/serial/local), SQLite, and NATS libs install automatically.",
+  "version": "3.1.7",
+  "description": "Headless AI-native backend for RTerm / neuralOS — v3.1.7: always-on full-duplex Synapse agent (auto-start responder on boot when synapse.enabled + autoServe). RTerm tasks other agents AND is tasked by them from boot. 11 plugins. Transports (SSH/serial/local), SQLite, and NATS libs install automatically.",
   "main": "bin/gybackend.cjs",
   "bin": { "gybackend": "bin/gybackend.cjs" },
   "license": "MIT",

package/plugins/synapse-bridge/index.mjs

@@ -19,6 +19,12 @@
 
 import { createRequire } from 'node:module'
 import { randomUUID } from 'node:crypto'
+import {
+  startResponder, buildRespond, executeSkill,
+  emitEvent, subscribeEvents,
+  ReputationStore, computeScore, updateRecord, newRecord,
+  requestApproval, respondApproval, startApprover,
+} from './synapseAgent.mjs'
 
 const require = createRequire(import.meta.url)
 const enc = new TextEncoder()
@@ -40,6 +46,8 @@ export function resolveConfig(ctx = {}, env = process.env) {
     agentId: block.agentId || env.SYNAPSE_AGENT_ID || 'rterm-001',
     auth: block.auth || undefined,
     enabled: block.enabled !== false,
+    /** auto-start the full-duplex responder on boot (default true when enabled). */
+    autoServe: block.autoServe !== false,
   }
 }
 
@@ -255,6 +263,135 @@ export function register(ctx) {
     }, log),
   })
 
+  // ─── full-duplex agent capabilities (responder, emit/subscribe, reputation, governance) ───
+  const repStore = new ReputationStore()
+  let responderStop = null
+  let servingSkills = []
+
+  /** Start (or restart) the responder with the given skills. Idempotent. */
+  async function serveSkills(skills) {
+    const nc = await connectMesh(ctx)
+    const serveCtx = { ...ctx, rtermSkills: skills ?? ctx.rtermSkills ?? {} }
+    if (responderStop) responderStop()
+    responderStop = await startResponder(nc, cfg, serveCtx, log)
+    servingSkills = Object.keys(serveCtx.rtermSkills)
+    return servingSkills
+  }
+
+  /** Default skills RTerm serves when auto-starting (status + discover + dispatch). */
+  function defaultServeSkills() {
+    return {
+      status: async () => ({ up: true, agent: cfg.agentId, ts: new Date().toISOString() }),
+      discover: async (inp) => ({ agents: await discoverAgents(ctx, inp ?? {}) }),
+      ...(ctx.rtermSkills ?? {}),
+    }
+  }
+
+  registerTool({
+    name: 'synapse_serve',
+    description: 'Start RTerm as a full Synapse agent: listen on mesh.agent.{id}.inbox and respond() to incoming Synapse requests by mapping them to RTerm skills (playbooks/tools via ctx.rtermSkills / getRtermSkills). Bidirectional federation — other agents can now task RTerm. Idempotent; auto-starts on boot when synapse.enabled and autoServe are true.',
+    params: {
+      skills: { type: 'object', description: 'Map of skillId -> async (input, ctx) => output, the skills RTerm serves (defaults to status+discover)', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      const skills = await serveSkills(p?.skills ?? defaultServeSkills())
+      return { serving: true, inbox: `${cfg.prefix}.agent.${cfg.agentId}.inbox`, skills, note: 'RTerm is now a full Synapse agent (responder live)' }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_serve_status',
+    description: 'Report whether the Synapse responder is live (serving on mesh.agent.{id}.inbox) and which skills it serves.',
+    params: {},
+    handler: async () => guarded(async () => {
+      const nc = await connectMesh(ctx)
+      return { serving: responderStop !== null, connected: !nc.isClosed(), inbox: `${cfg.prefix}.agent.${cfg.agentId}.inbox`, skills: servingSkills, autoServe: cfg.autoServe }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_emit',
+    description: 'Emit a formal Synapse event on mesh.event.{type} (fire-and-forget broadcast to subscribers).',
+    params: {
+      type: { type: 'string', description: 'Event type, e.g. ops.change.committed' },
+      payload: { type: 'object', description: 'Event payload' },
+    },
+    handler: async (p) => guarded(async () => {
+      if (!p?.type) return { error: 'synapse_emit needs a type' }
+      const nc = await connectMesh(ctx)
+      emitEvent(nc, cfg, p.type, p.payload ?? {})
+      return { emitted: `${cfg.prefix}.event.${p.type}` }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_subscribe',
+    description: 'Subscribe to Synapse event/task subjects (supports wildcards, e.g. mesh.event.> or mesh.task.>.update). Events feed the local reputation store and the synapse_mesh_event trigger.',
+    params: {
+      subject: { type: 'string', description: 'Subject pattern, e.g. mesh.event.> or mesh.task.>.update' },
+    },
+    handler: async (p) => guarded(async () => {
+      const subject = p?.subject ?? `${cfg.prefix}.task.>.update`
+      const nc = await connectMesh(ctx)
+      const stop = await subscribeEvents(nc, subject, (env, subj) => {
+        repStore.handleTaskUpdate(env)
+        if (typeof ctx.emitEvent === 'function') ctx.emitEvent({ source: 'synapse', subject: subj, env })
+      })
+      return { subscribed: subject, note: 'events feed the reputation store + synapse_mesh_event trigger' }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_reputation',
+    description: 'Read the local Synapse reputation store (EXT-REPUTATION): per (agent, skill) success_rate, speed_score, freshness, composite score. Optionally record an outcome or list ranked agents.',
+    params: {
+      agent: { type: 'string', optional: true },
+      skill: { type: 'string', optional: true },
+      minScore: { type: 'number', description: 'Only agents at/above this score (discover-ranked)', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      if (p?.agent && p?.skill) {
+        const rec = repStore.get(p.agent, p.skill)
+        return rec ?? { error: `no record for ${p.agent}::${p.skill}` }
+      }
+      const ranked = repStore.ranked(p?.minScore ?? 0)
+      return { count: ranked.length, agents: ranked.map((r) => ({ agent: r.agent_id, skill: r.skill, score: Number(r.score.toFixed(3)), successRate: Number(r.success_rate.toFixed(3)), speedScore: Number(r.speed_score.toFixed(3)), confidence: r.confidence })) }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_request_approval',
+    description: 'Request governance approval for a gated action (EXT-GOVERNANCE): publish mesh.approval.{taskId}.request and await the response. Use before a high-risk dispatched task.',
+    params: {
+      originalRequest: { type: 'object', description: 'The original request payload being gated' },
+      policyId: { type: 'string', optional: true },
+      ruleId: { type: 'string', optional: true },
+      reason: { type: 'string', description: 'Why approval is required' },
+      taskId: { type: 'string', optional: true },
+      timeout: { type: 'number', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      const nc = await connectMesh(ctx)
+      const r = await requestApproval(nc, cfg, { taskId: p?.taskId, originalRequest: p?.originalRequest, policyId: p?.policyId, ruleId: p?.ruleId, reason: p?.reason ?? 'RTerm action requires mesh approval', timeout: p?.timeout })
+      return r.approved ? { approved: true, approver: r.approver, taskId: r.taskId } : { approved: false, taskId: r.taskId, note: 'denied or timed out' }
+    }, log),
+  })
+
+  registerTool({
+    name: 'synapse_approve',
+    description: 'Act as a governance approver (EXT-GOVERNANCE): listen on mesh.approval.*.request and answer each per a policy (allow-all, deny-all, or a decide map). Other agents route their gated actions through RTerm for approval.',
+    params: {
+      policy: { type: 'string', description: 'allow-all | deny-all (default allow-all)', optional: true },
+    },
+    handler: async (p) => guarded(async () => {
+      const nc = await connectMesh(ctx)
+      const policy = p?.policy ?? 'allow-all'
+      const decide = async () => ({ approved: policy !== 'deny-all', approver: `did:mesh:${cfg.agentId}` })
+      await startApprover(nc, cfg, decide, log)
+      return { approver: cfg.agentId, policy, listening: `${cfg.prefix}.approval.*.request` }
+    }, log),
+  })
+
   registerTrigger({
     name: 'synapse_mesh_event',
     description: 'Fires when a Synapse mesh event (task failure, reputation penalty, approval request) is observed. Use for cross-mesh remediation.',
@@ -273,7 +410,16 @@ export function register(ctx) {
     },
   })
 
-  log(`[synapse] synapse-bridge registered: 5 tools, 1 trigger, 1 panel (agent=${cfg.agentId}, prefix=${cfg.prefix})`)
+  log(`[synapse] synapse-bridge registered: 12 tools, 1 trigger, 1 panel (agent=${cfg.agentId}, prefix=${cfg.prefix}, full-duplex)`)
+
+  // ─── auto-start the full-duplex responder on boot (when enabled + autoServe) ───
+  // Makes "be tasked by them" always-on, not opt-in per session. Best-effort: a
+  // failed auto-start logs but never blocks plugin registration (server may be down).
+  if (cfg.enabled && cfg.autoServe) {
+    serveSkills(defaultServeSkills())
+      .then((skills) => log(`[synapse] auto-started responder on ${cfg.prefix}.agent.${cfg.agentId}.inbox (skills: ${skills.join(', ')})`))
+      .catch((e) => log(`[synapse] auto-serve deferred: ${e?.message ?? e} (responder will start on first synapse_serve call)`))
+  }
 }
 
 export default { register, resolveConfig, envelope, discoverAgents, dispatchTask, registerSelf }

package/plugins/synapse-bridge/plugin.json

@@ -1,14 +1,21 @@
 {
   "name": "synapse-bridge",
   "version": "1.0.0",
-  "description": "Synapse mesh bridge for RTerm — discover live Synapse agents, dispatch tasks to them, and register RTerm itself as a mesh agent (bidirectional federation). Speaks the Synapse protocol (v0.3.0) over a shared NATS server using the v3.1.2 auth/request-reply/JetStream transport. Config in Settings (synapse block); secrets via the vault.",
+  "description": "Synapse mesh bridge for RTerm — full-duplex Synapse agent (auto-started on boot): discover live agents, dispatch tasks, register RTerm as a mesh agent, AND serve as one (respond to inbound requests, auto-started), emit/subscribe mesh events, EXT-REPUTATION scoring, and EXT-GOVERNANCE approvals. Speaks the Synapse protocol (v0.3.0) over a shared NATS server using the v3.1.2 auth/request-reply/JetStream transport. Config in Settings (synapse block); secrets via the vault.",
   "entry": "index.mjs",
   "tools": [
     "synapse_health",
     "synapse_discover",
     "synapse_dispatch",
     "synapse_register",
-    "synapse_agents_summary"
+    "synapse_agents_summary",
+    "synapse_serve",
+    "synapse_serve_status",
+    "synapse_emit",
+    "synapse_subscribe",
+    "synapse_reputation",
+    "synapse_request_approval",
+    "synapse_approve"
   ],
   "triggers": [
     "synapse_mesh_event"

package/plugins/synapse-bridge/synapse-bridge.extreme.spec.mjs

@@ -9,9 +9,28 @@ function eq(a, b, m) { if (a !== b) throw new Error(`${m ?? 'eq'}: expected ${JS
 function fakeConn() {
   const published = []
   const requests = new Map()
+  const subs = new Map()
   return {
     isClosed: () => false,
     publish(subject, data) { published.push({ subject, data: JSON.parse(new TextDecoder().decode(data)) }) },
+    subscribe(subject) {
+      const sub = {
+        async *[Symbol.asyncIterator]() {
+          while (true) {
+            const m = await new Promise((res) => {
+              const l = subs.get(subject) ?? []; subs.set(subject, l); l.push(res)
+            })
+            yield m
+          }
+        },
+        unsubscribe: () => subs.delete(subject),
+      }
+      return sub
+    },
+    _deliver(subject, env) {
+      const data = new TextEncoder().encode(JSON.stringify(env))
+      for (const fn of subs.get(subject) ?? []) fn({ data, subject, respond: (p) => { published.push({ subject: '_reply', env: JSON.parse(new TextDecoder().decode(p)) }) } })
+    },
     async request(subject, data, _opts) {
       const h = requests.get(subject)
       const reply = h ? h(JSON.parse(new TextDecoder().decode(data))) : { ok: true }
@@ -69,12 +88,12 @@ test('envelope has Synapse v0.3.0 shape', () => {
 
 // ─── register wiring ────────────────────────────────────────────────────────
 
-test('register wires 5 tools, 1 trigger, 1 panel', () => {
+test('register wires 12 tools, 1 trigger, 1 panel (full-duplex)', () => {
   const conn = fakeConn()
   const { tools, triggers, panels, ctx } = mkCtx({}, conn)
   register(ctx)
-  eq(tools.size, 5, 'tool count')
-  for (const n of ['synapse_health', 'synapse_discover', 'synapse_dispatch', 'synapse_register', 'synapse_agents_summary']) assert(tools.has(n), `missing ${n}`)
+  eq(tools.size, 12, 'tool count')
+  for (const n of ['synapse_health', 'synapse_discover', 'synapse_dispatch', 'synapse_register', 'synapse_agents_summary', 'synapse_serve', 'synapse_serve_status', 'synapse_emit', 'synapse_subscribe', 'synapse_reputation', 'synapse_request_approval', 'synapse_approve']) assert(tools.has(n), `missing ${n}`)
   eq(triggers.length, 1, 'trigger count')
   eq(triggers[0].name, 'synapse_mesh_event', 'trigger name')
   eq(panels.length, 1, 'panel count')
@@ -83,6 +102,7 @@ test('register wires 5 tools, 1 trigger, 1 panel', () => {
 // ─── discover ───────────────────────────────────────────────────────────────
 
 test('synapse_discover returns agents from registry', async () => {
+  __setConnForTest(null)
   const conn = fakeConn()
   conn._on('mesh.registry.discover', () => [
     { id: 'grip-cli-001', name: 'Grip CLI', skills: [{ id: 'himalaya' }] },
@@ -206,6 +226,50 @@ test('a failed connect is not cached — the next call retries', async () => {
   if (attempts !== 2) throw new Error(`expected 2 attempts (fail + retry), got ${attempts}`)
 })
 
+// ─── auto-start responder on boot (serveSkills + autoServe) ─────────────────
+
+test('autoServe: register() auto-starts the responder when enabled+autoServe (default skills)', async () => {
+  __setConnForTest(null)
+  const conn = fakeConn()
+  conn._on('mesh.registry.discover', () => [])
+  const { tools, logs, ctx } = mkCtx({}, conn)
+  register(ctx)
+  // auto-start is async (serveSkills → connectMesh → startResponder) — wait for it to settle
+  await new Promise((r) => setTimeout(r, 100))
+  const r = await tools.get('synapse_serve_status').handler({})
+  eq(r.serving, true, 'responder auto-started (serving=true)')
+  assert(r.skills.includes('status'), 'default skills include status')
+  assert(r.skills.includes('discover'), 'default skills include discover')
+  eq(r.autoServe, true, 'autoServe true by default')
+})
+
+test('autoServe: disabled when synapse.autoServe=false (no auto-start)', async () => {
+  __setConnForTest(null)
+  const conn = fakeConn()
+  const { tools, ctx } = mkCtx({ autoServe: false }, conn)
+  register(ctx)
+  await new Promise((r) => setTimeout(r, 20))
+  const r = await tools.get('synapse_serve_status').handler({})
+  eq(r.serving, false, 'responder NOT auto-started when autoServe=false')
+})
+
+test('autoServe: a failed auto-start does not break register (best-effort)', async () => {
+  __setConnForTest(null)
+  let failConnect = true
+  const conn = fakeConn()
+  const ctx = {
+    settings: { synapse: { url: 'nats://down:4222' } },
+    natsConnect: async () => { if (failConnect) throw new Error('server down'); return conn },
+    registerTool: () => {}, registerTrigger: () => {}, registerPanel: () => {}, log: () => {},
+  }
+  // register() must not throw even though the auto-start connection fails
+  const { register } = await import('./index.mjs')
+  let threw = false
+  try { register(ctx) } catch { threw = true }
+  assert(!threw, 'register() must not throw on auto-serve connection failure')
+  await new Promise((r) => setTimeout(r, 20)) // let the auto-start promise reject (handled)
+})
+
 // ─── runner ─────────────────────────────────────────────────────────────────
 async function main() {
   let pass = 0, fail = 0

package/plugins/synapse-bridge/synapseAgent.extreme.spec.mjs

@@ -0,0 +1,236 @@
+import {
+  buildRespond, executeSkill, startResponder,
+  emitEvent, subscribeEvents,
+  ReputationStore, computeScore, updateRecord, newRecord, REP_WEIGHTS,
+  requestApproval, respondApproval, startApprover,
+} from './synapseAgent.mjs'
+
+const cases = []
+function test(n, r) { cases.push({ name: n, run: r }) }
+function assert(c, m) { if (!c) throw new Error(m ?? 'assertion failed') }
+function eq(a, b, m) { if (a !== b) throw new Error(`${m ?? 'eq'}: expected ${JSON.stringify(b)}, got ${JSON.stringify(a)}`) }
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+const CFG = { agentId: 'rterm-001', prefix: 'mesh' }
+
+// ─── fake NATS connection (pub/sub + request/reply) ─────────────────────────
+// NATS wildcard grammar: '*' matches one token, '>' matches one or more (suffix).
+function subjectMatches(pattern, subject) {
+  if (pattern === subject) return true
+  const p = pattern.split('.')
+  const s = subject.split('.')
+  for (let i = 0; i < p.length; i++) {
+    if (p[i] === '>') return true
+    if (i >= s.length) return false
+    if (p[i] !== '*' && p[i] !== s[i]) return false
+  }
+  return p.length === s.length
+}
+
+function fakeConn() {
+  const published = []
+  const subs = new Map()
+  const requests = new Map()
+  const deliver = (subject, data, respondFn) => {
+    for (const [pattern, fns] of subs) {
+      if (subjectMatches(pattern, subject)) {
+        for (const fn of fns) fn({ data, subject, respond: respondFn })
+      }
+    }
+  }
+  return {
+    isClosed: () => false,
+    published,
+    publish(subject, data) {
+      const env = JSON.parse(dec.decode(data))
+      published.push({ subject, env })
+      deliver(subject, data, (p) => { published.push({ subject: '_reply', env: JSON.parse(dec.decode(p)) }) })
+    },
+    subscribe(subject) {
+      return {
+        async *[Symbol.asyncIterator]() {
+          while (true) {
+            const m = await new Promise((res) => {
+              const l = subs.get(subject) ?? []; subs.set(subject, l); l.push(res)
+            })
+            yield m
+          }
+        },
+        unsubscribe: () => subs.delete(subject),
+      }
+    },
+    async request(subject, data, _o) {
+      const env = JSON.parse(dec.decode(data))
+      const h = requests.get(subject)
+      const reply = h ? h(env) : { payload: { approved: true, approver: 'did:mesh:approver' } }
+      return { data: enc.encode(JSON.stringify(reply)) }
+    },
+    _deliver(subject, env) {
+      const data = enc.encode(JSON.stringify(env))
+      deliver(subject, data, (p) => { published.push({ subject: '_reply', env: JSON.parse(dec.decode(p)) }) })
+    },
+    _onRequest(subject, h) { requests.set(subject, h) },
+  }
+}
+
+// ─── 1. RESPONDER ────────────────────────────────────────────────────────────
+
+test('buildRespond: output envelope has to/task_id/in_reply_to + output payload', () => {
+  const req = { id: 'req-1', from: 'caller-001', task_id: 'task-9', payload: { skill: 'x' } }
+  const r = buildRespond(req, CFG, { output: { result: 42 } })
+  eq(r.type, 'respond', 'type')
+  eq(r.to, 'caller-001', 'to = original from')
+  eq(r.task_id, 'task-9', 'task_id')
+  eq(r.in_reply_to, 'req-1', 'in_reply_to = original id')
+  eq(r.payload.output.result, 42, 'output payload')
+  assert(!r.payload.error, 'no error when output present')
+})
+
+test('buildRespond: error envelope has error payload, no output; output+error throws', () => {
+  const req = { id: 'r2', from: 'c', task_id: 't' }
+  const r = buildRespond(req, CFG, { error: { code: 3001, message: 'nf' } })
+  eq(r.payload.error.code, 3001, 'error code')
+  assert(!r.payload.output, 'no output when error present')
+  let threw = false
+  try { buildRespond(req, CFG, { output: {}, error: { code: 1 } }) } catch { threw = true }
+  assert(threw, 'output+error must throw')
+})
+
+test('executeSkill: known skill returns output; unknown returns 3001 SKILL_NOT_FOUND', async () => {
+  const ctx = { rtermSkills: { greet: async (inp) => ({ hello: inp.name }) } }
+  const ok = await executeSkill('greet', { name: 'mesh' }, ctx)
+  eq(ok.output.hello, 'mesh', 'skill output')
+  const nf = await executeSkill('nope', {}, ctx)
+  eq(nf.error.code, 3001, 'SKILL_NOT_FOUND code')
+})
+
+test('startResponder: inbound request executes skill + responds on reply inbox', async () => {
+  const nc = fakeConn()
+  const ctx = { rtermSkills: { status: async () => ({ up: true }) } }
+  const stop = await startResponder(nc, CFG, ctx)
+  nc._deliver('mesh.agent.rterm-001.inbox', { id: 'q1', from: 'caller-001', task_id: 't1', payload: { skill: 'status', input: {} } })
+  await new Promise((r) => setTimeout(r, 20))
+  const reply = nc.published.find((p) => p.subject === '_reply')
+  assert(reply, 'expected a respond on the reply inbox')
+  eq(reply.env.type, 'respond', 'respond type')
+  eq(reply.env.to, 'caller-001', 'respond to caller')
+  eq(reply.env.payload.output.up, true, 'skill output delivered')
+  stop()
+})
+
+// ─── 2. EMIT / SUBSCRIBE ─────────────────────────────────────────────────────
+
+test('emitEvent publishes a formal emit envelope on mesh.event.{type}', () => {
+  const nc = fakeConn()
+  emitEvent(nc, CFG, 'ops.change.committed', { changeId: 'chg-1' })
+  const pub = nc.published.find((p) => p.subject === 'mesh.event.ops.change.committed')
+  assert(pub, 'expected emit publish')
+  eq(pub.env.type, 'emit', 'emit type')
+  eq(pub.env.payload.changeId, 'chg-1', 'emit payload')
+})
+
+test('subscribeEvents invokes handler for each event on the subject', async () => {
+  const nc = fakeConn()
+  const seen = []
+  const stop = await subscribeEvents(nc, 'mesh.event.>', (env, subj) => seen.push({ env, subj }))
+  nc._deliver('mesh.event.>', { type: 'emit', payload: { n: 1 } })
+  await new Promise((r) => setTimeout(r, 20))
+  eq(seen.length, 1, 'one event seen')
+  stop()
+})
+
+// ─── 3. REPUTATION ───────────────────────────────────────────────────────────
+
+test('computeScore: perfect record scores high', () => {
+  const rec = newRecord('a1', 'respond')
+  for (let i = 0; i < 5; i++) updateRecord(rec, { status: 'completed', latencyMs: 100 })
+  const s = computeScore(rec)
+  eq(s.success_rate, 1, 'success_rate 1')
+  assert(s.score > 0.8, `high score expected, got ${s.score}`)
+  eq(s.confidence, 1.0, 'full confidence at >=min samples')
+})
+
+test('updateRecord: failures lower success_rate + score', () => {
+  const rec = newRecord('a2', 'respond')
+  updateRecord(rec, { status: 'completed', latencyMs: 100 })
+  updateRecord(rec, { status: 'failed' })
+  updateRecord(rec, { status: 'timeout' })
+  const s = computeScore(rec)
+  assert(s.success_rate < 0.5, `success_rate should be low, got ${s.success_rate}`)
+  assert(s.score < 0.7, `score should be lower, got ${s.score}`)
+})
+
+test('reputation: 3 consecutive SKILL_NOT_FOUND flags lying-agent + zeroes score', () => {
+  const rec = newRecord('liar', 'respond')
+  updateRecord(rec, { status: 'skill_not_found' })
+  updateRecord(rec, { status: 'skill_not_found' })
+  updateRecord(rec, { status: 'skill_not_found' })
+  assert(rec.flags.misleading_capabilities, 'lying-agent flag set')
+  eq(rec.flags.penalty_reason.includes('SKILL_NOT_FOUND'), true, 'penalty reason')
+  const s = computeScore(rec)
+  eq(s.score, 0, 'lying penalty zeroes the score')
+})
+
+test('ReputationStore: observe + ranked + handleTaskUpdate', () => {
+  const store = new ReputationStore()
+  store.observe('a1', 'respond', { status: 'completed', latencyMs: 50 })
+  store.observe('a1', 'respond', { status: 'completed', latencyMs: 60 })
+  store.observe('a2', 'respond', { status: 'failed' })
+  const rec = store.get('a1', 'respond')
+  eq(rec.successes, 2, 'two successes recorded')
+  // task_update event path
+  store.handleTaskUpdate({ payload: { agent: 'a1', skill: 'respond', status: 'completed', latencyMs: 40 } })
+  eq(store.get('a1', 'respond').successes, 3, 'task_update fed the store')
+  const ranked = store.ranked(0)
+  assert(ranked.length >= 2, 'ranked returns all')
+  eq(ranked[0].agent_id, 'a1', 'a1 (higher score) ranks first')
+})
+
+// ─── 4. GOVERNANCE ───────────────────────────────────────────────────────────
+
+test('requestApproval publishes approval_request + returns approved response', async () => {
+  const nc = fakeConn()
+  let captured
+  nc._onRequest('mesh.approval.task-1.request', (env) => { captured = env; return { payload: { approved: true, approver: 'did:mesh:approver-001' } } })
+  const r = await requestApproval(nc, CFG, { taskId: 'task-1', originalRequest: { skill: 'pay' }, reason: 'payment needs approval' })
+  eq(captured.type, 'approval_request', 'request type')
+  eq(captured.task_id, 'task-1', 'request task_id')
+  eq(captured.payload.reason, 'payment needs approval', 'reason')
+  eq(r.approved, true, 'approved')
+  eq(r.approver, 'did:mesh:approver-001', 'approver')
+})
+
+test('respondApproval publishes approval_response on mesh.approval.{taskId}.response', () => {
+  const nc = fakeConn()
+  const req = { id: 'ar-1', from: 'agent-bob-001', task_id: 'task-7' }
+  respondApproval(nc, CFG, req, { approved: false, approver: 'did:mesh:rterm-001' })
+  const pub = nc.published.find((p) => p.subject === 'mesh.approval.task-7.response')
+  assert(pub, 'expected approval_response publish')
+  eq(pub.env.type, 'approval_response', 'response type')
+  eq(pub.env.to, 'agent-bob-001', 'to original requester')
+  eq(pub.env.payload.approved, false, 'denied')
+})
+
+test('startApprover answers inbound approval requests per the decide fn', async () => {
+  const nc = fakeConn()
+  const stop = await startApprover(nc, CFG, async () => ({ approved: true, approver: 'did:mesh:rterm-001' }))
+  nc._deliver('mesh.approval.task-9.request', { id: 'ar-9', from: 'agent-x', task_id: 'task-9', type: 'approval_request', payload: {} })
+  await new Promise((r) => setTimeout(r, 20))
+  const pub = nc.published.find((p) => p.subject === 'mesh.approval.task-9.response')
+  assert(pub, 'expected approver to answer')
+  eq(pub.env.payload.approved, true, 'approved by decide fn')
+  stop()
+})
+
+// ─── runner ─────────────────────────────────────────────────────────────────
+async function main() {
+  let pass = 0, fail = 0
+  for (const c of cases) {
+    try { await c.run(); pass++; console.log(`PASS ${c.name}`) }
+    catch (e) { fail++; console.log(`FAIL ${c.name}: ${e?.message ?? e}`) }
+  }
+  console.log(`\n${pass}/${pass + fail} passed, ${fail} failed`)
+  if (fail > 0) process.exit(1)
+}
+main()

package/plugins/synapse-bridge/synapseAgent.mjs

@@ -0,0 +1,254 @@
+/**
+ * synapseAgent — full-duplex Synapse agent capabilities for RTerm/neuralOS.
+ *
+ * Implements the four pieces that turn RTerm from a Synapse *client* into a full
+ * Synapse *agent* (EXT-GOVERNANCE + EXT-REPUTATION aware):
+ *
+ *   1. RESPONDER — listen on mesh.agent.{id}.inbox and respond() to incoming
+ *      Synapse requests by mapping them to RTerm skills (playbooks/tools).
+ *   2. EMIT/SUBSCRIBE — formal Synapse `emit` on mesh.event.{type} + wildcard
+ *      subscribe to mesh.event.* / mesh.task.* streams.
+ *   3. REPUTATION (EXT-REPUTATION) — observe task outcomes and maintain a local
+ *      ReputationRecord per (agent, skill): success_rate, speed_score, freshness,
+ *      composite score with lying-penalty + confidence, per Formula 11.5.
+ *   4. GOVERNANCE (EXT-GOVERNANCE) — speak mesh.approval.{task_id}.request/.response:
+ *      request approval for gated actions and answer approval requests (approver side).
+ *
+ * Transport is the injected NATS connection from the plugin (connectMesh). All pure
+ * logic (score formula, response building, record updates) is dependency-free + testable.
+ */
+
+import { randomUUID } from 'node:crypto'
+import { envelope } from './index.mjs'
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+const j = (v) => enc.encode(JSON.stringify(v))
+const uj = (b) => JSON.parse(dec.decode(b))
+
+// ─── 1. RESPONDER ────────────────────────────────────────────────────────────
+
+/** Build a Synapse respond envelope (payload has output XOR error). */
+export function buildRespond(requestEnv, cfg, { output, error } = {}) {
+  if (output && error) throw new Error('respond must contain output OR error, not both')
+  const payload = error ? { error } : { output: output ?? {} }
+  return envelope('respond', payload, cfg, {
+    to: requestEnv?.from,
+    task_id: requestEnv?.task_id,
+    in_reply_to: requestEnv?.id,
+  })
+}
+
+/** Map a Synapse skill id to an RTerm handler. The plugin supplies handlers for
+ * the skills RTerm advertises (playbooks/tools). Returns {output} or {error}. */
+export async function executeSkill(skillId, input, ctx) {
+  const skills = (typeof ctx.getRtermSkills === 'function' ? ctx.getRtermSkills() : ctx.rtermSkills) || {}
+  const handler = skills[skillId]
+  if (!handler) {
+    return { error: { code: 3001, message: `SKILL_NOT_FOUND: ${skillId}`, retryable: false } }
+  }
+  try {
+    const output = await handler(input ?? {}, ctx)
+    return { output: output ?? {} }
+  } catch (e) {
+    return { error: { code: 5000, message: String(e?.message ?? e), retryable: true } }
+  }
+}
+
+/** Start the responder loop: subscribe to mesh.agent.{id}.inbox, execute each
+ * request, and respond on the reply inbox. Returns a stop function. */
+export async function startResponder(nc, cfg, ctx, log = () => {}) {
+  const inbox = `${cfg.prefix}.agent.${cfg.agentId}.inbox`
+  const sub = nc.subscribe(inbox)
+  let stopped = false
+  const loop = (async () => {
+    for await (const msg of sub) {
+      if (stopped) break
+      ;(async () => {
+        try {
+          const req = uj(msg.data)
+          const skillId = req?.payload?.skill
+          const input = req?.payload?.input
+          log(`[synapse] inbound request from ${req?.from} skill=${skillId} task=${req?.task_id}`)
+          const result = await executeSkill(skillId, input, ctx)
+          const respond = buildRespond(req, cfg, result)
+          msg.respond(j(respond))
+        } catch (e) {
+          try { msg.respond(j({ error: { code: 5000, message: String(e?.message ?? e), retryable: true } })) } catch { /* best-effort */ }
+        }
+      })()
+    }
+  })()
+  loop.catch(() => {})
+  return () => { stopped = true; try { sub.unsubscribe() } catch {} }
+}
+
+// ─── 2. EMIT / SUBSCRIBE ─────────────────────────────────────────────────────
+
+/** Emit a formal Synapse event on mesh.event.{type}. */
+export function emitEvent(nc, cfg, eventType, payload, extra = {}) {
+  nc.publish(`${cfg.prefix}.event.${eventType}`, j(envelope('emit', payload, cfg, extra)))
+}
+
+/** Subscribe to a Synapse event/task subject (supports wildcards). Returns stop fn. */
+export async function subscribeEvents(nc, subject, handler) {
+  const sub = nc.subscribe(subject)
+  const loop = (async () => {
+    for await (const msg of sub) {
+      try { handler(uj(msg.data), msg.subject) } catch { /* ignore malformed */ }
+    }
+  })()
+  loop.catch(() => {})
+  return () => { try { sub.unsubscribe() } catch {} }
+}
+
+// ─── 3. REPUTATION (EXT-REPUTATION) ──────────────────────────────────────────
+
+export const REP_WEIGHTS = { success: 0.7, speed: 0.2, freshness: 0.1 }
+export const REP_DEFAULTS = { maxLatencyMs: 30000, freshnessHalfLifeHours: 24, minSampleSize: 3 }
+
+/** A ReputationRecord for one (agent, skill) pair. */
+export function newRecord(agentId, skill) {
+  return {
+    agent_id: agentId, skill,
+    total: 0, successes: 0, failures: 0, timeouts: 0,
+    skill_not_found: 0, overloaded: 0, rate_limited: 0,
+    latencies_ms: [],
+    success_rate: 0, speed_score: 0, freshness: 1, score: 0, confidence: 0.5,
+    flags: { misleading_capabilities: false, consecutive_skill_not_found: 0, last_penalty_at: null, penalty_reason: null },
+    last_seen: null,
+  }
+}
+
+/** Compute composite score per Formula 11.5. Pure. */
+export function computeScore(rec, weights = REP_WEIGHTS, defaults = REP_DEFAULTS, now = Date.now()) {
+  const outcomes = rec.successes + rec.failures + rec.timeouts
+  const success_rate = rec.successes / Math.max(1, outcomes)
+  const avgLatency = rec.latencies_ms.length ? rec.latencies_ms.reduce((a, b) => a + b, 0) / rec.latencies_ms.length : 0
+  const speed_score = success_rate > 0 ? 1 - Math.min(1, Math.max(0, avgLatency / defaults.maxLatencyMs)) : 0
+  const hoursSince = rec.last_seen ? (now - rec.last_seen) / 3600000 : 0
+  const freshness = Math.exp(-hoursSince / defaults.freshnessHalfLifeHours)
+  const confidence = outcomes >= defaults.minSampleSize ? 1.0 : 0.5
+  const lying_penalty = rec.flags.misleading_capabilities ? 0.0 : 1.0
+  const raw = weights.success * success_rate + weights.speed * speed_score + weights.freshness * freshness
+  const score = raw * lying_penalty * confidence
+  return { success_rate, speed_score, freshness, confidence, score }
+}
+
+/** Update a record from an observed task outcome. Pure-ish (returns the mutated record).
+ * outcome: { status: 'completed'|'failed'|'timeout'|'skill_not_found'|'overloaded'|'rate_limited', latencyMs? } */
+export function updateRecord(rec, outcome, defaults = REP_DEFAULTS, now = Date.now()) {
+  rec.total += 1
+  rec.last_seen = now
+  const st = outcome.status
+  if (st === 'completed') {
+    rec.successes += 1
+    rec.flags.consecutive_skill_not_found = 0
+    if (typeof outcome.latencyMs === 'number') rec.latencies_ms.push(outcome.latencyMs)
+  } else if (st === 'failed') {
+    rec.failures += 1
+    rec.flags.consecutive_skill_not_found = 0
+  } else if (st === 'timeout') {
+    rec.timeouts += 1
+    rec.flags.consecutive_skill_not_found = 0
+  } else if (st === 'skill_not_found') {
+    rec.skill_not_found += 1
+    rec.flags.consecutive_skill_not_found += 1
+    if (rec.flags.consecutive_skill_not_found >= 3) {
+      rec.flags.misleading_capabilities = true
+      rec.flags.penalty_reason = 'repeated SKILL_NOT_FOUND (lying-agent)'
+      rec.flags.last_penalty_at = new Date(now).toISOString()
+    }
+  } else if (st === 'overloaded') {
+    rec.overloaded += 1 // recorded, not scored
+  } else if (st === 'rate_limited') {
+    rec.rate_limited += 1 // recorded, not scored
+  }
+  const s = computeScore(rec, REP_WEIGHTS, defaults, now)
+  rec.success_rate = s.success_rate
+  rec.speed_score = s.speed_score
+  rec.freshness = s.freshness
+  rec.confidence = s.confidence
+  rec.score = s.score
+  return rec
+}
+
+/** Local ReputationStore: keyed {agent}::{skill}, fed by task_update events. */
+export class ReputationStore {
+  constructor(defaults = REP_DEFAULTS) {
+    this.defaults = defaults
+    this.records = new Map()
+  }
+  key(agentId, skill) { return `${agentId}::${skill}` }
+  get(agentId, skill) { return this.records.get(this.key(agentId, skill)) }
+  observe(agentId, skill, outcome, now = Date.now()) {
+    const k = this.key(agentId, skill)
+    let rec = this.records.get(k)
+    if (!rec) { rec = newRecord(agentId, skill); this.records.set(k, rec) }
+    return updateRecord(rec, outcome, this.defaults, now)
+  }
+  /** discover-ranked: all records at/above minScore, sorted by score desc. */
+  ranked(minScore = 0) {
+    return [...this.records.values()].filter((r) => r.score >= minScore).sort((a, b) => b.score - a.score)
+  }
+  /** Feed a mesh.task.{id}.update event (type task_update with payload {agent, skill, status, latencyMs?}). */
+  handleTaskUpdate(env, now = Date.now()) {
+    const p = env?.payload ?? {}
+    if (!p.agent || !p.skill || !p.status) return null
+    return this.observe(p.agent, p.skill, { status: p.status, latencyMs: p.latencyMs }, now)
+  }
+}
+
+// ─── 4. GOVERNANCE (EXT-GOVERNANCE) ──────────────────────────────────────────
+
+/** Request approval for a gated action: publish mesh.approval.{taskId}.request and
+ * await the response. Returns { approved, approver } or { approved: false, error }. */
+export async function requestApproval(nc, cfg, { taskId, originalRequest, policyId, ruleId, reason, timeout = 30000 }) {
+  const tid = taskId ?? randomUUID()
+  const env = envelope('approval_request', {
+    original_request: originalRequest ?? {},
+    policy_id: policyId,
+    rule_id: ruleId,
+    reason,
+  }, cfg, { task_id: tid })
+  const msg = await nc.request(`${cfg.prefix}.approval.${tid}.request`, j(env), { timeout })
+  const reply = uj(msg.data)
+  const p = reply?.payload ?? reply
+  return { approved: p?.approved === true, approver: p?.approver, taskId: tid, raw: reply }
+}
+
+/** Answer an approval request (approver side): publish mesh.approval.{taskId}.response. */
+export function respondApproval(nc, cfg, requestEnv, { approved, approver }) {
+  const tid = requestEnv?.task_id
+  const env = envelope('approval_response', { approved: approved === true, approver }, cfg, {
+    to: requestEnv?.from,
+    task_id: tid,
+    in_reply_to: requestEnv?.id,
+  })
+  nc.publish(`${cfg.prefix}.approval.${tid}.response`, j(env))
+  return { answered: tid, approved: approved === true }
+}
+
+/** Start an approver loop: subscribe to mesh.approval.*.request and answer each per
+ * the supplied decide() function ({approved, approver} or a policy name). Returns stop fn. */
+export async function startApprover(nc, cfg, decide, log = () => {}) {
+  const sub = nc.subscribe(`${cfg.prefix}.approval.*.request`)
+  let stopped = false
+  const loop = (async () => {
+    for await (const msg of sub) {
+      if (stopped) break
+      ;(async () => {
+        try {
+          const req = uj(msg.data)
+          const decision = await decide(req)
+          respondApproval(nc, cfg, req, decision)
+          log(`[synapse] approval ${decision.approved ? 'granted' : 'denied'} for task ${req?.task_id}`)
+        } catch (e) {
+          log(`[synapse] approval handling error: ${e?.message ?? e}`)
+        }
+      })()
+    }
+  })()
+  loop.catch(() => {})
+  return () => { stopped = true; try { sub.unsubscribe() } catch {} }
+}