@cohortapp/agent-sdk 2.4.1 → 2.5.1

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;
 }
 
 /**
@@ -114,6 +179,8 @@ export async function hydrate(o = {}) {
         return hydrateApproval(c, facts);
       case "handoff":
         return hydrateHandoff(c, facts);
+      case "calendar":
+        return hydrateCalendar(c, facts);
       case "email":
         return await hydrateEmail(c, facts, io, cache);
       default:
@@ -144,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,
@@ -324,6 +398,44 @@ function hydrateEscalation(c, facts) {
   };
 }
 
+/**
+ * A calendar event. The body came back on the ACL'd `calendar.list` read in the
+ * facts pass — that read IS the probe, so there is no second request here and
+ * nothing is rendered that hq did not already hand this seat.
+ */
+function hydrateCalendar(c, facts) {
+  const id = s(c.ids.eventId);
+  const e = facts.myEvents instanceof Map ? facts.myEvents.get(id) : null;
+  const title = s((e && e.title) || c.ids.title || id);
+  const lines = [`${describeCalendarKind(c.kind)} — "${title}"`];
+  const startsAt = s((e && e.startsAt) || c.ids.startsAt);
+  if (startsAt) lines.push(`Starts: ${startsAt}${e && e.endsAt ? ` · ends ${s(e.endsAt)}` : ""}`);
+  if (c.kind === "event.rsvp" && c.ids.rsvp) lines.push(`RSVP: ${s(c.ids.rsvp)}`);
+  if (e && e.location) lines.push(`Location: ${s(e.location)}`);
+  if (e && e.description) lines.push(clip(e.description, 1200));
+  return {
+    ok: true,
+    text: clip(lines.join("\n")),
+    subjectDetail: title,
+    threadId: id,
+    from: { id: s(c.actor), name: s(c.actor) },
+    channelId: s(c.ids.channelId || (e && e.channelId) || ""),
+    channelLabel: `calendar/${title}`,
+  };
+}
+
+/** Human phrasing for a `calendar.*` event kind. */
+export function describeCalendarKind(kind) {
+  switch (kind) {
+    case "event.created": return "Calendar event created";
+    case "event.updated": return "Calendar event updated";
+    case "event.rescheduled": return "Calendar event rescheduled";
+    case "event.rsvp": return "Calendar RSVP";
+    case "event.deleted": return "Calendar event cancelled";
+    default: return "Calendar update";
+  }
+}
+
 /** An approval — already read back by the facts pass (that IS the probe). */
 function hydrateApproval(c, facts) {
   const id = s(c.ids.approvalId);
@@ -427,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/inbound/index.test.mjs

@@ -322,3 +322,86 @@ test("an empty ledger window is a no-op that still advances nothing", async () =
   assert.deepEqual(out.events, []);
   assert.equal(out.nextCursor, 5);
 });
+
+// ---------------------------------------------------------------------------
+// Calendar (JOINT 3) — the surface hq's own agent.wait lanes do not carry
+// ---------------------------------------------------------------------------
+
+/**
+ * The calendar payload is redacted like every other family: `event.created`
+ * carries `attendeeCount` and the CALENDAR OWNER, never the attendee list. So
+ * "am I in this meeting?" is answered by `calendar.list` — hq's seat-scoped
+ * query (owner OR attendeeRows, under the PERSONAL_RESTRICTED lens floor) — and
+ * NEVER by widening the chain payload.
+ */
+test("calendar: an event I attend arrives; a colleague's event never does", async () => {
+  const io = fakeIo({
+    "read:events": okRead({
+      events: [
+        // Mine — I am an attendee (owner is someone else).
+        { seq: 900, family: "calendar", kind: "event.created", entity_id: "EV-mine", actor: BOSS,
+          at: "2026-08-11T10:00:00.000Z",
+          payload: { title: "Transport review", startsAt: "2026-08-12T10:00:00.000Z", endsAt: "2026-08-12T11:00:00.000Z",
+                     eventKind: "MEETING", attendeeCount: 4, calendarMemberId: BOSS } },
+        // NOT mine — a meeting between two colleagues. `calendar.list` will not
+        // return it, so it must never be delivered or hydrated.
+        { seq: 901, family: "calendar", kind: "event.created", entity_id: "EV-theirs", actor: THEM,
+          at: "2026-08-11T10:05:00.000Z",
+          payload: { title: "Their 1:1", startsAt: "2026-08-12T14:00:00.000Z",
+                     eventKind: "MEETING", attendeeCount: 2, calendarMemberId: THEM } },
+      ],
+      nextCursor: 901,
+    }),
+    "calendar.list": okFrame({
+      events: [
+        { id: "EV-mine", title: "Transport review", startsAt: "2026-08-12T10:00:00.000Z",
+          endsAt: "2026-08-12T11:00:00.000Z", location: "Huddle 2", description: "Walk the five hops",
+          calendarMemberId: BOSS, channelId: "C-pub" },
+      ],
+    }),
+  });
+
+  const res = await pullWideInbound({ cfg: CFG, agentId: ME, cursor: 899, io });
+
+  assert.equal(res.events.length, 1, "exactly one calendar item — the one I am in");
+  const ev = res.events[0];
+  assert.equal(ev.kind, "calendar");
+  assert.equal(ev.cohort.surface, "calendar");
+  assert.equal(ev.cohort.reason, "attendee", "attendance was proven by an ACL'd read, not by a payload");
+  assert.match(ev.text, /Calendar event created — "Transport review"/);
+  assert.match(ev.text, /Walk the five hops/);
+  assert.equal(res.stats.bySurface.calendar, 1);
+  assert.equal(res.stats.dropped.calendar_not_mine, 1, "the colleague's meeting was dropped with a named reason");
+
+  // ACL by call log: hq was asked ONE seat-scoped question, and we never probed
+  // the event we were not entitled to.
+  const calendarCalls = io.calls.filter((c) => c.method === "calendar.list");
+  assert.equal(calendarCalls.length, 1, "one list read per pull, not one probe per event");
+  assert.ok(
+    calendarCalls[0].params.calendarMemberId === undefined,
+    "no calendarMemberId → hq uses the ACTING SEAT's viewpoint; naming one would be asking about someone else's calendar",
+  );
+  assert.equal(io.calls.filter((c) => c.method === "calendar.get").length, 0, "no per-event probe at all");
+});
+
+test("calendar: an unreadable calendar fails CLOSED and says so", async () => {
+  const io = fakeIo({
+    "read:events": okRead({
+      events: [
+        { seq: 910, family: "calendar", kind: "event.rescheduled", entity_id: "EV-mine", actor: BOSS,
+          at: "2026-08-11T10:00:00.000Z", payload: { title: "Transport review", to: "2026-08-13T10:00:00.000Z" } },
+      ],
+      nextCursor: 910,
+    }),
+    // calendar.list not routed → the fake returns NOT_FOUND, i.e. a failed read.
+  });
+
+  const res = await pullWideInbound({ cfg: CFG, agentId: ME, cursor: 909, io });
+  assert.equal(res.events.length, 0, "a private surface guesses CLOSED, never open");
+  assert.equal(res.stats.dropped.calendar_unknown, 1);
+  assert.ok(res.stats.degraded.includes("calendar"), "and the degradation is reported, not swallowed");
+  assert.ok(
+    io.logs.some((l) => l.level === "warn" && /calendar\.list unreadable/.test(l.message)),
+    `fail-open is fine, silent is not; got ${JSON.stringify(io.logs)}`,
+  );
+});

package/lib/org/inbound/project.mjs

@@ -144,6 +144,14 @@ export function toMessageEvent(o = {}) {
       family: c.family,
       event_kind: c.kind,
       entity_id: entityId || null,
+      // The subject this surface hangs off, when it is NOT a channel: the task
+      // an approval blocks or an escalation flags, the decision a comment sits
+      // on, the file a comment is against. `channel_id` above deliberately only
+      // ever carries a real Cohort channel — a reply routes with it — so
+      // without this the downstream ladder has the event and no handle on the
+      // thing the event is about. `effects.escalate` needs exactly this to
+      // satisfy hq's "an escalation must reference a task or a channel".
+      scope_id: s(c.ids.taskId || c.ids.decisionId || c.ids.fileId || "") || null,
       seq: c.seq ?? null,
       me: s(me),
     },

package/lib/org/inbound/surfaces.mjs

@@ -127,6 +127,26 @@ export const SURFACES = Object.freeze({
     scope: "channel",
     default: true,
   }),
+  /**
+   * A calendar event on MY calendar, or one I am an attendee of: created,
+   * updated, rescheduled, RSVP'd, deleted.
+   *
+   * ADDRESSING. The `calendar.*` payload is redacted like every other family —
+   * `event.created` carries `attendeeCount`, `invitesQueued` and the CALENDAR
+   * OWNER (`calendarMemberId`), never the attendee list. So ownership is the
+   * only thing the frame can prove, and attendance has to come from
+   * `calendar.list`, which is ACL'd to the acting seat: it returns events where
+   * `calendarMemberId = viewpoint` OR `attendeeRows.some(memberId = viewpoint)`,
+   * under hq's PERSONAL_RESTRICTED lens floor (a colleague's restricted event is
+   * ABSENT, never redacted). We never widen the payload to carry attendees.
+   */
+  calendar: Object.freeze({
+    topic: "calendar",
+    kind: "calendar",
+    subject: "Cohort calendar",
+    scope: "channel",
+    default: true,
+  }),
   /** A delegation offered to me, or one I offered being accepted/declined. */
   handoff: Object.freeze({
     topic: "handoff",

package/lib/org/param-contract.mjs

@@ -422,11 +422,25 @@ export const PARAM_CONTRACT = {
     note: "hq resolves a member by SLUG, not id.",
   },
   "escalation.create": {
-    alias: { subject: "title", body: "detail", description: "detail" },
+    alias: { subject: "title", body: "detail", description: "detail", summary: "title" },
     enums: { severity: ESCALATION_SEVERITIES },
     required: ["title"],
     oneOf: [["taskId", "channelId"]],
-    note: "hq requires a title AND a target (taskId or channelId).",
+    unsupported: ["waitingOnMemberId", "options", "context"],
+    note:
+      "hq requires a title AND a target (taskId or channelId). `summary` is aliased " +
+      "because lib/execution/effects.mjs sent exactly that and 400'd on every call; " +
+      "`waitingOnMemberId`/`options`/`context` are NOT fields of this method — an " +
+      "escalation carrying OPTIONS is an OpenQuestion and belongs at escalation.ask.",
+  },
+  "escalation.ask": {
+    // hq methods/escalation/ask.ts: `question` (<=2000) + >=2 DISTINCT options,
+    // `context` is a STRING (<=4000) — not an object — and `trigger` <=100.
+    // The two-option floor is enforced server-side and is the whole point: an
+    // escalation with one option is a notification, with none it is prose.
+    alias: { text: "question", prompt: "question", choices: "options" },
+    required: ["question", "options"],
+    note: "at least two distinct options, or hq 400s; `context` is a string, not an object.",
   },
 
   // ── leases ───────────────────────────────────────────────────────────────

package/lib/org/protocol.checksum

@@ -1 +1 @@
-85e71129422236b2de83d7f2da1ed04821b9f7c3f7a025a31939cf95d5a4a7db
+1946d98145f4c1e56d80e58c37d9b54d5ea8d88c7d30251a694484418327dddf