opencode-plugboard 0.18.0 → 0.20.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/rpc.ts

@@ -26,6 +26,7 @@ export const UsageRpc = Rpc.define({
           from: { type: "string", description: "First UTC day, YYYY-MM-DD. Default: 29 days before `to`." },
           to: { type: "string", description: "Last UTC day, YYYY-MM-DD. Default: today." },
           app: { type: "string", description: "One app name. Default: every app." },
+          user: { type: "string", description: "One end user id. Each app's `users` then lists only that user. Default: every user." },
         },
         additionalProperties: false,
       },
@@ -37,7 +38,7 @@ export const UsageRpc = Rpc.define({
       errors: {
         invalid_query: {
           type: "object",
-          properties: { param: { type: "string", description: "The query parameter that is wrong: from, to or app." } },
+          properties: { param: { type: "string", description: "The query parameter that is wrong: from, to, app or user." } },
           required: ["param"],
           additionalProperties: false,
         },
@@ -51,7 +52,7 @@ export const UsageRpc = Rpc.define({
 function queryOf(input: unknown): UsageQuery {
   const record: Record<string, unknown> = typeof input === "object" && input !== null ? (input as Record<string, unknown>) : {}
   const text = (value: unknown) => (typeof value === "string" ? value : undefined)
-  return { from: text(record.from), to: text(record.to), app: text(record.app) }
+  return { from: text(record.from), to: text(record.to), app: text(record.app), user: text(record.user) }
 }
 
 /** The handlers for `UsageRpc`, reading the given usage query (the generation's recorder). */

package/src/runtime.ts

@@ -53,6 +53,7 @@ import { Cause, Effect, Stream } from "effect"
 import stableStringify from "safe-stable-stringify"
 import { raceAbort } from "./abort.js"
 import { cachedCaller, createCacheStore, type CacheStore } from "./cache.js"
+import { personaOf } from "./models.js"
 import type { PlugboardOptions } from "./config.js"
 import { isPlugError, type CatalogModel, type ModelCaller, type PlugError } from "./contract.js"
 import { errorMessage, log, logError, outsideRequest, setLogFormat } from "./log.js"
@@ -62,6 +63,8 @@ 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 { createKeyState, type KeyState } from "./keys.js"
 import { createUsageState, type UsageState } from "./usage.js"
 
 export type Handler = (request: IncomingMessage, response: ServerResponse) => void
@@ -115,8 +118,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
+/** 14: the runtime app keys (src/keys.ts, #55) are cached here, so a key created or revoked through the admin routes holds across plugin generations. 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 = 14
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -180,6 +183,10 @@ 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
+  /** The runtime app keys (src/keys.ts), loaded from storage on the first authentication. */
+  readonly runtimeKeys: KeyState
   listener?: Listener
   /** Present while a fiber is subscribed to the server event bus. */
   pump?: Pump
@@ -193,6 +200,8 @@ const detachedMetrics = createMetrics()
 const detachedStartedAt = Date.now()
 const detachedLimits = createLimitState()
 const detachedUsage = createUsageState()
+const detachedBudgets = createBudgetState()
+const detachedKeys = createKeyState()
 let foreignVersionLogged = false
 
 /** The process runtime, created on first use; undefined when a different version already owns the process. */
@@ -210,6 +219,8 @@ function runtime(): Runtime | undefined {
       metrics: createMetrics(),
       limits: createLimitState(),
       usage: createUsageState(),
+      budgets: createBudgetState(),
+      runtimeKeys: createKeyState(),
       startedAt: Date.now(),
     }
     slot[KEY] = created
@@ -291,6 +302,12 @@ 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 runtime app keys' cache shared by every generation in the process (detached under a foreign-version runtime). */
+export const processKeys = (): KeyState => runtime()?.runtimeKeys ?? detachedKeys
+
 /**
  * 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).
@@ -328,7 +345,7 @@ export function withResponseCache(caller: ModelCaller, options: PlugboardOptions
       if (rt) rt.cache = held
     }
     const count = options.metrics ? (app: string, result: "hit" | "miss") => processMetrics().cache(app, result) : undefined
-    return cachedCaller(caller, config, held.store, count)
+    return cachedCaller(caller, config, held.store, count, (model) => personaOf(options, model) !== undefined)
   }
   return { stream: (request, context) => (wrapped ??= build()).stream(request, context) }
 }

package/src/session/caller.ts

@@ -21,7 +21,7 @@ import { raceAbort } from "../abort.js"
 import { APP_NAME_PATTERN, DEFAULT_APP, appPolicy, type AppPolicy, type PlugboardOptions } from "../config.js"
 import { isPlugError, type CallContext, type ModelCaller, type PlugError, type PlugEvent, type PlugRequest } from "../contract.js"
 import { log, logError } from "../log.js"
-import { checkAppModel } from "../models.js"
+import { checkAppModel, type Persona } from "../models.js"
 import { RequestCollector } from "./events.js"
 import { ensureAppDir, makeTitle, renderTranscript } from "./history.js"
 import { describeError, type SessionPort } from "./host.js"
@@ -44,6 +44,11 @@ export interface SessionCallerDeps {
    * called right before `session.create`. An error ends the request without creating anything.
    */
   readonly ensureBackend?: (app: string, signal: AbortSignal) => Promise<PlugError | undefined>
+  /**
+   * What the requested name stands for beyond a plain model (`personaOf` in src/models.ts): a skill alias adds
+   * the skill's content to the system prompt, an agent runs its own system prompt and OpenCode agent.
+   */
+  readonly persona?: (model: string) => Persona | undefined
 }
 
 /** How long the request guard may outlive the response while the host has not reported the end of the execution. */
@@ -54,6 +59,8 @@ const failure = (status: number, message: string, code: string): PlugEvent => ({
   error: { status, kind: status >= 500 ? "server" : "invalid_request", message, code },
 })
 
+const notFound = (message: string): PlugError => ({ status: 404, kind: "not_found", message, code: "model_not_found", param: "model" })
+
 const countMedia = (request: PlugRequest): number =>
   request.messages.reduce((sum, message) => sum + message.content.filter((part) => part.type === "media").length, 0)
 
@@ -123,7 +130,7 @@ export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
       const policy = appPolicy({ apps }, app)
       const outOfScope = checkAppModel(policy, called.model, called.ref)
       if (outOfScope) return yield note({ type: "error", error: outOfScope })
-      const { request, stripped } = applyToolPolicy(called, policy)
+      let { request, stripped } = applyToolPolicy(called, policy)
       const tooMany = checkAppTools(request, app, policy)
       if (tooMany) return yield note({ type: "error", error: tooMany })
       if (stripped) {
@@ -166,23 +173,39 @@ export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
         if (unavailable) return yield note({ type: "error", error: unavailable })
         if (context.signal.aborted) return
 
+        // 3b. A persona (see `Persona`). A skill's content leads the system prompt; an agent's prompt replaces the
+        // caller's, and the session runs as that agent. Its permissions are still REQUEST_PERMISSIONS (deny all, then seeds).
+        const persona = deps.persona?.(called.model)
+        let prelude: ReadonlyArray<string> = []
+        if (persona?.kind === "skill") {
+          const content = await port.skill(directory, persona.skill)
+          if (content === undefined) return yield note({ type: "error", error: notFound(`Skill ${persona.skill} is not available`) })
+          prelude = [content]
+        } else if (persona?.kind === "agent") {
+          const agent = await port.agent(directory, persona.agent)
+          if (agent === undefined) return yield note({ type: "error", error: notFound(`Agent ${persona.agent} is not available`) })
+          request = { ...request, system: agent.system ? [agent.system] : [] }
+        }
+        if (context.signal.aborted) return
+
         collector = new RequestCollector({ stopTurn: interrupt, requestID })
         const created = await raceAbort(port.create({
           directory,
           model: { providerID: request.ref.providerID, id: request.ref.id, ...(request.ref.variant ? { variant: request.ref.variant } : {}) },
+          ...(persona?.kind === "agent" ? { agent: persona.agent } : {}),
           title: makeTitle(request),
           metadata: { plugboard: { app, model: request.model, requestID } },
           permissions: REQUEST_PERMISSIONS,
         }), context.signal)
         sessionID = String(created.id)
-        sessions.register({ sessionID, app, requestID, request, collector })
+        sessions.register({ sessionID, app, requestID, request, collector, prelude })
 
         context.signal.addEventListener("abort", onAbort, { once: true })
         if (context.signal.aborted) return onAbort()
 
         // The history id is known from here on: tell the front-end before the first event.
         try {
-          context.onRecord?.(sessionID)
+          context.onRecord?.(sessionID, directory)
         } catch (error) {
           logError("request.on_record_failed", { requestID, app, error: describeError(error) })
         }

package/src/session/context.ts

@@ -123,7 +123,9 @@ function applyContext(event: unknown, sessions: SessionStore, apps: PlugboardOpt
     return text("[image unavailable]")
   }
 
-  const system = systemFor(request.system, appPolicy({ apps }, state.app)).map(text)
+  // Order: the skill's content (prelude), then the app's system policy over the caller's (or an agent's) prompt,
+  // then the tool-choice steering below.
+  const system = [...(state.prelude ?? []), ...systemFor(request.system, appPolicy({ apps }, state.app))].map(text)
   // The OpenCode session API has no tool-choice control, so a forced or required tool is steered by instruction.
   const choice = request.toolChoice
   if (choice === "required") system.push(text("You must respond by calling one of the provided tools."))

package/src/session/history.ts

@@ -61,10 +61,16 @@ const CONTROLS_KEEP_LAYOUT = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u20
 /** One display line: whitespace (including line breaks) collapsed to single spaces, then control and bidi characters removed. */
 export const oneLine = (text: string): string => text.replace(/\s+/g, " ").replace(CONTROLS, "").trim()
 
-/** Session title: the first user text, one line, control and bidi characters removed, cut to 60 characters. */
+/**
+ * Session title: the end user as `[user] ` when the caller named one (#57), then the first user text, one
+ * line, control and bidi characters removed. The whole title is cut to 60 characters.
+ */
 export const makeTitle = (request: PlugRequest): string => {
+  const prefix = request.user === undefined ? "" : `[${request.user}] `
   const flat = oneLine(firstUserText(request))
-  return flat.length > TITLE_LENGTH ? flat.slice(0, TITLE_LENGTH - 1) + "…" : flat
+  const room = TITLE_LENGTH - prefix.length
+  const text = flat.length > room ? flat.slice(0, room - 1) + "…" : flat
+  return (prefix + text).trimEnd()
 }
 
 /** Readable transcript stored as the session's prompt; images are listed by attachment number. */

package/src/session/host.ts

@@ -24,12 +24,18 @@ export interface SessionPort {
   create(input: {
     readonly directory: string
     readonly model: { readonly providerID: string; readonly id: string; readonly variant?: string }
+    /** The OpenCode agent the session runs as (option `agents`); absent: the host's default agent. */
+    readonly agent?: string
     readonly title: string
     readonly metadata: { readonly [key: string]: Json }
     readonly permissions: ReadonlyArray<{ action: string; resource: string; effect: "allow" | "deny" }>
   }): Promise<{ id: string }>
   prompt(input: { readonly sessionID: string; readonly text: string; readonly files: ReadonlyArray<{ uri: string; name: string }> }): Promise<unknown>
   interrupt(sessionID: string): Promise<void>
+  /** The content of skill `id` in the Location at `directory`, or undefined when there is none. Briefly cached per directory. */
+  skill(directory: string, id: string): Promise<string | undefined>
+  /** The agent `id` in the Location at `directory` (its `system` prompt may be absent), or undefined when there is none. */
+  agent(directory: string, id: string): Promise<{ readonly system?: string } | undefined>
 }
 
 type HostSession = HostContext["session"]
@@ -45,6 +51,10 @@ const hostSessionID = (id: string): HostSessionID => id as HostSessionID
 type HostCreate = NonNullable<Parameters<HostSession["create"]>[0]>
 type HostModelRef = NonNullable<HostCreate["model"]>
 type HostDirectory = NonNullable<HostCreate["location"]>["directory"]
+type HostAgent = NonNullable<HostCreate["agent"]>
+
+/** How long a directory's skill list is reused: a skill edit is seen within this window (per plugin generation). */
+const SKILL_CACHE_MS = 30_000
 
 /**
  * Branded model ref and directory. Same kind of cast as the session ID: the values are the
@@ -65,17 +75,33 @@ const hostDirectory = (directory: string): HostDirectory => directory as HostDir
  */
 export function createSessionPort(ctx: HostContext): SessionPort {
   const run = <A>(effect: Effect.Effect<A, unknown>): Promise<A> => Effect.runPromise(effect)
+  const skillsByDirectory = new Map<string, { readonly at: number; readonly skills: ReadonlyMap<string, string> }>()
   return {
     create: (input) =>
       run(
         ctx.session.create({
           model: hostModel(input.model),
+          ...(input.agent === undefined ? {} : { agent: input.agent as HostAgent }),
           title: input.title,
           metadata: input.metadata,
           permissions: input.permissions,
           location: { directory: hostDirectory(input.directory) },
         } satisfies HostCreate),
       ).then((created) => ({ id: String(created.id) })),
+    skill: async (directory, id) => {
+      const now = Date.now()
+      let held = skillsByDirectory.get(directory)
+      if (held === undefined || now - held.at >= SKILL_CACHE_MS) {
+        const listed = await run(ctx.skill.list({ location: { directory } }))
+        held = { at: now, skills: new Map(listed.data.map((skill): [string, string] => [skill.id, skill.content])) }
+        skillsByDirectory.set(directory, held)
+      }
+      return held.skills.get(id)
+    },
+    agent: async (directory, id) => {
+      const listed = await run(ctx.agent.list({ location: { directory } }))
+      return listed.data.find((agent) => agent.id === id)
+    },
     prompt: (input) =>
       run(
         ctx.session.prompt({

package/src/session/link.ts

@@ -0,0 +1,33 @@
+/**
+ * Links from a response to the OpenCode session page of its request (#77). The host exposes no UI URL
+ * to a plugin, so option `historyUrl` is a template the operator fills in for how they reach OpenCode:
+ * `{id}` is the session id, `{directory}` the app directory (URL-encoded). With the option set, a
+ * response that carries `x-plugboard-session` also carries `x-plugboard-session-url` with the filled
+ * link, and the request log line gains `session_url=`.
+ *
+ * Pure: no node imports. The routes call `setSessionLink` from their `onRecord` callback, after they
+ * set the session header, so a link is only ever sent for a session that was named.
+ */
+
+export const SESSION_URL_HEADER = "x-plugboard-session-url"
+
+/** The template with `{id}` and `{directory}` filled (both URL-encoded). */
+export function sessionUrl(template: string, recordID: string, directory = ""): string {
+  return template.replaceAll("{id}", encodeURIComponent(recordID)).replaceAll("{directory}", encodeURIComponent(directory))
+}
+
+/**
+ * Sets `x-plugboard-session-url` for one history record and the log field, when a template is set.
+ * Nothing happens without a template, so a route calls this unconditionally.
+ */
+export function setSessionLink(
+  response: { setHeader(name: string, value: string): unknown },
+  info: { sessionUrl?: string },
+  template: string | undefined,
+  recordID: string,
+  directory?: string,
+): void {
+  if (template === undefined) return
+  info.sessionUrl = sessionUrl(template, recordID, directory)
+  response.setHeader(SESSION_URL_HEADER, info.sessionUrl)
+}

package/src/session/state.ts

@@ -32,6 +32,8 @@ export interface RequestState {
   readonly requestID: string
   readonly request: PlugRequest
   readonly collector: EventSink
+  /** System parts placed before the app's and the caller's (a skill's content, option `skill:` alias). Empty or absent for a plain model. */
+  readonly prelude?: ReadonlyArray<string>
 }
 
 export interface Retirement {

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/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))
+  }
+}