@cohortapp/agent-sdk 2.3.0

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

@@ -0,0 +1,589 @@
+/**
+ * tool-surface.test.mjs — the curated org tool table + shared executor.
+ *
+ * Hermetic: every network call rides an injected fetchImpl; the send-gate is an
+ * injected stub; env is snapshotted/cleared so a developer's COHORT_* vars
+ * can't leak in. Run: node --test lib/org/tool-surface.test.mjs
+ */
+
+"use strict";
+
+import { test, before, after } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  ORG_TOOLS,
+  getOrgTools,
+  isOrgTool,
+  orgToolDef,
+  OUTBOUND_METHODS,
+  emailFamilyAvailable,
+  artifactFamilyAvailable,
+  deskFamilyAvailable,
+  resolveOrgToolConfig,
+  executeOrgTool,
+  DEFAULT_COHORT_BASE,
+} from "./tool-surface.mjs";
+import { methodDef, PROTOCOL_VERSION } from "./protocol.mjs";
+
+// ── 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",
+  "COHORT_AGENT_ID", "COHORT_AGENT_EMAIL",
+];
+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];
+  }
+});
+
+// ── helpers ────────────────────────────────────────────────────────────────
+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;
+}
+
+// ── table shape ────────────────────────────────────────────────────────────
+
+test("table: curated 28 + 5 email + 5 artifact + 69 desk tools, snake_case names, valid access + schemas", () => {
+  // 2026-08 mobile-parity delta: +5 mail (report_spam/react/move_mailbox/
+  // summarise/ask) and +3 asks (files/calendar/crm) → desk 56 → 64; the
+  // call-working-sessions delta adds the 5 calls-desk tools → 69.
+  assert.equal(ORG_TOOLS.length, 107, "28 curated + 5 email + 5 artifact + 69 desk");
+  assert.equal(ORG_TOOLS.filter((t) => t.desk).length, 69, "exactly sixty-nine desk tools");
+  assert.equal(ORG_TOOLS.filter((t) => t.email).length, 5, "exactly five email tools");
+  assert.equal(ORG_TOOLS.filter((t) => t.artifact).length, 5, "exactly five artifact tools");
+  for (const t of ORG_TOOLS) {
+    assert.match(t.name, /^[a-z0-9_]+$/, `${t.name} snake_case`);
+    assert.ok(["read", "write", "admin"].includes(t.access), `${t.name} access`);
+    assert.ok(t.description && t.description.length > 10, `${t.name} described`);
+    assert.equal(t.input_schema.type, "object", `${t.name} schema object`);
+    assert.ok(t.binding && ["rpc", "read", "local"].includes(t.binding.kind), `${t.name} binding`);
+    if (t.binding.kind === "rpc") {
+      assert.ok(methodDef(t.binding.method), `${t.name} binds a real protocol method (${t.binding.method})`);
+    }
+  }
+});
+
+test("OUTBOUND_METHODS is DERIVED from outbound:true tools (messaging/email/mail-desk/share-step sends)", () => {
+  assert.deepEqual([...OUTBOUND_METHODS].sort(), ["calling.appShareAct", "email.draftSend", "email.send", "messaging.send"]);
+  const outboundTools = ORG_TOOLS.filter((t) => t.outbound).map((t) => t.name).sort();
+  assert.deepEqual(outboundTools, ["email_draft_send", "email_send", "messaging_send", "org_call_share_step"]);
+});
+
+test("email gating: family present in the vendored protocol → tools active; override excludes", () => {
+  // The email family landed in the vendored protocol (sync-protocol phase 1).
+  assert.equal(emailFamilyAvailable(), true, "vendored protocol carries email.send");
+  assert.equal(getOrgTools().length, 107);
+  const without = getOrgTools({ emailAvailable: false });
+  assert.equal(without.length, 102);
+  assert.ok(!without.some((t) => t.email), "email tools excluded when family absent");
+});
+
+test("artifact gating: family present → tools active; override excludes (email precedent)", () => {
+  assert.equal(artifactFamilyAvailable(), true, "vendored protocol carries artifact.act");
+  const without = getOrgTools({ artifactAvailable: false });
+  assert.equal(without.length, 102);
+  assert.ok(!without.some((t) => t.artifact), "artifact tools excluded when family absent");
+  const neither = getOrgTools({ emailAvailable: false, artifactAvailable: false, desksAvailable: false });
+  assert.equal(neither.length, 28, "all additive families off → the 28 always-on tools");
+});
+
+test("isOrgTool / orgToolDef cover the full table; unknown names rejected", () => {
+  for (const t of ORG_TOOLS) assert.equal(isOrgTool(t.name), true);
+  assert.equal(isOrgTool("slack_send"), false);
+  assert.equal(isOrgTool(""), false);
+  assert.equal(orgToolDef("org_rpc").access, "admin");
+});
+
+// ── config resolution (§1.4) ───────────────────────────────────────────────
+
+test("resolveOrgToolConfig: config base/token honoured; default base when nothing names one", () => {
+  const cfg = resolveOrgToolConfig({ orgConfig: CFG, agentRoot: "/tmp/none" });
+  assert.equal(cfg.base, "https://org.example");
+  assert.equal(cfg.token, "nlk_secret");
+  assert.equal(cfg.orgId, "acme");
+  const bare = resolveOrgToolConfig({ orgConfig: {}, agentRoot: "/tmp/none" });
+  assert.equal(bare.base, DEFAULT_COHORT_BASE);
+  assert.equal(bare.token, "");
+});
+
+test("resolveOrgToolConfig: COHORT_BASE env wins over config base (env-first)", () => {
+  process.env.COHORT_BASE = "https://env.example/";
+  try {
+    const cfg = resolveOrgToolConfig({ orgConfig: CFG, agentRoot: "/tmp/none" });
+    assert.equal(cfg.base, "https://env.example", "env base wins, trailing slash stripped");
+  } finally {
+    delete process.env.COHORT_BASE;
+  }
+});
+
+// ── executor: basics ───────────────────────────────────────────────────────
+
+test("executeOrgTool: unknown tool → NOT_FOUND frame, never a throw", async () => {
+  const frame = await executeOrgTool("nope_tool", {}, { orgConfig: CFG, agentRoot: "/tmp/none" });
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "NOT_FOUND");
+});
+
+test("executeOrgTool: missing token → clear UNAUTHORIZED frame for network tools", async () => {
+  const fetchImpl = fakeFetch();
+  const frame = await executeOrgTool("org_directory", {}, { orgConfig: {}, agentRoot: "/tmp/none", fetchImpl });
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "UNAUTHORIZED");
+  assert.match(frame.error.message, /COHORT_API_TOKEN/);
+  assert.equal(fetchImpl.calls.length, 0, "no network attempted");
+});
+
+test("org_describe: offline, no network, family filter works", async () => {
+  const fetchImpl = fakeFetch();
+  const frame = await executeOrgTool("org_describe", {}, { orgConfig: {}, agentRoot: "/tmp/none", fetchImpl });
+  assert.equal(frame.ok, true);
+  assert.equal(frame.result.protocolVersion, PROTOCOL_VERSION);
+  assert.ok(frame.result.methods.length >= 200, "full method table listed");
+  assert.ok(frame.result.reads.length >= 13, "reads listed");
+  const fam = await executeOrgTool("org_describe", { family: "board" }, { orgConfig: {}, agentRoot: "/tmp/none" });
+  assert.ok(fam.result.methods.every((m) => m.family === "board"));
+  assert.deepEqual(fam.result.families, ["board"]);
+  assert.equal(fetchImpl.calls.length, 0);
+});
+
+// ── executor: rpc + read bindings ──────────────────────────────────────────
+
+test("rpc binding: messaging_history POSTs /api/v1/messaging.history with Bearer + org pin", async () => {
+  const fetchImpl = fakeFetch({ ok: true, result: { messages: [] } });
+  const frame = await executeOrgTool("messaging_history", { channelId: "C1", limit: 5 }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
+  assert.equal(frame.ok, true);
+  assert.equal(fetchImpl.calls.length, 1);
+  const { url, init } = fetchImpl.calls[0];
+  assert.equal(url, "https://org.example/api/v1/messaging.history");
+  assert.equal(init.method, "POST");
+  assert.equal(init.headers.authorization, "Bearer nlk_secret");
+  assert.equal(init.headers["x-org-id"], "acme");
+  assert.deepEqual(JSON.parse(init.body), { channelId: "C1", limit: 5 });
+});
+
+test("read binding: board_ready GETs /api/v1/board.ready and normalises the bare payload", async () => {
+  const fetchImpl = fakeFetch({ items: [{ id: "w1" }] });
+  const frame = await executeOrgTool("board_ready", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
+  assert.equal(frame.ok, true);
+  assert.deepEqual(frame.result, { items: [{ id: "w1" }] });
+  assert.equal(fetchImpl.calls[0].init.method, "GET");
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/board\.ready$/);
+});
+
+test("org_events_tail: cursor + clamped limit ride the query string", async () => {
+  const fetchImpl = fakeFetch({ events: [] });
+  await executeOrgTool("org_events_tail", { cursor: 7, limit: 9999 }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/events\?cursor=7&limit=500$/, "limit clamped to 500");
+});
+
+test("approval_wait: requires approvalId; dispatches the bounded long-poll", async () => {
+  const missing = await executeOrgTool("approval_wait", {}, { orgConfig: CFG, agentRoot: "/tmp/none" });
+  assert.equal(missing.error.code, "BAD_REQUEST");
+  const fetchImpl = fakeFetch({ id: "a1", status: "approved" });
+  const frame = await executeOrgTool("approval_wait", { approvalId: "a1" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
+  assert.equal(frame.ok, true);
+  assert.match(fetchImpl.calls[0].url, /approval\.wait\?id=a1&timeoutMs=55000/);
+});
+
+// ── executor: send-gate parity (§1.5a) ─────────────────────────────────────
+
+test("messaging_send: screened through the send-gate, clientMsgId auto-minted", async () => {
+  const screened = [];
+  const fetchImpl = fakeFetch({ ok: true, result: { messageId: "m1" } });
+  const frame = await executeOrgTool(
+    "messaging_send",
+    { channelId: "C9", body: "hello org" },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (o) => { screened.push(o); return { allow: true }; } },
+  );
+  assert.equal(frame.ok, true);
+  assert.equal(screened.length, 1, "screenOutbound ran");
+  assert.equal(screened[0].recipient, "C9");
+  assert.equal(screened[0].text, "hello org");
+  const body = JSON.parse(fetchImpl.calls[0].init.body);
+  assert.ok(body.clientMsgId && body.clientMsgId.length >= 8, "clientMsgId auto-minted");
+  assert.ok(fetchImpl.calls[0].init.headers["x-idempotency-key"], "dispatcher idempotency key present");
+});
+
+test("messaging_send: a vetoing gate blocks BEFORE any network", async () => {
+  const fetchImpl = fakeFetch();
+  const frame = await executeOrgTool(
+    "messaging_send",
+    { channelId: "C9", body: "As an AI I love this" },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async () => ({ allow: false, reason: "banned-phrase" }) },
+  );
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "FORBIDDEN_SCOPE");
+  assert.match(frame.error.message, /banned-phrase/);
+  assert.equal(fetchImpl.calls.length, 0, "blocked before dispatch");
+});
+
+test("a THROWING gate fails open with a counted diagnostic (adapter parity)", async () => {
+  const counted = [];
+  const fetchImpl = fakeFetch({ ok: true, result: {} });
+  const frame = await executeOrgTool(
+    "messaging_send",
+    { channelId: "C9", body: "hi" },
+    {
+      orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl,
+      screenImpl: async () => { throw new Error("gate exploded"); },
+      bumpImpl: (name, attrs) => counted.push({ name, attrs }),
+    },
+  );
+  assert.equal(frame.ok, true, "fail-open");
+  assert.equal(counted[0].name, "channel.send_gate.fail_open");
+});
+
+// ── executor: escape hatches ───────────────────────────────────────────────
+
+test("org_rpc: unknown method rejected against the protocol table, NO network", async () => {
+  const fetchImpl = fakeFetch();
+  const frame = await executeOrgTool("org_rpc", { method: "nope.nothing" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "NOT_FOUND");
+  assert.equal(fetchImpl.calls.length, 0, "validated before any network");
+});
+
+test("org_rpc: escape-hatch parity — messaging.send through org_rpc is ALSO screened", async () => {
+  const screened = [];
+  const fetchImpl = fakeFetch({ ok: true, result: {} });
+  await executeOrgTool(
+    "org_rpc",
+    { method: "messaging.send", params: { channelId: "C2", body: "raw lane" } },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (o) => { screened.push(o); return { allow: true }; } },
+  );
+  assert.equal(screened.length, 1, "escape hatch screened");
+  assert.match(screened[0].text, /raw lane/, "params blob screened");
+  // and a blocked verdict stops the dispatch
+  const fetch2 = fakeFetch();
+  const blocked = await executeOrgTool(
+    "org_rpc",
+    { method: "email.send", params: { to: ["x@y.z"], text: "leak" } },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: fetch2, screenImpl: async () => ({ allow: false, reason: "no" }) },
+  );
+  assert.equal(blocked.ok, false);
+  assert.equal(fetch2.calls.length, 0);
+});
+
+test("org_rpc: non-outbound method dispatches unscreened with optional idempotencyKey", async () => {
+  const screened = [];
+  const fetchImpl = fakeFetch({ ok: true, result: { got: 1 } });
+  const frame = await executeOrgTool(
+    "org_rpc",
+    { method: "member.get", params: { memberId: "m-1" }, idempotencyKey: "k-1" },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (o) => { screened.push(o); return { allow: true }; } },
+  );
+  assert.equal(frame.ok, true);
+  assert.equal(screened.length, 0, "reads/non-outbound never screened");
+  assert.match(fetchImpl.calls[0].url, /member\.get$/);
+});
+
+test("org_read: validated against READS; query params encoded; unknown path rejected", async () => {
+  const fetchImpl = fakeFetch({ events: [] });
+  const frame = await executeOrgTool("org_read", { path: "events", query: { cursor: 3, limit: 10 } }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
+  assert.equal(frame.ok, true);
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/events\?cursor=3&limit=10$/);
+  const bad = await executeOrgTool("org_read", { path: "not-a-read" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
+  assert.equal(bad.error.code, "NOT_FOUND");
+  assert.equal(fetchImpl.calls.length, 1, "unknown path never dispatched");
+});
+
+// ── executor: email tools ──────────────────────────────────────────────────
+
+test("email_send: idempotencyId auto-minted; screened; rides email.send", async () => {
+  const screened = [];
+  const fetchImpl = fakeFetch({ ok: true, result: { status: "queued", messageId: "e1" } });
+  const frame = await executeOrgTool(
+    "email_send",
+    { to: ["a@ext.com"], subject: "Hi", text: "Body" },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (o) => { screened.push(o); return { allow: true }; } },
+  );
+  assert.equal(frame.ok, true);
+  assert.equal(screened[0].recipient, "a@ext.com");
+  assert.match(screened[0].text, /Subject: Hi/);
+  const body = JSON.parse(fetchImpl.calls[0].init.body);
+  assert.ok(body.idempotencyId && body.idempotencyId.length >= 8, "idempotencyId auto-minted");
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/email\.send$/);
+});
+
+test("email tools degrade to NOT_FOUND when the family is gated off (pre-sync install)", async () => {
+  const fetchImpl = fakeFetch();
+  const frame = await executeOrgTool("email_inbox", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, emailAvailable: false });
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "NOT_FOUND");
+  assert.match(frame.error.message, /upgrade/i);
+  assert.equal(fetchImpl.calls.length, 0);
+});
+
+// ── executor: artifact tools ───────────────────────────────────────────────
+
+test("artifact_create: clientMsgId auto-minted; unscreened (in-thread, not outbound); rides artifact.create", async () => {
+  const screened = [];
+  const envelope = { genui: "v2", artifact: { class: "ops.status", version: 1, state: "complete", source: { kind: "native" } }, actions: [], root: { type: "card", tone: "neutral", blocks: [] } };
+  const fetchImpl = fakeFetch({ ok: true, result: { artifactId: "a1", messageId: "m1" } });
+  const frame = await executeOrgTool(
+    "artifact_create",
+    { channelId: "C1", envelope },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (o) => { screened.push(o); return { allow: true }; } },
+  );
+  assert.equal(frame.ok, true);
+  assert.deepEqual(frame.result, { artifactId: "a1", messageId: "m1" });
+  assert.equal(screened.length, 0, "artifact posts are in-thread — never send-gate screened");
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/artifact\.create$/);
+  const body = JSON.parse(fetchImpl.calls[0].init.body);
+  assert.ok(body.clientMsgId && body.clientMsgId.length >= 8, "clientMsgId auto-minted");
+  assert.deepEqual(body.envelope, envelope, "envelope posted verbatim");
+  assert.equal(fetchImpl.calls[0].init.headers["x-idempotency-key"], undefined, "sideEffecting:false — no dispatcher key; the service dedupes on clientMsgId");
+});
+
+test("artifact_act: idempotencyKey auto-minted when absent, caller's key preserved; held result is a NORMAL frame", async () => {
+  const fetchImpl = fakeFetch({ ok: true, result: { held: true, approvalId: "ap-1" } });
+  const frame = await executeOrgTool(
+    "artifact_act",
+    { artifactId: "a1", action: "approve" },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl },
+  );
+  assert.equal(frame.ok, true, "approval-held is a result, not an error");
+  assert.equal(frame.result.held, true);
+  assert.equal(frame.result.approvalId, "ap-1");
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/artifact\.act$/);
+  const minted = JSON.parse(fetchImpl.calls[0].init.body);
+  assert.ok(minted.idempotencyKey && minted.idempotencyKey.length >= 8, "idempotencyKey auto-minted");
+  // A caller-supplied key (retry / post-approval re-invoke) rides through untouched.
+  await executeOrgTool(
+    "artifact_act",
+    { artifactId: "a1", action: "approve", idempotencyKey: "approve-a1" },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl },
+  );
+  assert.equal(JSON.parse(fetchImpl.calls[1].init.body).idempotencyKey, "approve-a1");
+});
+
+test("artifact reads ride their rpc methods; tools degrade to NOT_FOUND when the family is gated off", async () => {
+  const fetchImpl = fakeFetch({ ok: true, result: { items: [] } });
+  await executeOrgTool("artifact_list", { channelId: "C1", state: "complete" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/artifact\.list$/);
+  await executeOrgTool("artifact_catalog", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
+  assert.match(fetchImpl.calls[1].url, /\/api\/v1\/artifact\.catalog$/);
+  const gated = fakeFetch();
+  const frame = await executeOrgTool("artifact_get", { artifactId: "a1" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: gated, artifactAvailable: false });
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "NOT_FOUND");
+  assert.match(frame.error.message, /upgrade/i);
+  assert.equal(gated.calls.length, 0);
+});
+
+// ── executor: directory + design desks (2026-07) ───────────────────────────
+
+test("directory/design desks gate on their OWN probe, independently of the other desks", () => {
+  // One DESK_PROBES line lights a desk up on BOTH planes; a desk whose probe
+  // method is absent from the vendored protocol must not register.
+  assert.equal(deskFamilyAvailable("directory"), true, "vendored protocol carries directory.search");
+  assert.equal(deskFamilyAvailable("design"), true, "vendored protocol carries branding.getFoundation");
+  assert.equal(deskFamilyAvailable("nope"), false, "unknown desk → default-deny");
+  assert.equal(ORG_TOOLS.filter((t) => t.desk === "directory").length, 14);
+  assert.equal(ORG_TOOLS.filter((t) => t.desk === "design").length, 8);
+  // Neither desk smuggles an outbound lane in: no directory/design tool sends.
+  assert.equal(ORG_TOOLS.filter((t) => (t.desk === "directory" || t.desk === "design") && t.outbound).length, 0);
+});
+
+test("directory reads/writes ride their rpc methods; a side-effecting write carries a dispatcher key", async () => {
+  const fetchImpl = fakeFetch({ ok: true, result: { people: [] } });
+  const o = { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl };
+  await executeOrgTool("directory_search", { q: "hartmann" }, o);
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/directory\.search$/);
+  assert.deepEqual(JSON.parse(fetchImpl.calls[0].init.body), { q: "hartmann" });
+  assert.equal(fetchImpl.calls[0].init.headers["x-idempotency-key"], undefined, "sideEffecting:false read sends no key");
+
+  await executeOrgTool("directory_list_people", { relationship: "client", sort: "touch" }, o);
+  assert.match(fetchImpl.calls[1].url, /\/api\/v1\/directory\.listPeople$/);
+
+  await executeOrgTool(
+    "directory_propose_capture",
+    { kind: "PERSON", payload: { person: { displayName: "Dr. Lena Hartmann" } }, source: "MAIL", sourceFingerprint: "sig:abc" },
+    o,
+  );
+  assert.match(fetchImpl.calls[2].url, /\/api\/v1\/directory\.proposeCapture$/);
+  assert.ok(
+    fetchImpl.calls[2].init.headers["x-idempotency-key"],
+    "sideEffecting write gets a fresh dispatcher key",
+  );
+  assert.equal(JSON.parse(fetchImpl.calls[2].init.body).sourceFingerprint, "sig:abc");
+});
+
+test("design tools ride branding.*; the costed quote call posts budgetCents:0 verbatim", async () => {
+  const fetchImpl = fakeFetch({ ok: true, result: { slots: [], costCents: 0 } });
+  const o = { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl };
+  await executeOrgTool("design_foundation", { historyLimit: 5 }, o);
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/branding\.getFoundation$/);
+  await executeOrgTool("design_voice", {}, o);
+  assert.match(fetchImpl.calls[1].url, /\/api\/v1\/branding\.getVoice$/);
+  await executeOrgTool("design_generate_image", { budgetCents: 0 }, o);
+  assert.match(fetchImpl.calls[2].url, /\/api\/v1\/branding\.generateImage$/);
+  assert.equal(JSON.parse(fetchImpl.calls[2].init.body).budgetCents, 0, "0 is the QUOTE call, not a falsy drop");
+});
+
+test("design_rewrite_in_voice produces copy and is NEVER send-gate screened", async () => {
+  // It returns a rewrite; it sends nothing. Whatever the caller does with the
+  // result is screened at the send verb, not here.
+  const screened = [];
+  const fetchImpl = fakeFetch({ ok: true, result: { text: "Rewritten.", costCents: 3 } });
+  const frame = await executeOrgTool(
+    "design_rewrite_in_voice",
+    { text: "we are excited to announce" },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (x) => { screened.push(x); return { allow: true }; } },
+  );
+  assert.equal(frame.ok, true);
+  assert.equal(screened.length, 0);
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/branding\.rewriteInVoice$/);
+});
+
+test("directory/design tools degrade to NOT_FOUND when their desk is gated off (pre-sync install)", async () => {
+  for (const name of ["directory_search", "design_foundation"]) {
+    const gated = fakeFetch();
+    const frame = await executeOrgTool(name, { q: "x" }, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: gated, desksAvailable: false });
+    assert.equal(frame.ok, false, `${name} gated`);
+    assert.equal(frame.error.code, "NOT_FOUND");
+    assert.match(frame.error.message, /upgrade/i);
+    assert.equal(gated.calls.length, 0, `${name} never dispatched`);
+  }
+});
+
+// ── executor: calls desk (call working sessions, 2026-08) ──────────────────
+
+test("calls desk gates on calling.appShareStart; five tools, one outbound verb", () => {
+  assert.equal(deskFamilyAvailable("calls"), true, "vendored protocol carries calling.appShareStart");
+  const calls = ORG_TOOLS.filter((t) => t.desk === "calls");
+  assert.equal(calls.length, 5);
+  // The share-step verb is the block's ONE outbound lane: its highlight notes
+  // and typed text are read by every human on the call.
+  assert.deepEqual(calls.filter((t) => t.outbound).map((t) => t.name), ["org_call_share_step"]);
+  assert.deepEqual(
+    calls.filter((t) => t.access === "read").map((t) => t.name).sort(),
+    ["org_call_events", "org_call_visual_context"],
+  );
+});
+
+test("org_call_share_start/end ride their rpc methods with a fresh dispatcher key", async () => {
+  const fetchImpl = fakeFetch({ ok: true, result: { sessionId: "s1" } });
+  const o = { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl };
+  const frame = await executeOrgTool(
+    "org_call_share_start",
+    { callId: "call-1", surface: { kind: "doc", ref: "f-1", title: "Q3 plan" } },
+    o,
+  );
+  assert.equal(frame.ok, true);
+  assert.equal(frame.result.sessionId, "s1");
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/calling\.appShareStart$/);
+  assert.ok(fetchImpl.calls[0].init.headers["x-idempotency-key"], "sideEffecting write gets a fresh dispatcher key");
+  assert.deepEqual(JSON.parse(fetchImpl.calls[0].init.body).surface, { kind: "doc", ref: "f-1", title: "Q3 plan" });
+
+  await executeOrgTool("org_call_share_end", { callId: "call-1", sessionId: "s1" }, o);
+  assert.match(fetchImpl.calls[1].url, /\/api\/v1\/calling\.appShareEnd$/);
+});
+
+test("org_call_share_step: screened through the send-gate (notes + typed text), then rides calling.appShareAct", async () => {
+  const screened = [];
+  const fetchImpl = fakeFetch({ ok: true, result: { seq: 4 } });
+  const steps = [
+    { k: "scroll", anchor: "block:3" },
+    { k: "highlight", anchor: "block:3", note: "revenue line" },
+    { k: "type", anchor: "block:4", text: "Draft summary" },
+  ];
+  const frame = await executeOrgTool(
+    "org_call_share_step",
+    { callId: "call-1", sessionId: "s1", steps },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async (x) => { screened.push(x); return { allow: true }; } },
+  );
+  assert.equal(frame.ok, true);
+  assert.equal(screened.length, 1, "screenOutbound ran");
+  assert.equal(screened[0].recipient, "call-1");
+  assert.match(screened[0].text, /revenue line/);
+  assert.match(screened[0].text, /Draft summary/);
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/calling\.appShareAct$/);
+  assert.deepEqual(JSON.parse(fetchImpl.calls[0].init.body).steps, steps);
+
+  // A vetoing gate blocks BEFORE any network — messaging_send parity.
+  const fetch2 = fakeFetch();
+  const blocked = await executeOrgTool(
+    "org_call_share_step",
+    { callId: "call-1", sessionId: "s1", steps: [{ k: "highlight", anchor: "block:1", note: "As an AI" }] },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: fetch2, screenImpl: async () => ({ allow: false, reason: "banned-phrase" }) },
+  );
+  assert.equal(blocked.ok, false);
+  assert.equal(blocked.error.code, "FORBIDDEN_SCOPE");
+  assert.equal(fetch2.calls.length, 0, "blocked before dispatch");
+});
+
+test("calls reads ride their rpc methods without a dispatcher key", async () => {
+  const fetchImpl = fakeFetch({ ok: true, result: { events: [] } });
+  const o = { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl };
+  await executeOrgTool("org_call_visual_context", { callId: "call-1", limit: 10 }, o);
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/calling\.getVisualContext$/);
+  assert.equal(fetchImpl.calls[0].init.headers["x-idempotency-key"], undefined, "sideEffecting:false read sends no key");
+  await executeOrgTool("org_call_events", { callId: "call-1" }, o);
+  assert.match(fetchImpl.calls[1].url, /\/api\/v1\/calling\.getCallEvents$/);
+});
+
+test("calls tools degrade to NOT_FOUND when the desk is gated off (pre-sync install)", async () => {
+  const gated = fakeFetch();
+  const frame = await executeOrgTool(
+    "org_call_share_start",
+    { callId: "call-1", surface: { kind: "doc", ref: "f-1" } },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: gated, desksAvailable: false },
+  );
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "NOT_FOUND");
+  assert.match(frame.error.message, /upgrade/i);
+  assert.equal(gated.calls.length, 0, "never dispatched");
+});
+
+// ── executor: org_whoami ───────────────────────────────────────────────────
+
+test("org_whoami: unenrolled → config summary with member:null + note, never an error", async () => {
+  const frame = await executeOrgTool("org_whoami", {}, { orgConfig: {}, agentRoot: "/tmp/none" });
+  assert.equal(frame.ok, true);
+  assert.equal(frame.result.member, null);
+  assert.equal(frame.result.tokenPresent, false);
+  assert.match(frame.result.note, /setup --only org|COHORT_API_TOKEN|COHORT_ORG_ID/);
+});
+
+test("org_whoami: resolves the member via the org-data whoami lane; token never in the result", async () => {
+  const fetchImpl = fakeFetch({ slug: "astra", displayName: "Astra", agentEmail: "astra@agents.example" });
+  const frame = await executeOrgTool("org_whoami", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
+  assert.equal(frame.ok, true);
+  assert.equal(frame.result.member.slug, "astra");
+  assert.equal(frame.result.tokenPresent, true);
+  assert.equal(frame.result.protocolVersion, PROTOCOL_VERSION);
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/org\/whoami\?orgId=acme/);
+  assert.ok(!JSON.stringify(frame).includes("nlk_secret"), "token never surfaces");
+});
+
+test("org_whoami: unresolvable member degrades to summary + hint note (no error frame)", async () => {
+  const fetchImpl = fakeFetch({ error: { code: "NOT_FOUND", message: "ambiguous" } }, { status: 404, ok: false });
+  const frame = await executeOrgTool("org_whoami", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl });
+  assert.equal(frame.ok, true);
+  assert.equal(frame.result.member, null);
+  assert.match(frame.result.note, /COHORT_AGENT_ID/);
+});
+
+test("org_whoami: COHORT_AGENT_ID hint routes to the direct member GET", async () => {
+  const fetchImpl = fakeFetch({ slug: "astra", displayName: "Astra" });
+  const frame = await executeOrgTool("org_whoami", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, env: { COHORT_AGENT_ID: "astra" } });
+  assert.equal(frame.ok, true);
+  assert.match(fetchImpl.calls[0].url, /\/api\/v1\/org\/members\/astra\?orgId=acme/);
+});