opencode-plugboard 0.2.1 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ You logged in to ChatGPT, Claude, Copilot or OpenCode Go once, in OpenCode. Your
 
 OpenCode V2 has no such endpoint, and the V1 plugins that did this stopped working when the plugin API changed. Plugboard is V2 only. It was tested on OpenCode 2.0.26, and the peer range `>=2.0.26 <2.1` allows 2.0.x patch releases.
 
-Status: v0.1, in development and not published yet. Chat Completions and the model list only. There is no `/v1/responses`, see [Known gaps](#known-gaps) and the [roadmap](#roadmap).
+Status: early (0.x), [published on npm](https://www.npmjs.com/package/opencode-plugboard). Chat Completions, the Responses API and the model list. `/v1/responses` is a stateless subset, see [docs/responses.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/responses.md).
 
 Docs: [architecture](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/architecture.md), [development](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/development.md), [clients](#clients).
 
@@ -75,7 +75,7 @@ One short page per client, with a config snippet, a chat, a tool call, a structu
 | --- | --- | --- |
 | OpenAI Python SDK | [openai-python](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/openai-python.md) | pass |
 | OpenAI JS SDK | [openai-js](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/openai-js.md) | pass |
-| Vercel AI SDK | [vercel-ai-sdk](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/vercel-ai-sdk.md) | pass with `createOpenAICompatible` or `.chat()`; structured output needs `supportsStructuredOutputs: true` there; the default `@ai-sdk/openai` call needs `/v1/responses` |
+| Vercel AI SDK | [vercel-ai-sdk](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/vercel-ai-sdk.md) | pass with `createOpenAICompatible` or `.chat()`; structured output needs `supportsStructuredOutputs: true` there; the default `openai(id)` call works through `/v1/responses` (set `store: false` for multi-turn) |
 | LangChain Python | [langchain-python](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/langchain-python.md) | pass; `json_mode` on `fast` was unreliable |
 | LangChain JS | [langchain-js](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/langchain-js.md) | pass except `gpt-5.6*` ids, which force the Responses API, and `json_mode` on `fast` |
 | pydantic-ai | [pydantic-ai](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/pydantic-ai.md) | pass with `OpenAIChatModel` |
@@ -83,13 +83,13 @@ One short page per client, with a config snippet, a chat, a tool call, a structu
 | n8n | [n8n](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/n8n.md) | pass with "Use Responses API" off |
 | Anything else | [any-app](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/clients/any-app.md) | base URL, key, model id |
 
-Each run drove the client's own SDK or API against a dev server at an earlier commit: a plain chat, a tool round trip, streaming, an image and structured output on `fast`, a Claude model and a ChatGPT model. A pass here is not a clean sweep, and the notes in the table and on each page say where it was not. The release-candidate record has not been written yet.
+Each run drove the client's own SDK or API against a dev server at an earlier commit: a plain chat, a tool round trip, streaming, an image and structured output on `fast`, a Claude model and a ChatGPT model. A pass here is not a clean sweep, and the notes in the table and on each page say where it was not. The latest full acceptance run is in [compat/results/release-candidate.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/compat/results/release-candidate.md).
 
 ## Known gaps
 
-- **No `/v1/responses` yet.** Clients that default to the Responses API fail with `404 No route for POST /v1/responses`. That includes the Vercel AI SDK's `@ai-sdk/openai` default call (use `createOpenAICompatible` or `.chat(id)`), LangChain JS for `gpt-5.6*` ids, and n8n's "Use Responses API" option (turn it off).
+- **`/v1/responses` is stateless.** `previous_response_id`, `conversation`, `item_reference`, `background` and hosted tools return 400. See [docs/responses.md](https://github.com/jjjermiah/opencode-plugboard/blob/main/docs/responses.md).
 - Only `n=1`, no `logprobs`, no embeddings, audio or image generation.
-- No history pruning, no per-app concurrency limit.
+- No per-app concurrency limit yet ([#54](https://github.com/jjjermiah/opencode-plugboard/issues/54), [#86](https://github.com/jjjermiah/opencode-plugboard/issues/86)).
 
 ## Options
 
@@ -104,6 +104,7 @@ Options live under `options` in the plugin entry. `{env:VAR}` is expanded by Ope
 | `aliases` | none | Map of alias to `provider/model[#variant]`. Each target must also pass `models`. |
 | `maxTools` | `32` | Most tools one request may carry. Fixed when the plugin loads. |
 | `requestTimeoutMs` | `600000` | A request that runs longer is interrupted. |
+| `history` | none (keep forever) | `{ maxSessions, maxAgeDays }`. `maxSessions` keeps the newest N sessions per app, `maxAgeDays` deletes older ones; with both, the stricter wins. |
 | `remoteImages` | `false` | Let the server fetch `http(s)` image URLs from requests (20 MB cap, no redirects, `image/*` only). Off by default because it lets callers make the host request internal addresses; callers can always send `data:` URLs. |
 
 Changes to `listen` need a server restart; other option changes apply on config reload.
@@ -142,7 +143,7 @@ $XDG_DATA_HOME/opencode-plugboard/<app>/        # default ~/.local/share/opencod
 
 That directory only groups sessions: it is the `directory` a session is filed under. The prompts and replies are not stored in it. OpenCode keeps them in its own database, `opencode.db` in its data directory (`opencode debug paths` prints the exact location, and `OPENCODE_DB` can override it). So deleting, locking down or backing up the app directory removes, protects or saves no history. To back up, restrict or purge history, work on that database, or remove sessions through OpenCode ([`compat/tools/sessions.py`](https://github.com/jjjermiah/opencode-plugboard/blob/main/compat/tools/sessions.py) does that for one app).
 
-In OpenCode the sessions appear as one group per app in the desktop and phone app home screen. In the TUI they are visible in the all-projects view (ctrl+a), not in a project's own list. Nothing deletes them yet ([pruning is a roadmap item](https://github.com/jjjermiah/opencode-plugboard/issues/8)).
+In OpenCode the sessions appear as one group per app in the desktop and phone app home screen. In the TUI they are visible in the all-projects view (ctrl+a), not in a project's own list. Set `history` to delete old ones: sweeps run on requests, at most every 10 minutes, in bounded batches, and never touch a running session. Only sessions created while a limit is set are pruned; remove older ones with `compat/tools/sessions.py`.
 
 OpenCode loads plugin hooks per directory, so plugboard has to be loaded in those app directories, which is why it needs the global config. Everywhere outside the data root it is inert: it only joins the shared listener and registers no hooks, tools or agent rules, so your real projects behave as before.
 
@@ -220,7 +221,7 @@ The model call sits behind one interface, `ModelCaller`, so a native backend can
 
 ## Roadmap
 
-Work is tracked in GitHub issues. The [v0.1 milestone](https://github.com/jjjermiah/opencode-plugboard/milestone/1) lists what is needed before the first release, and the [later milestone](https://github.com/jjjermiah/opencode-plugboard/milestone/2) holds the rest: the `/v1/responses`, `/v1/messages` and Gemini front-ends, agent mode, a native backend, history pruning and an upstream request to boot plugins at server start.
+Work is tracked in GitHub issues. The [v0.1 milestone](https://github.com/jjjermiah/opencode-plugboard/milestone/1) lists what is needed before the first release, and the [later milestone](https://github.com/jjjermiah/opencode-plugboard/milestone/2) holds the rest: the `/v1/messages` and Gemini front-ends, agent mode, a native backend, usage accounting, rate limits and an upstream request to boot plugins at server start.
 
 Not planned: V1 support, embeddings, audio, image generation.
 

package/index.ts

@@ -26,7 +26,7 @@ import { createOpenAiRoute } from "./src/openai/route.js"
 import { ensureBackend, ensurePump, loadServingCatalog, registerGeneration, sessionStore } from "./src/runtime.js"
 import { createSessionCaller } from "./src/session/caller.js"
 import { installSessionHooks } from "./src/session/context.js"
-import { createSessionPort, loadCatalog } from "./src/session/host.js"
+import { createHistoryPort, createSessionPort, loadCatalog } from "./src/session/host.js"
 
 export default Plugin.define({
   id: "opencode-plugboard",
@@ -74,6 +74,8 @@ export default Plugin.define({
         directory: ctx.location.directory,
         // Rebuild the transforms below once a request has confirmed this Location as an app directory.
         refresh: () => Effect.runPromise(Effect.all([ctx.agent.reload(), ctx.tool.reload()], { discard: true })),
+        // Host handles for indexing and pruning request sessions; only called from request handling.
+        history: { port: createHistoryPort(ctx), limits: options.history },
         handler: (request, response) => {
           startPump()
           handle(request, response).catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-plugboard",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "license": "MIT",
   "description": "OpenCode V2 plugin that serves an OpenAI-compatible /v1/chat/completions and /v1/models from your OpenCode server, backed by the providers you already connected there.",
@@ -19,7 +19,8 @@
   },
   "files": ["index.ts", "src/", "README.md", "LICENSE"],
   "scripts": {
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "release": "bun scripts/release.ts"
   },
   "devDependencies": {
     "@opencode/plugin": "2.0.26",

package/src/config.ts

@@ -1,6 +1,7 @@
 /** Plugin options: type, defaults, validation, caller authentication and the loopback check. */
 
 import type { PlugError } from "./contract.js"
+import type { HistoryLimits } from "./session/prune.js"
 
 /** Plugin options, after defaults and validation (see `parseOptions`). */
 export interface PlugboardOptions {
@@ -15,6 +16,8 @@ export interface PlugboardOptions {
   readonly requestTimeoutMs: number
   /** Fetch http(s) image URLs server-side. Off by default: it is an SSRF vector into the host's network. */
   readonly remoteImages: boolean
+  /** Prune old request sessions (see `src/session/prune.ts`). A limit that is unset is not applied; with neither, history is kept forever. Applies per app. */
+  readonly history: HistoryLimits
 }
 
 export const APP_NAME_PATTERN = /^[a-z0-9-]+$/
@@ -26,7 +29,10 @@ const DEFAULTS = {
   requestTimeoutMs: 600_000,
 } as const
 
-const KNOWN = new Set(["listen", "keys", "models", "aliases", "maxTools", "requestTimeoutMs", "remoteImages"])
+const KNOWN = new Set(["listen", "keys", "models", "aliases", "maxTools", "requestTimeoutMs", "remoteImages", "history"])
+const HISTORY_KNOWN = new Set(["maxSessions", "maxAgeDays"])
+/** About 100 years: keeps `maxAgeDays * 86_400_000` a safe integer. */
+const MAX_AGE_DAYS = 36_500
 const MODEL_PATTERN = /^[^/#*\s]+\/(\*|[^#*\s]+(#[^#*\s]+)?)$/
 const ALIAS_TARGET = /^[^/#*\s]+\/[^#*\s]+(#[^#*\s]+)?$/
 /** `provider/model...` shaped: an alias like this would collide with real model ids in listing and resolution. */
@@ -113,6 +119,13 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   if (input.remoteImages !== undefined && typeof input.remoteImages !== "boolean")
     throw new Error("plugboard option `remoteImages` must be a boolean")
 
+  const historyInput = input.history
+  if (historyInput !== undefined && !isRecord(historyInput)) throw new Error("plugboard option `history` must be an object")
+  for (const key of Object.keys(historyInput ?? {}))
+    if (!HISTORY_KNOWN.has(key)) throw new Error(`Unknown plugboard option \`history.${key}\` (known: ${[...HISTORY_KNOWN].join(", ")})`)
+  const maxSessions = historyInput?.maxSessions === undefined ? undefined : positiveInt(historyInput.maxSessions, "history.maxSessions", 0)
+  const maxAgeDays = historyInput?.maxAgeDays === undefined ? undefined : positiveInt(historyInput.maxAgeDays, "history.maxAgeDays", 0, MAX_AGE_DAYS)
+
   return {
     listen: { host, port: port ?? DEFAULTS.port },
     keys,
@@ -121,6 +134,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     maxTools: positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024),
     requestTimeoutMs: positiveInt(input.requestTimeoutMs, "requestTimeoutMs", DEFAULTS.requestTimeoutMs, MAX_TIMER_MS),
     remoteImages: input.remoteImages === true,
+    history: { ...(maxSessions === undefined ? {} : { maxSessions }), ...(maxAgeDays === undefined ? {} : { maxAgeDays }) },
   }
 }
 

package/src/openai/route.ts

@@ -1,6 +1,6 @@
 /**
  * OpenAI front-end route table: `GET /healthz`, `GET /v1/models`, `GET /v1/models/{id}`,
- * `POST /v1/chat/completions`.
+ * `POST /v1/chat/completions`, and the dispatch of `POST /v1/responses` to `src/responses/route.ts`.
  *
  * The flow is: establish cancellation and the deadline, check origin, authenticate, parse, resolve
  * the model, call the ModelCaller, encode. Parsing, policy and encoding are imported directly;
@@ -30,6 +30,7 @@ import {
 } from "../http.js"
 import { errorMessage, log, logError } from "../log.js"
 import { listAvailableModels, resolveModel } from "../models.js"
+import { serveResponses } from "../responses/route.js"
 import { parseChatRequest } from "./request.js"
 import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
 
@@ -43,7 +44,7 @@ export interface RouteHost {
 
 const SESSION_HEADER = "x-plugboard-session"
 const MODEL_PREFIX = "/v1/models/"
-const KNOWN_ROUTES = ["GET /v1/models", "POST /v1/chat/completions"]
+const KNOWN_ROUTES = ["GET /v1/models", "POST /v1/chat/completions", "POST /v1/responses"]
 
 const decodeSegment = (raw: string): string => {
   try {
@@ -119,6 +120,7 @@ export function createOpenAiRoute(host: RouteHost) {
     if (unsupported) return fail(response, unsupported)
 
     const body = await readJsonBody(request, scope.signal)
+    if (route === "POST /v1/responses") return serveResponses(host, { app: auth.app, body, response, scope, info })
     const parsed = parseChatRequest(body, host.options)
     if (isPlugError(parsed)) return fail(response, parsed)
     const catalog = await scope.race(host.loadCatalog())

package/src/responses/request.ts

@@ -0,0 +1,377 @@
+/**
+ * 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
+ * `ModelRef` afterwards, which is why the request omits `ref`.
+ */
+import type { PlugboardOptions } from "../config.js"
+import {
+  isPlugError,
+  type PlugError,
+  type PlugGeneration,
+  type PlugMessage,
+  type PlugPart,
+  type PlugRequest,
+  type PlugTool,
+  type PlugToolChoice,
+} from "../contract.js"
+import type { ResponsesExchange } from "./response.js"
+
+type JsonObject = Record<string, unknown>
+
+export interface ParsedResponses {
+  /** The model call, minus the model ref the route resolves from `request.model`. */
+  readonly request: Omit<PlugRequest, "ref">
+  /** Response presentation state for the encoder; never reaches the model call. */
+  readonly exchange: ResponsesExchange
+  readonly reasoningEffort?: string
+}
+
+/** Name of the forced tool that carries structured output (same as the Chat Completions front-end). */
+const RESPOND_TOOL = "respond"
+
+/** System instruction for `json_object`: no schema, so the caller's prompt describes the keys. */
+const JSON_OBJECT_INSTRUCTION = "Respond with a single valid JSON object only."
+
+const isRecord = (value: unknown): value is JsonObject => typeof value === "object" && value !== null && !Array.isArray(value)
+
+const bad = (message: string, param?: string, code?: string): PlugError => ({
+  status: 400,
+  kind: "invalid_request",
+  message,
+  ...(code ? { code } : {}),
+  ...(param ? { param } : {}),
+})
+
+const unsupported = (message: string, param: string) => bad(message, param, "unsupported_parameter")
+
+const dataUrlType = (url: string) => /^data:([^;,]+)[;,]/.exec(url)?.[1]
+
+const parseJson = (value: string): unknown => {
+  try {
+    return JSON.parse(value)
+  } catch {
+    return value
+  }
+}
+
+/** Text of a string or a list of `input_text` / `output_text` parts (system, developer, tool output). */
+const textOf = (content: unknown): string | undefined => {
+  if (typeof content === "string") return content
+  if (!Array.isArray(content)) return undefined
+  const texts: string[] = []
+  for (const item of content) {
+    if (!isRecord(item) || typeof item.text !== "string") return undefined
+    texts.push(item.text)
+  }
+  return texts.join("\n")
+}
+
+/** Content of a user message: string, or parts of `input_text` / `input_image` / `input_file`. */
+const userParts = (content: unknown, param: string): PlugPart[] | PlugError => {
+  if (typeof content === "string") return [{ type: "text", text: content }]
+  if (!Array.isArray(content)) return bad("Message content must be a string or an array of content parts", param)
+  const parts: PlugPart[] = []
+  for (const [index, item] of content.entries()) {
+    const at = `${param}[${index}]`
+    if (!isRecord(item)) return bad("Content part must be an object", at)
+    if ((item.type === "input_text" || item.type === "output_text") && typeof item.text === "string") {
+      parts.push({ type: "text", text: item.text })
+    } else if (item.type === "input_image" || item.type === "image_url") {
+      // `image_url` is the Chat Completions part type; @langchain/openai sends it in Responses input for standard image blocks.
+      const url = typeof item.image_url === "string" ? item.image_url : isRecord(item.image_url) ? item.image_url.url : undefined
+      if (typeof url !== "string")
+        return unsupported(item.file_id != null ? "input_image.file_id is not supported (stateless); send image_url" : "input_image needs an image_url", `${at}.image_url`)
+      parts.push({ type: "media", url, ...(dataUrlType(url) ? { mediaType: dataUrlType(url) } : {}) })
+    } else if (item.type === "input_file") {
+      if (typeof item.file_data === "string") {
+        const data = item.file_data
+        const filename = typeof item.filename === "string" ? item.filename.toLowerCase() : ""
+        const url = data.startsWith("data:") ? data : `data:${filename.endsWith(".pdf") ? "application/pdf" : "application/octet-stream"};base64,${data}`
+        parts.push({ type: "media", url, mediaType: dataUrlType(url) })
+      } else if (typeof item.file_url === "string") {
+        parts.push({ type: "media", url: item.file_url })
+      } else return unsupported("input_file needs file_data or file_url; file_id is not supported (stateless)", `${at}.file_data`)
+    } else return unsupported(`Unsupported content part type "${String(item.type)}"`, `${at}.type`)
+  }
+  return parts
+}
+
+/** Assistant content: string, or `output_text` parts (refusals are dropped, like the Chat Completions front-end). */
+const assistantText = (content: unknown, param: string): string | PlugError => {
+  if (typeof content === "string") return content
+  if (!Array.isArray(content)) return bad("Assistant content must be a string or an array of output_text parts", param)
+  const texts: string[] = []
+  for (const [index, item] of content.entries()) {
+    if (!isRecord(item)) return bad("Content part must be an object", `${param}[${index}]`)
+    if (item.type === "refusal") continue
+    if ((item.type !== "output_text" && item.type !== "input_text") || typeof item.text !== "string")
+      return unsupported(`Unsupported assistant content part type "${String(item.type)}"`, `${param}[${index}].type`)
+    texts.push(item.text)
+  }
+  return texts.join("")
+}
+
+/**
+ * `input` items -> neutral messages. Adjacent assistant items (text, function calls) become one
+ * 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 => {
+  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")
+
+  const system: string[] = []
+  const messages: PlugMessage[] = []
+  const toolNames = new Map<string, string>()
+  let pending: PlugPart[] | undefined
+  const flush = () => {
+    if (pending && pending.length > 0) messages.push({ role: "assistant", content: pending })
+    pending = undefined
+  }
+
+  for (const [index, item] of input.entries()) {
+    const param = `input[${index}]`
+    if (!isRecord(item)) return bad("Each input item must be an object", param)
+    const type = item.type ?? (item.role !== undefined ? "message" : undefined)
+    switch (type) {
+      case "message": {
+        switch (item.role) {
+          case "system":
+          case "developer": {
+            const value = textOf(item.content)
+            if (value === undefined) return bad("System message content must be a string or text parts", `${param}.content`)
+            if (value.length > 0) system.push(value)
+            break
+          }
+          case "user": {
+            flush()
+            const parts = userParts(item.content, `${param}.content`)
+            if (!Array.isArray(parts)) return parts
+            messages.push({ role: "user", content: parts })
+            break
+          }
+          case "assistant": {
+            const text = assistantText(item.content, `${param}.content`)
+            if (typeof text !== "string") return text
+            if (text.length > 0) (pending ??= []).push({ type: "text", text })
+            break
+          }
+          default:
+            return bad(`Unsupported message role "${String(item.role)}"`, `${param}.role`)
+        }
+        break
+      }
+      case "function_call": {
+        if (typeof item.call_id !== "string" || item.call_id.length === 0) return bad("function_call needs a non-empty call_id", `${param}.call_id`)
+        if (typeof item.name !== "string" || item.name.length === 0) return bad("function_call needs a name", `${param}.name`)
+        toolNames.set(item.call_id, item.name)
+        ;(pending ??= []).push({
+          type: "tool-call",
+          id: item.call_id,
+          name: item.name,
+          input: typeof item.arguments === "string" ? parseJson(item.arguments) : (item.arguments ?? {}),
+        })
+        break
+      }
+      case "function_call_output": {
+        flush()
+        if (typeof item.call_id !== "string") return bad("function_call_output needs a call_id", `${param}.call_id`)
+        const result = textOf(item.output)
+        if (result === undefined) return bad("function_call_output output must be a string or an array of text parts", `${param}.output`)
+        const name = toolNames.get(item.call_id)
+        if (name === undefined)
+          return bad(`function_call_output answers call_id "${item.call_id}", which no earlier function_call item has`, `${param}.call_id`)
+        messages.push({ role: "tool", content: [{ type: "tool-result", id: item.call_id, name, result }] })
+        break
+      }
+      // 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`)
+    }
+  }
+  flush()
+  if (messages.length === 0) return bad("input has no user, assistant or tool items", "input")
+  return { system, messages }
+}
+
+const parseTools = (raw: unknown): PlugTool[] | PlugError => {
+  if (raw == null) return []
+  if (!Array.isArray(raw)) return bad("tools must be an array", "tools")
+  const tools: PlugTool[] = []
+  const names = new Set<string>()
+  for (const [index, entry] of raw.entries()) {
+    const at = `tools[${index}]`
+    if (!isRecord(entry)) return bad("Each tool must be an object", at)
+    if (entry.type !== "function")
+      return unsupported(`Unsupported tool type "${String(entry.type)}": only function tools are supported (built-in tools such as web_search and file_search run on OpenAI's servers)`, `${at}.type`)
+    if (typeof entry.name !== "string" || entry.name.length === 0) return bad('Each function tool needs a "name"', `${at}.name`)
+    if (names.has(entry.name)) return bad(`Duplicate tool name "${entry.name}"`, `${at}.name`)
+    if (entry.description != null && typeof entry.description !== "string") return bad("Tool description must be a string", `${at}.description`)
+    // `parameters` may be null (strict mode with no arguments): a tool without arguments.
+    if (entry.parameters != null && !isRecord(entry.parameters)) return bad("Tool parameters must be a JSON Schema object", `${at}.parameters`)
+    names.add(entry.name)
+    tools.push({
+      name: entry.name,
+      description: typeof entry.description === "string" ? entry.description : "",
+      parameters: isRecord(entry.parameters) ? entry.parameters : { type: "object", properties: {} },
+    })
+  }
+  return tools
+}
+
+const parseToolChoice = (raw: unknown): PlugToolChoice | undefined | PlugError => {
+  if (raw == null) return undefined
+  if (raw === "auto" || raw === "none" || raw === "required") return raw
+  if (isRecord(raw) && raw.type === "function" && typeof raw.name === "string") return { type: "tool", name: raw.name }
+  return unsupported("Unsupported tool_choice: use auto, none, required or {type:\"function\", name}", "tool_choice")
+}
+
+/**
+ * `text.format`: `json_schema` -> the `respond` tool (`structured`, forced unless the caller also
+ * sends tools); `json_object` -> a system instruction (`instruction`).
+ */
+const parseTextFormat = (raw: unknown): { structured?: PlugTool; instruction?: string } | PlugError => {
+  if (raw == null) return {}
+  if (!isRecord(raw)) return bad("text must be an object", "text")
+  const format = raw.format
+  if (format == null || (isRecord(format) && format.type === "text")) return {}
+  if (!isRecord(format)) return bad("text.format must be an object", "text.format")
+  if (format.type === "json_object") return { instruction: JSON_OBJECT_INSTRUCTION }
+  if (format.type === "json_schema") {
+    if (format.name != null && typeof format.name !== "string") return bad("text.format.name must be a string", "text.format.name")
+    if (format.description != null && typeof format.description !== "string") return bad("text.format.description must be a string", "text.format.description")
+    if (!isRecord(format.schema)) return bad("text.format.schema must be a JSON Schema object", "text.format.schema")
+    return {
+      structured: {
+        name: RESPOND_TOOL,
+        // With caller tools also on offer, this description is what tells the model which call is the final answer.
+        description:
+          "Give your final answer by calling this tool with JSON matching its schema." +
+          (typeof format.description === "string" ? ` ${format.description}` : ""),
+        parameters: format.schema,
+      },
+    }
+  }
+  return bad(`Unsupported text.format type "${String(format.type)}"`, "text.format.type")
+}
+
+const parseGeneration = (body: JsonObject): PlugGeneration | PlugError => {
+  const out: { -readonly [K in keyof PlugGeneration]: PlugGeneration[K] } = {}
+  for (const [key, field, min, max, integer] of [
+    ["temperature", "temperature", 0, 2, false],
+    ["top_p", "topP", 0, 1, false],
+    ["max_output_tokens", "maxTokens", 1, Number.MAX_SAFE_INTEGER, true],
+  ] as const) {
+    const value = body[key]
+    if (value == null) continue
+    if (typeof value !== "number" || !Number.isFinite(value)) return bad(`${key} must be a number`, key)
+    if (integer && !Number.isInteger(value)) return bad(`${key} must be an integer`, key)
+    if (value < min || value > max)
+      return bad(max === Number.MAX_SAFE_INTEGER ? `${key} must be at least ${min}` : `${key} must be between ${min} and ${max}`, key)
+    out[field] = value
+  }
+  return out
+}
+
+/** Fields that need server-side state or features plugboard does not have. */
+const checkUnsupported = (body: JsonObject): PlugError | undefined => {
+  if (body.previous_response_id != null)
+    return unsupported("previous_response_id is not supported: plugboard is stateless, send the full conversation in input", "previous_response_id")
+  if (body.conversation != null) return unsupported("conversation is not supported: plugboard is stateless", "conversation")
+  if (body.background === true) return unsupported("background mode is not supported", "background")
+  if (body.prompt != null) return unsupported("Stored prompts (prompt) are not supported", "prompt")
+  if (body.top_logprobs != null && body.top_logprobs !== 0) return unsupported("top_logprobs is not supported", "top_logprobs")
+  if (body.truncation != null && body.truncation !== "disabled") return unsupported('Only truncation "disabled" is supported', "truncation")
+}
+
+export function parseResponsesRequest(body: unknown, options: PlugboardOptions): 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")
+  const refused = checkUnsupported(body)
+  if (refused) return refused
+  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)
+  if (isPlugError(parsed)) return parsed
+  const callerTools = parseTools(body.tools)
+  if (!Array.isArray(callerTools)) return callerTools
+  const toolChoice = parseToolChoice(body.tool_choice)
+  if (isPlugError(toolChoice)) return toolChoice
+  const format = parseTextFormat(body.text)
+  if (isPlugError(format)) return format
+  const respond = format.structured
+  const generation = parseGeneration(body)
+  if (isPlugError(generation)) return generation
+
+  if (typeof toolChoice === "object" && !callerTools.some((tool) => tool.name === toolChoice.name))
+    return bad(`tool_choice names "${toolChoice.name}", which is not in tools`, "tool_choice.name")
+  if (respond && callerTools.some((tool) => tool.name === RESPOND_TOOL))
+    return bad(
+      `A tool named "${RESPOND_TOOL}" collides with text.format json_schema, which plugboard answers through that name`,
+      "tools",
+      "reserved_tool_name",
+    )
+  // json_schema + caller tools: the model may call a caller tool or `respond`, so `tool_choice` is
+  // `required` (not forced to `respond`). `tool_choice: none` leaves only `respond`; naming a tool
+  // contradicts a structured answer.
+  if (respond && typeof toolChoice === "object")
+    return unsupported("A tool_choice that names a tool cannot be combined with text.format json_schema", "tool_choice")
+  const withCallerTools = respond !== undefined && callerTools.length > 0 && toolChoice !== "none"
+  const tools = respond ? (withCallerTools ? [...callerTools, respond] : [respond]) : callerTools
+  if (tools.length > options.maxTools)
+    return bad(`Request has ${tools.length} tools; plugboard allows ${options.maxTools} (option \`maxTools\`)`, "tools", "too_many_tools")
+
+  const forced: PlugToolChoice | undefined = respond ? (withCallerTools ? "required" : { type: "tool", name: RESPOND_TOOL }) : toolChoice
+  const instructions = typeof body.instructions === "string" && body.instructions.length > 0 ? [body.instructions] : []
+  const system = [...instructions, ...parsed.system, ...(format.instruction ? [format.instruction] : [])]
+  const request: Omit<PlugRequest, "ref"> = {
+    model: body.model,
+    system,
+    messages: parsed.messages,
+    tools,
+    ...(forced && tools.length > 0 ? { toolChoice: forced } : {}),
+    generation,
+  }
+  const reasoningEffort = isRecord(body.reasoning) && typeof body.reasoning.effort === "string" ? body.reasoning.effort : undefined
+  const text = isRecord(body.text) ? body.text : undefined
+  return {
+    request,
+    exchange: {
+      model: body.model,
+      stream: body.stream === true,
+      // Echoed in the response object, as OpenAI does. `store` is always false: nothing is kept for retrieval.
+      envelope: {
+        instructions: typeof body.instructions === "string" ? body.instructions : null,
+        max_output_tokens: generation.maxTokens ?? null,
+        metadata: isRecord(body.metadata) ? body.metadata : {},
+        parallel_tool_calls: body.parallel_tool_calls !== false,
+        previous_response_id: null,
+        reasoning: { effort: reasoningEffort ?? null, summary: null },
+        store: false,
+        temperature: generation.temperature ?? null,
+        text: { format: isRecord(text?.format) ? text.format : { type: "text" } },
+        tool_choice: body.tool_choice ?? "auto",
+        tools: Array.isArray(body.tools) ? body.tools : [],
+        top_p: generation.topP ?? null,
+        truncation: "disabled",
+        user: typeof body.user === "string" ? body.user : null,
+      },
+      ...(respond ? { structuredTool: RESPOND_TOOL, ...(withCallerTools ? { callerTools: true } : {}) } : {}),
+    },
+    ...(reasoningEffort ? { reasoningEffort } : {}),
+  }
+}

package/src/responses/response.ts

@@ -0,0 +1,225 @@
+/**
+ * Neutral results -> OpenAI Responses wire objects: one response object, or the named SSE
+ * events of a stream.
+ *
+ * One state machine (`runResponse`) serves both: it emits stream events as it goes and returns
+ * the final response object, so the JSON body and the stream never disagree. A non-streaming
+ * call passes a no-op `emit`. Reasoning deltas are dropped (no reasoning items are produced).
+ */
+import type { PlugError, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
+
+type ToolCall = Extract<PlugEvent, { type: "tool-call" }>
+
+/** What the encoder needs besides the model events: Responses presentation state. The request decoder produces it. */
+export interface ResponsesExchange {
+  /** The model string the client sent; echoed in every response object. */
+  readonly model: string
+  readonly stream: boolean
+  /** Request fields echoed into the response object (instructions, tools, temperature, ...). */
+  readonly envelope: Readonly<Record<string, unknown>>
+  /** Name of the forced tool that carries `text.format` json_schema output; its input becomes the message text. */
+  readonly structuredTool?: string
+  /**
+   * The caller's own tools are offered next to the structured tool. A call to any of them is the
+   * response (function_call items, prose and the structured answer dropped); the structured
+   * answer is the message text only when the step called no caller tool.
+   */
+  readonly callerTools?: boolean
+}
+
+/** A stream event as emitted: `type` is also the SSE event name. */
+export type ResponsesStreamEvent = { readonly type: string; readonly sequence_number: number } & Record<string, unknown>
+
+/** How an exchange ended. Nothing was emitted when `failure` is set and `started` is false: the caller answers with a real HTTP error. */
+export interface ResponseRun {
+  readonly failure?: PlugError
+  /** Whether `response.created` was emitted (a streamed response is committed as a 200 SSE stream). */
+  readonly started: boolean
+  /** The final response object (completed, incomplete or failed once started). */
+  readonly response?: object
+}
+
+type Item = Record<string, unknown>
+
+const args = (input: unknown) => (typeof input === "string" ? input : JSON.stringify(input ?? {}))
+
+const newId = (prefix: string) => `${prefix}_${crypto.randomUUID().replaceAll("-", "")}`
+
+const encodeUsage = (usage: PlugUsage) => {
+  const input = usage.inputTokens ?? 0
+  const output = usage.outputTokens ?? 0
+  return {
+    input_tokens: input,
+    input_tokens_details: { cached_tokens: usage.cacheReadTokens ?? 0 },
+    output_tokens: output,
+    output_tokens_details: { reasoning_tokens: usage.reasoningTokens ?? 0 },
+    total_tokens: input + output,
+  }
+}
+
+const noFinish = (): PlugError => ({ status: 500, kind: "server", message: "Model stream ended without a finish event" })
+const failedRun = (): PlugError => ({ status: 500, kind: "server", message: "Model run failed" })
+
+/** SSE frame of one stream event: `event: <type>` then `data: <json>`. */
+export const sseFrame = (event: ResponsesStreamEvent): string => `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`
+
+/**
+ * Structured-output projection, same rules as the Chat Completions front-end: in structured mode
+ * the message text is exactly the arguments of the first call to the `respond` tool; prose and
+ * other calls are suppressed. Without an answer the exchange fails, except when the model
+ * stopped for `length` or `content-filter`, which keep their status with empty output.
+ */
+const structuredFailure = (exchange: ResponsesExchange, finish: Exclude<PlugFinish, "error">, answered: boolean): PlugError | undefined =>
+  exchange.structuredTool === undefined || answered || finish === "length" || finish === "content-filter"
+    ? undefined
+    : {
+        status: 502,
+        kind: "server",
+        code: "structured_output_missing",
+        message: `The model finished without calling the \`${exchange.structuredTool}\` tool, so there is no structured output`,
+      }
+
+export async function runResponse(
+  events: AsyncIterable<PlugEvent>,
+  exchange: ResponsesExchange,
+  emit: (event: ResponsesStreamEvent) => void,
+): Promise<ResponseRun> {
+  const id = newId("resp")
+  const createdAt = Math.floor(Date.now() / 1000)
+  let sequence = 0
+  const send = (type: string, data: Record<string, unknown>) => emit({ type, sequence_number: sequence++, ...data })
+  const envelope = (status: string, output: Item[], extra: Record<string, unknown> = {}) => ({
+    id,
+    object: "response",
+    created_at: createdAt,
+    status,
+    error: null,
+    incomplete_details: null,
+    model: exchange.model,
+    output,
+    ...exchange.envelope,
+    ...extra,
+  })
+
+  const items: Item[] = []
+  /** Output items that are open or done: the next item's `output_index`. */
+  let nextIndex = 0
+  let open: { id: string; index: number; text: string } | undefined
+  let started = false
+  let calls = 0
+  let answered = false
+  /** With caller tools offered the structured answer waits for the finish: a caller tool call in the same step replaces it. */
+  let held: ToolCall | undefined
+  let finish: Exclude<PlugFinish, "error"> | undefined
+  let usage: PlugUsage | undefined
+  let failure: PlugError | undefined
+
+  const start = () => {
+    if (started) return
+    started = true
+    send("response.created", { response: envelope("in_progress", []) })
+    send("response.in_progress", { response: envelope("in_progress", []) })
+  }
+  const messageItem = (itemId: string, status: string, text: string | undefined): Item => ({
+    id: itemId,
+    type: "message",
+    status,
+    role: "assistant",
+    content: text === undefined ? [] : [{ type: "output_text", text, annotations: [], logprobs: [] }],
+  })
+  const text = (delta: string) => {
+    if (delta.length === 0) return
+    start()
+    if (!open) {
+      open = { id: newId("msg"), index: nextIndex++, text: "" }
+      send("response.output_item.added", { output_index: open.index, item: messageItem(open.id, "in_progress", undefined) })
+      send("response.content_part.added", {
+        item_id: open.id,
+        output_index: open.index,
+        content_index: 0,
+        part: { type: "output_text", text: "", annotations: [], logprobs: [] },
+      })
+    }
+    open.text += delta
+    send("response.output_text.delta", { item_id: open.id, output_index: open.index, content_index: 0, delta, logprobs: [] })
+  }
+  const closeMessage = () => {
+    if (!open) return
+    const part = { type: "output_text", text: open.text, annotations: [], logprobs: [] }
+    send("response.output_text.done", { item_id: open.id, output_index: open.index, content_index: 0, text: open.text, logprobs: [] })
+    send("response.content_part.done", { item_id: open.id, output_index: open.index, content_index: 0, part })
+    const item = messageItem(open.id, "completed", open.text)
+    send("response.output_item.done", { output_index: open.index, item })
+    items.push(item)
+    open = undefined
+  }
+  /** Tool calls arrive whole, so each goes out as one arguments delta. */
+  const toolCall = (call: ToolCall) => {
+    start()
+    closeMessage()
+    const index = nextIndex++
+    const itemId = newId("fc")
+    const argumentsText = args(call.input)
+    const item = (status: string, text: string): Item => ({ id: itemId, type: "function_call", status, call_id: call.id, name: call.name, arguments: text })
+    send("response.output_item.added", { output_index: index, item: item("in_progress", "") })
+    send("response.function_call_arguments.delta", { item_id: itemId, output_index: index, delta: argumentsText })
+    send("response.function_call_arguments.done", { item_id: itemId, output_index: index, name: call.name, arguments: argumentsText })
+    const done = item("completed", argumentsText)
+    send("response.output_item.done", { output_index: index, item: done })
+    items.push(done)
+    calls++
+  }
+
+  for await (const event of events) {
+    if (event.type === "error") {
+      failure = event.error
+      break
+    }
+    if (event.type === "finish") {
+      usage = event.usage ?? usage
+      if (event.reason === "error") failure ??= failedRun()
+      else finish = event.reason
+      continue
+    }
+    if (event.type === "reasoning-delta") continue
+    if (exchange.structuredTool !== undefined) {
+      // Structured mode: only the first answer is content; prose and other tool calls are
+      // suppressed, except the caller's own tools when they are offered.
+      if (event.type === "tool-call" && event.name === exchange.structuredTool) {
+        if (!answered) {
+          answered = true
+          if (exchange.callerTools) held = event
+          else text(args(event.input))
+        }
+        continue
+      }
+      if (!(exchange.callerTools && event.type === "tool-call")) continue
+    }
+    if (event.type === "text-delta") text(event.text)
+    else toolCall(event)
+  }
+
+  const passthrough = exchange.callerTools === true && calls > 0
+  const structuredAnswer = exchange.structuredTool !== undefined && !passthrough
+  failure ??= finish ? (passthrough ? undefined : structuredFailure(exchange, finish, answered)) : noFinish()
+  if (failure) {
+    if (!started) return { failure, started }
+    closeMessage()
+    const response = envelope("failed", items, {
+      error: { code: failure.code ?? failure.kind, message: failure.message },
+      ...(usage ? { usage: encodeUsage(usage) } : {}),
+    })
+    send("response.failed", { response })
+    return { failure, started, response }
+  }
+  start()
+  if (held && structuredAnswer) text(args(held.input))
+  closeMessage()
+  const incomplete = finish === "length" ? "max_output_tokens" : finish === "content-filter" ? "content_filter" : undefined
+  const response = envelope(incomplete ? "incomplete" : "completed", items, {
+    ...(incomplete ? { incomplete_details: { reason: incomplete } } : {}),
+    ...(usage ? { usage: encodeUsage(usage) } : {}),
+  })
+  send(incomplete ? "response.incomplete" : "response.completed", { response })
+  return { started, response }
+}

package/src/responses/route.ts

@@ -0,0 +1,72 @@
+/**
+ * `POST /v1/responses`: the Responses front-end's half of the route. `src/openai/route.ts` has
+ * already checked origin, authenticated, and read the JSON body (the same handling and
+ * deadline as Chat Completions) and hands over here.
+ *
+ * Same flow as Chat Completions: parse, resolve the model, call the ModelCaller, encode. Nothing
+ * is committed until the encoder emits its first event, so a failure before any output is a
+ * real HTTP error even when the client asked for a stream.
+ */
+
+import type { ServerResponse } from "node:http"
+import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
+import { boundEvents, sendJson, sseWriter, type RequestScope } from "../http.js"
+import { resolveModel } from "../models.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"
+
+const SESSION_HEADER = "x-plugboard-session"
+
+export interface ResponsesCall {
+  readonly app: string
+  readonly body: unknown
+  readonly response: ServerResponse
+  readonly scope: RequestScope
+  /** The route's log fields: the resolved model, and the outcome of a stream that failed after it committed. */
+  readonly info: { model?: string; failed?: string }
+}
+
+export async function serveResponses(host: RouteHost, { app, body, response, scope, info }: ResponsesCall): Promise<void> {
+  const fail = (error: PlugError) => sendJson(response, error.status, encodeError(error))
+
+  const parsed = parseResponsesRequest(body, host.options)
+  if (isPlugError(parsed)) return fail(parsed)
+  const catalog = await scope.race(host.loadCatalog())
+  const ref = resolveModel(host.options, parsed.request.model, catalog, parsed.reasoningEffort)
+  if (isPlugError(ref)) return fail(ref)
+  info.model = `${ref.providerID}/${ref.id}${ref.variant ? `#${ref.variant}` : ""}`
+  const call: PlugRequest = { ...parsed.request, ref }
+  const { exchange } = parsed
+
+  // Abandoned requests (client gone, deadline passed) must never reach the model caller.
+  if (scope.signal.aborted) throw scope.signal.reason
+  const events = boundEvents(
+    host.caller.stream(call, {
+      app,
+      signal: scope.signal,
+      onRecord: (recordID) => {
+        if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
+        response.setHeader(SESSION_HEADER, recordID)
+      },
+    }),
+    scope,
+  )
+
+  if (exchange.stream) {
+    const sse = sseWriter(response, scope.signal)
+    const { failure } = await runResponse(sse.paced(events), exchange, (event) => sse.write(sseFrame(event)))
+    if (!sse.started && !response.headersSent) {
+      if (!scope.signal.aborted || scope.timedOut) fail(failure ?? { status: 502, kind: "server", message: "No response from the model" })
+    } else {
+      if (failure) info.failed = failure.code ?? failure.kind
+      if (!response.writableEnded) response.end()
+    }
+    return
+  }
+
+  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" })
+  sendJson(response, 200, run.response)
+}

package/src/runtime.ts

@@ -18,7 +18,10 @@
  *     scope, forwarding bus events of request sessions to the session store. If it dies, the
  *     requests in flight fail with a 502 instead of waiting for their deadline;
  *   - the session store (src/session/state.ts), which outlives the listener and owns the request
- *     guards, their cleanup timers included.
+ *     guards, their cleanup timers included;
+ *   - the history sweep state: every registered request session is indexed in the host's plugin
+ *     storage and, at most every `SWEEP_INTERVAL_MS`, a sweep prunes old ones past the `history`
+ *     limits (src/session/prune.ts). Both start from request handling (the store's `register`).
  *
  * Registration is explicit: `registerGeneration` returns whether the generation was accepted. A
  * rejected one (different `listen`, options that differ from the live ones, foreign runtime) never
@@ -42,6 +45,8 @@ import { Cause, Effect, Stream } from "effect"
 import { isPlugError, type CatalogModel, type PlugError } from "./contract.js"
 import { errorMessage, log, logError } from "./log.js"
 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"
 
 export type Handler = (request: IncomingMessage, response: ServerResponse) => void
@@ -76,15 +81,23 @@ export interface GenerationInput {
    * never from setup or a finalizer.
    */
   readonly refresh: () => Promise<void>
+  /** The host storage and session deletion used to index and prune request sessions, with the configured limits (identical in every accepted generation). */
+  readonly history: { readonly port: HistoryPort; readonly limits: HistoryLimits }
 }
 
 const GRACE_MS = 10_000
+/** Earliest next history sweep after one ran (sweeps are triggered by requests, never by a timer). */
+const SWEEP_INTERVAL_MS = 10 * 60_000
+/** Earliest next sweep when one left work behind (its budget ran out). */
+const SWEEP_BACKLOG_MS = 60_000
+/** A sweep stops starting host calls after this long; a hung one stops blocking later sweeps 5 s after. */
+const SWEEP_DEADLINE_MS = 60_000
 /** How long `ensureBackend` waits for a Location to boot and its generation to become ready. */
 const BACKEND_TIMEOUT_MS = 15_000
 const BACKEND_POLL_MS = 25
 
-/** 3: the runtime tracks confirmed directories and rejected generations (a version-2 runtime lacks both). */
-const VERSION = 3
+/** 4: adds the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
+const VERSION = 4
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -102,6 +115,7 @@ interface Generation {
   readonly handler: Handler
   readonly loadCatalog: GenerationInput["loadCatalog"]
   readonly refresh: GenerationInput["refresh"]
+  readonly history: GenerationInput["history"]
   /** The context hook and transforms are installed (setup got to its end). */
   hooked: boolean
   /** The transforms have been rebuilt since `confirmed` became true for the directory. */
@@ -124,6 +138,8 @@ interface Runtime {
   readonly confirmed: Set<string>
   /** Live rejected generations per directory: tells "rejected" from "no generation yet". */
   readonly rejected: Map<string, number>
+  /** History sweep rate limit: no sweep starts before `nextAt` (epoch ms) or while one `running`. */
+  readonly sweep: { nextAt: number; running: boolean }
   listener?: Listener
   /** Present while a fiber is subscribed to the server event bus. */
   pump?: Pump
@@ -140,7 +156,14 @@ function runtime(): Runtime | undefined {
   const slot = globalThis as Record<symbol, unknown>
   const existing = slot[KEY] as { readonly version: number } | undefined
   if (!existing) {
-    const created: Runtime = { version: VERSION, sessions: createSessionStore(), generations: [], confirmed: new Set(), rejected: new Map() }
+    const created: Runtime = {
+      version: VERSION,
+      sessions: createSessionStore({ onRegister: (state) => trackSession(created, state.app, state.sessionID) }),
+      generations: [],
+      confirmed: new Set(),
+      rejected: new Map(),
+      sweep: { nextAt: 0, running: false },
+    }
     slot[KEY] = created
     return created
   }
@@ -152,6 +175,54 @@ function runtime(): Runtime | undefined {
   return undefined
 }
 
+/**
+ * A request session was just created: index it, then sweep if due. Runs from request handling
+ * (the store's `register`), never awaited, never throws. Uses the preferred generation's host
+ * handles; the storage and `session.remove` are server-wide, so any live generation works.
+ */
+function trackSession(rt: Runtime, app: string, sessionID: string): void {
+  const history = preferred(rt)?.history
+  if (!history) return logError("history.index_skipped", { app, sessionID, reason: "no live generation" })
+  // No limits, no index: an unbounded index would grow opencode.db by a row per request forever (#85).
+  if (history.limits.maxSessions === undefined && history.limits.maxAgeDays === undefined) return
+  void recordSession(history.port, app, sessionID, Date.now())
+    .catch((error) => logError("history.index_failed", { app, sessionID, error: errorMessage(error) }))
+    .then(() => maybeSweep(rt, history))
+}
+
+/**
+ * Run a history sweep when limits are set, none is running and the rate limit allows. Bounded:
+ * see `sweepHistory`. A sweep that leaves work behind is followed up after `SWEEP_BACKLOG_MS`,
+ * a complete one after `SWEEP_INTERVAL_MS`. Logs one line with counts only.
+ */
+async function maybeSweep(rt: Runtime, history: GenerationInput["history"]): Promise<void> {
+  const { limits, port } = history
+  if (limits.maxSessions === undefined && limits.maxAgeDays === undefined) return
+  const now = Date.now()
+  if (rt.sweep.running || now < rt.sweep.nextAt) return
+  rt.sweep.running = true
+  rt.sweep.nextAt = now + SWEEP_INTERVAL_MS
+  const deadline = AbortSignal.timeout(SWEEP_DEADLINE_MS)
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    const result = await Promise.race([
+      sweepHistory({ port, limits, sessions: rt.sessions, now, signal: deadline }),
+      new Promise<undefined>((resolve) => {
+        timer = setTimeout(() => resolve(undefined), SWEEP_DEADLINE_MS + 5_000)
+        timer.unref?.()
+      }),
+    ])
+    if (!result) return logError("history.sweep_timeout", { limit: SWEEP_DEADLINE_MS })
+    if (result.more) rt.sweep.nextAt = Date.now() + SWEEP_BACKLOG_MS
+    log("history.swept", { ...result, durationMs: Date.now() - now })
+  } catch (error) {
+    logError("history.sweep_failed", { error: errorMessage(error) })
+  } finally {
+    clearTimeout(timer)
+    rt.sweep.running = false
+  }
+}
+
 /** The session store shared by every generation in the process. */
 export const sessionStore = (): SessionStore => runtime()?.sessions ?? detachedSessions
 
@@ -290,6 +361,7 @@ export function registerGeneration(input: GenerationInput): Registration {
     handler: input.handler,
     loadCatalog: input.loadCatalog,
     refresh: input.refresh,
+    history: input.history,
     hooked: false,
     // A directory confirmed before this Location booted needs no rebuild: its transforms already read `confirmed()` as true.
     activated: rt.confirmed.has(directory),

package/src/session/host.ts

@@ -89,6 +89,46 @@ export function createSessionPort(ctx: HostContext): SessionPort {
   }
 }
 
+/**
+ * What the history index needs from the host: the plugin's own key-value storage (`ctx.storage`,
+ * namespaced by plugin id and shared by every Location of the server) and `session.remove`. The
+ * plugin session API has no `list`, so plugboard indexes its own request sessions in that storage
+ * and prunes from the index (src/session/prune.ts).
+ */
+export interface HistoryPort {
+  put(key: string, value: string): Promise<void>
+  drop(key: string): Promise<void>
+  /** Keys under `prefix` in ascending order, after `after` (exclusive); `next` is set when more remain. */
+  scan(input: { readonly prefix: string; readonly after?: string; readonly limit: number }): Promise<{ readonly keys: ReadonlyArray<string>; readonly next?: string }>
+  /** `missing` when the session no longer exists (the host's `Session.NotFoundError`); any other failure rejects. */
+  removeSession(sessionID: string): Promise<"removed" | "missing">
+}
+
+const failureTag = (error: unknown): unknown => (typeof error === "object" && error !== null ? (error as { _tag?: unknown })._tag : undefined)
+
+/** `ctx.storage` and `ctx.session.remove` as a Promise port. The branded session ID is the same host-issued string as above. */
+export function createHistoryPort(ctx: HostContext): HistoryPort {
+  return {
+    put: (key, value) => Effect.runPromise(ctx.storage.set(key, value)),
+    drop: (key) => Effect.runPromise(ctx.storage.remove(key)),
+    scan: (input) =>
+      Effect.runPromise(ctx.storage.scan(input)).then((result) => ({
+        keys: result.entries.map((entry) => entry.key),
+        ...(result.next === undefined ? {} : { next: result.next }),
+      })),
+    removeSession: (sessionID) =>
+      Effect.runPromise(
+        ctx.session.remove({ sessionID: hostSessionID(sessionID) } satisfies Parameters<HostSession["remove"]>[0]).pipe(
+          Effect.match({ onSuccess: () => undefined, onFailure: (error) => ({ error }) }),
+        ),
+      ).then((failed) => {
+        if (failed === undefined) return "removed" as const
+        if (failureTag(failed.error) === "Session.NotFoundError") return "missing" as const
+        throw failed.error
+      }),
+  }
+}
+
 const record = (value: unknown): Record<string, unknown> | undefined =>
   typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined
 

package/src/session/prune.ts

@@ -0,0 +1,175 @@
+/**
+ * History pruning: an index of plugboard's own request sessions and the sweep that deletes the
+ * old ones.
+ *
+ * The plugin session API has no `list`, so plugboard cannot ask the host which sessions it owns.
+ * It keeps an index in the plugin's own host storage (`ctx.storage`, a key-value table in the
+ * host database, shared by every Location): one key per request session,
+ *
+ *   history/<app>/<created, 15 digits of epoch ms>/<sessionID>
+ *
+ * Everything the sweep needs is in the key, so a scan returns an app's sessions oldest first.
+ * Sessions created before this index existed are not in it and are never pruned.
+ *
+ * Both functions run from request handling only (the runtime calls them), never from plugin
+ * setup or a finalizer. A sweep does bounded work: it reads at most `maxScan` index entries per
+ * app, makes at most `maxDeletes` host deletions and stops at its deadline; what is left waits for
+ * the next sweep. A session whose request guard is still in the session store (the host
+ * execution has not ended) is never deleted.
+ */
+
+import type { HistoryPort } from "./host.js"
+import type { SessionStore } from "./state.js"
+
+/** Pruning limits. A field that is unset is not applied; with none set nothing is ever deleted. */
+export interface HistoryLimits {
+  /** Keep at most this many sessions per app (the newest). */
+  readonly maxSessions?: number
+  /** Delete sessions older than this many days. */
+  readonly maxAgeDays?: number
+}
+
+export interface SweepResult {
+  readonly apps: number
+  /** Index entries read. */
+  readonly scanned: number
+  readonly removed: number
+  /** Already gone from the host (deleted by hand); only the index entry was dropped. */
+  readonly missing: number
+  /** Host deletions or index updates that failed; retried by the next sweep. */
+  readonly failed: number
+  /** Over a limit but skipped because the request guard is still active. */
+  readonly active: number
+  /** Work was left (budget, deadline or scan cap reached): run the next sweep soon. */
+  readonly more: boolean
+}
+
+export interface SweepInput {
+  readonly port: HistoryPort
+  readonly limits: HistoryLimits
+  readonly sessions: SessionStore
+  readonly now: number
+  /** Aborts the sweep between host calls. */
+  readonly signal: AbortSignal
+  /** Most host deletions per sweep. */
+  readonly maxDeletes?: number
+  /** Most index entries read per app per sweep. */
+  readonly maxScan?: number
+}
+
+const PREFIX = "history/"
+const AT_WIDTH = 15
+const DAY_MS = 86_400_000
+const PAGE = 500
+const MAX_DELETES = 200
+const MAX_SCAN = 20_000
+
+export const indexKey = (app: string, createdAt: number, sessionID: string): string =>
+  `${PREFIX}${app}/${String(Math.max(0, Math.floor(createdAt))).padStart(AT_WIDTH, "0")}/${sessionID}`
+
+/** Index one new request session. The value repeats the ID; the key carries app and time. */
+export const recordSession = (port: HistoryPort, app: string, sessionID: string, createdAt: number): Promise<void> =>
+  port.put(indexKey(app, createdAt, sessionID), sessionID)
+
+interface Entry {
+  readonly key: string
+  readonly sessionID: string
+  readonly createdAt: number
+}
+
+function parseKey(key: string): Entry | undefined {
+  const [, at, ...rest] = key.slice(PREFIX.length).split("/")
+  const createdAt = Number(at)
+  const sessionID = rest.join("/")
+  if (!/^\d+$/.test(at ?? "") || !Number.isFinite(createdAt) || sessionID.length === 0) return undefined
+  return { key, sessionID, createdAt }
+}
+
+/** App names in the index, found by hopping over each app's keys (one tiny scan per app). */
+async function indexedApps(port: HistoryPort, signal: AbortSignal): Promise<string[]> {
+  const apps: string[] = []
+  let after: string | undefined
+  while (!signal.aborted) {
+    const page = await port.scan({ prefix: PREFIX, ...(after === undefined ? {} : { after }), limit: 1 })
+    const first = page.keys[0]
+    if (first === undefined) break
+    const app = first.slice(PREFIX.length).split("/")[0] ?? ""
+    if (app.length > 0) apps.push(app)
+    // `\uffff` sorts after every character of an ID or timestamp, so this skips the rest of the app.
+    after = `${PREFIX}${app}/\uffff`
+  }
+  return apps
+}
+
+/** One app's entries, oldest first, at most `maxScan`; `capped` when more remain in the index. */
+async function readApp(port: HistoryPort, app: string, maxScan: number, signal: AbortSignal): Promise<{ entries: Entry[]; capped: boolean }> {
+  const entries: Entry[] = []
+  const prefix = `${PREFIX}${app}/`
+  let after: string | undefined
+  while (!signal.aborted) {
+    const page = await port.scan({ prefix, ...(after === undefined ? {} : { after }), limit: Math.min(PAGE, maxScan - entries.length) })
+    for (const key of page.keys) {
+      const entry = parseKey(key)
+      if (entry) entries.push(entry)
+    }
+    if (page.next === undefined) return { entries, capped: false }
+    if (entries.length >= maxScan) return { entries, capped: true }
+    after = page.next
+  }
+  return { entries, capped: true }
+}
+
+/**
+ * One pass over the index. Per app, the sessions to delete are a prefix of its oldest-first list:
+ * as many as exceed `maxSessions`, or are older than `maxAgeDays`, whichever is more. A session
+ * with an active request guard is skipped (it still counts as kept). Entries of sessions the host
+ * no longer has are dropped. A scan that hit `maxScan` only undercounts the app, so it can only
+ * delete fewer sessions than the limit asks for, never more.
+ */
+export async function sweepHistory(input: SweepInput): Promise<SweepResult> {
+  const { port, limits, sessions, signal } = input
+  const maxDeletes = input.maxDeletes ?? MAX_DELETES
+  const maxScan = input.maxScan ?? MAX_SCAN
+  const cutoff = limits.maxAgeDays === undefined ? undefined : input.now - limits.maxAgeDays * DAY_MS
+  let scanned = 0
+  let removed = 0
+  let missing = 0
+  let failed = 0
+  let active = 0
+  let attempts = 0
+  let more = false
+
+  const apps = await indexedApps(port, signal)
+  for (const app of apps) {
+    if (signal.aborted) {
+      more = true
+      break
+    }
+    const { entries, capped } = await readApp(port, app, maxScan, signal)
+    scanned += entries.length
+    if (capped) more = true
+    const excess = limits.maxSessions === undefined ? 0 : Math.max(0, entries.length - limits.maxSessions)
+    const expired = cutoff === undefined ? 0 : entries.findIndex((entry) => entry.createdAt >= cutoff)
+    const count = Math.max(excess, cutoff === undefined ? 0 : expired === -1 ? entries.length : expired)
+    for (const entry of entries.slice(0, count)) {
+      if (signal.aborted || attempts >= maxDeletes) {
+        more = true
+        break
+      }
+      // Checked right before the host call: a guard that is still registered means the host execution is running.
+      if (sessions.lookup(entry.sessionID)) {
+        active++
+        continue
+      }
+      attempts++
+      try {
+        if ((await port.removeSession(entry.sessionID)) === "removed") removed++
+        else missing++
+        await port.drop(entry.key)
+      } catch {
+        failed++
+      }
+    }
+  }
+  return { apps: apps.length, scanned, removed, missing, failed, active, more }
+}

package/src/session/state.ts

@@ -67,7 +67,12 @@ interface Entry {
   timer?: ReturnType<typeof setTimeout>
 }
 
-export function createSessionStore(): SessionStore {
+export interface SessionStoreOptions {
+  /** Called once per `register`, from request handling (the runtime indexes the session for pruning). Must not block; errors are logged. */
+  readonly onRegister?: (state: RequestState) => void
+}
+
+export function createSessionStore(options: SessionStoreOptions = {}): SessionStore {
   const entries = new Map<string, Entry>()
 
   const release = (sessionID: string): boolean => {
@@ -82,6 +87,11 @@ export function createSessionStore(): SessionStore {
       const previous = entries.get(state.sessionID)
       if (previous?.timer) clearTimeout(previous.timer)
       entries.set(state.sessionID, { state, startedAt: Date.now() })
+      try {
+        options.onRegister?.(state)
+      } catch (error) {
+        logError("session.register_hook_failed", { error: errorMessage(error) })
+      }
     },
     lookup: (sessionID) => entries.get(sessionID)?.state,
     release,