@mjasnikovs/pi-task 0.13.6 → 0.13.8

package/dist/shared/child-process.d.ts

@@ -60,6 +60,33 @@ export interface RunChildJsonEventsOptions {
     onFirstByte?: () => void;
 }
 export type RunChildOptions = RunChildTextOptions | RunChildJsonEventsOptions;
+/**
+ * Parses a child's `--mode json` event stream into assistant text plus side
+ * effects (caller callbacks, loop-kill). It holds the cross-chunk line buffer
+ * and the text-assembly state, so event interpretation is independent of the
+ * spawn/kill machinery in runChild — and therefore unit-testable without a real
+ * child: construct one, `feed()` raw lines, assert on `text` / the callbacks /
+ * the onLoopKill signal.
+ */
+export declare class JsonEventSink {
+    private readonly opts;
+    /** Invoked when onToolCall reports a loop hit — runChild kills the child. */
+    private readonly onLoopKill;
+    /** Final assistant text from the agent_end event, if one arrived. */
+    finalText: string;
+    private textDeltaAccum;
+    private buf;
+    constructor(opts: RunChildJsonEventsOptions, 
+    /** Invoked when onToolCall reports a loop hit — runChild kills the child. */
+    onLoopKill: () => void);
+    /** Feed a raw stdout chunk: parse every complete line, buffer the partial tail. */
+    feed(chunk: string): void;
+    /** Flush a trailing event that wasn't newline-terminated (call on close). */
+    flush(): void;
+    /** Extracted assistant text: the agent_end text if present, else the deltas. */
+    get text(): string;
+    private handleEvent;
+}
 export declare function runChild(spawn: SpawnFn, invocation: {
     command: string;
     args: ReadonlyArray<string>;

package/dist/shared/child-process.js

@@ -10,31 +10,162 @@ export const CHILD_BASE_ARGS = [
     '--no-context-files',
     '--no-session'
 ];
+// ─── JSON event-stream sink ──────────────────────────────────────────────────
+/**
+ * Parses a child's `--mode json` event stream into assistant text plus side
+ * effects (caller callbacks, loop-kill). It holds the cross-chunk line buffer
+ * and the text-assembly state, so event interpretation is independent of the
+ * spawn/kill machinery in runChild — and therefore unit-testable without a real
+ * child: construct one, `feed()` raw lines, assert on `text` / the callbacks /
+ * the onLoopKill signal.
+ */
+export class JsonEventSink {
+    opts;
+    onLoopKill;
+    /** Final assistant text from the agent_end event, if one arrived. */
+    finalText = '';
+    textDeltaAccum = '';
+    // json-events lines can split across data chunks; this holds the trailing
+    // partial line between feeds so events spanning a boundary still parse. We
+    // deliberately do NOT accumulate the full raw stream: a long-running child
+    // emits hundreds of MB of events and buffering it would overflow V8's max
+    // string length (≈512MB). We keep only the parsed text.
+    buf = '';
+    constructor(opts, 
+    /** Invoked when onToolCall reports a loop hit — runChild kills the child. */
+    onLoopKill) {
+        this.opts = opts;
+        this.onLoopKill = onLoopKill;
+    }
+    /** Feed a raw stdout chunk: parse every complete line, buffer the partial tail. */
+    feed(chunk) {
+        this.buf += chunk;
+        let nl;
+        while ((nl = this.buf.indexOf('\n')) !== -1) {
+            const line = this.buf.slice(0, nl).trim();
+            this.buf = this.buf.slice(nl + 1);
+            if (line.length === 0)
+                continue;
+            try {
+                const evt = JSON.parse(line);
+                if (evt && typeof evt === 'object')
+                    this.handleEvent(evt);
+            }
+            catch {
+                // Non-JSON line (startup banner, etc.) — ignore.
+            }
+        }
+    }
+    /** Flush a trailing event that wasn't newline-terminated (call on close). */
+    flush() {
+        if (this.buf.trim().length > 0)
+            this.feed('\n');
+        this.buf = '';
+    }
+    /** Extracted assistant text: the agent_end text if present, else the deltas. */
+    get text() {
+        return (this.finalText || this.textDeltaAccum).trim();
+    }
+    handleEvent(evt) {
+        const opts = this.opts;
+        const t = typeof evt.type === 'string' ? evt.type : '';
+        if (t === 'context_usage' && opts.onContextUsage) {
+            const tokens = Number(evt.tokens ?? 0);
+            const contextWindow = Number(evt.contextWindow ?? 0);
+            const percent = Number(evt.percent ?? 0);
+            if (tokens > 0 || contextWindow > 0) {
+                opts.onContextUsage({ tokens, contextWindow, percent });
+            }
+            return;
+        }
+        if (t === 'message_end' && opts.onContextUsage) {
+            const msg = evt.message;
+            if (msg?.role === 'assistant') {
+                const usage = msg.usage;
+                if (usage) {
+                    const tokens = Number(usage.input ?? 0)
+                        + Number(usage.cacheRead ?? 0)
+                        + Number(usage.cacheWrite ?? 0)
+                        + Number(usage.output ?? 0);
+                    if (tokens > 0) {
+                        opts.onContextUsage({ tokens, contextWindow: 0, percent: 0 });
+                    }
+                }
+            }
+            return;
+        }
+        if (t === 'agent_end' && Array.isArray(evt.messages)) {
+            for (let i = evt.messages.length - 1; i >= 0; i--) {
+                const m = evt.messages[i];
+                if (m && m.role === 'assistant' && Array.isArray(m.content)) {
+                    const texts = [];
+                    for (const c of m.content) {
+                        if (c?.type === 'text' && typeof c.text === 'string') {
+                            texts.push(c.text);
+                        }
+                    }
+                    if (texts.length > 0) {
+                        this.finalText = texts.join('');
+                        break;
+                    }
+                }
+            }
+            return;
+        }
+        if (t === 'message_update') {
+            const ame = evt.assistantMessageEvent;
+            const ameType = ame && typeof ame.type === 'string' ? ame.type : '';
+            if (ameType === 'text_start') {
+                this.textDeltaAccum = '';
+                if (opts.onLine)
+                    opts.onLine('writing answer…');
+            }
+            else if (ameType === 'text_delta' && typeof ame.delta === 'string') {
+                this.textDeltaAccum += ame.delta;
+            }
+            else if (ameType === 'thinking_start' && opts.onLine) {
+                opts.onLine('thinking…');
+            }
+            return;
+        }
+        if (t === 'tool_execution_start') {
+            const tn = typeof evt.toolName === 'string' ? evt.toolName : 'tool';
+            if (opts.onLine) {
+                const detail = summarizeToolArgs(tn, evt.args);
+                opts.onLine(detail ? `${tn}: ${detail}` : tn);
+            }
+            if (opts.onToolCall) {
+                const hit = opts.onToolCall({ name: tn, args: evt.args });
+                if (hit)
+                    this.onLoopKill();
+            }
+        }
+    }
+}
 // ─── Unified runChild ────────────────────────────────────────────────────────
 export function runChild(spawn, invocation, cwd, signal, opts) {
     return new Promise(resolve => {
         let stdout = '';
         let stderr = '';
         let aborted = false;
-        const isJsonEvents = opts?.mode === 'json-events';
         const discardStdout = opts?.mode === 'text' && opts.discardStdout === true;
-        // State for json-events mode
-        let finalText = '';
-        let textDeltaAccum = '';
         const proc = spawn(invocation.command, invocation.args, {
             cwd,
             shell: false,
             stdio: ['ignore', 'pipe', 'pipe']
         });
+        // One kill path, shared by user-abort and loop-kill: SIGTERM, then
+        // SIGKILL after a grace period if the child ignored the term.
+        const killProc = () => {
+            aborted = true;
+            proc.kill('SIGTERM');
+            setTimeout(() => {
+                if (!proc.killed)
+                    proc.kill('SIGKILL');
+            }, KILL_GRACE_MS);
+        };
+        const sink = opts?.mode === 'json-events' ? new JsonEventSink(opts, killProc) : null;
         let firstByteFired = false;
-        // json-events lines can split across data chunks; this holds the trailing
-        // partial line between chunks so events spanning a boundary still parse.
-        // In json-events mode we deliberately do NOT accumulate the full raw
-        // stream: a long-running child emits hundreds of MB of events and
-        // `stdout += chunk` would overflow V8's max string length (≈512MB),
-        // crashing the process. We only need the parsed text, so we drop the raw
-        // bytes once drained.
-        let lineBuffer = '';
         proc.stdout?.on('data', (d) => {
             if (!firstByteFired) {
                 firstByteFired = true;
@@ -43,147 +174,28 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
             if (discardStdout)
                 return;
             const chunk = d.toString();
-            if (isJsonEvents) {
-                lineBuffer = drainJsonEvents(lineBuffer + chunk, opts);
-            }
-            else {
+            if (sink)
+                sink.feed(chunk);
+            else
                 stdout += chunk;
-            }
         });
         proc.stderr?.on('data', (d) => {
             stderr += d.toString();
         });
         proc.on('close', (code) => {
-            // Flush a final event that wasn't newline-terminated.
-            if (isJsonEvents && lineBuffer.trim().length > 0) {
-                drainJsonEvents(lineBuffer + '\n', opts);
-                lineBuffer = '';
-            }
-            const text = isJsonEvents ? (finalText || textDeltaAccum).trim() : undefined;
+            if (sink)
+                sink.flush();
+            const text = sink ? sink.text : undefined;
             resolve({ stdout, stderr, exitCode: code ?? 0, aborted, text });
         });
         proc.on('error', () => {
             resolve({ stdout, stderr, exitCode: 1, aborted });
         });
         if (signal) {
-            const kill = () => {
-                aborted = true;
-                proc.kill('SIGTERM');
-                setTimeout(() => {
-                    if (!proc.killed)
-                        proc.kill('SIGKILL');
-                }, KILL_GRACE_MS);
-            };
             if (signal.aborted)
-                kill();
+                killProc();
             else
-                signal.addEventListener('abort', kill, { once: true });
-        }
-        // ─── JSON event-stream processing ──────────────────────────────────
-        /**
-         * Parse every complete (newline-terminated) JSON line in `buf` and
-         * return the trailing partial line, which the caller carries into the
-         * next chunk. This avoids both losing events that span a chunk boundary
-         * and buffering the entire stream.
-         */
-        function drainJsonEvents(buf, jsonOpts) {
-            let nl;
-            while ((nl = buf.indexOf('\n')) !== -1) {
-                const line = buf.slice(0, nl).trim();
-                buf = buf.slice(nl + 1);
-                if (line.length === 0)
-                    continue;
-                try {
-                    const evt = JSON.parse(line);
-                    if (evt && typeof evt === 'object') {
-                        handleEvent(evt, jsonOpts);
-                    }
-                }
-                catch {
-                    // Non-JSON line (startup banner, etc.) — ignore.
-                }
-            }
-            return buf;
-        }
-        function handleEvent(evt, jsonOpts) {
-            const t = typeof evt.type === 'string' ? evt.type : '';
-            if (t === 'context_usage' && jsonOpts.onContextUsage) {
-                const tokens = Number(evt.tokens ?? 0);
-                const contextWindow = Number(evt.contextWindow ?? 0);
-                const percent = Number(evt.percent ?? 0);
-                if (tokens > 0 || contextWindow > 0) {
-                    jsonOpts.onContextUsage({ tokens, contextWindow, percent });
-                }
-                return;
-            }
-            if (t === 'message_end' && jsonOpts.onContextUsage) {
-                const msg = evt.message;
-                if (msg?.role === 'assistant') {
-                    const usage = msg.usage;
-                    if (usage) {
-                        const tokens = Number(usage.input ?? 0)
-                            + Number(usage.cacheRead ?? 0)
-                            + Number(usage.cacheWrite ?? 0)
-                            + Number(usage.output ?? 0);
-                        if (tokens > 0) {
-                            jsonOpts.onContextUsage({ tokens, contextWindow: 0, percent: 0 });
-                        }
-                    }
-                }
-                return;
-            }
-            if (t === 'agent_end' && Array.isArray(evt.messages)) {
-                for (let i = evt.messages.length - 1; i >= 0; i--) {
-                    const m = evt.messages[i];
-                    if (m && m.role === 'assistant' && Array.isArray(m.content)) {
-                        const texts = [];
-                        for (const c of m.content) {
-                            if (c?.type === 'text' && typeof c.text === 'string') {
-                                texts.push(c.text);
-                            }
-                        }
-                        if (texts.length > 0) {
-                            finalText = texts.join('');
-                            break;
-                        }
-                    }
-                }
-                return;
-            }
-            if (t === 'message_update') {
-                const ame = evt.assistantMessageEvent;
-                const ameType = ame && typeof ame.type === 'string' ? ame.type : '';
-                if (ameType === 'text_start') {
-                    textDeltaAccum = '';
-                    if (jsonOpts.onLine)
-                        jsonOpts.onLine('writing answer…');
-                }
-                else if (ameType === 'text_delta' && typeof ame.delta === 'string') {
-                    textDeltaAccum += ame.delta;
-                }
-                else if (ameType === 'thinking_start' && jsonOpts.onLine) {
-                    jsonOpts.onLine('thinking…');
-                }
-                return;
-            }
-            if (t === 'tool_execution_start') {
-                const tn = typeof evt.toolName === 'string' ? evt.toolName : 'tool';
-                if (jsonOpts.onLine) {
-                    const detail = summarizeToolArgs(tn, evt.args);
-                    jsonOpts.onLine(detail ? `${tn}: ${detail}` : tn);
-                }
-                if (jsonOpts.onToolCall) {
-                    const hit = jsonOpts.onToolCall({ name: tn, args: evt.args });
-                    if (hit) {
-                        aborted = true;
-                        proc.kill('SIGTERM');
-                        setTimeout(() => {
-                            if (!proc.killed)
-                                proc.kill('SIGKILL');
-                        }, KILL_GRACE_MS);
-                    }
-                }
-            }
+                signal.addEventListener('abort', killProc, { once: true });
         }
     });
 }

package/dist/task/auto-orchestrator.js

@@ -18,6 +18,7 @@ import { runPhaseChild, USER_CANCELLED } from './child-runner.js';
 import { SessionUI, registerBridgeCommand } from '../remote/bridge.js';
 import { getConfig } from '../config/config.js';
 import { startAutoLoader } from './widget.js';
+import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
 // Matches pi's @-file completion token (a path after @, until whitespace).
 const MENTION_RE = /(?:^|\s)@([^\s]+)/g;
 /**
@@ -54,8 +55,12 @@ export async function planAuto(ctx, cwd, feature, deps) {
     // clarify — sequential & adaptive: ask one question at a time, feeding every
     // answer back into the next call so later questions react to earlier ones
     // (e.g. a framework choice reshapes what gets asked). Each question is shown
-    // with the model's recommended default pre-filled (Enter to accept, type to
-    // override); we never auto-answer. The model emits NONE when nothing remains.
+    // exactly like /task's grill dialog: a binary fork offers two options (A/B),
+    // otherwise the model's recommendation is shown as the input placeholder and
+    // in the title. Nothing is pre-filled into the editor — submitting an empty
+    // field is what accepts the recommendation (see the typed.length === 0 branch
+    // below); typing overrides it. We never auto-answer; the model emits NONE when
+    // nothing remains.
     const theme = ctx.ui.theme;
     const ui = new SessionUI(ctx);
     // Inline any @file spec the user referenced so clarify/decompose reason over
@@ -68,26 +73,38 @@ export async function planAuto(ctx, cwd, feature, deps) {
         const parsed = parseClarifyList(qRaw);
         if (parsed.length === 0)
             break; // NONE / nothing left to ask
-        const { question, suggested } = parsed[0];
+        const { question, suggested, alt } = parsed[0];
         // Render markdown (bold/code) for the displayed prompt; keep plain text
         // for the editable default and the persisted file.
         const shownQ = renderInlineMarkdown(question, theme);
         const plainQ = stripInlineMarkdown(question);
         const plainSuggested = suggested === undefined ? undefined : stripInlineMarkdown(suggested);
-        const title = suggested ?
-            `${shownQ}\n${theme.fg('muted', 'Recommended:')}\n\n${renderInlineMarkdown(suggested, theme)}\n\n${theme.fg('muted', 'press Enter to accept')}`
-            : `${shownQ}\n${theme.fg('muted', '(no recommendation — please answer)')}`;
+        const plainAlt = alt === undefined ? undefined : stripInlineMarkdown(alt);
+        // Compact A/B presentation, identical to /task's grill dialog: a binary
+        // fork shows both options labelled A/B; a single recommendation shows just
+        // the default; an open question shows the bare prompt. No verbose
+        // "Recommended:" / "press Enter to accept" scaffolding.
+        const title = plainSuggested ?
+            plainAlt ?
+                `${shownQ}\nA: ${renderInlineMarkdown(suggested, theme)}\nB: ${renderInlineMarkdown(alt, theme)}`
+                : `${shownQ}\n${renderInlineMarkdown(suggested, theme)}`
+            : shownQ;
         const a = await ui.ask({
             localTitle: title,
             question: plainQ,
             recommended: plainSuggested,
-            allowSkip: plainSuggested === undefined
+            ...(plainAlt !== undefined && { recommended2: plainAlt }),
+            allowSkip: plainSuggested === undefined && plainAlt === undefined
         });
         if (a === undefined) {
             ctx.ui.notify('/task-auto cancelled.', 'warning');
             return null;
         }
         const typed = a.trim();
+        // Two-option mode labels the choices "A:"/"B:", so a user (local TUI or
+        // remote "Manual answer") naturally types the bare letter to pick. Map it
+        // back to the option's full text. Mirrors phaseGrill's answer mapping.
+        const twoOption = plainSuggested !== undefined && plainAlt !== undefined;
         let answer;
         if (typed.length === 0 && plainSuggested) {
             answer = `${plainSuggested} (accepted recommendation)`;
@@ -95,6 +112,12 @@ export async function planAuto(ctx, cwd, feature, deps) {
         else if (typed.length === 0) {
             answer = '(skipped)';
         }
+        else if (twoOption && /^a[.)]?$/i.test(typed)) {
+            answer = plainSuggested;
+        }
+        else if (twoOption && /^b[.)]?$/i.test(typed)) {
+            answer = plainAlt;
+        }
         else {
             answer = typed;
         }
@@ -136,7 +159,7 @@ function defaultDeps(ctx, cwd, signal, title) {
     // output line and context usage, exactly like the single-task phase widget.
     let lastLine;
     let contextUsage;
-    const parentContextWindow = ctx.model?.contextWindow ?? 0;
+    const parentContextWindow = getParentContextWindow(ctx);
     const phaseDeps = {
         cwd,
         taskId: '',
@@ -145,11 +168,7 @@ function defaultDeps(ctx, cwd, signal, title) {
             lastLine = line;
         },
         onContextUsage: snapshot => {
-            const cw = snapshot.contextWindow > 0 ?
-                snapshot.contextWindow
-                : contextUsage?.contextWindow || parentContextWindow;
-            const percent = cw > 0 ? Math.min(100, (snapshot.tokens / cw) * 100) : snapshot.percent;
-            contextUsage = { tokens: snapshot.tokens, contextWindow: cw, percent };
+            contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
         }
     };
     return {
@@ -233,6 +252,17 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     resumeId = undefined;
                 }
             }
+            // Before starting, fold any uncommitted work into its own checkpoint
+            // commit so a dirty tree at the start of the run — or edits left behind
+            // by an interrupted/failed task — land separately instead of being swept
+            // into this task's snapshot. Best-effort and a no-op on a clean tree
+            // (gitCommitAll commits nothing), so it only ever produces a commit when
+            // there is stray work; the matching post-task commit below is the "after"
+            // half. Only the success path is announced to keep the common no-op quiet.
+            const checkpoint = await deps.commit(cwd, `chore: checkpoint before "${next.title}"`);
+            if (checkpoint.committed) {
+                active.ui.notify(`${id}: checkpointed uncommitted work before "${next.title}".`, 'info');
+            }
             const res = await deps.runTask(active, cwd, next.title, {
                 resumeId,
                 onStart: resumeId ? undefined : (innerId => stampTaskInProgress(cwd, id, next.index, innerId, next.title))

package/dist/task/auto-prompts.d.ts

@@ -4,9 +4,10 @@
  */
 /**
  * Clarify: asks ONE question at a time. Output MUST match parseClarifyList — a
- * single numbered question followed by a "SUGGESTED: <default>" line, or the
- * literal token NONE when no clarification remains. priorQA carries the
- * questions already answered so each next question adapts to them.
+ * single numbered question followed by a "SUGGESTED: <default>" line, an optional
+ * "ALT: <alternative>" line for binary "A or B?" forks, or the literal token NONE
+ * when no clarification remains. priorQA carries the questions already answered so
+ * each next question adapts to them.
  */
 export declare const AUTO_CLARIFY_PROMPT: (feature: string, priorQA: string) => string;
 /**

package/dist/task/auto-prompts.js

@@ -4,9 +4,10 @@
  */
 /**
  * Clarify: asks ONE question at a time. Output MUST match parseClarifyList — a
- * single numbered question followed by a "SUGGESTED: <default>" line, or the
- * literal token NONE when no clarification remains. priorQA carries the
- * questions already answered so each next question adapts to them.
+ * single numbered question followed by a "SUGGESTED: <default>" line, an optional
+ * "ALT: <alternative>" line for binary "A or B?" forks, or the literal token NONE
+ * when no clarification remains. priorQA carries the questions already answered so
+ * each next question adapts to them.
  */
 export const AUTO_CLARIFY_PROMPT = (feature, priorQA) => `You are planning how to split a feature into separate implementation tasks, one clarifying question at a time.
 
@@ -33,14 +34,16 @@ fork the breakdown). Account for the answers so far:
   real-time vs polling transport, search, deployment).
 - Skip anything /task will naturally resolve per-task during its own research.
 
-Also propose the single most sensible default answer for this question, inferred
-from the repo, the referenced docs, and any stated philosophy or constraints —
+Also propose the most sensible default answer for this question, inferred from
+the repo, the referenced docs, and any stated philosophy or constraints —
 concrete and decisive, shown to the user as a recommendation they can accept or
-override.
+override. When the question is a genuine binary "A or B?" fork, also give the
+single best alternative as a second option; otherwise offer only the one default.
 
 OUTPUT FORMAT (exact):
 - One clarifying question as a single numbered line: "1. ...".
 - On the NEXT line (never inline), a line that begins with "SUGGESTED: <your recommended default>".
+- ONLY for a binary "A or B?" fork, on the line after that, a line beginning with "ALT: <the alternative option>". Omit the ALT line entirely for open-ended questions.
 - Put the core question in **bold**, followed by a short one-line rationale in plain prose. Backticks around code/identifiers are fine. Avoid other markdown (headings, bullet lists, links).
 - Only when the spec already pins down every choice that would change the task breakdown — nothing decision-changing is left to ask — output exactly:
 NONE`;

package/dist/task/child-runner.js

@@ -10,7 +10,7 @@ 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';
+import { readSection, setTaskSection } from './task-io.js';
 // ─── Loop detection constants ────────────────────────────────────────────────
 // Defined here (not in phases.ts) to avoid a circular dependency:
 //   phases.ts → child-runner.ts → phases.ts

package/dist/task/context-usage.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Context-usage resolution — shared by the single-task widget (TaskRunner) and
+ * the /task-auto planning loader (defaultDeps), which both mirror a child's
+ * context_usage events into a display snapshot with identical math.
+ */
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import type { ContextSnapshot } from '../shared/child-process.js';
+/** The parent session's context window, or 0 when the model doesn't expose it. */
+export declare function getParentContextWindow(ctx: ExtensionCommandContext): number;
+/**
+ * Fold a raw context_usage snapshot into a display snapshot: prefer the child's
+ * own contextWindow, else the last known one, else the parent session's; then
+ * derive percent against it — falling back to the child's reported percent when
+ * no window is known at all.
+ */
+export declare function resolveContextUsage(snapshot: ContextSnapshot, prev: ContextSnapshot | undefined, parentContextWindow: number): ContextSnapshot;

package/dist/task/context-usage.js

@@ -0,0 +1,22 @@
+/**
+ * Context-usage resolution — shared by the single-task widget (TaskRunner) and
+ * the /task-auto planning loader (defaultDeps), which both mirror a child's
+ * context_usage events into a display snapshot with identical math.
+ */
+/** The parent session's context window, or 0 when the model doesn't expose it. */
+export function getParentContextWindow(ctx) {
+    return (ctx.model?.contextWindow ?? 0);
+}
+/**
+ * Fold a raw context_usage snapshot into a display snapshot: prefer the child's
+ * own contextWindow, else the last known one, else the parent session's; then
+ * derive percent against it — falling back to the child's reported percent when
+ * no window is known at all.
+ */
+export function resolveContextUsage(snapshot, prev, parentContextWindow) {
+    const cw = snapshot.contextWindow > 0 ?
+        snapshot.contextWindow
+        : prev?.contextWindow || parentContextWindow;
+    const percent = cw > 0 ? Math.min(100, (snapshot.tokens / cw) * 100) : snapshot.percent;
+    return { tokens: snapshot.tokens, contextWindow: cw, percent };
+}

package/dist/task/external-context.d.ts

@@ -0,0 +1,27 @@
+/**
+ * External-context enrichment — extract packages / URLs / services from the
+ * refined spec, fan out to docs / fetch / search workers, and assemble the
+ * `EXTERNAL CONTEXT` block the research phase prepends to every worker prompt.
+ *
+ * Split out of phases.ts so the research phase reads as "gather context → run
+ * probes → assemble", and so this fan-out has its own test surface separate
+ * from the four research workers. `enrichment.ts` stays a pure parser; the I/O
+ * lives here.
+ */
+import { docsRaw } from '../workers/docs-core.js';
+import { fetchRaw } from '../workers/fetch-core.js';
+import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
+import type { PhaseDeps } from './child-runner.js';
+/** Injectable workers so enrichment is testable without spawning real lookups. */
+export interface ExternalContextDeps {
+    docsRaw?: typeof docsRaw;
+    fetchRaw?: typeof fetchRaw;
+    searchFn?: (input: SearchCoreInput) => Promise<SearchCoreResult>;
+}
+type GatherDeps = Pick<PhaseDeps, 'cwd' | 'signal' | 'recordSubStep'>;
+/**
+ * Returns the `EXTERNAL CONTEXT\n…\n\n` block for the refined spec, or `''` when
+ * there is nothing to enrich (no targets, or every lookup failed).
+ */
+export declare function gatherExternalContext(refined: string, deps: GatherDeps, researchDeps?: ExternalContextDeps): Promise<string>;
+export {};