@bongos/core 1.19.710 → 1.19.711

package/tests/agents_write_routes.mjs

@@ -0,0 +1,461 @@
+// tests/agents_write_routes.mjs — what the agent WRITE handlers actually do
+// (task 1002493, goal 1000038 Phase 2a).
+//
+// tests/agents_routes.mjs proves the SHAPE of the surface — which verbs exist and
+// which of them carry a rank gate. This drives the handlers themselves against a
+// fake pool and a fake grade port, so the behaviour the task is judged on is
+// asserted rather than inferred: authority fields refused, a protected scope
+// refused at any rank, an edit landing IN PLACE, and — the one an operator cares
+// about most — disabling actually stopping a fire.
+//
+// The gates are skipped deliberately: a handler is invoked directly with an
+// already-authenticated `req.builder`, because whether requireRank is mounted is
+// a structural question the other file answers, and whether the handler behaves
+// is this one's. No database, no HTTP, no model call.
+//
+// Run:  node tests/agents_write_routes.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+
+const api = require('../src/module-api.js');
+const routes = require('../modules/agents/routes/agents.js');
+
+let pass = 0;
+let fail = 0;
+const t = async (name, fn) => {
+  try { await fn(); pass += 1; console.log(`  ok  ${name}`); }
+  catch (e) { fail += 1; console.log(`  FAIL ${name}\n      ${e.stack || e.message}`); }
+};
+
+// ---- fakes ----------------------------------------------------------------
+
+const ARMED = Object.freeze({
+  id: 7, name: 'historian', title: 'Historian', persona: 'PERSONA',
+  trigger_type: 'on-demand', trigger_spec: {}, model_tier: 'default',
+  scope_modules: [], scope_paths: [], scope_violation: null,
+  source: 'db', provenance: 'instance', author_rank: 'metic', author_builder_id: 5,
+  source_path: null, last_synced_at: null, enabled: true,
+  created_at: 'T0', updated_at: 'T0',
+});
+
+function fakePool({ definition = ARMED, runId = 42 } = {}) {
+  const calls = [];
+  return {
+    calls,
+    async query(sql, params) {
+      calls.push({ sql, params });
+      // ANCHORED to SELECT. `/FROM agents_definitions/` alone also matches
+      // `DELETE FROM agents_definitions`, so the delete branch below was never
+      // reached and the delete test passed whether or not the file-ownership
+      // wall was there — found by removing that wall and watching only the PATCH
+      // test go red.
+      if (/^\s*SELECT[\s\S]*FROM agents_definitions/.test(sql)) {
+        return { rows: definition && (!params || definition.name === params[0]) ? [definition] : [] };
+      }
+      if (/^\s*INSERT INTO agents_runs/.test(sql)) return { rows: [{ id: runId }] };
+      if (/^\s*INSERT INTO agents_definitions/.test(sql)) return { rows: [{ ...ARMED, name: params[0], enabled: false }] };
+      if (/^\s*UPDATE agents_definitions/.test(sql)) return { rows: [{ ...definition, enabled: /enabled = true/.test(sql) }], rowCount: 1 };
+      if (/^\s*DELETE FROM agents_definitions/.test(sql)) return { rows: [], rowCount: 1 };
+      if (/FROM agents_runs/.test(sql)) {
+        // The ownership filter is params[1]; the fake honours it so the IDOR test
+        // exercises the real WHERE clause rather than a stub that ignores it.
+        if (params && params.length > 1 && String(params[1]) !== String(5)) return { rows: [] };
+        return { rows: [{ id: runId, agent_name: 'historian', trigger_ref: 'on-demand:a-builder', trigger_type: 'on-demand', gate_decision: 'go', gate_reason: null, status: 'ok', error_code: null, model: 'opus', cost_usd: '0.5000', duration_ms: 900, output_ref: null, created_at: 'T0', updated_at: 'T1' }] };
+      }
+      return { rows: [], rowCount: 0 };
+    },
+    sqlMatching(re) { return this.calls.filter((c) => re.test(c.sql)); },
+    insertedRun() {
+      const c = this.calls.find((x) => /^\s*INSERT INTO agents_runs/.test(x.sql));
+      if (!c) return null;
+      const cols = c.sql.match(/\(([^)]+)\) VALUES/)[1].split(',').map((s) => s.trim());
+      return Object.fromEntries(cols.map((k, i) => [k, c.params[i]]));
+    },
+  };
+}
+
+function fakeRes() {
+  const out = { status: 200, body: null, failed: null, headers: {} };
+  const res = {
+    headersSent: false,
+    set(k, v) { out.headers[k] = v; return res; },
+    status(code) { out.status = code; return res; },
+    json(body) { out.body = body; res.headersSent = true; return res; },
+    fail(code, statusOrOpts) {
+      const opts = statusOrOpts && typeof statusOrOpts === 'object' ? statusOrOpts : { status: statusOrOpts };
+      out.status = opts.status || 400;
+      out.failed = { code, message: opts.message || null, details: opts.details || null };
+      res.headersSent = true;
+      return res;
+    },
+    out,
+  };
+  return res;
+}
+
+const BUILDER = { id: 5, rank: 'metic', github_login: 'a-builder' };
+const req = (over = {}) => ({ builder: BUILDER, params: {}, body: {}, query: {}, ...over });
+
+// The LAST layer of a route is the handler; the ones before it are the gates,
+// which tests/agents_routes.mjs asserts separately.
+function handler(router, method, path) {
+  const layer = router.stack.filter((l) => l.route)
+    .find((l) => l.route.path === path && l.route.methods[method]);
+  assert.ok(layer, `${method} ${path} is not mounted`);
+  const stack = layer.route.stack;
+  return stack[stack.length - 1].handle;
+}
+
+// Stub the doorway for the duration — module-api's lazy getters are writable.
+const realPool = Object.getOwnPropertyDescriptor(api, 'pool');
+const realResolveOptional = api.resolveOptional;
+const realBranding = api.branding;
+api.branding = () => ({ models: { subagentDefault: 'opus', subagentRoutine: 'haiku' } });
+
+let lastPrompt = null;
+api.resolveOptional = (port) => (port === 'grade' ? {
+  runSubagentCached: async ({ prompt }) => { lastPrompt = prompt; return { stdout: 'THE ANSWER', cost_usd: 0.5 }; },
+} : null);
+
+// ---- invoke: the gate, and what "disable" buys an operator -----------------
+
+console.log('\ninvoke — a refusal is a ledger row, and off means off:');
+
+await t('a DISABLED agent is refused 409, the model is never called, and the no-go is RECORDED', async () => {
+  const pool = fakePool({ definition: { ...ARMED, enabled: false } });
+  api.pool = pool;
+  lastPrompt = null;
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/invoke')(req({ params: { name: 'historian' } }), res);
+
+  assert.equal(res.out.status, 409);
+  assert.equal(res.out.failed.code, 'agent_refused');
+  assert.match(res.out.failed.message, /not enabled/);
+  assert.equal(res.out.failed.details.run_id, '42', 'the refusal is on the record and the caller is told where');
+
+  const row = pool.insertedRun();
+  assert.equal(row.gate_decision, 'no-go');
+  assert.equal(row.status, 'skipped');
+  assert.equal(row.model, null, 'a no-go spawned nothing, so it has no model');
+  assert.equal(lastPrompt, null, 'the model was never called');
+});
+
+await t('an EVENT agent cannot be asked a question, and that refusal is recorded too', async () => {
+  const pool = fakePool({ definition: { ...ARMED, trigger_type: 'event', trigger_spec: { event: 'task.shipped' } } });
+  api.pool = pool;
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/invoke')(req({ params: { name: 'historian' } }), res);
+  assert.equal(res.out.status, 409);
+  assert.match(res.out.failed.message, /not 'on-demand'/);
+  assert.equal(pool.insertedRun().gate_decision, 'no-go');
+});
+
+await t('an ARMED agent answers 202 with a run id and a poll URL, never 200', async () => {
+  const pool = fakePool();
+  api.pool = pool;
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/invoke')(
+    req({ params: { name: 'historian' }, body: { input: 'why?' } }), res,
+  );
+  assert.equal(res.out.status, 202, 'a 60-120s fire cannot be a synchronous 200');
+  assert.equal(res.out.body.run_id, '42');
+  assert.equal(res.out.body.poll, '/agent-runs/42');
+  const row = pool.insertedRun();
+  assert.equal(row.gate_decision, 'go');
+  assert.equal(row.status, 'pending');
+  assert.equal(row.trigger_ref, 'on-demand:a-builder', 'attributed to the live session, not a flag');
+  assert.equal(row.requested_by_builder_id, 5);
+});
+
+await t('the persona and the caller\'s input BOTH reach the model', async () => {
+  api.pool = fakePool();
+  lastPrompt = null;
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/invoke')(
+    req({ params: { name: 'historian' }, body: { input: 'why is it so?' } }), res,
+  );
+  // The fire continues behind the 202, so let the microtask queue drain.
+  await new Promise((r) => setImmediate(r));
+  assert.match(lastPrompt, /PERSONA/);
+  assert.match(lastPrompt, /why is it so\?/);
+});
+
+await t('a body key the schema does not name is refused rather than ignored', async () => {
+  api.pool = fakePool();
+  const res = fakeRes();
+  // Stand in for the real validateOrRespond, which is what enforces `strict`.
+  await handler(routes(), 'post', '/agents/:name/invoke')(
+    req({ params: { name: 'BAD NAME' } }), res,
+  );
+  assert.equal(res.out.failed.code, 'invalid_agent_name');
+});
+
+// ---- create: the authority fields, and the stricter scope wall -------------
+
+console.log('\ncreate — nothing in the body decides authority:');
+
+await t('a body naming author_rank is REFUSED by name, not silently stripped', async () => {
+  api.pool = fakePool();
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents')(
+    req({ body: { name: 'x', persona: 'p', trigger_type: 'on-demand', author_rank: 'archon' } }), res,
+  );
+  assert.equal(res.out.status, 400);
+  assert.equal(res.out.failed.code, 'server_owned_field');
+  assert.match(res.out.failed.message, /author_rank/);
+  assert.match(res.out.failed.message, /live DB rank/);
+});
+
+await t('`enabled: true` in a create body is refused — creating and arming are separate acts', async () => {
+  api.pool = fakePool();
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents')(
+    req({ body: { name: 'x', persona: 'p', trigger_type: 'on-demand', enabled: true } }), res,
+  );
+  assert.equal(res.out.failed.code, 'server_owned_field');
+  assert.match(res.out.failed.message, /enable/);
+});
+
+await t('the stamped rank is the CALLER\'S live rank, and the row lands db/instance/disarmed', async () => {
+  const pool = fakePool();
+  api.pool = pool;
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents')(
+    req({ body: { name: 'librarian', persona: 'p', trigger_type: 'on-demand' } }), res,
+  );
+  assert.equal(res.out.status, 201, JSON.stringify(res.out.failed));
+  const [insert] = pool.sqlMatching(/INSERT INTO agents_definitions/);
+  assert.ok(insert, 'nothing was inserted');
+  assert.match(insert.sql, /'db','instance'/, "source and provenance are literals, not inputs");
+  assert.match(insert.sql, /,false\)/, 'a new definition lands DISARMED');
+  assert.equal(insert.params[8], 'metic', "author_rank is req.builder.rank");
+  assert.equal(insert.params[9], 5, 'author_builder_id is the session builder');
+});
+
+await t('a scope reaching a protected surface is refused 403 — at Metic AND at Archon', async () => {
+  for (const rank of ['metic', 'archon']) {
+    api.pool = fakePool();
+    const res = fakeRes();
+    await handler(routes(), 'post', '/agents')(
+      req({
+        builder: { ...BUILDER, rank },
+        body: { name: 'sneaky', persona: 'p', trigger_type: 'on-demand', scope_paths: ['src/bongos/auth.js'] },
+      }),
+      res,
+    );
+    assert.equal(res.out.status, 403, `${rank} was not refused`);
+    assert.equal(res.out.failed.code, 'scope_reaches_protected_surface');
+    assert.match(res.out.failed.message, /single call/);
+  }
+});
+
+// ---- edit: in place, and never over a file-owned row -----------------------
+
+console.log('\nedit — one row per name, and the sync keeps its own:');
+
+await t('a PATCH is an UPDATE, never an INSERT — editing does not make a second row', async () => {
+  const pool = fakePool();
+  api.pool = pool;
+  const res = fakeRes();
+  await handler(routes(), 'patch', '/agents/:name')(
+    req({ params: { name: 'historian' }, body: { title: 'Renamed' } }), res,
+  );
+  assert.equal(res.out.status, 200, JSON.stringify(res.out.failed));
+  assert.equal(pool.sqlMatching(/INSERT INTO agents_definitions/).length, 0);
+  const [update] = pool.sqlMatching(/UPDATE agents_definitions/);
+  assert.match(update.sql, /WHERE name = \$1 AND source = 'db'/,
+    'the source check is repeated structurally so a race cannot overwrite a file row');
+});
+
+await t('a FILE-owned definition is not editable here, and the reason names the file', async () => {
+  api.pool = fakePool({ definition: { ...ARMED, source: 'file', source_path: '.claude/agents/historian.md' } });
+  const res = fakeRes();
+  await handler(routes(), 'patch', '/agents/:name')(
+    req({ params: { name: 'historian' }, body: { title: 'Renamed' } }), res,
+  );
+  assert.equal(res.out.status, 409);
+  assert.equal(res.out.failed.code, 'agent_owned_by_file');
+  assert.match(res.out.failed.message, /historian\.md/);
+});
+
+await t('renaming is refused — the name is the identity every other surface keys on', async () => {
+  api.pool = fakePool();
+  const res = fakeRes();
+  await handler(routes(), 'patch', '/agents/:name')(
+    req({ params: { name: 'historian' }, body: { name: 'other' } }), res,
+  );
+  assert.equal(res.out.failed.code, 'agent_rename_unsupported');
+});
+
+await t('DELETE removes a db-authored definition and leaves the LEDGER alone', async () => {
+  const pool = fakePool();
+  api.pool = pool;
+  const res = fakeRes();
+  await handler(routes(), 'delete', '/agents/:name')(req({ params: { name: 'historian' } }), res);
+  assert.equal(res.out.status, 200, JSON.stringify(res.out.failed));
+  assert.equal(res.out.body.deleted, 'historian');
+  const [del] = pool.sqlMatching(/DELETE FROM agents_definitions/);
+  assert.match(del.sql, /AND source = 'db'/, 'the source check is repeated structurally against a race');
+  // What this agent spent and did outlives the definition it pointed at:
+  // agents_runs.definition_id is ON DELETE SET NULL with a denormalized name.
+  assert.equal(pool.sqlMatching(/DELETE FROM agents_runs/).length, 0);
+});
+
+await t('DELETE refuses a file-owned row — the next deploy would just recreate it', async () => {
+  api.pool = fakePool({ definition: { ...ARMED, source: 'file', source_path: '.claude/agents/historian.md' } });
+  const res = fakeRes();
+  await handler(routes(), 'delete', '/agents/:name')(req({ params: { name: 'historian' } }), res);
+  assert.equal(res.out.status, 409);
+  assert.equal(res.out.failed.code, 'agent_owned_by_file');
+});
+
+// ---- arm / disarm: the operator act ---------------------------------------
+
+console.log('\narm and disarm — the one write that works on a committed definition:');
+
+await t('enable WORKS on a file-sourced definition — this is how a committed agent runs at all', async () => {
+  const pool = fakePool({ definition: { ...ARMED, source: 'file', source_path: '.claude/agents/historian.md', enabled: false } });
+  api.pool = pool;
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/enable')(req({ params: { name: 'historian' } }), res);
+  assert.equal(res.out.status, 200, JSON.stringify(res.out.failed));
+  assert.equal(res.out.body.agent.armed, true);
+});
+
+await t('a FLAGGED definition cannot be armed, and the refusal quotes the wall', async () => {
+  api.pool = fakePool({ definition: { ...ARMED, enabled: false, scope_violation: 'scope_paths: "src/bongos/auth.js" reaches a protected surface' } });
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/enable')(req({ params: { name: 'historian' } }), res);
+  assert.equal(res.out.status, 409);
+  assert.equal(res.out.failed.code, 'agent_scope_flagged');
+  assert.match(res.out.failed.message, /protected surface/);
+});
+
+await t('a definition with NO author_rank has no authority to act with', async () => {
+  api.pool = fakePool({ definition: { ...ARMED, enabled: false, author_rank: null } });
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/enable')(req({ params: { name: 'historian' } }), res);
+  assert.equal(res.out.status, 409);
+  assert.equal(res.out.failed.code, 'agent_has_no_author');
+  assert.match(res.out.failed.message, /ADR 0016/);
+});
+
+await t('the arming UPDATE re-checks both invariants in its own WHERE clause', async () => {
+  const pool = fakePool({ definition: { ...ARMED, enabled: false } });
+  api.pool = pool;
+  await handler(routes(), 'post', '/agents/:name/enable')(req({ params: { name: 'historian' } }), fakeRes());
+  const [update] = pool.sqlMatching(/UPDATE agents_definitions SET enabled = true/);
+  assert.match(update.sql, /scope_violation IS NULL/);
+  assert.match(update.sql, /author_rank IS NOT NULL/);
+});
+
+await t('disable works on any definition and reports it disarmed', async () => {
+  api.pool = fakePool();
+  const res = fakeRes();
+  await handler(routes(), 'post', '/agents/:name/disable')(req({ params: { name: 'historian' } }), res);
+  assert.equal(res.out.status, 200, JSON.stringify(res.out.failed));
+  assert.equal(res.out.body.agent.armed, false);
+});
+
+// ---- the ledger read ------------------------------------------------------
+
+console.log('\nthe ledger read — the row, and the answer while it is still held:');
+
+await t('a run is served with its cost as a number and its answer beside it, not inside it', async () => {
+  const pool = fakePool();
+  api.pool = pool;
+  // Fire first so there is an answer to collect, then read the same router.
+  const router = routes();
+  await handler(router, 'post', '/agents/:name/invoke')(req({ params: { name: 'historian' } }), fakeRes());
+  await new Promise((r) => setImmediate(r));
+  await new Promise((r) => setImmediate(r));
+
+  const res = fakeRes();
+  await handler(router, 'get', '/agent-runs/:id')(req({ params: { id: '42' } }), res);
+  assert.equal(res.out.status, 200, JSON.stringify(res.out.failed));
+  const { run } = res.out.body;
+  assert.equal(run.id, '42');
+  assert.equal(run.cost_usd, 0.5, 'numeric, not the pg numeric string');
+  assert.equal(run.output_ref, null, 'the ledger holds a pointer, never the text');
+  assert.equal(run.answer, 'THE ANSWER', 'the answer travels beside the row, under its own key');
+});
+
+await t('a run from another router instance is not readable through this one', async () => {
+  api.pool = fakePool();
+  const res = fakeRes();
+  await handler(routes(), 'get', '/agent-runs/:id')(req({ params: { id: '42' } }), res);
+  assert.equal(res.out.body.run.answer, null, 'the hold is per-router; the LEDGER is the shared record');
+});
+
+await t('IDOR: another builder\'s run is filtered out IN SQL, and answers 404 not 403', async () => {
+  // The id is a sequential integer PK. Without the ownership filter any
+  // authenticated builder could walk the ledger and read someone else's held
+  // answer — model output generated from THEIR question — plus the github_login
+  // in trigger_ref. Filtering in the WHERE clause rather than after the read is
+  // the point: a post-read comparison is one early return away from leaking, and
+  // it would already have handed the row to hold.take() on the way past.
+  const pool = fakePool();
+  api.pool = pool;
+  const res = fakeRes();
+  await handler(routes(), 'get', '/agent-runs/:id')(
+    req({ params: { id: '42' }, builder: { ...BUILDER, id: 999 } }), res,
+  );
+  const [read] = pool.sqlMatching(/FROM agents_runs/);
+  assert.match(read.sql, /AND requested_by_builder_id = \$2/, 'the filter must be in SQL');
+  assert.deepEqual(read.params, [42, 999], 'filtered by the LIVE session builder, not by anything sent');
+  // 404, not 403: distinguishing "not yours" from "not there" makes the id space
+  // enumerable one bit at a time.
+  assert.equal(res.out.status, 404);
+  assert.equal(res.out.failed.code, 'agent_run_not_found');
+});
+
+console.log('\nthe spend ceiling — a fire costs about a dollar and 202 means nobody waits:');
+
+await t('a builder past the ceiling is refused 429 BEFORE anything is read or fired', async () => {
+  const pool = fakePool();
+  api.pool = pool;
+  routes.fireBudget.reset();
+  const router = routes();
+  const fire = handler(router, 'post', '/agents/:name/invoke');
+  const limit = routes.fireBudget.limit;
+  for (let i = 0; i < limit; i++) await fire(req({ params: { name: 'historian' } }), fakeRes());
+
+  // Let the backgrounded fires from the loop finish writing their ledger rows —
+  // the 202 returns before the UPDATE lands, so a snapshot taken too early keeps
+  // growing under the assertion below.
+  for (let i = 0; i < 5; i++) await new Promise((r) => setImmediate(r));
+  const before = pool.calls.length;
+  const res = fakeRes();
+  await fire(req({ params: { name: 'historian' } }), res);
+  assert.equal(res.out.status, 429);
+  assert.equal(res.out.failed.code, 'rate_limited');
+  assert.equal(res.out.failed.details.scope, 'agent-fire');
+  assert.ok(res.out.failed.details.retry_after_seconds > 0);
+  assert.equal(pool.calls.length, before, 'a refused fire must not even read the registry');
+  routes.fireBudget.reset();
+});
+
+await t('the ceiling is per BUILDER — one builder cannot exhaust another\'s', async () => {
+  api.pool = fakePool();
+  routes.fireBudget.reset();
+  const fire = handler(routes(), 'post', '/agents/:name/invoke');
+  for (let i = 0; i < routes.fireBudget.limit; i++) {
+    await fire(req({ params: { name: 'historian' } }), fakeRes());
+  }
+  const other = fakeRes();
+  await fire(req({ params: { name: 'historian' }, builder: { ...BUILDER, id: 777 } }), other);
+  assert.equal(other.out.status, 202, 'a second builder still has their own window');
+  routes.fireBudget.reset();
+});
+
+// ---- restore --------------------------------------------------------------
+if (realPool) Object.defineProperty(api, 'pool', realPool);
+api.resolveOptional = realResolveOptional;
+api.branding = realBranding;
+
+console.log(`\n${pass} passed, ${fail} failed`);
+if (fail > 0) process.exit(1);