@cohortapp/agent-sdk 2.5.0 → 2.6.0

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 () => {