@mjasnikovs/pi-task 0.38.15 → 0.38.17

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

@@ -3,7 +3,7 @@ import { Text } from '@earendil-works/pi-tui';
 import { FetchAndCleanError } from './html-clean.js';
 import { fetchFocused } from './fetch-core.js';
 import { formatResultText } from '../shared/child-output.js';
-import { makeWorkerTool } from './shared.js';
+import { childFailureReason, makeWorkerTool, workerAnswer, workerUnavailable } from './shared.js';
 import { normalizeQuery } from './research-cache.js';
 import { isAbstention } from './abstention.js';
 const RENDER_QUERY_MAX = 100;
@@ -35,7 +35,7 @@ export function registerPiWorkerFetch(pi, internals = {}) {
                 new URL(params.url);
             }
             catch {
-                return { text: `Invalid URL: ${params.url}`, details: {} };
+                return workerUnavailable(`Invalid URL: ${params.url}`, {}, 'bad-url');
             }
             try {
                 const result = await fetchFocused({
@@ -50,7 +50,10 @@ export function registerPiWorkerFetch(pi, internals = {}) {
                 // (workers/focused-extractor.ts) — this used to re-map the result back into a
                 // ChildOutcome just to ask formatChildFailure the same question.
                 if (result.failure !== undefined) {
-                    return { text: result.failure, details: { childExitCode: result.childExitCode } };
+                    return workerUnavailable(result.failure, { childExitCode: result.childExitCode }, childFailureReason({
+                        exitCode: result.childExitCode,
+                        aborted: result.aborted
+                    }));
                 }
                 const body = formatResultText('', // a fetched page answer carries no package header
                 { answer: result.answer, excerpt: result.excerpt }, result.excerptVerified) || '(no output)';
@@ -58,26 +61,20 @@ export function registerPiWorkerFetch(pi, internals = {}) {
                 // in the TEXT, not only in details: details are for the harness, and the
                 // worker acts on what it reads.
                 const text = result.nextStep ? `${body}\n\n${result.nextStep}` : body;
-                return {
-                    text,
-                    details: {
-                        childExitCode: 0,
-                        answer: result.answer,
-                        excerpt: result.excerpt,
-                        excerptVerified: result.excerptVerified,
-                        coverageMiss: result.coverageMiss,
-                        anchoredSection: result.anchoredSection
-                    }
-                };
+                return workerAnswer(text, {
+                    childExitCode: 0,
+                    answer: result.answer,
+                    excerpt: result.excerpt,
+                    excerptVerified: result.excerptVerified,
+                    coverageMiss: result.coverageMiss,
+                    anchoredSection: result.anchoredSection
+                });
             }
             catch (err) {
                 if (err instanceof FetchAndCleanError) {
-                    return { text: err.message, details: {} };
+                    return workerUnavailable(err.message, {}, 'fetch-failed');
                 }
-                return {
-                    text: `Could not fetch ${params.url}: ${err instanceof Error ? err.message : String(err)}`,
-                    details: {}
-                };
+                return workerUnavailable(`Could not fetch ${params.url}: ${err instanceof Error ? err.message : String(err)}`, {}, 'fetch-failed');
             }
         },
         renderCall(args, theme) {
@@ -109,8 +106,10 @@ export function registerPiWorkerFetch(pi, internals = {}) {
  * `docsCacheable`: pi-worker-fetch.test.ts carried a hand-retyped copy driving four
  * tests, which a change to the shipped rule would leave green.
  */
-export function fetchCacheable(d, text) {
-    return d.childExitCode === 0 && !isAbstention(text);
+export function fetchCacheable(_d, text) {
+    // Answer QUALITY only — see docsCacheable. `childExitCode === 0` used to lead
+    // this rule and was true of an aborted child, so `"Fetch aborted."` cached.
+    return !isAbstention(text);
 }
 /** The fetch cache key. URL verbatim (path case can matter), question normalised —
  *  same page, different question is a different answer. */

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

@@ -2,7 +2,7 @@ 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 { makeWorkerTool, workerAnswer, workerUnavailable } from './shared.js';
 import { normalizeQuery } from './research-cache.js';
 const Params = Type.Object({
     query: Type.String({ description: 'Search query.' }),
@@ -38,14 +38,16 @@ export function registerPiWorkerSearch(pi, internals = {}) {
                 ddgSearch: internals.ddgSearch
             });
             if (result.kind === 'no_key' || result.kind === 'error') {
-                return { text: result.message, details: { resultCount: 0 } };
+                return workerUnavailable(result.message, { resultCount: 0 }, result.kind);
             }
             const { results } = result;
+            // Zero results IS an answer: the search ran and the web has nothing.
+            // Only a search that could not run is unavailable.
             if (results.length === 0) {
-                return { text: `No results for: ${params.query}`, details: { resultCount: 0 } };
+                return workerAnswer(`No results for: ${params.query}`, { resultCount: 0 });
             }
             const lines = results.map((r, i) => `${i + 1}. [${r.title}](${r.url}) — ${r.description}`);
-            return { text: lines.join('\n'), details: { resultCount: results.length } };
+            return workerAnswer(lines.join('\n'), { resultCount: results.length });
         },
         renderCall(args, theme) {
             let text = theme.fg('toolTitle', theme.bold('pi-worker-search '));

package/dist/workers/pi-worker.js

@@ -9,7 +9,7 @@
 import { Text } from '@earendil-works/pi-tui';
 import { Type } from '@sinclair/typebox';
 import { runWorker } from './pi-worker-core.js';
-import { formatChildFailure, makeWorkerTool } from './shared.js';
+import { childFailureReason, formatChildFailure, makeWorkerTool, workerAnswer, workerUnavailable } from './shared.js';
 const RENDER_PROMPT_MAX = 120;
 const WorkerParams = Type.Object({
     prompt: Type.String({ description: 'Task for the worker to perform.' })
@@ -41,9 +41,10 @@ export function registerPiWorker(pi) {
             const result = await runWorker({ prompt: params.prompt, cwd: ctx.cwd, signal });
             const details = { exitCode: result.exitCode };
             const failure = formatChildFailure(result, 'Worker aborted.');
-            if (failure !== null)
-                return { text: failure, details };
-            return { text: result.text || '(no output)', details };
+            if (failure !== null) {
+                return workerUnavailable(failure, details, childFailureReason(result));
+            }
+            return workerAnswer(result.text || '(no output)', details);
         },
         renderCall(args, theme) {
             const prompt = args.prompt.replace(/\s+/g, ' ').trim();

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

@@ -1,7 +1,7 @@
 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';
+import { type SearchProvider, type SearchResult } from './search-types.js';
 export interface SearchCoreInput {
     query: string;
     count?: number;

package/dist/workers/search-core.js

@@ -1,12 +1,24 @@
 import { getConfig } from '../config/config.js';
-import { braveSearch as defaultBraveSearch, BraveSearchError } 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';
-function isLikeBraveSearchError(err) {
-    return (typeof err === 'object'
-        && err !== null
-        && err.name === 'BraveSearchError');
-}
+import { searchProviderKey, SEARCH_PROVIDER_LABELS } from './search-types.js';
+const SEARCH_ADAPTERS = {
+    exa: {
+        run: (input, _key, opts) => (input.exaSearch ?? defaultExaSearch)(input.query, opts)
+    },
+    ddg: {
+        run: (input, _key, opts) => (input.ddgSearch ?? defaultDdgSearch)(input.query, opts)
+    },
+    brave: {
+        run: (input, key, opts) => (input.braveSearch ?? defaultBraveSearch)(input.query, { ...opts, apiKey: key }),
+        missingKeyMessage: '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.',
+        errorName: 'BraveSearchError',
+        wrapUnknownError: m => `Brave Search request failed: ${m}`
+    }
+};
 /**
  * Provider selection is STRICT: the configured (or overridden) engine is the
  * only one tried — a failure reports as an error rather than silently switching
@@ -14,54 +26,36 @@ function isLikeBraveSearchError(err) {
  */
 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 adapter = SEARCH_ADAPTERS[provider];
     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) {
+    const key = searchProviderKey(provider, getEnv);
+    if (key === null) {
         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) or switch '
-                + 'the search provider in /task-config.'
+            message: adapter.missingKeyMessage
+                ?? `${SEARCH_PROVIDER_LABELS[provider]} search is not configured.`
         };
     }
     try {
-        const results = await braveSearch(input.query, {
-            apiKey,
-            count: input.count,
-            signal: input.signal
+        const results = await adapter.run(input, key, {
+            ...(input.count === undefined ? {} : { count: input.count }),
+            ...(input.signal === undefined ? {} : { signal: input.signal })
         });
         return { kind: 'ok', results };
     }
     catch (err) {
-        if (err instanceof BraveSearchError || isLikeBraveSearchError(err)) {
-            return { kind: 'error', message: err.message };
-        }
+        // Which throws already carry a finished user-facing message is the engine's
+        // own fact, so it is a row. This used to be an `err.name ===
+        // 'BraveSearchError'` STRING match in a brave-only branch — the check
+        // existed only because brave was reached down a different path from the
+        // other two, and it is the reason a subclass rename would have gone
+        // unnoticed.
+        const message = err instanceof Error ? err.message : String(err);
+        const known = adapter.errorName === undefined
+            || (err instanceof Error && err.name === adapter.errorName);
         return {
             kind: 'error',
-            message: `Brave Search request failed: ${err instanceof Error ? err.message : String(err)}`
+            message: known ? message : (adapter.wrapUnknownError?.(message) ?? message)
         };
     }
 }

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

@@ -12,6 +12,19 @@ export interface SearchResult {
  */
 export type SearchProvider = 'exa' | 'ddg' | 'brave';
 export declare const SEARCH_PROVIDERS: readonly SearchProvider[];
+/**
+ * The API-key env vars an engine needs, in lookup order. Empty = keyless.
+ *
+ * Declared beside the engine ids rather than inside `search()`, because two
+ * places ask the question: the search itself, and `searchConfigured` in
+ * phases.ts, which decides whether the APIS research worker is even given the
+ * search tool. That second copy was a hand-written re-statement of brave's env
+ * pair with a comment saying it "mirrors search-core's lookup" — the shape a
+ * table exists to make impossible.
+ */
+export declare const SEARCH_PROVIDER_KEY_ENV: Record<SearchProvider, readonly string[]>;
+/** The engine's key, or `null` when it needs one and none is set. `''` = keyless. */
+export declare function searchProviderKey(provider: SearchProvider, getEnv: (k: string) => string | undefined): string | null;
 /**
  * Human-readable engine names for the config UI. The short ids stay the stored
  * value (config-file compat); only the display layer uses these.

package/dist/workers/search-types.js

@@ -1,4 +1,31 @@
 export const SEARCH_PROVIDERS = ['exa', 'ddg', 'brave'];
+/**
+ * The API-key env vars an engine needs, in lookup order. Empty = keyless.
+ *
+ * Declared beside the engine ids rather than inside `search()`, because two
+ * places ask the question: the search itself, and `searchConfigured` in
+ * phases.ts, which decides whether the APIS research worker is even given the
+ * search tool. That second copy was a hand-written re-statement of brave's env
+ * pair with a comment saying it "mirrors search-core's lookup" — the shape a
+ * table exists to make impossible.
+ */
+export const SEARCH_PROVIDER_KEY_ENV = {
+    exa: [],
+    ddg: [],
+    brave: ['BRAVE_SEARCH_API_KEY', 'BRAVE_API_KEY']
+};
+/** The engine's key, or `null` when it needs one and none is set. `''` = keyless. */
+export function searchProviderKey(provider, getEnv) {
+    const vars = SEARCH_PROVIDER_KEY_ENV[provider];
+    if (vars.length === 0)
+        return '';
+    for (const v of vars) {
+        const value = getEnv(v);
+        if (value)
+            return value;
+    }
+    return null;
+}
 /**
  * Human-readable engine names for the config UI. The short ids stay the stored
  * value (config-file compat); only the display layer uses these.

package/dist/workers/shared.d.ts

@@ -2,6 +2,7 @@ import type { Static, TSchema } from '@sinclair/typebox';
 import type { AgentToolResult } from '@earendil-works/pi-agent-core';
 import type { ExtensionAPI, ExtensionContext, Theme } from '@earendil-works/pi-coding-agent';
 import type { Text } from '@earendil-works/pi-tui';
+import { type WorkerFailureInput } from './worker-failure.js';
 /** Build a plain-text AgentToolResult. */
 export declare function textResult<T>(text: string, details: T): AgentToolResult<T>;
 /**
@@ -22,21 +23,60 @@ export interface ChildOutcome {
  * (`pi-worker` skipped the `.trim()` the others applied).
  */
 export declare function formatChildFailure(child: ChildOutcome, abortedMessage: string): string | null;
+/**
+ * What a worker tool PRODUCED — an answer, or a statement that it has none.
+ *
+ * This used to be a bare `{text, details}` bag, and "did it succeed" was
+ * re-derived downstream from `details.childExitCode === 0`. That derivation was
+ * wrong in the one case it most needed to be right: a signal-killed child reports
+ * `code ?? 0` = 0 (shared/child-process.ts), so an aborted lookup arrived with
+ * exit code 0, `docsCacheable`/`fetchCacheable` said yes, and `"Docs lookup
+ * aborted."` was memoised for the whole run and re-served to every later sibling —
+ * exactly the failure `abstention.ts` exists to stop, with escalation unable to
+ * re-fire. `docsFailureResult`'s own contract said it recorded the code "NOT as
+ * 0"; the value it copied was 0.
+ *
+ * Stating the outcome makes that unrepresentable: `makeWorkerTool` stores only an
+ * `answer`, so no cache rule has to know anything about process health, and the
+ * `cacheable` predicates shrink to what they are actually about — answer quality.
+ */
+export type WorkerOutcome<TDetails> = {
+    kind: 'answer';
+    text: string;
+    details: TDetails;
+} | {
+    kind: 'unavailable';
+    text: string;
+    details: TDetails;
+    /**
+     * Why there is no answer, for the debug trail. A `WorkerFailureKind`
+     * where a child died (classifyWorkerFailure owns that precedence), or a
+     * short tag for the lookups that never got as far as a child.
+     */
+    reason: string;
+};
+/** This call produced an answer. Cacheable, subject to the tool's own rule. */
+export declare function workerAnswer<T>(text: string, details: T): WorkerOutcome<T>;
+/**
+ * The `reason` tag for a child that died, read off the ONE ladder that owns the
+ * precedence (`classifyWorkerFailure`). `'no-answer'` when nothing killed it and
+ * the caller still has no answer to give.
+ */
+export declare function childFailureReason(child: WorkerFailureInput): string;
+/** This call has no answer. NEVER cached, whatever the tool's rule says. */
+export declare function workerUnavailable<T>(text: string, details: T, reason: string): WorkerOutcome<T>;
 /**
  * What a worker tool is, minus the registration ritual: a name/label/schema,
- * a `run` that produces the focused text + structured details, and a `renderCall`
- * for the TUI. `makeWorkerTool` owns `registerTool`, the parallel execution mode,
- * and wrapping the result in `textResult`.
+ * a `run` that produces the outcome, and a `renderCall` for the TUI.
+ * `makeWorkerTool` owns `registerTool`, the parallel execution mode, and wrapping
+ * the result in `textResult`.
  */
 export interface WorkerToolSpec<TParams extends TSchema, TDetails> {
     name: string;
     label: string;
     description: string;
     parameters: TParams;
-    run(params: Static<TParams>, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<{
-        text: string;
-        details: TDetails;
-    }>;
+    run(params: Static<TParams>, signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<WorkerOutcome<TDetails>>;
     renderCall(args: Static<TParams>, theme: Theme): Text;
     /**
      * Per-run research-cache policy (F10). Return a stable cache key for this call —
@@ -57,10 +97,10 @@ export interface WorkerToolSpec<TParams extends TSchema, TDetails> {
      */
     cachePkg?(params: Static<TParams>): string | undefined;
     /**
-     * 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).
+     * Whether an ANSWER is safe to cache — a question about the answer's QUALITY
+     * (type-only, an abstention, an unverified excerpt), never about process
+     * health. An `unavailable` outcome never reaches this: `makeWorkerTool` has
+     * already refused it. Defaults to always-cacheable when omitted.
      */
     cacheable?(details: TDetails, text: string): boolean;
 }

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

@@ -0,0 +1,60 @@
+/**
+ * worker-channels — what a worker TOOL is, as data.
+ *
+ * `makeWorkerTool` already gives every worker tool one registration adapter, but
+ * `spec.name` never left the registration closure. So the same four name strings
+ * were re-typed as literals in three directories and had to agree by hand:
+ *
+ *   • `phases.ts` paired `'…,pi-worker-docs'` with `DOCS_EXTENSION_PATH`, and
+ *     `',pi-worker-search,pi-worker-fetch'` with `SEARCH_EXTENSION_PATH` — a tools
+ *     string and an `-e` path list that mean the same thing, written twice and
+ *     kept in step by eye.
+ *   • `GROUNDING_RETRIEVAL_TOOLS` was a second copy of the names.
+ *   • `summarizeToolArgs` was a third, and also re-stated each tool's parameter
+ *     shape (`module`/`query`, `query`, `url`).
+ *   • Worst for locality: `runWorker` — the GENERIC child runner — hardcoded one
+ *     tool's identity AND its parameter, `call.name === 'pi-worker-docs' &&
+ *     args.module === '.'`, to decide a fan-out deadline extension.
+ *
+ * A rename or a new tool was five edits in three directories with no compile
+ * error linking them. It is one row here now.
+ *
+ * What is NOT in a row: the tools string's non-worker members (`read`, `grep`,
+ * `find`, `ls`) are pi's own built-ins, not channels — they appear in
+ * {@link GROUNDING_RETRIEVAL_TOOLS} because grounding is about RETRIEVAL, not
+ * about which extension supplies it.
+ */
+/** One worker tool, and everything the rest of the codebase knows about it. */
+export interface WorkerChannel {
+    /** The tool name the model calls. The same string `WorkerToolSpec.name` declares. */
+    name: string;
+    /** The `-e` entry that registers it into a child pi. */
+    entryPath: string;
+    /** Does a call to this tool retrieve content a claim could be grounded in? */
+    grounding: boolean;
+    /** One line naming WHAT this call was about, for the debug log. */
+    summarize: (args: Record<string, unknown>) => string;
+    /**
+     * A call this tool's own consumers branch on. Only the docs channel has one:
+     * a `.` module is a PROJECT-SOURCE lookup, which reads the working tree
+     * rather than a package, and is what the fan-out deadline extends for.
+     *
+     * A property, not a method: it is read off the row and called on its own, so
+     * a method signature would invite an unbound `this`.
+     */
+    isProjectSourceLookup?: (args: Record<string, unknown>) => boolean;
+}
+export declare const WORKER_CHANNELS: readonly WorkerChannel[];
+/** The row for a tool call, or `undefined` when the tool is not a worker channel. */
+export declare function workerChannel(toolName: string): WorkerChannel | undefined;
+/**
+ * The tools string and the `-e` paths for a set of channels, together — they are
+ * one fact and used to be two literals. Entry paths are de-duplicated: search and
+ * fetch ship in one extension file.
+ */
+export declare function channelSet(names: readonly string[]): {
+    tools: string;
+    extensions: string[];
+};
+/** True when a tool call retrieves content an APIS entry could be grounded in. */
+export declare function isGroundingRetrieval(toolName: string): boolean;

package/dist/workers/worker-channels.js

@@ -0,0 +1,98 @@
+/**
+ * worker-channels — what a worker TOOL is, as data.
+ *
+ * `makeWorkerTool` already gives every worker tool one registration adapter, but
+ * `spec.name` never left the registration closure. So the same four name strings
+ * were re-typed as literals in three directories and had to agree by hand:
+ *
+ *   • `phases.ts` paired `'…,pi-worker-docs'` with `DOCS_EXTENSION_PATH`, and
+ *     `',pi-worker-search,pi-worker-fetch'` with `SEARCH_EXTENSION_PATH` — a tools
+ *     string and an `-e` path list that mean the same thing, written twice and
+ *     kept in step by eye.
+ *   • `GROUNDING_RETRIEVAL_TOOLS` was a second copy of the names.
+ *   • `summarizeToolArgs` was a third, and also re-stated each tool's parameter
+ *     shape (`module`/`query`, `query`, `url`).
+ *   • Worst for locality: `runWorker` — the GENERIC child runner — hardcoded one
+ *     tool's identity AND its parameter, `call.name === 'pi-worker-docs' &&
+ *     args.module === '.'`, to decide a fan-out deadline extension.
+ *
+ * A rename or a new tool was five edits in three directories with no compile
+ * error linking them. It is one row here now.
+ *
+ * What is NOT in a row: the tools string's non-worker members (`read`, `grep`,
+ * `find`, `ls`) are pi's own built-ins, not channels — they appear in
+ * {@link GROUNDING_RETRIEVAL_TOOLS} because grounding is about RETRIEVAL, not
+ * about which extension supplies it.
+ */
+import { fileURLToPath } from 'node:url';
+const DOCS_ENTRY = fileURLToPath(new URL('./docs-extension.js', import.meta.url));
+const SEARCH_ENTRY = fileURLToPath(new URL('./search-extension.js', import.meta.url));
+/** Clip an argument to one readable line. Shared by every row's `summarize`. */
+function clip(s) {
+    const one = s.replace(/\s+/g, ' ').trim();
+    return one.length > 60 ? one.slice(0, 59) + '…' : one;
+}
+export const WORKER_CHANNELS = [
+    {
+        name: 'pi-worker-docs',
+        entryPath: DOCS_ENTRY,
+        grounding: true,
+        summarize: a => typeof a.module === 'string' && typeof a.query === 'string' ?
+            `${a.module} "${clip(a.query)}"`
+            : '',
+        isProjectSourceLookup: a => a.module === '.'
+    },
+    {
+        name: 'pi-worker-search',
+        entryPath: SEARCH_ENTRY,
+        grounding: true,
+        // Without this the debug log shows a bare tool name and a run audit
+        // cannot tell WHAT was searched.
+        summarize: a => (typeof a.query === 'string' ? `"${clip(a.query)}"` : '')
+    },
+    {
+        name: 'pi-worker-fetch',
+        entryPath: SEARCH_ENTRY,
+        grounding: true,
+        summarize: a => (typeof a.url === 'string' ? clip(a.url) : '')
+    }
+];
+const BY_NAME = new Map(WORKER_CHANNELS.map(c => [c.name, c]));
+/** The row for a tool call, or `undefined` when the tool is not a worker channel. */
+export function workerChannel(toolName) {
+    return BY_NAME.get(toolName);
+}
+/**
+ * The tools string and the `-e` paths for a set of channels, together — they are
+ * one fact and used to be two literals. Entry paths are de-duplicated: search and
+ * fetch ship in one extension file.
+ */
+export function channelSet(names) {
+    // REFUSED, not dropped. Silently skipping an unrecognised name is the exact
+    // failure this table was built to eliminate: a typo or a half-finished rename
+    // yields a shorter tools string AND a shorter `-e` list, with no compile error
+    // and no runtime error, and the child just quietly loses a tool. At every call
+    // site that is indistinguishable from asking for fewer channels on purpose.
+    const unknown = names.filter(n => !BY_NAME.has(n));
+    if (unknown.length > 0) {
+        throw new Error(`channelSet: unknown worker channel(s): ${unknown.join(', ')}`);
+    }
+    const rows = names.map(n => BY_NAME.get(n)).filter((c) => c !== undefined);
+    return {
+        tools: rows.map(c => c.name).join(','),
+        extensions: [...new Set(rows.map(c => c.entryPath))]
+    };
+}
+/**
+ * Tool calls that retrieve content an APIS entry could be grounded in — the
+ * worker channels that say so, plus pi's own read/grep.
+ */
+const GROUNDING_RETRIEVAL_TOOLS = new Set([
+    'read',
+    'grep',
+    ...WORKER_CHANNELS.filter(c => c.grounding).map(c => c.name)
+]);
+/** True when a tool call retrieves content an APIS entry could be grounded in. */
+export function isGroundingRetrieval(toolName) {
+    return GROUNDING_RETRIEVAL_TOOLS.has(toolName);
+}

package/package.json

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