switchroom 0.18.13 → 0.18.15

package/telegram-plugin/gateway/throttle-tier-wiring.ts

@@ -0,0 +1,268 @@
+/**
+ * throttle-tier-wiring.ts — side-effect runner for the 429 throttle tier.
+ *
+ * The DECISION and notice text live in ../throttle-tier.ts (pure). This
+ * module owns the sequenced side effects, with every dependency injected so
+ * the wiring is unit-testable without importing gateway.ts:
+ *
+ *   1. Broker `mark-throttled` — records `throttled_until` in the quota
+ *      ledger (no roll, no eligibility change) and runs the broker-side
+ *      escalation guard (3 hits / 10 min → live probe → mark-exhausted when
+ *      corroborated). EVERY fire reaches the broker — the notice cooldown
+ *      below never suppresses the ledger write, because the escalation
+ *      counter is what corroborates a wall hiding behind transient wording.
+ *   2. ONE lightweight operator notice — deduped per account BOTH locally
+ *      (cooldown window) and FLEET-WIDE via the broker's claim-notification
+ *      verb (N agents sharing a throttled account produce one copy per chat,
+ *      not N). Claim failures FAIL OPEN (send anyway) per the claim
+ *      contract.
+ *   3. A delayed retry nudge — after `throttled_until` (+slack +jitter so N
+ *      agents don't restart-and-replay simultaneously into the just-cleared
+ *      account), replay the turn the 429 killed via the existing resume
+ *      lever (triggerSelfRestart → boot-resume). Guards, in order:
+ *        - a LIVE turn that started AFTER the throttle was armed supersedes
+ *          the dead turn — skip entirely (restarting would kill live work
+ *          and boot-resume would replay the WRONG turn);
+ *        - a live turn that started BEFORE the arm is the dead turn itself
+ *          still holding the in-flight gate — defer the restart to the
+ *          turn-complete drain (`pendingRestarts`) instead of SIGTERM-now;
+ *        - otherwise consult the SHARED fleet-fallback resume gate
+ *          (single-flight across throttle AND fallback resumes + staleness)
+ *          and restart on a 'resume' verdict.
+ *
+ * The escalated outcome (broker corroborated a wall and already rolled)
+ * posts its own announcement — gateway-side, per the reactive-path doctrine
+ * (`LastFleetRoll` docstring in src/auth/broker/server.ts), which also
+ * covers PINNED (non-fleet-active) account rolls — then nudges the resume
+ * immediately through the same turn-safety guards.
+ */
+
+import {
+  evaluateThrottleNotice,
+  renderThrottleEscalationNotice,
+  renderThrottleNotice,
+  THROTTLE_NOTICE_COOLDOWN_MS,
+  type ThrottleNoticeState,
+} from '../throttle-tier.js'
+
+/** Slack past throttled_until before the retry nudge fires. */
+export const THROTTLE_RETRY_NUDGE_SLACK_MS = 5_000
+
+/** Max random jitter added to the nudge so agents sharing the throttled
+ *  account stagger their restart-and-replay instead of stampeding the
+ *  just-cleared account. */
+export const THROTTLE_RETRY_NUDGE_JITTER_MAX_MS = 30_000
+
+/** The narrow broker surface the runner needs (structurally satisfied by
+ *  the gateway's AuthBrokerClient). */
+export interface ThrottleBrokerClient {
+  markThrottled(until: number): Promise<{
+    account: string
+    throttled_until: number
+    escalated: boolean
+    rolledTo?: string | null
+  }>
+  claimNotification(key: string, windowMs: number): Promise<{ granted: boolean }>
+}
+
+export interface ThrottleTierRunnerDeps {
+  /** This gateway's own agent (SWITCHROOM_AGENT_NAME). */
+  agentName: string
+  getBrokerClient(): Promise<ThrottleBrokerClient | null>
+  /** Chats the notice broadcasts to (access.allowFrom, resolved per call). */
+  listNoticeChats(): Array<string | number>
+  /** Fire-and-forget rich send (gateway wraps swallowingApiCall). */
+  sendNotice(chatId: string | number, markdown: string): void
+  /** THE shared fleet-fallback resume gate (single-flight + staleness). */
+  resumeDecide(failedTurnStartedAtMs: number | null): 'resume' | 'skip-inflight' | 'skip-stale'
+  newestActiveTurnStartedAtMs(): number | null
+  /** True while a turn is in flight (gateway turnInFlightForGate()). */
+  turnInFlight(): boolean
+  /** Defer the restart to the turn-complete drain (pendingRestarts). */
+  deferRestartToTurnComplete(agentName: string, reason: string): void
+  /** Restart now (gateway triggerSelfRestart). */
+  restartNow(agentName: string, reason: string): void
+  log(msg: string): void
+  now?: () => number
+  /** Timer seam (tests drive synchronously). Default setTimeout+unref. */
+  schedule?: (fn: () => void, ms: number) => { cancel(): void }
+  /** Jitter source (tests pin it). Default uniform 0..JITTER_MAX. */
+  jitterMs?: () => number
+}
+
+export interface ThrottleTierRunner {
+  /**
+   * Run the throttle path for one terminal transient 429. Fire-and-forget
+   * from the caller's perspective — never throws.
+   */
+  fire(triggerAgent: string, throttledUntilMs: number, resetParsed: boolean): Promise<void>
+  /** Test/debug view of internal state. */
+  inspect(): { noticeState: ThrottleNoticeState; nudgePending: boolean }
+}
+
+export function createThrottleTierRunner(deps: ThrottleTierRunnerDeps): ThrottleTierRunner {
+  const now = deps.now ?? (() => Date.now())
+  const schedule =
+    deps.schedule ??
+    ((fn: () => void, ms: number) => {
+      const t = setTimeout(fn, ms)
+      if (typeof t.unref === 'function') t.unref()
+      return { cancel: () => clearTimeout(t) }
+    })
+  const jitterMs =
+    deps.jitterMs ?? (() => Math.floor(Math.random() * THROTTLE_RETRY_NUDGE_JITTER_MAX_MS))
+
+  let noticeState: ThrottleNoticeState = { lastSentAtMsByAccount: {} }
+  /** The LATEST throttle owns the nudge — a newer hit replaces an armed
+   *  timer instead of stacking restarts. */
+  let pendingNudge: { cancel(): void } | null = null
+
+  /**
+   * Post `markdown` to every authorized chat, fleet-deduped per chat via the
+   * broker claim verb when a client + account are available. Fail-open: a
+   * claim error or missing broker never drops the notice.
+   */
+  async function broadcastDeduped(
+    client: ThrottleBrokerClient | null,
+    keyPrefix: string,
+    account: string | null,
+    markdown: string,
+  ): Promise<void> {
+    for (const chatId of deps.listNoticeChats()) {
+      let granted = true
+      if (client && account) {
+        try {
+          granted = (
+            await client.claimNotification(
+              `${keyPrefix}:${account}:${chatId}`,
+              THROTTLE_NOTICE_COOLDOWN_MS,
+            )
+          ).granted
+        } catch {
+          granted = true // fail open — a duplicated notice beats a dropped one
+        }
+      }
+      if (granted) {
+        deps.sendNotice(chatId, markdown)
+      } else {
+        deps.log(`[throttle-tier] notice suppressed (fleet claim) chat=${chatId}`)
+      }
+    }
+  }
+
+  /**
+   * Replay the dead turn via restart, with the turn-safety guards (see
+   * module docstring). `armedAtMs` anchors the "newer turn supersedes"
+   * check: a turn that started after the throttle was armed is live user
+   * work, never to be killed for a replay.
+   */
+  function nudgeResume(reason: string, armedAtMs: number): void {
+    const newest = deps.newestActiveTurnStartedAtMs()
+    if (deps.turnInFlight()) {
+      if (newest != null && newest > armedAtMs) {
+        deps.log(
+          `[throttle-tier] resume skipped (superseded by a live newer turn) reason=${reason}`,
+        )
+        return
+      }
+      // The in-flight gate is held by the dead throttled turn itself —
+      // defer to the turn-complete drain instead of SIGTERM-ing now.
+      deps.log(`[throttle-tier] resume deferred to turn-complete reason=${reason}`)
+      deps.deferRestartToTurnComplete(deps.agentName, reason)
+      return
+    }
+    const verdict = deps.resumeDecide(newest)
+    if (verdict === 'resume') {
+      deps.log(`[throttle-tier] resuming dead turn via self-restart reason=${reason}`)
+      deps.restartNow(deps.agentName, reason)
+    } else {
+      deps.log(`[throttle-tier] resume suppressed (${verdict}) reason=${reason}`)
+    }
+  }
+
+  async function fire(
+    triggerAgent: string,
+    throttledUntilMs: number,
+    resetParsed: boolean,
+  ): Promise<void> {
+    const armedAtMs = now()
+    let client: ThrottleBrokerClient | null = null
+    let account: string | null = null
+    let escalated = false
+    let rolledTo: string | null = null
+    try {
+      client = await deps.getBrokerClient()
+      if (client) {
+        const r = await client.markThrottled(throttledUntilMs)
+        account = r.account
+        escalated = r.escalated
+        rolledTo = r.rolledTo ?? null
+      } else {
+        deps.log(
+          `[throttle-tier] broker unreachable — notice only, no ledger record agent=${triggerAgent}`,
+        )
+      }
+    } catch (err) {
+      deps.log(
+        `[throttle-tier] markThrottled failed agent=${triggerAgent}: ${(err as Error)?.message ?? err}`,
+      )
+    }
+
+    if (escalated) {
+      // The broker corroborated a genuine wall via a live probe and already
+      // ran mark-exhausted + roll (fleet active AND pinned accounts alike).
+      // The RAISING gateway announces — reactive-path doctrine — fleet-
+      // deduped so N gateways sharing the account produce one copy per chat.
+      deps.log(
+        `[throttle-tier] escalated to wall account=${account ?? '?'} ` +
+          `rolledTo=${rolledTo ?? 'none (all blocked)'}`,
+      )
+      await broadcastDeduped(
+        client,
+        'throttle-escalation',
+        account,
+        renderThrottleEscalationNotice({ account, agent: triggerAgent, rolledTo }),
+      )
+      if (rolledTo) nudgeResume('throttle-escalation-resume', armedAtMs)
+      return
+    }
+
+    // ONE lightweight notice, deduped per account: locally by cooldown, then
+    // fleet-wide by broker claim. Unknown account (broker down) keys the
+    // local cooldown on the agent so the degraded path still can't spam.
+    const cooldownKey = account ?? `agent:${triggerAgent}`
+    const verdict = evaluateThrottleNotice(noticeState, cooldownKey, now())
+    if (verdict.send) {
+      noticeState = verdict.next
+      await broadcastDeduped(
+        client,
+        'throttle-notice',
+        account,
+        renderThrottleNotice({
+          account,
+          agent: triggerAgent,
+          throttledUntilMs,
+          resetParsed,
+          now: new Date(now()),
+        }),
+      )
+    } else {
+      deps.log(`[throttle-tier] notice suppressed (cooldown) key=${cooldownKey}`)
+    }
+
+    // Arm (or re-arm) the retry nudge: slack past the reset + jitter so
+    // agents sharing the account stagger their replays.
+    const delayMs =
+      Math.max(throttledUntilMs - now(), 0) + THROTTLE_RETRY_NUDGE_SLACK_MS + jitterMs()
+    if (pendingNudge) pendingNudge.cancel()
+    pendingNudge = schedule(() => {
+      pendingNudge = null
+      nudgeResume('throttle-retry-resume', armedAtMs)
+    }, delayMs)
+  }
+
+  return {
+    fire,
+    inspect: () => ({ noticeState, nudgePending: pendingNudge != null }),
+  }
+}

package/telegram-plugin/history.ts

@@ -108,6 +108,25 @@ export interface RecordedMessage {
    * Only emoji reactions are tracked — custom emoji are ignored for v1.
    */
   user_reaction: string | null
+  /**
+   * Set when the inbound user message was FORWARDED: the server-stamped
+   * `forward_origin` of the original message (Bot API 7.0+), so
+   * get_recent_messages can surface who originally sent the content the
+   * agent saw at delivery time. `forwarded_from` is the raw (truncated,
+   * unescaped) human-readable name/title; `forwarded_from_type` is
+   * user|hidden_user|chat|channel (hidden_user = self-reported display
+   * name, no verifiable id); `forwarded_from_id` is the numeric id when
+   * the origin shape exposes one; `forwarded_date` is the original
+   * message's ISO timestamp; `forwarded_message_id` is the message id
+   * inside the origin channel (channel origins only). For a multi-origin
+   * coalesced burst only the PRIMARY (first) origin is persisted here —
+   * origins 2+ exist only in the delivered channel tag's numbered attrs.
+   */
+  forwarded_from: string | null
+  forwarded_from_type: string | null
+  forwarded_from_id: string | null
+  forwarded_date: string | null
+  forwarded_message_id: number | null
 }
 
 export interface QueryOptions {
@@ -166,10 +185,20 @@ export function initHistory(stateDir: string, retentionDays = 30): void {
     CREATE INDEX IF NOT EXISTS idx_messages_recent
       ON messages (chat_id, thread_id, ts DESC)
   `)
-  // Migration: add reply_to columns to existing DBs that pre-date issue #119.
-  // SQLite has no IF NOT EXISTS for ALTER TABLE ADD COLUMN, so we tolerate
-  // "duplicate column name" errors and re-throw anything else.
-  for (const column of ["reply_to_message_id INTEGER", "reply_to_text TEXT", "user_reaction TEXT"]) {
+  // Migration: add reply_to columns to existing DBs that pre-date issue #119,
+  // and the forwarded_* origin columns (forward_origin metadata) to DBs that
+  // pre-date them. SQLite has no IF NOT EXISTS for ALTER TABLE ADD COLUMN, so
+  // we tolerate "duplicate column name" errors and re-throw anything else.
+  for (const column of [
+    "reply_to_message_id INTEGER",
+    "reply_to_text TEXT",
+    "user_reaction TEXT",
+    "forwarded_from TEXT",
+    "forwarded_from_type TEXT",
+    "forwarded_from_id TEXT",
+    "forwarded_date TEXT",
+    "forwarded_message_id INTEGER",
+  ]) {
     try {
       db.exec(`ALTER TABLE messages ADD COLUMN ${column}`)
     } catch (err) {
@@ -349,6 +378,19 @@ interface RecordInboundArgs {
    */
   reply_to_message_id?: number | null | undefined
   reply_to_text?: string | null | undefined
+  /**
+   * If the message was forwarded, the server-stamped origin metadata
+   * (Bot API 7.0 `forward_origin`). Populated from
+   * `ctx.message.forward_origin` in the gateway handler. `forwarded_from`
+   * is the RAW (truncated, unescaped) name — the XML-escaped form goes to
+   * the channel meta only. `forwarded_date` is the origin message's ISO
+   * timestamp; `forwarded_message_id` is set for channel origins only.
+   */
+  forwarded_from?: string | null | undefined
+  forwarded_from_type?: string | null | undefined
+  forwarded_from_id?: string | null | undefined
+  forwarded_date?: string | null | undefined
+  forwarded_message_id?: number | null | undefined
 }
 
 /**
@@ -364,8 +406,8 @@ export function recordInbound(args: RecordInboundArgs): void {
   if (args.message_id == null) return
   const stmt = requireDb().prepare(`
     INSERT OR REPLACE INTO messages
-      (chat_id, thread_id, message_id, role, user, user_id, ts, text, attachment_kind, group_id, reply_to_message_id, reply_to_text)
-    VALUES (?, ?, ?, 'user', ?, ?, ?, ?, ?, NULL, ?, ?)
+      (chat_id, thread_id, message_id, role, user, user_id, ts, text, attachment_kind, group_id, reply_to_message_id, reply_to_text, forwarded_from, forwarded_from_type, forwarded_from_id, forwarded_date, forwarded_message_id)
+    VALUES (?, ?, ?, 'user', ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?, ?, ?, ?)
   `)
   // Defense-in-depth: never persist a detected secret to the message store.
   // The inbound gate (server.ts handleInbound) already deletes + vaults a
@@ -382,6 +424,13 @@ export function recordInbound(args: RecordInboundArgs): void {
     args.attachment_kind ?? null,
     args.reply_to_message_id ?? null,
     args.reply_to_text != null ? redact(args.reply_to_text) : (args.reply_to_text ?? null),
+    // Origin names/titles are user-controlled display strings; run them
+    // through the same secret-redaction backstop as message text.
+    args.forwarded_from != null ? redact(args.forwarded_from) : null,
+    args.forwarded_from_type ?? null,
+    args.forwarded_from_id ?? null,
+    args.forwarded_date ?? null,
+    args.forwarded_message_id ?? null,
   )
 }
 

package/telegram-plugin/model-unavailable.ts

@@ -31,7 +31,20 @@ import { escapeMarkdown } from './card-format.js'
 
 // ─── Public types ────────────────────────────────────────────────────────────
 
-export type ModelUnavailableKind = 'overload' | 'quota_exhausted' | 'network'
+export type ModelUnavailableKind =
+  | 'overload'
+  | 'quota_exhausted'
+  | 'network'
+  /**
+   * 429 throttle tier — a TRANSIENT per-account 429 (explicit
+   * `transientUpstreamSignals` negation wording) whose parsed reset lies
+   * BEYOND the retry-in-place threshold, so the gateway escalates it to the
+   * standard mark-exhausted + fleet-failover machinery. Never produced by
+   * `detectModelUnavailable` (a transient-negation string classifies as
+   * `overload` there); constructed only by the gateway's throttle-tier
+   * branch so the card names the true cause instead of "quota exhausted".
+   */
+  | 'rate_limited'
 
 export interface ModelUnavailableDetection {
   kind: ModelUnavailableKind
@@ -79,6 +92,203 @@ export function isTransientUpstreamSignal(text: string): boolean {
   return transientUpstreamSignals.some(s => lower.includes(s))
 }
 
+// ─── LiteLLM-proxy-LOCAL 429 signals (canonical, single source of truth) ─────
+
+/**
+ * Explicit markers of a 429 generated by the LiteLLM proxy's OWN rate
+ * limiters — a router `tpm_limit`/`rpm_limit` deployment cap, a virtual-key /
+ * team / user cap, or an all-deployments-cooling-down router state. The
+ * request never reached Anthropic, so the condition is PROXY-LOCAL: it says
+ * nothing about the Anthropic account's quota and must never mark the account
+ * throttled/exhausted or trigger fleet failover.
+ *
+ * Each wording key is grounded in LiteLLM's source (verified against
+ * BerriAI/litellm `main`, 2026-07), matching how
+ * `accountScopedThrottleSignals` (throttle-tier.ts) documents its keys:
+ *
+ *  - "deployment over user-defined ratelimit" —
+ *    `RouterErrors.user_defined_ratelimit_error` (litellm/types/router.py),
+ *    the body prefix of every deployment tpm/rpm cap 429 raised by
+ *    litellm/router_utils/pre_call_checks/model_rate_limit_check.py:
+ *    "Deployment over user-defined ratelimit. tpm limit={n}. current
+ *    usage={n}. id={id}, model_group={g}".
+ *  - "model rate limit exceeded. tpm/rpm limit" — the `message` field of the
+ *    same enforcement RateLimitError: "Model rate limit exceeded. TPM
+ *    limit={n}, current usage={n}" (model_rate_limit_check.py).
+ *  - "deployment over defined rpm limit" — the usage-based-routing-v2
+ *    strategy wording "Deployment over defined rpm limit={n}. current
+ *    usage={n}" (litellm/router_strategy/lowest_tpm_rpm_v2.py). There is NO
+ *    tpm sibling in any known release — v2 TPM exhaustion surfaces as the
+ *    `no_deployments_available` wording below (the deployment is filtered
+ *    from the candidate set rather than erroring in the increment path).
+ *  - "no deployments available for selected model" —
+ *    `RouterErrors.no_deployments_available`, the RouterRateLimitError
+ *    message when every deployment for the model group is cooling down:
+ *    "No deployments available for selected model, Try again in {n}
+ *    seconds…" (litellm/types/router.py).
+ *  - "litellm rate limit handler" — the v1 parallel-request limiter's
+ *    ProxyRateLimitError detail prefix: "LiteLLM Rate Limit Handler for
+ *    rate limit type = {t}. Crossed TPM / RPM / Max Parallel Request
+ *    Limit. current rpm: {n}, rpm limit: {n}…"
+ *    (litellm/proxy/hooks/parallel_request_limiter.py).
+ *  - "crossed tpm / rpm" — `CommonProxyErrors
+ *    .max_parallel_request_limit_reached.value` = "Crossed TPM / RPM / Max
+ *    Parallel Request Limit" (litellm/proxy/_types.py), interpolated into
+ *    BOTH v1 detail shapes, so it also covers the zero-limit branch's
+ *    "Max parallel request limit reached {additional_details}" message.
+ *  - "max parallel request limit reached" — the standalone prefix
+ *    `raise_rate_limit_error` builds when a key's limit is set to 0
+ *    (parallel_request_limiter.py `error_message`).
+ *
+ * The proxy-side per-key/team/user limiter (parallel_request_limiter_v3.py
+ * `_handle_rate_limit_error`) is matched by CO-OCCURRENCE instead of a
+ * per-descriptor entry — see `isLitellmProxyLocal429`. Its detail shape:
+ * "Rate limit exceeded for {descriptor}: {value}. Limit type: {t}. Current
+ * limit: {n}, Remaining: {n}. Limit resets at: {ts}". Descriptor keys in
+ * source are numerous and growing (api_key / user / team / team_member /
+ * organization / end_user / agent / agent_session / model_per_key /
+ * model_per_team / model_per_organization / model_per_project / tag_per_key
+ * / mcp_per_key / mcp_per_team as of 2026-07), so enumerating them is a
+ * treadmill: the pair "rate limit exceeded for " + "limit type:" appears in
+ * every v3 body and in no Anthropic error. This is the shape a `tpm_limit`
+ * on the per-agent virtual keys (src/litellm/provision.ts) trips.
+ *
+ * Deliberately EXCLUDED: the bare exception-mapping prefix
+ * "litellm.RateLimitError:". LiteLLM wraps FORWARDED upstream 429s with the
+ * same prefix on the pass-through, so its presence is NOT evidence the limit
+ * was proxy-local — a genuine Anthropic account throttle traversing the
+ * proxy must keep its account-scoped classification (see
+ * `classify429Detail` in throttle-tier.ts for the tie-break).
+ */
+export const litellmProxyLocal429Signals = [
+  'deployment over user-defined ratelimit',
+  'model rate limit exceeded. tpm limit',
+  'model rate limit exceeded. rpm limit',
+  'deployment over defined rpm limit',
+  'no deployments available for selected model',
+  'litellm rate limit handler',
+  'crossed tpm / rpm',
+  'max parallel request limit reached',
+]
+
+/**
+ * The v3 proxy-limiter co-occurrence pair (see the provenance comment on
+ * `litellmProxyLocal429Signals`): both substrings appear in every
+ * parallel_request_limiter_v3 429 body regardless of descriptor key, and
+ * never in an Anthropic error. Exported so tests can pin the rule.
+ */
+export const litellmV3LimiterSignalPair = ['rate limit exceeded for ', 'limit type:'] as const
+
+/**
+ * True when `text` carries an EXPLICIT LiteLLM-proxy-local rate-limit marker:
+ * one of `litellmProxyLocal429Signals`, OR the v3 limiter co-occurrence pair
+ * (`litellmV3LimiterSignalPair` — descriptor-agnostic, so new v3 descriptor
+ * keys are covered without a list update). Never throws on weird input. Pure
+ * wording detection only — precedence against account-scoped wording is
+ * owned by `classify429Detail` (throttle-tier.ts).
+ */
+export function isLitellmProxyLocal429(text: string): boolean {
+  if (typeof text !== 'string' || text.length === 0) return false
+  const sample = text.length > 16_384 ? text.slice(0, 16_384) : text
+  const lower = sample.toLowerCase()
+  if (litellmProxyLocal429Signals.some(s => lower.includes(s))) return true
+  return litellmV3LimiterSignalPair.every(s => lower.includes(s))
+}
+
+/**
+ * Best-effort extraction of the limit detail LiteLLM embeds in its
+ * proxy-local 429 bodies, for instrumentation (the `rate_limit_429_classified`
+ * runtime metric). All fields null when nothing parseable is found — never
+ * throws. Shapes covered (same provenance as `litellmProxyLocal429Signals`):
+ *
+ *   - "tpm limit=8000. current usage=8241"    (model_rate_limit_check body)
+ *   - "TPM limit=8000, current usage=8241"    (model_rate_limit_check message)
+ *   - "Deployment over defined rpm limit=60. current usage=61"  (v2 strategy)
+ *   - "Limit type: tokens. Current limit: 8000 … Limit resets at:
+ *      2026-07-12 08:05:00 UTC"               (parallel_request_limiter_v3)
+ *   - "Try again in 27.5 seconds"             (RouterRateLimitError cooldown)
+ *
+ * CAVEAT — the v3 "Limit resets at" timestamp is NOT reliably UTC despite
+ * the literal: litellm formats it with a naive `datetime.fromtimestamp(...)
+ * .strftime("%Y-%m-%d %H:%M:%S UTC")` (parallel_request_limiter_v3.py
+ * `_handle_rate_limit_error`), i.e. proxy-LOCAL wall-clock time with a
+ * hard-coded "UTC" suffix. We parse it as UTC (nothing better is possible
+ * from the body alone), so `resetAtMs` — and the metric fields derived from
+ * it — can be skewed by the proxy host's UTC offset when the proxy doesn't
+ * run on UTC. Treat v3-derived resets as approximate; don't chase phantom
+ * clock drift from these metrics. The rate-limit windows are ≤1 minute
+ * anyway, so the absolute timestamp is informational.
+ */
+export function parseLitellmLimitDetail(
+  text: string,
+  parseTimeNow: Date = new Date(),
+): {
+  limitType: string | null
+  limit: number | null
+  currentUsage: number | null
+  resetAtMs: number | null
+} {
+  const empty = { limitType: null, limit: null, currentUsage: null, resetAtMs: null }
+  if (typeof text !== 'string' || text.length === 0) return empty
+  const sample = text.length > 16_384 ? text.slice(0, 16_384) : text
+  const lower = sample.toLowerCase()
+
+  // "tpm limit=8000" / "rpm limit=60" (body), "TPM limit=8000" (message),
+  // and the v1 limiter's colon form "rpm limit: 60".
+  let limitType: string | null = null
+  let limit: number | null = null
+  const eqLimit = lower.match(/\b([tr]pm)[ _]limit[=:]\s*(\d+)/)
+  if (eqLimit) {
+    limitType = eqLimit[1]
+    limit = Number(eqLimit[2])
+  }
+  // v3 limiter: "Limit type: tokens. Current limit: 8000"
+  if (limitType == null) {
+    const v3Type = lower.match(/limit type:\s*(tokens|requests|max_parallel_requests)/)
+    if (v3Type) limitType = v3Type[1]
+  }
+  if (limit == null) {
+    const v3Limit = lower.match(/current limit:\s*(\d+)/)
+    if (v3Limit) limit = Number(v3Limit[1])
+  }
+
+  // "current usage=8241" (body/message, both `=` and `= ` never occur with
+  // separators other than the literal shown in source).
+  let currentUsage: number | null = null
+  const usage = lower.match(/current usage=(\d+)/)
+  if (usage) currentUsage = Number(usage[1])
+
+  // Reset hints LiteLLM emits that the Anthropic-shaped parseResetTime does
+  // not cover: "Limit resets at: 2026-07-12 08:05:00 UTC" (v3 limiter — note
+  // the space separator, not ISO 'T') and "Try again in 27.5 seconds"
+  // (RouterRateLimitError).
+  let resetAtMs: number | null = null
+  const resetsAt = sample.match(
+    /limit resets at:\s*(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}) UTC/i,
+  )
+  if (resetsAt) {
+    const d = new Date(`${resetsAt[1]}T${resetsAt[2]}Z`)
+    if (!Number.isNaN(d.getTime())) resetAtMs = d.getTime()
+  }
+  if (resetAtMs == null) {
+    const tryAgain = lower.match(/try again in\s+(\d+(?:\.\d+)?)\s*seconds/)
+    if (tryAgain) {
+      const secs = Number(tryAgain[1])
+      if (Number.isFinite(secs) && secs > 0 && secs < 7 * 24 * 3600) {
+        resetAtMs = parseTimeNow.getTime() + Math.round(secs * 1000)
+      }
+    }
+  }
+
+  return {
+    limitType,
+    limit: limit != null && Number.isFinite(limit) ? limit : null,
+    currentUsage:
+      currentUsage != null && Number.isFinite(currentUsage) ? currentUsage : null,
+    resetAtMs,
+  }
+}
+
 // ─── Detection ───────────────────────────────────────────────────────────────
 
 /**
@@ -125,6 +335,23 @@ export function detectModelUnavailable(
       : { kind: 'overload', raw: stderr }
   }
 
+  // ── 0.5. LiteLLM-proxy-LOCAL 429 — never a quota signal ─────────────────
+  // A 429 raised by the LiteLLM proxy's own limiters (`tpm_limit`/`rpm_limit`
+  // caps, router cooldown) never reached Anthropic — nothing about the
+  // account is exhausted, so it must classify to the calm retryable kind
+  // BEFORE the quota substrings run (some LiteLLM bodies contain the word
+  // "limit", which a negation-blind quota match could seize on). Runs after
+  // step 0 deliberately: account-affirming wording, when present, can only
+  // have originated upstream (LiteLLM never emits it) and wins — see the
+  // tie-break note on `classify429Detail` (throttle-tier.ts). Uses the full
+  // matcher (list + v3 co-occurrence pair) so every descriptor is covered.
+  if (isLitellmProxyLocal429(sample)) {
+    const resetAt = parseResetTime(sample)
+    return resetAt !== undefined
+      ? { kind: 'overload', resetAt, raw: stderr }
+      : { kind: 'overload', raw: stderr }
+  }
+
   // ── 1. Quota / billing exhaustion ──────────────────────────────────────
   const quotaSignals = [
     'out of extra usage',
@@ -212,7 +439,7 @@ export function detectModelUnavailable(
  * arg lets tests pin the relative-clock anchor; production callers omit
  * it to use Date.now().
  */
-function parseResetTime(text: string, parseTimeNow: Date = new Date()): Date | undefined {
+export function parseResetTime(text: string, parseTimeNow: Date = new Date()): Date | undefined {
   const lower = text.toLowerCase()
 
   // "retry after 60 seconds" / "retry-after: 60"
@@ -459,6 +686,11 @@ function formatReason(d: ModelUnavailableDetection, now: Date): string {
       return `quota exhausted${reset}`
     case 'overload':
       return `model overloaded${reset}`
+    case 'rate_limited':
+      // Throttle-tier escalation (429 with transient wording but a reset too
+      // far out to wait in place). Honest cause: the account is rate-limited,
+      // not quota-exhausted — the reset names when it frees.
+      return `account rate-limited${reset}`
     case 'network':
       return 'network unreachable'
   }