opencode-plugboard 0.0.0-stage → 0.3.0

package/src/session/events.ts

@@ -0,0 +1,344 @@
+/**
+ * Session event translation.
+ *
+ * `RequestCollector` receives the OpenCode bus events of ONE plugboard request session
+ * (already filtered by the process-wide session store) and turns them into `PlugEvent`s that the
+ * ModelCaller streams out through `events()` (not buffered beyond the queue).
+ *
+ * The turn is stopped from inside the model loop (see `session/seeds.ts`): once the step has ended
+ * (`session.step.ended`) with at least one tool call, the owner is asked to interrupt the
+ * session before a second model step can start, and the request finishes as `tool-calls`.
+ * The collector never calls the host itself; the owner passes `stopTurn`.
+ */
+
+import { isPlugError, type PlugError, type PlugEvent, type PlugFinish, type PlugUsage } from "../contract.js"
+import type { BusEvent } from "./host.js"
+import { FAILURE_EVENT } from "./state.js"
+
+/** At most this many events may wait for a slow consumer, and at most this many (estimated) bytes of them. */
+const MAX_QUEUED_EVENTS = 10_000
+const MAX_QUEUED_BYTES = 8 * 1024 * 1024
+
+/** The error a request fails with when its consumer cannot keep up. */
+const RESPONSE_OVERFLOW: PlugError = {
+  status: 502,
+  kind: "server",
+  code: "response_overflow",
+  message: "The response was not read fast enough; too much output was waiting",
+}
+
+/** Rough size of an event's payload, for the queue's byte bound. */
+function sizeOf(event: PlugEvent): number {
+  switch (event.type) {
+    case "text-delta":
+    case "reasoning-delta":
+      return event.text.length
+    case "tool-call":
+      return 64 + event.name.length + (JSON.stringify(event.input) ?? "").length
+    default:
+      return 256
+  }
+}
+
+/**
+ * Minimal async queue: producers `push`, one consumer iterates; `close` ends the iteration.
+ * Bounded: `push` refuses an item that would exceed the item or byte limit (the caller decides
+ * what to do; it never waits), so a slow consumer cannot make one request grow without limit.
+ */
+class EventQueue<T> implements AsyncIterable<T> {
+  private items: Array<{ item: T; size: number }> = []
+  private bytes = 0
+  private waiter?: () => void
+  private closed = false
+
+  constructor(
+    private readonly maxItems: number,
+    private readonly maxBytes: number,
+  ) {}
+
+  /** False when the item was refused for size (nothing was queued). Unbounded when `force`. */
+  push(item: T, size: number, force = false): boolean {
+    if (this.closed) return true
+    if (!force && (this.items.length >= this.maxItems || this.bytes + size > this.maxBytes)) return false
+    this.items.push({ item, size })
+    this.bytes += size
+    this.wake()
+    return true
+  }
+
+  /** Drop everything that waits (the consumer is gone or too slow). */
+  clear(): void {
+    this.items = []
+    this.bytes = 0
+  }
+
+  close(): void {
+    this.closed = true
+    this.wake()
+  }
+
+  private wake() {
+    const waiter = this.waiter
+    this.waiter = undefined
+    waiter?.()
+  }
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<T> {
+    while (true) {
+      const next = this.items.shift()
+      if (next !== undefined) {
+        this.bytes -= next.size
+        yield next.item
+        continue
+      }
+      if (this.closed) return
+      await new Promise<void>((resolve) => {
+        this.waiter = resolve
+      })
+    }
+  }
+}
+
+/**
+ * The host's session token record (`TokenUsage.Info`, `session.step.ended` / `session.usage.updated`
+ * `tokens`). It is a NON-overlapping breakdown (`packages/core/src/session/usage.ts`): `input` is
+ * the non-cached prompt, `output` the visible (non-reasoning) completion, `reasoning` the hidden
+ * reasoning, and `cache.read` / `cache.write` the cached prompt parts.
+ */
+interface RawUsage {
+  readonly input?: number
+  readonly output?: number
+  readonly reasoning?: number
+  readonly cache?: { readonly read?: number; readonly write?: number }
+}
+
+interface RawError {
+  readonly type?: string
+  readonly message?: string
+  readonly status?: number
+}
+
+const total = (...parts: Array<number | undefined>): number | undefined =>
+  parts.some((part) => typeof part === "number") ? parts.reduce<number>((sum, part) => sum + (typeof part === "number" ? part : 0), 0) : undefined
+
+/**
+ * Host breakdown to `PlugUsage`, whose totals are inclusive (see `PlugUsage`):
+ *   inputTokens  = input + cache.read + cache.write
+ *   outputTokens = output + reasoning
+ * reasoning and cache fields pass through as the subsets they are.
+ */
+const toUsage = (tokens?: RawUsage): PlugUsage | undefined =>
+  tokens
+    ? {
+        inputTokens: total(tokens.input, tokens.cache?.read, tokens.cache?.write),
+        outputTokens: total(tokens.output, tokens.reasoning),
+        reasoningTokens: tokens.reasoning,
+        cacheReadTokens: tokens.cache?.read,
+        cacheWriteTokens: tokens.cache?.write,
+      }
+    : undefined
+
+/** Host `SessionError` (`{ type, message, status?, response? }`) to a `PlugError`. */
+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 }
+}
+
+export interface CollectorHooks {
+  /** The step ended with tool calls: stop the turn before the runner starts another model step. */
+  readonly stopTurn: () => void
+}
+
+export class RequestCollector {
+  private readonly queue = new EventQueue<PlugEvent>(MAX_QUEUED_EVENTS, MAX_QUEUED_BYTES)
+  private readonly emittedText = new Map<number, number>()
+  private readonly toolNames = new Map<string, string>()
+  private readonly calls = new Set<string>()
+  private usage?: RawUsage
+  private finished = false
+  private executionDone = false
+  private wasCancelled = false
+  private settled = false
+
+  constructor(private readonly hooks: CollectorHooks) {}
+
+  /** True once a `finish` or `error` event was emitted (or the stream was ended); later events are ignored. */
+  get terminal(): boolean {
+    return this.finished
+  }
+
+  /** True once the OpenCode execution ended (succeeded, failed or interrupted). */
+  get executionEnded(): boolean {
+    return this.executionDone
+  }
+
+  /** True once a step ended with a plain `stop` and no tool calls: the runner finishes by itself, nothing needs interrupting. */
+  get turnSettled(): boolean {
+    return this.settled
+  }
+
+  /** True once the owner cancelled the request (client gone or timeout). */
+  get cancelled(): boolean {
+    return this.wasCancelled
+  }
+
+  /** The request's events, in order. Ends when the collector is terminal. */
+  events(): AsyncIterable<PlugEvent> {
+    return this.queue
+  }
+
+  /** Mark the request cancelled by its owner (client gone or timed out) and close the stream without a terminal event. */
+  cancel(): void {
+    this.wasCancelled = true
+    this.end()
+  }
+
+  /**
+   * `item` is the flattened bus event: `{ type, ...data }`. Field types are not verified here:
+   * the host's event payloads are read defensively (`String(...)`, `Number(...)`), and the few
+   * structured fields (`tokens`, `error`) are cast to the shapes in `RawUsage` / `RawError`.
+   */
+  push(item: BusEvent): void {
+    switch (item.type) {
+      case "session.text.delta": {
+        if (this.finished) return
+        const ordinal = Number(item.ordinal ?? 0)
+        const delta = String(item.delta ?? "")
+        this.emittedText.set(ordinal, (this.emittedText.get(ordinal) ?? 0) + delta.length)
+        if (delta.length > 0) this.emit({ type: "text-delta", text: delta })
+        return
+      }
+      case "session.text.ended": {
+        if (this.finished) return
+        // Deltas are live-only; if any were missed, the ended event carries the full text.
+        const ordinal = Number(item.ordinal ?? 0)
+        const full = String(item.text ?? "")
+        const seen = this.emittedText.get(ordinal) ?? 0
+        if (full.length > seen) this.emit({ type: "text-delta", text: full.slice(seen) })
+        this.emittedText.set(ordinal, full.length)
+        return
+      }
+      case "session.reasoning.delta": {
+        if (this.finished) return
+        const delta = String(item.delta ?? "")
+        if (delta.length > 0) this.emit({ type: "reasoning-delta", text: delta })
+        return
+      }
+      case "session.tool.input.started":
+        this.toolNames.set(String(item.id), String(item.name ?? ""))
+        return
+      case "session.tool.called": {
+        if (this.finished) return
+        const id = String(item.id)
+        if (this.calls.has(id)) return
+        this.calls.add(id)
+        this.emit({ type: "tool-call", id, name: String(item.name ?? this.toolNames.get(id) ?? ""), input: item.input })
+        return
+      }
+      case "session.usage.updated":
+        // Assumed invariant: `tokens` is the host's token-usage record (RawUsage shape).
+        this.usage = (item.tokens as RawUsage | undefined) ?? this.usage
+        return
+      case "session.step.ended":
+        this.usage = (item.tokens as RawUsage | undefined) ?? this.usage
+        // Also after the response finished: a later step that ended with calls means the first
+        // interrupt lost the race or failed; ask again (the guard stays until the execution ends).
+        if (this.calls.size > 0 && !this.executionDone) this.hooks.stopTurn()
+        if (this.calls.size === 0 && toFinish(item.finish) === "stop") this.settled = true
+        this.finishWith(withCalls(toFinish(item.finish), this.calls.size > 0))
+        return
+      case FAILURE_EVENT:
+        // Synthetic, from inside the process (lost event stream, preparation mismatch).
+        if (isPlugError(item.error)) this.abort(item.error)
+        return
+      case "session.step.failed": {
+        this.usage = (item.tokens as RawUsage | undefined) ?? this.usage
+        // Assumed invariant: `error` is the host's `SessionError` (RawError shape).
+        const error = item.error as RawError | undefined
+        // The host can run another step after a failed one; the response is over, the turn must be too.
+        if (!this.executionDone && error?.type !== "aborted") this.hooks.stopTurn()
+        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"))
+      }
+      case "session.execution.failed":
+        this.executionDone = true
+        if (!this.finished) this.fail(toPlugError(item.error as RawError | undefined, "Session execution failed"))
+        this.end()
+        return
+      case "session.execution.interrupted":
+      case "session.execution.succeeded":
+        this.executionDone = true
+        if (!this.finished) {
+          if (this.calls.size > 0) this.finishWith("tool-calls")
+          else if (this.wasCancelled) this.end()
+          else if (item.type === "session.execution.succeeded") this.finishWith("stop")
+          else this.fail({ status: 500, kind: "server", message: "Request was interrupted before the model finished" })
+        }
+        this.end()
+        return
+      default:
+        return
+    }
+  }
+
+  /** Fail the request with `error` and stop the turn. No-op once the request is terminal. */
+  abort(error: PlugError): void {
+    if (this.finished) return
+    this.fail(error)
+    this.hooks.stopTurn()
+  }
+
+  /** Close the stream without a terminal event (client gone). */
+  end(): void {
+    this.finished = true
+    this.queue.close()
+  }
+
+  private finishWith(reason: PlugFinish): void {
+    if (this.finished) return
+    this.emit({ type: "finish", reason, usage: toUsage(this.usage) })
+    this.end()
+  }
+
+  private fail(error: PlugError): void {
+    if (this.finished) return
+    this.emit({ type: "error", error })
+    this.end()
+  }
+
+  private emit(event: PlugEvent): void {
+    // Errors are always queued: they are how an overflow is reported.
+    if (this.queue.push(event, sizeOf(event), event.type === "error")) return
+    // The consumer is not keeping up: drop what waits, fail this request only, and stop the turn.
+    this.queue.clear()
+    this.queue.push({ type: "error", error: RESPONSE_OVERFLOW }, 0, true)
+    this.end()
+    if (!this.executionDone) this.hooks.stopTurn()
+  }
+}
+
+/** A tool call turns a normal stop into `tool-calls`; a truncated, filtered or failed step keeps its reason. */
+const withCalls = (reason: PlugFinish, hasCalls: boolean): PlugFinish => (hasCalls && (reason === "stop" || reason === "tool-calls") ? "tool-calls" : reason)
+
+const toFinish = (finish: unknown): PlugFinish => {
+  switch (finish) {
+    case "length":
+    case "content-filter":
+    case "error":
+      return finish
+    case "tool-calls":
+      return "tool-calls"
+    default:
+      return "stop"
+  }
+}

package/src/session/history.ts

@@ -0,0 +1,89 @@
+/**
+ * Where request sessions live and what they store: the data root, the app directory, and the
+ * session title and prompt transcript.
+ *
+ * One request = one kept OpenCode session in the caller app's directory under the data root.
+ * The stored prompt is the full caller transcript rendered as readable text (images ride along
+ * as prompt files, listed here by attachment number); the context hook substitutes the real
+ * structured system/messages/tools for the model call.
+ */
+
+import { mkdir, realpath } from "node:fs/promises"
+import { homedir } from "node:os"
+import { join, sep } from "node:path"
+import type { PlugError, PlugRequest } from "../contract.js"
+
+/** `$XDG_DATA_HOME/opencode-plugboard`, else `~/.local/share/opencode-plugboard`. */
+function dataRoot(): string {
+  const base = process.env.XDG_DATA_HOME && process.env.XDG_DATA_HOME.length > 0 ? process.env.XDG_DATA_HOME : join(homedir(), ".local", "share")
+  return join(base, "opencode-plugboard")
+}
+
+/**
+ * Create (if needed) and return the real path of `<dataRoot>/<app>`. `app` must already be validated.
+ * Fails closed with a `PlugError` when the resolved path is not strictly inside the canonical data
+ * root (a symlinked app directory): a session there would run in another project, where plugboard
+ * registers no context hook and no seeds, so it must never be created.
+ *
+ * This is the only place ownership of a directory is decided, and it is asynchronous: plugin
+ * setup never touches the filesystem. A directory that comes back here is what the runtime treats
+ * as a plugboard app directory (`ensureBackend` in src/runtime.ts).
+ */
+export async function ensureAppDir(app: string): Promise<string | PlugError> {
+  const root = dataRoot()
+  const appDir = join(root, app)
+  await mkdir(appDir, { recursive: true })
+  const [realRoot, realApp] = await Promise.all([realpath(root), realpath(appDir)])
+  if (!realApp.startsWith(realRoot + sep)) {
+    return { status: 500, kind: "server", code: "app_dir_outside_root", message: "The app directory resolves outside the plugboard data root" }
+  }
+  return realApp
+}
+
+const TITLE_LENGTH = 60
+
+const firstUserText = (request: PlugRequest): string => {
+  for (const message of request.messages) {
+    if (message.role !== "user") continue
+    for (const part of message.content) if (part.type === "text" && part.text.trim().length > 0) return part.text
+  }
+  return request.model
+}
+
+/** Session title: the first user text, whitespace-collapsed and cut to 60 characters. */
+export const makeTitle = (request: PlugRequest): string => {
+  const flat = firstUserText(request).replace(/\s+/g, " ").trim()
+  return flat.length > TITLE_LENGTH ? flat.slice(0, TITLE_LENGTH - 1) + "…" : flat
+}
+
+/** Readable transcript stored as the session's prompt; images are listed by attachment number. */
+export function renderTranscript(request: PlugRequest): string {
+  const lines: string[] = []
+  let image = 0
+  if (request.system.length > 0) {
+    lines.push("## system", ...request.system, "")
+  }
+  for (const message of request.messages) {
+    lines.push(`## ${message.role}`)
+    for (const part of message.content) {
+      switch (part.type) {
+        case "text":
+          lines.push(part.text)
+          break
+        case "media":
+          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)}`)
+          break
+        case "tool-result":
+          lines.push(`[tool result ${part.name} (${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()
+  return text.length > 0 ? text : "(empty request)"
+}

package/src/session/host.ts

@@ -0,0 +1,215 @@
+/**
+ * The host adapter: the one place that touches OpenCode's Effect plugin API on behalf of the
+ * session code. It turns `ctx.session` into the Promise-shaped `SessionPort`, `ctx.model.list`
+ * into a neutral catalog, and defines the narrow shapes the session code reads from the host (the
+ * `context` hook event, the flat bus-event record).
+ *
+ * Pinned to the OpenCode version in docs/architecture.md. Beyond `Effect.runPromise` this module
+ * only imports host types; no module under `session/` imports `@opencode/ai` or core internals at
+ * runtime.
+ */
+
+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"
+
+export type HostContext = Plugin.Context
+
+/** JSON value, the shape of session metadata (the host's `Json`). */
+export type Json = string | number | boolean | null | ReadonlyArray<Json> | { readonly [key: string]: Json }
+
+/** Promise-shaped view of the host calls the session caller needs (the entry wires them to `ctx.session`). */
+export interface SessionPort {
+  create(input: {
+    readonly directory: string
+    readonly model: { readonly providerID: string; readonly id: string; readonly variant?: string }
+    readonly title: string
+    readonly metadata: { readonly [key: string]: Json }
+    readonly permissions: ReadonlyArray<{ action: string; resource: string; effect: "allow" | "deny" }>
+  }): Promise<{ id: string }>
+  prompt(input: { readonly sessionID: string; readonly text: string; readonly files: ReadonlyArray<{ uri: string; name: string }> }): Promise<unknown>
+  interrupt(sessionID: string): Promise<void>
+}
+
+type HostSession = HostContext["session"]
+
+/**
+ * The host's branded session ID. It is a string with a type-level brand and no runtime form, so
+ * the one cast below is the only unchecked step: the ID always comes from the host's own
+ * `session.create` result (or an event of that session).
+ */
+type HostSessionID = Parameters<HostSession["interrupt"]>[0]["sessionID"]
+const hostSessionID = (id: string): HostSessionID => id as HostSessionID
+
+type HostCreate = NonNullable<Parameters<HostSession["create"]>[0]>
+type HostModelRef = NonNullable<HostCreate["model"]>
+type HostDirectory = NonNullable<HostCreate["location"]>["directory"]
+
+/**
+ * Branded model ref and directory. Same kind of cast as the session ID: the values are the
+ * resolved catalog ref (a model the host listed) and the app directory `ensureAppDir` returned
+ * (absolute, inside the data root); the host validates both again at runtime.
+ */
+const hostModel = (model: { readonly providerID: string; readonly id: string; readonly variant?: string }): HostModelRef => ({
+  providerID: model.providerID as HostModelRef["providerID"],
+  id: model.id as HostModelRef["id"],
+  ...(model.variant ? { variant: model.variant as NonNullable<HostModelRef["variant"]> } : {}),
+})
+const hostDirectory = (directory: string): HostDirectory => directory as HostDirectory
+
+/**
+ * `ctx.session` as a Promise port. Inputs are built as object literals that must `satisfy` the
+ * host's own parameter types, so a host upgrade that changes them fails `bunx tsc --noEmit`;
+ * the only casts are the branded IDs (session, model, directory), one helper each. The host's effects need no services (it provides them).
+ */
+export function createSessionPort(ctx: HostContext): SessionPort {
+  const run = <A>(effect: Effect.Effect<A, unknown>): Promise<A> => Effect.runPromise(effect)
+  return {
+    create: (input) =>
+      run(
+        ctx.session.create({
+          model: hostModel(input.model),
+          title: input.title,
+          metadata: input.metadata,
+          permissions: input.permissions,
+          location: { directory: hostDirectory(input.directory) },
+        } satisfies HostCreate),
+      ).then((created) => ({ id: String(created.id) })),
+    prompt: (input) =>
+      run(
+        ctx.session.prompt({
+          sessionID: hostSessionID(input.sessionID),
+          text: input.text,
+          files: input.files,
+        } satisfies Parameters<HostSession["prompt"]>[0]),
+      ),
+    interrupt: (sessionID) =>
+      run(ctx.session.interrupt({ sessionID: hostSessionID(sessionID) } satisfies Parameters<HostSession["interrupt"]>[0])).then(() => undefined),
+  }
+}
+
+/**
+ * What the history index needs from the host: the plugin's own key-value storage (`ctx.storage`,
+ * namespaced by plugin id and shared by every Location of the server) and `session.remove`. The
+ * plugin session API has no `list`, so plugboard indexes its own request sessions in that storage
+ * and prunes from the index (src/session/prune.ts).
+ */
+export interface HistoryPort {
+  put(key: string, value: string): Promise<void>
+  drop(key: string): Promise<void>
+  /** Keys under `prefix` in ascending order, after `after` (exclusive); `next` is set when more remain. */
+  scan(input: { readonly prefix: string; readonly after?: string; readonly limit: number }): Promise<{ readonly keys: ReadonlyArray<string>; readonly next?: string }>
+  /** `missing` when the session no longer exists (the host's `Session.NotFoundError`); any other failure rejects. */
+  removeSession(sessionID: string): Promise<"removed" | "missing">
+}
+
+const failureTag = (error: unknown): unknown => (typeof error === "object" && error !== null ? (error as { _tag?: unknown })._tag : undefined)
+
+/** `ctx.storage` and `ctx.session.remove` as a Promise port. The branded session ID is the same host-issued string as above. */
+export function createHistoryPort(ctx: HostContext): HistoryPort {
+  return {
+    put: (key, value) => Effect.runPromise(ctx.storage.set(key, value)),
+    drop: (key) => Effect.runPromise(ctx.storage.remove(key)),
+    scan: (input) =>
+      Effect.runPromise(ctx.storage.scan(input)).then((result) => ({
+        keys: result.entries.map((entry) => entry.key),
+        ...(result.next === undefined ? {} : { next: result.next }),
+      })),
+    removeSession: (sessionID) =>
+      Effect.runPromise(
+        ctx.session.remove({ sessionID: hostSessionID(sessionID) } satisfies Parameters<HostSession["remove"]>[0]).pipe(
+          Effect.match({ onSuccess: () => undefined, onFailure: (error) => ({ error }) }),
+        ),
+      ).then((failed) => {
+        if (failed === undefined) return "removed" as const
+        if (failureTag(failed.error) === "Session.NotFoundError") return "missing" as const
+        throw failed.error
+      }),
+  }
+}
+
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined
+
+/**
+ * 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.
+ */
+function toCatalog(raw: ReadonlyArray<unknown>): CatalogModel[] {
+  const catalog: CatalogModel[] = []
+  for (const item of raw) {
+    const model = record(item)
+    if (!model || model.enabled === false) continue
+    const providerID = model.providerID
+    const id = model.modelID ?? model.id
+    if (typeof providerID !== "string" || typeof id !== "string" || !providerID || !id) continue
+    const variants = (Array.isArray(model.variants) ? model.variants : [])
+      .map((v) => (typeof v === "string" ? v : record(v)?.id))
+      .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
+    catalog.push({
+      providerID,
+      id,
+      ...(typeof model.name === "string" ? { name: model.name } : {}),
+      variants: [...new Set(variants)],
+      ...(caps
+        ? {
+            capabilities: {
+              ...(typeof caps.tools === "boolean" ? { tools: caps.tools } : {}),
+              ...(input ? { image: input.includes("image") } : {}),
+            },
+          }
+        : {}),
+      ...(typeof context === "number" ? { contextLimit: context } : {}),
+    })
+  }
+  return catalog
+}
+
+/** The serving Location's enabled models, as the neutral catalog. */
+export async function loadCatalog(ctx: HostContext): Promise<ReadonlyArray<CatalogModel>> {
+  const listed = await Effect.runPromise(ctx.model.list({}))
+  return toCatalog(listed.data ?? [])
+}
+
+/** One part of a host message. Media parts carry host-built Assets that plugboard passes through untouched. */
+export interface HostPart {
+  readonly type: string
+  readonly [key: string]: unknown
+}
+
+/** A tool descriptor as the `context` hook exposes it. Plugboard rewrites it in place (see `context.ts`). */
+export interface HostToolDescriptor {
+  description: string
+  input: unknown
+}
+
+/**
+ * The parts of the `session.hook("context")` event plugboard reads and writes. The host passes
+ * its mutable `SessionContext`; assigning to these fields is how the hook replaces the model
+ * request. Fields plugboard treats defensively are optional here.
+ */
+export interface ContextHookEvent {
+  readonly sessionID: string
+  system: unknown[]
+  messages?: Array<{ content?: unknown }>
+  options?: Record<string, unknown>
+  tools?: Record<string, HostToolDescriptor>
+}
+
+// Compile-time gate: fails to build when the pinned host's `SessionContext` stops being usable as a `ContextHookEvent`.
+type Assert<T extends true> = T
+export type HostContextMatches = Assert<SessionContext extends ContextHookEvent ? true : false>
+
+/** A flattened bus event: `{ type, ...data }` as routed by the process-wide session store. */
+export type BusEvent = Record<string, unknown>
+
+/** Short readable text for an unknown thrown value. */
+export const describeError = (error: unknown): string => {
+  if (error instanceof Error && error.message) return error.message
+  const text = String(error)
+  return text.length > 400 ? text.slice(0, 400) + "…" : text
+}