@cohortapp/agent-sdk 2.5.0 → 2.6.0

package/lib/org/inbound/hydrate.mjs

@@ -51,16 +51,81 @@ export function clip(text, max = 4000) {
   return `${sp > max * 0.8 ? cut.slice(0, sp) : cut}…`;
 }
 
-/** Render a comment list into a compact prior-thread context block. */
+/**
+ * How many of the most recent turns must survive a binding character budget.
+ * Without a per-turn cap one long message spends the whole allowance and the
+ * turns around it vanish.
+ */
+const MIN_TURNS_VISIBLE = 4;
+
+/**
+ * Who said it. hq denormalises `authorName` onto history rows, and when it is
+ * there it wins. When it is NOT — an older server, or any surface that never
+ * denormalised one — the fallback is a bare cuid, and a transcript of
+ * "cmqh0t9…: fix this / cmqh0tc…: which one?" loses the single distinction that
+ * matters most: which turns are MINE. An agent that cannot tell its own words
+ * from the sender's re-answers itself and misattributes its own statements back
+ * to them. `facts.me` is always known, so that distinction never has to be lost.
+ */
+export function speakerFor(m, facts) {
+  const name = s(m && m.authorName);
+  if (name) return name;
+  const id = s(m && (m.authorId || m.author));
+  if (facts && facts.me && id === s(facts.me)) {
+    return (Array.isArray(facts.myNames) && facts.myNames[0]) || "me";
+  }
+  return id || "someone";
+}
+
+/**
+ * Render a comment list into a compact prior-thread context block, oldest first.
+ *
+ * ORDER IS NOT A DETAIL HERE. The sources disagree: every comment read
+ * (`board.taskComments`, `file.listComments`, `files.comments`,
+ * `decision.listComments`) returns ASCENDING, but `messaging.history` returns
+ * DESCENDING — hq orders `createdAt desc` unless the caller pages forward with
+ * an `after` cursor, and the inbound pull never does. So the bare `slice(-limit)`
+ * this used to do took the OLDEST rows off a message page and then printed them
+ * backwards: the wrong window, in the wrong direction, silently.
+ *
+ * Sorting on the timestamp makes the tail mean "the most recent turns" for every
+ * source. The sort is stable and the comparator declines to order rows with no
+ * parseable timestamp, so a source that carries none keeps its arrival order.
+ */
 export function renderThread(comments, { limit = 8, max = 2000 } = {}) {
-  const rows = (Array.isArray(comments) ? comments : []).slice(-limit);
+  const all = (Array.isArray(comments) ? comments : []).slice();
+  all.sort((a, b) => {
+    const ta = Date.parse(s(a && (a.createdAt || a.at)));
+    const tb = Date.parse(s(b && (b.createdAt || b.at)));
+    if (!Number.isFinite(ta) || !Number.isFinite(tb)) return 0;
+    return ta - tb;
+  });
+  const rows = all.slice(-limit);
   if (rows.length === 0) return null;
+
+  // Spend the budget from the NEWEST turn backwards. Clipping the joined string
+  // — which is what this did — keeps the oldest turns and drops the newest, the
+  // exact inverse of what context is for: the turns nearest the message being
+  // answered are the ones that explain it. Caught on the live CEO DM, where one
+  // long reply of mine filled the 2000 chars and displaced the four newer turns,
+  // including the question under discussion. The per-turn cap is the other half:
+  // without it a single long message starves every turn around it.
+  const perTurn = Math.max(200, Math.floor(max / Math.min(rows.length, MIN_TURNS_VISIBLE)));
   const lines = rows.map((c) => {
     const who = s(c.authorName || c.authorId || c.author || "someone");
-    const body = s(c.body || c.text).replace(/\s+/g, " ").trim();
+    const body = clip(s(c.body || c.text).replace(/\s+/g, " ").trim(), perTurn);
     return `${who}: ${body}`;
   });
-  return clip(lines.join("\n"), max) || null;
+
+  const kept = [];
+  let used = 0;
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const cost = lines[i].length + (kept.length ? 1 : 0); // +1 for the joining newline
+    if (kept.length > 0 && used + cost > max) break;
+    kept.unshift(lines[i]);
+    used += cost;
+  }
+  return kept.join("\n") || null;
 }
 
 /**
@@ -146,17 +211,24 @@ function hydrateMessage(c, facts) {
 
   const chan = facts.channels instanceof Map ? facts.channels.get(s(c.ids.channelId)) : null;
   const root = s(msg.threadRootId || msg.thread_root_id);
-  let threadContext = null;
-  if (root && page) {
-    const siblings = page.messages.filter(
-      (m) => s(m.threadRootId || m.thread_root_id) === root || s(m.id) === root,
-    );
-    threadContext = renderThread(
-      siblings
-        .filter((m) => s(m.id) !== s(c.ids.messageId))
-        .map((m) => ({ authorName: m.authorName || m.authorId, body: m.body ?? m.text })),
-    );
-  }
+
+  // THE CONVERSATION SO FAR. For a thread reply that is the thread; for a
+  // TOP-LEVEL message it is the channel itself — which is the whole of a DM.
+  // This used to be gated on `root`, so a DM (no thread root, by definition)
+  // arrived with no context at all and the agent answered "fix this" without
+  // ever seeing what "this" referred to. The page is already in hand from the
+  // ACL'd `messaging.history` read `pageChannels` made, so re-joining it here
+  // costs no RPC and widens nothing: it is the same read, same aperture.
+  const scope = root
+    ? page.messages.filter((m) => s(m.threadRootId || m.thread_root_id) === root || s(m.id) === root)
+    : page.messages;
+  const threadContext = renderThread(
+    priorTo(scope, msg, c.ids.messageId).map((m) => ({
+      authorName: speakerFor(m, facts),
+      body: m.body ?? m.text,
+      createdAt: m.createdAt,
+    })),
+  );
 
   return {
     ok: true,
@@ -467,6 +539,26 @@ async function hydrateEmail(c, facts, io, cache) {
 // Small helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * The messages that came BEFORE the trigger — never the ones after it.
+ *
+ * A history page is a window, not a prefix: when the pull is running behind, or
+ * replaying after a crash, the page can hold turns that were said AFTER the
+ * message being hydrated. Handing those to the agent as "prior context" would
+ * have it answer a question using an answer it has not given yet. When a row
+ * carries no parseable timestamp we keep it rather than guess — dropping real
+ * conversation is the failure mode being fixed here.
+ */
+function priorTo(messages, trigger, triggerId) {
+  const at = Date.parse(s(trigger && trigger.createdAt));
+  return (Array.isArray(messages) ? messages : []).filter((m) => {
+    if (s(m.id) === s(triggerId)) return false;
+    if (!Number.isFinite(at)) return true;
+    const t = Date.parse(s(m.createdAt));
+    return !Number.isFinite(t) || t <= at;
+  });
+}
+
 /** Memoise an async read for the lifetime of one pull. */
 async function cached(cache, key, fn) {
   if (cache.has(key)) return cache.get(key);

package/lib/org/inbound/hydrate.test.mjs

@@ -118,6 +118,64 @@ test("a threaded message carries prior-thread context", async () => {
   assert.doesNotMatch(h.threadContext, /one more thing/, "the trigger itself is not its own context");
 });
 
+// A DM has no thread root — the CHANNEL is the conversation. Before this, the
+// `if (root)` guard meant a top-level message carried no context at all, so the
+// agent answered "fix this" with no idea what "this" referred to. The page is
+// already in hand from the ACL'd `messaging.history` read, so this costs no RPC.
+test("a top-level DM carries the preceding conversation as context", async () => {
+  // Newest-first, exactly as hq's messaging.history returns it.
+  const msgs = [
+    { id: "m3", authorId: THEM, authorName: "Casey", body: "fix this then", createdAt: "2026-08-11T15:33:54.000Z" },
+    { id: "m2", authorId: ME, authorName: "Alex", body: "16 min pickup on the morning batch", createdAt: "2026-08-11T15:32:00.000Z" },
+    { id: "m1", authorId: THEM, authorName: "Casey", body: "what is the reply latency here", createdAt: "2026-08-11T15:31:00.000Z" },
+  ];
+  const f = facts();
+  f.channels.set("C-dm", { id: "C-dm", kind: "DM", name: "dm-h001-a016" });
+  f.channelPages.set("C-dm", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m3", payload: { actor: THEM, channelId: "C-dm", channelKind: "DM" } }));
+  const io = fakeIo({});
+  const h = await hydrate({ candidate: c, verdict: { surface: "dm", reason: "dm" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.equal(io.calls.length, 0, "the page was already in hand — context must cost no extra RPC");
+  assert.ok(h.threadContext, "a DM with prior turns must carry them");
+  assert.match(h.threadContext, /Casey: what is the reply latency here/);
+  assert.match(h.threadContext, /Alex: 16 min pickup/);
+  assert.doesNotMatch(h.threadContext, /fix this then/, "the trigger itself is not its own context");
+  assert.ok(
+    h.threadContext.indexOf("what is the reply latency") < h.threadContext.indexOf("16 min pickup"),
+    "oldest first — the conversation must read forwards",
+  );
+});
+
+test("a first-ever message in a channel has no context, not an empty block", async () => {
+  const msgs = [{ id: "m1", authorId: THEM, authorName: "Casey", body: "hello", createdAt: "2026-08-11T15:31:00.000Z" }];
+  const f = facts();
+  f.channels.set("C-dm", { id: "C-dm", kind: "DM" });
+  f.channelPages.set("C-dm", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m1", payload: { actor: THEM, channelId: "C-dm", channelKind: "DM" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "dm", reason: "dm" }, facts: f, io: fakeIo({}) });
+
+  assert.equal(h.ok, true);
+  assert.equal(h.threadContext, null);
+});
+
+test("messages AFTER the trigger are never passed off as prior context", async () => {
+  const msgs = [
+    { id: "m3", authorId: THEM, authorName: "Casey", body: "later message", createdAt: "2026-08-11T16:00:00.000Z" },
+    { id: "m2", authorId: THEM, authorName: "Casey", body: "the trigger", createdAt: "2026-08-11T15:00:00.000Z" },
+    { id: "m1", authorId: ME, authorName: "Alex", body: "earlier message", createdAt: "2026-08-11T14:00:00.000Z" },
+  ];
+  const f = facts();
+  f.channels.set("C-dm", { id: "C-dm", kind: "DM" });
+  f.channelPages.set("C-dm", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m2", payload: { actor: THEM, channelId: "C-dm", channelKind: "DM" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "dm", reason: "dm" }, facts: f, io: fakeIo({}) });
+
+  assert.match(h.threadContext, /earlier message/);
+  assert.doesNotMatch(h.threadContext, /later message/);
+});
+
 // ---------------------------------------------------------------------------
 // board
 // ---------------------------------------------------------------------------
@@ -318,6 +376,75 @@ test("clip and renderThread are bounded", () => {
   assert.match(renderThread([{ authorName: "A", body: "hi" }]), /A: hi/);
 });
 
+// `messaging.history` returns DESCENDING; every comment source returns ASCENDING.
+// A bare slice(-limit) therefore took the OLDEST rows off a message page and
+// printed them backwards — the wrong window, in the wrong order.
+test("renderThread reads forwards and keeps the most RECENT turns", () => {
+  const rows = [];
+  for (let i = 12; i >= 1; i -= 1) {
+    rows.push({ authorName: "A", body: `turn ${i}`, createdAt: `2026-08-11T00:${String(i).padStart(2, "0")}:00.000Z` });
+  }
+  const out = renderThread(rows); // limit 8
+
+  assert.match(out, /turn 12/, "the newest turn is the one that matters most");
+  assert.doesNotMatch(out, /turn 1\b/, "the oldest turns fall off the window, not the newest");
+  assert.ok(out.indexOf("turn 5") < out.indexOf("turn 12"), "oldest first");
+});
+
+test("renderThread leaves undated rows in the order they arrived", () => {
+  const out = renderThread([
+    { authorName: "A", body: "first" },
+    { authorName: "B", body: "second" },
+  ]);
+  assert.ok(out.indexOf("first") < out.indexOf("second"));
+});
+
+// The `limit` window and the `max` CHARACTER budget are two different windows,
+// and only the first was covered: twelve short turns never reach 2000 chars, so
+// the clip never fired and the direction it clips in was never asserted. On the
+// real DM it fired immediately — one long reply filled the budget and the four
+// newest turns, including the question being answered, were the ones discarded.
+test("renderThread keeps the NEWEST turns when the CHARACTER budget binds", () => {
+  const out = renderThread(
+    [
+      { authorName: "A", body: "x".repeat(1500), createdAt: "2026-08-11T00:01:00.000Z" },
+      { authorName: "B", body: "the thing I actually asked", createdAt: "2026-08-11T00:02:00.000Z" },
+    ],
+    { max: 300 },
+  );
+  assert.match(out, /the thing I actually asked/, "the latest turn must survive the budget");
+});
+
+test("renderThread does not let one huge turn starve the turns around it", () => {
+  const out = renderThread(
+    [
+      { authorName: "A", body: "y".repeat(5000), createdAt: "2026-08-11T00:01:00.000Z" },
+      { authorName: "B", body: "second", createdAt: "2026-08-11T00:02:00.000Z" },
+      { authorName: "C", body: "third", createdAt: "2026-08-11T00:03:00.000Z" },
+    ],
+    { max: 2000 },
+  );
+  assert.match(out, /B: second/);
+  assert.match(out, /C: third/);
+  assert.ok(out.length <= 2100, `bounded, got ${out.length}`);
+});
+
+// Until hq's `authorName` denormalisation is deployed every row carries a bare
+// cuid, and the agent must still be able to see which turns are its own.
+test("a transcript labels my own turns even when the server sends no names", async () => {
+  const msgs = [
+    { id: "m1", authorId: ME, body: "already answered that", createdAt: "2026-08-11T14:00:00.000Z" },
+    { id: "m2", authorId: THEM, body: "and the other thing?", createdAt: "2026-08-11T15:00:00.000Z" },
+  ];
+  const f = facts({ myNames: ["Isla"] });
+  f.channels.set("C-dm", { id: "C-dm", kind: "DM" });
+  f.channelPages.set("C-dm", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m2", payload: { actor: THEM, channelId: "C-dm", channelKind: "DM" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "dm", reason: "dm" }, facts: f, io: fakeIo({}) });
+
+  assert.match(h.threadContext, /Isla: already answered that/, "my own turn is mine, not a cuid");
+});
+
 test("event-kind phrasing is stable and total", () => {
   assert.match(describeBoardKind("item.assigned"), /assigned to you/);
   assert.match(describeBoardKind("who.knows"), /Update on your board item/);

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,