@davidorex/pi-workflows 0.2.0 → 0.3.0

package/dist/step-loop.js

@@ -0,0 +1,278 @@
+/**
+ * Loop step executor — runs sub-steps repeatedly until a gate breaks,
+ * max attempts is reached, or a step fails.
+ */
+import path from "node:path";
+import { evaluateCondition, resolveExpressions } from "./expression.js";
+import { persistStepOutput } from "./output.js";
+import { executeGate } from "./step-gate.js";
+import { addUsage, buildPrompt, compileAgentSpec, DEFAULT_MAX_ATTEMPTS, zeroUsage } from "./step-shared.js";
+import { executeTransform } from "./step-transform.js";
+/**
+ * Execute a loop step: runs sub-steps repeatedly until a gate breaks,
+ * max attempts is reached, or a step fails.
+ *
+ * Loop sub-steps can be agent, gate, or transform steps.
+ * Gates inside loops support onPass: "break" (stop looping on success)
+ * and onFail: "continue" (retry on failure, the default inside loops).
+ *
+ * The loop scope provides ${{ loop.iteration }}, ${{ loop.maxAttempts }},
+ * and ${{ loop.priorAttempts }} for expression resolution inside sub-steps.
+ */
+export async function executeLoop(loopSpec, stepName, state, options) {
+    const { ctx, signal, loadAgent, dispatchAgent, runDir } = options;
+    const startTime = Date.now();
+    // Resolve maxAttempts (may be a ${{ }} expression)
+    const scope = { input: state.input, steps: state.steps };
+    let maxAttempts;
+    if (loopSpec.attempts) {
+        const resolved = resolveExpressions(loopSpec.attempts, scope);
+        maxAttempts = Number(resolved);
+        if (isNaN(maxAttempts) || maxAttempts < 1)
+            maxAttempts = loopSpec.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    }
+    else {
+        maxAttempts = loopSpec.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    }
+    const allAttempts = [];
+    let loopStatus = "failed"; // assume failure until break
+    let lastIterationSteps = {};
+    for (let iteration = 0; iteration < maxAttempts; iteration++) {
+        // Check cancellation
+        if (signal?.aborted)
+            break;
+        const iterationSteps = {};
+        let shouldBreak = false;
+        let iterationFailed = false;
+        // Execute sub-steps sequentially
+        const subStepEntries = Object.entries(loopSpec.steps);
+        for (const [subName, subSpec] of subStepEntries) {
+            if (signal?.aborted)
+                break;
+            // Build scope with loop context
+            const subScope = {
+                input: state.input,
+                steps: { ...state.steps, ...iterationSteps }, // see prior sub-steps in this iteration
+                loop: {
+                    iteration,
+                    maxAttempts,
+                    priorAttempts: allAttempts,
+                },
+            };
+            // Handle `when` conditional
+            if (subSpec.when) {
+                const condExpr = subSpec.when.replace(/^\$\{\{\s*/, "").replace(/\s*\}\}$/, "");
+                if (!evaluateCondition(condExpr, subScope)) {
+                    iterationSteps[subName] = {
+                        step: subName,
+                        agent: subSpec.agent ?? "skipped",
+                        status: "skipped",
+                        usage: zeroUsage(),
+                        durationMs: 0,
+                    };
+                    continue;
+                }
+            }
+            // Execute sub-step based on type
+            let result;
+            if (subSpec.gate) {
+                const resolvedCheck = String(resolveExpressions(subSpec.gate.check, subScope));
+                result = await executeGate({ ...subSpec.gate, check: resolvedCheck }, subName, { cwd: ctx.cwd, signal });
+                // Handle gate pass/fail with break/continue
+                const passed = result.output?.passed;
+                if (passed && subSpec.gate.onPass === "break") {
+                    iterationSteps[subName] = result;
+                    shouldBreak = true;
+                    loopStatus = "completed";
+                    break;
+                }
+                if (!passed) {
+                    if (subSpec.gate.onFail === "break") {
+                        iterationSteps[subName] = result;
+                        shouldBreak = true;
+                        break;
+                    }
+                    if (subSpec.gate.onFail === "fail") {
+                        // Explicitly set to "fail" — stop the loop
+                        result.status = "failed";
+                        iterationSteps[subName] = result;
+                        iterationFailed = true;
+                        break;
+                    }
+                    // Default inside loops is "continue" — proceed to next sub-step
+                    // (or end iteration, triggering retry)
+                }
+            }
+            else if (subSpec.transform) {
+                result = executeTransform(subSpec.transform, subName, subScope);
+                if (result.status === "failed") {
+                    iterationSteps[subName] = result;
+                    iterationFailed = true;
+                    break;
+                }
+            }
+            else if (subSpec.agent) {
+                // Resolve input, load agent, dispatch
+                let resolvedInput;
+                try {
+                    resolvedInput = resolveExpressions(subSpec.input ?? {}, subScope);
+                }
+                catch (err) {
+                    iterationSteps[subName] = {
+                        step: subName,
+                        agent: subSpec.agent,
+                        status: "failed",
+                        usage: zeroUsage(),
+                        durationMs: 0,
+                        error: err instanceof Error ? err.message : String(err),
+                    };
+                    iterationFailed = true;
+                    break;
+                }
+                let agentSpec;
+                try {
+                    agentSpec = loadAgent(subSpec.agent);
+                }
+                catch (err) {
+                    iterationSteps[subName] = {
+                        step: subName,
+                        agent: subSpec.agent,
+                        status: "failed",
+                        usage: zeroUsage(),
+                        durationMs: 0,
+                        error: err instanceof Error ? err.message : String(err),
+                    };
+                    iterationFailed = true;
+                    break;
+                }
+                agentSpec = compileAgentSpec(agentSpec, resolvedInput, options.templateEnv);
+                const prompt = buildPrompt(subSpec, agentSpec, resolvedInput, runDir, `${stepName}-${iteration}-${subName}`);
+                result = await dispatchAgent(subSpec, agentSpec, prompt, {
+                    cwd: ctx.cwd,
+                    sessionLogDir: path.join(runDir, "sessions"),
+                    stepName: `${stepName}-${iteration}-${subName}`,
+                    signal,
+                });
+                if (result.status === "failed") {
+                    iterationSteps[subName] = result;
+                    iterationFailed = true;
+                    break;
+                }
+            }
+            else {
+                continue; // unknown step type, skip
+            }
+            iterationSteps[subName] = result;
+        }
+        // Record this iteration
+        lastIterationSteps = iterationSteps;
+        allAttempts.push({ iteration, steps: iterationSteps });
+        if (shouldBreak)
+            break;
+        if (iterationFailed) {
+            // Agent step failed within loop — stop the loop (not just the iteration)
+            loopStatus = "failed";
+            break;
+        }
+        // End of iteration without break — loop continues to next iteration
+    }
+    // If loop exhausted without break or failure, run onExhausted
+    if (loopStatus !== "completed" && loopSpec.onExhausted) {
+        const exhaustedScope = {
+            input: state.input,
+            steps: state.steps,
+            loop: {
+                iteration: allAttempts.length,
+                maxAttempts,
+                priorAttempts: allAttempts,
+                allAttempts,
+            },
+        };
+        let resolvedInput;
+        let exhaustedError;
+        try {
+            resolvedInput = resolveExpressions(loopSpec.onExhausted.input ?? {}, exhaustedScope);
+        }
+        catch (err) {
+            exhaustedError = err instanceof Error ? err.message : String(err);
+            // Still proceed with onExhausted — let the agent run with empty input
+            // but record the expression error so it's visible in the result
+        }
+        if (loopSpec.onExhausted.agent) {
+            let agentSpec;
+            try {
+                agentSpec = loadAgent(loopSpec.onExhausted.agent);
+            }
+            catch (err) {
+                lastIterationSteps["_exhausted"] = {
+                    step: `${stepName}-exhausted`,
+                    agent: loopSpec.onExhausted.agent,
+                    status: "failed",
+                    usage: zeroUsage(),
+                    durationMs: 0,
+                    error: err instanceof Error ? err.message : String(err),
+                };
+                agentSpec = null;
+            }
+            if (agentSpec) {
+                const prompt = buildPrompt(loopSpec.onExhausted, agentSpec, resolvedInput, runDir, `${stepName}-exhausted`);
+                const exhaustedResult = await dispatchAgent(loopSpec.onExhausted, agentSpec, prompt, {
+                    cwd: ctx.cwd,
+                    sessionLogDir: path.join(runDir, "sessions"),
+                    stepName: `${stepName}-exhausted`,
+                    signal,
+                });
+                if (exhaustedResult && exhaustedError) {
+                    exhaustedResult.error = `Expression error in onExhausted input: ${exhaustedError}. Agent ran with empty input.`;
+                }
+                // Include exhausted result in the loop's output
+                lastIterationSteps["_exhausted"] = exhaustedResult;
+            }
+        }
+        if (!loopSpec.onExhausted.agent && exhaustedError) {
+            lastIterationSteps["_exhausted"] = {
+                step: `${stepName}-exhausted`,
+                agent: "exhausted",
+                status: "failed",
+                usage: zeroUsage(),
+                durationMs: 0,
+                error: `Expression error in onExhausted input: ${exhaustedError}`,
+            };
+        }
+    }
+    // Aggregate usage across all iterations
+    const totalUsage = zeroUsage();
+    for (const attempt of allAttempts) {
+        for (const result of Object.values(attempt.steps)) {
+            addUsage(totalUsage, result.usage);
+        }
+    }
+    const loopOutput = {
+        iterations: allAttempts.length,
+        maxAttempts,
+        attempts: allAttempts,
+        lastIteration: lastIterationSteps,
+    };
+    const loopTextOutput = `Loop '${stepName}': ${allAttempts.length}/${maxAttempts} iterations, status: ${loopStatus}`;
+    const result = {
+        step: stepName,
+        agent: "loop",
+        status: loopStatus,
+        output: loopOutput,
+        textOutput: loopTextOutput,
+        usage: totalUsage,
+        durationMs: Date.now() - startTime,
+    };
+    // Propagate truncation from any sub-step
+    const anyTruncated = allAttempts.some((a) => Object.values(a.steps).some((s) => s.truncated));
+    if (anyTruncated) {
+        result.truncated = true;
+        result.warnings = [
+            ...(result.warnings ?? []),
+            "One or more loop sub-steps had truncated stdout — usage totals may undercount.",
+        ];
+    }
+    result.outputPath = persistStepOutput(runDir, stepName, loopOutput, loopTextOutput, options.outputPath);
+    return result;
+}
+//# sourceMappingURL=step-loop.js.map

package/dist/step-loop.js.map

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

package/dist/step-monitor.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Monitor step executor — runs a monitor's classification as a workflow
+ * verification gate. Lightweight: reads monitor spec, loads patterns,
+ * renders prompt (Nunjucks or inline), calls LLM, parses verdict.
+ *
+ * Does NOT depend on pi-behavior-monitors — implements just enough to
+ * classify. No event handling, steering, ceiling, or escalation.
+ */
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { StepResult } from "./types.js";
+interface MonitorSpec {
+    name: string;
+    classify: {
+        model: string;
+        context: string[];
+        prompt: string;
+        promptTemplate?: string;
+    };
+    patterns: {
+        path: string;
+    };
+    instructions?: {
+        path: string;
+    };
+}
+/**
+ * Find a monitor spec by name. Searches:
+ *   1. .pi/monitors/ (project)
+ *   2. ~/.pi/agent/monitors/ (user)
+ *   3. pi-behavior-monitors examples (if installed as peer)
+ */
+export declare function findMonitorSpec(monitorName: string, cwd: string): {
+    spec: MonitorSpec;
+    dir: string;
+} | null;
+export interface MonitorStepOptions {
+    cwd: string;
+    ctx: ExtensionContext;
+    signal?: AbortSignal;
+    runDir?: string;
+    outputPath?: string;
+}
+/**
+ * Execute a monitor step: discover monitor, render prompt, classify, return verdict.
+ *
+ * - CLEAN → status: "completed", output: { verdict: "clean" }
+ * - FLAG  → status: "failed",    output: { verdict: "flag", description }
+ * - NEW   → status: "failed",    output: { verdict: "new", pattern, description }
+ */
+export declare function executeMonitor(monitorName: string, stepName: string, input: Record<string, unknown>, options: MonitorStepOptions): Promise<StepResult>;
+/**
+ * List all discoverable monitor names for validation.
+ */
+export declare function availableMonitors(cwd: string): string[];
+export {};
+//# sourceMappingURL=step-monitor.d.ts.map

package/dist/step-monitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-monitor.d.ts","sourceRoot":"","sources":["../src/step-monitor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAItE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAI7C,UAAU,WAAW;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,QAAQ,EAAE;QACT,IAAI,EAAE,MAAM,CAAC;KACb,CAAC;IACF,YAAY,CAAC,EAAE;QACd,IAAI,EAAE,MAAM,CAAC;KACb,CAAC;CACF;AAoBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAwC3G;AAoHD,MAAM,WAAW,kBAAkB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,gBAAgB,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CACnC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,kBAAkB,GACzB,OAAO,CAAC,UAAU,CAAC,CAuHrB;AAYD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CA0BvD"}

package/dist/step-monitor.js

@@ -0,0 +1,317 @@
+/**
+ * Monitor step executor — runs a monitor's classification as a workflow
+ * verification gate. Lightweight: reads monitor spec, loads patterns,
+ * renders prompt (Nunjucks or inline), calls LLM, parses verdict.
+ *
+ * Does NOT depend on pi-behavior-monitors — implements just enough to
+ * classify. No event handling, steering, ceiling, or escalation.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { complete } from "@mariozechner/pi-ai";
+import nunjucks from "nunjucks";
+import { persistStepOutput } from "./output.js";
+import { zeroUsage } from "./step-shared.js";
+// ── Discovery ────────────────────────────────────────────────────────────────
+/**
+ * Find a monitor spec by name. Searches:
+ *   1. .pi/monitors/ (project)
+ *   2. ~/.pi/agent/monitors/ (user)
+ *   3. pi-behavior-monitors examples (if installed as peer)
+ */
+export function findMonitorSpec(monitorName, cwd) {
+    const searchDirs = [
+        path.join(cwd, ".pi", "monitors"),
+        path.join(os.homedir(), ".pi", "agent", "monitors"),
+    ];
+    // Also check pi-behavior-monitors examples via node_modules
+    try {
+        const bmPath = require.resolve("@davidorex/pi-behavior-monitors/package.json", { paths: [cwd] });
+        searchDirs.push(path.join(path.dirname(bmPath), "examples"));
+    }
+    catch {
+        // pi-behavior-monitors not installed — skip
+    }
+    for (const dir of searchDirs) {
+        const filePath = path.join(dir, `${monitorName}.monitor.json`);
+        try {
+            const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+            if (raw.name && raw.classify && raw.patterns?.path) {
+                return {
+                    spec: {
+                        name: raw.name,
+                        classify: {
+                            model: raw.classify.model ?? "claude-sonnet-4-20250514",
+                            context: Array.isArray(raw.classify.context) ? raw.classify.context : [],
+                            prompt: raw.classify.prompt ?? "",
+                            promptTemplate: typeof raw.classify.promptTemplate === "string" ? raw.classify.promptTemplate : undefined,
+                        },
+                        patterns: { path: raw.patterns.path },
+                        instructions: raw.instructions?.path ? { path: raw.instructions.path } : undefined,
+                    },
+                    dir,
+                };
+            }
+        }
+        catch {
+            // file doesn't exist or is invalid — try next
+        }
+    }
+    return null;
+}
+// ── Pattern & instruction loading ────────────────────────────────────────────
+function loadPatterns(dir, patternsPath) {
+    try {
+        const resolved = path.resolve(dir, patternsPath);
+        return JSON.parse(fs.readFileSync(resolved, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+function loadInstructions(dir, instructionsPath) {
+    if (!instructionsPath)
+        return [];
+    try {
+        const resolved = path.resolve(dir, instructionsPath);
+        return JSON.parse(fs.readFileSync(resolved, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+}
+function formatPatterns(patterns) {
+    return patterns.map((p, i) => `${i + 1}. [${p.severity ?? "warning"}] ${p.description}`).join("\n");
+}
+function formatInstructions(instructions) {
+    if (instructions.length === 0)
+        return "";
+    const lines = instructions.map((i) => `- ${i.text}`).join("\n");
+    return `\nOperating instructions from the user (follow these strictly):\n${lines}\n`;
+}
+// ── Template rendering ───────────────────────────────────────────────────────
+function createTemplateEnv(cwd) {
+    const searchPaths = [];
+    const projectDir = path.join(cwd, ".pi", "monitors");
+    const userDir = path.join(os.homedir(), ".pi", "agent", "monitors");
+    if (fs.existsSync(projectDir))
+        searchPaths.push(projectDir);
+    if (fs.existsSync(userDir))
+        searchPaths.push(userDir);
+    // pi-behavior-monitors examples
+    try {
+        const bmPath = require.resolve("@davidorex/pi-behavior-monitors/package.json", { paths: [cwd] });
+        const exDir = path.join(path.dirname(bmPath), "examples");
+        if (fs.existsSync(exDir))
+            searchPaths.push(exDir);
+    }
+    catch {
+        /* not installed */
+    }
+    const loader = searchPaths.length > 0 ? new nunjucks.FileSystemLoader(searchPaths) : undefined;
+    return new nunjucks.Environment(loader, { autoescape: false, throwOnUndefined: false });
+}
+function renderPrompt(spec, dir, input, templateEnv) {
+    const patterns = loadPatterns(dir, spec.patterns.path);
+    if (patterns.length === 0)
+        return null;
+    const instructions = loadInstructions(dir, spec.instructions?.path);
+    // Build context: patterns, instructions, plus any input fields
+    const context = {
+        patterns: formatPatterns(patterns),
+        instructions: formatInstructions(instructions),
+        iteration: 0,
+        ...input,
+    };
+    if (spec.classify.promptTemplate) {
+        try {
+            return templateEnv.render(spec.classify.promptTemplate, context);
+        }
+        catch {
+            // Fall through to inline prompt
+            if (!spec.classify.prompt)
+                return null;
+        }
+    }
+    if (!spec.classify.prompt)
+        return null;
+    return spec.classify.prompt.replace(/\{(\w+)\}/g, (match, key) => {
+        return String(context[key] ?? match);
+    });
+}
+// ── Verdict parsing ──────────────────────────────────────────────────────────
+function parseVerdict(raw) {
+    const text = raw.trim();
+    if (text.startsWith("CLEAN"))
+        return { verdict: "clean" };
+    if (text.startsWith("NEW:")) {
+        const rest = text.slice(4);
+        const pipe = rest.indexOf("|");
+        if (pipe !== -1) {
+            return { verdict: "new", pattern: rest.slice(0, pipe).trim(), description: rest.slice(pipe + 1).trim() };
+        }
+        return { verdict: "new", pattern: rest.trim(), description: rest.trim() };
+    }
+    if (text.startsWith("FLAG:"))
+        return { verdict: "flag", description: text.slice(5).trim() };
+    return { verdict: "clean" };
+}
+function extractText(parts) {
+    return parts
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("");
+}
+/**
+ * Execute a monitor step: discover monitor, render prompt, classify, return verdict.
+ *
+ * - CLEAN → status: "completed", output: { verdict: "clean" }
+ * - FLAG  → status: "failed",    output: { verdict: "flag", description }
+ * - NEW   → status: "failed",    output: { verdict: "new", pattern, description }
+ */
+export async function executeMonitor(monitorName, stepName, input, options) {
+    const startTime = Date.now();
+    // 1. Discover monitor
+    const found = findMonitorSpec(monitorName, options.cwd);
+    if (!found) {
+        return {
+            step: stepName,
+            agent: `monitor:${monitorName}`,
+            status: "failed",
+            usage: zeroUsage(),
+            durationMs: Date.now() - startTime,
+            error: `Monitor '${monitorName}' not found`,
+        };
+    }
+    const { spec, dir } = found;
+    // 2. Render prompt
+    const templateEnv = createTemplateEnv(options.cwd);
+    const prompt = renderPrompt(spec, dir, input, templateEnv);
+    if (!prompt) {
+        return {
+            step: stepName,
+            agent: `monitor:${monitorName}`,
+            status: "completed",
+            output: { verdict: "clean", note: "No patterns loaded — nothing to classify" },
+            textOutput: "CLEAN (no patterns)",
+            usage: zeroUsage(),
+            durationMs: Date.now() - startTime,
+        };
+    }
+    // 3. Resolve model
+    const { provider, modelId } = parseModelSpec(spec.classify.model);
+    const model = options.ctx.modelRegistry.find(provider, modelId);
+    if (!model) {
+        return {
+            step: stepName,
+            agent: `monitor:${monitorName}`,
+            status: "failed",
+            usage: zeroUsage(),
+            durationMs: Date.now() - startTime,
+            error: `Model '${spec.classify.model}' not found in registry`,
+        };
+    }
+    const apiKey = await options.ctx.modelRegistry.getApiKey(model);
+    if (!apiKey) {
+        return {
+            step: stepName,
+            agent: `monitor:${monitorName}`,
+            status: "failed",
+            usage: zeroUsage(),
+            durationMs: Date.now() - startTime,
+            error: `No API key for model '${spec.classify.model}'`,
+        };
+    }
+    // 4. Classify
+    let response;
+    try {
+        response = await complete(model, { messages: [{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() }] }, { apiKey, maxTokens: 150, signal: options.signal });
+    }
+    catch (err) {
+        if (options.signal?.aborted) {
+            return {
+                step: stepName,
+                agent: `monitor:${monitorName}`,
+                status: "failed",
+                usage: zeroUsage(),
+                durationMs: Date.now() - startTime,
+                error: "Monitor classification cancelled",
+            };
+        }
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            step: stepName,
+            agent: `monitor:${monitorName}`,
+            status: "failed",
+            usage: zeroUsage(),
+            durationMs: Date.now() - startTime,
+            error: `Classification failed: ${msg}`,
+        };
+    }
+    // 5. Parse verdict
+    const rawText = extractText(response.content);
+    const verdict = parseVerdict(rawText);
+    const durationMs = Date.now() - startTime;
+    // Estimate usage from response
+    const usage = zeroUsage();
+    // Token counts not directly available from complete() — leave as zero
+    const output = {
+        verdict: verdict.verdict,
+        ...(verdict.description ? { description: verdict.description } : {}),
+        ...(verdict.pattern ? { pattern: verdict.pattern } : {}),
+    };
+    const result = {
+        step: stepName,
+        agent: `monitor:${monitorName}`,
+        status: verdict.verdict === "clean" ? "completed" : "failed",
+        output,
+        textOutput: rawText.trim(),
+        usage,
+        durationMs,
+        ...(verdict.verdict !== "clean" ? { error: verdict.description ?? "Monitor flagged an issue" } : {}),
+    };
+    if (options.runDir) {
+        result.outputPath = persistStepOutput(options.runDir, stepName, output, rawText.trim(), options.outputPath);
+    }
+    return result;
+}
+// ── Utility ──────────────────────────────────────────────────────────────────
+function parseModelSpec(spec) {
+    const slashIndex = spec.indexOf("/");
+    if (slashIndex !== -1) {
+        return { provider: spec.slice(0, slashIndex), modelId: spec.slice(slashIndex + 1) };
+    }
+    return { provider: "anthropic", modelId: spec };
+}
+/**
+ * List all discoverable monitor names for validation.
+ */
+export function availableMonitors(cwd) {
+    const searchDirs = [
+        path.join(cwd, ".pi", "monitors"),
+        path.join(os.homedir(), ".pi", "agent", "monitors"),
+    ];
+    try {
+        const bmPath = require.resolve("@davidorex/pi-behavior-monitors/package.json", { paths: [cwd] });
+        searchDirs.push(path.join(path.dirname(bmPath), "examples"));
+    }
+    catch {
+        /* not installed */
+    }
+    const seen = new Set();
+    for (const dir of searchDirs) {
+        try {
+            for (const file of fs.readdirSync(dir)) {
+                if (file.endsWith(".monitor.json")) {
+                    seen.add(file.replace(".monitor.json", ""));
+                }
+            }
+        }
+        catch {
+            /* dir doesn't exist */
+        }
+    }
+    return Array.from(seen).sort();
+}
+//# sourceMappingURL=step-monitor.js.map