@r3b1s/pi-repair-layer 0.3.0 → 0.4.0

package/README.md

@@ -8,6 +8,20 @@ same repair pipeline to tools in your own extension.
 
 No LLM calls. No network requests. No uploaded telemetry.
 
+## Contents
+
+- [Why use it?](#why-use-it)
+- [Install](#install)
+- [Terms in plain English](#terms-in-plain-english)
+- [What it repairs](#what-it-repairs)
+- [Safe by design](#safe-by-design)
+- [Use it in your own extension](#use-it-in-your-own-extension)
+- [Settings and local telemetry](#settings-and-local-telemetry)
+- [Documentation](#documentation)
+- [Prior art](#prior-art)
+- [Limitations](#limitations)
+- [Development](#development)
+
 ## Why use it?
 
 Models often understand the task but miss a detail of the tool contract:

package/docs/research.md

@@ -23,6 +23,16 @@ is protecting and where to re-verify it.
   `test/upstream-drift.test.ts` that execute the claims against the installed
   packages.
 
+Claims 10–14 (optional integration) were added later with their own provenance:
+
+- **Verification date:** 2026-07-18
+- **Source read:** the same pi clone (`v0.80.6-24-g0e6909f0`); line citations
+  below refer to it.
+- **Empirical runs:** a live pi 0.80.10 install (npm-dist `cli.js` under
+  Node 24) and the official `pi-linux-x64` release binary v0.80.10 (Bun
+  compiled executable), each driven with a throwaway probe extension
+  npm-installed into an isolated `$HOME/.pi/agent/npm` scope.
+
 ## Claims
 
 ### Claim 1 — Loop ordering: `prepareArguments` runs before validation, which runs before the `tool_call` event
@@ -202,6 +212,124 @@ queues value-free feedback, binds it at post-validation `tool_call`, then uses
 custom calls already have IDs and can be associated directly, without wrapping
 another extension's executor.
 
+### Claim 10 — pi maintains one shared npm install project per scope, with flat sibling resolution
+
+All `npm:`-installed extensions in a scope are dependencies of a single private
+npm project named `pi-extensions`, so their packages sit side by side in one
+flat `node_modules`. An end user who runs
+`pi install npm:@r3b1s/pi-repair-layer` therefore makes the package resolvable
+from every other npm-installed extension in that scope.
+
+- `packages/coding-agent/src/core/package-manager.ts:1933-1944` —
+  `ensureNpmProject` writes `{ name: "pi-extensions", private: true }` into the
+  install root's `package.json`.
+- `packages/coding-agent/src/core/package-manager.ts:1956-1964` —
+  `getNpmInstallRoot` returns `join(this.agentDir, "npm")` for the user scope
+  (project scope roots under the project's config dir instead).
+- Live install (pi 0.80.10): `~/.pi/agent/npm/package.json` has
+  `name: "pi-extensions"` with every npm-installed extension as a dependency,
+  and `node_modules` holds them as flat siblings (bun-backed, `bun.lock`
+  present).
+
+**Why it matters:** this is the mechanism behind the shared-`node_modules`
+adoption path in the optional-integration recipe
+(`docs/tool-owner-integration.md`). It is observed managed-install layout, not
+a documented pi API guarantee — the recipe never *depends* on it (resolution
+either succeeds or falls back safely), but the adoption story does.
+
+### Claim 11 — Missing-module error shapes: `MODULE_NOT_FOUND` (jiti/require) vs `ERR_MODULE_NOT_FOUND` (ESM import)
+
+A dynamic import of an uninstalled package surfaces differently depending on
+the loader, but always with one of two `code` values and a message that names
+the requested module:
+
+- jiti 2.7.0 require path (Node): plain `Error`, `code: "MODULE_NOT_FOUND"`,
+  message `Cannot find module '<full specifier>'`.
+- Native Node ESM `import()` (Node 24): `Error`,
+  `code: "ERR_MODULE_NOT_FOUND"`, message
+  `Cannot find package '<package name>'` — **it names the bare package, not
+  the full subpath specifier**, so absence checks must match the package name
+  (`@r3b1s/pi-repair-layer`), never the `/pi` subpath string.
+- Compiled Bun binary (pi-linux-x64 v0.80.10): Bun `ResolveMessage` (an
+  `Error` subclass), `code: "ERR_MODULE_NOT_FOUND"` for `import()` and
+  `"MODULE_NOT_FOUND"` for a scoped `require`, message
+  `Cannot find module '<full specifier>' from '<importer path>'`.
+
+**Why it matters:** the optional-integration recipe treats an import failure
+as "package absent" only when the code is one of these two values **and** the
+message names `@r3b1s/pi-repair-layer`; anything else rethrows so a broken
+install (a *transitive* module missing) is not silently misread as absent.
+All three observed shapes pass that discrimination.
+
+### Claim 12 — Git installs and other scopes do not resolve the shared npm siblings
+
+Git-installed extensions are cloned into `<agentDir>/git/<host>/<path>` and get
+their **own** dependency install inside the clone; they are not siblings of the
+shared npm root. User scope (`~/.pi/agent`) and project scope (`<cwd>/.pi`)
+likewise use separate install roots.
+
+- `packages/coding-agent/src/core/package-manager.ts:1820-1846` — `installGit`
+  clones into `getGitInstallPath(...)` and runs a dependency install inside the
+  clone when it has a `package.json`.
+- `packages/coding-agent/src/core/package-manager.ts:2036-2046` —
+  `getGitInstallRoot` returns `join(this.agentDir, "git")` (user scope) or
+  `join(this.cwd, CONFIG_DIR_NAME, "git")` (project scope).
+
+**Why it matters:** a git-installed or cross-scope consumer cannot resolve an
+npm-installed `@r3b1s/pi-repair-layer` sibling, so the optional recipe falls
+back there even though the user "installed" the package. Documented as a hard
+caveat in the integration guide; `optionalDependencies` is the alternative for
+those consumers.
+
+### Claim 13 — Bun-binary probe: the optional dynamic import falls back under the compiled binary, resolves under npm-dist pi
+
+pi loads extensions through jiti (`moduleCache: false`; in the compiled binary
+additionally `virtualModules` + `tryNative: false`; under Node, `alias`):
+
+- `packages/coding-agent/src/core/extensions/loader.ts:398-404` — the
+  `createJiti` call and both option branches.
+
+End-to-end probe (2026-07-18): a throwaway extension implementing the
+documented recipe, npm-installed into an isolated scope, run once with
+`@r3b1s/pi-repair-layer` npm-installed as a sibling and once without, under
+both pi distributions of v0.80.10:
+
+| runtime | package | observed error (`name`/`code`) | branch taken |
+|---|---|---|---|
+| npm-dist (Node) | absent | `Error`/`ERR_MODULE_NOT_FOUND` | fallback, note emitted |
+| npm-dist (Node) | present | — | **adapted** |
+| compiled binary | absent | `ResolveMessage`/`ERR_MODULE_NOT_FOUND` | fallback, note emitted |
+| compiled binary | present | `ResolveMessage`/`ERR_MODULE_NOT_FOUND` | fallback, note emitted |
+
+Under the compiled Bun binary, *static* imports of the sibling package do
+resolve (jiti's own resolver handles them — verified with a static-import
+probe extension in the same scope), but native dynamic `import()` and the
+scoped `require` both bypass jiti and hit Bun's embedded resolver, which does
+no filesystem `node_modules` resolution — even an absolute-path `import()` of
+the package's entry file loads but then dies on its transitive bare specifier
+(`typebox/value`). There is no consumer-accessible dynamic path through jiti's
+resolver as of this pi version.
+
+**Why it matters:** the optional-integration pattern *activates* only under
+Node-based pi installs (npm/bun global install). Under the official compiled
+binary it degrades safely — the import failure has exactly the absent-package
+shape, so consumers fall back to their raw definition with the one-line note,
+even when the package is installed. A hard static dependency, by contrast,
+works under both distributions. Both facts are documented in the integration
+guide's caveats.
+
+### Claim 14 — Unrecognized preprocessor kinds fall through `preprocessInput` untouched (local guarantee)
+
+This claim is about this repo, not pi: `preprocessInput`
+(`src/preprocess.ts`) matches each configured entry against the known `kind`
+branches and simply skips entries it does not recognize — no mutation, no
+error, no claimed change — and the pipeline still schema-validates the final
+result. A consumer configured against a newer options shape therefore degrades
+to the recognized subset when running against an older installed version.
+Promoted to a spec-level compatibility guarantee by the
+`optional-integration-fallback` change and pinned by a unit test in
+`test/pipeline.test.ts`.
+
 ### Package/runtime assumptions
 
 The published package targets Node 22+ and compiled ESM. `typebox` is a runtime
@@ -245,3 +373,18 @@ work through this list and update the citations/date above:
    messages, and handlers still compose in registration order.
 10. **Package/runtime:** run `pnpm run test:package`; re-check Node engines,
     peer/runtime dependencies, every `exports` target, and the pi extension path.
+11. **Shared npm root (Claim 10):** confirm `ensureNpmProject` still writes one
+    `pi-extensions` project per scope and installs remain flat siblings —
+    re-read `package-manager.ts` and inspect a live `~/.pi/agent/npm`.
+12. **Error shapes (Claim 11):** re-run a missing-module import under jiti, under
+    native Node `import()`, and under the compiled binary; confirm the codes are
+    still `MODULE_NOT_FOUND` / `ERR_MODULE_NOT_FOUND` and the message still names
+    the requested package.
+13. **Git/scope boundaries (Claim 12):** confirm git installs still get their own
+    clone-local dependency install and scopes still use separate install roots.
+14. **Bun-binary probe (Claim 13):** re-run the four-cell probe (npm-dist and
+    compiled binary, package present and absent) with a throwaway recipe
+    extension npm-installed into an isolated `$HOME`; update the outcome table —
+    especially whether dynamic `import()` in the compiled binary has gained
+    filesystem `node_modules` resolution, which would let optional consumers
+    activate there.

package/docs/tool-owner-integration.md

@@ -5,6 +5,19 @@ pipeline to tools that extension owns. The usual integration is one wrapper
 around the tool definition. A lower-level core API is available when the tool
 owner needs to control the surrounding lifecycle.
 
+## Contents
+
+- [The ownership boundary](#the-ownership-boundary)
+- [Install the package](#install-the-package)
+- [Recommended: wrap the tool definition](#recommended-wrap-the-tool-definition)
+- [Optional integration](#optional-integration)
+- [Configure only known-safe transforms](#configure-only-known-safe-transforms)
+- [Existing `prepareArguments` hooks](#existing-preparearguments-hooks)
+- [Optional: receive structured outcomes](#optional-receive-structured-outcomes)
+- [Optional: attach `<repair_note>` feedback](#optional-attach-repair_note-feedback)
+- [Lower level: call the pure core](#lower-level-call-the-pure-core)
+- [Test the integration](#test-the-integration)
+
 ## The ownership boundary
 
 pi validates tool arguments after calling that tool's `prepareArguments`.
@@ -24,6 +37,12 @@ Add pi-repair-layer as a dependency of the extension that owns the tool:
 pnpm add @r3b1s/pi-repair-layer
 ```
 
+The dependency does not have to be hard. A standalone extension can keep
+pi-repair-layer out of its runtime dependencies entirely and degrade to its
+raw tool definition when the package is absent — see
+[Optional integration](#optional-integration) before committing your users to
+an extra install.
+
 The public APIs are compiled ESM with TypeScript declarations:
 
 - `@r3b1s/pi-repair-layer/pi` provides the pi tool-definition adapter.
@@ -112,6 +131,208 @@ model-readable retry message. `unrepairable: "passthrough"` is available for a
 deliberate compatibility migration, but it can expose the input to pi's native
 conversion and should not be the default.
 
+## Optional integration
+
+`adaptToolDefinition` is a pure decorator: it takes a `ToolDefinition` and
+returns a `ToolDefinition`. That makes the identity function a complete
+fallback — an extension can attempt to load the adapter at activation time and
+register its unmodified definition when pi-repair-layer is not installed.
+Repair support then becomes an end-user opt-in instead of an author-imposed
+dependency.
+
+### The recipe
+
+Author repair options as pure data, import only types at compile time, and
+attempt one dynamic import inside the (awaited) extension factory:
+
+```ts
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type {
+  adaptToolDefinition,
+  PiToolOwnerAdapterOptions,
+} from "@r3b1s/pi-repair-layer/pi";
+import { Type } from "typebox";
+
+const parameters = Type.Object({ path: Type.String() });
+
+const repairOptions = {
+  policy: "adaptive",
+  preprocessors: [
+    {
+      kind: "alias",
+      selector: "/path",
+      aliases: ["file_path"],
+      accepts: "string",
+    },
+  ],
+} satisfies PiToolOwnerAdapterOptions;
+
+const definition: ToolDefinition<typeof parameters> = {
+  name: "inspect_asset",
+  label: "Inspect asset",
+  description: "Inspect an asset",
+  parameters,
+  async execute(_toolCallId, params) {
+    return {
+      content: [{ type: "text", text: `Inspecting ${params.path}` }],
+      details: undefined,
+    };
+  },
+};
+
+async function loadRepairAdapter(): Promise<
+  typeof adaptToolDefinition | undefined
+> {
+  try {
+    const repair = await import("@r3b1s/pi-repair-layer/pi");
+    return repair.adaptToolDefinition;
+  } catch (error) {
+    const code = (error as { code?: unknown } | null)?.code;
+    const message = error instanceof Error ? error.message : String(error);
+    const packageAbsent =
+      (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND") &&
+      message.includes("@r3b1s/pi-repair-layer");
+    if (!packageAbsent) throw error;
+    return undefined;
+  }
+}
+
+export default async function myExtension(pi: ExtensionAPI) {
+  const adapt = await loadRepairAdapter();
+  if (!adapt) {
+    console.error(
+      "[my-extension] @r3b1s/pi-repair-layer not found; inspect_asset running unwrapped",
+    );
+  }
+  pi.registerTool(adapt ? adapt(definition, repairOptions) : definition);
+}
+```
+
+The details are load-bearing:
+
+- **Discriminate before falling back.** A missing package surfaces as
+  `code: "MODULE_NOT_FOUND"` (jiti's require path) or
+  `code: "ERR_MODULE_NOT_FOUND"` (native ESM and the compiled pi binary). But
+  a *present-but-broken* install — pi-repair-layer resolvable while one of its
+  own transitive modules is not — throws the same codes naming the
+  *transitive* module. Requiring the message to name
+  `@r3b1s/pi-repair-layer` keeps a broken install loud instead of silently
+  running unwrapped while the user believes repairs are active. Match the
+  package name, not the `/pi` subpath: native ESM reports only
+  `Cannot find package '@r3b1s/pi-repair-layer'`.
+- **Rethrow everything else.** Any other error is a real failure, not
+  absence.
+- **Emit one stderr line when falling back.** The two branches differ in
+  behavior (see the caveats below); a silent divergence cannot be diagnosed
+  from a session transcript.
+- **Keep repair options as pure data.** `satisfies PiToolOwnerAdapterOptions`
+  with a type-only import gives full typechecking with no runtime import, so
+  the compiled extension activates in installs without the package.
+
+The runnable, tested copy of this recipe is
+[`test/fixtures/optional-consumer.ts`](../test/fixtures/optional-consumer.ts);
+the package smoke test exercises both branches in clean projects. Keep the
+snippet above and that fixture in sync when editing either.
+
+### Consumer `package.json` shape
+
+```jsonc
+{
+  "devDependencies": {
+    // for typechecking and local tests only; erased from the runtime story
+    "@r3b1s/pi-repair-layer": "^0.3.0"
+  },
+  "peerDependencies": {
+    "@r3b1s/pi-repair-layer": ">=0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@r3b1s/pi-repair-layer": { "optional": true }
+  }
+}
+```
+
+`import type` and `satisfies` are erased at compile time, so the
+`devDependencies` entry is all that is needed to build. The optional peer
+declaration documents which versions the extension was written against
+without forcing an install.
+
+### Adoption paths
+
+**End-user opt-in via pi's shared install root (the default story).** pi
+installs every `npm:`-installed extension into one shared project per scope,
+so all such extensions sit side by side in a flat `node_modules`. When an end
+user runs:
+
+```bash
+pi install npm:@r3b1s/pi-repair-layer
+```
+
+to get repairs for pi's built-in tools, the package also becomes resolvable to
+every npm-installed extension in that scope — and consenting extensions using
+this recipe light up automatically. Nothing is required from the extension
+author beyond the recipe.
+
+**Author-controlled `optionalDependencies`.** An author who wants repairs
+whenever the environment can provide them can instead declare:
+
+```jsonc
+{
+  "optionalDependencies": {
+    "@r3b1s/pi-repair-layer": "^0.3.0"
+  }
+}
+```
+
+The package installs alongside the extension when possible, and a failed
+optional install does not fail the extension's install. This is also the path
+for consumers the shared-root story cannot reach (see the caveats).
+
+### Caveats
+
+- **Install source and scope matter.** The shared `node_modules` is per pi
+  scope, and only for `npm:` installs. Git-installed extensions get their own
+  clone-local dependency install, and project-scope installs do not resolve
+  user-scope siblings (or vice versa). Those consumers fall back even though
+  the user installed the package; `optionalDependencies` is the alternative
+  there. The layout is observed pi behavior (verified 0.80.6–0.80.10), not a
+  documented pi guarantee — see
+  [research Claim 10](research.md#claim-10--pi-maintains-one-shared-npm-install-project-per-scope-with-flat-sibling-resolution).
+- **The compiled pi binary never takes the adapter branch today.** Under the
+  standalone (Bun-compiled) pi executable, dynamic `import()` cannot resolve
+  npm-installed siblings at all, so this recipe falls back — safely, with the
+  note — even when the package is installed. The optional pattern currently
+  activates only under Node-based pi installs (`npm install -g` /
+  `bun install -g`). A hard static dependency resolves under both
+  distributions. See
+  [research Claim 13](research.md#claim-13--bun-binary-probe-the-optional-dynamic-import-falls-back-under-the-compiled-binary-resolves-under-npm-dist-pi).
+- **Fallback mode is baseline pi, not "repairs minus notes."** Without the
+  adapter, pi's native validation runs `Value.Convert` first, which silently
+  coerces some invalid input into valid-looking values (`null` → `"null"`)
+  instead of repairing or rejecting it. Decide explicitly whether that is
+  acceptable for your tool, and test both branches.
+- **No double-wrap.** The installable pi-repair-layer extension only overrides
+  pi's built-in tools; it never discovers or wraps tools registered by other
+  extensions. A tool adapted by this recipe is wrapped exactly once in either
+  branch.
+
+### Stability contract for optional consumers
+
+Copies of this recipe keep working across versions because the surface it
+touches is deliberately small and covered by the compatibility contract in
+[Install the package](#install-the-package):
+
+- The subpath names (`/pi`, `/core`, `/grammar`) and the
+  `adaptToolDefinition(definition, options?)` signature are stable for the
+  current major; documented exports follow semantic versioning.
+- Absence detection semantics are part of the contract: a missing package
+  surfaces with `code` `MODULE_NOT_FOUND` or `ERR_MODULE_NOT_FOUND` and a
+  message naming the requested module.
+- Unrecognized preprocessor `kind`s are ignored — never fatal, no mutation, no
+  claimed change — and results are still schema-validated. Repair options
+  written against a newer minor version therefore degrade to the recognized
+  subset when an older version is installed, instead of throwing at
+  configuration time.
+
 ## Configure only known-safe transforms
 
 Preprocessors use JSON-Pointer-like selectors. `"/path"` selects a field,
@@ -321,6 +542,15 @@ At minimum, an owning extension should test:
    each and stale notes do not leak to later calls.
 7. Telemetry and persisted entries contain no argument values or note text.
 
+Optional consumers (the [Optional integration](#optional-integration) recipe)
+should additionally test both branches:
+
+8. With the package absent, activation still succeeds: the raw definition is
+   registered and the one-line fallback note is emitted.
+9. Strictly valid input behaves identically in both branches; for invalid
+   input, the fallback branch exposes pi's native coercion — confirm that is
+   acceptable for your tool.
+
 For a working compile-time example, see
 [`test/fixtures/public-consumer.ts`](../test/fixtures/public-consumer.ts). The
 package smoke test installs the packed tarball into a clean project and imports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r3b1s/pi-repair-layer",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Tool-input repair layer for the pi coding agent: validate-then-repair for built-in tool calls, ported from the behavior of commandcode's repair layer",
   "repository": {
     "type": "git",