@mjasnikovs/pi-task 0.39.4 → 0.40.0

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

@@ -8,6 +8,7 @@ import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import { docsLookup } from './docs-lookup.js';
 import { projectCorpus } from './docs-project.js';
 import { docsRaw, packageCorpus, buildVersionBanner } from './docs-core.js';
+import { ECOSYSTEMS } from './docs-ecosystems.js';
 import { npmVersionLookup as defaultNpmVersionLookup, formatNpmVersionSection } from './npm-version.js';
 import { childFailureReason, makeWorkerTool, workerAnswer, workerUnavailable } from './shared.js';
 import { isTypeOnlyAnswer } from '../task/type-only-answer.js';
@@ -20,11 +21,14 @@ import { groupChildArgs } from '../config/group-args.js';
 const RENDER_QUERY_MAX = 100;
 const Params = Type.Object({
     module: Type.String({
-        description: 'Bare npm module name (e.g. "zod", "@scope/name", "react/jsx-runtime"), OR "." to look up the current project\'s own source code. npm packages must be installed in node_modules.'
+        description: 'Bare package name (e.g. "zod", "@scope/name", "react/jsx-runtime"), OR "." to look up the current project\'s own source code.'
     }),
     query: Type.String({
         description: 'What to extract from the docs. The child pi reads ranked chunks and returns ONLY content answering this.'
-    })
+    }),
+    ecosystem: Type.Optional(Type.Union([Type.Literal('npm'), Type.Literal('cargo'), Type.Literal('hackage')], {
+        description: 'Which registry to read. Only needed in a repo holding more than one package manifest; otherwise the manifest decides.'
+    }))
 });
 /**
  * Pull `@see {@link https://…}` pointers out of retrieved .d.ts/README text.
@@ -90,18 +94,24 @@ export function registerPiWorkerDocs(pi, internals = {}) {
     makeWorkerTool(pi, {
         name: 'pi-worker-docs',
         label: 'Pi Worker Docs',
-        description: 'Look up an INSTALLED npm package and return a focused, version-pinned '
-            + 'answer from its .d.ts types and README, PLUS the latest published version '
-            + 'from a live npm registry call. USE THIS BEFORE ANSWERING any question '
+        description: 'Look up an INSTALLED package and return a focused, version-pinned '
+            + 'answer from its type declarations and README, PLUS the latest published '
+            + 'version from a live registry call. USE THIS BEFORE ANSWERING any question '
             + 'about how to use a library, what it exports, its types/overloads/config, '
-            + 'or the latest published version of an npm package. Do NOT answer package '
+            + 'or the latest published version of a package. Do NOT answer package '
             + 'APIs from memory, do NOT run `npm view`/bash to get a package version, and '
             + 'do NOT web-search for an installed package — this tool is the source of '
             + 'truth and is version-pinned to what is actually installed (training-data '
             + 'versions and APIs are typically months stale).\n'
+            + 'SUPPORTED ECOSYSTEMS: npm (package.json), cargo (Cargo.toml), hackage '
+            + '(*.cabal). The MANIFEST in the working '
+            + 'directory decides which registry a name is looked up in — you do not. If '
+            + 'the directory holds none of those manifests, this tool REFUSES and '
+            + 'installs nothing; use `pi-worker-search` or `pi-worker-fetch` for that '
+            + 'package instead.\n'
             + 'For a non-package framework/runtime version (e.g. Node.js, Ubuntu), use '
             + '`pi-worker-search` instead. If the package is not installed it is '
-            + 'auto-installed via bun add or npm install. The cache lives at '
+            + "auto-installed from the project's own registry. The cache lives at "
             + '~/.cache/pi-worker/docs.sqlite, keyed by exact installed version; the '
             + 'registry lookup is best-effort and silently absent when offline.\n'
             + '\n'
@@ -168,7 +178,8 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 }
                 if (projectResult.kind === 'no_chunks') {
                     // The project IS indexed and has nothing — a real answer.
-                    return workerAnswer(`Project "${projectResult.projectName}" has no .ts/.tsx files indexed.`, {
+                    return workerAnswer(`Project "${projectResult.projectName}" has no `
+                        + `${projectResult.sourceLabel} files indexed.`, {
                         hitCache: projectResult.hitCache,
                         indexedFiles: projectResult.filesIngested
                     });
@@ -214,6 +225,7 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 pkg: params.module,
                 query: params.query,
                 cwd: ctx.cwd,
+                ...(params.ecosystem ? { ecosystem: params.ecosystem } : {}),
                 resolvePackage: internals.resolvePackage,
                 ensureIndexed: internals.ensureIndexed,
                 retrieveChunks: internals.retrieveChunks,
@@ -222,7 +234,9 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 npmVersionLookup: internals.npmVersionLookup,
                 signal
             });
-            const npmHeader = rawResult.npmVersion ? `${formatNpmVersionSection(rawResult.npmVersion)}\n\n` : '';
+            const npmHeader = rawResult.npmVersion ?
+                `${formatNpmVersionSection(rawResult.npmVersion, rawResult.registryLabel)}\n\n`
+                : '';
             const npmDetails = rawResult.npmVersion ?
                 {
                     npmLatest: rawResult.npmVersion.latest,
@@ -248,13 +262,16 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 return workerUnavailable(npmHeader + rawResult.message, details, 'docs-error');
             }
             if (rawResult.kind === 'no_chunks') {
-                const banner = buildVersionBanner(rawResult.autoInstallPin, rawResult.pkg.name, rawResult.pkg.version, ctx.cwd);
+                const banner = buildVersionBanner(rawResult.autoInstallPin, rawResult.pkg.name, rawResult.pkg.version, ctx.cwd, ECOSYSTEMS[rawResult.pkg.ecosystem]);
                 // The package resolved and genuinely ships nothing to read — an
                 // answer, and a stable one for this run.
                 return workerAnswer(banner
                     + npmHeader
-                    + `Package ${rawResult.pkg.name}@${rawResult.pkg.version} has no .d.ts files or README. Use pi-worker to read source directly.`, {
+                    + `Package ${rawResult.pkg.name}@${rawResult.pkg.version} has no `
+                    + `${ECOSYSTEMS[rawResult.pkg.ecosystem].surfaceLabel}. Use pi-worker to `
+                    + 'read source directly.', {
                     version: rawResult.pkg.version,
+                    ecosystem: rawResult.pkg.ecosystem,
                     hitCache: rawResult.hitCache,
                     indexedFiles: rawResult.indexedFiles ?? 0,
                     cacheError: rawResult.cacheError,
@@ -264,9 +281,10 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 });
             }
             const { pkg, chunks, hitCache, indexingMs, cacheError, autoInstalled } = rawResult;
-            const versionBanner = buildVersionBanner(rawResult.autoInstallPin, pkg.name, pkg.version, ctx.cwd);
+            const versionBanner = buildVersionBanner(rawResult.autoInstallPin, pkg.name, pkg.version, ctx.cwd, ECOSYSTEMS[pkg.ecosystem]);
             const baseDetails = {
                 version: pkg.version,
+                ecosystem: pkg.ecosystem,
                 hitCache,
                 chunksRetrieved: chunks.length,
                 indexingMs,
@@ -387,14 +405,34 @@ export function docsCacheable(d, text) {
 /** 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
- *  mutates as tasks implement. */
+ *  mutates as tasks implement.
+ *
+ *  The ecosystem joins the key only when the caller named one, so the keys of every
+ *  call that lets the manifest decide are the ones they always were. */
 export function docsCacheKey(params) {
-    return params.module === '.' ?
-        null
-        : `${normalizeQuery(params.module)}::${normalizeQuery(params.query)}`;
+    if (params.module === '.')
+        return null;
+    const scope = params.ecosystem ? `${params.ecosystem}::` : '';
+    return `${scope}${normalizeQuery(params.module)}::${normalizeQuery(params.query)}`;
 }
 /** Package provenance for per-entry resume invalidation: the package ROOT of the
- *  specifier (`hono/client` → `hono`), and undefined for the project-source `.`. */
-export function docsCachePkg(params) {
-    return params.module === '.' ? undefined : packageRootOf(params.module);
+ *  specifier (`hono/client` → `hono`), and undefined for the project-source `.`.
+ *
+ *  The ecosystem comes from the RESOLVED lookup, not from the optional argument.
+ *  Reading the argument would record npm for every single-manifest cargo or cabal
+ *  project — the ordinary case, since the argument only exists to disambiguate a
+ *  polyglot repo — and the entry's version would then be looked for in a
+ *  `package.json` that is not there, leaving it un-prunable forever. */
+export function docsCachePkg(params, details) {
+    if (params.module === '.')
+        return undefined;
+    const ecosystem = details.ecosystem ?? 'npm';
+    // The ROW knows how its own specifiers nest: `hono/client` → `hono`, but
+    // `serde_json::Value` → `serde_json`. Splitting on `/` alone recorded the
+    // whole path, and no manifest names that — so the entry's version came back
+    // undefined and it was never invalidated again.
+    return {
+        pkg: ECOSYSTEMS[ecosystem].parentPackage(params.module),
+        ...(ecosystem !== 'npm' ? { ecosystem } : {})
+    };
 }

package/dist/workers/research-cache.d.ts

@@ -1,3 +1,4 @@
+import { type EcosystemId } from './docs-ecosystems.js';
 /** The env var the orchestrator stamps with the per-run id children inherit. */
 export declare const RESEARCH_RUN_ID_ENV = "PI_TASK_RUN_ID";
 /** Is this a transient filesystem error worth retrying inside the caller's deadline? */
@@ -24,18 +25,6 @@ export declare function configureResearchRun(enabled: boolean): string | undefin
  * of asking the same thing resolve to the same (correct) result.
  */
 export declare function normalizeQuery(s: string): string;
-/**
- * The project's declared dependency surface as a name→range map, flattened across every
- * dependency block (a package listed in two blocks resolves to the first range seen, in
- * block order — a real manifest does not disagree with itself, and a disagreement can
- * only make the comparison stricter, i.e. re-fetch).
- *
- * Returns undefined when the manifest is missing or unparseable: the caller then cannot
- * prove any package's version and must treat every package-scoped entry as unprovable.
- * Deliberately NOT the lockfile: it is rewritten by installs that change no resolved
- * version, which would drop digests for no correctness gain.
- */
-export declare function depsMap(cwd: string): Promise<Record<string, string> | undefined>;
 /**
  * Resume hook: keep the interrupted run's cache id and PRUNE the entries the manifest
  * has invalidated, rather than discarding the whole cache because anything moved. Returns
@@ -73,4 +62,4 @@ export declare function lookupResearch(cwd: string, runId: string, key: string):
  *
  * Best-effort: any failure is swallowed, leaving the caller's live result untouched.
  */
-export declare function storeResearch(cwd: string, runId: string, key: string, text: string, details: unknown, pkg?: string): Promise<void>;
+export declare function storeResearch(cwd: string, runId: string, key: string, text: string, details: unknown, pkg?: string, ecosystem?: EcosystemId): Promise<void>;

package/dist/workers/research-cache.js

@@ -79,6 +79,7 @@
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import { tasksDir } from '../task/task-io.js';
+import { ECOSYSTEMS } from './docs-ecosystems.js';
 const RESEARCH_CACHE_FILE = 'research-cache.json';
 /** The env var the orchestrator stamps with the per-run id children inherit. */
 export const RESEARCH_RUN_ID_ENV = 'PI_TASK_RUN_ID';
@@ -174,47 +175,13 @@ export function configureResearchRun(enabled) {
 export function normalizeQuery(s) {
     return s.replace(/\s+/g, ' ').trim().toLowerCase();
 }
-/**
- * The project's declared dependency surface as a name→range map, flattened across every
- * dependency block (a package listed in two blocks resolves to the first range seen, in
- * block order — a real manifest does not disagree with itself, and a disagreement can
- * only make the comparison stricter, i.e. re-fetch).
- *
- * Returns undefined when the manifest is missing or unparseable: the caller then cannot
- * prove any package's version and must treat every package-scoped entry as unprovable.
- * Deliberately NOT the lockfile: it is rewritten by installs that change no resolved
- * version, which would drop digests for no correctness gain.
- */
-export async function depsMap(cwd) {
-    try {
-        const raw = await fsp.readFile(path.join(cwd, 'package.json'), 'utf8');
-        const pkg = JSON.parse(raw);
-        const blocks = [
-            'dependencies',
-            'devDependencies',
-            'peerDependencies',
-            'optionalDependencies'
-        ];
-        const out = {};
-        for (const block of blocks) {
-            const deps = pkg[block];
-            if (!deps || typeof deps !== 'object')
-                continue;
-            for (const [name, range] of Object.entries(deps)) {
-                if (typeof range === 'string' && !(name in out))
-                    out[name] = range;
-            }
-        }
-        // No dependency block at all is a real, stable state (a dependency-free repo).
-        return out;
-    }
-    catch {
-        return undefined;
-    }
+/** The same question for any ecosystem: what does its manifest pin, name to version. */
+function depsMapFor(cwd, ecosystem) {
+    return ECOSYSTEMS[ecosystem].declaredDeps(cwd);
 }
 /** The version declared for `pkg`, or undefined when it is not in the manifest. */
-async function declaredVersion(cwd, pkg) {
-    return (await depsMap(cwd))?.[pkg];
+function declaredVersion(cwd, pkg, ecosystem) {
+    return depsMapFor(cwd, ecosystem)?.[pkg];
 }
 /**
  * Is this entry still current against the manifest as it stands now?
@@ -227,10 +194,10 @@ async function declaredVersion(cwd, pkg) {
  * - `pkg` whose version moved, which left the manifest, or an unreadable manifest
  *   (no evidence either way): DROPPED.
  */
-function entryStillFresh(entry, deps) {
+function entryStillFresh(entry, depsFor) {
     if (entry.pkg === undefined || entry.pkgVersion === undefined)
         return true;
-    return deps?.[entry.pkg] === entry.pkgVersion;
+    return depsFor(entry.ecosystem ?? 'npm')?.[entry.pkg] === entry.pkgVersion;
 }
 /**
  * Resume hook: keep the interrupted run's cache id and PRUNE the entries the manifest
@@ -267,11 +234,17 @@ async function pruneCache(cwd) {
     const file = await readCacheFile(cwd);
     if (!file || file.pkgv !== PKG_PROVENANCE_VERSION)
         return null;
-    const deps = await depsMap(cwd);
+    // Read each manifest at most once: a file can hold entries from several.
+    const byEcosystem = new Map();
+    const depsFor = (id) => {
+        if (!byEcosystem.has(id))
+            byEcosystem.set(id, depsMapFor(cwd, id));
+        return byEcosystem.get(id);
+    };
     const kept = {};
     let dropped = 0;
     for (const [key, entry] of Object.entries(file.entries)) {
-        if (entryStillFresh(entry, deps))
+        if (entryStillFresh(entry, depsFor))
             kept[key] = entry;
         else
             dropped++;
@@ -449,12 +422,12 @@ async function withCacheLock(cwd, fn) {
  *
  * Best-effort: any failure is swallowed, leaving the caller's live result untouched.
  */
-export async function storeResearch(cwd, runId, key, text, details, pkg) {
+export async function storeResearch(cwd, runId, key, text, details, pkg, ecosystem = 'npm') {
     try {
-        // Resolved OUTSIDE the critical section: it reads package.json, which no other
+        // Resolved OUTSIDE the critical section: it reads the manifest, which no other
         // writer can be mutating, and keeping it out holds the lock for the file
         // read/write alone. The version is still the one current at store time.
-        const pkgVersion = pkg === undefined ? undefined : await declaredVersion(cwd, pkg);
+        const pkgVersion = pkg === undefined ? undefined : declaredVersion(cwd, pkg, ecosystem);
         await withCacheLock(cwd, async () => {
             const existing = await readCacheFile(cwd);
             const entries = existing && existing.runId === runId ? existing.entries : {};
@@ -463,6 +436,9 @@ export async function storeResearch(cwd, runId, key, text, details, pkg) {
                 details,
                 at: Date.now(),
                 ...(pkg === undefined ? {} : { pkg }),
+                // npm is the absent default, so an npm-only file is byte-identical
+                // to what earlier versions wrote.
+                ...(pkg !== undefined && ecosystem !== 'npm' ? { ecosystem } : {}),
                 ...(pkgVersion === undefined ? {} : { pkgVersion })
             };
             // Evict oldest by write time if over the cap.

package/dist/workers/shared.d.ts

@@ -2,7 +2,13 @@ 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 { EcosystemId } from './docs-ecosystems.js';
 import { type WorkerFailureInput } from './worker-failure.js';
+/** Which package, in which registry, a cached answer is about. */
+export interface CachePackage {
+    pkg: string;
+    ecosystem?: EcosystemId;
+}
 /** Build a plain-text AgentToolResult. */
 export declare function textResult<T>(text: string, details: T): AgentToolResult<T>;
 /**
@@ -98,13 +104,18 @@ export interface WorkerToolSpec<TParams extends TSchema, TDetails> {
      */
     cacheKey?(params: Static<TParams>): string | null;
     /**
-     * The npm package this call's answer is ABOUT, for a package-scoped tool (docs).
-     * Recorded as structured provenance on the cache entry so a resume can drop just the
-     * entries whose package moved version, instead of the whole run's cache. A
-     * greenfield run adds packages every few tasks, so a whole-file gate never holds.
+     * The package this call's answer is ABOUT, and the registry it came from, for a
+     * package-scoped tool (docs). Recorded as structured provenance on the cache entry
+     * so a resume can drop just the entries whose package moved version, instead of
+     * the whole run's cache. A greenfield run adds packages every few tasks, so a
+     * whole-file gate never holds. The registry is part of it because `text` on npm
+     * and `text` on another registry are different packages that move separately.
      * Omit — or return undefined — and the entry survives every resume of its run.
+     *
+     * `details` is the finished call's own record, so the registry recorded here is
+     * the one the lookup RESOLVED to — not one the caller happened to name.
      */
-    cachePkg?(params: Static<TParams>): string | undefined;
+    cachePkg?(params: Static<TParams>, details: TDetails): CachePackage | undefined;
     /**
      * Whether an ANSWER is safe to cache — a question about the answer's QUALITY
      * (type-only, an abstention, an unverified excerpt), never about process

package/package.json

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