@smithers-orchestrator/agents 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/agents",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "AI SDK and CLI agent adapters for Smithers",
   "type": "module",
   "sideEffects": false,
@@ -35,6 +35,11 @@
       "import": "./src/cli-capabilities/index.js",
       "default": "./src/cli-capabilities/index.js"
     },
+    "./mcp/createMcpToolset": {
+      "types": "./src/mcp/createMcpToolset.d.ts",
+      "import": "./src/mcp/createMcpToolset.js",
+      "default": "./src/mcp/createMcpToolset.js"
+    },
     "./*": {
       "types": "./src/index.d.ts",
       "import": "./src/*.js",
@@ -51,9 +56,9 @@
     "ai": "^6.0.168",
     "effect": "^3.21.1",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/errors": "0.23.0",
-    "@smithers-orchestrator/driver": "0.23.0",
-    "@smithers-orchestrator/observability": "0.23.0"
+    "@smithers-orchestrator/driver": "0.24.0",
+    "@smithers-orchestrator/errors": "0.24.0",
+    "@smithers-orchestrator/observability": "0.24.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/BaseCliAgent/BaseCliAgent.js

@@ -451,6 +451,27 @@ function buildStreamResult(result) {
         fullStream: fullStream,
     };
 }
+/**
+ * Fallback when truncated stdout lost the per-message usage events: the
+ * interpreter's completed event carries the harness usage summary (#277).
+ * @param {{ usage?: unknown } | null} completedEvent
+ * @returns {CliUsageInfo | undefined}
+ */
+function usageFromCompletedEvent(completedEvent) {
+    const u = completedEvent?.usage;
+    if (!u || typeof u !== "object" || Array.isArray(u))
+        return undefined;
+    const num = (value) => (typeof value === "number" && Number.isFinite(value) ? value : undefined);
+    const usage = {
+        inputTokens: num(u.input_tokens) ?? num(u.inputTokens),
+        outputTokens: num(u.output_tokens) ?? num(u.outputTokens),
+        cacheReadTokens: num(u.cache_read_input_tokens) ?? num(u.cacheReadTokens),
+        cacheWriteTokens: num(u.cache_creation_input_tokens) ?? num(u.cacheWriteTokens),
+        reasoningTokens: num(u.reasoning_tokens) ?? num(u.reasoningTokens),
+        totalTokens: num(u.total_tokens) ?? num(u.totalTokens),
+    };
+    return Object.values(usage).some((value) => value !== undefined) ? usage : undefined;
+}
 /**
  * @param {string} raw
  * @returns {CliUsageInfo | undefined}
@@ -851,6 +872,10 @@ export class BaseCliAgent {
                     idleTimeoutMs: callTimeouts.idleMs,
                     signal: options?.abortSignal,
                     maxOutputBytes: this.maxOutputBytes ?? options?.maxOutputBytes,
+                    // CLI harnesses emit their final result event at the END of
+                    // the stream; if the capture cap trips, the tail is the part
+                    // that must survive (#277).
+                    truncateKeep: "tail",
                     onStdout: (chunk) => {
                         stdoutEmitter?.push(chunk);
                         handleInterpreterChunk("stdout", chunk);
@@ -863,12 +888,30 @@ export class BaseCliAgent {
                 flushBufferedLines("stdout", true);
                 flushBufferedLines("stderr", true);
                 emitEvents(interpreter?.onExit?.(result));
-                const stdout = commandSpec.outputFile
+                if (result.stdoutTruncated) {
+                    emitEvents({
+                        type: "action",
+                        engine: commandSpec.command,
+                        phase: "completed",
+                        entryType: "thought",
+                        action: {
+                            id: `stdout-truncated-${randomUUID()}`,
+                            kind: "warning",
+                            title: "captured stdout truncated",
+                            detail: {},
+                        },
+                        message: "Captured stdout exceeded maxOutputBytes; kept the stream tail. The streamed interpreter answer is used as the result text.",
+                        ok: true,
+                        level: "warning",
+                    });
+                }
+                const outputFileText = commandSpec.outputFile
                     ? yield* Effect.tryPromise({
                         try: () => fs.readFile(commandSpec.outputFile, "utf8"),
                         catch: (cause) => toSmithersError(cause, "read output file"),
-                    }).pipe(Effect.catchAll(() => Effect.succeed(result.stdout)))
-                    : result.stdout;
+                    }).pipe(Effect.catchAll(() => Effect.succeed(null)))
+                    : null;
+                const stdout = typeof outputFileText === "string" ? outputFileText : result.stdout;
                 if (result.exitCode && result.exitCode !== 0) {
                     const filteredStderr = filterBenignStderr(result.stderr, commandSpec.benignStderrPatterns);
                     if (!(commandSpec.command === "codex" && filteredStderr.length === 0)) {
@@ -934,13 +977,35 @@ export class BaseCliAgent {
                         }
                     }
                 }
-                const extractedText = outputFormat === "json" || outputFormat === "stream-json"
-                    ? (extractTextFromJsonPayload(rawText) ?? rawText)
+                const extractedFromStdout = outputFormat === "json" || outputFormat === "stream-json"
+                    ? extractTextFromJsonPayload(rawText)
                     : rawText;
-                const output = tryParseJson(extractedText);
+                // The interpreter parses the live stream line-by-line BEFORE the
+                // capture cap applies, so its completed answer survives stdout
+                // truncation. Prefer it whenever the captured stdout was
+                // truncated or yields no final message; otherwise keep the
+                // historical extraction so intact runs are unchanged (#277).
+                const streamedAnswer = typeof completedEvent?.answer === "string" && completedEvent.answer.trim().length > 0
+                    ? completedEvent.answer
+                    : undefined;
+                // A dedicated final-message file (e.g. codex --output-last-message)
+                // is the CLI's authoritative output channel: it holds the complete
+                // final message and is immune to the stdout byte cap and to
+                // line-by-line stream interpretation. When it parsed as JSON, trust
+                // it over the truncation/stream fallbacks, which otherwise surface a
+                // short `message` field instead of the full structured object.
+                const outputFileJson = typeof outputFileText === "string" && outputFileText.trim() !== ""
+                    ? tryParseJson(outputFileText)
+                    : null;
+                const extractedText = outputFileJson != null
+                    ? outputFileText
+                    : result.stdoutTruncated || extractedFromStdout == null || extractedFromStdout.trim() === ""
+                        ? (streamedAnswer ?? extractedFromStdout ?? rawText)
+                        : extractedFromStdout;
+                const output = outputFileJson ?? tryParseJson(extractedText);
                 // Extract token usage from raw stdout before text extraction strips it.
                 // Each CLI harness embeds usage differently (NDJSON events, JSON stats, etc.)
-                const cliUsage = extractUsageFromOutput(stdout);
+                const cliUsage = extractUsageFromOutput(stdout) ?? usageFromCompletedEvent(completedEvent);
                 const usage = cliUsage ? {
                     inputTokens: cliUsage.inputTokens,
                     inputTokenDetails: {

package/src/BaseCliAgent/RunCommandResult.ts

@@ -2,4 +2,8 @@ export type RunCommandResult = {
   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;
 };

package/src/BaseCliAgent/runCommandEffect.js

@@ -1,7 +1,7 @@
 import { Effect } from "effect";
 import { spawnCaptureEffect } from "@smithers-orchestrator/driver/child-process";
 /**
- * @typedef {{ cwd: string; env: Record<string, string>; input?: string; timeoutMs?: number; idleTimeoutMs?: number; signal?: AbortSignal; maxOutputBytes?: number; onStdout?: (chunk: string) => void; onStderr?: (chunk: string) => void; }} RunCommandOptions
+ * @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 */
@@ -13,7 +13,7 @@ import { spawnCaptureEffect } from "@smithers-orchestrator/driver/child-process"
  * @returns {Effect.Effect<RunCommandResult, SmithersError>}
  */
 export function runCommandEffect(command, args, options) {
-    const { cwd, env, input, timeoutMs, idleTimeoutMs, signal, maxOutputBytes, onStdout, onStderr, } = options;
+    const { cwd, env, input, timeoutMs, idleTimeoutMs, signal, maxOutputBytes, truncateKeep, onStdout, onStderr, } = options;
     return spawnCaptureEffect(command, args, {
         cwd,
         env,
@@ -22,6 +22,7 @@ export function runCommandEffect(command, args, options) {
         timeoutMs,
         idleTimeoutMs,
         maxOutputBytes,
+        truncateKeep,
         onStdout,
         onStderr,
     }).pipe(Effect.annotateLogs({

package/src/diagnostics/getDiagnosticStrategy.js

@@ -113,7 +113,7 @@ const claudeRateLimitCheck = {
                     "content-type": "application/json",
                 },
                 body: JSON.stringify({
-                    model: "claude-sonnet-4-20250514",
+                    model: "claude-fable-5",
                     messages: [{ role: "user", content: "hi" }],
                 }),
                 signal: AbortSignal.timeout(4_000),

package/src/mcp/McpToolsetOptions.ts

@@ -0,0 +1,16 @@
+/**
+ * Options for shaping the generated toolset. Mirrors the curation knobs on
+ * `createOpenApiTools` so MCP and OpenAPI integrations feel the same.
+ */
+export type McpToolsetOptions = {
+  /** Only expose these MCP tool names. */
+  include?: string[];
+  /** Drop these MCP tool names. */
+  exclude?: string[];
+  /** Prefix applied to every tool name, e.g. `"github_"`. */
+  namePrefix?: string;
+  /** Identifies this client to the server. */
+  clientName?: string;
+  /** Client version reported to the server. */
+  clientVersion?: string;
+};

package/src/mcp/createMcpToolset.d.ts

@@ -0,0 +1,12 @@
+import type { McpServerConfig } from "./McpServerConfig.js";
+import type { McpToolset } from "./McpToolset.js";
+import type { McpToolsetOptions } from "./McpToolsetOptions.js";
+
+export type { McpServerConfig } from "./McpServerConfig.js";
+export type { McpToolset } from "./McpToolset.js";
+export type { McpToolsetOptions } from "./McpToolsetOptions.js";
+
+export declare function createMcpToolset(
+  config: McpServerConfig,
+  options?: McpToolsetOptions,
+): Promise<McpToolset>;

package/src/mcp/createMcpToolset.js

@@ -4,18 +4,7 @@ import { dynamicTool, jsonSchema } from "ai";
 
 /** @typedef {import("./McpServerConfig.ts").McpServerConfig} McpServerConfig */
 /** @typedef {import("./McpToolset.ts").McpToolset} McpToolset */
-
-/**
- * Options for shaping the generated toolset. Mirrors the curation knobs on
- * `createOpenApiTools` so MCP and OpenAPI integrations feel the same.
- *
- * @typedef {object} McpToolsetOptions
- * @property {string[]} [include] Only expose these MCP tool names.
- * @property {string[]} [exclude] Drop these MCP tool names.
- * @property {string} [namePrefix] Prefix applied to every tool name (e.g. `"github_"`).
- * @property {string} [clientName] Identifies this client to the server.
- * @property {string} [clientVersion] Client version reported to the server.
- */
+/** @typedef {import("./McpToolsetOptions.ts").McpToolsetOptions} McpToolsetOptions */
 
 /**
  * Connect to an MCP server and expose its tools as AI SDK tools an agent can call.