opencode-plugboard 0.0.0-stage → 0.2.1

package/src/contract.ts

@@ -0,0 +1,155 @@
+/**
+ * The neutral vocabulary between plugboard's layers.
+ *
+ * Front-ends (OpenAI Chat Completions now; others later) translate their wire format to and
+ * from these types. A `ModelCaller` turns a `PlugRequest` into a stream of `PlugEvent`s. Names
+ * mirror `@opencode/ai` (request parts, `LLMEvent`, `Usage`) so a native `ctx.llm.stream`
+ * backend could replace the session backend without touching the front-ends.
+ *
+ * Nothing here is specific to a wire protocol: response-shaping choices (streaming, usage
+ * chunks, structured-output unwrapping) belong to the front-end, not to the request.
+ *
+ * Types plus one discriminator (`isPlugError`).
+ */
+
+// ---------------------------------------------------------------- models
+
+export interface ModelRef {
+  readonly providerID: string
+  readonly id: string
+  readonly variant?: string
+}
+
+/** One enabled model as the server sees it: what model listing and the request resolver work from. */
+export interface CatalogModel {
+  readonly providerID: string
+  readonly id: string
+  readonly name?: string
+  readonly variants: ReadonlyArray<string>
+  readonly capabilities?: { readonly tools?: boolean; readonly image?: boolean }
+  readonly contextLimit?: number
+}
+
+// ---------------------------------------------------------------- request
+
+export interface TextPart {
+  readonly type: "text"
+  readonly text: string
+}
+/** Image or file. `url` is a data: URL or http(s) URL; the backend turns it into a host media asset. */
+export interface MediaPart {
+  readonly type: "media"
+  readonly url: string
+  readonly mediaType?: string
+}
+export interface ToolCallPart {
+  readonly type: "tool-call"
+  readonly id: string
+  readonly name: string
+  readonly input: unknown
+}
+export interface ToolResultPart {
+  readonly type: "tool-result"
+  readonly id: string
+  readonly name: string
+  /** Text content as the caller sent it (JSON strings stay strings). */
+  readonly result: string
+  readonly isError?: boolean
+}
+
+export type PlugPart = TextPart | MediaPart | ToolCallPart | ToolResultPart
+
+export interface PlugMessage {
+  readonly role: "user" | "assistant" | "tool"
+  readonly content: ReadonlyArray<PlugPart>
+}
+
+export interface PlugTool {
+  readonly name: string
+  readonly description: string
+  /** JSON Schema object. */
+  readonly parameters: Readonly<Record<string, unknown>>
+}
+
+export type PlugToolChoice = "auto" | "none" | "required" | { readonly type: "tool"; readonly name: string }
+
+export interface PlugGeneration {
+  readonly maxTokens?: number
+  readonly temperature?: number
+  readonly topP?: number
+  readonly stop?: ReadonlyArray<string>
+  readonly presencePenalty?: number
+  readonly frequencyPenalty?: number
+}
+
+/** Format-neutral model call. Front-ends produce it; the `ModelCaller` consumes it. */
+export interface PlugRequest {
+  /** The model string the caller sent (id or alias). Informational for the backend (session title, metadata). */
+  readonly model: string
+  /** Resolved by the core before reaching the `ModelCaller`. */
+  readonly ref: ModelRef
+  readonly system: ReadonlyArray<string>
+  readonly messages: ReadonlyArray<PlugMessage>
+  readonly tools: ReadonlyArray<PlugTool>
+  readonly toolChoice?: PlugToolChoice
+  readonly generation: PlugGeneration
+}
+
+// ---------------------------------------------------------------- events
+
+/**
+ * Token usage for one model call. Totals are inclusive, like OpenAI's:
+ * `inputTokens` includes `cacheReadTokens` and `cacheWriteTokens`;
+ * `outputTokens` includes `reasoningTokens`.
+ */
+export interface PlugUsage {
+  readonly inputTokens?: number
+  readonly outputTokens?: number
+  readonly reasoningTokens?: number
+  readonly cacheReadTokens?: number
+  readonly cacheWriteTokens?: number
+}
+
+export type PlugFinish = "stop" | "length" | "tool-calls" | "content-filter" | "error"
+
+export type PlugEvent =
+  | { readonly type: "text-delta"; readonly text: string }
+  | { readonly type: "reasoning-delta"; readonly text: string }
+  | { readonly type: "tool-call"; readonly id: string; readonly name: string; readonly input: unknown }
+  | { readonly type: "finish"; readonly reason: PlugFinish; readonly usage?: PlugUsage }
+  | { readonly type: "error"; readonly error: PlugError }
+
+export type PlugErrorKind = "invalid_request" | "authentication" | "permission" | "not_found" | "rate_limit" | "server" | "timeout"
+
+/**
+ * An error with an HTTP status and a transport-neutral kind. Front-ends map `kind` to their wire
+ * vocabulary (OpenAI: `src/openai/response.ts`). `code` is a machine-readable detail and `param`
+ * names the offending request field, when there is one.
+ */
+export interface PlugError {
+  readonly status: number
+  readonly kind: PlugErrorKind
+  readonly message: string
+  readonly code?: string
+  readonly param?: string
+}
+
+/** The one discriminator for `PlugError` values returned in place of a result. */
+export const isPlugError = (value: unknown): value is PlugError =>
+  typeof value === "object" && value !== null && "status" in value && "kind" in value && "message" in value
+
+// ---------------------------------------------------------------- caller
+
+export interface CallContext {
+  /** App name (key name, or the default app). Decides the history directory. */
+  readonly app: string
+  /** Aborted on client disconnect or timeout. */
+  readonly signal: AbortSignal
+  /** Called once, before the first event, with the id of the history record this call writes (if any). */
+  readonly onRecord?: (recordID: string) => void
+}
+
+/** The seam between the core and a backend (the session backend now, `ctx.llm.stream` possibly later). */
+export interface ModelCaller {
+  stream(request: PlugRequest, context: CallContext): AsyncIterable<PlugEvent>
+}

package/src/http.ts

@@ -0,0 +1,324 @@
+/**
+ * HTTP ingress and transport helpers: request scope (disconnect abort and the one end-to-end
+ * deadline), body reading, header checks, JSON and SSE responses. Protocol-neutral: callers pass
+ * in already-encoded payloads, and checks return a `PlugError` for the caller to encode.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { isLoopbackHost, type PlugboardOptions } from "./config.js"
+import type { PlugError, PlugEvent } from "./contract.js"
+
+const MAX_BODY_BYTES = 32 * 1024 * 1024
+/** Largest delay `setTimeout` accepts; anything larger fires at once. */
+const MAX_TIMER_MS = 2 ** 31 - 1
+/** After answering a request whose body was not fully read, keep discarding it this long before cutting the socket. */
+const LINGER_MS = 5_000
+/** After the deadline passes, a response that has not finished flushing (a client that stopped reading) is destroyed after this long. */
+const DEADLINE_GRACE_MS = 2_000
+
+/** A request body that cannot be accepted: too large, or not JSON. `status` is the HTTP status to answer with. */
+export class BodyError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+/** 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") {
+    super(kind === "timeout" ? "Request deadline exceeded" : "Client disconnected")
+  }
+}
+
+/** Cancellation for one HTTP request: aborts on client disconnect and at the single end-to-end deadline. */
+export interface RequestScope {
+  readonly signal: AbortSignal
+  readonly timedOut: boolean
+  /** The `PlugError` to answer a timeout with. */
+  readonly timeoutError: PlugError
+  /** Settles like `promise`, or rejects with the abort reason (`RequestAborted`) as soon as the scope aborts. `promise` is always observed. */
+  race<T>(promise: Promise<T>): Promise<T>
+  /** Clears the deadline timer; call once the request is finished. */
+  dispose(): void
+}
+
+/**
+ * Establishes cancellation and the deadline. Call before the first `await` of a request: a socket
+ * that is already gone aborts immediately, so abandoned work never starts.
+ */
+export function beginRequest(request: IncomingMessage, response: ServerResponse, timeoutMs: number): RequestScope {
+  const controller = new AbortController()
+  const abort = (kind: RequestAborted["kind"]) => {
+    if (!controller.signal.aborted) controller.abort(new RequestAborted(kind))
+  }
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let graceTimer: ReturnType<typeof setTimeout> | undefined
+  const onDeadline = () => {
+    abort("timeout")
+    // The error response (or the rest of a stream) may never flush to a client that stopped reading: cut the transport.
+    // Cleared only once the socket is gone: on some runtimes the response reports finished/closed
+    // after `end()` while bytes are still queued for a client that stopped reading, so neither
+    // `writableFinished`, `writableLength` nor the response's `close` shows a flush. An idle
+    // connection cut here is harmless.
+    graceTimer = setTimeout(() => {
+      response.destroy()
+      request.socket?.destroy()
+    }, DEADLINE_GRACE_MS)
+    graceTimer.unref?.()
+  }
+  timer = setTimeout(onDeadline, Math.min(Math.max(timeoutMs, 1), MAX_TIMER_MS))
+  timer.unref?.()
+  const dispose = () => {
+    clearTimeout(timer)
+    timer = undefined
+  }
+  response.on("close", () => {
+    if (!response.writableFinished) abort("disconnected")
+    dispose()
+    if (request.socket?.destroyed) clearTimeout(graceTimer)
+  })
+  request.on("error", () => abort("disconnected"))
+  if (response.destroyed || request.destroyed || request.socket?.destroyed) abort("disconnected")
+
+  const { signal } = controller
+  const timedOut = () => signal.reason instanceof RequestAborted && signal.reason.kind === "timeout"
+  return {
+    signal,
+    get timedOut() {
+      return timedOut()
+    },
+    timeoutError: {
+      status: 504,
+      kind: "timeout",
+      code: "timeout",
+      message: `Request timed out after ${timeoutMs} ms (option requestTimeoutMs)`,
+    },
+    race<T>(promise: Promise<T>): Promise<T> {
+      promise.catch(() => {})
+      if (signal.aborted) return Promise.reject(signal.reason)
+      return new Promise<T>((resolve, reject) => {
+        const onAbort = () => reject(signal.reason)
+        signal.addEventListener("abort", onAbort, { once: true })
+        promise.then(
+          (value) => {
+            signal.removeEventListener("abort", onAbort)
+            resolve(value)
+          },
+          (error) => {
+            signal.removeEventListener("abort", onAbort)
+            reject(error)
+          },
+        )
+      })
+    },
+    dispose,
+  }
+}
+
+/**
+ * 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
+ * buffered, so the response can still be delivered (see `finishRequest`).
+ */
+export function readJsonBody(request: IncomingMessage, signal: AbortSignal): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const declared = Number(request.headers["content-length"])
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+      request.resume()
+      return reject(new BodyError(413, "Request body too large"))
+    }
+    if (signal.aborted) return reject(signal.reason)
+    const chunks: Buffer[] = []
+    let size = 0
+    const cleanup = () => {
+      request.off("data", onData)
+      request.off("error", onError)
+      request.off("end", onEnd)
+      signal.removeEventListener("abort", onAbort)
+    }
+    const stop = (error: unknown) => {
+      cleanup()
+      chunks.length = 0
+      request.resume()
+      reject(error)
+    }
+    const onData = (chunk: Buffer) => {
+      size += chunk.length
+      if (size > MAX_BODY_BYTES) return stop(new BodyError(413, "Request body too large"))
+      chunks.push(chunk)
+    }
+    const onError = (error: Error) => stop(error)
+    const onAbort = () => stop(signal.reason)
+    const onEnd = () => {
+      cleanup()
+      try {
+        resolve(chunks.length === 0 ? {} : JSON.parse(Buffer.concat(chunks).toString("utf8")))
+      } catch {
+        reject(new BodyError(400, "Request body is not valid JSON"))
+      }
+    }
+    request.on("data", onData)
+    request.on("error", onError)
+    request.on("end", onEnd)
+    signal.addEventListener("abort", onAbort, { once: true })
+  })
+}
+
+/**
+ * Call when a request is done. If the client is still sending a body that was not read, keep
+ * discarding it briefly so the response is not lost to a connection reset, then cut the socket.
+ */
+export function finishRequest(request: IncomingMessage, response: ServerResponse): void {
+  if (request.complete || request.destroyed) return
+  request.resume()
+  const timer = setTimeout(() => request.destroy(), LINGER_MS)
+  timer.unref?.()
+  response.once("close", () => clearTimeout(timer))
+}
+
+/** `close`: also tell the client to drop the connection (after an unread or abandoned body). */
+export const sendJson = (response: ServerResponse, status: number, payload: unknown, options?: { close?: boolean }) => {
+  if (response.headersSent || response.destroyed) return
+  const body = JSON.stringify(payload)
+  response.writeHead(status, {
+    "content-type": "application/json",
+    "content-length": Buffer.byteLength(body),
+    ...(options?.close ? { connection: "close" } : {}),
+  })
+  response.end(body)
+}
+
+/**
+ * SSE response writer. Headers go out with the first chunk, so nothing is committed until there
+ * is something to send; chunks after the client is gone are dropped. `write` is synchronous (the
+ * encoder's contract); backpressure is honoured by `paced`, which holds back the next event while
+ * the socket buffer is full. `signal` (the request scope's) ends those waits when it aborts.
+ */
+export function sseWriter(response: ServerResponse, signal?: AbortSignal) {
+  let started = false
+  let blocked = false
+  const waiters: Array<() => void> = []
+  const release = () => {
+    blocked = false
+    for (const resolve of waiters.splice(0)) resolve()
+  }
+  response.on("drain", release)
+  response.on("close", release)
+  const drained = (): Promise<void> => {
+    if (!blocked || response.destroyed || signal?.aborted) return Promise.resolve()
+    return new Promise((resolve) => {
+      const done = () => {
+        signal?.removeEventListener("abort", done)
+        const at = waiters.indexOf(done)
+        if (at >= 0) waiters.splice(at, 1)
+        resolve()
+      }
+      waiters.push(done)
+      signal?.addEventListener("abort", done, { once: true })
+    })
+  }
+  return {
+    get started() {
+      return started
+    },
+    write(chunk: string) {
+      if (response.destroyed || response.writableEnded) return
+      if (!started) {
+        started = true
+        response.writeHead(200, {
+          "content-type": "text/event-stream; charset=utf-8",
+          "cache-control": "no-cache, no-transform",
+          connection: "keep-alive",
+          "x-accel-buffering": "no",
+        })
+      }
+      if (!response.write(chunk)) blocked = true
+    },
+    /** Resolves when the socket buffer has room again, the client is gone, or the request scope aborted. */
+    drained,
+    /**
+     * Passes events through, waiting for `drain` before pulling each one, and stops when the client
+     * is gone. A scope abort ends the wait but not the stream: the next pull yields the timeout
+     * error (or ends), and the request deadline's grace timer cuts a socket that cannot take it.
+     */
+    async *paced(events: AsyncIterable<PlugEvent>): AsyncGenerator<PlugEvent> {
+      const iterator = events[Symbol.asyncIterator]()
+      try {
+        while (true) {
+          await drained()
+          if (response.destroyed) return
+          const next = await iterator.next()
+          if (next.done) return
+          yield next.value
+        }
+      } finally {
+        void iterator.return?.(undefined)?.catch?.(() => {})
+      }
+    },
+  }
+}
+
+/**
+ * Bound the event stream by the request scope. On timeout a 504 error event ends the stream; on
+ * disconnect the stream just ends. Either way the scope's abort already interrupted the caller.
+ */
+export async function* boundEvents(events: AsyncIterable<PlugEvent>, scope: RequestScope): AsyncGenerator<PlugEvent> {
+  const iterator = events[Symbol.asyncIterator]()
+  try {
+    while (true) {
+      let next: IteratorResult<PlugEvent>
+      try {
+        next = await scope.race(iterator.next())
+      } catch (error) {
+        if (!(error instanceof RequestAborted)) throw error
+        if (error.kind === "timeout") yield { type: "error", error: scope.timeoutError }
+        return
+      }
+      if (next.done) return
+      yield next.value
+    }
+  } finally {
+    // Not awaited: when the scope aborted, `next()` is still pending until the abort propagates.
+    void iterator.return?.(undefined)?.catch?.(() => {})
+  }
+}
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "[::1]"])
+
+/** Host header check against DNS rebinding: only meaningful when listening on loopback. */
+function hostAllowed(options: PlugboardOptions, hostHeader: string | undefined): boolean {
+  if (!isLoopbackHost(options.listen.host)) return true
+  const match = /^(\[[^\]]+\]|[^:]+)(?::(\d+))?$/.exec((hostHeader ?? "").trim().toLowerCase())
+  if (!match || !LOOPBACK_HOSTS.has(match[1]!)) return false
+  return (match[2] ?? "80") === String(options.listen.port)
+}
+
+/**
+ * Browser-reachable loopback endpoints: block DNS rebinding (Host header) and, on a keyless
+ * endpoint, cross-site calls (any Origin header).
+ */
+export function checkOrigin(request: IncomingMessage, options: PlugboardOptions): PlugError | undefined {
+  if (!hostAllowed(options, request.headers.host))
+    return { status: 403, kind: "permission", code: "invalid_host", message: "Host header not allowed" }
+  if (Object.keys(options.keys).length === 0 && request.headers.origin !== undefined)
+    return {
+      status: 403,
+      kind: "permission",
+      code: "cross_origin_forbidden",
+      message: "Cross-origin requests are not allowed on a keyless endpoint; configure `keys`",
+    }
+}
+
+export function checkJsonContentType(request: IncomingMessage): PlugError | undefined {
+  const contentType = request.headers["content-type"]?.split(";")[0]?.trim().toLowerCase()
+  if (contentType !== "application/json")
+    return {
+      status: 415,
+      kind: "invalid_request",
+      code: "unsupported_media_type",
+      message: "Content-Type must be application/json",
+    }
+}

package/src/log.ts

@@ -0,0 +1,28 @@
+/**
+ * Tiny structured logger: one line per event, `[opencode-plugboard] event key=value ...`.
+ *
+ * Callers pass only identifiers and outcomes (event name, request id, app, model, duration, an
+ * error message). Never pass API keys, request or response bodies, URLs or raw provider
+ * objects: nothing here redacts them.
+ */
+
+export type LogFields = Readonly<Record<string, string | number | boolean | undefined>>
+
+const PREFIX = "[opencode-plugboard]"
+
+function formatValue(value: string | number | boolean): string {
+  return typeof value === "string" && !/^[\w.:/#-]+$/.test(value) ? JSON.stringify(value) : String(value)
+}
+
+function format(event: string, fields: LogFields | undefined): string {
+  let line = `${PREFIX} ${event}`
+  for (const [key, value] of Object.entries(fields ?? {})) if (value !== undefined) line += ` ${key}=${formatValue(value)}`
+  return line
+}
+
+export const log = (event: string, fields?: LogFields): void => console.log(format(event, fields))
+
+export const logError = (event: string, fields?: LogFields): void => console.error(format(event, fields))
+
+/** The message of a thrown value, without its stack or attached properties. */
+export const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error))

package/src/models.ts

@@ -0,0 +1,100 @@
+/** Model refs and the allowlist/alias policy over a neutral catalog. Protocol-neutral: front-ends format the results. */
+
+import type { PlugboardOptions } from "./config.js"
+import type { CatalogModel, ModelRef, PlugError } from "./contract.js"
+
+/** `provider/model[#variant]`. The model id may contain slashes (`openrouter/vendor/model`). */
+function parseModelRef(s: string): ModelRef | undefined {
+  if (typeof s !== "string") return undefined
+  const slash = s.indexOf("/")
+  if (slash <= 0) return undefined
+  const hash = s.indexOf("#", slash + 1)
+  const id = s.slice(slash + 1, hash === -1 ? undefined : hash)
+  const variant = hash === -1 ? undefined : s.slice(hash + 1)
+  if (!id || s.slice(0, slash).includes("#")) return undefined
+  if (variant !== undefined && (!variant || variant.includes("#"))) return undefined
+  return { providerID: s.slice(0, slash), id, ...(variant ? { variant } : {}) }
+}
+
+function refToString(ref: ModelRef): string {
+  return `${ref.providerID}/${ref.id}${ref.variant ? `#${ref.variant}` : ""}`
+}
+
+/** `provider/*` any model of the provider; `provider/model` any variant; `provider/model#variant` exactly. */
+function allowed(options: PlugboardOptions, ref: ModelRef): boolean {
+  return options.models.some((pattern) => {
+    if (pattern.endsWith("/*")) return pattern.slice(0, -2) === ref.providerID
+    const p = parseModelRef(pattern)
+    return p !== undefined && p.providerID === ref.providerID && p.id === ref.id && (p.variant === undefined || p.variant === ref.variant)
+  })
+}
+
+function find(catalog: ReadonlyArray<CatalogModel>, ref: ModelRef): CatalogModel | undefined {
+  const model = catalog.find((m) => m.providerID === ref.providerID && m.id === ref.id)
+  return model && (ref.variant === undefined || model.variants.includes(ref.variant)) ? model : undefined
+}
+
+function own(map: Readonly<Record<string, string>>, key: string): string | undefined {
+  return Object.hasOwn(map, key) ? map[key] : undefined
+}
+
+/**
+ * Alias or `provider/model[#variant]` -> ModelRef. `reasoningEffort` picks the variant of that name when the
+ * ref has none and the model offers it. Errors: 403 when nothing is allowed, 404 for unknown/not-allowed models.
+ */
+export function resolveModel(
+  options: PlugboardOptions,
+  model: string,
+  catalog: ReadonlyArray<CatalogModel>,
+  reasoningEffort?: string,
+): ModelRef | PlugError {
+  if (options.models.length === 0)
+    return {
+      status: 403,
+      message: "No models are allowed: set the plugboard `models` option",
+      kind: "permission",
+      code: "no_models_configured",
+    }
+  const notAvailable: PlugError = {
+    status: 404,
+    message: `Model ${model} is not available`,
+    kind: "not_found",
+    code: "model_not_found",
+    param: "model",
+  }
+  let ref = parseModelRef(own(options.aliases, model) ?? model)
+  if (!ref) return notAvailable
+  if (!ref.variant && reasoningEffort && find(catalog, { ...ref, variant: reasoningEffort }))
+    ref = { ...ref, variant: reasoningEffort }
+  return allowed(options, ref) && find(catalog, ref) ? ref : notAvailable
+}
+
+/** One servable model id: a catalog id (`provider/model[#variant]`) or an alias, with the catalog model behind it. */
+export interface ListedModel {
+  readonly id: string
+  readonly ref: ModelRef
+  readonly model: CatalogModel
+}
+
+/** The allowlist intersected with the catalog, plus aliases whose target qualifies. Ids are unique except an alias may repeat one. */
+export function listAvailableModels(options: PlugboardOptions, catalog: ReadonlyArray<CatalogModel>): ListedModel[] {
+  const entry = (id: string, ref: ModelRef, model: CatalogModel): ListedModel => ({ id, ref, model })
+  const data: ListedModel[] = []
+  // The catalog can list a model more than once (and repeat variants); ids must be unique.
+  const seen = new Set<string>()
+  for (const model of catalog) {
+    const base = { providerID: model.providerID, id: model.id }
+    for (const ref of [base, ...model.variants.map((variant) => ({ ...base, variant }))]) {
+      const id = refToString(ref)
+      if (seen.has(id) || !allowed(options, ref)) continue
+      seen.add(id)
+      data.push(entry(id, ref, model))
+    }
+  }
+  for (const [alias, target] of Object.entries(options.aliases)) {
+    const ref = parseModelRef(target)
+    const model = ref && allowed(options, ref) ? find(catalog, ref) : undefined
+    if (ref && model) data.push(entry(alias, ref, model))
+  }
+  return data
+}