@smithers-orchestrator/agents 0.24.0 → 0.25.0

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 */
@@ -59,6 +60,15 @@ export class CodexAgent extends BaseCliAgent {
         super(opts);
         this.opts = opts;
         this.capabilities = createCodexCapabilityRegistry(opts);
+        // Native structured output (`codex exec --output-schema`) constrains the
+        // model to emit only final JSON and makes it refuse tool calls ("tool calls
+        // are constrained by a JSON response schema"), which breaks any agentic task
+        // (read/edit/run). It is therefore OPT-IN: by default Codex is treated like
+        // the other CLI engines (supportsNativeStructuredOutput=false), so the engine
+        // prompt-injects the schema and extracts JSON from the agent's final text,
+        // leaving tool use intact. Set nativeStructuredOutput:true for pure, tool-free
+        // extraction tasks that want strict schema enforcement.
+        this.supportsNativeStructuredOutput = opts.nativeStructuredOutput === true;
     }
     /**
    * @returns {CliOutputInterpreter}
@@ -548,11 +558,16 @@ export class CodexAgent extends BaseCliAgent {
         // turn.completed with token usage for metrics. extractUsageFromOutput
         // in BaseCliAgent will parse these automatically.
         args.push("--json");
-        // Auto-wire output schema from task context if not explicitly set.
+        // Auto-wire output schema from task context if not explicitly set — only when
+        // native structured output is opted in. Otherwise the engine handles the schema
+        // via prompt-injection and Codex keeps full tool access (see constructor note).
         // Skip when resuming — `codex exec resume` does not accept --output-schema.
         let schemaCleanupFile = null;
-        if (!resumeSession && !this.opts.outputSchema && params.options?.outputSchema) {
+        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

package/src/CodexAgentOptions.ts

@@ -17,6 +17,17 @@ export type CodexAgentOptions = BaseCliAgentOptions & {
   skipGitRepoCheck?: boolean;
   addDir?: string[];
   outputSchema?: string;
+  /**
+   * Opt in to Codex's native structured output (`codex exec --output-schema`).
+   *
+   * Defaults to `false`. Native structured output makes the model emit only the
+   * final JSON and refuse tool calls, so it BREAKS agentic tasks (read/edit/run) —
+   * Codex returns `blocked` with no changes. Left off, Smithers treats Codex like
+   * the other CLI engines: it prompt-injects the schema and extracts JSON from the
+   * agent's final message, so tool use stays intact. Enable only for pure, tool-free
+   * extraction tasks that need strict schema enforcement.
+   */
+  nativeStructuredOutput?: boolean;
   color?: "always" | "never" | "auto";
   json?: boolean;
   outputLastMessage?: string;