patchwork-os 0.2.0-alpha.2 → 0.2.0-alpha.22

package/dist/recipes/yamlRunner.js

@@ -25,16 +25,87 @@ import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, write
 import os from "node:os";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
+import { captureFixture } from "../connectors/fixtureRecorder.js";
+import { normalizeRecipeForRuntime } from "./legacyRecipeCompat.js";
+// Import tool registry and trigger tool self-registration
+import { applyToolOutputContext, executeTool, getTool, hasTool, registerPluginTools, } from "./toolRegistry.js";
+import "./tools/index.js";
+export function evaluateExpect(result, expect) {
+    const failures = [];
+    if (expect.stepsRun !== undefined && result.stepsRun !== expect.stepsRun) {
+        failures.push({
+            assertion: "stepsRun",
+            expected: expect.stepsRun,
+            actual: result.stepsRun,
+            message: `Expected stepsRun=${expect.stepsRun}, got ${result.stepsRun}`,
+        });
+    }
+    if (expect.errorMessage !== undefined) {
+        const expected = expect.errorMessage ?? null;
+        const actual = result.errorMessage ?? null;
+        if (expected !== actual) {
+            failures.push({
+                assertion: "errorMessage",
+                expected,
+                actual,
+                message: expected === null
+                    ? `Expected clean run (no error), got: ${actual}`
+                    : `Expected error "${expected}", got: ${actual === null ? "(none)" : actual}`,
+            });
+        }
+    }
+    if (expect.outputs !== undefined) {
+        for (const key of expect.outputs) {
+            if (!result.outputs.includes(key)) {
+                failures.push({
+                    assertion: "outputs",
+                    expected: key,
+                    actual: result.outputs,
+                    message: `Expected output key "${key}" not found in [${result.outputs.join(", ")}]`,
+                });
+            }
+        }
+    }
+    if (expect.context !== undefined) {
+        for (const [key, expectedVal] of Object.entries(expect.context)) {
+            const actual = result.context[key];
+            if (actual === undefined) {
+                failures.push({
+                    assertion: `context.${key}`,
+                    expected: expectedVal,
+                    actual: undefined,
+                    message: `Expected context key "${key}" to equal "${expectedVal}", but key is missing`,
+                });
+            }
+            else if (!actual.includes(expectedVal)) {
+                failures.push({
+                    assertion: `context.${key}`,
+                    expected: expectedVal,
+                    actual,
+                    message: `Expected context["${key}"] to contain "${expectedVal}", got "${actual}"`,
+                });
+            }
+        }
+    }
+    return failures;
+}
+// Strip tool-call narration some models (e.g. Gemini) prepend before the markdown block.
+function stripLeadingNarration(text) {
+    const lines = text.split("\n");
+    const firstMarkdown = lines.findIndex((l) => /^(#|>|`|\||[-*+] |\d+\. |\*\*)/.test(l.trimStart()));
+    return firstMarkdown > 0 ? lines.slice(firstMarkdown).join("\n") : text;
+}
 export function loadYamlRecipe(filePath) {
     const text = readFileSync(filePath, "utf-8");
     const raw = parseYaml(text);
     return validateYamlRecipe(raw);
 }
 export function validateYamlRecipe(raw) {
-    if (typeof raw !== "object" || raw === null) {
+    const normalized = normalizeRecipeForRuntime(raw);
+    if (typeof normalized !== "object" || normalized === null) {
         throw new Error("recipe must be an object");
     }
-    const r = raw;
+    const r = normalized;
     if (typeof r.name !== "string" || !r.name) {
         throw new Error("recipe.name required");
     }
@@ -44,51 +115,80 @@ export function validateYamlRecipe(raw) {
     if (!Array.isArray(r.steps) || r.steps.length === 0) {
         throw new Error("recipe.steps must be a non-empty array");
     }
+    if (r.servers !== undefined &&
+        (!Array.isArray(r.servers) ||
+            r.servers.some((s) => typeof s !== "string"))) {
+        throw new Error("recipe.servers must be an array of strings if present");
+    }
     return r;
 }
+/** Track already-loaded plugin specs to avoid double-loading within a process. */
+const loadedPluginSpecs = new Set();
+/**
+ * Load plugin specs declared in `recipe.servers` and register their tools into
+ * the recipe tool registry. Errors per-spec are logged as warnings — never fatal.
+ */
+export async function loadRecipeServers(specs) {
+    const toLoad = specs.filter((s) => !loadedPluginSpecs.has(s));
+    if (toLoad.length === 0)
+        return;
+    let loadPluginsFull;
+    try {
+        ({ loadPluginsFull } = await import("../pluginLoader.js"));
+    }
+    catch (err) {
+        console.warn(`[recipe servers] failed to import pluginLoader: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
+    const minimalConfig = {
+        workspace: process.cwd(),
+        workspaceFolders: [process.cwd()],
+        commandTimeout: 30_000,
+        maxResultSize: 1_048_576,
+    };
+    const minimalLogger = {
+        info: (msg) => console.info(`[recipe servers] ${msg}`),
+        warn: (msg) => console.warn(`[recipe servers] ${msg}`),
+        error: (msg) => console.error(`[recipe servers] ${msg}`),
+        debug: (_msg) => { },
+    };
+    for (const spec of toLoad) {
+        try {
+            const loaded = await loadPluginsFull([spec], minimalConfig, minimalLogger);
+            let toolCount = 0;
+            for (const plugin of loaded) {
+                const pluginTools = plugin.tools.map((t) => ({
+                    name: t.schema.name,
+                    handler: t.handler,
+                    schema: t.schema,
+                }));
+                toolCount += registerPluginTools(pluginTools);
+            }
+            loadedPluginSpecs.add(spec);
+            if (toolCount > 0) {
+                console.info(`[recipe servers] loaded "${spec}" — ${toolCount} tool(s) registered`);
+            }
+        }
+        catch (err) {
+            console.warn(`[recipe servers] failed to load "${spec}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
 export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
+    if (recipe.servers?.length) {
+        await loadRecipeServers(recipe.servers);
+    }
     const now = deps.now ? deps.now() : new Date();
     const ctx = {
         date: now.toISOString().slice(0, 10),
         time: now.toTimeString().slice(0, 5),
         ...seedContext,
     };
-    const readFile = deps.readFile ?? ((p) => readFileSync(expandHome(p), "utf-8"));
-    const writeFile = deps.writeFile ??
-        ((p, content) => {
-            const abs = expandHome(p);
-            mkdirSync(path.dirname(abs), { recursive: true });
-            writeFileSync(abs, content);
-        });
-    const appendFile = deps.appendFile ??
-        ((p, content) => {
-            const abs = expandHome(p);
-            mkdirSync(path.dirname(abs), { recursive: true });
-            appendFileSync(abs, content);
-        });
-    const mkdir = deps.mkdir ??
-        ((p) => mkdirSync(expandHome(p), { recursive: true }));
+    const stepDeps = resolveStepDeps(deps);
     const outputs = [];
+    const stepResults = [];
     let stepsRun = 0;
-    const workdir = deps.workdir ?? process.cwd();
-    const stepDeps = {
-        readFile,
-        writeFile,
-        appendFile,
-        mkdir,
-        workdir,
-        gitLogSince: deps.gitLogSince ?? defaultGitLogSince,
-        gitStaleBranches: deps.gitStaleBranches ?? defaultGitStaleBranches,
-        getDiagnostics: deps.getDiagnostics ?? (() => ""),
-        fetchFn: deps.fetchFn ?? globalThis.fetch,
-        claudeFn: deps.claudeFn ?? defaultClaudeFn,
-        claudeCodeFn: deps.claudeCodeFn ?? defaultClaudeCodeFn,
-        getGmailToken: deps.getGmailToken ??
-            (async () => {
-                const { getValidAccessToken } = await import("../connectors/gmail.js");
-                return getValidAccessToken();
-            }),
-    };
+    let runError;
     for (const step of recipe.steps) {
         // Handle agent steps separately
         if (step.agent) {
@@ -96,64 +196,147 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
             const renderedPrompt = render(agentCfg.prompt, ctx);
             const model = agentCfg.model ?? "claude-haiku-4-5-20251001";
             const intoKey = agentCfg.into ?? "agent_output";
+            const stepId = intoKey;
+            const stepStart = Date.now();
             let agentResult;
-            if (agentCfg.driver === "claude-code") {
-                agentResult = await stepDeps.claudeCodeFn(renderedPrompt);
-            }
-            else if (agentCfg.driver === "api") {
-                agentResult = await stepDeps.claudeFn(renderedPrompt, model);
-            }
-            else {
-                // Default driver: use API path. If no ANTHROPIC_API_KEY and caller did not provide a
-                // custom claudeFn (i.e. using the built-in default that returns a skip message), probe
-                // for the claude CLI and fall back automatically.
-                const usingDefaultClaudeFn = deps.claudeFn === undefined;
-                if (!process.env.ANTHROPIC_API_KEY && usingDefaultClaudeFn) {
-                    const probe = spawnSync("claude", ["--version"], {
-                        encoding: "utf-8",
-                        timeout: 5000,
-                    });
-                    if (!probe.error) {
-                        agentResult = await stepDeps.claudeCodeFn(renderedPrompt);
+            try {
+                if (agentCfg.driver === "claude-code") {
+                    agentResult = await stepDeps.claudeCodeFn(renderedPrompt);
+                }
+                else if (agentCfg.driver === "api") {
+                    agentResult = await stepDeps.claudeFn(renderedPrompt, model);
+                }
+                else if (agentCfg.driver === "openai" ||
+                    agentCfg.driver === "grok" ||
+                    agentCfg.driver === "gemini") {
+                    agentResult = await stepDeps.providerDriverFn(agentCfg.driver, renderedPrompt, agentCfg.model);
+                }
+                else {
+                    // Default driver: use API path. If no ANTHROPIC_API_KEY and caller did not provide a
+                    // custom claudeFn (i.e. using the built-in default that returns a skip message), probe
+                    // for the claude CLI and fall back automatically.
+                    const usingDefaultClaudeFn = deps.claudeFn === undefined;
+                    if (!process.env.ANTHROPIC_API_KEY && usingDefaultClaudeFn) {
+                        const probe = spawnSync("claude", ["--version"], {
+                            encoding: "utf-8",
+                            timeout: 5000,
+                        });
+                        if (!probe.error) {
+                            agentResult = await stepDeps.claudeCodeFn(renderedPrompt);
+                        }
+                        else {
+                            agentResult = await stepDeps.claudeFn(renderedPrompt, model);
+                        }
                     }
                     else {
                         agentResult = await stepDeps.claudeFn(renderedPrompt, model);
                     }
                 }
+                if (agentResult.startsWith("[agent step failed:")) {
+                    runError = runError ?? agentResult;
+                    stepResults.push({
+                        id: stepId,
+                        tool: "agent",
+                        status: "error",
+                        error: agentResult,
+                        durationMs: Date.now() - stepStart,
+                    });
+                }
                 else {
-                    agentResult = await stepDeps.claudeFn(renderedPrompt, model);
+                    const stripped = stripLeadingNarration(agentResult);
+                    if (!stripped.trim()) {
+                        const errMsg = `[agent step failed: ${agentCfg.driver ?? "agent"} returned only narration or whitespace — no content]`;
+                        runError = runError ?? errMsg;
+                        stepResults.push({
+                            id: stepId,
+                            tool: "agent",
+                            status: "error",
+                            error: errMsg,
+                            durationMs: Date.now() - stepStart,
+                        });
+                    }
+                    else {
+                        ctx[intoKey] = stripped;
+                        outputs.push(intoKey);
+                        stepResults.push({
+                            id: stepId,
+                            tool: "agent",
+                            status: "ok",
+                            durationMs: Date.now() - stepStart,
+                        });
+                    }
                 }
             }
-            ctx[intoKey] = agentResult;
-            outputs.push(intoKey);
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                runError = runError ?? `agent step "${stepId}" failed: ${msg}`;
+                stepResults.push({
+                    id: stepId,
+                    tool: "agent",
+                    status: "error",
+                    error: msg,
+                    durationMs: Date.now() - stepStart,
+                });
+            }
             stepsRun++;
             continue;
         }
-        const result = await executeStep(step, ctx, stepDeps);
+        const stepStart = Date.now();
+        const stepId = step.into ?? step.tool ?? `step_${stepsRun}`;
+        let result;
+        try {
+            result = await executeStep(step, ctx, stepDeps);
+            // Detect tool-level errors reported as JSON {ok: false, error: ...}
+            let stepError;
+            if (result !== null) {
+                try {
+                    const parsed = JSON.parse(result);
+                    if (parsed.ok === false && typeof parsed.error === "string") {
+                        stepError = parsed.error;
+                    }
+                }
+                catch {
+                    /* non-JSON result is fine */
+                }
+            }
+            stepResults.push({
+                id: stepId,
+                tool: step.tool,
+                status: result === null ? "skipped" : stepError ? "error" : "ok",
+                error: stepError,
+                durationMs: Date.now() - stepStart,
+            });
+            if (stepError)
+                runError = runError ?? `${step.tool} failed: ${stepError}`;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            runError = runError ?? `${step.tool} failed: ${msg}`;
+            stepResults.push({
+                id: stepId,
+                tool: step.tool,
+                status: "error",
+                error: msg,
+                durationMs: Date.now() - stepStart,
+            });
+            result = null;
+        }
         stepsRun++;
         if (result !== null) {
+            // Apply transform if present — render template with $result injected
+            if (step.transform) {
+                try {
+                    result = render(step.transform, { ...ctx, $result: result });
+                }
+                catch (err) {
+                    // warn but fall through with original result
+                    console.warn(`transform failed for step ${step.into ?? step.tool ?? "?"}: ${err}`);
+                }
+            }
             if (step.into) {
                 ctx[step.into] = result;
-                // For Gmail steps, also expose flat dot-notation keys for render()
-                const isGmailStep = step.tool === "gmail.fetch_unread" ||
-                    step.tool === "gmail.search" ||
-                    step.tool === "gmail.fetch_thread";
-                if (isGmailStep) {
-                    try {
-                        const parsed = JSON.parse(result);
-                        for (const [k, v] of Object.entries(parsed)) {
-                            if (typeof v === "string" || typeof v === "number") {
-                                ctx[`${step.into}.${k}`] = String(v);
-                            }
-                        }
-                        // Also expose messages array as JSON string for agent prompts
-                        if (Array.isArray(parsed.messages)) {
-                            ctx[`${step.into}.json`] = JSON.stringify(parsed.messages);
-                        }
-                    }
-                    catch {
-                        // non-JSON result, skip
-                    }
+                if (step.tool) {
+                    applyToolOutputContext(step.tool, step.into, result, ctx);
                 }
             }
             if (step.tool === "file.write" || step.tool === "file.append") {
@@ -161,7 +344,222 @@ export async function runYamlRecipe(recipe, deps = {}, seedContext = {}) {
             }
         }
     }
-    return { recipe: recipe.name, stepsRun, outputs, context: ctx };
+    // Evaluate expect block before persisting so failures are stored in the run log
+    const assertionFailures = recipe.expect
+        ? evaluateExpect({ stepsRun, outputs, context: ctx, errorMessage: runError }, recipe.expect)
+        : [];
+    // Write to RecipeRunLog so the dashboard Runs page shows this execution
+    if (!stepDeps.testMode) {
+        try {
+            const { RecipeRunLog } = await import("../runLog.js");
+            const { homedir } = await import("node:os");
+            const resolvedLogDir = deps.logDir ?? path.join(homedir(), ".patchwork");
+            const log = new RecipeRunLog({ dir: resolvedLogDir });
+            const trigger = recipe.trigger?.type ?? "manual";
+            const createdAt = now.getTime();
+            const doneAt = Date.now();
+            const outputTail = stepResults
+                .map((s) => `[${s.status}] ${s.tool ?? s.id}${s.error ? `: ${s.error}` : ""}`)
+                .join("\n")
+                .slice(0, 2000);
+            log.appendDirect({
+                taskId: `yaml:${recipe.name}:${createdAt}`,
+                recipeName: recipe.name,
+                trigger: (["cron", "webhook", "recipe"].includes(trigger)
+                    ? trigger
+                    : "recipe"),
+                status: runError ? "error" : "done",
+                createdAt,
+                startedAt: createdAt,
+                doneAt,
+                durationMs: doneAt - createdAt,
+                outputTail,
+                errorMessage: runError,
+                stepResults: stepResults.map((s) => ({
+                    id: s.id,
+                    tool: s.tool,
+                    status: s.status,
+                    error: s.error,
+                    durationMs: s.durationMs,
+                })),
+                ...(assertionFailures.length > 0 ? { assertionFailures } : {}),
+            });
+        }
+        catch {
+            // Non-fatal — run log write failure should never break recipe execution
+        }
+    }
+    // Notify via Slack if any step failed
+    if (runError && !stepDeps.testMode) {
+        try {
+            const { isConnected, postMessage } = await import("../connectors/slack.js");
+            if (isConnected()) {
+                // Read notification channel from ~/.patchwork/config.json, fallback to first available
+                let notifyChannel = "all-massappealdesigns";
+                try {
+                    const cfgPath = path.join(os.homedir(), ".patchwork", "config.json");
+                    const cfg = JSON.parse(readFileSync(cfgPath, "utf-8"));
+                    const notifications = cfg.notifications;
+                    if (typeof notifications?.slackChannel === "string") {
+                        notifyChannel = notifications.slackChannel;
+                    }
+                }
+                catch {
+                    /* use default */
+                }
+                const failedSteps = stepResults
+                    .filter((s) => s.status === "error")
+                    .map((s) => `• ${s.tool ?? s.id}: ${s.error ?? "unknown error"}`)
+                    .join("\n");
+                await postMessage(notifyChannel, `⚠️ *Recipe failed: ${recipe.name}*\n\n${failedSteps}\n\n_${new Date().toISOString()}_`);
+            }
+        }
+        catch {
+            // Non-fatal — notification failure should never mask the original error
+        }
+    }
+    return {
+        recipe: recipe.name,
+        stepsRun,
+        outputs,
+        context: ctx,
+        stepResults,
+        errorMessage: runError,
+        ...(assertionFailures.length > 0 ? { assertionFailures } : {}),
+    };
+}
+export async function executeStep(step, ctx, deps) {
+    const toolId = step.tool;
+    if (!toolId) {
+        return null;
+    }
+    // Check if tool is registered in the new registry
+    if (hasTool(toolId)) {
+        const tool = getTool(toolId);
+        // Build params with template rendering for string values
+        const params = {};
+        for (const [key, value] of Object.entries(step)) {
+            if (key === "tool" || key === "agent" || key === "into")
+                continue;
+            if (typeof value === "string") {
+                params[key] = render(value, ctx);
+            }
+            else {
+                params[key] = value;
+            }
+        }
+        // Check if mock connector is available for this tool
+        if (deps.mockConnectors?.[toolId]) {
+            return deps.mockConnectors[toolId].invoke("execute", params);
+        }
+        if (tool &&
+            deps.recordFixturesDir &&
+            tool.namespace !== "file" &&
+            tool.namespace !== "git" &&
+            tool.namespace !== "diagnostics") {
+            return captureFixture(path.join(deps.recordFixturesDir, `${tool.namespace}.json`), tool.namespace, toolId.split(".")[1] ?? toolId, params, async () => executeTool(toolId, { params, step, ctx, deps }));
+        }
+        return executeTool(toolId, { params, step, ctx, deps });
+    }
+    // Unknown tool — skip, don't throw (forward compat)
+    return null;
+}
+/** Minimal `{{ expr }}` renderer — replaces against flat context map. */
+export function render(template, ctx) {
+    return template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_, expr) => {
+        const key = expr.trim();
+        return Object.hasOwn(ctx, key) ? (ctx[key] ?? "") : "";
+    });
+}
+function expandHome(p) {
+    if (p.startsWith("~/"))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+function parseSinceToGitArg(since) {
+    const m = /^(\d+)(h|d)$/i.exec(since.trim());
+    if (!m)
+        return since;
+    const [, num, unit = "h"] = m;
+    return unit.toLowerCase() === "h" ? `${num} hours ago` : `${num} days ago`;
+}
+function defaultGitLogSince(since, workdir) {
+    try {
+        const sinceArg = parseSinceToGitArg(since);
+        const result = spawnSync("git", ["log", "--oneline", `--since=${sinceArg}`], {
+            cwd: workdir ?? process.cwd(),
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        if (result.error || result.status !== 0)
+            return "(git log unavailable)";
+        return (result.stdout ?? "").trim();
+    }
+    catch {
+        return "(git log unavailable)";
+    }
+}
+function defaultGitStaleBranches(days, workdir) {
+    try {
+        const cutoff = new Date(Date.now() - days * 86_400_000)
+            .toISOString()
+            .slice(0, 10);
+        const r = spawnSync("git", [
+            "branch",
+            "--no-column",
+            "--sort=-committerdate",
+            "--format=%(refname:short)",
+            `--since=${cutoff}`,
+        ], {
+            cwd: workdir ?? process.cwd(),
+            encoding: "utf-8",
+            timeout: 5000,
+        });
+        if (r.error || r.status !== 0)
+            return "(git branches unavailable)";
+        return (r.stdout ?? "").trim();
+    }
+    catch {
+        return "(git branches unavailable)";
+    }
+}
+/** Resolve all RunnerDeps to concrete StepDeps with production defaults filled in. */
+function resolveStepDeps(deps) {
+    const workdir = deps.workdir ?? process.cwd();
+    return {
+        readFile: deps.readFile ?? ((p) => readFileSync(expandHome(p), "utf-8")),
+        writeFile: deps.writeFile ??
+            ((p, content) => {
+                const abs = expandHome(p);
+                mkdirSync(path.dirname(abs), { recursive: true });
+                writeFileSync(abs, content);
+            }),
+        appendFile: deps.appendFile ??
+            ((p, content) => {
+                const abs = expandHome(p);
+                mkdirSync(path.dirname(abs), { recursive: true });
+                appendFileSync(abs, content);
+            }),
+        mkdir: deps.mkdir ??
+            ((p) => mkdirSync(expandHome(p), { recursive: true })),
+        workdir,
+        gitLogSince: deps.gitLogSince ?? defaultGitLogSince,
+        gitStaleBranches: deps.gitStaleBranches ?? defaultGitStaleBranches,
+        getDiagnostics: deps.getDiagnostics ?? (() => ""),
+        fetchFn: deps.fetchFn ?? globalThis.fetch,
+        claudeFn: deps.claudeFn ?? defaultClaudeFn,
+        claudeCodeFn: deps.claudeCodeFn ?? defaultClaudeCodeFn,
+        providerDriverFn: deps.providerDriverFn ?? defaultProviderDriverFn,
+        mockConnectors: deps.mockConnectors ?? {},
+        recordFixturesDir: deps.recordFixturesDir,
+        getGmailToken: deps.getGmailToken ??
+            (async () => {
+                const { getValidAccessToken } = await import("../connectors/gmail.js");
+                return getValidAccessToken();
+            }),
+        logDir: deps.logDir,
+        testMode: deps.testMode ?? false,
+    };
 }
 function defaultClaudeCodeFn(prompt) {
     try {
@@ -188,6 +586,49 @@ function defaultClaudeCodeFn(prompt) {
         return Promise.resolve(`[agent step failed: ${err instanceof Error ? err.message : String(err)}]`);
     }
 }
+// Cache provider drivers across steps within a single recipe process.
+const providerDriverCache = new Map();
+async function defaultProviderDriverFn(driverName, prompt, model) {
+    try {
+        let driver = providerDriverCache.get(driverName);
+        if (!driver) {
+            const { createDriver } = await import("../drivers/index.js");
+            const d = createDriver(driverName, { binary: "claude", antBinary: "ant" }, () => { });
+            if (!d)
+                return `[agent step failed: ${driverName} driver returned null]`;
+            driver = d;
+            providerDriverCache.set(driverName, driver);
+        }
+        const controller = new AbortController();
+        const timeoutMs = 300_000;
+        const startupTimeoutMs = 30_000;
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const result = await driver.run({
+                prompt,
+                workspace: process.cwd(),
+                timeoutMs,
+                startupTimeoutMs,
+                signal: controller.signal,
+                model,
+            });
+            if (result.exitCode !== undefined && result.exitCode !== 0) {
+                const detail = result.stderrTail ?? result.text ?? "";
+                return `[agent step failed: ${driverName} exited ${result.exitCode}${detail ? ` — ${detail.slice(0, 200)}` : ""}]`;
+            }
+            if (!result.text) {
+                return `[agent step failed: ${driverName} returned empty output (possible timeout or auth error)]`;
+            }
+            return result.text;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch (err) {
+        return `[agent step failed: ${err instanceof Error ? err.message : String(err)}]`;
+    }
+}
 async function defaultClaudeFn(prompt, model) {
     const apiKey = process.env.ANTHROPIC_API_KEY;
     if (!apiKey)
@@ -222,283 +663,108 @@ async function defaultClaudeFn(prompt, model) {
         return `[agent step failed: ${err instanceof Error ? err.message : String(err)}]`;
     }
 }
-async function executeStep(step, ctx, deps) {
-    switch (step.tool) {
-        case "file.read": {
-            const p = render(step.path, ctx);
-            try {
-                return deps.readFile(p);
-            }
-            catch {
-                if (step.optional)
-                    return "";
-                throw new Error(`file.read: could not read ${p}`);
-            }
-        }
-        case "file.write": {
-            const p = render(step.path, ctx);
-            const content = render(step.content, ctx);
-            deps.writeFile(p, content);
-            return content;
-        }
-        case "file.append": {
-            const p = render(step.path, ctx);
-            const content = render(step.content, ctx);
-            const when = step.when;
-            if (when && !evalWhen(when, ctx))
-                return null;
-            deps.appendFile(p, content);
-            return content;
-        }
-        case "git.log_since": {
-            const since = render(String(step.since ?? "24h"), ctx);
-            return deps.gitLogSince(since, deps.workdir);
-        }
-        case "git.stale_branches": {
-            const days = typeof step.days === "number" ? step.days : 30;
-            return deps.gitStaleBranches(days, deps.workdir);
-        }
-        case "diagnostics.get": {
-            const uri = render(String(step.uri ?? ""), ctx);
-            return deps.getDiagnostics(uri);
-        }
-        case "gmail.fetch_unread": {
-            const since = render(String(step.since ?? "24h"), ctx);
-            const MAX_GMAIL_RESULTS = 50;
-            const max = Math.min(typeof step.max === "number" ? step.max : 20, MAX_GMAIL_RESULTS);
-            const query = `is:unread newer_than:${sinceToGmailQuery(since)}`;
-            return gmailSearch(query, max, deps);
+/**
+ * Build ExecutionDeps for ChainedRecipeRunner backed by the yamlRunner step
+ * handlers. This lets chained recipes use the same tool set (file.*, git.*,
+ * gmail.*, github.*, linear.*, diagnostics.*) as simple YAML recipes.
+ *
+ * Pass the result as `chainedDeps` when calling `dispatchRecipe` or
+ * `runChainedRecipe` so that `executeTool` is properly wired.
+ */
+export function buildChainedDeps(runnerDeps, claudeCodeFnOverride) {
+    const stepDeps = resolveStepDeps(runnerDeps);
+    const executeTool = async (tool, params) => {
+        // Construct a YamlStep-compatible object so we can reuse executeStep.
+        const step = { tool, ...params };
+        // executeStep uses a RunContext for {{}} rendering — by the time executeTool
+        // is called the chained runner has already resolved templates, so we pass
+        // an empty context (no double-rendering).
+        const result = await executeStep(step, {}, stepDeps);
+        return result ?? "";
+    };
+    const executeAgent = async (prompt, model, driver) => {
+        const claudeCodeFn = claudeCodeFnOverride ?? stepDeps.claudeCodeFn;
+        if (driver === "claude-code") {
+            return claudeCodeFn(prompt);
         }
-        case "gmail.search": {
-            const query = render(String(step.query ?? ""), ctx);
-            const MAX_GMAIL_RESULTS = 50;
-            const max = Math.min(typeof step.max === "number" ? step.max : 10, MAX_GMAIL_RESULTS);
-            return gmailSearch(query, max, deps);
+        if (driver === "claude" || driver === "anthropic") {
+            return stepDeps.claudeFn(prompt, model ?? "claude-haiku-4-5-20251001");
         }
-        case "gmail.fetch_thread": {
-            const id = render(String(step.id ?? ""), ctx);
-            return gmailFetchThread(id, deps);
+        if (driver === "openai" || driver === "grok" || driver === "gemini") {
+            return stepDeps.providerDriverFn(driver, prompt, model);
         }
-        case "github.list_issues": {
-            const { listIssues } = await import("../connectors/github.js");
-            const repo = step.repo ? render(String(step.repo), ctx) : undefined;
-            const assignee = step.assignee
-                ? render(String(step.assignee), ctx)
-                : "@me";
-            const limit = typeof step.max === "number" ? step.max : 20;
-            const issues = listIssues({ repo, assignee, limit });
-            return JSON.stringify({ count: issues.length, issues });
+        // No driver specified — mirror runYamlRecipe fallback logic:
+        // prefer API if key is set, otherwise probe for claude CLI.
+        const usingDefaultClaudeFn = runnerDeps.claudeFn === undefined;
+        if (!process.env.ANTHROPIC_API_KEY && usingDefaultClaudeFn) {
+            const probe = spawnSync("claude", ["--version"], {
+                encoding: "utf-8",
+                timeout: 5000,
+            });
+            if (!probe.error) {
+                return claudeCodeFn(prompt);
+            }
         }
-        case "github.list_prs": {
-            const { listPRs } = await import("../connectors/github.js");
-            const repo = step.repo ? render(String(step.repo), ctx) : undefined;
-            const author = step.author ? render(String(step.author), ctx) : "@me";
-            const limit = typeof step.max === "number" ? step.max : 20;
-            const prs = listPRs({ repo, author, limit });
-            return JSON.stringify({ count: prs.length, prs });
+        return stepDeps.claudeFn(prompt, model ?? "claude-haiku-4-5-20251001");
+    };
+    const loadNestedRecipe = async (name) => {
+        const { homedir } = await import("node:os");
+        const recipesDir = path.join(homedir(), ".patchwork", "recipes");
+        const candidates = [
+            path.join(recipesDir, `${name}.yaml`),
+            path.join(recipesDir, `${name}.yml`),
+        ];
+        for (const p of candidates) {
+            try {
+                const raw = stepDeps.readFile(p);
+                const { parse } = await import("yaml");
+                const parsed = parse(raw);
+                if (parsed?.steps)
+                    return parsed;
+            }
+            catch {
+                // try next candidate
+            }
         }
-        default:
-            // Unknown tool — skip, don't throw (forward compat)
-            return null;
-    }
-}
-/** Minimal `{{ expr }}` renderer — replaces against flat context map. */
-export function render(template, ctx) {
-    return template.replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_, expr) => {
-        const key = expr.trim();
-        return Object.hasOwn(ctx, key) ? (ctx[key] ?? "") : "";
-    });
+        return null;
+    };
+    return { executeTool, executeAgent, loadNestedRecipe };
 }
 /**
- * Evaluate simple `N > 0 || M > 0` guards after template rendering.
- * Supports: numeric literals, >, <, >=, <=, ==, !=, ||, &&, !.
- * Returns true (run step) for anything it can't parse.
+ * Dispatch a loaded recipe to the appropriate runner.
+ *
+ * Recipes with `trigger.type: "chained"` are routed to the ChainedRecipeRunner
+ * (parallel execution, template variables, nested recipes, dry-run).
+ * All other recipes use the existing synchronous yamlRunner path.
+ *
+ * `chainedDeps` is only required when the recipe is chained; omit for simple recipes.
  */
-function evalWhen(when, ctx) {
-    try {
-        const expanded = render(when, ctx).trim();
-        // Only handle the `N op M` and `expr || expr` / `expr && expr` patterns.
-        const orParts = expanded.split("||");
-        if (orParts.length > 1) {
-            return orParts.some((p) => evalWhen(p.trim(), {}));
-        }
-        const andParts = expanded.split("&&");
-        if (andParts.length > 1) {
-            return andParts.every((p) => evalWhen(p.trim(), {}));
-        }
-        const m = /^(-?[\d.]+)\s*(>|<|>=|<=|==|!=)\s*(-?[\d.]+)$/.exec(expanded);
-        if (!m)
-            return true;
-        const [, lhs, op, rhs] = m;
-        const l = Number(lhs);
-        const r = Number(rhs);
-        switch (op) {
-            case ">":
-                return l > r;
-            case "<":
-                return l < r;
-            case ">=":
-                return l >= r;
-            case "<=":
-                return l <= r;
-            case "==":
-                return l === r;
-            case "!=":
-                return l !== r;
-            default:
-                return true;
+export async function dispatchRecipe(recipe, deps, seedContext = {}) {
+    const triggerType = recipe.trigger
+        ?.type;
+    if (triggerType === "chained") {
+        const { runChainedRecipe } = await import("./chainedRunner.js");
+        const chainedRecipe = recipe;
+        const now = deps.now ? deps.now() : new Date();
+        const options = {
+            env: {
+                ...process.env,
+                DATE: now.toISOString().slice(0, 10),
+                TIME: now.toTimeString().slice(0, 5),
+                ...seedContext,
+            },
+            maxConcurrency: chainedRecipe.maxConcurrency ?? 4,
+            maxDepth: chainedRecipe.maxDepth ?? 3,
+            dryRun: deps.chainedOptions?.dryRun ?? false,
+            onStepStart: deps.chainedOptions?.onStepStart,
+            onStepComplete: deps.chainedOptions?.onStepComplete,
+        };
+        if (!deps.chainedDeps) {
+            throw new Error("chainedDeps required for chained recipes (provide executeTool, executeAgent, loadNestedRecipe)");
         }
+        return runChainedRecipe(chainedRecipe, options, deps.chainedDeps);
     }
-    catch {
-        return true;
-    }
-}
-function sinceToGmailQuery(since) {
-    // "24h" → "1d", "7d" → "7d", "1h" → "1d" (round up)
-    const m = /^(\d+)(h|d)$/.exec(since.trim().toLowerCase());
-    if (!m)
-        return "1d";
-    const [, num, unit] = m;
-    if (unit === "d")
-        return `${num}d`;
-    // hours → round up to days (min 1d)
-    const days = Math.max(1, Math.ceil(Number(num) / 24));
-    return `${days}d`;
-}
-function getHeader(headers, name) {
-    return (headers.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ??
-        "");
-}
-async function gmailSearch(query, max, deps) {
-    const errorResult = (msg) => JSON.stringify({ count: 0, messages: [], error: msg });
-    let token;
-    try {
-        token = await deps.getGmailToken();
-    }
-    catch {
-        return errorResult("Gmail not connected");
-    }
-    try {
-        const listUrl = `https://gmail.googleapis.com/gmail/v1/users/me/messages?q=${encodeURIComponent(query)}&maxResults=${max}`;
-        const listRes = await deps.fetchFn(listUrl, {
-            headers: { Authorization: `Bearer ${token}` },
-        });
-        if (!listRes.ok)
-            return errorResult("Gmail API error");
-        const listJson = (await listRes.json());
-        const ids = listJson.messages ?? [];
-        const messages = await Promise.all(ids.slice(0, max).map(async (m) => {
-            const detailUrl = `https://gmail.googleapis.com/gmail/v1/users/me/messages/${m.id}?format=metadata&metadataHeaders=Subject,From,Date`;
-            const detailRes = await deps.fetchFn(detailUrl, {
-                headers: { Authorization: `Bearer ${token}` },
-            });
-            if (!detailRes.ok)
-                return { id: m.id, subject: "", from: "", date: "", snippet: "" };
-            const detail = (await detailRes.json());
-            const hdrs = detail.payload?.headers ?? [];
-            return {
-                id: detail.id,
-                subject: getHeader(hdrs, "Subject"),
-                from: getHeader(hdrs, "From"),
-                date: getHeader(hdrs, "Date"),
-                snippet: detail.snippet ?? "",
-            };
-        }));
-        const result = { count: messages.length, messages };
-        return JSON.stringify(result);
-    }
-    catch {
-        return errorResult("Gmail fetch failed");
-    }
-}
-async function gmailFetchThread(id, deps) {
-    const errorResult = (msg) => JSON.stringify({ subject: "", messages: [], error: msg });
-    let token;
-    try {
-        token = await deps.getGmailToken();
-    }
-    catch {
-        return errorResult("Gmail not connected");
-    }
-    try {
-        const url = `https://gmail.googleapis.com/gmail/v1/users/me/threads/${id}?format=metadata&metadataHeaders=Subject,From,Date`;
-        const res = await deps.fetchFn(url, {
-            headers: { Authorization: `Bearer ${token}` },
-        });
-        if (!res.ok)
-            return errorResult("Gmail API error");
-        const thread = (await res.json());
-        const msgs = thread.messages ?? [];
-        const firstHdrs = msgs[0]?.payload?.headers ?? [];
-        const subject = getHeader(firstHdrs, "Subject");
-        const messages = msgs.map((m) => {
-            const hdrs = m.payload?.headers ?? [];
-            return {
-                from: getHeader(hdrs, "From"),
-                date: getHeader(hdrs, "Date"),
-                body_snippet: m.snippet ?? "",
-            };
-        });
-        const result = { subject, messages };
-        return JSON.stringify(result);
-    }
-    catch {
-        return errorResult("Gmail fetch failed");
-    }
-}
-function expandHome(p) {
-    if (p.startsWith("~/"))
-        return path.join(os.homedir(), p.slice(2));
-    return p;
-}
-function parseSinceToGitArg(since) {
-    const m = /^(\d+)(h|d)$/i.exec(since.trim());
-    if (!m)
-        return since;
-    const [, num, unit = "h"] = m;
-    return unit.toLowerCase() === "h" ? `${num} hours ago` : `${num} days ago`;
-}
-function defaultGitLogSince(since, workdir) {
-    try {
-        const sinceArg = parseSinceToGitArg(since);
-        const result = spawnSync("git", ["log", "--oneline", `--since=${sinceArg}`], {
-            cwd: workdir ?? process.cwd(),
-            encoding: "utf-8",
-            timeout: 5000,
-        });
-        if (result.error || result.status !== 0)
-            return "(git log unavailable)";
-        return (result.stdout ?? "").trim();
-    }
-    catch {
-        return "(git log unavailable)";
-    }
-}
-function defaultGitStaleBranches(days, workdir) {
-    try {
-        const cutoff = new Date(Date.now() - days * 86_400_000)
-            .toISOString()
-            .slice(0, 10);
-        const r = spawnSync("git", ["branch", "--format=%(refname:short) %(committerdate:short)"], {
-            cwd: workdir ?? process.cwd(),
-            encoding: "utf-8",
-            timeout: 5000,
-        });
-        const branches = r.error || r.status !== 0 ? "" : (r.stdout ?? "").trim();
-        if (!branches)
-            return "(no local branches)";
-        return (branches
-            .split("\n")
-            .filter((line) => {
-            const parts = line.trim().split(/\s+/);
-            const dateStr = parts[1];
-            return dateStr && dateStr < cutoff;
-        })
-            .join("\n") || "(none older than 30 days)");
-    }
-    catch {
-        return "(git unavailable)";
-    }
+    return runYamlRecipe(recipe, deps, seedContext);
 }
 /** List all YAML recipes in a directory. Returns names. */
 export function listYamlRecipes(recipesDir) {