switchroom 0.18.15 → 0.18.18

package/telegram-plugin/send-gate.ts

@@ -118,6 +118,32 @@ export type PriorityClass = 'critical' | 'useful' | 'cosmetic'
  */
 export const UNTAGGED_SEND_CLASS: PriorityClass = 'critical'
 
+/**
+ * Distinguishable resolution value for a SHED call (#3110 review F1).
+ *
+ * `undefined` was overloaded three ways at the robustApiCall seam: a gate
+ * SHED (cosmetic call dropped under pressure — did NOT land), a gate no-op
+ * drop (identical payload already on screen — benign), and the retry
+ * policy's swallowed benign 400s ("message is not modified" — also benign).
+ * A caller that needs to know "did my edit land?" (the draft stream's
+ * shed-honesty handling in stream-controller.ts) could not tell these
+ * apart, and treating every `undefined` as a shed froze multi-piece
+ * streams on perfectly healthy chats.
+ *
+ * A shed now resolves THIS sentinel instead. `Symbol.for` keys it in the
+ * global symbol registry so duplicated module instances (server + gateway
+ * builds) agree on identity. The no-op drop and coalesced-revert drop keep
+ * resolving `undefined` — for those the payload IS on screen. Callers that
+ * ignore the result (reactions, typing, fire-and-forget card edits) are
+ * unaffected either way.
+ */
+export const SEND_GATE_SHED: unique symbol = Symbol.for('switchroom.send-gate.shed')
+
+/** True when a gate result is the {@link SEND_GATE_SHED} sentinel. */
+export function isSendGateShed(value: unknown): value is typeof SEND_GATE_SHED {
+  return value === SEND_GATE_SHED
+}
+
 /**
  * Extra metadata a call site can attach so the gate can key the right buckets.
  * All fields optional — a call with none still passes the global bucket. These
@@ -159,8 +185,9 @@ export interface BucketCounters {
   dropped: number
   /**
    * Cosmetic calls shed under pressure — no token free OR a flood window open
-   * (part3-design §2). A shed resolves as `undefined`; the next send carries
-   * full state.
+   * (part3-design §2). A shed resolves the SEND_GATE_SHED sentinel (F1 —
+   * distinguishable from a benign no-op drop's `undefined`); the next send
+   * carries full state.
    */
   shed: number
   /** Useful calls dropped because they exceeded their queue TTL (part3-design §2). */
@@ -277,6 +304,21 @@ export interface SendGateConfig {
    * `initialWindows` applied at construction (those already came from disk).
    */
   onWindowOpen?: (scopeKey: string, untilTs: number) => void
+  /**
+   * Conservative flood-scope posture (#3111). When `false` (the DEFAULT), a 429
+   * on a call bound to a specific chat opens ONLY that chat's (and, for groups,
+   * that group's) flood window — NOT a blanket `global` window — so a genuinely
+   * chat-scoped 429 (e.g. a per-group 20/min limit) cannot fail-fast CRITICAL
+   * sends to every other chat. `global` is opened only when the 429 carries no
+   * finer scope (no `chat_id`), i.e. the evidence is genuinely global.
+   *
+   * When `true`, the pre-#3111 posture is restored: EVERY 429 additionally opens
+   * the `global` window. Telegram 429s are per-bot-token, so a flood often IS
+   * global; an operator who prefers to over-suppress rather than risk a missed
+   * global ban can opt back in via
+   * `SWITCHROOM_TG_SEND_GATE_CONSERVATIVE_GLOBAL=1`.
+   */
+  conservativeGlobalFloodScope?: boolean
 }
 
 /**
@@ -435,22 +477,58 @@ export interface SendGate {
    * by PR 2 on a 429 and at boot from the persisted `flood-wait.json`.
    */
   openFloodWindow(scopeKey: string, untilTs: number): void
+  /**
+   * Open the SCOPE-PRECISE flood windows a 429 on a call with these `opts`
+   * implies (#3111). Used by the gateway's `onFloodWait` hook, which sees a
+   * SHORT slept-and-retried 429 the gate's own `FLOOD_WAIT_ACTIVE` catch never
+   * observes. Opens `global` only when `opts` carries no `chat_id` (genuinely
+   * global evidence) or the conservative posture is on — so a chat-scoped 429
+   * does not suppress unrelated chats. A pure no-op when the gate is disabled.
+   */
+  openScopedFloodWindows(opts: SendGateOpts | undefined, untilTs: number): void
   /** Snapshot of counters + current bucket fill. */
   stats(): SendGateStats
 }
 
 const GROUP_TYPES = new Set<ChatType>(['group', 'supergroup'])
 
+/**
+ * Compile-time default rate limits for the send gate's token buckets and edit
+ * floor — the values `createSendGate` falls back to when a field is omitted.
+ *
+ * Exposed so the config plumbing (`channels.telegram.send_gate.*` →
+ * `SWITCHROOM_TG_SEND_GATE_*` env → `sendGateConfigFromEnv`) defaults to the
+ * SAME numbers, and so a test can PIN them: a future accidental change to any
+ * default fails that pin. Changing a value here is a real behaviour change for
+ * every install — do it deliberately, never as a drive-by edit.
+ */
+export const SEND_GATE_DEFAULTS = {
+  /** Global bucket sustained rate (tokens/sec). */
+  globalPerSec: 25,
+  /** Global burst capacity (headroom under Telegram's ~30/s). */
+  globalBurst: 4,
+  /** Per-chat sustained rate (tokens/sec). */
+  perChatPerSec: 1,
+  /** Per-chat burst capacity. */
+  perChatBurst: 3,
+  /** Per-group sustained rate (tokens/min). */
+  perGroupPerMin: 18,
+  /** Per-group burst capacity (headroom under 20/min). */
+  perGroupBurst: 2,
+  /** Minimum ms between edits of the same message_id. */
+  editFloorMs: 1500,
+} as const
+
 export function createSendGate(config: SendGateConfig): SendGate {
   const enabled = config.enabled
   const clock = config.clock ?? systemClock
-  const globalPerSec = config.globalPerSec ?? 25
-  const globalBurst = config.globalBurst ?? 4
-  const perChatPerSec = config.perChatPerSec ?? 1
-  const perChatBurst = config.perChatBurst ?? 3
-  const perGroupPerMin = config.perGroupPerMin ?? 18
-  const perGroupBurst = config.perGroupBurst ?? 2
-  const editFloorMs = config.editFloorMs ?? 1500
+  const globalPerSec = config.globalPerSec ?? SEND_GATE_DEFAULTS.globalPerSec
+  const globalBurst = config.globalBurst ?? SEND_GATE_DEFAULTS.globalBurst
+  const perChatPerSec = config.perChatPerSec ?? SEND_GATE_DEFAULTS.perChatPerSec
+  const perChatBurst = config.perChatBurst ?? SEND_GATE_DEFAULTS.perChatBurst
+  const perGroupPerMin = config.perGroupPerMin ?? SEND_GATE_DEFAULTS.perGroupPerMin
+  const perGroupBurst = config.perGroupBurst ?? SEND_GATE_DEFAULTS.perGroupBurst
+  const editFloorMs = config.editFloorMs ?? SEND_GATE_DEFAULTS.editFloorMs
   const messageStateTtlMs = config.messageStateTtlMs ?? 60_000
   const maxMessageStates = config.maxMessageStates ?? 5_000
   const usefulTtlMs = config.usefulTtlMs ?? 120_000
@@ -458,6 +536,7 @@ export function createSendGate(config: SendGateConfig): SendGate {
   const criticalJitterMaxMs = config.criticalJitterMaxMs ?? 250
   const jitter = config.jitter ?? Math.random
   const onWindowOpen = config.onWindowOpen
+  const conservativeGlobalFloodScope = config.conservativeGlobalFloodScope ?? false
 
   const counters: BucketCounters = {
     sent: 0,
@@ -570,18 +649,35 @@ export function createSendGate(config: SendGateConfig): SendGate {
   }
 
   /**
-   * Open all scope windows implied by a call's `opts` at `untilTs` — global,
-   * plus per-chat / per-group / per-message where keyed. Called when a wrapped
-   * send surfaces a `FLOOD_WAIT_ACTIVE` (a real 429 or a pre-call
-   * short-circuit) so the ban is remembered at the finest scope we know
-   * (part3-design §7). Global is always opened as the conservative floor.
+   * Open the flood windows a 429 on this call implies at `untilTs`, at the
+   * FINEST scope the evidence supports (#3111). Called when a wrapped send
+   * surfaces a `FLOOD_WAIT_ACTIVE` (a real 429 or a pre-call short-circuit), and
+   * by the gateway's `onFloodWait` hook for a SHORT slept-and-retried 429 (via
+   * the public `openScopedFloodWindows`), so the ban is remembered at the finest
+   * scope we know (part3-design §7).
+   *
+   * SCOPE PRECISION (#3111): a call bound to a specific `chat_id` opens ONLY that
+   * chat's (and, for groups, that group's) window — NOT a blanket `global`
+   * window that would suppress unrelated chats. `global` is opened only when the
+   * call carries NO finer scope (no `chat_id`) — i.e. the evidence is genuinely
+   * global — OR when `conservativeGlobalFloodScope` restores the pre-#3111
+   * always-open-global posture. Telegram 429s are per-bot-token so a flood is
+   * OFTEN global, but a genuinely chat-scoped 429 (e.g. a per-group 20/min
+   * limit) must not fail-fast CRITICAL sends to every other chat. The
+   * per-message (`msg-edit:`) window is additive whenever a `messageId` is
+   * present. Monotonic/idempotent: `applyWindow` only ever extends.
    */
   function openScopedWindowsForOpts(opts: SendGateOpts | undefined, untilTs: number): void {
-    applyWindow('global', untilTs, true)
-    if (opts?.chat_id) {
-      applyWindow(`chat:${opts.chat_id}`, untilTs, true)
-      if (opts.chatType && GROUP_TYPES.has(opts.chatType)) {
-        applyWindow(`group:${opts.chat_id}`, untilTs, true)
+    const hasChatScope = opts?.chat_id != null && opts.chat_id !== ''
+    // Open `global` only when the 429 has no finer scope (genuinely global), or
+    // when the operator opted into the conservative always-global posture.
+    if (!hasChatScope || conservativeGlobalFloodScope) {
+      applyWindow('global', untilTs, true)
+    }
+    if (hasChatScope) {
+      applyWindow(`chat:${opts!.chat_id}`, untilTs, true)
+      if (opts!.chatType && GROUP_TYPES.has(opts!.chatType)) {
+        applyWindow(`group:${opts!.chat_id}`, untilTs, true)
       }
     }
     if (opts?.messageId != null) {
@@ -913,7 +1009,9 @@ export function createSendGate(config: SendGateConfig): SendGate {
       const msgWait = state.suppressedUntilMs > now ? state.suppressedUntilMs - now : 0
       if (wait > 0 || msgWait > 0) {
         counters.shed++
-        return Promise.resolve(undefined as unknown as T)
+        // Distinguishable from the no-op drop below (undefined): a shed did
+        // NOT land, and edit-driving callers must be able to tell (F1).
+        return Promise.resolve(SEND_GATE_SHED as unknown as T)
       }
     }
 
@@ -991,7 +1089,8 @@ export function createSendGate(config: SendGateConfig): SendGate {
     const outcome = await admitPriority(bucketsFor(opts), priority)
     if (outcome.result === 'shed') {
       counters.shed++
-      return undefined as unknown as T
+      // See SEND_GATE_SHED: distinguishable "did not land" resolution (F1).
+      return SEND_GATE_SHED as unknown as T
     }
     if (outcome.result === 'expired') {
       counters.expired++
@@ -1037,7 +1136,18 @@ export function createSendGate(config: SendGateConfig): SendGate {
     }
   }
 
-  return { gate, openFloodWindow, stats }
+  /**
+   * Public, scope-precise window opener for the gateway's `onFloodWait` hook
+   * (#3111). Flag-OFF is a pure no-op (mirrors `openFloodWindow`'s M3 guard) so
+   * a 429 never mutates suppression or writes `flood-windows.json` while the gate
+   * is disabled.
+   */
+  function openScopedFloodWindows(opts: SendGateOpts | undefined, untilTs: number): void {
+    if (!enabled) return
+    openScopedWindowsForOpts(opts, untilTs)
+  }
+
+  return { gate, openFloodWindow, openScopedFloodWindows, stats }
 }
 
 /**
@@ -1051,6 +1161,119 @@ export function createSendGate(config: SendGateConfig): SendGate {
 export function sendGateEnabledFromEnv(env: NodeJS.ProcessEnv = process.env): boolean {
   const v = env.SWITCHROOM_TELEGRAM_SEND_GATE
   if (v == null) return true
+  return !isOffValue(v)
+}
+
+/** Shared parse for the default-on kill-switch grammar: `0/false/off/no`. */
+function isOffValue(v: string): boolean {
   const t = v.trim().toLowerCase()
-  return !(t === '0' || t === 'false' || t === 'off' || t === 'no')
+  return t === '0' || t === 'false' || t === 'off' || t === 'no'
+}
+
+/** Parse a strictly-positive finite number env var; blank/NaN/≤0 → undefined. */
+function parsePositiveNumber(raw: string | undefined): number | undefined {
+  if (raw == null || raw.trim() === '') return undefined
+  const n = Number(raw)
+  return Number.isFinite(n) && n > 0 ? n : undefined
+}
+
+/** Parse a positive integer env var; blank/NaN/non-int/≤0 → undefined. */
+function parsePositiveInt(raw: string | undefined): number | undefined {
+  if (raw == null || raw.trim() === '') return undefined
+  const n = Number(raw)
+  return Number.isInteger(n) && n > 0 ? n : undefined
+}
+
+/** Parse a non-negative integer env var; blank/NaN/non-int/<0 → undefined. */
+function parseNonNegativeInt(raw: string | undefined): number | undefined {
+  if (raw == null || raw.trim() === '') return undefined
+  const n = Number(raw)
+  return Number.isInteger(n) && n >= 0 ? n : undefined
+}
+
+/**
+ * Parse a boolean env flag using the repo's on/off grammar
+ * (`1/true/on/yes` → true, `0/false/off/no` → false). Blank or unrecognised →
+ * undefined so the caller keeps its built-in default (#3111).
+ */
+function parseBoolFlag(raw: string | undefined): boolean | undefined {
+  if (raw == null || raw.trim() === '') return undefined
+  const t = raw.trim().toLowerCase()
+  if (t === '1' || t === 'true' || t === 'on' || t === 'yes') return true
+  if (isOffValue(t)) return false
+  return undefined
+}
+
+/**
+ * The resolved rate-limit + enable slice `createSendGate` consumes, sourced
+ * from env (which the scaffold populates from `channels.telegram.send_gate.*`).
+ * Only fields the operator SET are present; an unset rate field is absent so
+ * `createSendGate` applies its `SEND_GATE_DEFAULTS` fallback (unset ⇒ today's
+ * exact behaviour).
+ */
+export type SendGateEnvConfig = Pick<SendGateConfig, 'enabled'> &
+  Partial<
+    Pick<
+      SendGateConfig,
+      | 'globalPerSec'
+      | 'globalBurst'
+      | 'perChatPerSec'
+      | 'perChatBurst'
+      | 'perGroupPerMin'
+      | 'perGroupBurst'
+      | 'editFloorMs'
+      | 'conservativeGlobalFloodScope'
+    >
+  >
+
+/**
+ * Resolve the send gate's `enabled` flag + tunable rate limits from env.
+ *
+ * ENABLED PRECEDENCE (least-surprising, documented):
+ *   1. `SWITCHROOM_TELEGRAM_SEND_GATE` — the operator break-glass valve. When
+ *      EXPLICITLY set it ALWAYS wins (unchanged kill-switch semantics), on or
+ *      off, regardless of config. An operator disabling the gate in an incident
+ *      must not be overridden by YAML.
+ *   2. `SWITCHROOM_TG_SEND_GATE_ENABLED` — from `channels.telegram.send_gate.
+ *      enabled`. Decides only when the valve above is unset.
+ *   3. Both unset ⇒ `true` (the gate is ON by default, unchanged).
+ *
+ * The rate knobs come solely from config (there was never an env override for
+ * them). Config values are validated LOUDLY at load by the Zod schema; this
+ * parse is a defensive net — a hand-set malformed env falls back to undefined
+ * so `createSendGate` uses its built-in default rather than wedging sends.
+ */
+export function sendGateConfigFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): SendGateEnvConfig {
+  const killSwitch = env.SWITCHROOM_TELEGRAM_SEND_GATE
+  let enabled: boolean
+  if (killSwitch != null && killSwitch.trim() !== '') {
+    enabled = !isOffValue(killSwitch)
+  } else {
+    const cfg = env.SWITCHROOM_TG_SEND_GATE_ENABLED
+    enabled = cfg != null && cfg.trim() !== '' ? !isOffValue(cfg) : true
+  }
+
+  const out: SendGateEnvConfig = { enabled }
+  const globalPerSec = parsePositiveNumber(env.SWITCHROOM_TG_SEND_GATE_GLOBAL_PER_SEC)
+  if (globalPerSec !== undefined) out.globalPerSec = globalPerSec
+  const globalBurst = parsePositiveInt(env.SWITCHROOM_TG_SEND_GATE_GLOBAL_BURST)
+  if (globalBurst !== undefined) out.globalBurst = globalBurst
+  const perChatPerSec = parsePositiveNumber(env.SWITCHROOM_TG_SEND_GATE_PER_CHAT_PER_SEC)
+  if (perChatPerSec !== undefined) out.perChatPerSec = perChatPerSec
+  const perChatBurst = parsePositiveInt(env.SWITCHROOM_TG_SEND_GATE_PER_CHAT_BURST)
+  if (perChatBurst !== undefined) out.perChatBurst = perChatBurst
+  const perGroupPerMin = parsePositiveNumber(env.SWITCHROOM_TG_SEND_GATE_PER_GROUP_PER_MIN)
+  if (perGroupPerMin !== undefined) out.perGroupPerMin = perGroupPerMin
+  const perGroupBurst = parsePositiveInt(env.SWITCHROOM_TG_SEND_GATE_PER_GROUP_BURST)
+  if (perGroupBurst !== undefined) out.perGroupBurst = perGroupBurst
+  const editFloorMs = parseNonNegativeInt(env.SWITCHROOM_TG_SEND_GATE_EDIT_FLOOR_MS)
+  if (editFloorMs !== undefined) out.editFloorMs = editFloorMs
+  // #3111 break-glass: restore the pre-#3111 always-open-global flood posture.
+  // Unset ⇒ scope-precise default (global opened only on genuinely global 429s).
+  const conservativeGlobal = parseBoolFlag(env.SWITCHROOM_TG_SEND_GATE_CONSERVATIVE_GLOBAL)
+  if (conservativeGlobal !== undefined) out.conservativeGlobalFloodScope = conservativeGlobal
+
+  return out
 }

package/telegram-plugin/session-tail.ts

@@ -333,6 +333,22 @@ export function projectTranscriptLine(line: string): SessionEvent[] {
     const message = obj.message as Record<string, unknown> | undefined
     const content = message?.content as Array<Record<string, unknown>> | undefined
     if (!Array.isArray(content)) return []
+    // #llm-error-surfacing — DETERMINISTIC TERMINAL SOURCE. Claude Code writes a
+    // usage-limit / API error as a SYNTHETIC ASSISTANT MESSAGE
+    // (`isApiErrorMessage: true`) whose `content[].text` is the raw error string
+    // ("You've hit your limit · resets … b'{\"type\":\"error\"…}'"). That text
+    // used to fan out to the reply/answer passthrough AND the turn-end "done"
+    // card as if it were the model's answer. It is NOT an answer — it is an
+    // error the operator-event pipeline (detectErrorInTranscriptLine →
+    // humanized card) owns. Suppress the text/thinking events here at the ONE
+    // authoritative source so neither downstream surface can relay the raw
+    // bytes; the humanized card is rendered independently from the same line.
+    if (obj.isApiErrorMessage === true) {
+      const mainModel = message?.model
+      return typeof mainModel === 'string' && !isModelSentinel(mainModel)
+        ? [{ kind: 'model', model: mainModel }]
+        : []
+    }
     const events: SessionEvent[] = []
     // Live model capture: `message.model` is the exact resolved model that
     // served THIS assistant API call. Emit it FIRST (before the content events)

package/telegram-plugin/shared/local-time.ts

@@ -0,0 +1,69 @@
+/**
+ * shared/local-time.ts — operator-facing local wall-clock formatting.
+ *
+ * These four primitives render an epoch-ms instant in an operator's CONFIGURED
+ * IANA timezone (e.g. `Australia/Melbourne`) instead of UTC, so a card reading
+ * "clears ~4:52pm AEST" is legible at a glance where a raw `…T04:52:00Z UTC`
+ * is not. They were originally file-private in `send-gate-observability.ts`
+ * (#3084 / PR 3205); extracted here so BOTH the flood-window observer and the
+ * humanized LLM-error card (`llm-error-present.ts`) render timestamps through
+ * ONE source of truth rather than two drifting copies.
+ *
+ * Pure — no I/O, no clock, no env. Every function is total (never throws) and
+ * degrades gracefully: an unknown tz falls back to the offset form or the tz
+ * string itself. `tz='UTC'` reproduces the pre-extraction behaviour exactly, so
+ * `send-gate-observability`'s snapshot-locked output is byte-identical.
+ */
+
+/** Lowercased wall-clock time in `tz`, e.g. `9:39am`. */
+export function fmtLocalClock(ms: number, tz: string): string {
+  return new Intl.DateTimeFormat('en-US', {
+    timeZone: tz,
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: true,
+  })
+    .format(new Date(ms))
+    .replace(/\s([AP])M$/, (_m, p: string) => `${p.toLowerCase()}m`)
+}
+
+/** Compact local date, e.g. `12 Jul` — used only to disambiguate day-spanning windows. */
+export function fmtLocalDate(ms: number, tz: string): string {
+  return new Intl.DateTimeFormat('en-GB', {
+    timeZone: tz,
+    day: 'numeric',
+    month: 'short',
+  }).format(new Date(ms))
+}
+
+/** Calendar day (`YYYY-MM-DD`) in `tz`, for a timezone-correct "same day?" test. */
+export function localDay(ms: number, tz: string): string {
+  return new Intl.DateTimeFormat('en-CA', {
+    timeZone: tz,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).format(new Date(ms))
+}
+
+/**
+ * Short tz abbreviation for `tz` at `ms`, e.g. `AEST`, `EDT`, `BST`. ICU only
+ * surfaces the common alpha abbreviation for a locale whose region matches the
+ * zone, so we try a small locale list and take the first genuine abbreviation;
+ * zones with no common abbreviation (e.g. Asia/Kolkata) fall back to the offset
+ * form (`GMT+5:30`), and `UTC` stays `UTC`.
+ */
+export function tzAbbrev(ms: number, tz: string): string {
+  const at = new Date(ms)
+  for (const loc of ['en-US', 'en-AU', 'en-GB']) {
+    const v = new Intl.DateTimeFormat(loc, { timeZone: tz, timeZoneName: 'short' })
+      .formatToParts(at)
+      .find((p) => p.type === 'timeZoneName')?.value
+    if (v && !/^(?:GMT|UTC)/i.test(v)) return v
+  }
+  return (
+    new Intl.DateTimeFormat('en-US', { timeZone: tz, timeZoneName: 'short' })
+      .formatToParts(at)
+      .find((p) => p.type === 'timeZoneName')?.value ?? tz
+  )
+}