@smithers-orchestrator/agents 0.24.0 → 0.24.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/agents",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "description": "AI SDK and CLI agent adapters for Smithers",
   "type": "module",
   "sideEffects": false,
@@ -56,9 +56,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.24.2",
+    "@smithers-orchestrator/errors": "0.24.2",
+    "@smithers-orchestrator/observability": "0.24.2"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/BaseCliAgent/BaseCliAgent.js

@@ -862,7 +862,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,
@@ -1088,4 +1088,10 @@ export class BaseCliAgent {
     createOutputInterpreter() {
         return undefined;
     }
+    /**
+   * @returns {{ provider?: string; model?: string } | undefined}
+   */
+    diagnosticHints() {
+        return undefined;
+    }
 }

package/src/CodexAgent.js

@@ -59,6 +59,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,10 +557,12 @@ 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;
             const { z } = await import("zod");
             let jsonSchema = z.toJSONSchema(schema);

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;

package/src/PiAgent.js

@@ -104,11 +104,14 @@ export class PiAgent extends BaseCliAgent {
             : undefined;
         const effectiveSession = resumeSession ?? this.opts.session;
         this.issuedSessionRef = effectiveSession;
-        if (params.mode === "text") {
-            if (this.opts.print !== false)
-                args.push("--print");
+        // pi's --print (non-interactive: process prompt and exit) and --mode
+        // are independent. Apply --print to every non-RPC mode so json task
+        // executions also process one prompt and exit instead of lingering as
+        // an interactive session (#284).
+        if (params.mode !== "rpc" && this.opts.print !== false) {
+            args.push("--print");
         }
-        else {
+        if (params.mode !== "text") {
             args.push("--mode", params.mode);
         }
         pushFlag(args, "--provider", this.opts.provider);
@@ -197,7 +200,9 @@ export class PiAgent extends BaseCliAgent {
     createOutputInterpreter() {
         let sessionId = this.issuedSessionRef;
         let emittedStarted = false;
+        let emittedCompleted = false;
         let finalAnswer = "";
+        let finalUsage;
         /**
      * @param {unknown} value
      */
@@ -231,6 +236,17 @@ export class PiAgent extends BaseCliAgent {
                 }];
         };
         /**
+     * @param {Record<string, unknown>} payload
+     */
+        const captureUsage = (payload) => {
+            const candidate = (payload && typeof payload.usage === "object" && payload.usage) ||
+                (payload && typeof payload.message === "object" && payload.message && typeof payload.message.usage === "object" && payload.message.usage) ||
+                undefined;
+            if (candidate && typeof candidate === "object" && !Array.isArray(candidate)) {
+                finalUsage = candidate;
+            }
+        };
+        /**
      * @param {string} line
      * @returns {AgentCliEvent[]}
      */
@@ -267,6 +283,7 @@ export class PiAgent extends BaseCliAgent {
                 return startedEvents();
             }
             if (type === "message_end" || type === "turn_end") {
+                captureUsage(payload);
                 const message = payload.message;
                 if (message?.role === "assistant") {
                     const extracted = extractTextFromJsonValue(message);
@@ -276,6 +293,33 @@ export class PiAgent extends BaseCliAgent {
                 }
                 return startedEvents();
             }
+            if (type === "agent_end") {
+                captureUsage(payload);
+                if (Array.isArray(payload.messages)) {
+                    for (let i = payload.messages.length - 1; i >= 0; i--) {
+                        const message = payload.messages[i];
+                        if (message?.role === "assistant") {
+                            const extracted = extractTextFromJsonValue(message);
+                            if (extracted) {
+                                finalAnswer = extracted;
+                            }
+                            break;
+                        }
+                    }
+                }
+                emittedCompleted = true;
+                return [
+                    ...startedEvents(),
+                    {
+                        type: "completed",
+                        engine: this.cliEngine,
+                        ok: true,
+                        answer: finalAnswer || undefined,
+                        usage: finalUsage,
+                        resume: sessionId,
+                    },
+                ];
+            }
             if (type === "tool_execution_start") {
                 const toolName = asString(payload.toolName) ?? "tool";
                 const toolId = asString(payload.toolCallId) ?? toolName;
@@ -355,6 +399,9 @@ export class PiAgent extends BaseCliAgent {
                 const started = !emittedStarted && sessionId
                     ? startedEvents()
                     : [];
+                if (emittedCompleted) {
+                    return started;
+                }
                 return [
                     ...started,
                     {
@@ -362,6 +409,7 @@ export class PiAgent extends BaseCliAgent {
                         engine: this.cliEngine,
                         ok: !result.exitCode || result.exitCode === 0,
                         answer: finalAnswer || undefined,
+                        usage: finalUsage,
                         error: result.exitCode && result.exitCode !== 0
                             ? result.stderr.trim() || `PI exited with code ${result.exitCode}`
                             : undefined,
@@ -394,7 +442,7 @@ export class PiAgent extends BaseCliAgent {
         const cwd = this.cwd ?? options?.rootDir ?? process.cwd();
         const env = { ...process.env, ...this.env };
         const args = this.buildArgs({ prompt, cwd, options, mode });
-        const diagnosticsPromise = launchDiagnostics("pi", env, cwd);
+        const diagnosticsPromise = launchDiagnostics("pi", env, cwd, this.diagnosticHints());
         const interpreter = this.createOutputInterpreter();
         /**
      * @param {AgentCliEvent[] | AgentCliEvent | null | undefined} payload
@@ -465,4 +513,14 @@ export class PiAgent extends BaseCliAgent {
             outputFormat: mode,
         };
     }
+    /**
+   * @returns {{ provider?: string; model?: string; apiKey?: string }}
+   */
+    diagnosticHints() {
+        return {
+            provider: this.opts.provider,
+            model: this.opts.model ?? this.model,
+            apiKey: this.opts.apiKey,
+        };
+    }
 }

package/src/diagnostics/getDiagnosticStrategy.js

@@ -9,6 +9,9 @@ import { spawnSync } from "node:child_process";
 /**
  * @typedef {{ id: DiagnosticCheckId; run: (ctx: DiagnosticContext) => Promise<DiagnosticCheck>; }} DiagnosticCheckDef
  */
+/**
+ * @typedef {{ provider?: string; model?: string; apiKey?: string }} DiagnosticHints
+ */
 
 // ---------------------------------------------------------------------------
 // Shared check helpers
@@ -472,15 +475,75 @@ const antigravityStrategy = {
 // ---------------------------------------------------------------------------
 // Pi strategy
 // ---------------------------------------------------------------------------
-const piStrategy = {
-    agentId: "pi",
-    command: "pi",
-    checks: [
-        checkCliInstalled("pi", "Pi"),
-        googleAuthCheck,
-        googleRateLimitCheck,
-    ],
-};
+/**
+ * Resolve the effective pi provider family from an explicit `--provider`, a
+ * `provider/model` prefix, or a bare model id's well-known prefix. Returns ""
+ * when undeterminable so callers fall back to pi's default (google) (#284).
+ * @param {DiagnosticHints | undefined} hints
+ * @returns {string}
+ */
+function resolvePiProvider(hints) {
+    const explicit = (hints?.provider || "").trim().toLowerCase();
+    if (explicit) {
+        return explicit;
+    }
+    const model = typeof hints?.model === "string" ? hints.model.trim().toLowerCase() : "";
+    if (!model) {
+        return "";
+    }
+    if (model.includes("/")) {
+        return model.split("/")[0];
+    }
+    // Bare model id (no provider prefix) — infer the provider family from
+    // common id prefixes so diagnostics probe the right backend.
+    if (model.startsWith("gpt-") || model.startsWith("o1-") || model.startsWith("o3-") || model.startsWith("o4-") || model.startsWith("chatgpt")) {
+        return "openai";
+    }
+    if (model.startsWith("claude")) {
+        return "anthropic";
+    }
+    if (model.startsWith("gemini")) {
+        return "google";
+    }
+    return "";
+}
+/**
+ * @param {DiagnosticHints | undefined} hints
+ * @returns {DiagnosticCheckDef[]}
+ */
+function piProviderChecks(hints) {
+    const raw = resolvePiProvider(hints);
+    if (raw === "openai" || raw === "openai-codex" || raw === "azure" || raw === "azure-openai") {
+        return [...codexApiKeyAndRateLimitCheck];
+    }
+    if (raw === "anthropic" || raw === "claude") {
+        return [claudeApiKeyCheck, claudeRateLimitCheck];
+    }
+    return [googleAuthCheck, googleRateLimitCheck];
+}
+/**
+ * pi accepts credentials via the `--api-key` option instead of an environment
+ * variable. Diagnostics only see the process env, so map an explicit apiKey to
+ * the env var the selected provider's checks read — otherwise an apiKey-only pi
+ * run is misreported as "key missing" (#284). Returns undefined when there is
+ * nothing to inject.
+ * @param {string} command
+ * @param {DiagnosticHints | undefined} hints
+ * @returns {Record<string, string> | undefined}
+ */
+export function diagnosticApiKeyEnv(command, hints) {
+    if (command !== "pi" || !hints?.apiKey) {
+        return undefined;
+    }
+    const raw = resolvePiProvider(hints);
+    if (raw === "openai" || raw === "openai-codex" || raw === "azure" || raw === "azure-openai") {
+        return { OPENAI_API_KEY: hints.apiKey };
+    }
+    if (raw === "anthropic" || raw === "claude") {
+        return { ANTHROPIC_API_KEY: hints.apiKey };
+    }
+    return { GOOGLE_API_KEY: hints.apiKey };
+}
 // ---------------------------------------------------------------------------
 // Amp strategy
 // ---------------------------------------------------------------------------
@@ -524,13 +587,20 @@ const strategies = {
     antigravity: antigravityStrategy,
     agy: antigravityStrategy,
     gemini: geminiStrategy,
-    pi: piStrategy,
     amp: ampStrategy,
 };
 /**
  * @param {string} command
+ * @param {DiagnosticHints} [hints]
  * @returns {AgentDiagnosticStrategy | null}
  */
-export function getDiagnosticStrategy(command) {
+export function getDiagnosticStrategy(command, hints) {
+    if (command === "pi") {
+        return {
+            agentId: "pi",
+            command: "pi",
+            checks: [checkCliInstalled("pi", "Pi"), ...piProviderChecks(hints)],
+        };
+    }
     return strategies[command] ?? null;
 }

package/src/diagnostics/launchDiagnostics.js

@@ -1,4 +1,4 @@
-import { getDiagnosticStrategy } from "./getDiagnosticStrategy.js";
+import { diagnosticApiKeyEnv, getDiagnosticStrategy } from "./getDiagnosticStrategy.js";
 import { runDiagnostics } from "./runDiagnostics.js";
 /** @typedef {import("./DiagnosticReport.ts").DiagnosticReport} DiagnosticReport */
 
@@ -6,11 +6,14 @@ import { runDiagnostics } from "./runDiagnostics.js";
  * @param {string} command
  * @param {Record<string, string>} env
  * @param {string} cwd
+ * @param {{ provider?: string; model?: string; apiKey?: string }} [hints]
  * @returns {Promise<DiagnosticReport> | null}
  */
-export function launchDiagnostics(command, env, cwd) {
-    const strategy = getDiagnosticStrategy(command);
+export function launchDiagnostics(command, env, cwd, hints) {
+    const strategy = getDiagnosticStrategy(command, hints);
     if (!strategy)
         return null;
-    return runDiagnostics(strategy, { env, cwd }).catch(() => null);
+    const apiKeyEnv = diagnosticApiKeyEnv(command, hints);
+    const effectiveEnv = apiKeyEnv ? { ...env, ...apiKeyEnv } : env;
+    return runDiagnostics(strategy, { env: effectiveEnv, cwd }).catch(() => null);
 }