opencode-plugboard 0.0.0-stage → 0.3.0

package/src/session/caller.ts

@@ -0,0 +1,192 @@
+/**
+ * The session-backed `ModelCaller`: one model call = one kept OpenCode session in the caller
+ * app's directory under the data root, one model step.
+ *
+ * Lifecycle of `stream()`: validate the app name, prepare images, create the session, register
+ * its request state, start the prompt, then relay the collector's events until it is terminal.
+ * Abort is checked before every side effect (directory, backend, create, register, prompt), and
+ * the awaited host call (create) is raced against the request signal; teardown never is.
+ * Request sessions are registered in the process-wide session store (`state.ts`) so the
+ * app-directory hook (`context.ts`) and the event pump can find them.
+ *
+ * The response and the host execution have different lifetimes (docs/architecture.md). When the
+ * response is over, `finally` interrupts unless the host already reported the end of the
+ * execution or the turn settled with a plain stop (a step can fail while the runner goes on) and hands the store entry, the
+ * request guard, to `sessions.retire`: it stays until the host reports the end of the execution
+ * or a bounded cleanup runs out (logged). Nothing here waits for that.
+ */
+
+import { randomUUID } from "node:crypto"
+import { APP_NAME_PATTERN, DEFAULT_APP } from "../config.js"
+import { isPlugError, type CallContext, type ModelCaller, type PlugError, type PlugEvent, type PlugRequest } from "../contract.js"
+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 { REQUEST_PERMISSIONS, seedToolsFor } from "./seeds.js"
+import type { SessionStore } from "./state.js"
+
+export interface SessionCallerDeps {
+  readonly port: SessionPort
+  /** The process-wide store request sessions are registered in. */
+  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
+  /**
+   * 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.
+   */
+  readonly ensureBackend?: (app: string, signal: AbortSignal) => Promise<PlugError | undefined>
+}
+
+/** How long the request guard may outlive the response while the host has not reported the end of the execution. */
+const CLEANUP_TIMEOUT_MS = 30_000
+
+const failure = (status: number, message: string, code: string): PlugEvent => ({
+  type: "error",
+  error: { status, kind: status >= 500 ? "server" : "invalid_request", message, code },
+})
+
+const countMedia = (request: PlugRequest): number =>
+  request.messages.reduce((sum, message) => sum + message.content.filter((part) => part.type === "media").length, 0)
+
+/** Everything the hook will need must exist before dispatch: one prompt file per image, one seed tool per offered tool. */
+function checkPreparation(request: PlugRequest, images: number, maxTools: number): PlugError | undefined {
+  const wanted = countMedia(request)
+  if (images !== wanted) {
+    return { status: 500, kind: "server", code: "backend_preparation_failed", message: `Prepared ${images} attachment(s) for a request with ${wanted}` }
+  }
+  const tools = seedToolsFor(request).length
+  if (tools > maxTools) {
+    return {
+      status: 400,
+      kind: "invalid_request",
+      code: "backend_preparation_failed",
+      param: "tools",
+      message: `The request offers ${tools} tools but plugboard supports at most ${maxTools} (option \`maxTools\`)`,
+    }
+  }
+  return undefined
+}
+
+/** Settles with `promise`, or rejects as soon as `signal` aborts. Request side only: the promise itself keeps running. */
+function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  promise.catch(() => {}) // a late rejection after the race was lost must not become unhandled
+  if (signal.aborted) return Promise.reject(signal.reason)
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason)
+    signal.addEventListener("abort", onAbort, { once: true })
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort))
+  })
+}
+
+export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
+  const { port, sessions, maxTools, ensureBackend } = deps
+  const remoteImages = deps.remoteImages === true
+
+  return {
+    async *stream(request: PlugRequest, context: CallContext): AsyncGenerator<PlugEvent> {
+      const app = APP_NAME_PATTERN.test(context.app) || context.app === DEFAULT_APP ? context.app : undefined
+      if (!app) return yield failure(400, `Invalid app name: ${context.app}`, "invalid_app")
+      if (context.signal.aborted) return
+
+      const requestID = randomUUID()
+      const startedAt = Date.now()
+      let outcome = "cancelled"
+      const note = (event: PlugEvent): PlugEvent => {
+        if (event.type === "finish") outcome = `finish:${event.reason}`
+        else if (event.type === "error") outcome = `error:${event.error.status}${event.error.code ? `:${event.error.code}` : ""}`
+        return event
+      }
+
+      let sessionID: string | undefined
+      let collector: RequestCollector | undefined
+      let promptStarted = false
+      let interruptRequested = false
+      const interrupt = () => {
+        if (sessionID) {
+          interruptRequested = true
+          void port.interrupt(sessionID).catch((error) => logError("session.interrupt_failed", { requestID, app, error: describeError(error) }))
+        }
+      }
+      const onAbort = () => {
+        collector?.cancel()
+        interrupt()
+      }
+
+      try {
+        // 1. Prompt files: images become data URLs (http(s) ones are fetched once).
+        const images = await prepareImages(request, context.signal, remoteImages)
+        const invalid = checkPreparation(request, images.length, maxTools)
+        if (invalid) return yield note({ type: "error", error: invalid })
+
+        // 2. The app directory under the data root; one top-level session per request.
+        if (context.signal.aborted) return
+        const directory = await ensureAppDir(app)
+        if (isPlugError(directory)) return yield note({ type: "error", error: directory })
+
+        // 3. The backend must be able to run the session before it is created.
+        if (context.signal.aborted) return
+        const unavailable = await ensureBackend?.(app, context.signal)
+        if (unavailable) return yield note({ type: "error", error: unavailable })
+        if (context.signal.aborted) return
+
+        collector = new RequestCollector({ stopTurn: interrupt })
+        const created = await raceAbort(port.create({
+          directory,
+          model: { providerID: request.ref.providerID, id: request.ref.id, ...(request.ref.variant ? { variant: request.ref.variant } : {}) },
+          title: makeTitle(request),
+          metadata: { plugboard: { app, model: request.model, requestID } },
+          permissions: REQUEST_PERMISSIONS,
+        }), context.signal)
+        sessionID = String(created.id)
+        sessions.register({ sessionID, app, requestID, request, collector })
+
+        context.signal.addEventListener("abort", onAbort, { once: true })
+        if (context.signal.aborted) return onAbort()
+
+        // The history id is known from here on: tell the front-end before the first event.
+        try {
+          context.onRecord?.(sessionID)
+        } catch (error) {
+          logError("request.on_record_failed", { requestID, app, error: describeError(error) })
+        }
+
+        // 4. Prompt concurrently; events stream through the collector while it runs.
+        if (context.signal.aborted) return onAbort()
+        const owned = collector
+        promptStarted = true
+        void port.prompt({ sessionID, text: renderTranscript(request), files: images }).catch((error) => {
+          logError("session.prompt_failed", { requestID, app, model: request.model, error: describeError(error) })
+          if (owned.terminal) return
+          owned.push({ type: "session.execution.failed", error: { type: "prompt_failed", message: "Could not start the model session" } })
+        })
+
+        for await (const event of collector.events()) yield note(event)
+      } catch (error) {
+        if (error instanceof ImageError) yield note(failure(400, error.message, error.code))
+        else if (!context.signal.aborted) {
+          logError("request.backend_failed", { requestID, app, model: request.model, error: describeError(error) })
+          yield note(failure(502, "plugboard session backend failed", "backend_failed"))
+        }
+      } finally {
+        context.signal.removeEventListener("abort", onAbort)
+        if (sessionID && collector) {
+          // The response may be over (consumer left early, error, timeout, a failed step) while the
+          // host keeps running the session: interrupt unless it reported the end of the execution
+          // or the step ended plainly (the runner stops by itself), and only if no interrupt went
+          // out yet (the tool-calls path asked at the step end already).
+          if (!collector.terminal) collector.cancel()
+          if (!collector.executionEnded && !collector.turnSettled && !interruptRequested) interrupt()
+          // The response ends here, the host execution may not have: the guard is kept until it does.
+          if (promptStarted) sessions.retire(sessionID, { timeoutMs: CLEANUP_TIMEOUT_MS, onTimeout: interrupt })
+          else sessions.release(sessionID)
+        }
+        log("request.finished", { requestID, app, model: request.model, durationMs: Date.now() - startedAt, outcome })
+      }
+    },
+  }
+}

package/src/session/context.ts

@@ -0,0 +1,175 @@
+/**
+ * Context hook and seed tools: what plugboard installs inside the app directories, and what the
+ * `session.hook("context")` hook does for a plugboard request session.
+ *
+ * The stored prompt is only a readable transcript. The hook swaps in the caller's real
+ * structured system, messages, tool definitions and generation options. Sessions that are not
+ * plugboard requests (not in the process-wide session store) are untouched.
+ */
+
+import { Effect } from "effect"
+import type { PlugError, PlugMessage, PlugRequest } from "../contract.js"
+import type { ContextHookEvent, HostContext, HostPart, HostToolDescriptor } from "./host.js"
+import { SEED_PREFIX, SEED_RESULT, seedToolsFor } from "./seeds.js"
+import { FAILURE_EVENT, type SessionStore } from "./state.js"
+
+const text = (value: string): HostPart => ({ type: "text", text: value })
+
+/** Placeholder for a caller image; swapped for the host-built media part in `applyContext`. */
+const mediaPlaceholder = (index: number): HostPart => ({ type: "media", __attachment: index })
+
+/** Caller messages as host `Message` objects. Media placeholders are swapped in `applyContext`. */
+function toHostMessages(messages: ReadonlyArray<PlugMessage>): Array<{ role: string; content: HostPart[] }> {
+  let image = 0
+  const part = (item: PlugMessage["content"][number]): HostPart => {
+    switch (item.type) {
+      case "text":
+        return text(item.text)
+      case "media":
+        return mediaPlaceholder(image++)
+      case "tool-call":
+        return { type: "tool-call", id: item.id, name: item.name, input: item.input }
+      case "tool-result":
+        return { type: "tool-result", id: item.id, name: item.name, result: { type: "text", value: item.result } }
+    }
+  }
+  return messages.map((message) => ({ role: message.role, content: message.content.map(part) }))
+}
+
+function generationOptions(request: PlugRequest): Record<string, unknown> {
+  const generation = request.generation
+  const options: Record<string, unknown> = {}
+  if (generation.maxTokens !== undefined) options.maxTokens = generation.maxTokens
+  if (generation.temperature !== undefined) options.temperature = generation.temperature
+  if (generation.topP !== undefined) options.topP = generation.topP
+  if (generation.stop !== undefined) options.stop = [...generation.stop]
+  if (generation.presencePenalty !== undefined) options.presencePenalty = generation.presencePenalty
+  if (generation.frequencyPenalty !== undefined) options.frequencyPenalty = generation.frequencyPenalty
+  return options
+}
+
+/**
+ * Re-key the registered seed tools onto the caller's tool names.
+ *
+ * Descriptor object identity is load-bearing: the host maps a rewritten tool back to its
+ * registered tool by the descriptor object it handed to the hook (upstream
+ * `model-request.ts`, tool mapping after the `context` hook), so the descriptors are mutated in
+ * place and the very same objects are re-inserted under the caller's names. Never copy them.
+ * Returns how many caller tools got no seed (zero unless the seed pool is smaller than the request
+ * needs, or two caller tools share a name and would collapse into one key).
+ *
+ * The map is built with `Object.fromEntries`: a tool named `__proto__` becomes an own key like any
+ * other instead of assigning the prototype and vanishing.
+ */
+function remapSeedTools(session: ContextHookEvent, request: PlugRequest): number {
+  const seeds = Object.entries(session.tools ?? {}).filter(([name]) => name.startsWith(SEED_PREFIX))
+  const tools = seedToolsFor(request)
+  const next = new Map<string, HostToolDescriptor>()
+  let index = 0
+  for (const tool of tools) {
+    const seed = seeds[index]
+    if (!seed) break
+    index++
+    if (next.has(tool.name)) continue
+    const descriptor = seed[1]
+    descriptor.description = tool.description
+    descriptor.input = tool.parameters
+    next.set(tool.name, descriptor)
+  }
+  session.tools = Object.fromEntries(next)
+  return tools.length - next.size
+}
+
+const preparationFailed = (message: string): PlugError => ({ status: 500, kind: "server", code: "backend_preparation_failed", message })
+
+/**
+ * `session.hook("context")` body: swap the request session's system, messages, tools and
+ * generation options for the caller's.
+ */
+function applyContext(event: unknown, sessions: SessionStore): void {
+  // Assumed invariant: the host passes its mutable `SessionContext` (checked structurally by `HostContextMatches`).
+  const session = event as ContextHookEvent
+  const state = sessions.lookup(String(session.sessionID))
+  if (!state) return
+  const { request } = state
+
+  // Swap media placeholders for the Asset-carrying parts the host built from the prompt files.
+  const hostMedia = (session.messages ?? [])
+    .flatMap((message) => (Array.isArray(message.content) ? (message.content as unknown[]) : []))
+    .filter((part) => (part as HostPart | undefined)?.type === "media")
+  let missingMedia = 0
+  const swap = (part: HostPart) => {
+    if (typeof part.__attachment !== "number") return part
+    const media = hostMedia[part.__attachment]
+    if (media) return media
+    missingMedia++
+    return text("[image unavailable]")
+  }
+
+  const system = request.system.map(text)
+  // The OpenCode session API has no tool-choice control, so a forced or required tool is steered by instruction.
+  const choice = request.toolChoice
+  if (choice === "required") system.push(text("You must respond by calling one of the provided tools."))
+  if (typeof choice === "object") system.push(text(`You must respond by calling the \`${choice.name}\` tool.`))
+  session.system = system
+  session.messages = toHostMessages(request.messages).map((message) => ({ ...message, content: message.content.map(swap) }))
+  Object.assign(session.options ?? (session.options = {}), generationOptions(request))
+
+  const missingTools = remapSeedTools(session, request)
+
+  // The caller validates both before dispatch; this only fires if the host disagrees. The request is
+  // already rewritten (no real tool can run); fail it instead of answering from a truncated prompt.
+  if (missingMedia > 0 || missingTools > 0) {
+    const detail = [missingMedia > 0 ? `${missingMedia} attachment(s) not delivered by the host` : "", missingTools > 0 ? `${missingTools} tool(s) without a seed tool` : ""]
+    state.collector.push({
+      type: FAILURE_EVENT,
+      error: preparationFailed(`Could not prepare the model request: ${detail.filter(Boolean).join(", ")}`),
+    })
+  }
+}
+
+/**
+ * Registrations for a plugboard Location: the context hook, the agent deny for the seeds, and
+ * the seed tool pool.
+ *
+ * Whether the Location is inside the data root is only known after an asynchronous filesystem
+ * check (never during setup), so these are registered for every accepted generation and every
+ * one of them stays a no-op until `active()` turns true: the hook leaves sessions alone, the
+ * transforms add and change nothing. `active` is read synchronously on every run; the owner
+ * rebuilds the transforms (`ctx.agent.reload()`, `ctx.tool.reload()`) after it flips.
+ *
+ * Every agent denies the seeds; request sessions are created with a session permission that
+ * allows them again, so a person prompting inside an app directory is never offered them.
+ * Registration only: no host call that waits on readiness (see docs/architecture.md).
+ */
+export function installSessionHooks(
+  ctx: HostContext,
+  options: { readonly maxTools: number; readonly sessions: SessionStore; readonly active: () => boolean },
+) {
+  return Effect.gen(function* () {
+    // Swap in the caller's system/messages/tools for plugboard request sessions only.
+    yield* ctx.session.hook("context", (event) => Effect.sync(() => (options.active() ? applyContext(event, options.sessions) : undefined)))
+
+    yield* ctx.agent.transform((editor) => {
+      if (!options.active()) return
+      for (const agent of editor.list()) {
+        editor.update(agent.id, (item) => {
+          item.permissions.push({ action: `${SEED_PREFIX}*`, resource: "*", effect: "deny" })
+        })
+      }
+    })
+    yield* ctx.tool.transform((editor) => {
+      if (!options.active()) return
+      for (let index = 0; index < options.maxTools; index++) {
+        editor.add({
+          name: `${SEED_PREFIX}${index}`,
+          description: "Plugboard placeholder tool.",
+          input: { type: "object", properties: {}, additionalProperties: true },
+          options: { codemode: false },
+          // Settles at once so history shows a completed call; plugboard ends the turn itself (see seeds.ts).
+          execute: () => Effect.succeed({ content: SEED_RESULT }),
+        })
+      }
+    })
+  })
+}