@mjasnikovs/pi-task 0.39.5 → 0.40.1

package/README.md

@@ -9,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/@mjasnikovs/pi-task?color=cb3837&logo=npm)](https://www.npmjs.com/package/@mjasnikovs/pi-task)
 [![license](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
-[![tests](https://img.shields.io/badge/tests-4118%20passing-3fb950)](#development)
+[![tests](https://img.shields.io/badge/tests-4280%20passing-3fb950)](#development)
 [![types](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./tsconfig.json)
 
 </div>
@@ -66,7 +66,7 @@ A whole plan — `/task-auto` splits it into an ordered task list and runs each
 | --- | --- |
 | `/task <prompt>` | Start a new task and run it through the full pipeline. |
 | `/task-plan <prompt>` | Plan one task with the model — it asks, you answer, ask it something back, or proceed — then run it through `/task`. |
-| `/task-list` | Open the task list in an editor dialog. |
+| `/task-list` | Show a table of tasks in `.pi-tasks/` — id, state, phase, date, title — newest first, with a resume hint. |
 | `/task-resume [id]` | Resume the most recent (or named) unfinished task. |
 | `/task-cancel` | Stop the running task at the next safe checkpoint (still resumable). Mid-phase it kills the running child; during the implementation turn it lets the turn finish and stops before the gates. |
 | `/task-auto <feature>` | Plan a feature into a task list and run each title through `/task` in order (resumable). |
@@ -171,7 +171,7 @@ VAPID keys are generated once and persisted to `${XDG_DATA_HOME:-~/.local/share}
 `pi-task` also registers four MCP-style worker tools (formerly `@mjasnikovs/pi-worker`). All are parallel-execution-capable, so the parent session can issue several calls in one turn.
 
 ### `pi-worker`
-Spawns an isolated child `pi --print` session with read + bash tools. Use it for noisy file/code work that would otherwise flood the main context.
+Spawns an isolated child `pi --print` session with read-only tools (`read`, `grep`, `find`, `ls` — no bash, no writes). Use it for noisy file/code work that would otherwise flood the main context.
 
 ### `pi-worker-search`
 Runs a web search and returns a compact markdown list (title · URL · snippet). Use it to discover candidate URLs before fetching. The search engine is set in `/task-config` (default: **Exa**):
@@ -191,12 +191,25 @@ Fetches a URL, cleans HTML to markdown ([Readability](https://github.com/mozilla
 - The extraction child runs with `--no-tools` to mitigate visible-text prompt injection.
 
 ### `pi-worker-docs`
-Resolves an installed npm package, indexes its `.d.ts` files and README into a local SQLite cache, retrieves the most relevant chunks for your `query`, and passes them to an isolated child that extracts the focused answer. Version-pinned to whatever is in your `node_modules`.
+Resolves an installed package, indexes its API surface and README into a local SQLite cache, retrieves the most relevant chunks for your `query`, and passes them to an isolated child that extracts the focused answer. Version-pinned to whatever the project actually resolved.
 
-- The package must be installed in the project's `node_modules`; otherwise a one-time auto-install into a dedicated cache dir is attempted.
-- The first call for a `(package, version)` pair pays a one-time ingestion cost; later calls are FTS-only.
+**The manifest decides which registry, not the model.** `text`, `base`, `aeson`, `tokio` and `clap` are all real npm packages *and* real Rust/Haskell ones, so a name alone cannot say which was meant — and guessing npm returns a confident answer about an unrelated package. That is a wrong answer, not a miss.
+
+| Ecosystem | Detected by | Surface read | Version comes from |
+| --- | --- | --- | --- |
+| `npm` | `package.json`, or a `node_modules/` directory | the `.d.ts` files the package ships, plus README | the installed `package.json` |
+| `cargo` | `Cargo.toml`, at the directory or one level below it | `.rs` source reduced to public item heads, doc comments and attributes | `Cargo.lock` |
+| `hackage` | `*.cabal`, `cabal.project`, `stack.yaml` or `package.yaml` | `.hs` source reduced to the export list, signatures and type declarations | `dist-newstyle/cache/plan.json`, then `cabal.project.freeze`, then `stack.yaml.lock` |
+
+- **No manifest, no lookup.** In a directory with none of the above the tool refuses, spawns nothing and installs nothing, and points you at `pi-worker-search` / `pi-worker-fetch` instead.
+- **Two manifests** (a Tauri app, say) are resolved by whichever registry already has the package on disk. If neither does, the call is refused as ambiguous and you pass `ecosystem: "cargo"` to say which.
+- A package the project does not have is fetched once into a dedicated cache dir: `npm install --ignore-scripts` for npm, the `.crate` tarball for cargo, the Hackage tarball (or cabal's own cached copy) for hackage.
+- A Haskell **module** name is refused by name — `Data.Aeson` is not a package, `aeson` is.
+- The first call for a `(ecosystem, package, version)` triple pays a one-time ingestion cost; later calls are FTS-only.
 - Cache lives at `${XDG_CACHE_HOME:-~/.cache}/pi-worker/docs.sqlite` — delete it to reset.
 
+**Known gaps.** The rest of pi-task is still npm-shaped: the final gate, repo-health and orientation read the working directory first-wins, so a Tauri repo gets cargo docs answers while the gate runs `bun run test`, not `cargo test`. Phantom-import checking, dependency-name extraction for research enrichment, and the `@types/…` redirect chain are npm concepts and are no-ops elsewhere. Adding an ecosystem is one row in `src/workers/docs-ecosystems.ts` plus its parsers — profiles live in code and arrive as pull requests with tests, never as user configuration.
+
 ## Settings — `/task-config`
 
 Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings persist to `~/.config/pi-task/config.json`.
@@ -215,7 +228,7 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | **stuck reply retry** | 10 min | Inactivity ceiling on the **model stream**. A hung or silently-dropped stream throws nothing at all, so neither the connection-error retry (it needs a reported error) nor the **command timeout** (tool calls only) nor the dead-backend stall guard (a reachable endpoint reads as proof of life) can see it — an mx5 run lost ~2.9h to three of them while the model server stayed healthy. Measured as time since the **last stream event of any kind**, so a slow model emitting one token every 30s is never touched, and it pauses while a tool runs. On expiry the main session aborts the turn (through the same channel the command watchdog uses) and posts a resume reminder; a child is killed and routed into the existing connection-error retry. Choices: 5/10/20/30 min or **off**. Keep it generous on local backends — prompt processing on a large context legitimately emits nothing for minutes. |
 | **yolo mode** | off | **Unattended runs.** Wherever pi-task would stop and ask, it takes the option already marked RECOMMENDED, stamps the artifact `(YOLO)` so an audit can tell a machine decided, and shows no prompt at all — clarify/grill answers, the verify-FAIL picker (auto-**Accept**, recorded as a yolo debt), and the final-gate picker (autofix while the budget lasts, then leave the run FAILED). A question with no recommendation is **skipped**, never invented. For throwaway/test projects nobody is watching; a real run should decide these itself. |
 | **profile** | default | How much the helper sessions think, in one word, for every step at once. Local models differ sharply here: some break without reasoning, some waste minutes with it, and some cannot do it at all. **default** uses the per-step table pi-task has measured, **on** and **off** force one answer everywhere and ignore that table, and **custom** is whatever the step rows say — changing any of them switches this to custom. A step on **inherit** passes no flag at all, so it uses whatever thinking level pi itself is set to, which is what every step did before this setting existed. |
-| **steps: …** | all `inherit` | One row per group of steps, carrying BOTH dials: the model those children run on and the level they think at, shown as `level · model`. Enter walks a two-step picker — model first, then level — and **the level step offers only what that model declares, opening on the one that will actually run**. That is the whole point of the merge: pi silently CLAMPS a level a model cannot do (a level you set can be erased, and an `off` can be clamped back up to `medium`), so instead of discovering that later you watch the cursor land on the level you are really getting. Models are offered from `pi.modelRegistry.getAvailable()` and stored as the canonical `provider/id` that pi's own `--model` takes. **inherit** on the model half emits no flag, so an all-inherit table is byte-identical to a build without this feature; that is the shipped default, because which models exist is a property of your machine and nothing here can be measured for you. A stored model this machine cannot resolve is never erased (you may have set it on another machine): the flag is dropped, the step runs on pi's default, and a startup hint names the step. Two need care — a provider registered by a host **extension** needs that extension enabled under **ext: …** or those children exit 1; and **implementation** is not free, because it is *your* session moved for the turn and moved back, and a model switch re-bills the whole prompt as a cache miss, twice per task. |
+| **steps: …** | models `inherit`; levels per the shipped table | One row per group of steps, carrying BOTH dials: the model those children run on and the level they think at, shown as `level · model`. Enter walks a two-step picker — model first, then level — and **the level step offers only what that model declares, opening on the one that will actually run**. That is the whole point of the merge: pi silently CLAMPS a level a model cannot do (a level you set can be erased, and an `off` can be clamped back up to `medium`), so instead of discovering that later you watch the cursor land on the level you are really getting. Models are offered from `pi.modelRegistry.getAvailable()` and stored as the canonical `provider/id` that pi's own `--model` takes. **inherit** on the model half emits no flag, so an all-inherit table is byte-identical to a build without this feature; that is the shipped default, because which models exist is a property of your machine and nothing here can be measured for you. A stored model this machine cannot resolve is never erased (you may have set it on another machine): the flag is dropped, the step runs on pi's default, and a startup hint names the step. Two need care — a provider registered by a host **extension** needs that extension enabled under **ext: …** or those children exit 1; and **implementation** is not free, because it is *your* session moved for the turn and moved back, and a model switch re-bills the whole prompt as a cache miss, twice per task. |
 | **debug logs** | events | How much of a run is written to `.pi-tasks/*-debug.log`. **`events`** keeps decisions and guard actions — which phase ran, why a worker was retried, what the git-state guard restored, what a write-capable child changed on disk, why a gate returned FAIL — a few lines per task. **`full`** adds every line the child model emitted and every tool result; that's ~85% of the bytes (a real 247 KB `verify-debug.log` is 1315 lines, 521 of them tool dumps) and is what you want while actively debugging. **`off`** writes nothing. Nothing in pi-task ever reads these files back, so the setting cannot change how a run behaves — only whether you can explain it afterwards, and a log not written can't be recovered later. |
 | **watch: …** | all on | One toggle per tool in the live session, deciding whether **command timeout** applies to it. The list is discovered from `pi.getAllTools()` when the menu opens — built-ins first, then each extension's tools with the owning entry-point path in the description — so nothing is typed by hand and an uninstalled tool just stops being listed. Turn one **off** only for a tool that already owns a longer bounded, cancellable contract of its own (the guard exists because pi's `bash` has an optional timeout with *no* default — that reasoning doesn't transfer to a tool that has one). Two things to know before you do: a genuine hang in an unwatched tool is caught by nothing, since **stuck reply retry** is paused for the whole time any tool runs; and an unwatched tool is still killed as collateral if a *watched* sibling in the same turn overruns, because pi runs sibling tool calls concurrently and the abort ends the whole turn. Stored as exemptions, so the default and every tool pi-task has never seen stay guarded. |
 | **ext: …** | all off | One toggle per installed host `pi` extension, loading it into every child session by explicit path. Children otherwise run with extensions off, so a provider registered by an extension (e.g. `pi-lmstudio`) doesn't exist in them and they can't resolve the default model. Children also inherit the extension's tools and hooks, so only enable ones you trust. The list is strictly additive (discovery stays off), and an entry whose file is gone is skipped at spawn time, never fatal. |
@@ -226,6 +239,8 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | --- | --- | --- |
 | `BRAVE_SEARCH_API_KEY` / `BRAVE_API_KEY` | `pi-worker-search`, research enrichment | Required only when the **Brave** search engine is selected in `/task-config`. |
 | `XDG_CACHE_HOME` | `pi-worker-docs` | Overrides the docs cache location (defaults to `~/.cache`). |
+| `CARGO_HOME` | `pi-worker-docs` | Where crate source checkouts are read from (defaults to `~/.cargo`). |
+| `CABAL_DIR` | `pi-worker-docs` | Where cabal's downloaded package tarballs are read from (also checks `~/.cabal/packages` and `${XDG_CACHE_HOME:-~/.cache}/cabal/packages`). |
 | `XDG_DATA_HOME` | remote push | Where the VAPID keypair is stored (defaults to `~/.local/share`). |
 | `PI_REMOTE_PUSH_SUBJECT` | remote push | VAPID JWT `sub` contact. Defaults to the project URL; set your own `mailto:you@domain.com` or `https://…`. |
 | `PI_REMOTE_PUSH_DEBUG` | remote push | When set (e.g. `1`), logs push delivery and push-service HTTP status. Off by default. |
@@ -244,12 +259,12 @@ them checked in.
 
 ```sh
 bun install
-bun run test       # 4119 tests across 227 files
+bun run test       # 4281 tests across 234 files
 bun run lint       # prettier + eslint + tsc --noEmit
 bun run build      # tsc → dist/
 ```
 
-Built with [Bun](https://bun.sh), TypeScript (strict), and [TypeBox](https://github.com/sinclairzx81/typebox) for tool schemas. Design docs and plans live in [`docs/`](./docs).
+Built with [Bun](https://bun.sh), TypeScript (strict), and [TypeBox](https://github.com/sinclairzx81/typebox) for tool schemas. Design plans live in [`plans/`](./plans).
 
 ## License
 

package/dist/task/context-attribution.js

@@ -154,17 +154,29 @@ export function splitBulletSpans(context) {
 export function splitBullets(context) {
     return splitBulletSpans(context).map(s => s.text);
 }
+/**
+ * A version block is headed by its REGISTRY, so the heading is open-ended
+ * (`crates.io`, `hackage`). Anything else is one: the widened pattern also reads
+ * headings out of a retrieved README or page BODY, and calling those `docs` would
+ * let a package's own text forge the block that sources a semantics claim.
+ */
+function blockKind(heading) {
+    if (heading === 'freshness-check')
+        return 'freshness-skipped';
+    if (heading === 'docs' || heading === 'url' || heading === 'service')
+        return heading;
+    return 'npm';
+}
 /** Parse the `### npm:` / `### docs:` / `### url:` / `### service:` blocks out of an EXTERNAL CONTEXT header. */
 export function parseContextBlocks(externalContext) {
     const out = [];
-    const re = /^###\s+(npm|docs|url|service|freshness-check)\s*:?\s*(.*)$/gim;
+    // A version block is headed by its REGISTRY, so `npm` is one of several
+    // (`crates.io`, `hackage`). Matching only the fixed words made every non-npm
+    // block invisible to the parser.
+    const re = /^###\s+([A-Za-z][\w.-]*)\s*:?\s*(.*)$/gim;
     let m;
     while ((m = re.exec(externalContext)) !== null) {
-        const kind = m[1].toLowerCase();
-        out.push({
-            kind: kind === 'freshness-check' ? 'freshness-skipped' : kind,
-            subject: m[2].trim()
-        });
+        out.push({ kind: blockKind(m[1].toLowerCase()), subject: m[2].trim() });
     }
     return out;
 }

package/dist/task/external-context.d.ts

@@ -36,6 +36,8 @@ type GatherDeps = Pick<PhaseDeps, 'cwd' | 'signal' | 'recordSubStep' | 'docsRaw'
 export interface ExternalTargetResult {
     /** Emitted as an `### npm:` block ahead of every body. Absent for url targets. */
     npmVersion?: NpmVersionInfo | null;
+    /** Which registry the version block came from; npm when absent. */
+    registryLabel?: string;
     /**
      * The `### docs:`/`### url:` body. `undefined` means "this target contributes no
      * body block" — and the two call paths draw that line differently ON PURPOSE:
@@ -68,6 +70,11 @@ export interface ExternalContextLookups {
  * question, in front of a waiting user, while research is uncapped and trails its
  * sub-step.
  */
+/** A live version answer and the registry it came from, for the block heading. */
+export interface VersionBlock {
+    info: NpmVersionInfo;
+    label: string;
+}
 export interface ExternalContextPolicy {
     /**
      * Max combined docs+url targets fanned out, packages first. Omit for uncapped
@@ -83,7 +90,7 @@ export interface ExternalContextPolicy {
      * version at all, and a "which version?" question falls back to whatever the
      * model remembers — which is how a dependency gets pinned to a stale major.
      */
-    versionLookup?: (pkg: string) => Promise<NpmVersionInfo | null>;
+    versionLookup?: (pkg: string) => Promise<VersionBlock | null>;
     /** Sub-step label recorded via `deps.recordSubStep`. Omit to record nothing. */
     subStepLabel?: string;
     /**

package/dist/task/external-context.js

@@ -22,6 +22,7 @@
  * Run against a mixed source, the emitted headings come out in exactly that order:
  * `### npm:` then `### docs:` then `### url:` then `### service:`.
  */
+import { chooseEcosystem, defaultEcosystemIo } from '../workers/docs-ecosystems.js';
 import { docsRaw } from '../workers/docs-core.js';
 import { fetchRaw } from '../workers/fetch-core.js';
 import { formatNpmVersionSection, npmVersionLookup } from '../workers/npm-version.js';
@@ -61,6 +62,14 @@ export async function buildExternalContext(source, deps, lookups, policy = {}) {
         }).catch(() => null))),
         Promise.all(versionLookup ? extraVersionPkgs.map(pkg => versionLookup(pkg).catch(() => null)) : [])
     ]);
+    // A docs target that came back WITHOUT a version — a refused ecosystem, a dead
+    // registry — was dropped from `extraVersionPkgs` on the assumption docs would
+    // supply it. Ask for it now, or its block is silently lost.
+    const missedVersionPkgs = versionLookup ?
+        enrichTargets.versionPackages.filter(p => docsTargets.has(p)
+            && !targets.some((t, i) => t.name === p && targetResults[i]?.npmVersion))
+        : [];
+    const missedVersionResults = await Promise.all(missedVersionPkgs.map(pkg => versionLookup(pkg).catch(() => null)));
     const sections = [];
     // npm version blocks lead the section so the model anchors on live version
     // data before reading any docs body. The docs-fetched packages carry their
@@ -69,11 +78,11 @@ export async function buildExternalContext(source, deps, lookups, policy = {}) {
     // named dep.
     for (const r of targetResults) {
         if (r?.npmVersion)
-            sections.push(formatNpmVersionSection(r.npmVersion));
+            sections.push(formatNpmVersionSection(r.npmVersion, r.registryLabel));
     }
-    for (const v of extraVersionResults) {
+    for (const v of [...extraVersionResults, ...missedVersionResults]) {
         if (v)
-            sections.push(formatNpmVersionSection(v));
+            sections.push(formatNpmVersionSection(v.info, v.label));
     }
     for (let i = 0; i < targets.length; i++) {
         const body = targetResults[i]?.body;
@@ -118,6 +127,44 @@ export async function gatherExternalContext(refined, deps) {
     const fetchRawFn = deps.fetchRaw ?? fetchRaw;
     const npmVersionFn = deps.npmVersionLookup ?? npmVersionLookup;
     const docsQuery = refined.split('\n').find(l => l.trim()) ?? refined;
+    // Which registry to ask, decided PER PACKAGE.
+    //
+    // A cargo-only project's dependency names are crate names, and asking npm
+    // about them returns a real but unrelated package's versions — the exact
+    // confusion the docs tool refuses. But deciding once for the whole repo makes
+    // every polyglot project ambiguous, and then NO version block is emitted at
+    // all: worse than the old always-npm, because the prompts tell the model to
+    // quote a block that will never be there. Each name carries its own evidence,
+    // so each name gets its own answer.
+    const io = defaultEcosystemIo(deps.signal ? { signal: deps.signal } : {});
+    const askNpm = async (pkg) => {
+        const info = await npmVersionFn(pkg, { signal: deps.signal });
+        return info ? { info, label: 'npm' } : null;
+    };
+    const versionLookup = async (pkg) => {
+        const choice = chooseEcosystem({
+            cwd: deps.cwd,
+            declaresPackage: p => p.declaredRange(p.parentPackage(pkg), deps.cwd) !== null,
+            resolvesLocally: p => {
+                try {
+                    p.resolve(pkg, deps.cwd, io);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }
+        });
+        // No manifest at all keeps npm, which is what a bare directory has always
+        // done. A name genuinely ambiguous between two registries gets no block —
+        // a version from the wrong registry is worse than none.
+        if (!choice.ok)
+            return choice.reason === 'none' ? askNpm(pkg) : null;
+        if (choice.profile.id === 'npm')
+            return askNpm(pkg);
+        const info = await choice.profile.latest(pkg, io);
+        return info ? { info, label: choice.profile.registryLabel } : null;
+    };
     return buildExternalContext(refined, deps, {
         docs: async (pkg) => {
             const r = await docsRawFn({
@@ -128,6 +175,7 @@ export async function gatherExternalContext(refined, deps) {
             });
             return {
                 npmVersion: r.npmVersion,
+                ...(r.registryLabel ? { registryLabel: r.registryLabel } : {}),
                 body: r.kind === 'ok' && r.chunks.length > 0 ?
                     r.chunks
                         .map(c => c.content)
@@ -142,7 +190,7 @@ export async function gatherExternalContext(refined, deps) {
         },
         search: deps.searchFn
     }, {
-        versionLookup: pkg => npmVersionFn(pkg, { signal: deps.signal }),
+        versionLookup,
         subStepLabel: 'enrichment',
         earlyReturnOnNoTargets: true
     });

package/dist/task/phases.js

@@ -4,6 +4,7 @@
  */
 import { fileURLToPath } from 'node:url';
 import { docsFocused } from '../workers/docs-core.js';
+import { detectEcosystems } from '../workers/docs-ecosystems.js';
 import { fetchFocused } from '../workers/fetch-core.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { findPhantomImports, formatApiCorrections, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
@@ -550,7 +551,7 @@ export async function phaseResearch(deps, refined) {
             // queries the FILES worker just answered.
             prompt: prior => orientation.block
                 + promptHeader
-                + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined)
+                + RESEARCH_APIS_PROMPT(refined, prior.find(s => s.name === 'FILES')?.text || undefined, detectEcosystems(deps.cwd))
                 + (searchConfigured() ? RESEARCH_SEARCH_HINT : '')
                 // Empty unless PI_TASK_PROJECT_DOCS_BUDGET is set. The tool-side
                 // half lives in pi-worker-docs.ts; a budget enforced without being

package/dist/task/prompts.d.ts

@@ -26,7 +26,13 @@ export declare const COMPRESS_LABEL_PROMPT: (title: string, maxChars: number) =>
 declare const REFINE_PROMPT: (raw: string, planContext?: string, existingFiles?: string, contracts?: string, directives?: string) => string;
 declare const RESEARCH_READ_ONLY_CONSTRAINT = "IMPORTANT: You are ONLY allowed to READ. Do NOT create, modify, or delete any files. Use the read, grep, find, and ls tools to inspect the repo.";
 declare const RESEARCH_FILES_PROMPT: (refined: string) => string;
-declare const RESEARCH_APIS_PROMPT: (refined: string, filesMap?: string) => string;
+/**
+ * `ecosystems` is what `detectEcosystems` found in the worker's cwd. It is REQUIRED,
+ * and an empty list is a real answer: a directory with no package manifest has no
+ * registry to look a library up in, and the paragraph below has to say so rather
+ * than inviting a lookup that will be refused.
+ */
+declare const RESEARCH_APIS_PROMPT: (refined: string, filesMap: string | undefined, ecosystems: readonly string[]) => string;
 declare const RESEARCH_CONTEXT_PROMPT: (refined: string) => string;
 declare const RESEARCH_TOOLING_PROMPT: (refined: string) => string;
 declare const GRILL_GEN_PROMPT: (refined: string, research: string, priorQA: string) => string;

package/dist/task/prompts.js

@@ -97,13 +97,23 @@ No section header. No other sections. No preamble.
 
 Task:
 ${refined}`;
-const RESEARCH_APIS_PROMPT = (refined, filesMap) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools — and \`pi-worker-docs\` for installed npm packages — to identify the commands, functions, types, and interfaces the agent will use for the following task.
+/**
+ * `ecosystems` is what `detectEcosystems` found in the worker's cwd. It is REQUIRED,
+ * and an empty list is a real answer: a directory with no package manifest has no
+ * registry to look a library up in, and the paragraph below has to say so rather
+ * than inviting a lookup that will be refused.
+ */
+const RESEARCH_APIS_PROMPT = (refined, filesMap, ecosystems) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools${ecosystems.length ? ' — and `pi-worker-docs` for installed packages —' : ''} to identify the commands, functions, types, and interfaces the agent will use for the following task.
 
-NPM PACKAGES — use pi-worker-docs, NOT file reads: for any third-party npm package (e.g. "zod", "hono", "drizzle-orm"), call \`pi-worker-docs(module, query)\` to get its type signatures and API surface. Do NOT open node_modules source files directly — those reads are expensive and produce far more noise than the tool. The tool returns a compact, focused excerpt in a fraction of the token cost.
+${ecosystems.length ?
+    `LIBRARY PACKAGES — use pi-worker-docs, NOT file reads: for any third-party package, call \`pi-worker-docs(module, query)\` to get its type signatures and API surface. Do NOT open installed-package source files directly — those reads are expensive and produce far more noise than the tool. The tool returns a compact, focused excerpt in a fraction of the token cost. This project's package ecosystems are: ${ecosystems.join(', ')}.`
+    : 'LIBRARY PACKAGES — do NOT look them up: this directory holds no package manifest, so `pi-worker-docs` has no registry to read and will refuse. Do not list an external library API you cannot check here.'}
 
-PROJECT SOURCE — use pi-worker-docs with module ".", NOT file reads: for any function, class, type, or interface defined in THIS project's own .ts/.tsx source (e.g. "what does requireAuth check?", "what does CreateListingSchema look like?", "what does the listings query module export?"), call \`pi-worker-docs(".", query)\` instead of reading the file. The tool indexes all git-tracked source files and returns only the relevant chunks — far cheaper than reading whole files.
+PROJECT SOURCE — use pi-worker-docs with module ".", NOT file reads: for any function, class, type, or interface defined in THIS project's own source (e.g. "what does requireAuth check?", "what does CreateListingSchema look like?", "what does the listings query module export?"), call \`pi-worker-docs(".", query)\` instead of reading the file. The tool indexes all git-tracked source files and returns only the relevant chunks — far cheaper than reading whole files.
 
-RUNTIME BUILTINS — verify, do NOT echo: a task (or the spec doc it references) may name a runtime/builtin import like \`bun:sql\`, \`bun:sqlite\`, \`node:fs\`, or \`Bun.password\`. A runtime exposes only a small FIXED set of \`<runtime>:<submodule>\` modules, and a spec doc can confidently name one that does not exist. Before you list ANY \`<pkg>:<sub>\` specifier, confirm it with \`pi-worker-docs\` (e.g. \`pi-worker-docs("bun:sql", "sql tagged template and SQL class — the import")\` — the tool resolves the runtime's real types) and emit the CANONICAL import the types actually prove, NOT the string copied from the task. Concretely: Bun's SQL client is \`import { sql } from "bun"\` (or \`Bun.sql\` / \`new SQL()\`) — there is NO \`bun:sql\` module. Never pass an unverified colon-specifier through to the APIS list; a phantom import laundered here becomes fabricated \`declare module\` shims in the implementation.
+${ecosystems.includes('npm') ?
+    `RUNTIME BUILTINS — verify, do NOT echo: a task (or the spec doc it references) may name a runtime/builtin import like \`bun:sql\`, \`bun:sqlite\`, \`node:fs\`, or \`Bun.password\`. A runtime exposes only a small FIXED set of \`<runtime>:<submodule>\` modules, and a spec doc can confidently name one that does not exist. Before you list ANY \`<pkg>:<sub>\` specifier, confirm it with \`pi-worker-docs\` (e.g. \`pi-worker-docs("bun:sql", "sql tagged template and SQL class — the import")\` — the tool resolves the runtime's real types) and emit the CANONICAL import the types actually prove, NOT the string copied from the task. Concretely: Bun's SQL client is \`import { sql } from "bun"\` (or \`Bun.sql\` / \`new SQL()\`) — there is NO \`bun:sql\` module. Never pass an unverified colon-specifier through to the APIS list; a phantom import laundered here becomes fabricated \`declare module\` shims in the implementation.`
+    : ''}
 
 APIS owns symbols and commands BY NAME ONLY. Do NOT include any file path or path fragment — no \`package.json\`, no \`./src/foo.ts\`, no \`package.json#scripts.lint\`. If the symbol is a script defined in package.json, write the invocation (\`npm run lint\`), not its location. If the symbol is a config file, it does not belong in APIS at all — it belongs in FILES.
 

package/dist/workers/docs-cache.js

@@ -2,24 +2,37 @@ import { createRequire } from 'node:module';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+/**
+ * Bump whenever the shape below changes in a way old rows cannot satisfy. The
+ * migration is a DROP and rebuild: this is a derived cache of package sources,
+ * so re-indexing costs a walk, and hand-written ALTERs cost a defect class.
+ */
+const SCHEMA_VERSION = 1;
+/**
+ * `ecosystem` scopes every row to the registry it came from, so `text` on npm and
+ * `text` on Hackage are different packages. Project-source rows use their own
+ * scope value rather than a registry id.
+ */
 const SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS packages (
+  ecosystem    TEXT NOT NULL DEFAULT 'npm',
   name         TEXT NOT NULL,
   version      TEXT NOT NULL,
   content_hash TEXT NOT NULL,
   indexed_at   INTEGER NOT NULL,
-  PRIMARY KEY (name, version)
+  PRIMARY KEY (ecosystem, name, version)
 );
 
 CREATE TABLE IF NOT EXISTS chunks (
   id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  ecosystem TEXT NOT NULL DEFAULT 'npm',
   name      TEXT NOT NULL,
   version   TEXT NOT NULL,
   file_path TEXT NOT NULL,
   kind      TEXT NOT NULL CHECK (kind IN ('dts','readme')),
   content   TEXT NOT NULL
 );
-CREATE INDEX IF NOT EXISTS chunks_pkg ON chunks(name, version);
+CREATE INDEX IF NOT EXISTS chunks_pkg ON chunks(ecosystem, name, version);
 
 CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
   content,
@@ -34,6 +47,14 @@ CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
   INSERT INTO chunks_fts(chunks_fts, rowid, content) VALUES('delete', old.id, old.content);
 END;
 `;
+// Order matters: the triggers and the FTS index reference `chunks`.
+const DROP_SQL = `
+DROP TRIGGER IF EXISTS chunks_ai;
+DROP TRIGGER IF EXISTS chunks_ad;
+DROP TABLE IF EXISTS chunks_fts;
+DROP TABLE IF EXISTS chunks;
+DROP TABLE IF EXISTS packages;
+`;
 const req = createRequire(import.meta.url);
 // Branch on the RUNTIME, not on a try/catch: each builtin exists in exactly one
 // of them. Requiring `bun:sqlite` under node throws MODULE_NOT_FOUND, and
@@ -61,9 +82,35 @@ export function openCache(dbPath) {
     db.exec('PRAGMA journal_mode = WAL;');
     db.exec('PRAGMA synchronous = NORMAL;');
     db.exec('PRAGMA foreign_keys = ON;');
-    db.exec(SCHEMA_SQL);
+    // A blocking busy handler, not a tuned delay: research children open this
+    // cache concurrently, and the loser of the migration lock has to WAIT for the
+    // winner's COMMIT rather than throw SQLITE_BUSY on the spot. The bound only
+    // stops a wedged handle hanging the worker forever.
+    db.exec('PRAGMA busy_timeout = 30000;');
+    migrate(db);
     return {
         db,
         close: () => db.close()
     };
 }
+/**
+ * `CREATE TABLE IF NOT EXISTS` is a no-op against an older shape, so the version
+ * check has to run BEFORE it or a stale table survives untouched.
+ */
+function migrate(db) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const row = db.prepare('PRAGMA user_version').get();
+        // A brand-new database also reads 0, hence DROP ... IF EXISTS.
+        if ((row?.user_version ?? 0) < SCHEMA_VERSION) {
+            db.exec(DROP_SQL);
+            db.exec(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+        }
+        db.exec(SCHEMA_SQL);
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+    }
+}

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

@@ -53,15 +53,18 @@ export declare function splitAtMatches(text: string, re: RegExp): string[];
  */
 export declare function sliceBytes(s: string, maxBytes: number): string[];
 /**
- * Chunk a declaration file (`.d.ts`, `.ts`, `.tsx`), one chunk per declaration,
- * each labelled with the file it came from.
+ * Chunk a declaration file, one chunk per declaration, each labelled with the
+ * file it came from.
  *
  * `relPath` is a MODEL-FACING label and is used exactly as given. docs-index.ts
  * normalises it to POSIX (`.replace(/\\/g, '/')`) so a package index is identical
  * across platforms; docs-project.ts passes `path.relative` through with the native
  * separator. It is never re-joined to the filesystem, so neither is wrong — this
  * leaves the choice with the caller that has a reason for it.
+ *
+ * `splitRe` and `commentPrefix` default to the TypeScript pair, which is what
+ * both the project corpus and npm packages are written in.
  */
-export declare function chunkDeclarations(content: string, relPath: string): string[];
+export declare function chunkDeclarations(content: string, relPath: string, splitRe?: RegExp, commentPrefix?: string): string[];
 /** Chunk a README, one chunk per top-level section, each labelled by heading. */
 export declare function chunkReadme(content: string): string[];

package/dist/workers/docs-chunk.js

@@ -90,22 +90,25 @@ export function sliceBytes(s, maxBytes) {
     return out;
 }
 /**
- * Chunk a declaration file (`.d.ts`, `.ts`, `.tsx`), one chunk per declaration,
- * each labelled with the file it came from.
+ * Chunk a declaration file, one chunk per declaration, each labelled with the
+ * file it came from.
  *
  * `relPath` is a MODEL-FACING label and is used exactly as given. docs-index.ts
  * normalises it to POSIX (`.replace(/\\/g, '/')`) so a package index is identical
  * across platforms; docs-project.ts passes `path.relative` through with the native
  * separator. It is never re-joined to the filesystem, so neither is wrong — this
  * leaves the choice with the caller that has a reason for it.
+ *
+ * `splitRe` and `commentPrefix` default to the TypeScript pair, which is what
+ * both the project corpus and npm packages are written in.
  */
-export function chunkDeclarations(content, relPath) {
+export function chunkDeclarations(content, relPath, splitRe = DECL_SPLIT_RE, commentPrefix = '//') {
     const chunks = [];
-    for (const part of splitAtMatches(content, new RegExp(DECL_SPLIT_RE.source, 'gm'))) {
+    for (const part of splitAtMatches(content, new RegExp(splitRe.source, 'gm'))) {
         const trimmed = part.trim();
         if (!trimmed)
             continue;
-        const prefixed = `// ${relPath}\n${trimmed}`;
+        const prefixed = `${commentPrefix} ${relPath}\n${trimmed}`;
         if (Buffer.byteLength(prefixed, 'utf8') > MAX_CHUNK_BYTES) {
             for (const slice of sliceBytes(prefixed, MAX_CHUNK_BYTES))
                 chunks.push(slice);

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

@@ -1,5 +1,6 @@
 import { openCache as defaultOpenCache } from './docs-cache.js';
 import { ensureIndexed as defaultEnsureIndexed } from './docs-index.js';
+import { type EcosystemId, type EcosystemIo, type EcosystemProfile } from './docs-ecosystems.js';
 import { resolvePackage as defaultResolvePackage, type ResolvedPackage } from './docs-resolve.js';
 import { retrieveChunks as defaultRetrieveChunks, type RetrievedChunk } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup, type NpmVersionInfo } from './npm-version.js';
@@ -37,6 +38,8 @@ export type DocsRawResult = {
     autoInstalled?: boolean;
     autoInstallPin?: AutoInstallPin;
     npmVersion?: NpmVersionInfo | null;
+    /** The registry the answer came from, for the block that leads it. */
+    registryLabel?: string;
 } | {
     kind: 'no_chunks';
     pkg: ResolvedPackage;
@@ -46,10 +49,12 @@ export type DocsRawResult = {
     autoInstalled?: boolean;
     autoInstallPin?: AutoInstallPin;
     npmVersion?: NpmVersionInfo | null;
+    /** The registry the answer came from, for the block that leads it. */
+    registryLabel?: string;
 } | {
     kind: 'error';
     message: string;
-    resolveError?: 'not_installed' | 'invalid_name';
+    resolveError?: 'not_installed' | 'invalid_name' | 'unsupported_ecosystem' | 'ambiguous_ecosystem';
     installError?: string;
     version?: string;
     hitCache?: boolean;
@@ -57,11 +62,15 @@ export type DocsRawResult = {
     autoInstalled?: boolean;
     autoInstallPin?: AutoInstallPin;
     npmVersion?: NpmVersionInfo | null;
+    /** The registry the answer came from, for the block that leads it. */
+    registryLabel?: string;
 };
 export interface DocsRawInput {
     pkg: string;
     query: string;
     cwd: string;
+    /** Which registry to read, for a repo holding more than one manifest. */
+    ecosystem?: EcosystemId;
     autoInstall?: boolean;
     resolvePackage?: typeof defaultResolvePackage;
     ensureIndexed?: typeof defaultEnsureIndexed;
@@ -69,6 +78,8 @@ export interface DocsRawInput {
     openCache?: typeof defaultOpenCache;
     spawn?: SpawnFn;
     npmVersionLookup?: typeof defaultNpmVersionLookup;
+    /** Overrides for the filesystem and network a non-npm row reaches through. */
+    io?: Partial<EcosystemIo>;
     signal?: AbortSignal;
 }
 export interface DocsFocusedResult {
@@ -162,7 +173,7 @@ export declare function findDeclaredRange(parentPkg: string, cwd: string): strin
  * `bun`, and cannot declare `bun-types`, so a sentence about what package.json
  * does or does not say has to be a sentence about `bun`.
  */
-export declare function buildVersionBanner(pin: AutoInstallPin | undefined, resolved: string, version: string, cwd: string): string;
+export declare function buildVersionBanner(pin: AutoInstallPin | undefined, resolved: string, version: string, cwd: string, profile?: EcosystemProfile): string;
 export declare function getDocsModulesDir(): string;
 export declare function ensureDocsModulesDir(dir: string): void;
 /**
@@ -207,8 +218,13 @@ export interface AcquireInput {
     name: string;
     cwd: string;
     spawn: SpawnFn;
-    resolvePackage: typeof defaultResolvePackage;
+    /** Overrides `profile.resolve` when given, for callers that inject a resolver. */
+    resolvePackage?: typeof defaultResolvePackage;
     signal: AbortSignal | undefined;
+    /** Which registry to acquire from. */
+    profile?: EcosystemProfile;
+    /** The row's filesystem and network reach. Built from `spawn` when absent. */
+    io?: EcosystemIo;
 }
 /**
  * Get a package onto disk and resolved: resolve from `cwd`, and on
@@ -231,6 +247,14 @@ export interface AcquireInput {
  * sites should differ only about WHETHER to install, never about HOW.
  */
 export declare function acquirePackage(input: AcquireInput): Promise<AcquireOutcome>;
+/** The docs pipeline's adapter over the shared redirect walk (docs-resolve.ts):
+ *  hops resolve through the auto-installing lookup, so a declaration package that is
+ *  declared but not yet on disk is fetched rather than abandoned. */
+export declare function resolveTypeSourceForDocs(pkg: ResolvedPackage, requested: string, cwd: string, spawn: SpawnFn, resolvePackage: typeof defaultResolvePackage, signal: AbortSignal | undefined): Promise<{
+    pkg: ResolvedPackage;
+    installed: boolean;
+    pin?: AutoInstallPin;
+}>;
 export declare function docsRaw(input: DocsRawInput): Promise<DocsRawResult>;
 export declare function docsFocused(input: DocsFocusedInput): Promise<DocsFocusedResult>;
 export declare function buildPrompt(pkg: ResolvedPackage, query: string, content: string): string;