@cohortapp/agent-sdk 2.9.1 → 2.11.0

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

@@ -25,6 +25,7 @@ import {
   DEFAULT_COHORT_BASE,
 } from "./tool-surface.mjs";
 import { methodDef, PROTOCOL_VERSION, READS } from "./protocol.mjs";
+import { ADMIN_TOOLS, expectedAccessFor, normalizeToolAccess } from "./tool-access.mjs";
 
 // ── env hygiene ────────────────────────────────────────────────────────────
 const ENV_KEYS = [
@@ -59,7 +60,7 @@ function fakeFetch(body = { ok: true, result: { fine: true } }, { status = 200,
 
 // ── table shape ────────────────────────────────────────────────────────────
 
-test("table: curated 43 + 5 email + 5 artifact + 69 desk tools, snake_case names, valid access + schemas", () => {
+test("table: curated 54 + 5 email + 5 artifact + 77 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.
@@ -84,8 +85,40 @@ test("table: curated 43 + 5 email + 5 artifact + 69 desk tools, snake_case names
   // (channel.addMember), and engage_colleagues — the judged path that decides
   // WHETHER anyone needs involving before it opens anything at all.
   // Curated 38 → 42, +1 for work_track → 43.
-  assert.equal(ORG_TOOLS.length, 122, "43 curated + 5 email + 5 artifact + 69 desk");
-  assert.equal(ORG_TOOLS.filter((t) => t.desk).length, 69, "exactly sixty-nine desk tools");
+  // The VOICE delta adds messaging_send_voice_note — hq could synthesise a
+  // colleague's voice note only as a reflex (answering a human's spoken note in
+  // kind), so an agent ASKED in text for one had no verb and truthfully said it
+  // could not. A `local` binding: it records (messaging.synthesizeVoiceNote)
+  // then posts (plain messaging.send with the file attached). Curated 43 → 44.
+  // The MANDATE + REGISTRY + PREFERENCE delta (+10 → 54). Three families that
+  // were protocol-declared and curated NOWHERE, so a session could reach them
+  // only through `org_rpc` — access:"admin", i.e. not at all below the CEO tier:
+  //   mandate (5)     — hq's own chat colleague has carried the whole belt
+  //                     since the spine landed, under a docblock naming SDK
+  //                     parity as its reason; the SDK plane had none of it, so
+  //                     the daemon knew the seat's objectives and the session it
+  //                     spawned did not. adopt/retire are deliberately absent —
+  //                     `mandate.write` is not in DEFAULT_AGENT_SCOPES.
+  //   subagent (3)    — READS only. hq keeps the registry, maestro generates
+  //                     sub-agents locally, and the two halves never met. The
+  //                     writes stay with lib/subagents/client.mjs, which owns
+  //                     the offline outbox and the lock file a second writer
+  //                     would silently bypass.
+  //   preference (2)  — hq built this family FOR this plane and said so in the
+  //                     handler; no tool was ever added, so the same workspace
+  //                     remembered a standing preference when hq answered and
+  //                     forgot it when the seat's own daemon did.
+  // The RESOURCE delta (+8 desk → 77, table 133 → 141). A venture's artifacts
+  // cross from the portal and are filed as real WorkspaceFile rows, and the
+  // OrgResource catalogue that indexes them was reachable from NO agent code
+  // path in EITHER plane — the venture's own colleagues could not list, add,
+  // correct, reorder or remove one of their own deliverables. Unlike every
+  // block above it, this one is GENERATED from the vendored protocol
+  // declaration (lib/org/resource-tools.mjs) rather than transcribed from hq's
+  // desk, so it cannot acquire the 239-vs-69 drift the hand-copied desks
+  // already carry; resource-tools.test.mjs is the parity that holds it there.
+  assert.equal(ORG_TOOLS.length, 141, "54 curated + 5 email + 5 artifact + 77 desk");
+  assert.equal(ORG_TOOLS.filter((t) => t.desk).length, 77, "exactly seventy-seven 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) {
@@ -117,26 +150,37 @@ test("table: curated 43 + 5 email + 5 artifact + 69 desk tools, snake_case names
 
 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"]);
+  // messaging_send_voice_note is outbound-flagged but adds NOTHING to
+  // OUTBOUND_METHODS: it is a `local` binding, and the derivation reads rpc
+  // bindings only. Its POST leg is messaging.send, which is already in the set,
+  // so the escape hatch stays covered too — the flag here buys the screen on
+  // the SPOKEN words, before a billable character is synthesised.
   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"]);
+  assert.deepEqual(outboundTools, [
+    "email_draft_send",
+    "email_send",
+    "messaging_send",
+    "messaging_send_voice_note",
+    "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, 122);
+  assert.equal(getOrgTools().length, 141);
   const without = getOrgTools({ emailAvailable: false });
-  assert.equal(without.length, 117);
+  assert.equal(without.length, 136);
   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, 117);
+  assert.equal(without.length, 136);
   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, 43, "all additive families off → the 43 always-on tools");
+  assert.equal(neither.length, 54, "all additive families off → the 54 always-on tools");
 });
 
 test("isOrgTool / orgToolDef cover the full table; unknown names rejected", () => {
@@ -776,3 +820,336 @@ test("messaging_send passes mentions straight through to the wire", async () =>
   // fails hq's zod and 400s the WHOLE message, tags and body alike.
   assert.deepEqual(body.mentions, [{ memberId: "M-2" }]);
 });
+
+// ── speaking: messaging_send_voice_note ────────────────────────────────────
+//
+// The verb that closes "I can't send audio voice notes". hq could always
+// synthesise an agent's voice note, but only as a REFLEX answering a human's
+// spoken note in kind — asked in text, an agent had nothing to call.
+//
+// What is pinned here is the composition: record, then post the recording as an
+// ORDINARY message attachment. There is no audio-only send path, so the post
+// leg carries the same ACL, audit and dedup as any typed message; and a refused
+// recording must never be followed by a post that implies one was made.
+
+test("messaging_send_voice_note: records, then posts the file as an ordinary attachment", async () => {
+  let n = 0;
+  const calls = [];
+  const fetchImpl = async (url, init) => {
+    calls.push({ url: String(url), body: JSON.parse(init.body) });
+    n += 1;
+    return {
+      ok: true,
+      status: 200,
+      headers: { get: () => undefined },
+      json: async () =>
+        n === 1
+          ? { ok: true, result: { fileId: "file_v1", durationMs: 4200 } }
+          : { ok: true, result: { messageId: "m1" } },
+    };
+  };
+  const frame = await executeOrgTool(
+    "messaging_send_voice_note",
+    { channelId: "C1", text: "Shipping Friday." },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async () => ({ allow: true }) },
+  );
+  assert.equal(frame.ok, true);
+  assert.match(calls[0].url, /messaging\.synthesizeVoiceNote$/);
+  assert.equal(calls[0].body.text, "Shipping Friday.");
+  assert.match(calls[1].url, /messaging\.send$/);
+  assert.deepEqual(calls[1].body.attachments, [{ fileId: "file_v1" }]);
+  // The written body defaults to the spoken words, never an empty message.
+  assert.equal(calls[1].body.body, "Shipping Friday.");
+  assert.ok(calls[1].body.idempotencyId, "the post is dedup-keyed like any send");
+  assert.equal(frame.result.fileId, "file_v1");
+});
+
+test("messaging_send_voice_note: a refused recording is NOT followed by a post", async () => {
+  const calls = [];
+  const fetchImpl = async (url, init) => {
+    calls.push(String(url));
+    return {
+      ok: false,
+      status: 403,
+      headers: { get: () => undefined },
+      json: async () => ({
+        ok: false,
+        error: { code: "FORBIDDEN_SCOPE", message: "voice note not recorded (no-key): ..." },
+      }),
+    };
+  };
+  const frame = await executeOrgTool(
+    "messaging_send_voice_note",
+    { channelId: "C1", text: "hi" },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async () => ({ allow: true }) },
+  );
+  assert.equal(frame.ok, false);
+  assert.match(frame.error.message, /no-key/);
+  assert.equal(calls.length, 1, "no post claiming a voice note that was never recorded");
+});
+
+test("messaging_send_voice_note: the send-gate screens the SPOKEN words before synthesis", async () => {
+  const fetchImpl = fakeFetch();
+  const seen = [];
+  const frame = await executeOrgTool(
+    "messaging_send_voice_note",
+    { channelId: "C1", text: "the secret is hunter2", body: "see note" },
+    {
+      orgConfig: CFG,
+      agentRoot: "/tmp/none",
+      fetchImpl,
+      screenImpl: async (args) => {
+        seen.push(args);
+        return args.text.includes("hunter2") ? { allow: false, reason: "credential" } : { allow: true };
+      },
+    },
+  );
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "FORBIDDEN_SCOPE");
+  // The gate sees the PROSE — the spoken words and the written body — not a
+  // stringified params blob. A gate judging JSON would pass sentences it never
+  // actually read.
+  assert.equal(seen[0].text, "the secret is hunter2\nsee note");
+  assert.equal(seen[0].recipient, "C1");
+  // Blocked BEFORE the network: audio is the hardest content to retract, and a
+  // blocked note must not cost a billable synthesis either.
+  assert.equal(fetchImpl.calls.length, 0);
+});
+
+test("messaging_send_voice_note: channelId and text are both required", async () => {
+  const fetchImpl = fakeFetch();
+  const frame = await executeOrgTool(
+    "messaging_send_voice_note",
+    { channelId: "C1" },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl, screenImpl: async () => ({ allow: true }) },
+  );
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "BAD_REQUEST");
+  assert.equal(fetchImpl.calls.length, 0);
+});
+
+// ── mandate / sub-agent registry / preferences (2026-08 parity delta) ───────
+
+test("mandate tools ride their mandate.* methods and POST the params verbatim", async () => {
+  const seen = [];
+  const fetchImpl = async (url, init) => {
+    seen.push({ url: String(url), body: JSON.parse(init.body) });
+    return { ok: true, status: 200, headers: { get: () => undefined }, json: async () => ({ ok: true, result: {} }) };
+  };
+  fetchImpl.calls = seen;
+  const o = { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl };
+  await executeOrgTool("mandate_read", {}, o);
+  await executeOrgTool("mandate_objectives", { state: "active", includeRetired: false }, o);
+  await executeOrgTool("mandate_kpi_series", { objectiveId: "ob-1", limit: 20 }, o);
+  await executeOrgTool("mandate_propose_objective", { key: "pipeline-coverage", text: "3x cover", target: 3 }, o);
+  await executeOrgTool(
+    "mandate_record_kpi_sample",
+    { objectiveId: "ob-1", value: 2.4, window: "2026-W33", evidence: { method: "crm.listDeals" } },
+    o,
+  );
+  assert.deepEqual(seen.map((c) => c.url), [
+    "https://org.example/api/v1/mandate.get",
+    "https://org.example/api/v1/mandate.tree",
+    "https://org.example/api/v1/mandate.series",
+    "https://org.example/api/v1/mandate.propose",
+    "https://org.example/api/v1/mandate.sample",
+  ]);
+  // Pass-through, byte for byte: hq's mandate schemas read these names, and the
+  // evidence OBJECT is what the server's honesty gate inspects — flattening it
+  // to a string here would silently downgrade every sample to `llm`.
+  assert.deepEqual(seen[3].body, { key: "pipeline-coverage", text: "3x cover", target: 3 });
+  assert.deepEqual(seen[4].body.evidence, { method: "crm.listDeals" });
+});
+
+test("the mandate belt stops at PROPOSE — no adopt/retire tool exists at any tier", () => {
+  const names = new Set(ORG_TOOLS.map((t) => t.name));
+  for (const forbidden of ["mandate_adopt", "mandate_retire"]) {
+    assert.equal(names.has(forbidden), false, `${forbidden} must not exist`);
+  }
+  // The absence is structural, not incidental: no curated tool may bind a
+  // method whose scope is missing from DEFAULT_AGENT_SCOPES, because a tool the
+  // seat's own credential can never execute is a promise the model will make
+  // and fail to keep. `mandate.write` is the anti-Goodhart scope.
+  const bound = ORG_TOOLS.filter((t) => t.binding.kind === "rpc").map((t) => t.binding.method);
+  for (const m of bound) {
+    assert.notEqual(methodDef(m).scope, "mandate.write", `${m} needs mandate.write — not an agent's to hold`);
+  }
+});
+
+test("subagent tools are READS ONLY — the writes stay with the outbox-owning client", () => {
+  const subagentTools = ORG_TOOLS.filter(
+    (t) => t.binding.kind === "rpc" && t.binding.method.startsWith("subagent."),
+  );
+  assert.deepEqual(
+    subagentTools.map((t) => t.name).sort(),
+    ["subagent_get", "subagent_list", "subagent_resolve"],
+  );
+  for (const t of subagentTools) {
+    assert.equal(t.access, "read", `${t.name} is a read`);
+    assert.equal(methodDef(t.binding.method).sideEffecting, false, `${t.binding.method} mutates nothing`);
+  }
+});
+
+test("preference tools ship as a PAIR — a write-only memory is not parity", async () => {
+  const names = ORG_TOOLS.filter(
+    (t) => t.binding.kind === "rpc" && t.binding.method.startsWith("preference."),
+  );
+  assert.deepEqual(names.map((t) => t.name).sort(), ["preference_list", "preference_remember"]);
+  assert.equal(orgToolDef("preference_list").access, "read");
+  assert.equal(orgToolDef("preference_remember").access, "write");
+  // `why` is required in the SCHEMA, not just server-side: the evidence rule
+  // has to reach the model, or it learns the rule by BAD_REQUEST.
+  assert.ok(orgToolDef("preference_remember").input_schema.required.includes("why"));
+
+  const fetchImpl = fakeFetch({ ok: true, result: { id: "pref-1" } });
+  const frame = await executeOrgTool(
+    "preference_remember",
+    { domain: "travel", key: "seat", value: "aisle", why: "said so in #travel" },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl },
+  );
+  assert.equal(frame.ok, true);
+  assert.equal(fetchImpl.calls[0].url, "https://org.example/api/v1/preference.upsert");
+  // sideEffecting:true at the dispatcher → a fresh header key per invocation.
+  assert.ok(fetchImpl.calls[0].init.headers["x-idempotency-key"], "dispatcher key attached");
+});
+
+// ── the access mechanism, TABLE-WIDE ───────────────────────────────────────
+//
+// The per-delta assertion below ("the new tools reach the tiers that need
+// them") lists ten names by hand, so it polices the tools whose author
+// remembered to add them and nothing else — every family that ships after it is
+// unguarded by default. These three assertions are the table-wide version:
+// they iterate ORG_TOOLS, so a capability cannot be parked at the CEO-only tier
+// or given a tier its protocol scope contradicts without one of them going red,
+// whether or not anyone updates a list.
+
+test("ACCESS MECHANISM: `admin` is a CLOSED set of two escape hatches, not a parking space", () => {
+  const admins = ORG_TOOLS.filter((t) => t.access === "admin").map((t) => t.name).sort();
+  assert.deepEqual(
+    admins,
+    [...ADMIN_TOOLS].sort(),
+    "only org_rpc/org_read may be admin-tier — anything else is a CAPABILITY, and a capability " +
+      "at admin is CEO-only, i.e. exactly as unreachable for a leadership or default agent as " +
+      "the org_rpc route a curated tool exists to replace",
+  );
+  for (const name of ADMIN_TOOLS) {
+    const def = orgToolDef(name);
+    assert.ok(def, `${name} is in the table`);
+    assert.equal(def.access, "admin", `${name} is the escape hatch it claims to be`);
+    // Both hatches are `local`: they take a method/path NAME and validate it
+    // against the frozen table before any I/O. A desk verb can never be one.
+    assert.equal(def.binding.kind, "local", `${name} is a console, not a capability`);
+  }
+});
+
+test("ACCESS MECHANISM: every rpc-bound tool's tier is DERIVED from its protocol scope", () => {
+  // hq gates on SCOPE, so the native clamp has to mirror the scope lane or it
+  // either withholds a tool hq would have allowed or offers one hq will refuse.
+  // Note the rule this is NOT: `sideEffecting ? "write" : "read"` is wrong for
+  // seven tools already in the table — knowledge.search, directory.ask and the
+  // three branding renders/exports are AUDITED READS (side-effecting, `.read`
+  // scope, runnable by a VIEWER seat), and artifact.create/act are the mirror
+  // case. Deriving from sideEffecting would demote all five audited reads out
+  // of the lookup set every tier gets.
+  let checked = 0;
+  for (const t of ORG_TOOLS) {
+    if (!t.binding || t.binding.kind !== "rpc") continue;
+    checked += 1;
+    const want = expectedAccessFor(t.binding.method);
+    assert.ok(want, `${t.name} binds a vendored method`);
+    assert.equal(
+      t.access,
+      want,
+      `${t.name} (${t.binding.method}, scope ${methodDef(t.binding.method).scope}) must be access:"${want}"`,
+    );
+  }
+  assert.ok(checked >= 120, "the whole rpc-bound belt was checked, not a sample");
+});
+
+test("ACCESS MECHANISM: no tool can fall out of every tier — the partition is exhaustive", () => {
+  // Exact string equality used to bucket the table, so a missing or mis-cased
+  // `access` matched NO bucket and reached NO native access level, while the
+  // MCP plane kept publishing it. normalizeToolAccess is the tool-side twin of
+  // normalizeAccessLevel: it normalises casing and sends a genuinely
+  // unrecognised tier to the most-restricted bucket, loudly.
+  for (const t of ORG_TOOLS) {
+    assert.ok(
+      ["read", "write", "admin"].includes(t.access),
+      `${t.name} declares a known tier verbatim (the normaliser is a safety net, not a licence)`,
+    );
+    const warnings = [];
+    assert.equal(normalizeToolAccess(t.access, t.name, (m) => warnings.push(m)), t.access);
+    assert.equal(warnings.length, 0, `${t.name} normalises silently`);
+  }
+  // And the safety net itself: a typo fails CLOSED and NOISY, never invisible.
+  const warnings = [];
+  assert.equal(normalizeToolAccess("Read", "x_tool", (m) => warnings.push(m)), "read", "casing is forgiven");
+  assert.equal(normalizeToolAccess(undefined, "x_tool", (m) => warnings.push(m)), "admin", "a missing tier fails closed");
+  assert.equal(warnings.length, 1, "and says so out loud");
+  assert.match(warnings[0], /x_tool/);
+});
+
+test("the new tools reach the tiers that need them — reads everywhere, no new admin surface", () => {
+  const added = [
+    "mandate_read", "mandate_objectives", "mandate_kpi_series",
+    "mandate_propose_objective", "mandate_record_kpi_sample",
+    "subagent_list", "subagent_get", "subagent_resolve",
+    "preference_remember", "preference_list",
+  ];
+  for (const n of added) {
+    const def = orgToolDef(n);
+    assert.ok(def, `${n} is in the table`);
+    // The whole point of the delta: NONE of these may land at access:"admin",
+    // which is the CEO-only escape-hatch tier. A capability parked there is
+    // exactly as unreachable as the org_rpc route it was meant to replace.
+    assert.notEqual(def.access, "admin", `${n} must not be admin-tier`);
+    assert.equal(def.outbound, undefined, `${n} sends nothing a human reads as a message`);
+  }
+  assert.equal(
+    added.filter((n) => orgToolDef(n).access === "read").length,
+    7,
+    "seven reads (3 mandate, 3 subagent, 1 preference) land in EVERY tier's lookup set",
+  );
+});
+
+test("the new tools FAIL CLOSED with no credential — refusal, never a silent success", async () => {
+  const fetchImpl = fakeFetch();
+  for (const n of ["mandate_read", "subagent_list", "preference_remember"]) {
+    const frame = await executeOrgTool(n, {}, { orgConfig: {}, agentRoot: "/tmp/none", fetchImpl });
+    assert.equal(frame.ok, false, `${n} refuses`);
+    assert.equal(frame.error.code, "UNAUTHORIZED");
+    assert.match(frame.error.message, /COHORT_API_TOKEN/);
+  }
+  assert.equal(fetchImpl.calls.length, 0, "nothing dispatched without a credential");
+});
+
+test("a 401/403 from hq surfaces VERBATIM on the new tools (a refusal is an answer)", async () => {
+  const denied = fakeFetch(
+    { ok: false, error: { code: "FORBIDDEN_SCOPE", message: "resolving another member's sub-agents requires admin" } },
+    { ok: false, status: 403 },
+  );
+  const frame = await executeOrgTool(
+    "subagent_resolve",
+    { memberId: "someone-else" },
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: denied },
+  );
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "FORBIDDEN_SCOPE");
+  assert.match(frame.error.message, /admin/);
+
+  const unauth = fakeFetch({ ok: false, error: { code: "UNAUTHORIZED", message: "bad key" } }, { ok: false, status: 401 });
+  const f2 = await executeOrgTool("mandate_read", {}, { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: unauth });
+  assert.equal(f2.ok, false);
+  assert.equal(f2.error.code, "UNAUTHORIZED");
+});
+
+test("transport failure on a new tool fails open into an INTERNAL frame, never a throw", async () => {
+  const thrower = async () => { throw new Error("econnrefused"); };
+  const frame = await executeOrgTool(
+    "mandate_objectives",
+    {},
+    { orgConfig: CFG, agentRoot: "/tmp/none", fetchImpl: thrower },
+  );
+  assert.equal(frame.ok, false);
+  assert.equal(frame.error.code, "INTERNAL");
+});

package/lib/org/ui-parity.mjs

@@ -1,13 +1,21 @@
 /**
  * lib/org/ui-parity.mjs — Agent UI-parity helpers (full human-action mirror).
  *
- * A 1:1 mirror of the human Cohort UI: 359 named convenience wrappers over the
+ * A 1:1 mirror of the human Cohort UI: 373 named convenience wrappers over the
  * /v1 RPC binding, one per method behind a HUMAN SURFACE — the things a person
  * can do by clicking (charter, member, team, channel, persona, profile, sop,
  * escalation, annotation, contact, file, memory, compact, notification,
  * decision, messaging, calling, board, invitation, user, settings, billing, org,
- * integration, email + the Inbox app, artifact, and the agent desks: books,
- * calendar, crm, directory, files, meetings.recapFile).
+ * integration, email + the Inbox app, artifact, mandate, preference, and the
+ * agent desks: books, calendar, crm, directory, files, meetings.recapFile).
+ *
+ * THE FAMILIES THIS MODULE DOES NOT CLAIM are no longer a silence. Every family
+ * in the protocol table is now either claimed here or carries a written line in
+ * `ui-parity.test.mjs`'s UNCLAIMED_FAMILIES naming the surface that carries it
+ * (client.mjs for the org spine, lib/subagents/client.mjs for the registry, or
+ * "hq refuses an api-key principal outright" for genesis/architecture). Before
+ * that ledger existed a newly-declared family simply failed no test — which is
+ * how genesis, subagent and mandate all landed dark in one fortnight.
  *
  * "ONE PER HUMAN SURFACE", NOT "one per method in the family" — and the
  * difference is load-bearing, because the flat family list above reads like the
@@ -3322,6 +3330,29 @@ export function messagingTyping(params, o = {}) {
   return call("messaging.typing", params || {}, o);
 }
 
+/**
+ * Record a VOICE NOTE in this seat's own designed voice
+ * (messaging.synthesizeVoiceNote) → `{fileId, durationMs, sizeBytes}`.
+ *
+ * The human parity here is the hold-to-record button: a person speaks into the
+ * composer and the note lands as an attachment on an ordinary message. This is
+ * the same artifact by the same route — POST it with `messagingSendMessage` and
+ * `attachments:[{fileId}]`. There is no audio-only send path on either plane.
+ *
+ * hq splits record from post because synthesis is a provider round-trip that
+ * cannot ride its 5s transactional send lane; `messaging_send_voice_note`
+ * (tool-surface) composes the two so a model sees one verb.
+ *
+ * NOT ok is a real answer: no synthesis key on the deployment, no designed
+ * voice for this seat, or the hourly cap. Relay the reason — never report a
+ * voice note as sent when the frame was not ok.
+ * @param {object} params - { text }
+ * @param {object} o - { base, token, fetchImpl? }
+ */
+export function messagingSynthesizeVoiceNote(params, o = {}) {
+  return call("messaging.synthesizeVoiceNote", params || {}, o);
+}
+
 /**
  * Add or remove YOUR reaction on a message (messaging.react). `op:add` upserts,
  * `op:remove` deletes; both are no-ops when already in that state.
@@ -3561,3 +3592,165 @@ export function callingGetVisualContext(params, o = {}) {
 export function callingGetCallEvents(params, o = {}) {
   return call("calling.getCallEvents", params || {}, o);
 }
+
+// ---------------------------------------------------------------------------
+// mandate — the accountability spine (objectives, KPI samples, the adoption act)
+// ---------------------------------------------------------------------------
+//
+// The human surface is the objectives pane: a manager reads a seat's mandate,
+// adopts or retires an objective, and watches the KPI series move. The family
+// was protocol-declared with none of it wrapped, so the SDK could reach it only
+// through `call()` by hand — which is how `lib/mandate/refresh.mjs` ended up
+// spelling out "mandate.get" as a string constant of its own.
+//
+// The read/propose/write SPLIT is the anti-Goodhart law and it survives here
+// intact: `mandateAdopt`/`mandateRetire` bind methods whose scope
+// (`mandate.write`) is deliberately absent from DEFAULT_AGENT_SCOPES, so an
+// agent credential calling them gets FORBIDDEN_SCOPE — as it should. They are
+// wrapped anyway because ui-parity mirrors what a HUMAN does at the surface,
+// and an operator tool driving this SDK with an admin key is exactly that human.
+
+/**
+ * A seat's ADOPTED mandate snapshot (mandate.get) — {version, checksum, body}.
+ * `version: 0` with a null body means nothing is adopted yet: a legitimate
+ * steady state for a new seat, never an error.
+ * @param {object} params - { memberId? }
+ * @param {object} o - { base, token, fetchImpl? }
+ */
+export function mandateGet(params, o = {}) {
+  return call("mandate.get", params || {}, o);
+}
+
+/**
+ * The cheap ETag poll (mandate.version) — {version, checksum} only, so a daemon
+ * can ask "did my mandate move?" every beat without paying for the body.
+ * @param {object} params - { memberId? }
+ * @param {object} o - { base, token, fetchImpl? }
+ */
+export function mandateVersion(params, o = {}) {
+  return call("mandate.version", params || {}, o);
+}
+
+/**
+ * The org objective tree (mandate.tree) — a flat node list plus `childIds` and
+ * `roots`. Filters AND together; `includeRetired` defaults false.
+ * @param {object} params - { memberId?, kind?, state?, workstreamId?, includeRetired?, limit? }
+ * @param {object} o - { base, token, fetchImpl? }
+ */
+export function mandateTree(params, o = {}) {
+  return call("mandate.tree", params || {}, o);
+}
+
+/**
+ * One objective's KPI samples plus the derived {value, target, gap,
+ * normalizedGap, trend, staleness} (mandate.series).
+ * @param {object} params - { objectiveId, limit? }
+ * @param {object} o - { base, token, fetchImpl? }
+ */
+export function mandateSeries(params, o = {}) {
+  return call("mandate.series", params || {}, o);
+}
+
+/**
+ * Create or update an objective in `state:'proposed'` (mandate.propose).
+ * Idempotent on `(memberId, key)` — the same key UPDATES the proposal rather
+ * than duplicating it, so no `o.idempotencyKey` is needed for dedup. Refuses to
+ * touch a row that is already adopted.
+ * @param {object} params - { key, text, kind?, metric?, unit?, direction?, target?, baseline?, tolerance?, weight?, cadence?, dueAt?, parentId?, charterSectionId?, workstreamId?, sensor?, memberId? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function mandatePropose(params, o = {}) {
+  return call("mandate.propose", params || {}, o);
+}
+
+/**
+ * ADOPT an objective — make it live, work-creating and graded (mandate.adopt).
+ * Governance-gated and anti-self-grading: hq refuses the objective's owner and
+ * every agent principal that is not the owner's supervisor, and the scope
+ * (`mandate.write`) is not in DEFAULT_AGENT_SCOPES. Expect FORBIDDEN_SCOPE from
+ * an ordinary agent key; that refusal is the feature.
+ * @param {object} params - { objectiveId }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function mandateAdopt(params, o = {}) {
+  return call("mandate.adopt", params || {}, o);
+}
+
+/**
+ * Retire an adopted objective (mandate.retire). Same authority ladder as adopt.
+ * @param {object} params - { objectiveId, reason? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function mandateRetire(params, o = {}) {
+  return call("mandate.retire", params || {}, o);
+}
+
+/**
+ * Report one KPI measurement (mandate.sample). `source` is decided SERVER-side
+ * from `evidence` and any value sent for it is ignored; `(objectiveId, window)`
+ * is unique, so a repeated report for the same window updates rather than
+ * inflating the series.
+ * @param {object} params - { objectiveId, value, window, evidence? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function mandateSample(params, o = {}) {
+  return call("mandate.sample", params || {}, o);
+}
+
+/**
+ * Declare a probe-verified capability of this seat (mandate.declareCapability) —
+ * the manifest half of the mandate/plan split. Idempotent: pass a stable
+ * `o.idempotencyKey`.
+ * @param {object} params - { capability, kind?, evidence?, memberId? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function mandateDeclareCapability(params, o = {}) {
+  return call("mandate.declareCapability", params || {}, o);
+}
+
+/**
+ * Publish the agent's compiled PLAN DIGEST (mandate.publishPlan) — the
+ * obligation set it is actually executing, and the mandate version it compiled
+ * from. This is what hq's `read_agent_plan` reads back. Idempotent: pass a
+ * stable `o.idempotencyKey`.
+ * @param {object} params - { planVersion, mandateVersion, obligations[], memberId? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function mandatePublishPlan(params, o = {}) {
+  return call("mandate.publishPlan", params || {}, o);
+}
+
+/**
+ * Report a drift between the mandate and what the seat can actually do
+ * (mandate.reportDrift) — e.g. a sensor that no longer resolves.
+ * @param {object} params - { kind, detail?, objectiveId?, memberId? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function mandateReportDrift(params, o = {}) {
+  return call("mandate.reportDrift", params || {}, o);
+}
+
+// ---------------------------------------------------------------------------
+// preference — the durable facts hq injects into every conversation
+// ---------------------------------------------------------------------------
+
+/**
+ * Store (or update in place) one member-scoped preference (preference.upsert).
+ * Converges on ONE row per (subject, domain, key); `why` (the evidence) is
+ * mandatory server-side. Idempotent — pass a stable `o.idempotencyKey`.
+ * @param {object} params - { domain, key, value, why, confidence?, messageId?, subjectMemberId? }
+ * @param {object} o - { base, token, idempotencyKey?, fetchImpl? }
+ */
+export function preferenceUpsert(params, o = {}) {
+  return call("preference.upsert", params || {}, o);
+}
+
+/**
+ * The preferences remembered about one member (preference.list). READ-ONLY.
+ * Defaults to the acting seat.
+ * @param {object} params - { memberId?, domain? }
+ * @param {object} o - { base, token, fetchImpl? }
+ */
+export function preferenceList(params, o = {}) {
+  return call("preference.list", params || {}, o);
+}