opencode-plugboard 0.17.0 → 0.19.0

package/src/responses/store.ts

@@ -0,0 +1,51 @@
+/**
+ * The output items of recent Responses answers, so a later request can refer to them with an
+ * `item_reference` (#147). The Vercel AI SDK keeps `store: true` by default and sends the earlier
+ * assistant turn as references to the items plugboard returned, so without this store its
+ * multi-turn chat is refused.
+ *
+ * Bounded and per app: an app's store holds up to 1000 answers for an hour, and an app reads only
+ * its own answers. Nothing is written to disk. The store lives on `globalThis` under a versioned
+ * key, as the other process-wide state does (docs/architecture.md, I6), so it outlives a plugin
+ * generation that is replaced. A reference to an item that was evicted, expired or never returned
+ * is a 400 that suggests `store: false`; it is never a guess.
+ */
+import { LRUCache } from "lru-cache"
+
+type Item = Readonly<Record<string, unknown>>
+
+const TTL_MS = 60 * 60 * 1000
+const MAX_ANSWERS = 1000
+const SLOT = Symbol.for("opencode-plugboard.responses-items/1")
+
+const holder = globalThis as unknown as Record<symbol, Map<string, LRUCache<string, ReadonlyArray<Item>>> | undefined>
+
+/** The store of one app: answer id -> its output items. */
+function storeOf(app: string): LRUCache<string, ReadonlyArray<Item>> {
+  const apps = (holder[SLOT] ??= new Map())
+  let store = apps.get(app)
+  if (store === undefined) {
+    store = new LRUCache<string, ReadonlyArray<Item>>({ max: MAX_ANSWERS, ttl: TTL_MS })
+    apps.set(app, store)
+  }
+  return store
+}
+
+const isItem = (value: unknown): value is Item => typeof value === "object" && value !== null && typeof (value as Item).id === "string"
+
+/** Keeps the output items of a completed or incomplete answer (a failed one has no items to replay). */
+export function rememberAnswer(app: string, response: object): void {
+  const { id, output } = response as { id?: unknown; output?: unknown }
+  if (typeof id !== "string" || !Array.isArray(output)) return
+  const items = output.filter(isItem)
+  if (items.length > 0) storeOf(app).set(id, items)
+}
+
+/** The output item with this id that the app's recent answers returned, if still held. */
+export function findItem(app: string, itemId: string): Item | undefined {
+  for (const items of storeOf(app).values()) {
+    const found = items.find((item) => item.id === itemId)
+    if (found !== undefined) return found
+  }
+  return undefined
+}

package/src/runtime.ts

@@ -62,6 +62,7 @@ import { ensureAppDir } from "./session/history.js"
 import type { HistoryPort } from "./session/host.js"
 import { recordSession, sweepHistory, type HistoryLimits } from "./session/prune.js"
 import { createSessionStore, type SessionStore } from "./session/state.js"
+import { createBudgetState, type BudgetState } from "./budgets.js"
 import { createUsageState, type UsageState } from "./usage.js"
 
 export type Handler = (request: IncomingMessage, response: ServerResponse) => void
@@ -115,8 +116,8 @@ const BACKEND_POLL_MS = 25
 const BIND_RETRY_MS = 15_000
 const BIND_REMINDER_MS = 5 * 60_000
 
-/** 12: the live key set (`keys`, `Runtime.keys`) that a stricter newer generation replaces at once (#90). 11: the usage store's live days (`src/usage.ts`) live here too. 10: the response cache store (`src/cache.ts`) lives here too. 9: the request limiter state (`src/limits.ts`) lives here, so the concurrency caps and rate windows survive a generation. 8: `Metrics.render` is async and the registry is @prometheus-io/client's. 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
-const VERSION = 12
+/** 13: the budget warning state (`src/budgets.ts`) lives here too. 12: the live key set (`keys`, `Runtime.keys`) that a stricter newer generation replaces at once (#90). 11: the usage store's live days (`src/usage.ts`) live here too. 10: the response cache store (`src/cache.ts`) lives here too. 9: the request limiter state (`src/limits.ts`) lives here, so the concurrency caps and rate windows survive a generation. 8: `Metrics.render` is async and the registry is @prometheus-io/client's. 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
+const VERSION = 13
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -180,6 +181,8 @@ interface Runtime {
   cache?: { readonly fingerprint: string; readonly store: CacheStore }
   /** The usage store's live days and retention clock (src/usage.ts). */
   readonly usage: UsageState
+  /** The budget warnings already logged (src/budgets.ts). */
+  readonly budgets: BudgetState
   listener?: Listener
   /** Present while a fiber is subscribed to the server event bus. */
   pump?: Pump
@@ -193,6 +196,7 @@ const detachedMetrics = createMetrics()
 const detachedStartedAt = Date.now()
 const detachedLimits = createLimitState()
 const detachedUsage = createUsageState()
+const detachedBudgets = createBudgetState()
 let foreignVersionLogged = false
 
 /** The process runtime, created on first use; undefined when a different version already owns the process. */
@@ -210,6 +214,7 @@ function runtime(): Runtime | undefined {
       metrics: createMetrics(),
       limits: createLimitState(),
       usage: createUsageState(),
+      budgets: createBudgetState(),
       startedAt: Date.now(),
     }
     slot[KEY] = created
@@ -291,6 +296,9 @@ export const processLimits = (): LimitState => runtime()?.limits ?? detachedLimi
 /** The usage store's live days shared by every generation in the process (detached under a foreign-version runtime). */
 export const processUsage = (): UsageState => runtime()?.usage ?? detachedUsage
 
+/** The budget warning state shared by every generation in the process (detached under a foreign-version runtime). */
+export const processBudgets = (): BudgetState => runtime()?.budgets ?? detachedBudgets
+
 /**
  * The options authentication reads: `keys` is the live key set, not the serving generation's own
  * (a generation that is still live after a key revocation keeps its old keys otherwise, #90).

package/src/stop.ts

@@ -0,0 +1,54 @@
+/**
+ * Caller stop sequences on the answer text (#145, #149). A provider ends the answer at a sequence
+ * but does not always return it, and Anthropic, OpenAI and Gemini all leave it out of the answer
+ * when the stop is the one that ended it. The host reports only `stop`, so the end of a plain
+ * stop's text is checked for a sequence, which is removed and reported. A streamed text keeps its
+ * last characters back (`StopHoldback`) until the finish decides whether they end in a sequence.
+ */
+
+/** The longest of `stops` that `tail` ends with, if any. */
+export const stopTail = (tail: string, stops: ReadonlyArray<string>): string | undefined =>
+  stops.filter((stop) => tail.endsWith(stop)).sort((a, b) => b.length - a.length)[0]
+
+/** Streamed text with its last `size` characters (the longest sequence) held back. Without sequences nothing is held. */
+export class StopHoldback {
+  private held = ""
+  private readonly size: number
+
+  constructor(private readonly stops: ReadonlyArray<string>) {
+    this.size = Math.max(0, ...stops.map((stop) => stop.length))
+  }
+
+  /** Adds a chunk and returns the text that can be sent now: everything except the last `size` characters. */
+  push(chunk: string): string {
+    if (this.size === 0) return chunk
+    this.held += chunk
+    const out = this.held.slice(0, Math.max(0, this.held.length - this.size))
+    this.held = this.held.slice(out.length)
+    return out
+  }
+
+  /** Everything still held, unchanged. Used before a tool call or reasoning, which cannot be a stop. */
+  release(): string {
+    const out = this.held
+    this.held = ""
+    return out
+  }
+
+  /**
+   * The end of the text. `plainStop` is true when the model stopped for `stop` with no tool call:
+   * then a sequence the held text ends with is removed and returned as `matched`.
+   */
+  finish(plainStop: boolean): { readonly text: string; readonly matched?: string } {
+    const matched = plainStop && this.size > 0 ? stopTail(this.held, this.stops) : undefined
+    const text = matched === undefined ? this.held : this.held.slice(0, this.held.length - matched.length)
+    this.held = ""
+    return matched === undefined ? { text } : { text, matched }
+  }
+}
+
+/** A complete text (no streaming): the text without the sequence it ends with, if any. */
+export const stripStopTail = (text: string, stops: ReadonlyArray<string>): { readonly text: string; readonly matched?: string } => {
+  const matched = stopTail(text, stops)
+  return matched === undefined ? { text } : { text: text.slice(0, text.length - matched.length), matched }
+}

package/src/tui-format.ts

@@ -0,0 +1,217 @@
+/**
+ * Pure helpers for the `/plugboard` usage page (src/tui.tsx): the range presets, the rows and totals
+ * of a `UsageReport`, and the number formats. No OpenTUI, Solid or server imports, so `bun test`
+ * covers them directly. Types only from src/usage.ts (its runtime pulls in the server's logger).
+ */
+
+import type { UsageErrors, UsageReport, UsageTokens, UsageTotals } from "./usage.js"
+
+export type RangePreset = "today" | "week" | "month" | "quarter"
+
+/** The page's range keys, in the order the header lists them. `days` counts the UTC days ending today. */
+export const RANGE_PRESETS: ReadonlyArray<{ readonly key: string; readonly preset: RangePreset; readonly label: string; readonly days: number }> = [
+  { key: "t", preset: "today", label: "today", days: 1 },
+  { key: "w", preset: "week", label: "7 days", days: 7 },
+  { key: "m", preset: "month", label: "30 days", days: 30 },
+  { key: "q", preset: "quarter", label: "90 days", days: 90 },
+]
+
+const DAY_MS = 86_400_000
+
+/** The UTC calendar day of an epoch-ms instant, `YYYY-MM-DD`. */
+export function utcDay(at: number): string {
+  return new Date(at).toISOString().slice(0, 10)
+}
+
+/** The inclusive UTC range of a preset ending today, the same window the server's default uses. */
+export function presetRange(preset: RangePreset, at: number): { readonly from: string; readonly to: string } {
+  const days = RANGE_PRESETS.find((item) => item.preset === preset)?.days ?? 30
+  const to = utcDay(at)
+  return { from: utcDay(Date.parse(`${to}T00:00:00Z`) - (days - 1) * DAY_MS), to }
+}
+
+/** Counts in thousands and millions: 999, 1.2k, 45k, 3.4M. Inputs are whole numbers. */
+export function formatCount(value: number): string {
+  for (const [size, suffix] of [
+    [1_000_000_000, "B"],
+    [1_000_000, "M"],
+    [1_000, "k"],
+  ] as const) {
+    if (value >= size) return `${trimmed(value / size)}${suffix}`
+  }
+  return String(value)
+}
+
+function trimmed(value: number): string {
+  return value >= 100 ? String(Math.round(value)) : value.toFixed(1).replace(/\.0$/, "")
+}
+
+/** USD: `$0.00`, `<$0.01` for a cost below a cent, `$12.34`, and `$1.2k` from a thousand up. */
+export function formatCost(usd: number): string {
+  if (usd === 0) return "$0.00"
+  if (usd < 0.01) return "<$0.01"
+  if (usd < 1_000) return `$${usd.toFixed(2)}`
+  return `$${formatCount(usd)}`
+}
+
+/** A latency in ms, or `-` without requests. The percentiles are bucket bounds, so they read as estimates. */
+export function formatMs(ms: number | null): string {
+  if (ms === null) return "-"
+  if (ms < 1_000) return `${ms} ms`
+  return `${Number((ms / 1_000).toFixed(1))} s`
+}
+
+/** `part` of `whole` as a whole percent, or `-` when `whole` is zero. */
+export function formatPercent(part: number, whole: number): string {
+  return whole === 0 ? "-" : `${Math.round((part / whole) * 100)}%`
+}
+
+/** An ISO instant as `2026-10-11 14:02 UTC`, or `-` when absent. */
+export function formatInstant(iso: string | undefined): string {
+  return iso === undefined ? "-" : `${iso.slice(0, 16).replace("T", " ")} UTC`
+}
+
+/** A text cell of exactly `width` columns; longer text is cut with an ellipsis. */
+export function cell(text: string, width: number, align: "left" | "right"): string {
+  const clipped = text.length > width ? `${text.slice(0, width - 1)}…` : text
+  return align === "right" ? clipped.padStart(width) : clipped.padEnd(width)
+}
+
+export interface Column {
+  readonly title: string
+  readonly width: number
+  readonly align: "left" | "right"
+}
+
+export const APP_COLUMNS: ReadonlyArray<Column> = [
+  { title: "app", width: 18, align: "left" },
+  { title: "requests", width: 9, align: "right" },
+  { title: "tokens", width: 8, align: "right" },
+  { title: "cost", width: 9, align: "right" },
+  { title: "errors", width: 7, align: "right" },
+  { title: "p95", width: 8, align: "right" },
+  { title: "last request", width: 17, align: "left" },
+]
+
+export const MODEL_COLUMNS: ReadonlyArray<Column> = [
+  { title: "model", width: 36, align: "left" },
+  { title: "requests", width: 9, align: "right" },
+  { title: "tokens", width: 8, align: "right" },
+  { title: "cost", width: 9, align: "right" },
+]
+
+/** One line of a table: each value in its column, separated by one space. */
+export function formatLine(values: ReadonlyArray<string>, columns: ReadonlyArray<Column>): string {
+  return columns.map((column, index) => cell(values[index] ?? "", column.width, column.align)).join(" ")
+}
+
+/** A bar of up to `width` blocks for a share in 0..1; any positive share shows at least one block. */
+export function barCells(share: number, width: number): string {
+  if (!(share > 0)) return ""
+  return "█".repeat(Math.min(width, Math.max(1, Math.round(share * width))))
+}
+
+export function tokenTotal(tokens: UsageTokens): number {
+  return tokens.input + tokens.cacheRead + tokens.cacheWrite + tokens.output + tokens.reasoning
+}
+
+export function errorTotal(errors: UsageErrors): number {
+  return errors.client + errors.server + errors.timeout + errors.disconnected
+}
+
+export interface AppRow {
+  readonly app: string
+  readonly requests: number
+  readonly tokens: number
+  readonly costUsd: number
+  readonly errors: number
+  readonly p95Ms: number | null
+  readonly lastRequestAt?: string
+  /** Share of the range's cost, or of its requests when nothing was priced: 0..1, for the bar. */
+  readonly share: number
+}
+
+/** One row per app, most expensive first (then most requests, then name). */
+export function appRows(report: UsageReport): AppRow[] {
+  const { totals } = report
+  return Object.entries(report.apps)
+    .map(([app, entry]): AppRow => {
+      const share =
+        totals.costUsd > 0 ? entry.totals.costUsd / totals.costUsd : totals.requests > 0 ? entry.totals.requests / totals.requests : 0
+      return {
+        app,
+        requests: entry.totals.requests,
+        tokens: tokenTotal(entry.totals.tokens),
+        costUsd: entry.totals.costUsd,
+        errors: errorTotal(entry.totals.errors),
+        p95Ms: entry.totals.latency.p95Ms,
+        ...(entry.totals.lastRequestAt === undefined ? {} : { lastRequestAt: entry.totals.lastRequestAt }),
+        share,
+      }
+    })
+    .sort((a, b) => b.costUsd - a.costUsd || b.requests - a.requests || a.app.localeCompare(b.app))
+}
+
+export function appValues(row: AppRow): string[] {
+  return [
+    row.app,
+    formatCount(row.requests),
+    formatCount(row.tokens),
+    formatCost(row.costUsd),
+    formatCount(row.errors),
+    formatMs(row.p95Ms),
+    formatInstant(row.lastRequestAt),
+  ]
+}
+
+export interface ModelRow {
+  readonly model: string
+  readonly requests: number
+  readonly tokens: number
+  readonly costUsd: number
+}
+
+/** The models of every app, summed over the range: most expensive first, at most `limit`. */
+export function modelRows(report: UsageReport, limit: number): ModelRow[] {
+  const sums = new Map<string, { requests: number; tokens: number; costUsd: number }>()
+  for (const app of Object.values(report.apps)) {
+    for (const [model, usage] of Object.entries(app.models)) {
+      const sum = sums.get(model) ?? { requests: 0, tokens: 0, costUsd: 0 }
+      sums.set(model, { requests: sum.requests + usage.requests, tokens: sum.tokens + usage.tokens, costUsd: sum.costUsd + usage.costUsd })
+    }
+  }
+  return [...sums]
+    .map(([model, sum]): ModelRow => ({ model, ...sum }))
+    .sort((a, b) => b.costUsd - a.costUsd || b.requests - a.requests || a.model.localeCompare(b.model))
+    .slice(0, limit)
+}
+
+export function modelValues(row: ModelRow): string[] {
+  return [row.model, formatCount(row.requests), formatCount(row.tokens), formatCost(row.costUsd)]
+}
+
+export interface TotalItem {
+  readonly label: string
+  readonly value: string
+}
+
+/** The totals line, in the order the page shows it. */
+export function totalItems(totals: UsageTotals): TotalItem[] {
+  const lookups = totals.cacheHits + totals.cacheMisses
+  return [
+    { label: "requests", value: formatCount(totals.requests) },
+    { label: "tokens", value: formatCount(tokenTotal(totals.tokens)) },
+    { label: "est. cost", value: formatCost(totals.costUsd) },
+    { label: "errors", value: formatCount(errorTotal(totals.errors)) },
+    { label: "cache hit", value: formatPercent(totals.cacheHits, lookups) },
+    { label: "fallbacks", value: formatCount(totals.fallbacks) },
+    { label: "429s", value: formatCount(totals.limited) },
+    { label: "p95", value: formatMs(totals.latency.p95Ms) },
+  ]
+}
+
+/** The message the page shows when the usage RPC cannot answer (plugboard not loaded there, or usage off). */
+export function unavailableMessage(error: unknown): string {
+  const reason = error instanceof Error ? error.message : String(error)
+  return `Usage is unavailable on this server. Plugboard must be loaded there with usage enabled. (${reason})`
+}

package/src/tui.tsx

@@ -0,0 +1,166 @@
+/** @jsxImportSource @opentui/solid */
+/**
+ * The `/plugboard` usage page in OpenCode's terminal UI (package entry `./tui`). OpenCode loads it
+ * for every server that runs plugboard with the TUI feature: it reads the usage report over the
+ * server's own RPC (`context.client.rpc(UsageRpc).get`, src/rpc.ts), so it sees every app there.
+ * Nothing is served over HTTP, and nothing here runs on the server.
+ *
+ * Page keys: t, w, m, q pick the range (today, 7, 30, 90 UTC days); r reloads; esc goes back.
+ * Setup only registers the page and the command (no awaits). Shaping and formats: src/tui-format.ts.
+ */
+
+import { Plugin } from "@opencode/plugin/tui"
+import { TextAttributes } from "@opentui/core"
+import { createResource, createSignal, For, Show } from "solid-js"
+import { UsageRpc } from "./rpc.js"
+import type { UsageReport } from "./usage.js"
+import {
+  APP_COLUMNS,
+  appRows,
+  appValues,
+  barCells,
+  formatLine,
+  MODEL_COLUMNS,
+  modelRows,
+  modelValues,
+  presetRange,
+  RANGE_PRESETS,
+  totalItems,
+  unavailableMessage,
+  type RangePreset,
+} from "./tui-format.js"
+
+type Theme = Plugin.Context["theme"]
+
+interface Query {
+  readonly preset: RangePreset
+  /** Bumped by `r`; only here so that a reload is a new query. */
+  readonly reload: number
+}
+
+const PRESET_LABEL = (preset: RangePreset) => RANGE_PRESETS.find((item) => item.preset === preset)?.label ?? preset
+
+function UsagePage(props: { context: Plugin.Context; onClose: () => void }) {
+  const theme = props.context.theme
+  const [query, setQuery] = createSignal<Query>({ preset: "month", reload: 0 })
+  const [report] = createResource(query, async (current) => {
+    const range = presetRange(current.preset, Date.now())
+    try {
+      return (await props.context.client.rpc(UsageRpc).get({ from: range.from, to: range.to })) as UsageReport
+    } catch (error) {
+      props.context.ui.toast.show({ variant: "error", title: "Plugboard", message: unavailableMessage(error) })
+      throw error
+    }
+  })
+
+  props.context.keymap.layer(() => ({
+    commands: [
+      { bind: "escape", title: "back", run: props.onClose },
+      ...RANGE_PRESETS.map((item) => ({
+        bind: item.key,
+        title: `range ${item.label}`,
+        run: () => setQuery((current) => ({ preset: item.preset, reload: current.reload })),
+      })),
+      { bind: "r", title: "refresh", run: () => setQuery((current) => ({ ...current, reload: current.reload + 1 })) },
+    ],
+  }))
+
+  return (
+    <box width="100%" height="100%" backgroundColor={theme.background.base}>
+      <scrollbox flexGrow={1}>
+        <box flexDirection="column" gap={1} paddingLeft={2} paddingRight={2} paddingTop={1} paddingBottom={1}>
+          <text fg={theme.text.base} attributes={TextAttributes.BOLD}>
+            Plugboard usage
+          </text>
+          <text fg={theme.text.muted}>
+            {report() ? `${report()!.from} to ${report()!.to} (UTC)` : PRESET_LABEL(query().preset)}
+            {" · "}t today · w 7 days · m 30 days · q 90 days · r refresh · esc back
+          </text>
+          <Show
+            when={!report.error}
+            fallback={<text fg={theme.text.feedback.error.base}>{unavailableMessage(report.error)}</text>}
+          >
+            <Show when={report()} fallback={<text fg={theme.text.muted}>Loading usage…</text>}>
+              <UsageBody report={report()!} theme={theme} />
+            </Show>
+          </Show>
+        </box>
+      </scrollbox>
+    </box>
+  )
+}
+
+function UsageBody(props: { report: UsageReport; theme: Theme }) {
+  const apps = () => appRows(props.report)
+  const models = () => modelRows(props.report, 10)
+  return (
+    <box flexDirection="column" gap={1}>
+      <box flexDirection="row" flexWrap="wrap" gap={2}>
+        <For each={totalItems(props.report.totals)}>
+          {(item) => (
+            <box flexDirection="row" gap={1}>
+              <text fg={props.theme.text.muted}>{item.label}</text>
+              <text fg={props.theme.text.base} attributes={TextAttributes.BOLD}>
+                {item.value}
+              </text>
+            </box>
+          )}
+        </For>
+      </box>
+      <text fg={props.theme.text.muted} attributes={TextAttributes.BOLD}>
+        Apps
+      </text>
+      <Show when={apps().length > 0} fallback={<text fg={props.theme.text.muted}>No requests in this range.</text>}>
+        <text fg={props.theme.text.muted}>{formatLine(APP_COLUMNS.map((column) => column.title), APP_COLUMNS)}</text>
+        <For each={apps()}>
+          {(row) => (
+            <box flexDirection="row">
+              <text fg={props.theme.text.base}>{formatLine(appValues(row), APP_COLUMNS)}</text>
+              <text fg={props.theme.categorical[0][200]}>{`  ${barCells(row.share, 24)}`}</text>
+            </box>
+          )}
+        </For>
+      </Show>
+      <text fg={props.theme.text.muted} attributes={TextAttributes.BOLD}>
+        Models
+      </text>
+      <Show when={models().length > 0} fallback={<text fg={props.theme.text.muted}>No model calls in this range.</text>}>
+        <text fg={props.theme.text.muted}>{formatLine(MODEL_COLUMNS.map((column) => column.title), MODEL_COLUMNS)}</text>
+        <For each={models()}>
+          {(row) => <text fg={props.theme.text.base}>{formatLine(modelValues(row), MODEL_COLUMNS)}</text>}
+        </For>
+      </Show>
+    </box>
+  )
+}
+
+export default Plugin.define({
+  id: "opencode-plugboard.tui",
+  setup(context) {
+    const [previous, setPrevious] = createSignal({ ...context.ui.router.current() })
+    context.ui.router.register({
+      name: "plugboard.usage",
+      render: () => <UsagePage context={context} onClose={() => context.ui.router.navigate(previous())} />,
+    })
+    context.keymap.layer(() => ({
+      mode: "global",
+      commands: [
+        {
+          id: "plugboard.usage.open",
+          title: "Plugboard usage",
+          group: "Plugboard",
+          slash: { name: "plugboard" },
+          palette: true,
+          run() {
+            const current = context.ui.router.current()
+            if (current.type === "plugin" && current.name === "plugboard.usage") return
+            // The router exposes a mutable store; keep the route before navigating.
+            setPrevious({ ...current })
+            context.ui.dialog.clear()
+            context.ui.router.navigate({ type: "plugin", name: "plugboard.usage" })
+          },
+        },
+      ],
+    }))
+  },
+})

package/src/usage-header.ts

@@ -0,0 +1,46 @@
+/**
+ * `x-plugboard-usage` (#52): the tokens and USD cost of the model calls a response answered, so a
+ * caller sees what one request cost without asking `GET /v1/usage`. It is set only while usage
+ * recording is on (`withUsage`, src/usage.ts), and only on a non-streaming response: a stream
+ * sends its headers with its first event, before the usage is known, so it has no such header.
+ */
+import type { ServerResponse } from "node:http"
+import type { CallTotals } from "./contract.js"
+
+export const USAGE_HEADER = "x-plugboard-usage"
+
+/** The totals of one response, summed over its calls. `costUsd` is undefined when any call had no price. */
+interface Totals {
+  readonly inputTokens: number
+  readonly outputTokens: number
+  readonly cacheReadTokens: number
+  readonly costUsd?: number
+}
+
+/** `input=<n>; output=<n>; cache_read=<n>; cost_usd=<x.xxxxxx>`; the cost part is left out for an unpriced model. */
+export function formatUsage(totals: Totals): string {
+  const parts = [`input=${totals.inputTokens}`, `output=${totals.outputTokens}`, `cache_read=${totals.cacheReadTokens}`]
+  if (totals.costUsd !== undefined) parts.push(`cost_usd=${totals.costUsd.toFixed(6)}`)
+  return parts.join("; ")
+}
+
+/**
+ * The `CallContext.onUsage` of one response: each answered call adds its totals and the header
+ * is rewritten while the headers are still open, so the fan-out's `n` choices sum into one value.
+ * `undefined` for a stream (see the module comment).
+ */
+export function reportUsage(response: ServerResponse, stream: boolean): ((call: CallTotals) => void) | undefined {
+  if (stream) return undefined
+  let totals: Totals = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, costUsd: 0 }
+  return (call) => {
+    if (response.headersSent || response.destroyed) return
+    const costUsd = totals.costUsd === undefined || call.costUsd === undefined ? undefined : totals.costUsd + call.costUsd
+    totals = {
+      inputTokens: totals.inputTokens + call.inputTokens,
+      outputTokens: totals.outputTokens + call.outputTokens,
+      cacheReadTokens: totals.cacheReadTokens + call.cacheReadTokens,
+      ...(costUsd === undefined ? {} : { costUsd }),
+    }
+    response.setHeader(USAGE_HEADER, formatUsage(totals))
+  }
+}