@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/org/registry.test.mjs

@@ -1,100 +0,0 @@
-/**
- * registry.test.mjs — tests for the file-backed org registry.
- * Run: node --test lib/org/registry.test.mjs
- */
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import {
-  buildSelfEntry, currentFocus, writeSelfEntry, readSelfEntry, readDirectory,
-} from "./registry.mjs";
-
-function tmp() { return mkdtempSync(join(tmpdir(), "org-registry-")); }
-function repo() {
-  const root = tmp();
-  mkdirSync(join(root, "config"), { recursive: true });
-  return root;
-}
-
-test("buildSelfEntry: maps identity + company + profile + focus", () => {
-  const entry = buildSelfEntry({
-    identity: {
-      firstName: "Alex", fullName: "Alex Chen", title: "Chief of Staff",
-      email: "alex@example.com", slackMemberId: "U1", repoSlug: "alex-ai",
-      function: "executive-operator", altitude: "c-suite",
-      principal: { fullName: "Sam Smith", title: "CEO" },
-    },
-    company: { name: "Northwind", domain: "northwind.example.com" },
-    profile: { label: "C-Suite Executive Operator", towers: [{ id: "t1", name: "Strategic Initiatives", focus: "x" }] },
-    focus: [{ title: "Ship Q3 plan", queue: "action-stack", priority: "high" }],
-    nowMs: Date.parse("2026-06-03T12:00:00Z"),
-  });
-  assert.equal(entry.id, "alex-ai");
-  assert.equal(entry.fullName, "Alex Chen");
-  assert.equal(entry.archetype.function, "executive-operator");
-  assert.equal(entry.archetype.label, "C-Suite Executive Operator");
-  assert.equal(entry.towers.length, 1);
-  assert.equal(entry.towers[0].name, "Strategic Initiatives");
-  assert.equal(entry.focus[0].title, "Ship Q3 plan");
-  assert.equal(entry.principal.fullName, "Sam Smith");
-  assert.equal(entry.company.name, "Northwind");
-  assert.equal(entry.updatedAt, "2026-06-03T12:00:00.000Z");
-});
-
-test("buildSelfEntry: derives repo + id from firstName when no repoSlug", () => {
-  const entry = buildSelfEntry({ identity: { firstName: "Robin" } });
-  assert.equal(entry.repo, "robin-ai");
-  assert.equal(entry.id, "robin-ai");
-});
-
-test("currentFocus: uses injected items, capped", async () => {
-  const items = Array.from({ length: 9 }, (_, i) => ({ title: `t${i}`, queue: "q", priority: "normal" }));
-  const focus = await currentFocus("/x", { items, limit: 3 });
-  assert.equal(focus.length, 3);
-});
-
-test("currentFocus: reads + filters queue YAML (open only)", async () => {
-  const root = repo();
-  try {
-    mkdirSync(join(root, "state", "queues"), { recursive: true });
-    writeFileSync(join(root, "state", "queues", "action-stack.yaml"),
-      "items:\n  - title: Open one\n    status: open\n    priority: high\n  - title: Done one\n    status: done\n");
-    const focus = await currentFocus(root, { queues: ["action-stack"], limit: 5 });
-    assert.equal(focus.length, 1);
-    assert.equal(focus[0].title, "Open one");
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("writeSelfEntry/readSelfEntry: round-trip", () => {
-  const root = repo();
-  try {
-    const e = buildSelfEntry({ identity: { firstName: "Alex", repoSlug: "alex-ai" } });
-    assert.equal(writeSelfEntry(root, e), true);
-    assert.equal(readSelfEntry(root).id, "alex-ai");
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});
-
-test("readDirectory: merges known-agents peers + self; self + synced override", () => {
-  const root = repo();
-  try {
-    writeFileSync(join(root, "config", "known-agents.json"), JSON.stringify({
-      agents: [{ name: "Bob", fullName: "Bob Lee", slackId: "U2", role: "Head of Eng", repo: "bob-ai" }],
-    }));
-    // synced richer peer overrides the static known-agents entry
-    mkdirSync(join(root, "state", "org", "peers"), { recursive: true });
-    writeFileSync(join(root, "state", "org", "peers", "bob.json"), JSON.stringify({ id: "bob-ai", name: "Bob", title: "VP Engineering", source: "cohort" }));
-    writeSelfEntry(root, buildSelfEntry({ identity: { firstName: "Alex", repoSlug: "alex-ai", title: "CoS" } }));
-    const dir = readDirectory(root);
-    const bob = dir.find((d) => d.id === "bob-ai");
-    const alex = dir.find((d) => d.id === "alex-ai");
-    assert.equal(bob.title, "VP Engineering", "synced peer overrides known-agents role");
-    assert.equal(bob.source, "cohort");
-    assert.equal(alex.self, true, "self entry flagged");
-    assert.equal(dir.length, 2);
-  } finally { rmSync(root, { recursive: true, force: true }); }
-});

package/lib/org/resource-tools.test.mjs

@@ -1,361 +0,0 @@
-/**
- * resource-tools.test.mjs — the venture-deliverable desk, and the parity that
- * keeps it from drifting the way every other desk already has.
- *
- * WHAT THIS FILE IS FOR. hq exposes 239 responder ops across 11 families;
- * maestro's curated table exposed 69 desk tools across 9 — files 29 vs 7, crm
- * 44 vs 8. One cause: both tool tables are hand-written, so the moment one side
- * moves, the other is stale and NOTHING is red. The `resource_*` block is
- * generated from the vendored protocol declaration instead, and the assertions
- * below are what make "generated" a guarantee rather than a claim: they read
- * the protocol table at run time and demand the tool block match it exactly, in
- * BOTH directions.
- *
- * It also pins the access-level rule the wave was called on: reads at "read"
- * (org.read → every tier including least-privilege "default"), writes at
- * "write" (org.write → ceo + leadership), and NOTHING at "admin", which is the
- * CEO-only escape-hatch tier where a capability is exactly as unreachable as
- * the org_rpc route a curated tool exists to replace.
- *
- * Hermetic: no network, no env dependence beyond the snapshot below.
- * Run: node --test lib/org/resource-tools.test.mjs
- */
-
-"use strict";
-
-import { test, before, after } from "node:test";
-import assert from "node:assert/strict";
-
-import { METHODS, methodDef } from "./protocol.mjs";
-import { ADMIN_TOOLS, expectedAccessFor } from "./tool-access.mjs";
-import {
-  RESOURCE_FAMILY,
-  RESOURCE_DESK,
-  RESOURCE_PRESENTATION,
-  RESOURCE_TOOLS,
-  buildResourceTools,
-  toolNameForMethod,
-} from "./resource-tools.mjs";
-import { ORG_TOOLS, getOrgTools, orgToolDef, executeOrgTool, deskFamilyAvailable } from "./tool-surface.mjs";
-import { getToolNamesForAccessLevel } from "../tool-definitions.js";
-
-// ── env hygiene ────────────────────────────────────────────────────────────
-const ENV_KEYS = [
-  "COHORT_API_TOKEN", "COHORT_TOKEN", "COHORT_API_KEY", "COHORT_ORG_ID",
-  "COHORT_BASE", "COHORT_API_URL", "COHORT_AGENT_ROOT", "AGENT_ROOT",
-];
-const saved = {};
-before(() => {
-  for (const k of ENV_KEYS) { saved[k] = process.env[k]; delete process.env[k]; }
-});
-after(() => {
-  for (const k of ENV_KEYS) {
-    if (saved[k] === undefined) delete process.env[k];
-    else process.env[k] = saved[k];
-  }
-});
-
-const CFG = { org: { cohort: { enabled: true, base: "https://org.example", orgId: "acme", token: "nlk_secret" } } };
-
-/** fetch stub: records calls, returns a res-frame body. */
-function fakeFetch(body = { ok: true, result: { fine: true } }, { status = 200, ok = true } = {}) {
-  const calls = [];
-  const fn = async (url, init) => {
-    calls.push({ url: String(url), init: init || {} });
-    return { ok, status, json: async () => body, headers: { get: () => undefined } };
-  };
-  fn.calls = calls;
-  return fn;
-}
-
-/** The family, straight from the vendored protocol — the ONLY authority here. */
-const PROTOCOL_OPS = Object.entries(METHODS)
-  .filter(([, d]) => d.family === RESOURCE_FAMILY)
-  .map(([name]) => name);
-
-// ── parity: the block IS the protocol declaration ──────────────────────────
-
-test("parity: one curated tool per registered resource op, and NO extras", () => {
-  // Eight is not a magic number typed here — it is whatever the vendored
-  // protocol declares, which is what makes this an anti-drift test rather than
-  // a second hand-list. It is asserted non-empty so a protocol that lost the
-  // family cannot make this file pass vacuously.
-  assert.ok(PROTOCOL_OPS.length > 0, "the vendored protocol carries a resource family");
-  assert.equal(PROTOCOL_OPS.length, 8, "eight resource methods (list/get + 6 writes)");
-
-  const toolMethods = RESOURCE_TOOLS.map((t) => t.binding.method).sort();
-  assert.deepEqual(
-    toolMethods,
-    [...PROTOCOL_OPS].sort(),
-    "every resource method has exactly one curated tool, and no tool names a method that is not one",
-  );
-  assert.equal(
-    new Set(RESOURCE_TOOLS.map((t) => t.name)).size,
-    RESOURCE_TOOLS.length,
-    "tool names are unique",
-  );
-});
-
-test("parity: every binding names a REAL protocol method, resolved through methodDef", () => {
-  for (const t of RESOURCE_TOOLS) {
-    assert.equal(t.binding.kind, "rpc", `${t.name} is rpc-bound (no local shim to drift)`);
-    const def = methodDef(t.binding.method);
-    assert.ok(def, `${t.name} binds a method the frozen table carries (${t.binding.method})`);
-    assert.equal(def.family, RESOURCE_FAMILY, `${t.name} stays inside its own family`);
-  }
-});
-
-test("parity: access MIRRORS the declaration — sideEffecting false→read, true→write", () => {
-  for (const t of RESOURCE_TOOLS) {
-    const def = methodDef(t.binding.method);
-    assert.equal(
-      t.access,
-      def.sideEffecting ? "write" : "read",
-      `${t.name} access must mirror sideEffecting (${t.binding.method})`,
-    );
-    // Same answer from the scope lane, which is what hq actually gates on. For
-    // this family the two rules coincide exactly (org.read ↔ not side-effecting,
-    // org.write ↔ side-effecting), so asserting both pins the coincidence: a
-    // future resource method that broke it would fail here rather than ship a
-    // tool at a tier hq will refuse.
-    assert.equal(t.access, expectedAccessFor(t.binding.method), `${t.name} access mirrors its scope lane`);
-    assert.match(def.scope, /^org\.(read|write)$/, `${t.binding.method} rides org.read/org.write — no new scope minted`);
-  }
-  assert.deepEqual(
-    RESOURCE_TOOLS.filter((t) => t.access === "read").map((t) => t.name),
-    ["resource_list", "resource_get"],
-    "exactly the two reads",
-  );
-  assert.equal(RESOURCE_TOOLS.filter((t) => t.access === "write").length, 6, "exactly six writes");
-});
-
-test("parity: NOTHING at access:\"admin\", and nothing carries `outbound`", () => {
-  for (const t of RESOURCE_TOOLS) {
-    // access:"admin" is the CEO-only escape-hatch tier. A venture's own
-    // colleagues are default- and leadership-tier agents, so a deliverable verb
-    // parked there would be exactly as dark as the org_rpc route it replaces —
-    // i.e. this whole wave would ship as a no-op for the seats it is for.
-    assert.notEqual(t.access, "admin", `${t.name} must not be admin-tier`);
-    assert.ok(!ADMIN_TOOLS.has(t.name), `${t.name} is not an escape hatch`);
-    // No free text a human reads leaves the org through this desk: a card is
-    // org-internal metadata. The send-gate lane stays messaging_send /
-    // email_send / email_draft_send / org_call_share_step.
-    assert.equal(t.outbound, undefined, `${t.name} is not an outbound-content verb`);
-    assert.equal(t.email, undefined, `${t.name} is not an email tool`);
-    assert.equal(t.integration, undefined, `${t.name} is not an integration proxy`);
-  }
-});
-
-// ── generation, not transcription ──────────────────────────────────────────
-
-test("the block is GENERATED: a protocol method with no presentation still gets a tool", () => {
-  // The point of the generator, proved against a synthetic table. A ninth
-  // resource method must not be able to arrive and be silently absent from the
-  // tool surface — that silence is the 239-vs-69 mechanism. It appears with a
-  // derived description (an under-described capability is a documentation bug;
-  // a MISSING one is the failure this wave exists to fix), and the coverage
-  // test below is what goes red.
-  const synthetic = {
-    ...METHODS,
-    "resource.archive": { family: "resource", scope: "org.write", sideEffecting: true, idempotent: true },
-  };
-  const built = buildResourceTools(synthetic);
-  const archive = built.find((t) => t.binding.method === "resource.archive");
-  assert.ok(archive, "a brand-new family method produces a tool with no edit to the tool file");
-  assert.equal(archive.name, "resource_archive");
-  assert.equal(archive.access, "write", "its tier is derived from its scope, not typed by hand");
-  assert.equal(archive.desk, RESOURCE_DESK);
-  assert.match(archive.description, /add a presentation entry/i, "and it says out loud that it is undescribed");
-});
-
-test("the block is GENERATED: a presentation entry for a NON-family method is never emitted", () => {
-  // The reverse drift: a description left behind after a method was removed
-  // from the protocol must not resurrect a tool that binds a method the frozen
-  // table no longer carries.
-  const withoutDetach = Object.fromEntries(
-    Object.entries(METHODS).filter(([m]) => m !== "resource.detachFile"),
-  );
-  const built = buildResourceTools(withoutDetach);
-  assert.equal(
-    built.find((t) => t.binding.method === "resource.detachFile"),
-    undefined,
-    "a stale presentation entry cannot emit a tool for a method the protocol dropped",
-  );
-  assert.equal(built.length, PROTOCOL_OPS.length - 1);
-});
-
-test("the block is GENERATED: an older vendored protocol degrades to an empty block", () => {
-  const noFamily = Object.fromEntries(
-    Object.entries(METHODS).filter(([, d]) => d.family !== RESOURCE_FAMILY),
-  );
-  assert.deepEqual(buildResourceTools(noFamily), [], "no family → no tools, never a broken binding");
-});
-
-test("presentation covers the family EXACTLY — this is the assertion that goes red on drift", () => {
-  assert.deepEqual(
-    Object.keys(RESOURCE_PRESENTATION).sort(),
-    [...PROTOCOL_OPS].sort(),
-    "every resource method is described, and no description outlives its method",
-  );
-  for (const [method, p] of Object.entries(RESOURCE_PRESENTATION)) {
-    assert.ok(p.title && p.title.length > 3, `${method} titled`);
-    assert.ok(p.description && p.description.length > 80, `${method} described in earnest`);
-    assert.equal(p.input_schema.type, "object", `${method} schema is an object`);
-    assert.ok(p.input_schema.properties, `${method} schema has properties`);
-    assert.ok(Array.isArray(p.input_schema.required), `${method} schema declares required[]`);
-    // Presentation is presentation. A `name`/`access`/`binding` literal here
-    // would be the hand-copy the generator exists to prevent.
-    for (const forbidden of ["name", "access", "binding", "desk"]) {
-      assert.equal(p[forbidden], undefined, `${method} presentation must not hand-write ${forbidden}`);
-    }
-  }
-});
-
-test("tool names are a pure function of the method name", () => {
-  assert.equal(toolNameForMethod("resource.list"), "resource_list");
-  assert.equal(toolNameForMethod("resource.attachFile"), "resource_attach_file");
-  assert.equal(toolNameForMethod("resource.detachFile"), "resource_detach_file");
-  for (const t of RESOURCE_TOOLS) {
-    assert.equal(t.name, toolNameForMethod(t.binding.method), `${t.name} derives from its method`);
-    assert.match(t.name, /^[a-z0-9_]+$/, `${t.name} snake_case`);
-  }
-});
-
-// ── the schemas the model actually sees ────────────────────────────────────
-
-test("the schemas require what hq requires, and nothing hq refuses", () => {
-  // .strict() on the hq side means an unknown key is a BAD_REQUEST, so every
-  // property advertised here has to be one the handler accepts.
-  const req = (n) => orgToolDef(n).input_schema.required;
-  const props = (n) => Object.keys(orgToolDef(n).input_schema.properties);
-
-  // Ref-addressed verbs take EITHER slug OR resourceId, so neither can be
-  // schema-`required` — the "exactly one" rule is a refine, and the
-  // description carries it.
-  for (const n of ["resource_get", "resource_update", "resource_delete", "resource_detach_file"]) {
-    assert.deepEqual(req(n), [], `${n} cannot mark either ref required`);
-    assert.ok(props(n).includes("slug") && props(n).includes("resourceId"), `${n} offers both refs`);
-  }
-  assert.deepEqual(req("resource_create"), ["kind", "title"]);
-  assert.deepEqual(req("resource_reorder"), ["slugs"]);
-  assert.deepEqual(req("resource_attach_file"), ["fileId"]);
-
-  // `source` is server-owned: an agent must never be able to relabel its own
-  // card as "ftlab-portal" and inherit the portal's provenance.
-  assert.ok(!props("resource_create").includes("source"), "create cannot set source");
-  assert.ok(!props("resource_update").includes("source"), "update cannot set source");
-  // slug is the ref AND the portal's re-sync key — renaming it would orphan the
-  // upsert and duplicate the card on the next push.
-  assert.ok(!props("resource_update").includes("slug_new"), "update has no slug rename");
-  // Re-pointing a card at a different drive row is a separately-audited act.
-  assert.ok(!props("resource_update").includes("fileId"), "update cannot re-point the file");
-  assert.equal(orgToolDef("resource_reorder").input_schema.properties.slugs.type, "array");
-});
-
-test("the descriptions carry the semantics the SCHEMA cannot", () => {
-  // A tool schema can say `metadata: object`. It cannot say that a null value
-  // deletes a key, that reorder is total, or that the file survives a delete —
-  // and an agent that does not know those three will destroy delivery
-  // provenance, scramble a catalogue, or tell a human their deck is gone.
-  assert.match(orgToolDef("resource_update").description, /shallow merge/i);
-  assert.match(orgToolDef("resource_update").description, /null is DELETED|null is deleted/i);
-  assert.match(orgToolDef("resource_reorder").description, /TOTAL, not partial/i);
-  assert.match(orgToolDef("resource_reorder").description, /CONFLICT/);
-  assert.match(orgToolDef("resource_delete").description, /fileRetained/);
-  assert.match(orgToolDef("resource_delete").description, /ftlab-portal/);
-  assert.match(orgToolDef("resource_create").description, /CONFLICT/);
-  assert.match(orgToolDef("resource_attach_file").description, /setUrl` defaults to FALSE|defaults to FALSE/i);
-  assert.match(orgToolDef("resource_detach_file").description, /CONFLICT/);
-  // The files bridge is a pointer: say where bytes actually come from.
-  assert.match(orgToolDef("resource_list").description, /files_get|files_doc_read/);
-});
-
-// ── the desk gate + the surrounding table ──────────────────────────────────
-
-test("the desk registers only when the vendored protocol carries the family", () => {
-  assert.equal(deskFamilyAvailable(RESOURCE_DESK), true, "the vendored protocol carries resource.list");
-  for (const t of RESOURCE_TOOLS) assert.equal(t.desk, RESOURCE_DESK, `${t.name} is desk-gated`);
-  // desksAvailable:false is the older-protocol shape — the block disappears
-  // cleanly rather than binding methods the server does not implement.
-  const off = getOrgTools({ desksAvailable: false }).filter((t) => t.desk === RESOURCE_DESK);
-  assert.equal(off.length, 0, "an older protocol drops the block whole");
-  const on = getOrgTools({}).filter((t) => t.desk === RESOURCE_DESK);
-  assert.equal(on.length, PROTOCOL_OPS.length, "and carries all of it when present");
-});
-
-test("the generated block is spliced into ORG_TOOLS itself (both planes see it)", () => {
-  for (const t of RESOURCE_TOOLS) {
-    assert.ok(orgToolDef(t.name), `${t.name} is resolvable by name`);
-    assert.equal(orgToolDef(t.name), ORG_TOOLS.find((x) => x.name === t.name));
-  }
-});
-
-// ── the access-level bug, at its consumer ──────────────────────────────────
-
-test("ACCESS LEVELS: the reads reach EVERY tier; the writes reach ceo + leadership; none is CEO-only", () => {
-  // This is the assertion the wave turns on. lib/tool-definitions.js routes
-  // access:"read" into lookupTools (every tier, including least-privilege
-  // "default"), access:"write" into writeToolsCeo + writeToolsLeadership, and
-  // access:"admin" into writeToolsCeo ALONE. A venture's own colleagues are
-  // default- and leadership-tier agents, so the family is only actually shipped
-  // if it lands in those two surfaces.
-  const ceo = new Set(getToolNamesForAccessLevel("ceo"));
-  const leadership = new Set(getToolNamesForAccessLevel("leadership"));
-  const dflt = new Set(getToolNamesForAccessLevel("default"));
-
-  for (const t of RESOURCE_TOOLS) {
-    assert.ok(ceo.has(t.name), `${t.name} reaches ceo`);
-    assert.ok(leadership.has(t.name), `${t.name} reaches leadership — the tier a venture's colleagues run at`);
-  }
-  assert.ok(dflt.has("resource_list"), "a least-privilege seat can SEE its venture's deliverables");
-  assert.ok(dflt.has("resource_get"), "and open one");
-  for (const t of RESOURCE_TOOLS.filter((x) => x.access === "write")) {
-    assert.ok(!dflt.has(t.name), `${t.name} does not leak into the least-privilege tier`);
-  }
-});
-
-// ── dispatch ───────────────────────────────────────────────────────────────
-
-test("every tool POSTS its protocol method with the params verbatim", async () => {
-  for (const t of RESOURCE_TOOLS) {
-    const fetchImpl = fakeFetch({ ok: true, result: { resources: [] } });
-    const frame = await executeOrgTool(t.name, { probe: 1 }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
-    assert.equal(frame.ok, true, `${t.name} dispatches`);
-    assert.equal(
-      fetchImpl.calls[0].url,
-      `https://org.example/api/v1/${t.binding.method}`,
-      `${t.name} hits its own method`,
-    );
-    const body = JSON.parse(fetchImpl.calls[0].init.body);
-    assert.equal(body.probe, 1, `${t.name} passes params through untouched`);
-    // sideEffecting:true at the dispatcher → a fresh idempotency header per
-    // invocation; the reads must not carry one.
-    const hasKey = Boolean(fetchImpl.calls[0].init.headers["x-idempotency-key"]);
-    assert.equal(hasKey, methodDef(t.binding.method).sideEffecting, `${t.name} idempotency header matches the declaration`);
-  }
-});
-
-test("the desk FAILS CLOSED with no credential — a refusal, never a silent success", async () => {
-  const fetchImpl = fakeFetch();
-  for (const t of RESOURCE_TOOLS) {
-    const frame = await executeOrgTool(t.name, {}, { orgConfig: {}, agentRoot: "/tmp/none", fetchImpl });
-    assert.equal(frame.ok, false, `${t.name} refuses`);
-    assert.equal(frame.error.code, "UNAUTHORIZED");
-  }
-  assert.equal(fetchImpl.calls.length, 0, "nothing dispatched without a credential");
-});
-
-test("a FORBIDDEN from hq surfaces verbatim — the scope gate is the server's answer, not ours", async () => {
-  const fetchImpl = fakeFetch(
-    { ok: false, error: { code: "FORBIDDEN", message: "scope org.write required" } },
-    { ok: false, status: 403 },
-  );
-  const frame = await executeOrgTool(
-    "resource_create",
-    { kind: "deck", title: "Seed deck", url: "https://example.com/deck" },
-    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl },
-  );
-  assert.equal(frame.ok, false);
-  assert.equal(frame.error.code, "FORBIDDEN");
-  assert.match(frame.error.message, /org\.write/);
-});

package/lib/org/tool-access.test.mjs

@@ -1,144 +0,0 @@
-/**
- * tool-access.test.mjs — the access-tier mechanism, and the two silent failures
- * it exists to close.
- *
- * REGRESSION 1 — THE ADMIN TRAPDOOR. `access:"admin"` is the CEO-only tier
- * (lib/tool-definitions.js withholds it from writeToolsLeadership AND from the
- * default lookup set). A CAPABILITY parked there is shipped and dark for every
- * seat below the operator's console — the exact state tool-surface.mjs's header
- * describes when it says "for a leadership or default agent, 'the long tail is
- * reachable via org_rpc' is false". The rule against it used to live in
- * per-delta hand-listed name arrays, so it guarded the names someone
- * remembered. ADMIN_TOOLS makes the tier a closed set instead.
- *
- * REGRESSION 2 — THE TYPO TRAPDOOR. The tiers were bucketed by exact string
- * equality, so an entry whose `access` was missing or mis-cased matched no
- * bucket and reached NO native tier at all, while the MCP plane kept publishing
- * it. That is the tool-side twin of the caller-side footgun `normalizeAccessLevel`
- * already fixes ("'CEO' yielded zero tools, a silent UNDER-privilege footgun").
- * The test below drives the OLD comparison and the NEW one over the same bad
- * row so the difference is on the record.
- *
- * Hermetic, no network, no env. Run: node --test lib/org/tool-access.test.mjs
- */
-
-"use strict";
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import { METHODS } from "./protocol.mjs";
-import {
-  TOOL_ACCESS_LEVELS,
-  MOST_RESTRICTED_ACCESS,
-  ADMIN_TOOLS,
-  expectedAccessFor,
-  normalizeToolAccess,
-  partitionByAccess,
-} from "./tool-access.mjs";
-
-// ── the derivation ─────────────────────────────────────────────────────────
-
-test("expectedAccessFor derives the tier from the protocol SCOPE, not from sideEffecting", () => {
-  assert.equal(expectedAccessFor("resource.list"), "read");
-  assert.equal(expectedAccessFor("resource.create"), "write");
-
-  // The five audited reads: side-effecting (they land on the chain or the AI
-  // meter) yet `.read`-scoped on purpose, because a VIEWER seat may run them —
-  // exactly the ability its human seat has. hq keeps the same list under
-  // AUDITED_READ_SCOPE_WRITES. A sideEffecting-derived rule would demote every
-  // one of them out of the lookup set that every tier gets.
-  for (const m of [
-    "knowledge.search",
-    "directory.ask",
-    "branding.renderTemplate",
-    "branding.rewriteInVoice",
-    "branding.exportKit",
-  ]) {
-    assert.equal(METHODS[m].sideEffecting, true, `${m} is side-effecting`);
-    assert.equal(expectedAccessFor(m), "read", `${m} is nonetheless a read-tier tool`);
-  }
-
-  // The mirror case: not side-effecting, but write-scoped.
-  assert.equal(METHODS["artifact.create"].sideEffecting, false);
-  assert.equal(expectedAccessFor("artifact.create"), "write");
-
-  // Scopes that are neither `.read` nor `.write` (board.work, approval.request,
-  // mandate.propose) are writes — they are not callable by a read-only seat.
-  assert.equal(expectedAccessFor("board.claim"), "write");
-  assert.equal(expectedAccessFor("approval.request"), "write");
-  assert.equal(expectedAccessFor("mandate.propose"), "write");
-
-  // An unknown method is null, not a guess — the caller decides how loud to be.
-  assert.equal(expectedAccessFor("nope.nothing"), null);
-  assert.equal(expectedAccessFor(""), null);
-});
-
-// ── the admin trapdoor ─────────────────────────────────────────────────────
-
-test("ADMIN_TOOLS is the closed set of escape hatches — two names, both consoles", () => {
-  assert.deepEqual([...ADMIN_TOOLS].sort(), ["org_read", "org_rpc"]);
-  assert.equal(ADMIN_TOOLS.has("resource_create"), false);
-  // Frozen: a runtime widening would be a privilege change with no diff.
-  assert.throws(() => ADMIN_TOOLS.add("resource_create"));
-});
-
-// ── the typo trapdoor ──────────────────────────────────────────────────────
-
-test("normalizeToolAccess forgives casing/whitespace — 'Read' must not mean 'nowhere'", () => {
-  for (const good of TOOL_ACCESS_LEVELS) assert.equal(normalizeToolAccess(good, "t", () => {}), good);
-  assert.equal(normalizeToolAccess("Read", "t", () => {}), "read");
-  assert.equal(normalizeToolAccess(" WRITE ", "t", () => {}), "write");
-  assert.equal(normalizeToolAccess("Admin", "t", () => {}), "admin");
-});
-
-test("an unrecognised tier fails CLOSED and NOISY, never invisible", () => {
-  for (const bad of [undefined, null, "", "readonly", 7, {}, []]) {
-    const warnings = [];
-    const got = normalizeToolAccess(bad, "broken_tool", (m) => warnings.push(m));
-    assert.equal(got, MOST_RESTRICTED_ACCESS, `${JSON.stringify(bad)} → most-restricted`);
-    assert.equal(warnings.length, 1, `${JSON.stringify(bad)} warns exactly once`);
-    assert.match(warnings[0], /broken_tool/, "the warning names the bad row so it is findable");
-  }
-});
-
-test("a throwing warn sink cannot take the tool table down", () => {
-  assert.equal(
-    normalizeToolAccess("nonsense", "t", () => {
-      throw new Error("logger exploded");
-    }),
-    MOST_RESTRICTED_ACCESS,
-  );
-});
-
-test("REGRESSION: the old equality bucketing dropped a bad row from EVERY tier", () => {
-  const table = [
-    { name: "good_read", access: "read" },
-    { name: "good_write", access: "write" },
-    { name: "mis_cased", access: "Read" }, // a plausible table typo
-    { name: "no_access" }, // an entry someone forgot to tier
-  ];
-
-  // What the code used to do, verbatim: three independent equality filters.
-  const oldBuckets = ["read", "write", "admin"].map((a) => table.filter((t) => t.access === a));
-  const oldReach = new Set(oldBuckets.flat().map((t) => t.name));
-  assert.equal(oldReach.has("mis_cased"), false, "the old filter lost a mis-cased row…");
-  assert.equal(oldReach.has("no_access"), false, "…and an untiered one");
-  assert.equal(oldReach.size, 2, "two of four tools reached no access level at all, silently");
-
-  // What it does now: an exhaustive partition. Nothing is dropped.
-  const warnings = [];
-  const now = partitionByAccess(table, (m) => warnings.push(m));
-  assert.equal(now.read.length + now.write.length + now.admin.length, table.length, "exhaustive");
-  assert.deepEqual(now.read.map((t) => t.name), ["good_read", "mis_cased"], "casing recovered into its real tier");
-  assert.deepEqual(now.admin.map((t) => t.name), ["no_access"], "the untiered row fails closed, not open");
-  assert.equal(warnings.length, 1, "and exactly the untiered row is reported");
-  assert.match(warnings[0], /no_access/);
-});
-
-test("partitionByAccess survives a null/empty table (fail-open, like the rest of the client)", () => {
-  const empty = partitionByAccess(null, () => {});
-  assert.deepEqual(empty, { read: [], write: [], admin: [] });
-  const nullish = partitionByAccess([null, undefined], () => {});
-  assert.equal(nullish.admin.length, 2, "a null row is tiered, not thrown on");
-});