@cohortapp/agent-sdk 2.15.0 → 2.17.0

package/lib/context/budget.test.mjs

@@ -0,0 +1,252 @@
+/**
+ * budget.test.mjs — the declared token budget (spec §5.4, SDK half).
+ *
+ * Three properties are under test throughout:
+ *   1. the budget is DECLARED per tier, not discovered by a char clamp;
+ *   2. sections are filled in PRIORITY order, so the trigger survives a budget
+ *      that the backlog cannot, and RENDERED in cache order, which is a
+ *      different order for a different reason; and
+ *   3. every drop is VISIBLE in the rendered text. A silent drop is the bug —
+ *      the reader cannot tell an absent turn from a turn that never happened.
+ *
+ * Run: node --test lib/context/budget.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  TIER_BUDGETS,
+  SECTION_ORDER,
+  FILL_PRIORITY,
+  RENDER_ORDER,
+  CHARS_PER_TOKEN,
+  budgetFor,
+  estimateTokens,
+  fitSections,
+} from "./budget.mjs";
+
+const turns = (n, text = "x".repeat(40)) => Array.from({ length: n }, (_, i) => `s${i}: ${text}`);
+
+// ---------------------------------------------------------------------------
+// the declared budget
+// ---------------------------------------------------------------------------
+
+test("each tier declares its own budget, and the table is frozen", () => {
+  assert.equal(TIER_BUDGETS.answer, 6000);
+  assert.equal(TIER_BUDGETS.work, 12000);
+  assert.equal(TIER_BUDGETS.plan, 20000);
+  assert.equal(Object.isFrozen(TIER_BUDGETS), true);
+});
+
+test("an unknown tier takes the WORK budget rather than an unbounded one", () => {
+  assert.equal(budgetFor("plan"), 20000);
+  assert.equal(budgetFor("nonsense"), TIER_BUDGETS.work);
+  assert.equal(budgetFor(undefined), TIER_BUDGETS.work);
+});
+
+test("estimateTokens is the declared chars-per-token ratio, rounded up", () => {
+  assert.equal(estimateTokens(""), 0);
+  assert.equal(estimateTokens("a".repeat(CHARS_PER_TOKEN)), 1);
+  assert.equal(estimateTokens("a".repeat(CHARS_PER_TOKEN + 1)), 2);
+  assert.equal(estimateTokens(null), 0);
+});
+
+// ---------------------------------------------------------------------------
+// fitting
+// ---------------------------------------------------------------------------
+
+test("everything that fits is kept, verbatim, with no drop notes", () => {
+  const out = fitSections({
+    tier: "plan",
+    sections: [
+      { name: "trigger", text: "fix the invoice total" },
+      { name: "thread", turns: turns(3) },
+    ],
+  });
+  assert.equal(out.drops.length, 0);
+  assert.match(out.text, /fix the invoice total/);
+  assert.doesNotMatch(out.text, /not shown/);
+  assert.ok(out.usedTokens <= out.budgetTokens);
+});
+
+test("an overflowing thread keeps the NEWEST turns and says how many it dropped", () => {
+  const out = fitSections({
+    tier: "answer",
+    budgetTokens: 60, // ~240 chars
+    sections: [
+      { name: "trigger", text: "which one?" },
+      { name: "thread", turns: turns(20, "y".repeat(60)) },
+    ],
+  });
+  const thread = out.sections.find((s) => s.name === "thread");
+  assert.ok(thread.keptTurns > 0, "at least one turn survives");
+  assert.ok(thread.droppedTurns > 0, "the rest were dropped");
+  assert.equal(thread.keptTurns + thread.droppedTurns, 20);
+  // The newest turn is the one nearest the message being answered.
+  assert.match(out.text, /s19:/);
+  assert.doesNotMatch(out.text, /s0:/);
+  assert.match(out.text, new RegExp(`… ${thread.droppedTurns} earlier turns not shown`));
+});
+
+test("the drop note is singular for exactly one dropped turn", () => {
+  // Two turns, and room for the newest one plus its drop note but not for both.
+  const out = fitSections({
+    tier: "answer",
+    budgetTokens: 60,
+    sections: [{ name: "thread", turns: [`s0: ${"a".repeat(200)}`, `s1: ${"b".repeat(200)}`] }],
+  });
+  const thread = out.sections.find((s) => s.name === "thread");
+  assert.equal(thread.keptTurns, 1);
+  assert.equal(thread.droppedTurns, 1);
+  assert.match(out.text, /… 1 earlier turn not shown/);
+  assert.doesNotMatch(out.text, /earlier turns not shown/);
+});
+
+test("sections fill in priority order — the trigger outranks the backlog", () => {
+  const out = fitSections({
+    tier: "answer",
+    budgetTokens: 12,
+    sections: [
+      { name: "backlog", turns: turns(6, "b".repeat(80)) },
+      { name: "trigger", text: "the one question that matters" },
+    ],
+  });
+  assert.match(out.text, /the one question that matters/);
+  const backlog = out.sections.find((s) => s.name === "backlog");
+  assert.equal(backlog.included, false);
+});
+
+test("a section dropped WHOLE is still visible — never silently absent", () => {
+  const out = fitSections({
+    tier: "answer",
+    budgetTokens: 20,
+    sections: [
+      { name: "trigger", text: "t".repeat(60) },
+      { name: "memory", turns: turns(4, "m".repeat(100)) },
+    ],
+  });
+  const memory = out.sections.find((s) => s.name === "memory");
+  assert.equal(memory.included, false);
+  assert.match(out.text, /… memory not shown/);
+  assert.equal(out.drops.some((d) => d.section === "memory"), true);
+});
+
+test("a long text section is clipped and says how many characters went", () => {
+  const body = "z".repeat(4000);
+  const out = fitSections({
+    tier: "answer",
+    budgetTokens: 100,
+    sections: [{ name: "entity", title: "Document", text: body }],
+  });
+  const entity = out.sections.find((s) => s.name === "entity");
+  assert.ok(entity.droppedChars > 0);
+  assert.match(out.text, /characters not shown/);
+  assert.ok(out.usedTokens <= out.budgetTokens);
+});
+
+test("the trigger is never dropped whole — it is the thing being answered", () => {
+  const out = fitSections({
+    tier: "answer",
+    budgetTokens: 5,
+    sections: [{ name: "trigger", text: "q".repeat(2000) }],
+  });
+  const trigger = out.sections.find((s) => s.name === "trigger");
+  assert.equal(trigger.included, true);
+  assert.ok(trigger.text.length > 0);
+});
+
+test("rendered order is CACHE order — stable first, the trigger last", () => {
+  // Fill priority and render order are two different questions. The trigger
+  // WINS the budget (it is the thing being answered) and RENDERS last (it is
+  // the only section that changes on every inbound). A block that opened with
+  // the trigger would have a zero-length stable prefix, so WP-4's cache_control
+  // breakpoint would sit after volatile content and every cache read would miss
+  // silently — design §4, "any byte change before a breakpoint invalidates
+  // everything after it".
+  const out = fitSections({
+    tier: "plan",
+    sections: [
+      { name: "memory", turns: ["m: one"] },
+      { name: "trigger", text: "the ask" },
+      { name: "thread", turns: ["t: two"] },
+      { name: "entity", text: "the card" },
+    ],
+  });
+  assert.deepEqual(out.sections.map((s) => s.name), ["entity", "memory", "thread", "trigger"]);
+  assert.ok(out.text.indexOf("the card") < out.text.indexOf("m: one"));
+  assert.ok(out.text.indexOf("m: one") < out.text.indexOf("t: two"));
+  assert.ok(out.text.indexOf("t: two") < out.text.indexOf("the ask"));
+  assert.ok(out.text.endsWith("the ask"), "the volatile section is the tail, so everything before it can be cached");
+});
+
+test("FILL priority still decides who is dropped — the trigger wins the budget", () => {
+  // Same four sections, a budget only one of them fits. Render order must not
+  // become a fill order by accident: `entity` renders first but `trigger` is
+  // what survives.
+  const out = fitSections({
+    budgetTokens: 8,
+    sections: [
+      { name: "entity", text: "E".repeat(400) },
+      { name: "backlog", text: "B".repeat(400) },
+      { name: "trigger", text: "the ask itself" },
+    ],
+  });
+  const byName = Object.fromEntries(out.sections.map((s) => [s.name, s]));
+  assert.equal(byName.trigger.included, true, "the trigger is filled first, whatever it renders after");
+  assert.equal(byName.trigger.droppedChars, 0, "…and it is filled WHOLE");
+  assert.match(out.text, /the ask itself/);
+  assert.equal(byName.backlog.included, false, "the last section in fill priority is the first to go");
+  assert.ok(byName.entity.droppedChars > 0, "and the higher-priority one is only trimmed");
+  assert.equal(out.text.endsWith("the ask itself"), true, "render order is unchanged by who was dropped");
+});
+
+test("FILL_PRIORITY and RENDER_ORDER name the same sections, and are not the same array", () => {
+  assert.deepEqual([...FILL_PRIORITY].sort(), [...RENDER_ORDER].sort(),
+    "a section that can be filled must be renderable, and vice versa");
+  assert.notDeepEqual([...FILL_PRIORITY], [...RENDER_ORDER]);
+  assert.equal(FILL_PRIORITY[0], "trigger", "the trigger wins the budget");
+  assert.equal(RENDER_ORDER[RENDER_ORDER.length - 1], "trigger", "…and renders last, so the prefix is cacheable");
+});
+
+test("an unknown section name sorts after every declared one, keeping its order", () => {
+  const out = fitSections({
+    tier: "plan",
+    sections: [
+      { name: "weather", text: "w" },
+      { name: "trigger", text: "t" },
+      { name: "tides", text: "d" },
+    ],
+  });
+  assert.deepEqual(out.sections.map((s) => s.name), ["trigger", "weather", "tides"]);
+  assert.equal(SECTION_ORDER.includes("trigger"), true);
+  assert.equal(SECTION_ORDER.includes("weather"), false);
+});
+
+// ---------------------------------------------------------------------------
+// purity
+// ---------------------------------------------------------------------------
+
+test("pure: same input, same output, and the caller's arrays are untouched", () => {
+  const input = { tier: "work", sections: [{ name: "thread", turns: turns(50) }] };
+  const before = JSON.stringify(input);
+  const a = fitSections(input);
+  const b = fitSections(input);
+  assert.deepEqual(a, b);
+  assert.equal(JSON.stringify(input), before, "fitSections mutated its argument");
+});
+
+test("no sections is an empty block, not a throw", () => {
+  const out = fitSections({ tier: "answer", sections: [] });
+  assert.equal(out.text, "");
+  assert.equal(out.usedTokens, 0);
+  assert.deepEqual(out.drops, []);
+});
+
+test("a malformed section is ignored rather than taking the prompt down", () => {
+  const out = fitSections({ tier: "answer", sections: [null, { text: "no name" }, { name: "trigger", text: "ok" }] });
+  assert.equal(out.sections.length, 1);
+  assert.match(out.text, /ok/);
+});

package/lib/context/history-scope.mjs

@@ -0,0 +1,138 @@
+/**
+ * lib/context/history-scope.mjs — which interaction logs may be read for THIS
+ * reply.
+ *
+ * THE DEFECT THIS EXISTS TO CLOSE
+ *
+ * `scripts/daemon/responder.mjs#logInteraction` files every exchange under
+ * `memory/interactions/<service>/…`, and it files each one TWICE: once under the
+ * room (`<channelId>`) and once under the person (`dm-<sender-slug>`). The two
+ * readers — `prompt-builder.mjs` and `context-compiler.mjs` — then merged every
+ * candidate directory into one timestamp-sorted block headed "Recent
+ * conversation history with this sender".
+ *
+ * While that read was pinned to `…/slack/…` the merge was inert for every other
+ * service. Reading the item's own service (design §3 R12) makes it live, and
+ * Cohort is the one service where a person's DMs and the public rooms they post
+ * in share a namespace. So: Dana DMs the agent something private, later
+ * @-mentions the agent in a public channel, and the public room's prompt
+ * carries the DM sentence verbatim. That is design §5.5's resource-scope leak —
+ * "per-person facts may inform a reply but are NEVER quoted into a shared room"
+ * — arriving through the back door of a directory list.
+ *
+ * THE RULE, stated once so both readers and the writer cannot drift:
+ *
+ *   A per-person directory is readable only when the reply itself is going to
+ *   that person privately. In a shared room only the room's own log is read.
+ *   Unknown is not private: an item that does not positively say it is a DM is
+ *   treated as a room.
+ *
+ * PURE. Everything arrives on the argument; nothing is read from disk, the
+ * clock or the environment.
+ *
+ * @module lib/context/history-scope
+ */
+
+"use strict";
+
+/** A blank-safe string. */
+function s(v) {
+  return v == null ? "" : String(v);
+}
+
+/**
+ * Is this inbound item a private 1:1 (or small group DM) conversation?
+ *
+ * The signals, in the order they are trusted:
+ *   1. `is_dm` — set from Cohort's `channel_kind` (`lib/org/inbound/project.mjs`)
+ *      and from Slack's `channel_type` (`scripts/poller/utils.mjs`). A literal
+ *      `false` is a positive assertion of "room" and ends the question.
+ *   2. `channel_type` — Slack's own envelope field: `im` / `mpim`.
+ *   3. A Slack channel id beginning `D` — the convention the raw_ref parser in
+ *      `prompt-builder.mjs` already relies on.
+ *   4. A `dm/<name>` channel label, which is what the Telegram and Slack
+ *      adapters write for a private chat.
+ *
+ * Anything else is a room. That direction is deliberate and is the opposite of
+ * this module's neighbours: everywhere else in hydration an unknown degrades
+ * towards MORE context, because the cost is a thinner prompt. Here the cost of
+ * guessing wrong is one person's private sentence in a public channel, so
+ * unknown buys nothing.
+ *
+ * @param {object} item inbound item (`{service, is_dm, channel_type, channel_id, channel}`)
+ * @returns {boolean}
+ */
+export function isPrivateConversation(item) {
+  if (!item || typeof item !== "object") return false;
+  if (item.is_dm === true) return true;
+  if (item.is_dm === false) return false;
+
+  const type = s(item.channel_type).toLowerCase();
+  if (type === "im" || type === "mpim") return true;
+  if (type === "channel" || type === "group") return false;
+
+  // Slack's own id convention. `service` defaults to slack here for the same
+  // reason both readers write `String(item.service || "slack")` — an item that
+  // predates the per-service split carries no service field, and a `D…` id on
+  // such an item is a Slack DM.
+  const service = s(item.service) || "slack";
+  const channelId = s(item.channel_id || item.channelId);
+  if (service === "slack" && /^D[A-Z0-9]+$/.test(channelId)) return true;
+
+  if (/^dm\//i.test(s(item.channel))) return true;
+
+  return false;
+}
+
+/**
+ * The interaction-log directory NAMES this reply may read, relative to
+ * `memory/interactions/<service>/`. Callers join them onto the service root.
+ *
+ * Ordered room-first so a merged read still prefers the room's own record.
+ * Slack keeps its legacy bare `<sender-slug>` directory alongside the `dm-`
+ * one — historical logs live there and must not go dark — and it is subject to
+ * exactly the same gate.
+ *
+ * @param {object} o
+ * @param {string|null} [o.channelId]  the room/DM channel id, when known
+ * @param {string|null} [o.senderSlug] the sender, slugified
+ * @param {boolean} [o.isPrivate]      is the reply going to that person privately
+ * @param {string} [o.service]
+ * @returns {string[]} directory names, possibly empty
+ */
+export function historyDirNames({ channelId, senderSlug, isPrivate, service } = {}) {
+  const dirs = [];
+  const cid = s(channelId);
+  const slug = s(senderSlug);
+  if (cid) dirs.push(cid);
+  if (isPrivate === true && slug) {
+    dirs.push(`dm-${slug}`);
+    if ((s(service) || "slack") === "slack") dirs.push(slug);
+  }
+  return dirs;
+}
+
+/**
+ * The directories `logInteraction` may WRITE this exchange to.
+ *
+ * The read gate above is the one that stops the leak, but leaving the writer
+ * unconditional keeps every per-person directory permanently contaminated with
+ * public-room content — so a future reader, or an operator grepping the tree,
+ * meets the same defect again. One rule, both ends.
+ *
+ * @param {object} o
+ * @param {string|null} [o.channelId]
+ * @param {string|null} [o.senderSlug]
+ * @param {boolean} [o.isPrivate]
+ * @returns {string[]}
+ */
+export function interactionWriteDirNames({ channelId, senderSlug, isPrivate } = {}) {
+  const dirs = [];
+  const cid = s(channelId);
+  const slug = s(senderSlug);
+  if (cid) dirs.push(cid);
+  if (isPrivate === true && slug) dirs.push(`dm-${slug}`);
+  return dirs;
+}
+
+export default { isPrivateConversation, historyDirNames, interactionWriteDirNames };

package/lib/context/history-scope.test.mjs

@@ -0,0 +1,79 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  isPrivateConversation,
+  historyDirNames,
+  interactionWriteDirNames,
+} from "./history-scope.mjs";
+
+test("is_dm is the authoritative signal, in both directions", () => {
+  assert.equal(isPrivateConversation({ is_dm: true }), true);
+  assert.equal(isPrivateConversation({ is_dm: false, channel_type: "im" }), false,
+    "an explicit is_dm:false is an assertion of 'room' and outranks a stale channel_type");
+});
+
+test("Slack's channel_type and the D-prefixed channel id both read as private", () => {
+  assert.equal(isPrivateConversation({ service: "slack", channel_type: "im" }), true);
+  assert.equal(isPrivateConversation({ service: "slack", channel_type: "mpim" }), true);
+  assert.equal(isPrivateConversation({ service: "slack", channel_id: "D099N1JGKRQ" }), true);
+  assert.equal(isPrivateConversation({ service: "slack", channel_id: "C099N1JGKRQ" }), false);
+  assert.equal(isPrivateConversation({ service: "slack", channel_type: "channel", channel_id: "D1" }), false);
+});
+
+test("a missing service reads as Slack — the historical default both readers use", () => {
+  assert.equal(isPrivateConversation({ channel_id: "D001TESTCH" }), true);
+  assert.equal(isPrivateConversation({ channel_id: "C001TESTCH" }), false);
+  assert.deepEqual(
+    historyDirNames({ channelId: "D001TESTCH", senderSlug: "alice-smith", isPrivate: true }),
+    ["D001TESTCH", "dm-alice-smith", "alice-smith"],
+    "…including its legacy bare-slug directory",
+  );
+});
+
+test("a dm/<name> label counts, and everything unknown is a ROOM", () => {
+  assert.equal(isPrivateConversation({ service: "telegram", channel: "dm/dana" }), true);
+  assert.equal(isPrivateConversation({ service: "cohort", channel_id: "c_capital_formation" }), false,
+    "unknown is not private — guessing wrong here puts a private sentence in a public room");
+  assert.equal(isPrivateConversation(null), false);
+  assert.equal(isPrivateConversation("nope"), false);
+});
+
+test("a shared room reads ONLY the room's own log — never a per-person directory", () => {
+  const dirs = historyDirNames({
+    channelId: "c_capital_formation", senderSlug: "dana", isPrivate: false, service: "cohort",
+  });
+  assert.deepEqual(dirs, ["c_capital_formation"]);
+  assert.equal(dirs.some((d) => d.includes("dana")), false);
+});
+
+test("a DM reads the room and the person; Slack also keeps its legacy bare slug", () => {
+  assert.deepEqual(
+    historyDirNames({ channelId: "c_dm", senderSlug: "dana", isPrivate: true, service: "cohort" }),
+    ["c_dm", "dm-dana"],
+  );
+  assert.deepEqual(
+    historyDirNames({ channelId: "D1", senderSlug: "dana", isPrivate: true, service: "slack" }),
+    ["D1", "dm-dana", "dana"],
+  );
+});
+
+test("the WRITER is gated by the same rule, so per-person logs stay per-person", () => {
+  assert.deepEqual(
+    interactionWriteDirNames({ channelId: "c_public", senderSlug: "dana", isPrivate: false }),
+    ["c_public"],
+  );
+  assert.deepEqual(
+    interactionWriteDirNames({ channelId: "c_dm", senderSlug: "dana", isPrivate: true }),
+    ["c_dm", "dm-dana"],
+  );
+  assert.deepEqual(
+    interactionWriteDirNames({ channelId: null, senderSlug: "dana", isPrivate: true }),
+    ["dm-dana"],
+  );
+  assert.deepEqual(
+    interactionWriteDirNames({ channelId: null, senderSlug: "dana", isPrivate: false }),
+    [],
+    "a room exchange with no room id is not filed under the person as a consolation prize",
+  );
+});

package/lib/model-router/economics.mjs

@@ -310,6 +310,8 @@ const DEFERRABLE_PREFIXES = Object.freeze([
 // the live conversational / inbox path.
 const REALTIME_TASK_CLASSES = Object.freeze(new Set([
   "session.responder",
+  "session.answer",
+  "session.plan",
   "classify.inbox",
   "huddle",
   "voice.brief",
@@ -556,6 +558,13 @@ const HAIKU_EXPLORE = Object.freeze({
 // cheap classes where a subagent would only add overhead.
 const SPAWN_KNOBS = Object.freeze({
   "session.responder": { maxTurns: 40, effort: null, agentsJson: HAIKU_EXPLORE },
+  // The reply tiers (design §5.6 / §5.1). Until now `dispatcher.mjs` hardcoded
+  // `session.responder` for every spawn, so `effort` was ALWAYS null and
+  // `maxTurns` always 40 — complexity moved the model and the timeout and
+  // nothing else. An answer gets low effort and a short leash; a plan gets high
+  // effort, a longer one, and the cheap-subagent map it will actually use.
+  "session.answer":    { maxTurns: 6,  effort: "low",  agentsJson: null },
+  "session.plan":      { maxTurns: 60, effort: "high", agentsJson: HAIKU_EXPLORE },
   "classify.inbox":    { maxTurns: 1,  effort: null, agentsJson: null },
   lookup:              { maxTurns: 2,  effort: null, agentsJson: null },
   enrich:              { maxTurns: 3,  effort: null, agentsJson: null },

package/lib/model-router/resolve.mjs

@@ -93,6 +93,12 @@ const TASK_CLASS_MAX_TURNS = Object.freeze({
   "voice.brief": 4,
   "learning.reflect": 6,
   "learning.curate": 6,
+  // The reply tiers (design §5.6). `session.responder` keeps the historical
+  // default; an ANSWER is a question the classifier already judged answerable,
+  // so a 40-turn ceiling is 39 turns of rope it does not need, and a PLAN is
+  // the rung that genuinely has multi-step work to do.
+  "session.answer": 6,
+  "session.plan": 60,
 });
 
 // ---------------------------------------------------------------------------

package/lib/org/inbound/facts.mjs

@@ -76,7 +76,7 @@ export const DEFAULT_LIMITS = Object.freeze({
  * @property {Map<string,Set<string>>} decisionVoices
  * @property {Map<string,object>|null} escalations
  * @property {Map<string,object>|null} approvals
- * @property {Map<string,object>|null} fileAcl     fileId → {ownerId, shared, mentionsMe}
+ * @property {Map<string,object>|null} fileAcl     fileId → {ownerId, shared, mentionsMe, kind}
  * @property {Set<string>|null} myEventIds        calendar events I own or attend (null == unreadable)
  * @property {Map<string,object>|null} myEvents   eventId → the calendar event DTO
  * @property {string[]} degraded               names of facts that could not be read
@@ -602,7 +602,9 @@ async function resolveFileFacts({ candidates, facts, io, limits, log, degraded }
     const permission = String(res.permission || "").toLowerCase();
     const ownerId = String(file.ownerId || file.owner || "") || null;
     const shared = Boolean(permission && permission !== "none");
-    const entry = { ownerId, shared, permission, mentionsMe: false, name: file.name || "" };
+    // `kind` (DOC | SHEET | DECK | …) rides along so the doc hydrator can skip a
+    // `files.docRead` that hq would answer BAD_REQUEST for. One field, no read.
+    const entry = { ownerId, shared, permission, mentionsMe: false, name: file.name || "", kind: String(file.kind || "") };
 
     if (!shared && !(ownerId && ownerId === facts.me) && facts.myNames.length > 0) {
       const cf = await io.call("files.comments", { fileId, limit: 20 });