@mjasnikovs/pi-task 0.38.10 → 0.38.11

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

@@ -12,4 +12,17 @@ export interface RetrieveOptions {
     limit?: number;
     contentBudget?: number;
 }
+/**
+ * How many chunks a retrieval returns, per corpus.
+ *
+ * The two values differ and always have; this is the first place they sit side by
+ * side, and no comment in the history explains WHY an npm package gets 8 and
+ * project source gets 50. Recorded as-is rather than harmonised: changing either is
+ * a retrieval-policy change with its own A/B, not a tidy-up. Before this they were
+ * three declarations across three files, so the divergence was invisible.
+ */
+export declare const PACKAGE_RETRIEVE_LIMIT = 8;
+export declare const PROJECT_RETRIEVE_LIMIT = 50;
+/** Character budget for the assembled chunk text. The same for both corpora. */
+export declare const RETRIEVE_CONTENT_BUDGET = 24000;
 export declare function retrieveChunks(cache: CacheHandle, opts: RetrieveOptions): RetrievedChunk[];

package/dist/workers/docs-retrieve.js

@@ -1,5 +1,20 @@
-const DEFAULT_LIMIT = 50;
-const DEFAULT_BUDGET = 24_000;
+/**
+ * How many chunks a retrieval returns, per corpus.
+ *
+ * The two values differ and always have; this is the first place they sit side by
+ * side, and no comment in the history explains WHY an npm package gets 8 and
+ * project source gets 50. Recorded as-is rather than harmonised: changing either is
+ * a retrieval-policy change with its own A/B, not a tidy-up. Before this they were
+ * three declarations across three files, so the divergence was invisible.
+ */
+export const PACKAGE_RETRIEVE_LIMIT = 8;
+export const PROJECT_RETRIEVE_LIMIT = 50;
+/** Character budget for the assembled chunk text. The same for both corpora. */
+export const RETRIEVE_CONTENT_BUDGET = 24_000;
+// Both callers always pass `limit`/`contentBudget` explicitly, so these defaults are
+// only a backstop for a third caller that does not.
+const DEFAULT_LIMIT = PROJECT_RETRIEVE_LIMIT;
+const DEFAULT_BUDGET = RETRIEVE_CONTENT_BUDGET;
 const MIN_TOKEN_LEN = 2;
 const FALLBACK_DTS_CHARS = 12_000;
 const FALLBACK_README_CHARS = 4_000;

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

@@ -104,7 +104,3 @@ export interface SelectedContent {
 export declare function selectContent(markdown: string, requestedUrl: string): SelectedContent;
 /** The shipped strategy: fragment-aware selection + the recalibrated prompt. */
 export declare const shippedStrategy: PromptStrategy;
-export declare function formatResultText(parsed: {
-    answer: string;
-    excerpt?: string;
-}, verified: boolean | undefined): string;

package/dist/workers/fetch-core.js

@@ -1,7 +1,6 @@
 import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
 import { runFocusedExtraction } from './focused-extractor.js';
 import { abstentionSentence } from './abstention.js';
-import { formatResultText as formatResultTextShared } from '../shared/child-output.js';
 const CONTENT_BUDGET = 30_000;
 const HEAD_CHARS = 25_000;
 const TAIL_CHARS = 5_000;
@@ -243,7 +242,5 @@ function buildPrompt(args) {
 }
 /** The shipped strategy: fragment-aware selection + the recalibrated prompt. */
 export const shippedStrategy = { selectContent, buildPrompt };
-// ─── Thin wrapper: fetch-core formatResultText (no header) ───────────────────
-export function formatResultText(parsed, verified) {
-    return formatResultTextShared('', parsed, verified);
-}
+// A fetch answer carries no package header, so the shared formatter is bound with an
+// empty one at the single call site rather than behind a wrapper of its own.

package/dist/workers/phantom-imports.d.ts

@@ -26,14 +26,14 @@ export interface RuntimeImportVerdict {
  */
 export declare function classifyRuntimeImport(spec: string, runtime: string, sub: string, typeText: string): RuntimeImportVerdict;
 /** Default loader: resolve the runtime's installed types and read their .d.ts. */
-export declare function loadRuntimeTypeText(runtime: string, cwd: string): string | null;
+export declare function loadRuntimeTypeText(runtime: string, cwd: string): Promise<string | null>;
 /**
  * Scan `text` for runtime-namespace specifiers and return the ones the installed
  * types do not declare. `loadText` is injectable for tests; in production it reads
  * the runtime's type package. A runtime whose types can't be loaded is skipped
  * (we never flag what we can't verify), so this is silent when types are absent.
  */
-export declare function findPhantomImports(text: string, cwd: string, loadText?: (runtime: string, cwd: string) => string | null): PhantomImport[];
+export declare function findPhantomImports(text: string, cwd: string, loadText?: (runtime: string, cwd: string) => string | null | Promise<string | null>): Promise<PhantomImport[]>;
 /** Render flagged phantoms as an authoritative research section, or '' if none. */
 export declare function formatApiCorrections(phantoms: PhantomImport[]): string;
 /**
@@ -54,7 +54,7 @@ export declare function formatApiOverrideBanner(phantoms: PhantomImport[]): stri
  * Unreadable mentions are skipped; silent when types are absent or nothing is flagged.
  * Drives the impl-handoff override banner (Layer B).
  */
-export declare function findDeliveryPhantoms(spec: string, cwd: string): PhantomImport[];
+export declare function findDeliveryPhantoms(spec: string, cwd: string): Promise<PhantomImport[]>;
 /**
  * Subtractively rewrite every flagged phantom specifier in `text` to the canonical
  * import the installed types prove, so NO affirmative occurrence of the non-existent

package/dist/workers/phantom-imports.js

@@ -13,7 +13,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { resolvePackage, splitRuntimeNamespace, detectTypesRedirect, typesPackageName, hasTypeFiles, isDtsFile, ResolveError } from './docs-resolve.js';
+import { resolvePackage, splitRuntimeNamespace, hasTypeFiles, isDtsFile, resolveTypeSource, ResolveError } from './docs-resolve.js';
 // Runtime builtin specifiers as they appear in prose/code: `bun:sql`,
 // `node:fs/promises`. Bounded to the runtimes splitRuntimeNamespace accepts.
 const SPEC_RE = /\b(?:bun|node|deno):[a-z0-9][a-z0-9/_-]*/gi;
@@ -67,40 +67,27 @@ function suggestionFor(v, runtime) {
     return (`\`${v.spec}\` is NOT a real module.${list} Import the needed symbol from `
         + `"${runtime}" or verify the correct specifier with pi-worker-docs; do not declare a module for it.`);
 }
-/** Sync resolution of a runtime to the package that actually holds its type
- *  declarations (bun -> @types/bun -> bun-types), bounded to a few hops. No
- *  auto-install: a runtime whose types aren't installed simply can't be verified
- *  (returns null), so we never flag what we can't prove. */
-function resolveRuntimeTypesRoot(runtime, cwd) {
-    let cur;
+/** The phantom-import checker's adapter over the shared redirect walk: hops resolve
+ *  SYNCHRONOUSLY and never install. A runtime whose types aren't on disk simply
+ *  can't be verified (null), so we never flag what we can't prove. */
+async function resolveRuntimeTypesRoot(runtime, cwd) {
+    let start;
     try {
-        cur = resolvePackage(runtime, cwd);
+        start = resolvePackage(runtime, cwd);
     }
     catch (err) {
         if (err instanceof ResolveError)
             return null;
         throw err;
     }
-    const visited = new Set([cur.name, runtime]);
-    for (let hop = 0; hop < 3; hop++) {
-        let next = detectTypesRedirect(cur);
-        if (next && visited.has(next))
-            next = null;
-        if (!next && !hasTypeFiles(cur.root)) {
-            const types = typesPackageName(cur.name);
-            if (types && !visited.has(types))
-                next = types;
-        }
-        if (!next)
-            break;
-        visited.add(next);
+    const cur = await resolveTypeSource(start, runtime, next => {
         try {
-            cur = resolvePackage(next, cwd);
+            return Promise.resolve(resolvePackage(next, cwd));
         }
         catch {
-            break;
+            return Promise.resolve(null);
         }
-    }
+    });
     return hasTypeFiles(cur.root) ? cur.root : null;
 }
 const MAX_TYPE_BYTES = 4_000_000;
@@ -141,8 +128,8 @@ function readRuntimeTypeText(root) {
     return parts.join('\n');
 }
 /** Default loader: resolve the runtime's installed types and read their .d.ts. */
-export function loadRuntimeTypeText(runtime, cwd) {
-    const root = resolveRuntimeTypesRoot(runtime, cwd);
+export async function loadRuntimeTypeText(runtime, cwd) {
+    const root = await resolveRuntimeTypesRoot(runtime, cwd);
     if (!root)
         return null;
     const text = readRuntimeTypeText(root);
@@ -154,7 +141,7 @@ export function loadRuntimeTypeText(runtime, cwd) {
  * the runtime's type package. A runtime whose types can't be loaded is skipped
  * (we never flag what we can't verify), so this is silent when types are absent.
  */
-export function findPhantomImports(text, cwd, loadText = loadRuntimeTypeText) {
+export async function findPhantomImports(text, cwd, loadText = loadRuntimeTypeText) {
     const out = [];
     const typeTextByRuntime = new Map();
     for (const spec of extractRuntimeSpecifiers(text)) {
@@ -162,7 +149,7 @@ export function findPhantomImports(text, cwd, loadText = loadRuntimeTypeText) {
         if (!ns)
             continue;
         if (!typeTextByRuntime.has(ns.runtime)) {
-            typeTextByRuntime.set(ns.runtime, loadText(ns.runtime, cwd));
+            typeTextByRuntime.set(ns.runtime, await loadText(ns.runtime, cwd));
         }
         const typeText = typeTextByRuntime.get(ns.runtime);
         if (!typeText)
@@ -219,7 +206,7 @@ const MENTION_TRAILING_PUNCT = /[.,;:!?)\]}>"']+$/;
  * Unreadable mentions are skipped; silent when types are absent or nothing is flagged.
  * Drives the impl-handoff override banner (Layer B).
  */
-export function findDeliveryPhantoms(spec, cwd) {
+export async function findDeliveryPhantoms(spec, cwd) {
     let text = spec;
     const seen = new Set();
     for (const m of spec.matchAll(MENTION_RE)) {

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

@@ -5,6 +5,32 @@ import { resolvePackage as defaultResolvePackage } from './docs-resolve.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
 import type { SpawnFn } from '../shared/child-process.js';
+interface DocsDetails {
+    version?: string;
+    hitCache?: boolean;
+    chunksRetrieved?: number;
+    excerptVerified?: boolean;
+    childExitCode?: number;
+    indexingMs?: number;
+    indexedFiles?: number;
+    resolveError?: 'not_installed' | 'invalid_name';
+    cacheError?: string;
+    aborted?: boolean;
+    autoInstalled?: boolean;
+    installError?: string;
+    npmLatest?: string;
+    npmPublishedAt?: string;
+    versionSource?: 'declared-range' | 'npm-latest';
+    declaredRange?: string;
+    /**
+     * The answer restated a declaration for a question that needed usage semantics, so it
+     * is UNANSWERED (F-2). Set by isTypeOnlyAnswer; read by `cacheable` so a non-answer is
+     * never memoised and re-served to a later sibling task.
+     */
+    typeOnly?: boolean;
+    /** The 5B CAP arm refused this call: the attempt's project-lookup budget is spent. */
+    budgetSpent?: boolean;
+}
 /**
  * Pull `@see {@link https://…}` pointers out of retrieved .d.ts/README text.
  *
@@ -30,3 +56,26 @@ export interface PiWorkerDocsInternals {
     npmVersionLookup?: typeof defaultNpmVersionLookup;
 }
 export declare function registerPiWorkerDocs(pi: ExtensionAPI, internals?: PiWorkerDocsInternals): void;
+/**
+ * The F-2(e) cache rule for the docs channel, as a NAMED export rather than an
+ * anonymous property of an adapter literal.
+ *
+ * It was reachable only through `registerTool → execute()`, so
+ * pi-worker-docs-typeonly.test.ts gave up and hand-retyped it under a
+ * "keep in sync" comment — six tests asserting against a copy that a change to the
+ * shipped rule would leave green. That is the same drift class the rule itself
+ * exists to prevent: four regexes matching three phrasings, documented at length in
+ * abstention.ts, which cost a real bug.
+ */
+export declare function docsCacheable(d: Pick<DocsDetails, 'childExitCode' | 'typeOnly' | 'excerptVerified'>, text: string): boolean;
+/** The docs cache key: a package's answer is per (module, question). A project-source
+ *  `.` lookup is never cached — the working tree mutates as tasks implement. */
+export declare function docsCacheKey(params: {
+    module: string;
+    query: string;
+}): string | null;
+/** Package provenance for per-entry resume invalidation. */
+export declare function docsCachePkg(params: {
+    module: string;
+}): string | undefined;
+export {};

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

@@ -3,7 +3,8 @@ import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
 import { openCache as defaultOpenCache } from './docs-cache.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
-import { docsRaw, formatResultText, packageHeader, buildPrompt, buildVersionBanner } from './docs-core.js';
+import { formatResultText } from '../shared/child-output.js';
+import { docsRaw, packageHeader, buildPrompt, buildVersionBanner } from './docs-core.js';
 import { formatNpmVersionSection } from './npm-version.js';
 import { runFocusedExtraction } from './focused-extractor.js';
 import { makeWorkerTool } from './shared.js';
@@ -374,15 +375,13 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         // 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)}`,
+        cacheKey: docsCacheKey,
         // Package provenance for per-entry resume invalidation: a docs digest describes
         // one package at one declared version, so a resume drops it only when THAT
         // package moves — an unrelated install no longer discards it. Package names are
         // matched against package.json verbatim (npm names are case-sensitive), unlike
         // the cache key, which normalises for phrasing collisions.
-        cachePkg: params => (params.module === '.' ? undefined : packageRootOf(params.module)),
+        cachePkg: docsCachePkg,
         // 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.
@@ -396,9 +395,34 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         //
         // `text` is supplied by makeWorkerTool (shared.ts) alongside details, so the
         // content check needs no new plumbing.
-        cacheable: (d, text) => d.childExitCode === 0
-            && d.typeOnly !== true
-            && d.excerptVerified !== false
-            && !isAbstention(text)
+        cacheable: docsCacheable
     });
 }
+/**
+ * The F-2(e) cache rule for the docs channel, as a NAMED export rather than an
+ * anonymous property of an adapter literal.
+ *
+ * It was reachable only through `registerTool → execute()`, so
+ * pi-worker-docs-typeonly.test.ts gave up and hand-retyped it under a
+ * "keep in sync" comment — six tests asserting against a copy that a change to the
+ * shipped rule would leave green. That is the same drift class the rule itself
+ * exists to prevent: four regexes matching three phrasings, documented at length in
+ * abstention.ts, which cost a real bug.
+ */
+export function docsCacheable(d, text) {
+    return (d.childExitCode === 0
+        && d.typeOnly !== true
+        && d.excerptVerified !== false
+        && !isAbstention(text));
+}
+/** The docs cache key: a package's answer is per (module, question). A project-source
+ *  `.` lookup is never cached — the working tree mutates as tasks implement. */
+export function docsCacheKey(params) {
+    return params.module === '.' ?
+        null
+        : `${normalizeQuery(params.module)}::${normalizeQuery(params.query)}`;
+}
+/** Package provenance for per-entry resume invalidation. */
+export function docsCachePkg(params) {
+    return params.module === '.' ? undefined : packageRootOf(params.module);
+}

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

@@ -1,6 +1,12 @@
 import type { EventEmitter } from 'node:events';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { fetchAndClean as defaultFetchAndClean } from './html-clean.js';
+interface FetchDetails {
+    childExitCode?: number;
+    answer?: string;
+    excerpt?: string;
+    excerptVerified?: boolean;
+}
 interface ProcLike extends EventEmitter {
     stdout: EventEmitter | null;
     stderr: EventEmitter | null;
@@ -17,4 +23,16 @@ export interface PiWorkerFetchInternals {
     spawn?: SpawnFn;
 }
 export declare function registerPiWorkerFetch(pi: ExtensionAPI, internals?: PiWorkerFetchInternals): void;
+/**
+ * The F-2(e) cache rule for the fetch channel, named for the same reason as
+ * `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 declare function fetchCacheable(d: Pick<FetchDetails, 'childExitCode'>, text: string): boolean;
+/** The fetch cache key. URL verbatim (path case can matter), question normalised —
+ *  same page, different question is a different answer. */
+export declare function fetchCacheKey(params: {
+    url: string;
+    query: string;
+}): string;
 export {};

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

@@ -1,7 +1,8 @@
 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 { fetchFocused } from './fetch-core.js';
+import { formatResultText } from '../shared/child-output.js';
 import { makeWorkerTool } from './shared.js';
 import { normalizeQuery } from './research-cache.js';
 import { isAbstention } from './abstention.js';
@@ -51,7 +52,8 @@ export function registerPiWorkerFetch(pi, internals = {}) {
                 if (result.failure !== undefined) {
                     return { text: result.failure, details: { childExitCode: result.childExitCode } };
                 }
-                const body = formatResultText({ answer: result.answer, excerpt: result.excerpt }, result.excerptVerified) || '(no output)';
+                const body = formatResultText('', // a fetched page answer carries no package header
+                { answer: result.answer, excerpt: result.excerpt }, result.excerptVerified) || '(no output)';
                 // The coverage miss is the one outcome that carries an instruction. It goes
                 // in the TEXT, not only in details: details are for the harness, and the
                 // worker acts on what it reads.
@@ -90,7 +92,7 @@ export function registerPiWorkerFetch(pi, internals = {}) {
         // 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)}`,
+        cacheKey: fetchCacheKey,
         // Only a completed fetch (child exited 0) is a real answer; invalid-URL,
         // fetch failures, and aborts omit childExitCode:0 and fall through.
         // F-2(e), on the fetch channel. A child that ran fine and answered
@@ -99,6 +101,19 @@ export function registerPiWorkerFetch(pi, internals = {}) {
         // the same dead-end-paid-many-times shape pi-worker-docs already closed
         // for packages, with escalation unable to re-fire because the miss never
         // recurred. One predicate now covers every corpus (workers/abstention.ts).
-        cacheable: (d, text) => d.childExitCode === 0 && !isAbstention(text)
+        cacheable: fetchCacheable
     });
 }
+/**
+ * The F-2(e) cache rule for the fetch channel, named for the same reason as
+ * `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);
+}
+/** The fetch cache key. URL verbatim (path case can matter), question normalised —
+ *  same page, different question is a different answer. */
+export function fetchCacheKey(params) {
+    return `${params.url.trim()}::${normalizeQuery(params.query)}`;
+}

package/package.json

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