opencode-plugboard 0.5.0 → 0.7.0

package/src/anthropic/route.ts

@@ -0,0 +1,148 @@
+/**
+ * `POST /v1/messages` (and a clear 404 for `POST /v1/messages/count_tokens`): the Anthropic
+ * Messages front-end's half of the route. `src/openai/route.ts` hands every request for these
+ * paths over before it does anything else, because this route differs from the OpenAI ones in
+ * three ways: errors use Anthropic's body shape from the first check on, `x-api-key` authenticates
+ * as well as `Authorization: Bearer`, and there is no `[DONE]`.
+ *
+ * Same flow as the other front-ends: origin check, authenticate, 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.
+ * `anthropic-version` and `anthropic-beta` are accepted and ignored.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { authenticate } from "../config.js"
+import { isPlugError, type PlugError, type PlugRequest } from "../contract.js"
+import {
+  BodyError,
+  RequestAborted,
+  boundEvents,
+  checkJsonContentType,
+  checkOrigin,
+  readJsonBody,
+  sendJson,
+  sseWriter,
+  type RequestScope,
+} from "../http.js"
+import { resolveModel } from "../models.js"
+import { dropRejected } from "../openai/sampling.js"
+import type { RouteHost } from "../openai/route.js"
+import { parseMessagesRequest } from "./request.js"
+import { encodeError, runMessage, sseFrame } from "./response.js"
+
+const SESSION_HEADER = "x-plugboard-session"
+const DROPPED_HEADER = "x-plugboard-dropped-params"
+const MESSAGES = "/v1/messages"
+const COUNT_TOKENS = "/v1/messages/count_tokens"
+
+/** Paths this front-end owns, whatever the method. */
+export const isMessagesPath = (path: string) => path === MESSAGES || path === COUNT_TOKENS
+
+export interface MessagesCall {
+  readonly path: string
+  readonly request: IncomingMessage
+  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: { route: string; app?: string; model?: string; failed?: string; dropped?: string }
+}
+
+const header = (request: IncomingMessage, name: string): string | undefined => {
+  const value = request.headers[name]
+  return (Array.isArray(value) ? value[0] : value)?.trim() || 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 bearer = authenticate(host.options, request.headers.authorization)
+  const apiKey = header(request, "x-api-key")
+  return isPlugError(bearer) && apiKey ? authenticate(host.options, `Bearer ${apiKey}`) : bearer
+}
+
+export async function serveMessages(host: RouteHost, call: MessagesCall): Promise<void> {
+  const { path, request, response, scope, info } = call
+  const fail = (error: PlugError, close = false) => sendJson(response, error.status, encodeError(error), { close })
+  if (request.method === "POST") info.route = `POST ${path}`
+  response.setHeader("request-id", `req_${crypto.randomUUID().replaceAll("-", "")}`)
+
+  try {
+    await serve()
+  } catch (caught) {
+    // 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)
+      else if (caught instanceof RequestAborted) {
+        if (caught.kind === "timeout") fail(scope.timeoutError, true)
+      } else fail({ status: 500, kind: "server", message: "Internal server error" })
+    }
+    throw caught
+  }
+
+  async function serve(): Promise<void> {
+    if (request.method !== "POST")
+      return fail({ status: 405, kind: "invalid_request", code: "method_not_allowed", message: `Method ${request.method} is not allowed for ${path}; use POST` })
+    const rejected = checkOrigin(request, host.options)
+    if (rejected) return fail(rejected)
+    const auth = authenticateRequest(host, request)
+    if (isPlugError(auth)) return fail(auth)
+    info.app = auth.app
+    if (path === COUNT_TOKENS)
+      return fail({ status: 404, kind: "not_found", code: "not_found", message: "count_tokens is not supported by plugboard" })
+    const unsupported = checkJsonContentType(request)
+    if (unsupported) return fail(unsupported)
+
+    const body = await readJsonBody(request, scope.signal)
+    const parsed = parseMessagesRequest(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}` : ""}`
+    // Sampling parameters the model is known to reject are dropped; `top_k` has no neutral
+    // equivalent and is always dropped. Both are reported before any response bytes.
+    const sampled = host.options.dropUnsupportedParams ? dropRejected(ref, parsed.request.generation) : undefined
+    const dropped = [...(sampled?.dropped ?? []), ...(parsed.topKIgnored ? ["top_k"] : [])]
+    if (dropped.length > 0) {
+      info.dropped = dropped.join(",")
+      response.setHeader(DROPPED_HEADER, info.dropped)
+    }
+    const model: PlugRequest = { ...parsed.request, ...(sampled ? { generation: sampled.generation } : {}), 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(model, {
+        app: auth.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, started } = await runMessage(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
+          // Committed by a keepalive before the encoder wrote anything: the encoder left the error for us.
+          if (!started && !response.writableEnded) sse.write(sseFrame(encodeError(failure)))
+        }
+        if (!response.writableEnded) response.end()
+      }
+      return
+    }
+
+    const run = await runMessage(events, exchange, () => {})
+    if (run.failure || !run.message) return fail(run.failure ?? { status: 502, kind: "server", message: "No response from the model" })
+    sendJson(response, 200, run.message)
+  }
+}

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 { parseAllowEntry, type RemoteImages } from "./session/media.js"
 import type { HistoryLimits } from "./session/prune.js"
 
 /** Plugin options, after defaults and validation (see `parseOptions`). */
@@ -14,8 +15,13 @@ export interface PlugboardOptions {
   readonly aliases: Readonly<Record<string, string>>
   readonly maxTools: number
   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
+  /**
+   * Fetch http(s) image URLs server-side. Off by default: it is an SSRF vector into the host's network.
+   * `true` fetches public addresses only (loopback, private, link-local, CGNAT and ULA ranges are refused);
+   * `{ allow }` is on too, and lists the hosts (`name`, `*.suffix`), addresses or CIDR ranges that may be
+   * fetched even when they are not public.
+   */
+  readonly remoteImages: RemoteImages
   /** 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
   /** Drop sampling parameters the target model is known to reject (reported in `x-plugboard-dropped-params`). On by default; off forwards them as sent. */
@@ -68,6 +74,23 @@ function positiveInt(value: unknown, name: string, fallback: number, max = Numbe
   return value
 }
 
+const REMOTE_IMAGES_ERROR =
+  "plugboard option `remoteImages` must be a boolean or `{ allow: [...] }` with host names, IP addresses or CIDR ranges that may be fetched even when they are not public"
+
+function parseRemoteImages(value: unknown): RemoteImages {
+  if (value === undefined) return false
+  if (typeof value === "boolean") return value
+  if (!isRecord(value)) throw new Error(REMOTE_IMAGES_ERROR)
+  for (const key of Object.keys(value))
+    if (key !== "allow") throw new Error(`Unknown plugboard option \`remoteImages.${key}\` (known: allow)`)
+  const allow = value.allow ?? []
+  if (!Array.isArray(allow)) throw new Error(REMOTE_IMAGES_ERROR)
+  for (const entry of allow)
+    if (typeof entry !== "string" || parseAllowEntry(entry) === undefined)
+      throw new Error(`plugboard \`remoteImages.allow\` entry \`${String(entry)}\` must be a host name (\`images.internal\`, \`*.internal\`), an IP address or a CIDR range`)
+  return { allow: allow as string[] }
+}
+
 /** Validates raw plugin options and applies defaults. Throws `Error` with an actionable message. */
 export function parseOptions(raw: unknown): PlugboardOptions {
   if (raw !== undefined && raw !== null && !isRecord(raw)) throw new Error("plugboard options must be an object")
@@ -122,8 +145,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
   }
   const aliases: Record<string, string> = Object.fromEntries(aliasEntries)
 
-  if (input.remoteImages !== undefined && typeof input.remoteImages !== "boolean")
-    throw new Error("plugboard option `remoteImages` must be a boolean")
+  const remoteImages = parseRemoteImages(input.remoteImages)
   if (input.dropUnsupportedParams !== undefined && typeof input.dropUnsupportedParams !== "boolean")
     throw new Error("plugboard option `dropUnsupportedParams` must be a boolean")
 
@@ -145,7 +167,7 @@ export function parseOptions(raw: unknown): PlugboardOptions {
     aliases,
     maxTools: positiveInt(input.maxTools, "maxTools", DEFAULTS.maxTools, 1024),
     requestTimeoutMs: positiveInt(input.requestTimeoutMs, "requestTimeoutMs", DEFAULTS.requestTimeoutMs, MAX_TIMER_MS),
-    remoteImages: input.remoteImages === true,
+    remoteImages,
     history: { ...(maxSessions === undefined ? {} : { maxSessions }), ...(maxAgeDays === undefined ? {} : { maxAgeDays }) },
     dropUnsupportedParams: input.dropUnsupportedParams !== false,
     logFormat: input.logFormat === "json" ? "json" : "text",

package/src/openai/route.ts

@@ -38,6 +38,7 @@ import {
 import { errorMessage, log, logError, withRequestId } from "../log.js"
 import { NO_APP, outcomeLabel, type Metrics } from "../metrics.js"
 import { listAvailableModels, resolveModel } from "../models.js"
+import { isMessagesPath, serveMessages } from "../anthropic/route.js"
 import { serveResponses } from "../responses/route.js"
 import { processMetrics, processStatus, type RuntimeStatus } from "../runtime.js"
 import { parseChatRequest } from "./request.js"
@@ -135,6 +136,8 @@ export function createOpenAiRoute(routeHost: RouteHost) {
     const route = `${request.method} ${modelId !== undefined ? "/v1/models/{id}" : path}`
     // Arbitrary client paths stay out of the log.
     info.route = modelId !== undefined || known(route) || route === "GET /healthz" ? route : "unknown"
+    // Anthropic Messages: its own error shape and x-api-key auth, so it takes the request from here.
+    if (isMessagesPath(path)) return serveMessages(host, { path, request, response, scope, info })
 
     const rejected = checkOrigin(request, host.options)
     if (rejected) return fail(response, rejected)
@@ -157,6 +160,11 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       return sendText(response, 200, "text/html; charset=utf-8", renderDiscoveryHtml(doc), PAGE_HEADERS)
     }
 
+    // Authenticate before anything reveals which routes exist: an unauthenticated caller sees 401 for every path but /healthz and the first-run pages.
+    const auth = authenticate(host.options, request.headers.authorization)
+    if (isPlugError(auth)) return fail(response, auth)
+    info.app = auth.app
+
     if (modelId === undefined && !known(route)) {
       return fail(response, {
         status: 404,
@@ -166,10 +174,6 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       })
     }
 
-    const auth = authenticate(host.options, request.headers.authorization)
-    if (isPlugError(auth)) return fail(response, auth)
-    info.app = auth.app
-
     if (route === "GET /v1/status") {
       const catalog = await optionalCatalog(scope)
       return sendJson(response, 200, buildStatus({ options: host.options, app: auth.app, runtime: runtimeStatus(), catalog }))

package/src/runtime.ts

@@ -100,8 +100,12 @@ const SWEEP_DEADLINE_MS = 60_000
 const BACKEND_TIMEOUT_MS = 15_000
 const BACKEND_POLL_MS = 25
 
-/** 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
-const VERSION = 5
+/** How often a listener that could not bind tries again, and how often it repeats the error while it still cannot (#87). */
+const BIND_RETRY_MS = 15_000
+const BIND_REMINDER_MS = 5 * 60_000
+
+/** 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
+const VERSION = 6
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -111,6 +115,11 @@ interface Listener {
   fingerprint: string
   mismatchLogged: boolean
   bound: boolean
+  /** Failed bind attempts since the last success: while this is above 0 nothing receives requests on the port. */
+  bindFailures: number
+  /** When the bind failure was last logged (epoch ms). */
+  bindLoggedAt: number
+  retryTimer?: ReturnType<typeof setTimeout>
   graceTimer?: ReturnType<typeof setTimeout>
 }
 
@@ -312,7 +321,7 @@ const unavailable = (response: ServerResponse, message: string) => {
 }
 
 function startListener(rt: Runtime, listen: { host: string; port: number }, fingerprint: string): Listener {
-  const listener: Listener = { server: createServer(), listen, fingerprint, mismatchLogged: false, bound: false }
+  const listener: Listener = { server: createServer(), listen, fingerprint, mismatchLogged: false, bound: false, bindFailures: 0, bindLoggedAt: 0 }
   listener.server.on("request", (request, response) => {
     const current = preferred(rt)
     if (!current) return unavailable(response, "plugboard is reloading")
@@ -325,22 +334,39 @@ function startListener(rt: Runtime, listen: { host: string; port: number }, fing
   })
   listener.server.on("error", (error: NodeJS.ErrnoException) => {
     if (listener.bound) return logError("listener.error", { code: error.code, error: error.message })
-    // Never bound: another process (or an older runtime) owns the port. Log once, stay inert.
-    logError(error.code === "EADDRINUSE" ? "listener.address_in_use" : "listener.failed", {
-      listen: `${listen.host}:${listen.port}`,
-      error: error.message,
-    })
+    // Not bound: another process (or an older runtime) owns the port, so nothing here receives
+    // requests while clients may be sending their keys and prompts to whoever holds it. Say so
+    // loudly (error level, again every few minutes), keep trying, and mention it on every
+    // generation that registers meanwhile (`registerGeneration`).
+    listener.bindFailures++
+    if (Date.now() - listener.bindLoggedAt >= BIND_REMINDER_MS) {
+      listener.bindLoggedAt = Date.now()
+      logError(error.code === "EADDRINUSE" ? "listener.address_in_use" : "listener.failed", {
+        listen: `${listen.host}:${listen.port}`,
+        error: error.message,
+        status: "not serving: clients of this port reach another process",
+        action: "stop the process that holds the port or change `listen`; plugboard retries every 15s",
+      })
+    }
+    listener.retryTimer = setTimeout(() => {
+      listener.retryTimer = undefined
+      if (rt.listener === listener && !listener.bound) listener.server.listen(listen.port, listen.host)
+    }, BIND_RETRY_MS)
+    listener.retryTimer.unref?.()
   })
-  listener.server.listen(listen.port, listen.host, () => {
+  listener.server.on("listening", () => {
     listener.bound = true
-    log("listener.listening", { listen: `${listen.host}:${listen.port}` })
+    log("listener.listening", { listen: `${listen.host}:${listen.port}`, ...(listener.bindFailures > 0 ? { recoveredAfterFailedBinds: listener.bindFailures } : {}) })
+    listener.bindFailures = 0
   })
+  listener.server.listen(listen.port, listen.host)
   return listener
 }
 
 function closeListener(rt: Runtime, listener: Listener): void {
   if (rt.listener !== listener) return
   rt.listener = undefined
+  clearTimeout(listener.retryTimer)
   try {
     rt.pump?.stop()
   } catch {}
@@ -404,6 +430,13 @@ export function registerGeneration(input: GenerationInput): Registration {
   }
   if (listener.graceTimer) clearTimeout(listener.graceTimer)
   listener.graceTimer = undefined
+  if (listener.bindFailures > 0) {
+    logError("listener.not_serving", {
+      listen: `${listen.host}:${listen.port}`,
+      status: "another process holds the port; this generation serves nothing",
+      action: "stop that process or change `listen`",
+    })
+  }
   const generation: Generation = {
     directory,
     handler: input.handler,

package/src/session/caller.ts

@@ -23,7 +23,7 @@ import { log, logError } from "../log.js"
 import { RequestCollector } from "./events.js"
 import { ensureAppDir, makeTitle, renderTranscript } from "./history.js"
 import { describeError, type SessionPort } from "./host.js"
-import { ImageError, prepareImages } from "./media.js"
+import { ImageError, prepareImages, type RemoteImages } from "./media.js"
 import { REQUEST_PERMISSIONS, seedToolsFor } from "./seeds.js"
 import type { SessionStore } from "./state.js"
 
@@ -33,8 +33,8 @@ export interface SessionCallerDeps {
   readonly sessions: SessionStore
   /** The seed pool size of the app directories (option `maxTools`); a request needing more tools fails before dispatch. */
   readonly maxTools: number
-  /** Allow fetching http(s) image URLs (option `remoteImages`). */
-  readonly remoteImages?: boolean
+  /** Allow fetching http(s) image URLs (option `remoteImages`: off, public addresses only, or with an allowlist). */
+  readonly remoteImages?: RemoteImages
   /**
    * Make sure the backend of `app` can run request sessions (the app directory's plugin is loaded),
    * called right before `session.create`. An error ends the request without creating anything.
@@ -85,7 +85,7 @@ function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
 
 export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
   const { port, sessions, maxTools, ensureBackend } = deps
-  const remoteImages = deps.remoteImages === true
+  const remoteImages = deps.remoteImages ?? false
 
   return {
     async *stream(request: PlugRequest, context: CallContext): AsyncGenerator<PlugEvent> {
@@ -134,7 +134,7 @@ export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
         if (unavailable) return yield note({ type: "error", error: unavailable })
         if (context.signal.aborted) return
 
-        collector = new RequestCollector({ stopTurn: interrupt })
+        collector = new RequestCollector({ stopTurn: interrupt, requestID })
         const created = await raceAbort(port.create({
           directory,
           model: { providerID: request.ref.providerID, id: request.ref.id, ...(request.ref.variant ? { variant: request.ref.variant } : {}) },

package/src/session/events.ts

@@ -12,6 +12,7 @@
  */
 
 import { isPlugError, type PlugError, type PlugEvent, type PlugFinish, type PlugUsage } from "../contract.js"
+import { logError } from "../log.js"
 import type { BusEvent } from "./host.js"
 import { FAILURE_EVENT } from "./state.js"
 
@@ -116,6 +117,8 @@ interface RawError {
   readonly type?: string
   readonly message?: string
   readonly status?: number
+  /** Raw provider response. Read for classification and the log only; never copied to the caller. */
+  readonly response?: { readonly body?: string }
 }
 
 const total = (...parts: Array<number | undefined>): number | undefined =>
@@ -138,23 +141,56 @@ const toUsage = (tokens?: RawUsage): PlugUsage | undefined =>
       }
     : undefined
 
-/** Host `SessionError` (`{ type, message, status?, response? }`) to a `PlugError`. */
+/** Provider wording for "the prompt does not fit the model" (a subset of the host's own matcher; the host does not forward its classification). */
+const CONTEXT_OVERFLOW =
+  /context[_ ](?:length|window)|maximum context|prompt (?:is )?too long|too many tokens|token limit|input length.*exceeds|exceeds the (?:available )?context|reduce the length of the messages/i
+
+/**
+ * Host `SessionError` (`{ type, message, status?, response? }`) to a `PlugError`. Provider and host
+ * error text can carry endpoints, account or organization ids, so it never reaches the caller:
+ * the caller gets a stable `code` and a fixed message per class. The classes a caller can act on
+ * stay distinct (rate limit, quota, context length, provider credentials, timeout, content filter).
+ * The raw text goes to the log only (`RequestCollector.failFromHost`).
+ */
 function toPlugError(error: RawError | undefined, fallback: string): PlugError {
   const status = typeof error?.status === "number" && error.status >= 400 ? error.status : undefined
-  const message = error?.message || fallback
-  const base = { message, ...(error?.type ? { code: error.type } : {}) }
-  if (status === 401) return { status, kind: "authentication", ...base }
-  if (status === 403) return { status, kind: "permission", ...base }
-  if (status === 404) return { status, kind: "not_found", ...base }
-  if (status === 429) return { status, kind: "rate_limit", ...base }
-  if (status === 408 || status === 504) return { status, kind: "timeout", ...base }
-  if (status !== undefined && status < 500) return { status, kind: "invalid_request", ...base }
-  return { status: status ?? 502, kind: "server", ...base }
+  const type = error?.type ?? ""
+  // Our own constant (the session caller reports a prompt that could not start); the host never uses this type.
+  if (type === "prompt_failed") return { status: 502, kind: "server", code: "prompt_failed", message: error?.message || fallback }
+  if (type === "provider.rate-limit" || status === 429) {
+    return { status: 429, kind: "rate_limit", code: "rate_limited", message: "The model provider is rate limiting requests; retry later" }
+  }
+  if (type === "provider.quota") {
+    return { status: 429, kind: "rate_limit", code: "quota_exceeded", message: "The model provider's usage quota is exhausted" }
+  }
+  if ((type === "provider.invalid-request" || status === 400 || status === 413) && CONTEXT_OVERFLOW.test(`${error?.message ?? ""}\n${error?.response?.body ?? ""}`)) {
+    return { status: 400, kind: "invalid_request", code: "context_length_exceeded", param: "messages", message: "The request is longer than the model's context window" }
+  }
+  if (type === "provider.auth" || status === 401 || status === 403) {
+    const message = "The model provider rejected its credentials; the plugboard host needs to sign in again"
+    if (status === 401) return { status, kind: "authentication", code: "provider_auth_failed", message }
+    if (status === 403) return { status, kind: "permission", code: "provider_auth_failed", message }
+    return { status: 502, kind: "server", code: "provider_auth_failed", message }
+  }
+  if (type === "provider.content-filter") {
+    return { status: 400, kind: "invalid_request", code: "content_filter", message: "The model provider's content filter blocked the request" }
+  }
+  if (type === "provider.timeout" || status === 408 || status === 504) {
+    return { status: 504, kind: "timeout", code: "provider_timeout", message: "The model provider timed out" }
+  }
+  if (type.startsWith("provider.")) {
+    if (status === 404) return { status, kind: "not_found", code: "provider_rejected_request", message: "The model provider rejected the request" }
+    if (status !== undefined && status < 500) return { status, kind: "invalid_request", code: "provider_rejected_request", message: "The model provider rejected the request" }
+    return { status: status ?? 502, kind: "server", code: "provider_unavailable", message: "The model provider is unavailable or returned an error" }
+  }
+  return { status: 502, kind: "server", code: "model_run_failed", message: fallback }
 }
 
 export interface CollectorHooks {
   /** The step ended with tool calls: stop the turn before the runner starts another model step. */
   readonly stopTurn: () => void
+  /** The request's id, for the log line that carries a failure's raw host text. */
+  readonly requestID?: string
 }
 
 export class RequestCollector {
@@ -268,11 +304,11 @@ export class RequestCollector {
         if (this.calls.size > 0 && error?.type === "aborted") return this.finishWith("tool-calls")
         if (item.finish === "content-filter") return this.finishWith("content-filter")
         if (error?.type === "aborted" && this.wasCancelled) return this.end()
-        return this.fail(toPlugError(error, "Model step failed"))
+        return this.failFromHost(error, "Model step failed")
       }
       case "session.execution.failed":
         this.executionDone = true
-        if (!this.finished) this.fail(toPlugError(item.error as RawError | undefined, "Session execution failed"))
+        if (!this.finished) this.failFromHost(item.error as RawError | undefined, "Session execution failed")
         this.end()
         return
       case "session.execution.interrupted":
@@ -310,6 +346,18 @@ export class RequestCollector {
     this.end()
   }
 
+  /** Fail with the caller-safe mapping of a host error; the raw text is logged here and goes nowhere else. */
+  private failFromHost(raw: RawError | undefined, fallback: string): void {
+    if (this.finished) return
+    logError("model.failed", {
+      requestID: this.hooks.requestID,
+      type: raw?.type,
+      status: raw?.status,
+      message: raw?.message?.slice(0, 500),
+    })
+    this.fail(toPlugError(raw, fallback))
+  }
+
   private fail(error: PlugError): void {
     if (this.finished) return
     this.emit({ type: "error", error })

package/src/session/history.ts

@@ -50,9 +50,20 @@ const firstUserText = (request: PlugRequest): string => {
   return request.model
 }
 
-/** Session title: the first user text, whitespace-collapsed and cut to 60 characters. */
+/**
+ * Control characters that terminal and app UIs act on: C0 (ESC, BEL, CR, ...), DEL, C1 (8-bit CSI),
+ * and the bidirectional marks and overrides (ALM, LRM, RLM, U+202A-202E, U+2066-2069) that reorder text.
+ * `\t` and `\n` are included here; callers that keep layout use `LAYOUT_SAFE`.
+ */
+const CONTROLS = /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g
+const CONTROLS_KEEP_LAYOUT = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g
+
+/** One display line: whitespace (including line breaks) collapsed to single spaces, then control and bidi characters removed. */
+export const oneLine = (text: string): string => text.replace(/\s+/g, " ").replace(CONTROLS, "").trim()
+
+/** Session title: the first user text, one line, control and bidi characters removed, cut to 60 characters. */
 export const makeTitle = (request: PlugRequest): string => {
-  const flat = firstUserText(request).replace(/\s+/g, " ").trim()
+  const flat = oneLine(firstUserText(request))
   return flat.length > TITLE_LENGTH ? flat.slice(0, TITLE_LENGTH - 1) + "…" : flat
 }
 
@@ -74,16 +85,17 @@ export function renderTranscript(request: PlugRequest): string {
           lines.push(`[image ${++image}]`)
           break
         case "tool-call":
-          lines.push(`[tool call ${part.name} (${part.id})] ${typeof part.input === "string" ? part.input : JSON.stringify(part.input)}`)
+          lines.push(`[tool call ${oneLine(part.name)} (${oneLine(part.id)})] ${typeof part.input === "string" ? part.input : JSON.stringify(part.input)}`)
           break
         case "tool-result":
-          lines.push(`[tool result ${part.name} (${part.id})${part.isError ? " (error)" : ""}] ${part.result}`)
+          lines.push(`[tool result ${oneLine(part.name)} (${oneLine(part.id)})${part.isError ? " (error)" : ""}] ${part.result}`)
           break
       }
     }
     lines.push("")
   }
-  if (request.tools.length > 0) lines.push("## tools", request.tools.map((tool) => tool.name).join(", "), "")
-  const text = lines.join("\n").trim()
+  if (request.tools.length > 0) lines.push("## tools", request.tools.map((tool) => oneLine(tool.name)).join(", "), "")
+  // The stored text is display only (the model sees the structured request): body text keeps its line breaks and tabs, nothing else that a UI would act on.
+  const text = lines.join("\n").replace(CONTROLS_KEEP_LAYOUT, "").trim()
   return text.length > 0 ? text : "(empty request)"
 }