@mjasnikovs/pi-task 0.16.3 → 0.16.4

package/dist/task/phases.js

@@ -9,6 +9,7 @@ import { runWorker } from '../workers/pi-worker-core.js';
 import { findPhantomImports, formatApiCorrections, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
 import { search as defaultSearch } from '../workers/search-core.js';
 import { extractEnrichTargets } from './enrichment.js';
+import { isIntegrationUnknown } from './unknown-routing.js';
 import { getFileInventory } from './file-inventory.js';
 import { buildOrientation } from './orientation.js';
 import { getConfig } from '../config/config.js';
@@ -459,7 +460,21 @@ export async function phaseAutoAnswer(deps, refined, research, question, autoDep
             // otherwise a preamble line leaks out as the recommended answer.
             text = await runPhaseChild(deps, 'grill-auto', 'read', prependHint(GRILL_AUTO_FORMAT_HINT, basePrompt));
         }
-        return parseAutoAnswer(text);
+        const parsed = parseAutoAnswer(text);
+        // Surviving-unknown routing: an integration / build-wiring unknown whose
+        // wrong guess is a structural landmine must NOT be silently auto-answered.
+        // We first try to ground it from fetched docs (the enrichment fan-out
+        // above); only when NO doc/fetch worker produced a grounding section do we
+        // refuse the guess and surface it to the user — carrying the model's
+        // best-effort answer as the pre-filled recommendation so the user accepts
+        // it with one keystroke or overrides it. Benign unknowns are untouched.
+        const docResolved = docSections.filter(Boolean).length > 0;
+        if (parsed.kind === 'answered' && !docResolved && isIntegrationUnknown(question)) {
+            deps.logDebug?.(`grill-auto: integration unknown unresolved by fetch — surfacing to user `
+                + `instead of auto-answering: ${question.replace(/\s+/g, ' ').slice(0, 120)}`);
+            return { kind: 'unknown', suggested: parsed.text, raw: parsed.raw };
+        }
+        return parsed;
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);

package/dist/task/unknown-routing.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Surviving-unknown routing.
+ *
+ * The grill phase generates one clarifying question per KNOWN-UNKNOWN and lets a
+ * `grill-auto` child either auto-answer it (ANSWER → the user never sees it) or
+ * surface it (UNKNOWN → asked). The dangerous class is an integration / build-
+ * wiring unknown — "how is this plugin wired into the build", "should the import
+ * structure in the HTML entry change" — which `grill-auto` happily auto-answers
+ * with a GUESS that then ships as a silent landmine (a real run shipped an
+ * unstyled build this way).
+ *
+ * This classifier identifies that class so the orchestrator can route it: try to
+ * resolve it from fetched docs first, and if nothing grounded the answer, surface
+ * it to the user instead of letting the guess stand. Pure + deterministic so it
+ * is unit-tested independently of the model.
+ *
+ * Deliberately GENERIC: it keys on build/tooling CATEGORIES (plugin, bundler,
+ * loader, build pipeline, entry point, …) and wiring INTENT (wire, integrate,
+ * configure, set up, how/where to …), never on any specific tool or project.
+ */
+/**
+ * True when `question` is an integration / build-wiring unknown — one whose
+ * wrong guess is a structural landmine, so it must be resolved by a worker or
+ * surfaced to the user rather than auto-answered. Requires BOTH a tooling-surface
+ * mention and wiring intent, so benign questions ("which log format?", "what
+ * default page size?", "which file holds the auth handler?") do not trip it.
+ */
+export declare function isIntegrationUnknown(question: string): boolean;

package/dist/task/unknown-routing.js

@@ -0,0 +1,38 @@
+/**
+ * Surviving-unknown routing.
+ *
+ * The grill phase generates one clarifying question per KNOWN-UNKNOWN and lets a
+ * `grill-auto` child either auto-answer it (ANSWER → the user never sees it) or
+ * surface it (UNKNOWN → asked). The dangerous class is an integration / build-
+ * wiring unknown — "how is this plugin wired into the build", "should the import
+ * structure in the HTML entry change" — which `grill-auto` happily auto-answers
+ * with a GUESS that then ships as a silent landmine (a real run shipped an
+ * unstyled build this way).
+ *
+ * This classifier identifies that class so the orchestrator can route it: try to
+ * resolve it from fetched docs first, and if nothing grounded the answer, surface
+ * it to the user instead of letting the guess stand. Pure + deterministic so it
+ * is unit-tested independently of the model.
+ *
+ * Deliberately GENERIC: it keys on build/tooling CATEGORIES (plugin, bundler,
+ * loader, build pipeline, entry point, …) and wiring INTENT (wire, integrate,
+ * configure, set up, how/where to …), never on any specific tool or project.
+ */
+// Factor A — the question concerns a build/tooling integration surface, not a
+// value, a name, an output format, or a file location.
+const TOOLING_CONCERN_RE = /\b(?:plugins?|bundlers?|loaders?|middlewares?|adapters?|toolchains?|transpilers?|compilers?|build\s+(?:pipeline|step|process|chain|config|tool|system)|import\s+structure|entry[\s-]*points?|dev[\s-]*servers?|module\s+resolution|build\s+wiring|wiring)\b/i;
+// Factor B — the question is about HOW to connect/configure that surface (or
+// expresses uncertainty about where something hooks in), not which value to pick.
+const WIRING_INTENT_RE = /\b(?:wir(?:e|ed|ing)|integrat(?:e|ed|es|ing|ion)|hook(?:ed|s|ing)?\s+(?:it\s+|them\s+)?(?:up|in|into)|plug(?:ged|s|ging)?\s+(?:it\s+|them\s+)?(?:in|into)|configur(?:e|ed|es|ing|ation)|set[\s-]*up|register(?:ed|s|ing)?|mount(?:ed|s|ing)?|how\s+(?:to|do|does|should|is|are)|where\s+(?:to|should|does|is))\b/i;
+/**
+ * True when `question` is an integration / build-wiring unknown — one whose
+ * wrong guess is a structural landmine, so it must be resolved by a worker or
+ * surfaced to the user rather than auto-answered. Requires BOTH a tooling-surface
+ * mention and wiring intent, so benign questions ("which log format?", "what
+ * default page size?", "which file holds the auth handler?") do not trip it.
+ */
+export function isIntegrationUnknown(question) {
+    if (!question)
+        return false;
+    return TOOLING_CONCERN_RE.test(question) && WIRING_INTENT_RE.test(question);
+}

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

@@ -4,6 +4,19 @@ import { resolvePackage as defaultResolvePackage, type ResolvedPackage } from '.
 import { retrieveChunks as defaultRetrieveChunks, type RetrievedChunk } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup, type NpmVersionInfo } from './npm-version.js';
 import { type SpawnFn } from '../shared/child-process.js';
+/**
+ * Provenance of an auto-installed package's version, so the answer can state
+ * what the version is grounded in instead of leaving it buried in tool details.
+ * - 'declared-range': install was pinned to the project's own package.json range
+ *   (the resolved version therefore matches project intent).
+ * - 'npm-latest': nothing in the project declared the dep, so the install fell
+ *   back to whatever npm tags `latest` — which may be a newer MAJOR than the
+ *   project targets (this is what a scaffolding task hits, and needs a banner).
+ */
+export interface AutoInstallPin {
+    source: 'declared-range' | 'npm-latest';
+    range?: string;
+}
 export type DocsRawResult = {
     kind: 'ok';
     pkg: ResolvedPackage;
@@ -13,6 +26,7 @@ export type DocsRawResult = {
     indexedFiles?: number;
     cacheError?: string;
     autoInstalled?: boolean;
+    autoInstallPin?: AutoInstallPin;
     npmVersion?: NpmVersionInfo | null;
 } | {
     kind: 'not_installed';
@@ -25,6 +39,7 @@ export type DocsRawResult = {
     indexedFiles?: number;
     cacheError?: string;
     autoInstalled?: boolean;
+    autoInstallPin?: AutoInstallPin;
     npmVersion?: NpmVersionInfo | null;
 } | {
     kind: 'error';
@@ -35,6 +50,7 @@ export type DocsRawResult = {
     hitCache?: boolean;
     cacheError?: string;
     autoInstalled?: boolean;
+    autoInstallPin?: AutoInstallPin;
     npmVersion?: NpmVersionInfo | null;
 };
 export interface DocsRawInput {
@@ -69,9 +85,28 @@ export interface DocsFocusedResult {
 }
 export type DocsFocusedInput = DocsRawInput;
 export declare function extractParentPackage(moduleName: string): string;
+/**
+ * The version range a project DECLARES for `parentPkg` in its package.json under
+ * `cwd`. Lets a not-yet-installed scaffolding dependency be documented against
+ * the major the project intends, instead of whatever npm currently tags
+ * `latest`. Scans the four standard dependency maps in priority order. Returns
+ * null — caller falls back to latest — when the dep is undeclared, the
+ * package.json is missing/unreadable, or the declared value is not a usable
+ * range. Best-effort; never throws.
+ */
+export declare function findDeclaredRange(parentPkg: string, cwd: string): string | null;
+/**
+ * One-line version-provenance banner that LEADS a docs answer for a package the
+ * worker had to auto-install (not yet present in node_modules — every
+ * scaffolding task). Surfaces the version the answer is grounded in directly in
+ * the prose the impl model reads, rather than burying it in tool `details`.
+ * Empty string when there was no auto-install (already-installed packages need
+ * no banner — their version is the project's own).
+ */
+export declare function buildVersionBanner(pin: AutoInstallPin | undefined, pkgName: string, version: string): string;
 export declare function getDocsModulesDir(): string;
 export declare function ensureDocsModulesDir(dir: string): void;
-export declare function runAutoInstall(spawn: SpawnFn, packageName: string, signal: AbortSignal | undefined): Promise<{
+export declare function runAutoInstall(spawn: SpawnFn, packageName: string, signal: AbortSignal | undefined, versionRange?: string): Promise<{
     success: boolean;
     installDir: string;
     stderr: string;

package/dist/workers/docs-core.js

@@ -24,6 +24,70 @@ export function extractParentPackage(moduleName) {
     }
     return moduleName.split('/')[0];
 }
+const DEP_FIELDS = [
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies'
+];
+/** A declared value that is a real, installable npm semver range — not a
+ *  wildcard (which pins nothing) and not a non-registry protocol (which is not
+ *  an `install <pkg>@<range>` target). */
+function isUsableRange(range) {
+    const r = range.trim();
+    if (r.length === 0 || r === '*' || r === 'x' || r === 'latest')
+        return false;
+    if (/^(?:workspace|link|file|git|github|http|https|portal|patch|npm):/i.test(r))
+        return false;
+    return true;
+}
+/**
+ * The version range a project DECLARES for `parentPkg` in its package.json under
+ * `cwd`. Lets a not-yet-installed scaffolding dependency be documented against
+ * the major the project intends, instead of whatever npm currently tags
+ * `latest`. Scans the four standard dependency maps in priority order. Returns
+ * null — caller falls back to latest — when the dep is undeclared, the
+ * package.json is missing/unreadable, or the declared value is not a usable
+ * range. Best-effort; never throws.
+ */
+export function findDeclaredRange(parentPkg, cwd) {
+    let json;
+    try {
+        json = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    for (const field of DEP_FIELDS) {
+        const map = json[field];
+        if (!map || typeof map !== 'object')
+            continue;
+        const range = map[parentPkg];
+        if (typeof range === 'string' && isUsableRange(range))
+            return range.trim();
+    }
+    return null;
+}
+/**
+ * One-line version-provenance banner that LEADS a docs answer for a package the
+ * worker had to auto-install (not yet present in node_modules — every
+ * scaffolding task). Surfaces the version the answer is grounded in directly in
+ * the prose the impl model reads, rather than burying it in tool `details`.
+ * Empty string when there was no auto-install (already-installed packages need
+ * no banner — their version is the project's own).
+ */
+export function buildVersionBanner(pin, pkgName, version) {
+    if (!pin)
+        return '';
+    if (pin.source === 'declared-range') {
+        return (`[VERSION] "${pkgName}" resolved to this project's declared range `
+            + `${pin.range} (installed v${version}); the answer below is pinned to that version.\n\n`);
+    }
+    return (`[VERSION — verify] "${pkgName}" is not declared in this project's package.json, `
+        + `so this answer is based on npm latest (v${version}). Your project may target a `
+        + `different MAJOR — confirm the version you intend to install and treat any API that `
+        + `differs across majors as unverified until you check it against that version.\n\n`);
+}
 export function getDocsModulesDir() {
     const base = process.env.XDG_CACHE_HOME?.trim() || path.join(os.homedir(), '.cache');
     return path.join(base, 'pi-worker', 'docs-modules');
@@ -35,12 +99,15 @@ export function ensureDocsModulesDir(dir) {
         fs.writeFileSync(pkgPath, '{"name":"pi-worker-docs-modules","private":true}\n', 'utf8');
     }
 }
-export async function runAutoInstall(spawn, packageName, signal) {
+export async function runAutoInstall(spawn, packageName, signal, versionRange) {
     const installDir = getDocsModulesDir();
     ensureDocsModulesDir(installDir);
+    // `shell: false` in runChild, so a `^`/`~`/space in the range stays a single
+    // literal arg — no glob/expansion risk from `<pkg>@<range>`.
+    const target = versionRange ? `${packageName}@${versionRange}` : packageName;
     const result = await runChild(spawn, {
         command: 'npm',
-        args: ['install', '--no-audit', '--no-fund', '--loglevel=error', packageName]
+        args: ['install', '--no-audit', '--no-fund', '--loglevel=error', target]
     }, installDir, signal, { mode: 'text', discardStdout: true });
     return { success: result.exitCode === 0 && !result.aborted, installDir, stderr: result.stderr };
 }
@@ -111,20 +178,30 @@ export async function docsRaw(input) {
     // Step 1: resolve package
     let pkg;
     let autoInstalled = false;
+    let autoInstallPin;
     try {
         pkg = resolvePackage(requested, input.cwd);
     }
     catch (firstErr) {
         if (firstErr instanceof ResolveError && firstErr.kind === 'not_installed') {
-            // auto-install
+            // auto-install — but FIRST honour the version the project intends.
+            // If the dep is declared in the project's package.json, install that
+            // range so a scaffolding answer is grounded in the project's major,
+            // not whatever npm currently tags `latest`.
             const parentPkg = extractParentPackage(requested);
-            const installResult = await runAutoInstall(spawn, parentPkg, undefined);
+            const declaredRange = findDeclaredRange(parentPkg, input.cwd);
+            autoInstallPin =
+                declaredRange ?
+                    { source: 'declared-range', range: declaredRange }
+                    : { source: 'npm-latest' };
+            const installResult = await runAutoInstall(spawn, parentPkg, undefined, declaredRange ?? undefined);
             if (!installResult.success) {
                 return {
                     kind: 'error',
                     message: `Package "${parentPkg}" is not installed and auto-install failed.\n${installResult.stderr}`,
                     resolveError: 'not_installed',
                     installError: installResult.stderr,
+                    autoInstallPin,
                     npmVersion: await npmVersionPromise
                 };
             }
@@ -139,6 +216,7 @@ export async function docsRaw(input) {
                         message: retryErr.message,
                         resolveError: retryErr.kind,
                         autoInstalled,
+                        autoInstallPin,
                         npmVersion: await npmVersionPromise
                     };
                 }
@@ -146,6 +224,7 @@ export async function docsRaw(input) {
                     kind: 'error',
                     message: `Could not resolve "${input.pkg}" after install: ${retryErr instanceof Error ? retryErr.message : String(retryErr)}`,
                     autoInstalled,
+                    autoInstallPin,
                     npmVersion: await npmVersionPromise
                 };
             }
@@ -186,6 +265,8 @@ export async function docsRaw(input) {
         docsRawCached(cache, pkg, input.query, ensureIndexed, retrieveChunks, autoInstalled)
         : docsRawUncached(pkg, cacheError ?? 'unknown cache error', autoInstalled);
     result.npmVersion = await npmVersionPromise;
+    if (autoInstallPin && result.kind !== 'not_installed')
+        result.autoInstallPin = autoInstallPin;
     return result;
 }
 function docsRawCached(cache, pkg, query, ensureIndexed, retrieveChunks, autoInstalled) {

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

@@ -2,7 +2,7 @@ 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, buildPrompt } from './docs-core.js';
+import { docsRaw, formatResultText, buildPrompt, buildVersionBanner } from './docs-core.js';
 import { formatNpmVersionSection } from './npm-version.js';
 import { runChild, CHILD_BASE_ARGS } from '../shared/child-process.js';
 import { parseChildOutput, isExcerptInContent } from '../shared/child-output.js';
@@ -19,6 +19,9 @@ const Params = Type.Object({
         description: 'What to extract from the docs. The child pi reads ranked chunks and returns ONLY content answering this.'
     })
 });
+function pinDetails(pin) {
+    return pin ? { versionSource: pin.source, declaredRange: pin.range } : {};
+}
 export function registerPiWorkerDocs(pi, internals = {}) {
     makeWorkerTool(pi, {
         name: 'pi-worker-docs',
@@ -172,8 +175,10 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 };
             }
             if (rawResult.kind === 'no_chunks') {
+                const banner = buildVersionBanner(rawResult.autoInstallPin, rawResult.pkg.name, rawResult.pkg.version);
                 return {
-                    text: npmHeader
+                    text: banner
+                        + npmHeader
                         + `Package ${rawResult.pkg.name}@${rawResult.pkg.version} has no .d.ts files or README. Use pi-worker to read source directly.`,
                     details: {
                         version: rawResult.pkg.version,
@@ -181,12 +186,14 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                         indexedFiles: rawResult.indexedFiles ?? 0,
                         cacheError: rawResult.cacheError,
                         autoInstalled: rawResult.autoInstalled,
+                        ...pinDetails(rawResult.autoInstallPin),
                         ...npmDetails
                     }
                 };
             }
             // kind === 'ok'
             const { pkg, chunks, hitCache, indexingMs, cacheError, autoInstalled } = rawResult;
+            const versionBanner = buildVersionBanner(rawResult.autoInstallPin, pkg.name, pkg.version);
             const baseDetails = {
                 version: pkg.version,
                 hitCache,
@@ -194,6 +201,7 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 indexingMs,
                 cacheError,
                 autoInstalled,
+                ...pinDetails(rawResult.autoInstallPin),
                 ...npmDetails
             };
             const concatenated = chunks.map(c => c.content).join('\n\n');
@@ -203,7 +211,7 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             const failure = formatChildFailure(child, 'Docs lookup aborted.');
             if (failure !== null) {
                 return {
-                    text: npmHeader + failure,
+                    text: versionBanner + npmHeader + failure,
                     details: {
                         ...baseDetails,
                         ...(child.aborted ? { aborted: true } : {}),
@@ -213,7 +221,7 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             }
             const parsed = parseChildOutput(child.stdout);
             const verified = parsed.excerpt ? isExcerptInContent(parsed.excerpt, concatenated) : undefined;
-            const text = npmHeader + formatResultText(pkg, parsed, verified);
+            const text = versionBanner + npmHeader + formatResultText(pkg, parsed, verified);
             return {
                 text,
                 details: {

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

@@ -17,8 +17,15 @@ export function registerPiWorkerFetch(pi, internals = {}) {
         description: 'Fetch a web page or text resource (HTML, markdown, plain text, JSON, '
             + 'XML/feeds), clean HTML to markdown, and hand it to an isolated child '
             + 'Pi session that extracts ONLY content answering `query`. Returns the '
-            + 'focused answer. Use after `pi-worker-search` (or with a known URL) to '
-            + 'avoid stuffing raw content into the main context.',
+            + 'focused answer.\n'
+            + 'REACH FOR THIS when you need to know how an external library, tool, '
+            + 'plugin, framework, or service is CONFIGURED, WIRED, or INTEGRATED and '
+            + 'the installed-package docs (pi-worker-docs) do not cover it: fetch its '
+            + 'README or official documentation page and extract the setup/wiring you '
+            + 'need, instead of guessing. Do NOT guess integration or configuration '
+            + 'details from memory — fetch the authoritative page. Also use it to read '
+            + 'any known URL, or after `pi-worker-search` to read a result, without '
+            + 'stuffing raw content into the main context.',
         parameters: Params,
         async run(params, signal, ctx) {
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.16.3",
+    "version": "0.16.4",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",