@cohortapp/agent-sdk 2.14.0 → 2.16.0

package/scripts/daemon/deliver.mjs

@@ -466,9 +466,9 @@ async function sendGmailResponse(item, text) {
  * and hq's server-side dedup swallows every message after the first, which
  * would turn "never silent" into "acknowledged once and then silent forever".
  *
- * It must be distinct per MESSAGE, not per kind: two progress updates that both
- * key on "progress" are one message as far as hq is concerned. Callers that can
- * emit a kind more than once pass an ordinal (`progress-1`, `progress-2`). A
+ * It must be distinct per MESSAGE, not per kind: two failure notices that both
+ * key on "failure" are one message as far as hq is concerned. Callers that can
+ * emit a kind more than once pass an ordinal (`failure-1`, `failure-2`). A
  * genuine transport RETRY deliberately reuses the same suffix — that is the
  * dedup doing its job.
  */
@@ -636,7 +636,10 @@ async function sendCohortEntityComment(route, text, o = {}) {
  * @param {object} item      daemon inbox item
  * @param {string} text      exactly what the human will read
  * @param {object} [o]
- * @param {string} [o.kind]  receipt kind: "ack" | "progress" | "failure" | "reply"
+ * @param {string} [o.kind]  receipt kind: "reply" (an ANSWER) or one of the
+ *        courtesy kinds "ack" | "plan" | "notice" | "failure". Only "reply"
+ *        discharges an obligation — see `lib/comms/receipts.NON_ANSWER_KINDS`.
+ *        ("progress" is retired: nothing emits it since 2026-09-12.)
  * @param {string[]} [o.mentions] org member ids to @-tag (cohort room sends only)
  * @param {function} [o.fetchImpl] test seam
  * @param {function} [o.callImpl] test seam — the org RPC (entity-thread routes)

package/scripts/daemon/prompt-builder.mjs

@@ -836,11 +836,18 @@ function buildBacklogContext(queueItem) {
  *
  * @param {object} item - The inbox item (sender, content, channel, service, subject, thread_context, etc.)
  * @param {object} classResult - Classifier output (priority, action, model, summary, category)
- * @param {object} options - { type: "inbox" | "backlog", queueItem?: object }
+ * @param {object} options - { type, queueItem?, holdingMessage?, holdingSent?, interimAlreadySent? }
+ *   `holdingMessage`      the interim's TEXT, when this process composed it.
+ *   `holdingSent`         false ⇒ it was composed but did not land.
+ *   `interimAlreadySent`  true ⇒ an interim reached the sender but its text is
+ *                         not available here (the re-delivery / retry path,
+ *                         where the debt is already open with interimSaid). It
+ *                         is what stops the no-contact block asserting silence
+ *                         at a session whose human has already been spoken to.
  * @returns {string} Prompt string ready for claude --print
  */
 export async function buildPrompt(item, classResult, options = {}) {
-  const { type = "inbox", queueItem, holdingMessage, holdingSent } = options;
+  const { type = "inbox", queueItem, holdingMessage, holdingSent, interimAlreadySent } = options;
   // Only `false` — an explicit "the send failed" from the caller — flips the
   // framing. Callers that pass no flag keep the historical assertion, so this
   // cannot silently downgrade a genuinely delivered acknowledgement.
@@ -895,16 +902,31 @@ export async function buildPrompt(item, classResult, options = {}) {
   // 1a. Holding message warning — TOP OF PROMPT so Claude sees it before action instructions.
   // This is the most critical instruction in the prompt: prevents double-replies.
   // We repeat it at section 7a as well, immediately before the action block.
+  //
+  // WHEN EACH BRANCH IS REACHED (2026-09-12). The daemon opens the obligation
+  // and says NOTHING, so on the ordinary inbound path `holdingMessage` is null.
+  // The first two branches exist for the case where an interim genuinely did go
+  // out WITH ITS TEXT IN HAND before the prompt was built: the PLAN tier, whose
+  // one message is posted as the first step of the work. Do not delete them as
+  // dead; they are the correct rendering of a fact that is about to be common.
+  //
+  // The third branch is for an interim that went out whose TEXT THIS PROCESS
+  // DOES NOT HAVE — a re-delivery of an item whose debt is already open with
+  // `interimSaid: true`, which `openAndAcknowledge` answers with
+  // `{acked:true, ackText:null}`. Before it existed, that case fell into FIRST
+  // CONTACT and told a RETRY session that a human who had already received a
+  // holding line AND a "Hit a problem — … Retrying now" had heard nothing.
   if (holdingMessage && holdingDelivered) {
     parts.push("===== STOP — READ THIS FIRST =====");
     parts.push(`A HOLDING MESSAGE has ALREADY been sent to the sender by the daemon. The exact text was:`);
     parts.push(`  "${holdingMessage}"`);
     parts.push("");
+    parts.push("That was the ONE interim this ask gets. The sender will hear nothing else until you deliver something substantive, and nothing in the daemon will fill the gap — the timed progress updates were deleted on 2026-09-12 because a message derived from elapsed minutes carries no information.");
     parts.push("Your job is to deliver the FULL substantive response or complete the actual work — NOT to acknowledge again.");
     parts.push("- Do NOT start your reply with 'Got it', 'On it', 'Looking into this', 'Will get back to you', 'Thanks for reaching out', or any similar acknowledgment phrase.");
     parts.push("- Do NOT echo what the user asked — they already received the holding note confirming receipt.");
     parts.push("- Open with the actual answer, the actual draft, or the actual finding. Be direct.");
-    parts.push("- If after investigation you still cannot deliver a substantive response and need more time, send a SECOND-LEVEL UPDATE (specific blocker, ETA, what you need from the user) — never a generic 'still looking into it'.");
+    parts.push("- If the work runs long, say nothing OR say something with CONTENT in it — a specific blocker, a partial finding, what you need from the user. Never 'still looking into it', never a status line whose only content is how long it has been.");
     parts.push("===== END WARNING =====");
     parts.push("");
   } else if (holdingMessage) {
@@ -926,6 +948,40 @@ export async function buildPrompt(item, classResult, options = {}) {
     parts.push("- If you do NOT, do not let the item evaporate. Record the undeliverable ask and escalate it to the operator — silence plus a closed inbox item is how a request disappears.");
     parts.push("===== END WARNING =====");
     parts.push("");
+  } else if (interimAlreadySent && type === "inbox" && item) {
+    // AN INTERIM WENT OUT AND THIS PROCESS CANNOT QUOTE IT. See the note above:
+    // this is the re-delivery / retry path. What it must NOT say is "the sender
+    // has heard nothing", which is the specific falsehood the FIRST CONTACT
+    // block would assert here.
+    parts.push("===== ALREADY IN CONTACT =====");
+    parts.push("A short interim about this item has already reached the sender. This process no longer holds its text, so do not quote it or guess at it.");
+    parts.push("That was the ONE interim this ask gets. Nothing else will be sent on your behalf — the timed progress updates were deleted on 2026-09-12 because a message derived from elapsed minutes carries no information.");
+    parts.push("- Deliver the substantive response. Do NOT acknowledge receipt again.");
+    parts.push("- Do not apologise for the delay and do not recap what they asked.");
+    parts.push("- If the work runs long, say nothing OR say something with CONTENT in it — a specific blocker, a partial finding, what you need from the sender.");
+    parts.push("===== END =====");
+    parts.push("");
+  } else if (type === "inbox" && item) {
+    // NOTHING HAS BEEN SENT, AND THAT IS THE DEFAULT. Gated on `inbox` because a
+    // backlog item is work the agent gave itself — there is no sender on the
+    // other end of it and this block would be addressed to nobody.
+    //
+    // WHAT THIS BLOCK MAY AND MAY NOT CLAIM. It is built at dispatch time, t≈0.
+    // It can state a FACT about the past — nothing has gone out yet — and it
+    // must not state a PREDICTION about the future, which is what "your reply is
+    // the first thing they will read" was: measured p50 session duration is
+    // 14.7 min against an ACK_AFTER_MS of 90 s, so for most sessions the sweep
+    // will in fact have posted one line before the reply lands. A prompt that
+    // tells a session it is the first voice in the room, when a holding line
+    // lands in front of it, produces exactly the double-contact the first two
+    // blocks exist to prevent — in the other direction.
+    parts.push("===== NO CONTACT YET =====");
+    parts.push("Nothing has been sent to the sender about this item so far. If this runs long, the daemon may post at most ONE short holding line before your reply — you will not be told if it does, and it is the only one this ask gets.");
+    parts.push("- Open with the answer, the draft or the finding. Do not open by acknowledging receipt, and do not apologise for the delay.");
+    parts.push("- Do not write as though a conversation is already underway — no 'as I mentioned', no 'following up on my earlier note'.");
+    parts.push("- If you cannot deliver something substantive, say the specific thing that is blocking you. Never a bare 'looking into it'.");
+    parts.push("===== END =====");
+    parts.push("");
   }
 
   // 2. Session context
@@ -987,11 +1043,14 @@ export async function buildPrompt(item, classResult, options = {}) {
   // If a holding message was already sent, prepend a second reminder so the
   // action block is unambiguous about not re-acknowledging.
   if (holdingMessage && holdingDelivered) {
-    parts.push("REMINDER: A holding message was already sent (see top of prompt). The action below describes WHAT to do — but you must NOT begin your reply with another acknowledgment. Open with substance.");
+    parts.push("REMINDER: A holding message was already sent (see top of prompt), and it was the only one this ask gets. The action below describes WHAT to do — but you must NOT begin your reply with another acknowledgment. Open with substance.");
     parts.push("");
   } else if (holdingMessage) {
     parts.push("REMINDER: The acknowledgement for this item FAILED to send (see top of prompt) — the sender has heard nothing. The action below describes WHAT to do; carry it out knowing this is still first contact, and escalate rather than close the item silently if you cannot reach them.");
     parts.push("");
+  } else if (interimAlreadySent) {
+    parts.push("REMINDER: An interim about this item already reached the sender (see top of prompt), and it was the only one this ask gets. The action below describes WHAT to do — but you must NOT begin your reply with another acknowledgment. Open with substance.");
+    parts.push("");
   }
   parts.push(actionBlock);
   parts.push("");

package/scripts/daemon/prompt-builder.test.mjs

@@ -267,6 +267,74 @@ test("buildPrompt does NOT claim delivery when the acknowledgement failed to sen
   assert.ok(prompt.includes("Understood — I'm digging into this now (the noted issues). I want to get this right, so I'll come back to you here with a full answer — usually within 10-20 minutes — and you'll hear from me either way."));
 });
 
+// ---------------------------------------------------------------------------
+// THE THIRD AND FOURTH STATES: an interim whose text this process does not
+// hold, and no contact at all. Both were one block before 2026-09-12, and that
+// block asserted a fact that is false on most dispatches.
+// ---------------------------------------------------------------------------
+
+test("REGRESSION: a retry session is NOT told the sender has heard nothing", async () => {
+  // The reachable-today path. An item re-delivered while its debt is open with
+  // interimSaid:true makes openAndAcknowledge return {acked:true, ackText:null}:
+  // holdingMessage is null, so both holding blocks are skipped, and before this
+  // fix the no-contact block rendered — telling a RETRY session that a human who
+  // had already received a holding line AND a "Hit a problem — … Retrying now"
+  // had heard nothing. On main this path produced no block at all, so the false
+  // claim was introduced by the acknowledgement-discipline change itself.
+  const prompt = await buildPrompt(ITEM, CLASS, { type: "inbox", interimAlreadySent: true });
+  assert.match(prompt, /ALREADY IN CONTACT/);
+  assert.match(prompt, /already reached the sender/);
+  assert.ok(!/heard nothing/.test(prompt), "must not assert silence at a sender who has been spoken to");
+  assert.ok(!/NO CONTACT YET/.test(prompt), "the no-contact block must not render alongside it");
+  // It must not invent the text it does not have.
+  assert.match(prompt, /do not quote it or guess at it/);
+  // And the second reminder, immediately before the action block, agrees.
+  assert.match(prompt, /REMINDER: An interim about this item already reached the sender/);
+});
+
+test("the no-contact block states a FACT about the past, not a PREDICTION about the future", async () => {
+  // What it said before: "your reply is the first thing they will read". That is
+  // false on the majority of dispatches — the sweep posts one interim at
+  // ACK_AFTER_MS (90 s) while measured p50 session duration is 14.7 min — and a
+  // session told it is the first voice in the room, with a holding line landing
+  // in front of it, produces exactly the double-contact the delivered-holding
+  // block exists to prevent, in the other direction.
+  const prompt = await buildPrompt(ITEM, CLASS, { type: "inbox" });
+  assert.match(prompt, /NO CONTACT YET/);
+  assert.match(prompt, /Nothing has been sent to the sender about this item so far/);
+  assert.ok(
+    !/first thing they will read/.test(prompt),
+    "the prompt may not predict that no interim will land before the reply",
+  );
+  // It must say the opposite instead: one may yet go out, silently.
+  assert.match(prompt, /may post at most ONE short holding line/);
+  assert.ok(!/ALREADY IN CONTACT/.test(prompt));
+});
+
+test("a delivered holding message outranks the interim-already-sent flag", async () => {
+  // When the text IS in hand, quoting it is strictly better than saying it
+  // exists — so the ordering of the branches is pinned rather than incidental.
+  const prompt = await buildPrompt(ITEM, CLASS, {
+    type: "inbox",
+    holdingMessage: "Give me a few minutes on the July reconciliation — I'll have the variances.",
+    holdingSent: true,
+    interimAlreadySent: true,
+  });
+  assert.match(prompt, /A HOLDING MESSAGE has ALREADY been sent/);
+  assert.ok(!/ALREADY IN CONTACT/.test(prompt));
+  assert.ok(!/NO CONTACT YET/.test(prompt));
+});
+
+test("neither block reaches a backlog item — there is no sender on the other end", async () => {
+  const prompt = await buildPrompt(null, CLASS, {
+    type: "backlog",
+    queueItem: { id: "q-1", title: "Sweep the stale worktrees", status: "open" },
+    interimAlreadySent: true,
+  });
+  assert.ok(!/ALREADY IN CONTACT/.test(prompt));
+  assert.ok(!/NO CONTACT YET/.test(prompt));
+});
+
 test("buildPrompt treats an unspecified holdingSent as delivered (back-compat)", async () => {
   const prompt = await buildPrompt(ITEM, CLASS, {
     type: "inbox",

package/scripts/daemon/responder.mjs

@@ -993,9 +993,14 @@ export async function sendQuickResponse(item, classResult, routed = null) {
  * via the cheapest model under a tight (~5s, env-tunable) cap, and on ANY
  * generation failure this function sends NOTHING and says so in the log. The
  * durability story is unchanged — the caller opened the obligation before
- * calling this, the assurance sweep retries generation once within
- * ASSURANCE_ACK_GRACE_MS, and the progress/failure notices still guarantee the
- * human is never left in long-term silence.
+ * calling this, and the assurance sweep owns whether a line goes out at all.
+ *
+ * NOTE (2026-09-12): the daemon no longer calls this from the acknowledgement
+ * path. `assurance.openAndAcknowledge` says NOTHING at open time; the sweep
+ * emits at most one interim per obligation, past ASSURANCE_ACK_AFTER_MS and
+ * inside the per-room budget. The timed progress updates are deleted. The
+ * failure, stale and interrupted notices still guarantee the human is never
+ * left in long-term silence.
  *
  * @returns {{ sent: boolean, holdingText: string|null }} result
  */