privateer-agent 0.1.0

package/src/engine/QueryEngine.ts

@@ -0,0 +1,399 @@
+import {
+  streamText,
+  generateText,
+  generateObject,
+  stepCountIs,
+  type ModelMessage,
+  type ToolSet,
+} from "ai";
+import { z } from "zod";
+import { type EngineEvent, type UsageTotals, emptyUsage, addUsage } from "./events.ts";
+import { type RouteSet, selectRoute, requiredModalities } from "./router.ts";
+import { redactText } from "../util/redact.ts";
+import { describeError, type DescribedError } from "./errors.ts";
+
+// Structured shape for compaction so the summary preserves the parts that matter for
+// continuing the work, rather than a free-form blob.
+const CompactionSchema = z.object({
+  goals: z.string().describe("The user's overall goals for this session."),
+  decisions: z.array(z.string()).describe("Key decisions, approaches, and findings so far."),
+  filesTouched: z.array(z.string()).describe("File paths created or modified, each with a short note."),
+  openThreads: z.array(z.string()).describe("Unfinished tasks, next steps, and open questions."),
+});
+
+export function formatCompaction(o: z.infer<typeof CompactionSchema>): string {
+  const list = (items: string[]) => (items.length ? items.map((i) => `- ${i}`).join("\n") : "- (none)");
+  return [
+    `Goals: ${o.goals}`,
+    `Decisions:\n${list(o.decisions)}`,
+    `Files touched:\n${list(o.filesTouched)}`,
+    `Open threads:\n${list(o.openThreads)}`,
+  ].join("\n\n");
+}
+
+export interface QueryEngineOptions {
+  // The model routes for this session. `routes.default` is always used unless a
+  // turn's data/shape selects a specialized route (see src/engine/router.ts).
+  // Per-route flags (cacheControl/thinkingBudget) travel on each Route. Compaction
+  // always runs on the default route.
+  routes: RouteSet;
+  system: string;
+  tools: ToolSet;
+  maxSteps: number;
+  // Approx token budget; when the estimated context exceeds budget*ratio before a
+  // turn, older history is summarized away. 0/undefined disables auto-compaction.
+  contextBudget?: number;
+  compactRatio?: number;
+}
+
+// Number of most-recent messages kept verbatim when compacting.
+const KEEP_RECENT = 6;
+
+// How many times to auto-retry a turn that failed transiently (rate limit, 5xx,
+// network) before any output streamed. Fatal errors (auth/billing/data-policy/bad
+// model) are never retried — describeError leaves their `retryable` flag unset.
+const MAX_RETRIES = 3;
+
+// The agent loop. Each `send` streams one user turn through the model, letting the
+// AI SDK run the multi-step tool loop internally (executing our tools' execute()),
+// while we translate the raw stream into normalized EngineEvents and accumulate usage.
+// History persists on the instance so follow-up turns keep context. A turn can be
+// interrupted via an AbortSignal; partial output is still persisted to history.
+export class QueryEngine {
+  readonly messages: ModelMessage[] = [];
+  usage: UsageTotals = emptyUsage();
+
+  constructor(private readonly opts: QueryEngineOptions) {}
+
+  // Current context-window occupancy: estimated tokens in history over the budget
+  // that triggers compaction. Drives the Claude-Code-style "% of context" readout.
+  // `budget` is 0 when auto-compaction is disabled.
+  contextUsage(): { used: number; budget: number } {
+    return { used: estimateTokens(this.messages), budget: this.opts.contextBudget ?? 0 };
+  }
+
+  async *send(
+    userText: string,
+    signal?: AbortSignal,
+    attachments?: { data: string; mediaType: string; modality?: string }[],
+  ): AsyncGenerator<EngineEvent, void, void> {
+    // Auto-compact before the turn if the context has grown past the budget.
+    if (this.shouldCompact()) {
+      const res = await this.compact();
+      if (res) yield { type: "compacted", before: res.before, after: res.after };
+    }
+
+    if (attachments && attachments.length > 0) {
+      this.messages.push({
+        role: "user",
+        content: [
+          { type: "text", text: userText },
+          // Images go as image parts; documents/audio/video as generic file parts.
+          ...attachments.map((a) =>
+            a.modality === "image" || a.mediaType.startsWith("image/")
+              ? ({ type: "image" as const, image: a.data, mediaType: a.mediaType })
+              : ({ type: "file" as const, data: a.data, mediaType: a.mediaType })),
+        ],
+      });
+    } else {
+      this.messages.push({ role: "user", content: userText });
+    }
+
+    // Pick the model for this turn from its data/shape. Modality requirements are
+    // sticky over the whole conversation so attachment history never gets replayed to
+    // a model that can't accept it.
+    const sel = selectRoute(this.opts.routes, {
+      modalities: requiredModalities(this.messages),
+      estTokens: estimateTokens(this.messages),
+      promptChars: userText.length,
+    });
+    if (sel.name !== "default" || (sel.missing && sel.missing.length > 0)) {
+      yield {
+        type: "routed",
+        route: sel.name,
+        label: sel.route.label,
+        reason: sel.reason,
+        missing: sel.missing,
+      };
+    }
+    const route = sel.route;
+
+    let result;
+    try {
+      result = streamText({
+        model: route.model,
+        system: this.opts.system,
+        messages: route.cacheControl ? withCacheBreakpoints(this.messages) : this.messages,
+        tools: this.opts.tools,
+        stopWhen: stepCountIs(this.opts.maxSteps),
+        abortSignal: signal,
+        // Re-place the rolling cache breakpoint on every internal tool-loop step.
+        // streamText runs the multi-step loop itself, appending tool-call/result
+        // messages between API calls; without this the breakpoint stays on the
+        // pre-loop tail, so each step's accumulating tool output is re-sent at full
+        // price. Marking the new last message each step caches the prefix the
+        // previous step already sent. (No-op for non-Anthropic routes.)
+        prepareStep: route.cacheControl
+          ? ({ messages }) => ({ messages: withCacheBreakpoints(messages) })
+          : undefined,
+        providerOptions: route.thinkingBudget
+          ? { anthropic: { thinking: { type: "enabled", budgetTokens: route.thinkingBudget } } }
+          : undefined,
+      });
+    } catch (err) {
+      const d = describeError(err);
+      yield { type: "error", error: d.message, hint: d.hint, retryable: d.retryable };
+      return;
+    }
+
+    // The AI SDK exposes several derived promises that reject lazily when the
+    // stream errors. We await some below in their own try/catch, but any we
+    // never touch would surface as an unhandled rejection — which Node dumps,
+    // unredacted, to the terminal (scrambling the TUI and leaking the request
+    // body). Attach no-op catches so a stream error stays inside our channel.
+    for (const key of ["text", "steps", "warnings", "sources", "files", "reasoning"] as const) {
+      const p = (result as unknown as Record<string, unknown>)[key];
+      if (p && typeof (p as Promise<unknown>).then === "function") {
+        (p as Promise<unknown>).catch(() => {});
+      }
+    }
+
+    let assistantText = "";
+    let aborted = false;
+    // Track usage as steps finish so the UI can tick the token count up live,
+    // instead of jumping only when the whole turn ends. `totalUsage` reconciles
+    // the authoritative number at finish.
+    const baseline = this.usage;
+    let stepsUsage = emptyUsage();
+
+    try {
+      for await (const part of result.fullStream) {
+        switch (part.type) {
+          case "text-delta":
+            if (part.text) {
+              assistantText += part.text;
+              yield { type: "text", text: part.text };
+            }
+            break;
+          case "reasoning-delta":
+            if (part.text) yield { type: "reasoning", text: part.text };
+            break;
+          case "tool-call":
+            yield { type: "tool-call", id: part.toolCallId, name: part.toolName, input: part.input };
+            break;
+          case "tool-result":
+            yield {
+              type: "tool-result",
+              id: part.toolCallId,
+              name: part.toolName,
+              output: (part as { output: unknown }).output,
+            };
+            break;
+          case "tool-error":
+            yield {
+              type: "tool-error",
+              id: part.toolCallId,
+              name: part.toolName,
+              error: errMsg((part as { error: unknown }).error),
+            };
+            break;
+          case "finish-step": {
+            const u = (part as { usage?: Partial<UsageTotals> }).usage;
+            if (u) {
+              stepsUsage = addUsage(stepsUsage, {
+                inputTokens: u.inputTokens ?? 0,
+                outputTokens: u.outputTokens ?? 0,
+                totalTokens: u.totalTokens ?? 0,
+                cachedInputTokens: u.cachedInputTokens ?? 0,
+              });
+              this.usage = addUsage(baseline, stepsUsage);
+              yield { type: "usage", usage: this.usage, turn: stepsUsage };
+            }
+            yield { type: "step-finish" };
+            break;
+          }
+          case "abort":
+            aborted = true;
+            break;
+          case "error": {
+            const d = describeError(part.error);
+            yield { type: "error", error: d.message, hint: d.hint, retryable: d.retryable };
+            break;
+          }
+        }
+      }
+    } catch (err) {
+      if (signal?.aborted || isAbortError(err)) {
+        aborted = true;
+      } else {
+        const d = describeError(err);
+        yield { type: "error", error: d.message, hint: d.hint, retryable: d.retryable };
+        return;
+      }
+    }
+
+    // Persist the model's response so the next turn keeps context. On a clean finish
+    // we use the SDK's structured messages; on an interrupt those may be unavailable,
+    // so we fall back to a synthetic assistant message from the text we streamed.
+    let persisted = false;
+    try {
+      const response = await result.response;
+      if (response?.messages?.length) {
+        this.messages.push(...response.messages);
+        persisted = true;
+      }
+    } catch {
+      /* aborted/errored before a response was assembled */
+    }
+    if (!persisted && assistantText.trim()) {
+      this.messages.push({ role: "assistant", content: assistantText });
+    }
+
+    if (aborted) {
+      yield { type: "aborted" };
+      return;
+    }
+
+    const turnUsage = await result.totalUsage.catch(() => ({}) as Record<string, number>);
+    const usage: UsageTotals = {
+      inputTokens: turnUsage.inputTokens ?? 0,
+      outputTokens: turnUsage.outputTokens ?? 0,
+      totalTokens: turnUsage.totalTokens ?? 0,
+      cachedInputTokens: turnUsage.cachedInputTokens ?? 0,
+    };
+    // Reconcile against the authoritative turn total. We already folded per-step
+    // usage into this.usage live; rebase on the baseline so we don't double-count.
+    // Fall back to the accumulated step usage if the provider omitted totalUsage.
+    this.usage = addUsage(baseline, usage.totalTokens > 0 ? usage : stepsUsage);
+
+    const finishReason = await result.finishReason.catch(() => "unknown");
+    yield { type: "finish", usage, finishReason };
+  }
+
+  private shouldCompact(): boolean {
+    const budget = this.opts.contextBudget;
+    if (!budget) return false;
+    const ratio = this.opts.compactRatio ?? 0.8;
+    return this.messages.length > KEEP_RECENT && estimateTokens(this.messages) > budget * ratio;
+  }
+
+  // Summarize older history into a single briefing message, keeping the most recent
+  // messages verbatim. Uses a schema-guided summary (goals / decisions / files /
+  // open threads) so the structure survives, falling back to a plain-text summary if
+  // structured output fails. The cut always lands on a `user` message so tool-call /
+  // result pairs are never orphaned. Returns before/after token estimates, or null
+  // when there's nothing worth compacting. Best-effort: failures leave history intact.
+  async compact(): Promise<{ before: number; after: number } | null> {
+    const before = estimateTokens(this.messages);
+    const cut = safeCutIndex(this.messages, KEEP_RECENT);
+    if (cut <= 0) return null;
+
+    const older = this.messages.slice(0, cut);
+    const recent = this.messages.slice(cut);
+    const transcript = older.map((m) => `${m.role}: ${renderContent(m.content)}`).join("\n\n");
+    const instruction =
+      `Summarize the earlier part of this coding session so the work can continue without the ` +
+      `full history. Be specific and terse.\n\n---\n${transcript}`;
+
+    let summary: string;
+    try {
+      const { object } = await generateObject({
+        model: this.opts.routes.default.model,
+        schema: CompactionSchema,
+        prompt: instruction,
+      });
+      summary = formatCompaction(object);
+    } catch {
+      // Some models/providers handle structured output poorly — fall back to text.
+      try {
+        const { text } = await generateText({ model: this.opts.routes.default.model, prompt: instruction });
+        summary = text.trim();
+      } catch {
+        return null; // leave history untouched on failure
+      }
+    }
+    if (!summary) return null;
+
+    this.messages.length = 0;
+    this.messages.push({ role: "user", content: `[Summary of earlier conversation]\n${summary}` });
+    this.messages.push(...recent);
+
+    return { before, after: estimateTokens(this.messages) };
+  }
+}
+
+// Cheap heuristic token estimate (~4 chars/token) over serialized message content.
+export function estimateTokens(messages: ModelMessage[]): number {
+  let chars = 0;
+  for (const m of messages) chars += renderContent(m.content).length + m.role.length;
+  return Math.ceil(chars / 4);
+}
+
+// Choose a cut so the kept tail starts on a `user` message — never orphaning a tool
+// result from its tool-call. Returns 0 when there's nothing safe to drop.
+function safeCutIndex(messages: ModelMessage[], minKeep: number): number {
+  let cut = messages.length - minKeep;
+  if (cut <= 0) return 0;
+  while (cut < messages.length && messages[cut].role !== "user") cut++;
+  return cut >= messages.length ? 0 : cut;
+}
+
+function renderContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((p) => {
+        const part = p as { type?: string; text?: string; toolName?: string };
+        if (part.type === "text" && part.text) return part.text;
+        if (part.type === "tool-call") return `[tool-call ${part.toolName ?? ""}]`;
+        if (part.type === "tool-result") return `[tool-result ${part.toolName ?? ""}]`;
+        return `[${part.type ?? "part"}]`;
+      })
+      .join(" ");
+  }
+  return "";
+}
+
+// Attach Anthropic ephemeral cache breakpoints. Anthropic caches the longest prefix
+// ending at a breakpoint, so we mark the first message (stable base: system + tools +
+// first turn) and the last message (rolling: grows with the conversation). Returns a
+// shallow copy so the stored history stays free of provider-specific annotations.
+const CACHE = { anthropic: { cacheControl: { type: "ephemeral" } } } as const;
+
+function withCacheBreakpoints(messages: ModelMessage[]): ModelMessage[] {
+  if (messages.length === 0) return messages;
+  const out = messages.slice();
+  markBreakpoint(out, 0);
+  if (out.length > 1) markBreakpoint(out, out.length - 1);
+  return out;
+}
+
+function markBreakpoint(messages: ModelMessage[], i: number): void {
+  const msg = messages[i] as { role: string; content: unknown };
+  const parts =
+    typeof msg.content === "string"
+      ? [{ type: "text", text: msg.content }]
+      : (msg.content as unknown[]).slice();
+  if (parts.length === 0) return;
+  const last = parts.length - 1;
+  parts[last] = { ...(parts[last] as object), providerOptions: CACHE };
+  messages[i] = { ...msg, content: parts } as unknown as ModelMessage;
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && (err.name === "AbortError" || /abort/i.test(err.message));
+}
+
+function errMsg(err: unknown): string {
+  return redactText(rawErrMsg(err));
+}
+
+function rawErrMsg(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}

package/src/engine/errors.ts

@@ -0,0 +1,197 @@
+// Turn provider / AI-SDK errors into something a human can act on. These errors
+// (e.g. `AI_APICallError`) carry structured fields well beyond `.message` —
+// statusCode, responseBody, the request's model — but Node's default printer
+// would dump the whole object (request messages and all) to the terminal,
+// unredacted. We read the useful fields defensively and emit a short message
+// plus an actionable hint, both run through secret redaction.
+
+import { redactText } from "../util/redact.ts";
+
+export interface DescribedError {
+  message: string; // short, user-facing, redacted
+  hint?: string; // actionable next step, rendered dim below the message
+  retryable?: boolean;
+}
+
+interface ErrorFacts {
+  statusCode?: number;
+  providerMessage?: string;
+  code?: string; // provider's machine-readable error code, e.g. "DAILY_CAP_HIT"
+  model?: string;
+  provider?: string;
+}
+
+const HOST_LABELS: Record<string, string> = {
+  "openrouter.ai": "OpenRouter",
+  "api.anthropic.com": "Anthropic",
+  "api.openai.com": "OpenAI",
+  "cloud-api.near.ai": "NEAR AI",
+};
+
+// The AI SDK wraps the real provider error: a retry sequence that exhausts its
+// attempts throws AI_RetryError, whose `.lastError` is the APICallError that
+// actually carries statusCode / responseBody / requestBodyValues. Without peeling
+// that off we'd read undefined for every field and fall back to the wrapper's bare
+// "Too Many Requests". Follow `.lastError` (and a `.cause` that looks like a
+// richer error) until we reach the one with the useful fields.
+function unwrap(err: unknown): unknown {
+  let cur = err;
+  for (let i = 0; i < 5; i++) {
+    if (!cur || typeof cur !== "object") break;
+    const e = cur as Record<string, unknown>;
+    const richer = e.statusCode == null && e.responseBody == null;
+    const inner = e.lastError ?? (richer ? e.cause : undefined);
+    if (!inner || inner === cur) break;
+    cur = inner;
+  }
+  return cur;
+}
+
+// Pull structured fields off an unknown error without trusting any one shape.
+function extract(err: unknown): ErrorFacts {
+  const e = (err ?? {}) as Record<string, unknown>;
+  const statusCode = typeof e.statusCode === "number" ? e.statusCode : undefined;
+
+  // The provider's own message + machine code, preferred over the SDK's wrapper
+  // text. Providers disagree on shape: OpenAI/OpenRouter nest under `error`, while
+  // the Privateer account backend returns a flat `{ message, code }` (e.g. a daily
+  // usage cap). Read both shapes; keep the first message/code we find.
+  let providerMessage: string | undefined;
+  let code: string | undefined;
+  const readBody = (body: unknown) => {
+    const b = body as
+      | { error?: { message?: unknown; code?: unknown }; message?: unknown; code?: unknown }
+      | undefined;
+    if (!b || typeof b !== "object") return;
+    const msg = b.error?.message ?? b.message;
+    if (providerMessage == null && typeof msg === "string") providerMessage = msg;
+    const c = b.error?.code ?? b.code;
+    if (code == null && typeof c === "string") code = c;
+  };
+  readBody(e.data);
+  if (typeof e.responseBody === "string") {
+    try {
+      readBody(JSON.parse(e.responseBody));
+    } catch {
+      /* responseBody wasn't JSON — fall back to the wrapper message */
+    }
+  }
+
+  const reqBody = e.requestBodyValues as { model?: unknown } | undefined;
+  const model = typeof reqBody?.model === "string" ? reqBody.model : undefined;
+
+  let provider: string | undefined;
+  if (typeof e.url === "string") {
+    try {
+      provider = HOST_LABELS[new URL(e.url).host];
+    } catch {
+      /* not a URL */
+    }
+  }
+
+  return { statusCode, providerMessage, code, model, provider };
+}
+
+// Machine codes the Privateer backend returns for a hard account cap (daily /
+// monthly message or token limit, or an empty balance). Exported so the provider
+// fetch wrapper can recognise the same condition and rewrite the 429 to a
+// non-retryable status — otherwise the AI SDK burns its full retry budget on a
+// limit that won't clear by retrying. Keep this the single source of truth.
+const CAP_CODE = /CAP|QUOTA|LIMIT_REACHED|INSUFFICIENT|TOP_?UP/i;
+
+export function isAccountCapCode(code: string | null | undefined): boolean {
+  return typeof code === "string" && CAP_CODE.test(code);
+}
+
+function rawMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+
+// Map a provider error to a friendly message + hint. Falls back to the raw
+// (redacted) message for anything we don't recognize, so nothing is swallowed.
+export function describeError(err: unknown): DescribedError {
+  const inner = unwrap(err);
+  const facts = extract(inner);
+  const status = facts.statusCode;
+  const text = facts.providerMessage ?? rawMessage(inner);
+  const forModel = facts.model ? ` for ${facts.model}` : "";
+  const forProvider = facts.provider ? ` for ${facts.provider}` : "";
+
+  const out = (d: DescribedError): DescribedError => ({
+    message: redactText(d.message),
+    hint: d.hint ? redactText(d.hint) : undefined,
+    retryable: d.retryable,
+  });
+
+  // OpenRouter: the account's data-policy / guardrail settings exclude every
+  // provider that could serve this model. The phrasing is distinctive, so match on
+  // it regardless of status — OpenRouter returns this as a 404 *or* a 403, and the
+  // 403 must not fall through to the generic "authentication failed" branch below.
+  // This is a "you must act" error: never retried (no `retryable` flag).
+  if (/data[- ]?policy|guardrail|no endpoints?\b/i.test(text)) {
+    return out({
+      message: `No provider endpoint matches your data-policy settings${forModel}.`,
+      hint: "Enable providers at https://openrouter.ai/settings/privacy, or pick a different model with /model.",
+    });
+  }
+  // Privateer account usage cap (daily/monthly message or token limit). The
+  // backend returns this as a 429 with a machine `code` like DAILY_CAP_HIT and a
+  // ready-to-show message ("Daily message limit of 25 reached. Upgrade or top up
+  // to continue."). Unlike a transient rate limit, retrying never helps — the user
+  // must upgrade, top up, or switch providers — so surface the backend's own
+  // message verbatim and do NOT mark it retryable (which would invite a retry).
+  const capText = /limit of .* reached|upgrade or top ?up|usage limit reached/i.test(text);
+  if (isAccountCapCode(facts.code) || (status === 429 && capText)) {
+    return out({
+      message: facts.providerMessage ?? text,
+      hint: "Upgrade or top up your Privateer account, or run /provider to use your own API key.",
+    });
+  }
+  if (status === 401 || status === 403) {
+    return out({
+      message: `Authentication failed${forProvider} (${status}).`,
+      hint: "Check the API key — run /provider, or set the provider's API key env var.",
+    });
+  }
+  if (status === 402) {
+    return out({
+      message: `Request rejected for billing reasons${forProvider} (402).`,
+      hint: "Check your account credits or billing.",
+    });
+  }
+  if (status === 404) {
+    return out({
+      message: `Model not found${forModel} (404).`,
+      hint: "Check the model id — run /model to switch.",
+    });
+  }
+  if (status === 429) {
+    return out({
+      message: `Rate limited${forProvider} (429).`,
+      hint: "Wait a moment and try again.",
+      retryable: true,
+    });
+  }
+  if (status != null && status >= 500) {
+    return out({
+      message: `Provider error${forProvider} (${status}).`,
+      hint: "Usually transient — retry shortly.",
+      retryable: true,
+    });
+  }
+  if (/fetch failed|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|network/i.test(text)) {
+    return out({
+      message: "Network error reaching the provider.",
+      hint: "Check your connection and try again.",
+      retryable: true,
+    });
+  }
+
+  return out({ message: text });
+}

package/src/engine/events.ts

@@ -0,0 +1,74 @@
+import type { RouteName, Modality } from "./router.ts";
+
+// Normalized events the engine emits while streaming a turn. The UI (and the
+// headless print path) consume these without knowing anything about the provider
+// or the AI SDK's internal stream-part shapes.
+
+export interface UsageTotals {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  // Cache-read input tokens (a subset of input, billed at a fraction of the base
+  // rate). Providers differ on whether `inputTokens` already includes these — see
+  // `effectiveTokens`, which handles both conventions.
+  cachedInputTokens: number;
+}
+
+export type EngineEvent =
+  | { type: "text"; text: string }
+  | { type: "reasoning"; text: string }
+  | { type: "tool-call"; id: string; name: string; input: unknown }
+  | { type: "tool-result"; id: string; name: string; output: unknown }
+  | { type: "tool-error"; id: string; name: string; error: string }
+  | { type: "step-finish" }
+  // `usage` is the cumulative session total; `turn` is just this turn's accumulation
+  // so far. Both emitted live as steps finish so the UI can show either.
+  | { type: "usage"; usage: UsageTotals; turn: UsageTotals }
+  | { type: "aborted" }
+  | { type: "compacted"; before: number; after: number }
+  // The router switched this turn to a non-default model. `missing` lists modalities
+  // the chosen model can't accept (set when no configured model fully covers the turn).
+  | { type: "routed"; route: RouteName; label: string; reason?: string; missing?: Modality[] }
+  | { type: "finish"; usage: UsageTotals; finishReason: string }
+  // A transient failure (rate limit, 5xx, network) is being retried automatically
+  // before any output streamed. `attempt`/`max` are 1-based for display; `reason` is
+  // the redacted error message that triggered the retry.
+  | { type: "retrying"; attempt: number; max: number; delayMs: number; reason: string }
+  // `error` is the short user-facing message; `hint` is an optional actionable
+  // next step rendered dim beneath it. Both are already secret-redacted.
+  | { type: "error"; error: string; hint?: string; retryable?: boolean };
+
+export const emptyUsage = (): UsageTotals => ({
+  inputTokens: 0,
+  outputTokens: 0,
+  totalTokens: 0,
+  cachedInputTokens: 0,
+});
+
+export function addUsage(a: UsageTotals, b: Partial<UsageTotals>): UsageTotals {
+  return {
+    inputTokens: (a.inputTokens ?? 0) + (b.inputTokens ?? 0),
+    outputTokens: (a.outputTokens ?? 0) + (b.outputTokens ?? 0),
+    totalTokens: (a.totalTokens ?? 0) + (b.totalTokens ?? 0),
+    cachedInputTokens: (a.cachedInputTokens ?? 0) + (b.cachedInputTokens ?? 0),
+  };
+}
+
+// Anthropic bills a cache read at ~10% of the base input rate. Re-price the cached
+// portion at that rate to estimate what was actually billed, rather than the raw
+// `totalTokens` which counts every re-sent cached token at full weight.
+const CACHE_READ_RATE = 0.1;
+
+// Effective (billed-weighted) token estimate. Providers disagree on whether
+// `inputTokens` already includes `cachedInputTokens`: OpenRouter's `prompt_tokens`
+// includes them (cached ≤ input), Anthropic's `input_tokens` counts only fresh
+// tokens (cached reported separately, so cached may exceed input). We detect which
+// convention applies and discount the cached portion either way. With no cache
+// hits this collapses to `inputTokens + outputTokens` (== totalTokens).
+export function effectiveTokens(u: UsageTotals): number {
+  const cached = u.cachedInputTokens ?? 0;
+  const input = u.inputTokens ?? 0;
+  const inputIncludesCached = cached <= input;
+  const fullPriceInput = inputIncludesCached ? input - cached : input;
+  return Math.round(fullPriceInput + cached * CACHE_READ_RATE + (u.outputTokens ?? 0));
+}