@moondeck/station 0.0.1 → 1.0.1

package/lib/agents/mock.ts

@@ -0,0 +1,133 @@
+/**
+ * MockAgentSession — a fake AgentSession for building and testing the
+ * chat pipeline without Docker or a real CLI.
+ *
+ * On send(), it streams a few `message_delta` chunks, sometimes a
+ * `tool_call` card, then `message_complete` + `turn_complete`. Enough
+ * shape that the orchestrator, SSE stream, and chat UI can all be
+ * exercised end to end. The real ClaudeSession / CodexSession adapters
+ * replace this behind the identical interface.
+ */
+
+import { newId } from "../ulid";
+import type {
+  AgentEvent,
+  AgentEventHandler,
+  AgentKind,
+  AgentSession,
+  AgentSessionFactory,
+  RosterAgent,
+} from "./types";
+
+/** Tunable so tests can run instantly while dev feels lifelike. */
+const DELTA_INTERVAL_MS = Number(process.env.UAI_MOCK_DELTA_MS ?? 60);
+
+export class MockAgentSession implements AgentSession {
+  readonly agentId: string;
+  readonly kind: AgentKind;
+
+  private readonly handlers = new Set<AgentEventHandler>();
+  private readonly timers = new Set<ReturnType<typeof setTimeout>>();
+  private closed = false;
+  private turn = 0;
+
+  constructor(args: { agent: RosterAgent; systemPreamble: string }) {
+    this.agentId = args.agent.id;
+    this.kind = args.agent.kind;
+  }
+
+  onEvent(handler: AgentEventHandler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  private emit(event: AgentEvent): void {
+    if (this.closed) return;
+    for (const h of this.handlers) h(event);
+  }
+
+  /** schedule(fn, ms) — like setTimeout but cleaned up on close(). */
+  private schedule(fn: () => void, ms: number): void {
+    const t = setTimeout(() => {
+      this.timers.delete(t);
+      if (!this.closed) fn();
+    }, ms);
+    this.timers.add(t);
+  }
+
+  async send(text: string): Promise<void> {
+    if (this.closed) return;
+    this.turn += 1;
+
+    // Compose a canned reply that echoes a little of the input so the
+    // feed visibly reflects what was sent.
+    const trimmed = text.trim().replace(/\s+/g, " ");
+    const echo = trimmed.length > 60 ? `${trimmed.slice(0, 57)}…` : trimmed;
+    const reply =
+      `[mock ${this.agentId}] received: "${echo}". ` +
+      `This is turn ${this.turn}. Wiring up the real ${this.kind} ` +
+      `adapter is the next step — until then I just echo.`;
+
+    const words = reply.split(" ");
+    let cursor = 0;
+    let assembled = "";
+
+    // Stream the reply word-by-word.
+    const streamNext = (): void => {
+      if (cursor >= words.length) {
+        this.emit({ type: "message_complete", text: assembled });
+        // Halfway through the conversation, fake a tool call so the
+        // card rendering path gets exercised.
+        if (this.turn === 1) {
+          this.schedule(() => {
+            this.emit({
+              type: "tool_call",
+              id: newId(),
+              title: "Read",
+              detail: "README.md (mock)",
+            });
+            this.schedule(() => this.emit({ type: "turn_complete" }), 200);
+          }, 150);
+        } else {
+          this.emit({ type: "turn_complete" });
+        }
+        return;
+      }
+      const chunk = (cursor === 0 ? "" : " ") + words[cursor];
+      assembled += chunk;
+      cursor += 1;
+      this.emit({ type: "message_delta", text: chunk });
+      this.schedule(streamNext, DELTA_INTERVAL_MS);
+    };
+
+    // Small initial "thinking" delay before the first token.
+    this.schedule(streamNext, DELTA_INTERVAL_MS * 2);
+  }
+
+  async interrupt(): Promise<void> {
+    if (this.closed) return;
+    // Stop any in-flight streaming and end the turn — the mock's ESC.
+    for (const t of this.timers) clearTimeout(t);
+    this.timers.clear();
+    this.emit({ type: "turn_complete" });
+  }
+
+  async resolvePermission(): Promise<void> {
+    // The mock never raises permission requests, so nothing to resolve.
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    for (const t of this.timers) clearTimeout(t);
+    this.timers.clear();
+    this.emit({ type: "exit", code: 0 });
+    this.handlers.clear();
+  }
+}
+
+/** Factory that hands back MockAgentSessions. */
+export const mockAgentFactory: AgentSessionFactory = {
+  create: async ({ agent, systemPreamble }) =>
+    new MockAgentSession({ agent, systemPreamble }),
+};

package/lib/agents/mode.ts

@@ -0,0 +1,64 @@
+/**
+ * Which agent adapters this host runs — `UAI_AGENTS`.
+ *
+ * REAL IS THE DEFAULT. It did not used to be: the check was
+ * `UAI_AGENTS === "real" ? real : mock`, so every value except that one
+ * literal — including unset — silently selected the echo mock. That was a
+ * sane default while the adapters were unproven and the only hosts were the
+ * author's, but it shipped to npm unchanged. A user installs `@runuai/host`,
+ * enrolls, starts a task, and the host looks perfectly healthy while every
+ * agent echoes canned text. Nothing in the logs or `uai-host status` said so.
+ *
+ * The desktop host app (since deleted) never hit it because it hardcoded
+ * `UAI_AGENTS: "real"` — the npm path had no equivalent, so
+ * the bug was invisible to exactly the people who could reproduce it.
+ *
+ * So: a host runs real agents unless it is explicitly told not to. `mock` is
+ * the opt-in for tests and for dev boxes with no Docker, and an unrecognised
+ * value resolves to `real` with a warning rather than quietly downgrading —
+ * a typo must never cost someone a day of echoed output again.
+ */
+
+export type AgentMode = "real" | "mock";
+
+/** Values that select the in-process echo mock. */
+const MOCK_VALUES = new Set(["mock", "fake", "echo"]);
+/** Values that select the real Claude/Codex adapters (the default). */
+const REAL_VALUES = new Set(["real", "prod", "production"]);
+
+export interface AgentModeResolution {
+  mode: AgentMode;
+  /** Set when the raw value was neither recognised nor empty. */
+  warning?: string;
+}
+
+/**
+ * Resolve `UAI_AGENTS` to a mode. Pure and case/whitespace insensitive so a
+ * stray `UAI_AGENTS=Mock ` from a hand-edited .env.local behaves as written.
+ */
+export function resolveAgentMode(
+  raw: string | undefined = process.env.UAI_AGENTS,
+): AgentModeResolution {
+  const value = (raw ?? "").trim().toLowerCase();
+  if (value === "") return { mode: "real" };
+  if (MOCK_VALUES.has(value)) return { mode: "mock" };
+  if (REAL_VALUES.has(value)) return { mode: "real" };
+  return {
+    mode: "real",
+    warning:
+      `unrecognised UAI_AGENTS=${JSON.stringify(raw)} — running REAL agents. ` +
+      `Use "mock" for the echo agent, or unset it.`,
+  };
+}
+
+/** The mode this process is running in. */
+export function agentMode(): AgentMode {
+  return resolveAgentMode().mode;
+}
+
+/** Echo/mock sessions cannot execute the in-task structured-dispatch CLI. */
+export function canAdvertiseTypedSecretaryDispatch(
+  raw: string | undefined = process.env.UAI_AGENTS,
+): boolean {
+  return resolveAgentMode(raw).mode === "real";
+}

package/lib/agents/opencode.ts

@@ -0,0 +1,508 @@
+/**
+ * OpencodeSession — a real AgentSession backed by the OpenCode CLI's
+ * non-interactive `run` mode, executed inside the task environment (ADR-077):
+ *
+ *   ~/.opencode/bin/opencode run \
+ *     --format json --auto --model <provider/model> [--variant <effort>] \
+ *     [--session <id>] "<prompt>"
+ *
+ * Like Kimi/Grok/Cursor (ADR-066/067/068) OpenCode is **one-shot per turn**:
+ * `run` executes a single prompt to completion, streams newline-delimited JSON
+ * events to stdout, and exits. Multi-turn continuity is `--session <id>` (the
+ * id is captured from the first turn's event stream). Each `send()` spawns a
+ * fresh provider process; sends are serialized so a second message can't race a
+ * running turn.
+ *
+ * `--format json` vocabulary (one object per line, `type` field):
+ *   {"type":"step_start", ...}                        → (ignored)
+ *   {"type":"text","part":{"text":"…"}}               → message_complete
+ *   {"type":"tool_use","part":{"tool","state":{…}}}   → tool_call
+ *   {"type":"step_finish","part":{"cost","tokens":…}} → (accumulated usage)
+ *   {"type":"error","error":{…}}                      → error
+ * Every event carries a top-level `sessionID` (captured for --session). The
+ * turn ends when the process exits (turn_complete, with accumulated usage).
+ *
+ * AUTH is the operator's OpenCode provider keys in
+ * `~/.local/share/opencode/auth.json`, docker-cp'd into the container at
+ * task-up (like Codex's ~/.codex) — never the cloud (ADR-015). `--auto`
+ * auto-approves tool permissions (the container is the isolation boundary), so
+ * there are no permission prompts to resolve. ADR-076: `OPENCODE_DATA_DIR` in
+ * agentEnv selects which account's data dir (auth) this exec uses.
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { requireContainerRuntimeOperational } from "../runtime-guard";
+import type {
+  TaskEnvironmentAgentSessionSurface,
+  TaskEnvironmentSessionRequest,
+} from "../task-environment/types";
+import { newId } from "../ulid";
+import {
+  AGENT_SESSION_OUTPUT_BUFFER_BYTES,
+  spawnEnvironmentProcess,
+  type AgentEnvironmentProcess,
+} from "./proc";
+import { rateLimitErrorUsage } from "./rate-limit";
+import { register } from "./registry";
+import type {
+  AgentEvent,
+  AgentEventHandler,
+  AgentKind,
+  AgentSession,
+  AgentUsage,
+  RosterAgent,
+} from "./types";
+
+/** Installed by the image's opencode installer (opencode.ai/install); absolute
+ *  so a non-login provider process doesn't depend on PATH. */
+const OPENCODE_BIN = "/home/node/.opencode/bin/opencode";
+
+// OpenCode is multi-provider: models are `provider/model` strings. This is a
+// curated slice keyed to OpenCode Zen (the `opencode/…` gateway that the
+// connect picker defaults to — OpenCode's own coding-benchmarked catalog);
+// any provider/model the operator's auth.json can drive is still typable in
+// the composer (unlisted values round-trip). If you bring native provider
+// keys instead of Zen, type e.g. `anthropic/claude-sonnet-5` directly.
+// UPDATE alongside lib/agent-catalog.ts. Order = display order. Deprecated Zen
+// models are intentionally omitted (they 4xx): the gpt-5.x-codex/gpt-5-codex
+// line (retired 2026-07-23), glm-5, minimax-m2.5, kimi-k2.5.
+const OPENCODE_MODELS = [
+  // Anthropic (Claude).
+  "opencode/claude-sonnet-5",
+  "opencode/claude-opus-5",
+  "opencode/claude-opus-4-8",
+  "opencode/claude-opus-4-7",
+  "opencode/claude-opus-4-6",
+  "opencode/claude-opus-4-5",
+  "opencode/claude-sonnet-4-6",
+  "opencode/claude-sonnet-4-5",
+  "opencode/claude-haiku-4-5",
+  "opencode/claude-fable-5",
+  // OpenAI (GPT).
+  "opencode/gpt-5.6-sol",
+  "opencode/gpt-5.6-terra",
+  "opencode/gpt-5.6-luna",
+  "opencode/gpt-5.5",
+  "opencode/gpt-5.5-pro",
+  "opencode/gpt-5.4",
+  "opencode/gpt-5.4-pro",
+  "opencode/gpt-5.4-mini",
+  "opencode/gpt-5.4-nano",
+  "opencode/gpt-5.3-codex",
+  "opencode/gpt-5.3-codex-spark",
+  "opencode/gpt-5.2",
+  "opencode/gpt-5.1",
+  "opencode/gpt-5",
+  "opencode/gpt-5-nano",
+  // Google (Gemini).
+  "opencode/gemini-3.6-flash",
+  "opencode/gemini-3.5-flash",
+  "opencode/gemini-3.5-flash-lite",
+  "opencode/gemini-3.1-pro",
+  "opencode/gemini-3-flash",
+  // xAI (Grok).
+  "opencode/grok-4.5",
+  "opencode/grok-build-0.1",
+  // Open-weight — Moonshot Kimi.
+  "opencode/kimi-k2.7-code",
+  "opencode/kimi-k2.6",
+  // Open-weight — Alibaba Qwen.
+  "opencode/qwen3.7-max",
+  "opencode/qwen3.7-plus",
+  "opencode/qwen3.6-plus",
+  "opencode/qwen3.5-plus",
+  // Open-weight — DeepSeek.
+  "opencode/deepseek-v4-pro",
+  "opencode/deepseek-v4-flash",
+  // Open-weight — Z.ai GLM.
+  "opencode/glm-5.2",
+  "opencode/glm-5.1",
+  // Open-weight — MiniMax.
+  "opencode/minimax-m3",
+  "opencode/minimax-m2.7",
+  // Free / stealth (time-limited; some retain data during their free window).
+  "opencode/big-pickle",
+  "opencode/deepseek-v4-flash-free",
+  "opencode/mimo-v2.5-free",
+  "opencode/laguna-s-2.1-free",
+  "opencode/ling-3.0-flash-free",
+  "opencode/north-mini-code-free",
+  "opencode/nemotron-3-ultra-free",
+];
+const OPENCODE_DEFAULT_MODEL = "opencode/claude-sonnet-5";
+
+// Reasoning effort is a provider-specific `--variant`, not a fixed list, so the
+// picker offers none; a typed effort is still passed through.
+const OPENCODE_EFFORTS: string[] = [];
+
+/** Host path to the operator's OpenCode auth — its presence gates the engine
+ *  (mirrors Codex's ~/.codex/auth.json check). */
+function opencodeAuthPath(): string {
+  return join(
+    process.env.UAI_OWNER_HOME?.trim() || homedir(),
+    ".local",
+    "share",
+    "opencode",
+    "auth.json",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Pure protocol mapping — one JSON line → AgentEvent[] (+ session id / usage).
+// ---------------------------------------------------------------------------
+
+function isObj(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+function str(v: unknown, fallback = ""): string {
+  return typeof v === "string" ? v : fallback;
+}
+
+function num(v: unknown): number | undefined {
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+export interface MappedOpencodeLine {
+  events: AgentEvent[];
+  /** The session id, when this line carried one (for --session continuity). */
+  sessionId?: string;
+  /** Usage accounting, when this line was a step_finish. */
+  usage?: AgentUsage;
+}
+
+/** Best-effort one-line detail for a tool card from a tool_use part. */
+function toolDetail(state: unknown): string {
+  if (!isObj(state)) return "";
+  const title = state.title;
+  if (typeof title === "string" && title.length > 0) return title;
+  const input = state.input;
+  if (typeof input === "string") return input;
+  try {
+    return input !== undefined ? JSON.stringify(input) : "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Map a single OpenCode `run --format json` line. Non-JSON lines and events
+ * with no user-facing meaning (step_start) map to no events. Total + pure.
+ */
+export function mapOpencodeLine(
+  line: string,
+  now: number = Date.now(),
+): MappedOpencodeLine {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("{")) return { events: [] };
+  let msg: Record<string, unknown>;
+  try {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (!isObj(parsed)) return { events: [] };
+    msg = parsed;
+  } catch {
+    return { events: [] };
+  }
+
+  const sessionId =
+    typeof msg.sessionID === "string" ? msg.sessionID : undefined;
+  const type = str(msg.type);
+  const part = isObj(msg.part) ? msg.part : {};
+
+  if (type === "text") {
+    const text = str(part.text);
+    return text
+      ? { events: [{ type: "message_complete", text }], sessionId }
+      : { events: [], sessionId };
+  }
+
+  if (type === "tool_use") {
+    const state = isObj(part.state) ? part.state : {};
+    return {
+      events: [
+        {
+          type: "tool_call",
+          id: str(part.callID) || str(part.id) || newId(),
+          title: str(part.tool, "tool"),
+          detail: toolDetail(state),
+        },
+      ],
+      sessionId,
+    };
+  }
+
+  if (type === "step_finish") {
+    const tokens = isObj(part.tokens) ? part.tokens : {};
+    const cache = isObj(tokens.cache) ? tokens.cache : {};
+    const usage: AgentUsage = {
+      inputTokens: num(tokens.input),
+      outputTokens: num(tokens.output),
+      cacheReadTokens: num(cache.read),
+      cacheCreateTokens: num(cache.write),
+      costUsd: num(part.cost),
+    };
+    return { events: [], sessionId, usage };
+  }
+
+  if (type === "error") {
+    const err = isObj(msg.error) ? msg.error : {};
+    const data = isObj(err.data) ? err.data : {};
+    const message =
+      str(data.message) || str(err.name) || "opencode error";
+    const accountUsage = rateLimitErrorUsage(message, now);
+    return {
+      events: accountUsage
+        ? [
+            { type: "account_usage", usage: accountUsage },
+            {
+              type: "error",
+              message,
+              retryable: "rate_limit",
+              ...(accountUsage.resetsAt === undefined
+                ? {}
+                : { resetsAt: accountUsage.resetsAt }),
+            },
+          ]
+        : [
+            { type: "error", message },
+          ],
+      sessionId,
+    };
+  }
+
+  return { events: [], sessionId };
+}
+
+// ---------------------------------------------------------------------------
+// Session
+// ---------------------------------------------------------------------------
+
+/** Injectable spawn seam (tests provide a fake). */
+export type Spawner = (
+  request: TaskEnvironmentSessionRequest,
+) => AgentEnvironmentProcess;
+
+/** Sum this turn's step usage into a running total. */
+function addUsage(acc: AgentUsage, u: AgentUsage): AgentUsage {
+  const add = (a?: number, b?: number): number | undefined =>
+    a === undefined && b === undefined ? undefined : (a ?? 0) + (b ?? 0);
+  return {
+    inputTokens: add(acc.inputTokens, u.inputTokens),
+    outputTokens: add(acc.outputTokens, u.outputTokens),
+    cacheReadTokens: add(acc.cacheReadTokens, u.cacheReadTokens),
+    cacheCreateTokens: add(acc.cacheCreateTokens, u.cacheCreateTokens),
+    costUsd: add(acc.costUsd, u.costUsd),
+  };
+}
+
+export class OpencodeSession implements AgentSession {
+  readonly agentId: string;
+  readonly kind: AgentKind = "opencode";
+
+  private readonly environment: TaskEnvironmentAgentSessionSurface;
+  private readonly model?: string;
+  private readonly effort?: string;
+  private readonly systemPreamble: string;
+  private readonly agentEnv: Record<string, string>;
+  private readonly spawner: Spawner;
+
+  private readonly handlers = new Set<AgentEventHandler>();
+  private sessionId: string | null = null;
+  private current: AgentEnvironmentProcess | null = null;
+  private queue: Promise<void> = Promise.resolve();
+  private sentPreamble = false;
+  private closed = false;
+
+  constructor(args: {
+    taskId: string;
+    agent: RosterAgent;
+    environment: TaskEnvironmentAgentSessionSurface;
+    systemPreamble: string;
+    agentEnv?: Record<string, string>;
+    spawner?: Spawner;
+  }) {
+    this.agentId = args.agent.id;
+    this.environment = args.environment;
+    this.model = args.agent.model;
+    this.effort = args.agent.effort;
+    this.systemPreamble = args.systemPreamble;
+    this.agentEnv = args.agentEnv ?? {};
+    this.spawner =
+      args.spawner ?? ((request) => spawnEnvironmentProcess(this.environment, request));
+  }
+
+  onEvent(handler: AgentEventHandler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  private emit(event: AgentEvent): void {
+    if (this.closed && event.type !== "exit") return;
+    for (const h of this.handlers) h(event);
+  }
+
+  /** One-shot per turn; serialize so a second message queues behind the
+   *  running one instead of spawning a racing `opencode run`. */
+  async send(text: string): Promise<void> {
+    if (this.closed) return;
+    const turn = this.queue.catch(() => {}).then(() => this.runTurn(text));
+    this.queue = turn;
+    return turn;
+  }
+
+  private buildRequest(prompt: string): TaskEnvironmentSessionRequest {
+    const argv = [
+      OPENCODE_BIN,
+      "run",
+      "--format",
+      "json",
+      // Auto-approve permissions not explicitly denied — the container is the
+      // sandbox, and headless has no interactive approver.
+      "--auto",
+    ];
+    if (this.model) argv.push("--model", this.model);
+    if (this.effort) argv.push("--variant", this.effort);
+    // Continue the same OpenCode session across turns (captured from the first
+    // turn's stream). First turn has none → a fresh session.
+    if (this.sessionId) argv.push("--session", this.sessionId);
+    // The prompt is positional; put it LAST so it's never mistaken for a flag.
+    argv.push(prompt);
+    return {
+      argv: argv as [string, ...string[]],
+      projectEnvProfile: "task",
+      user: "node",
+      env: this.agentEnv,
+      maxOutputBytes: AGENT_SESSION_OUTPUT_BUFFER_BYTES,
+    };
+  }
+
+  private async runTurn(text: string): Promise<void> {
+    if (this.closed) return;
+    requireContainerRuntimeOperational();
+    // `run` has no system-prompt flag, so fold the channel briefing into the
+    // FIRST turn's prompt (later turns carry it via the resumed session).
+    const prompt =
+      !this.sentPreamble && this.systemPreamble.trim().length > 0
+        ? `${this.systemPreamble}\n\n---\n\n${text}`
+        : text;
+    this.sentPreamble = true;
+
+    const child = this.spawner(this.buildRequest(prompt));
+    this.current = child;
+
+    let turnUsage: AgentUsage = {};
+    let sawUsage = false;
+    // Whether the JSON stream already surfaced an error this turn. `opencode
+    // run` reports a provider/gateway failure as a `{type:"error"}` event AND
+    // then exits 1 — without this we'd double-report one failure (e.g.
+    // "Unexpected server error" followed by a bare "opencode exited 1").
+    let sawError = false;
+    let buf = "";
+    const consume = (chunk: string): void => {
+      buf += chunk;
+      let nl: number;
+      while ((nl = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        const { events, sessionId, usage } = mapOpencodeLine(line);
+        if (sessionId) this.sessionId = sessionId;
+        if (usage) {
+          turnUsage = addUsage(turnUsage, usage);
+          sawUsage = true;
+        }
+        for (const e of events) {
+          if (e.type === "error") sawError = true;
+          this.emit(e);
+        }
+      }
+    };
+    child.stdout?.on("data", (b: Buffer) => consume(b.toString("utf8")));
+    let stderr = "";
+    child.stderr?.on("data", (b: Buffer) => {
+      stderr += b.toString("utf8");
+    });
+
+    await new Promise<void>((resolve) => {
+      child.on("exit", (code) => {
+        this.current = null;
+        if (buf.trim().length > 0) consume("\n"); // flush a trailing line
+        if (!this.closed) {
+          // Only surface the bare exit code when the stream didn't already
+          // explain the failure (see sawError) — otherwise it's a redundant
+          // second error card for the same turn.
+          if (code !== 0 && !sawError) {
+            const tail = stderr.trim().slice(-500);
+            const message = `opencode exited ${code ?? "null"}${tail ? `: ${tail}` : ""}`;
+            const accountUsage = rateLimitErrorUsage(message);
+            if (accountUsage) {
+              this.emit({ type: "account_usage", usage: accountUsage });
+              this.emit({
+                type: "error",
+                message,
+                retryable: "rate_limit",
+                ...(accountUsage.resetsAt === undefined
+                  ? {}
+                  : { resetsAt: accountUsage.resetsAt }),
+              });
+            } else {
+              this.emit({ type: "error", message });
+            }
+          }
+          this.emit({
+            type: "turn_complete",
+            usage: sawUsage ? turnUsage : undefined,
+          });
+        }
+        resolve();
+      });
+      child.on("error", (err) => {
+        this.current = null;
+        if (!this.closed) {
+          this.emit({
+            type: "error",
+            message: `opencode spawn failed: ${err.message}`,
+          });
+          this.emit({ type: "turn_complete" });
+        }
+        resolve();
+      });
+    });
+  }
+
+  async interrupt(): Promise<void> {
+    // Kill the running turn's exec. Best-effort — the in-container `opencode`
+    // may finish the current tool, but no further output is emitted.
+    this.current?.kill("SIGKILL");
+  }
+
+  // `--auto` approves tools (the container is the sandbox), so no permission
+  // requests are ever emitted — nothing to resolve.
+  async resolvePermission(): Promise<void> {
+    /* no-op */
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    this.current?.kill("SIGKILL");
+    this.current = null;
+    this.emit({ type: "exit", code: 0 });
+    this.handlers.clear();
+  }
+}
+
+// Register the OpenCode adapter at module load (ADR-021/077).
+register({
+  kind: "opencode",
+  label: "OpenCode",
+  supportedModels: () => [...OPENCODE_MODELS],
+  defaultModel: OPENCODE_DEFAULT_MODEL,
+  supportedEfforts: () => [...OPENCODE_EFFORTS],
+  // Gated on the operator's OpenCode auth (copied into containers at task-up).
+  // No auth → the engine isn't advertised.
+  available: () => existsSync(opencodeAuthPath()),
+  create: async ({ taskId, agent, environment, systemPreamble, agentEnv }) =>
+    new OpencodeSession({ taskId, agent, environment, systemPreamble, agentEnv }),
+});