@huynle/hub 0.9.2 → 0.10.0

package/src/central/context-cards/config.ts

@@ -0,0 +1,145 @@
+// Context cards configuration (docs/context-cards.md "Configuration"):
+//
+//   hub.json "contextCards": {
+//     "enabled": true,                         // false (or env HUB_CONTEXT_CARDS=off): the hub-wide kill switch
+//     "model": {                               // the light model the hub calls (all optional)
+//       "provider": "openrouter",              // or "openai-compatible" (needs baseURL)
+//       "model": "anthropic/claude-haiku-4.5", // default on OpenRouter
+//       "baseURL": "https://…/v1",             // https, or http on a private host
+//       "apiKey": "…"                          // else OpenRouter reuses the speech OpenRouter key
+//     },
+//     "budget": { "calls": 200, "tokens": 400000 }   // per user per UTC day
+//   }
+//
+// The speech key is reused only for OpenRouter at OpenRouter's own base URL (a key never follows the settings to
+// another endpoint, as in speech/settings.ts). A file other users can read has its apiKey ignored (as speech's).
+import { OPENROUTER_BASE_URL } from "../speech/openrouter"
+import { isPrivateHost, type StoredSpeech } from "../speech/settings"
+
+export const CARD_MODEL_DEFAULT = "anthropic/claude-haiku-4.5"
+export const CARD_PROVIDERS = ["openrouter", "openai-compatible"] as const
+export type CardProviderName = (typeof CARD_PROVIDERS)[number]
+
+export interface ContextCardsConfig {
+  readonly enabled?: boolean
+  readonly model?: {
+    readonly provider?: CardProviderName
+    readonly model?: string
+    readonly baseURL?: string
+    readonly apiKey?: string
+  }
+  readonly budget?: { readonly calls?: number; readonly tokens?: number }
+}
+
+/** The model the hub calls, with its key (never sent to clients). */
+export interface ResolvedCardModel {
+  readonly provider: CardProviderName
+  readonly model: string
+  readonly baseURL: string
+  readonly apiKey: string
+  /** config: contextCards.model.apiKey; speech: the speech OpenRouter key (saved, hub.json or env). */
+  readonly keySource: "config" | "speech"
+}
+
+const KEYS = new Set(["enabled", "model", "budget"])
+const MODEL_KEYS = new Set(["provider", "model", "baseURL", "apiKey"])
+const BUDGET_KEYS = new Set(["calls", "tokens"])
+const MAX_CHARS = 500
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** https, or http on a private host; no user info. */
+function validBaseURL(raw: string): boolean {
+  try {
+    const url = new URL(raw)
+    if (url.username || url.password) return false
+    return url.protocol === "https:" || (url.protocol === "http:" && isPrivateHost(url.hostname))
+  } catch {
+    return false
+  }
+}
+
+const text = (value: unknown, name: string, fail: (message: string) => never): string => {
+  if (typeof value !== "string" || !value.trim() || value.length > MAX_CHARS) fail(`contextCards.${name} must be a non-empty string`)
+  return (value as string).trim()
+}
+
+/** hub.json `contextCards`, validated (fail throws); `shared`: the file is readable by others (its key is dropped). */
+export function readContextCards(raw: unknown, file: string, warnings: string[], fail: (message: string) => never, shared: boolean): ContextCardsConfig {
+  if (!isObj(raw)) fail("contextCards must be an object")
+  const input = raw as Record<string, unknown>
+  for (const key of Object.keys(input)) if (!KEYS.has(key)) warnings.push(`${file}: unknown key "contextCards.${key}" ignored`)
+  const out: { -readonly [K in keyof ContextCardsConfig]: ContextCardsConfig[K] } = {}
+  if (input.enabled !== undefined) {
+    if (typeof input.enabled !== "boolean") fail("contextCards.enabled must be true or false")
+    out.enabled = input.enabled as boolean
+  }
+  if (input.model !== undefined) {
+    if (!isObj(input.model)) fail("contextCards.model must be an object")
+    const m = input.model as Record<string, unknown>
+    for (const key of Object.keys(m)) if (!MODEL_KEYS.has(key)) warnings.push(`${file}: unknown key "contextCards.model.${key}" ignored`)
+    const model: { provider?: CardProviderName; model?: string; baseURL?: string; apiKey?: string } = {}
+    if (m.provider !== undefined) {
+      if (!CARD_PROVIDERS.includes(m.provider as CardProviderName)) fail(`contextCards.model.provider must be one of ${CARD_PROVIDERS.join(", ")}`)
+      model.provider = m.provider as CardProviderName
+    }
+    if (m.model !== undefined) model.model = text(m.model, "model.model", fail)
+    if (m.baseURL !== undefined) {
+      const url = text(m.baseURL, "model.baseURL", fail).replace(/\/+$/, "")
+      if (!validBaseURL(url)) fail("contextCards.model.baseURL must be https (or http on a private host)")
+      model.baseURL = url
+    }
+    if (m.apiKey !== undefined) {
+      const key = text(m.apiKey, "model.apiKey", fail)
+      if (shared) warnings.push(`${file} is readable by other users, so its contextCards.model.apiKey is ignored. Fix it with: chmod 600 ${file}`)
+      else model.apiKey = key
+    }
+    out.model = model
+  }
+  if (input.budget !== undefined) {
+    if (!isObj(input.budget)) fail("contextCards.budget must be an object")
+    const b = input.budget as Record<string, unknown>
+    const budget: { calls?: number; tokens?: number } = {}
+    for (const key of Object.keys(b)) {
+      if (!BUDGET_KEYS.has(key)) {
+        warnings.push(`${file}: unknown key "contextCards.budget.${key}" ignored`)
+        continue
+      }
+      const n = b[key]
+      if (typeof n !== "number" || !Number.isInteger(n) || n < 0) fail(`contextCards.budget.${key} must be a whole number ≥ 0`)
+      budget[key as "calls" | "tokens"] = n as number
+    }
+    out.budget = budget
+  }
+  return out
+}
+
+export interface KeySources {
+  /** OPENROUTER_API_KEY. */
+  readonly envKey?: string
+  /** Speech settings layers, highest first (the saved server default, then hub.json's). */
+  readonly speech?: readonly StoredSpeech[]
+}
+
+/** The speech settings' OpenRouter key (highest layer first), else the env's. */
+function speechKey(sources: KeySources): string | undefined {
+  for (const layer of sources.speech ?? []) {
+    for (const direction of [layer.stt, layer.tts]) {
+      if (direction?.apiKey && (direction.provider ?? "openrouter") === "openrouter" && (direction.baseURL === undefined || direction.baseURL.replace(/\/+$/, "") === OPENROUTER_BASE_URL)) return direction.apiKey
+    }
+  }
+  return sources.envKey || undefined
+}
+
+/** The configured model, or undefined (off, or no usable key / base URL). */
+export function resolveCardModel(config: ContextCardsConfig, sources: KeySources): ResolvedCardModel | undefined {
+  if (config.enabled === false) return undefined
+  const provider = config.model?.provider ?? "openrouter"
+  const openrouter = provider === "openrouter"
+  const model = config.model?.model ?? (openrouter ? CARD_MODEL_DEFAULT : undefined)
+  const baseURL = config.model?.baseURL ?? (openrouter ? OPENROUTER_BASE_URL : undefined)
+  if (!model || !baseURL) return undefined
+  if (config.model?.apiKey) return { provider, model, baseURL, apiKey: config.model.apiKey, keySource: "config" }
+  if (!openrouter || baseURL !== OPENROUTER_BASE_URL) return undefined
+  const apiKey = speechKey(sources)
+  return apiKey ? { provider, model, baseURL, apiKey, keySource: "speech" } : undefined
+}

package/src/central/context-cards/engine.ts

@@ -0,0 +1,379 @@
+// The context card engine (decision 9604b0a1; docs/context-cards.md). Triggers come in per user and session
+// (turn-end, blocked, user-return from http.ts's wiring; sweep from the leader's timer; manual from a refresh) and
+// run each provider that lists the trigger, through these gates, in order:
+//
+//   unknown provider → skipped "unknown"
+//   the kill switch / the user's setting (enabled) → "disabled"
+//   automatic only: recent human activity in the session (humanActive, injectable) → "inactive"
+//   automatic only: at most one run per provider and session per minIntervalMs → "throttled" (the last trigger is
+//     kept and runs once the interval is over)
+//   model providers: a model configured → "no-model"; then the inputs are gathered (only the provider's needs)
+//   automatic only: inputs (and provider version) unchanged since the stored card → "unchanged"
+//   model providers: the user's failure backoff → "backoff"; the hub-wide circuit breaker → "circuit"
+//   not forced: strictly weaker inputs than the stored card's (e.g. an offline spoke: no transcript) → "weaker"
+//   model providers: each call RESERVES one call in the user's daily budget first (atomic) → "budget"; the tokens it
+//     reports are added after it, also when it failed (a failed or timed-out call still counts)
+//   generate() → bounded (registry.boundCard) → the session still exists (exists) → "gone" → stored
+//   (ContextCardStore) → onCard (SSE + journal)
+//
+// Manual refreshes (refresh()): one run per card at a time (concurrent requests share it), at most one per card per
+// REFRESH_CARD_MS and REFRESH_USER_MAX per user per minute ("rate_limited" with retryAfterMs), and unchanged inputs
+// are skipped unless forced. run(…, "manual") is the forced, unlimited form (tests, internal).
+//
+// Automatic triggers are debounced (debounceMs, the latest wins) and only run where isLeader() holds (one pod
+// generates: http.ts elects "context-cards"). A manual refresh runs at once on the pod that took the request. A run
+// never throws: failures are a `failed` outcome (logged without text). The primary provider's run on a session
+// whose title is a placeholder (agent/names.ts) asks the existing autoName op, at most every AUTO_NAME_EVERY_MS
+// per session; real titles are never touched.
+import { createHash } from "node:crypto"
+import type { ContextCard, ContextCardTrigger } from "../../protocol"
+import { realTimers } from "../backend/memory-bus"
+import type { Timers } from "../backend/types"
+import { isPlaceholderTitle } from "../agent/names"
+import { ChatError, type ChatClient } from "../llm/chat"
+import type { CardBudget } from "./budget"
+import { boundCard, type CardRegistry } from "./registry"
+import type { ContextCardStore } from "./store"
+import type { CardChat, CardInputs, ContextCardProvider, InputNeed } from "./types"
+
+export const DEBOUNCE_MS = 15_000
+/** Manual refreshes: at most one per card this often, and this many per user per minute. */
+export const REFRESH_CARD_MS = 30_000
+export const REFRESH_USER_MAX = 10
+/** Consecutive model failures before a user backs off (BACKOFF_BASE_MS doubling, at most BACKOFF_MAX_MS). */
+export const BACKOFF_AFTER = 3
+export const BACKOFF_BASE_MS = 60_000
+export const BACKOFF_MAX_MS = 3_600_000
+/**
+ * The hub-wide breaker opens when PROVIDER-level errors (ChatError kind "provider": 401/403/408/429/5xx, network)
+ * came from at least CIRCUIT_USERS distinct users within CIRCUIT_WINDOW_MS, and pauses every model call for
+ * CIRCUIT_MS. One user can never open it alone, and content errors never count.
+ */
+export const CIRCUIT_USERS = 3
+export const CIRCUIT_WINDOW_MS = 5 * 60_000
+export const CIRCUIT_MS = 5 * 60_000
+
+/** The budget refused a model call (the run is skipped "budget"). */
+class BudgetRefused extends Error {}
+/** A placeholder-titled session's auto name is asked at most this often. */
+export const AUTO_NAME_EVERY_MS = 30 * 60_000
+/** In-memory throttle entries kept (oldest dropped first). */
+const TRACKED = 10_000
+
+export interface CardModel {
+  readonly client: ChatClient
+  readonly model: string
+}
+
+export interface EngineDeps {
+  readonly registry: CardRegistry
+  readonly store: ContextCardStore
+  readonly budget: CardBudget
+  /** Gathers the inputs a provider needs (./inputs.ts). */
+  readonly inputs: (userID: string, sessionID: string, needs: readonly InputNeed[]) => Promise<CardInputs>
+  /**
+   * Whether the user was recently active in the session (automatic triggers need it): the persisted per-user
+   * activity (src/central/human-activity.ts) in the hub, an in-memory map without it.
+   */
+  readonly humanActive: (userID: string, sessionID: string) => boolean | Promise<boolean>
+  /** The hub's kill switch and the user's setting. */
+  readonly enabled: (userID: string) => Promise<boolean>
+  /** The configured model, else undefined (model providers are skipped). */
+  readonly model: () => CardModel | undefined
+  /** Whether this pod generates automatic cards (the "context-cards" leader). */
+  readonly isLeader: () => boolean
+  readonly onCard: (userID: string, card: ContextCard) => void
+  /** The autoName op for a placeholder-titled session (best effort). */
+  readonly autoName?: (userID: string, sessionID: string) => Promise<void>
+  /** Whether the session still exists right before a card is stored (a deleted session gets none). */
+  readonly exists?: (userID: string, sessionID: string) => Promise<boolean>
+  /** The session's live title, re-checked right before an auto name (a title the user just set wins). */
+  readonly title?: (userID: string, sessionID: string) => string | undefined
+  /** Sessions the sweep looks at (recently active ones). */
+  readonly recent?: () => Iterable<{ readonly userID: string; readonly sessionID: string }>
+  readonly now?: () => number
+  readonly timers?: Timers
+  readonly debounceMs?: number
+  readonly log?: (message: string) => void
+}
+
+export type SkipReason = "unknown" | "disabled" | "inactive" | "throttled" | "no-model" | "unchanged" | "budget" | "empty" | "gone" | "backoff" | "circuit" | "weaker" | "rate_limited"
+
+export type RunOutcome =
+  | { readonly status: "generated"; readonly card: ContextCard }
+  | { readonly status: "skipped"; readonly reason: SkipReason; readonly retryAfterMs?: number }
+  | { readonly status: "failed"; readonly error: string }
+
+const keyOf = (userID: string, sessionID: string, provider: string) => `${userID}\n${sessionID}\n${provider}`
+
+/** Hash of a provider's inputs and version (unchanged → no regeneration). */
+export function inputsHash(provider: Pick<ContextCardProvider, "id" | "version">, inputs: CardInputs): string {
+  return createHash("sha256").update(JSON.stringify([provider.id, provider.version, inputs])).digest("hex").slice(0, 24)
+}
+
+/** The needs a run actually had (an offline spoke leaves the transcript and changes out). */
+function basisOf(needs: readonly InputNeed[], inputs: CardInputs): InputNeed[] {
+  return needs.filter((need) => {
+    switch (need) {
+      case "status":
+        return inputs.state !== undefined
+      case "intent":
+        return !!inputs.intent
+      case "transcript":
+        return !!inputs.transcript?.length
+      case "changes":
+        return inputs.changes !== undefined
+    }
+  })
+}
+
+/** `now` is a strict subset of `before`. */
+const weaker = (now: readonly string[], before: readonly string[]) => now.length < before.length && now.every((n) => before.includes(n))
+
+/** Sets `key` as the newest entry of a bounded, insertion-ordered map. */
+function remember<K, V>(map: Map<K, V>, key: K, value: V): void {
+  map.delete(key)
+  map.set(key, value)
+  if (map.size > TRACKED) map.delete(map.keys().next().value!)
+}
+
+export class ContextCardEngine {
+  private readonly now: () => number
+  private readonly timers: Timers
+  private readonly debounceMs: number
+  private readonly log: (message: string) => void
+  /** Pending automatic runs: key → timer and the latest trigger. */
+  private readonly pending = new Map<string, { handle: unknown; trigger: ContextCardTrigger }>()
+  /** key → when its last automatic-eligible run started generating. */
+  private readonly lastRun = new Map<string, number>()
+  /** `user\nsession` → when its auto name was last asked. */
+  private readonly named = new Map<string, number>()
+  /** `user\nsession` → forget() count (a run that started before a forget does not store). */
+  private readonly epochs = new Map<string, number>()
+  private readonly running = new Set<Promise<unknown>>()
+  /** Manual refreshes in flight, per card. */
+  private readonly inflight = new Map<string, Promise<RunOutcome>>()
+  /** Manual refreshes: per card the last, per user the times within the last minute. */
+  private readonly lastRefresh = new Map<string, number>()
+  private readonly userRefreshes = new Map<string, number[]>()
+  /** Model failures per user: consecutive count and the backoff's end (only that user's success clears it). */
+  private readonly failures = new Map<string, { count: number; until: number }>()
+  /** Model attempts in flight per user (a user with a pending failure gets one at a time). */
+  private readonly attempts = new Map<string, number>()
+  /** Provider-level failures per user (last time), for the hub-wide breaker; and the breaker's end. */
+  private readonly providerFailures = new Map<string, number>()
+  private circuitUntil = 0
+
+  constructor(private readonly deps: EngineDeps) {
+    this.now = deps.now ?? Date.now
+    this.timers = deps.timers ?? realTimers
+    this.debounceMs = deps.debounceMs ?? DEBOUNCE_MS
+    this.log = deps.log ?? ((message) => console.error(message))
+  }
+
+  /** An automatic trigger: each provider listing it runs after the debounce (on the leader only). */
+  trigger(userID: string, sessionID: string, trigger: Exclude<ContextCardTrigger, "manual">): void {
+    if (!this.deps.isLeader()) return
+    for (const provider of this.deps.registry.list()) {
+      if (provider.triggers.includes(trigger)) this.schedule(keyOf(userID, sessionID, provider.id), userID, sessionID, provider.id, trigger, this.debounceMs)
+    }
+  }
+
+  /** The sweep: a `sweep` trigger for each recently active session; answers how many. */
+  sweep(): number {
+    if (!this.deps.isLeader()) return 0
+    let n = 0
+    for (const { userID, sessionID } of this.deps.recent?.() ?? []) {
+      this.trigger(userID, sessionID, "sweep")
+      n++
+    }
+    return n
+  }
+
+  /** Waits for every run in flight (tests, drain). */
+  async settled(): Promise<void> {
+    while (this.running.size) await Promise.allSettled([...this.running])
+  }
+
+  /** Drops a session's cards and pending runs (session deleted). */
+  async forget(userID: string, sessionID: string): Promise<void> {
+    const prefix = `${userID}\n${sessionID}\n`
+    for (const [key, entry] of [...this.pending]) {
+      if (!key.startsWith(prefix)) continue
+      this.timers.clear(entry.handle)
+      this.pending.delete(key)
+    }
+    const session = `${userID}\n${sessionID}`
+    remember(this.epochs, session, (this.epochs.get(session) ?? 0) + 1)
+    await this.deps.store.forget(userID, sessionID)
+  }
+
+  /** A user's manual refresh: deduped per card, rate limited, unchanged inputs skipped unless forced. Never throws. */
+  refresh(userID: string, sessionID: string, providerID: string, options: { readonly force?: boolean } = {}): Promise<RunOutcome> {
+    const key = keyOf(userID, sessionID, providerID)
+    const shared = this.inflight.get(key)
+    if (shared) return shared
+    const now = this.now()
+    const last = this.lastRefresh.get(key)
+    if (last !== undefined && now - last < REFRESH_CARD_MS) return Promise.resolve({ status: "skipped", reason: "rate_limited", retryAfterMs: last + REFRESH_CARD_MS - now })
+    const recent = (this.userRefreshes.get(userID) ?? []).filter((at) => now - at < 60_000)
+    if (recent.length >= REFRESH_USER_MAX) return Promise.resolve({ status: "skipped", reason: "rate_limited", retryAfterMs: recent[0]! + 60_000 - now })
+    remember(this.userRefreshes, userID, [...recent, now])
+    remember(this.lastRefresh, key, now)
+    const run = this.run(userID, sessionID, providerID, "manual", { force: options.force === true }).finally(() => this.inflight.delete(key))
+    this.inflight.set(key, run)
+    return run
+  }
+
+  /** Runs one provider for a session now, through the gates; never throws. A manual run is forced unless told. */
+  run(userID: string, sessionID: string, providerID: string, trigger: ContextCardTrigger, options: { readonly force?: boolean } = {}): Promise<RunOutcome> {
+    const force = trigger === "manual" && options.force !== false
+    const run = this.attempt(userID, sessionID, providerID, trigger, force).catch((cause: unknown): RunOutcome => {
+      if (cause instanceof BudgetRefused) return { status: "skipped", reason: "budget" }
+      const error = cause instanceof Error ? cause.message : String(cause)
+      this.log(`[hub] context card ${providerID} failed: ${error.slice(0, 200)}`)
+      return { status: "failed", error }
+    })
+    this.running.add(run)
+    void run.finally(() => this.running.delete(run))
+    return run
+  }
+
+  private schedule(key: string, userID: string, sessionID: string, providerID: string, trigger: ContextCardTrigger, delayMs: number): void {
+    const existing = this.pending.get(key)
+    if (existing) {
+      existing.trigger = trigger
+      return
+    }
+    const entry = {
+      trigger,
+      handle: this.timers.set(() => {
+        this.pending.delete(key)
+        if (this.deps.isLeader()) void this.run(userID, sessionID, providerID, entry.trigger)
+      }, delayMs),
+    }
+    this.pending.set(key, entry)
+  }
+
+  private async attempt(userID: string, sessionID: string, providerID: string, trigger: ContextCardTrigger, force: boolean): Promise<RunOutcome> {
+    const provider = this.deps.registry.get(providerID)
+    if (!provider) return { status: "skipped", reason: "unknown" }
+    if (!(await this.deps.enabled(userID))) return { status: "skipped", reason: "disabled" }
+    const manual = trigger === "manual"
+    const key = keyOf(userID, sessionID, provider.id)
+    if (!manual) {
+      if (!(await this.deps.humanActive(userID, sessionID))) return { status: "skipped", reason: "inactive" }
+      const last = this.lastRun.get(key)
+      const wait = last === undefined ? 0 : last + provider.minIntervalMs - this.now()
+      if (wait > 0) {
+        this.schedule(key, userID, sessionID, provider.id, trigger, wait)
+        return { status: "skipped", reason: "throttled" }
+      }
+    }
+    const model = provider.usesModel ? this.deps.model() : undefined
+    if (provider.usesModel && !model) return { status: "skipped", reason: "no-model" }
+    if (model) {
+      if (this.now() < this.circuitUntil) return { status: "skipped", reason: "circuit" }
+      if (this.now() < (this.failures.get(userID)?.until ?? 0)) return { status: "skipped", reason: "backoff" }
+    }
+    const session = `${userID}\n${sessionID}`
+    const epoch = this.epochs.get(session) ?? 0
+    const inputs = await this.deps.inputs(userID, sessionID, provider.needs)
+    const hash = inputsHash(provider, inputs)
+    const basis = basisOf(provider.needs, inputs)
+    if (!force) {
+      const stored = await this.deps.store.get(userID, sessionID, provider.id)
+      if (stored?.inputsHash === hash && stored.version === provider.version) return { status: "skipped", reason: "unchanged" }
+      if (stored?.basis && weaker(basis, stored.basis)) return { status: "skipped", reason: "weaker" }
+    }
+    if (model) {
+      // Checked and counted with no await between: concurrent attempts see each other. After a failure that is not
+      // cleared yet, a user's attempts run one at a time (a burst cannot fail many calls at once).
+      if (this.now() < this.circuitUntil) return { status: "skipped", reason: "circuit" }
+      const failing = this.failures.get(userID)
+      if (failing && (this.now() < failing.until || (this.attempts.get(userID) ?? 0) > 0)) return { status: "skipped", reason: "backoff" }
+      this.attempts.set(userID, (this.attempts.get(userID) ?? 0) + 1)
+    }
+    remember(this.lastRun, key, this.now())
+    let draft
+    try {
+      draft = await provider.generate({ userID, sessionID, trigger, inputs, now: this.now(), ...(model ? { chat: this.chat(userID, model) } : {}) })
+    } catch (cause) {
+      if (model && !(cause instanceof BudgetRefused)) this.failed(userID, cause)
+      throw cause
+    } finally {
+      if (model) {
+        const left = (this.attempts.get(userID) ?? 1) - 1
+        if (left > 0) this.attempts.set(userID, left)
+        else this.attempts.delete(userID)
+      }
+    }
+    if (model) this.succeeded(userID)
+    const card = boundCard(provider, sessionID, draft, { generatedAt: this.now(), inputsHash: hash, trigger, basis })
+    if (!card) return { status: "skipped", reason: "empty" }
+    if ((this.epochs.get(session) ?? 0) !== epoch) return { status: "skipped", reason: "gone" }
+    if (this.deps.exists && !(await this.deps.exists(userID, sessionID))) return { status: "skipped", reason: "gone" }
+    // The user may have turned cards off during the run (privacy): store and send nothing, before and after the write.
+    if (!(await this.deps.enabled(userID))) return { status: "skipped", reason: "disabled" }
+    await this.deps.store.put(userID, card)
+    if (!(await this.deps.enabled(userID))) {
+      await this.deps.store.forget(userID, sessionID)
+      return { status: "skipped", reason: "disabled" }
+    }
+    this.deps.onCard(userID, card)
+    if (provider.primary) this.maybeName(userID, sessionID, inputs)
+    return { status: "generated", card }
+  }
+
+  /** The model for one run: each call reserves its place in the user's budget first; its tokens are added after. */
+  private chat(userID: string, model: CardModel): CardChat {
+    return {
+      model: model.model,
+      complete: async (request) => {
+        if (!(await this.deps.budget.reserve(userID)).ok) throw new BudgetRefused("budget")
+        try {
+          const result = await model.client.complete({ ...request, model: model.model })
+          await this.deps.budget.settle(userID, result.usage.inputTokens + result.usage.outputTokens)
+          return result
+        } catch (cause) {
+          const usage = cause instanceof ChatError ? cause.usage : undefined
+          if (usage) await this.deps.budget.settle(userID, usage.inputTokens + usage.outputTokens).catch(() => {})
+          throw cause
+        }
+      },
+    }
+  }
+
+  private failed(userID: string, cause: unknown): void {
+    const now = this.now()
+    const count = (this.failures.get(userID)?.count ?? 0) + 1
+    const until = count >= BACKOFF_AFTER ? now + Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** (count - BACKOFF_AFTER)) : 0
+    remember(this.failures, userID, { count, until })
+    if (!(cause instanceof ChatError) || cause.kind !== "provider") return
+    remember(this.providerFailures, userID, now)
+    for (const [user, at] of this.providerFailures) if (now - at > CIRCUIT_WINDOW_MS) this.providerFailures.delete(user)
+    if (this.providerFailures.size >= CIRCUIT_USERS) {
+      this.providerFailures.clear()
+      this.circuitUntil = now + CIRCUIT_MS
+      this.log("[hub] context cards: the model keeps failing; paused for 5 minutes")
+    }
+  }
+
+  /** Clears this user's failures only; the hub's record only when this user is not among its recent failures. */
+  private succeeded(userID: string): void {
+    this.failures.delete(userID)
+    if (!this.providerFailures.has(userID)) this.providerFailures.clear()
+  }
+
+  /** A placeholder title (known from the status input): ask the autoName op, throttled per session. */
+  private maybeName(userID: string, sessionID: string, inputs: CardInputs): void {
+    if (!this.deps.autoName || !("title" in inputs) || !isPlaceholderTitle(inputs.title)) return
+    // Re-checked now: the user may have named it while the card was being made.
+    if (this.deps.title && !isPlaceholderTitle(this.deps.title(userID, sessionID))) return
+    const session = `${userID}\n${sessionID}`
+    const last = this.named.get(session)
+    if (last !== undefined && this.now() - last < AUTO_NAME_EVERY_MS) return
+    remember(this.named, session, this.now())
+    void this.deps.autoName(userID, sessionID).catch((cause: unknown) => this.log(`[hub] context card auto name failed: ${(cause as Error).message}`))
+  }
+}

package/src/central/context-cards/inputs.ts

@@ -0,0 +1,111 @@
+// The context card inputs gatherer: only what a provider needs, each piece best effort (an offline spoke or a
+// failed read leaves it out; the provider decides what it can do without).
+//   status:     the live session (registry): title, state (the session's own status entry), open blockers' summaries
+//   intent:     the session's effective intent text (CON-02)
+//   transcript: the newest timeline rows from the spoke (op "timeline", order desc): user, assistant, tool and error
+//               rows, oldest first, sanitised and cut (reasoning, retries and hub messages are left out; tool rows
+//               keep only the tool's name and state, never their input or output)
+//   changes:    the spoke summary's working-tree changes and branch
+import { redactCredentials } from "../../../packages/protocol/src/credentials.ts"
+import { sanitizeText } from "../agent/envelope"
+import type { CardInputs, ChangesInput, InputNeed, TranscriptRow } from "./types"
+
+/** Timeline rows asked for. */
+export const TRANSCRIPT_ROWS = 40
+/** A row's text is cut to this many characters. */
+export const ROW_TEXT_MAX = 1500
+const BLOCKERS_MAX = 5
+const BLOCKER_MAX = 200
+const NAME_MAX = 60
+
+export interface InputSession {
+  readonly title?: string
+  readonly status?: ReadonlyArray<{ readonly id: string; readonly state: string; readonly blockers?: ReadonlyArray<{ readonly summary?: string }> }>
+}
+
+export interface InputDeps {
+  readonly session: (userID: string, sessionID: string) => InputSession | undefined
+  readonly intent: (userID: string, sessionID: string) => Promise<string | undefined>
+  /** The newest timeline rows (TRANSCRIPT_ROWS). */
+  readonly timeline: (userID: string, sessionID: string) => Promise<readonly unknown[]>
+  /** The spoke's summary (GET /api/sessions/:id/summary's body). */
+  readonly summary: (userID: string, sessionID: string) => Promise<unknown>
+}
+
+const rec = (v: unknown): Record<string, unknown> => (typeof v === "object" && v !== null ? (v as Record<string, unknown>) : {})
+const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? v : 0)
+/** Raw text redacted at most (bounds the work on a hostile row); far beyond any cut, so redaction always runs first. */
+const REDACT_MAX = 1024 * 1024
+/** Sanitised and credentials redacted first, then cut: a secret straddling the limit never leaks a part. */
+const cut = (text: string, max: number) =>
+  redactCredentials(sanitizeText(text.slice(0, REDACT_MAX))).text.replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim().slice(0, max)
+
+const KINDS: ReadonlySet<string> = new Set(["user", "assistant", "tool", "error"])
+
+/** Timeline items → transcript rows, oldest first (by `pos` when every row has one). */
+export function transcriptRows(items: readonly unknown[]): TranscriptRow[] {
+  const rows = items.map(rec).filter((item) => typeof item.kind === "string" && KINDS.has(item.kind))
+  if (rows.every((item) => typeof item.pos === "number")) rows.sort((a, b) => num(a.pos) - num(b.pos))
+  const out: TranscriptRow[] = []
+  for (const item of rows) {
+    const kind = item.kind as TranscriptRow["kind"]
+    if (kind === "tool") {
+      const name = typeof item.name === "string" ? cut(item.name, NAME_MAX) : ""
+      if (name) out.push({ kind, name, ...(typeof item.state === "string" ? { state: cut(item.state, 16) } : {}) })
+      continue
+    }
+    const text = typeof item.text === "string" ? cut(item.text, ROW_TEXT_MAX) : ""
+    if (text) out.push({ kind, text })
+  }
+  return out
+}
+
+/** The spoke summary's changes (undefined for anything but an object). */
+export function changesInput(summary: unknown): ChangesInput | undefined {
+  if (typeof summary !== "object" || summary === null) return undefined
+  const s = rec(summary)
+  const c = rec(s.changes)
+  const files = (Array.isArray(c.files) ? c.files : [])
+    .map(rec)
+    .filter((f) => typeof f.file === "string" && f.file)
+    .map((f) => ({ file: String(f.file), additions: num(f.additions), deletions: num(f.deletions) }))
+  return {
+    ...(typeof s.branch === "string" && s.branch ? { branch: s.branch } : {}),
+    files,
+    totalFiles: num(c.totalFiles) || files.length,
+    additions: num(c.additions),
+    deletions: num(c.deletions),
+  }
+}
+
+const quietly = async <T>(read: () => Promise<T>): Promise<T | undefined> => {
+  try {
+    return await read()
+  } catch {
+    return undefined
+  }
+}
+
+export async function gatherInputs(deps: InputDeps, userID: string, sessionID: string, needs: readonly InputNeed[]): Promise<CardInputs> {
+  const want = new Set(needs)
+  const live = want.has("status") ? deps.session(userID, sessionID) : undefined
+  const own = live?.status?.find((s) => s.id === sessionID) ?? live?.status?.[0]
+  const blockers = (own?.blockers ?? [])
+    .map((b) => (typeof b.summary === "string" ? cut(b.summary, BLOCKER_MAX).replace(/\s+/g, " ") : ""))
+    .filter(Boolean)
+    .slice(0, BLOCKERS_MAX)
+  const [intent, timeline, summary] = await Promise.all([
+    want.has("intent") ? quietly(() => deps.intent(userID, sessionID)) : undefined,
+    want.has("transcript") ? quietly(() => deps.timeline(userID, sessionID)) : undefined,
+    want.has("changes") ? quietly(() => deps.summary(userID, sessionID)) : undefined,
+  ])
+  const changes = summary === undefined ? undefined : changesInput(summary)
+  return {
+    sessionID,
+    ...(live?.title !== undefined ? { title: live.title } : {}),
+    ...(own ? { state: own.state, blockers } : {}),
+    ...(intent ? { intent } : {}),
+    ...(timeline ? { transcript: transcriptRows(timeline) } : {}),
+    ...(changes ? { changes } : {}),
+  }
+}