switchroom 0.17.10 → 0.18.6

package/telegram-plugin/hooks/silent-end-scan.mjs

@@ -33,6 +33,28 @@
  * delivery obligation.
  */
 
+// Verified complete (2026-07-09, adversarial-review follow-up): `reply`
+// and `stream_reply` are the ONLY two MCP tools whose payload is the
+// model's free-text final-answer content reaching the user — the exact
+// scope `final-answer-detect.ts`'s own docstring claims ("plain assistant
+// transcript text instead of a `reply` / `stream_reply` tool call").
+// Cross-checked the full tool surface in `telegram-plugin/bridge/bridge.ts`
+// (`TOOL_SCHEMAS`, kept in sync with `gateway/gateway.ts`): `edit_message`
+// explicitly does NOT ping/deliver a fresh answer (its own description says
+// "send a new reply when a long task completes"); `react`, `pin_message`,
+// `delete_message`, `forward_message`, `send_typing`, `download_attachment`,
+// `get_recent_messages` carry no model-authored answer text at all;
+// `send_checklist` / `send_sticker` / `send_gif` / `ask_user` /
+// `update_checklist` deliver structured/templated content, not the turn's
+// prose answer, and are intentionally a different interaction pattern (a
+// question or a fixed artifact, not "the answer"). `stream_reply` sends its
+// FULL cumulative text snapshot on every call (not incremental chunks —
+// see `stream-reply-handler.ts` docstring), and each call is its own
+// `tool_use` block in the transcript in chronological order, so the
+// "last delivery event wins" walk below already treats a stream's final
+// (`done:true`) call as the qualifying one regardless of how many
+// intermediate non-final `stream_reply` calls preceded it. No gap found;
+// re-verify only if a new outbound-delivery tool is added to bridge.ts.
 const REPLY_TOOLS = new Set([
   'mcp__switchroom-telegram__reply',
   'mcp__switchroom-telegram__stream_reply',
@@ -126,24 +148,47 @@ function buildTurnKey(chatId, threadId) {
   return `${chatId}:${threadId == null || threadId === 0 ? '_' : threadId}`
 }
 
+/**
+ * Build the `{ decided: 'block', ... }` result shape, populating
+ * `turnKey`/`chatId`/`threadId` from the enqueue envelope when
+ * available. Shared by both block branches below.
+ *
+ * @param {ReturnType<typeof parseChannelEnvelope>} envelope
+ * @param {string} reason
+ */
+function buildBlockResult(envelope, reason) {
+  const block = { decided: 'block', reason }
+  if (envelope.chatId) {
+    block.chatId = envelope.chatId
+    block.threadId = envelope.threadId
+    block.turnKey = buildTurnKey(envelope.chatId, envelope.threadId)
+  }
+  return block
+}
+
 /**
  * Scan a JSONL transcript and decide whether the current turn ended
  * with a final reply delivered.
  *
  * Returns:
- *   { decided: 'allow', reason }    — qualifying reply OR silent marker found
+ *   { decided: 'allow', reason }    — qualifying reply OR silent marker found,
+ *                                     and nothing undelivered was written
+ *                                     after it
  *   { decided: 'block', reason, turnKey?, chatId?, threadId? }
- *                                   — turn-start found, no qualifying reply,
- *                                     no marker. `turnKey`/`chatId`/`threadId`
- *                                     populated from the enqueue's channel
- *                                     envelope so the hook can write a state
- *                                     file shape that matches what the
- *                                     gateway's `recordSilentTurnEnd` would
- *                                     write — keeping the retry-count
- *                                     preservation gate at
- *                                     `silent-end.ts:114` happy when the
- *                                     gateway's later write reads back the
- *                                     hook's state.
+ *                                   — turn-start found, no qualifying reply
+ *                                     delivered (or a qualifying reply
+ *                                     happened, but the model kept writing
+ *                                     plain-text content afterward that was
+ *                                     never sent through a delivery tool).
+ *                                     `turnKey`/`chatId`/`threadId` populated
+ *                                     from the enqueue's channel envelope so
+ *                                     the hook can write a state file shape
+ *                                     that matches what the gateway's
+ *                                     `recordSilentTurnEnd` would write —
+ *                                     keeping the retry-count preservation
+ *                                     gate at `silent-end.ts:114` happy when
+ *                                     the gateway's later write reads back
+ *                                     the hook's state.
  *   { decided: 'unknown', reason }  — couldn't locate turn-start; caller fail-open
  *
  * Turn-start anchor: the most recent `queue-operation`/`enqueue` line
@@ -154,6 +199,38 @@ function buildTurnKey(chatId, threadId) {
  * edge case where the model replied combined ahead of the second
  * enqueue's append; accepted residual.)
  *
+ * IMPORTANT — trailing-content check (fixes the "at least once" bug):
+ * a naive scan that returns 'allow' on the FIRST qualifying reply it
+ * finds is wrong. A turn can legitimately call `reply` early (e.g. a
+ * notification-bearing interim ack — `disable_notification` unset/false
+ * always qualifies as "final" under `isFinalAnswerReply`, regardless of
+ * how short the text is) and then keep working, eventually writing a
+ * SUBSTANTIVE plain-text verdict that never goes through `reply` again.
+ * The early ack satisfied "reply was called somewhere in this turn",
+ * but the user never saw the actual answer. So this scan does NOT
+ * short-circuit on the first match: it walks the ENTIRE turn in
+ * chronological order, remembers the position of the LAST qualifying
+ * delivery event (a final-answer reply/stream_reply call, or an
+ * explicit silent-marker), and then checks whether any plain assistant
+ * text block appears AFTER that position. If one does, that content was
+ * written but never delivered — block, same as the zero-reply case.
+ *
+ * This deliberately does NOT flag a turn that ends on a delivery
+ * tool_use with nothing after it (the normal, healthy shape), nor a
+ * turn where all assistant text precedes the final delivering reply
+ * (the model narrating before it sends) — only text that comes AFTER
+ * the last delivery event counts as a drop.
+ *
+ * Substance floor (#2956 review): the trailing-text check only BLOCKS
+ * when the trailing text is SUBSTANTIVE — at least FINAL_ANSWER_MIN_CHARS
+ * (the same bar `isFinalAnswerReply` uses to recognise a real answer). A
+ * SHORT trailing pleasantry / closer after a delivered reply ("Let me
+ * know if you need anything else.") is not a dropped answer and must not
+ * trigger a re-prompt (no-spam / single-answer invariant). A long
+ * trailing verdict the model forgot to send still blocks. The floor keeps
+ * the "at least once" guarantee for real dropped answers while stopping a
+ * false-positive that burned retry budget on healthy turns.
+ *
  * @param {string} jsonl
  * @returns {{ decided: 'allow' | 'block' | 'unknown', reason: string, turnKey?: string, chatId?: string, threadId?: number | null }}
  */
@@ -178,8 +255,13 @@ export function scanTurnForFinalReply(jsonl) {
     return { decided: 'unknown', reason: 'no-turn-start' }
   }
 
-  // 2. Scan forward from the turn start; look for qualifying tool_use
-  //    or silent-marker text.
+  // 2. Flatten every assistant content block (text and tool_use) from
+  //    the turn into a single chronologically-ordered list. Classify
+  //    each block as it's collected: a "delivery" event (qualifying
+  //    final-answer reply/stream_reply, or an explicit silent marker —
+  //    whether emitted as plain text or as a reply-tool payload) or
+  //    plain undelivered text.
+  const blocks = []
   for (let i = startIdx + 1; i < lines.length; i++) {
     const line = lines[i]
     if (!line || line[0] !== '{') continue
@@ -193,16 +275,28 @@ export function scanTurnForFinalReply(jsonl) {
     const content = obj?.message?.content
     if (!Array.isArray(content)) continue
     for (const c of content) {
-      // Plain assistant text carve-out (#2053): a turn that ends with a
-      // trailing bare NO_REPLY / HEARTBEAT_OK line — emitted as plain
-      // transcript text, NOT through the reply tool — is the model
-      // explicitly signalling "intentionally silent". The anchored
-      // SILENT_MARKER_RE below only fires when the ENTIRE reply-tool
-      // text is the bare marker, so a plain-text prose+NO_REPLY turn
-      // matched nothing here → block → nag → sentinel leak. Treat a
-      // trailing-marker text block as a valid silent end.
-      if (c?.type === 'text' && endsWithSilentMarker(String(c.text ?? ''))) {
-        return { decided: 'allow', reason: 'silent-marker-text' }
+      if (c?.type === 'text') {
+        // Plain assistant text carve-out (#2053): a turn that ends with
+        // a trailing bare NO_REPLY / HEARTBEAT_OK line — emitted as
+        // plain transcript text, NOT through the reply tool — is the
+        // model explicitly signalling "intentionally silent". Treat a
+        // trailing-marker text block as a delivery/silence event;
+        // anything else is candidate undelivered content.
+        if (endsWithSilentMarker(String(c.text ?? ''))) {
+          blocks.push({ kind: 'deliver', reason: 'silent-marker-text' })
+        } else if (String(c.text ?? '').trim().length > 0) {
+          // Carry the trimmed char count so the trailing-content check
+          // (step 3) can apply a substance floor: a SHORT trailing text
+          // after a delivered reply (a pleasantry / closer like "Let me
+          // know if you need anything else.") is NOT a dropped answer and
+          // must not trigger a re-prompt (no-spam invariant). Only
+          // SUBSTANTIVE trailing text — at least FINAL_ANSWER_MIN_CHARS,
+          // the same bar `isFinalAnswerReply` uses to recognise a real
+          // answer — counts as "undelivered content the user was waiting
+          // on". #2956 review finding.
+          blocks.push({ kind: 'text', chars: String(c.text ?? '').trim().length })
+        }
+        continue
       }
       if (c?.type !== 'tool_use') continue
       if (!REPLY_TOOLS.has(c.name)) continue
@@ -214,33 +308,63 @@ export function scanTurnForFinalReply(jsonl) {
       // prose+trailing-marker shape (#2053). Same posture as the
       // gateway's silent-marker suppression at gateway.ts:6692.
       if (SILENT_MARKER_RE.test(text.trim()) || endsWithSilentMarker(text)) {
-        return { decided: 'allow', reason: 'silent-marker' }
+        blocks.push({ kind: 'deliver', reason: 'silent-marker' })
+        continue
       }
       if (isFinalAnswerReply({
         text,
         disableNotification: input.disable_notification === true,
         done: input.done === true,
       })) {
-        return { decided: 'allow', reason: 'final-reply' }
+        blocks.push({ kind: 'deliver', reason: 'final-reply' })
+        continue
       }
+      // Non-qualifying reply call (interim ack) — delivered to the
+      // user, but not a "final answer". It's neither a delivery event
+      // nor undelivered text, so it doesn't affect the decision either
+      // way; simply not pushed.
     }
   }
 
-  // Cron-fired turns (#2053): a scheduled turn that produced no
-  // qualifying reply is NOT a delivery failure the user is waiting on —
-  // nagging it only pushes the model to escape the loop by shoving a
-  // NO_REPLY sentinel through the reply tool, which leaks to chat. A
-  // cron turn that genuinely needs to speak will have called reply
-  // (caught above); otherwise let it end silently.
-  if (envelope.source === 'cron') {
-    return { decided: 'allow', reason: 'cron-source' }
+  // 3. Find the LAST delivery event's position, then check whether any
+  //    plain-text block appears strictly after it. This is the fix for
+  //    the "at least once" bug: a naive scan that stops at the FIRST
+  //    qualifying reply misses substantive content the model wrote
+  //    afterward and never (re-)sent.
+  let lastAllowBlockIdx = -1
+  let lastAllowReason = null
+  for (let i = 0; i < blocks.length; i++) {
+    if (blocks[i].kind === 'deliver') {
+      lastAllowBlockIdx = i
+      lastAllowReason = blocks[i].reason
+    }
   }
+  const sawUndeliveredTextAfterAllow = blocks
+    .slice(lastAllowBlockIdx + 1)
+    .some((b) => b.kind === 'text' && (b.chars ?? 0) >= FINAL_ANSWER_MIN_CHARS)
 
-  const block = { decided: 'block', reason: 'no-final-reply' }
-  if (envelope.chatId) {
-    block.chatId = envelope.chatId
-    block.threadId = envelope.threadId
-    block.turnKey = buildTurnKey(envelope.chatId, envelope.threadId)
+  if (lastAllowBlockIdx === -1) {
+    // No qualifying delivery/silence event anywhere in the turn.
+    // Cron-fired turns (#2053): a scheduled turn that produced no
+    // qualifying reply is NOT a delivery failure the user is waiting
+    // on — nagging it only pushes the model to escape the loop by
+    // shoving a NO_REPLY sentinel through the reply tool, which leaks
+    // to chat. A cron turn that genuinely needs to speak will have
+    // called reply (caught above); otherwise let it end silently.
+    if (envelope.source === 'cron') {
+      return { decided: 'allow', reason: 'cron-source' }
+    }
+    return buildBlockResult(envelope, 'no-final-reply')
   }
-  return block
+
+  if (sawUndeliveredTextAfterAllow) {
+    // A qualifying delivery DID happen somewhere in the turn, but the
+    // model kept writing after it and that trailing content was never
+    // sent through a delivery tool. This is the "at least once" bug:
+    // an early ack (or any qualifying reply) must not amnesty
+    // everything written afterward.
+    return buildBlockResult(envelope, 'trailing-text-after-reply')
+  }
+
+  return { decided: 'allow', reason: lastAllowReason }
 }

package/telegram-plugin/operator-events.ts

@@ -26,6 +26,7 @@ export type OperatorEventKind =
   | 'agent-restarted-unexpectedly'
   | 'unknown-4xx'
   | 'unknown-5xx'
+  | 'config-warning'
 
 export interface OperatorEvent {
   kind: OperatorEventKind
@@ -375,6 +376,26 @@ export function renderOperatorEvent(ev: OperatorEvent): RenderResult {
           ],
         },
       }
+
+    // Deliberately low-severity framing (ℹ️, Dismiss-only — no Restart /
+    // Reauth / Show-logs actions): config-warning is for boot-time config
+    // problems (e.g. a dropped `person_id` entry) that must be visible to
+    // the operator but MUST NOT read like a real outage or page anyone.
+    case 'config-warning':
+      return {
+        text: [
+          `ℹ️ **Config warning** for **${agent}**.`,
+          detail ? `_${detail}_` : '',
+          `Non-urgent — config will keep working with today's fallback behavior.`,
+        ]
+          .filter(Boolean)
+          .join('\n'),
+        keyboard: {
+          inline_keyboard: [
+            [{ text: '❌ Dismiss', callback_data: `op:dismiss:${encodeURIComponent(ev.agent)}` }],
+          ],
+        },
+      }
   }
 }
 

package/telegram-plugin/package.json

@@ -33,8 +33,14 @@
     "@secretlint/types": "^12.2.0",
     "@xterm/headless": "^6.0.0",
     "grammy": "^1.44",
+    "mdast-util-from-markdown": "^2.0.2",
+    "mdast-util-gfm": "^3.0.0",
+    "micromark-extension-gfm": "^3.0.0",
     "posthog-node": "^5.29.2"
   },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4"
+  },
   "engines": {
     "node": ">=20.11.0"
   },

package/telegram-plugin/pending-work-progress.ts

@@ -419,9 +419,15 @@ function tick(now: number): void {
       newText,
       literalText: s.anchorLiteralText,
     }
-    // Fire-and-forget so a slow edit doesn't block the tick loop.
-    // Errors are logged but never bubble (a 429 / "message not modified"
-    // / chat-deleted is a soft failure).
+    // Fire-and-forget so a slow edit doesn't block the tick loop. The
+    // production `editMessage` dep is `swallowingApiCall`-wrapped, which
+    // catches every transport outcome (not-modified / not-found / 429 /
+    // network) upstream and never rejects — so in production this `.catch`
+    // is a backstop that rarely fires. It is kept as a contract-level guard
+    // (a throwing dep, or a future non-swallowing wiring, must not log a
+    // scary "edit failed" warning for a best-effort liveness surface nor
+    // keep hammering a dead anchor). Only a genuinely unexpected error
+    // reaches the fallthrough; transport classes are silent.
     void Promise.resolve()
       .then(() => activeDeps!.editMessage(editCtx))
       .then(() => {
@@ -432,10 +438,39 @@ function tick(now: number): void {
         })
       })
       .catch((err) => {
-        process.stderr.write(
-          `pending-work-progress: edit failed key=${key} ` +
-            `msg=${editCtx.messageId}: ${(err as Error).message}\n`,
-        )
+        const desc =
+          err instanceof Error ? err.message : err != null && typeof err === 'object' && 'description' in err
+            ? String((err as { description?: unknown }).description)
+            : String(err)
+        const low = desc.toLowerCase()
+        // "message is not modified" — the anchor already shows this suffix.
+        // The card is correct; count it as an edit and move on silently.
+        if (low.includes('not modified')) {
+          activeDeps!.emitMetric?.({
+            kind: 'pending_progress_edited',
+            chatKey: key,
+            elapsedMs: elapsed,
+          })
+          return
+        }
+        // Message / chat gone, or the 48h edit window closed. The anchor
+        // is dead — stop retrying it (clear state) so the tick isn't
+        // hammering a non-existent message every EDIT_INTERVAL_MS. The
+        // next outbound reply re-establishes a fresh anchor. Silent: no
+        // card to update is not a liveness-logic error.
+        if (
+          low.includes('not found') ||
+          low.includes("can't be edited") ||
+          low.includes('cannot be edited') ||
+          low.includes('not enough rights')
+        ) {
+          clearPending(key, 'stale_turn')
+          return
+        }
+        // 429 / transient network blip — leave state intact; the next tick
+        // retries. No stderr: a transport hiccup on a best-effort card is
+        // not a logic error, and the production wiring already applies
+        // retry_after backoff upstream.
       })
   }
 }