@smithers-orchestrator/agents 0.16.9 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/agents",
-  "version": "0.16.9",
+  "version": "0.18.0",
   "description": "AI SDK and CLI agent adapters for Smithers",
   "type": "module",
   "sideEffects": false,
@@ -48,13 +48,15 @@
     "@ai-sdk/anthropic": "^3.0.71",
     "@ai-sdk/openai": "^3.0.53",
     "ai": "^6.0.168",
+    "effect": "^3.21.1",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/driver": "0.16.9",
-    "@smithers-orchestrator/errors": "0.16.9",
-    "@smithers-orchestrator/observability": "0.16.9"
+    "@smithers-orchestrator/errors": "0.18.0",
+    "@smithers-orchestrator/observability": "0.18.0",
+    "@smithers-orchestrator/driver": "0.18.0"
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "react": "^19.2.5",
     "typescript": "~5.9.3"
   },
   "scripts": {

package/src/AgentLike.ts

@@ -1,4 +1,5 @@
 import type { AgentCapabilityRegistry } from "./capability-registry";
+import type { AgentGenerateOptions } from "./BaseCliAgent/AgentGenerateOptions";
 
 /**
  * Represents an entity capable of generating responses or actions based on prompts.
@@ -11,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.
    *
@@ -24,5 +27,5 @@ export type AgentLike = {
    * @param args.outputSchema - Optional Zod schema defining the expected structured output format
    * @returns A promise resolving to the generated output
    */
-  generate: (args: unknown) => Promise<unknown>;
+  generate: (args?: AgentGenerateOptions) => Promise<unknown>;
 };

package/src/AmpAgent.js

@@ -3,6 +3,7 @@
 // @smithers-type-exports-end
 
 import { BaseCliAgent, pushFlag, isRecord, asString, toolKindFromName, createSyntheticIdGenerator, } from "./BaseCliAgent/index.js";
+/** @typedef {import("./capability-registry/AgentCapabilityRegistry.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
 /** @typedef {import("./BaseCliAgent/CliOutputInterpreter.ts").CliOutputInterpreter} CliOutputInterpreter */
 
 /**
@@ -11,6 +12,7 @@ import { BaseCliAgent, pushFlag, isRecord, asString, toolKindFromName, createSyn
  */
 export class AmpAgent extends BaseCliAgent {
     opts;
+    /** @type {AgentCapabilityRegistry} */
     capabilities;
     cliEngine = "amp";
     /**

package/src/AnthropicAgent.js

@@ -1,8 +1,9 @@
 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 */
+/** @typedef {import("./BaseCliAgent/AgentGenerateOptions.ts").AgentGenerateOptions} AgentGenerateOptions */
 
 /**
  * @template [CALL_OPTIONS=never], [TOOLS=import("ai").ToolSet]
@@ -16,6 +17,7 @@ import { streamResultToGenerateResult } from "./streamResultToGenerateResult.js"
 
 export class AnthropicAgent extends ToolLoopAgent {
     hijackEngine = "anthropic-sdk";
+    supportsNativeStructuredOutput = true;
     /**
    * @param {AnthropicAgentOptions<CALL_OPTIONS, TOOLS>} opts
    */
@@ -27,18 +29,22 @@ export class AnthropicAgent extends ToolLoopAgent {
         });
     }
     /**
-   * @param {ExtendedGenerateArgs<CALL_OPTIONS, TOOLS>} args
+   * @param {AgentGenerateOptions} [args]
    * @returns {Promise<GenerateTextResult<TOOLS, never>>}
    */
-    generate(args) {
+    generate(args = {}) {
         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,
             });
@@ -47,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/AgentGenerateOptions.ts

@@ -0,0 +1,24 @@
+import type { AgentCliEvent } from "./AgentCliEvent";
+
+/**
+ * Loosely-typed generation options. The AI SDK passes a dynamic shape here
+ * (GenerateTextOptions / StreamTextOptions and provider-specific extensions)
+ * so we keep this permissive but avoid raw `any`.
+ */
+export type AgentGenerateOptions = {
+  prompt?: unknown;
+  messages?: unknown;
+  timeout?: unknown;
+  abortSignal?: AbortSignal;
+  rootDir?: string;
+  resumeSession?: string;
+  maxOutputBytes?: number;
+  onStdout?: (text: string) => void;
+  onStderr?: (text: string) => void;
+  onEvent?: (event: AgentCliEvent) => unknown;
+  retry?: unknown;
+  isRetry?: unknown;
+  retryAttempt?: unknown;
+  schemaRetry?: unknown;
+  [key: string]: unknown;
+};

package/src/BaseCliAgent/BaseCliAgent.js

@@ -3,7 +3,7 @@ import { promises as fs } from "node:fs";
 import { Cause, Effect, Exit, Metric } from "effect";
 import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
 import { logDebug, logInfo, logWarning } from "@smithers-orchestrator/observability/logging";
-import { agentDurationMs, agentErrorsTotal, agentInvocationsTotal, agentRetriesTotal, agentTokensTotal, toolOutputTruncatedTotal, } from "@smithers-orchestrator/observability/metrics";
+import { agentDurationMs, agentErrorsTotal, agentInvocationsTotal, agentRetriesTotal, agentTokensTotal, } from "@smithers-orchestrator/observability/metrics";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { launchDiagnostics, enrichReportWithErrorAnalysis, formatDiagnosticSummary } from "../diagnostics/index.js";
 import { extractPrompt } from "./extractPrompt.js";
@@ -16,6 +16,7 @@ import { buildGenerateResult } from "./buildGenerateResult.js";
 import { runCommandEffect } from "./runCommandEffect.js";
 /** @typedef {import("./AgentCliEvent.ts").AgentCliEvent} AgentCliEvent */
 
+/** @typedef {import("./AgentGenerateOptions.ts").AgentGenerateOptions} AgentGenerateOptions */
 /** @typedef {import("./BaseCliAgentOptions.ts").BaseCliAgentOptions} BaseCliAgentOptions */
 /** @typedef {import("./CliOutputInterpreter.ts").CliOutputInterpreter} CliOutputInterpreter */
 /** @typedef {import("./CliUsageInfo.ts").CliUsageInfo} CliUsageInfo */
@@ -38,29 +39,6 @@ import { runCommandEffect } from "./runCommandEffect.js";
  *   totalTokens?: number;
  * }} AgentTokenTotals
  */
-/**
- * Loosely-typed generation options. The AI SDK passes a dynamic shape here
- * (GenerateTextOptions / StreamTextOptions and provider-specific extensions)
- * so we keep this permissive but avoid raw `any`.
- * @typedef {{
- *   prompt?: unknown;
- *   messages?: unknown;
- *   timeout?: unknown;
- *   abortSignal?: AbortSignal;
- *   rootDir?: string;
- *   resumeSession?: string;
- *   maxOutputBytes?: number;
- *   onStdout?: (text: string) => void;
- *   onStderr?: (text: string) => void;
- *   onEvent?: (event: AgentCliEvent) => unknown;
- *   retry?: unknown;
- *   isRetry?: unknown;
- *   retryAttempt?: unknown;
- *   schemaRetry?: unknown;
- *   [key: string]: unknown;
- * }} AgentGenerateOptions
- */
-
 /**
  * @template A
  * @param {Effect.Effect<A, SmithersError, never>} effect
@@ -303,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}
@@ -425,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) {
@@ -475,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;
@@ -554,7 +603,7 @@ export class BaseCliAgent {
         this.extraArgs = opts.extraArgs;
     }
     /**
-   * @param {AgentGenerateOptions} [options]
+   * @param {AgentGenerateOptions | undefined} options
    * @param {AgentInvocationOperation} operation
    * @returns {Effect.Effect<GenerateTextResult<Record<string, never>, unknown>, SmithersError>}
    */
@@ -598,9 +647,52 @@ export class BaseCliAgent {
         const recordDurationMetric = () => Effect.sync(() => performance.now() - invocationStart).pipe(Effect.flatMap((durationMs) => Metric.update(taggedMetric(agentDurationMs, metricTags), durationMs)));
         /**
      * @param {string} stderr
+     * @param {ReadonlyArray<RegExp>} [extraPatterns]
      * @returns {string}
      */
-        function filterBenignStderr(stderr) {
+        const agentId = this.id;
+        const agentModel = this.model;
+        const agentEngine = resolveAgentEngineTag(this);
+        /**
+     * Detect well-known non-retryable CLI agent configuration errors so the
+     * engine surfaces them with a clear, actionable message and stops retrying
+     * (these errors are deterministic and will never recover by re-running).
+     *
+     * @param {string} message
+     * @param {string} command
+     * @returns {SmithersError | null}
+     */
+        function classifyNonRetryableAgentError(message, command) {
+            if (!message)
+                return null;
+            const nonRetryablePatterns = [
+                { re: /\bLLM not set\b/i, hint: "the agent's model name is not present in the CLI's configured providers" },
+                { re: /\bLLM not supported\b/i, hint: "the agent's model is not supported by this CLI build" },
+                { re: /\bmodel\s+['"]?[^'"\s]+['"]?\s+not found\b/i, hint: "the requested model is not registered with the CLI" },
+                { re: /\bunknown model\b/i, hint: "the requested model is not registered with the CLI" },
+                { re: /\b401\b[\s\S]{0,200}?(invalid[_\s-]?authentication|unauthorized|invalid[_\s-]?api[_\s-]?key)/i, hint: `the CLI's stored credentials are invalid or expired — re-authenticate (e.g. for kimi run \`kimi login\`)` },
+                { re: /\bAPI\s*Key\b[\s\S]{0,120}?(invalid|expired|may have expired)/i, hint: `the CLI's stored credentials are invalid or expired — re-authenticate (e.g. for kimi run \`kimi login\`)` },
+                { re: /\b(access|auth(entication)?|oauth|bearer)\s+token\b[\s\S]{0,80}?(expired|invalid|revoked)/i, hint: `the CLI's auth token is no longer valid — re-authenticate (e.g. for kimi run \`kimi login\`)` },
+                { re: /\binvalid[_\s-]?authentication[_\s-]?error\b/i, hint: `the CLI's stored credentials are invalid — re-authenticate (e.g. for kimi run \`kimi login\`)` },
+            ];
+            for (const { re, hint } of nonRetryablePatterns) {
+                if (re.test(message)) {
+                    const modelLabel = agentModel ?? "<unset>";
+                    const idLabel = agentId ?? "<anonymous>";
+                    const summary = `Agent "${idLabel}" (${command}, model=${modelLabel}) failed with non-retryable configuration error: ${message.slice(0, 300)}. Hint: ${hint}. Fix the agent's model in .smithers/agents.ts (or the CLI's config) — retrying will not help.`;
+                    return new SmithersError("AGENT_CONFIG_INVALID", summary, {
+                        failureRetryable: false,
+                        agentId: idLabel,
+                        agentEngine,
+                        agentModel: modelLabel,
+                        command,
+                        underlying: message.slice(0, 500),
+                    });
+                }
+            }
+            return null;
+        }
+        function filterBenignStderr(stderr, extraPatterns) {
             const benignPatterns = [
                 /^.*state db missing rollout path.*$/gm,
                 /^.*codex_core::rollout::list.*$/gm,
@@ -612,6 +704,12 @@ export class BaseCliAgent {
             for (const pattern of benignPatterns) {
                 filtered = filtered.replace(pattern, "");
             }
+            if (extraPatterns?.length) {
+                for (const pattern of extraPatterns) {
+                    const regex = new RegExp(pattern.source, pattern.flags);
+                    filtered = filtered.replace(regex, "");
+                }
+            }
             // Clean up extra blank lines
             return filtered.replace(/\n{3,}/g, "\n\n").trim();
         }
@@ -663,6 +761,7 @@ export class BaseCliAgent {
             const interpreter = this.createOutputInterpreter();
             let stdoutBuffer = "";
             let stderrBuffer = "";
+            let completedEvent = null;
             /**
      * @param {AgentCliEvent[] | AgentCliEvent | null | undefined} eventPayload
      */
@@ -671,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;
@@ -750,14 +852,44 @@ export class BaseCliAgent {
                     }).pipe(Effect.catchAll(() => Effect.succeed(result.stdout)))
                     : result.stdout;
                 if (result.exitCode && result.exitCode !== 0) {
-                    const filteredStderr = filterBenignStderr(result.stderr);
+                    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);
+                        if (nonRetryable) {
+                            return yield* Effect.fail(nonRetryable);
+                        }
+                        // Detect kimi session-loss. Kimi crashes mid-stream and prints
+                        // `To resume this session: kimi -r <uuid>` to stderr (and often
+                        // also to the merged error text after the benign-stderr filter
+                        // strips the bare-line variant). The session itself is corrupt
+                        // — re-running with `--session <same-uuid>` deterministically
+                        // reproduces the same crash. Surface a typed error that tells
+                        // the engine retry path to DROP the broken session id and
+                        // start a fresh one on the next attempt.
+                        const rawStderr = result.stderr ?? "";
+                        const sessionLossMatch = rawStderr.match(/kimi -r ([0-9a-f-]{8,})/i)
+                            || errorText.match(/kimi -r ([0-9a-f-]{8,})/i);
+                        if (commandSpec.command === "kimi" && sessionLossMatch) {
+                            return yield* Effect.fail(new SmithersError("AGENT_SESSION_LOST", `Kimi session ${sessionLossMatch[1]} is broken; CLI exited ${result.exitCode}. Retry will start a fresh session.`, {
+                                failureRetryable: true,
+                                discardResumeSession: true,
+                                command: "kimi",
+                                kimiSessionId: sessionLossMatch[1],
+                            }));
+                        }
                         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 ?? [];
@@ -778,7 +910,9 @@ export class BaseCliAgent {
                     for (const pattern of stdoutErrorPatterns) {
                         const regex = new RegExp(pattern.source, pattern.flags);
                         if (regex.test(rawText)) {
-                            return yield* Effect.fail(new SmithersError("AGENT_CLI_ERROR", `CLI agent error (stdout): ${rawText.slice(0, 500)}`));
+                            const stdoutErrText = `CLI agent error (stdout): ${rawText.slice(0, 500)}`;
+                            const nonRetryable = classifyNonRetryableAgentError(rawText, commandSpec.command);
+                            return yield* Effect.fail(nonRetryable ?? new SmithersError("AGENT_CLI_ERROR", stdoutErrText));
                         }
                     }
                 }
@@ -801,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/extractPrompt.js

@@ -1,4 +1,3 @@
-import { extractTextFromJsonValue } from "./extractTextFromJsonValue.js";
 /** @typedef {import("ai").ModelMessage} ModelMessage */
 /**
  * @typedef {{ prompt: string; systemFromMessages?: string; }} PromptParts

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/BaseCliAgent/index.js

@@ -6,6 +6,7 @@
 /** @typedef {import("./AgentCliEvent.ts").AgentCliEvent} AgentCliEvent */
 /** @typedef {import("./AgentCliEvent.ts").AgentCliEventLevel} AgentCliEventLevel */
 /** @typedef {import("./AgentCliEvent.ts").AgentCliStartedEvent} AgentCliStartedEvent */
+/** @typedef {import("./AgentGenerateOptions.ts").AgentGenerateOptions} AgentGenerateOptions */
 /** @typedef {import("./BaseCliAgentOptions.ts").BaseCliAgentOptions} BaseCliAgentOptions */
 /** @typedef {import("./CliOutputInterpreter.ts").CliOutputInterpreter} CliOutputInterpreter */
 /** @typedef {import("./CliUsageInfo.ts").CliUsageInfo} CliUsageInfo */

package/src/ClaudeCodeAgent.js

@@ -97,15 +97,16 @@ export class ClaudeCodeAgent extends BaseCliAgent {
         // Clear env vars that cause "Cannot run nested Claude Code instances" errors.
         // CLAUDE_CODE_ENTRYPOINT / CLAUDECODE are set by a parent Claude Code process;
         // child instances refuse to start when they detect these.
-        // ANTHROPIC_API_KEY is cleared so Claude Code uses the subscription instead of API billing.
+        // ANTHROPIC_API_KEY is cleared so Claude Code uses the subscription instead of API billing,
+        // unless the caller explicitly opts in by passing `apiKey`.
         const parentEnvOverrides = {};
         if (process.env.CLAUDE_CODE_ENTRYPOINT)
             parentEnvOverrides.CLAUDE_CODE_ENTRYPOINT = "";
         if (process.env.CLAUDECODE)
             parentEnvOverrides.CLAUDECODE = "";
-        if (process.env.ANTHROPIC_API_KEY) {
+        if (process.env.ANTHROPIC_API_KEY && !opts.apiKey) {
             logWarning("ClaudeCodeAgent: unsetting ANTHROPIC_API_KEY so Claude Code uses your subscription. " +
-                "To use API billing instead, use ToolLoopAgent from 'ai' with anthropic() provider.", {}, "agent.init");
+                "To use API billing instead, pass `apiKey` to ClaudeCodeAgent or use ToolLoopAgent from 'ai' with anthropic() provider.", {}, "agent.init");
             parentEnvOverrides.ANTHROPIC_API_KEY = "";
         }
         if (Object.keys(parentEnvOverrides).length > 0) {
@@ -446,10 +447,16 @@ export class ClaudeCodeAgent extends BaseCliAgent {
             args.push(...this.extraArgs);
         if (params.prompt)
             args.push(params.prompt);
+        const accountEnv = {};
+        if (this.opts.configDir)
+            accountEnv.CLAUDE_CONFIG_DIR = this.opts.configDir;
+        if (this.opts.apiKey)
+            accountEnv.ANTHROPIC_API_KEY = this.opts.apiKey;
         return {
             command: "claude",
             args,
             outputFormat,
+            env: Object.keys(accountEnv).length > 0 ? accountEnv : undefined,
         };
     }
 }

package/src/ClaudeCodeAgentOptions.ts

@@ -9,6 +9,22 @@ export type ClaudeCodeAgentOptions = BaseCliAgentOptions & {
   allowDangerouslySkipPermissions?: boolean;
   allowedTools?: string[];
   appendSystemPrompt?: string;
+  /**
+   * Path to an isolated Claude Code config directory. Sets `CLAUDE_CONFIG_DIR`
+   * on the spawned process so this invocation uses the credentials stored at
+   * `<configDir>/.credentials.json` (instead of the user's default `~/.claude/`).
+   *
+   * Use this to run multiple Claude Code subscriptions side-by-side. Set up
+   * the directory by running `CLAUDE_CONFIG_DIR=<path> claude` once and
+   * completing `/login` interactively.
+   */
+  configDir?: string;
+  /**
+   * Anthropic API key for billing this invocation against the API instead of
+   * a Claude Pro/Max subscription. When set, ClaudeCodeAgent stops unsetting
+   * `ANTHROPIC_API_KEY` (which it normally clears so subscription auth wins).
+   */
+  apiKey?: string;
   betas?: string[];
   chrome?: boolean;
   continue?: boolean;

package/src/CodexAgent.js

@@ -567,12 +567,18 @@ export class CodexAgent extends BaseCliAgent {
             : "";
         const fullPrompt = `${systemPrefix}${params.prompt ?? ""}`;
         args.push("-");
+        const accountEnv = {};
+        if (this.opts.configDir)
+            accountEnv.CODEX_HOME = this.opts.configDir;
+        if (this.opts.apiKey)
+            accountEnv.OPENAI_API_KEY = this.opts.apiKey;
         return {
             command: "codex",
             args,
             stdin: fullPrompt,
             outputFile,
             outputFormat: "stream-json",
+            env: Object.keys(accountEnv).length > 0 ? accountEnv : undefined,
             stdoutBannerPatterns: [
                 // Codex CLI prints a startup banner like:
                 // "OpenAI Codex v0.99.0-alpha.13 (research preview)"

package/src/CodexAgentOptions.ts

@@ -20,4 +20,19 @@ export type CodexAgentOptions = BaseCliAgentOptions & {
   color?: "always" | "never" | "auto";
   json?: boolean;
   outputLastMessage?: string;
+  /**
+   * Path to an isolated Codex CLI config directory. Sets `CODEX_HOME` on the
+   * spawned process so this invocation uses the credentials stored at
+   * `<configDir>/auth.json` (instead of the user's default `~/.codex/`).
+   *
+   * Use this to run multiple Codex / ChatGPT subscriptions side-by-side. Set
+   * up the directory by running `CODEX_HOME=<path> codex login` once.
+   */
+  configDir?: string;
+  /**
+   * OpenAI API key for billing this invocation against the API instead of a
+   * ChatGPT Plus/Pro subscription. Sets `OPENAI_API_KEY` on the spawned
+   * process.
+   */
+  apiKey?: string;
 };

package/src/ForgeAgent.js

@@ -1,11 +1,13 @@
 import { BaseCliAgent, pushFlag, } from "./BaseCliAgent/index.js";
 import { randomUUID } from "node:crypto";
+/** @typedef {import("./capability-registry/AgentCapabilityRegistry.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
 /** @typedef {import("./BaseCliAgent/BaseCliAgentOptions.ts").BaseCliAgentOptions} BaseCliAgentOptions */
 /** @typedef {import("./BaseCliAgent/CliOutputInterpreter.ts").CliOutputInterpreter} CliOutputInterpreter */
 /** @typedef {import("./ForgeAgentOptions.ts").ForgeAgentOptions} ForgeAgentOptions */
 
 export class ForgeAgent extends BaseCliAgent {
     opts;
+    /** @type {AgentCapabilityRegistry} */
     capabilities;
     cliEngine = "forge";
     issuedConversationId;

package/src/GeminiAgent.js

@@ -56,7 +56,6 @@ export class GeminiAgent extends BaseCliAgent {
     createOutputInterpreter() {
         let sessionId;
         let finalAnswer = "";
-        let emittedStarted = false;
         let didEmitCompleted = false;
         const nextSyntheticId = createSyntheticIdGenerator();
         /**
@@ -84,7 +83,6 @@ export class GeminiAgent extends BaseCliAgent {
                 if (resume) {
                     sessionId = resume;
                 }
-                emittedStarted = true;
                 return [{
                         type: "started",
                         engine: this.cliEngine,
@@ -264,10 +262,16 @@ export class GeminiAgent extends BaseCliAgent {
             : "";
         const fullPrompt = `${systemPrefix}${params.prompt ?? ""}${jsonReminder}`;
         args.push("--prompt", fullPrompt);
+        const accountEnv = {};
+        if (this.opts.configDir)
+            accountEnv.GEMINI_DIR = this.opts.configDir;
+        if (this.opts.apiKey)
+            accountEnv.GEMINI_API_KEY = this.opts.apiKey;
         return {
             command: "gemini",
             args,
             outputFormat,
+            env: Object.keys(accountEnv).length > 0 ? accountEnv : undefined,
         };
     }
 }

package/src/GeminiAgentOptions.ts

@@ -17,4 +17,16 @@ export type GeminiAgentOptions = BaseCliAgentOptions & {
   includeDirectories?: string[];
   screenReader?: boolean;
   outputFormat?: "text" | "json" | "stream-json";
+  /**
+   * Path to an isolated Gemini CLI config directory. Sets `GEMINI_DIR` on the
+   * spawned process so this invocation uses the credentials stored at
+   * `<configDir>/oauth_creds.json` (instead of the user's default
+   * `~/.gemini/`). Use this to run multiple Gemini accounts side-by-side.
+   */
+  configDir?: string;
+  /**
+   * Gemini API key. Sets `GEMINI_API_KEY` on the spawned process for
+   * API-billed invocations.
+   */
+  apiKey?: string;
 };