opencode-plugboard 0.19.0 → 0.21.0

package/src/runtime.ts

@@ -53,6 +53,7 @@ import { Cause, Effect, Stream } from "effect"
 import stableStringify from "safe-stable-stringify"
 import { raceAbort } from "./abort.js"
 import { cachedCaller, createCacheStore, type CacheStore } from "./cache.js"
+import { personaOf } from "./models.js"
 import type { PlugboardOptions } from "./config.js"
 import { isPlugError, type CatalogModel, type ModelCaller, type PlugError } from "./contract.js"
 import { errorMessage, log, logError, outsideRequest, setLogFormat } from "./log.js"
@@ -63,6 +64,7 @@ import type { HistoryPort } from "./session/host.js"
 import { recordSession, sweepHistory, type HistoryLimits } from "./session/prune.js"
 import { createSessionStore, type SessionStore } from "./session/state.js"
 import { createBudgetState, type BudgetState } from "./budgets.js"
+import { createKeyState, type KeyState } from "./keys.js"
 import { createUsageState, type UsageState } from "./usage.js"
 
 export type Handler = (request: IncomingMessage, response: ServerResponse) => void
@@ -116,8 +118,8 @@ const BACKEND_POLL_MS = 25
 const BIND_RETRY_MS = 15_000
 const BIND_REMINDER_MS = 5 * 60_000
 
-/** 13: the budget warning state (`src/budgets.ts`) lives here too. 12: the live key set (`keys`, `Runtime.keys`) that a stricter newer generation replaces at once (#90). 11: the usage store's live days (`src/usage.ts`) live here too. 10: the response cache store (`src/cache.ts`) lives here too. 9: the request limiter state (`src/limits.ts`) lives here, so the concurrency caps and rate windows survive a generation. 8: `Metrics.render` is async and the registry is @prometheus-io/client's. 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
-const VERSION = 13
+/** 15: the last options error (`configError`, #159) and `catalogLoaded` for `/readyz` (#160). 14: the runtime app keys (src/keys.ts, #55) are cached here, so a key created or revoked through the admin routes holds across plugin generations. 13: the budget warning state (`src/budgets.ts`) lives here too. 12: the live key set (`keys`, `Runtime.keys`) that a stricter newer generation replaces at once (#90). 11: the usage store's live days (`src/usage.ts`) live here too. 10: the response cache store (`src/cache.ts`) lives here too. 9: the request limiter state (`src/limits.ts`) lives here, so the concurrency caps and rate windows survive a generation. 8: `Metrics.render` is async and the registry is @prometheus-io/client's. 7: the options fingerprint comes from safe-stable-stringify, so it must not be compared with an older one. 6: the listener retries a failed bind (new fields on `Listener`). 5: adds the metrics registry and the start time. 4: the history sweep state and the session store's register hook. 3: confirmed directories and rejected generations. */
+const VERSION = 15
 const KEY = Symbol.for("opencode-plugboard.runtime")
 
 interface Listener {
@@ -154,6 +156,12 @@ interface Pump {
   stop(): void
 }
 
+/** A plugin options error and when it was recorded (epoch ms). */
+export interface ConfigError {
+  readonly message: string
+  readonly at: number
+}
+
 interface Runtime {
   readonly version: number
   readonly sessions: SessionStore
@@ -183,6 +191,12 @@ interface Runtime {
   readonly usage: UsageState
   /** The budget warnings already logged (src/budgets.ts). */
   readonly budgets: BudgetState
+  /** The runtime app keys (src/keys.ts), loaded from storage on the first authentication. */
+  readonly runtimeKeys: KeyState
+  /** The last plugin options error (`index.ts`), cleared by the next Location whose options parse (#159). */
+  configError?: ConfigError
+  /** Set once the serving catalog has loaded successfully (`loadServingCatalog`); `/readyz` reads it (#160). */
+  catalogLoaded?: boolean
   listener?: Listener
   /** Present while a fiber is subscribed to the server event bus. */
   pump?: Pump
@@ -197,6 +211,7 @@ const detachedStartedAt = Date.now()
 const detachedLimits = createLimitState()
 const detachedUsage = createUsageState()
 const detachedBudgets = createBudgetState()
+const detachedKeys = createKeyState()
 let foreignVersionLogged = false
 
 /** The process runtime, created on first use; undefined when a different version already owns the process. */
@@ -215,6 +230,7 @@ function runtime(): Runtime | undefined {
       limits: createLimitState(),
       usage: createUsageState(),
       budgets: createBudgetState(),
+      runtimeKeys: createKeyState(),
       startedAt: Date.now(),
     }
     slot[KEY] = created
@@ -299,6 +315,9 @@ export const processUsage = (): UsageState => runtime()?.usage ?? detachedUsage
 /** The budget warning state shared by every generation in the process (detached under a foreign-version runtime). */
 export const processBudgets = (): BudgetState => runtime()?.budgets ?? detachedBudgets
 
+/** The runtime app keys' cache shared by every generation in the process (detached under a foreign-version runtime). */
+export const processKeys = (): KeyState => runtime()?.runtimeKeys ?? detachedKeys
+
 /**
  * The options authentication reads: `keys` is the live key set, not the serving generation's own
  * (a generation that is still live after a key revocation keeps its old keys otherwise, #90).
@@ -336,7 +355,9 @@ export function withResponseCache(caller: ModelCaller, options: PlugboardOptions
       if (rt) rt.cache = held
     }
     const count = options.metrics ? (app: string, result: "hit" | "miss") => processMetrics().cache(app, result) : undefined
-    return cachedCaller(caller, config, held.store, count)
+    // One bypass predicate: a persona model, or an app whose answers depend on live OpenCode tool output (#82).
+    const serverToolApps = new Set(Object.entries(options.apps).filter(([, policy]) => policy.serverTools !== undefined).map(([app]) => app))
+    return cachedCaller(caller, config, held.store, count, (model, app) => personaOf(options, model) !== undefined || serverToolApps.has(app))
   }
   return { stream: (request, context) => (wrapped ??= build()).stream(request, context) }
 }
@@ -348,12 +369,16 @@ export interface RuntimeStatus extends RuntimeSnapshot {
   readonly listener?: { readonly host: string; readonly port: number; readonly bound: boolean }
   /** The serving generation's Location is a confirmed app directory (else the newest generation serves). */
   readonly servingConfirmed: boolean
+  /** The last plugin options error, when its Location was the latest to load the plugin (#159). */
+  readonly configError?: ConfigError
+  /** The serving catalog has loaded at least once in this process (`/readyz`, #160). */
+  readonly catalogLoaded: boolean
 }
 
 /** A synchronous snapshot of the runtime: no host call, no filesystem. */
 export function processStatus(): RuntimeStatus {
   const rt = runtime()
-  if (!rt) return { runtimeVersion: VERSION, generations: 0, pumpRunning: false, guards: detachedSessions.size(), startedAt: detachedStartedAt, servingConfirmed: false }
+  if (!rt) return { runtimeVersion: VERSION, generations: 0, pumpRunning: false, guards: detachedSessions.size(), startedAt: detachedStartedAt, servingConfirmed: false, catalogLoaded: false }
   const serving = preferred(rt)
   return {
     runtimeVersion: rt.version,
@@ -362,10 +387,23 @@ export function processStatus(): RuntimeStatus {
     guards: rt.sessions.size(),
     startedAt: rt.startedAt,
     servingConfirmed: serving !== undefined && rt.confirmed.has(serving.directory),
+    catalogLoaded: rt.catalogLoaded === true,
     ...(rt.listener ? { listener: { host: rt.listener.listen.host, port: rt.listener.listen.port, bound: rt.listener.bound } } : {}),
+    ...(rt.configError ? { configError: rt.configError } : {}),
   }
 }
 
+/**
+ * Records the plugin options error of the Location that just failed to parse its options, or clears
+ * it (`undefined`) once options parse. Synchronous, so plugin setup may call it. The status and
+ * `/readyz` show it while a listener from an earlier good generation still serves (#159).
+ */
+export function setConfigError(message: string | undefined): void {
+  const rt = runtime()
+  if (!rt) return
+  rt.configError = message === undefined ? undefined : { message, at: Date.now() }
+}
+
 /** The generation that serves requests and supplies the catalog: the newest confirmed app-directory one, else the newest. */
 function preferred(rt: Runtime): Generation | undefined {
   for (let index = rt.generations.length - 1; index >= 0; index--) if (rt.confirmed.has(rt.generations[index]!.directory)) return rt.generations[index]
@@ -376,9 +414,11 @@ function preferred(rt: Runtime): Generation | undefined {
  * The catalog of the preferred accepted generation. `fallback` (the caller's own loader) is only
  * used when no generation is registered, which a live request does not normally see.
  */
-export function loadServingCatalog(fallback: () => Promise<ReadonlyArray<CatalogModel>>): Promise<ReadonlyArray<CatalogModel>> {
+export async function loadServingCatalog(fallback: () => Promise<ReadonlyArray<CatalogModel>>): Promise<ReadonlyArray<CatalogModel>> {
   const rt = runtime()
-  return (rt ? (preferred(rt)?.loadCatalog ?? fallback) : fallback)()
+  const models = await (rt ? (preferred(rt)?.loadCatalog ?? fallback) : fallback)()
+  if (rt) rt.catalogLoaded = true
+  return models
 }
 
 /** JSON with object keys sorted at every level, so equal options compare equal whatever their key order (undefined values are left out, as in `JSON.stringify`). */
@@ -512,7 +552,13 @@ export function registerGeneration(input: GenerationInput): Registration {
   } else if (canonicalJson(keys) !== canonicalJson(rt.keys ?? {})) {
     const live = rt.keys ?? {}
     if (rt.generations.length === 0) rt.keys = keys
-    else if (revokesOrRotatesOnly(live, keys)) {
+    else if (Object.keys(keys).length === 0) {
+      // #152: removing the last key fails closed. The old key must not keep working, and the set must not go keyless.
+      if (canonicalJson(live) !== canonicalJson(REVOKED_KEYS)) {
+        log("listener.keys_updated", { removed: Object.keys(live).length, rotated: 0 })
+        rt.keys = REVOKED_KEYS
+      }
+    } else if (revokesOrRotatesOnly(live, keys)) {
       log("listener.keys_updated", {
         removed: Object.keys(live).filter((app) => !Object.hasOwn(keys, app)).length,
         rotated: Object.keys(keys).filter((app) => Object.hasOwn(live, app) && live[app] !== keys[app]).length,
@@ -562,6 +608,13 @@ export function registerGeneration(input: GenerationInput): Registration {
   }
 }
 
+/**
+ * #152: the live key set once the last key is revoked while a generation serves. An empty key set means
+ * keyless, so this one keeps an entry no request can match: `*` is not a valid app name, and its key is
+ * empty, which `Bearer` (it needs a non-empty token) never presents. Every request gets 401 until restart.
+ */
+const REVOKED_KEYS: Readonly<Record<string, string>> = { "*": "" }
+
 /** #90: `next` names no app that `live` lacks, and names at least one app: it only removes or changes keys. */
 function revokesOrRotatesOnly(live: Readonly<Record<string, string>>, next: Readonly<Record<string, string>>): boolean {
   const apps = Object.keys(next)

package/src/session/caller.ts

@@ -18,15 +18,15 @@
 
 import { randomUUID } from "node:crypto"
 import { raceAbort } from "../abort.js"
-import { APP_NAME_PATTERN, DEFAULT_APP, appPolicy, type AppPolicy, type PlugboardOptions } from "../config.js"
+import { APP_NAME_PATTERN, DEFAULT_APP, DEFAULT_SERVER_TOOL_STEPS, appPolicy, type AppPolicy, type PlugboardOptions } 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 { checkAppModel } from "../models.js"
+import { log, logError, logWarn } from "../log.js"
+import { checkAppModel, type Persona } from "../models.js"
 import { RequestCollector } from "./events.js"
 import { ensureAppDir, makeTitle, renderTranscript } from "./history.js"
 import { describeError, type SessionPort } from "./host.js"
 import { ImageError, prepareImages, type RemoteImages } from "./media.js"
-import { REQUEST_PERMISSIONS, seedToolsFor } from "./seeds.js"
+import { requestPermissions, seedToolsFor } from "./seeds.js"
 import type { SessionStore } from "./state.js"
 
 export interface SessionCallerDeps {
@@ -44,6 +44,11 @@ export interface SessionCallerDeps {
    * called right before `session.create`. An error ends the request without creating anything.
    */
   readonly ensureBackend?: (app: string, signal: AbortSignal) => Promise<PlugError | undefined>
+  /**
+   * What the requested name stands for beyond a plain model (`personaOf` in src/models.ts): a skill alias adds
+   * the skill's content to the system prompt, an agent runs its own system prompt and OpenCode agent.
+   */
+  readonly persona?: (model: string) => Persona | undefined
 }
 
 /** How long the request guard may outlive the response while the host has not reported the end of the execution. */
@@ -54,6 +59,8 @@ const failure = (status: number, message: string, code: string): PlugEvent => ({
   error: { status, kind: status >= 500 ? "server" : "invalid_request", message, code },
 })
 
+const notFound = (message: string): PlugError => ({ status: 404, kind: "not_found", message, code: "model_not_found", param: "model" })
+
 const countMedia = (request: PlugRequest): number =>
   request.messages.reduce((sum, message) => sum + message.content.filter((part) => part.type === "media").length, 0)
 
@@ -99,6 +106,33 @@ function checkAppTools(request: PlugRequest, app: string, policy: AppPolicy | un
     message: `Request has ${request.tools.length} tools; app ${app} allows ${max} (option \`apps.${app}.maxTools\`)`,
   }
 }
+/** A caller tool may not share a name with one of the app's server tools: the model would see two tools under one name. */
+function checkServerToolNames(request: PlugRequest, policy: AppPolicy | undefined): PlugError | undefined {
+  const clash = request.tools.find((tool) => policy?.serverTools?.includes(tool.name))
+  if (!clash) return undefined
+  return {
+    status: 400,
+    kind: "invalid_request",
+    code: "server_tool_collision",
+    param: "tools",
+    message: `Tool \`${clash.name}\` is one of this app's OpenCode server tools (option \`apps.<name>.serverTools\`); rename the caller's tool`,
+  }
+}
+
+/** Every server tool must be a direct tool of this location right now (fail closed; checked per request, never at setup). */
+async function checkServerToolsAvailable(port: SessionPort, policy: AppPolicy | undefined, signal: AbortSignal): Promise<PlugError | undefined> {
+  if (!policy?.serverTools) return undefined
+  const offered = new Set(await raceAbort(port.directTools(), signal))
+  const missing = policy.serverTools.filter((tool) => !offered.has(tool))
+  if (missing.length === 0) return undefined
+  return {
+    status: 400,
+    kind: "invalid_request",
+    code: "server_tool_unavailable",
+    message: `OpenCode tool(s) not available in this location: ${missing.join(", ")} (option \`apps.<name>.serverTools\`). CodeMode tools, including MCP tools by default, cannot be listed; set codemode: false on the tool`,
+  }
+}
+
 export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
   const { port, sessions, maxTools, ensureBackend } = deps
   const apps = deps.apps ?? {}
@@ -113,9 +147,12 @@ export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
       const requestID = randomUUID()
       const startedAt = Date.now()
       let outcome = "cancelled"
+      // Whether the model produced anything at all (text, reasoning or a tool call), for `answer.empty` (#172).
+      let produced = false
       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}` : ""}`
+        else produced = true
         return event
       }
 
@@ -123,9 +160,11 @@ export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
       const policy = appPolicy({ apps }, app)
       const outOfScope = checkAppModel(policy, called.model, called.ref)
       if (outOfScope) return yield note({ type: "error", error: outOfScope })
-      const { request, stripped } = applyToolPolicy(called, policy)
+      let { request, stripped } = applyToolPolicy(called, policy)
       const tooMany = checkAppTools(request, app, policy)
       if (tooMany) return yield note({ type: "error", error: tooMany })
+      const clash = checkServerToolNames(request, policy)
+      if (clash) return yield note({ type: "error", error: clash })
       if (stripped) {
         try {
           context.onPolicy?.(["tools-stripped"])
@@ -165,24 +204,60 @@ export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
         const unavailable = await ensureBackend?.(app, context.signal)
         if (unavailable) return yield note({ type: "error", error: unavailable })
         if (context.signal.aborted) return
+        const missingServerTools = await checkServerToolsAvailable(port, policy, context.signal)
+        if (missingServerTools) return yield note({ type: "error", error: missingServerTools })
+        if (context.signal.aborted) return
+
+        // 3b. A persona (see `Persona`). A skill's content leads the system prompt; an agent's prompt replaces the
+        // caller's, and the session runs as that agent. Its permissions are still REQUEST_PERMISSIONS (deny all, then seeds).
+        const persona = deps.persona?.(called.model)
+        let prelude: ReadonlyArray<string> = []
+        if (persona?.kind === "skill") {
+          const content = await port.skill(directory, persona.skill)
+          if (content === undefined) return yield note({ type: "error", error: notFound(`Skill ${persona.skill} is not available`) })
+          prelude = [content]
+        } else if (persona?.kind === "agent") {
+          const agent = await port.agent(directory, persona.agent)
+          if (agent === undefined) return yield note({ type: "error", error: notFound(`Agent ${persona.agent} is not available`) })
+          request = { ...request, system: agent.system ? [agent.system] : [] }
+        }
+        if (context.signal.aborted) return
+
+        collector = new RequestCollector({
+          stopTurn: interrupt,
+          requestID,
+          app,
+          ...(policy?.serverTools
+            ? { serverTools: new Set(policy.serverTools), maxServerToolSteps: policy.maxServerToolSteps ?? DEFAULT_SERVER_TOOL_STEPS }
+            : {}),
+        })
 
-        collector = new RequestCollector({ stopTurn: interrupt, requestID })
-        const created = await raceAbort(port.create({
+        const creating = port.create({
           directory,
           model: { providerID: request.ref.providerID, id: request.ref.id, ...(request.ref.variant ? { variant: request.ref.variant } : {}) },
+          ...(persona?.kind === "agent" ? { agent: persona.agent } : {}),
           title: makeTitle(request),
           metadata: { plugboard: { app, model: request.model, requestID } },
-          permissions: REQUEST_PERMISSIONS,
-        }), context.signal)
+          permissions: requestPermissions(policy?.serverTools ?? []),
+        })
+        const created = await raceAbort(creating, context.signal).catch((error) => {
+          // The host keeps creating after the abort. A session that lands now is in no index, so it is removed.
+          if (context.signal.aborted)
+            void creating.then(
+              (late) => port.remove(late.id).catch((removeError) => logError("session.late_remove_failed", { requestID, app, sessionID: late.id, error: describeError(removeError) })),
+              () => {},
+            )
+          throw error
+        })
         sessionID = String(created.id)
-        sessions.register({ sessionID, app, requestID, request, collector })
+        sessions.register({ sessionID, app, requestID, request, collector, prelude })
 
         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)
+          context.onRecord?.(sessionID, directory)
         } catch (error) {
           logError("request.on_record_failed", { requestID, app, error: describeError(error) })
         }
@@ -217,6 +292,16 @@ export function createSessionCaller(deps: SessionCallerDeps): ModelCaller {
           if (promptStarted) sessions.retire(sessionID, { timeoutMs: CLEANUP_TIMEOUT_MS, onTimeout: interrupt })
           else sessions.release(sessionID)
         }
+        const serverToolCalls = collector?.serverCallCount ?? 0
+        if (serverToolCalls > 0 && context.onServerTools) {
+          try {
+            context.onServerTools(serverToolCalls)
+          } catch (error) {
+            logError("request.on_server_tools_failed", { requestID, app, error: describeError(error) })
+          }
+        }
+        // A turn that stopped with nothing in it is kept as a session for inspection: the session id finds it.
+        if (outcome === "finish:stop" && !produced) logWarn("answer.empty", { requestID, app, model: request.model, sessionID, tools: request.tools.length })
         log("request.finished", { requestID, app, model: request.model, durationMs: Date.now() - startedAt, outcome })
       }
     },

package/src/session/context.ts

@@ -59,10 +59,13 @@ function generationOptions(request: PlugRequest): Record<string, unknown> {
  * 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 app's `serverTools` (option `apps`) are kept as the host offered them: their descriptors were
+ * never rewritten, so the host runs the real tool. Not offered when the caller set `tool_choice` none.
+ *
  * 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 {
+function remapSeedTools(session: ContextHookEvent, request: PlugRequest, serverTools: ReadonlyArray<string>): number {
   const seeds = Object.entries(session.tools ?? {}).filter(([name]) => name.startsWith(SEED_PREFIX))
   const tools = seedToolsFor(request)
   const next = new Map<string, HostToolDescriptor>()
@@ -77,8 +80,16 @@ function remapSeedTools(session: ContextHookEvent, request: PlugRequest): number
     descriptor.input = tool.parameters
     next.set(tool.name, descriptor)
   }
+  const missing = tools.length - next.size
+  if (request.toolChoice !== "none") {
+    const offered = session.tools ?? {}
+    for (const name of serverTools) {
+      if (!Object.hasOwn(offered, name) || next.has(name)) continue
+      next.set(name, offered[name] as HostToolDescriptor)
+    }
+  }
   session.tools = Object.fromEntries(next)
-  return tools.length - next.size
+  return missing
 }
 
 /**
@@ -109,6 +120,7 @@ function applyContext(event: unknown, sessions: SessionStore, apps: PlugboardOpt
   const state = sessions.lookup(String(session.sessionID))
   if (!state) return
   const { request } = state
+  const policy = appPolicy({ apps }, state.app)
 
   // Swap media placeholders for the Asset-carrying parts the host built from the prompt files.
   const hostMedia = (session.messages ?? [])
@@ -123,7 +135,9 @@ function applyContext(event: unknown, sessions: SessionStore, apps: PlugboardOpt
     return text("[image unavailable]")
   }
 
-  const system = systemFor(request.system, appPolicy({ apps }, state.app)).map(text)
+  // Order: the skill's content (prelude), then the app's system policy over the caller's (or an agent's) prompt,
+  // then the tool-choice steering below.
+  const system = [...(state.prelude ?? []), ...systemFor(request.system, policy)].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."))
@@ -132,7 +146,7 @@ function applyContext(event: unknown, sessions: SessionStore, apps: PlugboardOpt
   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)
+  const missingTools = remapSeedTools(session, request, policy?.serverTools ?? [])
 
   // 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.

package/src/session/events.ts

@@ -6,13 +6,18 @@
  * 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.step.ended`) with at least one caller 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`.
+ *
+ * A call to one of the app's `serverTools` is not the caller's: OpenCode runs it, the runner starts
+ * the next step with its result, and the collector neither emits it nor stops the turn. A step with
+ * only server calls continues; a step that also holds a caller call is returned to the caller as usual.
+ * Server steps are counted and capped (`maxServerToolSteps`); each server call is logged once.
  */
 
 import { isPlugError, type PlugError, type PlugEvent, type PlugFinish, type PlugUsage } from "../contract.js"
-import { logError } from "../log.js"
+import { log, logError } from "../log.js"
 import type { BusEvent } from "./host.js"
 import { FAILURE_EVENT } from "./state.js"
 
@@ -145,6 +150,18 @@ const toUsage = (tokens?: RawUsage): PlugUsage | undefined =>
 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
 
+/**
+ * Provider wording that the status does not settle (#171). A ChatGPT subscription at its limit is a
+ * `provider.invalid-request` with `subscription_sharing_usage_limit_exceeded` and no status. These
+ * are matched on the message and the raw body, and only ever decide a class; the text never leaves.
+ */
+const USAGE_LIMIT = /usage[_ ]limit|quota/i
+const RATE_LIMIT = /rate[_ ]limit|too many requests/i
+const AUTH_FAILURE = /unauthori[sz]ed|invalid[_ ]api[_ ]key|incorrect api key|not logged in|log in again|sign in|permission denied/i
+const MODEL_NOT_FOUND = /model[^\n]{0,60}(?:not found|does not exist|not supported|unknown)|unknown model|model_not_found/i
+
+const AUTH_MESSAGE = "The model provider rejected its credentials; the plugboard host needs to sign in again"
+
 /**
  * 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:
@@ -167,10 +184,9 @@ function toPlugError(error: RawError | undefined, fallback: string): PlugError {
     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 (status === 401) return { status, kind: "authentication", code: "provider_auth_failed", message: AUTH_MESSAGE }
+    if (status === 403) return { status, kind: "permission", code: "provider_auth_failed", message: AUTH_MESSAGE }
+    return { status: 502, kind: "server", code: "provider_auth_failed", message: AUTH_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" }
@@ -179,6 +195,11 @@ function toPlugError(error: RawError | undefined, fallback: string): PlugError {
     return { status: 504, kind: "timeout", code: "provider_timeout", message: "The model provider timed out" }
   }
   if (type.startsWith("provider.")) {
+    const detail = `${error?.message ?? ""}\n${error?.response?.body ?? ""}`
+    if (USAGE_LIMIT.test(detail)) return { status: 429, kind: "rate_limit", code: "quota_exceeded", message: "The model provider's usage quota is exhausted" }
+    if (RATE_LIMIT.test(detail)) return { status: 429, kind: "rate_limit", code: "rate_limited", message: "The model provider is rate limiting requests; retry later" }
+    if (MODEL_NOT_FOUND.test(detail)) return { status: 404, kind: "not_found", code: "model_not_found", param: "model", message: "The model provider does not know the requested model" }
+    if (AUTH_FAILURE.test(detail)) return { status: 502, kind: "server", code: "provider_auth_failed", message: AUTH_MESSAGE }
     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" }
@@ -191,6 +212,18 @@ export interface CollectorHooks {
   readonly stopTurn: () => void
   /** The request's id, for the log line that carries a failure's raw host text. */
   readonly requestID?: string
+  /** The app, for the `server_tool.call` log lines. */
+  readonly app?: string
+  /** The app's `serverTools` (option `apps`): OpenCode runs these calls, the caller never sees them. */
+  readonly serverTools?: ReadonlySet<string>
+  /** Steps that may run server tools before the turn is stopped. The owner passes it with `serverTools`. */
+  readonly maxServerToolSteps?: number
+}
+
+interface ServerCall {
+  readonly name: string
+  readonly startedAt: number
+  done: boolean
 }
 
 export class RequestCollector {
@@ -198,6 +231,9 @@ export class RequestCollector {
   private readonly emittedText = new Map<number, number>()
   private readonly toolNames = new Map<string, string>()
   private readonly calls = new Set<string>()
+  private readonly serverCalls = new Map<string, ServerCall>()
+  private stepServerCalls = 0
+  private serverSteps = 0
   private usage?: RawUsage
   private finished = false
   private executionDone = false
@@ -221,6 +257,11 @@ export class RequestCollector {
     return this.settled
   }
 
+  /** How many server tool calls OpenCode ran in this session (each counted when it started). */
+  get serverCallCount(): number {
+    return this.serverCalls.size
+  }
+
   /** True once the owner cancelled the request (client gone or timeout). */
   get cancelled(): boolean {
     return this.wasCancelled
@@ -274,23 +315,48 @@ export class RequestCollector {
       case "session.tool.called": {
         if (this.finished) return
         const id = String(item.id)
-        if (this.calls.has(id)) return
+        if (this.calls.has(id) || this.serverCalls.has(id)) return
+        const name = String(item.name ?? this.toolNames.get(id) ?? "")
+        if (this.hooks.serverTools?.has(name)) {
+          this.serverCalls.set(id, { name, startedAt: Date.now(), done: false })
+          this.stepServerCalls++
+          return
+        }
         this.calls.add(id)
-        this.emit({ type: "tool-call", id, name: String(item.name ?? this.toolNames.get(id) ?? ""), input: item.input })
+        this.emit({ type: "tool-call", id, name, input: item.input })
+        return
+      }
+      case "session.tool.success":
+      case "session.tool.failed": {
+        const call = this.serverCalls.get(String(item.id))
+        if (!call || call.done) return
+        call.done = true
+        log("server_tool.call", {
+          requestID: this.hooks.requestID,
+          app: this.hooks.app,
+          tool: call.name,
+          durationMs: Date.now() - call.startedAt,
+          ok: item.type === "session.tool.success",
+        })
         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":
+      case "session.step.ended": {
         this.usage = (item.tokens as RawUsage | undefined) ?? this.usage
+        const serverCalls = this.stepServerCalls
+        this.stepServerCalls = 0
         // 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))
+        const reason = toFinish(item.finish)
+        if (this.calls.size === 0 && serverCalls > 0) return this.serverStepEnded(reason)
+        if (this.calls.size === 0 && reason === "stop") this.settled = true
+        this.finishWith(withCalls(reason, 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)
@@ -308,12 +374,14 @@ export class RequestCollector {
       }
       case "session.execution.failed":
         this.executionDone = true
+        this.logUnfinishedServerCalls()
         if (!this.finished) this.failFromHost(item.error as RawError | undefined, "Session execution failed")
         this.end()
         return
       case "session.execution.interrupted":
       case "session.execution.succeeded":
         this.executionDone = true
+        this.logUnfinishedServerCalls()
         if (!this.finished) {
           if (this.calls.size > 0) this.finishWith("tool-calls")
           else if (this.wasCancelled) this.end()
@@ -346,16 +414,52 @@ export class RequestCollector {
     this.end()
   }
 
+  /**
+   * A step that ran only server tools: the runner starts the next step with their results. The cap is
+   * checked on each such step; past it the request fails and the turn is stopped.
+   */
+  private serverStepEnded(reason: PlugFinish): void {
+    this.serverSteps++
+    if (this.serverSteps > (this.hooks.maxServerToolSteps ?? 0)) {
+      this.abort({
+        status: 502,
+        kind: "server",
+        code: "server_tool_steps_exceeded",
+        message: "The model used more OpenCode tool steps than this app allows",
+      })
+      return
+    }
+    if (reason === "stop" || reason === "tool-calls") return
+    this.finishWith(reason)
+  }
+
+  /** Server calls the execution ended before they reported back are logged as not ok, once each. */
+  private logUnfinishedServerCalls(): void {
+    for (const call of this.serverCalls.values()) {
+      if (call.done) continue
+      call.done = true
+      log("server_tool.call", {
+        requestID: this.hooks.requestID,
+        app: this.hooks.app,
+        tool: call.name,
+        durationMs: Date.now() - call.startedAt,
+        ok: false,
+      })
+    }
+  }
+
   /** 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
+    const error = toPlugError(raw, fallback)
     logError("model.failed", {
       requestID: this.hooks.requestID,
       type: raw?.type,
       status: raw?.status,
+      code: error.code,
       message: raw?.message?.slice(0, 500),
     })
-    this.fail(toPlugError(raw, fallback))
+    this.fail(error)
   }
 
   private fail(error: PlugError): void {