@mjasnikovs/pi-task 0.37.1 → 0.37.3

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

@@ -4,6 +4,7 @@ import { type ExcerptVerification } from '../shared/child-output.js';
 /** The exact non-answers the child is instructed to emit, matched at the tool layer. */
 export declare const UNCLEAR_ANSWER = "unclear from this page";
 export declare const NOT_COVERED_ANSWER = "not covered by this page";
+export declare function normaliseSourceUrl(url: string): string;
 export interface FetchRawInput {
     url: string;
     signal?: AbortSignal;
@@ -51,6 +52,15 @@ export interface FetchFocusedResult {
      * "page has no answer" and "answer is ambiguous" as the same thing (PROMPT-3 item 3).
      */
     coverageMiss: boolean;
+    /**
+     * What to do INSTEAD, present only on a coverage miss. `coverageMiss` was computed and
+     * stored and read nowhere, so the distinct channel it exists to provide never reached the
+     * worker: all it ever saw was the bare sentence "not covered by this page", which reads
+     * as "ask again, differently". It did — 9 of the 84 corpus fetches re-read a URL that had
+     * already returned a non-answer, one release-notes page three times with near-identical
+     * questions.
+     */
+    nextStep?: string;
     /** The #fragment slug that was anchored, when the URL carried one and it was located. */
     anchoredSection?: string;
     /** Retained evidence for a false `excerptVerified`, so it is diagnosable without re-fetch. */
@@ -63,6 +73,16 @@ export interface FetchFocusedResult {
     stdout: string;
 }
 export declare function fetchFocused(input: FetchFocusedInput): Promise<FetchFocusedResult>;
+/**
+ * The instruction that goes with a coverage miss. It says two things the bare sentinel does
+ * not: WHICH page was actually read (after the blob rewrite these differ, and a worker that
+ * cannot see that would "retry" the raw URL it already got), and that re-reading this page
+ * with a reworded question returns the same answer — so the next move is a different URL.
+ *
+ * Deliberately not a suggestion of WHICH other URL. Nothing at this layer knows one, and
+ * naming a guess is how a dead end becomes two dead ends.
+ */
+export declare function coverageMissNextStep(requestedUrl: string, fetchedUrl: string): string;
 export interface SelectedContent {
     content: string;
     /** The #fragment slug that was anchored, if the URL carried one AND it was located. */

package/dist/workers/fetch-core.js

@@ -11,18 +11,58 @@ const TRUNCATION_MARKER = '\n\n[...page continues, truncated...]\n\n';
 /** The exact non-answers the child is instructed to emit, matched at the tool layer. */
 export const UNCLEAR_ANSWER = 'unclear from this page';
 export const NOT_COVERED_ANSWER = 'not covered by this page';
-const NOT_COVERED_RE = /not covered by this page/i;
+/**
+ * Rule 6 asks the child to write the sentinel and NOTHING else, so the sentinel is the whole
+ * answer — anchored, not a substring search. A substring search misreads the opposite case:
+ * rule 5 tells the child to answer partially and say what is missing, and it says it in the
+ * prompt's own words ("… `obs_add_raw_audio_callback` and `obs_remove_raw_audio_callback`
+ * are not covered by this page"). That is a sourced answer, and the loose match filed it as
+ * a coverage miss. Observed twice in 5 reps of scripts/fetch-url-normalise-ab.ts once the
+ * rewrite started delivering pages that could half-answer; never in the 84 recorded corpus
+ * fetches, where 11 of 11 sentinel answers are the bare sentinel — so tightening it changes
+ * no recorded verdict.
+ */
+const NOT_COVERED_RE = /^not covered by this page[.\s]*$/i;
 const childArgs = () => [...childBaseArgs(), '--no-tools'];
+/**
+ * `github.com/{owner}/{repo}/blob/{ref}/{path}` renders the file through a client-side
+ * viewer, so the HTML we clean carries GitHub chrome ("Sign in", "Appearance settings")
+ * and none of the file. Every one of the 8 blob URLs in the three-project research-cache
+ * corpus came back a non-answer for that reason. `raw.githubusercontent.com` serves the
+ * same bytes as text/plain.
+ *
+ * Only the URL handed to the fetcher is rewritten — the caller's URL still keys the cache
+ * and still supplies the #fragment — so a worker that retries the raw URL by hand hits the
+ * cache, and a run's own recorded URLs stay what the run asked for.
+ *
+ * The query string is dropped: every blob query param (`?plain=1`, `?w=1`, …) is a viewer
+ * setting with no meaning on raw. The #fragment is dropped from the request too (it never
+ * reaches a server) but is preserved for {@link selectContent} via the original URL.
+ */
+const GH_BLOB_RE = /^https?:\/\/(?:www\.)?github\.com\/([^/?#]+)\/([^/?#]+)\/blob\/([^?#]+?)\/*(?:[?#].*)?$/i;
+export function normaliseSourceUrl(url) {
+    const m = GH_BLOB_RE.exec(url.trim());
+    if (!m)
+        return url;
+    const [, owner, repo, refAndPath] = m;
+    // `/blob/{ref}/{path}` — a bare `/blob/{ref}` with no path names no file.
+    if (!refAndPath.includes('/'))
+        return url;
+    return `https://raw.githubusercontent.com/${owner}/${repo}/${refAndPath}`;
+}
 export async function fetchRaw(input) {
     const fetchAndCleanFn = input.fetchAndClean ?? defaultFetchAndClean;
-    const cleaned = await fetchAndCleanFn(input.url, { signal: input.signal });
+    const cleaned = await fetchAndCleanFn(normaliseSourceUrl(input.url), {
+        signal: input.signal
+    });
     return { markdown: cleaned.markdown, finalUrl: cleaned.finalUrl, title: cleaned.title };
 }
 export async function fetchFocused(input) {
     const fetchAndCleanFn = input.fetchAndClean ?? defaultFetchAndClean;
     const spawnFn = input.spawn ?? defaultSpawn;
     const strategy = input.strategy ?? shippedStrategy;
-    const cleaned = await fetchAndCleanFn(input.url, { signal: input.signal });
+    const fetchedUrl = normaliseSourceUrl(input.url);
+    const cleaned = await fetchAndCleanFn(fetchedUrl, { signal: input.signal });
     // The #fragment is a client-side concern the server never sees, so anchor from the
     // ORIGINALLY REQUESTED url, not the post-redirect finalUrl (which will have dropped it).
     const selected = strategy.selectContent(cleaned.markdown, input.url);
@@ -60,6 +100,7 @@ export async function fetchFocused(input) {
         };
     }
     const parsed = parseChildOutput(childResult.stdout);
+    const coverageMiss = NOT_COVERED_RE.test(parsed.answer.trim());
     // Verify against the FULL page, not the anchored slice: the slice is a substring of it,
     // so a genuine excerpt still verifies, and an excerpt the child pulled from memory still
     // fails — the detector's discrimination is unchanged by fragment anchoring.
@@ -69,12 +110,32 @@ export async function fetchFocused(input) {
         excerpt: parsed.excerpt,
         excerptVerified: check?.verified,
         excerptCheck: check,
-        coverageMiss: NOT_COVERED_RE.test(parsed.answer),
+        coverageMiss,
+        nextStep: coverageMiss ? coverageMissNextStep(input.url, fetchedUrl) : undefined,
         childExitCode: 0,
         aborted: false,
         ...base
     };
 }
+/**
+ * The instruction that goes with a coverage miss. It says two things the bare sentinel does
+ * not: WHICH page was actually read (after the blob rewrite these differ, and a worker that
+ * cannot see that would "retry" the raw URL it already got), and that re-reading this page
+ * with a reworded question returns the same answer — so the next move is a different URL.
+ *
+ * Deliberately not a suggestion of WHICH other URL. Nothing at this layer knows one, and
+ * naming a guess is how a dead end becomes two dead ends.
+ */
+export function coverageMissNextStep(requestedUrl, fetchedUrl) {
+    const rewritten = fetchedUrl !== requestedUrl ?
+        ` ${requestedUrl} is a GitHub file viewer whose HTML does not carry the file, so the`
+            + ` file itself was already read from ${fetchedUrl} — fetching that raw URL by hand`
+            + ` returns exactly this.`
+        : '';
+    return (`NEXT STEP: this page does not contain the answer.${rewritten}`
+        + ` Asking ${fetchedUrl} the same question a different way returns this same result —`
+        + ` do not re-read it. Try a different URL, or search for one.`);
+}
 /** Read the #fragment from a URL. Empty string when there is none. */
 function fragmentOf(url) {
     const h = url.indexOf('#');

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

@@ -52,7 +52,11 @@ export function registerPiWorkerFetch(pi, internals = {}) {
                 if (failure !== null) {
                     return { text: failure, details: { childExitCode: result.childExitCode } };
                 }
-                const text = formatResultText({ answer: result.answer, excerpt: result.excerpt }, result.excerptVerified) || '(no output)';
+                const body = formatResultText({ 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.
+                const text = result.nextStep ? `${body}\n\n${result.nextStep}` : body;
                 return {
                     text,
                     details: {

package/package.json

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