opencode-plugboard 0.4.1 → 0.6.0

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)"
 }

package/src/session/host.ts

@@ -12,7 +12,7 @@
 import type { Plugin } from "@opencode/plugin/effect"
 import type { SessionContext } from "@opencode/plugin/effect/session"
 import { Effect } from "effect"
-import type { CatalogModel } from "../contract.js"
+import type { CatalogCost, CatalogModel } from "../contract.js"
 
 export type HostContext = Plugin.Context
 
@@ -132,9 +132,39 @@ export function createHistoryPort(ctx: HostContext): HistoryPort {
 const record = (value: unknown): Record<string, unknown> | undefined =>
   typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined
 
+const finite = (value: unknown): number | undefined => (typeof value === "number" && Number.isFinite(value) ? value : undefined)
+const strings = (value: unknown): string[] | undefined =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : undefined
+const STATUSES = new Set(["alpha", "beta", "deprecated", "active"])
+
+/** Host `Model.Cost[]` (USD per million tokens, optional context tier) -> neutral price entries; malformed entries are skipped. */
+function toCosts(raw: unknown): CatalogCost[] | undefined {
+  if (!Array.isArray(raw)) return undefined
+  const costs: CatalogCost[] = []
+  for (const item of raw) {
+    const cost = record(item)
+    const input = finite(cost?.input)
+    const output = finite(cost?.output)
+    if (!cost || input === undefined || output === undefined) continue
+    const cache = record(cost.cache)
+    const tier = record(cost.tier)
+    const size = tier?.type === "context" ? finite(tier.size) : undefined
+    costs.push({
+      input,
+      output,
+      cacheRead: finite(cache?.read) ?? 0,
+      cacheWrite: finite(cache?.write) ?? 0,
+      ...(size === undefined ? {} : { aboveContext: size }),
+    })
+  }
+  return costs
+}
+
 /**
  * Reduces `ctx.model.list` data (V2 `Model.Info`, tolerant of missing fields) to the catalog.
  * Models with `enabled: false` are dropped; `modelID` wins over `id`; variants may be `{ id }` or strings.
+ * Cost, limits, modalities, status, family and release date are carried as the host reports them
+ * (`Model.Info`, packages/schema/src/model.ts); anything absent or malformed is left out.
  */
 function toCatalog(raw: ReadonlyArray<unknown>): CatalogModel[] {
   const catalog: CatalogModel[] = []
@@ -149,7 +179,13 @@ function toCatalog(raw: ReadonlyArray<unknown>): CatalogModel[] {
       .filter((v): v is string => typeof v === "string" && v.length > 0)
     const caps = record(model.capabilities)
     const input = caps && Array.isArray(caps.input) ? caps.input : undefined
-    const context = record(model.limit)?.context
+    const limit = record(model.limit)
+    const context = limit?.context
+    const limits = { context: finite(limit?.context), input: finite(limit?.input), output: finite(limit?.output) }
+    const modalityIn = strings(caps?.input)
+    const modalityOut = strings(caps?.output)
+    const cost = toCosts(model.cost)
+    const released = finite(record(model.time)?.released)
     catalog.push({
       providerID,
       id,
@@ -164,6 +200,14 @@ function toCatalog(raw: ReadonlyArray<unknown>): CatalogModel[] {
           }
         : {}),
       ...(typeof context === "number" ? { contextLimit: context } : {}),
+      ...(limits.context !== undefined || limits.input !== undefined || limits.output !== undefined
+        ? { limits: Object.fromEntries(Object.entries(limits).filter(([, value]) => value !== undefined)) }
+        : {}),
+      ...(modalityIn || modalityOut ? { modalities: { input: modalityIn ?? [], output: modalityOut ?? [] } } : {}),
+      ...(cost && cost.length > 0 ? { cost } : {}),
+      ...(typeof model.status === "string" && STATUSES.has(model.status) ? { status: model.status as NonNullable<CatalogModel["status"]> } : {}),
+      ...(typeof model.family === "string" && model.family ? { family: model.family } : {}),
+      ...(released !== undefined ? { released } : {}),
     })
   }
   return catalog

package/src/session/media.ts

@@ -4,20 +4,39 @@
  * Prompt files must be inline `data:` URLs. http(s) images are fetched once, only when the
  * `remoteImages` option is on, with no redirects, a 20 s timeout and a 20 MB cap. All images of
  * one request together may hold at most 50 MB (`images_too_large`), data URLs and fetched ones alike.
+ *
+ * A remote fetch is a request the server makes on a caller's behalf, so it must not reach the
+ * server's own network (#84): the host is resolved first, every address it resolves to must be a
+ * public one (loopback, private, link-local, CGNAT, ULA, multicast, reserved and mapped or
+ * translated forms of those are refused) unless the operator's `remoteImages.allow` list names the
+ * host or the address, and the request then connects to the address that was checked, not to the
+ * name, so a second DNS answer cannot redirect it (DNS rebinding). The caller sees one generic
+ * error for every fetch failure, whatever the cause.
  */
 
+import { lookup } from "node:dns/promises"
+import { request as httpRequest, type IncomingMessage } from "node:http"
+import { request as httpsRequest } from "node:https"
+import { isIP } from "node:net"
 import type { PlugRequest } from "../contract.js"
+import { log } from "../log.js"
 
 const MAX_REMOTE_IMAGE_BYTES = 20 * 1024 * 1024
 /** Aggregate size of the prepared data URLs of one request. */
 const MAX_TOTAL_IMAGE_BYTES = 50 * 1024 * 1024
+const FETCH_TIMEOUT_MS = 20_000
 const TOO_MANY = () => new ImageError("images_too_large", "The request's images are larger than 50 MB in total")
+/** The one message for every failed fetch (blocked address, DNS, refused, timeout, bad status): no oracle for the server's network. */
+const FETCH_FAILED = () => new ImageError("image_fetch_failed", "Could not fetch image")
 
 /** What one request's images may still use, in data URL characters (== bytes held). */
 interface Budget {
   remaining: number
 }
 
+/** The `remoteImages` option as the session caller receives it: off, on (public addresses only), or on with an allowlist. */
+export type RemoteImages = boolean | { readonly allow: ReadonlyArray<string> }
+
 /** A caller image that cannot be used; `code` becomes the error code of the 400 response. */
 export class ImageError extends Error {
   constructor(
@@ -28,41 +47,255 @@ export class ImageError extends Error {
   }
 }
 
-async function toDataUrl(url: string, signal: AbortSignal, remoteImages: boolean, budget: Budget): Promise<string> {
+// ---- addresses
+
+interface Ip {
+  readonly family: 4 | 6
+  readonly bytes: ReadonlyArray<number>
+}
+
+/** Dotted IPv4 or any IPv6 text form (compressed, with an embedded IPv4 tail, with a zone) to bytes. */
+function parseIp(text: string): Ip | undefined {
+  const family = isIP(text)
+  if (family === 4) return { family, bytes: text.split(".").map(Number) }
+  if (family !== 6) return undefined
+  let head = text.split("%")[0]!
+  const dot = head.lastIndexOf(".")
+  if (dot !== -1) {
+    const colon = head.lastIndexOf(":")
+    const v4 = head.slice(colon + 1).split(".").map(Number)
+    head = `${head.slice(0, colon + 1)}${((v4[0]! << 8) | v4[1]!).toString(16)}:${((v4[2]! << 8) | v4[3]!).toString(16)}`
+  }
+  const [left = "", right = ""] = head.split("::")
+  const first = left === "" ? [] : left.split(":")
+  const last = head.includes("::") ? (right === "" ? [] : right.split(":")) : []
+  const groups = head.includes("::") ? [...first, ...Array<string>(8 - first.length - last.length).fill("0"), ...last] : head.split(":")
+  const bytes: number[] = []
+  for (const group of groups) {
+    const value = Number.parseInt(group, 16)
+    bytes.push(value >> 8, value & 0xff)
+  }
+  return { family, bytes }
+}
+
+interface Cidr {
+  readonly ip: Ip
+  readonly bits: number
+}
+
+function inCidr(ip: Ip, cidr: Cidr): boolean {
+  if (ip.family !== cidr.ip.family) return false
+  let left = cidr.bits
+  for (let i = 0; left > 0; i++, left -= 8) {
+    const mask = left >= 8 ? 0xff : (0xff << (8 - left)) & 0xff
+    if ((ip.bytes[i]! & mask) !== (cidr.ip.bytes[i]! & mask)) return false
+  }
+  return true
+}
+
+function parseCidr(text: string): Cidr | undefined {
+  const [address = "", length, extra] = text.split("/")
+  const ip = parseIp(address)
+  if (!ip || extra !== undefined) return undefined
+  const max = ip.family === 4 ? 32 : 128
+  if (length === undefined) return { ip, bits: max }
+  const bits = Number(length)
+  return /^\d{1,3}$/.test(length) && bits <= max ? { ip, bits } : undefined
+}
+
+const cidrs = (list: string[]): Cidr[] => list.map((entry) => parseCidr(entry)!)
+
+/** IPv4 that is not a public unicast address. */
+const BLOCKED_V4 = cidrs([
+  "0.0.0.0/8", // "this network"
+  "10.0.0.0/8",
+  "100.64.0.0/10", // CGNAT
+  "127.0.0.0/8", // loopback
+  "169.254.0.0/16", // link-local, cloud metadata
+  "172.16.0.0/12",
+  "192.0.0.0/24", // IETF protocol assignments
+  "192.0.2.0/24", // documentation
+  "192.168.0.0/16",
+  "198.18.0.0/15", // benchmarking
+  "198.51.100.0/24", // documentation
+  "203.0.113.0/24", // documentation
+  "224.0.0.0/4", // multicast
+  "240.0.0.0/4", // reserved, broadcast
+])
+
+/**
+ * IPv6 that is not a public unicast address. NAT64 (`64:ff9b::/96`) and 6to4 (`2002::/16`) are
+ * not listed: they embed an IPv4 address, which `isPublic` checks as IPv4 (a DNS64 network answers
+ * with NAT64 addresses for ordinary public hosts).
+ */
+const BLOCKED_V6 = cidrs([
+  "::/96", // unspecified, loopback, deprecated IPv4-compatible
+  "::ffff:0:0/96", // IPv4-mapped: never a real answer for a public host
+  "64:ff9b:1::/48", // local-use NAT64
+  "100::/64", // discard
+  "2001::/32", // Teredo
+  "2001:db8::/32", // documentation
+  "fc00::/7", // unique local
+  "fe80::/10", // link-local
+  "fec0::/10", // site-local (deprecated)
+  "ff00::/8", // multicast
+])
+
+/** The IPv4 address embedded in a NAT64 or 6to4 address (or a mapped one), if it is one. */
+function embeddedV4(ip: Ip): Ip | undefined {
+  if (ip.family !== 6) return undefined
+  const b = ip.bytes
+  const mapped = b.slice(0, 10).every((x) => x === 0) && b[10] === 0xff && b[11] === 0xff
+  const nat64 = b[0] === 0 && b[1] === 0x64 && b[2] === 0xff && b[3] === 0x9b && b.slice(4, 12).every((x) => x === 0)
+  if (mapped || nat64) return { family: 4, bytes: b.slice(12, 16) }
+  if (b[0] === 0x20 && b[1] === 0x02) return { family: 4, bytes: b.slice(2, 6) }
+  return undefined
+}
+
+function isPublic(ip: Ip): boolean {
+  const inner = embeddedV4(ip)
+  if (inner && !isPublic(inner)) return false
+  return !(ip.family === 4 ? BLOCKED_V4 : BLOCKED_V6).some((cidr) => inCidr(ip, cidr))
+}
+
+// ---- allowlist
+
+/** One `remoteImages.allow` entry: a host name (`images.internal`, or `*.internal` for subdomains), an IP address, or a CIDR range. */
+type AllowEntry = { readonly kind: "host"; readonly name: string } | { readonly kind: "net"; readonly cidr: Cidr }
+
+const HOSTNAME = /^(?:\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/
+
+/** Undefined when `entry` is none of the three forms. */
+export function parseAllowEntry(entry: string): AllowEntry | undefined {
+  const text = entry.trim().toLowerCase()
+  const cidr = parseCidr(text)
+  if (cidr) return { kind: "net", cidr }
+  return HOSTNAME.test(text) && !text.includes("/") ? { kind: "host", name: text } : undefined
+}
+
+const hostMatches = (entry: { readonly name: string }, host: string): boolean =>
+  entry.name.startsWith("*.") ? host.endsWith(entry.name.slice(1)) : host === entry.name
+
+/** All addresses of `host`, in resolver order; rejects when `signal` aborts (the lookup itself cannot be cancelled). */
+function resolveAddresses(host: string, signal: AbortSignal): Promise<string[]> {
+  return new Promise((done, fail) => {
+    const onAbort = () => fail(signal.reason)
+    if (signal.aborted) return onAbort()
+    signal.addEventListener("abort", onAbort, { once: true })
+    lookup(host, { all: true, verbatim: true }).then(
+      (found) => (signal.removeEventListener("abort", onAbort), done(found.map((entry) => entry.address))),
+      (error) => (signal.removeEventListener("abort", onAbort), fail(error)),
+    )
+  })
+}
+
+/**
+ * Resolve the URL's host and decide which address to connect to. Every address the name resolves
+ * to has to be allowed (a name that answers with one public and one private address is refused),
+ * so the pinned one cannot be a surprise. Throws the generic fetch error when anything is refused.
+ */
+async function pickAddress(url: URL, allow: ReadonlyArray<AllowEntry>, signal: AbortSignal): Promise<string> {
+  const host = url.hostname.replace(/^\[|\]$/g, "").toLowerCase()
+  const literal = parseIp(host)
+  const addresses = literal ? [host] : await resolveAddresses(host, signal)
+  const nameAllowed = allow.some((entry) => entry.kind === "host" && hostMatches(entry, host))
+  const permitted = (address: string): boolean => {
+    const ip = parseIp(address)
+    if (!ip) return false
+    return nameAllowed || isPublic(ip) || allow.some((entry) => entry.kind === "net" && inCidr(ip, entry.cidr))
+  }
+  if (addresses.length === 0 || !addresses.every(permitted)) {
+    // The log says which kind of refusal, never the host or the URL.
+    log("media.remote_refused", { reason: addresses.length === 0 ? "no_address" : "address_not_allowed" })
+    throw FETCH_FAILED()
+  }
+  return addresses[0]!
+}
+
+/** GET `url` over a connection to `address` (already checked), keeping the URL's host for `Host` and TLS. No redirects are followed by the caller. */
+function get(url: URL, address: string, signal: AbortSignal): Promise<IncomingMessage> {
+  return new Promise((resolve, reject) => {
+    const secure = url.protocol === "https:"
+    const name = url.hostname.replace(/^\[|\]$/g, "")
+    const request = (secure ? httpsRequest : httpRequest)(
+      {
+        host: address,
+        port: url.port === "" ? (secure ? 443 : 80) : Number(url.port),
+        path: `${url.pathname}${url.search}`,
+        method: "GET",
+        agent: false,
+        headers: { host: url.host, accept: "image/*", "user-agent": "opencode-plugboard" },
+        // Certificate checks use the URL's host name, not the pinned address.
+        ...(secure && isIP(name) === 0 ? { servername: name } : {}),
+      },
+      resolve,
+    )
+    request.on("error", reject)
+    const abort = () => request.destroy(new Error("aborted"))
+    request.on("close", () => signal.removeEventListener("abort", abort))
+    if (signal.aborted) return abort()
+    signal.addEventListener("abort", abort, { once: true })
+    request.end()
+  })
+}
+
+// ---- preparation
+
+async function toDataUrl(url: string, signal: AbortSignal, remoteImages: RemoteImages, budget: Budget): Promise<string> {
   if (url.startsWith("data:")) {
     if (url.length > budget.remaining) throw TOO_MANY()
     return url
   }
   if (!/^https?:\/\//i.test(url)) throw new ImageError("unsupported_image_url", "Unsupported image URL scheme; use a data: URL or an http(s) URL")
-  if (!remoteImages)
+  if (remoteImages === false)
     throw new ImageError("remote_images_disabled", "Remote image URLs are disabled; send a data: URL or set the plugboard `remoteImages` option")
-  // Messages never carry the URL or the fetch error text: both can hold credentials in the query string.
-  const response = await fetch(url, { redirect: "error", signal: AbortSignal.any([signal, AbortSignal.timeout(20_000)]) }).catch((error: unknown) => {
-    const reason = error instanceof Error && error.name === "TimeoutError" ? "timed out" : "network error"
-    throw new ImageError("image_fetch_failed", `Could not fetch image (${reason})`)
+
+  // Messages never carry the URL, the status, the content type or the fetch error text: they can hold
+  // credentials in the query string or describe the server's network to the caller.
+  const bounded = AbortSignal.any([signal, AbortSignal.timeout(FETCH_TIMEOUT_MS)])
+  let target: URL
+  try {
+    target = new URL(url)
+  } catch {
+    throw FETCH_FAILED()
+  }
+  const allow = typeof remoteImages === "object" ? remoteImages.allow.flatMap((entry) => parseAllowEntry(entry) ?? []) : []
+  const address = await pickAddress(target, allow, bounded).catch((error: unknown) => {
+    throw error instanceof ImageError ? error : FETCH_FAILED()
+  })
+  const response = await get(target, address, bounded).catch(() => {
+    throw FETCH_FAILED()
   })
-  if (!response.ok) throw new ImageError("image_fetch_failed", `Could not fetch image (HTTP ${response.status})`)
-  const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() ?? ""
-  if (!mediaType.startsWith("image/")) throw new ImageError("invalid_image", `URL did not return an image (content-type: ${mediaType || "none"})`)
-  const declared = Number(response.headers.get("content-length"))
+  // A redirect is never followed (it could point inside); anything but a plain success is a failed fetch.
+  if (response.statusCode === undefined || response.statusCode < 200 || response.statusCode > 299) {
+    response.destroy()
+    throw FETCH_FAILED()
+  }
+  const mediaType = (response.headers["content-type"] ?? "").split(";")[0]?.trim().toLowerCase() ?? ""
+  if (!mediaType.startsWith("image/")) {
+    response.destroy()
+    throw new ImageError("invalid_image", "URL did not return an image")
+  }
+  const declared = Number(response.headers["content-length"])
   // The data URL is 4/3 of the raw size plus a short prefix: stop reading once it cannot fit the budget.
   const budgetRaw = Math.floor((budget.remaining * 3) / 4)
   const limit = Math.min(MAX_REMOTE_IMAGE_BYTES, budgetRaw)
   const tooLarge = () => (limit < MAX_REMOTE_IMAGE_BYTES ? TOO_MANY() : new ImageError("image_too_large", "Image is larger than 20 MB"))
-  if (Number.isFinite(declared) && declared > limit) throw tooLarge()
-  const chunks: Uint8Array[] = []
+  if (Number.isFinite(declared) && declared > limit) {
+    response.destroy()
+    throw tooLarge()
+  }
+  const chunks: Buffer[] = []
   let size = 0
-  const reader = response.body?.getReader()
-  if (!reader) throw new ImageError("invalid_image", "Image response had no body")
-  while (true) {
-    const { done, value } = await reader.read()
-    if (done) break
-    size += value.byteLength
-    if (size > limit) {
-      void reader.cancel().catch(() => {})
-      throw tooLarge()
+  try {
+    for await (const chunk of response as AsyncIterable<Buffer>) {
+      size += chunk.byteLength
+      if (size > limit) throw tooLarge()
+      chunks.push(chunk)
     }
-    chunks.push(value)
+  } catch (error) {
+    response.destroy()
+    throw error instanceof ImageError ? error : FETCH_FAILED()
   }
   const dataUrl = `data:${mediaType};base64,${Buffer.concat(chunks).toString("base64")}`
   if (dataUrl.length > budget.remaining) throw TOO_MANY()
@@ -73,7 +306,7 @@ async function toDataUrl(url: string, signal: AbortSignal, remoteImages: boolean
 export async function prepareImages(
   request: PlugRequest,
   signal: AbortSignal,
-  remoteImages: boolean,
+  remoteImages: RemoteImages,
 ): Promise<Array<{ uri: string; name: string }>> {
   const images: Array<{ uri: string; name: string }> = []
   const budget: Budget = { remaining: MAX_TOTAL_IMAGE_BYTES }

package/src/session/state.ts

@@ -57,6 +57,8 @@ export interface SessionStore {
   retire(sessionID: string, retirement: Retirement): void
   /** Fail every registered request with `error`; returns how many were registered. */
   failAll(error: PlugError): number
+  /** How many request guards are outstanding (metrics and status only). */
+  size(): number
 }
 
 const EXECUTION_END = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"])
@@ -140,5 +142,6 @@ export function createSessionStore(options: SessionStoreOptions = {}): SessionSt
       }
       return entries.size
     },
+    size: () => entries.size,
   }
 }