@cohortapp/agent-sdk 2.3.0

package/lib/tool-definitions.test.mjs

@@ -0,0 +1,437 @@
+/**
+ * tool-definitions.test.mjs — access-control / privilege-escalation tests for
+ * the maestro tool surface (lib/tool-definitions.js).
+ *
+ * The tool-definitions module is the SoT for which Claude API tools are exposed
+ * to a caller given their access level (ceo / leadership / voice / default).
+ * Because the write tools here can send email, place phone calls, and generate
+ * outbound documents, the scoping logic is a privilege boundary: a regression
+ * that leaks a CEO-only write tool into the `default` (read-only) surface is a
+ * real escalation. These tests pin that boundary plus the structural invariants
+ * every tool schema must satisfy to be accepted by the Claude API.
+ *
+ * Pure assertions over the exported functions; the only dependency is
+ * node:test + node:assert and the module under test.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  getToolsForAccessLevel,
+  getToolNamesForAccessLevel,
+  getAllToolsByCategory,
+  normalizeAccessLevel,
+  KNOWN_ACCESS_LEVELS,
+} from "./tool-definitions.js";
+
+// Access levels the module is documented to recognise.
+const KNOWN_LEVELS = ["ceo", "leadership", "voice", "default"];
+
+// Read-only tools must never confer the ability to act. These are the
+// write/side-effecting tools that gate on privilege; none may appear in the
+// `default` surface.
+const WRITE_TOOL_NAMES = new Set([
+  "slack_send",
+  "draft_email",
+  "whatsapp_send",
+  "sms_send",
+  "send_voice_message",
+  "place_voice_call",
+  "queue_update",
+  "create_action_item",
+  "schedule_meeting",
+  "create_reminder",
+  "generate_memo",
+  "generate_report",
+]);
+
+// The most sensitive write tools — CEO-only, must NOT leak down to leadership.
+const CEO_ONLY_WRITE_NAMES = [
+  "whatsapp_send",
+  "sms_send",
+  "place_voice_call",
+  "generate_memo",
+  "generate_report",
+];
+
+/** Resolve a tool by name within an access level's surface (the module has no
+ * direct getToolByName export, so this mirrors how a caller would look one up). */
+function findToolByName(accessLevel, name) {
+  return getToolsForAccessLevel(accessLevel).find((t) => t.name === name);
+}
+
+// ---------------------------------------------------------------------------
+// Each access level returns a defined, non-empty tool set
+// ---------------------------------------------------------------------------
+
+for (const level of KNOWN_LEVELS) {
+  test(`getToolsForAccessLevel("${level}") returns a defined, non-empty array`, () => {
+    const tools = getToolsForAccessLevel(level);
+    assert.ok(Array.isArray(tools), `${level} should return an array`);
+    assert.ok(tools.length > 0, `${level} should expose at least one tool`);
+  });
+
+  test(`getToolNamesForAccessLevel("${level}") matches the tool array`, () => {
+    const names = getToolNamesForAccessLevel(level);
+    const tools = getToolsForAccessLevel(level);
+    assert.ok(Array.isArray(names));
+    assert.equal(names.length, tools.length);
+    assert.deepEqual(names, tools.map((t) => t.name));
+  });
+
+  test(`"${level}" surface has no duplicate tool names`, () => {
+    const names = getToolNamesForAccessLevel(level);
+    assert.equal(new Set(names).size, names.length, `${level} has duplicate tools`);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Unknown access level: least-privilege "default" surface, never empty, no throw
+// (audit M4 + the CEO-case footgun — "CEO" used to yield 0 tools silently)
+// ---------------------------------------------------------------------------
+
+test("unknown access level coerces to the default surface (NOT empty), no throw", () => {
+  let tools;
+  assert.doesNotThrow(() => {
+    tools = getToolsForAccessLevel("intern");
+  });
+  assert.ok(Array.isArray(tools));
+  assert.ok(tools.length > 0, "unknown level must not yield an empty tool set");
+  assert.deepEqual(tools, getToolsForAccessLevel("default"));
+});
+
+test("undefined / null / empty / numeric access levels coerce to default, no throw", () => {
+  const defaultTools = getToolsForAccessLevel("default");
+  for (const bad of [undefined, null, "", 42, {}, []]) {
+    let tools;
+    assert.doesNotThrow(() => {
+      tools = getToolsForAccessLevel(bad);
+    }, `access level ${JSON.stringify(bad)} should not throw`);
+    assert.ok(Array.isArray(tools));
+    assert.deepEqual(
+      tools,
+      defaultTools,
+      `access level ${JSON.stringify(bad)} should fall back to default`,
+    );
+  }
+});
+
+test("access-level lookups are case/whitespace-insensitive (CEO === ceo)", () => {
+  // The CEO-case footgun: "CEO" previously yielded 0 tools (silent under-privilege).
+  const upper = getToolNamesForAccessLevel("CEO");
+  const lower = getToolNamesForAccessLevel("ceo");
+  assert.ok(upper.length > 0, "'CEO' must not yield an empty tool set");
+  assert.deepEqual(upper, lower);
+  assert.deepEqual(getToolsForAccessLevel("  Ceo  "), getToolsForAccessLevel("ceo"));
+  assert.deepEqual(
+    getToolNamesForAccessLevel(" Leadership "),
+    getToolNamesForAccessLevel("leadership"),
+  );
+});
+
+test("normalizeAccessLevel maps casing/whitespace to known keys", () => {
+  assert.equal(normalizeAccessLevel("CEO"), "ceo");
+  assert.equal(normalizeAccessLevel("  Ceo  "), "ceo");
+  assert.equal(normalizeAccessLevel("LEADERSHIP"), "leadership");
+  assert.equal(normalizeAccessLevel("Voice"), "voice");
+  assert.equal(normalizeAccessLevel("default"), "default");
+});
+
+test("normalizeAccessLevel coerces unknown/invalid input to least-privilege default", () => {
+  for (const bad of ["intern", "", null, undefined, 42, {}, []]) {
+    assert.equal(
+      normalizeAccessLevel(bad),
+      "default",
+      `${JSON.stringify(bad)} should normalise to default`,
+    );
+  }
+});
+
+test("known access levels return unchanged tool sets (no privilege change)", () => {
+  // Lock the privilege boundary: default must never gain a write tool, and the
+  // ceo surface must remain a superset of leadership.
+  const ceo = getToolNamesForAccessLevel("ceo");
+  const leadership = new Set(getToolNamesForAccessLevel("leadership"));
+  const def = new Set(getToolNamesForAccessLevel("default"));
+  assert.ok(ceo.includes("slack_send"), "ceo retains communication write tools");
+  assert.ok(!def.has("slack_send"), "default must not gain a write tool");
+  for (const name of leadership) {
+    assert.ok(
+      new Set(ceo).has(name),
+      `leadership tool "${name}" must also exist at ceo`,
+    );
+  }
+});
+
+test("KNOWN_ACCESS_LEVELS lists exactly the configured levels", () => {
+  assert.ok(Array.isArray(KNOWN_ACCESS_LEVELS));
+  for (const level of ["ceo", "leadership", "voice", "default"]) {
+    assert.ok(
+      KNOWN_ACCESS_LEVELS.includes(level),
+      `KNOWN_ACCESS_LEVELS should include ${level}`,
+    );
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Privilege boundaries — no escalation
+// ---------------------------------------------------------------------------
+
+test("default (read-only) surface contains NO write/side-effecting tools", () => {
+  const names = new Set(getToolNamesForAccessLevel("default"));
+  for (const write of WRITE_TOOL_NAMES) {
+    assert.equal(
+      names.has(write),
+      false,
+      `default access must not expose write tool "${write}"`,
+    );
+  }
+});
+
+test("default surface is a strict subset of both leadership and ceo surfaces", () => {
+  const defaultNames = new Set(getToolNamesForAccessLevel("default"));
+  const leadershipNames = new Set(getToolNamesForAccessLevel("leadership"));
+  const ceoNames = new Set(getToolNamesForAccessLevel("ceo"));
+
+  for (const name of defaultNames) {
+    assert.ok(leadershipNames.has(name), `leadership missing read tool "${name}"`);
+    assert.ok(ceoNames.has(name), `ceo missing read tool "${name}"`);
+  }
+  // Strict subset: higher levels strictly add capability.
+  assert.ok(leadershipNames.size > defaultNames.size, "leadership should add tools over default");
+  assert.ok(ceoNames.size > defaultNames.size, "ceo should add tools over default");
+});
+
+test("leadership surface is a subset of ceo (no leadership-only tool exceeds ceo)", () => {
+  const leadershipNames = getToolNamesForAccessLevel("leadership");
+  const ceoNames = new Set(getToolNamesForAccessLevel("ceo"));
+  for (const name of leadershipNames) {
+    assert.ok(
+      ceoNames.has(name),
+      `leadership tool "${name}" is not present in ceo — privilege inversion`,
+    );
+  }
+});
+
+test("ceo has strictly more capability than leadership", () => {
+  const leadershipNames = new Set(getToolNamesForAccessLevel("leadership"));
+  const ceoNames = new Set(getToolNamesForAccessLevel("ceo"));
+  assert.ok(ceoNames.size > leadershipNames.size, "ceo should outrank leadership in tool count");
+});
+
+test("sensitive CEO-only write tools never leak into the leadership surface", () => {
+  const leadershipNames = new Set(getToolNamesForAccessLevel("leadership"));
+  for (const name of CEO_ONLY_WRITE_NAMES) {
+    assert.equal(
+      leadershipNames.has(name),
+      false,
+      `CEO-only write tool "${name}" must not appear at leadership level`,
+    );
+    // sanity: it really is a CEO tool, otherwise the assertion above is vacuous.
+    assert.ok(
+      new Set(getToolNamesForAccessLevel("ceo")).has(name),
+      `expected "${name}" to be a CEO tool`,
+    );
+  }
+});
+
+test("any voice write tool is also granted at ceo level (voice ⊆ ceo for write tools)", () => {
+  const ceoNames = new Set(getToolNamesForAccessLevel("ceo"));
+  const voiceTools = getToolsForAccessLevel("voice");
+  for (const tool of voiceTools) {
+    if (WRITE_TOOL_NAMES.has(tool.name)) {
+      assert.ok(
+        ceoNames.has(tool.name),
+        `voice write tool "${tool.name}" is not authorised at ceo level — escalation`,
+      );
+    }
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Name-based lookup: unknown name resolves to nothing, no throw
+// ---------------------------------------------------------------------------
+
+test("looking up an unknown tool name returns undefined without throwing", () => {
+  let found;
+  assert.doesNotThrow(() => {
+    found = findToolByName("ceo", "definitely_not_a_real_tool");
+  });
+  assert.equal(found, undefined);
+});
+
+test("looking up a known write tool at default level resolves to undefined (scoped out)", () => {
+  assert.equal(findToolByName("default", "place_voice_call"), undefined);
+  // ...but it does resolve at ceo level.
+  const atCeo = findToolByName("ceo", "place_voice_call");
+  assert.ok(atCeo);
+  assert.equal(atCeo.name, "place_voice_call");
+});
+
+// ---------------------------------------------------------------------------
+// Structural invariants — every tool is a valid Claude API tool schema
+// ---------------------------------------------------------------------------
+
+/** Collect every distinct tool object exposed across all surfaces + categories. */
+function allDistinctTools() {
+  const byName = new Map();
+  for (const level of KNOWN_LEVELS) {
+    for (const tool of getToolsForAccessLevel(level)) {
+      byName.set(tool.name, tool);
+    }
+  }
+  for (const tools of Object.values(getAllToolsByCategory())) {
+    for (const tool of tools) byName.set(tool.name, tool);
+  }
+  return [...byName.values()];
+}
+
+test("every tool definition has a non-empty string name", () => {
+  for (const tool of allDistinctTools()) {
+    assert.equal(typeof tool.name, "string", `tool name not a string: ${JSON.stringify(tool)}`);
+    assert.ok(tool.name.length > 0, "tool name is empty");
+    // Claude API tool names: letters, numbers, underscores, hyphens.
+    assert.match(tool.name, /^[a-zA-Z0-9_-]+$/, `tool name "${tool.name}" has invalid chars`);
+  }
+});
+
+test("every tool definition has a non-empty string description", () => {
+  for (const tool of allDistinctTools()) {
+    assert.equal(typeof tool.description, "string", `${tool.name} description not a string`);
+    assert.ok(tool.description.trim().length > 0, `${tool.name} has empty description`);
+  }
+});
+
+test("every tool definition has an object-typed input_schema with properties", () => {
+  for (const tool of allDistinctTools()) {
+    assert.ok(tool.input_schema, `${tool.name} missing input_schema`);
+    assert.equal(typeof tool.input_schema, "object", `${tool.name} input_schema not an object`);
+    assert.equal(tool.input_schema.type, "object", `${tool.name} input_schema.type !== "object"`);
+    assert.equal(
+      typeof tool.input_schema.properties,
+      "object",
+      `${tool.name} input_schema.properties missing`,
+    );
+    // Every name in `required` must actually be declared in properties.
+    if (Array.isArray(tool.input_schema.required)) {
+      for (const req of tool.input_schema.required) {
+        assert.ok(
+          Object.prototype.hasOwnProperty.call(tool.input_schema.properties, req),
+          `${tool.name} requires "${req}" but it is not declared in properties`,
+        );
+      }
+    }
+  }
+});
+
+// ---------------------------------------------------------------------------
+// getAllToolsByCategory shape
+// ---------------------------------------------------------------------------
+
+test("getAllToolsByCategory returns all seven categories, each a non-empty array", () => {
+  const cats = getAllToolsByCategory();
+  const expected = [
+    "communication",
+    "search",
+    "knowledge",
+    "operations",
+    "analysis",
+    "documents",
+    "org",
+  ];
+  assert.deepEqual(Object.keys(cats).sort(), [...expected].sort());
+  for (const key of expected) {
+    assert.ok(Array.isArray(cats[key]), `${key} is not an array`);
+    assert.ok(cats[key].length > 0, `${key} category is empty`);
+  }
+});
+
+test("every categorised tool is a structurally valid tool definition", () => {
+  for (const [cat, tools] of Object.entries(getAllToolsByCategory())) {
+    for (const tool of tools) {
+      assert.ok(tool.name, `tool in ${cat} missing name`);
+      assert.ok(tool.description, `${tool.name} in ${cat} missing description`);
+      assert.equal(tool.input_schema?.type, "object", `${tool.name} in ${cat} bad input_schema`);
+    }
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Category 7 — Org (Cohort): the curated surface from lib/org/tool-surface.mjs
+// ---------------------------------------------------------------------------
+
+import { getOrgTools, emailFamilyAvailable } from "./org/tool-surface.mjs";
+
+test("org category mirrors the tool-surface table exactly (one SoT, two planes)", () => {
+  const org = getAllToolsByCategory().org;
+  const table = getOrgTools();
+  assert.deepEqual(org.map((t) => t.name), table.map((t) => t.name), "same tools, same order");
+  for (const t of org) {
+    assert.ok(t.name && t.description && t.input_schema?.type === "object");
+    assert.equal(t.access, undefined, "table-internal fields are stripped from the Claude schema");
+    assert.equal(t.binding, undefined, "binding never leaks into the Claude schema");
+  }
+});
+
+test("org access monotonicity: default ⊂ leadership ⊂ ceo on the org subset", () => {
+  const table = getOrgTools();
+  const orgNames = new Set(table.map((t) => t.name));
+  const orgAt = (level) => getToolNamesForAccessLevel(level).filter((n) => orgNames.has(n));
+  const def = orgAt("default");
+  const lead = orgAt("leadership");
+  const ceo = orgAt("ceo");
+  for (const n of def) assert.ok(lead.includes(n), `default org tool ${n} must exist at leadership`);
+  for (const n of lead) assert.ok(ceo.includes(n), `leadership org tool ${n} must exist at ceo`);
+  // default = exactly the reads; leadership adds exactly the writes; ceo adds the hatches
+  const reads = table.filter((t) => t.access === "read").map((t) => t.name).sort();
+  const writes = table.filter((t) => t.access === "write").map((t) => t.name).sort();
+  assert.deepEqual([...def].sort(), reads, "every level's lookup set = the org reads");
+  assert.deepEqual(lead.filter((n) => !def.includes(n)).sort(), writes, "leadership adds the org writes");
+});
+
+test("escape hatches (org_rpc / org_read) are CEO-only in the native plane", () => {
+  const def = new Set(getToolNamesForAccessLevel("default"));
+  const lead = new Set(getToolNamesForAccessLevel("leadership"));
+  const voice = new Set(getToolNamesForAccessLevel("voice"));
+  const ceo = new Set(getToolNamesForAccessLevel("ceo"));
+  for (const hatch of ["org_rpc", "org_read"]) {
+    assert.ok(ceo.has(hatch), `${hatch} present at ceo`);
+    assert.ok(!def.has(hatch), `${hatch} must NOT reach default`);
+    assert.ok(!lead.has(hatch), `${hatch} must NOT reach leadership`);
+    assert.ok(!voice.has(hatch), `${hatch} must NOT reach voice`);
+  }
+});
+
+test("org writes gate on leadership+: default/voice never gain messaging_send-class tools", () => {
+  const def = new Set(getToolNamesForAccessLevel("default"));
+  for (const w of ["messaging_send", "board_claim", "task_create", "decision_propose", "email_send", "email_mark_read", "escalation_raise"]) {
+    if (getOrgTools().some((t) => t.name === w)) {
+      assert.ok(!def.has(w), `org write ${w} must not reach the default (read-only) surface`);
+      assert.ok(new Set(getToolNamesForAccessLevel("leadership")).has(w), `${w} present at leadership`);
+    }
+  }
+});
+
+test("voice curation: conversation-sized org tools only", () => {
+  const voice = new Set(getToolNamesForAccessLevel("voice"));
+  for (const n of ["org_whoami", "messaging_history", "messaging_send", "board_ready"]) {
+    assert.ok(voice.has(n), `${n} curated into voice`);
+  }
+  for (const n of ["org_rpc", "org_read", "email_send", "knowledge_append", "decision_propose"]) {
+    assert.ok(!voice.has(n), `${n} must NOT reach the voice surface`);
+  }
+});
+
+test("email tools present in the native surface iff the vendored protocol carries the family", () => {
+  const lead = new Set(getToolNamesForAccessLevel("leadership"));
+  const def = new Set(getToolNamesForAccessLevel("default"));
+  if (emailFamilyAvailable()) {
+    assert.ok(def.has("email_inbox") && def.has("email_message") && def.has("email_thread"), "email reads in every level's lookup set");
+    assert.ok(lead.has("email_send") && lead.has("email_mark_read"), "email writes at leadership+");
+  } else {
+    for (const n of ["email_inbox", "email_send", "email_mark_read"]) {
+      assert.ok(!def.has(n) && !lead.has(n), `${n} absent while the family is unvendored`);
+    }
+  }
+});

package/lib/util/fetch-timeout.mjs

@@ -0,0 +1,136 @@
+/**
+ * lib/util/fetch-timeout.mjs
+ *
+ * `fetchWithTimeout(url, init, timeoutMs)` — a thin AbortController wrapper that
+ * gives every network call a hard deadline and a TYPED timeout error.
+ *
+ * The audit (gaps-enterprise-ops, confirmed silent-failure source) found the
+ * codebase doing un-timed `fetch()` calls: a hung connection or a relay that
+ * never responds wedges the caller forever with no signal. A bare `fetch`
+ * provides no built-in timeout, so the only correct primitive is an
+ * AbortController armed with a timer — exactly what this module standardizes.
+ *
+ * Behaviour:
+ *   - Arms an AbortController; if `timeoutMs` elapses before the response, the
+ *     request is aborted and a {@link FetchTimeoutError} (name `FetchTimeoutError`,
+ *     `code: "ETIMEDOUT"`) is thrown — distinguishable from a network error or a
+ *     caller-supplied AbortSignal abort.
+ *   - Honours a caller-supplied `init.signal`: if the caller aborts, the request
+ *     aborts with the caller's reason (NOT a timeout), and our timer is cleared.
+ *   - Always clears the timer (success, network error, or abort) so no handle
+ *     leaks and the event loop is never kept alive.
+ *   - `fetchImpl` is injectable so tests need no real network; defaults to the
+ *     global `fetch` (Node 20+).
+ *
+ * House style: ESM .mjs, Node built-ins only, everything injectable.
+ *
+ * @module lib/util/fetch-timeout
+ */
+
+/** Default per-request timeout when the caller passes none. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Error thrown when a request exceeds its timeout. Carries a stable `name` and
+ * `code` so callers can branch on the timeout case without string-matching the
+ * message, and `timeoutMs` / `url` for diagnostics.
+ */
+export class FetchTimeoutError extends Error {
+  /**
+   * @param {string} message
+   * @param {{timeoutMs?:number, url?:string}} [info]
+   */
+  constructor(message, info = {}) {
+    super(message);
+    this.name = "FetchTimeoutError";
+    /** @type {string} */
+    this.code = "ETIMEDOUT";
+    if (info && typeof info.timeoutMs === "number") this.timeoutMs = info.timeoutMs;
+    if (info && typeof info.url !== "undefined") this.url = String(info.url);
+  }
+}
+
+/**
+ * Resolve the effective fetch implementation: an injected one wins; otherwise
+ * the global `fetch`. Throws a clear error if neither is available rather than
+ * failing with an opaque "fetchImpl is not a function".
+ *
+ * @param {object} [opts]
+ * @param {Function} [opts.fetchImpl]
+ * @returns {Function}
+ */
+function resolveFetch(opts) {
+  if (opts && typeof opts.fetchImpl === "function") return opts.fetchImpl;
+  if (typeof fetch === "function") return fetch;
+  throw new TypeError("fetchWithTimeout: no fetch implementation available (pass opts.fetchImpl)");
+}
+
+/**
+ * `fetch` with a hard timeout.
+ *
+ * @param {string|URL} url - The request URL (or anything the fetch impl accepts).
+ * @param {RequestInit} [init] - Standard fetch init. A caller `init.signal` is
+ *   composed with the internal timeout signal — whichever fires first aborts.
+ * @param {number} [timeoutMs=DEFAULT_TIMEOUT_MS] - Deadline in milliseconds. A
+ *   non-positive / non-finite value disables the timeout (plain pass-through).
+ * @param {object} [opts]
+ * @param {Function} [opts.fetchImpl] - Injected fetch (tests / non-global env).
+ * @returns {Promise<Response>} The fetch Response.
+ * @throws {FetchTimeoutError} If the request exceeds `timeoutMs`.
+ */
+export async function fetchWithTimeout(url, init = {}, timeoutMs = DEFAULT_TIMEOUT_MS, opts = {}) {
+  const doFetch = resolveFetch(opts);
+  const ms = Number(timeoutMs);
+
+  // No (or invalid) timeout requested → straight pass-through, signal untouched.
+  if (!Number.isFinite(ms) || ms <= 0) {
+    return doFetch(url, init);
+  }
+
+  const controller = new AbortController();
+  let timedOut = false;
+  let timer = null;
+
+  // Compose a caller-supplied signal: if the caller aborts, we abort too, but
+  // we mark it NOT a timeout so the original reason surfaces.
+  const callerSignal = init && init.signal;
+  /** @type {(() => void) | null} */
+  let detachCaller = null;
+  if (callerSignal) {
+    if (callerSignal.aborted) {
+      controller.abort(callerSignal.reason);
+    } else {
+      const onAbort = () => controller.abort(callerSignal.reason);
+      callerSignal.addEventListener("abort", onAbort, { once: true });
+      detachCaller = () => callerSignal.removeEventListener("abort", onAbort);
+    }
+  }
+
+  timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, ms);
+  // Don't let the timer hold the event loop open on its own.
+  if (timer && typeof timer.unref === "function") timer.unref();
+
+  try {
+    return await doFetch(url, { ...init, signal: controller.signal });
+  } catch (err) {
+    if (timedOut) {
+      throw new FetchTimeoutError(
+        `fetchWithTimeout: request to ${String(url)} timed out after ${ms}ms`,
+        { timeoutMs: ms, url }
+      );
+    }
+    throw err;
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (detachCaller) detachCaller();
+  }
+}
+
+export default {
+  fetchWithTimeout,
+  FetchTimeoutError,
+  DEFAULT_TIMEOUT_MS,
+};