@mjasnikovs/pi-task 0.40.25 → 0.40.27

package/dist/workers/docs-chunk.js

@@ -99,6 +99,11 @@ export function splitAtMatches(text, re) {
  * possible hallucination. Only reachable on non-ASCII text past the chunk ceiling.
  */
 export function sliceBytes(s, maxBytes) {
+    // A non-positive cap never shrinks the buffer, so the loop below runs forever.
+    // Guarded here rather than at the callers: the cap is usually computed, and the
+    // next caller to compute one must not have to rediscover this.
+    if (maxBytes <= 0)
+        return s ? [s] : [];
     const out = [];
     let buf = Buffer.from(s, 'utf8');
     while (buf.length > maxBytes) {
@@ -134,8 +139,19 @@ export function headedSlices(header, body, maxBytes) {
     const prefixed = `${header}\n${body}`;
     if (Buffer.byteLength(prefixed, 'utf8') <= maxBytes)
         return [prefixed];
-    const room = maxBytes - Buffer.byteLength(`${header}\n`, 'utf8');
-    return sliceBytes(body, room).map(slice => `${header}\n${slice}`);
+    // The header is a LABEL, and `chunkReadme` builds it from an unbounded heading line.
+    // Left whole it starves the body: a header two bytes short of the cap turned a 200 KB
+    // section into 100,000 two-byte chunks, each re-carrying the 8 KB header. Splitting the
+    // cap evenly is the one division that needs no tuning, and a cut label still names the
+    // source.
+    const head = sliceBytes(header, Math.floor(maxBytes / 2))[0] ?? '';
+    const room = maxBytes - Buffer.byteLength(`${head}\n`, 'utf8');
+    // Only a cap of a byte or two reaches this. Slice the prefixed string and accept the
+    // degenerate result: the body pieces carry no provenance — the very defect this
+    // function exists to fix, but the alternative here is emitting nothing.
+    if (room <= 0)
+        return sliceBytes(prefixed, maxBytes);
+    return sliceBytes(body, room).map(slice => `${head}\n${slice}`);
 }
 /**
  * Chunk a declaration file, one chunk per declaration, each labelled with the

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

@@ -41,6 +41,12 @@ interface DocsDetails {
     /** The project-lookup budget for this attempt is spent, so the call was refused
      *  before any work. Only set when PI_TASK_PROJECT_DOCS_BUDGET is configured. */
     budgetSpent?: boolean;
+    /**
+     * The child declined to answer. Recorded HERE, at the one place the bare
+     * `<answer>` is in hand: the tool text a cache predicate is handed leads with a
+     * provenance header, and the anchored matcher scores that as a real answer.
+     */
+    abstained?: boolean;
 }
 /**
  * Pull `@see {@link https://…}` pointers out of retrieved .d.ts/README text.
@@ -70,15 +76,6 @@ export interface PiWorkerDocsInternals {
     npmVersionLookup?: typeof defaultNpmVersionLookup;
 }
 export declare function registerPiWorkerDocs(pi: ExtensionAPI, internals?: PiWorkerDocsInternals): void;
-/**
- * The cache rule for the docs channel, as a NAMED export rather than an anonymous
- * property of an adapter literal.
- *
- * As a property of the adapter literal it would be reachable only through
- * `registerTool → execute()`, so a test would have to retype the rule and would then
- * assert against its own copy — green even after the shipped rule changed. Exported,
- * the test imports the rule it is checking.
- */
 /**
  * Did the excerpt cite a word the source never wrote?
  *
@@ -89,7 +86,16 @@ export declare function registerPiWorkerDocs(pi: ExtensionAPI, internals?: PiWor
 export declare function excerptFabricated(check: {
     absent: readonly string[];
 } | undefined): boolean;
-export declare function docsCacheable(d: Pick<DocsDetails, 'typeOnly' | 'excerptVerified' | 'excerptFabricated'>, text: string): boolean;
+/**
+ * The cache rule for the docs channel, as a NAMED export rather than an anonymous
+ * property of an adapter literal.
+ *
+ * As a property of the adapter literal it would be reachable only through
+ * `registerTool → execute()`, so a test would have to retype the rule and would then
+ * assert against its own copy — green even after the shipped rule changed. Exported,
+ * the test imports the rule it is checking.
+ */
+export declare function docsCacheable(d: Pick<DocsDetails, 'typeOnly' | 'excerptVerified' | 'excerptFabricated' | 'abstained'>): boolean;
 /** The docs cache key: a package's answer is per (module, question), with the question
  *  lowercased and its whitespace collapsed so phrasing variants share one entry. Returns
  *  null for the project-source `.` lookup, which is never cached — the working tree

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

@@ -219,7 +219,8 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 return workerAnswer(text, {
                     ...baseDetails,
                     excerptVerified: verified,
-                    excerptFabricated: excerptFabricated(extraction.excerptCheck)
+                    excerptFabricated: excerptFabricated(extraction.excerptCheck),
+                    ...(isAbstention(extraction.answer) ? { abstained: true } : {})
                 });
             }
             // ── npm package lookup (existing path) ──────────────────────────
@@ -355,7 +356,8 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 ...baseDetails,
                 excerptVerified: verified,
                 excerptFabricated: excerptFabricated(extraction.excerptCheck),
-                ...(typeOnly.typeOnly ? { typeOnly: true } : {})
+                ...(typeOnly.typeOnly ? { typeOnly: true } : {}),
+                ...(isAbstention(extraction.answer) ? { abstained: true } : {})
             });
         },
         renderCall(args, theme) {
@@ -384,21 +386,9 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         // child that ran fine and answered "unclear from this package" exits 0 — so a rule
         // keyed on exit code would memoise that non-answer and re-serve it as a hit to
         // every later sibling, with nothing left to re-trigger an escalation.
-        //
-        // `text` is supplied by makeWorkerTool (shared.ts) alongside details, so the
-        // content check needs no new plumbing.
         cacheable: docsCacheable
     });
 }
-/**
- * The cache rule for the docs channel, as a NAMED export rather than an anonymous
- * property of an adapter literal.
- *
- * As a property of the adapter literal it would be reachable only through
- * `registerTool → execute()`, so a test would have to retype the rule and would then
- * assert against its own copy — green even after the shipped rule changed. Exported,
- * the test imports the rule it is checking.
- */
 /**
  * Did the excerpt cite a word the source never wrote?
  *
@@ -409,7 +399,16 @@ export function registerPiWorkerDocs(pi, internals = {}) {
 export function excerptFabricated(check) {
     return check !== undefined && check.absent.length > 0;
 }
-export function docsCacheable(d, text) {
+/**
+ * The cache rule for the docs channel, as a NAMED export rather than an anonymous
+ * property of an adapter literal.
+ *
+ * As a property of the adapter literal it would be reachable only through
+ * `registerTool → execute()`, so a test would have to retype the rule and would then
+ * assert against its own copy — green even after the shipped rule changed. Exported,
+ * the test imports the rule it is checking.
+ */
+export function docsCacheable(d) {
     // Answer QUALITY only. Whether there IS an answer is `WorkerOutcome.kind`, and
     // `makeWorkerTool` has already refused an `unavailable` before reaching here —
     // opening this with `childExitCode === 0` memoises an aborted lookup for the
@@ -420,7 +419,12 @@ export function docsCacheable(d, text) {
     // classifier defect 18 added, 41 of 41 unverified excerpts across seven runs are
     // STITCHED — every span verbatim, not one absent word. The gate was refusing
     // non-contiguous quoting, and every sibling paid a fresh child for it.
-    return d.typeOnly !== true && d.excerptFabricated !== true && !isAbstention(text);
+    //
+    // The abstention is read off DETAILS, not off the tool text. `makeWorkerTool`
+    // hands this the FINAL text, which leads with `Per <pkg>@<version>:` — and
+    // `isAbstention` is anchored, so testing that text scored every abstention as a
+    // real answer and memoised the dead end for the whole run.
+    return d.typeOnly !== true && d.excerptFabricated !== true && d.abstained !== true;
 }
 /** The docs cache key: a package's answer is per (module, question), with the question
  *  lowercased and its whitespace collapsed so phrasing variants share one entry. Returns

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

@@ -6,6 +6,8 @@ interface FetchDetails {
     answer?: string;
     excerpt?: string;
     excerptVerified?: boolean;
+    coverageMiss?: boolean;
+    anchoredSection?: string;
 }
 interface ProcLike extends EventEmitter {
     stdout: EventEmitter | null;
@@ -32,7 +34,7 @@ export declare function registerPiWorkerFetch(pi: ExtensionAPI, internals?: PiWo
  * ABOUT that page, and re-fetching cannot change it — only the abstention sentinel is
  * refused.
  */
-export declare function fetchCacheable(_d: Pick<FetchDetails, never>, text: string): boolean;
+export declare function fetchCacheable(d: Pick<FetchDetails, 'answer'>): 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: {

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

@@ -61,6 +61,8 @@ 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;
+                // Named, not inferred: `workerAnswer<T>` reads T off the literal, so a
+                // field added here would never reach the declaration the cache rules Pick from.
                 return workerAnswer(text, {
                     childExitCode: 0,
                     answer: result.answer,
@@ -112,12 +114,16 @@ export function registerPiWorkerFetch(pi, internals = {}) {
  * ABOUT that page, and re-fetching cannot change it — only the abstention sentinel is
  * refused.
  */
-export function fetchCacheable(_d, text) {
-    // Answer QUALITY only — see docsCacheable. This predicate returns true for
-    // `"Fetch aborted."` on its own; what keeps an aborted fetch out of the cache is
-    // the `unavailable` outcome upstream. Leading the rule with `childExitCode === 0`
-    // would not, because an aborted child settles at exit code 0.
-    return !isAbstention(text);
+export function fetchCacheable(d) {
+    // Answer QUALITY only — see docsCacheable. An aborted fetch is kept out of the
+    // cache by its `unavailable` outcome upstream, never by this rule; leading with
+    // `childExitCode === 0` would not work, because an aborted child settles at 0.
+    //
+    // It reads the child's bare answer, not the rendered tool text: `isAbstention` is
+    // anchored, and the text leads with an excerpt NOTE/WARNING whenever the excerpt
+    // did not verify — which, since rule 4 asks for the closest related text, is the
+    // ordinary shape of an abstention.
+    return d.answer !== undefined && !isAbstention(d.answer);
 }
 /** The fetch cache key. URL verbatim (path case can matter), question normalised —
  *  same page, different question is a different answer. */

package/dist/workers/shared.d.ts

@@ -99,8 +99,8 @@ export interface WorkerToolSpec<TParams extends TSchema, TDetails> {
      * 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 — joined with a literal NUL, which is why the
-     * separator is invisible to `grep` and to a plain editor.
+     * key is namespaced by tool name — joined with a NUL, a byte no tool name or key
+     * can contain, so no pair of them can collide by concatenation.
      */
     cacheKey?(params: Static<TParams>): string | null;
     /**
@@ -121,8 +121,12 @@ export interface WorkerToolSpec<TParams extends TSchema, TDetails> {
      * (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.
+     *
+     * It sees `details` only. Handed the rendered tool text as well, a rule reaches
+     * for it and reads a string that leads with provenance and excerpt notes — and an
+     * anchored abstention matcher then scores every abstention as an answer.
      */
-    cacheable?(details: TDetails, text: string): boolean;
+    cacheable?(details: TDetails): 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.40.25",
+    "version": "0.40.27",
     "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",