@r3b1s/pi-repair-layer 0.2.1 → 0.4.0

package/README.md

@@ -1,42 +1,46 @@
 # pi-repair-layer
 
-A tool-input repair layer for the [pi coding agent](https://github.com/earendil-works/pi), doing
-what commandcode's repair layer does: catch the small, finite set of malformed
-tool calls that open models emit, fix them at the exact paths the validator
-flags, and tell the model what was fixed so it can self-correct next turn.
-
-No LLM calls, no network, no uploaded telemetry.
-
-## Glossary
-
-Plain-English first, precise meaning after — for readers new to LLM tool-calling.
-
-- **Tool call** — the model asking the agent to run a tool (read a file, run a
-  shell command). Concretely, a structured request with a tool name and a JSON
-  arguments object that the agent validates and executes.
-- **Schema / validation** — the rulebook for a tool's arguments, and the check
-  against it. Each built-in tool declares a schema (which fields exist, their
-  types, which are required); pi validates every call against it and rejects
-  calls that don't fit.
-- **Silent coercion** — when a wrong value gets quietly bent into a valid-looking
-  one and runs anyway. pi's validator runs TypeBox `Value.Convert` first, which
-  turns `null` into the string `"null"` and `'["a"]'` into `['["a"]']` — the call
-  then passes validation and executes with garbage instead of erroring.
-- **Grammar leak** — the model prints its tool call as text instead of actually
-  making one. Different model families use different tool-call "grammars" (XML
-  tags, sentinel tokens); when one leaks, a block like
-  `<tool_call>read<arg_key>path</arg_key>…` shows up in the assistant's prose and
-  no tool runs.
-- **Anchor bleed** — regex anchor characters (`^`, `$`) stuck onto a value that
-  isn't a regex. Some models emit `read {path: "^/x$"}` where the `^`/`$` bled in
-  from the tool-call grammar and were never meant to be part of the path.
-- **Phantom tool call** — the model signals "I'm calling a tool" but sends no
-  actual call. On some providers the stream ends with a tool-use stop reason but
-  zero tool-call blocks, leaving the loop with nothing to run. (Out of scope
-  here — see [Limitations](#limitations).)
-- **Repair note** — the short explanation this layer hands back to the model
-  after fixing a call, so it can self-correct. It rides along as a
-  `<repair_note>…</repair_note>` line prefixed to the tool result.
+pi-repair-layer repairs the small, predictable tool-call mistakes that can
+derail an otherwise productive [pi](https://github.com/earendil-works/pi) turn.
+Install it for pi's built-in tools, or follow the
+[tool-owner integration guide](docs/tool-owner-integration.md) to bring the
+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:
+
+| Model sends | Tool expects |
+|---|---|
+| `{file_path: "/x"}` | `{path: "/x"}` |
+| `{include: "src"}` | `{include: ["src"]}` |
+| `{offset: null}` | omit optional `offset` |
+| `'{"command":"ls"}'` | `{command: "ls"}` |
+| flat `old_string` / `new_string` fields | an `edits` array |
+
+Without a pre-validation repair seam, pi may reject the call or convert a bad
+value into valid-looking garbage. pi-repair-layer fixes only configured or
+schema-proven cases, validates the result, executes it, and returns a
+`<repair_note>` so the model learns the correct shape for its next call.
+
+It covers pi's `read`, `bash`, `edit`, `write`, `grep`, `find`, and `ls` tools.
+Already-valid input takes the fast path and is returned untouched.
 
 ## Install
 
@@ -44,285 +48,161 @@ Plain-English first, precise meaning after — for readers new to LLM tool-calli
 pi install npm:@r3b1s/pi-repair-layer
 ```
 
-Or from git:
+Or install directly from GitHub:
 
 ```bash
 pi install git:github.com/r3b1s/pi-repair-layer
 ```
 
-pi's TUI will show a one-time warning that built-in tools were overridden —
-that is this extension working as intended.
+pi will show a one-time warning that built-in tools were overridden. The
+extension reuses pi's real schemas, executors, renderers, and runtime modules;
+it adds the pre-validation repair step.
+
+## Terms in plain English
+
+- **Tool call** — the model asking the agent to run a tool with structured arguments.
+- **Schema / validation** — the rules for those arguments and the check that they fit.
+- **Silent coercion** — a bad value being converted into a valid-looking but unintended value.
+- **Grammar leak** — the model printing a tool call as text instead of making the call.
+- **Anchor bleed** — stray `^` or `$` grammar characters attached to a non-regex value.
+- **Phantom tool call** — a tool-use signal that contains no actual call to run.
+- **Repair note** — a short explanation returned to the model after a repair.
+- **Fast path** — returning valid input without changing or cloning it.
+- **Path selector** — an address such as `/path` or `/edits/*/oldText` for one configured location.
+- **Preprocessor** — an explicit cleanup that runs at a path selector before validation.
+- **Invariant** — a safety rule that must remain true for every input.
+- **Fail closed** — rejecting input when the pipeline cannot prove a safe, valid repair.
 
-At runtime pi's extension loader aliases `@earendil-works/pi-coding-agent` and
-`typebox` to the running instance's own modules, so the extension always binds
-to your live pi and its exact validator version. The `node_modules/` here is
-only used for the tests and `tsc`.
+## What it repairs
 
-```bash
-pnpm install   # once, if you want to run the tests
-pnpm test      # pure engine unit tests + end-to-end against pi's real tools
+The default adaptive policy handles:
+
+- exact field aliases such as `file_path` → `path`, `cmd` → `command`, and
+  `old_string` → `oldText`;
+- JSON-stringified objects and arrays, singleton object envelopes, and bare
+  strings where a configured object or array is expected;
+- invalid optional `null` values and empty object placeholders;
+- markdown auto-links in configured filesystem paths;
+- the legacy flat edit shape used by several coding agents; and
+- model-gated anchor bleed and leaked argument tokens at configured locations.
+
+Unknown keys are not fuzzily renamed or generically deleted. See
+[How repair works](docs/how-it-works.md) for the ordered pipeline, complete
+repair catalog, grammar handling, and the reasoning behind the hook placement.
+
+## Safe by design
+
+The pipeline recovers the outer argument envelope, chains the tool owner's
+compatibility hook, applies explicitly scoped preprocessing, validates strictly,
+repairs only reported schema issues, and validates again before returning a
+repaired result.
+
+- Valid input stays untouched unless an explicitly configured valid-value
+  transform applies.
+- Every mutation carries a stable rule ID and model-facing note.
+- Repair work is bounded, deterministic, and covered by property and seeded-fuzz tests.
+- Unrepairable input produces a model-readable retry error rather than `{}` or guessed values.
+- Telemetry stays local and excludes arguments, paths, commands, content, and note text.
+- Turning assistant text into an executable tool call always requires explicit `recover` mode.
+
+| Profile | Tool arguments | Grammar text | Promotion |
+|---|---|---|---|
+| `conservative` | exact, schema-guided repair | observe only | never |
+| `adaptive` (default) | adds validated/model-gated recovery | strip known tools | never |
+| `recover` | same as adaptive | strip known tools | safety-gated |
+
+Unknown or unavailable tool grammar is preserved by default in every profile.
+The [behavior and safety reference](docs/how-it-works.md) explains the gates and
+invariants in detail.
+
+## Use it in your own extension
+
+Tools registered by other extensions are not intercepted automatically: their
+owner must opt in at the `prepareArguments` boundary.
+
+```ts
+import { adaptToolDefinition } from "@r3b1s/pi-repair-layer/pi";
+
+pi.registerTool(
+  adaptToolDefinition(definition, {
+    policy: "adaptive",
+    preprocessors: [
+      { kind: "alias", selector: "/path", aliases: ["file_path"] },
+    ],
+  }),
+);
 ```
 
-The toolchain is managed with [mise](https://mise.jdx.dev/) (`mise.toml` pins
-node/pnpm). `mise run ci` runs typecheck + lint + test.
+The adapter chains an existing owner hook and fails closed by default. The
+[full integration guide](docs/tool-owner-integration.md) covers selectors,
+custom transforms, the side-effect-free `/core` API, call-ID correlation,
+`<repair_note>` attachment, privacy, and integration tests.
 
-## What it repairs
+Public subpaths are compiled ESM with declarations and source maps:
 
-| Rule | Example | Fix |
-|---|---|---|
-| `renameAliasedField` | `{file_path: "/x"}` for `read` | `{path: "/x"}` |
-| `dropNullOrUndefinedField` | `{path: "/x", offset: null}` | `{path: "/x"}` |
-| `dropEmptyObjectPlaceholder` | `{tags: {}}` where array expected | field dropped |
-| `parseJsonStringifiedArray` | `{include: '["a","b"]'}` | `{include: ["a","b"]}` |
-| `parseJsonStringifiedObject` | stringified object for object field | parsed |
-| `wrapBareStringAsArray` | `{include: "foo"}` | `{include: ["foo"]}` |
-| `wrapRootStringAsObject` | `"echo hi"` as the whole input to `bash` | `{command: "echo hi"}` |
-| `parseJsonStringifiedRootObject` | `'{"command":"ls"}'` as the whole input | parsed |
-| `unwrapMarkdownAutoLink` | `path: "/x/[notes.md](http://notes.md)"` | `path: "/x/notes.md"` |
-| `foldFlatEditFields` | `{path, old_string, new_string}` for `edit` | `{path, edits: [{oldText, newText}]}` |
-
-Alias tables cover the contracts models actually leak: Claude Code's
-`file_path`/`old_string`/`new_string`, aider's `search`/`replace`, generic
-`cmd`/`query`/`text`/`contents`, at any nesting depth (e.g. inside `edits[n]`).
-
-Every repair is surfaced to the model as a `<repair_note>` prefixed to the tool
-result, e.g.:
+- `@r3b1s/pi-repair-layer/pi` — tool-owner adapter;
+- `@r3b1s/pi-repair-layer/core` — pure pipeline, policy, lifecycle, and formatting APIs; and
+- `@r3b1s/pi-repair-layer/grammar` — pure grammar parsing and recovery helpers.
 
-```
-<repair_note>Renamed `file_path` to `path` for tool "read". `file_path` is not a valid field for this tool — use `path` next time.</repair_note>
-```
+Node 22+ is supported; pi 0.80.6 is the verified baseline. Documented exports
+follow semantic versioning, and the existing `repairToolInput` API remains
+supported for the current major.
 
-Transparency over silent magic: the model sees what was picked and can correct
-itself on the next turn.
-
-## Model-gated value strips
-
-Before the validate-then-repair engine runs, a small pre-pass
-(`src/value-strips.ts`) cleans two model-specific artifacts that are *valid
-strings* and so slip past validation entirely:
-
-- **Anchor bleed** — leading `^` / trailing `$` bled into a value
-  (`read {path: "^/x$"}` → `{path: "/x"}`).
-- **Grammar-token leaks** — GLM `<arg_key>`/`<arg_value>` markers stuck onto
-  object keys or values (`{"<arg_key>pattern</arg_key>": "<arg_value>foo</arg_value>"}`
-  → `{pattern: "foo"}`).
-
-Both are gated on the current model id — anchor bleed on `kimi-k2` / `minimax` /
-`glm`, grammar tokens on `glm` — since these are model-specific quirks. Each
-strip emits a `<repair_note>` and telemetry exactly like an engine repair, and
-the strips are adapted from [pi-tool-repair](#prior-art). One improvement over
-upstream: the anchor strip **skips `grep.pattern`**, the one built-in field
-that is a real regex, where a `^`/`$` may be intended syntax and is
-indistinguishable from a bled anchor — so it is never guessed at.
-(`find.pattern` is a glob, not a regex, so it is *not* exempt.) Whether anchor
-bleed happens on pi at all is an open empirical question; shipping the strips
-instrumented answers it for free.
-
-## Grammar-leak recovery (opt-in)
-
-When a model prints a tool call as text (a [grammar leak](#glossary)) instead of
-emitting a real one, `src/grammar-recovery.ts` (adapted from
-[pi-tool-repair](#prior-art), 10 grammar families, code-fence-aware) handles it
-on pi's `message_end` hook. Modes, set via `/repair-settings`:
-
-- **`off`** — never touch assistant text.
-- **`strip`** (default) — remove the leaked grammar from the text on gated
-  models, but never promote it to an executable call.
-- **`recover`** — additionally promote the parsed call to a real tool call that
-  executes the same turn and re-enters this layer's `prepareArguments` repair
-  path. A recovery note is stashed so the executed call surfaces
-  `<repair_note>recovered a leaked … tool call…</repair_note>`.
-
-Because promotion turns model *text* into *execution*, it is guarded: opt-in
-`recover` mode, a known-tool allowlist, an empty-arguments skip, role
-preservation, and a **stopReason gate** — a call is promoted only when the
-original message's `stopReason` is `"stop"`. Upstream promotes regardless and
-overwrites `stopReason: "length"`, which would defeat pi's protection that fails
-all tool calls on truncated output ([research.md Claim 7][r-claim7]). Stripping
-leaked text is allowed on any stopReason; only promotion is gated.
-
-## Design: validate-then-repair, hooked pre-validation
-
-pi's agent loop runs, per tool call ([research.md Claim 1][r-claim1]):
+## Settings and local telemetry
 
-```
-tool.prepareArguments(raw) → validateToolArguments() → tool_call event → execute
-```
+All telemetry stays on your machine and is used only for debugging and tracing tool-call repairs; nothing is sent or uploaded.
 
-Every mechanical claim in this section is verified against pi's source, with
-file:line citations and a verification date, in
-[`docs/research.md`](docs/research.md); the linked claim numbers point at the
-specific entries. Automated tripwires in `test/upstream-drift.test.ts` execute
-these claims against the installed pi so a pi upgrade can't invalidate them
-silently.
-
-Two consequences drove the architecture:
-
-1. **The `tool_call` extension event fires *after* validation**
-   ([research.md Claims 1–2][r-claim1]). A validation
-   failure short-circuits to an error result before any event handler runs, so
-   an extension listening on `tool_call` can never see — let alone repair —
-   malformed input. (This is why repair extensions built on that hook can't
-   work for built-in tools.) The only pre-validation seam is
-   `prepareArguments`, which extensions reach by overriding a built-in tool via
-   `pi.registerTool({ same name })`. Each override here spreads the original
-   definition (`createReadToolDefinition(cwd)` etc. are exported from pi's
-   root), so renderers, prompt metadata, and execution are the real built-ins;
-   only `prepareArguments` is chained and `execute` thinly wrapped for notes.
-
-2. **pi's own coercion (`Value.Convert`) silently corrupts the classic failure
-   modes.** Measured on typebox 1.1.38, which pi validates with:
-
-   | Model sends | Convert produces | Then |
-   |---|---|---|
-   | `'["a","b"]'` for an array | `['["a","b"]']` | passes validation, executes with garbage |
-   | `null` for an optional string | `"null"` | passes, e.g. greps for the string `null` |
-   | `null` for a required `path` | `"null"` | passes, reads a file named `null` |
-   | `null` for an optional number | `0` | passes, offset silently zero |
-
-   So this engine checks **strictly first** (no Convert) and repairs at the
-   strict-error sites before Convert can mangle them. Benign coercions
-   (`"5"` → `5`) still fall through to pi's native behavior untouched. The
-   repair layer therefore doesn't just recover calls that would have errored —
-   it fixes calls pi currently executes *wrongly*.
-
-The engine itself follows the validate-then-repair shape commandcode's author
-described publicly: parse as-is; if it succeeds, ship it untouched (fast path
-returns the original object by reference); on failure, walk the validator's own
-issue list and spend repair budget only at the paths the schema disagreed with;
-re-validate; never ship a repair that doesn't verify. Rule order is fixed —
-JSON-array parsing before bare-string wrapping, renames before null-drops.
-
-The one deliberate preprocess (not validate-then-repair) is markdown auto-link
-unwrapping on path fields, because `"/x/[notes.md](http://notes.md)"` is a
-perfectly valid string that validation can never flag. It unwraps only the
-degenerate case where the link text equals the URL minus its protocol; real
-markdown links pass through, and content fields are never touched.
-
-## Telemetry (local only)
-
-Repair outcomes append to `~/.pi/agent/tool-repair/telemetry.jsonl`: timestamp,
-tool, model id, outcome, rules fired, an issue summary, and an FNV-1a
-fingerprint of the (tool, failure-shape) pair — the same shape-fingerprint
-trick commandcode uses to count distinct failure signatures. Inputs themselves
-are never logged.
-
-Records come on two channels. The **tool channel** (the default; records with no
-`channel` field, so old logs read unchanged) keys on a tool, with `outcome` one
-of `repaired`, `unrepairable`, or `recovered` (a promoted grammar-leak call).
-The **message channel** (`channel: "message"`) records grammar strip-only events
-— a leak removed with nothing promoted, so there is no tool to key on — with the
-grammar family that was stripped. `/repair-stats` summarizes both:
+- `/repair-settings` changes the policy, grammar mode, unknown-tool text policy,
+  TUI indicator, and visible repair notes.
+- `/repair-stats` summarizes local repair outcomes by model, tool, and rule.
+- `PI_TOOL_REPAIR_LOG=1` prints decisions to stderr.
+- `PI_TOOL_REPAIR_TELEMETRY=off` disables local telemetry.
+- `PI_TOOL_REPAIR_PASSTHROUGH=1` restores pi's native behavior for unrepairable input.
 
-```
-/repair-stats
-```
+Settings persist under `~/.pi/agent/tool-repair/`. See the
+[operations guide](docs/operations.md) for paths, record contents, privacy,
+diagnostics, and verification commands.
 
-It reports repairs/recoveries by tool and by model, grammar strip-only events by
-family, and a rules-fired tally. Watch per-model rates to catch a model
-regressing on a specific contract.
+## Documentation
 
-Env switches: `PI_TOOL_REPAIR_LOG=1` logs decisions to stderr;
-`PI_TOOL_REPAIR_TELEMETRY=off` disables telemetry (or set it to a path).
+- [Integrating extension-owned tools](docs/tool-owner-integration.md)
+- [How repair works: behavior, safety, and limitations](docs/how-it-works.md)
+- [Operations, settings, telemetry, and verification](docs/operations.md)
+- [Source-backed pi integration research](docs/research.md)
 
-## Chaos test (deterministic live exercise)
+## Prior art
 
-`test/run-chaos.sh` + `test/chaos-provider.ts` register a scripted fake
-provider that replays canned malformed tool calls through pi's real agent loop
-(print mode via the `pi` binary, no network, no tokens), then reports the
-`<repair_note>` lines the "model" saw and asserts on them. It exercises the full
-path end-to-end — streaming, preflight, validation, repair, execution, and note
-surfacing — and passes against pi 0.80.6:
+The value-strip rules and grammar-recovery approach originate in Tom X Nguyen's
+MIT-licensed [`monotykamary/pi-tool-repair`](https://github.com/monotykamary/pi-tool-repair).
+This project adapted its anchor/token cleanup and grammar parsers, then scoped
+the transforms, added reporting, and gated executable promotion.
 
-```bash
-test/run-chaos.sh
-```
+The key integration difference is mechanical: pi runs
+`prepareArguments → validation → tool_call → execute`. A malformed call fails
+before `tool_call`, so this extension hooks the owning tool's
+`prepareArguments`; the sequence and propagation behavior are verified in
+[research Claims 1–4](docs/research.md#claim-1--loop-ordering-preparearguments-runs-before-validation-which-runs-before-the-tool_call-event).
+See [How repair works](docs/how-it-works.md#prior-art-and-hook-placement) for the
+full adaptation notes and comparison.
 
-(An earlier pi release resolved the stream function before an extension's
-custom provider finished registering, so this hung; 0.80.6 streams through the
-registered provider correctly.) The `test/upstream-drift.test.ts` suite drives
-the same real loop fully in-process (via pi-ai's faux provider), so the loop
-behaviors this layer depends on are covered by `pnpm test` too, without the
-`pi` binary.
-
-## Display settings
-
-Repaired tool calls get a `🔨 ✓ input repaired (rules...)` line appended to
-their result row in the TUI; optionally the repair note text renders beneath
-it. `/repair-settings` toggles the indicator and the note text independently,
-and cycles the grammar-leak recovery mode (`off → strip → recover`; default
-`strip`). All three persist to `~/.pi/agent/tool-repair/settings.json` (or
-`PI_TOOL_REPAIR_SETTINGS=<path>`), alongside an optional `grammarAllowedTools`
-list that restricts which tool names a leaked call may be promoted to (when
-empty, the active tool set is used). Indicators are persisted per session via
-custom entries, so they survive `/reload` and session resume.
-
-## Unrepairable input
-
-When repairs can't make the input valid, the layer raises a model-readable
-retry error (`Invalid input for tool "write". Fix these issues and retry: ...`)
-instead of passing the input through — passing through would let pi's
-`Value.Convert` coerce it into garbage (`content: null` becomes the literal
-string `"null"` on disk) and execute anyway. Set `PI_TOOL_REPAIR_PASSTHROUGH=1`
-to restore pi's native behavior.
+## Limitations
 
-## Prior art
+- Another extension's tools require owner opt-in through `/pi` or `/core`.
+- Two extensions overriding the same built-in do not compose; load order wins.
+- Similar but unconfigured aliases are not guessed.
+- Phantom tool calls are not synthesized into calls.
+- Grammar promotion is limited to recognized, non-empty calls for active or
+  explicitly allowed tools and never runs on truncated output.
 
-The value strips and the grammar-leak recovery approach come from
-[`monotykamary/pi-tool-repair`](https://github.com/monotykamary/pi-tool-repair)
-(MIT), Tom X Nguyen's pi extension. What this project adapted from it:
-
-- The anchor-bleed and grammar-token-leak strips (`src/value-strips.ts`),
-  reworked to run inside `prepareArguments`, to skip the `grep.pattern` regex
-  field, and to report through this layer's repair-note / telemetry machinery.
-- The grammar-leak recovery parsers, candidate selection, code-fence handling,
-  and range removal (`src/grammar-recovery.ts`, ~10 grammar families), adapted
-  in place with a one-line provenance header, plus the new `stopReason`
-  promotion gate.
-
-The two projects also share a common Command Code lineage in their
-validate-then-repair engines (near-identical rule names and alias tables).
-
-Where they differ is **which hook reaches a malformed built-in call**, and that
-is mechanical, not a matter of quality. pi runs
-`prepareArguments → validateToolArguments → tool_call event → execute`
-([research.md Claim 1][r-claim1]). A malformed built-in call makes
-`validateToolArguments` **throw** before the `tool_call` event ever fires
-([Claim 2][r-claim1]), so a repair that keys on `tool_call` cannot see it; and
-even for a call that does pass, the `tool_call` event only propagates a handler's
-*in-place* mutation of `event.input`, never a reassignment ([Claim 3][r-claim3]).
-pi-tool-repair's built-in repair keys on `tool_call`; this project overrides the
-built-in tool so its repair runs in `prepareArguments`, the one seam ahead of
-validation. That is why the two hooks reach different cases — see the cited
-research entries for the source. Conversely, the capabilities assimilated here
-(value strips, grammar recovery) live on hooks that *do* propagate their results
-(`prepareArguments`, `message_end` — [Claim 4][r-claim4]), which is why adapting
-them is sound.
-
-[r-claim1]: docs/research.md#claim-1--loop-ordering-preparearguments-runs-before-validation-which-runs-before-the-tool_call-event
-[r-claim3]: docs/research.md#claim-3--tool_call-event-in-place-input-mutation-propagates-reassignment-does-not
-[r-claim4]: docs/research.md#claim-4--message_end-replacement-mutates-the-loops-message-in-place-listeners-are-awaited-and-the-replacement-executes-same-turn-with-a-role-guard
-[r-claim7]: docs/research.md#claim-7--stopreason-length-causes-pi-to-fail-all-tool-calls-in-the-message
+## Development
 
-## Limitations
+```bash
+pnpm install
+mise run ci              # typecheck + lint + tests
+pnpm run test:package    # packed clean-consumer smoke test
+pnpm run test:fuzz       # deterministic bounded fuzz campaign
+test/run-chaos.sh        # scripted real pi-loop exercise
+```
 
-- Only pi's seven built-in tools are wrapped. Custom tools from other
-  extensions aren't (pi has no API to wrap another extension's execute), but
-  they can import `repairToolInput` from `src/repair-engine.ts` and use it in
-  their own `prepareArguments`.
-- Wrong-but-optional fields are invisible to validation by design: pi's schemas
-  allow extra keys, so `grep {pattern, directory: "src"}` validates and
-  silently searches the cwd. No validate-then-repair layer can catch this
-  (commandcode's included); it would take strict schemas or key-similarity
-  heuristics, both with false-positive costs.
-- Unrepairable input falls through to pi's stock validation error, which is
-  already model-readable (per-path issues plus the received arguments).
-- If another extension also overrides a built-in tool, load order decides which
-  override wins — they don't compose.
-- Phantom tool calls (a tool-use stop reason with zero tool-call blocks) are not
-  handled. On pi 0.80.6 that state is a clean terminal stop, not a recoverable
-  retry ([research.md Claim 6][r-claim6]), so normalizing it would be cosmetic;
-  it will be revisited only if a concrete stuck state is reproduced on a
-  provider.
-
-[r-claim6]: docs/research.md#claim-6--stopreason-error-and-aborted-is-terminal-not-a-retry
+Larger fuzz runs and replay instructions are in the
+[operations guide](docs/operations.md#verification).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from "./src/index.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC"}

package/{index.ts → dist/index.js}

@@ -1,2 +1,3 @@
 // Entry point for pi's extension auto-discovery (~/.pi/agent/extensions/*/index.ts).
-export { default } from "./src/index.ts";
+export { default } from "./src/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/src/core.d.ts

@@ -0,0 +1,8 @@
+export { DEFAULT_ENVELOPE_LIMITS, type EnvelopeLimits, type EnvelopeRecoveryResult, escapeJsonStringControlCharacters, isPlainObject, recoverEnvelope, truncatedEnvelopeChange, } from "./envelope.ts";
+export { attachRepairNotes, formatRepairNotes, type RepairFeedback, RepairLifecycle, type RepairLifecycleOptions, stableSerialize, } from "./lifecycle.ts";
+export { runRepairPipeline } from "./pipeline.ts";
+export { type GrammarPolicyMode, type RepairPolicy, type RepairPolicyOverrides, type RepairPolicyProfile, resolveRepairPolicy, type UnknownGrammarTextPolicy, } from "./policy.ts";
+export { type AliasPreprocessor, type FieldPreprocessor, type ObjectLocationSelector, type Preprocessor, preprocessInput, type StructuralPreprocessor, } from "./preprocess.ts";
+export { type RepairResult, repairToolInput, type StructuralRepair, type ToolRepairConfig, unwrapMarkdownAutoLinks, } from "./repair-engine.ts";
+export type { RepairChange, RepairObservation, RepairPipelineConfig, RepairPipelineLimits, RepairPipelineResult, RepairStage, } from "./types.ts";
+//# sourceMappingURL=core.d.ts.map

package/dist/src/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,iCAAiC,EACjC,aAAa,EACb,eAAe,EACf,uBAAuB,GACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,cAAc,EACnB,eAAe,EACf,KAAK,sBAAsB,EAC3B,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,mBAAmB,EACnB,KAAK,wBAAwB,GAC9B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EACjB,eAAe,EACf,KAAK,sBAAsB,GAC5B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,YAAY,EACjB,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/src/core.js

@@ -0,0 +1,7 @@
+export { DEFAULT_ENVELOPE_LIMITS, escapeJsonStringControlCharacters, isPlainObject, recoverEnvelope, truncatedEnvelopeChange, } from "./envelope.js";
+export { attachRepairNotes, formatRepairNotes, RepairLifecycle, stableSerialize, } from "./lifecycle.js";
+export { runRepairPipeline } from "./pipeline.js";
+export { resolveRepairPolicy, } from "./policy.js";
+export { preprocessInput, } from "./preprocess.js";
+export { repairToolInput, unwrapMarkdownAutoLinks, } from "./repair-engine.js";
+//# sourceMappingURL=core.js.map

package/dist/src/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EAGvB,iCAAiC,EACjC,aAAa,EACb,eAAe,EACf,uBAAuB,GACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EAEjB,eAAe,EAEf,eAAe,GAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAKL,mBAAmB,GAEpB,MAAM,aAAa,CAAC;AACrB,OAAO,EAKL,eAAe,GAEhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,eAAe,EAGf,uBAAuB,GACxB,MAAM,oBAAoB,CAAC"}

package/dist/src/envelope.d.ts

@@ -0,0 +1,21 @@
+import type { RepairChange, RepairPipelineLimits } from "./types.ts";
+export interface EnvelopeLimits {
+    maxInputBytes: number;
+    maxNestingDepth: number;
+    maxDecodeAttempts: number;
+    maxCandidates: number;
+    maxWorkMs: number;
+}
+export declare const DEFAULT_ENVELOPE_LIMITS: EnvelopeLimits;
+export interface EnvelopeRecoveryResult {
+    value: unknown;
+    changes: RepairChange[];
+    candidates: unknown[];
+    limited: boolean;
+}
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** Escape only literal JSON control characters that occur inside a string. */
+export declare function escapeJsonStringControlCharacters(text: string): string;
+export declare function recoverEnvelope(input: unknown, overrides?: RepairPipelineLimits): EnvelopeRecoveryResult;
+export declare function truncatedEnvelopeChange(): RepairChange;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/src/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAErE,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,uBAAuB,EAAE,cAMrC,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMlC;AAiCD,8EAA8E;AAC9E,wBAAgB,iCAAiC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmCtE;AAgBD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,SAAS,GAAE,oBAAyB,GACnC,sBAAsB,CA4ExB;AAED,wBAAgB,uBAAuB,IAAI,YAAY,CAKtD"}