@cohortapp/agent-sdk 2.5.1 → 2.6.0

package/lib/org/messaging.mjs

@@ -55,6 +55,7 @@ import { isEnabled, configFromAgent, call, read } from "./client.mjs";
 import { errFrame } from "./protocol.mjs";
 import { screenOutbound } from "../comms/send-gate.mjs";
 import { getHookBus } from "../hooks/bus.mjs";
+import { recordOutbound } from "../comms/receipts.mjs";
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -73,6 +74,55 @@ function resolveOrg(cfg) {
   return { base: c.base, token: c.token };
 }
 
+/**
+ * Normalise a mentions list onto the shape hq actually validates.
+ *
+ * ── WHY THIS EXISTS ──
+ * hq's `sendMessageSchemaV1` declares
+ *   `mentions: z.array(z.object({ memberId: string, offset?: number })).max(50)`
+ * (server/validation/message.ts#mentionSchema). This module sent
+ * `params.mentions.map(String)` — an array of BARE STRINGS. Zod rejects the
+ * whole object, so a send carrying mentions did not merely lose its tags: the
+ * ENTIRE `messaging.send` came back `BAD_REQUEST`. Tagging was not "missing"
+ * from the SDK, it was a landmine — the one call an agent would make to bring a
+ * colleague in was the one call guaranteed to fail.
+ *
+ * Accepts, in the wild: `"M-1"`, `{memberId:"M-1"}`, `{id:"M-1"}`,
+ * `{memberId:"M-1", offset:12}`. Drops empties and de-dupes on memberId, since
+ * mentioning the same person twice creates two notification rows for one ask.
+ *
+ * @param {any} mentions
+ * @returns {Array<{memberId:string, offset?:number}>}
+ */
+export function normaliseMentions(mentions) {
+  if (!Array.isArray(mentions)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const m of mentions) {
+    let memberId = "";
+    let offset;
+    if (typeof m === "string" || typeof m === "number") {
+      memberId = String(m).trim();
+    } else if (m && typeof m === "object") {
+      memberId = String(m.memberId ?? m.id ?? m.member ?? "").trim();
+      if (Number.isInteger(m.offset) && m.offset >= 0) offset = m.offset;
+    }
+    if (!memberId || seen.has(memberId)) continue;
+    seen.add(memberId);
+    out.push(offset === undefined ? { memberId } : { memberId, offset });
+  }
+  return out.slice(0, 50);
+}
+
+/** Pull a channel id out of the several shapes hq's channel.* results use. */
+function channelIdOf(result) {
+  if (!result || typeof result !== "object") return null;
+  const direct = result.channelId || result.id;
+  if (direct) return String(direct);
+  const nested = result.channel && (result.channel.id || result.channel.channelId);
+  return nested ? String(nested) : null;
+}
+
 /** A best-effort agent id for ledger attribution (never throws). */
 function agentIdOf(cfg) {
   const n = (cfg && cfg.org && cfg.org.cohort) || {};
@@ -201,11 +251,14 @@ export async function sendMessage(params = {}, o = {}) {
   // SDK was rejected with "channelId: Required" — no agent could post to Cohort
   // at all. The legacy names are kept alongside for any older server that still
   // reads them; the canonical ones are what hq validates.
+  const mentions = normaliseMentions(params.mentions);
   const wire = {
     channelId: channel,
     channel,
     body: text,
-    ...(Array.isArray(params.mentions) && params.mentions.length ? { mentions: params.mentions.map(String) } : {}),
+    // `[{memberId}]`, never `["M-1"]` — see normaliseMentions for what the bare
+    // string cost.
+    ...(mentions.length ? { mentions } : {}),
     ...(params.threadId != null ? { threadRootId: String(params.threadId), threadId: String(params.threadId) } : {}),
     ...(idempotencyId ? { idempotencyId, id: idempotencyId } : {}),
   };
@@ -216,10 +269,20 @@ export async function sendMessage(params = {}, o = {}) {
     fetchImpl: o.fetchImpl,
   });
 
-  // (4) on success: observe-only afterSend + source="messaging" attribution.
+  // (4) on success: observe-only afterSend + source="messaging" attribution +
+  // a DELIVERY RECEIPT. The receipt is what lets the daemon answer "did a human
+  // actually hear from us about this ask" with evidence instead of an exit code.
   if (frame && frame.ok) {
+    recordOutbound({
+      service: "cohort",
+      channel,
+      kind: "reply",
+      via: "messaging.send",
+      chars: text.length,
+      agentRoot: o.agentRoot,
+    });
     await emitAfterSend(
-      { channel: "cohort", recipient: channel, text, mentions: wire.mentions || [], result: frame.result, source: "messaging" },
+      { channel: "cohort", recipient: channel, text, mentions: mentions.map((m) => m.memberId), result: frame.result, source: "messaging" },
       o
     );
     await attributeMessaging({ cfg: o.cfg, agentRoot: o.agentRoot, action: "messaging.send", channel }, o);
@@ -309,6 +372,165 @@ export async function listChannels(o = {}) {
   return [];
 }
 
+// ---------------------------------------------------------------------------
+// Rooms — open a DM, open a group, create a channel, add someone to one
+// ---------------------------------------------------------------------------
+//
+// All four methods have been in the frozen protocol table since it was written
+// (`channel.resolveOrCreateDm` / `.createConversation` / `.create` / `.addMember`,
+// all on `messaging.write`). None of them had a helper here, so an SDK agent
+// could reply where it was spoken to and nowhere else: it could not open a 1:1
+// with someone who had not written to it first, could not put three people in a
+// room, and could not pull a fourth into an existing one. "Bring the right
+// people in" was unreachable not because the org lacked the verb but because
+// this layer never bound it.
+//
+// Each returns `{ok, channelId, created, frame}` rather than a raw frame, since
+// every caller's next move is `sendMessage({channel: channelId, …})` and the id
+// arrives under three different keys depending on the handler.
+
+/**
+ * Resolve (or create) the deterministic 1:1 DM channel with a member.
+ * Idempotent by construction — hq derives the slug from the two member slugs,
+ * so a retry reuses the room instead of littering DMs.
+ *
+ * @param {object} params - { memberId }
+ * @param {object} o - { cfg, fetchImpl?, agentRoot? }
+ * @returns {Promise<{ok:boolean, channelId:string|null, created:boolean, frame:object}>}
+ */
+export async function openDm(params = {}, o = {}) {
+  const memberId = params.memberId != null ? String(params.memberId).trim() : "";
+  if (!memberId) {
+    const frame = errFrame("BAD_REQUEST", "openDm: missing memberId");
+    return { ok: false, channelId: null, created: false, frame };
+  }
+  const org = resolveOrg(o.cfg);
+  if (!org) {
+    const frame = errFrame("BAD_REQUEST", "org messaging disabled or unconfigured");
+    return { ok: false, channelId: null, created: false, frame };
+  }
+  const frame = await call("channel.resolveOrCreateDm", { memberId }, {
+    base: org.base, token: org.token, fetchImpl: o.fetchImpl,
+  });
+  const channelId = frame && frame.ok ? channelIdOf(frame.result) : null;
+  return {
+    ok: !!(frame && frame.ok && channelId),
+    channelId,
+    created: !!(frame && frame.ok && frame.result && frame.result.created === true),
+    frame,
+  };
+}
+
+/**
+ * Open a conversation with one or more people (channel.createConversation).
+ * hq collapses a single other person onto the deterministic 1:1 DM and mints a
+ * fresh GROUP_DM for two or more — so this is the right call for "get these
+ * three in a room" without the caller having to branch on the count.
+ *
+ * @param {object} params - { memberIds:string[], name? }
+ * @param {object} o - { cfg, fetchImpl?, idempotencyKey? }
+ * @returns {Promise<{ok:boolean, channelId:string|null, created:boolean, frame:object}>}
+ */
+export async function openConversation(params = {}, o = {}) {
+  const memberIds = Array.from(
+    new Set((Array.isArray(params.memberIds) ? params.memberIds : []).map((m) => String(m || "").trim()).filter(Boolean)),
+  );
+  if (!memberIds.length) {
+    const frame = errFrame("BAD_REQUEST", "openConversation: memberIds is empty");
+    return { ok: false, channelId: null, created: false, frame };
+  }
+  const org = resolveOrg(o.cfg);
+  if (!org) {
+    const frame = errFrame("BAD_REQUEST", "org messaging disabled or unconfigured");
+    return { ok: false, channelId: null, created: false, frame };
+  }
+  const wire = { memberIds, ...(params.name ? { name: String(params.name).slice(0, 120) } : {}) };
+  const frame = await call("channel.createConversation", wire, {
+    base: org.base, token: org.token, idempotencyKey: o.idempotencyKey, fetchImpl: o.fetchImpl,
+  });
+  const channelId = frame && frame.ok ? channelIdOf(frame.result) : null;
+  return {
+    ok: !!(frame && frame.ok && channelId),
+    channelId,
+    created: !!(frame && frame.ok && frame.result && frame.result.created !== false),
+    frame,
+  };
+}
+
+/**
+ * Create a named org channel (channel.create). This is the MOST expensive room
+ * an agent can make — it is persistent, it appears in everyone's sidebar, and
+ * nobody can un-see it — so callers should reach for `openConversation` first
+ * and only create a channel when the work is durable and the audience standing.
+ *
+ * @param {object} params - { slug, name, kind?, topic?, members? }
+ * @param {object} o - { cfg, fetchImpl?, idempotencyKey? }
+ * @returns {Promise<{ok:boolean, channelId:string|null, created:boolean, frame:object}>}
+ */
+export async function createChannel(params = {}, o = {}) {
+  const slug = params.slug != null ? String(params.slug).trim().toLowerCase() : "";
+  const name = params.name != null ? String(params.name).trim() : "";
+  if (!slug || !name) {
+    const frame = errFrame("BAD_REQUEST", "createChannel: slug and name are required");
+    return { ok: false, channelId: null, created: false, frame };
+  }
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
+    // hq's `channelSlugSchema` refuses anything else; say so here rather than
+    // spending a round trip to be told.
+    const frame = errFrame("BAD_REQUEST", `createChannel: slug "${slug}" must be lowercase alphanumerics and hyphens`);
+    return { ok: false, channelId: null, created: false, frame };
+  }
+  const org = resolveOrg(o.cfg);
+  if (!org) {
+    const frame = errFrame("BAD_REQUEST", "org messaging disabled or unconfigured");
+    return { ok: false, channelId: null, created: false, frame };
+  }
+  const wire = {
+    slug,
+    name: name.slice(0, 120),
+    kind: params.kind ? String(params.kind).toUpperCase() : "PRIVATE",
+    ...(params.topic ? { topic: String(params.topic).slice(0, 500) } : {}),
+    ...(Array.isArray(params.members) && params.members.length
+      ? { members: params.members.map((m) => String(m)).filter(Boolean) }
+      : {}),
+  };
+  const frame = await call("channel.create", wire, {
+    base: org.base, token: org.token, idempotencyKey: o.idempotencyKey, fetchImpl: o.fetchImpl,
+  });
+  const channelId = frame && frame.ok ? channelIdOf(frame.result) : null;
+  return { ok: !!(frame && frame.ok && channelId), channelId, created: !!(frame && frame.ok), frame };
+}
+
+/**
+ * Add a member to a channel (channel.addMember). Idempotent — hq returns the
+ * existing row with `added:false` rather than erroring, so a re-invite is a
+ * no-op. The acting agent must already be in the channel (hq default-denies
+ * inviting into a room you are not in).
+ *
+ * @param {object} params - { channelId, memberId }
+ * @param {object} o - { cfg, fetchImpl?, idempotencyKey? }
+ * @returns {Promise<{ok:boolean, added:boolean, frame:object}>}
+ */
+export async function addChannelMember(params = {}, o = {}) {
+  const channelId = params.channelId != null ? String(params.channelId).trim() : "";
+  const memberId = params.memberId != null ? String(params.memberId).trim() : "";
+  if (!channelId || !memberId) {
+    return { ok: false, added: false, frame: errFrame("BAD_REQUEST", "addChannelMember: channelId and memberId are required") };
+  }
+  const org = resolveOrg(o.cfg);
+  if (!org) {
+    return { ok: false, added: false, frame: errFrame("BAD_REQUEST", "org messaging disabled or unconfigured") };
+  }
+  const frame = await call("channel.addMember", { channelId, memberId }, {
+    base: org.base, token: org.token, idempotencyKey: o.idempotencyKey, fetchImpl: o.fetchImpl,
+  });
+  return {
+    ok: !!(frame && frame.ok),
+    added: !!(frame && frame.ok && frame.result && frame.result.added !== false),
+    frame,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Calling — start / join
 // ---------------------------------------------------------------------------
@@ -660,6 +882,11 @@ export default {
   reactMessage,
   fetchHistory,
   listChannels,
+  openDm,
+  openConversation,
+  createChannel,
+  addChannelMember,
+  normaliseMentions,
   initiateCall,
   joinCall,
   pullInbound,

package/lib/org/messaging.test.mjs

@@ -15,6 +15,10 @@ import {
   reactMessage,
   fetchHistory,
   listChannels,
+  openDm,
+  openConversation,
+  createChannel,
+  addChannelMember,
   initiateCall,
   joinCall,
   pullInbound,
@@ -93,10 +97,41 @@ test("sendMessage: a clean message posts to /v1/messaging.send with Bearer + pro
   // wire shape
   assert.equal(f.calls[0].body.channel, "C-eng");
   assert.equal(f.calls[0].body.body, "Deploy is green on staging.");
-  assert.deepEqual(f.calls[0].body.mentions, ["agent-2"]);
+  // `[{memberId}]`, NOT `["agent-2"]`. hq's mentionSchema is an object schema,
+  // so the bare-string form this used to assert did not merely lose the tag — it
+  // failed zod and 400'd the entire send. The one call an agent makes to bring a
+  // colleague in was the one call guaranteed to fail.
+  assert.deepEqual(f.calls[0].body.mentions, [{ memberId: "agent-2" }]);
   assert.equal(f.calls[0].body.id, "msg-xyz");
 });
 
+test("sendMessage: mentions accept strings or objects, de-dupe, and keep offsets", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "m2b" } } }));
+  await sendMessage(
+    {
+      channel: "C-eng",
+      body: "hi",
+      mentions: ["agent-2", { memberId: "agent-2" }, { id: "agent-3" }, { memberId: "agent-4", offset: 7 }, "", null],
+      idempotencyId: "msg-m",
+    },
+    { cfg: CFG, fetchImpl: f, gateImpl: allowGate, hookBus: captureBus(), ledgerImpl: captureLedger() },
+  );
+  assert.deepEqual(f.calls[0].body.mentions, [
+    { memberId: "agent-2" },
+    { memberId: "agent-3" },
+    { memberId: "agent-4", offset: 7 },
+  ]);
+});
+
+test("sendMessage: no mentions means the key is absent, not an empty array", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "m2c" } } }));
+  await sendMessage(
+    { channel: "C-eng", body: "hi", mentions: [] },
+    { cfg: CFG, fetchImpl: f, gateImpl: allowGate, hookBus: captureBus(), ledgerImpl: captureLedger() },
+  );
+  assert.equal("mentions" in f.calls[0].body, false);
+});
+
 test("sendMessage: emits afterSend + attributes a source='messaging' ledger row on success", async () => {
   const f = fakeFetch(() => ({ body: { ok: true, result: { id: "m3" } } }));
   const ledger = captureLedger();
@@ -353,3 +388,77 @@ test("isDirectedAtAgent: an explicit mentions[] still wins when a producer suppl
   // …and someone else's mention in the same space is still not ours.
   assert.equal(isDirectedAtAgent(ev, "agent-other"), false);
 });
+
+// ---------------------------------------------------------------------------
+// Rooms — the four verbs the SDK had in its protocol table and could not call
+// ---------------------------------------------------------------------------
+
+test("openDm resolves the 1:1 channel and hands back the id the send needs", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { channelId: "C-dm-1", created: true } } }));
+  const r = await openDm({ memberId: "M-2" }, { cfg: CFG, fetchImpl: f });
+  assert.equal(r.ok, true);
+  assert.equal(r.channelId, "C-dm-1");
+  assert.equal(r.created, true);
+  assert.match(f.calls[0].url, /\/v1\/channel\.resolveOrCreateDm$/);
+  assert.deepEqual(f.calls[0].body, { memberId: "M-2" });
+});
+
+test("openDm reads the channel id out of whichever shape the handler returns", async () => {
+  for (const result of [{ id: "C-x" }, { channelId: "C-x" }, { channel: { id: "C-x" } }]) {
+    const r = await openDm({ memberId: "M-2" }, { cfg: CFG, fetchImpl: fakeFetch(() => ({ body: { ok: true, result } })) });
+    assert.equal(r.channelId, "C-x", JSON.stringify(result));
+  }
+});
+
+test("openConversation de-dupes the member list and sends hq's `memberIds`", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "C-gdm" } } }));
+  const r = await openConversation({ memberIds: ["M-2", "M-3", "M-2", ""], name: "Vendor contract" }, { cfg: CFG, fetchImpl: f });
+  assert.equal(r.ok, true);
+  assert.equal(r.channelId, "C-gdm");
+  assert.match(f.calls[0].url, /\/v1\/channel\.createConversation$/);
+  assert.deepEqual(f.calls[0].body.memberIds, ["M-2", "M-3"]);
+  assert.equal(f.calls[0].body.name, "Vendor contract");
+});
+
+test("openConversation with nobody in it never reaches the wire", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: {} } }));
+  const r = await openConversation({ memberIds: [] }, { cfg: CFG, fetchImpl: f });
+  assert.equal(r.ok, false);
+  assert.equal(f.calls.length, 0);
+});
+
+test("createChannel refuses a slug hq would reject, before spending a round trip", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { id: "C-1" } } }));
+  const bad = await createChannel({ slug: "Vendor Contract!", name: "Vendor" }, { cfg: CFG, fetchImpl: f });
+  assert.equal(bad.ok, false);
+  assert.match(bad.frame.error.message, /lowercase alphanumerics and hyphens/);
+  assert.equal(f.calls.length, 0);
+
+  const good = await createChannel({ slug: "vendor-contract", name: "Vendor", members: ["M-2"] }, { cfg: CFG, fetchImpl: f });
+  assert.equal(good.ok, true);
+  assert.equal(f.calls[0].body.kind, "PRIVATE", "a channel an agent makes is private by default");
+  assert.deepEqual(f.calls[0].body.members, ["M-2"]);
+});
+
+test("addChannelMember reports hq's idempotent re-add as added:false, not as a failure", async () => {
+  const f = fakeFetch(() => ({ body: { ok: true, result: { channelId: "C-1", memberId: "M-2", added: false } } }));
+  const r = await addChannelMember({ channelId: "C-1", memberId: "M-2" }, { cfg: CFG, fetchImpl: f });
+  assert.equal(r.ok, true);
+  assert.equal(r.added, false);
+  assert.match(f.calls[0].url, /\/v1\/channel\.addMember$/);
+});
+
+test("every room verb fails open to an error frame when the org is unconfigured", async () => {
+  const off = { org: { cohort: { enabled: false } } };
+  for (const [name, fn, args] of [
+    ["openDm", openDm, { memberId: "M-2" }],
+    ["openConversation", openConversation, { memberIds: ["M-2"] }],
+    ["createChannel", createChannel, { slug: "x", name: "X" }],
+    ["addChannelMember", addChannelMember, { channelId: "C", memberId: "M-2" }],
+  ]) {
+    const r = await fn(args, { cfg: off });
+    assert.equal(r.ok, false, name);
+    assert.equal(r.frame.ok, false, name);
+    assert.ok(r.frame.error.message, `${name} must say why`);
+  }
+});

package/lib/org/param-contract.mjs

@@ -131,6 +131,54 @@ function firstString(...vals) {
   return "";
 }
 
+/**
+ * Coerce `mentions` onto the OBJECT shape hq validates.
+ *
+ * hq's `mentionSchema` is `z.object({memberId, offset?})` and `mentions` is an
+ * array of it (server/validation/message.ts). Every SDK call site wrote the
+ * obvious thing — an array of member id STRINGS — and zod rejects the array, so
+ * the entire `messaging.send` came back BAD_REQUEST. Not "the tags were lost":
+ * the whole message was refused. Tagging somebody is the one action an agent
+ * takes to make a colleague accountable for answering, and it was the one action
+ * guaranteed to fail.
+ *
+ * It belongs HERE, in the one contract every plane goes through, rather than in
+ * any single helper: the curated `messaging_send` tool, the `org_rpc` escape
+ * hatch, the ui-parity wrappers and `messaging.sendMessage` all reach the wire
+ * through `client.call`, and fixing one of them would have left the rest armed.
+ *
+ * Idempotent: already-shaped input passes through untouched.
+ *
+ * @param {object} params
+ * @returns {object}
+ */
+export function normaliseMentionParams(params) {
+  const p = isObj(params) ? params : {};
+  if (!Array.isArray(p.mentions)) return p;
+  const seen = new Set();
+  const mentions = [];
+  for (const m of p.mentions) {
+    let memberId = "";
+    let offset;
+    if (typeof m === "string" || typeof m === "number") {
+      memberId = String(m).trim();
+    } else if (isObj(m)) {
+      memberId = String(m.memberId ?? m.id ?? m.member ?? "").trim();
+      if (Number.isInteger(m.offset) && m.offset >= 0) offset = m.offset;
+    }
+    if (!memberId || seen.has(memberId)) continue;
+    seen.add(memberId);
+    mentions.push(offset === undefined ? { memberId } : { memberId, offset });
+  }
+  // An EMPTY list is dropped rather than sent: hq is happy with `[]`, but an
+  // absent key states "no tags" without asserting an empty relation.
+  if (!mentions.length) {
+    const { mentions: _drop, ...rest } = p;
+    return rest;
+  }
+  return { ...p, mentions: mentions.slice(0, 50) };
+}
+
 /**
  * Project a rich maestro self-entry onto hq's `.strict()` registerSchema
  * ({displayName, archetype, humanSponsor, card}). Everything the server does not
@@ -255,7 +303,11 @@ export const PARAM_CONTRACT = {
     },
     mint: ["idempotencyId"],
     required: ["channelId", "body", "idempotencyId"],
-    note: "hq reads idempotencyId (NOT clientMsgId) — sendMessageSchemaV1.",
+    transform: normaliseMentionParams,
+    note:
+      "hq reads idempotencyId (NOT clientMsgId) — sendMessageSchemaV1. `mentions` is an array of " +
+      "OBJECTS ({memberId, offset?}), not of id strings: the string form fails zod and 400s the " +
+      "whole send, so the transform coerces it.",
   },
   "messaging.history": {
     alias: { channel: "channelId", cursor: "before", since: "after" },
@@ -274,7 +326,9 @@ export const PARAM_CONTRACT = {
     note: "pagination anchors are MESSAGE IDS (before=older, after=newer), not timestamps.",
   },
   "messaging.react": { alias: { channel: "channelId" }, required: ["messageId", "emoji"] },
-  "messaging.edit": { required: ["messageId", "body"] },
+  // Same object-shaped `mentions` as `messaging.send` (editMessageSchema reuses
+  // mentionSchema), so it carries the same landmine and the same fix.
+  "messaging.edit": { required: ["messageId", "body"], transform: normaliseMentionParams },
 
   // ── calling ──────────────────────────────────────────────────────────────
   "calling.start": {

package/lib/org/param-contract.test.mjs

@@ -449,3 +449,29 @@ test("GUARD: enum-valued tool params list exactly hq's vocabulary", () => {
     }
   }
 });
+
+test("messaging.send/edit: mentions are coerced to hq's object shape at the ONE chokepoint", () => {
+  const sent = normalizeParams("messaging.send", {
+    channelId: "C-1",
+    body: "b",
+    idempotencyId: "i",
+    mentions: ["M-2", { memberId: "M-2" }, { id: "M-3" }, { memberId: "M-4", offset: 3 }, "", null],
+  });
+  assert.deepEqual(sent.params.mentions, [
+    { memberId: "M-2" },
+    { memberId: "M-3" },
+    { memberId: "M-4", offset: 3 },
+  ]);
+
+  // Idempotent: applying the contract twice must not re-wrap.
+  const twice = normalizeParams("messaging.send", sent.params);
+  assert.deepEqual(twice.params.mentions, sent.params.mentions);
+
+  // An empty list states nothing rather than asserting an empty relation.
+  const none = normalizeParams("messaging.send", { channelId: "C", body: "b", idempotencyId: "i", mentions: [] });
+  assert.equal("mentions" in none.params, false);
+
+  // messaging.edit reuses hq's mentionSchema, so it gets the same coercion.
+  const edited = normalizeParams("messaging.edit", { messageId: "m1", body: "b", mentions: ["M-9"] });
+  assert.deepEqual(edited.params.mentions, [{ memberId: "M-9" }]);
+});

package/lib/org/protocol.checksum

@@ -1 +1 @@
-1946d98145f4c1e56d80e58c37d9b54d5ea8d88c7d30251a694484418327dddf
+358b95ed6a48faeffa78b7ca717a909905e8ff4e7b75278edf274a0acdaf5dd6

package/lib/org/protocol.mjs

@@ -485,6 +485,11 @@ export const METHODS = Object.freeze({
   "board.removeTaskAttachment": { family: "board", scope: "board.write", sideEffecting: true },
   "board.taskComments": { family: "board", scope: "board.read", sideEffecting: false },
   "board.taskAttachments": { family: "board", scope: "board.read", sideEffecting: false },
+  // board.track — ONE step of an agent's work made visible: find-or-open the row
+  // for an ask, move its column, comment progress, attach what it produced, and
+  // TAG the requester. Idempotent on (askKey, stage): the same step replayed
+  // creates no second row, no duplicate comment and no second notification.
+  "board.track": { family: "board", scope: "board.write", sideEffecting: true, idempotent: true },
   // --- invitation ---
   "invitation.create": { family: "invitation", scope: "admin", sideEffecting: true, idempotent: true },
   "invitation.revoke": { family: "invitation", scope: "admin", sideEffecting: true },

package/lib/org/protocol.test.mjs

@@ -169,8 +169,14 @@ test("protocol: frozen family + method counts (additive evolution guard)", () =>
   // escalation.ask/answer, memory.recall, preference.upsert/list (6 reverse-
   // parity methods), the 9 subagent.* registry methods, agent.wait, the 11
   // mandate.* spine methods, and board.requestReview/resolveReview → 460.
+  // The 2026-08 work-visibility pass adds 1: board.track — ONE step of an
+  // agent's work made visible (find-or-open the row for an ask, move its
+  // column, comment progress, attach output, tag the requester). It is the
+  // single door BOTH planes use: hq's in-process responder calls the same
+  // `server/work/ledger.ts` directly, the daemon reaches it over this wire, so
+  // the threshold and the idempotency cannot fork → 461.
   // the descriptors; the checksum (read at runtime) is the primary drift guard.
-  assert.equal(Object.keys(METHODS).length, 460, "method count");
+  assert.equal(Object.keys(METHODS).length, 461, "method count");
 });
 
 test("protocol SP3: messaging + calling families/methods/scopes", async () => {