opencode-plugboard 0.19.0 → 0.21.0

package/src/http.ts

@@ -6,7 +6,7 @@
 
 import type { IncomingMessage, ServerResponse } from "node:http"
 import { raceAbort } from "./abort.js"
-import { isLoopbackHost, type PlugboardOptions } from "./config.js"
+import { BODY_LIMIT_DEFAULTS, type BodyLimits, isLoopbackHost, type PlugboardOptions } from "./config.js"
 import type { PlugError, PlugEvent } from "./contract.js"
 
 const MAX_BODY_BYTES = 32 * 1024 * 1024
@@ -19,16 +19,44 @@ const DEADLINE_GRACE_MS = 2_000
 /** An SSE stream idle for this long gets a comment line, so a client with a header or idle timeout keeps waiting for a model that is still reasoning. */
 const KEEPALIVE_MS = 15_000
 
-/** A request body that cannot be accepted: too large, or not JSON. `status` is the HTTP status to answer with. */
+/**
+ * A request body that cannot be accepted: too large, not JSON, not complete in time (408), or refused
+ * because the process has no room for it (503). `status` is the HTTP status to answer with; `code` and
+ * `retryAfterSeconds` go to the wire (`bodyPlugError`).
+ */
 export class BodyError extends Error {
   constructor(
     readonly status: number,
     message: string,
+    readonly code?: string,
+    readonly retryAfterSeconds?: number,
   ) {
     super(message)
   }
 }
 
+/** The `PlugError` a refused body answers with: `server_busy` (503) is a server kind, a slow body (408) a timeout. */
+export function bodyPlugError(error: BodyError): PlugError {
+  const kind: PlugError["kind"] = error.status === 503 ? "server" : error.status === 408 ? "timeout" : "invalid_request"
+  return {
+    status: error.status,
+    kind,
+    message: error.message,
+    ...(error.code === undefined ? {} : { code: error.code }),
+    ...(error.retryAfterSeconds === undefined ? {} : { retryAfterSeconds: error.retryAfterSeconds }),
+  }
+}
+
+/** Process-wide bytes of request bodies being read. On `globalThis` under a versioned key (I6), so every plugin generation shares one budget. */
+interface BodyBudget {
+  inFlight: number
+}
+const BODY_BUDGET = Symbol.for("opencode-plugboard.body-budget/1")
+const bodyBudget = (): BodyBudget => {
+  const slot = globalThis as Record<symbol, BodyBudget | undefined>
+  return (slot[BODY_BUDGET] ??= { inFlight: 0 })
+}
+
 /** Why a request's work was abandoned: the client went away, or the deadline passed. It is the abort reason of `RequestScope.signal`. */
 export class RequestAborted extends Error {
   constructor(readonly kind: "disconnected" | "timeout") {
@@ -105,21 +133,40 @@ export function beginRequest(request: IncomingMessage, response: ServerResponse,
 }
 
 /**
- * Reads the body as JSON (an empty body is `{}`). Rejects with `BodyError` (413, 400), the abort
- * reason of `signal` or the stream's error. On rejection the rest of the body is discarded, not
+ * Reads the body as JSON (an empty body is `{}`). Rejects with `BodyError` (413, 400, 408 or 503), the
+ * abort reason of `signal` or the stream's error. On rejection the rest of the body is discarded, not
  * buffered, so the response can still be delivered (see `finishRequest`).
+ *
+ * Bounded before it is buffered (#156, invariant I28). The bytes held by every body being read in the
+ * process stay within `limits.maxBytesInFlight`: a declared Content-Length is charged before the first
+ * byte is read, a body without one as it arrives, and a body that would go over is refused with 503
+ * `server_busy` (Retry-After 1). A body not complete within `limits.readTimeoutMs` is refused with 408.
  */
-export function readJsonBody(request: IncomingMessage, signal: AbortSignal): Promise<unknown> {
+export function readJsonBody(request: IncomingMessage, signal: AbortSignal, limits: BodyLimits = BODY_LIMIT_DEFAULTS): Promise<unknown> {
   return new Promise((resolve, reject) => {
-    const declared = Number(request.headers["content-length"])
-    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+    const declared = Math.max(0, Number(request.headers["content-length"]) || 0)
+    if (declared > MAX_BODY_BYTES) {
       request.resume()
       return reject(new BodyError(413, "Request body too large"))
     }
     if (signal.aborted) return reject(signal.reason)
+    const budget = bodyBudget()
     const chunks: Buffer[] = []
     let size = 0
+    // Bytes this read holds in the budget. Released on every exit: complete, refused or abandoned.
+    let held = 0
+    const charge = (bytes: number): boolean => {
+      if (budget.inFlight + bytes > limits.maxBytesInFlight) return false
+      budget.inFlight += bytes
+      held += bytes
+      return true
+    }
+    const busy = () => new BodyError(503, "Too many request bodies are being read; retry shortly", "server_busy", 1)
+    let timer: ReturnType<typeof setTimeout> | undefined
     const cleanup = () => {
+      clearTimeout(timer)
+      budget.inFlight -= held
+      held = 0
       request.off("data", onData)
       request.off("error", onError)
       request.off("end", onEnd)
@@ -134,6 +181,7 @@ export function readJsonBody(request: IncomingMessage, signal: AbortSignal): Pro
     const onData = (chunk: Buffer) => {
       size += chunk.length
       if (size > MAX_BODY_BYTES) return stop(new BodyError(413, "Request body too large"))
+      if (size > held && !charge(size - held)) return stop(busy())
       chunks.push(chunk)
     }
     const onError = (error: Error) => stop(error)
@@ -146,6 +194,16 @@ export function readJsonBody(request: IncomingMessage, signal: AbortSignal): Pro
         reject(new BodyError(400, "Request body is not valid JSON"))
       }
     }
+    // The declared length is charged before the first byte is read, so a refusal costs no buffering.
+    if (declared > 0 && !charge(declared)) {
+      request.resume()
+      return reject(busy())
+    }
+    timer = setTimeout(
+      () => stop(new BodyError(408, `Request body was not received within ${limits.readTimeoutMs} ms (option limits.bodyReadTimeoutMs)`, "body_read_timeout")),
+      limits.readTimeoutMs,
+    )
+    timer.unref?.()
     request.on("data", onData)
     request.on("error", onError)
     request.on("end", onEnd)

package/src/keys.ts

@@ -0,0 +1,172 @@
+/**
+ * Runtime app keys (#55): keys created through `/v1/admin/keys` (src/admin/route.ts), kept beside
+ * the keys of the config.
+ *
+ * Each runtime key is one record in the plugin's host storage (`ctx.storage`, the table the history
+ * index and usage use) under `keys/<id>`, as JSON `{ app, digest, createdAt }`. The digest is the
+ * SHA-256 of the key, so the key value is never stored: it is returned once, by the create call.
+ * The id is the first 8 hex chars of that digest, the name `DELETE` takes; it is safe to show.
+ *
+ * The records are read lazily, from request handling, by the first request that authenticates (never
+ * from plugin setup, I3), and cached on the process runtime (`KeyState`), so the cache outlives a
+ * plugin generation. A failed read leaves the cache unloaded: runtime keys then fail closed (401) and
+ * the next request reads again. Create and revoke write storage first and the cache second, so a
+ * revoked key stops authenticating on the next request.
+ */
+
+import { createHash, randomBytes } from "node:crypto"
+import { APP_NAME_PATTERN } from "./config.js"
+import { errorMessage, logError } from "./log.js"
+import type { StoragePort } from "./session/host.js"
+
+const PREFIX = "keys/"
+const SCAN_PAGE = 200
+/** A collision of two 32-bit ids is rare; a fresh key is drawn instead of sharing an id. */
+const ID_ATTEMPTS = 5
+
+export interface RuntimeKey {
+  readonly id: string
+  readonly app: string
+  readonly digest: Buffer
+  readonly createdAt: string
+}
+
+/** The live cache of runtime keys on the process runtime (src/runtime.ts). */
+export interface KeyState {
+  loaded: boolean
+  readonly keys: Map<string, RuntimeKey>
+}
+
+export const createKeyState = (): KeyState => ({ loaded: false, keys: new Map() })
+
+/** SHA-256 of a key: what is stored and compared. */
+export const keyDigest = (key: string): Buffer => createHash("sha256").update(key).digest()
+
+/** The id of a key: the first 8 hex chars of its digest. */
+export const keyIdOf = (digest: Buffer): string => digest.subarray(0, 4).toString("hex")
+
+export interface KeyListing {
+  readonly id: string
+  readonly app: string
+  readonly source: "config" | "runtime"
+  readonly createdAt?: string
+}
+
+export interface CreatedKey {
+  readonly id: string
+  readonly app: string
+  /** The key value. Returned by `create` only; it is never stored or listed. */
+  readonly key: string
+  readonly createdAt: string
+}
+
+export interface KeyStore {
+  /** The digests of the loaded runtime keys, as `[app, digest]`. Reads storage once; a failed read answers with what is loaded. */
+  digests(): Promise<ReadonlyArray<readonly [string, Buffer]>>
+  /** Config keys and runtime keys, without key values. */
+  list(config: Readonly<Record<string, string>>): Promise<ReadonlyArray<KeyListing>>
+  /** A new random key for `app`. The caller checks the app name and that the config has no key for it. */
+  create(app: string, config: Readonly<Record<string, string>>): Promise<CreatedKey>
+  /** `config` when the id names a config key (not revocable here), `not_found` when no runtime key has it. */
+  revoke(id: string, config: Readonly<Record<string, string>>): Promise<"revoked" | "config" | "not_found">
+}
+
+export interface KeyStoreDeps {
+  readonly state: KeyState
+  readonly storage: StoragePort
+  /** Epoch ms; tests inject a clock. */
+  readonly now?: () => number
+}
+
+const configIds = (config: Readonly<Record<string, string>>): Set<string> => new Set(Object.values(config).map((key) => keyIdOf(keyDigest(key))))
+
+/** A stored record, or undefined when the value is not one (logged; the key then never authenticates). */
+function parseRecord(id: string, raw: string | undefined): RuntimeKey | undefined {
+  try {
+    const value = JSON.parse(raw ?? "") as { app?: unknown; digest?: unknown; createdAt?: unknown }
+    const digest = typeof value.digest === "string" && /^[0-9a-f]{64}$/.test(value.digest) ? Buffer.from(value.digest, "hex") : undefined
+    if (typeof value.app !== "string" || !APP_NAME_PATTERN.test(value.app) || digest === undefined || typeof value.createdAt !== "string") throw new Error("shape")
+    if (keyIdOf(digest) !== id) throw new Error("id")
+    return { id, app: value.app, digest, createdAt: value.createdAt }
+  } catch {
+    logError("keys.unreadable", { id })
+    return undefined
+  }
+}
+
+export function createKeyStore(deps: KeyStoreDeps): KeyStore {
+  const { state, storage } = deps
+  const now = deps.now ?? Date.now
+  let loading: Promise<void> | undefined
+
+  /** Reads every stored key once. Concurrent callers share one read. */
+  const ensure = (): Promise<void> => {
+    if (state.loaded) return Promise.resolve()
+    loading ??= (async () => {
+      const found = new Map<string, RuntimeKey>()
+      let after: string | undefined
+      for (;;) {
+        const page = await storage.scan({ prefix: PREFIX, ...(after === undefined ? {} : { after }), limit: SCAN_PAGE })
+        for (const key of page.keys) {
+          const record = parseRecord(key.slice(PREFIX.length), await storage.get(key))
+          if (record) found.set(record.id, record)
+        }
+        if (page.next === undefined) break
+        after = page.next
+      }
+      state.keys.clear()
+      for (const [id, record] of found) state.keys.set(id, record)
+      state.loaded = true
+    })().finally(() => {
+      loading = undefined
+    })
+    return loading
+  }
+
+  return {
+    async digests() {
+      try {
+        await ensure()
+      } catch (error) {
+        logError("keys.load_failed", { error: errorMessage(error) })
+      }
+      return [...state.keys.values()].map((record) => [record.app, record.digest] as const)
+    },
+
+    async list(config) {
+      await ensure()
+      const runtime = [...state.keys.values()].sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0))
+      return [
+        ...Object.entries(config).map(([app, key]) => ({ id: keyIdOf(keyDigest(key)), app, source: "config" as const })),
+        ...runtime.map((record) => ({ id: record.id, app: record.app, source: "runtime" as const, createdAt: record.createdAt })),
+      ]
+    },
+
+    async create(app, config) {
+      await ensure()
+      const taken = configIds(config)
+      for (let attempt = 0; attempt < ID_ATTEMPTS; attempt++) {
+        const key = randomBytes(32).toString("base64url")
+        const digest = keyDigest(key)
+        const id = keyIdOf(digest)
+        if (taken.has(id) || state.keys.has(id)) continue
+        const createdAt = new Date(now()).toISOString()
+        // Storage first: a failed write creates no key, and the value is never returned for a key that does not exist.
+        await storage.put(PREFIX + id, JSON.stringify({ app, digest: digest.toString("hex"), createdAt }))
+        state.keys.set(id, { id, app, digest, createdAt })
+        return { id, app, key, createdAt }
+      }
+      throw new Error("could not draw an unused key id")
+    },
+
+    async revoke(id, config) {
+      await ensure()
+      if (configIds(config).has(id)) return "config"
+      if (!state.keys.has(id)) return "not_found"
+      // Storage first: if the delete fails the key keeps working and the caller can retry.
+      await storage.drop(PREFIX + id)
+      state.keys.delete(id)
+      return "revoked"
+    },
+  }
+}

package/src/models.ts

@@ -3,6 +3,12 @@
 import { appPolicy, type AppPolicy, type PlugboardOptions } from "./config.js"
 import type { CatalogModel, ModelRef, PlugError } from "./contract.js"
 
+/** Alias target prefix that binds a skill: `skill:<id>@provider/model[#variant]` (see `parseAliasTarget`). */
+export const SKILL_PREFIX = "skill:"
+/** Listed id prefix of an agent (option `agents`): `agent/<name>`. Aliases cannot contain `/`, so the two never collide. */
+export const AGENT_PREFIX = "agent/"
+const SKILL_TARGET = /^skill:([^@\s#*/]+)@([^@/#*\s]+\/[^@#*\s]+(#[^#*\s]+)?)$/
+
 /** `provider/model[#variant]`. The model id may contain slashes (`openrouter/vendor/model`). */
 export function parseModelRef(s: string): ModelRef | undefined {
   if (typeof s !== "string") return undefined
@@ -58,6 +64,42 @@ export function allowedBy(models: ReadonlyArray<string>, ref: ModelRef): boolean
 
 const allowed = (options: PlugboardOptions, ref: ModelRef): boolean => allowedBy(options.models, ref)
 
+/** An alias target as written in `aliases`: `provider/model[#variant]`, or `skill:<id>@` in front of one. */
+export interface AliasTarget {
+  readonly ref: ModelRef
+  /** The skill the alias binds, for a `skill:` target. */
+  readonly skill?: string
+}
+
+/** The model (and skill) an alias target names, or undefined when it is neither form. */
+export function parseAliasTarget(target: string): AliasTarget | undefined {
+  if (!target.startsWith(SKILL_PREFIX)) {
+    const ref = parseModelRef(target)
+    return ref === undefined ? undefined : { ref }
+  }
+  const match = SKILL_TARGET.exec(target)
+  const ref = match ? parseModelRef(match[2]!) : undefined
+  return match && ref ? { ref, skill: match[1]! } : undefined
+}
+
+/**
+ * What a request name stands for, beyond a plain model: a skill alias (its skill id) or an agent (its name
+ * in option `agents`). Undefined for plain model ids and plain aliases. The caller reads it to add the
+ * skill's content or the agent's system prompt to the session.
+ */
+export type Persona = { readonly kind: "skill"; readonly skill: string } | { readonly kind: "agent"; readonly agent: string }
+
+export function personaOf(options: Pick<PlugboardOptions, "aliases" | "agents">, name: string): Persona | undefined {
+  const target = own(options.aliases, name)
+  if (target !== undefined) {
+    const skill = parseAliasTarget(target)?.skill
+    return skill === undefined ? undefined : { kind: "skill", skill }
+  }
+  if (!name.startsWith(AGENT_PREFIX)) return undefined
+  const agent = name.slice(AGENT_PREFIX.length)
+  return Object.hasOwn(options.agents, agent) ? { kind: "agent", agent } : undefined
+}
+
 /**
  * Per-app narrowing (`apps.<name>.models`), applied on top of the global allowlist, never instead of it.
  * `name` is what the caller sent (an alias or a model id). An entry that is an alias name admits that
@@ -108,7 +150,15 @@ export function resolveModel(
     param: "model",
   }
   // Aliases keep priority over slugs; a slug and a canonical id both resolve, whatever `modelIds` lists.
-  let ref = parseModelRef(own(options.aliases, model) ?? fromSlug(model) ?? model)
+  // An agent runs on the model its `agents` entry names (the allowlist still applies below).
+  const target = own(options.aliases, model)
+  const persona = personaOf(options, model)
+  let ref =
+    target !== undefined
+      ? parseAliasTarget(target)?.ref
+      : persona?.kind === "agent"
+        ? parseModelRef(options.agents[persona.agent]!)
+        : parseModelRef(fromSlug(model) ?? model)
   if (!ref) return notAvailable
   if (!ref.variant && reasoningEffort && find(catalog, { ...ref, variant: reasoningEffort }))
     ref = { ...ref, variant: reasoningEffort }
@@ -120,6 +170,10 @@ export interface ListedModel {
   readonly id: string
   readonly ref: ModelRef
   readonly model: CatalogModel
+  /** The skill an alias binds (`skill:` target), listed as `plugboard.skill`. */
+  readonly skill?: string
+  /** The agent an `agent/<name>` id runs, listed as `plugboard.agent`. */
+  readonly agent?: string
 }
 
 /**
@@ -146,9 +200,16 @@ export function listAvailableModels(options: PlugboardOptions, catalog: Readonly
     }
   }
   for (const [alias, target] of Object.entries(options.aliases)) {
-    const ref = parseModelRef(target)
+    const parsed = parseAliasTarget(target)
+    const ref = parsed?.ref
     const model = ref && allowed(options, ref) && inAppScope(policy, alias, ref) ? find(catalog, ref) : undefined
-    if (ref && model) data.push(entry(alias, ref, model))
+    if (ref && model) data.push({ ...entry(alias, ref, model), ...(parsed.skill === undefined ? {} : { skill: parsed.skill }) })
+  }
+  for (const [name, target] of Object.entries(options.agents)) {
+    const id = `${AGENT_PREFIX}${name}`
+    const ref = parseModelRef(target)
+    const model = ref && allowed(options, ref) && inAppScope(policy, id, ref) ? find(catalog, ref) : undefined
+    if (ref && model) data.push({ ...entry(id, ref, model), agent: name })
   }
   return data
 }

package/src/openai/fanout.ts

@@ -24,10 +24,21 @@ import type { ServerResponse } from "node:http"
 import type { PlugError, PlugEvent, PlugRequest, PlugUsage } from "../contract.js"
 import { reportServed, type ServedInfo } from "../fallback.js"
 import { reportCache } from "../cache.js"
-import { reportPolicy } from "../policy.js"
+import { reportPolicy, reportServerTools } from "../policy.js"
 import { reportUsage } from "../usage-header.js"
+import { SESSION_URL_HEADER, sessionUrl } from "../session/link.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 {
+  STRUCTURED_FALLBACK_HEADER,
+  chatUsageChunk,
+  collectCompletion,
+  encodeError,
+  streamCompletion,
+  type CollectedChoice,
+  type OpenAiExchange,
+  type StreamChoice,
+  type StreamResult,
+} from "./response.js"
 import type { RouteHost } from "./route.js"
 
 const SESSION_HEADER = "x-plugboard-session"
@@ -39,7 +50,7 @@ export interface ChoiceCodec {
   /** Prefix of the shared stream id (`chatcmpl-`, `cmpl-`). */
   readonly idPrefix: string
   /** One choice as a complete JSON body with `choices[0]` and `usage`. */
-  collect(events: AsyncIterable<PlugEvent>, index: number): Promise<{ status: number; body: object; retryAfterSeconds?: number }>
+  collect(events: AsyncIterable<PlugEvent>, index: number): Promise<CollectedChoice>
   /** One choice of the shared stream: this choice's chunks only (see `StreamChoice`). */
   streamChoice(events: AsyncIterable<PlugEvent>, write: (chunk: string) => void, choice: StreamChoice): Promise<StreamResult>
   /** The final chunk with the summed usage (`include_usage`). */
@@ -155,7 +166,7 @@ const addUsage = (a: PlugUsage, b: PlugUsage): PlugUsage => {
   return out
 }
 
-export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls, response, scope, info, codec }: ChoicesCall): Promise<void> {
+export async function serveChoices(host: Pick<RouteHost, "caller" | "options">, { app, calls, response, scope, info, codec }: ChoicesCall): Promise<void> {
   const fail = (error: PlugError) => sendError(response, error, encodeError(error))
   // Abandoned requests (client gone, deadline passed) must never reach the model caller.
   if (scope.signal.aborted) throw scope.signal.reason
@@ -165,6 +176,8 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
   const gscope = groupScope(scope, AbortSignal.any([scope.signal, group.signal]))
   /** History record ids as the callers report them, in choice order, for the response header (comma separated). */
   const records: Array<string | undefined> = []
+  /** The session page links of the same records, in choice order (option `historyUrl`, src/session/link.ts). */
+  const links: Array<string | undefined> = []
   // Headers: the first choice to be served wins. Body model: only a single call echoes the served model.
   const served = reportServed(response, info, (s) => {
     if (calls.length === 1) codec.setModel(s.model)
@@ -172,6 +185,8 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
   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)
+  // One header for all choices too: the server tool calls of every choice add up (`x-plugboard-server-tools`).
+  const serverToolsHeader = reportServerTools(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) =>
@@ -179,14 +194,20 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
       host.caller.stream(calls[index]!, {
         app,
         signal: gscope.signal,
-        onRecord: (recordID) => {
+        onRecord: (recordID, directory) => {
           if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
           records[index] = recordID
           response.setHeader(SESSION_HEADER, records.filter((id) => id !== undefined).join(","))
+          if (host.options.historyUrl !== undefined) {
+            links[index] = sessionUrl(host.options.historyUrl, recordID, directory)
+            info.sessionUrl = links.filter((link) => link !== undefined).join(",")
+            response.setHeader(SESSION_URL_HEADER, info.sessionUrl)
+          }
         },
         onServed: served,
         onPolicy: policy,
         onUsage: usageHeader,
+        onServerTools: serverToolsHeader,
         onCache: cache,
         noCache: calls.length > 1,
       }),
@@ -194,8 +215,8 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
     )
 
   if (!codec.stream) {
-    const results = await new Promise<Array<{ status: number; body: object; retryAfterSeconds?: number }>>((resolve, reject) => {
-      const done: Array<{ status: number; body: object; retryAfterSeconds?: number }> = []
+    const results = await new Promise<CollectedChoice[]>((resolve, reject) => {
+      const done: CollectedChoice[] = []
       let left = calls.length
       calls.forEach((_, index) => {
         codec.collect(open(index), index).then(
@@ -215,6 +236,7 @@ export async function serveChoices(host: Pick<RouteHost, "caller">, { app, calls
       })
     })
     const first = results[0]!
+    if (results.some((result) => result.structuredFallback)) response.setHeader(STRUCTURED_FALLBACK_HEADER, "text")
     return sendJson(response, first.status, results.length === 1 ? first.body : mergeBodies(results.map((result) => result.body)), { retryAfterSeconds: first.retryAfterSeconds })
   }
 

package/src/openai/request.ts

@@ -6,6 +6,7 @@
  * the request omits `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
+import { bodyUser, userField } from "../user.js"
 import {
   isPlugError,
   type PlugError,
@@ -31,7 +32,7 @@ export interface ParsedChat {
 }
 
 /** Name of the forced tool that carries structured output. */
-const RESPOND_TOOL = "respond"
+export const RESPOND_TOOL = "respond"
 
 /** The most stop sequences OpenAI accepts. */
 const MAX_STOP = 4
@@ -195,14 +196,14 @@ const parseToolChoice = (raw: unknown): PlugToolChoice | undefined | PlugError =
 }
 
 /** System instruction for `json_object`: no schema, so the caller's prompt describes the keys (OpenAI semantics). */
-const JSON_OBJECT_INSTRUCTION = "Respond with a single valid JSON object only."
+export const JSON_OBJECT_INSTRUCTION = "Respond with a single valid JSON object only."
 
 /**
  * `json_schema` -> the `respond` tool (`structured`; forced unless the caller also sends tools).
  * `json_object` -> a system instruction and plain text content (`instruction`): there is no schema
  * to force a tool with.
  */
-const parseResponseFormat = (raw: unknown): { structured?: PlugTool; instruction?: string } | PlugError => {
+export const parseResponseFormat = (raw: unknown): { structured?: PlugTool; instruction?: string } | PlugError => {
   if (raw == null) return {}
   if (!isRecord(raw)) return bad("response_format must be an object", "response_format")
   if (raw.type === "text") return {}
@@ -322,6 +323,7 @@ export function parseChatRequest(body: unknown, options: PlugboardOptions): Pars
 
   const forced: PlugToolChoice | undefined = respond ? (withCallerTools ? "required" : { type: "tool", name: RESPOND_TOOL }) : toolChoice
   const request: Omit<PlugRequest, "ref"> = {
+    ...userField(bodyUser(body)),
     model: body.model,
     system: format.instruction ? [...parsed.system, format.instruction] : parsed.system,
     messages: parsed.messages,
@@ -337,7 +339,7 @@ export function parseChatRequest(body: unknown, options: PlugboardOptions): Pars
       model: body.model,
       stream: body.stream === true,
       includeUsage: streamOptions.include_usage === true,
-      ...(respond ? { structuredTool: RESPOND_TOOL, ...(withCallerTools ? { callerTools: true } : {}) } : {}),
+      ...(respond ? { structuredTool: RESPOND_TOOL, structuredSchema: respond.parameters, ...(withCallerTools ? { callerTools: true } : {}) } : {}),
       ...(format.instruction ? { jsonObject: true } : {}),
       ...(generation.stop ? { stop: generation.stop } : {}),
     },