@huynle/hub 0.9.2 → 0.10.0

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

@@ -0,0 +1,134 @@
+// The `pickup` context card (primary): "Pick up where you left off", a short summary the user (and the Concierge)
+// reads to get back into a session: what you were doing / last asked, what the agent did since, where it stands,
+// and the next step or what it waits on. Written by the context card model from a bounded, sanitised, redacted
+// view of the session (title unless a placeholder, intent, state, blockers, the newest transcript rows: tool rows
+// as names only). Its one-line headline is the session list's second line.
+import { redactCredentials } from "../../../packages/protocol/src/credentials.ts"
+import { isPlaceholderTitle } from "../agent/names"
+import type { CardDraft, CardInputs, ContextCardProvider, TranscriptRow } from "./types"
+
+/** The prompt's user message stays within this many characters. */
+export const PICKUP_PROMPT_MAX = 8000
+/** A transcript row in the prompt is cut to this many characters. */
+const PROMPT_ROW_MAX = 1200
+/** Room for reasoning models, which spend output tokens before they answer (the answer itself is ~150 tokens). */
+export const PICKUP_MAX_TOKENS = 800
+
+export const PICKUP_SYSTEM = [
+  "You write a short pick-up note for one AI coding session so its user (or their assistant) can get back into it fast.",
+  "Read the session facts and transcript excerpt. Be terse and factual; never invent work that is not in the excerpt.",
+  "Answer ONE JSON object only:",
+  '{"headline": "<= 90 characters: where the work stands now, e.g. \\"Login loop fixed; waiting for your review\\"",',
+  ' "summary": "<= 300 characters: what the user was doing or last asked, what the agent did since, and the current state",',
+  ' "next": "<= 120 characters: the next step, or what the session is waiting on (omit if nothing)"}',
+  "Write to the user as \"you\". No greetings, no markdown headings, no secrets.",
+].join("\n")
+
+const LABEL: Record<Exclude<TranscriptRow["kind"], "tool">, string> = { user: "User", assistant: "Agent", error: "Error", message: "Message" }
+
+/** Transcript rows as prompt lines, oldest first; consecutive tool rows fold into one "Tools: a, b" line. */
+function lines(rows: readonly TranscriptRow[]): string[] {
+  const out: string[] = []
+  let tools: string[] = []
+  const flush = () => {
+    if (tools.length) out.push(`Tools: ${tools.join(", ")}`)
+    tools = []
+  }
+  for (const row of rows) {
+    if (row.kind === "tool") {
+      if (row.name) tools.push(row.state === "failed" ? `${row.name} (failed)` : row.name)
+      continue
+    }
+    flush()
+    if (row.text) out.push(`${LABEL[row.kind]}: ${clip(row.text, PROMPT_ROW_MAX)}`)
+  }
+  flush()
+  return out
+}
+
+/** Credentials redacted, THEN cut: a secret straddling the limit never leaks a part. */
+const clip = (text: string, max: number) => redactCredentials(text).text.slice(0, max)
+
+export function buildPickupPrompt(inputs: CardInputs): { system: string; user: string } {
+  const head: string[] = []
+  if (!isPlaceholderTitle(inputs.title)) head.push(`Title: ${clip(inputs.title!, 200)}`)
+  if (inputs.intent) head.push(`Intent: ${clip(inputs.intent, 280)}`)
+  if (inputs.state) head.push(`State: ${clip(inputs.state, 20)}`)
+  if (inputs.blockers?.length) head.push(`Waiting on: ${clip(inputs.blockers.join("; "), 1000)}`)
+  const header = `${head.join("\n")}\n\nTranscript (oldest first):\n`
+  // Newest lines first until the budget is used, then back in order.
+  const kept: string[] = []
+  let used = header.length
+  for (const line of lines(inputs.transcript ?? []).reverse()) {
+    const clean = line
+    if (used + clean.length + 1 > PICKUP_PROMPT_MAX) break
+    kept.push(clean)
+    used += clean.length + 1
+  }
+  return { system: PICKUP_SYSTEM, user: `${header}${kept.reverse().join("\n")}`.slice(0, PICKUP_PROMPT_MAX) }
+}
+
+/** The model's answer as a draft: JSON {headline, summary, next?} (fenced or not); plain text: its first line. */
+export function parsePickup(text: string): CardDraft | undefined {
+  const raw = text.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "").trim()
+  if (!raw) return undefined
+  const start = raw.indexOf("{")
+  const end = raw.lastIndexOf("}")
+  if (start !== -1 && end > start) {
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(raw.slice(start, end + 1))
+    } catch {
+      parsed = undefined
+    }
+    if (parsed !== undefined) {
+      const answer = (typeof parsed === "object" && parsed !== null ? parsed : {}) as Record<string, unknown>
+      const str = (v: unknown) => (typeof v === "string" ? v.trim() : "")
+      const headline = str(answer.headline)
+      if (!headline) return undefined
+      const summary = str(answer.summary)
+      const next = str(answer.next)
+      return { headline, body: [summary, next ? `Next: ${next}` : ""].filter(Boolean).join("\n\n") }
+    }
+  }
+  // JSON the model cut or broke: its headline field when it can be read, else nothing (never the raw JSON).
+  if (/^[[{]/.test(raw)) {
+    const headline = /"headline"\s*:\s*"((?:[^"\\]|\\.)*)"/.exec(raw)?.[1]
+    if (headline === undefined) return undefined
+    let text: string
+    try {
+      text = JSON.parse(`"${headline}"`) as string
+    } catch {
+      return undefined
+    }
+    return text.trim() ? { headline: text.trim(), body: "" } : undefined
+  }
+  const first = raw.split("\n").map((l) => l.trim()).find(Boolean)
+  return first && !/[{}"]/.test(first.slice(0, 2)) ? { headline: first, body: "" } : undefined
+}
+
+export function pickupProvider(options: { readonly minIntervalMs?: number } = {}): ContextCardProvider {
+  return {
+    id: "pickup",
+    label: "Pick up where you left off",
+    version: 1,
+    primary: true,
+    usesModel: true,
+    triggers: ["turn-end", "blocked", "user-return", "sweep"],
+    minIntervalMs: options.minIntervalMs ?? 5 * 60_000,
+    needs: ["status", "intent", "transcript"],
+    async generate({ inputs, chat }) {
+      if (!chat) return undefined
+      if (!inputs.transcript?.length && !inputs.intent) return undefined
+      const { system, user } = buildPickupPrompt(inputs)
+      const answer = await chat.complete({ system, user, maxTokens: PICKUP_MAX_TOKENS, json: true })
+      const draft = parsePickup(answer.text)
+      if (!draft) return undefined
+      const fields = [
+        ...(inputs.state ? [{ label: "State", value: inputs.state }] : []),
+        ...(inputs.blockers?.length ? [{ label: "Waiting on", value: inputs.blockers.join("; ") }] : []),
+      ]
+      return { ...draft, ...(fields.length ? { fields } : {}), model: answer.model }
+    },
+  }
+}

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

@@ -0,0 +1,89 @@
+// The context card provider registry and the bounding of a provider's draft into a stored card. Card text is
+// untrusted (a model or a session wrote it): sanitised (control, ANSI, bidi, zero-width characters go), literal
+// credentials redacted, every field cut to CONTEXT_CARD_LIMITS. A draft without a headline is no card.
+import { redactCredentials } from "../../../packages/protocol/src/credentials.ts"
+import { CONTEXT_CARD_LIMITS, type ContextCard, type ContextCardField, type ContextCardProviderInfo, type ContextCardTrigger } from "../../protocol"
+import { sanitizeText } from "../agent/envelope"
+import type { CardDraft, ContextCardProvider } from "./types"
+
+const PROVIDER_ID = /^[a-z][a-z0-9-]{1,31}$/
+
+export class CardRegistry {
+  private readonly providers = new Map<string, ContextCardProvider>()
+
+  /** Adds a provider; throws on a bad or taken id, or a second primary. */
+  register(provider: ContextCardProvider): void {
+    if (!PROVIDER_ID.test(provider.id)) throw new Error(`Context card provider id ${JSON.stringify(provider.id)} must be 2–32 lowercase letters, digits or -`)
+    if (this.providers.has(provider.id)) throw new Error(`Context card provider ${provider.id} is registered already`)
+    if (provider.primary && this.primary()) throw new Error(`Context card provider ${provider.id}: ${this.primary()!.id} is the primary already`)
+    this.providers.set(provider.id, provider)
+  }
+
+  list(): ContextCardProvider[] {
+    return [...this.providers.values()]
+  }
+
+  get(id: string): ContextCardProvider | undefined {
+    return this.providers.get(id)
+  }
+
+  primary(): ContextCardProvider | undefined {
+    return this.list().find((p) => p.primary)
+  }
+
+  /** What clients see of the providers. */
+  info(): ContextCardProviderInfo[] {
+    return this.list().map((p) => ({ id: p.id, label: p.label, primary: p.primary === true, usesModel: p.usesModel === true }))
+  }
+}
+
+/** Sanitised, credentials redacted, cut to `max` code points. `lines`: newlines kept (runs of blank lines folded). */
+export function cardText(input: unknown, max: number, lines = false): string {
+  if (typeof input !== "string") return ""
+  // Redacted on the whole (bounded) text BEFORE the cut, so a secret straddling the limit never leaks a part.
+  let text = redactCredentials(sanitizeText(input.slice(0, 1024 * 1024))).text
+  text = lines ? text.replace(/[ \t]+/g, " ").replace(/ *\n */g, "\n").replace(/\n{3,}/g, "\n\n").trim() : text.replace(/\s+/g, " ").trim()
+  return Array.from(text).slice(0, max).join("").trimEnd()
+}
+
+function boundFields(fields: unknown): ContextCardField[] | undefined {
+  if (!Array.isArray(fields)) return undefined
+  const out: ContextCardField[] = []
+  for (const field of fields) {
+    if (out.length >= CONTEXT_CARD_LIMITS.fields) break
+    if (!field || typeof field !== "object") continue
+    const label = cardText((field as { label?: unknown }).label, CONTEXT_CARD_LIMITS.fieldLabel)
+    const value = cardText((field as { value?: unknown }).value, CONTEXT_CARD_LIMITS.fieldValue)
+    if (label && value) out.push({ label, value })
+  }
+  return out.length ? out : undefined
+}
+
+/** A provider's draft as a stored card (undefined when it has no headline). */
+export function boundCard(
+  provider: Pick<ContextCardProvider, "id" | "label" | "version" | "primary">,
+  sessionID: string,
+  draft: CardDraft | null | undefined,
+  meta: { readonly generatedAt: number; readonly inputsHash: string; readonly trigger: ContextCardTrigger; readonly basis?: readonly string[] },
+): ContextCard | undefined {
+  if (!draft || typeof draft !== "object") return undefined
+  const headline = cardText(draft.headline, CONTEXT_CARD_LIMITS.headline)
+  if (!headline) return undefined
+  const fields = boundFields(draft.fields)
+  const model = cardText(draft.model, CONTEXT_CARD_LIMITS.model)
+  return {
+    provider: provider.id,
+    sessionID,
+    title: cardText(draft.title, CONTEXT_CARD_LIMITS.title) || cardText(provider.label, CONTEXT_CARD_LIMITS.title),
+    headline,
+    body: cardText(draft.body, CONTEXT_CARD_LIMITS.body, true),
+    ...(fields ? { fields } : {}),
+    generatedAt: meta.generatedAt,
+    ...(model ? { model } : {}),
+    inputsHash: meta.inputsHash,
+    version: provider.version,
+    trigger: meta.trigger,
+    ...(meta.basis ? { basis: [...meta.basis] } : {}),
+    ...(provider.primary ? { primary: true as const } : {}),
+  }
+}

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

@@ -0,0 +1,37 @@
+// Context card agent route (docs/context-cards.md "API"):
+//
+//   GET /api/agent/sessions/:addr/context-cards → {sessionID, cards: ContextCard[], providers}
+//       users; app tokens holding sessions:read; session tokens (the session read rules, team-scoped when the hub
+//       has team discovery), exactly like the intent read. Another user's session is 404 not_found.
+//
+// None while cards are off for the user. The Concierge reads a session's cards here (and the primary headline rides its board). Card text is untrusted.
+import type { Directory, DirectoryEntry } from "../agent/directory"
+import type { AgentActor } from "../agent/actor"
+import { AGENT_PREFIX, type AgentRoute } from "../agent/routes"
+import type { TeamDiscovery } from "../teams/discovery"
+import type { ContextCardService } from "./service"
+
+export interface ContextCardRoutesDeps {
+  readonly cards: Pick<ContextCardService, "list" | "registry">
+  readonly directory: Directory
+  readonly discovery?: TeamDiscovery
+}
+
+export function contextCardRoutes(deps: ContextCardRoutesDeps): AgentRoute[] {
+  async function resolve(userID: string, actor: AgentActor, addr: string): Promise<DirectoryEntry> {
+    if (deps.discovery) return deps.discovery.resolveOne(await deps.discovery.census(userID, actor), addr)
+    return deps.directory.resolveOne(userID, addr)
+  }
+  return [
+    {
+      method: "GET",
+      path: `${AGENT_PREFIX}/sessions/:addr/context-cards`,
+      allow: { session: true, scope: "sessions:read" },
+      handle: async ({ user, actor, params }) => {
+        const entry = await resolve(user.id, actor, params.addr!)
+        const cards = await deps.cards.list(user.id, entry.sessionID)
+        return Response.json({ sessionID: entry.sessionID, cards, providers: deps.cards.registry.info() }, { headers: { "cache-control": "no-store" } })
+      },
+    },
+  ]
+}

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

@@ -0,0 +1,367 @@
+// The context card service (docs/context-cards.md): the registry with the built-in providers (pickup, changes),
+// the store, the daily budget, the engine, the human activity gate, the per-user setting, the model, and the
+// triggers http.ts feeds it:
+//   - journal appends (cardTriggerOf): a root session's turn ended (working → idle | error) → "turn-end";
+//     the tree went blocked (state blocked, or a blocker opened) → "blocked"
+//   - human turns and read marks (the user opened the session): human activity; after RETURN_GAP_MS without any
+//     (or the first time this process sees one) → "user-return"
+//   - the leader's sweep every SWEEP_MS: "sweep" for every session with recent human activity; and every
+//     PRUNE_EVERY_MS cards older than CARD_RETENTION_MS are dropped (a deleted session's cards go at once: forget)
+// Automatic triggers run on the "context-cards" leader only: other pods forward them (forward, a leader kick)
+// with the human activity time, so the leader's gate knows it.
+//
+// Opt-in (user decision 2026-11-08): cards are OFF for every user until that user turns them on in Settings; nothing
+// is gathered or sent to a model for a user who has not, even with a model configured. HUB_CONTEXT_CARDS=off (or
+// contextCards.enabled false) is the hub-wide kill switch over every user's choice.
+//
+// Privacy: while cards are off for a user (their setting or the kill switch) every read (console, primary headlines,
+// agent API, Concierge board) answers none and no card is stored or sent; turning them off deletes their stored cards.
+//
+// Human activity: the engine takes an injectable predicate (EngineDeps.humanActive). The hub gives the persisted
+// per-user activity (deps.lastHumanAt, src/central/human-activity.ts `last`, root sessions): active when the user
+// touched the session within HUMAN_ACTIVE_MS. Without it, the in-memory HumanActivity below (bounded) decides. The
+// in-memory map still tells a return after RETURN_GAP_MS ("user-return") and lists the sweep's recent sessions; in the
+// hub it is fed from the same human touches (prompts typed or sent, Voice, answers, explicit opens).
+import type { ContextCard, ContextCardProviderInfo, ContextCardTrigger } from "../../protocol"
+import { realTimers } from "../backend/memory-bus"
+import type { StateStore, Timers } from "../backend/types"
+import type { AgentEvent, EventInput } from "../agent/events"
+import { OpenAICompatibleChat, type ChatClient } from "../llm/chat"
+import { DailyBudget, DEFAULT_BUDGET, type BudgetUsage } from "./budget"
+import { changesProvider } from "./changes"
+import { resolveCardModel, type ContextCardsConfig, type KeySources } from "./config"
+import { ContextCardEngine, type CardModel, type RunOutcome } from "./engine"
+import { gatherInputs, type InputDeps } from "./inputs"
+import { pickupProvider } from "./pickup"
+import { CardRegistry } from "./registry"
+import { ContextCardStore } from "./store"
+
+/** A session the user touched within this long is "recently active" (automatic cards, the sweep). */
+export const HUMAN_ACTIVE_MS = 24 * 3_600_000
+/** A human touch after this long without one is a return ("user-return"). */
+export const RETURN_GAP_MS = 30 * 60_000
+export const SWEEP_MS = 30 * 60_000
+export const PRUNE_EVERY_MS = 6 * 3_600_000
+export const CARD_RETENTION_MS = 30 * 86_400_000
+const ACTIVITY_MAX = 10_000
+
+export type AutoTrigger = Exclude<ContextCardTrigger, "manual">
+
+/** The card trigger a journal event is, on which (root) session; undefined for most events. */
+export function cardTriggerOf(event: Pick<AgentEvent, "type" | "subject" | "data"> | null | undefined): { sessionID: string; trigger: "turn-end" | "blocked" } | undefined {
+  if (typeof event !== "object" || event === null) return undefined
+  const subject = event.subject ?? {}
+  const data = event.data ?? {}
+  const root = subject.rootID ?? subject.sessionID
+  if (typeof root !== "string" || !root) return undefined
+  if (event.type === "blocker.opened") return { sessionID: root, trigger: "blocked" }
+  if (event.type !== "session.changed" || subject.sessionID !== root) return undefined
+  if (data.state === "blocked") return { sessionID: root, trigger: "blocked" }
+  if ((data.state === "idle" || data.state === "error") && data.prev === "working") return { sessionID: root, trigger: "turn-end" }
+  return undefined
+}
+
+/** When the user last acted in each session (human turns, read marks), in memory, bounded. */
+export class HumanActivity {
+  private readonly now: () => number
+  private readonly max: number
+  /** `user\nsession` → at (insertion order = age). */
+  private readonly last = new Map<string, number>()
+
+  constructor(options: { readonly now?: () => number; readonly max?: number } = {}) {
+    this.now = options.now ?? Date.now
+    this.max = options.max ?? ACTIVITY_MAX
+  }
+
+  /** The user acted now; `returned` after RETURN_GAP_MS without activity (or none known). */
+  touch(userID: string, sessionID: string): { returned: boolean } {
+    const at = this.now()
+    const before = this.last.get(`${userID}\n${sessionID}`)
+    this.note(userID, sessionID, at)
+    return { returned: before === undefined || at - before > RETURN_GAP_MS }
+  }
+
+  /** Records activity seen elsewhere (another pod's forward). */
+  note(userID: string, sessionID: string, at: number): void {
+    const key = `${userID}\n${sessionID}`
+    if ((this.last.get(key) ?? 0) > at) return
+    this.last.delete(key)
+    this.last.set(key, at)
+    if (this.last.size > this.max) this.last.delete(this.last.keys().next().value!)
+  }
+
+  lastAt(userID: string, sessionID: string): number | undefined {
+    return this.last.get(`${userID}\n${sessionID}`)
+  }
+
+  active(userID: string, sessionID: string): boolean {
+    const at = this.lastAt(userID, sessionID)
+    return at !== undefined && this.now() - at <= HUMAN_ACTIVE_MS
+  }
+
+  *recent(): Iterable<{ userID: string; sessionID: string }> {
+    const now = this.now()
+    for (const [key, at] of this.last) {
+      if (now - at > HUMAN_ACTIVE_MS) continue
+      const [userID, sessionID] = key.split("\n") as [string, string]
+      yield { userID, sessionID }
+    }
+  }
+
+  forget(userID: string, sessionID: string): void {
+    this.last.delete(`${userID}\n${sessionID}`)
+  }
+}
+
+export const CARD_SETTINGS = "context-card-settings"
+
+/** The per-user setting (StateStore `context-card-settings`, key "settings"): {enabled}; unset is off (opt-in). */
+export class CardSettings {
+  constructor(private readonly deps: { readonly state: StateStore }) {}
+
+  async stored(userID: string): Promise<boolean | undefined> {
+    const value = (await this.deps.state.get<{ enabled?: unknown }>(userID, CARD_SETTINGS, "settings"))?.value
+    return typeof value?.enabled === "boolean" ? value.enabled : undefined
+  }
+
+  async enabled(userID: string, fallback: boolean): Promise<boolean> {
+    return (await this.stored(userID)) ?? fallback
+  }
+
+  /** The user turned context cards on (opt-in: never by default). */
+  async optedIn(userID: string): Promise<boolean> {
+    return (await this.stored(userID)) === true
+  }
+
+  async set(userID: string, enabled: boolean): Promise<void> {
+    await this.deps.state.put(userID, CARD_SETTINGS, "settings", { enabled })
+  }
+}
+
+/** The journal event of a new card: its provider, version and primary flag; never the text. */
+export const contextCardEvent = (card: ContextCard): EventInput => ({
+  type: "session.contextCard",
+  family: "session",
+  subject: { sessionID: card.sessionID },
+  data: { provider: card.provider, version: card.version, primary: card.primary === true },
+})
+
+export interface ContextCardsView {
+  readonly cards: ContextCard[]
+  readonly providers: ContextCardProviderInfo[]
+  /** Cards are on for this user (hub kill switch and their setting). */
+  readonly enabled: boolean
+  /** A model is configured (model providers can run). */
+  readonly configured: boolean
+}
+
+export interface ContextCardSettingsView {
+  /** The user's effective setting. */
+  readonly enabled: boolean
+  /** The hub allows cards (HUB_CONTEXT_CARDS / contextCards.enabled). */
+  readonly available: boolean
+  readonly configured: boolean
+  readonly model?: { readonly provider: string; readonly model: string; readonly keySource: string }
+  readonly usage: BudgetUsage
+}
+
+export interface ContextCardServiceDeps {
+  readonly state: StateStore
+  readonly config: ContextCardsConfig
+  /** The speech keys (read per call: settings changes apply at once). */
+  readonly keySources: () => KeySources
+  /** Overrides the model client (tests). */
+  readonly chat?: ChatClient
+  readonly fetch?: typeof globalThis.fetch
+  readonly inputs: InputDeps
+  readonly isLeader: () => boolean
+  /** Another pod's automatic trigger goes to the leader (a leader kick). */
+  readonly forward?: (userID: string, sessionID: string, trigger: AutoTrigger, humanAt?: number) => void
+  readonly onCard: (userID: string, card: ContextCard) => void
+  readonly autoName?: (userID: string, sessionID: string) => Promise<void>
+  /** The session still exists (not deleted) right before a card is stored. */
+  readonly exists?: (userID: string, sessionID: string) => Promise<boolean>
+  /** The live title, re-checked right before an auto name. */
+  readonly title?: (userID: string, sessionID: string) => string | undefined
+  /** When the user last touched the (root) session, persisted (the automatic cards' gate); in memory without it. */
+  readonly lastHumanAt?: (userID: string, sessionID: string) => Promise<number | undefined> | number | undefined
+  readonly users?: () => Promise<Iterable<string>>
+  readonly now?: () => number
+  readonly timers?: Timers
+  readonly debounceMs?: number
+  readonly log?: (message: string) => void
+}
+
+export class ContextCardService {
+  readonly registry = new CardRegistry()
+  readonly store: ContextCardStore
+  readonly budget: DailyBudget
+  readonly engine: ContextCardEngine
+  readonly activity: HumanActivity
+  readonly settings: CardSettings
+  private readonly now: () => number
+  private readonly timers: Timers
+  private timer: unknown
+  private lastPrune = 0
+  private client: { key: string; baseURL: string; chat: ChatClient } | undefined
+
+  constructor(private readonly deps: ContextCardServiceDeps) {
+    this.now = deps.now ?? Date.now
+    this.timers = deps.timers ?? realTimers
+    this.registry.register(pickupProvider())
+    this.registry.register(changesProvider())
+    this.store = new ContextCardStore({ state: deps.state })
+    this.budget = new DailyBudget({ state: deps.state, now: this.now, limits: { ...DEFAULT_BUDGET, ...deps.config.budget } })
+    this.activity = new HumanActivity({ now: this.now })
+    this.settings = new CardSettings({ state: deps.state })
+    const lastHumanAt = deps.lastHumanAt
+    this.engine = new ContextCardEngine({
+      registry: this.registry,
+      store: this.store,
+      budget: this.budget,
+      inputs: (userID, sessionID, needs) => gatherInputs(deps.inputs, userID, sessionID, needs),
+      humanActive: lastHumanAt
+        ? async (userID, sessionID) => this.now() - ((await lastHumanAt(userID, sessionID)) ?? Number.NEGATIVE_INFINITY) <= HUMAN_ACTIVE_MS
+        : (userID, sessionID) => this.activity.active(userID, sessionID),
+      enabled: (userID) => this.enabled(userID),
+      model: () => this.model(),
+      isLeader: deps.isLeader,
+      onCard: deps.onCard,
+      ...(deps.autoName ? { autoName: deps.autoName } : {}),
+      ...(deps.exists ? { exists: deps.exists } : {}),
+      ...(deps.title ? { title: deps.title } : {}),
+      recent: () => this.activity.recent(),
+      now: this.now,
+      timers: this.timers,
+      ...(deps.debounceMs !== undefined ? { debounceMs: deps.debounceMs } : {}),
+      ...(deps.log ? { log: deps.log } : {}),
+    })
+  }
+
+  /** The hub-wide kill switch (HUB_CONTEXT_CARDS=off, contextCards.enabled false). */
+  available(): boolean {
+    return this.deps.config.enabled !== false
+  }
+
+  private resolved() {
+    return resolveCardModel(this.deps.config, this.deps.keySources())
+  }
+
+  /** The model, when one is configured (an injected client counts). */
+  model(): CardModel | undefined {
+    if (!this.available()) return undefined
+    const resolved = this.resolved()
+    if (this.deps.chat) return { client: this.deps.chat, model: resolved?.model ?? "test" }
+    if (!resolved) return undefined
+    if (this.client?.key !== resolved.apiKey || this.client.baseURL !== resolved.baseURL) {
+      const apiKey = resolved.apiKey
+      this.client = { key: apiKey, baseURL: resolved.baseURL, chat: new OpenAICompatibleChat({ baseURL: resolved.baseURL, apiKey: async () => apiKey, ...(this.deps.fetch ? { fetch: this.deps.fetch } : {}) }) }
+    }
+    return { client: this.client.chat, model: resolved.model }
+  }
+
+  configured(): boolean {
+    return this.model() !== undefined
+  }
+
+  /** Cards on for a user: the hub allows them and the user opted in (off by default, model or not). */
+  async enabled(userID: string): Promise<boolean> {
+    return this.available() && (await this.settings.optedIn(userID))
+  }
+
+  /** An automatic trigger: run here on the leader, else forwarded to it. */
+  trigger(userID: string, sessionID: string, trigger: AutoTrigger): void {
+    if (this.deps.isLeader()) this.engine.trigger(userID, sessionID, trigger)
+    else this.deps.forward?.(userID, sessionID, trigger, this.activity.lastAt(userID, sessionID))
+  }
+
+  /** A forwarded trigger, on the leader. */
+  forwarded(userID: string, sessionID: string, trigger: AutoTrigger, humanAt?: number): void {
+    if (humanAt !== undefined) this.activity.note(userID, sessionID, humanAt)
+    this.engine.trigger(userID, sessionID, trigger)
+  }
+
+  /** A journal append (the AgentEvents onAppend path). Never throws. */
+  onEvent(userID: string, event: Pick<AgentEvent, "type" | "subject" | "data">): void {
+    const found = cardTriggerOf(event)
+    if (found) this.trigger(userID, found.sessionID, found.trigger)
+  }
+
+  /** The user acted in a session (a human turn, a read mark): after a gap, its user-return cards run. */
+  human(userID: string, sessionID: string): void {
+    if (this.activity.touch(userID, sessionID).returned) this.trigger(userID, sessionID, "user-return")
+  }
+
+  async forget(userID: string, sessionID: string): Promise<void> {
+    this.activity.forget(userID, sessionID)
+    await this.engine.forget(userID, sessionID)
+  }
+
+  async view(userID: string, sessionID: string): Promise<ContextCardsView> {
+    const enabled = await this.enabled(userID)
+    return { cards: enabled ? await this.store.list(userID, sessionID) : [], providers: this.registry.info(), enabled, configured: this.configured() }
+  }
+
+  /** A session's cards, none while cards are off for the user (kill switch or their setting): every read goes here. */
+  async list(userID: string, sessionID: string): Promise<ContextCard[]> {
+    return (await this.enabled(userID)) ? this.store.list(userID, sessionID) : []
+  }
+
+  /** A manual refresh: deduped, rate limited, unchanged inputs skipped unless forced. */
+  refresh(userID: string, sessionID: string, provider: string, options: { readonly force?: boolean } = {}): Promise<RunOutcome> {
+    return this.engine.refresh(userID, sessionID, provider, options)
+  }
+
+  /** The primary card of each session (the list's second line, the Concierge board); none while cards are off. */
+  async primaries(userID: string, sessionIDs: Iterable<string>): Promise<Map<string, ContextCard>> {
+    return (await this.enabled(userID)) ? this.store.primaries(userID, sessionIDs) : new Map()
+  }
+
+  async settingsView(userID: string): Promise<ContextCardSettingsView> {
+    const resolved = this.available() ? this.resolved() : undefined
+    return {
+      enabled: await this.enabled(userID),
+      available: this.available(),
+      configured: this.configured(),
+      ...(resolved ? { model: { provider: resolved.provider, model: resolved.model, keySource: resolved.keySource } } : {}),
+      usage: await this.budget.usage(userID),
+    }
+  }
+
+  /** Turning cards off deletes the user's stored cards (privacy): turning them on again starts fresh. */
+  async setEnabled(userID: string, enabled: boolean): Promise<ContextCardSettingsView> {
+    await this.settings.set(userID, enabled)
+    if (!enabled) await this.store.clear(userID)
+    return this.settingsView(userID)
+  }
+
+  /** The leader's loop: the sweep every SWEEP_MS, retention every PRUNE_EVERY_MS. */
+  start(): void {
+    if (this.timer !== undefined) return
+    this.timer = this.timers.set(() => {
+      this.timer = undefined
+      void this.tick().finally(() => this.start())
+    }, SWEEP_MS)
+  }
+
+  stop(): void {
+    if (this.timer !== undefined) this.timers.clear(this.timer)
+    this.timer = undefined
+  }
+
+  /** One sweep (and retention when due). */
+  async tick(): Promise<void> {
+    this.engine.sweep()
+    if (this.now() - this.lastPrune < PRUNE_EVERY_MS || !this.deps.users) return
+    this.lastPrune = this.now()
+    try {
+      for (const userID of await this.deps.users()) await this.store.prune(userID, this.now() - CARD_RETENTION_MS)
+    } catch (cause) {
+      ;(this.deps.log ?? console.error)(`[hub] context card retention failed: ${(cause as Error).message}`)
+    }
+  }
+
+  settled(): Promise<void> {
+    return this.engine.settled()
+  }
+}