rterm-backend 3.8.3 → 3.8.5

package/plugins/reactorpro-bridge/reactorpro-bridge.extreme.spec.mts

@@ -0,0 +1,273 @@
+/**
+ * reactorpro-bridge — wire compatibility with the ReactorPro gateway.
+ *
+ * This is the contract test for v3.8.5: the plugin must be interoperable
+ * with the REAL gateway implementation (crates/agent-gateway/internal/mesh),
+ * the way the ReactorPro desktop implements it. Two halves:
+ *
+ *   A. Pure-JS invariants (always run): fingerprint derivation, signing
+ *      payload construction, envelope sign/verify round-trip, respond/error
+ *      shapes, identity minting + tamper detection, settings persistence
+ *      (the v3.1.3 lesson: a settings block missing from pickBackendSnapshot
+ *      is silently wiped on save).
+ *
+ *   B. Go cross-check (runs when the ReactorPro checkout + Go are present):
+ *      the plugin signs an envelope, and the GATEWAY's own VerifyEnvelope
+ *      must accept it; the gateway signs one, and the plugin must accept it.
+ *      Skipped cleanly when the checkout is absent — CI without the ReactorPro
+ *      repo still runs part A.
+ *
+ * Run:  npx tsx plugins/reactorpro-bridge/reactorpro-bridge.extreme.spec.mts
+ */
+import { execFileSync, spawnSync } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import {
+  AUTH_KEYS,
+  buildRespond,
+  checkIdentity,
+  envelope,
+  fingerprintFor,
+  mintIdentity,
+  rawPublicKeyFromPem,
+  signEnvelope,
+  signingPayload,
+  verifyEnvelope,
+} from './reactorproAgent.mjs'
+import { loadOrCreateIdentity, resolveConfig } from './index.mjs'
+
+let pass = 0
+let fail = 0
+const failures: string[] = []
+
+function ok(cond: unknown, label: string, note = ''): void {
+  if (cond) {
+    pass++
+    console.log(`PASS ${label}`)
+  } else {
+    fail++
+    failures.push(label)
+    console.log(`FAIL ${label}${note ? ` — ${note}` : ''}`)
+  }
+}
+
+// ─── A. pure-JS invariants ───────────────────────────────────────────────────
+
+// A1. Fingerprint: sha256:<16hex> over "<agent id>\n" + raw SPKI public key.
+{
+  const id = mintIdentity('rterm/xcheck/fixture')
+  const fp = fingerprintFor('rterm/xcheck/fixture', id.publicKeyPem)
+  ok(/^sha256:[0-9a-f]{16}$/.test(fp), 'fingerprint is sha256:<16hex>')
+  // The id is inside the digest: same key, different id => different fp.
+  const fp2 = fingerprintFor('rterm/xcheck/other', id.publicKeyPem)
+  ok(fp !== fp2, 'fingerprint binds the agent id (different id => different fp)')
+  // And the raw public key must round-trip from the PEM.
+  ok(rawPublicKeyFromPem(id.publicKeyPem).length === 32, 'raw public key is 32 bytes (Ed25519)')
+}
+
+// A2. checkIdentity detects tampering.
+{
+  const id = mintIdentity('rterm/xcheck/tamper')
+  let threw = false
+  try {
+    // The identity's id field is `identity` — mutating it (e.g. renaming the
+    // agent) breaks the fingerprint, which binds id + key.
+    checkIdentity({ ...id, identity: 'someone-else' } as never)
+  } catch {
+    threw = true
+  }
+  ok(threw, 'checkIdentity rejects an identity whose fingerprint does not match')
+
+  let threwKey = false
+  const other = mintIdentity('rterm/xcheck/tamper')
+  try {
+    checkIdentity({ ...id, publicKeyPem: other.publicKeyPem } as never)
+  } catch {
+    threwKey = true
+  }
+  ok(threwKey, 'checkIdentity rejects a swapped public key')
+}
+
+// A3. signEnvelope/verifyEnvelope round-trip, ReactorPro convention.
+{
+  const id = mintIdentity('rterm/xcheck/signer')
+  const cfg = { agentId: 'rterm/xcheck/signer', prefix: 'mesh', fingerprint: id.fingerprint }
+  const env = envelope('request', { skill: 'ping', input: {}, reply_to: '_REPLY.abc.123' }, cfg, { to: 'peer-1' })
+  const signed = signEnvelope(env, id)
+
+  ok(AUTH_KEYS.every((k) => typeof (signed as Record<string, unknown>)[k] === 'string'),
+    'signed envelope carries sig/pub/fp')
+  const v = verifyEnvelope(signed)
+  ok(v.ok && v.note !== 'unsigned', `plugin verifies its own signature (${v.note})`)
+
+  // Tamper with the payload -> signature must fail.
+  const tampered = { ...(signed as Record<string, unknown>), payload: { skill: 'invoke', input: { evil: true } } }
+  const tv = verifyEnvelope(tampered)
+  ok(!tv.ok, 'tampered payload fails verification')
+
+  // Swap the fingerprint -> identity mismatch.
+  const fpSwap = { ...(signed as Record<string, unknown>), fp: 'sha256:deadbeefdeadbeef' }
+  const fv = verifyEnvelope(fpSwap)
+  ok(!fv.ok, 'swapped fingerprint fails verification')
+}
+
+// A4. The signing payload covers every meaning-bearing field (gateway order).
+{
+  const env = {
+    v: '0.3.0', id: 'id-1', type: 'respond', ts: '2026-09-17T00:00:00Z',
+    from: 'a', to: 'b', task_id: 't-1', in_reply_to: 'r-1', fp: 'sha256:0123456789abcdef',
+    trace: { trace_id: 'tr-1', span_id: 'sp-1' },
+    error: { code: 3001, message: 'SKILL_NOT_FOUND', retryable: false },
+    payload: { output: { x: 1 } },
+  }
+  const sp = signingPayload(env as never)
+  const text = sp.toString('latin1')
+  // Length-prefixed fields in gateway order: v, id, type, ts, from, to, task_id, in_reply_to, fp
+  ok(text.startsWith('5:0.3.0\n'), 'signing payload starts with the version field, length-prefixed')
+  ok(text.includes('4:id-1\n'), 'signing payload includes id')
+  ok(text.includes('7:respond\n'), 'signing payload includes type')
+  ok(text.includes('1:a\n'), 'signing payload includes from')
+  ok(text.includes('5:tr-1\n') || text.includes('4:tr-1\n'), 'signing payload includes trace_id')
+  ok(text.includes('4:3001\n'), 'signing payload includes error code')
+  // Absent trace/error contribute their empty positions.
+  const bare = signingPayload({ v: '0.3.0', id: 'x', type: 'emit', ts: 't', from: 'f' } as never)
+  const bareText = bare.toString('latin1')
+  ok(bareText.includes('0:\n0:\n'), 'absent trace/error contribute empty positions')
+}
+
+// A5. buildRespond: output XOR error, in_reply_to + task_id correlation.
+{
+  const cfg = { agentId: 'a', prefix: 'mesh' }
+  const req = { id: 'req-1', from: 'caller', task_id: 'task-9' }
+  const r = buildRespond(req as never, cfg, { output: { pong: true } })
+  ok(r.in_reply_to === 'req-1' && r.task_id === 'task-9' && r.to === 'caller',
+    'respond correlates in_reply_to/task_id/to')
+  ok((r.payload as Record<string, unknown>).output !== undefined, 'respond payload carries output')
+
+  let threw = false
+  try {
+    buildRespond(req as never, cfg, { output: { a: 1 }, error: { code: 1, message: 'x', retryable: false } } as never)
+  } catch {
+    threw = true
+  }
+  ok(threw, 'respond rejects output AND error together')
+}
+
+// A6. Settings persistence — the v3.1.3 lesson.
+// resolveConfig must read the reactorpro block, and the block must survive
+// the migration snapshot (pickBackendSnapshot) — verified by importing the
+// real migrations module.
+{
+  const cfg = resolveConfig({
+    settings: {
+      reactorpro: {
+        enabled: true,
+        url: 'nats://mesh.example:4222',
+        agentId: 'rterm/xcheck/persist',
+        prefix: 'mesh',
+        identityPath: '/tmp/xcheck-identity.json',
+        dispatchTimeout: 240000,
+      },
+    },
+  })
+  ok(cfg.agentId === 'rterm/xcheck/persist', 'resolveConfig reads reactorpro.agentId')
+  ok(cfg.dispatchTimeout === 240000, 'resolveConfig reads reactorpro.dispatchTimeout')
+  ok(cfg.enabled === true, 'resolveConfig reads reactorpro.enabled')
+
+  // The migration whitelist must carry the block. Import the real module.
+  const migrationsPath = join(import.meta.dirname, '..', '..', 'packages', 'backend', 'src', 'services', 'settings', 'migrations.ts')
+  if (existsSync(migrationsPath)) {
+    const src = readFileSync(migrationsPath, 'utf-8')
+    ok(src.includes('reactorpro: raw.reactorpro'),
+      'pickBackendSnapshot carries reactorpro (v3.1.3 lesson: missing keys are silently wiped)')
+    ok(src.includes('normalizeReactorProSettings'),
+      'normalizeBackendSettings sanitizes the reactorpro block')
+  } else {
+    ok(false, 'migrations.ts not found for the persistence check')
+  }
+}
+
+// A7. Identity persistence: mint once, load forever; 0600; tamper detection.
+{
+  const dir = mkdtempSync(join(tmpdir(), 'rp-xcheck-'))
+  const identityPath = join(dir, 'identity.json')
+  const cfg = { agentId: 'rterm/xcheck/persist-id', identityPath }
+  const first = loadOrCreateIdentity(cfg as never)
+  const second = loadOrCreateIdentity(cfg as never)
+  ok(first.fingerprint === second.fingerprint, 'identity is minted once and reloaded unchanged')
+
+  // Tamper with the stored identity -> loadOrCreateIdentity must throw.
+  const stored = JSON.parse(readFileSync(identityPath, 'utf-8'))
+  stored.identity = 'attacker'
+  writeFileSync(identityPath, JSON.stringify(stored))
+  let threw = false
+  try {
+    loadOrCreateIdentity(cfg as never)
+  } catch {
+    threw = true
+  }
+  ok(threw, 'a tampered identity file is rejected on load')
+}
+
+// ─── B. Go cross-check against the REAL gateway ──────────────────────────────
+
+const RP_CHECKOUT = process.env.RP_CHECKOUT ?? join(process.env.HOME ?? '', 'work', 'ReactorPro')
+const RP_GW = join(RP_CHECKOUT, 'crates', 'agent-gateway')
+
+if (existsSync(join(RP_GW, 'go.mod')) && existsSync('/opt/homebrew/bin/go')) {
+  console.log('\n-- Go cross-check against the real gateway --')
+  const fixtureDir = mkdtempSync(join(tmpdir(), 'rp-fixtures-'))
+
+  // B1. Plugin signs -> gateway verifies.
+  const id = mintIdentity('rterm/xcheck/go')
+  writeFileSync(join(fixtureDir, 'gateway_identity.json'), JSON.stringify({
+    identity: 'rterm/xcheck/go',
+    privateKeyPem: id.privateKeyPem,
+    publicKeyPem: id.publicKeyPem,
+    fingerprint: id.fingerprint,
+  }, null, 2))
+
+  const cfg = { agentId: 'rterm/xcheck/go', prefix: 'mesh', fingerprint: id.fingerprint }
+  const env = envelope('respond', { output: { cross: true } }, cfg, { to: 'reactorpro/edge-1' })
+  const signed = signEnvelope(env, id)
+  // COMPACT on purpose. The gateway's Envelope.Payload is a json.RawMessage,
+  // which captures the payload bytes EXACTLY as they appear in the file —
+  // including any pretty-print indentation. The plugin signs
+  // JSON.stringify(payload) (compact) and publishes j(signed) (compact), so a
+  // pretty-printed fixture would make the gateway re-hash DIFFERENT bytes than
+  // were signed and fail verification even though the real wire exchange is
+  // correct. The fixture must be byte-faithful to the wire.
+  writeFileSync(join(fixtureDir, 'plugin_signed_envelope.json'), JSON.stringify(signed))
+  writeFileSync(join(fixtureDir, 'plugin_signing_payload.hex'),
+    signingPayload(signed as never).toString('hex') + '\n')
+
+  const goTest = spawnSync('/opt/homebrew/bin/go', ['test', './internal/mesh', '-run', 'TestRtermBridgeCrossVerify', '-v', '-count=1'],
+    { cwd: RP_GW, env: { ...process.env, RTERM_BRIDGE_FIXTURES: fixtureDir }, encoding: 'utf-8', timeout: 180000 })
+
+  ok(goTest.status === 0,
+    `the REAL gateway verifies the plugin's envelope (go test exit ${goTest.status})`,
+    goTest.status !== 0 ? (goTest.stderr || goTest.stdout || '').split('\n').filter((l) => l.includes('FAIL') || l.includes('mismatch')).slice(0, 3).join('; ') : '')
+
+  // B2. Gateway signs -> plugin verifies.
+  const gwEnvPath = join(fixtureDir, 'gateway_signed_envelope.json')
+  if (existsSync(gwEnvPath)) {
+    const gwEnv = JSON.parse(readFileSync(gwEnvPath, 'utf-8'))
+    const v = verifyEnvelope(gwEnv)
+    ok(v.ok && v.note !== 'unsigned',
+      `the plugin verifies the gateway's envelope (${v.note})`,
+      JSON.stringify(v))
+  } else {
+    ok(false, 'gateway_signed_envelope.json was not produced by the Go test')
+  }
+} else {
+  console.log('\n-- Go cross-check skipped (ReactorPro checkout or Go not present) --')
+}
+
+console.log(`\n${pass} passed, ${fail} failed`)
+if (fail > 0) {
+  console.log(`FAILURES:\n${failures.map((f) => `  - ${f}`).join('\n')}`)
+  process.exit(1)
+}
+console.log('reactorpro-bridge: ALL TESTS PASSED')

package/plugins/reactorpro-bridge/reactorproAgent.mjs

@@ -0,0 +1,347 @@
+/**
+ * reactorproAgent — full-duplex ReactorPro mesh citizen for RTerm/neuralOS.
+ *
+ * Implements the ReactorPro gateway wire protocol exactly as the gateway
+ * enforces it (crates/agent-gateway/internal/mesh/):
+ *
+ *   1. IDENTITY — Ed25519 keypair bound to an agent id; fingerprint
+ *      sha256:<16hex> over `<agent id>\n` + raw public key bytes. The id is
+ *      inside the digest, so a key under another id is a different identity.
+ *   2. ENVELOPE — v0.3.0 signed JSON with `sig`/`pub`/`fp` (the ReactorPro
+ *      convention; the legacy Synapse `signature`/`from_identity` fields are
+ *      ignored by ReactorPro edges and cannot invoke).
+ *   3. RESPONDER — serve `mesh.agent.<id>.inbox` (core NATS, NEVER JetStream
+ *      — a stream over the inbox breaks request/reply), answering skills.
+ *   4. HEARTBEAT — signed liveness on `mesh.heartbeat.<id>`; registry entries
+ *      expire (TTL ≈ 3× heartbeat), so a dead edge stops being advertised.
+ *   5. REGISTRY — announce the manifest on `mesh.registry.register` (KV bucket
+ *      `mesh_registry`) and answer `mesh.registry.discover` broadcasts.
+ *
+ * Pure functions (signing, fingerprint, envelope) are dependency-free and
+ * unit-testable; transport is injected.
+ */
+
+import { randomUUID, createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign as edSign, verify as edVerify } from 'node:crypto'
+
+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. IDENTITY ────────────────────────────────────────────────────────────
+
+/** Raw 32-byte Ed25519 public key from a PEM SPKI certificate.
+ *
+ * The gateway's FingerprintFor hashes the RAW key bytes
+ * (identity.go: `sha256(agentID + "\n" + publicKey)` where publicKey is
+ * ed25519.PublicKey), and VerifyEnvelope calls ed25519.Verify with that raw
+ * key. The PEM body is the 44-byte SPKI DER — a 12-byte ASN.1 header
+ * (302a300506032b6570032100) followed by the 32-byte key — so the header must
+ * be stripped. Base64-decoding the PEM body alone returns all 44 bytes. */
+export function rawPublicKeyFromPem(pem) {
+  const keyObject = createPublicKey(pem)
+  const spki = keyObject.export({ type: 'spki', format: 'der' })
+  if (spki.length < 32) {
+    throw new Error(`SPKI DER too short for Ed25519: ${spki.length} bytes`)
+  }
+  return Buffer.from(spki.subarray(spki.length - 32))
+}
+
+/**
+ * fingerprint = "sha256:" + hex(sha256(agent_id + "\n" + raw_pubkey))[:16]
+ * The id is inside the digest — same key under another id = different fp.
+ */
+export function fingerprintFor(agentId, publicKeyPem) {
+  const raw = rawPublicKeyFromPem(publicKeyPem)
+  const digest = Buffer.concat([enc.encode(agentId + '\n'), raw])
+  const hex = createHash('sha256').update(digest).digest('hex')
+  return 'sha256:' + hex.slice(0, 16)
+}
+
+/** Mint a new gateway-compatible identity: {identity, privateKeyPem,
+ *  publicKeyPem, fingerprint}. The id is permanent — it is bound into the
+ *  fingerprint; minting again under the same id is a DIFFERENT identity. */
+export function mintIdentity(agentId) {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519')
+  const publicKeyPem = publicKey.export({ type: 'spki', format: 'pem' }).toString()
+  const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString()
+  return {
+    identity: agentId,
+    privateKeyPem,
+    publicKeyPem,
+    fingerprint: fingerprintFor(agentId, publicKeyPem),
+  }
+}
+
+/** Verify an identity file's internal consistency (id ↔ key ↔ fingerprint). */
+export function checkIdentity(id) {
+  const fp = fingerprintFor(id.identity, id.publicKeyPem)
+  if (id.fingerprint !== fp) {
+    throw new Error('identity fails its own fingerprint check — tampered or wrong format')
+  }
+  return id
+}
+
+// ─── 2. ENVELOPE + SIGNING (ReactorPro convention) ──────────────────────────
+
+export const AUTH_KEYS = ['sig', 'pub', 'fp']
+
+/** The exact byte string an Ed25519 signature covers — a field-joined,
+ *  length-prefixed digest, mirrored from the gateway's SigningPayload
+ *  (internal/mesh/identity.go). Lengths are UTF-8 byte lengths.
+ *
+ *  Fields: v, id, type, ts, from, to, task_id, in_reply_to, fp,
+ *  [trace_id, span_id], [err_code, err_message, err_retryable],
+ *  then the raw sha256(payload) digest. Optional groups contribute their
+ *  empty positions when absent, so "absent" and "empty" cannot collide. */
+export function signingPayload(env) {
+  const parts = [
+    env.v ?? '', env.id ?? '', env.type ?? '',
+    env.ts ?? '', env.from ?? '', env.to ?? '',
+    env.task_id ?? '', env.in_reply_to ?? '', env.fp ?? '',
+  ]
+  const trace = env.trace
+  if (trace && typeof trace === 'object') {
+    parts.push(trace.trace_id ?? '', trace.span_id ?? '')
+  } else {
+    parts.push('', '')
+  }
+  const error = env.error
+  if (error && typeof error === 'object') {
+    parts.push(String(error.code ?? 0), String(error.message ?? ''), error.retryable ? 'true' : 'false')
+  } else {
+    parts.push('', '', '')
+  }
+
+  const chunks = []
+  for (const part of parts) {
+    const raw = enc.encode(String(part))
+    chunks.push(enc.encode(`${Buffer.byteLength(raw)}:`), raw, enc.encode('\n'))
+  }
+  const payload = env.payload
+  const payloadBytes = payload === undefined || payload === null
+    ? Buffer.alloc(0)
+    : Buffer.from(JSON.stringify(payload), 'utf-8')
+  chunks.push(createHash('sha256').update(payloadBytes).digest())
+  return Buffer.concat(chunks)
+}
+
+/** Build an unsigned envelope (register|discover|request|respond|emit|heartbeat). */
+export function envelope(type, payload, cfg, extra = {}) {
+  return {
+    v: '0.3.0',
+    id: randomUUID(),
+    type,
+    ts: new Date().toISOString(),
+    from: cfg.agentId,
+    ...(cfg.fingerprint ? { fp: cfg.fingerprint } : {}),
+    trace: { trace_id: randomUUID(), span_id: randomUUID() },
+    payload,
+    ...extra,
+  }
+}
+
+/** Attach pub/fp/sig the ReactorPro way. The signature covers the fingerprint
+ *  but not the public key or itself, matching the gateway. */
+export function signEnvelope(env, identity) {
+  const signed = {}
+  for (const [k, v] of Object.entries(env)) {
+    if (!AUTH_KEYS.includes(k)) signed[k] = v
+  }
+  signed.pub = identity.publicKeyPem
+  signed.fp = identity.fingerprint
+  const priv = createPrivateKey(identity.privateKeyPem)
+  signed.sig = edSign(null, signingPayload(signed), priv).toString('hex')
+  return signed
+}
+
+/** Verify a ReactorPro-convention signature. { ok: true, note: 'unsigned' }
+ *  when the envelope carries none — that is a policy decision, not a
+ *  verification failure.
+ *
+ *  Only sig and pub are stripped before recomputing the payload — the
+ *  fingerprint is deliberately RETAINED because the gateway's SigningPayload
+ *  covers it (identity.go: "Fingerprint is deliberately retained: it is part
+ *  of the signed payload"). Stripping fp here made the verifier's payload
+ *  differ from the signer's, so every signature failed. */
+export function verifyEnvelope(env) {
+  const pubPem = env?.pub ?? ''
+  const sigHex = env?.sig ?? ''
+  if (!pubPem || !sigHex) return { ok: true, note: 'unsigned' }
+  try {
+    const unsigned = {}
+    for (const [k, v] of Object.entries(env)) {
+      if (k === 'sig' || k === 'pub') continue
+      unsigned[k] = v
+    }
+    // Node's edVerify needs a KeyObject — a raw 32-byte buffer throws
+    // ERR_OSSL_UNSUPPORTED. The PEM round-trips through createPublicKey.
+    const pub = createPublicKey(pubPem)
+    const ok = edVerify(null, signingPayload(unsigned), pub, Buffer.from(sigHex, 'hex'))
+    if (!ok) return { ok: false, note: 'signature check failed' }
+  } catch (e) {
+    return { ok: false, note: `signature check failed: ${e?.message ?? e}` }
+  }
+  const claimed = env?.fp ?? ''
+  const proved = fingerprintFor(String(env?.from ?? ''), pubPem)
+  if (claimed && claimed !== proved) {
+    return { ok: false, note: `fingerprint mismatch: claims ${claimed}, key proves ${proved}` }
+  }
+  return { ok: true, note: proved }
+}
+
+/** A JetStream PubAck ({"stream":…,"seq":…}) rather than a mesh envelope. */
+export function isPublishAck(data) {
+  try {
+    const o = uj(data)
+    return typeof o === 'object' && o !== null && 'stream' in o && 'seq' in o && !('type' in o) && !('id' in o)
+  } catch { return false }
+}
+
+// ─── 3. RESPONDER (inbox serving, core NATS only) ───────────────────────────
+
+/** Build a ReactorPro 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,
+  })
+}
+
+/** Skills RTerm serves on the mesh by default. The `invoke` skill routes a
+ *  prompt into a real RTerm agent turn (the same path the desktop uses). */
+export function defaultServeSkills(cfg, deps = {}) {
+  return {
+    ping: async () => ({ pong: true, ts: new Date().toISOString() }),
+    describe: async () => buildManifest(cfg, deps.skills ? Object.keys(deps.skills) : ['ping', 'describe', 'status', 'invoke']),
+    status: async () => ({
+      agent_id: cfg.agentId,
+      fingerprint: cfg.fingerprint ?? null,
+      connected: true,
+      skills: ['ping', 'describe', 'status', 'invoke'],
+      uptime_seconds: Math.floor((Date.now() - (deps.startedAt ?? Date.now())) / 1000),
+    }),
+    ...(deps.skills ?? {}),
+  }
+}
+
+/** Start the responder loop: subscribe to mesh.agent.<id>.inbox (core NATS),
+ *  execute each request's skill, and respond on the reply subject. Returns a
+ *  stop function. Never JetStream over the inbox — see §inbox-streaming. */
+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 {
+          if (isPublishAck(msg.data)) return // skip ack-shaped messages
+          const req = uj(msg.data)
+          const skillId = req?.payload?.skill
+          const input = req?.payload?.input
+          log(`[reactorpro] inbound request from ${req?.from} skill=${skillId} task=${req?.task_id}`)
+          const result = await executeSkill(skillId, input, ctx)
+          const respond = buildRespond(req, cfg, result)
+          const signed = ctx.identity ? signEnvelope(respond, ctx.identity) : respond
+          const replySubject = req?.payload?.reply_to || msg.reply
+          if (replySubject && typeof nc.publish === 'function') nc.publish(replySubject, j(signed))
+          else if (typeof msg.respond === 'function') msg.respond(j(signed))
+        } catch (e) {
+          try {
+            const errEnv = envelope('respond', { error: { code: 5000, message: String(e?.message ?? e), retryable: true } }, cfg)
+            const signed = ctx.identity ? signEnvelope(errEnv, ctx.identity) : errEnv
+            if (typeof msg.respond === 'function') msg.respond(j(signed))
+          } catch { /* best-effort */ }
+        }
+      })()
+    }
+  })()
+  loop.catch(() => {})
+  return () => { stopped = true; try { sub.unsubscribe() } catch { /* best-effort */ } }
+}
+
+/** Map a ReactorPro skill id to an RTerm handler. Returns {output} or {error}. */
+export async function executeSkill(skillId, input, ctx) {
+  const skills = (typeof ctx.getSkills === 'function' ? ctx.getSkills() : ctx.skills) || {}
+  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 } }
+  }
+}
+
+// ─── 4. HEARTBEAT ────────────────────────────────────────────────────────────
+
+/** Publish a signed heartbeat (liveness + id-collision detection). */
+export function heartbeat(nc, cfg, identity) {
+  const env = envelope('heartbeat', { ts: new Date().toISOString() }, cfg)
+  nc.publish(`${cfg.prefix}.heartbeat.${cfg.agentId}`, j(signEnvelope(env, identity)))
+}
+
+/** Start a periodic signed heartbeat. Returns a stop function. */
+export function startHeartbeat(nc, cfg, identity, intervalMs = 30000, log = () => {}) {
+  try { heartbeat(nc, cfg, identity) } catch (e) { log(`[reactorpro] heartbeat failed: ${e?.message ?? e}`) }
+  const t = setInterval(() => {
+    try { heartbeat(nc, cfg, identity) } catch (e) { log(`[reactorpro] heartbeat failed: ${e?.message ?? e}`) }
+  }, intervalMs)
+  return () => clearInterval(t)
+}
+
+// ─── 5. REGISTRY ─────────────────────────────────────────────────────────────
+
+/** The manifest this RTerm advertises. */
+export function buildManifest(cfg, skillIds) {
+  return {
+    identity: cfg.agentId,
+    name: cfg.name ?? cfg.agentId,
+    capabilities: ['rterm', 'agent', ...(cfg.capabilities ?? [])],
+    skills: skillIds,
+    fingerprint: cfg.fingerprint ?? null,
+    local_agents: [{ id: cfg.agentId, name: cfg.name ?? cfg.agentId, capabilities: ['rterm', 'agent'] }],
+  }
+}
+
+/** Register with the mesh registry (mesh.registry.register). */
+export function registerManifest(nc, cfg, identity, manifest) {
+  const env = envelope('register', { manifest }, cfg, { to: 'REGISTRY' })
+  nc.publish(`${cfg.prefix}.registry.register`, j(signEnvelope(env, identity)))
+}
+
+/** Graceful exit. */
+export function deregisterManifest(nc, cfg, identity) {
+  const env = envelope('register', { manifest: { identity: cfg.agentId, gone: true } }, cfg, { to: 'REGISTRY' })
+  nc.publish(`${cfg.prefix}.registry.deregister`, j(signEnvelope(env, identity)))
+}
+
+/** Answer discovery broadcasts with our manifest. */
+export async function answerDiscovery(nc, cfg, identity, manifest, log = () => {}) {
+  const subject = `${cfg.prefix}.registry.discover`
+  const sub = nc.subscribe(subject)
+  let stopped = false
+  const loop = (async () => {
+    for await (const msg of sub) {
+      if (stopped) break
+      try {
+        if (isPublishAck(msg.data)) continue
+        const req = uj(msg.data)
+        if (req?.from === cfg.agentId) continue // don't answer ourselves
+        if (msg.reply) {
+          const env = envelope('respond', { manifest }, cfg, { to: req?.from, in_reply_to: req?.id })
+          nc.publish(msg.reply, j(signEnvelope(env, identity)))
+        }
+      } catch (e) { log(`[reactorpro] discovery answer failed: ${e?.message ?? e}`) }
+    }
+  })()
+  loop.catch(() => {})
+  return () => { stopped = true; try { sub.unsubscribe() } catch { /* best-effort */ } }
+}