@smithers-orchestrator/agents 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/agents",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "AI SDK and CLI agent adapters for Smithers",
   "type": "module",
   "sideEffects": false,
@@ -50,9 +50,9 @@
     "ai": "^6.0.168",
     "effect": "^3.21.1",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/driver": "0.17.0",
-    "@smithers-orchestrator/errors": "0.17.0",
-    "@smithers-orchestrator/observability": "0.17.0"
+    "@smithers-orchestrator/errors": "0.18.0",
+    "@smithers-orchestrator/observability": "0.18.0",
+    "@smithers-orchestrator/driver": "0.18.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/AgentLike.ts

@@ -12,6 +12,8 @@ export type AgentLike = {
   tools?: Record<string, unknown>;
   /** Optional structured capability registry for cache and diagnostics */
   capabilities?: AgentCapabilityRegistry;
+  /** True when the agent consumes outputSchema through a native structured-output API. */
+  supportsNativeStructuredOutput?: boolean;
   /**
    * Generates a response or action based on the provided arguments.
    *

package/src/AnthropicAgent.js

@@ -1,5 +1,5 @@
 import { anthropic } from "@ai-sdk/anthropic";
-import { ToolLoopAgent, } from "ai";
+import { Output, ToolLoopAgent, } from "ai";
 import { resolveSdkModel } from "./resolveSdkModel.js";
 import { streamResultToGenerateResult } from "./streamResultToGenerateResult.js";
 /** @typedef {import("ai").AgentCallParameters} AgentCallParameters */
@@ -17,6 +17,7 @@ import { streamResultToGenerateResult } from "./streamResultToGenerateResult.js"
 
 export class AnthropicAgent extends ToolLoopAgent {
     hijackEngine = "anthropic-sdk";
+    supportsNativeStructuredOutput = true;
     /**
    * @param {AnthropicAgentOptions<CALL_OPTIONS, TOOLS>} opts
    */
@@ -35,11 +36,15 @@ export class AnthropicAgent extends ToolLoopAgent {
         const promptArgs = "messages" in args
             ? { messages: args.messages }
             : { prompt: args.prompt };
+        const outputArgs = args.outputSchema
+            ? { output: Output.object({ schema: args.outputSchema }) }
+            : {};
         if (!args.onStdout) {
             return super.generate({
                 options: args.options,
                 abortSignal: args.abortSignal,
                 ...promptArgs,
+                ...outputArgs,
                 timeout: args.timeout,
                 onStepFinish: args.onStepFinish,
             });
@@ -48,6 +53,7 @@ export class AnthropicAgent extends ToolLoopAgent {
             options: args.options,
             abortSignal: args.abortSignal,
             ...promptArgs,
+            ...outputArgs,
             timeout: args.timeout,
             onStepFinish: args.onStepFinish,
         }).then((stream) => streamResultToGenerateResult(stream, args.onStdout));

package/src/BaseCliAgent/BaseCliAgent.js

@@ -281,15 +281,67 @@ function extractTextFromJsonPayload(raw) {
                     return text;
             }
         }
+        // OpenCode-style CLIs emit a final "finish" or "done" event with the
+        // complete response text directly on the payload. Prefer this over
+        // concatenating all text_delta chunks which would duplicate content.
+        if (type === "finish" || type === "done") {
+            const text = typeof parsed?.text === "string" ? parsed.text : undefined;
+            if (text)
+                return text;
+        }
+        // OpenCode nd-JSON format: "text" events carry part.text with finalized
+        // text chunks. Accumulate these as a fallback when the interpreter's
+        // completed event isn't surfaced properly.
+        if (type === "text" && parsed?.part?.text) {
+            // Don't return early — accumulate via the chunks path below
+        }
     }
     const chunks = [];
     for (const parsed of parsedLines) {
-        const text = extractTextFromJsonValue(parsed);
+        let text;
+        if (parsed?.type === "text" && typeof parsed?.part?.text === "string") {
+            text = parsed.part.text;
+        }
+        else {
+            text = extractTextFromJsonValue(parsed);
+        }
         if (text)
             chunks.push(text);
     }
     return chunks.length ? chunks.join("") : undefined;
 }
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function stripOscSequences(raw) {
+    return raw.replace(/\x1b\]0;[^\x07]*\x07/g, "");
+}
+/**
+ * @param {string} raw
+ * @returns {string | undefined}
+ */
+function extractErrorFromJsonPayload(raw) {
+    const trimmed = stripOscSequences(raw).trim();
+    if (!trimmed)
+        return undefined;
+    const lines = trimmed.split(/\r?\n/).filter(Boolean);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const parsed = JSON.parse(lines[i]);
+            if (parsed?.type !== "error")
+                continue;
+            const message = parsed?.error?.data?.message ?? parsed?.error?.message ?? parsed?.error?.name;
+            if (typeof message === "string" && message.trim()) {
+                return message.trim();
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
 /**
  * @param {string[]} args
  * @returns {string | undefined}
@@ -403,7 +455,7 @@ function buildStreamResult(result) {
  * @returns {CliUsageInfo | undefined}
  */
 export function extractUsageFromOutput(raw) {
-    const lines = raw.split(/\r?\n/).filter(Boolean);
+    const lines = stripOscSequences(raw).split(/\r?\n/).filter(Boolean);
     const usage = {};
     let found = false;
     for (const line of lines) {
@@ -453,6 +505,25 @@ export function extractUsageFromOutput(raw) {
             found = true;
             continue;
         }
+        if (parsed.type === "step_finish" && parsed.part?.tokens && typeof parsed.part.tokens === "object") {
+            const tokens = parsed.part.tokens;
+            const input = tokens.input ?? 0;
+            const output = tokens.output ?? 0;
+            const total = tokens.total ?? 0;
+            const reasoning = tokens.reasoning ?? 0;
+            const cacheRead = tokens.cache?.read ?? 0;
+            const cacheWrite = tokens.cache?.write ?? 0;
+            if (input > 0 || output > 0 || total > 0 || reasoning > 0 || cacheRead > 0 || cacheWrite > 0) {
+                usage.inputTokens = (usage.inputTokens ?? 0) + input;
+                usage.outputTokens = (usage.outputTokens ?? 0) + output;
+                usage.totalTokens = (usage.totalTokens ?? 0) + total;
+                usage.reasoningTokens = (usage.reasoningTokens ?? 0) + reasoning;
+                usage.cacheReadTokens = (usage.cacheReadTokens ?? 0) + cacheRead;
+                usage.cacheWriteTokens = (usage.cacheWriteTokens ?? 0) + cacheWrite;
+                found = true;
+                continue;
+            }
+        }
         if (parsed.usage && typeof parsed.usage === "object") {
             const u = parsed.usage;
             const inTok = u.input_tokens ?? u.inputTokens ?? u.prompt_tokens ?? 0;
@@ -690,6 +761,7 @@ export class BaseCliAgent {
             const interpreter = this.createOutputInterpreter();
             let stdoutBuffer = "";
             let stderrBuffer = "";
+            let completedEvent = null;
             /**
      * @param {AgentCliEvent[] | AgentCliEvent | null | undefined} eventPayload
      */
@@ -698,6 +770,9 @@ export class BaseCliAgent {
                     return;
                 const events = Array.isArray(eventPayload) ? eventPayload : [eventPayload];
                 for (const event of events) {
+                    if (event?.type === "completed") {
+                        completedEvent = event;
+                    }
                     logAgentCliEvent(event, commandLogAnnotations, span);
                     if (!options?.onEvent)
                         continue;
@@ -779,7 +854,11 @@ export class BaseCliAgent {
                 if (result.exitCode && result.exitCode !== 0) {
                     const filteredStderr = filterBenignStderr(result.stderr, commandSpec.benignStderrPatterns);
                     if (!(commandSpec.command === "codex" && filteredStderr.length === 0)) {
-                        const errorText = filteredStderr ||
+                        const structuredError = (commandSpec.outputFormat === "json" || commandSpec.outputFormat === "stream-json")
+                            ? extractErrorFromJsonPayload(result.stdout)
+                            : undefined;
+                        const errorText = structuredError ||
+                            filteredStderr ||
                             result.stdout.trim() ||
                             `CLI exited with code ${result.exitCode}`;
                         const nonRetryable = classifyNonRetryableAgentError(errorText, commandSpec.command);
@@ -808,6 +887,9 @@ export class BaseCliAgent {
                         return yield* Effect.fail(new SmithersError("AGENT_CLI_ERROR", errorText));
                     }
                 }
+                if (completedEvent?.ok === false) {
+                    return yield* Effect.fail(new SmithersError("AGENT_CLI_ERROR", completedEvent.error || "CLI agent reported an error"));
+                }
                 // Some CLIs may print extra banners to stdout. Allow individual agents
                 // to provide patterns so this logic stays opt-in and agent-specific.
                 const stdoutBannerPatterns = commandSpec.stdoutBannerPatterns ?? [];
@@ -853,7 +935,7 @@ export class BaseCliAgent {
                         textTokens: undefined,
                         reasoningTokens: cliUsage.reasoningTokens,
                     },
-                    totalTokens: (cliUsage.inputTokens ?? 0) + (cliUsage.outputTokens ?? 0) || undefined,
+                    totalTokens: cliUsage.totalTokens ?? ((cliUsage.inputTokens ?? 0) + (cliUsage.outputTokens ?? 0) || undefined),
                 } : undefined;
                 const tokenTotals = extractAgentTokenTotals(usage);
                 stdoutEmitter?.flush(extractedText);

package/src/BaseCliAgent/extractTextFromJsonValue.js

@@ -32,6 +32,8 @@ export function extractTextFromJsonValue(value) {
         if (parts.trim())
             return parts;
     }
+    if (record.type === "text" && record.part)
+        return extractTextFromJsonValue(record.part);
     if (record.response)
         return extractTextFromJsonValue(record.response);
     if (record.message)

package/src/OpenAIAgent.js

@@ -1,5 +1,5 @@
 import { openai } from "@ai-sdk/openai";
-import { ToolLoopAgent, } from "ai";
+import { Output, ToolLoopAgent, } from "ai";
 import { resolveSdkModel } from "./resolveSdkModel.js";
 import { streamResultToGenerateResult } from "./streamResultToGenerateResult.js";
 /** @typedef {import("ai").AgentCallParameters} AgentCallParameters */
@@ -17,6 +17,7 @@ import { streamResultToGenerateResult } from "./streamResultToGenerateResult.js"
 
 export class OpenAIAgent extends ToolLoopAgent {
     hijackEngine = "openai-sdk";
+    supportsNativeStructuredOutput = true;
     /**
    * @param {OpenAIAgentOptions<CALL_OPTIONS, TOOLS>} opts
    */
@@ -35,11 +36,15 @@ export class OpenAIAgent extends ToolLoopAgent {
         const promptArgs = "messages" in args
             ? { messages: args.messages }
             : { prompt: args.prompt };
+        const outputArgs = args.outputSchema
+            ? { output: Output.object({ schema: args.outputSchema }) }
+            : {};
         if (!args.onStdout) {
             return super.generate({
                 options: args.options,
                 abortSignal: args.abortSignal,
                 ...promptArgs,
+                ...outputArgs,
                 timeout: args.timeout,
                 onStepFinish: args.onStepFinish,
             });
@@ -48,6 +53,7 @@ export class OpenAIAgent extends ToolLoopAgent {
             options: args.options,
             abortSignal: args.abortSignal,
             ...promptArgs,
+            ...outputArgs,
             timeout: args.timeout,
             onStepFinish: args.onStepFinish,
         }).then((stream) => streamResultToGenerateResult(stream, args.onStdout));

package/src/OpenCodeAgent.js

@@ -0,0 +1,495 @@
+import {
+  BaseCliAgent,
+  pushFlag,
+  isRecord,
+  asString,
+  truncate,
+  toolKindFromName,
+  shouldSurfaceUnparsedStdout,
+  createSyntheticIdGenerator,
+} from "./BaseCliAgent/index.js";
+import { normalizeCapabilityStringList } from "./capability-registry/index.js";
+
+/** @typedef {import("./BaseCliAgent/index.ts").BaseCliAgentOptions} BaseCliAgentOptions */
+/** @typedef {import("./capability-registry/index.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
+
+/**
+ * @typedef {BaseCliAgentOptions & {
+ *   model?: string;
+ *   agentName?: string;
+ *   attachFiles?: string[];
+ *   continueSession?: boolean;
+ *   sessionId?: string;
+ *   variant?: "high" | "medium" | "low";
+ * }} OpenCodeAgentOptions
+ */
+
+/** @typedef {import("./BaseCliAgent/index.ts").CliOutputInterpreter} CliOutputInterpreter */
+
+/**
+ * @param {OpenCodeAgentOptions} [opts]  Currently unused — kept for API
+ *   consistency with other agents (e.g. ClaudeCodeAgent uses opts to resolve
+ *   builtIns based on tool allow/deny lists).  OpenCode does not yet expose
+ *   CLI flags for restricting built-in tools, so the set is static.
+ * @returns {AgentCapabilityRegistry}
+ */
+export function createOpenCodeCapabilityRegistry(opts = {}) {
+  return {
+    version: 1,
+    engine: "opencode",
+    runtimeTools: {},
+    mcp: {
+      bootstrap: "project-config",
+      supportsProjectScope: true,
+      supportsUserScope: true,
+    },
+    skills: {
+      supportsSkills: true,
+      installMode: "plugin",
+      smithersSkillIds: [],
+    },
+    humanInteraction: {
+      supportsUiRequests: false,
+      methods: [],
+    },
+    builtIns: normalizeCapabilityStringList([
+      "read",
+      "write",
+      "edit",
+      "apply_patch",
+      "bash",
+      "glob",
+      "grep",
+      "list",
+      "webfetch",
+      "websearch",
+      "codesearch",
+      "question",
+      "task",
+      "todowrite",
+      "skill",
+    ]),
+  };
+}
+
+/**
+ * CLI agent wrapper for OpenCode (https://opencode.ai).
+ *
+ * Shells out to `opencode run` in non-interactive mode with `--format json`
+ * for streaming nd-JSON output. Parses AgentCliEvents from the JSON stream.
+ *
+ * Usage:
+ *   const agent = new OpenCodeAgent({
+ *     model: "anthropic/claude-opus-4-20250514",
+ *     yolo: true,
+ *   });
+ *   const result = await agent.generate({
+ *     messages: [{ role: "user", content: "Fix the bug" }],
+ *   });
+ */
+export class OpenCodeAgent extends BaseCliAgent {
+  /** @type {OpenCodeAgentOptions} */
+  opts;
+  /** @type {AgentCapabilityRegistry} */
+  capabilities;
+  /** @type {"opencode"} */
+  cliEngine = "opencode";
+
+  /**
+   * @param {OpenCodeAgentOptions} [opts]
+   */
+  constructor(opts = {}) {
+    super(opts);
+    this.opts = opts;
+    this.capabilities = createOpenCodeCapabilityRegistry(opts);
+  }
+
+  /**
+   * Create an output interpreter that parses OpenCode's nd-JSON streaming format.
+   *
+   * OpenCode `--format json` emits one JSON object per line (verified from source:
+   * packages/opencode/src/cli/cmd/run.ts). The envelope is:
+   *
+   *   { type, timestamp: number, sessionID: string, ...payload }
+   *
+   * Event types:
+   *   step_start  → { part: { type:"step-start", id, sessionID, messageID } }
+   *   text        → { part: { type:"text", text, time: { start, end } } }
+   *   tool_use    → { part: { type:"tool", tool, callID, state: { status, ... } } }
+   *   step_finish → { part: { type:"step-finish", reason, tokens, cost } }
+   *   reasoning   → { part: { type:"reasoning", text } }
+   *   error       → { error: { name, data: { message } } }
+   *
+   * We map these to Smithers' AgentCliEvent union (started | action | completed).
+   *
+   * @returns {CliOutputInterpreter}
+   */
+  createOutputInterpreter() {
+    let fullText = "";
+    let sessionId = "";
+    let didEmitStarted = false;
+    let didEmitCompleted = false;
+    let terminalError = null;
+
+    // Accumulate tokens across multiple step_finish events
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalTokens = 0;
+
+    const nextSyntheticId = createSyntheticIdGenerator();
+
+    /**
+     * @param {string} title
+     * @param {string} message
+     * @param {"warning" | "error"} [level]
+     * @returns {import("./BaseCliAgent/index.ts").AgentCliEvent}
+     */
+    const warningAction = (title, message, level = "warning") => ({
+      type: "action",
+      engine: this.cliEngine,
+      phase: "completed",
+      entryType: "thought",
+      action: {
+        id: nextSyntheticId("opencode-warning"),
+        kind: "warning",
+        title,
+        detail: {},
+      },
+      message,
+      ok: level !== "error",
+      level,
+    });
+
+    /**
+     * @param {string} line
+     * @returns {import("./BaseCliAgent/index.ts").AgentCliEvent[]}
+     */
+    const parseLine = (line) => {
+      // Strip OSC terminal escape sequences (e.g. title-setting "\x1b]0;...\x07")
+      // that OpenCode emits inline with JSON events on stdout.
+      const cleaned = line.replace(/\x1b\]0;[^\x07]*\x07/g, "");
+      const trimmed = cleaned.trim();
+      if (!trimmed) return [];
+
+      /** @type {Record<string, unknown>} */
+      let payload;
+      try {
+        payload = JSON.parse(trimmed);
+      } catch {
+        if (!shouldSurfaceUnparsedStdout(trimmed)) return [];
+        return [warningAction("stdout", truncate(trimmed, 220))];
+      }
+
+      if (!isRecord(payload)) return [];
+
+      const eventType = asString(payload.type);
+      if (!eventType) return [];
+
+      // Capture sessionID from the envelope (present on every event)
+      const envelopeSessionId = asString(payload.sessionID);
+      if (envelopeSessionId) {
+        sessionId = envelopeSessionId;
+      }
+
+      const part = isRecord(payload.part) ? payload.part : null;
+
+      // --- step_start: session/step beginning ---
+      if (eventType === "step_start") {
+        if (!didEmitStarted) {
+          didEmitStarted = true;
+          return [
+            {
+              type: "started",
+              engine: this.cliEngine,
+              title: "OpenCode",
+              resume: sessionId || undefined,
+              detail: sessionId ? { sessionId } : undefined,
+            },
+          ];
+        }
+        return [];
+      }
+
+      // --- text: finalized text chunk from the model ---
+      if (eventType === "text") {
+        const text = part ? asString(part.text) : null;
+        if (text) {
+          fullText += text;
+          return [
+            {
+              type: "action",
+              engine: this.cliEngine,
+              phase: "updated",
+              entryType: "message",
+              action: {
+                id: nextSyntheticId("opencode-text"),
+                kind: "note",
+                title: "assistant",
+                detail: {},
+              },
+              message: text,
+              ok: true,
+              level: "info",
+            },
+          ];
+        }
+        return [];
+      }
+
+      // --- tool_use: tool completed or errored ---
+      if (eventType === "tool_use" && part) {
+        const toolName = asString(part.tool) ?? "tool";
+        const callID = asString(part.callID) ?? nextSyntheticId("opencode-tool");
+        const state = isRecord(part.state) ? part.state : null;
+        const status = state ? asString(state.status) : null;
+        const isError = status === "error";
+
+        const events = [];
+
+        // Emit a "started" action for the tool
+        events.push({
+          type: "action",
+          engine: this.cliEngine,
+          phase: "started",
+          entryType: "thought",
+          action: {
+            id: callID,
+            kind: toolKindFromName(toolName),
+            title: toolName,
+            detail: state && isRecord(state.input)
+              ? { input: state.input }
+              : {},
+          },
+          message: `Running ${toolName}`,
+          level: "info",
+        });
+
+        // Emit a "completed" action for the tool
+        const output = state
+          ? asString(state.output) ?? asString(state.error)
+          : undefined;
+        events.push({
+          type: "action",
+          engine: this.cliEngine,
+          phase: "completed",
+          entryType: "thought",
+          action: {
+            id: callID,
+            kind: toolKindFromName(toolName),
+            title: toolName,
+            detail: {},
+          },
+          message: output ? truncate(output, 300) : undefined,
+          ok: !isError,
+          level: isError ? "warning" : "info",
+        });
+
+        return events;
+      }
+
+      // --- step_finish: step completed with token usage ---
+      if (eventType === "step_finish" && part) {
+        const tokens = isRecord(part.tokens) ? part.tokens : null;
+        if (tokens) {
+          const input = typeof tokens.input === "number" ? tokens.input : 0;
+          const output = typeof tokens.output === "number" ? tokens.output : 0;
+          const total = typeof tokens.total === "number" ? tokens.total : 0;
+          totalInputTokens += input;
+          totalOutputTokens += output;
+          totalTokens += total;
+        }
+
+        const reason = asString(part.reason);
+        // Only emit "completed" on the final step (reason: "stop")
+        if (reason === "stop") {
+          if (didEmitCompleted) return [];
+          didEmitCompleted = true;
+
+          return [
+            {
+              type: "completed",
+              engine: this.cliEngine,
+              ok: true,
+              answer: fullText || undefined,
+              resume: sessionId || undefined,
+              usage: {
+                inputTokens: totalInputTokens,
+                outputTokens: totalOutputTokens,
+                totalTokens: totalTokens,
+              },
+            },
+          ];
+        }
+
+        return [];
+      }
+
+      // --- reasoning: model thinking (only with --thinking flag) ---
+      if (eventType === "reasoning") {
+        // Surface reasoning as a thought action, don't accumulate into fullText
+        const text = part ? asString(part.text) : null;
+        if (text) {
+          return [
+            {
+              type: "action",
+              engine: this.cliEngine,
+              phase: "updated",
+              entryType: "thought",
+              action: {
+                id: nextSyntheticId("opencode-reasoning"),
+                kind: "note",
+                title: "reasoning",
+                detail: {},
+              },
+              message: truncate(text, 500),
+              ok: true,
+              level: "info",
+            },
+          ];
+        }
+        return [];
+      }
+
+      // --- error: session error ---
+      if (eventType === "error") {
+        const errorObj = isRecord(payload.error) ? payload.error : null;
+        const errorData = errorObj && isRecord(errorObj.data) ? errorObj.data : null;
+        const errorName = errorObj ? asString(errorObj.name) : null;
+        const errorMessage = errorData
+          ? asString(errorData.message)
+          : errorName ?? "OpenCode reported an error";
+        terminalError = errorMessage ?? "OpenCode reported an error";
+
+        if (didEmitCompleted) {
+          return [warningAction("error", errorMessage ?? "OpenCode reported an error", "error")];
+        }
+
+        didEmitCompleted = true;
+        return [
+          {
+            type: "completed",
+            engine: this.cliEngine,
+            ok: false,
+            answer: fullText || undefined,
+            error: errorMessage ?? "OpenCode reported an error",
+          },
+        ];
+      }
+
+      return [];
+    };
+
+    return {
+      onStdoutLine: parseLine,
+
+      onStderrLine: (line) => {
+        const trimmed = line.trim();
+        if (!trimmed) return [];
+        return [warningAction("stderr", truncate(trimmed, 220))];
+      },
+
+      onExit: (result) => {
+        if (didEmitCompleted) return [];
+        const isSuccess = (result.exitCode ?? 0) === 0 && !terminalError;
+        didEmitCompleted = true;
+        return [
+          {
+            type: "completed",
+            engine: this.cliEngine,
+            ok: isSuccess,
+            answer: isSuccess ? fullText || undefined : undefined,
+            error: isSuccess
+              ? undefined
+              : terminalError ?? `OpenCode exited with code ${result.exitCode ?? -1}`,
+          },
+        ];
+      },
+    };
+  }
+
+  /**
+   * Build the CLI command spec for `opencode run`.
+   *
+   * @param {{ prompt: string; systemPrompt?: string; cwd: string; options: any }} params
+   */
+  async buildCommand(params) {
+    const resumeSession = typeof params.options?.resumeSession === "string"
+      ? params.options.resumeSession
+      : undefined;
+    const args = ["run"];
+
+    // Model selection
+    pushFlag(args, "-m", this.opts.model ?? this.model);
+
+    // Working directory
+    pushFlag(args, "--dir", params.cwd);
+
+    // Streaming nd-JSON output
+    pushFlag(args, "--format", "json");
+
+    // Named agent config
+    pushFlag(args, "--agent", this.opts.agentName);
+
+    // File attachments: -f file1 -f file2 (repeated flag)
+    if (this.opts.attachFiles) {
+      for (const file of this.opts.attachFiles) {
+        args.push("-f", file);
+      }
+    }
+
+    // Session continuation
+    const explicitSession = resumeSession ?? this.opts.sessionId;
+    if (this.opts.continueSession && !explicitSession) {
+      args.push("--continue");
+    }
+    pushFlag(args, "--session", explicitSession);
+
+    // Variant / reasoning effort
+    pushFlag(args, "--variant", this.opts.variant);
+
+    // Yolo mode: auto-approve all tool calls.
+    // OpenCode parses OPENCODE_PERMISSION with JSON.parse() and expects a
+    // permission object.  '{"*":"allow"}' grants blanket approval for every
+    // tool category.  See: packages/opencode/src/config/config.ts
+    const yoloEnabled = this.opts.yolo ?? this.yolo;
+    const env = {};
+    if (yoloEnabled) {
+      env.OPENCODE_PERMISSION = '{"*":"allow"}';
+    }
+
+    // Extra args from constructor
+    if (this.extraArgs?.length) {
+      args.push(...this.extraArgs);
+    }
+
+    const systemPrefix = params.systemPrompt
+      ? `${params.systemPrompt}\n\n`
+      : "";
+    const fullPrompt = `${systemPrefix}${params.prompt ?? ""}`;
+
+    // When flags like -f (yargs [array] type) are present, subsequent
+    // positional arguments can be consumed as flag values. Insert '--'
+    // to tell yargs to stop parsing flags and treat the rest as positional.
+    if (fullPrompt) {
+      args.push("--", fullPrompt);
+    }
+
+    return {
+      command: "opencode",
+      args,
+      outputFormat: "stream-json",
+      env: Object.keys(env).length > 0 ? env : undefined,
+      stdoutBannerPatterns: [
+        // OpenCode may print a version banner
+        /^opencode\s+v[\d.]+/gim,
+        // Strip OSC terminal title-setting sequences (ESC ] 0 ; ... BEL)
+        // OpenCode emits these even with --format json
+        /\x1b\]0;[^\x07]*\x07/g,
+      ],
+      stdoutErrorPatterns: [
+        /^error:/im,
+        /^fatal:/im,
+      ],
+    };
+  }
+}

package/src/OpenCodeAgent.ts

@@ -0,0 +1,43 @@
+import { type CliOutputInterpreter, BaseCliAgent } from "./BaseCliAgent";
+import type { BaseCliAgentOptions } from "./BaseCliAgent";
+import { type AgentCapabilityRegistry } from "./capability-registry";
+
+export type OpenCodeAgentOptions = BaseCliAgentOptions & {
+  /** Model identifier (e.g., "anthropic/claude-opus-4-20250514", "openai/gpt-5.4") */
+  model?: string;
+  /** OpenCode agent name (maps to --agent flag, selects predefined agent config) */
+  agentName?: string;
+  /** Files to attach to the prompt via -f flags */
+  attachFiles?: string[];
+  /** Continue a previous session */
+  continueSession?: boolean;
+  /** Resume a specific session by ID */
+  sessionId?: string;
+  /** Provider-specific model variant/reasoning effort level */
+  variant?: string;
+};
+
+export declare function createOpenCodeCapabilityRegistry(
+  opts?: OpenCodeAgentOptions
+): AgentCapabilityRegistry;
+
+export declare class OpenCodeAgent extends BaseCliAgent {
+  private readonly opts: OpenCodeAgentOptions;
+  readonly capabilities: AgentCapabilityRegistry;
+  readonly cliEngine: "opencode";
+  constructor(opts?: OpenCodeAgentOptions);
+  createOutputInterpreter(): CliOutputInterpreter;
+  buildCommand(params: {
+    prompt: string;
+    systemPrompt?: string;
+    cwd: string;
+    options: any;
+  }): Promise<{
+    command: string;
+    args: string[];
+    outputFormat: "stream-json";
+    env?: Record<string, string>;
+    stdoutBannerPatterns: RegExp[];
+    stdoutErrorPatterns: RegExp[];
+  }>;
+}

package/src/__type-tests__/AgentLike.assignability.test-d.ts

@@ -13,6 +13,11 @@ import type {
 
 type AssertAssignable<T extends AgentLike> = T;
 
+type _CustomNativeStructuredAgent = AssertAssignable<{
+  supportsNativeStructuredOutput: true;
+  generate: () => Promise<unknown>;
+}>;
+
 type _ConcreteAgentsAreAgentLike = [
   AssertAssignable<AmpAgent>,
   AssertAssignable<AnthropicAgent>,

package/src/capability-registry/AgentCapabilityRegistry.ts

@@ -2,7 +2,7 @@ import type { AgentToolDescriptor } from "./AgentToolDescriptor";
 
 export type AgentCapabilityRegistry = {
   version: 1;
-  engine: "claude-code" | "codex" | "gemini" | "kimi" | "pi" | "amp" | "forge";
+  engine: "claude-code" | "codex" | "gemini" | "kimi" | "pi" | "amp" | "forge" | "opencode";
   runtimeTools: Record<string, AgentToolDescriptor>;
   mcp: {
     bootstrap: "inline-config" | "project-config" | "allow-list" | "unsupported";

package/src/cli-capabilities/CliAgentCapabilityAdapterId.ts

@@ -3,4 +3,5 @@ export type CliAgentCapabilityAdapterId =
   | "codex"
   | "gemini"
   | "kimi"
+  | "opencode"
   | "pi";

package/src/cli-capabilities/getCliAgentCapabilityReport.js

@@ -3,6 +3,7 @@ import { createClaudeCodeCapabilityRegistry } from "../ClaudeCodeAgent.js";
 import { createCodexCapabilityRegistry } from "../CodexAgent.js";
 import { createGeminiCapabilityRegistry } from "../GeminiAgent.js";
 import { createKimiCapabilityRegistry } from "../KimiAgent.js";
+import { createOpenCodeCapabilityRegistry } from "../OpenCodeAgent.js";
 import { createPiCapabilityRegistry } from "../PiAgent.js";
 /** @typedef {import("./CliAgentCapabilityReportEntry.ts").CliAgentCapabilityReportEntry} CliAgentCapabilityReportEntry */
 
@@ -27,6 +28,11 @@ const CLI_AGENT_CAPABILITY_ADAPTERS = [
         binary: "kimi",
         buildRegistry: () => createKimiCapabilityRegistry(),
     },
+    {
+        id: "opencode",
+        binary: "opencode",
+        buildRegistry: () => createOpenCodeCapabilityRegistry(),
+    },
     {
         id: "pi",
         binary: "pi",

package/src/index.d.ts

@@ -112,7 +112,7 @@ type AgentToolDescriptor$1 = {
 
 type AgentCapabilityRegistry$3 = {
     version: 1;
-    engine: "claude-code" | "codex" | "gemini" | "kimi" | "pi" | "amp" | "forge";
+    engine: "claude-code" | "codex" | "gemini" | "kimi" | "pi" | "amp" | "forge" | "opencode";
     runtimeTools: Record<string, AgentToolDescriptor$1>;
     mcp: {
         bootstrap: "inline-config" | "project-config" | "allow-list" | "unsupported";
@@ -151,6 +151,8 @@ type AgentLike$1 = {
     tools?: Record<string, unknown>;
     /** Optional structured capability registry for cache and diagnostics */
     capabilities?: AgentCapabilityRegistry$1;
+    /** True when the agent consumes outputSchema through a native structured-output API. */
+    supportsNativeStructuredOutput?: boolean;
     /**
      * Generates a response or action based on the provided arguments.
      *
@@ -762,6 +764,42 @@ declare class ForgeAgent extends BaseCliAgent {
 type CliOutputInterpreter = CliOutputInterpreter$8;
 type ForgeAgentOptions = ForgeAgentOptions$1;
 
+type OpenCodeAgentOptions$1 = BaseCliAgentOptions$1 & {
+    /** Model identifier (e.g., "anthropic/claude-opus-4-20250514", "openai/gpt-5.4") */
+    model?: string;
+    /** OpenCode agent name (maps to --agent flag, selects predefined agent config) */
+    agentName?: string;
+    /** Files to attach to the prompt via -f flags */
+    attachFiles?: string[];
+    /** Continue a previous session */
+    continueSession?: boolean;
+    /** Resume a specific session by ID */
+    sessionId?: string;
+    /** Provider-specific model variant/reasoning effort level */
+    variant?: string;
+};
+
+declare class OpenCodeAgent extends BaseCliAgent {
+    constructor(opts?: OpenCodeAgentOptions);
+    opts: OpenCodeAgentOptions$1;
+    capabilities: AgentCapabilityRegistry$3;
+    cliEngine: "opencode";
+    createOutputInterpreter(): CliOutputInterpreter;
+    buildCommand(params: {
+        prompt: string;
+        systemPrompt?: string;
+        cwd: string;
+        options: any;
+    }): Promise<{
+        command: string;
+        args: string[];
+        outputFormat: "stream-json";
+        env?: Record<string, string>;
+        stdoutBannerPatterns: RegExp[];
+        stdoutErrorPatterns: RegExp[];
+    }>;
+}
+
 /**
  * @param {CreateSmithersAgentContractOptions} options
  * @returns {SmithersAgentContract}
@@ -821,6 +859,7 @@ type AgentCapabilityRegistry = AgentCapabilityRegistry$3;
 type AgentLike = AgentLike$1;
 type AgentToolDescriptor = AgentToolDescriptor$1;
 type AnthropicAgentOptions<CALL_OPTIONS = never, TOOLS = ai.ToolSet> = AnthropicAgentOptions$2<CALL_OPTIONS, TOOLS>;
+type OpenCodeAgentOptions = OpenCodeAgentOptions$1;
 type OpenAIAgentOptions<CALL_OPTIONS = never, TOOLS = ai.ToolSet> = OpenAIAgentOptions$2<CALL_OPTIONS, TOOLS>;
 type PiAgentOptions = PiAgentOptions$2;
 type PiExtensionUiRequest = PiExtensionUiRequest$1;
@@ -831,4 +870,4 @@ type SmithersAgentToolCategory = SmithersAgentToolCategory$1;
 type SmithersListedTool = SmithersListedTool$2;
 type SmithersToolSurface = SmithersToolSurface$2;
 
-export { type AgentCapabilityRegistry, type AgentGenerateOptions, type AgentLike, type AgentToolDescriptor, AmpAgent, AnthropicAgent, type AnthropicAgentOptions, BaseCliAgent, ClaudeCodeAgent, CodexAgent, ForgeAgent, GeminiAgent, KimiAgent, OpenAIAgent, type OpenAIAgentOptions, PiAgent, type PiAgentOptions, type PiExtensionUiRequest, type PiExtensionUiResponse, type SmithersAgentContract, type SmithersAgentContractTool, type SmithersAgentToolCategory, type SmithersListedTool, type SmithersToolSurface, createSmithersAgentContract, hashCapabilityRegistry, renderSmithersAgentPromptGuidance, sanitizeForOpenAI, zodToOpenAISchema };
+export { type AgentCapabilityRegistry, type AgentGenerateOptions, type AgentLike, type AgentToolDescriptor, AmpAgent, AnthropicAgent, type AnthropicAgentOptions, BaseCliAgent, ClaudeCodeAgent, CodexAgent, ForgeAgent, GeminiAgent, KimiAgent, OpenAIAgent, type OpenAIAgentOptions, OpenCodeAgent, type OpenCodeAgentOptions, PiAgent, type PiAgentOptions, type PiExtensionUiRequest, type PiExtensionUiResponse, type SmithersAgentContract, type SmithersAgentContractTool, type SmithersAgentToolCategory, type SmithersListedTool, type SmithersToolSurface, createSmithersAgentContract, hashCapabilityRegistry, renderSmithersAgentPromptGuidance, sanitizeForOpenAI, zodToOpenAISchema };

package/src/index.js

@@ -16,6 +16,7 @@
 /** @typedef {import("./PiAgentOptions.ts").PiAgentOptions} PiAgentOptions */
 /** @typedef {import("./BaseCliAgent/PiExtensionUiRequest.ts").PiExtensionUiRequest} PiExtensionUiRequest */
 /** @typedef {import("./BaseCliAgent/PiExtensionUiResponse.ts").PiExtensionUiResponse} PiExtensionUiResponse */
+/** @typedef {import("./OpenCodeAgent.ts").OpenCodeAgentOptions} OpenCodeAgentOptions */
 /** @typedef {import("./agent-contract/SmithersAgentContract.ts").SmithersAgentContract} SmithersAgentContract */
 /** @typedef {import("./agent-contract/SmithersAgentContractTool.ts").SmithersAgentContractTool} SmithersAgentContractTool */
 /** @typedef {import("./agent-contract/SmithersAgentToolCategory.ts").SmithersAgentToolCategory} SmithersAgentToolCategory */
@@ -34,6 +35,7 @@ export { GeminiAgent } from "./GeminiAgent.js";
 export { PiAgent } from "./PiAgent.js";
 export { KimiAgent } from "./KimiAgent.js";
 export { ForgeAgent } from "./ForgeAgent.js";
+export { OpenCodeAgent } from "./OpenCodeAgent.js";
 export { createSmithersAgentContract } from "./agent-contract/createSmithersAgentContract.js";
 export { renderSmithersAgentPromptGuidance } from "./agent-contract/renderSmithersAgentPromptGuidance.js";
 export { zodToOpenAISchema } from "./zodToOpenAISchema.js";