@smithers-orchestrator/agents 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/agents",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "AI SDK and CLI agent adapters for Smithers",
   "type": "module",
   "sideEffects": false,
@@ -11,7 +11,7 @@
       "default": "./src/index.js"
     },
     "./BaseCliAgent": {
-      "types": "./src/index.d.ts",
+      "types": "./src/BaseCliAgent/index.d.ts",
       "import": "./src/BaseCliAgent/index.js",
       "default": "./src/BaseCliAgent/index.js"
     },
@@ -40,6 +40,16 @@
       "import": "./src/mcp/createMcpToolset.js",
       "default": "./src/mcp/createMcpToolset.js"
     },
+    "./document-parsing/createDocumentParsingToolset": {
+      "types": "./src/document-parsing/createDocumentParsingToolset.d.ts",
+      "import": "./src/document-parsing/createDocumentParsingToolset.js",
+      "default": "./src/document-parsing/createDocumentParsingToolset.js"
+    },
+    "./image-generation/createImageGenerationTool": {
+      "types": "./src/image-generation/createImageGenerationTool.d.ts",
+      "import": "./src/image-generation/createImageGenerationTool.js",
+      "default": "./src/image-generation/createImageGenerationTool.js"
+    },
     "./*": {
       "types": "./src/index.d.ts",
       "import": "./src/*.js",
@@ -56,9 +66,9 @@
     "ai": "^6.0.168",
     "effect": "^3.21.1",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/driver": "0.24.0",
-    "@smithers-orchestrator/errors": "0.24.0",
-    "@smithers-orchestrator/observability": "0.24.0"
+    "@smithers-orchestrator/driver": "0.25.0",
+    "@smithers-orchestrator/errors": "0.25.0",
+    "@smithers-orchestrator/observability": "0.25.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/AgentLike.ts

@@ -14,6 +14,11 @@ export type AgentLike = {
   capabilities?: AgentCapabilityRegistry;
   /** True when the agent consumes outputSchema through a native structured-output API. */
   supportsNativeStructuredOutput?: boolean;
+  /**
+   * Performs deterministic startup checks before the first generation call in a
+   * workflow run. A rejected promise fails the task without retrying.
+   */
+  preflight?: (args?: AgentGenerateOptions) => Promise<void>;
   /**
    * Generates a response or action based on the provided arguments.
    *

package/src/AmpAgent.js

@@ -194,7 +194,15 @@ export class AmpAgent extends BaseCliAgent {
    * @param {{ prompt: string; systemPrompt?: string; cwd: string; options: any; }} params
    */
     async buildCommand(params) {
-        const args = [];
+        // Resume an existing thread when a session id is provided. Amp continues a
+        // thread with `amp threads continue <id>` (vs starting a fresh thread), so
+        // new-thread-only flags (--visibility, --archive) are skipped on resume.
+        // NB: the `threads continue` invocation follows the Amp manifest; confirm
+        // against the live `amp` CLI if its thread syntax changes.
+        const resumeSession = typeof params.options?.resumeSession === "string"
+            ? params.options.resumeSession
+            : this.opts.resume;
+        const args = resumeSession ? ["threads", "continue", resumeSession] : [];
         const yoloEnabled = this.opts.yolo ?? this.yolo;
         // Dangerous allow all (yolo mode) — must come before --execute
         if (this.opts.dangerouslyAllowAll || yoloEnabled) {
@@ -202,8 +210,9 @@ export class AmpAgent extends BaseCliAgent {
         }
         // Model / mode
         pushFlag(args, "--model", this.opts.model ?? this.model);
-        // Visibility for new threads
-        pushFlag(args, "--visibility", this.opts.visibility);
+        // Visibility for new threads (not applicable when continuing one)
+        if (!resumeSession)
+            pushFlag(args, "--visibility", this.opts.visibility);
         // MCP config
         pushFlag(args, "--mcp-config", this.opts.mcpConfig);
         // Settings file
@@ -217,8 +226,9 @@ export class AmpAgent extends BaseCliAgent {
         args.push("--no-jetbrains");
         // Color handling
         args.push("--no-color");
-        // Archive thread after execution to keep things clean
-        args.push("--archive");
+        // Archive thread after execution to keep things clean (new threads only)
+        if (!resumeSession)
+            args.push("--archive");
         if (this.extraArgs?.length)
             args.push(...this.extraArgs);
         // Build prompt with system prompt prepended

package/src/AmpAgentOptions.ts

@@ -4,6 +4,12 @@ import type { BaseCliAgentOptions } from "./BaseCliAgent/BaseCliAgentOptions";
  * Configuration options for the AmpAgent.
  */
 export type AmpAgentOptions = BaseCliAgentOptions & {
+  /**
+   * Thread id to continue. When set (or when a task passes
+   * `options.resumeSession`), buildCommand emits `amp threads continue <id>`
+   * instead of starting a fresh thread.
+   */
+  resume?: string;
   /** Visibility setting for the new thread (e.g., private, public) */
   visibility?: "private" | "public" | "workspace" | "group";
   /** Path to a specific MCP configuration file */

package/src/BaseCliAgent/BaseCliAgent.js

@@ -5,6 +5,68 @@ import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
 import { logDebug, logInfo, logWarning } from "@smithers-orchestrator/observability/logging";
 import { agentDurationMs, agentErrorsTotal, agentInvocationsTotal, agentRetriesTotal, agentTokensTotal, } from "@smithers-orchestrator/observability/metrics";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+
+const QUOTA_PATTERNS = [
+    /\bhit\s+your\s+usage\s+limit\b/i,
+    /\busage\s+limit\s+exceeded\b/i,
+    /\bquota\s+exceeded\b/i,
+    /\brate\s+limit\s+exceeded\b/i,
+    /\byou('ve| have)\s+reached\s+(your\s+)?(usage|rate|quota)\b/i,
+    /\b(usage|quota|rate)\s+(cap|ceiling|limit)\s+(reached|exceeded|hit)\b/i,
+    /\btoo\s+many\s+requests\b/i,
+    /\b(429|rate.limit)\b[\s\S]{0,100}?try\s+again\b/i,
+];
+
+/**
+ * Detects provider quota/rate-limit errors and returns a SmithersError with
+ * AGENT_QUOTA_EXCEEDED code. The reset time is parsed when present.
+ *
+ * @param {string} message
+ * @param {string} command
+ * @param {{ agentId?: string; agentModel?: string; agentEngine?: string; nowMs?: () => number }} [context]
+ * @returns {SmithersError | null}
+ */
+export function classifyQuotaError(message, command, context = {}) {
+    if (!message) return null;
+    const isQuota = QUOTA_PATTERNS.some((re) => re.test(message));
+    if (!isQuota) return null;
+    const { agentId, agentModel, agentEngine, nowMs = () => Date.now() } = context;
+    const now = nowMs();
+    let quotaResetAtMs;
+    let resetHint;
+    // Format: "try again at Jun 18th, 2026 9:54 AM" — strip ordinal suffix before parsing
+    const dateMatch = /try again at\s+([A-Z][a-z]+ \d+(?:st|nd|rd|th)?,?\s+\d{4}\s+\d+:\d+\s+(?:AM|PM))/i.exec(message);
+    if (dateMatch) {
+        const normalized = dateMatch[1].replace(/(\d+)(st|nd|rd|th)\b/gi, "$1");
+        const parsed = Date.parse(normalized);
+        if (Number.isFinite(parsed) && parsed > now) {
+            quotaResetAtMs = parsed;
+        }
+        resetHint = dateMatch[0];
+    } else {
+        // Format: "retry after N seconds"
+        const secondsMatch = /retry after\s+(\d+)\s+second/i.exec(message);
+        if (secondsMatch) {
+            const deltaMs = Number(secondsMatch[1]) * 1000;
+            if (deltaMs > 0) {
+                quotaResetAtMs = now + deltaMs;
+            }
+            resetHint = secondsMatch[0];
+        }
+    }
+    const modelLabel = agentModel ?? "<unset>";
+    const idLabel = agentId ?? "<anonymous>";
+    const summary = `Agent "${idLabel}" (${command}, model=${modelLabel}) hit a provider usage/quota limit: ${message.slice(0, 300)}.${resetHint ? ` ${resetHint}.` : ""} Retries are preserved; the run will pause until the quota resets.`;
+    return new SmithersError("AGENT_QUOTA_EXCEEDED", summary, {
+        failureQuota: true,
+        agentId: idLabel,
+        agentEngine: agentEngine ?? "unknown",
+        agentModel: modelLabel,
+        command,
+        underlying: message.slice(0, 500),
+        ...(quotaResetAtMs != null ? { quotaResetAtMs } : {}),
+    });
+}
 import { launchDiagnostics, enrichReportWithErrorAnalysis, formatDiagnosticSummary } from "../diagnostics/index.js";
 import { extractPrompt } from "./extractPrompt.js";
 import { resolveTimeouts } from "./resolveTimeouts.js";
@@ -299,6 +361,8 @@ function extractTextFromJsonPayload(raw) {
     }
     const chunks = [];
     for (const parsed of parsedLines) {
+        if (typeof parsed?.role === "string" && parsed.role !== "assistant")
+            continue;
         let text;
         if (parsed?.type === "text" && typeof parsed?.part?.text === "string") {
             text = parsed.part.text;
@@ -692,15 +756,8 @@ export class BaseCliAgent {
         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}
-     */
+        const agentCtx = { agentId, agentModel, agentEngine };
+        const classifyQuota = (message, command) => classifyQuotaError(message, command, agentCtx);
         function classifyNonRetryableAgentError(message, command) {
             if (!message)
                 return null;
@@ -862,7 +919,7 @@ export class BaseCliAgent {
                 }
                 flushBufferedLines(stream, false);
             };
-            diagnosticsPromise = launchDiagnostics(commandSpec.command, commandEnv, cwd);
+            diagnosticsPromise = launchDiagnostics(commandSpec.command, commandEnv, cwd, this.diagnosticHints?.());
             return Effect.gen(this, function* () {
                 const result = yield* runCommandEffect(commandSpec.command, commandSpec.args, {
                     cwd,
@@ -922,6 +979,10 @@ export class BaseCliAgent {
                             filteredStderr ||
                             result.stdout.trim() ||
                             `CLI exited with code ${result.exitCode}`;
+                        const quota = classifyQuota(errorText, commandSpec.command);
+                        if (quota) {
+                            return yield* Effect.fail(quota);
+                        }
                         const nonRetryable = classifyNonRetryableAgentError(errorText, commandSpec.command);
                         if (nonRetryable) {
                             return yield* Effect.fail(nonRetryable);
@@ -949,7 +1010,12 @@ export class BaseCliAgent {
                     }
                 }
                 if (completedEvent?.ok === false) {
-                    return yield* Effect.fail(new SmithersError("AGENT_CLI_ERROR", completedEvent.error || "CLI agent reported an error"));
+                    const completedError = completedEvent.error || "CLI agent reported an error";
+                    const completedQuota = classifyQuota(completedError, commandSpec.command);
+                    if (completedQuota) {
+                        return yield* Effect.fail(completedQuota);
+                    }
+                    return yield* Effect.fail(new SmithersError("AGENT_CLI_ERROR", completedError));
                 }
                 // Some CLIs may print extra banners to stdout. Allow individual agents
                 // to provide patterns so this logic stays opt-in and agent-specific.
@@ -1069,6 +1135,128 @@ export class BaseCliAgent {
     }
     /**
    * @param {AgentGenerateOptions} [options]
+   * @returns {Promise<void>}
+   */
+    async preflight(options) {
+        const cwd = this.cwd ?? options?.rootDir ?? process.cwd();
+        const env = {
+            ...process.env,
+            ...this.env,
+            ...taskContextEnv(options?.taskContext),
+        };
+        const { systemFromMessages } = extractPrompt(options);
+        const combinedSystem = combineNonEmpty([
+            this.systemPrompt,
+            systemFromMessages,
+        ]);
+        const agentId = this.id ?? "<anonymous>";
+        const agentModel = this.model ?? "<unset>";
+        let cleanup;
+        let command = resolveAgentEngineTag(this);
+        try {
+            const commandSpec = await this.buildCommand({
+                prompt: "",
+                systemPrompt: combinedSystem,
+                cwd,
+                options,
+            });
+            cleanup = commandSpec.cleanup;
+            command = commandSpec.command;
+            const commandEnv = commandSpec.env
+                ? { ...env, ...commandSpec.env }
+                : env;
+            const report = await launchDiagnostics(commandSpec.command, commandEnv, cwd, this.diagnosticHints?.());
+            if (!report) {
+                logDebug("agent preflight skipped; no diagnostics strategy", {
+                    agentId,
+                    agentEngine: commandSpec.command,
+                    agentModel,
+                    cwd,
+                }, "agent.preflight");
+                return;
+            }
+            const failed = report.checks.filter((check) => check.status === "fail");
+            const errored = report.checks.filter((check) => check.status === "error");
+            if (failed.length > 0) {
+                const summary = formatDiagnosticSummary(report);
+                logWarning(summary, {
+                    agentId,
+                    agentEngine: commandSpec.command,
+                    agentModel,
+                    cwd,
+                }, "agent.preflight");
+                throw new SmithersError("AGENT_CONFIG_INVALID", `Agent "${agentId}" (${commandSpec.command}, model=${agentModel}) failed preflight: ${summary}`, {
+                    failureRetryable: false,
+                    preflight: true,
+                    agentId,
+                    agentEngine: commandSpec.command,
+                    agentModel,
+                    command: commandSpec.command,
+                    diagnostics: report,
+                });
+            }
+            if (errored.length > 0) {
+                logWarning(`Agent preflight diagnostics had non-blocking errors: ${formatDiagnosticSummary(report)}`, {
+                    agentId,
+                    agentEngine: commandSpec.command,
+                    agentModel,
+                    cwd,
+                }, "agent.preflight");
+            }
+            else {
+                logDebug("agent preflight passed", {
+                    agentId,
+                    agentEngine: commandSpec.command,
+                    agentModel,
+                    cwd,
+                    durationMs: Math.round(report.durationMs),
+                }, "agent.preflight");
+            }
+        }
+        catch (cause) {
+            if (cause instanceof SmithersError && cause.details?.preflight === true) {
+                throw cause;
+            }
+            const normalized = cause instanceof SmithersError
+                ? cause
+                : toSmithersError(cause, "build agent preflight command", {
+                    code: "AGENT_CONFIG_INVALID",
+                    details: {
+                        failureRetryable: false,
+                        preflight: true,
+                        agentId,
+                        agentEngine: command,
+                        agentModel,
+                        command,
+                    },
+                });
+            throw new SmithersError(normalized.code ?? "AGENT_CONFIG_INVALID", `Agent "${agentId}" (${command}, model=${agentModel}) failed preflight: ${normalized.summary ?? normalized.message}`, {
+                ...normalized.details,
+                failureRetryable: false,
+                preflight: true,
+                agentId,
+                agentEngine: normalized.details?.agentEngine ?? command,
+                agentModel,
+                command: normalized.details?.command ?? command,
+            }, { cause: normalized });
+        }
+        finally {
+            if (cleanup) {
+                try {
+                    await cleanup();
+                }
+                catch (error) {
+                    logWarning("agent preflight cleanup failed", {
+                        agentId,
+                        agentEngine: command,
+                        error: error instanceof Error ? error.message : String(error),
+                    }, "agent.preflight");
+                }
+            }
+        }
+    }
+    /**
+   * @param {AgentGenerateOptions} [options]
    * @returns {Promise<GenerateTextResult<Record<string, never>, unknown>>}
    */
     async generate(options) {
@@ -1088,4 +1276,10 @@ export class BaseCliAgent {
     createOutputInterpreter() {
         return undefined;
     }
+    /**
+   * @returns {{ provider?: string; model?: string } | undefined}
+   */
+    diagnosticHints() {
+        return undefined;
+    }
 }

package/src/BaseCliAgent/createAgentStdoutTextEmitter.js

@@ -24,7 +24,7 @@ function extractLastAssistantMessage(messages) {
 }
 /**
  * @param {unknown} parsed
- * @param {{ sawDeltaSinceBoundary: boolean }} state
+ * @param {{ sawDeltaSinceBoundary: boolean; lastFinalText?: string }} state
  * @returns {string[]}
  */
 function extractCliStreamTextChunks(parsed, state) {
@@ -45,6 +45,24 @@ function extractCliStreamTextChunks(parsed, state) {
     const emitFinal = (text) => {
         if (text && !state.sawDeltaSinceBoundary) {
             chunks.push(text);
+            state.lastFinalText = text;
+        }
+        state.sawDeltaSinceBoundary = false;
+    };
+    /**
+   * The end-of-run `result` payload echoes the final assistant message — e.g.
+   * Claude Code emits a complete `assistant` line AND a `result` line that both
+   * carry the same answer, with no deltas in between. Treat `result` as a
+   * fallback: surface it only when nothing already covered this turn and it is
+   * not a verbatim repeat of the text we just emitted. Without this the answer
+   * is streamed (and persisted as a NodeOutput) twice, so every consumer — the
+   * TUI, `smithers chat`, the gateway UI — shows it doubled.
+   * @param {string | undefined} text
+   */
+    const emitResult = (text) => {
+        if (text && !state.sawDeltaSinceBoundary && text !== state.lastFinalText) {
+            chunks.push(text);
+            state.lastFinalText = text;
         }
         state.sawDeltaSinceBoundary = false;
     };
@@ -103,7 +121,7 @@ function extractCliStreamTextChunks(parsed, state) {
         emitFinal(extractTextFromJsonValue(message));
     }
     if (type === "result") {
-        emitFinal(extractTextFromJsonValue(record.result ?? record.response ?? record.output ?? record));
+        emitResult(extractTextFromJsonValue(record.result ?? record.response ?? record.output ?? record));
     }
     if (type === "turn_end" && message?.role === "assistant") {
         emitFinal(extractTextFromJsonValue(message));
@@ -132,7 +150,7 @@ export function createAgentStdoutTextEmitter(options) {
     const { outputFormat, onText } = options;
     let buffer = "";
     let emittedAnyText = false;
-    const state = { sawDeltaSinceBoundary: false };
+    const state = { sawDeltaSinceBoundary: false, lastFinalText: undefined };
     /**
    * @param {string | undefined} text
    */