switchroom 0.18.17 → 0.18.18

package/telegram-plugin/llm-error-present.ts

@@ -0,0 +1,436 @@
+/**
+ * llm-error-present.ts — humanized, cross-surface-deduped presentation of an
+ * LLM/API error, so a raw `b'{"type":"error",…}'` line never reaches a user.
+ *
+ * THE PROBLEM this closes
+ * -----------------------
+ * One Anthropic error JSONL line fans out to THREE independent render surfaces,
+ * none consulting each other, each historically printing the raw `detail`
+ * string with its `b'{…}'` byte-blob attached:
+ *   1. the agent turn-end "done" card (tool-activity-summary result block),
+ *   2. the operator-event "🚦 Rate limited" card (raw `detail`), and
+ *   3. the reply/answer passthrough (the synthetic-assistant error text relayed
+ *      as the turn's answer).
+ *
+ * This module owns the ONE clean rendering + the ONE dedup authority the three
+ * surfaces consult, so a fan-out produces EXACTLY ONE user-facing message with
+ * NO raw JSON. It reuses the existing classifiers rather than re-deriving them:
+ * `classify429Detail` (throttle-tier.ts), `detectModelUnavailable` /
+ * `parseResetTime` (model-unavailable.ts), `isLitellmProxyLocal429` /
+ * `isTransientUpstreamSignal` (model-unavailable.ts), `classifyClaudeError`
+ * (operator-events.ts). `coreText` is ALWAYS built from a per-kind template —
+ * never from the raw `detail` — and `stripRawErrorBytes` is the belt-and-braces
+ * scrub so even the enrichment `reason` can carry no JSON.
+ *
+ * Pure module: no IPC, no bot, no FS. The only mutable state is the
+ * `ErrorPresenceGate` singleton (an in-memory dedup ledger), driven by an
+ * injectable `now`.
+ */
+
+import {
+  detectModelUnavailable,
+  isLitellmProxyLocal429,
+  parseResetTime,
+} from './model-unavailable.js'
+import { classify429Detail } from './throttle-tier.js'
+import { classifyClaudeError } from './operator-events.js'
+import type { InlineKeyboardMarkup } from './operator-events.js'
+import { stripRawErrorBytes, extractRequestId } from './raw-error-scrub.js'
+import { fmtLocalClock, tzAbbrev } from './shared/local-time.js'
+
+export { stripRawErrorBytes, extractRequestId } from './raw-error-scrub.js'
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type LlmErrorKind =
+  | 'rate_limit'
+  | 'overload_529'
+  | 'quota_wall'
+  | 'auth'
+  | 'transient'
+  | 'unknown'
+
+export type LlmErrorSource = 'anthropic' | 'litellm-local' | 'network'
+
+export interface ParsedLlmError {
+  kind: LlmErrorKind
+  /** Human, JSON-STRIPPED one-liner built from a per-kind template. Never raw. */
+  coreText: string
+  /** Parsed reset instant, when the source carried one. */
+  resetAt?: Date
+  /** Parsed retry-after window in ms, when the source carried one. */
+  retryAfterMs?: number
+  /** Resolved model id, when the source named one. */
+  model?: string
+  /** Anthropic `request_id`, when present — the strongest dedup key. */
+  requestId?: string
+  source: LlmErrorSource
+  /** True when the harness is still retrying this error internally (mid-retry). */
+  autoRetrying: boolean
+  /** True when the failure is final (NOT an in-flight retry). */
+  terminal: boolean
+}
+
+/** Optional retry-state annotations Claude Code stamps on a retried error line. */
+export interface LlmErrorRetryState {
+  retryAttempt: number | null
+  maxRetries: number | null
+}
+
+// ─── model extraction ────────────────────────────────────────────────────────
+
+/** Pull a resolved model id (`claude-…`, `sr-…`) out of a raw string, or undefined. */
+function extractModel(raw: string): string | undefined {
+  const m = raw.match(/["']?model["']?\s*[=:]\s*["']?((?:claude|sr)[A-Za-z0-9._-]+)/i)
+  return m ? m[1] : undefined
+}
+
+// ─── Parser ──────────────────────────────────────────────────────────────────
+
+const TRANSIENT_KINDS: ReadonlySet<LlmErrorKind> = new Set<LlmErrorKind>([
+  'rate_limit',
+  'overload_529',
+  'transient',
+])
+
+/** The always-actionable kinds — NEVER silenced, even inside a collapse window. */
+export function isActionableKind(kind: LlmErrorKind): boolean {
+  return kind === 'auth' || kind === 'quota_wall'
+}
+
+/**
+ * Parse a raw error string (a session-tail `detail`, an isApiErrorMessage
+ * text, or a raw stderr line) into a structured, JSON-free ParsedLlmError.
+ * Reuses the existing wording classifiers; maps their kinds into this union.
+ */
+export function parseLlmError(
+  raw: string,
+  retryState?: LlmErrorRetryState,
+): ParsedLlmError {
+  const text = typeof raw === 'string' ? raw : ''
+  const requestId = extractRequestId(text)
+  const model = extractModel(text)
+
+  // Reset / retry-after best-effort (Anthropic + relative wordings).
+  const resetAt = parseResetTime(text)
+  const retryAfterMs =
+    resetAt != null ? Math.max(0, resetAt.getTime() - Date.now()) : undefined
+
+  const { kind, source } = classifyKindAndSource(text)
+
+  // Retry / terminal semantics. Only the transient family can be mid-retry;
+  // auth / quota_wall / model_unavailable are terminal by construction.
+  let autoRetrying = false
+  let terminal = true
+  if (TRANSIENT_KINDS.has(kind)) {
+    const { retryAttempt, maxRetries } = retryState ?? { retryAttempt: null, maxRetries: null }
+    if (retryAttempt != null && maxRetries != null) {
+      autoRetrying = retryAttempt < maxRetries
+      terminal = retryAttempt >= maxRetries
+    } else {
+      // No retry annotation: treat as a surfaced (terminal) failure — Claude
+      // writes the user-facing error shape only after its own retries are done.
+      autoRetrying = false
+      terminal = true
+    }
+  }
+
+  return {
+    kind,
+    coreText: buildCoreText(kind, source),
+    ...(resetAt != null ? { resetAt } : {}),
+    ...(retryAfterMs != null ? { retryAfterMs } : {}),
+    ...(model != null ? { model } : {}),
+    ...(requestId != null ? { requestId } : {}),
+    source,
+    autoRetrying,
+    terminal,
+  }
+}
+
+function classifyKindAndSource(text: string): { kind: LlmErrorKind; source: LlmErrorSource } {
+  const lower = text.toLowerCase()
+
+  // 1. Auth — always terminal, always actionable.
+  const claudeKind = classifyClaudeError({ message: text, type: text })
+  if (claudeKind === 'credentials-expired' || claudeKind === 'credentials-invalid') {
+    return { kind: 'auth', source: 'anthropic' }
+  }
+
+  // 2. LiteLLM-proxy-LOCAL 429 — the proxy's own limiter, never Anthropic.
+  //    Checked before the generic quota/overload matchers because some LiteLLM
+  //    bodies contain the word "limit" that a quota matcher could seize on.
+  if (isLitellmProxyLocal429(text)) {
+    return { kind: 'rate_limit', source: 'litellm-local' }
+  }
+
+  // 3. Model-unavailable detector owns quota-wall / overload / network wording.
+  const mu = detectModelUnavailable(text)
+  if (mu != null) {
+    if (mu.kind === 'quota_exhausted') return { kind: 'quota_wall', source: 'anthropic' }
+    if (mu.kind === 'network') return { kind: 'transient', source: 'network' }
+    // mu.kind === 'overload' | 'rate_limited' — split 529 overload from a 429.
+    if (
+      lower.includes('529') ||
+      lower.includes('overloaded')
+    ) {
+      return { kind: 'overload_529', source: 'anthropic' }
+    }
+    // A 429-family transient. Three-way classify picks the source nuance; all
+    // land on the calm rate_limit kind here.
+    const c = classify429Detail(text)
+    return {
+      kind: 'rate_limit',
+      source: c === 'litellm-local' ? 'litellm-local' : 'anthropic',
+    }
+  }
+
+  // 4. Credit balance is a quota-family wall (actionable).
+  if (claudeKind === 'credit-exhausted') {
+    return { kind: 'quota_wall', source: 'anthropic' }
+  }
+
+  // 5. Bare rate-limit classification from the operator taxonomy.
+  if (claudeKind === 'rate-limited') {
+    return { kind: 'rate_limit', source: 'anthropic' }
+  }
+  if (claudeKind === 'unknown-5xx') {
+    return { kind: 'overload_529', source: 'anthropic' }
+  }
+
+  return { kind: 'unknown', source: 'anthropic' }
+}
+
+function buildCoreText(kind: LlmErrorKind, source: LlmErrorSource): string {
+  switch (kind) {
+    case 'rate_limit':
+      return source === 'litellm-local'
+        ? 'Hit the local proxy rate limit — retrying automatically.'
+        : 'Rate limited by Anthropic — retrying automatically.'
+    case 'overload_529':
+      return 'Anthropic is overloaded (529) — retrying automatically.'
+    case 'quota_wall':
+      return 'Usage limit reached on this Claude subscription.'
+    case 'auth':
+      return 'Claude login needs re-authentication.'
+    case 'transient':
+      return source === 'network'
+        ? "Couldn't reach Anthropic (network) — retrying automatically."
+        : 'A temporary upstream hiccup — retrying automatically.'
+    case 'unknown':
+      return 'The model returned an error.'
+  }
+}
+
+// ─── Rendering ───────────────────────────────────────────────────────────────
+
+export interface RenderedLlmError {
+  text: string
+  keyboard?: InlineKeyboardMarkup
+}
+
+/**
+ * Format a reset instant in the operator's local tz plus a relative tail, e.g.
+ * `clears ~4:52pm AEST (~in 38m)`. Returns '' when there is no reset to show.
+ */
+export function formatResetLocal(resetAt: Date | undefined, tz: string, now: Date = new Date()): string {
+  if (resetAt == null) return ''
+  const ms = resetAt.getTime()
+  if (!Number.isFinite(ms)) return ''
+  const clock = fmtLocalClock(ms, tz)
+  const abbrev = tzAbbrev(ms, tz)
+  const rel = formatRelativeTail(ms - now.getTime())
+  return rel ? `clears ~${clock} ${abbrev} (${rel})` : `clears ~${clock} ${abbrev}`
+}
+
+function formatRelativeTail(deltaMs: number): string {
+  if (deltaMs <= 0) return '~now'
+  const totalMin = Math.round(deltaMs / 60_000)
+  if (totalMin < 1) return '~in <1m'
+  if (totalMin < 60) return `~in ${totalMin}m`
+  const hours = Math.floor(totalMin / 60)
+  const mins = totalMin % 60
+  if (hours < 24) return mins > 0 ? `~in ${hours}h ${mins}m` : `~in ${hours}h`
+  const days = Math.floor(hours / 24)
+  const remH = hours % 24
+  return remH > 0 ? `~in ${days}d ${remH}h` : `~in ${days}d`
+}
+
+/**
+ * Render ONE clean card for a parsed LLM error. Action buttons for the
+ * actionable kinds (auth → Reauth, quota_wall → Wait/switch). `agent` is used
+ * in the callback_data (URL-encoded) and the headline; `tz` localizes the reset.
+ */
+export function renderLlmError(
+  parsed: ParsedLlmError,
+  agent: string,
+  tz: string,
+  now: Date = new Date(),
+): RenderedLlmError {
+  const safeAgent = escapeAgent(agent)
+  const emoji = kindEmoji(parsed.kind)
+  const lines: string[] = [`${emoji} ${parsed.coreText} (**${safeAgent}**)`]
+
+  const resetLine = formatResetLocal(parsed.resetAt, tz, now)
+  if (resetLine) lines.push(`_${resetLine}_`)
+
+  if (parsed.model) lines.push(`_model: ${escapeAgent(parsed.model)}_`)
+
+  const text = lines.join('\n')
+
+  switch (parsed.kind) {
+    case 'auth':
+      return {
+        text,
+        keyboard: {
+          inline_keyboard: [
+            [
+              { text: '🔐 Reauth now', callback_data: `op:reauth:${encodeURIComponent(agent)}` },
+              { text: '❌ Dismiss', callback_data: `op:dismiss:${encodeURIComponent(agent)}` },
+            ],
+          ],
+        },
+      }
+    case 'quota_wall':
+      return {
+        text,
+        keyboard: {
+          inline_keyboard: [
+            [{ text: '⏳ Wait', callback_data: `op:dismiss:${encodeURIComponent(agent)}` }],
+          ],
+        },
+      }
+    default:
+      return { text }
+  }
+}
+
+function kindEmoji(kind: LlmErrorKind): string {
+  switch (kind) {
+    case 'rate_limit':
+      return '🚦'
+    case 'overload_529':
+      return '🔥'
+    case 'quota_wall':
+      return '⚠️'
+    case 'auth':
+      return '🔑'
+    case 'transient':
+      return '🌐'
+    case 'unknown':
+      return '⚠️'
+  }
+}
+
+/** Minimal markdown-safe agent rendering (mirrors operator-events escapeMarkdown intent). */
+function escapeAgent(s: string): string {
+  return s.replace(/([_*`\[\]])/g, '\\$1')
+}
+
+// ─── Cross-surface dedup: ErrorPresenceGate ──────────────────────────────────
+
+/**
+ * How long ONE terminal error owns the "already surfaced" claim across all
+ * three surfaces. Distinct from — and additional to — the 5-minute per-kind
+ * `shouldEmitOperatorEvent` cooldown (operator-events.ts): that debounces an
+ * error STORM on one surface; this collapses ONE error's FAN-OUT across
+ * surfaces within a single turn.
+ */
+export const ERROR_COLLAPSE_WINDOW_MS = 60_000
+
+/**
+ * A tiny in-memory dedup ledger. The FIRST surface to `claim(key)` within the
+ * collapse window wins (returns true) and renders; every later surface loses
+ * (returns false) and suppresses. Key preference: the Anthropic `request_id`
+ * when present (exact), else a `${kind}:${agent}:${windowBucket}` coarse key so
+ * two distinct-but-unlabelled errors of the same kind within 60s still collapse.
+ */
+export class ErrorPresenceGate {
+  private readonly claims = new Map<string, number>()
+
+  /** Build the dedup key for a parsed error + agent. */
+  keyFor(parsed: Pick<ParsedLlmError, 'kind' | 'requestId'>, agent: string, now: number): string {
+    if (parsed.requestId) return `rid:${parsed.requestId}`
+    const bucket = Math.floor(now / ERROR_COLLAPSE_WINDOW_MS)
+    return `${parsed.kind}:${agent}:${bucket}`
+  }
+
+  /**
+   * Attempt to claim ownership of `key`. Returns true for the first caller
+   * within the window, false for every subsequent caller. Expired claims are
+   * pruned lazily on each call.
+   */
+  claim(key: string, now: number = Date.now()): boolean {
+    this.prune(now)
+    const existing = this.claims.get(key)
+    if (existing != null && now - existing < ERROR_COLLAPSE_WINDOW_MS) {
+      return false
+    }
+    this.claims.set(key, now)
+    return true
+  }
+
+  /** True when `key` is currently claimed (does NOT claim). */
+  isClaimed(key: string, now: number = Date.now()): boolean {
+    const existing = this.claims.get(key)
+    return existing != null && now - existing < ERROR_COLLAPSE_WINDOW_MS
+  }
+
+  private prune(now: number): void {
+    for (const [k, at] of this.claims) {
+      if (now - at >= ERROR_COLLAPSE_WINDOW_MS) this.claims.delete(k)
+    }
+  }
+
+  /** Test-only: forget every claim. */
+  reset(): void {
+    this.claims.clear()
+  }
+}
+
+/** The process-wide gate the three surfaces consult. */
+export const errorPresenceGate = new ErrorPresenceGate()
+
+/**
+ * The single decision a surface makes before rendering a parsed LLM error.
+ * Returns:
+ *   - 'render'   — this surface owns the humanized card, render it.
+ *   - 'suppress' — another surface already owns it (dedup) OR it is a
+ *     transient error the harness is still auto-retrying — stay silent.
+ *
+ * ACTIONABLE kinds (auth / quota_wall) ALWAYS return 'render' — they are never
+ * deduped away and never silenced mid-retry, because the operator must always
+ * see (and be able to act on) a login/quota wall.
+ */
+export function decideErrorSurface(
+  parsed: ParsedLlmError,
+  agent: string,
+  opts: { claim: boolean; now?: number; gate?: ErrorPresenceGate } = { claim: true },
+): 'render' | 'suppress' {
+  const now = opts.now ?? Date.now()
+  const gate = opts.gate ?? errorPresenceGate
+
+  if (isActionableKind(parsed.kind)) {
+    // Always render — but still record the claim so a redundant transient
+    // surface for the same key stays collapsed.
+    if (opts.claim) gate.claim(gate.keyFor(parsed, agent, now), now)
+    return 'render'
+  }
+
+  // Auto-retry silence: a transient error still being retried internally is
+  // NOT surfaced on ANY surface until it goes terminal. NOTE: in the current
+  // production wiring the operator surface reaches here only AFTER session-tail
+  // (readNew → `errEvent.terminal || !errEvent.transient`) has already dropped
+  // in-flight transients, and the gateway calls `parseLlmError(detail)` with no
+  // retryState (the raw retry annotations don't survive the IPC hop) — so a
+  // production `parsed.autoRetrying` is always false here. This branch is the
+  // module's own guarantee for ANY caller that DOES pass retryState (unit-tested
+  // as such); prod silence is owned upstream at session-tail, not re-derived here.
+  if (parsed.autoRetrying && !parsed.terminal) return 'suppress'
+
+  const key = gate.keyFor(parsed, agent, now)
+  if (opts.claim) {
+    return gate.claim(key, now) ? 'render' : 'suppress'
+  }
+  return gate.isClaimed(key, now) ? 'suppress' : 'render'
+}

package/telegram-plugin/operator-events.ts

@@ -13,6 +13,7 @@
  */
 
 import { escapeMarkdown } from './format.js'
+import { stripRawErrorBytes } from './raw-error-scrub.js'
 
 // ─── Taxonomy ────────────────────────────────────────────────────────────────
 
@@ -216,7 +217,12 @@ export interface RenderResult {
  */
 export function renderOperatorEvent(ev: OperatorEvent): RenderResult {
   const agent = escapeMarkdown(ev.agent)
-  const detail = escapeMarkdown(ev.detail)
+  // #llm-error-surfacing: NEVER let a raw API-error byte-blob (`· b'{…}'`,
+  // trailing `{"type":"error"…}` JSON, `API Error:` prefix) reach a user. A
+  // clean human detail passes through unchanged; only smuggled raw bytes are
+  // stripped. This is the belt-and-braces scrub for every card kind — the
+  // rate-limited card in particular used to relay the raw synthetic-error text.
+  const detail = escapeMarkdown(stripRawErrorBytes(ev.detail))
 
   switch (ev.kind) {
     case 'credentials-expired':

package/telegram-plugin/permission-title.ts

@@ -20,7 +20,7 @@
 import { basename } from "node:path";
 import { escapeMarkdown } from "./card-format.js";
 import { prettyMcpServer, type ScopeOption } from "./permission-rule.js";
-import { redact } from "./secret-detect/redact.js";
+import { redact, REDACTED_MARKER } from "./secret-detect/redact.js";
 
 const COMMAND_TITLE_MAX = 48;
 const DESCRIPTION_LINE_MAX = 240;
@@ -35,6 +35,55 @@ const ARG_SUMMARY_MAX_KEYS = 4; // how many payload keys to surface on the card
 const ARG_VALUE_MAX = 40; // per-value truncation in the arg-summary line
 const ARG_SUMMARY_LINE_MAX = 180; // total cap for the arg-summary line
 
+/**
+ * Input keys that are routing / formatting / id noise, never operator-
+ * meaningful context. Stripped when synthesizing the fallback `context:`
+ * line (#3167) so it surfaces the substance (the reply text, the command,
+ * the query) and not `chat_id` / `format` / `disable_notification` chrome.
+ * `reason`/`why` are here too because their presence takes the `why:` path —
+ * they never reach the synthesizer.
+ */
+const CONTEXT_NOISE_KEYS = new Set([
+  "reason",
+  "why",
+  "chat_id",
+  "message_id",
+  "message_thread_id",
+  "thread_id",
+  "origin_turn_id",
+  "reply_to",
+  "quote",
+  "quote_text",
+  "format",
+  "parse_mode",
+  "disable_web_page_preview",
+  "disable_notification",
+  "protect_content",
+  "single_use",
+  "ack_text",
+  "inline_keyboard",
+  "file_id",
+]);
+
+/**
+ * Input keys whose VALUE is credential-shaped by name — hard-masked whole,
+ * never partially revealed (#3167 review). The token-shape detectors in
+ * `redact()` need a random-looking value to fire, so a low-entropy password
+ * or a short secret under one of these keys would otherwise slip through the
+ * synthesized `context:` line. Matching the key is the reliable signal.
+ */
+const SENSITIVE_VALUE_KEY_RE =
+  /token|secret|password|passwd|key|auth|dsn|conn|url|credential|cookie|session/i;
+
+/**
+ * Credential-bearing DSN schemes that `redactUrls()` (inside `redact()`) does
+ * NOT cover — it only handles http(s)/ws(s)/ftp. A `postgres://user:pass@host`
+ * DATABASE_URL is a real vault-key shape here, so mask the whole DSN when its
+ * authority carries a `user:pass@` credential (#3167 review).
+ */
+const NON_HTTP_DSN_RE =
+  /\b(?:postgres(?:ql)?|mysql|mariadb|redis|rediss|mongodb(?:\+srv)?|amqp|amqps):\/\/\S*@\S+/gi;
+
 /**
  * Human verb-phrases for switchroom-managed MCP tools. The raw
  * `mcp__<server>__<tool>` name is operator-hostile. Phrases are written
@@ -141,15 +190,23 @@ export function formatPermissionCardBody(opts: {
   // static schema description (#2469).
   const callerReason = callerSuppliedReason(opts.inputPreview);
   const rawWhy = (callerReason ?? "").replace(/\s+/g, " ").trim();
-  const truncatedWhy =
-    rawWhy.length > DESCRIPTION_LINE_MAX
-      ? rawWhy.slice(0, DESCRIPTION_LINE_MAX - 1) + "…"
-      : rawWhy;
-  lines.push(
-    truncatedWhy.length > 0
-      ? `why: _${escapeTgHtml(truncatedWhy)}_`
-      : `why: _not provided_`,
-  );
+  if (rawWhy.length > 0) {
+    const truncatedWhy =
+      rawWhy.length > DESCRIPTION_LINE_MAX
+        ? rawWhy.slice(0, DESCRIPTION_LINE_MAX - 1) + "…"
+        : rawWhy;
+    lines.push(`why: _${escapeTgHtml(truncatedWhy)}_`);
+  } else {
+    // No caller reason. Many tools (reply, react, edit_message, …) carry no
+    // `reason`/`why` argument at all, so a bare "why: not provided" gives the
+    // operator nothing to decide on — the post-rollout permission storm filled
+    // the chat with contentless cards (#3167). Fall back to an honest,
+    // redaction-safe `context:` line synthesized from the tool + its salient
+    // input, so the card always carries something meaningful. The distinct
+    // label keeps the agent's omission of a rationale visible (it is NOT a
+    // fabricated "why"), while still surfacing what the tool is about to do.
+    lines.push(`context: _${escapeTgHtml(synthesizeContext(opts.toolName, opts.inputPreview))}_`);
+  }
 
   // Third line (REST-wrapper MCP writes only): a redaction-safe summary of
   // the payload so the operator can see WHAT is being sent, not just the
@@ -597,6 +654,111 @@ function callerSuppliedReason(inputPreview: string | undefined): string | null {
   return null;
 }
 
+/**
+ * Honest, redaction-safe fallback for the card's rationale line when the
+ * caller supplied no `reason`/`why` (#3167). Synthesizes context from a
+ * summary of the tool's salient input fields — the reply text, the command,
+ * the search query — so the operator always has something to decide on
+ * instead of a contentless "not provided". Every value passes through
+ * `redact()`; ids / routing / formatting keys are stripped. Falls back to
+ * the natural action phrase when the input exposes nothing salient.
+ * Deterministic (no model in the loop): same input → same line. Exported
+ * for unit testing.
+ */
+export function synthesizeContext(
+  toolName: string,
+  inputPreview: string | undefined,
+): string {
+  const input = parseInput(inputPreview);
+  const summary = input ? salientInputSummary(input) : null;
+  // Prefer the salient input summary (the reply text, the query, the diff
+  // target) — the substance the title's verb-phrase does NOT already carry.
+  // When the input exposes nothing meaningful, fall back to the natural
+  // action so the line still names the tool rather than reading empty.
+  const base = summary ?? naturalAction(toolName, inputPreview);
+  // Acceptance criteria (#3167) call for "tool + summarized input +
+  // originating turn". When the call carries a forum-topic origin turn,
+  // append a compact reference so the operator can tie the card to the turn
+  // that spawned it. Kept short — it's a routing id, not prose.
+  const turnRef = input ? readString(input, "origin_turn_id") : null;
+  return turnRef ? `${base} · turn ${shortTurnRef(turnRef)}` : base;
+}
+
+/** Compact display form of an origin-turn id — the tail is the distinguishing
+ *  part; a full opaque id would swamp the line. */
+function shortTurnRef(turnId: string): string {
+  const t = turnId.trim();
+  return t.length <= 10 ? t : `…${t.slice(-8)}`;
+}
+
+/**
+ * A compact, redaction-safe summary of the operator-meaningful scalar fields
+ * of a tool input — used to build the synthesized `context:` line (#3167).
+ * Skips {@link CONTEXT_NOISE_KEYS} (ids/routing/formatting), surfaces up to
+ * {@link ARG_SUMMARY_MAX_KEYS} scalar `key: value` pairs (each redacted +
+ * truncated), and renders nested objects/arrays as the bare key name (no
+ * value dump — avoids leaking PII/secrets and oversized blobs). Returns null
+ * when nothing meaningful remains, so the caller falls back to the bare
+ * action phrase.
+ *
+ * Free-text fields (e.g. a reply `text`) surface as content — a conscious
+ * choice (#3167 review, LOW-1): the operator NEEDS to see *what* is being
+ * sent to judge the card. Exposure is bounded to {@link ARG_VALUE_MAX} chars
+ * and every value is redaction-passed via {@link redactSalientValue}, so a
+ * card can never leak more than the outbound reply already does in history
+ * (both use the same `redact()` chokepoint). We do not mask free text to a
+ * placeholder, which would gut the card's usefulness.
+ */
+function salientInputSummary(input: Record<string, unknown>): string | null {
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(input)) {
+    if (CONTEXT_NOISE_KEYS.has(key)) continue;
+    if (value == null) continue;
+    if (parts.length >= ARG_SUMMARY_MAX_KEYS) {
+      parts.push("…");
+      break;
+    }
+    if (typeof value === "object") {
+      parts.push(key); // nested object/array → key name only, never dumped
+      continue;
+    }
+    const shown = truncate(redactSalientValue(key, String(value)), ARG_VALUE_MAX);
+    if (shown.length === 0) continue;
+    parts.push(`${key}: ${shown}`);
+  }
+  if (parts.length === 0) return null;
+  const joined = parts.join(", ");
+  return joined.length > ARG_SUMMARY_LINE_MAX
+    ? joined.slice(0, ARG_SUMMARY_LINE_MAX - 1) + "…"
+    : joined;
+}
+
+/**
+ * Redact a single salient value for display on the synthesized `context:`
+ * line, given its input KEY (#3167 review). Three layers, defense-in-depth:
+ *
+ *   1. Hard-mask whole when the key is credential-shaped
+ *      ({@link SENSITIVE_VALUE_KEY_RE}) — the token-shape detectors need a
+ *      random-looking value, so a low-entropy password / short secret under a
+ *      `token`/`password`/`api_key` key would otherwise leak. The key name is
+ *      the reliable signal.
+ *   2. Mask non-http DSN credentials ({@link NON_HTTP_DSN_RE}) that
+ *      `redactUrls()` misses (postgres://user:pass@host, mysql://, redis://…).
+ *   3. Run `redact()` WITH the key restored as `key=value` context, so the
+ *      contextual detectors (`kv_entropy` / `env_key_value`) that require the
+ *      `key[:=]value` shape in one string can fire — then strip the synthetic
+ *      `key=` prefix. Redacting the BARE value (the pre-review bug) blinded
+ *      those detectors, since `redact()` deliberately excludes the
+ *      low-precision `generic_high_entropy` fallback.
+ */
+function redactSalientValue(key: string, value: string): string {
+  if (SENSITIVE_VALUE_KEY_RE.test(key)) return REDACTED_MARKER;
+  const dsnScrubbed = value.replace(NON_HTTP_DSN_RE, REDACTED_MARKER);
+  const scrubbed = redact(`${key}=${dsnScrubbed}`);
+  const prefix = `${key}=`;
+  return scrubbed.startsWith(prefix) ? scrubbed.slice(prefix.length) : scrubbed;
+}
+
 /**
  * Regex-based fallback to extract a `reason` or `why` value from a raw
  * (possibly truncated / invalid-JSON) inputPreview string. Mirrors