opencode-plugboard 0.0.0-stage → 0.2.1

package/src/session/media.ts

@@ -0,0 +1,89 @@
+/**
+ * Bounded attachment preparation: request images become prompt files.
+ *
+ * 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.
+ */
+
+import type { PlugRequest } from "../contract.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 TOO_MANY = () => new ImageError("images_too_large", "The request's images are larger than 50 MB in total")
+
+/** What one request's images may still use, in data URL characters (== bytes held). */
+interface Budget {
+  remaining: number
+}
+
+/** A caller image that cannot be used; `code` becomes the error code of the 400 response. */
+export class ImageError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+async function toDataUrl(url: string, signal: AbortSignal, remoteImages: boolean, 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)
+    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})`)
+  })
+  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"))
+  // 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[] = []
+  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()
+    }
+    chunks.push(value)
+  }
+  const dataUrl = `data:${mediaType};base64,${Buffer.concat(chunks).toString("base64")}`
+  if (dataUrl.length > budget.remaining) throw TOO_MANY()
+  return dataUrl
+}
+
+/** Prompt files for every image in the request, in message order, named `image-1`, `image-2`, ... Throws `ImageError`. */
+export async function prepareImages(
+  request: PlugRequest,
+  signal: AbortSignal,
+  remoteImages: boolean,
+): Promise<Array<{ uri: string; name: string }>> {
+  const images: Array<{ uri: string; name: string }> = []
+  const budget: Budget = { remaining: MAX_TOTAL_IMAGE_BYTES }
+  for (const message of request.messages)
+    for (const part of message.content)
+      if (part.type === "media") {
+        signal.throwIfAborted()
+        const uri = await toDataUrl(part.url, signal, remoteImages, budget)
+        budget.remaining -= uri.length
+        images.push({ uri, name: `image-${images.length + 1}` })
+      }
+  return images
+}

package/src/session/seeds.ts

@@ -0,0 +1,47 @@
+/**
+ * Seed tools.
+ *
+ * OpenCode's `session.hook("context")` may only advertise tool definitions that
+ * correspond to a *registered* Tool.Info (unmatched entries are dropped), so plugboard owns a
+ * pool of registered seeds (`maxTools` of them) and re-keys them in the hook:
+ * the caller's name becomes the map key (what the provider sees), while the seed keeps its
+ * own `name` (what the executor dispatches on).
+ *
+ * A seed's `execute` returns at once with `SEED_RESULT`, so history shows the call as
+ * completed. A tool result always makes the runner start a second model step
+ * (`record.needsContinuation`, runner/step.ts), and no tool result, hook or agent setting
+ * ends the loop (failing the seed, even with a typed non-`Tool.Error`, is converted to a
+ * normal tool failure, and `Permission.DeclinedError` is only reachable from host tools).
+ * So plugboard stops the turn itself: once the step has settled with a normal `tool-calls`
+ * finish (`session.step.ended`) it interrupts the session. Nothing orders that interrupt
+ * before the runner's next step, so a second step can occasionally start and be wasted (extra
+ * tokens, a stray assistant message in history, never a wrong response; tracked in issue #14).
+ * The captured `session.tool.called` events are what a `tool_calls` response needs.
+ * Seeds are registered only inside the plugboard data root, denied to every agent there,
+ * and allowed again by the permissions of plugboard's own request sessions. Those permissions
+ * deny every other tool (defense in depth: if a second step ever runs outside the context
+ * hook's replacement, it cannot run real OpenCode tools).
+ */
+
+import type { PlugRequest, PlugTool } from "../contract.js"
+
+export const SEED_PREFIX = "plugboard_seed_"
+
+/** Output of every seed tool call: the caller, not OpenCode, runs the tool. */
+export const SEED_RESULT = "Returned to caller (opencode-plugboard)"
+
+/**
+ * Session permissions of a request session. The host takes the last matching rule (session rules
+ * come after the agent's): everything is denied, then the seeds are allowed again.
+ */
+export const REQUEST_PERMISSIONS: ReadonlyArray<{ action: string; resource: string; effect: "allow" | "deny" }> = [
+  { action: "*", resource: "*", effect: "deny" },
+  { action: `${SEED_PREFIX}*`, resource: "*", effect: "allow" },
+]
+
+/** The caller tools that get a seed in the model request (`tool_choice` none offers none, a named tool only that one). */
+export function seedToolsFor(request: PlugRequest): ReadonlyArray<PlugTool> {
+  const choice = request.toolChoice
+  if (choice === "none") return []
+  return typeof choice === "object" ? request.tools.filter((tool) => tool.name === choice.name) : request.tools
+}

package/src/session/state.ts

@@ -0,0 +1,134 @@
+/**
+ * Session ownership store shared across plugin generations.
+ *
+ * The generation that serves an HTTP request and the generation inside the app directory that
+ * runs its session are different plugin instances (one per Location), and either can be replaced
+ * at any time. So per-request state is kept by session ID in one store owned by the process
+ * runtime (src/runtime.ts): the serving side registers it, the app-directory hook looks it up,
+ * and the process-wide event pump dispatches bus events to the request's event sink. Events of
+ * sessions that are not registered are dropped before anything is buffered.
+ *
+ * An entry is the request guard: while it exists, the context hook replaces the model request
+ * and tools. It outlives the HTTP response. It is released when the host reports the end of the
+ * session's execution (`session.execution.*`), or, after the response finished, when the bounded
+ * cleanup of `retire` runs out. Timers here are unref'd and owned by the process runtime's store,
+ * never by a plugin finalizer.
+ */
+
+import type { PlugError, PlugRequest } from "../contract.js"
+import { errorMessage, logError } from "../log.js"
+
+/** Receives the flattened bus events of one session. The collector implements it. */
+export interface EventSink {
+  push(event: Record<string, unknown>): void
+}
+
+/** Synthetic event (`{ type, error: PlugError }`) that fails a request from inside the process: lost event stream, preparation mismatch. */
+export const FAILURE_EVENT = "plugboard.failure"
+
+export interface RequestState {
+  readonly sessionID: string
+  readonly app: string
+  readonly requestID: string
+  readonly request: PlugRequest
+  readonly collector: EventSink
+}
+
+export interface Retirement {
+  /** How long the guard may outlive the response while the host execution has not ended. */
+  readonly timeoutMs: number
+  /** Called once if the timeout runs out (the host never confirmed the end of the execution). Must not block. */
+  onTimeout(): void
+}
+
+export interface SessionStore {
+  /** Own a request session; replaces any state registered under the same session ID. */
+  register(state: RequestState): void
+  lookup(sessionID: string): RequestState | undefined
+  /** Route one bus envelope (`{ type, data: { sessionID, ... } }`) to its request's sink, if any. Releases the session when its execution ended. */
+  dispatch(event: unknown): void
+  /** Stop owning a session; false when it was not registered. */
+  release(sessionID: string): boolean
+  /**
+   * The response is over: keep the guard until the host reports the end of the execution, or
+   * until `timeoutMs` passes, which is logged and released after `onTimeout`. No-op when the
+   * session is already released.
+   */
+  retire(sessionID: string, retirement: Retirement): void
+  /** Fail every registered request with `error`; returns how many were registered. */
+  failAll(error: PlugError): number
+}
+
+const EXECUTION_END = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"])
+
+interface Entry {
+  readonly state: RequestState
+  readonly startedAt: number
+  timer?: ReturnType<typeof setTimeout>
+}
+
+export function createSessionStore(): SessionStore {
+  const entries = new Map<string, Entry>()
+
+  const release = (sessionID: string): boolean => {
+    const entry = entries.get(sessionID)
+    if (!entry) return false
+    if (entry.timer) clearTimeout(entry.timer)
+    return entries.delete(sessionID)
+  }
+
+  return {
+    register(state) {
+      const previous = entries.get(state.sessionID)
+      if (previous?.timer) clearTimeout(previous.timer)
+      entries.set(state.sessionID, { state, startedAt: Date.now() })
+    },
+    lookup: (sessionID) => entries.get(sessionID)?.state,
+    release,
+    dispatch(event) {
+      const envelope = event as { type?: unknown; data?: Record<string, unknown> } | null
+      const sessionID = envelope?.data?.sessionID
+      if (typeof sessionID !== "string") return
+      const entry = entries.get(sessionID)
+      if (!entry) return
+      try {
+        entry.state.collector.push({ type: envelope?.type, ...envelope?.data })
+      } catch (error) {
+        logError("session.event_failed", { error: errorMessage(error) })
+      }
+      if (typeof envelope?.type === "string" && EXECUTION_END.has(envelope.type)) release(sessionID)
+    },
+    retire(sessionID, retirement) {
+      const entry = entries.get(sessionID)
+      if (!entry || entry.timer) return
+      entry.timer = setTimeout(() => {
+        if (entries.get(sessionID) !== entry) return
+        logError("session.cleanup_timeout", {
+          sessionID,
+          requestID: entry.state.requestID,
+          app: entry.state.app,
+          model: entry.state.request.model,
+          durationMs: Date.now() - entry.startedAt,
+          outcome: "execution_end_not_confirmed",
+        })
+        try {
+          retirement.onTimeout()
+        } catch (error) {
+          logError("session.cleanup_failed", { requestID: entry.state.requestID, error: errorMessage(error) })
+        }
+        entries.delete(sessionID)
+      }, retirement.timeoutMs)
+      entry.timer.unref?.()
+    },
+    failAll(error) {
+      for (const entry of entries.values()) {
+        try {
+          entry.state.collector.push({ type: FAILURE_EVENT, error })
+        } catch (cause) {
+          logError("session.event_failed", { error: errorMessage(cause) })
+        }
+      }
+      return entries.size
+    },
+  }
+}