@mjasnikovs/pi-task 0.7.2 → 0.7.3

package/README.md

@@ -2,7 +2,7 @@
 
 <img src="./assets/pipeline.svg" alt="pi-task pipeline: a /task request runs through refine, research, grill, compose and critique, then the final spec is delivered to your main pi session in the same chat. Every phase boundary is persisted to .pi-tasks/TASK_NNNN.md, so the task is crash-safe and resumable." width="820"/>
 
-# 🧩 pi-task
+# <img src="./assets/pi-logo.svg" alt="" height="30" align="top"/> pi-task
 
 **Deterministic spec-orchestration for local models — with bundled web, docs, fetch, and worker sub-agent tools.**
 

package/assets/pi-logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 180" width="180" height="180" role="img" aria-label="pi-task logo">
+  <rect width="180" height="180" rx="38" fill="#1e1e2e"/>
+  <text x="90" y="130" font-family="Georgia, serif" font-size="100" text-anchor="middle" fill="#cba6f7">π</text>
+</svg>

package/dist/shared/leaked-tool-call.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Detect tool calls that leaked into a child's assistant *text* instead of
+ * being executed.
+ *
+ * Background: every child pi runs under `--mode json`; pi-task only ever treats
+ * a structured `tool_execution_start` event as a tool call (see
+ * shared/child-process.ts). When a local model emits a call in a markup dialect
+ * pi's harness doesn't recognise — e.g.
+ *
+ *     <tool_call>
+ *     <function=bash>
+ *     <parameter=command>grep …</parameter>
+ *     </function>
+ *     </tool_call>
+ *
+ * pi passes the raw markup through as ordinary assistant text. The command never
+ * runs, no event fires, and pi-task's guards (loop detector, widget) never see
+ * it. The phase then "passes" on its only gates (non-empty text + exit 0) and
+ * the unexecuted call flows downstream — a silently skipped beat.
+ *
+ * This is fundamentally an upstream mismatch (model output format ↔ pi's parser)
+ * that pi-task cannot fix. What it CAN do is notice the leaked markup and refuse
+ * to accept the turn, so the skip becomes visible instead of silent.
+ */
+export declare const MAX_LEAK_RETRIES = 2;
+/**
+ * Return the offending marker string if `text` contains a leaked tool call, or
+ * null if it looks clean. The marker is suitable for logging and for naming the
+ * problem back to the model in a re-prompt hint.
+ */
+export declare function detectLeakedToolCall(text: string): string | null;
+/**
+ * A correction hint to prepend to a re-spawn after a leak, naming the offending
+ * markup so the model stops repeating that exact mistake.
+ */
+export declare function leakedToolCallHint(marker: string): string;

package/dist/shared/leaked-tool-call.js

@@ -0,0 +1,60 @@
+/**
+ * Detect tool calls that leaked into a child's assistant *text* instead of
+ * being executed.
+ *
+ * Background: every child pi runs under `--mode json`; pi-task only ever treats
+ * a structured `tool_execution_start` event as a tool call (see
+ * shared/child-process.ts). When a local model emits a call in a markup dialect
+ * pi's harness doesn't recognise — e.g.
+ *
+ *     <tool_call>
+ *     <function=bash>
+ *     <parameter=command>grep …</parameter>
+ *     </function>
+ *     </tool_call>
+ *
+ * pi passes the raw markup through as ordinary assistant text. The command never
+ * runs, no event fires, and pi-task's guards (loop detector, widget) never see
+ * it. The phase then "passes" on its only gates (non-empty text + exit 0) and
+ * the unexecuted call flows downstream — a silently skipped beat.
+ *
+ * This is fundamentally an upstream mismatch (model output format ↔ pi's parser)
+ * that pi-task cannot fix. What it CAN do is notice the leaked markup and refuse
+ * to accept the turn, so the skip becomes visible instead of silent.
+ */
+// A child that wrote a tool call as plain text (wrong dialect, never executed)
+// gets re-prompted with a correction hint up to this many times before the
+// caller gives up. Mirrors MAX_LOOP_RESTARTS: 3 attempts total.
+export const MAX_LEAK_RETRIES = 2;
+// The Hermes-style wrapper a leaked call is most often wrapped in. pi-task never
+// legitimately emits this tag, so its presence alone is a confident signal.
+const TOOL_CALL_WRAPPER = /<tool_call\b[^>]*>/i;
+// The "XML function call" dialect: <function=name> … <parameter=key>. Either tag
+// alone is too weak (a stray "<function=x>" can appear in prose or source), so we
+// require the structural pair before flagging it.
+const FUNCTION_TAG = /<function=[\w.-]+\s*>/i;
+const PARAMETER_TAG = /<parameter=[\w.-]+\s*>/i;
+/**
+ * Return the offending marker string if `text` contains a leaked tool call, or
+ * null if it looks clean. The marker is suitable for logging and for naming the
+ * problem back to the model in a re-prompt hint.
+ */
+export function detectLeakedToolCall(text) {
+    const wrapper = TOOL_CALL_WRAPPER.exec(text);
+    if (wrapper)
+        return wrapper[0];
+    const fn = FUNCTION_TAG.exec(text);
+    if (fn && PARAMETER_TAG.test(text))
+        return fn[0];
+    return null;
+}
+/**
+ * A correction hint to prepend to a re-spawn after a leak, naming the offending
+ * markup so the model stops repeating that exact mistake.
+ */
+export function leakedToolCallHint(marker) {
+    return (`[SYSTEM NOTE: Your previous turn wrote a tool call as plain text (\`${marker}\`) `
+        + `instead of invoking the tool — so it never ran and you proceeded without its result. `
+        + `Invoke tools through the native tool-calling mechanism; never type `
+        + `<tool_call>/<function=…>/<parameter=…> markup into your answer.]`);
+}

package/dist/task/child-runner.d.ts

@@ -14,6 +14,8 @@ export interface PhaseRunResult {
     exitCode: number;
     stderr: string;
     loopHit?: LoopHit;
+    /** Set when the assistant text contains an unexecuted, leaked tool call. */
+    leakedToolCall?: string;
 }
 export declare function childArgs(tools: string, prompt: string): string[];
 export declare const USER_CANCELLED = "__user_cancelled__";
@@ -38,7 +40,13 @@ interface PhaseDeps {
     spawn?: SpawnFn;
 }
 export type { PhaseDeps };
-/** Run a child pi and return its assistant text. Throws if exit code != 0. */
+/**
+ * Run a child pi and return its assistant text. Throws if exit code != 0.
+ *
+ * If the child leaks a tool call as plain text (wrong dialect — never executed),
+ * re-prompt with a correction hint up to MAX_LEAK_RETRIES times; if it keeps
+ * leaking, throw LeakedToolCallError rather than returning the unexecuted call.
+ */
 export declare function runPhaseChild(deps: PhaseDeps, name: string, tools: string, prompt: string): Promise<string>;
 export declare function prependHint(hint: string | null, prompt: string): string;
 /**
@@ -64,3 +72,13 @@ export declare class LoopExhaustedError extends Error {
     readonly history: LoopHit[];
     constructor(phase: string, history: LoopHit[]);
 }
+/**
+ * Thrown when a phase child repeatedly wrote a tool call as plain text (a markup
+ * dialect pi's harness didn't parse) instead of invoking it. The call never ran,
+ * so the phase output is untrustworthy — fail loudly rather than check it off.
+ */
+export declare class LeakedToolCallError extends Error {
+    readonly phase: string;
+    readonly marker: string;
+    constructor(phase: string, marker: string);
+}

package/dist/task/child-runner.js

@@ -9,6 +9,7 @@ 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 { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
 import { readSection, setTaskSection } from './task-file.js';
 // ─── Loop detection constants ────────────────────────────────────────────────
 // Defined here (not in phases.ts) to avoid a circular dependency:
@@ -57,28 +58,52 @@ export async function runChild(cwd, tools, prompt, signal, onLine, onContextUsag
             return hit; // propagate to unified runner so it can kill
         }
     });
+    // Use `||` (not `??`) so an empty string from json-events mode falls
+    // back to raw stdout. Without this, a child that exits 0 but emits no
+    // assistant text (e.g. model API error swallowed in json mode) always
+    // fails with the unhelpful "X child produced no output" — the raw
+    // stdout/stderr that might contain the real error is discarded.
+    const text = result.text || result.stdout.trim();
     return {
-        // Use `||` (not `??`) so an empty string from json-events mode falls
-        // back to raw stdout. Without this, a child that exits 0 but emits no
-        // assistant text (e.g. model API error swallowed in json mode) always
-        // fails with the unhelpful "X child produced no output" — the raw
-        // stdout/stderr that might contain the real error is discarded.
-        text: result.text || result.stdout.trim(),
+        text,
         exitCode: result.exitCode,
         stderr: result.stderr.trim(),
-        loopHit
+        loopHit,
+        // A tool call the model wrote as text (wrong dialect) never executed and
+        // sailed past the structured-event guards above; flag it so the wrappers
+        // can re-prompt instead of accepting the unexecuted call. Only meaningful
+        // when the run otherwise succeeded — a loop kill truncates text mid-stream.
+        leakedToolCall: loopHit ? undefined : (detectLeakedToolCall(text) ?? undefined)
     };
 }
-/** Run a child pi and return its assistant text. Throws if exit code != 0. */
+/**
+ * Run a child pi and return its assistant text. Throws if exit code != 0.
+ *
+ * If the child leaks a tool call as plain text (wrong dialect — never executed),
+ * re-prompt with a correction hint up to MAX_LEAK_RETRIES times; if it keeps
+ * leaking, throw LeakedToolCallError rather than returning the unexecuted call.
+ */
 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${r.stderr ? ' — stderr: ' + r.stderr : ''}`);
+    let hint = null;
+    for (let attempt = 0; attempt <= MAX_LEAK_RETRIES; attempt++) {
+        const r = await runChild(deps.cwd, tools, prependHint(hint, 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${r.stderr ? ' — stderr: ' + r.stderr : ''}`);
+        }
+        if (r.leakedToolCall) {
+            if (attempt === MAX_LEAK_RETRIES) {
+                throw new LeakedToolCallError(name, r.leakedToolCall);
+            }
+            hint = leakedToolCallHint(r.leakedToolCall);
+            continue;
+        }
+        return r.text;
     }
-    return r.text;
+    // Unreachable: the loop returns clean text or throws on the final leak.
+    throw new LeakedToolCallError(name, '(unknown)');
 }
 function formatLoopHint(hit) {
     const argsStr = JSON.stringify(hit.call.args);
@@ -106,12 +131,13 @@ async function appendLoopEvent(cwd, taskId, phase, hit, strike, outcome) {
  */
 export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt) {
     const loopHistory = [];
+    // Carries the correction hint (loop OR leaked-tool-call) into the next strike.
+    let nextHint = null;
     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 prompt = buildPrompt(nextHint);
         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);
@@ -121,6 +147,7 @@ export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt) {
             await appendLoopEvent(deps.cwd, deps.taskId, name, r.loopHit, strike + 1, isLastStrike ? 'phase failed' : 'restarted with hint');
             if (isLastStrike)
                 throw new LoopExhaustedError(name, loopHistory);
+            nextHint = formatLoopHint(r.loopHit);
             continue;
         }
         if (r.exitCode !== 0) {
@@ -129,6 +156,13 @@ export async function runPhaseWithLoopGuard(deps, name, tools, buildPrompt) {
         if (r.text.trim().length === 0) {
             throw new Error(`${name} child produced no output${r.stderr ? ' — stderr: ' + r.stderr : ''}`);
         }
+        if (r.leakedToolCall) {
+            if (strike === MAX_LOOP_RESTARTS) {
+                throw new LeakedToolCallError(name, r.leakedToolCall);
+            }
+            nextHint = leakedToolCallHint(r.leakedToolCall);
+            continue;
+        }
         return r.text;
     }
     throw new LoopExhaustedError(name, loopHistory);
@@ -160,3 +194,20 @@ export class LoopExhaustedError extends Error {
         this.name = 'LoopExhaustedError';
     }
 }
+// ─── LeakedToolCallError ─────────────────────────────────────────────────────
+/**
+ * Thrown when a phase child repeatedly wrote a tool call as plain text (a markup
+ * dialect pi's harness didn't parse) instead of invoking it. The call never ran,
+ * so the phase output is untrustworthy — fail loudly rather than check it off.
+ */
+export class LeakedToolCallError extends Error {
+    phase;
+    marker;
+    constructor(phase, marker) {
+        super(`${phase} child wrote a tool call as text instead of invoking it `
+            + `(${marker.trim()}) — it never ran`);
+        this.phase = phase;
+        this.marker = marker;
+        this.name = 'LeakedToolCallError';
+    }
+}

package/dist/task/failure-classifier.js

@@ -4,7 +4,7 @@
  */
 import { updateTaskFrontMatter } from './task-file.js';
 import { flashTerminalWidget } from './widget.js';
-import { LoopExhaustedError, USER_CANCELLED } from './child-runner.js';
+import { LoopExhaustedError, LeakedToolCallError, USER_CANCELLED } from './child-runner.js';
 // ─── Classifier ──────────────────────────────────────────────────────────────
 export function classifyFailure(err, aborted) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -20,6 +20,15 @@ export function classifyFailure(err, aborted) {
             level: 'error'
         };
     }
+    if (err instanceof LeakedToolCallError) {
+        return {
+            state: 'failed',
+            reason: `leaked tool call in ${err.phase}: ${err.marker.trim()}`,
+            flash: 'leaked_tool_call',
+            notify: `failed: ${err.phase} wrote a tool call as text instead of running it — it never executed. Resume to retry.`,
+            level: 'error'
+        };
+    }
     if (msg === 'no_verify_block') {
         return {
             state: 'failed',

package/dist/task/phases.js

@@ -233,6 +233,10 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
         if (result.text.trim().length === 0) {
             throw new Error(`Research ${name} worker produced no output`);
         }
+        if (result.leakedToolCall) {
+            throw new Error(`Research ${name} worker wrote a tool call as text instead of invoking it `
+                + `(${result.leakedToolCall.trim()}) — it never ran`);
+        }
     }
     return `FILES\n${files.text}\n\nAPIS\n${apis.text}\n\nCONTEXT\n${context.text}\n\nTOOLING\n${tooling.text}`;
 }

package/dist/workers/pi-worker-core.d.ts

@@ -24,5 +24,11 @@ export interface RunWorkerResult {
      * elapsed when the child never produced output.
      */
     workMs: number;
+    /**
+     * Set when the worker exhausted its re-prompts still leaking a tool call as
+     * text (wrong dialect, never executed). The caller must treat this as a
+     * failure rather than trusting the returned text.
+     */
+    leakedToolCall?: string;
 }
 export declare function runWorker(input: RunWorkerInput): Promise<RunWorkerResult>;

package/dist/workers/pi-worker-core.js

@@ -1,6 +1,7 @@
 import { getPiInvocation } from '../shared/pi-invocation.js';
 import { CHILD_BASE_ARGS, runChildDefault } from '../shared/child-process.js';
 import { LoopDetector } from '../task/loop-detector.js';
+import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../shared/leaked-tool-call.js';
 // `--mode json` makes pi emit structured events as they happen instead of
 // buffering the assistant text and flushing on exit. That matters for the
 // wait/work timing split: in text mode the first stdout chunk only arrives at
@@ -11,25 +12,39 @@ import { LoopDetector } from '../task/loop-detector.js';
 const DEFAULT_TOOLS = 'read,grep,find,ls';
 export async function runWorker(input) {
     const tools = input.tools ?? DEFAULT_TOOLS;
-    const childArgs = [...CHILD_BASE_ARGS, '--mode', 'json', '--tools', tools];
-    const invocation = getPiInvocation([...childArgs, input.prompt]);
-    const tStart = Date.now();
-    let tFirstByte = null;
-    const loopDetector = new LoopDetector(20, 5);
-    const result = await runChildDefault(invocation, input.cwd, input.signal, {
-        mode: 'json-events',
-        onFirstByte: () => (tFirstByte = Date.now()),
-        onToolCall: call => loopDetector.record(call)
-    }, input.spawn);
-    const tEnd = Date.now();
-    const waitMs = tFirstByte === null ? tEnd - tStart : tFirstByte - tStart;
-    const workMs = tFirstByte === null ? 0 : tEnd - tFirstByte;
-    return {
-        text: result.text ?? '',
-        exitCode: result.exitCode,
-        stderr: result.stderr.trim(),
-        aborted: result.aborted,
-        waitMs,
-        workMs
-    };
+    const baseArgs = [...CHILD_BASE_ARGS, '--mode', 'json', '--tools', tools];
+    let hint = null;
+    for (let attempt = 0;; attempt++) {
+        const prompt = hint === null ? input.prompt : `${hint}\n\n${input.prompt}`;
+        const invocation = getPiInvocation([...baseArgs, prompt]);
+        const tStart = Date.now();
+        let tFirstByte = null;
+        const loopDetector = new LoopDetector(20, 5);
+        const result = await runChildDefault(invocation, input.cwd, input.signal, {
+            mode: 'json-events',
+            onFirstByte: () => (tFirstByte = Date.now()),
+            onToolCall: call => loopDetector.record(call)
+        }, input.spawn);
+        const tEnd = Date.now();
+        const waitMs = tFirstByte === null ? tEnd - tStart : tFirstByte - tStart;
+        const workMs = tFirstByte === null ? 0 : tEnd - tFirstByte;
+        const text = result.text ?? '';
+        // Only treat output as a leak on a clean, complete run — a non-zero exit
+        // or abort yields partial text the caller already handles, and detecting
+        // there would just mislabel the real failure.
+        const leaked = result.exitCode === 0 && !result.aborted ? detectLeakedToolCall(text) : null;
+        if (leaked && attempt < MAX_LEAK_RETRIES) {
+            hint = leakedToolCallHint(leaked);
+            continue;
+        }
+        return {
+            text,
+            exitCode: result.exitCode,
+            stderr: result.stderr.trim(),
+            aborted: result.aborted,
+            waitMs,
+            workMs,
+            ...(leaked ? { leakedToolCall: leaked } : {})
+        };
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.7.2",
+    "version": "0.7.3",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",