@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/skills/bundled/loop.js

@@ -0,0 +1,358 @@
+/**
+ * `pugi loop` — drives a repeating prompt against the engine until a
+ * stop-condition matches.
+ *
+ * Bundled skill, batch 2 (backlog). Useful for autonomous "fix
+ * until green" or "scaffold until verified" inner loops where the
+ * operator does not want to hand-paste the same prompt repeatedly.
+ *
+ * # Flow
+ *
+ *  1. Build the prompt + optional `--until <regex>` stop condition.
+ *  2. Iterate up to `--max-iterations` (default 10, hard cap 100).
+ *  3. Each iteration calls the injected `engineInvoker` once and
+ *     captures the assistant text + tool-call summaries.
+ *  4. Concatenate the captured text and test the stop regex against
+ *     it; if it matches, exit early with `status='matched'`.
+ *  5. Enforce a USD ceiling via `--max-cost-usd` (default 2.0); when
+ *     crossed, exit early with `status='cost-cap'`.
+ *  6. Persist per-iteration progress to
+ *     `.pugi/loops/<loop-id>.jsonl` (atomic tmp + rename per write).
+ *
+ * # Why a hard iteration cap
+ *
+ * The operator can set `--max-iterations` up to 100; beyond that the
+ * skill refuses at CLI parse time. The ceiling protects against a
+ * misconfigured stop regex that never matches — at $0.02/turn typical
+ * cost, 100 iterations is still under the default USD cap, so the
+ * tighter of the two limits always wins.
+ *
+ * # Provenance
+ *
+ * Inspired by the external bundled-skills pattern (intel from
+ * leak-research memos, independent implementation TS). No upstream code reused.
+ * Multi-provider council mode inside loop is backlog; today the
+ * skill is single-engine.
+ */
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+const DEFAULT_MAX_ITERATIONS = 10;
+const HARD_MAX_ITERATIONS = 100;
+const DEFAULT_MAX_COST_USD = 2.0;
+function parseFlags(args) {
+    const flags = {
+        json: false,
+        prompt: null,
+        until: null,
+        maxIterations: DEFAULT_MAX_ITERATIONS,
+        maxCostUsd: DEFAULT_MAX_COST_USD,
+    };
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === '--json') {
+            flags.json = true;
+            continue;
+        }
+        if (arg === '--prompt') {
+            const next = args[i + 1];
+            if (next === undefined)
+                return { flags, error: '--prompt requires a value' };
+            flags.prompt = next;
+            i += 1;
+            continue;
+        }
+        if (arg === '--until') {
+            const next = args[i + 1];
+            if (next === undefined)
+                return { flags, error: '--until requires a regex' };
+            flags.until = next;
+            i += 1;
+            continue;
+        }
+        if (arg === '--max-iterations') {
+            const next = args[i + 1];
+            if (next === undefined) {
+                return { flags, error: '--max-iterations requires a value' };
+            }
+            const parsed = Number.parseInt(next, 10);
+            if (!Number.isFinite(parsed) || parsed <= 0) {
+                return { flags, error: '--max-iterations must be a positive integer' };
+            }
+            if (parsed > HARD_MAX_ITERATIONS) {
+                return {
+                    flags,
+                    error: `--max-iterations must be <= ${HARD_MAX_ITERATIONS}`,
+                };
+            }
+            flags.maxIterations = parsed;
+            i += 1;
+            continue;
+        }
+        if (arg === '--max-cost-usd') {
+            const next = args[i + 1];
+            if (next === undefined) {
+                return { flags, error: '--max-cost-usd requires a value' };
+            }
+            const parsed = Number.parseFloat(next);
+            if (!Number.isFinite(parsed) || parsed <= 0) {
+                return {
+                    flags,
+                    error: '--max-cost-usd must be a positive number (USD)',
+                };
+            }
+            flags.maxCostUsd = parsed;
+            i += 1;
+            continue;
+        }
+        if (arg === '--help' || arg === '-h') {
+            return { flags, error: 'help' };
+        }
+        return { flags, error: `unknown argument: ${arg}` };
+    }
+    return { flags, error: null };
+}
+/** Hard cap on `--until` source length — defends against ReDoS via long input. */
+const MAX_STOP_REGEX_LEN = 256;
+/**
+ * Reject patterns that contain nested unbounded quantifiers — the classic
+ * catastrophic-backtracking shape `(a+)+`, `(.+)*`, `(x*)*`, etc. Cheap
+ * heuristic: look for any `+`/`*` immediately following a `)` that itself
+ * closes a group whose body ends in another unbounded quantifier. Anything
+ * that matches is rejected outright rather than handed to the V8 regex
+ * engine where a malicious operator could pin a CPU core through the
+ * loop's iteration budget.
+ *
+ * NOT a full regex AST parser — it just blocks the two known shapes that
+ * matter. Operators with a legitimate need can pass an explicit
+ * `/pattern/flags` form after the check (the rejection still fires).
+ */
+function hasNestedUnboundedQuantifier(source) {
+    // Strip character classes so `[+*]` does not trip the heuristic.
+    const stripped = source.replace(/\[(?:\\.|[^\]\\])*\]/g, '');
+    // `(...+)+` / `(...+)*` / `(...*)*` / `(...*)+` shapes after class strip.
+    return /\([^)]*[+*][^)]*\)\s*[+*]/.test(stripped);
+}
+/**
+ * Parse the `--until` argument into a RegExp. Accepts either a raw
+ * pattern (used with the `s` flag so `.` spans newlines, friendly to
+ * multi-line assistant output) or `/pattern/flags` for explicit control.
+ *
+ * Returns `null` on length overflow (> 256 chars), nested unbounded
+ * quantifier (ReDoS shield), or any RegExp construction error. The
+ * caller surfaces "invalid_stop_regex" so the operator can fix it
+ * rather than discover a hang at iteration N.
+ *
+ * Public for test coverage.
+ */
+export function parseStopRegex(input) {
+    if (input.length === 0)
+        return null;
+    if (input.length > MAX_STOP_REGEX_LEN)
+        return null;
+    if (input.startsWith('/') && /\/[gimsuy]*$/.test(input.slice(1))) {
+        const lastSlash = input.lastIndexOf('/');
+        const source = input.slice(1, lastSlash);
+        if (hasNestedUnboundedQuantifier(source))
+            return null;
+        try {
+            return new RegExp(source, input.slice(lastSlash + 1));
+        }
+        catch {
+            return null;
+        }
+    }
+    if (hasNestedUnboundedQuantifier(input))
+        return null;
+    try {
+        return new RegExp(input, 's');
+    }
+    catch {
+        return null;
+    }
+}
+function makeLoopId(now) {
+    const iso = now.toISOString().replace(/[:.]/g, '-');
+    const suffix = Math.floor(Math.random() * 0xfffff)
+        .toString(16)
+        .padStart(5, '0');
+    return `loop-${iso}-${suffix}`;
+}
+/**
+ * Atomic JSONL append — keeps the file consistent for chokidar / tail
+ * watchers by rewriting the whole document via tmp + rename on every
+ * iteration. The watcher never sees a partial line.
+ *
+ * Public so the test suite can drive the helper directly.
+ */
+export function atomicWriteFile(targetPath, body) {
+    const parent = dirname(targetPath);
+    if (!existsSync(parent)) {
+        mkdirSync(parent, { recursive: true });
+    }
+    const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}-${Math.floor(Math.random() * 1_000_000)}`;
+    try {
+        writeFileSync(tmpPath, body, 'utf8');
+        renameSync(tmpPath, targetPath);
+    }
+    catch (err) {
+        try {
+            rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // ignore cleanup
+        }
+        throw err;
+    }
+}
+function renderHumanReport(result) {
+    const lines = [];
+    lines.push(`pugi loop — id=${result.loopId} status=${result.status}`);
+    lines.push(`iterations: ${result.iterations.length} totalCostUsd: ${result.totalCostUsd.toFixed(4)}`);
+    lines.push(`progress: ${result.progressPath}`);
+    lines.push('');
+    for (const iter of result.iterations) {
+        lines.push(` [${String(iter.iteration).padStart(3, '0')}] cost=$${iter.costUsd.toFixed(4)} (cum=$${iter.cumulativeCostUsd.toFixed(4)})${iter.stopMatched ? ' <- stop matched' : ''}`);
+    }
+    return lines.join('\n');
+}
+export async function runLoopCommand(args, ctx) {
+    const { flags, error } = parseFlags(args);
+    if (error === 'help') {
+        ctx.writeOutput({ ok: true, command: 'loop', usage: LOOP_USAGE }, LOOP_USAGE);
+        return emptyResult('help', '', 'aborted', 0);
+    }
+    if (error !== null) {
+        ctx.writeOutput({ ok: false, command: 'loop', error }, `pugi loop: ${error}`);
+        return emptyResult('args-error', '', 'aborted', 2);
+    }
+    if (flags.prompt === null || flags.prompt.trim() === '') {
+        const msg = '--prompt is required';
+        ctx.writeOutput({ ok: false, command: 'loop', error: msg }, `pugi loop: ${msg}\n\n${LOOP_USAGE}`);
+        return emptyResult('args-error', '', 'no-prompt', 2);
+    }
+    const stopRegex = flags.until !== null ? parseStopRegex(flags.until) : null;
+    if (flags.until !== null && stopRegex === null) {
+        const msg = `--until is not a valid regex: ${flags.until}`;
+        ctx.writeOutput({ ok: false, command: 'loop', error: msg }, `pugi loop: ${msg}`);
+        return emptyResult('args-error', '', 'aborted', 2);
+    }
+    const loopId = ctx.newLoopId ? ctx.newLoopId() : makeLoopId(ctx.now());
+    const progressPath = join(ctx.cwd, '.pugi', 'loops', `${loopId}.jsonl`);
+    const iterations = [];
+    let cumulative = 0;
+    let status = 'max-iterations';
+    for (let i = 1; i <= flags.maxIterations; i += 1) {
+        const startedAt = ctx.now().toISOString();
+        let engineOut;
+        try {
+            engineOut = await ctx.engineInvoker({
+                iteration: i,
+                prompt: flags.prompt,
+                transcript: iterations,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            status = 'aborted';
+            const completedAt = ctx.now().toISOString();
+            iterations.push({
+                iteration: i,
+                startedAt,
+                completedAt,
+                assistantText: `engine error: ${message}`,
+                toolCallSummary: [],
+                costUsd: 0,
+                cumulativeCostUsd: cumulative,
+                stopMatched: false,
+            });
+            persistProgress(progressPath, iterations);
+            break;
+        }
+        const completedAt = ctx.now().toISOString();
+        const stopMatched = stopRegex !== null
+            ? stopRegex.test([engineOut.assistantText, ...engineOut.toolCallSummary].join('\n'))
+            : false;
+        cumulative += engineOut.costUsd;
+        iterations.push({
+            iteration: i,
+            startedAt,
+            completedAt,
+            assistantText: engineOut.assistantText,
+            toolCallSummary: engineOut.toolCallSummary,
+            costUsd: engineOut.costUsd,
+            cumulativeCostUsd: cumulative,
+            stopMatched,
+        });
+        persistProgress(progressPath, iterations);
+        if (stopMatched) {
+            status = 'matched';
+            break;
+        }
+        if (cumulative >= flags.maxCostUsd) {
+            status = 'cost-cap';
+            break;
+        }
+    }
+    const exitCode = status === 'matched' || status === 'max-iterations'
+        ? 0
+        : 1;
+    const result = {
+        loopId,
+        status,
+        iterations,
+        totalCostUsd: cumulative,
+        progressPath,
+        exitCode,
+    };
+    ctx.writeOutput({ ok: true, command: 'loop', result }, renderHumanReport(result));
+    return result;
+}
+function persistProgress(progressPath, iterations) {
+    const body = iterations
+        .map((iter) => JSON.stringify(iter))
+        .join('\n');
+    try {
+        atomicWriteFile(progressPath, body === '' ? '' : `${body}\n`);
+    }
+    catch {
+        // The persistence path is informational; a fs failure must not
+        // bring the loop down. The operator still sees the in-memory
+        // summary on stdout / via the returned result.
+    }
+}
+function emptyResult(loopId, progressPath, status, exitCode) {
+    return {
+        loopId,
+        status,
+        iterations: [],
+        totalCostUsd: 0,
+        progressPath,
+        exitCode,
+    };
+}
+const LOOP_USAGE = [
+    'pugi loop — repeat a prompt against the engine until a stop condition.',
+    '',
+    'Usage:',
+    ' pugi loop --prompt "<text>" [--until "<regex>"]',
+    '           [--max-iterations <N>] [--max-cost-usd <USD>] [--json]',
+    '',
+    'Flags:',
+    ' --prompt <text>         The prompt sent to the engine each iteration.',
+    ' --until <regex>         Stop regex; matched against assistant + tool',
+    '                          output. Bare patterns get the `s` flag (`.`',
+    '                          spans newlines); `/pattern/flags` is explicit.',
+    ' --max-iterations <N>    Iteration ceiling (default 10, hard cap 100).',
+    ' --max-cost-usd <USD>    USD ceiling (default 2.0). EXPERIMENTAL — only',
+    '                          enforced when the engine invoker emits a',
+    '                          non-zero costUsd. The shipped stub returns 0,',
+    '                          so this cap is a no-op until the real engine',
+    '                          variant lands (backlog follow-up).',
+    ' --json                  JSON envelope instead of human text.',
+    '',
+    'Progress lands at .pugi/loops/<loop-id>.jsonl (one line per iteration,',
+    'rewritten atomically every iteration).',
+].join('\n');
+//# sourceMappingURL=loop.js.map