opencode-plugboard 0.18.0 → 0.19.0

package/src/gemini/route.ts

@@ -21,6 +21,7 @@ import { boundEvents, checkJsonContentType, readJsonBody, sendError, sendJson, s
 import { listAvailableModels, resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
+import { reportUsage } from "../usage-header.js"
 import type { RouteHost } from "../openai/route.js"
 import { dropRejected } from "../openai/sampling.js"
 import { estimateTokens } from "../anthropic/tokens.js"
@@ -162,6 +163,7 @@ export async function serveGemini(host: RouteHost, { match, request, url, app, r
       },
       onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
       onPolicy: reportPolicy(response),
+      onUsage: reportUsage(response, match.stream),
       onCache: reportCache(response),
     }),
     scope,

package/src/log.ts

@@ -142,5 +142,8 @@ export const log = (event: string, fields?: LogFields): void => state().logger.i
 
 export const logError = (event: string, fields?: LogFields): void => state().logger.error(record(event, fields))
 
+/** A line for something that needs attention but did not fail a request (a budget at 80%). Info-level destination, `warn` in the level field. */
+export const logWarn = (event: string, fields?: LogFields): void => state().logger.warn(record(event, fields))
+
 /** The message of a thrown value, without its stack or attached properties. */
 export const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error))

package/src/metrics.ts

@@ -62,8 +62,8 @@ export interface Metrics {
   dropped(params: ReadonlyArray<string>): void
   /** A model call failed before any output and was retried on the next target of its alias. */
   fallback(app: string): void
-  /** A call was refused with 429 by a concurrency cap (`concurrency`) or a requests-per-minute limit (`rate`). */
-  limited(app: string, reason: "concurrency" | "rate"): void
+  /** A call was refused with 429 by a concurrency cap (`concurrency`), a requests-per-minute limit (`rate`) or a budget (`budget`). */
+  limited(app: string, reason: "concurrency" | "rate" | "budget"): void
   /** A call the response cache applied to: a stored answer replayed (`hit`) or the model run (`miss`). */
   cache(app: string, result: "hit" | "miss"): void
   /** One history sweep ended. */
@@ -110,7 +110,7 @@ export function createMetrics(): Metrics {
   })
   const limited = new Counter({
     name: "plugboard_limited_total",
-    help: "Model calls refused with 429 by a concurrency cap or a requests-per-minute limit, by app and reason.",
+    help: "Model calls refused with 429 by a concurrency cap, a requests-per-minute limit or a budget, by app and reason.",
     labelNames: ["app", "reason"],
     registers: [registry],
   })

package/src/openai/fanout.ts

@@ -25,6 +25,7 @@ import type { PlugError, PlugEvent, PlugRequest, PlugUsage } from "../contract.j
 import { reportServed, type ServedInfo } from "../fallback.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
+import { reportUsage } from "../usage-header.js"
 import { RequestAborted, boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "../http.js"
 import { chatUsageChunk, collectCompletion, encodeError, streamCompletion, type OpenAiExchange, type StreamChoice, type StreamResult } from "./response.js"
 import type { RouteHost } from "./route.js"
@@ -169,6 +170,8 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
     if (calls.length === 1) codec.setModel(s.model)
   })
   const policy = reportPolicy(response)
+  // One header for all choices: each answered call adds its tokens and cost (`x-plugboard-usage`, #52).
+  const usageHeader = reportUsage(response, codec.stream)
   // Each choice is a fresh sample: the response cache never serves or stores fan-out calls.
   const cache = reportCache(response)
   const open = (index: number) =>
@@ -183,6 +186,7 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
         },
         onServed: served,
         onPolicy: policy,
+        onUsage: usageHeader,
         onCache: cache,
         noCache: calls.length > 1,
       }),

package/src/openai/request.ts

@@ -339,6 +339,7 @@ export function parseChatRequest(body: unknown, options: PlugboardOptions): Pars
       includeUsage: streamOptions.include_usage === true,
       ...(respond ? { structuredTool: RESPOND_TOOL, ...(withCallerTools ? { callerTools: true } : {}) } : {}),
       ...(format.instruction ? { jsonObject: true } : {}),
+      ...(generation.stop ? { stop: generation.stop } : {}),
     },
     ...(typeof body.reasoning_effort === "string" ? { reasoningEffort: body.reasoning_effort } : {}),
   }

package/src/openai/response.ts

@@ -6,6 +6,7 @@
  */
 import type { PlugError, PlugErrorKind, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
 import type { ListedModel } from "../models.js"
+import { StopHoldback, stripStopTail } from "../stop.js"
 
 type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
 
@@ -33,6 +34,8 @@ export interface OpenAiExchange {
    * stripped from the content (`unfence`).
    */
   readonly jsonObject?: boolean
+  /** The request's `stop`. A plain stop whose text ends with one of these leaves the sequence out (src/stop.ts). Not applied to structured output. */
+  readonly stop?: ReadonlyArray<string>
 }
 
 /** How a streamed exchange ended. Nothing was written when `failure` is set and `started` is false: the caller answers with a real HTTP error. */
@@ -219,6 +222,7 @@ export async function collectCompletion(
     const error = failure ?? noFinish()
     return { status: error.status, body: encodeError(error), retryAfterSeconds: error.retryAfterSeconds }
   }
+  if (finish === "stop" && calls.length === 0 && exchange.structuredTool === undefined) text = stripStopTail(text, exchange.stop ?? []).text
 
   const answer = calls.find((call) => structured.isAnswer(exchange, call))
   const others = calls.filter((call) => !structured.isAnswer(exchange, call))
@@ -309,6 +313,12 @@ export async function streamCompletion(
     started = true
     chunk({ role: "assistant", content: "" })
   }
+  // A stop sequence is held back until the finish decides it (src/stop.ts). Structured output has none.
+  const holdback = exchange.structuredTool === undefined ? new StopHoldback(exchange.stop ?? []) : undefined
+  const send = (text: string) => {
+    const out = holdback ? holdback.push(text) : text
+    if (out.length > 0) chunk({ content: out })
+  }
   // json_object: text that opens with a backtick may be a fenced answer, so it waits (as `pending`)
   // until a tool call or the finish shows the whole text; anything else streams as it comes. A
   // fenced answer therefore arrives as one chunk.
@@ -319,7 +329,7 @@ export async function streamCompletion(
     const text = unfence(pending)
     pending = ""
     start()
-    chunk({ content: text })
+    send(text)
   }
 
   for await (const event of events) {
@@ -359,10 +369,14 @@ export async function streamCompletion(
       }
       continue
     }
-    if (event.type !== "text-delta") flush()
+    if (event.type !== "text-delta") {
+      flush()
+      const rest = holdback?.release() ?? ""
+      if (rest.length > 0) chunk({ content: rest })
+    }
     start()
     if (event.type === "text-delta") {
-      if (event.text.length > 0) chunk({ content: event.text })
+      send(event.text)
     } else {
       // Tool calls arrive whole, so each goes out as one chunk with the next index.
       chunk({ tool_calls: [{ index: calls++, id: event.id, type: "function", function: { name: event.name, arguments: args(event.input) } }] })
@@ -382,6 +396,10 @@ export async function streamCompletion(
   }
   flush()
   start()
+  if (holdback) {
+    const rest = holdback.finish(finish === "stop" && calls === 0).text
+    if (rest.length > 0) chunk({ content: rest })
+  }
   if (held && isStructured) chunk({ content: structured.content(held) })
   chunk({}, finishReason(finish!, calls, isStructured))
   if (choice) return { started, ...(usage ? { usage } : {}) }

package/src/openai/route.ts

@@ -46,10 +46,12 @@ import { NO_APP, outcomeLabel, type Metrics } from "../metrics.js"
 import { filterByCapability, listAvailableModels, parseCapability, resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
+import { reportUsage } from "../usage-header.js"
 import { isMessagesPath, serveMessages } from "../anthropic/route.js"
 import { serveCompletions } from "../completions/route.js"
 import { serveResponses } from "../responses/route.js"
 import { liveOptions, processMetrics, processStatus, type RuntimeStatus } from "../runtime.js"
+import { budgetFor, budgetStatus } from "../budgets.js"
 import type { UsageRecorder } from "../usage.js"
 import { DASHBOARD_ROUTES } from "../dashboard/page.js"
 import { serveDashboard } from "../dashboard/assets.js"
@@ -154,7 +156,9 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     const path = url.pathname
     const modelId = request.method === "GET" && path.startsWith(MODEL_PREFIX) && path.length > MODEL_PREFIX.length ? decodeSegment(path.slice(MODEL_PREFIX.length)) : undefined
     const gemini = matchGeminiRoute(request.method, path)
-    if (gemini) googleErrors.add(response)
+    // Any /v1beta path is Google's API, even one that matches no Gemini route (#150): its errors use Google's body.
+    const googleShaped = gemini !== undefined || path === "/v1beta" || path.startsWith("/v1beta/")
+    if (googleShaped) googleErrors.add(response)
     const route = gemini?.route ?? `${request.method} ${modelId !== undefined ? "/v1/models/{id}" : path}`
     // Arbitrary client paths stay out of the log.
     info.route = gemini || modelId !== undefined || known(route) || route === "GET /healthz" ? route : "unknown"
@@ -190,10 +194,19 @@ export function createOpenAiRoute(routeHost: RouteHost) {
 
     // Authenticate before anything reveals which routes exist: an unauthenticated caller sees 401 for every path but /healthz and the first-run pages.
     // Gemini clients also send the key as `x-goog-api-key` or `?key=` (see `geminiAuthorization`).
-    const auth = authenticate(liveOptions(host.options), gemini ? geminiAuthorization(request, url) : request.headers.authorization)
+    const auth = authenticate(liveOptions(host.options), googleShaped ? geminiAuthorization(request, url) : request.headers.authorization)
     if (isPlugError(auth)) return fail(response, auth)
     info.app = auth.app
 
+    // A /v1beta path no Gemini route matches: the AI SDK and LangChain send a model id with a slash and no `models/` prefix (#150).
+    if (googleShaped && !gemini)
+      return fail(response, {
+        status: 404,
+        kind: "not_found",
+        code: "not_found",
+        message: `No Gemini route for ${request.method} ${path}. Expected POST /v1beta/models/{model}:generateContent or POST /v1beta/models/{model}:streamGenerateContent; the path must start with /v1beta/models/. GET /v1beta/models lists the models.`,
+      })
+
     if (!gemini && modelId === undefined && !known(route)) {
       return fail(response, {
         status: 404,
@@ -274,6 +287,7 @@ export function createOpenAiRoute(routeHost: RouteHost) {
         // An alias with fallbacks: report which target answered, and echo it as the response model.
         onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
         onPolicy: reportPolicy(response),
+        onUsage: reportUsage(response, exchange.stream),
         onCache: reportCache(response),
       }),
       scope,
@@ -318,6 +332,14 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       app: who.admin ? app : who.app,
     })
     if (isPlugError(report)) return fail(response, report)
+    // Each app's budget state, read from its current window rather than from the report's range (src/budgets.ts).
+    if (host.options.budgets) {
+      const at = Date.now()
+      for (const [name, entry] of Object.entries(report.apps)) {
+        const budget = budgetFor(host.options.budgets, name)
+        if (budget) entry.budgets = await budgetStatus(usage, budget, name, at)
+      }
+    }
     return sendJson(response, 200, report)
   }
 

package/src/responses/request.ts

@@ -2,10 +2,11 @@
  * OpenAI Responses request -> neutral `PlugRequest` plus the `ResponsesExchange` the response
  * encoder needs.
  *
- * Pure function: no I/O. Stateless subset: the caller sends the whole conversation in `input`
- * each time, which is how history already works. Anything that needs server-side state
- * (`previous_response_id`, `conversation`, `item_reference`, `background`) or a hosted tool is
- * rejected with 400 `unsupported_parameter` naming the field. The route resolves `model` to a
+ * Pure function: no I/O. The caller sends the whole conversation in `input` each time, which is
+ * how history already works. An `item_reference` is resolved through the `resolve` argument (the
+ * route passes the per-app store of recent answers, src/responses/store.ts; #147). Anything else that
+ * needs server-side state (`previous_response_id`, `conversation`, `background`) or a hosted tool
+ * is rejected with 400 `unsupported_parameter` naming the field. The route resolves `model` to a
  * `ModelRef` afterwards, which is why the request omits `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
@@ -121,7 +122,23 @@ const assistantText = (content: unknown, param: string): string | PlugError => {
  * assistant message, the shape the Chat Completions front-end produces, so a parallel-call turn
  * is one message followed by its results.
  */
-const parseInput = (input: unknown): { system: string[]; messages: PlugMessage[] } | PlugError => {
+/** The output item an `item_reference` names, or undefined when the app's store does not hold it. */
+export type ItemResolver = (itemId: string) => JsonObject | undefined
+
+/** An `item_reference` is the output item of an earlier answer, decoded as that item (#147). */
+const resolveReference = (item: JsonObject, param: string, resolve: ItemResolver | undefined): JsonObject | PlugError => {
+  if (typeof item.id !== "string" || item.id.length === 0) return bad("item_reference needs the id of an output item", `${param}.id`)
+  const found = resolve?.(item.id)
+  if (found === undefined)
+    return bad(
+      `item_reference "${item.id}" is not known to plugboard: it keeps the output of recent answers for an hour, per app. Send the earlier items in full, or send store: false (Vercel AI SDK: providerOptions.openai.store = false)`,
+      `${param}.id`,
+      "item_not_found",
+    )
+  return found
+}
+
+const parseInput = (input: unknown, resolve: ItemResolver | undefined): { system: string[]; messages: PlugMessage[] } | PlugError => {
   if (typeof input === "string") return { system: [], messages: [{ role: "user", content: [{ type: "text", text: input }] }] }
   if (!Array.isArray(input) || input.length === 0) return bad("input must be a string or a non-empty array of items", "input")
 
@@ -134,9 +151,11 @@ const parseInput = (input: unknown): { system: string[]; messages: PlugMessage[]
     pending = undefined
   }
 
-  for (const [index, item] of input.entries()) {
+  for (const [index, given] of input.entries()) {
     const param = `input[${index}]`
-    if (!isRecord(item)) return bad("Each input item must be an object", param)
+    if (!isRecord(given)) return bad("Each input item must be an object", param)
+    const item = given.type === "item_reference" ? resolveReference(given, param, resolve) : given
+    if (isPlugError(item)) return item
     const type = item.type ?? (item.role !== undefined ? "message" : undefined)
     switch (type) {
       case "message": {
@@ -192,11 +211,6 @@ const parseInput = (input: unknown): { system: string[]; messages: PlugMessage[]
       // Reasoning items carry no content plugboard can replay; they are dropped.
       case "reasoning":
         break
-      case "item_reference":
-        return unsupported(
-          "item_reference needs server-side state, which plugboard does not keep; send the full items instead (Vercel AI SDK: providerOptions.openai.store = false)",
-          `${param}.type`,
-        )
       default:
         return unsupported(`Unsupported input item type "${String(type)}"`, `${param}.type`)
     }
@@ -296,7 +310,7 @@ const checkUnsupported = (body: JsonObject): PlugError | undefined => {
   if (body.truncation != null && body.truncation !== "disabled") return unsupported('Only truncation "disabled" is supported', "truncation")
 }
 
-export function parseResponsesRequest(body: unknown, options: PlugboardOptions): ParsedResponses | PlugError {
+export function parseResponsesRequest(body: unknown, options: PlugboardOptions, resolve?: ItemResolver): ParsedResponses | PlugError {
   if (!isRecord(body)) return bad("Request body must be a JSON object")
   if (typeof body.model !== "string" || body.model.length === 0) return bad("model is required", "model")
   if (body.input == null) return bad("input is required", "input")
@@ -305,7 +319,7 @@ export function parseResponsesRequest(body: unknown, options: PlugboardOptions):
   if (body.instructions != null && typeof body.instructions !== "string") return bad("instructions must be a string", "instructions")
   if (body.reasoning != null && !isRecord(body.reasoning)) return bad("reasoning must be an object", "reasoning")
 
-  const parsed = parseInput(body.input)
+  const parsed = parseInput(body.input, resolve)
   if (isPlugError(parsed)) return parsed
   const callerTools = parseTools(body.tools)
   if (!Array.isArray(callerTools)) return callerTools

package/src/responses/route.ts

@@ -15,10 +15,12 @@ import { boundEvents, sendError, sendJson, sseWriter, type RequestScope } from "
 import { resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
 import { reportPolicy } from "../policy.js"
+import { reportUsage } from "../usage-header.js"
 import { encodeError } from "../openai/response.js"
 import type { RouteHost } from "../openai/route.js"
 import { parseResponsesRequest } from "./request.js"
 import { runResponse, sseFrame } from "./response.js"
+import { findItem, rememberAnswer } from "./store.js"
 
 const SESSION_HEADER = "x-plugboard-session"
 
@@ -34,7 +36,7 @@ export interface ResponsesCall {
 export async function serveResponses(host: RouteHost, { app, body, response, scope, info }: ResponsesCall): Promise<void> {
   const fail = (error: PlugError) => sendError(response, error, encodeError(error))
 
-  const parsed = parseResponsesRequest(body, host.options)
+  const parsed = parseResponsesRequest(body, host.options, (itemId) => findItem(app, itemId))
   if (isPlugError(parsed)) return fail(parsed)
   const catalog = await scope.race(host.loadCatalog())
   const ref = resolveModel(host.options, parsed.request.model, catalog, parsed.reasoningEffort)
@@ -55,6 +57,7 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
       },
       onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
       onPolicy: reportPolicy(response),
+      onUsage: reportUsage(response, exchange.stream),
       onCache: reportCache(response),
     }),
     scope,
@@ -62,11 +65,12 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
 
   if (exchange.stream) {
     const sse = sseWriter(response, scope.signal)
-    const { failure } = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)), () => sse.started)
+    const run = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)), () => sse.started)
+    if (run.response && !run.failure) rememberAnswer(app, run.response)
     if (!sse.started && !response.headersSent) {
-      if (!scope.signal.aborted || scope.timedOut) fail(failure ?? { status: 502, kind: "server", message: "No response from the model" })
+      if (!scope.signal.aborted || scope.timedOut) fail(run.failure ?? { status: 502, kind: "server", message: "No response from the model" })
     } else {
-      if (failure) info.failed = failure.code ?? failure.kind
+      if (run.failure) info.failed = run.failure.code ?? run.failure.kind
       if (!response.writableEnded) response.end()
     }
     return
@@ -74,5 +78,6 @@ export async function serveResponses(host: RouteHost, { app, body, response, sco
 
   const run = await runResponse(events, exchange, () => {})
   if (run.failure || !run.response) return fail(run.failure ?? { status: 502, kind: "server", message: "No response from the model" })
+  rememberAnswer(app, run.response)
   sendJson(response, 200, run.response)
 }

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