@huynle/hub 0.9.2 → 0.10.1

package/src/central/human-activity.ts

@@ -0,0 +1,453 @@
+// Session findability (Brain decisions iaspcry7, qqmworx1): per user and root session, the user's last action (a
+// prompt, Voice, an answer) and last explicit open, plus a small histogram of human and agent activity, so the console
+// can find "the sessions I work with" among hundreds (Touched by me, the sidebar's Working set, the activity meter).
+//
+// Feeds (wired in http.ts; every session ID here is a root session's):
+//   human(…, "prompt-web")  a prompt the hub carried for the user (console Send, /api/agent prompt by the user); never
+//                           a launch's first prompt (intent "first") or a Concierge proposal (intent false)
+//   human(…, "prompt-tui")  a prompt typed in the terminal: Registry.onTerminalPrompt (exact: an OpenCode spoke marks
+//                           the user items the hub carried, `carried`; other harnesses report the hub's prompts as
+//                           origin "hub"; an older OpenCode spoke's user items are not counted, never guessed)
+//   human(…, "voice")       a Voice utterance
+//   human(…, "answer")      the user's permission or form answer on a card
+//   human(…, "view")        an explicit open (POST /api/sessions/:id/read {open: true}): moves `last`, never counted,
+//                           and never replaces an action as what the session shows
+//   agent(…, turn | tool)   a turn started (session.execution.started) or a tool was called
+//
+// Storage: StateStore collection `human-activity` (tenant = user, key = root session ID):
+//   {a?, k?, v?, b: [[bucketStart, human, turns, tools], …], u}
+// `a`/`k`: the last action and its kind; `v`: the last open; `b`: 30-minute buckets, the last 48 (24 h); `u`: the last
+// update. What a session shows (at, kind): its last action while it is within a day of the latest touch, else the
+// open. Records not updated for 30 days are left out of reads and deleted by a background sweep (at most hourly per
+// user), and at most 2000 are kept per user.
+//
+// Writes are fire-and-forget: recording never waits on the store (a console prompt's request does not). Events are
+// aggregated in memory per session and written at most once a minute per session by this process (an action of a
+// session whose last write was not one, or the first touch, goes out at once); agent counts wait for the throttle
+// (a timer). A write is a version-checked read-modify-write, so pods add their counts. A failed write (the store, or
+// five version conflicts in a row) puts the activity back in the queue and backs the session off (30 s, doubling to
+// 10 min). At most `inFlight` store operations are pending at once. A touch written out at once takes no buffer slot.
+// lastAt (the context cards' gate) gives up on the store after readTimeoutMs: unknown, so not active.
+import type { Actions, PromptInput } from "./actions"
+import type { Clock, StateStore } from "./backend/types"
+
+export const HUMAN_ACTIVITY_COLLECTION = "human-activity"
+
+export const HUMAN_ACTIVITY_LIMITS = {
+  /** Histogram bucket width. */
+  bucketMs: 30 * 60_000,
+  /** Buckets kept per session (48 × 30 min = 24 h). */
+  buckets: 48,
+  /** At most one write per session per this long (the first action after an open excepted). */
+  writeEveryMs: 60_000,
+  /** How often the timer looks for buffered sessions due a write. */
+  flushEveryMs: 15_000,
+  /** Records not updated for this long are dropped. */
+  keepMs: 30 * 86_400_000,
+  /** Records kept per user (the least recently updated go first). */
+  perUser: 2000,
+  /** Sessions this process buffers or remembers (oldest dropped first). */
+  tracked: 10_000,
+  /** lastAt's store read gives up after this long (a hanging store never blocks the context cards' gate). */
+  readTimeoutMs: 2_000,
+  /** Store operations pending at once; past it, writes wait in the queue. */
+  inFlight: 100,
+  /** A user's records are swept at most this often. */
+  sweepEveryMs: 3_600_000,
+  /** An action keeps speaking for its session while it is within this long of the latest touch. */
+  actionShownMs: 86_400_000,
+  /** Backoff after a failed write (doubling per failure, up to maxRetryMs). */
+  retryMs: 30_000,
+  maxRetryMs: 600_000,
+} as const
+
+const L = HUMAN_ACTIVITY_LIMITS
+
+export const HUMAN_KINDS = ["prompt-tui", "prompt-web", "voice", "answer", "view"] as const
+export type HumanKind = (typeof HUMAN_KINDS)[number]
+type ActionKind = Exclude<HumanKind, "view">
+
+/** [bucket start (ms), human actions, agent turns, agent tool calls]. */
+export type Bucket = [number, number, number, number]
+
+/** What the console gets per session (GET /api/activity/mine, SSE `activity`). */
+export interface ActivityEntry {
+  /** What the session shows: the last action (within a day of `last`), else the last open. */
+  at?: number
+  kind?: HumanKind
+  /** The latest touch of any kind (sorts and filters). */
+  last?: number
+  buckets: Bucket[]
+}
+
+interface ActivityRecord {
+  readonly a?: number
+  readonly k?: ActionKind
+  readonly v?: number
+  readonly b: Bucket[]
+  readonly u: number
+}
+
+interface Pending {
+  readonly userID: string
+  readonly sessionID: string
+  acted?: number
+  actKind?: ActionKind
+  viewed?: number
+  /** bucket start → [human, turns, tools] */
+  readonly deltas: Map<number, [number, number, number]>
+}
+
+export interface HumanActivityOptions {
+  readonly state: StateStore
+  readonly now?: Clock
+  /** How often the timer looks for due writes (default flushEveryMs). */
+  readonly flushEveryMs?: number
+  /** At most one write per session per this long (default writeEveryMs; tests shorten it). */
+  readonly writeEveryMs?: number
+  /** Sessions buffered at once (default tracked; tests shorten it). */
+  readonly tracked?: number
+  /** lastAt gives up on a store read after this long (default readTimeoutMs): unknown, not active. */
+  readonly readTimeoutMs?: number
+  /** A session's record changed (after the write): the owner's consoles get it. */
+  readonly onChange?: (userID: string, sessionID: string, entry: ActivityEntry) => void
+}
+
+const slotOf = (at: number) => Math.floor(at / L.bucketMs) * L.bucketMs
+const isAction = (kind: HumanKind): kind is ActionKind => kind !== "view"
+
+export class HumanActivity {
+  private readonly state: StateStore
+  private readonly now: Clock
+  private readonly onChange: HumanActivityOptions["onChange"]
+  private readonly flushEveryMs: number
+  private readonly writeEveryMs: number
+  private readonly tracked: number
+  private readonly readTimeoutMs: number
+  private readonly pending = new Map<string, Pending>()
+  /** `userID\nsessionID` → when this process last wrote it and whether that write held an action. */
+  private readonly written = new Map<string, { at: number; action: boolean }>()
+  /** `userID\nsessionID` → backoff after failed writes. */
+  private readonly backoff = new Map<string, { until: number; failures: number }>()
+  private readonly swept = new Map<string, number>()
+  private readonly running = new Set<Promise<unknown>>()
+  private readonly touchListeners = new Set<(userID: string, sessionID: string, kind: HumanKind) => void>()
+  private inFlight = 0
+  private timer: ReturnType<typeof setInterval> | undefined
+  private lastLogged = Number.NEGATIVE_INFINITY
+
+  constructor(options: HumanActivityOptions) {
+    this.state = options.state
+    this.now = options.now ?? Date.now
+    this.onChange = options.onChange
+    this.flushEveryMs = options.flushEveryMs ?? L.flushEveryMs
+    this.writeEveryMs = options.writeEveryMs ?? L.writeEveryMs
+    this.tracked = options.tracked ?? L.tracked
+    this.readTimeoutMs = options.readTimeoutMs ?? L.readTimeoutMs
+  }
+
+  /** The user touched the (root) session. Queued: never waits on the store, never throws. */
+  human(userID: string, sessionID: string, kind: HumanKind): void {
+    try {
+      const now = this.now()
+      const key = this.key(userID, sessionID)
+      const last = this.written.get(key)
+      const due = !last || now - last.at >= this.writeEveryMs || (isAction(kind) && !last.action)
+      // Written out at once (flush takes it out of the buffer before its first await): it needs no buffer slot.
+      const p = this.pendingOf(userID, sessionID, due && this.writable(key, now) ? "passing" : "human")
+      if (!p) return
+      if (isAction(kind)) {
+        p.acted = now
+        p.actKind = kind
+        this.count(p, now, 0)
+      } else p.viewed = now
+      if (due) this.track(this.flush(key))
+      for (const listener of [...this.touchListeners]) listener(userID, sessionID, kind)
+    } catch (cause) {
+      this.log(cause)
+    }
+  }
+
+  /** Listens to every human touch as it is recorded (the context cards' user-return). Returns an unsubscribe. */
+  onTouch(listener: (userID: string, sessionID: string, kind: HumanKind) => void): () => void {
+    this.touchListeners.add(listener)
+    return () => this.touchListeners.delete(listener)
+  }
+
+  /** When the user last touched the (root) session: buffered here, else persisted (`last`); undefined when never. */
+  async lastAt(userID: string, sessionID: string): Promise<number | undefined> {
+    const p = this.pending.get(this.key(userID, sessionID))
+    const buffered = Math.max(p?.acted ?? Number.NEGATIVE_INFINITY, p?.viewed ?? Number.NEGATIVE_INFINITY)
+    const stored = await this.storedRecord(userID, sessionID)
+    const last = stored && typeof stored.u === "number" && this.now() - stored.u <= L.keepMs ? entryOf(stored, this.now()).last : undefined
+    const at = Math.max(buffered, last ?? Number.NEGATIVE_INFINITY)
+    return Number.isFinite(at) ? at : undefined
+  }
+
+  /** The stored record, or undefined when the store fails or does not answer within readTimeoutMs (unknown). */
+  private async storedRecord(userID: string, sessionID: string): Promise<ActivityRecord | undefined> {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const late = new Promise<undefined>((resolve) => (timer = setTimeout(() => (this.log(new Error(`activity read of ${sessionID} took over ${this.readTimeoutMs} ms`)), resolve(undefined)), this.readTimeoutMs)))
+    try {
+      return await Promise.race([this.state.get<ActivityRecord>(userID, HUMAN_ACTIVITY_COLLECTION, sessionID).then((r) => r?.value), late])
+    } catch (cause) {
+      this.log(cause)
+      return undefined
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  /** The agent worked in the session: counted in memory, written by the throttle. */
+  agent(userID: string, sessionID: string, what: "turn" | "tool"): void {
+    const p = this.pendingOf(userID, sessionID)
+    if (p) this.count(p, this.now(), what === "turn" ? 1 : 2)
+  }
+
+  /** Waits until every queued write and sweep has finished (stop, tests). */
+  async settled(): Promise<void> {
+    while (this.running.size) await Promise.allSettled([...this.running])
+  }
+
+  /** Writes the buffered sessions whose throttle (and backoff) has passed, and waits for them. */
+  async flushDue(): Promise<void> {
+    const now = this.now()
+    for (const key of [...this.pending.keys()]) {
+      const last = this.written.get(key)
+      if (!last || now - last.at >= this.writeEveryMs) this.track(this.flush(key))
+    }
+    await this.settled()
+  }
+
+  /** Writes everything buffered (on stop), backoffs aside. */
+  async flushAll(): Promise<void> {
+    this.backoff.clear()
+    for (const key of [...this.pending.keys()]) this.track(this.flush(key))
+    await this.settled()
+  }
+
+  start(): void {
+    if (this.timer) return
+    this.timer = setInterval(() => void this.flushDue().catch((cause) => this.log(cause)), this.flushEveryMs)
+    ;(this.timer as { unref?: () => void }).unref?.()
+  }
+
+  /** Stops the timer and writes what is buffered, giving up after `timeoutMs` (a store that hangs never holds shutdown). */
+  async stop(timeoutMs = 5_000): Promise<void> {
+    if (this.timer) clearInterval(this.timer)
+    this.timer = undefined
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const late = new Promise<void>((resolve) => (timer = setTimeout(() => (this.log(new Error(`not all activity written within ${timeoutMs} ms of stop`)), resolve()), timeoutMs)))
+    await Promise.race([this.flushAll().catch((cause) => this.log(cause)), late])
+    clearTimeout(timer)
+  }
+
+  /** The user's sessions touched within 30 days, with buckets of the last 24 h. Reads only: expired ones are swept later. */
+  async list(userID: string): Promise<Record<string, ActivityEntry>> {
+    const now = this.now()
+    const { live, stale } = await this.scan(userID, now)
+    if (stale) this.track(this.sweepThrottled(userID, now))
+    const out: Record<string, ActivityEntry> = {}
+    for (const { key, value } of live) out[key] = entryOf(value, now)
+    return out
+  }
+
+  /** Deletes the user's expired records, and the least recently updated past perUser. */
+  async sweep(userID: string): Promise<void> {
+    const { drop } = await this.scan(userID, this.now())
+    for (const { key, version } of drop) await this.state.delete(userID, HUMAN_ACTIVITY_COLLECTION, key, { ifVersion: version }).catch(() => {})
+  }
+
+  private async sweepThrottled(userID: string, now: number): Promise<void> {
+    const last = this.swept.get(userID)
+    if (last !== undefined && now - last < L.sweepEveryMs) return
+    remember(this.swept, userID, now, L.tracked)
+    await this.sweep(userID).catch((cause) => this.log(cause))
+  }
+
+  private async scan(userID: string, now: number): Promise<{ live: Array<{ key: string; value: ActivityRecord }>; drop: Array<{ key: string; version: number }>; stale: boolean }> {
+    const cutoff = now - L.keepMs
+    const live: Array<{ key: string; version: number; value: ActivityRecord }> = []
+    const drop: Array<{ key: string; version: number }> = []
+    for (const entry of await this.state.list<ActivityRecord>(userID, HUMAN_ACTIVITY_COLLECTION)) {
+      const u = entry.value?.u
+      if (typeof u === "number" && u >= cutoff && Array.isArray(entry.value.b)) live.push(entry)
+      else drop.push(entry)
+    }
+    live.sort((a, b) => b.value.u - a.value.u)
+    if (live.length > L.perUser) drop.push(...live.splice(L.perUser))
+    return { live, drop, stale: drop.length > 0 }
+  }
+
+  private track(work: Promise<unknown>): void {
+    const done: Promise<unknown> = work.catch((cause) => this.log(cause)).finally(() => this.running.delete(done))
+    this.running.add(done)
+  }
+
+  private key(userID: string, sessionID: string): string {
+    return `${userID}\n${sessionID}`
+  }
+
+  /**
+   * The session's buffer entry. When the buffer is full, a human touch that stays buffered takes the place of the
+   * oldest entry that holds only agent work (its counts are lost); agent work, or a human touch with no such entry, is
+   * dropped. A "passing" touch (written out at once, so it leaves the buffer right away) evicts nothing.
+   */
+  private pendingOf(userID: string, sessionID: string, mode: "agent" | "human" | "passing" = "agent"): Pending | undefined {
+    const key = this.key(userID, sessionID)
+    let p = this.pending.get(key)
+    if (!p) {
+      if (this.pending.size >= this.tracked && mode !== "passing") {
+        if (mode === "agent") return undefined
+        const agentOnly = [...this.pending].find(([, q]) => q.acted === undefined && q.viewed === undefined)
+        if (!agentOnly) return undefined
+        this.pending.delete(agentOnly[0])
+      }
+      p = { userID, sessionID, deltas: new Map() }
+      this.pending.set(key, p)
+    }
+    return p
+  }
+
+  private count(p: Pending, at: number, lane: 0 | 1 | 2): void {
+    const slot = slotOf(at)
+    const counts = p.deltas.get(slot) ?? [0, 0, 0]
+    counts[lane]++
+    p.deltas.set(slot, counts)
+  }
+
+  /** flush would write the session now (no backoff, the store not busy) rather than leave it queued. */
+  private writable(key: string, now: number): boolean {
+    const backoff = this.backoff.get(key)
+    return !(backoff && now < backoff.until) && this.inFlight < L.inFlight
+  }
+
+  /** Writes one session's buffered activity, merged into the stored record; on failure it goes back to the queue. */
+  private async flush(key: string): Promise<void> {
+    const p = this.pending.get(key)
+    if (!p) return
+    const now = this.now()
+    if (!this.writable(key, now)) return // backing off, or the store is busy: stays queued for the timer
+    this.pending.delete(key)
+    remember(this.written, key, { at: now, action: p.acted !== undefined || this.written.get(key)?.action === true }, L.tracked)
+    this.inFlight++
+    let wrote = false
+    try {
+      for (let attempt = 0; attempt < 5 && !wrote; attempt++) {
+        const stored = await this.state.get<ActivityRecord>(p.userID, HUMAN_ACTIVITY_COLLECTION, p.sessionID)
+        const next = merge(stored?.value, p, now)
+        const result = await this.state.put<ActivityRecord>(p.userID, HUMAN_ACTIVITY_COLLECTION, p.sessionID, next, { ifVersion: stored?.version ?? 0 })
+        if (!result.ok) continue
+        wrote = true
+        const written = this.written.get(key)
+        if (written && next.a !== undefined) written.action = true
+        this.backoff.delete(key)
+        this.onChange?.(p.userID, p.sessionID, entryOf(next, now))
+      }
+      if (!wrote) throw new Error(`version conflicts on ${p.sessionID}`)
+    } catch (cause) {
+      this.requeue(key, p, now)
+      this.log(cause)
+    } finally {
+      this.inFlight--
+    }
+    if (wrote) this.track(this.sweepThrottled(p.userID, now))
+  }
+
+  /** Puts a failed write's activity back (merged with what came meanwhile) and backs the session off. */
+  private requeue(key: string, failed: Pending, now: number): void {
+    this.written.delete(key)
+    const failures = (this.backoff.get(key)?.failures ?? 0) + 1
+    remember(this.backoff, key, { until: now + Math.min(L.maxRetryMs, L.retryMs * 2 ** (failures - 1)), failures }, L.tracked)
+    const p = this.pendingOf(failed.userID, failed.sessionID, failed.acted !== undefined || failed.viewed !== undefined ? "human" : "agent")
+    if (!p) return
+    if (failed.acted !== undefined && (p.acted === undefined || failed.acted > p.acted)) {
+      p.acted = failed.acted
+      p.actKind = failed.actKind
+    }
+    if (failed.viewed !== undefined && (p.viewed === undefined || failed.viewed > p.viewed)) p.viewed = failed.viewed
+    for (const [slot, [h, t, x]] of failed.deltas) {
+      const counts = p.deltas.get(slot) ?? [0, 0, 0]
+      counts[0] += h
+      counts[1] += t
+      counts[2] += x
+      p.deltas.set(slot, counts)
+    }
+  }
+
+  private log(cause: unknown): void {
+    const now = Date.now()
+    if (now - this.lastLogged < 60_000) return
+    this.lastLogged = now
+    console.error(`[hub] human activity: ${cause instanceof Error ? cause.message : String(cause)} (kept queued, retried later)`)
+  }
+}
+
+/** The stored record with a session's buffered activity added. */
+function merge(stored: ActivityRecord | undefined, p: Pending, now: number): ActivityRecord {
+  const buckets = new Map<number, Bucket>()
+  for (const b of Array.isArray(stored?.b) ? stored.b : []) if (Array.isArray(b) && b.length === 4) buckets.set(b[0], [...b] as Bucket)
+  for (const [slot, [h, t, x]] of p.deltas) {
+    const b = buckets.get(slot) ?? [slot, 0, 0, 0]
+    b[1] += h
+    b[2] += t
+    b[3] += x
+    buckets.set(slot, b)
+  }
+  let a = stored?.a
+  let k = stored?.k
+  if (p.acted !== undefined && (a === undefined || p.acted >= a)) {
+    a = p.acted
+    k = p.actKind
+  }
+  const v = Math.max(stored?.v ?? Number.NEGATIVE_INFINITY, p.viewed ?? Number.NEGATIVE_INFINITY)
+  return { ...(a !== undefined && k ? { a, k } : {}), ...(Number.isFinite(v) ? { v } : {}), b: recent([...buckets.values()], now), u: now }
+}
+
+/** The buckets of the last 24 h, oldest first. */
+function recent(buckets: Bucket[], now: number): Bucket[] {
+  const from = slotOf(now) - (L.buckets - 1) * L.bucketMs
+  return buckets.filter((b) => b[0] >= from).sort((a, b) => a[0] - b[0])
+}
+
+function entryOf(record: ActivityRecord, now: number): ActivityEntry {
+  const a = typeof record.a === "number" && record.k && (HUMAN_KINDS as readonly string[]).includes(record.k) ? record.a : undefined
+  const v = typeof record.v === "number" ? record.v : undefined
+  const last = Math.max(a ?? Number.NEGATIVE_INFINITY, v ?? Number.NEGATIVE_INFINITY)
+  const shown: { at: number; kind: HumanKind } | undefined =
+    a !== undefined && (v === undefined || last - a <= L.actionShownMs) ? { at: a, kind: record.k! } : v !== undefined ? { at: v, kind: "view" } : undefined
+  return { ...(shown ? { at: shown.at, kind: shown.kind, last } : {}), buckets: recent(record.b.map((b) => [...b] as Bucket), now) }
+}
+
+function remember<K, V>(map: Map<K, V>, key: K, value: V, max: number): void {
+  map.delete(key)
+  map.set(key, value)
+  if (map.size > max) map.delete(map.keys().next().value!)
+}
+
+export interface HumanActivityRouting {
+  /** The session's owner (its tenant); undefined when unknown. */
+  readonly tenant: (sessionID: string) => string | undefined
+  /** The root of the session's tree (activity is per root session). */
+  readonly root: (sessionID: string) => string
+}
+
+/**
+ * The shared action executor with "touched by me": the user's own prompts the hub carries (the console's Send, a
+ * user's /api/agent prompt) are prompt-web actions on the root session, recorded once the prompt reached the session;
+ * a launch's first prompt (intent "first") and a Concierge proposal the user only approved (intent false) are not.
+ * The spoke's report of the same prompt is marked carried (or origin hub), so it is never counted again.
+ */
+export function withHumanActivity<A extends Pick<Actions, "prompt">>(actions: A, activity: Pick<HumanActivity, "human">, routing: HumanActivityRouting): A {
+  return {
+    ...actions,
+    async prompt(input: PromptInput) {
+      const result = await actions.prompt(input)
+      if (result.outcome === "done" && input.intent !== "first" && input.intent !== false) {
+        const userID = routing.tenant(input.sessionID)
+        if (userID !== undefined) activity.human(userID, routing.root(input.sessionID), "prompt-web")
+      }
+      return result
+    },
+  }
+}

package/src/central/llm/chat.ts

@@ -0,0 +1,133 @@
+// The hub's own small model client (context cards, decision 9604b0a1): ONE OpenAI-compatible chat completion
+// (POST {baseURL}/chat/completions), deterministic (temperature 0), bounded (max_tokens, a timeout), optionally
+// asking for a JSON object. Provider-agnostic: OpenRouter and any OpenAI-compatible server work. The key is read
+// per call (settings changes apply at once) and never appears in errors. fetch is injectable (tests never touch
+// the network).
+
+/**
+ * What failed: "provider" (the model service: 401/403/408/429/5xx, network, timeout, no key), "request" (another 4xx:
+ * this request), "content" (the answer: none, or cut by the token limit). Only provider errors trip the hub breaker.
+ */
+export type ChatErrorKind = "provider" | "request" | "content"
+
+const PROVIDER_STATUSES: ReadonlySet<number> = new Set([401, 403, 408, 429])
+
+export class ChatError extends Error {
+  readonly kind: ChatErrorKind
+  constructor(
+    message: string,
+    readonly status?: number,
+    /** What the failed call used, when the upstream said (counted against the budget). */
+    readonly usage?: ChatUsage,
+    kind?: ChatErrorKind,
+  ) {
+    super(message)
+    this.name = "ChatError"
+    this.kind = kind ?? (status === undefined || status >= 500 || PROVIDER_STATUSES.has(status) ? "provider" : "request")
+  }
+}
+
+export interface ChatRequest {
+  readonly model: string
+  readonly system: string
+  readonly user: string
+  readonly maxTokens: number
+  /** Ask for a JSON object (response_format json_object). */
+  readonly json?: boolean
+}
+
+export interface ChatUsage {
+  readonly inputTokens: number
+  readonly outputTokens: number
+}
+
+export interface ChatResult {
+  readonly text: string
+  /** The model that answered (the upstream's, else the one asked for). */
+  readonly model: string
+  readonly usage: ChatUsage
+}
+
+/** What the context cards need of a model: one completion. Tests inject fakes. */
+export interface ChatClient {
+  complete(request: ChatRequest, signal?: AbortSignal): Promise<ChatResult>
+}
+
+export interface OpenAICompatibleChatOptions {
+  readonly baseURL: string
+  readonly apiKey: () => Promise<string | undefined>
+  readonly fetch?: typeof globalThis.fetch
+  /** Per request (default 30 s). */
+  readonly timeoutMs?: number
+}
+
+export const CHAT_TIMEOUT_MS = 30_000
+/** Upstream error detail kept in a ChatError (bounded; keys scrubbed). */
+const DETAIL_MAX = 300
+
+export class OpenAICompatibleChat implements ChatClient {
+  private readonly fetch: typeof globalThis.fetch
+  private readonly baseURL: string
+
+  constructor(private readonly options: OpenAICompatibleChatOptions) {
+    this.fetch = options.fetch ?? globalThis.fetch
+    this.baseURL = options.baseURL.replace(/\/+$/, "")
+  }
+
+  async complete(request: ChatRequest, signal?: AbortSignal): Promise<ChatResult> {
+    const key = await this.options.apiKey()
+    if (!key) throw new ChatError("No API key for the context card model")
+    const timeout = AbortSignal.timeout(this.options.timeoutMs ?? CHAT_TIMEOUT_MS)
+    const send = (json: boolean) => this.send(request, key, json, signal ? AbortSignal.any([signal, timeout]) : timeout)
+    let response = await send(request.json === true)
+    // Some OpenAI-compatible servers refuse response_format: once more without it (the prompt still asks for JSON).
+    if (request.json && response.status === 400) {
+      await response.text().catch(() => "")
+      response = await send(false)
+    }
+    if (!response.ok) {
+      const detail = await response.text().catch(() => "")
+      throw new ChatError(`Model request failed (${response.status}): ${scrub(detail, key)}`, response.status)
+    }
+    const json = (await response.json().catch(() => undefined)) as
+      | { model?: unknown; choices?: Array<{ message?: { content?: unknown }; finish_reason?: unknown }>; usage?: { prompt_tokens?: unknown; completion_tokens?: unknown } }
+      | undefined
+    const usage = { inputTokens: count(json?.usage?.prompt_tokens), outputTokens: count(json?.usage?.completion_tokens) }
+    const choice = json?.choices?.[0]
+    const content = choice?.message?.content
+    if (typeof content !== "string") throw new ChatError("The model answered without a message", undefined, usage, "content")
+    // A reasoning model can spend every token before it answers.
+    if (!content.trim() && choice?.finish_reason === "length") throw new ChatError("The model ran out of tokens before answering", undefined, usage, "content")
+    return { text: content, model: typeof json?.model === "string" && json.model ? json.model : request.model, usage }
+  }
+
+  private async send(request: ChatRequest, key: string, json: boolean, signal: AbortSignal): Promise<Response> {
+    const body = {
+      model: request.model,
+      messages: [
+        { role: "system", content: request.system },
+        { role: "user", content: request.user },
+      ],
+      max_tokens: request.maxTokens,
+      temperature: 0,
+      ...(json ? { response_format: { type: "json_object" } } : {}),
+    }
+    try {
+      return await this.fetch(`${this.baseURL}/chat/completions`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal,
+      })
+    } catch (cause) {
+      throw new ChatError(`Model request failed: ${scrub(cause instanceof Error ? cause.message : String(cause), key)}`)
+    }
+  }
+}
+
+const count = (n: unknown) => (typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.round(n) : 0)
+
+/** An upstream detail without the key, on one line, bounded. */
+function scrub(text: string, key: string): string {
+  return text.split(key).join("[key]").replace(/\s+/g, " ").trim().slice(0, DETAIL_MAX)
+}