@mjasnikovs/pi-task 0.10.2 → 0.10.3

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

@@ -38,6 +38,8 @@ interface PhaseDeps {
      */
     recordSubStep?: (label: string, ms: number) => void;
     spawn?: SpawnFn;
+    /** Write a timestamped line to the per-task debug log. Fire-and-forget. */
+    logDebug?: (msg: string) => void;
 }
 export type { PhaseDeps };
 /**

package/dist/task/orchestrator.js

@@ -164,6 +164,13 @@ export class TaskRunner {
         // any phase work — and recover it if the session dies mid-pipeline.
         if (this._onStart)
             await this._onStart(id);
+        // Wire up per-task debug log (<cwd>/.pi-tasks/TASK_XXXX-debug.log).
+        const debugLogPath = path.join(tasksDir(cwd), `${id}-debug.log`);
+        this._deps.logDebug = (msg) => {
+            const line = `${new Date().toISOString()} ${msg}\n`;
+            fsp.appendFile(debugLogPath, line).catch(() => { });
+        };
+        this._deps.logDebug(`run: start phase=${resumePhase}`);
         // Register as active.
         this._widgetState.taskId = id;
         this._widgetState.title = title;
@@ -194,6 +201,7 @@ export class TaskRunner {
                     continue;
                 }
                 await advance(phase.name);
+                this._deps.logDebug?.(`phase:${phase.name}: start`);
                 const children = [];
                 this._currentPhaseChildren = children;
                 const phaseStart = Date.now();
@@ -202,12 +210,10 @@ export class TaskRunner {
                     out = await phase.run(this._deps, this._pc);
                 }
                 finally {
-                    this._timings.push({
-                        label: phase.name,
-                        ms: Date.now() - phaseStart,
-                        children
-                    });
+                    const phaseMs = Date.now() - phaseStart;
+                    this._timings.push({ label: phase.name, ms: phaseMs, children });
                     this._currentPhaseChildren = null;
+                    this._deps.logDebug?.(`phase:${phase.name}: done ms=${phaseMs}`);
                 }
                 await setTaskSection(cwd, id, phase.section, out);
                 this._pc[phase.field] = out;

package/dist/task/phases.js

@@ -74,6 +74,7 @@ export async function phaseVerifyTooling(deps, research) {
     await setTaskSection(deps.cwd, deps.taskId, 'verified tooling', verifiedSection);
     return replaceToolingWithVerified(research, parsed.verified);
 }
+const DOCS_EXTENSION_PATH = new URL('../workers/docs-extension.js', import.meta.url).pathname;
 export async function phaseResearch(deps, refined, researchDeps = {}) {
     const docsRawFn = researchDeps.docsRaw ?? docsRaw;
     const fetchRawFn = researchDeps.fetchRaw ?? fetchRaw;
@@ -192,7 +193,12 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
             label: 'worker:files',
             prompt: appendNoThink(promptHeader + RESEARCH_FILES_PROMPT(refined))
         },
-        { label: 'worker:apis', prompt: appendNoThink(promptHeader + RESEARCH_APIS_PROMPT(refined)) },
+        {
+            label: 'worker:apis',
+            prompt: appendNoThink(promptHeader + RESEARCH_APIS_PROMPT(refined)),
+            tools: 'read,grep,find,ls,pi-worker-docs',
+            extensions: [DOCS_EXTENSION_PATH]
+        },
         {
             label: 'worker:context',
             prompt: appendNoThink(promptHeader + RESEARCH_CONTEXT_PROMPT(refined)),
@@ -209,13 +215,22 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
     ];
     const workerResults = [];
     for (const spec of workerSpecs) {
+        deps.logDebug?.(`${spec.label}: start`);
         const r = await recordWorker(spec.label, runWorker({
             prompt: spec.prompt,
             cwd: deps.cwd,
             signal: deps.signal,
             spawn: deps.spawn,
-            ...(spec.tools ? { tools: spec.tools } : {})
+            ...(spec.tools ? { tools: spec.tools } : {}),
+            ...(spec.extensions ? { extensions: spec.extensions } : {}),
+            onLine: line => {
+                deps.logDebug?.(`${spec.label}: ${line}`);
+                deps.onChildOutput?.(`${spec.label}: ${line}`);
+            }
         }));
+        deps.logDebug?.(`${spec.label}: done exit=${r.exitCode} wait=${r.waitMs}ms work=${r.workMs}ms`
+            + (r.stderr ? ` stderr=${r.stderr.slice(0, 300)}` : '')
+            + (r.leakedToolCall ? ` leaked=${r.leakedToolCall.trim().slice(0, 80)}` : ''));
         updateProgress();
         workerResults.push(r);
     }

package/dist/task/prompts.js

@@ -88,7 +88,9 @@ No section header. No other sections. No preamble.
 
 Task:
 ${refined}`;
-const RESEARCH_APIS_PROMPT = (refined) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools to identify the commands, functions, types, and interfaces the agent will use for the following task.
+const RESEARCH_APIS_PROMPT = (refined) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools — and \`pi-worker-docs\` for installed npm packages — to identify the commands, functions, types, and interfaces the agent will use for the following task.
+
+NPM PACKAGES — use pi-worker-docs, NOT file reads: for any third-party npm package (e.g. "zod", "hono", "drizzle-orm"), call \`pi-worker-docs(module, query)\` to get its type signatures and API surface. Do NOT open node_modules source files directly — those reads are expensive and produce far more noise than the tool. The tool returns a compact, focused excerpt in a fraction of the token cost.
 
 APIS owns symbols and commands BY NAME ONLY. Do NOT include any file path or path fragment — no \`package.json\`, no \`./src/foo.ts\`, no \`package.json#scripts.lint\`. If the symbol is a script defined in package.json, write the invocation (\`npm run lint\`), not its location. If the symbol is a config file, it does not belong in APIS at all — it belongs in FILES.
 

package/dist/workers/docs-extension.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export default function (pi: ExtensionAPI): void;

package/dist/workers/docs-extension.js

@@ -0,0 +1,4 @@
+import { registerPiWorkerDocs } from './pi-worker-docs.js';
+export default function (pi) {
+    registerPiWorkerDocs(pi);
+}

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

@@ -6,6 +6,10 @@ export interface RunWorkerInput {
     spawn?: SpawnFn;
     /** Comma-separated tool whitelist passed to `pi --tools`. Defaults to read,grep,find,ls. */
     tools?: string;
+    /** Extension entry-point paths to load via `-e <path>` before CHILD_BASE_ARGS. */
+    extensions?: string[];
+    /** Called for each tool execution start and text-writing event inside the worker. */
+    onLine?: (line: string) => void;
 }
 export interface RunWorkerResult {
     text: string;

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

@@ -12,7 +12,8 @@ import { detectLeakedToolCall, leakedToolCallHint, MAX_LEAK_RETRIES } from '../s
 const DEFAULT_TOOLS = 'read,grep,find,ls';
 export async function runWorker(input) {
     const tools = input.tools ?? DEFAULT_TOOLS;
-    const baseArgs = [...CHILD_BASE_ARGS, '--mode', 'json', '--tools', tools];
+    const extensionArgs = (input.extensions ?? []).flatMap(e => ['-e', e]);
+    const baseArgs = [...extensionArgs, ...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}`;
@@ -23,7 +24,8 @@ export async function runWorker(input) {
         const result = await runChildDefault(invocation, input.cwd, input.signal, {
             mode: 'json-events',
             onFirstByte: () => (tFirstByte = Date.now()),
-            onToolCall: call => loopDetector.record(call)
+            onToolCall: call => loopDetector.record(call),
+            onLine: input.onLine
         }, input.spawn);
         const tEnd = Date.now();
         const waitMs = tFirstByte === null ? tEnd - tStart : tFirstByte - tStart;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.10.2",
+    "version": "0.10.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",