@mjasnikovs/pi-task 0.2.0

package/dist/task/child-runner.js

@@ -0,0 +1,157 @@
+/**
+ * Child process runner for the pi-task orchestrator.
+ *
+ * Thin wrapper layer over the unified `runChild` in `shared/child-process.ts`.
+ * Provides JSON event-stream parsing, loop detection, and context-usage tracking
+ * for phase-level child pi invocations.
+ */
+import { spawn } from 'node:child_process';
+import { getPiInvocation } from '../shared/pi-invocation.js';
+import { runChild as runChildUnified, CHILD_BASE_ARGS } from '../shared/child-process.js';
+import { LoopDetector } from './loop-detector.js';
+import { readSection, setTaskSection } from './task-file.js';
+// ─── Loop detection constants ────────────────────────────────────────────────
+// Defined here (not in phases.ts) to avoid a circular dependency:
+//   phases.ts → child-runner.ts → phases.ts
+export const LOOP_WINDOW = 20;
+export const LOOP_THRESHOLD = 5;
+export const MAX_LOOP_RESTARTS = 2; // 3 strikes total (initial attempt + 2 restarts)
+// ─── Spawn helpers ───────────────────────────────────────────────────────────
+export function childArgs(tools, prompt) {
+    // `--mode json` puts the child into the structured event stream the
+    // unified runner parses in `mode: 'json-events'`. Without it the child
+    // emits plain text, every line fails JSON.parse, finalText stays empty,
+    // and every phase fails with "X child produced no output". Was silently
+    // dropped in the 4e34f96 split-refactor; do not remove again.
+    //
+    // An empty `tools` string means "no tools at all" — emit `--no-tools`
+    // instead of `--tools ''` (which pi would reject). Used by pure-judgment
+    // phases like critique-triage that should reason only over the text we
+    // hand them, never spend time reading the repo.
+    const toolFlags = tools === '' ? ['--no-tools'] : ['--tools', tools];
+    return [...CHILD_BASE_ARGS, '--mode', 'json', ...toolFlags, prompt];
+}
+// Sentinel error thrown when the user dismisses a grill-me dialog.
+// Defined here (not in failure-classifier.ts) to avoid circular dependency.
+export const USER_CANCELLED = '__user_cancelled__';
+// ─── Core child runner (JSON event-stream mode) ─────────────────────────────
+/**
+ * Run a child pi process with JSON event-stream output, loop detection, and
+ * context-usage tracking. This is the typed convenience wrapper used by
+ * phase-level code.
+ */
+export async function runChild(cwd, tools, prompt, signal, onLine, onContextUsage, onToolCall, spawnFn) {
+    const invocation = getPiInvocation(childArgs(tools, prompt));
+    let loopHit;
+    const result = await runChildUnified(spawnFn ?? spawn, invocation, cwd, signal, {
+        mode: 'json-events',
+        onLine,
+        onContextUsage,
+        onToolCall: call => {
+            if (!onToolCall)
+                return null;
+            const hit = onToolCall(call);
+            if (hit && !loopHit) {
+                loopHit = hit;
+            }
+            return hit; // propagate to unified runner so it can kill
+        }
+    });
+    return {
+        text: result.text ?? result.stdout.trim(),
+        exitCode: result.exitCode,
+        stderr: result.stderr.trim(),
+        loopHit
+    };
+}
+/** Run a child pi and return its assistant text. Throws if exit code != 0. */
+export async function runPhaseChild(deps, name, tools, prompt) {
+    const r = await runChild(deps.cwd, tools, prompt, deps.signal, deps.onChildOutput, deps.onContextUsage, undefined, deps.spawn);
+    if (r.exitCode !== 0) {
+        throw new Error(`${name} child failed: ${r.stderr || '(no stderr)'}`);
+    }
+    if (r.text.trim().length === 0) {
+        throw new Error(`${name} child produced no output`);
+    }
+    return r.text;
+}
+function formatLoopHint(hit) {
+    const argsStr = JSON.stringify(hit.call.args);
+    return (`[SYSTEM NOTE: Your prior attempt called ${hit.call.name}(${argsStr}) `
+        + `${hit.count} times in the last ${hit.windowSize} tool calls — you appeared to be `
+        + `stuck in a loop. Avoid repeating that exact call; if you've already seen its result, `
+        + `work from memory or pick a different angle.]`);
+}
+export function prependHint(hint, prompt) {
+    return hint === null ? prompt : `${hint}\n\n${prompt}`;
+}
+async function appendLoopEvent(cwd, taskId, phase, hit, strike, outcome) {
+    const ts = new Date().toISOString();
+    const argsStr = JSON.stringify(hit.call.args);
+    const line = `- ${ts}  ${phase}  strike ${strike}/${MAX_LOOP_RESTARTS + 1}  `
+        + `${hit.call.name}(${argsStr}) ×${hit.count} in last ${hit.windowSize} calls  → ${outcome}`;
+    const existing = (await readSection(cwd, taskId, 'loop events')) ?? '';
+    const next = existing ? `${existing}\n${line}` : line;
+    await setTaskSection(cwd, taskId, 'loop events', next);
+}
+/**
+ * Run a phase child with loop detection. On a detected loop, kill and re-spawn
+ * with a hint that names the offending call. Cap at MAX_LOOP_RESTARTS restarts;
+ * the (MAX_LOOP_RESTARTS+1)th loop throws LoopExhaustedError.
+ */
+export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt) {
+    const loopHistory = [];
+    for (let strike = 0; strike <= MAX_LOOP_RESTARTS; strike++) {
+        if (deps.signal.aborted)
+            throw new Error(USER_CANCELLED);
+        const detector = new LoopDetector(LOOP_WINDOW, LOOP_THRESHOLD);
+        const hint = strike === 0 ? null : formatLoopHint(loopHistory[strike - 1]);
+        const prompt = buildPrompt(hint);
+        const r = await runChild(deps.cwd, tools, prompt, deps.signal, deps.onChildOutput, deps.onContextUsage, call => detector.record(call), deps.spawn);
+        if (deps.signal.aborted)
+            throw new Error(USER_CANCELLED);
+        if (r.loopHit) {
+            const isLastStrike = strike === MAX_LOOP_RESTARTS;
+            loopHistory.push(r.loopHit);
+            await appendLoopEvent(deps.cwd, deps.taskId, name, r.loopHit, strike + 1, isLastStrike ? 'phase failed' : 'restarted with hint');
+            if (isLastStrike)
+                throw new LoopExhaustedError(name, loopHistory);
+            continue;
+        }
+        if (r.exitCode !== 0) {
+            throw new Error(`${name} child failed: ${r.stderr || '(no stderr)'}`);
+        }
+        if (r.text.trim().length === 0) {
+            throw new Error(`${name} child produced no output`);
+        }
+        return r.text;
+    }
+    throw new LoopExhaustedError(name, loopHistory);
+}
+/**
+ * Run a child up to twice; the second attempt gets `emphasized=true` to escalate
+ * the prompt. On success, return the validator's value; on two failures, throw
+ * the caller-supplied error built from the last problem string.
+ */
+export async function runWithEmphasisRetry(deps, name, tools, build, validate, onFail) {
+    let lastProblem = 'unknown';
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const text = await runPhaseChild(deps, name, tools, build(attempt === 0 ? null : lastProblem));
+        const result = validate(text);
+        if (result.ok)
+            return result.value;
+        lastProblem = result.problem;
+    }
+    throw onFail(lastProblem);
+}
+// ─── LoopExhaustedError ──────────────────────────────────────────────────────
+export class LoopExhaustedError extends Error {
+    phase;
+    history;
+    constructor(phase, history) {
+        super(`loop detected ${history.length} times in ${phase}`);
+        this.phase = phase;
+        this.history = history;
+        this.name = 'LoopExhaustedError';
+    }
+}

package/dist/task/enrichment.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Research enrichment — extract package names and URLs from text so the
+ * orchestrator can fan out docs/URL lookups before the research phase.
+ */
+export declare function extractEnrichTargets(text: string): {
+    packages: string[];
+    urls: string[];
+    services: Array<{
+        name: string;
+        query: string;
+    }>;
+};

package/dist/task/enrichment.js

@@ -0,0 +1,82 @@
+/**
+ * Research enrichment — extract package names and URLs from text so the
+ * orchestrator can fan out docs/URL lookups before the research phase.
+ */
+const ENRICH_PKG_RE = /`((?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*)`/g;
+const ENRICH_URL_RE = /https?:\/\/[^\s)`>]+/g;
+const ENRICH_DENYLIST = new Set([
+    'bun',
+    'node',
+    'npm',
+    'pnpm',
+    'yarn',
+    'git',
+    'sh',
+    'bash',
+    'cd',
+    'ls',
+    'cat',
+    'grep',
+    'find',
+    'rm'
+]);
+const ENRICH_CAP = 3;
+const ENRICH_SERVICE_HEADER = 'EXTERNAL-DEPENDENCIES';
+const ENRICH_HEADER_LINE_RE = /^[A-Z][A-Z0-9 -]+$/;
+const ENRICH_SERVICE_BULLET_RE = /^\s*-\s+(.+?)\s{2,}(.+?)\s*$/;
+function parseServices(text) {
+    const lines = text.split('\n');
+    const startIdx = lines.findIndex(l => l.trim() === ENRICH_SERVICE_HEADER);
+    if (startIdx === -1)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed === '')
+            break;
+        // The refine model sometimes emits the section header twice in a row.
+        // A repeated EXTERNAL-DEPENDENCIES line is not a section terminator —
+        // skip it and keep reading bullets. Any *other* all-caps header still
+        // ends the section.
+        if (trimmed === ENRICH_SERVICE_HEADER)
+            continue;
+        if (ENRICH_HEADER_LINE_RE.test(trimmed))
+            break;
+        const m = line.match(ENRICH_SERVICE_BULLET_RE);
+        if (!m)
+            continue;
+        const name = m[1].trim();
+        // Dedupe by name (case-insensitive); the model also duplicates bullets.
+        // Keep the first occurrence's query and count uniques against the cap.
+        const key = name.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ name, query: m[2].trim() });
+        if (out.length >= ENRICH_CAP)
+            break;
+    }
+    return out;
+}
+export function extractEnrichTargets(text) {
+    const pkgs = new Set();
+    for (const m of text.matchAll(ENRICH_PKG_RE)) {
+        const t = m[1];
+        if (ENRICH_DENYLIST.has(t))
+            continue;
+        pkgs.add(t);
+        if (pkgs.size >= ENRICH_CAP)
+            break;
+    }
+    const urls = new Set();
+    for (const m of text.matchAll(ENRICH_URL_RE)) {
+        const u = m[0].replace(/[.,;:!?]+$/, '');
+        urls.add(u);
+        if (urls.size >= ENRICH_CAP)
+            break;
+    }
+    const services = parseServices(text);
+    return { packages: [...pkgs], urls: [...urls], services };
+}

package/dist/task/failure-classifier.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Failure classification — map runtime errors to task state transitions,
+ * widget flash messages, and user notifications.
+ */
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+export type NotifyLevel = 'info' | 'warning' | 'error';
+export interface FailureClass {
+    state: 'failed' | 'cancelled';
+    reason?: string;
+    flash?: string;
+    notify: string;
+    level: NotifyLevel;
+}
+export declare function classifyFailure(err: unknown, aborted: boolean): FailureClass;
+export declare function handleFailure(err: unknown, ctx: ExtensionCommandContext, cwd: string, id: string, aborted: boolean): Promise<void>;

package/dist/task/failure-classifier.js

@@ -0,0 +1,63 @@
+/**
+ * Failure classification — map runtime errors to task state transitions,
+ * widget flash messages, and user notifications.
+ */
+import { updateTaskFrontMatter } from './task-file.js';
+import { flashTerminalWidget } from './widget.js';
+import { LoopExhaustedError, USER_CANCELLED } from './child-runner.js';
+// ─── Classifier ──────────────────────────────────────────────────────────────
+export function classifyFailure(err, aborted) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (aborted || msg === USER_CANCELLED) {
+        return { state: 'cancelled', notify: 'cancelled.', level: 'warning' };
+    }
+    if (err instanceof LoopExhaustedError) {
+        return {
+            state: 'failed',
+            reason: `loop detected ${err.history.length}× in ${err.phase}`,
+            flash: 'loop_detected',
+            notify: `failed: ${err.phase} loop detected ${err.history.length}×. Resume to retry.`,
+            level: 'error'
+        };
+    }
+    if (msg === 'no_verify_block') {
+        return {
+            state: 'failed',
+            reason: 'no_verify_block',
+            flash: 'no_verify_block',
+            notify: 'failed: spec has no VERIFY block. Resume to edit and try again.',
+            level: 'error'
+        };
+    }
+    if (msg.startsWith('compose_invalid')) {
+        return {
+            state: 'failed',
+            reason: msg.slice(0, 200),
+            flash: 'compose_invalid',
+            notify: `failed: compose produced malformed spec (${msg.replace(/^compose_invalid:\s*/, '')}). Resume to retry.`,
+            level: 'error'
+        };
+    }
+    if (/ECONNREFUSED|fetch failed|connect/i.test(msg)) {
+        return {
+            state: 'failed',
+            reason: `model_unreachable: ${msg.slice(0, 120)}`,
+            flash: 'model_unreachable',
+            notify: 'failed: model unreachable.',
+            level: 'error'
+        };
+    }
+    return {
+        state: 'failed',
+        reason: msg.slice(0, 200),
+        flash: msg.slice(0, 80),
+        notify: `failed: ${msg.slice(0, 120)}`,
+        level: 'error'
+    };
+}
+export async function handleFailure(err, ctx, cwd, id, aborted) {
+    const c = classifyFailure(err, aborted);
+    await updateTaskFrontMatter(cwd, id, { state: c.state, reason: c.reason });
+    flashTerminalWidget(ctx, c.state, id, c.flash);
+    ctx.ui.notify(`${id} ${c.notify}`, c.level);
+}

package/dist/task/file-inventory.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Project file inventory — runs `git ls-files` once per /task run so research
+ * workers can skip their own discovery loops and jump straight to targeted
+ * read/grep on known paths. Returns '' on failure (non-git repo, git missing,
+ * timeout) so callers can fall back to the pre-inventory behavior.
+ */
+/** Cap output to maxLines real (non-blank) paths; tag truncation when cut. */
+export declare function capInventory(raw: string, maxLines?: number): string;
+export declare function getFileInventory(cwd: string, signal?: AbortSignal, maxLines?: number): Promise<string>;

package/dist/task/file-inventory.js

@@ -0,0 +1,44 @@
+/**
+ * Project file inventory — runs `git ls-files` once per /task run so research
+ * workers can skip their own discovery loops and jump straight to targeted
+ * read/grep on known paths. Returns '' on failure (non-git repo, git missing,
+ * timeout) so callers can fall back to the pre-inventory behavior.
+ */
+import { spawn } from 'node:child_process';
+const DEFAULT_MAX_LINES = 2000;
+function runGitLsFiles(cwd, signal) {
+    return new Promise(resolve => {
+        let stdout = '';
+        let proc;
+        try {
+            proc = spawn('git', ['ls-files'], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+        }
+        catch {
+            resolve('');
+            return;
+        }
+        proc.stdout?.on('data', (d) => {
+            stdout += d.toString();
+        });
+        proc.on('error', () => resolve(''));
+        proc.on('close', code => resolve(code === 0 ? stdout : ''));
+        signal?.addEventListener('abort', () => {
+            if (!proc.killed)
+                proc.kill('SIGTERM');
+        });
+    });
+}
+/** Cap output to maxLines real (non-blank) paths; tag truncation when cut. */
+export function capInventory(raw, maxLines = DEFAULT_MAX_LINES) {
+    const lines = raw.split('\n').filter(l => l.trim().length > 0);
+    if (lines.length <= maxLines)
+        return lines.join('\n');
+    const shown = lines.slice(0, maxLines);
+    return `${shown.join('\n')}\n(truncated: ${lines.length - maxLines} more files)`;
+}
+export async function getFileInventory(cwd, signal, maxLines = DEFAULT_MAX_LINES) {
+    const raw = await runGitLsFiles(cwd, signal);
+    if (!raw)
+        return '';
+    return capInventory(raw, maxLines);
+}

package/dist/task/loop-detector.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pure-logic loop detector for pi-task sub-agent phases.
+ *
+ * Watches a ring buffer of recent tool-call keys. When the same
+ * `(toolName, stable-stringified args)` key appears `threshold` times
+ * within the last `window` events, returns a LoopHit so the caller can
+ * kill the child and re-spawn with a hint.
+ *
+ * No I/O. No imports from index.ts. Trivially unit-testable.
+ */
+export interface ToolCall {
+    name: string;
+    args: unknown;
+}
+export interface LoopHit {
+    call: ToolCall;
+    count: number;
+    windowSize: number;
+}
+/**
+ * JSON.stringify with sorted object keys so {a:1,b:2} and {b:2,a:1} hash equal.
+ * Arrays preserve their order (positional). undefined / primitives passthrough.
+ */
+export declare function stableStringify(value: unknown): string;
+export declare class LoopDetector {
+    private readonly window;
+    private readonly threshold;
+    private readonly buf;
+    constructor(window?: number, threshold?: number);
+    /** Record a tool call. Returns LoopHit if the threshold is breached, else null. */
+    record(call: ToolCall): LoopHit | null;
+}

package/dist/task/loop-detector.js

@@ -0,0 +1,46 @@
+/**
+ * Pure-logic loop detector for pi-task sub-agent phases.
+ *
+ * Watches a ring buffer of recent tool-call keys. When the same
+ * `(toolName, stable-stringified args)` key appears `threshold` times
+ * within the last `window` events, returns a LoopHit so the caller can
+ * kill the child and re-spawn with a hint.
+ *
+ * No I/O. No imports from index.ts. Trivially unit-testable.
+ */
+/**
+ * JSON.stringify with sorted object keys so {a:1,b:2} and {b:2,a:1} hash equal.
+ * Arrays preserve their order (positional). undefined / primitives passthrough.
+ */
+export function stableStringify(value) {
+    return JSON.stringify(value, (_key, v) => {
+        if (v === null || typeof v !== 'object' || Array.isArray(v))
+            return v;
+        const sorted = {};
+        for (const k of Object.keys(v).sort()) {
+            sorted[k] = v[k];
+        }
+        return sorted;
+    });
+}
+export class LoopDetector {
+    window;
+    threshold;
+    buf = [];
+    constructor(window = 20, threshold = 5) {
+        this.window = window;
+        this.threshold = threshold;
+    }
+    /** Record a tool call. Returns LoopHit if the threshold is breached, else null. */
+    record(call) {
+        const key = `${call.name}\x00${stableStringify(call.args)}`;
+        this.buf.push(key);
+        if (this.buf.length > this.window)
+            this.buf.shift();
+        let count = 0;
+        for (const k of this.buf)
+            if (k === key)
+                count++;
+        return count >= this.threshold ? { call, count, windowSize: this.buf.length } : null;
+    }
+}

package/dist/task/orchestrator.d.ts

@@ -0,0 +1,54 @@
+/**
+ * pi-task — deterministic spec orchestrator for local models.
+ *
+ * Drives the prompt through five phases — refine → research → grill → compose →
+ * critique — then hands the final spec to the main pi thread via
+ * pi.sendUserMessage so the user can keep working in the main conversation.
+ *
+ * Slash commands:
+ *   /task <prompt>         start a new task
+ *   /task-list             open the task list in an editor dialog
+ *   /task-resume [id]      resume the most recent (or named) non-completed task
+ *   /task-cancel           cancel the running task (soft-terminal — still resumable)
+ *
+ * The orchestrator persists after every phase boundary to
+ * <cwd>/.pi-tasks/TASK_NNNN.md. All user interaction during phases runs through
+ * ctx.ui dialogs; the main pi chat only receives the final spec.
+ */
+import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import { type WidgetState } from './widget.js';
+import type { SpawnFn } from '../shared/child-process.js';
+/** Encapsulates the full lifecycle of a single pi-task run. */
+export declare class TaskRunner {
+    private readonly _ctx;
+    private readonly _cwd;
+    private readonly _rawPrompt;
+    private readonly _resumeId;
+    private readonly _sendSpec;
+    private readonly _abort;
+    private readonly _startedAt;
+    private readonly _widgetState;
+    private _stopWidget;
+    private readonly _deps;
+    private readonly _pc;
+    /**
+     * Per-phase wall-clock durations collected during the run. Written to the
+     * `## phase timings` section on successful completion so we can spot
+     * regressions and target future speed work. Each top-level entry is a
+     * phase (refine/research/grill/compose/critique); children are optional
+     * sub-step splits the phase chose to record via deps.recordSubStep.
+     */
+    private readonly _timings;
+    private _currentPhaseChildren;
+    constructor(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, resumeId?: string, sendSpec?: (spec: string) => Promise<void>, spawnFn?: SpawnFn);
+    get taskId(): string;
+    get signal(): AbortSignal;
+    /** Return the current widget state, or null if not started. */
+    status(): WidgetState | null;
+    /** Cancel the running task by aborting the signal. */
+    cancel(): void;
+    /** Execute the full task lifecycle. */
+    run(): Promise<void>;
+    private _deliverSpec;
+}
+export declare function registerTask(pi: ExtensionAPI): void;