opencode-plugboard 0.0.0-stage → 0.3.0

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/prune.ts

@@ -0,0 +1,175 @@
+/**
+ * History pruning: an index of plugboard's own request sessions and the sweep that deletes the
+ * old ones.
+ *
+ * The plugin session API has no `list`, so plugboard cannot ask the host which sessions it owns.
+ * It keeps an index in the plugin's own host storage (`ctx.storage`, a key-value table in the
+ * host database, shared by every Location): one key per request session,
+ *
+ *   history/<app>/<created, 15 digits of epoch ms>/<sessionID>
+ *
+ * Everything the sweep needs is in the key, so a scan returns an app's sessions oldest first.
+ * Sessions created before this index existed are not in it and are never pruned.
+ *
+ * Both functions run from request handling only (the runtime calls them), never from plugin
+ * setup or a finalizer. A sweep does bounded work: it reads at most `maxScan` index entries per
+ * app, makes at most `maxDeletes` host deletions and stops at its deadline; what is left waits for
+ * the next sweep. A session whose request guard is still in the session store (the host
+ * execution has not ended) is never deleted.
+ */
+
+import type { HistoryPort } from "./host.js"
+import type { SessionStore } from "./state.js"
+
+/** Pruning limits. A field that is unset is not applied; with none set nothing is ever deleted. */
+export interface HistoryLimits {
+  /** Keep at most this many sessions per app (the newest). */
+  readonly maxSessions?: number
+  /** Delete sessions older than this many days. */
+  readonly maxAgeDays?: number
+}
+
+export interface SweepResult {
+  readonly apps: number
+  /** Index entries read. */
+  readonly scanned: number
+  readonly removed: number
+  /** Already gone from the host (deleted by hand); only the index entry was dropped. */
+  readonly missing: number
+  /** Host deletions or index updates that failed; retried by the next sweep. */
+  readonly failed: number
+  /** Over a limit but skipped because the request guard is still active. */
+  readonly active: number
+  /** Work was left (budget, deadline or scan cap reached): run the next sweep soon. */
+  readonly more: boolean
+}
+
+export interface SweepInput {
+  readonly port: HistoryPort
+  readonly limits: HistoryLimits
+  readonly sessions: SessionStore
+  readonly now: number
+  /** Aborts the sweep between host calls. */
+  readonly signal: AbortSignal
+  /** Most host deletions per sweep. */
+  readonly maxDeletes?: number
+  /** Most index entries read per app per sweep. */
+  readonly maxScan?: number
+}
+
+const PREFIX = "history/"
+const AT_WIDTH = 15
+const DAY_MS = 86_400_000
+const PAGE = 500
+const MAX_DELETES = 200
+const MAX_SCAN = 20_000
+
+export const indexKey = (app: string, createdAt: number, sessionID: string): string =>
+  `${PREFIX}${app}/${String(Math.max(0, Math.floor(createdAt))).padStart(AT_WIDTH, "0")}/${sessionID}`
+
+/** Index one new request session. The value repeats the ID; the key carries app and time. */
+export const recordSession = (port: HistoryPort, app: string, sessionID: string, createdAt: number): Promise<void> =>
+  port.put(indexKey(app, createdAt, sessionID), sessionID)
+
+interface Entry {
+  readonly key: string
+  readonly sessionID: string
+  readonly createdAt: number
+}
+
+function parseKey(key: string): Entry | undefined {
+  const [, at, ...rest] = key.slice(PREFIX.length).split("/")
+  const createdAt = Number(at)
+  const sessionID = rest.join("/")
+  if (!/^\d+$/.test(at ?? "") || !Number.isFinite(createdAt) || sessionID.length === 0) return undefined
+  return { key, sessionID, createdAt }
+}
+
+/** App names in the index, found by hopping over each app's keys (one tiny scan per app). */
+async function indexedApps(port: HistoryPort, signal: AbortSignal): Promise<string[]> {
+  const apps: string[] = []
+  let after: string | undefined
+  while (!signal.aborted) {
+    const page = await port.scan({ prefix: PREFIX, ...(after === undefined ? {} : { after }), limit: 1 })
+    const first = page.keys[0]
+    if (first === undefined) break
+    const app = first.slice(PREFIX.length).split("/")[0] ?? ""
+    if (app.length > 0) apps.push(app)
+    // `\uffff` sorts after every character of an ID or timestamp, so this skips the rest of the app.
+    after = `${PREFIX}${app}/\uffff`
+  }
+  return apps
+}
+
+/** One app's entries, oldest first, at most `maxScan`; `capped` when more remain in the index. */
+async function readApp(port: HistoryPort, app: string, maxScan: number, signal: AbortSignal): Promise<{ entries: Entry[]; capped: boolean }> {
+  const entries: Entry[] = []
+  const prefix = `${PREFIX}${app}/`
+  let after: string | undefined
+  while (!signal.aborted) {
+    const page = await port.scan({ prefix, ...(after === undefined ? {} : { after }), limit: Math.min(PAGE, maxScan - entries.length) })
+    for (const key of page.keys) {
+      const entry = parseKey(key)
+      if (entry) entries.push(entry)
+    }
+    if (page.next === undefined) return { entries, capped: false }
+    if (entries.length >= maxScan) return { entries, capped: true }
+    after = page.next
+  }
+  return { entries, capped: true }
+}
+
+/**
+ * One pass over the index. Per app, the sessions to delete are a prefix of its oldest-first list:
+ * as many as exceed `maxSessions`, or are older than `maxAgeDays`, whichever is more. A session
+ * with an active request guard is skipped (it still counts as kept). Entries of sessions the host
+ * no longer has are dropped. A scan that hit `maxScan` only undercounts the app, so it can only
+ * delete fewer sessions than the limit asks for, never more.
+ */
+export async function sweepHistory(input: SweepInput): Promise<SweepResult> {
+  const { port, limits, sessions, signal } = input
+  const maxDeletes = input.maxDeletes ?? MAX_DELETES
+  const maxScan = input.maxScan ?? MAX_SCAN
+  const cutoff = limits.maxAgeDays === undefined ? undefined : input.now - limits.maxAgeDays * DAY_MS
+  let scanned = 0
+  let removed = 0
+  let missing = 0
+  let failed = 0
+  let active = 0
+  let attempts = 0
+  let more = false
+
+  const apps = await indexedApps(port, signal)
+  for (const app of apps) {
+    if (signal.aborted) {
+      more = true
+      break
+    }
+    const { entries, capped } = await readApp(port, app, maxScan, signal)
+    scanned += entries.length
+    if (capped) more = true
+    const excess = limits.maxSessions === undefined ? 0 : Math.max(0, entries.length - limits.maxSessions)
+    const expired = cutoff === undefined ? 0 : entries.findIndex((entry) => entry.createdAt >= cutoff)
+    const count = Math.max(excess, cutoff === undefined ? 0 : expired === -1 ? entries.length : expired)
+    for (const entry of entries.slice(0, count)) {
+      if (signal.aborted || attempts >= maxDeletes) {
+        more = true
+        break
+      }
+      // Checked right before the host call: a guard that is still registered means the host execution is running.
+      if (sessions.lookup(entry.sessionID)) {
+        active++
+        continue
+      }
+      attempts++
+      try {
+        if ((await port.removeSession(entry.sessionID)) === "removed") removed++
+        else missing++
+        await port.drop(entry.key)
+      } catch {
+        failed++
+      }
+    }
+  }
+  return { apps: apps.length, scanned, removed, missing, failed, active, more }
+}

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,144 @@
+/**
+ * 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 interface SessionStoreOptions {
+  /** Called once per `register`, from request handling (the runtime indexes the session for pruning). Must not block; errors are logged. */
+  readonly onRegister?: (state: RequestState) => void
+}
+
+export function createSessionStore(options: SessionStoreOptions = {}): 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() })
+      try {
+        options.onRegister?.(state)
+      } catch (error) {
+        logError("session.register_hook_failed", { error: errorMessage(error) })
+      }
+    },
+    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
+    },
+  }
+}