@cohortapp/agent-sdk 2.18.13 → 2.18.15

package/lib/assurance/first-reply.mjs

@@ -0,0 +1,423 @@
+/**
+ * lib/assurance/first-reply.mjs — what an agent says FIRST, and whether it says
+ * anything at all.
+ *
+ * THE DIRECTIVE THIS IMPLEMENTS (owner, 2026-09-25, with four screenshots of
+ * the org's own channels attached)
+ *
+ *   "Get rid of the use of these kind of generic placeholder replies. Instead,
+ *   the first reply should come as part of the actual LLM's initial
+ *   consideration of the question, and then replying with an appropriate
+ *   initial short reply that uses a natural tone of voice that is contextually
+ *   relevant… So for example, if there's a flurry of 4 messages in one go by
+ *   others, instead of having a generic reply per message, it would be
+ *   responding to the batch of messages. And then also, sometimes a reply isn't
+ *   needed (only do this when it truly doesn't need any reply), and then also
+ *   sometimes the initial response can be an emoji response."
+ *
+ * Three decisions fall out of that, and all three are made HERE, as pure
+ * functions, rather than as sentences in a system prompt. A rule that lives
+ * only in a prompt is a rule nothing checks: the ack prompt has said "never a
+ * generic 'on it'" since it was written, and 3,069 generic acks shipped anyway
+ * (see `tier.mjs`). Prompts state intent; functions are the enforcement.
+ *
+ *   SHAPE  — none / react / line. `firstReplyShape` below.
+ *   BATCH  — a flurry in one room is ONE first reply, not one per message.
+ *            `groupForFirstReply` below.
+ *   VOICE  — the line itself is generated from the actual thread
+ *            (`scripts/daemon/assurance.generateAck`); this module never
+ *            composes prose, it only decides whether prose is owed.
+ *
+ * THE REGISTER, AND WHY IT IS A LIST OF EXACT SENTENCES
+ *
+ * `RETIRED_FIRST_REPLIES` holds the four sentences the owner screenshotted, in
+ * the exact bytes they shipped in. Two separate defects put them on screen and
+ * the register answers both:
+ *
+ *   (1) Two seats were still running a preserved local copy of the daemon that
+ *       predates the 2026-08-30 removal of the canned rotation, and went on
+ *       emitting "On it." / "Looking now." / "On it — digging in now." while
+ *       reporting a current SDK version. `isRetiredFirstReply` is the check at
+ *       the SEND chokepoint that makes a stale composer upstream unable to put
+ *       one on screen anyway.
+ *   (2) The failure notices were deterministic strings by design, so every
+ *       dead session in the fleet said the same two sentences. Those two are
+ *       in the register too, which is what makes it impossible to reintroduce
+ *       them by editing the composer back.
+ *
+ * PURE. Nothing here reads the clock, the filesystem, the environment or the
+ * network; every input arrives on the argument. That is what lets the whole
+ * matrix be pinned by a test rather than sampled off a live daemon.
+ *
+ * @module lib/assurance/first-reply
+ */
+
+"use strict";
+
+/**
+ * The exact sentences the owner screenshotted on 2026-09-25, byte for byte.
+ *
+ * FROZEN LITERALS, deliberately — the opposite convention to
+ * `assurance.narratorPatterns()`, which derives its templates from the live
+ * composers so the list cannot drift from the emitter. Here drift is the POINT:
+ * these must stay recognisable after the composers that produced them are gone,
+ * and a derived list would delete them at exactly the moment they stop being
+ * produced locally and start arriving from a seat that has not updated yet.
+ *
+ * @type {readonly string[]}
+ */
+export const RETIRED_FIRST_REPLIES = Object.freeze([
+  "On it.",
+  "Looking now.",
+  "On it — digging in now.",
+  "Hit a problem — the working session ended with an error. Retrying now; if it fails again I'll come straight back rather than leave you waiting.",
+  "Couldn't finish this — the work never came back with a result and has now outrun its time limit. I've stopped retrying and flagged it so it isn't lost. Want me to try a narrower version, hand it off, or leave it with you?",
+]);
+
+/**
+ * The same five with their variable middle replaced by a wildcard, so the
+ * register catches the whole FAMILY and not only the one cause that happened
+ * to be screenshotted. `composeFailure`'s cause is interpolated; "the working
+ * session ended with an error" and "the work never came back with a result and
+ * has now outrun its time limit" are two of roughly a dozen `classifyFailure`
+ * can produce, and pinning only those two would leave ten siblings live.
+ */
+const RETIRED_PATTERNS = Object.freeze([
+  /^on it[.!]?$/i,
+  /^looking now[.!]?$/i,
+  /^on it\s*[—–-]\s*digging in now[.!]?$/i,
+  /^hit a problem\s*[—–-]\s*.+\.\s*retrying now;\s*if it fails again i'?ll come straight back rather than leave you waiting\.?$/i,
+  /^couldn'?t finish this\s*[—–-]\s*.+\.\s*i'?ve stopped retrying and flagged it so it isn'?t lost\.\s*want me to try a narrower version,\s*hand it off,\s*or leave it with you\?$/i,
+]);
+
+/**
+ * One line, in the shape the register compares. Collapses whitespace, unifies
+ * the three dashes and the two apostrophes, and trims — so a copy that survived
+ * a round trip through a chat client's smart-quote substitution still matches.
+ *
+ * @param {unknown} text
+ * @returns {string}
+ */
+export function normaliseLine(text) {
+  return String(text == null ? "" : text)
+    .replace(/[‘’ʼ]/g, "'")
+    .replace(/[“”]/g, '"')
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Split a body into the units the register judges: paragraphs, then lines.
+ *
+ * WHY PARAGRAPHS AND NOT THE WHOLE BODY. The owner's 15:04 screenshot showed
+ * the same failure sentence twice under one timestamp. Whatever produced that —
+ * two notices concatenated, or a client rendering two sends as one block — a
+ * check that only tests the WHOLE string against the register would pass it,
+ * because "<sentence>\n\n<sentence>" is not equal to "<sentence>". Judging each
+ * paragraph closes that.
+ *
+ * @param {unknown} body
+ * @returns {string[]}
+ */
+export function bodySegments(body) {
+  const t = String(body == null ? "" : body).trim();
+  if (!t) return [];
+  const out = [];
+  for (const para of t.split(/\n\s*\n/)) {
+    const p = normaliseLine(para);
+    if (p) out.push(p);
+    for (const line of para.split("\n")) {
+      const l = normaliseLine(line);
+      if (l && l !== p) out.push(l);
+    }
+  }
+  return out;
+}
+
+/**
+ * Is this text — or any paragraph of it — one of the retired placeholder
+ * replies?
+ *
+ * Used as the last gate before a send, so it answers the only question that
+ * matters there: would a reader see one of these sentences on screen. It does
+ * NOT try to judge whether a line is "generic" in general; `GENERIC_OPENER` in
+ * `plan-note.mjs` owns that, and this is the narrower, exact, un-arguable half.
+ *
+ * @param {unknown} text
+ * @returns {boolean}
+ */
+export function isRetiredFirstReply(text) {
+  const segs = bodySegments(text);
+  if (!segs.length) return false;
+  return segs.some((s) => RETIRED_PATTERNS.some((re) => re.test(s)));
+}
+
+/**
+ * Does a body repeat one of its own paragraphs verbatim?
+ *
+ * The 15:04 defect, made checkable independently of WHICH sentence repeated.
+ * A body that says the same paragraph twice is telling the reader nothing the
+ * second time; whatever composed it has double-counted.
+ *
+ * @param {unknown} body
+ * @returns {boolean}
+ */
+export function repeatsItself(body) {
+  const paras = String(body == null ? "" : body)
+    .trim()
+    .split(/\n\s*\n/)
+    .map(normaliseLine)
+    .filter((p) => p.length >= 12); // a bare "Yes." or a bullet marker may legitimately recur
+  if (paras.length < 2) return false;
+  return new Set(paras).size !== paras.length;
+}
+
+// ---------------------------------------------------------------------------
+// THE SHAPE DECISION
+// ---------------------------------------------------------------------------
+
+/** The three things a first response can be. */
+export const SHAPES = Object.freeze(["none", "react", "line"]);
+
+/**
+ * Reactions, by what the message was. Deliberately tiny and deliberately dull:
+ * a reaction is an acknowledgement, not a performance, and a vocabulary big
+ * enough to be expressive is a vocabulary big enough to be wrong.
+ *
+ * `seen` is the default because it is the only one that is always honest — it
+ * claims nothing beyond "this reached me".
+ */
+export const REACTIONS = Object.freeze({
+  seen: "👀",
+  agreed: "👍",
+  thanks: "🙏",
+  done: "✅",
+});
+
+/**
+ * Classifier actions that are, by their own verdict, nothing to answer.
+ * `archive` and `ignore` are the classifier saying so in as many words.
+ */
+const NO_REPLY_ACTIONS = Object.freeze(["archive", "ignore"]);
+
+/**
+ * Does this inbound ASK something of the agent?
+ *
+ * A question mark is the strong signal but not the only one: "let me know what
+ * you think" and "can you take this" are questions without one. Kept narrow on
+ * purpose — the cost of a false negative here is an emoji where a sentence was
+ * owed, which is the failure the owner explicitly warned about ("an emoji is
+ * wrong for a question").
+ *
+ * @param {unknown} text
+ * @returns {boolean}
+ */
+export function asksSomething(text) {
+  const t = normaliseLine(text);
+  if (!t) return false;
+  if (t.includes("?")) return true;
+  if (/\b(let me know|tell me|send me|can you|could you|would you|please|pls|need you to|thoughts\?*$|any update|update on|when can|how soon)\b/i.test(t)) return true;
+  // An interrogative opener is a question whatever the punctuation. Chat drops
+  // the question mark constantly ("what's the status on the raise", "when does
+  // the window close"), and a dropped mark must not downgrade a question to an
+  // emoji — that is the one outcome the owner named as wrong. Erring toward
+  // `true` costs a sentence where a reaction would have done; erring toward
+  // `false` leaves a question answered with a thumb.
+  if (/^(what|when|where|who|whose|which|why|how|is|are|was|were|do|does|did|can|could|would|should|will|have|has|any)\b/i.test(t)) return true;
+  return false;
+}
+
+/**
+ * THE DECISION: what is the first thing said about this inbound, if anything?
+ *
+ * The rules, in the order they are applied, because the order IS the policy:
+ *
+ *   1. Already covered by a batch ⇒ `none`. One flurry, one first reply. This
+ *      is first because it outranks every other reason to speak: the batch's
+ *      OWN first reply has already said whatever was owed.
+ *   2. Tier `answer` ⇒ `none`. Unchanged and load-bearing — the reply arrives
+ *      in this turn, so anything in front of it is the content-free traffic
+ *      `tier.mjs` was written to delete.
+ *   3. The classifier says archive/ignore ⇒ `none`.
+ *   4. Not addressed to this agent and asking nothing ⇒ `none`. This is the
+ *      owner's "sometimes a reply isn't needed", scoped as narrowly as he
+ *      scoped it ("only do this when it truly doesn't need any reply"): the
+ *      agent must be neither the addressee NOR asked anything.
+ *   5. Addressed, but asking nothing, on a surface that has reactions ⇒
+ *      `react`. The FYI case. An acknowledgement is owed — someone deliberately
+ *      put this in front of this agent — but a sentence would be noise.
+ *   6. Otherwise ⇒ `line`, and the line is generated, never canned.
+ *
+ * Note rule 5's guard: `asksSomething` must be FALSE. A question never gets an
+ * emoji, whatever else is true of it. That is the distinction the owner drew
+ * and it is the one this function exists to make mechanical.
+ *
+ * @param {object} [o]
+ * @param {"answer"|"work"|"plan"} [o.tier]  from `replyTier`
+ * @param {string} [o.action]                classifier action
+ * @param {boolean} [o.directed]             was this agent addressed (mention, DM, assignment)
+ * @param {string} [o.text]                  the inbound body
+ * @param {boolean} [o.coveredByBatch]       an earlier message in this flurry already owns the first reply
+ * @param {boolean} [o.reactionsAvailable]   does this surface support a reaction
+ * @param {string} [o.reaction]              which REACTIONS key, when one is right
+ * @returns {{shape:"none"|"react"|"line", emoji:string|null, reason:string}}
+ */
+export function firstReplyShape(o = {}) {
+  const a = o && typeof o === "object" ? o : {};
+  const none = (reason) => ({ shape: "none", emoji: null, reason });
+
+  if (a.coveredByBatch === true) return none("covered-by-batch");
+  if (a.tier === "answer") return none("tier-answer");
+  if (NO_REPLY_ACTIONS.includes(String(a.action || ""))) return none(`action-${a.action}`);
+
+  const asks = asksSomething(a.text);
+  if (a.directed !== true && !asks) return none("not-directed-nothing-asked");
+
+  if (!asks && a.reactionsAvailable === true) {
+    const key = Object.prototype.hasOwnProperty.call(REACTIONS, String(a.reaction || "")) ? String(a.reaction) : "seen";
+    return { shape: "react", emoji: REACTIONS[key], reason: "acknowledged-not-answered" };
+  }
+
+  return { shape: "line", emoji: null, reason: asks ? "question-owed-an-answer" : "no-reaction-surface" };
+}
+
+// ---------------------------------------------------------------------------
+// THE BATCH
+// ---------------------------------------------------------------------------
+
+/** How close together messages must be to count as one flurry. */
+export const DEFAULT_BATCH_WINDOW_MS = 3 * 60_000;
+
+/** The room a first reply would land in. Thread-aware: two threads in one
+ *  channel are two conversations and each is owed its own first reply. */
+function conversationKey(item) {
+  const i = item && typeof item === "object" ? item : {};
+  const svc = String(i.service || "").trim().toLowerCase() || "unknown";
+  const ch = String(i.channel_id || "").trim().toLowerCase() || "unknown";
+  const th = String(i.thread_id || "").trim().toLowerCase();
+  return th ? `${svc}|${ch}|t:${th}` : `${svc}|${ch}`;
+}
+
+const atOf = (item) => {
+  const v = item && (item.received_at ?? item.ts ?? item.createdAt ?? item.at);
+  const n = typeof v === "number" ? v : Date.parse(String(v || ""));
+  return Number.isFinite(n) ? n : null;
+};
+
+/**
+ * Group a poll's worth of inbound into the flurries a human would recognise.
+ *
+ * "If there's a flurry of 4 messages in one go by others, instead of having a
+ * generic reply per message, it would be responding to the batch." So: same
+ * conversation, within `windowMs` of the previous message in that conversation,
+ * is one batch. The batch's FIRST message carries the reply; every later member
+ * is returned with `coveredByBatch`, which rule 1 of `firstReplyShape` turns
+ * into silence.
+ *
+ * The leader is the first message, not the last, because the first is the one
+ * the generated line is composed against — and every other member of the batch
+ * is handed to that composer as context, so the one line answers all four.
+ *
+ * PURE: the clock arrives as a field on each item, never from `Date.now()`.
+ * An item with no readable timestamp starts its own batch rather than being
+ * folded into whatever came before it — guessing a time is how four unrelated
+ * asks become one reply.
+ *
+ * @param {Array<object>} items
+ * @param {object} [o] {windowMs}
+ * @returns {Array<{key:string, leader:object, members:object[]}>}
+ */
+export function groupForFirstReply(items, o = {}) {
+  const windowMs = Number.isFinite(o.windowMs) ? o.windowMs : DEFAULT_BATCH_WINDOW_MS;
+  const list = Array.isArray(items) ? items.filter((i) => i && typeof i === "object") : [];
+  const ordered = list
+    .map((item, idx) => ({ item, idx, at: atOf(item) }))
+    .sort((x, y) => (x.at ?? Number.POSITIVE_INFINITY) - (y.at ?? Number.POSITIVE_INFINITY) || x.idx - y.idx);
+
+  const open = new Map(); // conversationKey → {batch, lastAt}
+  const batches = [];
+  for (const { item, at } of ordered) {
+    const key = conversationKey(item);
+    const cur = open.get(key);
+    const joinable = cur && at != null && cur.lastAt != null && at - cur.lastAt <= windowMs;
+    if (joinable) {
+      cur.batch.members.push(item);
+      cur.lastAt = at;
+      continue;
+    }
+    const batch = { key, leader: item, members: [item] };
+    batches.push(batch);
+    open.set(key, { batch, lastAt: at });
+  }
+  return batches;
+}
+
+/**
+ * The per-item verdict for a whole poll: every item, with the batch it belongs
+ * to and whether it is the one that speaks.
+ *
+ * @param {Array<object>} items
+ * @param {object} [o] {windowMs}
+ * @returns {Array<{item:object, key:string, leader:boolean, batchSize:number, coveredByBatch:boolean}>}
+ */
+export function firstReplyPlan(items, o = {}) {
+  const out = [];
+  for (const b of groupForFirstReply(items, o)) {
+    b.members.forEach((item, i) => {
+      out.push({
+        item,
+        key: b.key,
+        leader: i === 0,
+        batchSize: b.members.length,
+        coveredByBatch: i !== 0,
+      });
+    });
+  }
+  return out;
+}
+
+/**
+ * Stamp a poll's worth of inbound with its flurry verdict, in place.
+ *
+ * WHY THIS IS A FUNCTION AND NOT FOUR LINES IN THE DAEMON. It used to be four
+ * lines inside `pollService`, and that made the wiring untestable: the only
+ * call site was inside a module-internal function, so deleting it left every
+ * test — including one named "wired, not just available" — green. A defect that
+ * no test can detect is the exact shape that let the previous generation of
+ * this fix rot unnoticed, so the loop moved here, where a test can call it, and
+ * `scripts/daemon/agent-daemon.pollService` calls this.
+ *
+ * MUTATES ITS INPUT, deliberately. `processItem` is called per item further
+ * down the same function and reads the stamp off the item it is handed; a
+ * returned copy would be thrown away. The mutation is confined to two fields
+ * this module owns.
+ *
+ * @param {Array<object>} items the poll's surviving items, in arrival order
+ * @param {object} [o] {windowMs}
+ * @returns {Array<{item:object, key:string, leader:boolean, batchSize:number, coveredByBatch:boolean}>}
+ *          the plan, for a caller that wants to log or assert on it
+ */
+export function stampFirstReplyPlan(items, o = {}) {
+  const plan = firstReplyPlan(items, o);
+  for (const p of plan) {
+    p.item.covered_by_batch = p.coveredByBatch;
+    p.item.batch_size = p.batchSize;
+  }
+  return plan;
+}
+
+export default {
+  RETIRED_FIRST_REPLIES,
+  SHAPES,
+  REACTIONS,
+  DEFAULT_BATCH_WINDOW_MS,
+  normaliseLine,
+  bodySegments,
+  isRetiredFirstReply,
+  repeatsItself,
+  asksSomething,
+  firstReplyShape,
+  groupForFirstReply,
+  firstReplyPlan,
+  stampFirstReplyPlan,
+};