@davidorex/pi-workflows 0.1.0 → 0.3.0

package/dist/dispatch.js

@@ -0,0 +1,311 @@
+/**
+ * Subprocess dispatch for workflow steps — spawns pi in JSON mode,
+ * collects events, usage, and output. Supports cancellation and timeout.
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { SIGKILL_GRACE_MS } from "./step-shared.js";
+/**
+ * Prompt length threshold (chars) for switching to @file argument passing.
+ * Avoids OS-level argument length limits (typically 128–256 KB) with headroom
+ * for the rest of the CLI args. 8000 chars is well under all limits while
+ * keeping short prompts as direct args for simplicity.
+ */
+const PROMPT_ARG_LIMIT = 8000;
+/** Maximum stdout buffer size (10 MB) to prevent OOM from runaway subprocesses. */
+const MAX_STDOUT_BYTES = 10 * 1024 * 1024;
+export function extractText(content) {
+    if (!content || !Array.isArray(content))
+        return "";
+    for (const part of content) {
+        if (part && typeof part === "object" && "type" in part && part.type === "text" && "text" in part) {
+            return String(part.text);
+        }
+    }
+    return "";
+}
+export function extractToolArgsPreview(args) {
+    if (!args || typeof args !== "object")
+        return "";
+    const obj = args;
+    for (const key of ["command", "path", "pattern", "query", "task"]) {
+        if (typeof obj[key] === "string") {
+            const val = obj[key];
+            return val.length > 60 ? val.slice(0, 57) + "..." : val;
+        }
+    }
+    return "";
+}
+export function buildArgs(step, agentSpec, prompt, options) {
+    const args = ["--mode", "json"];
+    // Session log
+    args.push("--session-dir", options.sessionLogDir);
+    // Model: step > agent spec > model-config by role > model-config default
+    const model = step.model ??
+        agentSpec.model ??
+        (agentSpec.role && options.modelConfig?.by_role?.[agentSpec.role]) ??
+        options.modelConfig?.default;
+    if (model) {
+        const modelArg = `${model}:${agentSpec.thinking ?? "off"}`;
+        args.push("--models", modelArg);
+    }
+    // Tool filtering
+    if (agentSpec.tools?.length) {
+        const builtinTools = [];
+        const extensionPaths = [];
+        for (const tool of agentSpec.tools) {
+            if (tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")) {
+                extensionPaths.push(tool);
+            }
+            else {
+                builtinTools.push(tool);
+            }
+        }
+        if (builtinTools.length > 0)
+            args.push("--tools", builtinTools.join(","));
+        for (const ext of extensionPaths)
+            args.push("--extension", ext);
+    }
+    // Extension scoping
+    if (agentSpec.extensions !== undefined) {
+        args.push("--no-extensions");
+        for (const ext of agentSpec.extensions)
+            args.push("--extension", ext);
+    }
+    // Skill scoping
+    if (agentSpec.skills?.length) {
+        args.push("--no-skills");
+        // Skills are injected via --append-system-prompt, not CLI flags
+    }
+    // System prompt (if agent spec has one)
+    // Write to temp file if present, pass via --append-system-prompt
+    // (handled in dispatch() body, not buildArgs)
+    // Prompt — use @file for long prompts
+    args.push("-p");
+    args.push(prompt); // or @<tmpfile> if prompt > 8000 chars
+    return args;
+}
+/**
+ * Spawn a pi subprocess for a workflow step and collect the result.
+ *
+ * Builds CLI args from the step spec and agent spec.
+ * Streams stdout as newline-delimited JSON.
+ * Collects messages, usage, timing.
+ * Returns StepResult when the process exits.
+ */
+export async function dispatch(step, agentSpec, prompt, options) {
+    const startTime = Date.now();
+    const args = buildArgs(step, agentSpec, prompt, options);
+    // Handle long prompts: write to temp file
+    let tmpDir = null;
+    if (prompt.length > PROMPT_ARG_LIMIT) {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wf-"));
+        const promptFile = path.join(tmpDir, "prompt.md");
+        fs.writeFileSync(promptFile, prompt, { mode: 0o600 });
+        // Replace last two args ("-p", prompt) with ("-p", "@<file>")
+        args[args.length - 1] = `@${promptFile}`;
+    }
+    // Handle system prompt: write to temp file
+    if (agentSpec.systemPrompt) {
+        if (!tmpDir)
+            tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-wf-"));
+        const sysFile = path.join(tmpDir, "system.md");
+        fs.writeFileSync(sysFile, agentSpec.systemPrompt, { mode: 0o600 });
+        // Insert before -p flag
+        const pIdx = args.indexOf("-p");
+        args.splice(pIdx, 0, "--append-system-prompt", sysFile);
+    }
+    const proc = spawn("pi", args, {
+        cwd: options.cwd,
+        env: process.env,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    // Cancellation support
+    if (options.signal) {
+        const kill = () => {
+            proc.kill("SIGTERM");
+            setTimeout(() => {
+                if (!proc.killed)
+                    proc.kill("SIGKILL");
+            }, SIGKILL_GRACE_MS);
+        };
+        if (options.signal.aborted)
+            kill();
+        else
+            options.signal.addEventListener("abort", kill, { once: true });
+    }
+    // Timeout support: SIGTERM after deadline, SIGKILL after 5s grace
+    let timedOut = false;
+    let timeoutTimer;
+    let killTimer;
+    if (options.timeoutMs) {
+        timeoutTimer = setTimeout(() => {
+            timedOut = true;
+            proc.kill("SIGTERM");
+            killTimer = setTimeout(() => {
+                if (!proc.killed)
+                    proc.kill("SIGKILL");
+            }, SIGKILL_GRACE_MS);
+        }, options.timeoutMs);
+    }
+    // Collect result
+    const messages = [];
+    const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+    let lastAssistantText = "";
+    let stderrBuf = "";
+    function processEvent(evt) {
+        // Track messages
+        if (evt.type === "message_end" && evt.message) {
+            messages.push(evt.message);
+            if (evt.message.role === "assistant") {
+                usage.turns++;
+                const u = evt.message.usage;
+                if (u) {
+                    usage.input += u.input || 0;
+                    usage.output += u.output || 0;
+                    usage.cacheRead += u.cacheRead || 0;
+                    usage.cacheWrite += u.cacheWrite || 0;
+                    usage.cost += u.cost?.total || 0;
+                }
+                // Extract text from last assistant message
+                const text = extractText(evt.message.content);
+                if (text)
+                    lastAssistantText = text;
+            }
+        }
+        // Forward to TUI callback
+        if (options.onEvent) {
+            options.onEvent({
+                type: evt.type || "unknown",
+                raw: evt,
+                toolName: evt.type === "tool_execution_start" ? evt.toolName : undefined,
+                toolArgs: evt.type === "tool_execution_start" ? extractToolArgsPreview(evt.args) : undefined,
+                messageText: evt.type === "message_end" && evt.message?.role === "assistant"
+                    ? extractText(evt.message.content)
+                    : undefined,
+                usage: evt.type === "message_end" && evt.message?.role === "assistant" && evt.message.usage
+                    ? {
+                        input: evt.message.usage.input,
+                        output: evt.message.usage.output,
+                        cost: evt.message.usage.cost?.total,
+                    }
+                    : undefined,
+            });
+        }
+    }
+    // Stream stdout as newline-delimited JSON
+    let buf = "";
+    let bufBytes = 0;
+    let stdoutTruncated = false;
+    proc.stdout.on("data", (chunk) => {
+        bufBytes += chunk.length;
+        if (bufBytes > MAX_STDOUT_BYTES) {
+            if (!stdoutTruncated) {
+                stdoutTruncated = true;
+                // Process any remaining partial line in buf before discarding
+                if (buf.trim()) {
+                    try {
+                        const evt = JSON.parse(buf);
+                        processEvent(evt);
+                    }
+                    catch {
+                        // incomplete JSON line — discard
+                    }
+                    buf = "";
+                }
+            }
+            return;
+        }
+        buf += chunk.toString();
+        const lines = buf.split("\n");
+        buf = lines.pop() || "";
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const evt = JSON.parse(line);
+                processEvent(evt);
+            }
+            catch {
+                // Skip unparseable lines
+            }
+        }
+    });
+    proc.stderr.on("data", (chunk) => {
+        stderrBuf += chunk.toString();
+    });
+    // Wait for process to exit
+    const exitCode = await new Promise((resolve) => {
+        proc.on("close", (code) => {
+            // Process remaining buffer
+            if (buf.trim()) {
+                try {
+                    const evt = JSON.parse(buf);
+                    processEvent(evt);
+                }
+                catch {
+                    // Skip unparseable remainder
+                }
+            }
+            resolve(code);
+        });
+    });
+    // Clear timeout timers
+    if (timeoutTimer)
+        clearTimeout(timeoutTimer);
+    if (killTimer)
+        clearTimeout(killTimer);
+    // Cleanup temp files
+    if (tmpDir) {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            // Best-effort cleanup
+        }
+    }
+    // Timeout overrides exit code interpretation
+    if (timedOut) {
+        const warnings = [];
+        if (stdoutTruncated) {
+            warnings.push(`Stdout exceeded ${MAX_STDOUT_BYTES / (1024 * 1024)}MB limit — ` +
+                `output stream was truncated at ${bufBytes} bytes. ` +
+                `Usage counters (tokens, cost, turns) and textOutput may be incomplete.`);
+        }
+        return {
+            step: options.stepName,
+            agent: step.agent,
+            status: "failed",
+            output: undefined,
+            textOutput: lastAssistantText,
+            sessionLog: options.sessionLogDir,
+            usage,
+            durationMs: Date.now() - startTime,
+            error: `Step timed out after ${options.timeoutMs / 1000}s`,
+            truncated: stdoutTruncated || undefined,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    }
+    const warnings = [];
+    if (stdoutTruncated) {
+        warnings.push(`Stdout exceeded ${MAX_STDOUT_BYTES / (1024 * 1024)}MB limit — ` +
+            `output stream was truncated at ${bufBytes} bytes. ` +
+            `Usage counters (tokens, cost, turns) and textOutput may be incomplete.`);
+    }
+    return {
+        step: options.stepName,
+        agent: step.agent,
+        status: exitCode === 0 ? "completed" : "failed",
+        output: undefined, // structured output handled by caller (workflow-executor)
+        textOutput: lastAssistantText,
+        sessionLog: options.sessionLogDir,
+        usage,
+        durationMs: Date.now() - startTime,
+        error: exitCode !== 0 ? stderrBuf.trim() || "Process exited with code " + exitCode : undefined,
+        truncated: stdoutTruncated || undefined,
+        warnings: warnings.length > 0 ? warnings : undefined,
+    };
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../src/dispatch.ts"],"names":[],"mappings":"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"}

package/dist/expression.d.ts

@@ -0,0 +1,64 @@
+/** Filter names derived from the FILTERS registry — add a filter above, this updates automatically. */
+export declare const FILTER_NAMES: string[];
+/** Known root-level expression scope keys. */
+export declare const EXPRESSION_ROOTS: readonly ["input", "steps"];
+/**
+ * Error class for expression resolution failures.
+ * Contains the original expression and a diagnostic reason.
+ */
+export declare class ExpressionError extends Error {
+    readonly expression: string;
+    readonly reason: string;
+    constructor(expression: string, reason: string);
+}
+/**
+ * Resolve a single expression string (without the ${{ }} delimiters).
+ * E.g. "steps.diagnose.output.rootCause" walks scope.steps.diagnose.output.rootCause
+ *
+ * Supports pipe filters: "totalDurationMs | duration"
+ *
+ * Scope is Record<string, unknown> — accepts ExpressionScope, CompletionScope, or any object.
+ *
+ * Throws ExpressionError if any segment of the path is undefined or null,
+ * or if a filter name is unknown.
+ */
+export declare function resolveExpression(expr: string, scope: Record<string, unknown>): unknown;
+/**
+ * Resolve all ${{ }} expressions in a value.
+ *
+ * - If `value` is a string containing `${{ expr }}`, resolve the expression.
+ * - If `value` is a string that IS entirely `${{ expr }}`, return the resolved value
+ *   (preserving its type -- object, array, number, etc.).
+ * - If `value` is a string with `${{ expr }}` embedded in other text,
+ *   stringify the resolved value and interpolate.
+ * - If `value` is an object, recursively resolve all values.
+ * - If `value` is an array, recursively resolve all elements.
+ * - If `value` is anything else (number, boolean, null), return as-is.
+ *
+ * Throws ExpressionError if a property path doesn't resolve.
+ */
+export declare function resolveExpressions(value: unknown, scope: Record<string, unknown>): unknown;
+/**
+ * Parse a right-hand operand string into a typed value.
+ * Supports: string literals ('value' or "value"), number literals, boolean literals (true/false),
+ * null, undefined, or expression paths resolved against scope.
+ */
+export declare function parseRightOperand(str: string, scope: Record<string, unknown>): unknown;
+/**
+ * Compare two values using a comparison operator.
+ * == and === both use strict equality (===).
+ */
+export declare function compare(left: unknown, right: unknown, op: string): boolean;
+/**
+ * Evaluate a condition expression for boolean truthiness.
+ *
+ * Supports:
+ * - Simple path expressions: truthy/falsy evaluation of the resolved value
+ * - Negation with ! prefix
+ * - Comparison operators: ==, !=, ===, !==, >, <, >=, <=
+ * - Right operands: string literals, number literals, boolean literals, null, undefined, or expression paths
+ *
+ * JS truthiness rules: undefined, null, false, 0, "" are falsy; everything else is truthy.
+ */
+export declare function evaluateCondition(expr: string, scope: Record<string, unknown>): boolean;
+//# sourceMappingURL=expression.d.ts.map

package/dist/expression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.d.ts","sourceRoot":"","sources":["../src/expression.ts"],"names":[],"mappings":"AAkBA,uGAAuG;AACvG,eAAO,MAAM,YAAY,UAAuB,CAAC;AAEjD,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,6BAA8B,CAAC;AAE5D;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM9C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAuDvF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAmB1F;AAmCD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAoBtF;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAmB1E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAgCvF"}