smithers-orchestrator 0.8.1 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smithers-orchestrator",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "AI workflow orchestration with JSX",
   "author": "William Cory",
   "license": "MIT",

package/src/SmithersCtx.ts

@@ -1,5 +1,14 @@
 import type { OutputKey } from "./OutputKey";
 import type { OutputAccessor, InferOutputEntry } from "./OutputAccessor";
+import type { z } from "zod";
+
+/**
+ * Reverse-lookup: given Schema and a value type V, find the key K where Schema[K] extends V.
+ * Used to narrow return types when passing Zod schema objects directly.
+ */
+type SchemaKeyForValue<Schema, V> = {
+  [K in keyof Schema & string]: Schema[K] extends V ? K : never;
+}[keyof Schema & string];
 
 export interface SmithersCtx<Schema> {
   runId: string;
@@ -8,22 +17,49 @@ export interface SmithersCtx<Schema> {
   input: Schema extends { input: infer T } ? T : Record<string, unknown>;
   outputs: OutputAccessor<Schema>;
 
+  // Overload: pass Zod schema value directly → narrowed return type
+  output<V extends z.ZodTypeAny>(
+    table: V,
+    key: OutputKey,
+  ): SchemaKeyForValue<Schema, V> extends never
+    ? InferOutputEntry<V>
+    : InferOutputEntry<V>;
+
+  // Overload: pass string key → narrowed via K
   output<K extends keyof Schema & string>(
     table: K,
     key: OutputKey,
   ): InferOutputEntry<Schema[K]>;
 
+  // Overload: pass Zod schema value directly → narrowed return type
+  outputMaybe<V extends z.ZodTypeAny>(
+    table: V,
+    key: OutputKey,
+  ): SchemaKeyForValue<Schema, V> extends never
+    ? InferOutputEntry<V> | undefined
+    : InferOutputEntry<V> | undefined;
+
+  // Overload: pass string key → narrowed via K
   outputMaybe<K extends keyof Schema & string>(
     table: K,
     key: OutputKey,
   ): InferOutputEntry<Schema[K]> | undefined;
 
+  // Overload: pass Zod schema value directly → narrowed return type
+  latest<V extends z.ZodTypeAny>(
+    table: V,
+    nodeId: string,
+  ): SchemaKeyForValue<Schema, V> extends never
+    ? InferOutputEntry<V> | undefined
+    : InferOutputEntry<V> | undefined;
+
+  // Overload: pass string key → narrowed via K
   latest<K extends keyof Schema & string>(
     table: K,
     nodeId: string,
   ): InferOutputEntry<Schema[K]> | undefined;
 
-  latestArray(value: unknown, schema: import("zod").ZodType): any[];
+  latestArray(value: unknown, schema: z.ZodType): any[];
 
   iterationCount(table: any, nodeId: string): number;
 }

package/src/TaskDescriptor.ts

@@ -17,9 +17,8 @@ export type TaskDescriptor = {
   retries: number;
   timeoutMs: number | null;
   continueOnFail: boolean;
-  agent?: AgentLike;
-  /** Fallback agent used on retry when the primary agent fails (e.g. rate-limited). */
-  fallbackAgent?: AgentLike;
+  /** Agent or array of agents [primary, fallback1, fallback2, ...]. Tries in order until one succeeds. */
+  agent?: AgentLike | AgentLike[];
   prompt?: string;
   staticPayload?: unknown;
   computeFn?: () => unknown | Promise<unknown>;

package/src/agents/AmpAgent.ts

@@ -0,0 +1,94 @@
+import {
+  BaseCliAgent,
+  pushFlag,
+} from "./BaseCliAgent";
+import type { BaseCliAgentOptions } from "./BaseCliAgent";
+
+type AmpAgentOptions = BaseCliAgentOptions & {
+  workDir?: string;
+  thread?: string;
+  visibility?: "private" | "public" | "workspace" | "group";
+  quiet?: boolean;
+  mcpConfig?: string;
+  settingsFile?: string;
+  logLevel?: "error" | "warn" | "info" | "debug" | "audit";
+  logFile?: string;
+  dangerouslyAllowAll?: boolean;
+  ide?: boolean;
+  jetbrains?: boolean;
+};
+
+export class AmpAgent extends BaseCliAgent {
+  private readonly opts: AmpAgentOptions;
+
+  constructor(opts: AmpAgentOptions = {}) {
+    super(opts);
+    this.opts = opts;
+  }
+
+  protected async buildCommand(params: {
+    prompt: string;
+    systemPrompt?: string;
+    cwd: string;
+    options: any;
+  }) {
+    const args: string[] = ["threads", "continue"];
+    const yoloEnabled = this.opts.yolo ?? this.yolo;
+
+    // Working directory
+    pushFlag(args, "--work-dir", this.opts.workDir ?? params.cwd);
+
+    // Thread ID (if continuing existing thread)
+    pushFlag(args, "--thread", this.opts.thread);
+
+    // Visibility for new threads
+    pushFlag(args, "--visibility", this.opts.visibility);
+
+    // Model
+    pushFlag(args, "--model", this.opts.model ?? this.model);
+
+    // Quiet mode
+    if (this.opts.quiet) args.push("--quiet");
+
+    // MCP config
+    pushFlag(args, "--mcp-config", this.opts.mcpConfig);
+
+    // Settings file
+    pushFlag(args, "--settings-file", this.opts.settingsFile);
+
+    // Log level
+    pushFlag(args, "--log-level", this.opts.logLevel);
+
+    // Log file
+    pushFlag(args, "--log-file", this.opts.logFile);
+
+    // Dangerous allow all (yolo mode)
+    if (this.opts.dangerouslyAllowAll || yoloEnabled) {
+      args.push("--dangerously-allow-all");
+    }
+
+    // IDE integration
+    if (this.opts.ide === false) args.push("--no-ide");
+    if (this.opts.jetbrains === false) args.push("--no-jetbrains");
+
+    // Color handling
+    args.push("--no-color"); // Disable color for clean output parsing
+
+    if (this.extraArgs?.length) args.push(...this.extraArgs);
+
+    // Build prompt with system prompt prepended
+    const systemPrefix = params.systemPrompt
+      ? `${params.systemPrompt}\n\n`
+      : "";
+    const fullPrompt = `${systemPrefix}${params.prompt ?? ""}`;
+
+    // Amp accepts prompt as final argument
+    args.push(fullPrompt);
+
+    return {
+      command: "amp",
+      args,
+      outputFormat: "text" as const,
+    };
+  }
+}

package/src/agents/BaseCliAgent.ts

@@ -190,6 +190,7 @@ export function extractTextFromJsonValue(value: any): string | undefined {
       .join("");
     if (parts.trim()) return parts;
   }
+  if (value.response) return extractTextFromJsonValue(value.response);
   if (value.message) return extractTextFromJsonValue(value.message);
   if (value.result) return extractTextFromJsonValue(value.result);
   if (value.output) return extractTextFromJsonValue(value.output);
@@ -780,6 +781,7 @@ export abstract class BaseCliAgent implements Agent<any, any, any> {
         outputFormat === "json" || outputFormat === "stream-json"
           ? (extractTextFromJsonPayload(rawText) ?? rawText)
           : rawText;
+
       const output = tryParseJson(extractedText);
       return buildGenerateResult(
         extractedText,

package/src/agents/GeminiAgent.ts

@@ -40,7 +40,10 @@ export class GeminiAgent extends BaseCliAgent {
   }) {
     const args: string[] = [];
     const yoloEnabled = this.opts.yolo ?? this.yolo;
-    const outputFormat = this.opts.outputFormat ?? "text";
+    // Default to "json" output format to separate model responses from tool
+    // output text. With "text" format, tool call results (file contents etc.)
+    // are concatenated into the response, making JSON extraction unreliable.
+    const outputFormat = this.opts.outputFormat ?? "json";
 
     if (this.opts.debug) args.push("--debug");
     pushFlag(args, "--model", this.opts.model ?? this.model);
@@ -70,7 +73,12 @@ export class GeminiAgent extends BaseCliAgent {
     const systemPrefix = params.systemPrompt
       ? `${params.systemPrompt}\n\n`
       : "";
-    const fullPrompt = `${systemPrefix}${params.prompt ?? ""}`;
+    // Reinforce JSON output requirement in the prompt for Gemini models which
+    // tend to forget structured output instructions on long responses.
+    const jsonReminder = params.prompt?.includes("REQUIRED OUTPUT")
+      ? "\n\nREMINDER: Your response MUST end with a ```json code fence containing the required JSON object. Do NOT skip this step — the pipeline will reject your response without it.\n"
+      : "";
+    const fullPrompt = `${systemPrefix}${params.prompt ?? ""}${jsonReminder}`;
     args.push("--prompt", fullPrompt);
 
     return {

package/src/agents/KimiAgent.ts

@@ -46,9 +46,14 @@ export class KimiAgent extends BaseCliAgent {
     // Note: --print implicitly adds --yolo
     args.push("--print");
 
-    // Output format
-    const outputFormat = this.opts.outputFormat ?? "stream-json";
+    // Output format — use text with --final-message-only to get only the
+    // model's final response without tool call outputs mixed in.
+    const outputFormat = this.opts.outputFormat ?? "text";
     pushFlag(args, "--output-format", outputFormat);
+    // When using text format, --final-message-only ensures we only get
+    // the model's final response, not intermediate tool output.
+    const finalMessageOnly = this.opts.finalMessageOnly ?? (outputFormat === "text");
+    if (finalMessageOnly) args.push("--final-message-only");
 
     // Other flags
     pushFlag(args, "--work-dir", this.opts.workDir ?? params.cwd);
@@ -76,7 +81,10 @@ export class KimiAgent extends BaseCliAgent {
     const systemPrefix = params.systemPrompt
       ? `${params.systemPrompt}\n\n`
       : "";
-    const fullPrompt = `${systemPrefix}${params.prompt ?? ""}`;
+    const jsonReminder = params.prompt?.includes("REQUIRED OUTPUT")
+      ? "\n\nREMINDER: Your response MUST end with a ```json code fence containing the required JSON object. Do NOT skip this step — the pipeline will reject your response without it.\n"
+      : "";
+    const fullPrompt = `${systemPrefix}${params.prompt ?? ""}${jsonReminder}`;
 
     // Pass prompt via --prompt flag
     pushFlag(args, "--prompt", fullPrompt);

package/src/agents/index.ts

@@ -1,5 +1,7 @@
 export { BaseCliAgent } from "./BaseCliAgent";
 
+export { AmpAgent } from "./AmpAgent";
+
 export { ClaudeCodeAgent } from "./ClaudeCodeAgent";
 
 export { CodexAgent } from "./CodexAgent";

package/src/components/Task.ts

@@ -8,9 +8,8 @@ export type TaskProps<Row> = {
   key?: string;
   id: string;
   output: import("zod").ZodObject<any>;
-  agent?: AgentLike;
-  /** Fallback agent used on retry when the primary agent fails (e.g. rate-limited). */
-  fallbackAgent?: AgentLike;
+  /** Agent or array of agents [primary, fallback1, fallback2, ...]. Tries in order on retries. */
+  agent?: AgentLike | AgentLike[];
   skipIf?: boolean;
   needsApproval?: boolean;
   timeoutMs?: number;

package/src/dom/extract.ts

@@ -208,7 +208,6 @@ export function extractFromHost(
       const continueOnFail = Boolean(raw.continueOnFail);
 
       const agent = raw.agent;
-      const fallbackAgent = raw.fallbackAgent;
       const kind = raw.__smithersKind;
       const isAgent = kind === "agent" || Boolean(agent);
       const prompt = isAgent ? String(raw.children ?? "") : undefined;
@@ -243,7 +242,6 @@ export function extractFromHost(
         timeoutMs,
         continueOnFail,
         agent,
-        fallbackAgent,
         prompt,
         staticPayload,
         computeFn,

package/src/engine/index.ts

@@ -778,9 +778,9 @@ async function executeTask(
     }
 
     if (!payload) {
-      const effectiveAgent =
-        attemptNo > 1 && desc.fallbackAgent ? desc.fallbackAgent : desc.agent;
-      if (desc.agent) {
+      const agents = Array.isArray(desc.agent) ? desc.agent : (desc.agent ? [desc.agent] : []);
+      const effectiveAgent = agents[Math.min(attemptNo - 1, agents.length - 1)];
+      if (effectiveAgent) {
         // Use fallback agent on retry attempts when available
         const result = await runWithToolContext(
           {
@@ -802,15 +802,23 @@ async function executeTask(
             let effectivePrompt = desc.prompt ?? "";
             if (desc.outputTable) {
               const schemaDesc = describeSchemaShape(desc.outputTable as any, desc.outputSchema);
-              effectivePrompt += [
-                "",
-                "",
+              const jsonInstructions = [
                 "**REQUIRED OUTPUT** — You MUST end your response with a JSON object in a code fence matching this schema:",
                 "```json",
                 schemaDesc,
                 "```",
                 "Output the JSON at the END of your response. The workflow will fail without it.",
               ].join("\n");
+              // Prepend a brief reminder at the top AND append full instructions at the end.
+              // This ensures models with long outputs don't lose track of the JSON requirement.
+              effectivePrompt = [
+                "IMPORTANT: After completing the task below, you MUST output a JSON object in a ```json code fence at the very end of your response. Do NOT forget this — the workflow fails without it.",
+                "",
+                effectivePrompt,
+                "",
+                "",
+                jsonInstructions,
+              ].join("\n");
             }
             const emitOutput = (text: string, stream: "stdout" | "stderr") => {
               eventBus.emit("event", {
@@ -869,7 +877,7 @@ async function executeTask(
             // Not valid JSON, try extraction
           }
 
-          // Helper to extract balanced JSON from text
+          // Helper to extract balanced JSON from text (first occurrence)
           function extractBalancedJson(str: string): string | null {
             const start = str.indexOf("{");
             if (start === -1) return null;
@@ -902,13 +910,27 @@ async function executeTask(
             return null;
           }
 
+          // Helper to extract the LAST balanced JSON object in text.
+          // Agents like Kimi emit all intermediate tool output before the final
+          // required JSON, so searching from the end finds the right object.
+          function extractLastBalancedJson(str: string): string | null {
+            let pos = str.lastIndexOf("{");
+            while (pos >= 0) {
+              const json = extractBalancedJson(str.slice(pos));
+              if (json !== null) return json;
+              pos = str.lastIndexOf("{", pos - 1);
+            }
+            return null;
+          }
+
           // Try to extract JSON from code fence (```json ... ```)
           if (output === undefined) {
-            // Check text first - look for code fence with balanced JSON
-            const codeFenceStart = text.search(/```(?:json)?\s*\{/);
-            if (codeFenceStart !== -1) {
+            // Find the LAST code fence — the required output is always at the end
+            const allFences = [...text.matchAll(/```(?:json)?\s*\{/g)];
+            const lastFence = allFences[allFences.length - 1];
+            if (lastFence?.index !== undefined) {
               const afterFence = text
-                .slice(codeFenceStart)
+                .slice(lastFence.index)
                 .replace(/```(?:json)?\s*/, "");
               const jsonStr = extractBalancedJson(afterFence);
               if (jsonStr) {
@@ -965,9 +987,10 @@ async function executeTask(
             }
           }
 
-          // Try text itself
+          // Try text itself — search from END so we get the required output JSON,
+          // not an earlier JSON object from intermediate tool output
           if (output === undefined) {
-            const jsonStr = extractBalancedJson(text);
+            const jsonStr = extractLastBalancedJson(text);
             if (jsonStr) {
               try {
                 const parsed = JSON.parse(jsonStr);
@@ -983,8 +1006,16 @@ async function executeTask(
           // If no JSON found, send a follow-up prompt asking for just the JSON with schema info
           if (output === undefined && desc.agent) {
             const schemaDesc = describeSchemaShape(desc.outputTable as any, desc.outputSchema);
+            // Include a truncated summary of the original response so the model has context
+            const responseSummary = text.length > 2000
+              ? text.slice(0, 1000) + "\n...[truncated]...\n" + text.slice(-1000)
+              : text;
             const jsonPrompt = [
-              `You have completed your task. Now you MUST output ONLY a valid JSON object (no other text) with exactly these fields and types:`,
+              `You previously completed a task and produced this response (possibly truncated):`,
+              ``,
+              responseSummary,
+              ``,
+              `Now you MUST output ONLY a valid JSON object (no other text) summarizing your work above, with exactly these fields and types:`,
               schemaDesc,
               ``,
               `Output ONLY the JSON object, nothing else.`,
@@ -1028,7 +1059,8 @@ async function executeTask(
             console.log(
               `[JSON Debug] finishReason=${finishReason}, text.length=${text.length}, steps.count=${debugSteps.length}`,
             );
-            console.log(`[JSON Debug] text preview: ${text.slice(0, 300)}`);
+            console.log(`[JSON Debug] text start: ${text.slice(0, 300)}`);
+            console.log(`[JSON Debug] text end: ${text.slice(-500)}`);
             console.log(
               `[JSON Debug] last step text: ${debugSteps[debugSteps.length - 1]?.text?.slice(0, 500) ?? "none"}`,
             );

package/src/index.ts

@@ -29,6 +29,7 @@ export {
 
 // Agents
 export {
+  AmpAgent,
   ClaudeCodeAgent,
   CodexAgent,
   GeminiAgent,