switchroom 0.17.6 → 0.18.3

package/telegram-plugin/render/render.ts

@@ -0,0 +1,440 @@
+// IR -> Telegram rich-markdown renderer for the Telegram HTML render engine
+// (name kept for continuity with render/ir.ts + render/parse.ts; the actual
+// wire format is GFM markdown, NOT HTML — see the note below).
+//
+// Increment 2 of the render pipeline: takes the typed IR produced by
+// `parse.ts` (per `ir.ts`) and emits a string suitable for the `markdown`
+// field of `InputRichMessageMarkdown` (`telegram-plugin/rich-send.ts`).
+//
+// IMPORTANT — why this emits markdown, not HTML:
+// `ir.ts`'s block-type doc comment (written during Increment 1) sketches an
+// HTML tag mapping "for the next increment." That comment predates the Bot
+// API 10.1 migration (#2669, `telegram-plugin/rich-send.ts`) becoming the
+// live send path: `sendRichMessage` / `editMessageText` are called with
+// `{ markdown: string }` — raw GFM markdown — not with `{ text, parse_mode:
+// "HTML" }`. There is no HTML anywhere on the current outbound path (see
+// `reference/telegram-formatting-guide.md`). This renderer therefore targets
+// the ACTUAL contract: GFM markdown with the Bot API 10.1 extensions
+// documented in the formatting guide (expandable blockquote via `**> `,
+// spoiler via `||…||`, GFM pipe tables, etc). This module is NOT wired into
+// the live send path yet — that is a later increment, per the RFC's phased
+// rollout (rich rendering stays gated off by default until then).
+//
+// Round-trip note: `parse.ts` folds inline text (`PlainNode.text`,
+// `CodeNode.text`, `code-block` `text`, link `href`) into DECODED strings —
+// entity references and escapes are already resolved by mdast. Rendering
+// back to markdown therefore re-escapes GFM-special characters in prose
+// context with `escapeMarkdown` (same helper `format.ts` uses for
+// dynamic-content interpolation) and re-defuses embedded backticks in code
+// spans with `codeSpanSafe`, so the emitted markdown parses back to
+// equivalent entities rather than accidentally re-triggering formatting or
+// breaking out of a code span.
+
+import { escapeMarkdown, codeSpanSafe, RICH_MESSAGE_MAX_CHARS } from "../format.js";
+import type {
+  Block,
+  BlockquoteNode,
+  CodeBlockNode,
+  Document,
+  Inline,
+  ListItem,
+  ListNode,
+  TableNode,
+  TableRow,
+} from "./ir.js";
+
+// ---------------------------------------------------------------------------
+// Inline rendering
+// ---------------------------------------------------------------------------
+
+function renderInline(node: Inline): string {
+  switch (node.type) {
+    case "plain":
+      return escapeMarkdown(node.text);
+    case "bold":
+      return `**${renderInlineChildren(node.children)}**`;
+    case "italic":
+      return `*${renderInlineChildren(node.children)}*`;
+    case "underline":
+      return `__${renderInlineChildren(node.children)}__`;
+    case "strike":
+      return `~~${renderInlineChildren(node.children)}~~`;
+    case "spoiler":
+      return `||${renderInlineChildren(node.children)}||`;
+    case "highlight":
+      return `==${renderInlineChildren(node.children)}==`;
+    case "code":
+      return `\`${codeSpanSafe(node.text)}\``;
+    case "link":
+      return `[${renderInlineChildren(node.children)}](${node.href})`;
+    default: {
+      // Exhaustiveness guard — the IR union is closed; a new variant must be
+      // handled above rather than silently dropped.
+      const _exhaustive: never = node;
+      return escapeMarkdown((_exhaustive as Inline & { text?: string }).text ?? "");
+    }
+  }
+}
+
+function renderInlineChildren(children: Inline[]): string {
+  return children.map(renderInline).join("");
+}
+
+// ---------------------------------------------------------------------------
+// Block rendering
+// ---------------------------------------------------------------------------
+
+/** Prefix every line of `text` with `prefix` (used for blockquote nesting). */
+function prefixLines(text: string, prefix: string): string {
+  return text
+    .split("\n")
+    .map((line) => (line.length > 0 ? `${prefix}${line}` : prefix.trimEnd()))
+    .join("\n");
+}
+
+function renderBlockquote(node: BlockquoteNode): string {
+  const inner = renderBlocks(node.children);
+  // Bot API 10.1 expandable blockquote: `**> ` on the first quoted line.
+  // Plain blockquote: `> ` on every line.
+  if (node.expandable) {
+    const lines = inner.split("\n");
+    return lines
+      .map((line, i) => {
+        const marker = i === 0 ? "**> " : "> ";
+        return line.length > 0 ? `${marker}${line}` : marker.trimEnd();
+      })
+      .join("\n");
+  }
+  return prefixLines(inner, "> ");
+}
+
+function renderCodeBlock(node: CodeBlockNode): string {
+  const lang = node.language ?? "";
+  // Fenced code content is verbatim per the formatting guide; the only
+  // hazard is an embedded ``` closing the fence early. Widen the fence to a
+  // run of backticks one longer than the longest run already present in the
+  // content, mirroring the guide's `preBlock` defusal strategy.
+  const longestRun = Math.max(
+    0,
+    ...(node.text.match(/`+/g) ?? []).map((run) => run.length),
+  );
+  const fence = "`".repeat(Math.max(3, longestRun + 1));
+  return `${fence}${lang}\n${node.text}\n${fence}`;
+}
+
+function renderListItem(item: ListItem, ordered: boolean, index: number): string {
+  const checkbox =
+    item.checked === null ? "" : item.checked ? "[x] " : "[ ] ";
+  const marker = ordered ? `${index}. ` : "- ";
+  // Tight item (spread=false): join the item's block children with a single
+  // newline so a paragraph and its nested sub-list stay adjacent — no spurious
+  // blank line injected before the sub-list. Loose item (spread=true): keep the
+  // blank-line separation the source author intended.
+  const body = renderBlocksJoined(item.children, item.spread ? "\n\n" : "\n");
+  const lines = body.split("\n");
+  const first = `${marker}${checkbox}${lines[0] ?? ""}`;
+  const contIndent = " ".repeat(marker.length);
+  const rest = lines
+    .slice(1)
+    .map((line) => (line.length > 0 ? `${contIndent}${line}` : line));
+  return [first, ...rest].join("\n");
+}
+
+function renderList(node: ListNode): string {
+  const start = node.startNumber ?? 1;
+  // Loose list (spread=true): a blank line between top-level items, as the
+  // source author wrote them. Tight list (spread=false, the common case and
+  // all nested sub-lists): siblings on adjacent lines, single newline.
+  const sep = node.spread ? "\n\n" : "\n";
+  return node.items
+    .map((item, i) => renderListItem(item, node.ordered, start + i))
+    .join(sep);
+}
+
+/** Render a single cell's inline content for a table (no line breaks — GFM
+ *  table cells can't contain them; pipes are escaped defensively). */
+function renderTableCell(cells: TableRow["cells"][number]): string {
+  return renderInlineChildren(cells.children).replace(/\n+/g, " ");
+}
+
+function alignSeparator(align: TableNode["align"][number]): string {
+  switch (align) {
+    case "left":
+      return ":---";
+    case "right":
+      return "---:";
+    case "center":
+      return ":---:";
+    default:
+      return "---";
+  }
+}
+
+function renderTable(node: TableNode): string {
+  const headerCells = node.header.cells.map(renderTableCell);
+  const colCount = headerCells.length;
+  const align = node.align.length > 0 ? node.align : new Array(colCount).fill(null);
+  const headerLine = `| ${headerCells.join(" | ")} |`;
+  const sepLine = `| ${align
+    .slice(0, colCount)
+    .map(alignSeparator)
+    .join(" | ")} |`;
+  const bodyLines = node.rows.map(
+    (row) => `| ${row.cells.map(renderTableCell).join(" | ")} |`,
+  );
+  return [headerLine, sepLine, ...bodyLines].join("\n");
+}
+
+function renderBlock(node: Block): string {
+  switch (node.type) {
+    case "paragraph":
+      return renderInlineChildren(node.children);
+    case "heading":
+      return `${"#".repeat(node.level)} ${renderInlineChildren(node.children)}`;
+    case "blockquote":
+      return renderBlockquote(node);
+    case "code-block":
+      return renderCodeBlock(node);
+    case "list":
+      return renderList(node);
+    case "thematic-break":
+      return "---";
+    case "table":
+      return renderTable(node);
+    default: {
+      const _exhaustive: never = node;
+      return escapeMarkdown((_exhaustive as Block & { text?: string }).text ?? "");
+    }
+  }
+}
+
+/** Join a run of blocks with an explicit separator. Blockquote children and
+ *  the top-level document use a blank line (`\n\n`); tight list items pass a
+ *  single newline so a nested sub-list stays adjacent to its item's paragraph
+ *  (see `renderListItem`). */
+function renderBlocksJoined(blocks: Block[], sep: string): string {
+  return blocks.map(renderBlock).join(sep);
+}
+
+function renderBlocks(blocks: Block[]): string {
+  return renderBlocksJoined(blocks, "\n\n");
+}
+
+/** Render a full IR `Document` to Bot API 10.1 rich GFM markdown. */
+export function render(doc: Document): string {
+  return renderBlocks(doc.blocks);
+}
+
+// ---------------------------------------------------------------------------
+// Construct allowlist (gap #2: escape/degrade anything unsupported)
+// ---------------------------------------------------------------------------
+
+// The IR node types this renderer emits NATIVE Telegram markup for. The IR
+// union is closed and TypeScript's exhaustiveness `default` branches in
+// `renderInline` / `renderBlock` already escape any unknown variant to literal
+// text rather than emitting a broken tag — so the allowlist is enforced at
+// COMPILE time. These runtime constants make the allowlist inspectable (and
+// unit-testable: a test asserts every IR `type` appears here, so adding an IR
+// node without teaching the renderer to render it fails the build), which is
+// the concrete "construct-allowlist validator" that pairs with the expandable-
+// blockquote / spoiler / underline additions.
+export const SUPPORTED_INLINE = [
+  "plain",
+  "bold",
+  "italic",
+  "underline",
+  "strike",
+  "spoiler",
+  "highlight",
+  "code",
+  "link",
+] as const;
+
+export const SUPPORTED_BLOCK = [
+  "paragraph",
+  "heading",
+  "blockquote",
+  "code-block",
+  "list",
+  "thematic-break",
+  "table",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Oversized / malformed-content safe fallback
+// ---------------------------------------------------------------------------
+
+/** Which construct degraded. `document` = the whole message fell back to
+ *  plain text. */
+export type DegradationConstruct = "table" | "code-block" | "blockquote" | "document";
+
+/** Why a construct could not be emitted as a proper rich construct.
+ *   - `table-malformed`    : the table's structure is not renderable as a rich
+ *                            GFM table (e.g. no columns, ragged rows); emitted
+ *                            as a preformatted code fence instead.
+ *   - `oversize`           : a single atomic block alone exceeds the wire cap;
+ *                            emitted as plain source text.
+ *   - `document-oversize`  : the whole document still exceeds the cap after
+ *                            per-block substitution; sent as plain text with no
+ *                            rich wrapper. */
+export type DegradationReason = "table-malformed" | "oversize" | "document-oversize";
+
+/** A tracked degradation — WHY a construct fell back from its native rich form
+ *  to a plain/code rendering. Returned on `RenderResult` so the caller can log
+ *  / surface it instead of the fallback happening silently. */
+export interface Degradation {
+  construct: DegradationConstruct;
+  reason: DegradationReason;
+  /** Human-readable detail for logs / telemetry. */
+  detail: string;
+}
+
+export interface RenderResult {
+  /** The rendered text to send. */
+  text: string;
+  /** "markdown": send as rich `{ markdown }`. "plain": send as a literal
+   *  string with no rich wrapper (structure stripped, content preserved). */
+  mode: "markdown" | "plain";
+  /** Constructs that could not be emitted in their native rich form, each with
+   *  a tracked reason. Empty when everything rendered natively. Never silently
+   *  degrade — a caller can log/telemeter these. */
+  degradations: Degradation[];
+}
+
+/**
+ * Classify a table that cannot render as a proper rich GFM table. Returns a
+ * human-readable reason string, or null when the table is well-formed.
+ *
+ * mdast normally normalises tables, but a table folded from degraded/adversarial
+ * source (or a future IR producer) can still be structurally unrenderable — no
+ * header columns, or body rows whose cell count doesn't match the header. Such a
+ * table would emit pipes that Telegram renders as broken/literal text, so we
+ * catch it here and fall back to a preformatted code fence (content preserved,
+ * degradation tracked) rather than shipping a broken row.
+ */
+function tableDegradationReason(node: TableNode): string | null {
+  const cols = node.header.cells.length;
+  if (cols === 0) return "table has no header columns";
+  for (let i = 0; i < node.rows.length; i++) {
+    const n = node.rows[i].cells.length;
+    if (n !== cols) {
+      return `row ${i + 1} has ${n} cell(s), expected ${cols} to match the header`;
+    }
+  }
+  return null;
+}
+
+/** Wrap a block's raw source text in a widened preformatted code fence — the
+ *  degraded rendering for a malformed table (content verbatim, no broken
+ *  markup). Fence-widening mirrors `renderCodeBlock`. */
+function degradeToCodeFence(source: string, node: Block): string {
+  const raw = source.slice(node.start, node.end);
+  const longestRun = Math.max(0, ...(raw.match(/`+/g) ?? []).map((run) => run.length));
+  const fence = "`".repeat(Math.max(3, longestRun + 1));
+  return `${fence}\n${raw}\n${fence}`;
+}
+
+/**
+ * A block is "atomic" for chunking purposes when splitting it mid-construct
+ * would break the wire format — an unterminated fence, a half table row, or
+ * a blockquote whose closing marker got separated from its opener. These are
+ * exactly the constructs `splitMarkdownChunks` (format.ts) already knows how
+ * to avoid bisecting for a MULTI-block body, but a SINGLE such block that by
+ * itself exceeds the cap has nowhere left to cut without breaking mid-tag —
+ * that's the case this module must catch before send.
+ */
+function isAtomicBlock(node: Block): boolean {
+  return (
+    node.type === "code-block" ||
+    node.type === "table" ||
+    node.type === "blockquote"
+  );
+}
+
+/** Render `node`'s raw source text as a plain literal (escaped so none of
+ *  the source's own markdown-special characters accidentally re-trigger
+ *  formatting when sent WITHOUT the rich wrapper — a plain send has no
+ *  parser, but downstream literal display should still show the author's
+ *  intended characters, not stray backslashes, so we use the raw slice
+ *  as-is: a plain send does not interpret markdown at all). */
+function plainSlice(source: string, node: Block): string {
+  return source.slice(node.start, node.end);
+}
+
+/**
+ * Render `doc` to Bot API 10.1 rich markdown, honoring the wire cap
+ * (`RICH_MESSAGE_MAX_CHARS` by default). Behaviour:
+ *
+ *   1. If the full rendered markdown fits under `maxLen`, return it as-is
+ *      (`mode: "markdown"`).
+ *   2. Otherwise, any individual ATOMIC block (table / code-block /
+ *      blockquote — constructs that cannot be safely bisected without
+ *      producing a broken tag/fence/row) whose OWN rendered form alone
+ *      exceeds `maxLen` is replaced by its raw plain-text source slice
+ *      instead of being emitted as rich markdown that a later chunker would
+ *      have to cut mid-construct.
+ *   3. If the document *still* exceeds `maxLen` after that per-block
+ *      substitution (i.e. the oversized content isn't isolated to one
+ *      swappable block, or the whole document is one giant atomic
+ *      construct), the ENTIRE document falls back to plain text — the raw
+ *      source, verbatim, sent with no rich wrapper at all. This never
+ *      truncates: the caller's ordinary length-based chunker
+ *      (`splitMarkdownChunks` and `hardSliceToCap`) is what applies size
+ *      limits to plain text before send; this function's only job is to
+ *      guarantee it is never handed a rich-markdown body with a mid-tag cut.
+ */
+export function renderSafe(
+  doc: Document,
+  source: string,
+  maxLen: number = RICH_MESSAGE_MAX_CHARS,
+): RenderResult {
+  const degradations: Degradation[] = [];
+
+  // Per-block render, degrading a MALFORMED table (any size) to a preformatted
+  // code fence up front so a structurally-unrenderable table never ships as
+  // broken pipes — and the reason is recorded, not swallowed.
+  const rendered = doc.blocks.map((block) => {
+    if (block.type === "table") {
+      const reason = tableDegradationReason(block);
+      if (reason != null) {
+        degradations.push({ construct: "table", reason: "table-malformed", detail: reason });
+        return { block, text: degradeToCodeFence(source, block) };
+      }
+    }
+    return { block, text: renderBlock(block) };
+  });
+
+  const full = rendered.map((r) => r.text).join("\n\n");
+  if (full.length <= maxLen) {
+    return { text: full, mode: "markdown", degradations };
+  }
+
+  // Oversized: swap any atomic block whose OWN rendered form alone exceeds the
+  // cap for its raw plain-text source (a construct that can't be safely
+  // bisected), recording an `oversize` degradation for each.
+  const swapped = rendered.map(({ block, text }) => {
+    if (isAtomicBlock(block) && text.length > maxLen) {
+      degradations.push({
+        construct: block.type as DegradationConstruct,
+        reason: "oversize",
+        detail: `${block.type} of ${text.length} chars exceeds the ${maxLen}-char cap; sent as plain source text`,
+      });
+      return escapeMarkdown(plainSlice(source, block));
+    }
+    return text;
+  });
+  const patched = swapped.join("\n\n");
+  if (patched.length <= maxLen) {
+    return { text: patched, mode: "markdown", degradations };
+  }
+
+  // Still oversized (or a giant atomic block never fit even as plain text) —
+  // fall all the way back to plain text for the whole document. Never
+  // truncate here; that is the length-based chunker's job downstream.
+  degradations.push({
+    construct: "document",
+    reason: "document-oversize",
+    detail: `rendered document of ${patched.length} chars exceeds the ${maxLen}-char cap; sent as plain text without the rich wrapper`,
+  });
+  return { text: source, mode: "plain", degradations };
+}

package/telegram-plugin/render/rich-render.ts

@@ -0,0 +1,72 @@
+// Flag-gated wiring for the Bot API 10.1 rich renderer (parse.ts + render.ts)
+// into the live outbound send path.
+//
+// The renderer (`render/render.ts`, PR #2930) and parser (`render/parse.ts`)
+// have full unit coverage but were, until this module, wired into NOTHING —
+// no outbound message ever flowed through them. This module is the single,
+// feature-flagged bridge: the gateway's rich send path (stream-controller.ts)
+// runs the assistant's raw markdown through `parse → renderSafe` before it
+// reaches `sendRichMessage`, but ONLY when the flag is on.
+//
+// Feature flag — `SWITCHROOM_RICH_RENDER`, default OFF:
+//   Mirrors the `SWITCHROOM_VISIBLE_ANSWER_STREAM` convention
+//   (`answer-stream-flag.ts`): an env var read at runtime, default off, opted
+//   in PER AGENT via the `env:` block in `switchroom.yaml` (propagated into
+//   the container `environment:` by `src/agents/compose.ts`). When off,
+//   `maybeRenderOutbound` returns the input untouched, so the live send path
+//   is byte-for-byte unchanged — no agent's behaviour moves until an operator
+//   explicitly flips the flag for a specific agent. Accepts `1/true/on/yes`.
+//
+// Why route through `renderSafe` and not bare `render`:
+//   `renderSafe` guarantees the returned body is never a rich-markdown string
+//   with a mid-construct cut, and degrades a document it can't safely fit to
+//   plain-text mode (structure stripped, content preserved). The send path
+//   honours that `mode` — a `plain` result is sent WITHOUT the rich wrapper.
+
+import { parse } from "./parse.js";
+import { renderSafe, type RenderResult } from "./render.js";
+import { RICH_MESSAGE_MAX_CHARS } from "../format.js";
+
+/** Parse the `SWITCHROOM_RICH_RENDER` flag value. Default OFF; accepts the
+ *  same truthy tokens as the other switchroom env flags. Pure so the default
+ *  + parsing are unit-testable. */
+export function parseRichRenderEnabled(raw: string | undefined): boolean {
+  if (raw == null) return false;
+  const v = raw.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "on" || v === "yes";
+}
+
+/** Is the rich renderer enabled in this process? Reads the env flag live so a
+ *  test can set/unset it per-case; defaults OFF. */
+export function richRenderEnabled(
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  return parseRichRenderEnabled(env.SWITCHROOM_RICH_RENDER);
+}
+
+/** Unconditionally run `text` through `parse → renderSafe` (ignores the flag).
+ *  Exposed for tests and callers that have already gated on the flag. */
+export function renderOutbound(
+  text: string,
+  maxLen: number = RICH_MESSAGE_MAX_CHARS,
+): RenderResult {
+  return renderSafe(parse(text), text, maxLen);
+}
+
+/**
+ * Flag-gated transform for the live send path.
+ *
+ *   - flag OFF (default): returns the input untouched, `mode: "markdown"` —
+ *     identical to the pre-existing behaviour (raw transcript markdown sent
+ *     straight to `sendRichMessage`). No behavioural change for any agent.
+ *   - flag ON: returns `parse → renderSafe` output. `mode: "plain"` signals
+ *     the caller to send WITHOUT the rich wrapper (oversized/unsafe content).
+ */
+export function maybeRenderOutbound(
+  text: string,
+  env: NodeJS.ProcessEnv = process.env,
+  maxLen: number = RICH_MESSAGE_MAX_CHARS,
+): RenderResult {
+  if (!richRenderEnabled(env)) return { text, mode: "markdown", degradations: [] };
+  return renderOutbound(text, maxLen);
+}

package/telegram-plugin/scoped-approval.ts

@@ -214,6 +214,65 @@ export function sweepScopedGrants(store: ScopedGrantStore, now: number): void {
   }
 }
 
+/** Total number of live-or-not grant entries across all agents. Cheap change
+ *  signal for "did a sweep remove anything?" (sweeps only ever remove). */
+export function countScopedGrants(store: ScopedGrantStore): number {
+  let n = 0;
+  for (const list of store.values()) n += list.length;
+  return n;
+}
+
+/**
+ * A single grant flattened for on-disk persistence. Carries the agent it
+ * belongs to (the store is keyed by agent), the narrow rule/signature, and
+ * the ABSOLUTE wall-clock expiry — never a relative TTL, so a reload can
+ * never extend a window (the restart-doesn't-extend invariant). No grant
+ * time is stored because nothing needs it: expiry is the only gate.
+ */
+export interface SerializedScopedGrant {
+  readonly agent: string;
+  readonly rule: string;
+  readonly expiresAt: number;
+}
+
+/** Flatten the per-agent store to a plain array for JSON persistence. */
+export function serializeScopedGrants(store: ScopedGrantStore): SerializedScopedGrant[] {
+  const out: SerializedScopedGrant[] = [];
+  for (const [agent, list] of store) {
+    for (const g of list) out.push({ agent, rule: g.rule, expiresAt: g.expiresAt });
+  }
+  return out;
+}
+
+/**
+ * Rebuild the store from persisted entries at gateway boot. Entries already
+ * at/past `now` are DROPPED (expiry is absolute — a restart never revives or
+ * extends a window). Malformed rows are skipped defensively (fail-closed:
+ * an unparseable grant simply doesn't exist → the action re-cards). A
+ * duplicate rule for one agent collapses to the latest expiry, mirroring
+ * `recordScopedGrant`'s replace-not-accumulate behaviour.
+ */
+export function deserializeScopedGrants(
+  data: readonly unknown[],
+  now: number,
+): ScopedGrantStore {
+  const store: ScopedGrantStore = new Map();
+  if (!Array.isArray(data)) return store;
+  for (const raw of data) {
+    if (!raw || typeof raw !== "object") continue;
+    const entry = raw as Partial<SerializedScopedGrant>;
+    if (typeof entry.agent !== "string" || entry.agent.length === 0) continue;
+    if (typeof entry.rule !== "string" || entry.rule.length === 0) continue;
+    if (typeof entry.expiresAt !== "number" || !Number.isFinite(entry.expiresAt)) continue;
+    if (entry.expiresAt <= now) continue; // absolute expiry already elapsed → drop
+    const list = store.get(entry.agent) ?? [];
+    const others = list.filter((g) => g.rule !== entry.rule);
+    others.push({ rule: entry.rule, expiresAt: entry.expiresAt });
+    store.set(entry.agent, others);
+  }
+  return store;
+}
+
 /**
  * Heuristic destructive/irreversible-command detector. FAIL-CLOSED: when
  * a command can't be read or looks risky, return `true` so it is never

package/telegram-plugin/silent-end.ts

@@ -49,6 +49,17 @@ export interface SilentEndDeps {
   stateDir?: string
   /** stderr writer (defaults to `process.stderr.write`). */
   log?: (line: string) => void
+  /**
+   * Has a genuine assistant reply been delivered to this chat (optionally
+   * scoped to thread) at or after `sinceMs`? Same predicate shape as
+   * `history.hasOutboundDeliveredSince` / the represent-guard's dep
+   * (`gateway/represent-guard.ts`) — injected here so the exhaustion check
+   * below is a pure, testable decision. When omitted (history unavailable,
+   * or callers that don't wire it), the check is skipped and the guard
+   * falls back to the pre-existing turnKey/retryCount bookkeeping only —
+   * never suppress on doubt.
+   */
+  hasOutboundDeliveredSince?: (chatId: string, sinceMs: number, threadId?: number | null) => boolean
 }
 
 /**
@@ -69,6 +80,35 @@ export interface SilentEndDeps {
  */
 export const SILENT_END_MAX_RETRIES = 2
 
+/**
+ * User-facing fallback text delivered when a user-message turn ends with no
+ * final answer AND the deterministic Stop-hook re-prompt has already been
+ * exhausted (#1161). Without this the user only sees the progress card
+ * vanish; silence must never be the failure mode.
+ *
+ * PR #2892 (reference/rfcs/deterministic-turn-liveness.md Phase 2
+ * hardening): include the turn's elapsed so the fallback is honest about
+ * how long the user actually waited, instead of a generic apology with no
+ * timing. A degenerate/unknown duration (missing, non-finite, or <= 0 —
+ * e.g. a turn whose `startedAt` was never stamped) omits the waited clause
+ * rather than printing a nonsensical "(waited 0s)".
+ *
+ * Lives here (not gateway.ts) so the transport-boundary tests exercise the
+ * REAL string (tests/silent-end-transport.test.ts), not a hand-maintained
+ * copy — gateway.ts is not importable in tests.
+ */
+export function silentEndFallbackText(turnDurationMs: number | undefined): string {
+  const elapsed =
+    typeof turnDurationMs === 'number' && Number.isFinite(turnDurationMs) && turnDurationMs > 0
+      ? ` (waited ${Math.round(turnDurationMs / 1000)}s)`
+      : ''
+  return (
+    '⚠️ The agent finished working but didn’t send a reply' +
+    elapsed +
+    ' — your last message may not have been answered. Please try asking again.'
+  )
+}
+
 function resolveStateDir(deps?: SilentEndDeps): string {
   if (deps?.stateDir != null) return deps.stateDir
   const env = process.env.TELEGRAM_STATE_DIR
@@ -255,6 +295,44 @@ export function recordSilentTurnEnd(
     prev.turnKey === args.turnKey &&
     prev.retryCount >= SILENT_END_MAX_RETRIES
   ) {
+    // Staleness guard (mirrors the represent-guard's #2472 fix,
+    // `gateway/represent-guard.ts:shouldSuppressRepresent`): `turnKey` here
+    // is `statusKey(chatId, threadId)` — stable across every turn on the
+    // same chat/thread, NOT a per-turn nonce (unlike the obligation
+    // ledger's `originTurnId`). The whole mechanism depends on a reply
+    // ALWAYS clearing this state file via `clearSilentEndState` at the
+    // send-site. `clearSilentEndState` is fail-silent by design (state
+    // corruption / a write race must never crash the gateway), so if a
+    // clear is ever missed, a stale `retryCount >= MAX_RETRIES` record
+    // from an OLD, already-answered turn would be misread as "this
+    // brand-new dark turn already exhausted its re-prompt budget" —
+    // firing the user-facing fallback immediately, without the turn ever
+    // going through the Stop-hook re-prompt ladder. Before trusting that
+    // reading, verify against real delivery history: has a genuine reply
+    // landed on this chat/thread since the stale record was last written?
+    // If so, the record is satisfied-but-misdetected — drop it silently
+    // and let this dark turn start its OWN fresh retry cycle instead of
+    // inheriting someone else's spent budget.
+    if (deps?.hasOutboundDeliveredSince?.(args.chatId, prev.timestamp, args.threadId)) {
+      emitLog(
+        deps,
+        `silent-end: stale exhausted record for turnKey=${args.turnKey} ` +
+          `(retryCount=${prev.retryCount}) but a reply was delivered since ` +
+          `${prev.timestamp} — treating as satisfied-but-misdetected, not exhausted\n`,
+      )
+      // MUST clear before writing (adversarial review of #2892):
+      // writeSilentEndState re-inherits retryCount whenever the on-disk
+      // turnKey matches — which it ALWAYS does here, since turnKey is the
+      // stable statusKey(chatId, threadId). Writing over the stale record
+      // directly would start the "fresh" ladder at retryCount=MAX: the
+      // Stop hook would see retryCount >= MAX_RETRIES and never re-prompt,
+      // while this call just returned exhausted:false so no fallback fires
+      // either — pure silence, strictly worse than the pre-fix behaviour.
+      // Clearing first makes the new record genuinely start at retryCount=0.
+      clearSilentEndState(args.turnKey, deps)
+      writeSilentEndState(args, deps)
+      return { exhausted: false }
+    }
     clearSilentEndState(args.turnKey, deps)
     emitLog(
       deps,