@mjasnikovs/pi-task 0.2.0

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

@@ -0,0 +1,143 @@
+import { Type } from '@sinclair/typebox';
+import { Text } from '@earendil-works/pi-tui';
+import { docsRaw, formatResultText, buildPrompt } from './docs-core.js';
+import { formatNpmVersionSection } from './npm-version.js';
+import { runChild, CHILD_BASE_ARGS } from '../shared/child-process.js';
+import { parseChildOutput, isExcerptInContent } from '../shared/child-output.js';
+import { getPiInvocation } from '../shared/pi-invocation.js';
+import { textResult } from './shared.js';
+const CHILD_ARGS = [...CHILD_BASE_ARGS, '--no-tools'];
+const RENDER_QUERY_MAX = 100;
+const Params = Type.Object({
+    module: Type.String({
+        description: 'Bare npm module name (e.g. "zod", "@scope/name", "react/jsx-runtime"). Must be installed in the project\'s node_modules.'
+    }),
+    query: Type.String({
+        description: 'What to extract from the module\'s docs. The child pi reads ranked chunks and returns ONLY content answering this.'
+    })
+});
+export function registerPiWorkerDocs(pi, internals = {}) {
+    pi.registerTool({
+        name: 'pi-worker-docs',
+        label: 'Pi Worker Docs',
+        description: 'Look up an npm package locally and return a focused, version-pinned '
+            + 'answer extracted from its .d.ts types and README. No network after install (except a small '
+            + 'live npm registry call described below). The cache lives at ~/.cache/pi-worker/docs.sqlite '
+            + 'and is keyed by exact installed version.\n'
+            + 'If the package is not yet installed, it is installed automatically via bun add or npm install.\n'
+            + '\n'
+            + 'Live registry data: in addition to the docs answer, the tool fetches the latest published '
+            + 'version, recent versions, and publish date from the npm registry and prepends them to the '
+            + 'output (and exposes them in details). This is the source of truth for "what is the latest '
+            + 'version of X" questions — training-data versions are typically months stale. The lookup is '
+            + 'best-effort and silently absent when offline.\n'
+            + '\n'
+            + 'Good fits:\n'
+            + '- "What does library X export?" / "How does function Y work?"\n'
+            + '- Confirming generic shapes, overload sets, exported types\n'
+            + '- Pulling README configuration prose without burning context on raw markdown\n'
+            + '- Checking the current latest published version of a package\n'
+            + '\n'
+            + 'Skip when:\n'
+            + '- You need docs for a specific newer version than what is installed — use pi-worker-fetch on the upstream docs site',
+        parameters: Params,
+        executionMode: 'parallel',
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            const spawn = internals.spawn
+                ?? (globalThis.Bun !== undefined ?
+                    globalThis.Bun.spawn
+                    : (await import('node:child_process')).spawn);
+            const rawResult = await docsRaw({
+                pkg: params.module,
+                query: params.query,
+                cwd: ctx.cwd,
+                resolvePackage: internals.resolvePackage,
+                ensureIndexed: internals.ensureIndexed,
+                retrieveChunks: internals.retrieveChunks,
+                openCache: internals.openCache,
+                spawn,
+                npmVersionLookup: internals.npmVersionLookup,
+                signal
+            });
+            const npmHeader = rawResult.npmVersion ? `${formatNpmVersionSection(rawResult.npmVersion)}\n\n` : '';
+            const npmDetails = rawResult.npmVersion ?
+                {
+                    npmLatest: rawResult.npmVersion.latest,
+                    npmPublishedAt: rawResult.npmVersion.publishedAt
+                }
+                : {};
+            if (rawResult.kind === 'error') {
+                const details = {
+                    resolveError: rawResult.resolveError,
+                    installError: rawResult.installError,
+                    version: rawResult.version,
+                    hitCache: rawResult.hitCache,
+                    cacheError: rawResult.cacheError,
+                    autoInstalled: rawResult.autoInstalled,
+                    ...npmDetails
+                };
+                return textResult(npmHeader + rawResult.message, details);
+            }
+            if (rawResult.kind === 'not_installed') {
+                return textResult(npmHeader
+                    + `Package "${rawResult.pkg}" is not installed and auto-install failed.`, { resolveError: 'not_installed', ...npmDetails });
+            }
+            if (rawResult.kind === 'no_chunks') {
+                return textResult(npmHeader
+                    + `Package ${rawResult.pkg.name}@${rawResult.pkg.version} has no .d.ts files or README. Use pi-worker to read source directly.`, {
+                    version: rawResult.pkg.version,
+                    hitCache: rawResult.hitCache,
+                    indexedFiles: rawResult.indexedFiles ?? 0,
+                    cacheError: rawResult.cacheError,
+                    autoInstalled: rawResult.autoInstalled,
+                    ...npmDetails
+                });
+            }
+            // kind === 'ok'
+            const { pkg, chunks, hitCache, indexingMs, cacheError, autoInstalled } = rawResult;
+            const baseDetails = {
+                version: pkg.version,
+                hitCache,
+                chunksRetrieved: chunks.length,
+                indexingMs,
+                cacheError,
+                autoInstalled,
+                ...npmDetails
+            };
+            const concatenated = chunks.map(c => c.content).join('\n\n');
+            const prompt = buildPrompt(pkg, params.query, concatenated);
+            const invocation = getPiInvocation([...CHILD_ARGS, prompt]);
+            const child = await runChild(spawn, invocation, ctx.cwd, signal);
+            if (child.aborted) {
+                return textResult(npmHeader + 'Docs lookup aborted.', {
+                    ...baseDetails,
+                    aborted: true,
+                    childExitCode: child.exitCode
+                });
+            }
+            if (child.exitCode !== 0) {
+                const tail = child.stderr.trim().slice(-500) || '(no stderr)';
+                return textResult(npmHeader + `Worker exited ${child.exitCode}.\n${tail}`, {
+                    ...baseDetails,
+                    childExitCode: child.exitCode
+                });
+            }
+            const parsed = parseChildOutput(child.stdout);
+            const verified = parsed.excerpt ? isExcerptInContent(parsed.excerpt, concatenated) : undefined;
+            const text = npmHeader + formatResultText(pkg, parsed, verified);
+            return textResult(text, {
+                ...baseDetails,
+                childExitCode: 0,
+                excerptVerified: verified
+            });
+        },
+        renderCall(args, theme) {
+            const query = args.query.replace(/\s+/g, ' ').trim();
+            const truncated = query.length > RENDER_QUERY_MAX ? `${query.slice(0, RENDER_QUERY_MAX - 1)}…` : query;
+            let text = theme.fg('toolTitle', theme.bold('pi-worker-docs '));
+            text += theme.fg('accent', args.module);
+            text += `\n${theme.fg('dim', `  query: ${truncated}`)}`;
+            return new Text(text, 0, 0);
+        }
+    });
+}

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

@@ -0,0 +1,20 @@
+import type { EventEmitter } from 'node:events';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
+interface ProcLike extends EventEmitter {
+    stdout: EventEmitter | null;
+    stderr: EventEmitter | null;
+    killed: boolean;
+    kill(signal: string): boolean | void;
+}
+type SpawnFn = (command: string, args: ReadonlyArray<string>, options: {
+    cwd: string;
+    shell: boolean;
+    stdio: ['ignore', 'pipe', 'pipe'];
+}) => ProcLike;
+export interface PiWorkerFetchInternals {
+    fetchAndClean?: typeof defaultFetchAndClean;
+    spawn?: SpawnFn;
+}
+export declare function registerPiWorkerFetch(pi: ExtensionAPI, internals?: PiWorkerFetchInternals): void;
+export {};

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

@@ -0,0 +1,72 @@
+import { Type } from '@sinclair/typebox';
+import { Text } from '@earendil-works/pi-tui';
+import { FetchAndCleanError } from './html-clean.js';
+import { fetchFocused, formatResultText } from './fetch-core.js';
+import { textResult } from './shared.js';
+const RENDER_QUERY_MAX = 100;
+const Params = Type.Object({
+    url: Type.String({ description: 'URL to fetch. Must be http or https.' }),
+    query: Type.String({
+        description: 'What to extract from the page. The child pi reads the page and returns ONLY content answering this.'
+    })
+});
+export function registerPiWorkerFetch(pi, internals = {}) {
+    pi.registerTool({
+        name: 'pi-worker-fetch',
+        label: 'Pi Worker Fetch',
+        description: 'Fetch an HTML page, clean it to markdown, and hand it to an isolated '
+            + 'child Pi session that extracts ONLY content answering `query`. '
+            + 'Returns the focused answer. Use after `pi-worker-search` (or with a '
+            + 'known URL) to avoid stuffing raw HTML into the main context.',
+        parameters: Params,
+        executionMode: 'parallel',
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            try {
+                new URL(params.url);
+            }
+            catch {
+                return textResult(`Invalid URL: ${params.url}`, {});
+            }
+            try {
+                const result = await fetchFocused({
+                    url: params.url,
+                    query: params.query,
+                    cwd: ctx.cwd,
+                    signal,
+                    fetchAndClean: internals.fetchAndClean,
+                    spawn: internals.spawn
+                });
+                if (result.aborted) {
+                    return textResult('Fetch aborted.', { childExitCode: result.childExitCode });
+                }
+                if (result.childExitCode !== 0) {
+                    const tail = result.stderr.trim().slice(-500) || '(no stderr)';
+                    return textResult(`Worker exited ${result.childExitCode}.\n${tail}`, {
+                        childExitCode: result.childExitCode
+                    });
+                }
+                const text = formatResultText({ answer: result.answer, excerpt: result.excerpt }, result.excerptVerified) || '(no output)';
+                return textResult(text, {
+                    childExitCode: 0,
+                    answer: result.answer,
+                    excerpt: result.excerpt,
+                    excerptVerified: result.excerptVerified
+                });
+            }
+            catch (err) {
+                if (err instanceof FetchAndCleanError) {
+                    return textResult(err.message, {});
+                }
+                return textResult(`Could not fetch ${params.url}: ${err instanceof Error ? err.message : String(err)}`, {});
+            }
+        },
+        renderCall(args, theme) {
+            const query = args.query.replace(/\s+/g, ' ').trim();
+            const truncatedQuery = query.length > RENDER_QUERY_MAX ? `${query.slice(0, RENDER_QUERY_MAX - 1)}…` : query;
+            let text = theme.fg('toolTitle', theme.bold('pi-worker-fetch '));
+            text += theme.fg('accent', args.url);
+            text += `\n${theme.fg('dim', `  query: ${truncatedQuery}`)}`;
+            return new Text(text, 0, 0);
+        }
+    });
+}

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

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { braveSearch as defaultBraveSearch } from './brave-search.js';
+export interface PiWorkerSearchInternals {
+    braveSearch?: typeof defaultBraveSearch;
+    getEnv?: (key: string) => string | undefined;
+}
+export declare function registerPiWorkerSearch(pi: ExtensionAPI, internals?: PiWorkerSearchInternals): void;

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

@@ -0,0 +1,55 @@
+import { Type } from '@sinclair/typebox';
+import { Text } from '@earendil-works/pi-tui';
+import { search } from './search-core.js';
+import { textResult } from './shared.js';
+const Params = Type.Object({
+    query: Type.String({ description: 'Search query.' }),
+    count: Type.Optional(Type.Integer({
+        minimum: 1,
+        maximum: 20,
+        description: 'How many results to return (default 10, max 20).'
+    }))
+});
+export function registerPiWorkerSearch(pi, internals = {}) {
+    pi.registerTool({
+        name: 'pi-worker-search',
+        label: 'Pi Worker Search',
+        description: 'Search the web via Brave Search. Returns a compact markdown list of '
+            + 'up to 10 results (title, URL, snippet). Use this to find candidate '
+            + 'URLs, then call `pi-worker-fetch` on the URL you want to read. '
+            + 'Requires BRAVE_SEARCH_API_KEY env var.',
+        parameters: Params,
+        executionMode: 'parallel',
+        async execute(_toolCallId, params, signal) {
+            const result = await search({
+                query: params.query,
+                count: params.count,
+                signal,
+                getEnv: internals.getEnv,
+                braveSearch: internals.braveSearch
+            });
+            if (result.kind === 'no_key') {
+                return textResult(result.message, { resultCount: 0 });
+            }
+            if (result.kind === 'error') {
+                return textResult(result.message, { resultCount: 0 });
+            }
+            const { results } = result;
+            if (results.length === 0) {
+                return textResult(`No results for: ${params.query}`, {
+                    resultCount: 0
+                });
+            }
+            const lines = results.map((r, i) => `${i + 1}. [${r.title}](${r.url}) — ${r.description}`);
+            return textResult(lines.join('\n'), { resultCount: results.length });
+        },
+        renderCall(args, theme) {
+            let text = theme.fg('toolTitle', theme.bold('pi-worker-search '));
+            text += theme.fg('accent', args.query);
+            if (typeof args.count === 'number') {
+                text += theme.fg('dim', ` (count=${args.count})`);
+            }
+            return new Text(text, 0, 0);
+        }
+    });
+}

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

@@ -0,0 +1,10 @@
+/**
+ * pi-worker — minimal subagent tool.
+ *
+ * Spawns a sandboxed child `pi --print` for each call, returns its stdout.
+ * Child has read+grep+find+ls only (no bash, write, or edit) — no skills,
+ * extensions, prompt templates, context files, or session storage. Cannot
+ * recurse into another worker.
+ */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export declare function registerPiWorker(pi: ExtensionAPI): void;

package/dist/workers/pi-worker.js

@@ -0,0 +1,61 @@
+/**
+ * pi-worker — minimal subagent tool.
+ *
+ * Spawns a sandboxed child `pi --print` for each call, returns its stdout.
+ * Child has read+grep+find+ls only (no bash, write, or edit) — no skills,
+ * extensions, prompt templates, context files, or session storage. Cannot
+ * recurse into another worker.
+ */
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from '@sinclair/typebox';
+import { runWorker } from './pi-worker-core.js';
+import { textResult } from './shared.js';
+const RENDER_PROMPT_MAX = 120;
+const WorkerParams = Type.Object({
+    prompt: Type.String({ description: 'Task for the worker to perform.' })
+});
+export function registerPiWorker(pi) {
+    pi.registerTool({
+        name: 'pi-worker',
+        label: 'Pi Worker',
+        description: 'Dispatch an isolated child Pi to investigate a question and return its '
+            + 'conclusion — not the raw evidence. Use when answering requires reading '
+            + 'multiple files, running several greps, or scanning large command output '
+            + 'you do not need verbatim.\n'
+            + '\n'
+            + 'Good fits:\n'
+            + '- "Where/how is X handled in this repo?" across unfamiliar code\n'
+            + '- Audits and pattern scans across many files ("every place we log PII")\n'
+            + '- Summarising long test output, logs, or shell output\n'
+            + '- Parallel fan-out: dispatch several workers in one turn for independent questions\n'
+            + '\n'
+            + 'Skip when:\n'
+            + '- You already know the exact file — call `read` directly\n'
+            + '- The task needs writes/edits (worker is read-only)\n'
+            + '- The task needs the web — use `pi-worker-search` / `pi-worker-fetch`',
+        parameters: WorkerParams,
+        executionMode: 'parallel',
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            const result = await runWorker({ prompt: params.prompt, cwd: ctx.cwd, signal });
+            if (result.aborted) {
+                return textResult('Worker aborted.', { exitCode: result.exitCode });
+            }
+            if (result.exitCode !== 0) {
+                const tail = result.stderr.slice(-500) || '(no stderr)';
+                return textResult(`Worker exited ${result.exitCode}.\n${tail}`, {
+                    exitCode: result.exitCode
+                });
+            }
+            return textResult(result.text || '(no output)', { exitCode: result.exitCode });
+        },
+        renderCall(args, theme) {
+            const prompt = args.prompt.replace(/\s+/g, ' ').trim();
+            const truncated = prompt.length > RENDER_PROMPT_MAX ?
+                `${prompt.slice(0, RENDER_PROMPT_MAX - 1)}…`
+                : prompt;
+            const head = theme.fg('toolTitle', theme.bold('pi-worker '));
+            const body = theme.fg('accent', truncated);
+            return new Text(head + body, 0, 0);
+        }
+    });
+}

package/dist/workers/search-core.d.ts

@@ -0,0 +1,19 @@
+import { braveSearch as defaultBraveSearch, type BraveResult } from './brave-search.js';
+export interface SearchCoreInput {
+    query: string;
+    count?: number;
+    signal?: AbortSignal;
+    getEnv?: (key: string) => string | undefined;
+    braveSearch?: typeof defaultBraveSearch;
+}
+export type SearchCoreResult = {
+    kind: 'ok';
+    results: BraveResult[];
+} | {
+    kind: 'no_key';
+    message: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+export declare function search(input: SearchCoreInput): Promise<SearchCoreResult>;

package/dist/workers/search-core.js

@@ -0,0 +1,35 @@
+import { braveSearch as defaultBraveSearch, BraveSearchError } from './brave-search.js';
+function isLikeBraveSearchError(err) {
+    return (typeof err === 'object'
+        && err !== null
+        && err.name === 'BraveSearchError');
+}
+export async function search(input) {
+    const getEnv = input.getEnv ?? ((k) => process.env[k]);
+    const braveSearch = input.braveSearch ?? defaultBraveSearch;
+    const apiKey = getEnv('BRAVE_SEARCH_API_KEY') ?? getEnv('BRAVE_API_KEY');
+    if (!apiKey) {
+        return {
+            kind: 'no_key',
+            message: 'Brave Search not configured. Set BRAVE_SEARCH_API_KEY env var. '
+                + 'Get a key at https://api.search.brave.com/app/keys'
+        };
+    }
+    try {
+        const results = await braveSearch(input.query, {
+            apiKey,
+            count: input.count,
+            signal: input.signal
+        });
+        return { kind: 'ok', results };
+    }
+    catch (err) {
+        if (err instanceof BraveSearchError || isLikeBraveSearchError(err)) {
+            return { kind: 'error', message: err.message };
+        }
+        return {
+            kind: 'error',
+            message: `Brave Search request failed: ${err instanceof Error ? err.message : String(err)}`
+        };
+    }
+}

package/dist/workers/shared.d.ts

@@ -0,0 +1,3 @@
+import type { AgentToolResult } from '@earendil-works/pi-agent-core';
+/** Build a plain-text AgentToolResult. */
+export declare function textResult<T>(text: string, details: T): AgentToolResult<T>;

package/dist/workers/shared.js

@@ -0,0 +1,4 @@
+/** Build a plain-text AgentToolResult. */
+export function textResult(text, details) {
+    return { content: [{ type: 'text', text }], details };
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@mjasnikovs/pi-task",
+    "version": "0.2.0",
+    "description": "Deterministic spec-orchestration for local models, with bundled web/docs/fetch/worker subagent tools.",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "files": ["dist", "README.md", "LICENSE"],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json",
+        "lint": "prettier --log-level warn --write 'src/**/*.ts' && eslint --fix . && tsc --noEmit",
+        "test": "bun test src/",
+        "prepublishOnly": "bun run build"
+    },
+    "peerDependencies": {
+        "@earendil-works/pi-coding-agent": "0.75.5",
+        "@earendil-works/pi-agent-core": "0.75.5",
+        "@earendil-works/pi-tui": "0.75.5"
+    },
+    "dependencies": {
+        "@mozilla/readability": "^0.6.0",
+        "@sinclair/typebox": "0.34.49",
+        "jsdom": "^29.1.1",
+        "turndown": "^7.2.4"
+    },
+    "devDependencies": {
+        "@earendil-works/pi-coding-agent": "0.75.5",
+        "@earendil-works/pi-agent-core": "0.75.5",
+        "@earendil-works/pi-tui": "0.75.5",
+        "@eslint/js": "10.0.1",
+        "@sinclair/typebox": "0.34.49",
+        "@types/bun": "1.3.12",
+        "@types/jsdom": "^28.0.3",
+        "@types/turndown": "^5.0.6",
+        "eslint": "10.2.1",
+        "globals": "17.5.0",
+        "prettier": "3.8.3",
+        "typescript": "6.0.3",
+        "typescript-eslint": "8.58.2"
+    },
+    "keywords": ["pi", "pi-extension", "coding-agent", "task-orchestration", "local-llm"],
+    "repository": {
+        "type": "git",
+        "url": "github:mjasnikovs/pi-task"
+    },
+    "license": "MIT",
+    "pi": {
+        "extensions": ["src/index.ts"]
+    }
+}