switchroom 0.19.42 → 0.19.43

package/telegram-plugin/hooks/silent-end-interrupt-stop.mjs

@@ -69,6 +69,11 @@ import {
   isCapturedProseDeliveryEnabledEnv,
   isGatewayHeartbeatFresh,
 } from './silent-end-scan.mjs'
+import {
+  decideCaptureAudience,
+  resolveOpenObligation,
+  AUDIENCE_INTERNAL,
+} from './audience-classify.mjs'
 
 // MUST stay in sync with SILENT_END_MAX_RETRIES in telegram-plugin/silent-end.ts
 // (this hook is a standalone .mjs and can't import the TS module).
@@ -114,6 +119,16 @@ function buildNextState(base, decision, retryCount) {
   } else {
     delete next.pendingText
   }
+  // #4141: carry THIS turn's reply-throw signal through to the captured-prose
+  // bridge, which is the delivering machine on the ELECTED path and has no
+  // transcript of its own. Same stale-carryover discipline as `pendingText` /
+  // `turnId`: explicitly DELETED when this turn's scan saw no throw, so a
+  // spread of a prior turn's file can never mislabel a clean turn.
+  if (decision.replyToolThrewThisTurn === true) {
+    next.replyToolThrewThisTurn = true
+  } else {
+    delete next.replyToolThrewThisTurn
+  }
   return next
 }
 
@@ -156,13 +171,64 @@ function outboxAlreadyDelivered(outboxDir, nonce) {
   return false
 }
 
+/**
+ * W1-d (#3865): classify WHO the captured prose is for, at capture time — the
+ * only point in the pipeline that can still see the turn.
+ *
+ * The obligation snapshot is read here (impure) and the verdict is computed by
+ * the shared pure classifier, so the hook and the gateway run the identical
+ * predicate. Any failure resolves to `'user'` via `resolveOpenObligation`'s
+ * `'unknown'` → the record delivers exactly as it does today.
+ *
+ * @param {string} stateDir
+ * @param {{ chatId: string|null, originChatId?: string|null, replyToolThrewThisTurn?: boolean }} capture
+ * @returns {'user' | 'internal'}
+ */
+function classifyCaptureAudience(stateDir, capture) {
+  let snapshotRaw = null
+  try {
+    const p = join(stateDir, 'obligations.json')
+    if (existsSync(p)) snapshotRaw = readFileSync(p, 'utf8')
+  } catch {
+    /* unreadable ⇒ null ⇒ 'unknown' ⇒ 'user' (fail-safe toward delivering) */
+  }
+  // #4146: with the ledger disabled, obligations are going UNTRACKED and any
+  // file on disk is a leftover, not a fact. Distrust it outright rather than
+  // read a stale empty set as positive proof that nobody is waiting — that is
+  // the one configuration in which the asymmetric default would invert. (The
+  // gateway also unlinks the snapshot at boot in this mode; this is the
+  // reader-side half, covering the window before it does.)
+  // STATIC is the second persistence-off mode (`gateway.ts:1343` gates the same
+  // `onChange` wiring on it at `:2810`), so it must distrust the file for the
+  // same reason. Writer-side cleanup already covers it at boot; this leg covers
+  // the window the writer cannot — an unlink that failed (EACCES) or a gateway
+  // that has not restarted since the mode changed. Honest caveat:
+  // `TELEGRAM_ACCESS_MODE` is supplied by the host, not by this repo, so if it
+  // is not exported into the hook's environment this leg degrades to a no-op and
+  // the writer-side unlink remains the cover. It can only ever move the verdict
+  // toward DELIVER, so a degraded read is never worse than today.
+  const snapshotTrusted =
+    process.env.SWITCHROOM_OBLIGATION_LEDGER !== '0' &&
+    process.env.TELEGRAM_ACCESS_MODE !== 'static'
+  return decideCaptureAudience({
+    replyToolThrewThisTurn: capture.replyToolThrewThisTurn === true,
+    openInboundObligation: resolveOpenObligation({
+      snapshotRaw,
+      snapshotTrusted,
+      // Same chat the sweep will route to: the envelope chat when present,
+      // else this session's origin chat (`resolveOutboxChat`'s F2 fallback).
+      chatId: capture.chatId ?? capture.originChatId ?? null,
+    }),
+  })
+}
+
 /**
  * Write the durable outbox record for a captured undelivered final answer
  * (atomic tmp+rename), mirroring `writeOutboxRecordAtomic` in `../outbox.ts`.
  * The gateway heartbeat sweep is the single deliverer. Best-effort; never
  * throws. Returns true when a record exists on disk for the nonce afterward.
  */
-function writeOutboxRecord(stateDir, capture) {
+function writeOutboxRecord(stateDir, capture, audience) {
   const outboxDir = join(stateDir, 'outbox')
   try {
     mkdirSync(outboxDir, { recursive: true })
@@ -187,6 +253,18 @@ function writeOutboxRecord(stateDir, capture) {
       // journal alone. Driven by the SAME boolean that gates capture-vs-election
       // in main() — fix and telemetry cannot drift.
       replyAlreadyDeliveredThisTurn: capture.replyAlreadyDeliveredThisTurn === true,
+      // W1-d (#3865): WHO this text is for. Always stamped explicitly (never
+      // left implicit) so a post-change record is self-describing and the
+      // sweep's gate never has to infer. `'user'` is byte-for-byte the
+      // pre-change behaviour.
+      audience: audience === AUDIENCE_INTERNAL ? AUDIENCE_INTERNAL : 'user',
+      // W1-d follow-up (#4141): the RAW structural signal, persisted alongside
+      // the verdict it fed. `audience` collapses it with the obligation state
+      // and loses it; the sweep needs it on its own to decide provenance
+      // framing for the `'user'` records the audience gate deliberately does
+      // not catch (the foreground case). Stamped here because this is the last
+      // point in the pipeline that can still see the transcript.
+      replyToolThrewThisTurn: capture.replyToolThrewThisTurn === true,
     }
     const tmpPath = join(outboxDir, `.${capture.turnNonce}.${process.pid}.tmp`)
     writeFileSync(tmpPath, JSON.stringify(record), 'utf8')
@@ -267,11 +345,16 @@ function main() {
             `deferring to single-writer election (#3510)\n`,
         )
       } else {
-        writeOutboxRecord(stateDir, capture)
+        const audience = classifyCaptureAudience(stateDir, capture)
+        writeOutboxRecord(stateDir, capture, audience)
         process.stderr.write(
           `[silent-end-interrupt] captured undelivered final answer to outbox ` +
             `(nonce=${capture.turnNonce} source=${capture.source} chars=${capture.text.length} ` +
-            `replyAlreadyDeliveredThisTurn=false) — sweep will deliver; allowing stop\n`,
+            `replyAlreadyDeliveredThisTurn=false audience=${audience} ` +
+            `replyToolThrewThisTurn=${capture.replyToolThrewThisTurn === true}) — ` +
+            `${audience === AUDIENCE_INTERNAL
+              ? 'internal prose: journaled for inspection, sweep will NOT deliver'
+              : 'sweep will deliver'}; allowing stop\n`,
         )
         process.exit(0)
       }

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

@@ -248,9 +248,18 @@ function buildTurnId(chatId, threadId, messageId) {
  *   reply tool (Option A transcript-prose bridge). Only populated when it
  *   clears the substance floor, so the gateway never re-delivers a short
  *   trailing pleasantry. Omitted entirely otherwise.
+ * @param {boolean} [replyToolThrewThisTurn] W1-d follow-up (#4141): one of this
+ *   turn's reply-tool calls came back `is_error: true`. Carried on the BLOCK
+ *   result so the single-writer election can persist it onto the silent-end
+ *   state file — the captured-prose bridge (the machine that actually delivers
+ *   on the ELECTED path, where no outbox record is ever written) has no other
+ *   way to learn it. A raw SIGNAL, never a verdict: downstream it only ever
+ *   adds a provenance banner. Omitted rather than `false` when absent, so a
+ *   spread of a prior state file cannot be read as positive evidence.
  */
-function buildBlockResult(envelope, reason, pendingText, hasTrailingProse) {
+function buildBlockResult(envelope, reason, pendingText, hasTrailingProse, replyToolThrewThisTurn) {
   const block = { decided: 'block', reason }
+  if (replyToolThrewThisTurn === true) block.replyToolThrewThisTurn = true
   // Single-writer election input (#duplicate-message fix): does ANY
   // non-empty, non-silent trailing text block exist after the last
   // delivery event? The zero-reply election allows only when this is
@@ -381,6 +390,15 @@ export function scanTurnForFinalReply(jsonl) {
   //    whether emitted as plain text or as a reply-tool payload) or
   //    plain undelivered text.
   const blocks = []
+  // W1-d follow-up (#4141): the same reply-throw signal `scanForOutboxCapture`
+  // already derives, computed here too because the ELECTED path never reaches
+  // that scanner's capture branch (a thrown-but-qualifying reply sets
+  // `replyAlreadyDeliveredThisTurn`, so the hook defers to the election and
+  // writes NO outbox record). Collected as two id sets whose intersection is
+  // the signal. Read-only: nothing below branches on it, so no verdict of this
+  // scanner changes.
+  const replyToolUseIds = new Set()
+  const erroredToolUseIds = new Set()
   for (let i = startIdx + 1; i < lines.length; i++) {
     const line = lines[i]
     if (!line || line[0] !== '{') continue
@@ -390,6 +408,20 @@ export function scanTurnForFinalReply(jsonl) {
     // be in a separate transcript file, but `isSidechain:true` is the
     // documented marker if they leak).
     if (obj?.isSidechain === true) continue
+    if (obj?.type === 'user') {
+      // Tool RESULT lines: `user`-type, content array carrying
+      // `{type:'tool_result', tool_use_id, is_error}`. Same shape read by
+      // `scanForOutboxCapture` (#3865).
+      const rc = obj?.message?.content
+      if (!Array.isArray(rc)) continue
+      for (const r of rc) {
+        if (r?.type !== 'tool_result') continue
+        if (r?.is_error !== true) continue
+        if (typeof r.tool_use_id !== 'string') continue
+        erroredToolUseIds.add(r.tool_use_id)
+      }
+      continue
+    }
     if (obj?.type !== 'assistant') continue
     const content = obj?.message?.content
     if (!Array.isArray(content)) continue
@@ -449,6 +481,9 @@ export function scanTurnForFinalReply(jsonl) {
         }
         continue
       }
+      // #4141: EVERY reply-tool call's id, qualifying or not — an interim ack
+      // that threw is still a reply-tool throw.
+      if (typeof c.id === 'string') replyToolUseIds.add(c.id)
       const input = c.input ?? {}
       const text = String(input.text ?? '')
       // Silent-marker carve-out: the operator explicitly signaled
@@ -555,6 +590,10 @@ export function scanTurnForFinalReply(jsonl) {
   // delivers the joined prose instead of dropping. A pure narration run still
   // yields `undefined` (the #3228 Finding 2 guard, now structural).
   const zeroReplyPendingText = backstopText
+  // #4141 — one of this turn's reply-tool calls errored. Derived here, consumed
+  // only by `buildBlockResult` below (and thence the elected state file); it
+  // gates nothing in this scanner.
+  const replyToolThrewThisTurn = [...replyToolUseIds].some((id) => erroredToolUseIds.has(id))
 
   if (lastAllowBlockIdx === -1) {
     // No qualifying delivery/silence event anywhere in the turn.
@@ -567,7 +606,9 @@ export function scanTurnForFinalReply(jsonl) {
     if (envelope.source === 'cron') {
       return { decided: 'allow', reason: 'cron-source' }
     }
-    return buildBlockResult(envelope, 'no-final-reply', zeroReplyPendingText, hasTrailingProse)
+    return buildBlockResult(
+      envelope, 'no-final-reply', zeroReplyPendingText, hasTrailingProse, replyToolThrewThisTurn,
+    )
   }
 
   if (sawUndeliveredTextAfterAllow) {
@@ -576,7 +617,9 @@ export function scanTurnForFinalReply(jsonl) {
     // 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', pendingText, hasTrailingProse)
+    return buildBlockResult(
+      envelope, 'trailing-text-after-reply', pendingText, hasTrailingProse, replyToolThrewThisTurn,
+    )
   }
 
   return { decided: 'allow', reason: lastAllowReason }
@@ -917,7 +960,7 @@ function resolveSessionOriginChat(lines) {
  *
  * @param {string} jsonl
  * @param {number} [now]
- * @returns {{ capture: false, reason: string } | { capture: true, text: string, turnNonce: string, chatId: string|null, threadId: number|null, source: string, anchorContent: string, replyAlreadyDeliveredThisTurn: boolean, deliveredReplySha256: string|null }}
+ * @returns {{ capture: false, reason: string } | { capture: true, text: string, turnNonce: string, chatId: string|null, threadId: number|null, source: string, anchorContent: string, replyAlreadyDeliveredThisTurn: boolean, deliveredReplySha256: string|null, replyToolThrewThisTurn: boolean }}
  */
 export function scanForOutboxCapture(jsonl, now = Date.now()) {
   const lines = jsonl.split('\n')
@@ -925,12 +968,34 @@ export function scanForOutboxCapture(jsonl, now = Date.now()) {
   const { envelope } = anchor
 
   const blocks = []
+  // W1-d (#3865): ids of reply-tool `tool_use` blocks seen this turn, and the
+  // ids whose `tool_result` came back `is_error: true`. Their intersection is
+  // the "did the reply tool throw this turn" signal.
+  const replyToolUseIds = new Set()
+  const erroredToolUseIds = new Set()
   for (let i = anchor.startIdx + 1; i < lines.length; i++) {
     const line = lines[i]
     if (!line || line[0] !== '{') continue
     let obj
     try { obj = JSON.parse(line) } catch { continue }
     if (obj?.isSidechain === true) continue
+    // W1-d (#3865): tool RESULT lines are how a reply-tool THROW becomes
+    // visible. Claude Code writes the result of a `tool_use` as a `user`-type
+    // line whose content array carries `{type:'tool_result', tool_use_id,
+    // is_error}`. Nothing in this scanner read those before, which is exactly
+    // why an errored reply was indistinguishable from a delivered one — the
+    // transcript shape is otherwise identical.
+    if (obj?.type === 'user') {
+      const rc = obj?.message?.content
+      if (!Array.isArray(rc)) continue
+      for (const r of rc) {
+        if (r?.type !== 'tool_result') continue
+        if (r?.is_error !== true) continue
+        if (typeof r.tool_use_id !== 'string') continue
+        erroredToolUseIds.add(r.tool_use_id)
+      }
+      continue
+    }
     if (obj?.type !== 'assistant') continue
     const content = obj?.message?.content
     if (!Array.isArray(content)) continue
@@ -971,6 +1036,12 @@ export function scanForOutboxCapture(jsonl, now = Date.now()) {
         }
         continue
       }
+      // W1-d (#3865): remember EVERY reply-tool call's id, not just the
+      // qualifying-final-answer ones. An interim ack that threw is still a
+      // reply-tool throw, and the #3861 shape (reply raises, agent then writes
+      // trailing working notes) does not require the errored call to have been
+      // a qualifying final answer.
+      if (typeof c.id === 'string') replyToolUseIds.add(c.id)
       const input = c.input ?? {}
       const text = String(input.text ?? '')
       if (SILENT_MARKER_RE.test(text.trim()) || endsWithSilentMarker(text)) {
@@ -1081,5 +1152,10 @@ export function scanForOutboxCapture(jsonl, now = Date.now()) {
     originThreadId: origin.threadId,
     replyAlreadyDeliveredThisTurn,
     deliveredReplySha256,
+    // W1-d (#3865): one of this turn's reply-tool calls came back an error.
+    // Reported as a raw SIGNAL, not a verdict — `decideCaptureAudience` in
+    // `audience-classify.mjs` combines it with the obligation state (which
+    // this pure transcript scanner cannot see) to decide the audience.
+    replyToolThrewThisTurn: [...replyToolUseIds].some((id) => erroredToolUseIds.has(id)),
   }
 }

package/telegram-plugin/outbox.ts

@@ -65,6 +65,19 @@ import {
 } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
+// W1-d (#3865). The audience vocabulary and its resolution rule live in ONE
+// shared pure module because the unbundled Stop hooks (which stamp it) and this
+// bundled gateway code (which persists and enforces it) must agree exactly. A
+// hand-synced second copy here would be a leak waiting on a drift.
+import type { Audience } from './hooks/audience-classify.mjs'
+// #4141: the provenance-framing rule lives in the same shared pure module, for
+// the same reason — the decision must be one implementation, not two.
+import {
+  applyReplyThrowFraming,
+  shouldFrameReplyThrow,
+} from './hooks/audience-classify.mjs'
+
+export type { Audience }
 
 /** One captured, not-yet-delivered final message for a single main-session turn. */
 export interface OutboxRecord {
@@ -113,6 +126,42 @@ export interface OutboxRecord {
    * or in a sweep journal entry — is direct evidence of a regression.
    */
   replyAlreadyDeliveredThisTurn?: boolean
+  /**
+   * W1-d (#3865): WHO this text is addressed to, decided at capture time by
+   * `hooks/audience-classify.mjs` (`decideCaptureAudience`) — the only point in
+   * the pipeline that can still see the turn that produced it.
+   *
+   * `'internal'` means the text is the agent's own working notes (the #3861
+   * shape: the reply tool threw, nobody was waiting, and the structurally-
+   * selected terminal prose run is orchestration narration rather than an
+   * answer). Such a record is journaled and inspectable but MUST NEVER reach a
+   * chat — the sweep drops it at entry selection.
+   *
+   * OPTIONAL for legacy reasons: every record written before this field
+   * existed has no `audience`, and `resolveRecordAudience` maps missing (and
+   * any non-`'internal'` value) to `'user'`. Suppression requires an
+   * affirmative tag; absence is never evidence.
+   */
+  audience?: Audience
+  /**
+   * W1-d follow-up (#4141): did one of this turn's reply-tool calls come back
+   * `is_error: true`? Stamped at capture by `hooks/silent-end-scan.mjs` (which
+   * reads the `tool_result` blocks) and persisted here so the SWEEP — hours
+   * later, in another process, with the transcript long gone — can still state
+   * this text's provenance.
+   *
+   * This is the raw structural SIGNAL, not a verdict. `audience` already
+   * consumed it once (combined with the obligation state) to decide
+   * suppression; the sweep consumes it again, on its own, to decide FRAMING for
+   * the records suppression deliberately does NOT catch — the foreground case,
+   * where the reply threw but someone is provably still waiting, so the record
+   * is `'user'` and MUST deliver.
+   *
+   * OPTIONAL: absent on every pre-#4141 record and on gateway-authored records
+   * (`gateway/flood-reply-queue.ts`), both of which deliver unframed. Only an
+   * exact boolean `true` changes anything — see `shouldFrameReplyThrow`.
+   */
+  replyToolThrewThisTurn?: boolean
 }
 
 /** One line of the delivered-keys journal (`outbox/delivered.jsonl`). */
@@ -131,6 +180,30 @@ export interface DeliveredEntry {
   deliverySource?: 'sweep' | 'reply-tool' | 'flush'
   /** #3510 instrumentation: see `OutboxRecord.replyAlreadyDeliveredThisTurn`. */
   replyAlreadyDeliveredThisTurn?: boolean
+  /** W1-d (#3865): the record's audience, carried onto the journal line. */
+  audience?: Audience
+  /**
+   * W1-d (#3865): this journal line is a TERMINAL SUPPRESSION, not a delivery.
+   * The sweep withheld an `'internal'` record from the chat and wrote this line
+   * so the nonce is terminally claimed (a second tick sends nothing) and the
+   * decision is durably auditable.
+   *
+   * This is what keeps suppression honest: the outcome is recorded as an
+   * explicit, named state rather than as an absence. `tgMessageId` is absent on
+   * these lines because nothing was sent.
+   */
+  suppressedAudience?: Audience
+  /**
+   * W1-d follow-up (#4141): this delivery carried the reply-throw provenance
+   * banner (`REPLY_THROW_PROVENANCE_NOTICE`) in front of the captured prose.
+   *
+   * Durable and terminal, for the same reason `suppressedAudience` is: framing
+   * changes what a human sees, so the outcome is recorded as an explicit named
+   * state on the journal line rather than being inferable only from a log line
+   * that may have rotated away. `tgMessageId` IS present on these lines — a
+   * framed delivery is a delivery.
+   */
+  framedProvenance?: 'reply-throw'
 }
 
 export function sha256Hex(s: string): string {
@@ -439,6 +512,13 @@ export interface OutboxSweepDecision {
   action: OutboxSweepAction
   /** The text to deliver (with any "(delayed)"/"(from background task)" prefix). */
   text?: string
+  /**
+   * W1-d follow-up (#4141): `text` carries the reply-throw provenance banner.
+   * Surfaced on the decision (rather than left implicit in a string compare) so
+   * the caller can journal the outcome and emit telemetry without re-deriving
+   * the rule.
+   */
+  framedProvenance?: 'reply-throw'
 }
 
 /**
@@ -456,7 +536,10 @@ export interface OutboxSweepDecision {
  *   send-delayed    — older than max-age; deliver with a "(delayed)" prefix, never drop.
  */
 export function decideOutboxSweep(input: {
-  record: Pick<OutboxRecord, 'turnNonce' | 'text' | 'createdAt'>
+  record: Pick<
+    OutboxRecord,
+    'turnNonce' | 'text' | 'createdAt' | 'replyToolThrewThisTurn'
+  >
   now: number
   deliveredNonces: Set<string>
   textAlreadyDelivered: boolean
@@ -476,6 +559,13 @@ export function decideOutboxSweep(input: {
    * `normalizeOutboundBody` (it sends via `bot.api.sendMessage` directly).
    */
   shownLedgerHit?: boolean
+  /**
+   * W1-d follow-up (#4141) kill switch for the reply-throw provenance banner.
+   * `false` restores the pre-change body byte-for-byte; the default is ON.
+   * Passed in rather than read from env here so this core stays pure and the
+   * revert-check can flip it in-process.
+   */
+  provenanceFraming?: boolean
 }): OutboxSweepDecision {
   const {
     record,
@@ -487,6 +577,7 @@ export function decideOutboxSweep(input: {
     quietMs = OUTBOX_QUIET_MS,
     maxAgeMs = OUTBOX_MAX_AGE_MS,
     shownLedgerHit = false,
+    provenanceFraming = true,
   } = input
   if (deliveredNonces.has(record.turnNonce)) return { action: 'skip-journaled' }
   if (shownLedgerHit) return { action: 'skip-ephemeral-shown' }
@@ -496,7 +587,17 @@ export function decideOutboxSweep(input: {
   if (!routable) return { action: 'skip-unroutable' }
   const delayed = age > maxAgeMs
   const prefix = (delayed ? '(delayed) ' : '') + routePrefix
-  return { action: delayed ? 'send-delayed' : 'send', text: prefix + record.text }
+  // #4141: the banner sits BETWEEN the delivery prefixes and the body — the
+  // prefixes describe the DELIVERY ("(delayed)", "(from background task)"),
+  // the banner describes the TEXT. It is additive only: it can never turn a
+  // send into a skip, so this branch cannot manufacture silence.
+  const framed = shouldFrameReplyThrow(record, { frameEnabled: provenanceFraming })
+  const body = framed ? applyReplyThrowFraming(record.text) : record.text
+  return {
+    action: delayed ? 'send-delayed' : 'send',
+    text: prefix + body,
+    ...(framed && body !== record.text ? { framedProvenance: 'reply-throw' as const } : {}),
+  }
 }
 
 export interface ResolvedChat {

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

@@ -28,7 +28,11 @@
 
 import { parse } from "./parse.js";
 import { renderSafe, type RenderResult } from "./render.js";
-import { RICH_MESSAGE_MAX_CHARS, splitMarkdownChunks } from "../format.js";
+import {
+  PLAIN_TEXT_MAX_CHARS,
+  RICH_MESSAGE_MAX_CHARS,
+  splitMarkdownChunks,
+} from "../format.js";
 
 /**
  * The legacy plain-text `sendMessage` / `editMessageText` wire cap (4096
@@ -38,8 +42,12 @@ import { RICH_MESSAGE_MAX_CHARS, splitMarkdownChunks } from "../format.js";
  * the plain `sendMessage` endpoint (see stream-controller `doSend`/`doEdit`).
  * A degraded plain body larger than this is rejected by Telegram with
  * `message is too long`, so `renderOutboundChunks` caps plain pieces here.
+ *
+ * Defined in `format.ts` (#4043) so the parse-reject plain FALLBACKS in the
+ * send path can share the one constant without importing the renderer;
+ * re-exported here for this module's existing importers.
  */
-export const PLAIN_TEXT_MAX_CHARS = 4096;
+export { PLAIN_TEXT_MAX_CHARS };
 
 /** Parse the `SWITCHROOM_RICH_RENDER` kill-switch value. Default ON; disabled
  *  only by an explicit falsey/off token (`0`/`false`/`off`/`no`,

package/telegram-plugin/reply-quote.ts

@@ -0,0 +1,150 @@
+/**
+ * Surgical quote-reply parameters (`reply_parameters.quote`).
+ *
+ * The `reply` / `stream_reply` tools document a `quote_text` argument: quote a
+ * specific fragment of the message being replied to, so the reply visibly
+ * anchors on that fragment instead of the whole message.
+ *
+ * WIRE SHAPE — the bug this module exists to make unrepeatable
+ * ------------------------------------------------------------
+ * Bot API `ReplyParameters` (https://core.telegram.org/bots/api#replyparameters):
+ *
+ *   quote           String   Quoted part of the message to be replied to;
+ *                            0-1024 characters after entities parsing.
+ *   quote_parse_mode String  Mode for parsing entities in the quote.
+ *   quote_entities   Array   Entities in the quote.
+ *   quote_position   Integer Position of the quote in the original message in
+ *                            UTF-16 code units.
+ *
+ * `quote` is a **String** and `quote_position` is a **separate sibling
+ * Integer**. Both send sites used to emit `quote: { text, position: 0 }` — an
+ * object — so Telegram rejected every quoted reply with
+ * `400 Bad Request: field "quote" must be of type String`, the reply threw, and
+ * the agent re-attempted a payload that could never be accepted. A fleet sweep
+ * of `tg-post method=sendRichMessage … status=err` lines found 378 of 384 total
+ * send failures were this one error (agent `overlord`, 2026-07-29 → 07-30, in
+ * retry bursts). The feature had never worked.
+ *
+ * DELIBERATE OMISSIONS
+ * --------------------
+ * - **No `quote_position`.** Telegram locates the quote text on its own; a
+ *   fabricated `0` is what encouraged the object shape in the first place, and
+ *   neither send site has a real position source (the model supplies text, not
+ *   an offset). A wrong position is worse than none: it either mislocates the
+ *   highlight or 400s.
+ * - **No `quote_parse_mode` / `quote_entities`, and therefore NO HTML
+ *   escaping.** With no parse mode the quote is matched as literal text, which
+ *   is exactly what `quote_text` carries (plain text the model copied out of
+ *   the user's message). Escaping it (`&` → `&`) would make the string stop
+ *   being an exact substring of the original and guarantee a rejection.
+ *
+ * REJECTION HANDLING
+ * ------------------
+ * The quote must be an exact substring of the target message; Telegram 400s
+ * when it isn't found. That is a *quote* failure, not an answer failure — the
+ * reply body is still correct and must still be delivered. {@link
+ * isQuoteRejectionError} classifies it and {@link dropQuoteFromSendOpts}
+ * produces the same options with the quote removed, so callers can retry once
+ * and land the reply as an ordinary (unquoted) reply.
+ */
+
+import { GrammyError } from 'grammy'
+
+import { isHtmlParseRejectError, isMessageTooLongError } from './retry-api-call.js'
+
+/** Bot API cap: `quote` is 0-1024 characters after entities parsing. */
+export const QUOTE_MAX_CHARS = 1024
+
+/**
+ * Normalize a caller-supplied `quote_text` into the string Telegram accepts, or
+ * `null` when there is nothing worth quoting.
+ *
+ * - empty / whitespace-only ⇒ `null` (an empty quote highlights nothing and is
+ *   a guaranteed rejection).
+ * - longer than {@link QUOTE_MAX_CHARS} ⇒ truncated. A PREFIX of an exact
+ *   substring is still an exact substring, so truncation still matches the
+ *   original message, whereas an over-length quote is a certain 400. The cut
+ *   never splits a surrogate pair (a lone surrogate is not valid UTF-8 on the
+ *   wire).
+ * - otherwise verbatim — never escaped, never trimmed (leading/trailing spaces
+ *   are part of the substring the user may have selected).
+ */
+export function normalizeQuoteText(quoteText: string | null | undefined): string | null {
+  if (typeof quoteText !== 'string') return null
+  if (quoteText.trim().length === 0) return null
+  if (quoteText.length <= QUOTE_MAX_CHARS) return quoteText
+  let end = QUOTE_MAX_CHARS
+  const code = quoteText.charCodeAt(end - 1)
+  // High surrogate at the cut boundary ⇒ drop it rather than emit half a pair.
+  if (code >= 0xd800 && code <= 0xdbff) end -= 1
+  return quoteText.slice(0, end)
+}
+
+/**
+ * Build the `reply_parameters` object for a reply to `messageId`, optionally
+ * carrying a surgical quote.
+ *
+ * This is the ONLY place the `quote` field is constructed. Both send sites (the
+ * `reply` chunk loop in `gateway/outbound-send-path.ts` and the `stream_reply`
+ * controller in `stream-controller.ts`) call it, so the wire shape cannot drift
+ * apart again.
+ */
+export function buildReplyParameters(
+  messageId: number,
+  quoteText?: string | null,
+): { message_id: number; quote?: string } {
+  const quote = normalizeQuoteText(quoteText)
+  return { message_id: messageId, ...(quote != null ? { quote } : {}) }
+}
+
+/**
+ * True when Telegram rejected the send because of the QUOTE, not the body.
+ *
+ * Covers the "quote isn't in the original message" family (the documented
+ * failure mode) and any other 400 naming the quote — matched on the word rather
+ * than one exact phrase, because the Bot API's wording for this class has
+ * changed before (`QUOTE_TEXT_INVALID` vs the prose form) and a missed match
+ * costs the whole answer.
+ *
+ * A BODY error must never be claimed here, though, and the word alone is not
+ * enough to tell them apart: `<blockquote>` in a rich body produces
+ * `can't parse entities: Can't find end tag corresponding to start tag
+ * "blockquote"` / `Unsupported start tag "blockquote"` — 400s that contain the
+ * substring "quote" but are PARSE failures. Claiming one would drop the quote
+ * and resend the same unparseable body, hit the same 400, and throw straight
+ * out of the caller's fallback ladder — losing the answer that the plain-text
+ * rescue would otherwise have delivered. So defer to the body classifiers
+ * first, exactly as `isHtmlParseRejectError` defers to `isMessageTooLongError`
+ * (retry-api-call.ts) for the same reason. No false negative results: the real
+ * quote rejections (`QUOTE_TEXT_INVALID`, "message quote not found") contain
+ * neither a parse phrase nor a length phrase.
+ */
+export function isQuoteRejectionError(err: unknown): boolean {
+  if (!(err instanceof GrammyError) || err.error_code !== 400) return false
+  if (isHtmlParseRejectError(err) || isMessageTooLongError(err)) return false
+  return (err.description || '').toLowerCase().includes('quote')
+}
+
+/** True when `opts` carries a `reply_parameters.quote`. Structural on purpose:
+ *  the reply path builds untyped `Record<string, unknown>` send options and the
+ *  stream path a typed `StreamSendOpts`, and both must be checkable. */
+export function sendOptsHaveQuote(opts: object): boolean {
+  const rp = (opts as { reply_parameters?: { quote?: unknown } }).reply_parameters
+  return rp != null && typeof rp === 'object' && rp.quote != null
+}
+
+/**
+ * Same send options with the surgical quote removed — the retry payload after a
+ * {@link isQuoteRejectionError}. Everything else (reply target, thread, markup,
+ * notification) is preserved, so the answer still lands as a reply to the right
+ * message; only the highlight is sacrificed.
+ */
+export function dropQuoteFromSendOpts<T extends object>(opts: T): T {
+  if (!sendOptsHaveQuote(opts)) return { ...opts }
+  const rp = { ...((opts as { reply_parameters: Record<string, unknown> }).reply_parameters) }
+  delete rp.quote
+  delete rp.quote_parse_mode
+  delete rp.quote_entities
+  delete rp.quote_position
+  return { ...opts, reply_parameters: rp }
+}