opencode-plugboard 0.19.0 → 0.21.0

package/src/admin/route.ts

@@ -0,0 +1,81 @@
+/**
+ * Admin routes for runtime app keys (#55): `GET /v1/admin/keys` (keys without values),
+ * `POST /v1/admin/keys` with body `{ "app": "<name>" }` (a new random key, returned once) and
+ * `DELETE /v1/admin/keys/{keyId}` (revokes a runtime key; a config key is a 409).
+ *
+ * The routes exist only when option `adminKey` is set: without it every path here is a 404. Only the
+ * admin key passes; an app key, a wrong key or no key is a 401. src/openai/route.ts dispatches here
+ * after the origin check and before app authentication, so an app key never reaches them.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { APP_NAME_PATTERN, DEFAULT_APP, authenticateUsage, type PlugboardOptions } from "../config.js"
+import { isPlugError, type PlugError } from "../contract.js"
+import { checkJsonContentType, readJsonBody, sendError, sendJson, type RequestScope } from "../http.js"
+import type { KeyStore } from "../keys.js"
+import { log } from "../log.js"
+import { encodeError } from "../openai/response.js"
+
+export interface AdminHost {
+  /** The live options (`liveOptions`): the config keys, and `adminKey`. */
+  readonly options: PlugboardOptions
+  /** The runtime key store; absent means the admin routes are not served. */
+  readonly keys?: KeyStore
+}
+
+export interface AdminCall {
+  readonly path: string
+  readonly request: IncomingMessage
+  readonly response: ServerResponse
+  readonly scope: RequestScope
+  /** The route's log fields: the route name is set here, so the request log names the admin route. */
+  readonly info: { route: string; app?: string }
+}
+
+const KEYS = "/v1/admin/keys"
+const ONE_KEY = /^\/v1\/admin\/keys\/([0-9a-f]{8})$/
+
+export async function serveAdmin(host: AdminHost, call: AdminCall): Promise<void> {
+  const { path, request, response, scope, info } = call
+  const fail = (error: PlugError) => sendError(response, error, encodeError(error))
+  const { keys } = host
+  if (host.options.adminKey === undefined || keys === undefined)
+    return fail({ status: 404, kind: "not_found", code: "not_found", message: `No route for ${request.method} ${path}` })
+
+  const who = authenticateUsage(host.options, request.headers.authorization, await keys.digests())
+  if (isPlugError(who) || !who.admin) return fail({ status: 401, kind: "authentication", code: "invalid_api_key", message: "Missing or invalid admin key" })
+
+  const id = ONE_KEY.exec(path)?.[1]
+  if (path === KEYS && request.method === "GET") {
+    info.route = "GET /v1/admin/keys"
+    return sendJson(response, 200, { keys: await keys.list(host.options.keys) })
+  }
+  if (path === KEYS && request.method === "POST") {
+    info.route = "POST /v1/admin/keys"
+    const unsupported = checkJsonContentType(request)
+    if (unsupported) return fail(unsupported)
+    const body = await readJsonBody(request, scope.signal)
+    const app = typeof body === "object" && body !== null && !Array.isArray(body) ? (body as { app?: unknown }).app : undefined
+    if (typeof app !== "string" || app === DEFAULT_APP || !APP_NAME_PATTERN.test(app))
+      return fail({ status: 400, kind: "invalid_request", code: "invalid_app", param: "app", message: `\`app\` must match ${APP_NAME_PATTERN} and must not be \`${DEFAULT_APP}\`` })
+    if (Object.hasOwn(host.options.keys, app))
+      return fail({ status: 409, kind: "invalid_request", code: "app_has_config_key", param: "app", message: `App ${app} already has a key in the plugboard config; edit \`keys\` to change it` })
+    const created = await keys.create(app, host.options.keys)
+    log("admin.key_created", { id: created.id, app })
+    // The key value is shown once: a cache or a log of this response must not keep it.
+    response.setHeader("cache-control", "no-store")
+    return sendJson(response, 201, created)
+  }
+  if (id !== undefined && request.method === "DELETE") {
+    info.route = "DELETE /v1/admin/keys/{keyId}"
+    const result = await keys.revoke(id, host.options.keys)
+    if (result === "config")
+      return fail({ status: 409, kind: "invalid_request", code: "config_key", message: "This key is set in the plugboard config (`keys`). Remove it there and reload OpenCode." })
+    if (result === "not_found") return fail({ status: 404, kind: "not_found", code: "key_not_found", message: `No runtime key ${id}` })
+    log("admin.key_revoked", { id })
+    return sendJson(response, 200, { id, revoked: true })
+  }
+  if (path === KEYS || id !== undefined)
+    return fail({ status: 405, kind: "invalid_request", code: "method_not_allowed", message: `Method ${request.method} is not allowed for ${path}` })
+  return fail({ status: 404, kind: "not_found", code: "not_found", message: `No route for ${request.method} ${path}` })
+}

package/src/anthropic/request.ts

@@ -9,6 +9,7 @@
  * afterwards, which is why the request omits `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
+import { bodyUserId, userField } from "../user.js"
 import {
   isPlugError,
   type PlugError,
@@ -327,6 +328,7 @@ export function parseMessagesRequest(body: unknown, options: PlugboardOptions):
     return bad(`tool_choice.name: "${toolChoice.name}" is not in tools`)
 
   const request: Omit<PlugRequest, "ref"> = {
+    ...userField(bodyUserId(body)),
     model: body.model,
     system,
     messages,

package/src/anthropic/response.ts

@@ -114,6 +114,8 @@ export async function runMessage(
   emit: (event: MessagesStreamEvent) => void,
 ): Promise<MessageRun> {
   const id = newId("msg")
+  // Only a non-streamed body needs the aggregate: a stream is already on the wire, so nothing grows (#153).
+  const aggregate = !exchange.stream
   const content: Block[] = []
   /** Blocks opened so far: the next block's `index`. */
   let nextIndex = 0
@@ -155,7 +157,7 @@ export async function runMessage(
     emit({ type: "content_block_stop", index: open.index })
     // The signature is always empty: the host does not expose the provider's thinking signature (#146), so a
     // replayed thinking block cannot carry the real one. Clients that replay thinking are told by the docs.
-    content.push(open.kind === "text" ? { type: "text", text: open.text } : { type: "thinking", thinking: open.text, signature: "" })
+    if (aggregate) content.push(open.kind === "text" ? { type: "text", text: open.text } : { type: "thinking", thinking: open.text, signature: "" })
     open = undefined
   }
   const releaseHeld = () => delta("text", holdback.release())
@@ -173,7 +175,7 @@ export async function runMessage(
       })
       ping()
     }
-    open.text += text
+    if (aggregate) open.text += text
     emit({
       type: "content_block_delta",
       index: open.index,
@@ -192,7 +194,7 @@ export async function runMessage(
     ping()
     emit({ type: "content_block_delta", index, delta: { type: "input_json_delta", partial_json: JSON.stringify(input) } })
     emit({ type: "content_block_stop", index })
-    content.push({ type: "tool_use", id: toolUseId, name: call.name, input })
+    if (aggregate) content.push({ type: "tool_use", id: toolUseId, name: call.name, input })
     calls++
   }
 

package/src/anthropic/route.ts

@@ -12,11 +12,13 @@
  */
 
 import type { IncomingMessage, ServerResponse } from "node:http"
-import { authenticate } from "../config.js"
+import { authenticate, bodyLimits } from "../config.js"
 import { liveOptions } from "../runtime.js"
+import { bodyUserId, noteEndUser } from "../user.js"
 import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
 import {
   BodyError,
+  bodyPlugError,
   RequestAborted,
   boundEvents,
   checkJsonContentType,
@@ -30,8 +32,9 @@ import {
 import { reportServed, type ServedInfo } from "../fallback.js"
 import { resolveModel } from "../models.js"
 import { reportCache } from "../cache.js"
-import { reportPolicy } from "../policy.js"
+import { reportPolicy, reportServerTools } from "../policy.js"
 import { reportUsage } from "../usage-header.js"
+import { setSessionLink } from "../session/link.js"
 import { dropRejected } from "../openai/sampling.js"
 import type { RouteHost } from "../openai/route.js"
 import { parseMessagesRequest } from "./request.js"
@@ -54,7 +57,7 @@ export interface MessagesCall {
   readonly response: ServerResponse
   readonly scope: RequestScope
   /** The route's log fields: the route name, the app, the resolved model, dropped parameters, and the outcome of a stream that failed after it committed. */
-  readonly info: ServedInfo & { route: string; app?: string; model?: string; failed?: string; dropped?: string }
+  readonly info: ServedInfo & { route: string; app?: string; model?: string; failed?: string; dropped?: string; user?: string }
 }
 
 const header = (request: IncomingMessage, name: string): string | undefined => {
@@ -63,11 +66,12 @@ const header = (request: IncomingMessage, name: string): string | undefined => {
 }
 
 /** `Authorization: Bearer` first (Claude Code with ANTHROPIC_AUTH_TOKEN), then `x-api-key` (the Anthropic SDKs). One key store. */
-const authenticateRequest = (host: RouteHost, request: IncomingMessage) => {
+const authenticateRequest = async (host: RouteHost, request: IncomingMessage) => {
   const options = liveOptions(host.options)
-  const bearer = authenticate(options, request.headers.authorization)
+  const runtime = host.keys ? await host.keys.digests() : []
+  const bearer = authenticate(options, request.headers.authorization, runtime)
   const apiKey = header(request, "x-api-key")
-  return isPlugError(bearer) && apiKey ? authenticate(options, `Bearer ${apiKey}`) : bearer
+  return isPlugError(bearer) && apiKey ? authenticate(options, `Bearer ${apiKey}`, runtime) : bearer
 }
 
 export async function serveMessages(host: RouteHost, call: MessagesCall): Promise<void> {
@@ -82,7 +86,7 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
     // Answer in this route's error shape, then rethrow: the shared handler logs the outcome and
     // finds the response already sent.
     if (!response.headersSent) {
-      if (caught instanceof BodyError) fail({ status: caught.status, kind: "invalid_request", message: caught.message }, caught.status === 413)
+      if (caught instanceof BodyError) fail(bodyPlugError(caught), caught.status !== 400)
       else if (caught instanceof RequestAborted) {
         if (caught.kind === "timeout") fail(scope.timeoutError, true)
       } else fail({ status: 500, kind: "server", message: "Internal server error" })
@@ -94,7 +98,7 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
     const rejected = checkOrigin(request, host.options)
     if (rejected) return fail(rejected)
     // Authenticate before the method check, so an unauthenticated caller cannot map this path (#137).
-    const auth = authenticateRequest(host, request)
+    const auth = await authenticateRequest(host, request)
     if (isPlugError(auth)) return fail(auth)
     info.app = auth.app
     if (request.method !== "POST")
@@ -102,7 +106,8 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
     const unsupported = checkJsonContentType(request)
     if (unsupported) return fail(unsupported)
 
-    const body = await readJsonBody(request, scope.signal)
+    const body = await readJsonBody(request, scope.signal, bodyLimits(host.options))
+    noteEndUser(response, info, bodyUserId(body))
     // count_tokens takes the message body without max_tokens; the parser needs one, so a placeholder stands in
     // (the count never uses it). A max_tokens the client did send is still validated.
     const sized = path === COUNT_TOKENS && isRecord(body) && body.max_tokens === undefined ? { ...body, max_tokens: Number.MAX_SAFE_INTEGER } : body
@@ -130,13 +135,15 @@ export async function serveMessages(host: RouteHost, call: MessagesCall): Promis
       host.caller.stream(model, {
         app: auth.app,
         signal: scope.signal,
-        onRecord: (recordID) => {
+        onRecord: (recordID, directory) => {
           if (response.headersSent || response.destroyed || !/^[\x21-\x7e]+$/.test(recordID)) return
           response.setHeader(SESSION_HEADER, recordID)
+          setSessionLink(response, info, host.options.historyUrl, recordID, directory)
         },
         onServed: reportServed(response, info, (served) => void (exchange.model = served.model)),
         onPolicy: reportPolicy(response),
         onUsage: reportUsage(response, exchange.stream),
+        onServerTools: reportServerTools(response, exchange.stream),
         onCache: reportCache(response),
       }),
       scope,

package/src/cache.ts

@@ -25,6 +25,10 @@
  *
  * Fan-out (`n` above 1, prompt arrays) calls the caller once per choice with the same request, so
  * the fan-out sets `noCache`: every choice must be a fresh sample.
+ *
+ * A persona (a skill alias or an `agent/<name>` id, `bypass`) is never cached: its answer depends on
+ * the skill's content or the agent's prompt, which the key does not see, and a skill edit must not be
+ * masked by an old entry.
  */
 
 import { createHash } from "node:crypto"
@@ -114,12 +118,22 @@ function append(events: PlugEvent[], event: { readonly type: "text-delta" | "rea
   else events.push({ type: event.type, text: event.text })
 }
 
-/** Wraps `inner`: hits are replayed, misses stream through and are stored when they qualify. */
-export function cachedCaller(inner: ModelCaller, config: CacheConfig, store: CacheStore, count?: CacheCounter): ModelCaller {
+/**
+ * Wraps `inner`: hits are replayed, misses stream through and are stored when they qualify. `bypass(model, app)`
+ * decides per call that the cache is not used: a persona model, or an app whose answers depend on live OpenCode
+ * tool output (`serverTools`, #82). Both conditions live in the one predicate the runtime passes.
+ */
+export function cachedCaller(
+  inner: ModelCaller,
+  config: CacheConfig,
+  store: CacheStore,
+  count?: CacheCounter,
+  bypass?: (model: string, app: string) => boolean,
+): ModelCaller {
   const apps = config.apps ? new Set(config.apps) : undefined
   return {
     async *stream(request: PlugRequest, context: CallContext): AsyncIterable<PlugEvent> {
-      if (context.noCache || (apps && !apps.has(context.app))) return yield* inner.stream(request, context)
+      if (context.noCache || bypass?.(request.model, context.app) || (apps && !apps.has(context.app))) return yield* inner.stream(request, context)
       const key = cacheKey(context.app, request)
       const hit = store.get(key)
       if (hit) {
@@ -151,9 +165,16 @@ export function cachedCaller(inner: ModelCaller, config: CacheConfig, store: Cac
       }
       const recorded: PlugEvent[] = []
       let storable = true
+      // Text bytes seen so far. An answer over `maxBytes` could never be stored, so capture stops there and frees what it kept (#153).
+      let captured = 0
       for await (const event of inner.stream(request, forward)) {
-        if (event.type === "text-delta" || event.type === "reasoning-delta") append(recorded, event)
-        else if (event.type === "finish") {
+        if (event.type === "text-delta" || event.type === "reasoning-delta") {
+          captured += Buffer.byteLength(event.text)
+          if (captured > config.maxBytes) {
+            storable = false
+            recorded.length = 0
+          } else if (storable) append(recorded, event)
+        } else if (event.type === "finish") {
           // Stored before the event is handed on, so a consumer that stops reading at `finish` still fills the cache.
           if (storable && CACHEABLE_FINISH.has(event.reason) && recorded.length > 0 && !context.signal.aborted)
             store.set(key, { events: [...recorded, { type: "finish", reason: event.reason }], ...(served ? { served } : {}), ...(policy?.length ? { policy } : {}) })

package/src/completions/request.ts

@@ -9,8 +9,9 @@
  * `ref`.
  */
 import type { PlugboardOptions } from "../config.js"
-import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
-import { parseChoiceCount, parseGeneration } from "../openai/request.js"
+import { isPlugError, type PlugError, type PlugRequest, type PlugToolChoice } from "../contract.js"
+import { bodyUser, userField } from "../user.js"
+import { RESPOND_TOOL, parseChoiceCount, parseGeneration, parseResponseFormat } from "../openai/request.js"
 import type { CompletionsExchange } from "./response.js"
 
 export interface ParsedCompletions {
@@ -79,15 +80,23 @@ export function parseCompletionsRequest(body: unknown, options: PlugboardOptions
     )
   const generation = parseGeneration(body)
   if (isPlugError(generation)) return generation
+  // The same response_format as Chat Completions: json_schema is the forced `respond` tool, json_object an instruction.
+  const format = parseResponseFormat(body.response_format)
+  if (isPlugError(format)) return format
 
   const suffix = typeof body.suffix === "string" && body.suffix.length > 0 ? body.suffix : undefined
+  const system = [...(suffix ? [SUFFIX_INSTRUCTION(suffix)] : []), ...(format.instruction ? [format.instruction] : [])]
+  const tools = format.structured ? [format.structured] : []
+  const toolChoice: PlugToolChoice | undefined = format.structured ? { type: "tool", name: RESPOND_TOOL } : undefined
   const streamOptions = isRecord(body.stream_options) ? body.stream_options : {}
   return {
     requests: prompts.map((prompt) => ({
       model: body.model as string,
-      system: suffix ? [SUFFIX_INSTRUCTION(suffix)] : [],
+      ...userField(bodyUser(body)),
+      system,
       messages: [{ role: "user", content: [{ type: "text", text: prompt }] }],
-      tools: [],
+      tools,
+      ...(toolChoice ? { toolChoice } : {}),
       generation,
     })),
     n,
@@ -98,6 +107,8 @@ export function parseCompletionsRequest(body: unknown, options: PlugboardOptions
       perPrompt: n,
       ...(body.echo === true ? { echo: prompts } : {}),
       ...(generation.stop ? { stop: generation.stop } : {}),
+      ...(format.structured ? { structuredTool: RESPOND_TOOL, structuredSchema: format.structured.parameters } : {}),
+      ...(format.instruction ? { jsonObject: true } : {}),
     },
     ...(typeof body.reasoning_effort === "string" ? { reasoningEffort: body.reasoning_effort } : {}),
   }

package/src/completions/response.ts

@@ -5,9 +5,9 @@
  * Reasoning deltas and tool calls are dropped: the legacy format has neither, and the request
  * offers no tools. `logprobs` is always null.
  */
-import type { PlugError, PlugEvent, PlugFinish, PlugUsage } from "../contract.js"
+import { isPlugError, type PlugError, type PlugEvent, type PlugFinish, type PlugUsage } from "../contract.js"
 import type { ChoiceCodec } from "../openai/fanout.js"
-import { encodeError, type StreamChoice, type StreamResult } from "../openai/response.js"
+import { args, encodeError, structuredMissing, textFallback, unfence, type CollectedChoice, type StreamChoice, type StreamResult } from "../openai/response.js"
 import { StopHoldback, stripStopTail } from "../stop.js"
 
 /** What the encoders need besides the model events; the request decoder produces it, the model call never sees it. */
@@ -23,6 +23,12 @@ export interface CompletionsExchange {
   readonly echo?: ReadonlyArray<string>
   /** The request's `stop`. A plain stop whose text ends with one of these leaves the sequence out (src/stop.ts). */
   readonly stop?: ReadonlyArray<string>
+  /** `response_format: json_schema`: the name of the forced tool whose input is the answer (`respond`). The answer is its arguments as text. */
+  readonly structuredTool?: string
+  /** The caller's `json_schema`: a text answer is taken when the model skipped the call and its text is that JSON (`textFallback`). */
+  readonly structuredSchema?: Readonly<Record<string, unknown>>
+  /** `response_format: json_object`: a single markdown fence around the answer is stripped (`unfence`). */
+  readonly jsonObject?: boolean
 }
 
 const FINISH_REASONS: Record<Exclude<PlugFinish, "error">, string> = {
@@ -46,15 +52,31 @@ const encodeUsage = (usage: PlugUsage) => {
 
 const prefixOf = (exchange: CompletionsExchange, index: number) => exchange.echo?.[Math.floor(index / exchange.perPrompt)] ?? ""
 
-/** One choice as a complete body: `choices[0]` carries the text, `usage` the totals. */
-async function collectText(events: AsyncIterable<PlugEvent>, exchange: CompletionsExchange, index: number): Promise<{ status: number; body: object; retryAfterSeconds?: number }> {
+/** A choice's settled answer: its text, the finish reason and the usage. */
+interface Settled {
+  readonly text: string
+  readonly reason: Exclude<PlugFinish, "error">
+  readonly usage?: PlugUsage
+  /** The structured answer came from the text (see `textFallback`), not the respond call. */
+  readonly fallback?: boolean
+}
+
+/**
+ * Reads one whole choice. A structured answer is the arguments of the `respond` call (the text is
+ * ignored); a json_object answer loses one code fence. Without the call a structured choice fails,
+ * as in Chat Completions (`structuredMissing`).
+ */
+async function settle(events: AsyncIterable<PlugEvent>, exchange: CompletionsExchange): Promise<Settled | PlugError> {
   let text = ""
+  let answer: string | undefined
   let finish: Exclude<PlugFinish, "error"> | undefined
   let usage: PlugUsage | undefined
   let failure: PlugError | undefined
   for await (const event of events) {
     if (event.type === "text-delta") text += event.text
-    else if (event.type === "finish") {
+    else if (event.type === "tool-call") {
+      if (exchange.structuredTool !== undefined && event.name === exchange.structuredTool) answer ??= args(event.input)
+    } else if (event.type === "finish") {
       usage = event.usage ?? usage
       if (event.reason === "error") failure ??= failedRun()
       else finish = event.reason
@@ -64,20 +86,31 @@ async function collectText(events: AsyncIterable<PlugEvent>, exchange: Completio
     }
   }
   if (!failure && !finish) failure = noFinish()
-  if (failure || !finish) {
-    const error = failure ?? noFinish()
-    return { status: error.status, body: encodeError(error), retryAfterSeconds: error.retryAfterSeconds }
+  if (failure || !finish) return failure ?? noFinish()
+  if (exchange.structuredTool !== undefined) {
+    if (answer !== undefined) return { text: answer, reason: finish, usage }
+    const fallback = exchange.structuredSchema === undefined ? undefined : textFallback(text, exchange.structuredSchema)
+    if (fallback === undefined) return structuredMissing(exchange.structuredTool)
+    return { text: fallback, reason: finish, usage, fallback: true }
   }
   if (finish === "stop") text = stripStopTail(text, exchange.stop ?? []).text
+  return { text: exchange.jsonObject ? unfence(text) : text, reason: finish, usage }
+}
+
+/** One choice as a complete body: `choices[0]` carries the text, `usage` the totals. */
+async function collectText(events: AsyncIterable<PlugEvent>, exchange: CompletionsExchange, index: number): Promise<CollectedChoice> {
+  const settled = await settle(events, exchange)
+  if (isPlugError(settled)) return { status: settled.status, body: encodeError(settled), retryAfterSeconds: settled.retryAfterSeconds }
   return {
+    ...(settled.fallback ? { structuredFallback: true } : {}),
     status: 200,
     body: {
       id: `cmpl-${crypto.randomUUID().replaceAll("-", "").slice(0, 29)}`,
       object: "text_completion",
       created: now(),
       model: exchange.model,
-      choices: [{ text: prefixOf(exchange, index) + text, index: 0, logprobs: null, finish_reason: FINISH_REASONS[finish] }],
-      ...(usage ? { usage: encodeUsage(usage) } : {}),
+      choices: [{ text: prefixOf(exchange, index) + settled.text, index: 0, logprobs: null, finish_reason: FINISH_REASONS[settled.reason] }],
+      ...(settled.usage ? { usage: encodeUsage(settled.usage) } : {}),
     },
   }
 }
@@ -110,6 +143,15 @@ async function streamText(
     const prefix = prefixOf(exchange, choice.index)
     if (prefix.length > 0) chunk(prefix)
   }
+  if (exchange.structuredTool !== undefined || exchange.jsonObject) {
+    // A structured or json_object answer is only known at the end (the call, the fence), so it is written as one chunk.
+    const settled = await settle(events, exchange)
+    if (isPlugError(settled)) return { failure: settled, started: false }
+    start()
+    if (settled.text.length > 0) chunk(settled.text)
+    chunk("", FINISH_REASONS[settled.reason])
+    return { started, ...(settled.usage ? { usage: settled.usage } : {}) }
+  }
   // A stop sequence is held back until the finish decides it (src/stop.ts).
   const holdback = new StopHoldback(exchange.stop ?? [])
   let finish: Exclude<PlugFinish, "error"> | undefined