@smithers-orchestrator/agents 0.24.2 → 0.25.1

package/src/BaseCliAgent/index.d.ts

@@ -0,0 +1,467 @@
+import * as ai from 'ai';
+import * as _smithers_orchestrator_errors_SmithersError from '@smithers-orchestrator/errors/SmithersError';
+import { SmithersError as SmithersError$1 } from '@smithers-orchestrator/errors/SmithersError';
+import { Effect } from 'effect';
+import { spawn } from 'node:child_process';
+
+type RunCommandResult$2 = {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    /** True when captured stdout exceeded maxOutputBytes and was truncated. */
+    stdoutTruncated?: boolean;
+    /** True when captured stderr exceeded maxOutputBytes and was truncated. */
+    stderrTruncated?: boolean;
+};
+
+type PiExtensionUiResponse$2 = {
+    type: "extension_ui_response";
+    id: string;
+    value?: string;
+    cancelled?: boolean;
+    [key: string]: unknown;
+};
+
+type PiExtensionUiRequest$2 = {
+    type: "extension_ui_request";
+    id: string;
+    method: string;
+    title?: string;
+    placeholder?: string;
+    [key: string]: unknown;
+};
+
+type CodexConfigOverrides$2 = Record<string, string | number | boolean | object | null> | string[];
+
+type NormalizedTokenUsage$2 = {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+    totalTokens?: number;
+};
+
+type CliUsageInfo$2 = {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+};
+
+type AgentCliActionKind$2 = "turn" | "command" | "tool" | "file_change" | "web_search" | "todo_list" | "reasoning" | "warning" | "note";
+
+type AgentCliActionPhase$1 = "started" | "updated" | "completed";
+type AgentCliEventLevel$1 = "debug" | "info" | "warning" | "error";
+type AgentCliStartedEvent$1 = {
+    type: "started";
+    engine: string;
+    title: string;
+    resume?: string;
+    detail?: Record<string, unknown>;
+};
+type AgentCliActionEvent$1 = {
+    type: "action";
+    engine: string;
+    phase: AgentCliActionPhase$1;
+    entryType?: "thought" | "message";
+    action: {
+        id: string;
+        kind: AgentCliActionKind$2;
+        title: string;
+        detail?: Record<string, unknown>;
+    };
+    message?: string;
+    ok?: boolean;
+    level?: AgentCliEventLevel$1;
+};
+type AgentCliCompletedEvent$1 = {
+    type: "completed";
+    engine: string;
+    ok: boolean;
+    answer?: string;
+    error?: string;
+    resume?: string;
+    usage?: Record<string, unknown>;
+};
+type AgentCliEvent$1 = AgentCliStartedEvent$1 | AgentCliActionEvent$1 | AgentCliCompletedEvent$1;
+
+type CliOutputInterpreter$2 = {
+    onStdoutLine?: (line: string) => AgentCliEvent$1[] | AgentCliEvent$1 | null | undefined;
+    onStderrLine?: (line: string) => AgentCliEvent$1[] | AgentCliEvent$1 | null | undefined;
+    onExit?: (result: RunCommandResult$2) => AgentCliEvent$1[] | AgentCliEvent$1 | null | undefined;
+};
+
+type BaseCliAgentOptions$2 = {
+    id?: string;
+    model?: string;
+    systemPrompt?: string;
+    instructions?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    yolo?: boolean;
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+    maxOutputBytes?: number;
+    extraArgs?: string[];
+};
+
+/**
+ * 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`.
+ */
+type AgentGenerateOptions$2 = {
+    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$1) => unknown;
+    retry?: unknown;
+    isRetry?: unknown;
+    retryAttempt?: unknown;
+    schemaRetry?: unknown;
+    /**
+     * Run context for the task this agent invocation belongs to. Surfaced to the
+     * spawned agent process (and its subprocesses) as SMITHERS_RUN_ID / NODE_ID /
+     * ITERATION / ATTEMPT so the agent can address its own run — e.g. to raise a
+     * blocking `smithers ask-human` request.
+     */
+    taskContext?: {
+        runId?: string;
+        nodeId?: string;
+        iteration?: number;
+        attempt?: number;
+    };
+    [key: string]: unknown;
+};
+
+/**
+ * @typedef {number | { totalMs?: number; idleMs?: number; } | undefined} TimeoutInput
+ */
+/**
+ * @param {TimeoutInput} timeout
+ * @param {{ totalMs?: number; idleMs?: number }} [fallback]
+ * @returns {{ totalMs?: number; idleMs?: number }}
+ */
+declare function resolveTimeouts(timeout: TimeoutInput, fallback?: {
+    totalMs?: number;
+    idleMs?: number;
+}): {
+    totalMs?: number;
+    idleMs?: number;
+};
+type TimeoutInput = number | {
+    totalMs?: number;
+    idleMs?: number;
+} | undefined;
+
+/**
+ * @param {Array<string | undefined>} parts
+ * @returns {string | undefined}
+ */
+declare function combineNonEmpty(parts: Array<string | undefined>): string | undefined;
+
+/**
+ * @param {unknown} options
+ * @returns {PromptParts}
+ */
+declare function extractPrompt(options: unknown): PromptParts;
+type PromptParts = {
+    prompt: string;
+    systemFromMessages?: string;
+};
+
+/**
+ * @param {string} text
+ * @returns {unknown | undefined}
+ */
+declare function tryParseJson(text: string): unknown | undefined;
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+declare function extractTextFromJsonValue(value: unknown): string | undefined;
+
+/**
+ * @param {unknown} usage
+ * @returns {NormalizedTokenUsage | null}
+ */
+declare function normalizeTokenUsage(usage: unknown): NormalizedTokenUsage$1 | null;
+type NormalizedTokenUsage$1 = NormalizedTokenUsage$2;
+
+/**
+ * @param {AgentStdoutTextEmitterOptions} options
+ * @returns {AgentStdoutTextEmitter}
+ */
+declare function createAgentStdoutTextEmitter(options: AgentStdoutTextEmitterOptions): AgentStdoutTextEmitter;
+type AgentStdoutTextEmitter = {
+    push: (chunk: string) => void;
+    flush: (finalText?: string) => void;
+};
+type AgentStdoutTextEmitterOptions = {
+    outputFormat?: string;
+    onText?: (text: string) => void;
+};
+
+/**
+ * @param {string} text
+ * @param {number} [maxBytes]
+ * @returns {string}
+ */
+declare function truncateToBytes(text: string, maxBytes?: number): string;
+
+/** @typedef {import("ai").GenerateTextResult} GenerateTextResult */
+/** @typedef {import("ai").LanguageModelUsage} LanguageModelUsage */
+/**
+ * @param {string} text
+ * @param {unknown} output
+ * @param {string} modelId
+ * @param {LanguageModelUsage} [usage]
+ * @returns {GenerateTextResult<Record<string, never>, unknown>}
+ */
+declare function buildGenerateResult(text: string, output: unknown, modelId: string, usage?: LanguageModelUsage): GenerateTextResult$1<Record<string, never>, unknown>;
+type GenerateTextResult$1 = ai.GenerateTextResult<any, any>;
+type LanguageModelUsage = ai.LanguageModelUsage;
+
+/**
+ * @typedef {{ cwd: string; env: Record<string, string>; input?: string; timeoutMs?: number; idleTimeoutMs?: number; signal?: AbortSignal; maxOutputBytes?: number; truncateKeep?: "head" | "tail"; onStdout?: (chunk: string) => void; onStderr?: (chunk: string) => void; }} RunCommandOptions
+ */
+/** @typedef {import("./RunCommandResult.ts").RunCommandResult} RunCommandResult */
+/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} SmithersError */
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {RunCommandOptions} options
+ * @returns {Effect.Effect<RunCommandResult, SmithersError>}
+ */
+declare function runCommandEffect(command: string, args: string[], options: RunCommandOptions): Effect.Effect<RunCommandResult$1, SmithersError>;
+type RunCommandOptions = {
+    cwd: string;
+    env: Record<string, string>;
+    input?: string;
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+    signal?: AbortSignal;
+    maxOutputBytes?: number;
+    truncateKeep?: "head" | "tail";
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+};
+type RunCommandResult$1 = RunCommandResult$2;
+type SmithersError = _smithers_orchestrator_errors_SmithersError.SmithersError;
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {RunRpcCommandOptions} options
+ * @returns {Effect.Effect<{ text: string; output: unknown; stderr: string; exitCode: number | null; usage?: any; }, SmithersError>}
+ */
+declare function runRpcCommandEffect(command: string, args: string[], options: RunRpcCommandOptions): Effect.Effect<{
+    text: string;
+    output: unknown;
+    stderr: string;
+    exitCode: number | null;
+    usage?: any;
+}, SmithersError$1>;
+type PiExtensionUiResponse$1 = PiExtensionUiResponse$2;
+type PiExtensionUiRequest$1 = PiExtensionUiRequest$2;
+type RunRpcCommandOptions = {
+    cwd: string;
+    env: Record<string, string>;
+    prompt: string;
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+    signal?: AbortSignal;
+    maxOutputBytes?: number;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    onJsonEvent?: (event: Record<string, unknown>) => Promise<void> | void;
+    onExtensionUiRequest?: (request: PiExtensionUiRequest$1) => Promise<PiExtensionUiResponse$1 | null> | PiExtensionUiResponse$1 | null;
+    spawnFn?: typeof spawn;
+};
+
+/**
+ * @param {string[]} args
+ * @param {string} flag
+ * @param {string | number | boolean} [value]
+ */
+declare function pushFlag(args: string[], flag: string, value?: string | number | boolean): void;
+
+/**
+ * @param {string[]} args
+ * @param {string} flag
+ * @param {string[]} [values]
+ */
+declare function pushList(args: string[], flag: string, values?: string[]): void;
+
+/** @typedef {import("./CodexConfigOverrides.ts").CodexConfigOverrides} CodexConfigOverrides */
+/**
+ * @param {CodexConfigOverrides} [config]
+ * @returns {string[]}
+ */
+declare function normalizeCodexConfig(config?: CodexConfigOverrides$1): string[];
+type CodexConfigOverrides$1 = CodexConfigOverrides$2;
+
+/** @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 */
+/** @typedef {import("ai").GenerateTextResult} GenerateTextResult */
+/** @typedef {import("ai").StreamTextResult} StreamTextResult */
+/** @typedef {import("ai").LanguageModelUsage} LanguageModelUsage */
+/**
+ * @typedef {"generate" | "stream"} AgentInvocationOperation
+ */
+/**
+ * @typedef {Record<string, string | undefined>} AgentInvocationTags
+ */
+/**
+ * @typedef {{
+ *   inputTokens?: number;
+ *   outputTokens?: number;
+ *   cacheReadTokens?: number;
+ *   cacheWriteTokens?: number;
+ *   reasoningTokens?: number;
+ *   totalTokens?: number;
+ * }} AgentTokenTotals
+ */
+/**
+ * @template A
+ * @param {Effect.Effect<A, SmithersError, never>} effect
+ * @returns {Promise<A>}
+ */
+declare function runAgentPromise<A>(effect: Effect.Effect<A, SmithersError$1, never>): Promise<A>;
+/**
+ * @param {string} raw
+ * @returns {CliUsageInfo | undefined}
+ */
+declare function extractUsageFromOutput(raw: string): CliUsageInfo$1 | undefined;
+declare class BaseCliAgent {
+    /**
+   * @param {BaseCliAgentOptions} opts
+   */
+    constructor(opts: BaseCliAgentOptions$1);
+    version: string;
+    tools: {};
+    capabilities: any;
+    id: string;
+    model: string | undefined;
+    systemPrompt: string | undefined;
+    cwd: string | undefined;
+    env: Record<string, string> | undefined;
+    yolo: boolean;
+    timeoutMs: number | undefined;
+    idleTimeoutMs: number | undefined;
+    maxOutputBytes: number | undefined;
+    extraArgs: string[] | undefined;
+    /**
+   * @param {AgentGenerateOptions | undefined} options
+   * @param {AgentInvocationOperation} operation
+   * @returns {Effect.Effect<GenerateTextResult<Record<string, never>, unknown>, SmithersError>}
+   */
+    runGenerateEffect(options: AgentGenerateOptions$1 | undefined, operation: AgentInvocationOperation): Effect.Effect<GenerateTextResult<Record<string, never>, unknown>, SmithersError$1>;
+    /**
+   * @param {AgentGenerateOptions} [options]
+   * @returns {Promise<void>}
+   */
+    preflight(options?: AgentGenerateOptions$1): Promise<void>;
+    /**
+   * @param {AgentGenerateOptions} [options]
+   * @returns {Promise<GenerateTextResult<Record<string, never>, unknown>>}
+   */
+    generate(options?: AgentGenerateOptions$1): Promise<GenerateTextResult<Record<string, never>, unknown>>;
+    /**
+   * @param {AgentGenerateOptions} [options]
+   * @returns {Promise<StreamTextResult<Record<string, never>, unknown>>}
+   */
+    stream(options?: AgentGenerateOptions$1): Promise<StreamTextResult<Record<string, never>, unknown>>;
+    /**
+   * @returns {CliOutputInterpreter | undefined}
+   */
+    createOutputInterpreter(): CliOutputInterpreter$1 | undefined;
+    /**
+   * @returns {{ provider?: string; model?: string } | undefined}
+   */
+    diagnosticHints(): {
+        provider?: string;
+        model?: string;
+    } | undefined;
+}
+type AgentGenerateOptions$1 = AgentGenerateOptions$2;
+type BaseCliAgentOptions$1 = BaseCliAgentOptions$2;
+type CliOutputInterpreter$1 = CliOutputInterpreter$2;
+type CliUsageInfo$1 = CliUsageInfo$2;
+type GenerateTextResult = ai.GenerateTextResult<any, any>;
+type StreamTextResult = ai.StreamTextResult<any, any>;
+type AgentInvocationOperation = "generate" | "stream";
+
+/** @typedef {import("./AgentCliActionKind.ts").AgentCliActionKind} AgentCliActionKind */
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+declare function asString(value: unknown): string | undefined;
+/**
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+declare function asNumber(value: unknown): number | undefined;
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+declare function truncate(value: string, maxLength?: number): string;
+/**
+ * @param {string | undefined} name
+ * @param {ReadonlyArray<readonly [string[], AgentCliActionKind]>} [extraRules]
+ * @returns {AgentCliActionKind}
+ */
+declare function toolKindFromName(name: string | undefined, extraRules?: ReadonlyArray<readonly [string[], AgentCliActionKind$1]>): AgentCliActionKind$1;
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+declare function isLikelyRuntimeMetadata(value: string): boolean;
+/**
+ * @param {string} line
+ * @returns {boolean}
+ */
+declare function shouldSurfaceUnparsedStdout(line: string): boolean;
+/**
+ * @returns {(prefix: string) => string}
+ */
+declare function createSyntheticIdGenerator(): (prefix: string) => string;
+type AgentCliActionKind$1 = AgentCliActionKind$2;
+
+type AgentCliActionEvent = AgentCliActionEvent$1;
+type AgentCliActionKind = AgentCliActionKind$2;
+type AgentCliActionPhase = AgentCliActionPhase$1;
+type AgentCliCompletedEvent = AgentCliCompletedEvent$1;
+type AgentCliEvent = AgentCliEvent$1;
+type AgentCliEventLevel = AgentCliEventLevel$1;
+type AgentCliStartedEvent = AgentCliStartedEvent$1;
+type AgentGenerateOptions = AgentGenerateOptions$2;
+type BaseCliAgentOptions = BaseCliAgentOptions$2;
+type CliOutputInterpreter = CliOutputInterpreter$2;
+type CliUsageInfo = CliUsageInfo$2;
+type NormalizedTokenUsage = NormalizedTokenUsage$2;
+type CodexConfigOverrides = CodexConfigOverrides$2;
+type PiExtensionUiRequest = PiExtensionUiRequest$2;
+type PiExtensionUiResponse = PiExtensionUiResponse$2;
+type RunCommandResult = RunCommandResult$2;
+
+export { type AgentCliActionEvent, type AgentCliActionKind, type AgentCliActionPhase, type AgentCliCompletedEvent, type AgentCliEvent, type AgentCliEventLevel, type AgentCliStartedEvent, type AgentGenerateOptions, BaseCliAgent, type BaseCliAgentOptions, type CliOutputInterpreter, type CliUsageInfo, type CodexConfigOverrides, type NormalizedTokenUsage, type PiExtensionUiRequest, type PiExtensionUiResponse, type RunCommandResult, asNumber, asString, buildGenerateResult, combineNonEmpty, createAgentStdoutTextEmitter, createSyntheticIdGenerator, extractPrompt, extractTextFromJsonValue, extractUsageFromOutput, isLikelyRuntimeMetadata, isRecord, normalizeCodexConfig, normalizeTokenUsage, pushFlag, pushList, resolveTimeouts, runAgentPromise, runCommandEffect, runRpcCommandEffect, shouldSurfaceUnparsedStdout, toolKindFromName, truncate, truncateToBytes, tryParseJson };

package/src/ClaudeCodeAgent.js

@@ -56,6 +56,7 @@ export function createClaudeCodeCapabilityRegistry(opts = {}) {
     };
 }
 const TOOL_OUTPUT_MAX_CHARS = 500;
+let didWarnAnthropicApiKeyUnset = false;
 /**
  * @param {string} toolName
  * @param {string | undefined} rawOutput
@@ -105,8 +106,11 @@ export class ClaudeCodeAgent extends BaseCliAgent {
         if (process.env.CLAUDECODE)
             parentEnvOverrides.CLAUDECODE = "";
         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, pass `apiKey` to ClaudeCodeAgent or use ToolLoopAgent from 'ai' with anthropic() provider.", {}, "agent.init");
+            if (!didWarnAnthropicApiKeyUnset) {
+                didWarnAnthropicApiKeyUnset = true;
+                logWarning("ClaudeCodeAgent: unsetting ANTHROPIC_API_KEY so Claude Code uses your subscription. " +
+                    "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) {

package/src/CodexAgent.js

@@ -4,6 +4,7 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { BaseCliAgent, normalizeCodexConfig, pushFlag, pushList, isRecord, asString, asNumber, truncate, shouldSurfaceUnparsedStdout, createSyntheticIdGenerator, } from "./BaseCliAgent/index.js";
 import { normalizeCapabilityStringList, } from "./capability-registry/index.js";
+import { assertZodV4 } from "@smithers-orchestrator/errors/assertZodV4";
 import { sanitizeForOpenAI } from "./sanitizeForOpenAI.js";
 /** @typedef {import("./BaseCliAgent/BaseCliAgentOptions.ts").BaseCliAgentOptions} BaseCliAgentOptions */
 /** @typedef {import("./BaseCliAgent/CodexConfigOverrides.ts").CodexConfigOverrides} CodexConfigOverrides */
@@ -564,6 +565,9 @@ export class CodexAgent extends BaseCliAgent {
         let schemaCleanupFile = null;
         if (!resumeSession && this.opts.nativeStructuredOutput === true && !this.opts.outputSchema && params.options?.outputSchema) {
             const schema = params.options.outputSchema;
+            // z.toJSONSchema() reads Zod v4 internals; a v3 schema throws a cryptic
+            // `schema._zod.def` TypeError. Surface a clear, actionable error instead.
+            assertZodV4(schema);
             const { z } = await import("zod");
             let jsonSchema = z.toJSONSchema(schema);
             // Sanitize for OpenAI structured output compatibility