@mjasnikovs/pi-task 0.18.4 → 0.18.6

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

@@ -8,6 +8,7 @@ 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 { formatChildFailure, makeWorkerTool } from './shared.js';
+import { normalizeQuery } from './research-cache.js';
 import { projectDocsRaw, buildProjectPrompt } from './docs-project.js';
 const CHILD_ARGS = [...CHILD_BASE_ARGS, '--no-tools'];
 const RENDER_QUERY_MAX = 100;
@@ -239,6 +240,17 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             text += theme.fg('accent', label);
             text += `\n${theme.fg('dim', `  query: ${truncated}`)}`;
             return new Text(text, 0, 0);
-        }
+        },
+        // Cache npm-package answers per run (a package's installed types/README + latest
+        // version do not change within a run). A project-source `.` lookup is NOT cached:
+        // the working tree mutates as tasks implement, so its answer can go stale mid-run
+        // (the docs SQLite index already keys those on file mtime).
+        cacheKey: params => params.module === '.' ?
+            null
+            : `${normalizeQuery(params.module)}::${normalizeQuery(params.query)}`,
+        // Only a completed lookup (child exited 0) is a real answer; not-installed,
+        // no-chunks, resolve/cache errors, and aborts omit childExitCode:0 and fall
+        // through to a live retry next time.
+        cacheable: d => d.childExitCode === 0
     });
 }

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

@@ -3,6 +3,7 @@ import { Text } from '@earendil-works/pi-tui';
 import { FetchAndCleanError } from './html-clean.js';
 import { fetchFocused, formatResultText } from './fetch-core.js';
 import { formatChildFailure, makeWorkerTool } from './shared.js';
+import { normalizeQuery } from './research-cache.js';
 const RENDER_QUERY_MAX = 100;
 const Params = Type.Object({
     url: Type.String({ description: 'URL to fetch. Must be http or https.' }),
@@ -79,6 +80,14 @@ export function registerPiWorkerFetch(pi, internals = {}) {
             text += theme.fg('accent', args.url);
             text += `\n${theme.fg('dim', `  query: ${truncatedQuery}`)}`;
             return new Text(text, 0, 0);
-        }
+        },
+        // Cache fetch answers per run (the same page re-fetched across sibling tasks
+        // otherwise). The URL is kept verbatim (path case can matter); the query is
+        // normalised. Both parts key the entry — same page, different question is a
+        // different answer.
+        cacheKey: params => `${params.url.trim()}::${normalizeQuery(params.query)}`,
+        // Only a completed fetch (child exited 0) is a real answer; invalid-URL,
+        // fetch failures, and aborts omit childExitCode:0 and fall through.
+        cacheable: d => d.childExitCode === 0
     });
 }

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

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

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

@@ -1,7 +1,9 @@
 import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
+import { getConfig } from '../config/config.js';
 import { search } from './search-core.js';
 import { makeWorkerTool } from './shared.js';
+import { normalizeQuery } from './research-cache.js';
 const Params = Type.Object({
     query: Type.String({ description: 'Search query.' }),
     count: Type.Optional(Type.Integer({
@@ -11,26 +13,29 @@ const Params = Type.Object({
     }))
 });
 export function registerPiWorkerSearch(pi, internals = {}) {
+    const provider = () => internals.provider ?? getConfig().searchProvider;
     makeWorkerTool(pi, {
         name: 'pi-worker-search',
         label: 'Pi Worker Search',
-        description: 'Search the live web via Brave Search. CALL THIS BEFORE ANSWERING any '
+        description: 'Search the live web. CALL THIS BEFORE ANSWERING any '
             + 'question about current or version-specific external facts: '
             + 'library/framework versions and their APIs, latest releases, recently '
             + 'shipped features, current events, prices, or who currently holds a '
             + 'role. Your built-in knowledge is out of date — do NOT answer such '
             + 'questions from memory and do NOT shell out with bash to guess. Returns '
             + 'a compact markdown list of up to 10 results (title, URL, snippet); then '
-            + 'call `pi-worker-fetch` on the URL you want to read. '
-            + 'Requires BRAVE_SEARCH_API_KEY env var.',
+            + 'call `pi-worker-fetch` on the URL you want to read.',
         parameters: Params,
         async run(params, signal) {
             const result = await search({
                 query: params.query,
                 count: params.count,
                 signal,
+                provider: internals.provider,
                 getEnv: internals.getEnv,
-                braveSearch: internals.braveSearch
+                braveSearch: internals.braveSearch,
+                exaSearch: internals.exaSearch,
+                ddgSearch: internals.ddgSearch
             });
             if (result.kind === 'no_key' || result.kind === 'error') {
                 return { text: result.message, details: { resultCount: 0 } };
@@ -49,6 +54,14 @@ export function registerPiWorkerSearch(pi, internals = {}) {
                 text += theme.fg('dim', ` (count=${args.count})`);
             }
             return new Text(text, 0, 0);
-        }
+        },
+        // Cache search results per run (the same query re-run across sibling tasks hits
+        // the live web anew otherwise). Count is part of the key — a larger request is a
+        // different result set — and so is the provider: two engines' result sets for
+        // one query are different answers and must not serve for each other.
+        cacheKey: params => `${provider()}::${normalizeQuery(params.query)}::${params.count ?? ''}`,
+        // Only a non-empty result set is worth caching; no-key, error, and empty results
+        // (resultCount 0) fall through so a later attempt can succeed.
+        cacheable: d => d.resultCount > 0
     });
 }

package/dist/workers/research-cache.d.ts

@@ -0,0 +1,39 @@
+/** The env var the orchestrator stamps with the per-run id children inherit. */
+export declare const RESEARCH_RUN_ID_ENV = "PI_TASK_RUN_ID";
+export declare function researchCacheFile(cwd: string): string;
+/**
+ * The current run's id, or undefined when caching is off (the orchestrator did not
+ * stamp one for this run). A worker treats undefined as "do not cache".
+ */
+export declare function researchRunId(): string | undefined;
+/** A fresh, per-invocation run token — stable within one run, unique across runs. */
+export declare function newRunToken(): string;
+/**
+ * Orchestrator hook: called once at the start of every /task-auto invocation. When
+ * caching is enabled it stamps a FRESH token (so a long-lived host never reuses a
+ * prior run's token, and planAuto + the task loop of THIS run share one id); when
+ * disabled it clears any token a prior run left, so the workers cache nothing.
+ */
+export declare function configureResearchRun(enabled: boolean): string | undefined;
+/**
+ * Normalise a query/module string for the cache KEY: collapse whitespace and
+ * lowercase, so trivially-varied phrasings of the same question share a digest. The
+ * stored value is the real answer, so a case/spacing collision only means two ways
+ * of asking the same thing resolve to the same (correct) result.
+ */
+export declare function normalizeQuery(s: string): string;
+/**
+ * Look up a cached result for `key` in the current run. Returns undefined on a miss,
+ * a stale-run file (different id ⇒ another run's digest, ignored), or any failure.
+ */
+export declare function lookupResearch(cwd: string, runId: string, key: string): Promise<{
+    text: string;
+    details: unknown;
+} | undefined>;
+/**
+ * Store a successful result under `key` for the current run. A file written for a
+ * different run id is discarded and started fresh (first write of a new run drops the
+ * prior run's contents — self-healing per-run isolation without an explicit clear).
+ * Best-effort: any failure is swallowed, leaving the caller's live result untouched.
+ */
+export declare function storeResearch(cwd: string, runId: string, key: string, text: string, details: unknown): Promise<void>;

package/dist/workers/research-cache.js

@@ -0,0 +1,140 @@
+/**
+ * research-cache — a per-run cache of docs/search/fetch worker RESULTS, shared
+ * across the sibling task pipelines of one /task-auto run.
+ *
+ * The failure this serves (mx5 run 8, F10): the research phase alone burned 75 of
+ * 363 minutes because ~20 sibling task pipelines each re-fetched the SAME external
+ * docs and re-ran the SAME searches (the tailwind CLI docs fetched anew for task
+ * after task). Each of those worker results is a deterministic function of (tool,
+ * package/url, query) that does not change within a run — so the first pipeline to
+ * ask a question can answer every later one from a shared digest instead of a fresh
+ * network round-trip plus child-summariser spawn.
+ *
+ * SCOPE — stable external lookups only: npm-package docs, web search, web fetch. A
+ * PROJECT-SOURCE (`.`) docs lookup is deliberately NOT cached: the working tree
+ * mutates as tasks implement, so a `.` answer from an early task can be stale by a
+ * later one (the docs SQLite index already keys those on file mtime). Only a result
+ * the tool marks successful is cached — an error, an empty result, or an abort is
+ * never memoised, so a transient failure cannot poison the run.
+ *
+ * PER-RUN ISOLATION: the orchestrator stamps a FRESH run id into the environment
+ * (PI_TASK_RUN_ID) at the start of every /task-auto invocation; the research-worker
+ * children inherit it. The cache file records the run id it was written for, and any
+ * read or write for a different id discards the stale contents. So a long-lived host
+ * process running many /task-auto runs never serves one run's digest to another, and
+ * a run started with the feature flag OFF (no id in the environment) does not cache
+ * at all — the cache is inert unless the orchestrator turned it on for this run.
+ *
+ * Stored under `.pi-tasks/` (sibling of env-notes.md / contracts.md), which the
+ * git-state guard and discardEdits both exclude. Best-effort throughout: any I/O or
+ * parse failure falls back to a live fetch — the cache only ever saves time, it can
+ * never change an answer or block a worker.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { tasksDir } from '../task/task-io.js';
+const RESEARCH_CACHE_FILE = 'research-cache.json';
+/** The env var the orchestrator stamps with the per-run id children inherit. */
+export const RESEARCH_RUN_ID_ENV = 'PI_TASK_RUN_ID';
+/**
+ * Cap stored entries so a chatty run cannot grow the file unboundedly; the newest
+ * (by write time) are kept. Sized well above a 20-task run's distinct external
+ * lookups (dozens), so a real run never evicts a still-useful digest.
+ */
+const MAX_ENTRIES = 250;
+export function researchCacheFile(cwd) {
+    return path.join(tasksDir(cwd), RESEARCH_CACHE_FILE);
+}
+/**
+ * The current run's id, or undefined when caching is off (the orchestrator did not
+ * stamp one for this run). A worker treats undefined as "do not cache".
+ */
+export function researchRunId() {
+    const v = process.env[RESEARCH_RUN_ID_ENV]?.trim();
+    return v && v.length > 0 ? v : undefined;
+}
+/** A fresh, per-invocation run token — stable within one run, unique across runs. */
+export function newRunToken() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+ * Orchestrator hook: called once at the start of every /task-auto invocation. When
+ * caching is enabled it stamps a FRESH token (so a long-lived host never reuses a
+ * prior run's token, and planAuto + the task loop of THIS run share one id); when
+ * disabled it clears any token a prior run left, so the workers cache nothing.
+ */
+export function configureResearchRun(enabled) {
+    if (!enabled) {
+        delete process.env[RESEARCH_RUN_ID_ENV];
+        return undefined;
+    }
+    const token = newRunToken();
+    process.env[RESEARCH_RUN_ID_ENV] = token;
+    return token;
+}
+/**
+ * Normalise a query/module string for the cache KEY: collapse whitespace and
+ * lowercase, so trivially-varied phrasings of the same question share a digest. The
+ * stored value is the real answer, so a case/spacing collision only means two ways
+ * of asking the same thing resolve to the same (correct) result.
+ */
+export function normalizeQuery(s) {
+    return s.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+async function readCacheFile(cwd) {
+    try {
+        const raw = await fsp.readFile(researchCacheFile(cwd), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed
+            && typeof parsed === 'object'
+            && typeof parsed.runId === 'string'
+            && typeof parsed.entries === 'object'
+            && parsed.entries !== null) {
+            return parsed;
+        }
+    }
+    catch {
+        // missing or corrupt ⇒ treated as empty
+    }
+    return null;
+}
+/**
+ * Look up a cached result for `key` in the current run. Returns undefined on a miss,
+ * a stale-run file (different id ⇒ another run's digest, ignored), or any failure.
+ */
+export async function lookupResearch(cwd, runId, key) {
+    const file = await readCacheFile(cwd);
+    if (!file || file.runId !== runId)
+        return undefined;
+    const entry = file.entries[key];
+    return entry ? { text: entry.text, details: entry.details } : undefined;
+}
+/**
+ * Store a successful result under `key` for the current run. A file written for a
+ * different run id is discarded and started fresh (first write of a new run drops the
+ * prior run's contents — self-healing per-run isolation without an explicit clear).
+ * Best-effort: any failure is swallowed, leaving the caller's live result untouched.
+ */
+export async function storeResearch(cwd, runId, key, text, details) {
+    try {
+        const existing = await readCacheFile(cwd);
+        const entries = existing && existing.runId === runId ? existing.entries : {};
+        entries[key] = { text, details, at: Date.now() };
+        // Evict oldest by write time if over the cap.
+        const keys = Object.keys(entries);
+        if (keys.length > MAX_ENTRIES) {
+            const ordered = keys.sort((a, b) => entries[a].at - entries[b].at);
+            for (const k of ordered.slice(0, keys.length - MAX_ENTRIES))
+                delete entries[k];
+        }
+        const out = { runId, entries };
+        await fsp.mkdir(tasksDir(cwd), { recursive: true });
+        // Atomic-ish write so a concurrent reader never sees a half-written file.
+        const tmp = `${researchCacheFile(cwd)}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+        await fsp.writeFile(tmp, JSON.stringify(out), 'utf8');
+        await fsp.rename(tmp, researchCacheFile(cwd));
+    }
+    catch {
+        // best-effort cache
+    }
+}

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

@@ -1,14 +1,21 @@
-import { braveSearch as defaultBraveSearch, type BraveResult } from './brave-search.js';
+import { braveSearch as defaultBraveSearch } from './brave-search.js';
+import { ddgSearch as defaultDdgSearch } from './ddg-search.js';
+import { exaSearch as defaultExaSearch } from './exa-search.js';
+import type { SearchProvider, SearchResult } from './search-types.js';
 export interface SearchCoreInput {
     query: string;
     count?: number;
     signal?: AbortSignal;
     getEnv?: (key: string) => string | undefined;
+    /** Engine override; defaults to the configured `searchProvider` (exa). */
+    provider?: SearchProvider;
     braveSearch?: typeof defaultBraveSearch;
+    exaSearch?: typeof defaultExaSearch;
+    ddgSearch?: typeof defaultDdgSearch;
 }
 export type SearchCoreResult = {
     kind: 'ok';
-    results: BraveResult[];
+    results: SearchResult[];
 } | {
     kind: 'no_key';
     message: string;
@@ -16,4 +23,9 @@ export type SearchCoreResult = {
     kind: 'error';
     message: string;
 };
+/**
+ * Provider selection is STRICT: the configured (or overridden) engine is the
+ * only one tried — a failure reports as an error rather than silently switching
+ * engines, so results always come from where the user thinks they do.
+ */
 export declare function search(input: SearchCoreInput): Promise<SearchCoreResult>;

package/dist/workers/search-core.js

@@ -1,18 +1,50 @@
+import { getConfig } from '../config/config.js';
 import { braveSearch as defaultBraveSearch, BraveSearchError } from './brave-search.js';
+import { ddgSearch as defaultDdgSearch } from './ddg-search.js';
+import { exaSearch as defaultExaSearch } from './exa-search.js';
 function isLikeBraveSearchError(err) {
     return (typeof err === 'object'
         && err !== null
         && err.name === 'BraveSearchError');
 }
+/**
+ * Provider selection is STRICT: the configured (or overridden) engine is the
+ * only one tried — a failure reports as an error rather than silently switching
+ * engines, so results always come from where the user thinks they do.
+ */
 export async function search(input) {
+    const provider = input.provider ?? getConfig().searchProvider;
+    if (provider === 'brave')
+        return braveSearchCore(input);
+    const run = provider === 'exa' ?
+        () => (input.exaSearch ?? defaultExaSearch)(input.query, {
+            count: input.count,
+            signal: input.signal
+        })
+        : () => (input.ddgSearch ?? defaultDdgSearch)(input.query, {
+            count: input.count,
+            signal: input.signal
+        });
+    try {
+        return { kind: 'ok', results: await run() };
+    }
+    catch (err) {
+        return {
+            kind: 'error',
+            message: err instanceof Error ? err.message : String(err)
+        };
+    }
+}
+async function braveSearchCore(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'
+            message: 'Brave Search not configured. Set BRAVE_SEARCH_API_KEY env var '
+                + '(get a key at https://api.search.brave.com/app/keys) or switch '
+                + 'the search provider in /task-config.'
         };
     }
     try {

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

@@ -0,0 +1,15 @@
+/** One web-search hit, in the shape every provider normalises to. */
+export interface SearchResult {
+    title: string;
+    url: string;
+    description: string;
+}
+/**
+ * Which engine backs pi-worker-search and the freshness/enrichment lookups.
+ * - `exa`   — Exa's public MCP endpoint; no key needed (default).
+ * - `ddg`   — DuckDuckGo's HTML endpoint; no key needed.
+ * - `brave` — Brave Search API; needs BRAVE_SEARCH_API_KEY.
+ */
+export type SearchProvider = 'exa' | 'ddg' | 'brave';
+export declare const SEARCH_PROVIDERS: readonly SearchProvider[];
+export declare function isSearchProvider(value: unknown): value is SearchProvider;

package/dist/workers/search-types.js

@@ -0,0 +1,4 @@
+export const SEARCH_PROVIDERS = ['exa', 'ddg', 'brave'];
+export function isSearchProvider(value) {
+    return typeof value === 'string' && SEARCH_PROVIDERS.includes(value);
+}

package/dist/workers/shared.d.ts

@@ -38,6 +38,23 @@ export interface WorkerToolSpec<TParams extends TSchema, TDetails> {
         details: TDetails;
     }>;
     renderCall(args: Static<TParams>, theme: Theme): Text;
+    /**
+     * Per-run research-cache policy (F10). Return a stable cache key for this call —
+     * a result keyed on it is a deterministic function of the inputs that does not
+     * change within a run, so a later sibling task can reuse it instead of re-running
+     * the network fetch + child summariser. Return `null` to opt a particular call
+     * OUT of caching (e.g. a project-source `.` lookup, whose answer the working tree
+     * mutates within a run). Omit entirely and the tool is never cached. The stored
+     * key is namespaced by tool name, so keys need only be unique within a tool.
+     */
+    cacheKey?(params: Static<TParams>): string | null;
+    /**
+     * Whether a produced result is safe to cache. Only a SUCCESS is memoised — an
+     * error, empty, or aborted result must fall through so a transient failure never
+     * poisons the run. Defaults to always-cacheable when omitted (but a tool with a
+     * cacheKey should always supply this).
+     */
+    cacheable?(details: TDetails, text: string): boolean;
 }
 /** Register a worker tool from its spec, supplying the shared registration ritual. */
 export declare function makeWorkerTool<TParams extends TSchema, TDetails>(pi: ExtensionAPI, spec: WorkerToolSpec<TParams, TDetails>): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.18.4",
+    "version": "0.18.6",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",