@smithers-orchestrator/agents 0.16.8 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/agents",
-  "version": "0.16.8",
+  "version": "0.17.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.8",
-    "@smithers-orchestrator/errors": "0.16.8",
-    "@smithers-orchestrator/observability": "0.16.8"
+    "@smithers-orchestrator/driver": "0.17.0",
+    "@smithers-orchestrator/errors": "0.17.0",
+    "@smithers-orchestrator/observability": "0.17.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.
@@ -24,5 +25,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

@@ -3,6 +3,7 @@ import { 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]
@@ -27,10 +28,10 @@ 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 };

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
@@ -554,7 +532,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 +576,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 +633,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();
         }
@@ -750,11 +777,34 @@ 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 ||
                             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));
                     }
                 }
@@ -778,7 +828,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));
                         }
                     }
                 }

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/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;
 };

package/src/KimiAgent.js

@@ -1,9 +1,190 @@
-import { mkdtempSync, cpSync, existsSync, rmSync } from "node:fs";
+import { mkdtempSync, cpSync, existsSync, readFileSync, writeFileSync, readdirSync, rmSync, renameSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { tmpdir, homedir } from "node:os";
 import { BaseCliAgent, pushFlag, pushList, isRecord, asString, toolKindFromName, createSyntheticIdGenerator, } from "./BaseCliAgent/index.js";
 import { normalizeCapabilityStringList, } from "./capability-registry/index.js";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+
+/**
+ * The kimi CLI's OAuth refresh endpoint, mirroring the Python implementation
+ * in `kimi_cli.auth.oauth.refresh_token`. Honour the same env-var override
+ * the CLI uses (KIMI_OAUTH_HOST) so test/staging overrides keep working.
+ */
+function kimiOAuthHost() {
+    return process.env.KIMI_OAUTH_HOST?.replace(/\/+$/, "") || "https://auth.kimi.com";
+}
+
+/**
+ * Process-level dedup map: if multiple parallel KimiAgent invocations land in
+ * the refresh path concurrently, share one in-flight Promise so we issue a
+ * single POST instead of racing (kimi rotates refresh tokens — only one
+ * refresh wins, the other gets invalid_grant and would be wrongly classified
+ * as expired).
+ *
+ * @type {Map<string, Promise<void>>}
+ */
+const inflightRefreshes = new Map();
+
+async function refreshKimiTokenIfNeeded(credsDir, fileName) {
+    const path = join(credsDir, fileName);
+    /** @type {{access_token?: string, refresh_token?: string, expires_at?: number, token_type?: string, scope?: string} | null} */
+    let data = null;
+    try {
+        data = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return { ok: false, reason: "unreadable", expiredAt: null };
+    }
+    if (!data || typeof data.expires_at !== "number") {
+        // Not an OAuth file — leave alone, kimi will handle.
+        return { ok: true, refreshed: false };
+    }
+    // Refresh proactively a bit before expiry to avoid races (matches the
+    // CLI's _refresh_threshold behaviour, simplified to a fixed 60s window).
+    const nowSec = Date.now() / 1000;
+    if (data.expires_at - 60 > nowSec) {
+        return { ok: true, refreshed: false };
+    }
+    if (typeof data.refresh_token !== "string" || data.refresh_token.length === 0) {
+        return { ok: false, reason: "no-refresh-token", expiredAt: new Date(data.expires_at * 1000).toISOString() };
+    }
+    // Dedupe concurrent refreshes per-credential-file within this process.
+    const flightKey = path;
+    const inflight = inflightRefreshes.get(flightKey);
+    if (inflight) {
+        try {
+            await inflight;
+            return { ok: true, refreshed: true, deduped: true };
+        }
+        catch (err) {
+            return { ok: false, reason: err?.message ?? "refresh-failed", expiredAt: new Date(data.expires_at * 1000).toISOString() };
+        }
+    }
+    const refresher = (async () => {
+        const tokenUrl = `${kimiOAuthHost()}/api/oauth/token`;
+        // client_id matches kimi_cli.auth.oauth.KIMI_CODE_CLIENT_ID. Without it the
+        // /api/oauth/token endpoint returns 400 invalid_request.
+        const body = new URLSearchParams({
+            client_id: "17e5f671-d194-4dfb-9706-5516cb48c098",
+            grant_type: "refresh_token",
+            refresh_token: data.refresh_token,
+        });
+        // Mirror kimi-cli's `_common_headers()` so the auth service treats this
+        // refresh as coming from a legitimate kimi-cli install. Some of these
+        // (notably X-Msh-Device-Id) appear to gate refresh acceptance.
+        const headers = {
+            "Content-Type": "application/x-www-form-urlencoded",
+            "X-Msh-Platform": "kimi_cli",
+            "X-Msh-Version": "1.37.0",
+            "X-Msh-Device-Name": "smithers-orchestrator",
+            "X-Msh-Device-Model": "smithers-orchestrator",
+            "X-Msh-Os-Version": process.platform,
+        };
+        try {
+            const deviceIdPath = join(credsDir, "..", "device_id");
+            if (existsSync(deviceIdPath)) {
+                const deviceId = readFileSync(deviceIdPath, "utf8").trim();
+                if (deviceId)
+                    headers["X-Msh-Device-Id"] = deviceId;
+            }
+        }
+        catch { /* device-id is optional */ }
+        const resp = await fetch(tokenUrl, {
+            method: "POST",
+            headers,
+            body,
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => "");
+            const tag = resp.status === 401 ? "invalid_grant" : `http-${resp.status}`;
+            throw new Error(`kimi oauth refresh failed (${tag}): ${text.slice(0, 200)}`);
+        }
+        /** @type {any} */
+        const fresh = await resp.json();
+        if (typeof fresh?.access_token !== "string") {
+            throw new Error("kimi oauth refresh: missing access_token in response");
+        }
+        const expiresIn = typeof fresh.expires_in === "number"
+            ? fresh.expires_in
+            : 3600;
+        const merged = {
+            ...data,
+            access_token: fresh.access_token,
+            refresh_token: typeof fresh.refresh_token === "string" ? fresh.refresh_token : data.refresh_token,
+            token_type: typeof fresh.token_type === "string" ? fresh.token_type : data.token_type,
+            scope: typeof fresh.scope === "string" ? fresh.scope : data.scope,
+            expires_in: expiresIn,
+            expires_at: Math.floor(Date.now() / 1000) + expiresIn,
+        };
+        // Write atomically so kimi-cli reading concurrently never sees a torn file.
+        const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+        writeFileSync(tmp, JSON.stringify(merged, null, 2), { mode: 0o600 });
+        renameSync(tmp, path);
+    })();
+    inflightRefreshes.set(flightKey, refresher);
+    try {
+        await refresher;
+        return { ok: true, refreshed: true };
+    }
+    catch (err) {
+        return { ok: false, reason: err?.message ?? "refresh-failed", expiredAt: new Date(data.expires_at * 1000).toISOString() };
+    }
+    finally {
+        inflightRefreshes.delete(flightKey);
+    }
+}
+
+/**
+ * Inspect the kimi CLI's on-disk OAuth credentials and, if any are expired,
+ * attempt a non-interactive refresh against `${KIMI_OAUTH_HOST or
+ * https://auth.kimi.com}/api/oauth/token` using the stored refresh_token.
+ * Only if refresh fails do we surface a clear, non-retryable
+ * AGENT_CONFIG_INVALID error.
+ *
+ * @param {string} shareDir
+ * @param {string} agentId
+ * @param {string} agentModel
+ */
+async function ensureKimiCredentialsUsable(shareDir, agentId, agentModel) {
+    const credsDir = join(shareDir, "credentials");
+    if (!existsSync(credsDir))
+        return; // No creds dir → kimi will print "LLM not set" which the BaseCliAgent classifier handles.
+    let entries;
+    try {
+        entries = readdirSync(credsDir);
+    }
+    catch {
+        return;
+    }
+    const tokenFiles = entries.filter((n) => n.endsWith(".json"));
+    if (tokenFiles.length === 0)
+        return;
+    let lastFailure = null;
+    let anyUsable = false;
+    for (const name of tokenFiles) {
+        const result = await refreshKimiTokenIfNeeded(credsDir, name);
+        if (result.ok) {
+            anyUsable = true;
+        }
+        else {
+            lastFailure = result;
+        }
+    }
+    if (!anyUsable && lastFailure) {
+        const reason = lastFailure.reason === "no-refresh-token"
+            ? `OAuth token expired at ${lastFailure.expiredAt} and no refresh_token is stored`
+            : `OAuth token expired at ${lastFailure.expiredAt}; auto-refresh failed: ${lastFailure.reason}`;
+        throw new SmithersError("AGENT_CONFIG_INVALID", `${reason}. Run \`kimi login\` to re-authenticate, then resume the run. (agent="${agentId}", model="${agentModel}", credentials="${credsDir}")`, {
+            failureRetryable: false,
+            agentId,
+            agentEngine: "kimi",
+            agentModel,
+            command: "kimi",
+            underlying: reason,
+        });
+    }
+}
 /** @typedef {import("./BaseCliAgent/BaseCliAgentOptions.ts").BaseCliAgentOptions} BaseCliAgentOptions */
 /** @typedef {import("./capability-registry/AgentCapabilityRegistry.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
 /** @typedef {import("./BaseCliAgent/CliOutputInterpreter.ts").CliOutputInterpreter} CliOutputInterpreter */
@@ -165,13 +346,18 @@ export class KimiAgent extends BaseCliAgent {
         let cleanup;
         // Isolate kimi metadata per invocation to avoid concurrent writes to
         // ~/.kimi/kimi.json across parallel tasks. If caller explicitly provides
-        // KIMI_SHARE_DIR in opts.env, preserve that override.
-        if (!this.opts.env?.KIMI_SHARE_DIR) {
-            const defaultShareDir = process.env.KIMI_SHARE_DIR ?? join(homedir(), ".kimi");
+        // configDir or KIMI_SHARE_DIR in opts.env, preserve that override.
+        const explicitShareDir = this.opts.configDir ?? this.opts.env?.KIMI_SHARE_DIR;
+        const sourceShareDir = explicitShareDir ?? process.env.KIMI_SHARE_DIR ?? join(homedir(), ".kimi");
+        // Refresh expired OAuth credentials in place using the stored refresh_token,
+        // and only fail fast (non-retryable) if the refresh itself fails. This avoids
+        // forcing the user to run `kimi login` every time their access_token rotates.
+        await ensureKimiCredentialsUsable(sourceShareDir, this.id ?? "<anonymous>", this.opts.model ?? this.model ?? "<unset>");
+        if (!explicitShareDir) {
             const isolatedShareDir = mkdtempSync(join(tmpdir(), "kimi-share-"));
-            if (existsSync(defaultShareDir)) {
+            if (existsSync(sourceShareDir)) {
                 for (const name of ["config.toml", "credentials", "device_id", "latest_version.txt"]) {
-                    const src = join(defaultShareDir, name);
+                    const src = join(sourceShareDir, name);
                     if (existsSync(src)) {
                         try {
                             cpSync(src, join(isolatedShareDir, name), { recursive: true });
@@ -187,6 +373,11 @@ export class KimiAgent extends BaseCliAgent {
                 rmSync(isolatedShareDir, { recursive: true, force: true });
             };
         }
+        else if (this.opts.configDir) {
+            // configDir takes precedence over any env-var inheritance: spawn the
+            // CLI with KIMI_SHARE_DIR pointing at the user-specified path.
+            commandEnv = { KIMI_SHARE_DIR: this.opts.configDir };
+        }
         // Print mode is required for non-interactive execution
         // Note: --print implicitly adds --yolo
         args.push("--print");
@@ -253,6 +444,20 @@ export class KimiAgent extends BaseCliAgent {
                 /^Interrupted by user$/i,
                 /^Unknown error:/i,
                 /^Error:/i,
+                // Auth failures kimi prints when OAuth/api-key is invalid or expired.
+                // BaseCliAgent's classifyNonRetryableAgentError treats these as
+                // non-retryable so the run does not waste turns on a 401 loop.
+                /Error code:\s*401\b[^\n]*/i,
+                /\binvalid_authentication_error\b/i,
+                /API\s*Key\s+appears to be invalid or may have expired/i,
+            ],
+            // The kimi CLI emits "To resume this session: kimi -r <id>" to stderr
+            // on every non-zero exit (it's a hint for interactive users, not the
+            // actual error). Strip it so the real underlying error surfaces — and
+            // when it's the only stderr content, our runner will fall back to a
+            // useful "exited with code N" message that the engine can retry.
+            benignStderrPatterns: [
+                /^\s*To resume this session: kimi -r [0-9a-f-]+\s*$/gim,
             ],
             errorOnBannerOnly: true,
         };

package/src/KimiAgentOptions.ts

@@ -18,4 +18,12 @@ export type KimiAgentOptions = BaseCliAgentOptions & {
   maxRalphIterations?: number;
   verbose?: boolean;
   debug?: boolean;
+  /**
+   * Path to an isolated Kimi share directory. Sets `KIMI_SHARE_DIR` on the
+   * spawned process so this invocation reads/writes credentials at
+   * `<configDir>/credentials` (instead of the user's default `~/.kimi/`).
+   * Equivalent to passing `env: { KIMI_SHARE_DIR: <path> }` but uniform with
+   * the other agents' `configDir` option.
+   */
+  configDir?: string;
 };

package/src/OpenAIAgent.js

@@ -3,6 +3,7 @@ import { 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, TOOLS
@@ -27,10 +28,10 @@ export class OpenAIAgent 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 };

package/src/PiAgent.js

@@ -4,7 +4,7 @@
 // @smithers-type-exports-end
 
 import { Effect } from "effect";
-import { BaseCliAgent, buildGenerateResult, combineNonEmpty, extractPrompt, extractTextFromJsonValue, pushFlag, resolveTimeouts, runAgentPromise, runRpcCommandEffect, tryParseJson, asString, truncate, toolKindFromName, } from "./BaseCliAgent/index.js";
+import { BaseCliAgent, buildGenerateResult, combineNonEmpty, extractPrompt, extractTextFromJsonValue, pushFlag, resolveTimeouts, runAgentPromise, runRpcCommandEffect, asString, truncate, toolKindFromName, } from "./BaseCliAgent/index.js";
 import { normalizeCapabilityStringList, } from "./capability-registry/index.js";
 import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";

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

@@ -0,0 +1,26 @@
+import type {
+  AgentLike,
+  AmpAgent,
+  AnthropicAgent,
+  ClaudeCodeAgent,
+  CodexAgent,
+  ForgeAgent,
+  GeminiAgent,
+  KimiAgent,
+  OpenAIAgent,
+  PiAgent,
+} from "../index.js";
+
+type AssertAssignable<T extends AgentLike> = T;
+
+type _ConcreteAgentsAreAgentLike = [
+  AssertAssignable<AmpAgent>,
+  AssertAssignable<AnthropicAgent>,
+  AssertAssignable<ClaudeCodeAgent>,
+  AssertAssignable<CodexAgent>,
+  AssertAssignable<ForgeAgent>,
+  AssertAssignable<GeminiAgent>,
+  AssertAssignable<KimiAgent>,
+  AssertAssignable<OpenAIAgent>,
+  AssertAssignable<PiAgent>,
+];

package/src/index.d.ts

@@ -4,7 +4,6 @@ import { ToolLoopAgent, ToolSet, ToolLoopAgentSettings } from 'ai';
 import { anthropic } from '@ai-sdk/anthropic';
 import { Effect } from 'effect';
 import { SmithersError } from '@smithers-orchestrator/errors/SmithersError';
-import * as zod from 'zod';
 import * as zod_v4_core from 'zod/v4/core';
 
 type SmithersToolSurface$2 = "raw" | "semantic";
@@ -165,7 +164,7 @@ type AgentLike$1 = {
      * @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>;
 };
 
 type RunCommandResult = {
@@ -238,11 +237,11 @@ declare class BaseCliAgent {
     maxOutputBytes: number | undefined;
     extraArgs: string[] | undefined;
     /**
-   * @param {AgentGenerateOptions} [options]
+   * @param {AgentGenerateOptions | undefined} options
    * @param {AgentInvocationOperation} operation
    * @returns {Effect.Effect<GenerateTextResult<Record<string, never>, unknown>, SmithersError>}
    */
-    runGenerateEffect(options?: AgentGenerateOptions, operation: AgentInvocationOperation): Effect.Effect<GenerateTextResult$3<Record<string, never>, unknown>, SmithersError>;
+    runGenerateEffect(options: AgentGenerateOptions | undefined, operation: AgentInvocationOperation): Effect.Effect<GenerateTextResult$3<Record<string, never>, unknown>, SmithersError>;
     /**
    * @param {AgentGenerateOptions} [options]
    * @returns {Promise<GenerateTextResult<Record<string, never>, unknown>>}
@@ -304,20 +303,12 @@ declare class AnthropicAgent extends ToolLoopAgent<never, any, never> {
     constructor(opts: AnthropicAgentOptions$1<CALL_OPTIONS, TOOLS>);
     hijackEngine: string;
     /**
-   * @param {ExtendedGenerateArgs<CALL_OPTIONS, TOOLS>} args
+   * @param {AgentGenerateOptions} [args]
    * @returns {Promise<GenerateTextResult<TOOLS, never>>}
    */
-    generate(args: ExtendedGenerateArgs$1<CALL_OPTIONS, TOOLS>): Promise<GenerateTextResult$2<TOOLS, never>>;
+    generate(args?: AgentGenerateOptions): Promise<GenerateTextResult$2<TOOLS, never>>;
 }
-type AgentCallParameters$1 = any;
 type AnthropicAgentOptions$1<CALL_OPTIONS = never, TOOLS = ai.ToolSet> = AnthropicAgentOptions$2<CALL_OPTIONS, TOOLS>;
-type ExtendedGenerateArgs$1<CALL_OPTIONS, TOOLS> = AgentCallParameters$1<CALL_OPTIONS, TOOLS> & {
-    onStdout?: (text: string) => void;
-    onStderr?: (text: string) => void;
-    onEvent?: (event: unknown) => Promise<void> | void;
-    outputSchema?: zod.ZodTypeAny;
-    resumeSession?: string;
-};
 type GenerateTextResult$2 = ai.GenerateTextResult<any, any>;
 
 /** @typedef {import("ai").AgentCallParameters} AgentCallParameters */
@@ -337,19 +328,11 @@ declare class OpenAIAgent extends ToolLoopAgent<never, any, never> {
     constructor(opts: OpenAIAgentOptions$1<CALL_OPTIONS, TOOLS>);
     hijackEngine: string;
     /**
-   * @param {ExtendedGenerateArgs<CALL_OPTIONS, TOOLS>} args
+   * @param {AgentGenerateOptions} [args]
    * @returns {Promise<GenerateTextResult<TOOLS, never>>}
    */
-    generate(args: ExtendedGenerateArgs<CALL_OPTIONS, TOOLS>): Promise<GenerateTextResult$1<TOOLS, never>>;
+    generate(args?: AgentGenerateOptions): Promise<GenerateTextResult$1<TOOLS, never>>;
 }
-type AgentCallParameters = any;
-type ExtendedGenerateArgs<CALL_OPTIONS, TOOLS> = AgentCallParameters<CALL_OPTIONS, TOOLS> & {
-    onStdout?: (text: string) => void;
-    onStderr?: (text: string) => void;
-    onEvent?: (event: unknown) => Promise<void> | void;
-    outputSchema?: zod.ZodTypeAny;
-    resumeSession?: string;
-};
 type GenerateTextResult$1 = ai.GenerateTextResult<any, any>;
 type OpenAIAgentOptions$1<CALL_OPTIONS = never, TOOLS = ai.ToolSet> = OpenAIAgentOptions$2<CALL_OPTIONS, TOOLS>;
 
@@ -391,25 +374,7 @@ declare class AmpAgent extends BaseCliAgent {
      */
     constructor(opts?: AmpAgentOptions);
     opts: AmpAgentOptions$1;
-    capabilities: {
-        version: number;
-        engine: string;
-        runtimeTools: {};
-        mcp: {
-            bootstrap: string;
-            supportsProjectScope: boolean;
-            supportsUserScope: boolean;
-        };
-        skills: {
-            supportsSkills: boolean;
-            smithersSkillIds: never[];
-        };
-        humanInteraction: {
-            supportsUiRequests: boolean;
-            methods: never[];
-        };
-        builtIns: string[];
-    };
+    capabilities: AgentCapabilityRegistry$3;
     cliEngine: string;
     /**
    * @returns {CliOutputInterpreter}
@@ -526,6 +491,21 @@ type CodexAgentOptions$1 = BaseCliAgentOptions$1 & {
     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;
 };
 
 declare class CodexAgent extends BaseCliAgent {
@@ -758,25 +738,7 @@ declare class ForgeAgent extends BaseCliAgent {
    */
     constructor(opts?: ForgeAgentOptions);
     opts: ForgeAgentOptions$1;
-    capabilities: {
-        version: number;
-        engine: string;
-        runtimeTools: {};
-        mcp: {
-            bootstrap: string;
-            supportsProjectScope: boolean;
-            supportsUserScope: boolean;
-        };
-        skills: {
-            supportsSkills: boolean;
-            smithersSkillIds: never[];
-        };
-        humanInteraction: {
-            supportsUiRequests: boolean;
-            methods: never[];
-        };
-        builtIns: string[];
-    };
+    capabilities: AgentCapabilityRegistry$3;
     cliEngine: string;
     issuedConversationId: any;
     /**
@@ -869,4 +831,4 @@ type SmithersAgentToolCategory = SmithersAgentToolCategory$1;
 type SmithersListedTool = SmithersListedTool$2;
 type SmithersToolSurface = SmithersToolSurface$2;
 
-export { type AgentCapabilityRegistry, 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, 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

@@ -1,5 +1,6 @@
 // @smithers-type-exports-begin
 /** @typedef {import("./capability-registry/AgentCapabilityRegistry.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
+/** @typedef {import("./BaseCliAgent/AgentGenerateOptions.ts").AgentGenerateOptions} AgentGenerateOptions */
 /** @typedef {import("./AgentLike.ts").AgentLike} AgentLike */
 /** @typedef {import("./capability-registry/AgentToolDescriptor.ts").AgentToolDescriptor} AgentToolDescriptor */
 /**