@cohortapp/agent-sdk 2.10.0 → 2.11.1

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

@@ -0,0 +1,361 @@
+/**
+ * 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.mjs

@@ -0,0 +1,176 @@
+/**
+ * lib/org/tool-access.mjs — the ONE place a curated tool's access tier is decided.
+ *
+ * THE BUG THIS MODULE EXISTS TO CLOSE. `access` used to be a hand-written
+ * literal on all 133 `ORG_TOOLS` entries with nothing deriving it and nothing
+ * checking it. Two failures follow from that, and both are silent:
+ *
+ *   (1) THE ADMIN TRAPDOOR. `lib/tool-definitions.js` routes by tier:
+ *       `access:"read"` lands in `lookupTools` and therefore in EVERY tier
+ *       including least-privilege "default"; `"write"` lands in `writeToolsCeo`
+ *       + `writeToolsLeadership`; `"admin"` is withheld from
+ *       `writeToolsLeadership` AND from the default lookup set — i.e. CEO ONLY.
+ *       tool-surface.mjs's own header says what that costs: "for a leadership
+ *       or default agent, 'the long tail is reachable via org_rpc' is false — a
+ *       capability with no curated tool simply does not exist for it." A tool
+ *       parked at "admin" is in exactly that state: shipped, tested, and dark
+ *       for every seat below the operator's console. The rule against it was
+ *       enforced only by per-delta, HAND-LISTED name arrays in
+ *       tool-surface.test.mjs (ten names for the mandate/subagent/preference
+ *       delta), so it policed the tools whose author remembered to list them
+ *       and nothing else. Every future family was unpoliced by default — the
+ *       same "only guards what someone already thought to claim" hole hq
+ *       plugged with its closed-set family assertion. `ADMIN_TOOLS` below
+ *       inverts it: the admin tier is a CLOSED, NAMED set of two escape
+ *       hatches, asserted table-wide, so parking a ninth capability there now
+ *       takes a deliberate edit to this file.
+ *
+ *   (2) THE TYPO TRAPDOOR. The tier buckets are built with exact string
+ *       equality (`t.access === access`), so an entry whose `access` is absent
+ *       or mis-cased ("Read", " write ") matches NO bucket and reaches NO
+ *       native tier — not ceo, not leadership, not voice, not default — while
+ *       the MCP plane keeps publishing it (lib/mcp/server.mjs reads `access`
+ *       only to set `readOnlyHint`). That is the tool-side twin of the
+ *       caller-side footgun `normalizeAccessLevel` was written to kill —
+ *       "'CEO' (instead of 'ceo') yielded zero tools, a silent UNDER-privilege
+ *       footgun" — fixed on one side of the same comparison and never on the
+ *       other. `normalizeToolAccess` closes it: normalise the casing, and send
+ *       a genuinely unrecognised value to the MOST-restricted tier with a loud
+ *       warning, so a table typo fails CLOSED and NOISY instead of silently
+ *       vanishing from every surface.
+ *
+ * THE DERIVATION (`expectedAccessFor`). For an rpc-bound tool the tier is not
+ * a matter of taste — hq gates on the method's SCOPE, so the native clamp must
+ * mirror the scope lane or it either withholds a tool hq would have allowed or
+ * offers one hq will refuse. `*.read` → "read" (a VIEWER-tier seat can call it,
+ * so it belongs in the lookup set every tier gets); everything else → "write".
+ *
+ * NOTE THE RULE IT IS *NOT*: `sideEffecting ? "write" : "read"`. That reading
+ * is wrong for seven tools already in the table and would demote every one of
+ * them. `knowledge.search`, `directory.ask`, `branding.renderTemplate` /
+ * `rewriteInVoice` / `exportKit` are side-effecting (audited reads: they land
+ * on the chain or the AI meter) yet ride a `.read` scope 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`. Conversely `artifact.create`
+ * / `artifact.act` are not side-effecting yet ride `messaging.write`. Scope is
+ * the authority both planes actually resolve against; `sideEffecting` governs
+ * idempotency keys and chain appends, not privilege. Verified: the scope rule
+ * holds for all 120 rpc-bound curated tools with ZERO exceptions, which is why
+ * this module ships no allowlist.
+ *
+ * Node builtins only. ESM. Imported by lib/org/tool-surface.mjs,
+ * lib/org/resource-tools.mjs and lib/tool-definitions.js — deliberately a leaf
+ * module (it imports only the vendored protocol) so none of those three can
+ * form an import cycle through it.
+ *
+ * @module lib/org/tool-access
+ */
+
+"use strict";
+
+import { methodDef } from "./protocol.mjs";
+
+/**
+ * The tiers `lib/tool-definitions.js` buckets by. Ordered LEAST → MOST
+ * restricted, which is what makes `MOST_RESTRICTED_ACCESS` a definition rather
+ * than a magic string.
+ * @type {readonly string[]}
+ */
+export const TOOL_ACCESS_LEVELS = Object.freeze(["read", "write", "admin"]);
+
+/** The tier an unrecognised `access` falls back to: CEO-only. Fail closed. */
+export const MOST_RESTRICTED_ACCESS = "admin";
+
+/**
+ * A Set whose mutators throw. `Object.freeze(new Set(...))` does NOT do this —
+ * a Set's contents are internal slots, not own properties, so a frozen Set is
+ * still `.add()`-able. For a table that decides who reaches which tier, "the
+ * allowlist can be widened at runtime with no diff" is not an acceptable
+ * property, so the mutators are replaced rather than merely frozen.
+ * @param {Iterable<string>} values
+ * @returns {ReadonlySet<string>}
+ */
+function sealedSet(values) {
+  const s = new Set(values);
+  const refuse = (op) => () => {
+    throw new TypeError(`this set is sealed — ${op}() would change an access decision with no diff`);
+  };
+  for (const op of ["add", "delete", "clear"]) {
+    Object.defineProperty(s, op, { value: refuse(op), writable: false, configurable: false });
+  }
+  return Object.freeze(s);
+}
+
+/**
+ * The ONLY curated tools allowed at `access:"admin"` — the two operator escape
+ * hatches. Both are `binding.kind:"local"`: they take a method/path name and
+ * validate it against the frozen protocol table before any network I/O, so
+ * they are a console over the whole surface rather than one capability.
+ *
+ * Nothing that represents a CAPABILITY belongs here. A capability at "admin" is
+ * reachable by the CEO tier alone, which is indistinguishable — for a
+ * leadership or default agent — from never having shipped it.
+ * @type {ReadonlySet<string>}
+ */
+export const ADMIN_TOOLS = sealedSet(["org_rpc", "org_read"]);
+
+/**
+ * The access tier an rpc-bound curated tool MUST carry, derived from the
+ * vendored protocol declaration rather than chosen by the table author.
+ *
+ * @param {string} method - Full dotted protocol method, e.g. "resource.list".
+ * @returns {"read"|"write"|null} null when the method is not in the vendored
+ *   table (an older protocol, or a typo — the caller decides how loud to be).
+ */
+export function expectedAccessFor(method) {
+  const def = methodDef(method);
+  if (!def) return null;
+  return String(def.scope || "").endsWith(".read") ? "read" : "write";
+}
+
+/**
+ * Normalise a TOOL's declared access tier (the mirror of
+ * `normalizeAccessLevel`, which normalises the CALLER's level).
+ *
+ * Known tiers are returned unchanged. Case/whitespace variants normalise.
+ * Anything else — missing, misspelled, non-string — coerces to the
+ * most-restricted tier and warns, so the entry stays reachable by the operator
+ * and visibly wrong, instead of falling out of every bucket unannounced.
+ *
+ * @param {unknown} access - The raw `access` field from a tool descriptor.
+ * @param {string} [toolName] - Named in the warning so the bad row is findable.
+ * @param {(msg: string) => void} [warn] - Injectable sink (tests assert on it).
+ * @returns {"read"|"write"|"admin"}
+ */
+export function normalizeToolAccess(access, toolName = "<unnamed>", warn = console.warn) {
+  const key = typeof access === "string" ? access.trim().toLowerCase() : "";
+  if (TOOL_ACCESS_LEVELS.includes(key)) return /** @type {"read"|"write"|"admin"} */ (key);
+  try {
+    warn(
+      `[tool-access] Tool ${JSON.stringify(String(toolName))} declares unknown access ` +
+        `${JSON.stringify(access)}; coercing to most-restricted ` +
+        `"${MOST_RESTRICTED_ACCESS}". Fix the table entry — an unrecognised tier used to ` +
+        `drop the tool from EVERY native access level silently.`,
+    );
+  } catch {
+    /* a throwing sink must not take the tool table down */
+  }
+  return MOST_RESTRICTED_ACCESS;
+}
+
+/**
+ * Partition a tool table into the three native tiers, EXHAUSTIVELY — every
+ * entry lands in exactly one bucket, which is the property the old
+ * `filter(t => t.access === x)` triple did not have.
+ *
+ * @param {Array<{name?:string, access?:unknown}>} tools
+ * @param {(msg: string) => void} [warn]
+ * @returns {{read: object[], write: object[], admin: object[]}}
+ */
+export function partitionByAccess(tools, warn = console.warn) {
+  const out = { read: [], write: [], admin: [] };
+  for (const t of tools || []) {
+    out[normalizeToolAccess(t && t.access, t && t.name, warn)].push(t);
+  }
+  return out;
+}