switchroom 0.21.8 → 0.21.10

package/telegram-plugin/format.ts

@@ -99,9 +99,26 @@ export function codeSpanSafe(s: string): string {
  * `\` first (so we never double-escape a following escape), then BOTH `(` and
  * `)` — the whole URL is preserved balanced and micromark decodes it back to
  * the original href on round-trip. Bot API 10.1 lists `(`/`)` as escapable.
+ *
+ * WHITESPACE and control characters are PERCENT-ENCODED rather than
+ * backslash-escaped. A bare link destination ends at the first ASCII
+ * whitespace character, so a space or a newline inside the href does not just
+ * truncate the URL — the remainder is re-read as a link title, or (for a
+ * newline) the inline link is terminated outright, leaving a structurally
+ * broken construct with URL fragments visible as prose. Backslash cannot
+ * rescue that: whitespace is not escapable in a bare destination. `%20` /
+ * `%0A` are the canonical URL encodings, so the href a client resolves is
+ * equivalent to the one the author wrote.
  */
 export function escapeLinkHref(href: string): string {
-  return href.replace(/\\/g, '\\\\').replace(/\(/g, '\\(').replace(/\)/g, '\\)')
+  return href
+    .replace(/\\/g, '\\\\')
+    .replace(/\(/g, '\\(')
+    .replace(/\)/g, '\\)')
+    .replace(
+      /[\x00-\x20\x7f]/g,
+      (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`,
+    )
 }
 
 /**
@@ -735,9 +752,12 @@ export function normalizePunctuation(text: string): string {
   // The dash rewrite runs per line so blockquote lines can be exempted:
   // `>` blockquotes are reserved for VERBATIM quoted text, and rewriting an
   // author's ` — ` to `, ` inside a quotation would corrupt what they quoted.
-  // The expandable-blockquote opener `**>` is a blockquote line too even though
-  // isBlockquoteLine (which keys on a leading `>`) doesn't catch the `**`
-  // prefix, so exempt it explicitly. Code spans and link hrefs stay masked
+  // A line opening with the LEGACY `**>` expandable-quote marker is a
+  // blockquote line too (the render path no longer emits `**>` — it is
+  // MarkdownV2-only syntax, see render.ts renderBlockquote — but legacy agent
+  // output still contains it and parse.ts repairs it into a real quote), so
+  // exempt it explicitly even though isBlockquoteLine (which keys on a leading
+  // `>`) doesn't catch the `**` prefix. Code spans and link hrefs stay masked
   // throughout, so their dashes are already protected on every line.
   const rewriteDashes = (line: string): string =>
     line
@@ -1414,7 +1434,12 @@ const INLINE_SPAN_PATTERNS: readonly RegExp[] = [
   /\*\*[^*\n]+\*\*/g, // bold
   /__[^_\n]+__/g, // underline
   /(?<![\w*])_[^_\n]+_(?![\w*])/g, // italic (snake_case-guarded)
-  /\[[^\]\n]*\]\([^)\n]*\)/g, // link [label](href)
+  // link `[label](href)` — and, via the optional leading `!`, Telegram's
+  // inline-entity form `![22:45 tomorrow](tg://time?unix=…&format=…)` /
+  // `![](tg://emoji?id=…)`. Without the `!?` the protected span would start at
+  // the `[`, so a cut could land in the one-character gap and strand the `!`
+  // on the previous chunk — silently demoting a date_time entity to a link.
+  /!?\[[^\]\n]*\]\([^)\n]*\)/g,
   /~~[^~\n]+~~/g, // strikethrough
   /\|\|[^|\n]+\|\|/g, // spoiler
 ]

package/telegram-plugin/gateway/outbound-send-path.ts

@@ -43,6 +43,7 @@ import {
   isQuoteRejectionError,
   sendOptsHaveQuote,
 } from '../reply-quote.js'
+import { captureSpeechText } from './speech-capture.js'
 
 // ── send-orchestration façade imports (#2996 P2) ──
 // Pure/deterministic helpers are imported; stateful or side-effecting gateway
@@ -1376,6 +1377,12 @@ export async function sendReply(
   // plain-text TTS input); synthesis happens just before the send so a
   // voice-only reply can suppress the text chunk loop on success. Voice is
   // fully best-effort — every failure below falls back to the text reply.
+  // Raw-corpus capture (TTS redesign PR-0, flag-gated, off by default): `text`
+  // here IS Stage A's future input — capture it byte-for-byte BEFORE the
+  // resolve call, ahead of any TTS normalisation, so the redesign's property
+  // tests can validate against real markdown instead of synthetic fixtures
+  // only. See telegram-plugin/gateway/speech-capture.ts.
+  captureSpeechText(text)
   const voiceOutPlan = resolveVoiceOutPlan(access.voice_out, text)
   const configParseMode = access.parseMode ?? 'html'
   const format = (args.format as string | undefined) ?? configParseMode

package/telegram-plugin/gateway/speech-capture.ts

@@ -0,0 +1,158 @@
+/**
+ * Raw pre-normalisation speech-text capture (TTS normalisation redesign,
+ * PR-0 — `/tmp/claude-0/tts/out/fable-plan-v2.md` §9).
+ *
+ * Flag-gated on `SWITCHROOM_SPEECH_CAPTURE=1` (or `=true`), OFF by default:
+ * unset (or any other value) is a true no-op — `captureSpeechText` returns
+ * immediately without touching the filesystem, so the send path pays zero
+ * cost. When enabled, appends exactly one JSON line `{ts, text}` — where
+ * `text` is the EXACT string about to be passed to `resolveVoiceOutPlan`,
+ * byte-for-byte, no re-encoding — to `$TELEGRAM_STATE_DIR/speech-capture.jsonl`
+ * before that call (fable-plan-v2.md §0 C-4: that string IS Stage A's future
+ * input). NOT the same string the visible rich render displays — the render
+ * path additionally runs `computeEffectiveText`/`addParagraphSpacers` (U+00A0
+ * paragraph spacers) downstream of this capture point; this captures the
+ * plain pre-spacer prose Stage A will actually consume.
+ *
+ * Why this exists: `corpus.json` (the existing replay corpus) was captured
+ * downstream of the legacy pass-1 normaliser, so it carries zero tables,
+ * fences, pipes, or emoji (fable-plan-v2.md §0 C-3) — useless for validating
+ * the new Stage-A renderer beyond synthetic fixtures. `telegram/history.db`
+ * is also unusable: it stores text as Telegram echoed it back (rendered),
+ * not the pre-render markdown. Capture must happen in-process, here.
+ *
+ * Privacy: the capture file holds the full plaintext body of every outbound
+ * reply while the flag is on, so it is created `0o600` (owner-only) — NOT
+ * the default-umask `0o644` `appendFileSync` would otherwise produce, which
+ * would leave it world-readable in a directory where `access.json` (the chat
+ * allowlist) is deliberately `0o600`. Mode only applies at file CREATION
+ * (Node ignores `mode` on an append to an existing file), matching the
+ * established pattern in this codebase (`shown-ledger.ts`, `outbox.ts`).
+ *
+ * Write failures are swallowed — capture must never break a send — but never
+ * silently: the first write failure (and, rate-limited, subsequent ones)
+ * logs one stderr line, because a foreign-uid EACCES on this file (the #4371
+ * failure class: some other process touches it, it becomes root-owned, the
+ * agent uid EACCESes on every append thereafter) must be observable across a
+ * 7-day unattended capture window, not discovered after the fact from an
+ * empty corpus.
+ *
+ * Deliberately does NOT bound or rotate the capture file: the spec (§9 PR-0)
+ * describes a plain unbounded append for a time-boxed 7-day fleet-wide
+ * capture window (measured fleet-wide: ~2.9 MB over 7 days), after which the
+ * file is reviewed, secrets-scrubbed, and checked into the repo as a static
+ * fixture — it is not a long-lived production log.
+ *
+ * The enabled check reads `process.env` on every call (deliberately NOT
+ * cached at module scope, unlike `current-turn-map.ts`'s
+ * `EMISSION_AUTHORITY_ENABLED` kill-switch convention): the read is a single
+ * property lookup, not the per-turn state-store cost that convention exists
+ * to avoid, and caching it would make the flag un-togglable within a single
+ * test process — which the load-bearing "a capture write failure never
+ * breaks the reply" guarantee needs to exercise against the REAL `sendReply`
+ * wiring (see `send-reply-golden.test.ts`), not a synthetic call.
+ */
+
+import { appendFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const SPEECH_CAPTURE_FILE_NAME = 'speech-capture.jsonl'
+
+/** File created owner-read-write only (see the Privacy note above). */
+const SPEECH_CAPTURE_FILE_MODE = 0o600
+
+export interface CaptureSpeechTextOptions {
+  /** Override the enabled flag (tests only); default reads
+   *  `SWITCHROOM_SPEECH_CAPTURE` from the environment. */
+  enabled?: boolean
+  /** Override the destination directory (tests only); default
+   *  `process.env.TELEGRAM_STATE_DIR`. */
+  stateDir?: string
+  /** Override the clock (tests only). */
+  now?: () => number
+}
+
+function envFlagEnabled(): boolean {
+  const v = process.env.SWITCHROOM_SPEECH_CAPTURE
+  return v === '1' || v === 'true'
+}
+
+function isCaptureEnabled(override: boolean | undefined): boolean {
+  if (override !== undefined) return override
+  return envFlagEnabled()
+}
+
+// One-shot "capture is live" log line, latched the first time capture
+// actually fires (not at module import — importing this module must stay a
+// true no-op regardless of whether the flag ends up used) — and a
+// rate-limited write-error log so a foreign-uid EACCES (#4371 class) is
+// observable within the window, not just discoverable from an empty corpus
+// after the fact.
+let loggedEnabledOnce = false
+// `null`, not `0`: a real failure at `Date.now() === 0` (or in a test driven
+// by `vi.setSystemTime(0)`) must still log — `0` is a valid past timestamp,
+// not "never logged", so it cannot double as the sentinel.
+let lastWriteErrorLoggedAt: number | null = null
+const WRITE_ERROR_LOG_INTERVAL_MS = 5 * 60_000
+
+function logEnabledOnce(): void {
+  if (loggedEnabledOnce) return
+  loggedEnabledOnce = true
+  try {
+    process.stderr.write(
+      `telegram gateway: speech-capture: enabled — writing $TELEGRAM_STATE_DIR/${SPEECH_CAPTURE_FILE_NAME}\n`,
+    )
+  } catch {
+    // Logging must never break the send path.
+  }
+}
+
+function logWriteErrorRateLimited(err: unknown, nowMs: number): void {
+  if (lastWriteErrorLoggedAt !== null && nowMs - lastWriteErrorLoggedAt < WRITE_ERROR_LOG_INTERVAL_MS) return
+  lastWriteErrorLoggedAt = nowMs
+  try {
+    const msg = err instanceof Error ? err.message : String(err)
+    process.stderr.write(
+      `telegram gateway: speech-capture: write failed (further failures rate-limited ` +
+        `${Math.round(WRITE_ERROR_LOG_INTERVAL_MS / 60_000)}m) err=${msg}\n`,
+    )
+  } catch {
+    // Logging must never break the send path.
+  }
+}
+
+/**
+ * Append one `{ts, text}` JSON line to the raw-corpus capture file when
+ * capture is enabled. `text` must be the EXACT string about to be passed to
+ * `resolveVoiceOutPlan` — no trimming, no re-encoding, byte-for-byte
+ * preservation of markdown (tables, fences, pipes, emoji, backticks, ...).
+ * Off by default; a true no-op when the flag is unset. Never throws.
+ */
+export function captureSpeechText(text: string, opts: CaptureSpeechTextOptions = {}): void {
+  if (!isCaptureEnabled(opts.enabled)) return
+  logEnabledOnce()
+  try {
+    const stateDir = opts.stateDir ?? process.env.TELEGRAM_STATE_DIR
+    if (stateDir == null || stateDir.length === 0) return
+    const now = opts.now ?? Date.now
+    const line = `${JSON.stringify({ ts: now(), text })}\n`
+    appendFileSync(join(stateDir, SPEECH_CAPTURE_FILE_NAME), line, {
+      encoding: 'utf8',
+      mode: SPEECH_CAPTURE_FILE_MODE,
+    })
+  } catch (err) {
+    // Capture must never break the send path — but never silently either
+    // (M2/#4371 class).
+    logWriteErrorRateLimited(err, Date.now())
+  }
+}
+
+/**
+ * Test-only: reset the one-shot enable log and the write-error rate limiter,
+ * so a test asserting stderr output is independent of import/call order
+ * versus every other test sharing this module instance.
+ */
+export function __resetSpeechCaptureLogStateForTests(): void {
+  loggedEnabledOnce = false
+  lastWriteErrorLoggedAt = null
+}

package/telegram-plugin/package.json

@@ -31,7 +31,7 @@
     "@secretlint/core": "^12.2.0",
     "@secretlint/secretlint-rule-preset-recommend": "^12.2.0",
     "@xterm/headless": "^6.0.0",
-    "grammy": "^1.44",
+    "grammy": "^1.45",
     "mdast-util-from-markdown": "^2.0.2",
     "mdast-util-gfm": "^3.0.0",
     "micromark-extension-gfm": "^3.0.0",

package/telegram-plugin/render/code-segments.ts

@@ -73,6 +73,13 @@ export function splitCodeSegments(text: string): Segment[] {
 //   • bare autolinked URLs — `http(s)://…` and `www.…` runs Telegram auto-links.
 //   • GFM table rows — a table's structural pipes / empty cells (`|a||b|`) must
 //     survive; escaping inside a real table row corrupts the table.
+//   • inline-math `$…$` spans — Telegram's rich GFM parser typesets a `$…$`
+//     pair as a real mathematical_expression node (wire-verified 2026-08-13).
+//     A COMPACT span (whitespace-free inner run that is not a bare currency
+//     amount, e.g. `$x^2+y^2$`) is intentional math and must reach the wire
+//     byte-identical: no guard may escape its `$`, `^`, `_`, `*`, or `+`.
+//     Currency-shaped inners (`$5M-$`) are NOT protected, so the dollar-math
+//     guard still breaks accidental `$5M … $10M` currency pairs (#3252).
 // Everything else is prose and stays fully guarded. This is the sibling of the
 // code-span skip: a PROTECTED segment (`code: true`) is emitted verbatim.
 //
@@ -93,6 +100,19 @@ function isTableCandidateLine(line: string): boolean {
   return /^\s*\|/.test(line);
 }
 
+/** A compact `$…$` inline-math pair: opening `$`, a whitespace-free inner run
+ *  with no nested `$`, closing `$`. Anchored — tested at the scanner's current
+ *  position only. */
+const COMPACT_MATH_PAIR = /^\$([^\s$]+)\$/;
+
+/** A currency-shaped inner run: digits plus amount punctuation and magnitude
+ *  suffix letters only (`5M-`, `0.5`, `10,000`, `5+`). Such a run between two
+ *  `$` is a pair of ADJACENT currency amounts (`$5M-$10M`), not math — it must
+ *  stay guardable so the dollar-math guard can break the accidental pair. A
+ *  run containing any other character (`x^2+y^2`, `\alpha`, `a_b`) is treated
+ *  as intentional math and protected. */
+const CURRENCY_SHAPED_INNER = /^[0-9.,+\-kKmMbB]+$/;
+
 /** Find the [start, end) char ranges (relative to `text`) of GFM table blocks —
  *  maximal runs of 2+ consecutive `|`-leading lines that contain a delimiter
  *  row. Each returned range spans whole lines INCLUDING their trailing newline,
@@ -185,6 +205,19 @@ function splitProseProtected(text: string): Segment[] {
         continue;
       }
     }
+    // 4. Compact inline-math pair `$…$` — a supported Telegram construct
+    //    (mathematical_expression, wire-verified 2026-08-13) that must reach
+    //    the wire verbatim. Currency-shaped inners are NOT math (they are two
+    //    adjacent amounts like `$5M-$10M`) and stay guardable.
+    if (ch === "$") {
+      const m = COMPACT_MATH_PAIR.exec(text.slice(i));
+      if (m && !CURRENCY_SHAPED_INNER.test(m[1])) {
+        const end = i + m[0].length;
+        pushProtected(i, end);
+        i = end;
+        continue;
+      }
+    }
     i++;
   }
   if (plainStart < text.length) out.push({ code: false, text: text.slice(plainStart) });
@@ -193,10 +226,11 @@ function splitProseProtected(text: string): Segment[] {
 
 /** Split rendered markdown into prose / protected segments where a PROTECTED
  *  (`code: true`) segment is any content a guard must emit verbatim: code spans,
- *  fenced code blocks, markdown link destinations, bare autolinks, and GFM
- *  table rows. This is the link/table-aware superset of `splitCodeSegments` that
- *  all four #3252 guards route through. Prose segments (`code: false`) remain
- *  guardable (including a link's `[label]` text). Deterministic, linear-time. */
+ *  fenced code blocks, markdown link destinations, bare autolinks, GFM table
+ *  rows, and compact `$…$` inline-math spans. This is the link/table/math-aware
+ *  superset of `splitCodeSegments` that all the #3252 guards route through.
+ *  Prose segments (`code: false`) remain guardable (including a link's
+ *  `[label]` text). Deterministic, linear-time. */
 export function splitProtectedSegments(text: string): Segment[] {
   const out: Segment[] = [];
   for (const seg of splitCodeSegments(text)) {

package/telegram-plugin/render/dollar-math-guard.ts

@@ -29,6 +29,20 @@
 // a `$…$` pair if only the leading-`$digit` token is escaped — so we escape the
 // lot once the currency signal + 2-dollar threshold are met.
 //
+// ── INTENTIONAL math is exempt (wire-verified 2026-08-13) ─────────────────
+// Telegram's rich path renders a `$…$` pair as a native mathematical_expression
+// node, and intentional math (`$x^2+y^2$`) must reach the wire byte-identical —
+// an escaped `\$x^2+y^2\$` destroys a SUPPORTED construct. The discrimination
+// lives in `splitProtectedSegments` (code-segments.ts): a COMPACT math span
+// (whitespace-free inner, not currency-shaped) is a protected segment, so this
+// guard neither counts its `$`s toward the 2+ threshold nor escapes them.
+// Currency amounts always sit next to whitespace/prose (`$5M and $10M`) or have
+// a digits-and-punctuation-only inner (`$5M-$10M`), so #3252-class accidental
+// pairs remain fully guarded. Known residual: a SPACED math span (`$a + b$`)
+// is indistinguishable from currency prose and is not exempted — it is escaped
+// when the message also carries a currency signal, rendering as literal text
+// (legible, not broken).
+//
 // Idempotent (F5): the escape uses a negative-lookbehind (`(?<!\\)\$`) so an
 // already-escaped `\$` is never doubled to `\\$`. Running the guard twice (e.g.
 // the streaming path renders then this wrapper re-wraps) is a strict no-op the
@@ -100,7 +114,8 @@ const UNESCAPED_DOLLAR = /(?<!\\)\$/g;
  * them is digit-adjacent (a currency signal). When armed, EVERY unescaped prose
  * `$` is backslash-escaped so no two `$` can pair into a math span — this is
  * what closes the F3 trailing-`$` / `$.50` false-negatives. Code spans / fenced
- * blocks are never touched. Idempotent (F5) and deterministic.
+ * blocks AND compact intentional-math `$…$` spans (protected segments, see
+ * code-segments.ts) are never touched. Idempotent (F5) and deterministic.
  */
 export function guardDollarMath(text: string): string {
   if (!text.includes("$")) return text;