@caupulican/pi-adaptative 0.81.9 → 0.81.12

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [Unreleased]
+
+## [0.81.12] - 2026-07-07
+
+0.81.10/0.81.11 retracted before distribution; changes are folded into this section for 0.81.12.
+
+### Fixed
+- Fixed external editor resolution so both inline and path-edit flows prefer `$VISUAL` before `$EDITOR`.
+- Fixed registered extension models without token limits to receive default context and max-output limits.
+- Fixed grep/find result-limit notices so exact-limit result sets are not reported as truncated.
+- Fixed edit tool argument preparation to leave stringified `edits` for the shared validation repair layer.
+- Added session analytics aggregation for shape-only tool argument validation telemetry.
+- Added a host-keyed per-model adaptation store for repair rules, protocol calibration, and teach statistics.
+- Added learned per-model tool-shape rules to system prompt assembly after repeated repair telemetry.
+- Added per-model teach-efficacy aggregation for tool argument validation telemetry.
+- Added per-model text tool-call protocol calibration before the first real turn.
+- Added sanitized tool-validation bounce records to the local failure corpus for repair-mode discovery.
+- Added tool repair health reporting, learned-rule removal, visible repaired-call markers, and repair/teach/protocol kill switches.
+- Fixed delegated worker action parsing to use the shared tool-argument validation repair path.
+- Documented tool repair diagnostics, controls, and replay workflow.
+
 ## [0.81.9] - 2026-07-07
 
 ## [0.81.8] - 2026-07-07

package/dist/bundled-resources/skills/tool-call-repair/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: tool-call-repair
+description: Use when improving Pi's tool calling, when a model "can't do tool calls" or fails argument validation repeatedly, when adding an argument repair or coercion, or when touching validateToolArguments, prepareArguments, or provider tool-call assembly. Doctrine for making tool calling succeed with any model, especially open models with weak native tool support - validate-then-repair at one choke point, a finite failure-mode catalogue, shape-vs-relational rules, efficiency and telemetry requirements.
+---
+
+# Tool-call repair
+
+A model that "can't do tool calls" is almost always emitting one of a SMALL,
+FINITE set of shape mistakes (about 90% of cases across deepseek-flash,
+deepseek v4 pro, glm, qwen; observed 2026-07). The harness's job is a
+four-stage loop: **CAPTURE** every malformed or failing call, **FIX** what is
+mechanically repairable, **RECOVER** the turn when repair is impossible
+(bounce with a schema echo, never a dead end), and **TEACH** the model so the
+mistake stops recurring. Every mechanical repair saves one full turn of
+latency and tokens; every successful teach makes the repair unnecessary. That
+compounding saving is the feature.
+
+## Decisions (non-negotiable)
+
+1. **One choke point, and it is CODE.** All argument repair lives behind
+   `validateToolArguments` (`packages/ai/src/utils/validation.ts`), which
+   every tool call already passes through (`packages/agent/src/agent-loop.ts`
+   prepareToolCall). The layer itself is a dedicated module of pure
+   deterministic functions - `utils/tool-repair/`: `registry.ts` (named
+   entries), `analyzer.ts` (validator errors -> classified modes),
+   `repairer.ts` (clone -> transform -> guard -> re-check),
+   `text-protocol.ts` (primer generator + envelope parser over one shared
+   grammar). No I/O, no clock, no randomness, no model calls anywhere in the
+   repair path; same input, same output; unit tests need no mocks. This
+   skill is doctrine for whoever maintains that module - prose never
+   substitutes for the parser/analyzer/repairer code. Never add per-tool
+   special cases; `prepareEditArguments` in `edit.ts` is legacy exactly-this
+   and gets deleted when the general repair covers it.
+2. **Validate, then repair.** Run `Check` first. Well-formed args are NEVER
+   mutated (hot path pays one cached compiled-validator check, returns the
+   SAME object, nothing else). On failure, walk the validator's error list
+   and apply repairs keyed to the error type at the failing path, then
+   re-Check once. Still failing: bounce to the model as an error tool result
+   that echoes the expected schema fragment. Never preprocess-then-validate;
+   blind coercion mutates correct input and hides bugs.
+2a. **Performance is a hard requirement, not a hope.** Completeness lives
+   ENTIRELY on the slow (already-failed) path; the fast path is one cached
+   `Check`. Repairs are O(validation-errors), not O(schema): a static
+   `(expect, got)` dispatch Map, precompiled matchers, no RegExp/schema
+   compilation/JSON parse per call except the one a mode explicitly needs.
+   Bounded work: ≤1 clone, ≤1 transform per failing path, ≤1 sub-Check per
+   transform, exactly 1 whole-args re-Check, no transform loops. A microbench
+   fixture GATES this (clean-path cost within noise of a bare Check). Adding
+   the 20th failure mode must cost the hot path nothing.
+3. **Shape repairs only.** A repair may reshape what the model clearly meant
+   (parse a stringified array, wrap a bare item, drop a null optional). It may
+   never invent a value. Required-but-null, cross-field constraints, and
+   semantic errors are relational: bounce those to the model. The current
+   `coercePrimitiveByType` null-to-zero-value behavior violates this rule and
+   is scheduled to be replaced by the catalogue's null rule.
+4. **Uniform across schema kinds.** TypeBox tools (built-ins) and plain
+   JSON-schema tools (MCP, extensions) get the same repair set. Today
+   built-ins get FEWER repairs (the `hasTypeBoxMetadata` guard skips the
+   coercion pass); that asymmetry is a defect, not a design.
+5. **Every repair is check-guarded and ordered.** Apply on a cloned candidate,
+   keep only if the sub-check passes. Within string-where-array-expected, try
+   JSON.parse FIRST and wrap second, or `'["a","b"]'` becomes `['["a","b"]']`.
+6. **Telemetry or it does not improve.** Count `{model, failureMode,
+   repaired|bounced|taught}` per firing, and link each repair to its
+   execution outcome and to recurrence-after-teach. That table tells us which
+   models need which repairs, proves the round-trips saved, and marks dead
+   repairs and dead teach notes for removal. A repair that never fires in 30
+   days is a deletion candidate.
+7. **Teach, do not nag.** A silent repair leaves the model repeating the
+   mistake forever. When a repair fires, the tool result carries a ONE-LINE
+   corrective note ("your `edits` arrived as a JSON string; it was repaired
+   to an array - emit a raw JSON array") the FIRST time that (tool, mode)
+   fires in a session, throttled after. A mode that keeps firing for a model
+   graduates to a standing per-model rule injected into the system prompt,
+   capped and retired when telemetry shows it stopped firing. Teaching that
+   does not reduce recurrence gets reworded or dropped, measured, not
+   assumed.
+8. **Only detectable failures can be taught.** A well-formed call that does
+   the wrong thing is invisible to this layer except for enumerated
+   detectable subclasses (see the teachable-error catalogue in references).
+   Do not pretend otherwise; general semantic wrongness belongs to review,
+   not to the repair loop.
+
+## Two grammars (the complete contract)
+
+The layer is defined by two formal grammars, both in references, both encoded
+as code (not prose):
+- **Envelope grammar** (`references/text-protocol-grammar.md`) — how a text-
+  mode call is shaped: EBNF for `<pi:call name="X">{json}</pi:call>`, the
+  recognized inbound variants, the schema→primer projection, and the
+  DICTIONARY generated from pi's real tools (bash, read, edit, write, ls,
+  grep, find).
+- **Failure grammar** (`references/failure-grammar.md`) — how a malformed
+  call is recognized and repaired: the `errorSignature → transform → guard →
+  note` table (modes 1–10, tool-agnostic) plus the tool-specific rows for
+  bash (`command` as argv-array or object-wrapper, `timeout` as string/{}),
+  edit, read/ls/grep/find. This is what `analyzer.ts` classifies against.
+
+## The catalogue (summary; full table in references/failure-grammar.md)
+
+| # | Name | Model emits | Repair (guard-gated) |
+|---|---|---|---|
+| 1 | nullOptionalDrop | `null` for an optional field | delete key (required+null → bounce) |
+| 2 | jsonStringParse | `"[...]"`/`"{...}"` string where container expected | JSON.parse; keep if it matches + checks |
+| 3 | singleObjectWrap | single object where array-of-objects expected | wrap `[obj]` if it passes `items` |
+| 4 | bareScalarWrap | bare scalar where array expected | wrap `[v]` if it passes `items` |
+| 5 | emptyObjectPlaceholder | `{}` placeholder where scalar expected | delete if optional (default applies); else bounce |
+| 6 | numberFromString | `"42"` where number expected | `Number(s)` if finite |
+| 7 | boolFromString | `"true"`/`"false"` where bool expected | exact map (never truthiness) |
+| 8 | enumCaseNormalize | case/space enum variant | match to the one member, else bounce |
+| 9 | singleElementUnwrap | `[v]` where scalar expected | unwrap if 1 elem and checks |
+| 10 | stringifiedNumberInArray | `["1","2"]` where number[] expected | map Number if all finite |
+
+Plus bash-specific: `bashCommandArgvJoin` (argv list → joined string) and
+`bashCommandUnwrap` (`{cmd}` → string). Every entry is a NAMED registry entry
+`{name, errorSignature, transform, guard, noteTemplate}` — one table powers
+the repair, the teach note, the telemetry tag, and the docs row: the
+deterministic set of what pi can and will repair. Repairs NEVER invent values
+and are ALWAYS guard-gated (kept only if the transform Checks), so a repair
+can only ever turn an invalid call valid, never alter a valid one. Modes 6–10
+and the bash rows are the increment past the original four; they cost the hot
+path nothing because they run only on already-failed calls (see decision 2a).
+
+## Method for an improvement pass
+
+Measure first (telemetry, or fixture-replay of failing transcripts). Pick the
+top firing failure mode. Write a failing fixture per affected provider. Land
+the error-keyed repair at the choke point. Prove the hot path is unchanged
+(well-formed fixture bytes untouched). Record ledger + CHANGELOG entries per
+repo convention. Adjacent gaps (missing tool-call id synthesis, text tool-call
+extraction and the plain-text protocol primer + calibration handshake for
+untrained models, truncated-stream guard, name sanitization parity,
+history-replay policy) are catalogued with code anchors in the references
+file; take them as separate items, not riders.
+
+## Output contract
+
+Code and fixtures land in `packages/ai` (validation + provider tests).
+Per-model observations and new failure modes append to the model-notes table
+in `references/repair-catalogue.md`. Durable findings go to the AGENTS.md
+ledger. Never chat-only.
+
+## Guards
+
+- Never loosen a schema or delete a test to make a call pass.
+- Repairs are pure, deterministic, bounded (~100 lines each, one re-Check).
+- A repair without a fixture per provider it claims to fix does not merge.
+- Do not repair relational failures; the model must decide values.

package/dist/bundled-resources/skills/tool-call-repair/references/failure-grammar.md

@@ -0,0 +1,128 @@
+# Failure grammar — the deterministic error→repair map
+
+Two grammars make the layer complete: the ENVELOPE grammar
+(`text-protocol-grammar.md`) says how a call is shaped; this FAILURE grammar
+says how a malformed call is recognized and repaired. It is the formal
+contract `analyzer.ts` classifies against and `registry.ts` encodes. Every
+entry is `errorSignature → transform → guard → note`, keyed to a validator
+error at an instance path. Adding a mode = adding a row here + a registry
+entry + fixtures. Nothing is repaired that is not in this table.
+
+Notation: `P` = failing instance path; `expect(P)` = the JSON-schema type(s)
+declared at P; `got` = the received value's runtime type; `req(P)` = whether P
+is in its parent's `required`; `def(P)` = P has a schema `default`.
+
+## Core failure grammar (tool-agnostic — applies to every schema)
+
+| # | name | errorSignature | got | transform | guard (keep iff) | note |
+|---|---|---|---|---|---|---|
+| 1 | nullOptionalDrop | type mismatch at P | `null`, `!req(P)` | delete key P | always (absence is valid for optional) | "sent null for optional `P` → omit the field instead" |
+| 1b | nullRequiredBounce | type mismatch at P | `null`, `req(P)`, `!def(P)` | none | never (bounce) | "`P` is required and cannot be null → send a real value" |
+| 2 | jsonStringParse | expect array\|object at P, got string | `"[...]"`/`"{...}"` | `JSON.parse(s)` | parsed matches expect(P) AND sub-checks | "sent `P` as a quoted JSON string → send a raw JSON array/object" |
+| 3 | singleObjectWrap | expect array at P, got object | `{...}` | `[obj]` | `[obj]` passes `items(P)` | "sent one object where `P` takes a list → wrap it in `[ ]`" |
+| 4 | bareScalarWrap | expect array at P, got scalar | string/number/bool | `[v]` | `[v]` passes `items(P)` | "sent a single value where `P` takes a list → wrap it in `[ ]`" |
+| 5 | emptyObjectPlaceholder | expect scalar at P (or array whose `items` reject `{}`), got object | `{}` | delete key P | `!req(P)` (schema default applies) else bounce | "sent `{}` as a placeholder → omit `P`; its default applies" |
+| 6 | numberFromString | expect number/integer at P, got string | `"42"`, numeric | `Number(s)` | finite (and integer if integer(P)) | "sent `P` as a quoted number → send a bare number" |
+| 7 | boolFromString | expect boolean at P, got string | `"true"`/`"false"` | `s === "true"` | exact match only (never truthiness) | "sent `P` as a quoted boolean → send bare true/false" |
+| 8 | enumCaseNormalize | expect enum at P, got string not in set | case/space variant | match case-insensitively/trimmed to one enum member | exactly one member matches | "`P` must be one of `a|b|c` → matched `<value>`" |
+| 9 | singleElementUnwrap | expect scalar at P, got 1-elem array | `[v]` | `v` | `v` passes expect(P) AND `length===1` | "sent `P` as a 1-item list where a single value was expected → send the value" |
+| 10 | stringifiedNumberInArray | expect number[] at P, got string[] | `["1","2"]` | map `Number` | all finite | "list `P` holds quoted numbers → send bare numbers" |
+
+Rules that keep this deterministic and safe:
+- **Repairs never invent a value.** 5 relies on the schema `default`; nothing
+  fabricates content. If a guard fails, the mode does not apply → bounce.
+- **Guard is mandatory.** Every transform runs on a clone and is kept ONLY if
+  it Checks against the sub-schema at P. A transform whose guard fails leaves
+  args untouched and falls through to the next applicable mode, then bounce.
+- **Order within one path:** 2 (parse) → 8/6/7 (coerce scalar) → 3/4/10 (wrap)
+  → 9 (unwrap) → 5 (placeholder-drop) → 1 (null-drop). Parse before wrap so a
+  stringified array becomes an array, not a wrapped string. Across paths:
+  instance-path order.
+- **One re-Check.** After all per-path transforms, Check the whole args once.
+  Pass → return repaired; fail → bounce. Never loop transforms.
+- Modes 6–10 are the increment past the original four; each is guard-gated so
+  it can only ever turn an invalid call into a valid one, never change a
+  valid call (the hot path never reaches them — see Performance).
+
+## Tool-specific failure grammar (bash and the shape-sensitive tools)
+
+The core grammar is schema-driven and covers every tool automatically. A few
+tools have a KNOWN, recurring, tool-shaped failure that the core grammar sees
+only as a generic type error; naming them lets the note teach precisely.
+These are still guard-gated core repairs — NOT special-cased logic — the
+tool-specificity lives only in the note text and the telemetry tag.
+
+### bash(command:string, timeout:number?)
+`command` is the arg models most often mis-shape, and bash is the highest-
+traffic tool, so its failures matter most.
+
+| observed | core mode | note (bash-specific) |
+|---|---|---|
+| `command` sent as `["ls","-la"]` (argv array) | bareScalarWrap inverse → join | "bash takes ONE command string, not an argv list → joined to `ls -la`" (guard: every element string; join with spaces) |
+| `command: {"cmd":"ls"}` (object wrapper) | emptyObjectPlaceholder sibling: unwrap known single key | "bash `command` is a string → unwrapped `{cmd}`" (guard: single string-valued key in {cmd,command,script}) |
+| `timeout: "30"` | numberFromString | "timeout is a number of seconds → sent 30" |
+| `timeout: {}` | emptyObjectPlaceholder | "sent `{}` for timeout → omitted; silence watchdog applies" |
+| `timeout: 0` / negative | NOT a failure — schema-valid, tool treats as unset | (no repair; documented tool behavior) |
+
+The argv-array and object-wrapper `command` cases are common enough to be
+named registry entries (`bashCommandArgvJoin`, `bashCommandUnwrap`) with the
+same guard-then-keep discipline; they only fire when the core string check
+already failed.
+
+### edit(path, edits:{oldText,newText}[])
+The canonical array-shape offender (Opus 4.6, GLM-5.1 in the code comment).
+
+| observed | core mode | note |
+|---|---|---|
+| `edits: "[{...}]"` | jsonStringParse | "sent `edits` as a quoted JSON string → send a raw array" |
+| `edits: {oldText,newText}` | singleObjectWrap | "sent one edit object → wrap in `[ ]`" |
+| `oldText`/`newText` at top level (no `edits`) | legacy adapter (NOT a repair) | migrated to `edits:[{...}]` by the existing edit adapter |
+
+### read / ls / grep / find (numeric + enum args)
+| observed | core mode | note |
+|---|---|---|
+| `offset`/`limit`/`context`/`tail`: `"10"` | numberFromString | "`P` is a number → sent 10" |
+| `limit`/`offset`: `null` | nullOptionalDrop | "omit `P` to use the default" |
+| read `filter`: `"None"`/`" minimal"` | enumCaseNormalize | "`filter` is one of none/minimal/aggressive → matched `<value>`" |
+| `ignoreCase`/`literal`/`metadata`: `"true"` | boolFromString | "`P` is a boolean → sent true" |
+
+## What is deliberately NOT in the grammar (bounce, do not repair)
+
+- Missing REQUIRED args with no default — the model must supply intent.
+- Wrong VALUE that is validly typed (e.g. a nonexistent path, a bad regex) —
+  not a shape error; belongs to execution + R44 teachable-errors, not repair.
+- Ambiguous enum (matches 2+ members) — bounce with the candidate list.
+- Any transform whose guard fails — never force it.
+- Semantic wrongness in a well-formed call — out of mechanical reach.
+
+## Performance contract (binding — the grammar must not slow the harness)
+
+The failure grammar only ever runs on ALREADY-FAILED calls. The hot path
+(well-formed args) never touches it. Concretely:
+
+1. **Check-first, allocation-free on success.** A valid call pays exactly one
+   `validator.Check(args)` (cached compiled validator) and returns the SAME
+   object — no clone, no walk, no grammar lookup. This is the ~99% path for
+   strong models and it is unchanged from today's cost.
+2. **Repairs are O(errors), not O(schema).** The analyzer walks the
+   validator's error list (already produced by the failed Check), not the
+   schema tree. Each error maps to at most a few candidate modes by a static
+   dispatch table keyed on `(expect, got)` — a Map lookup, not a scan.
+3. **No per-call compilation.** errorSignature matchers are precompiled
+   constants; note templates are format strings; the registry is built once
+   at module load. Nothing in the repair path constructs a RegExp, compiles a
+   schema, or parses JSON except the one `JSON.parse` a mode explicitly needs.
+4. **Bounded work.** At most: one clone of args, one transform per failing
+   path, one sub-Check per attempted transform, one whole-args re-Check. No
+   loops over transforms, no backtracking search. Worst case is linear in the
+   number of validation errors, which is itself tiny.
+5. **Text protocol only for flagged models.** The parser (R38) runs only when
+   a model is configured for text mode; native-tool-call models never invoke
+   it. The primer is generated once per session, not per turn.
+6. **Measured.** A microbench fixture asserts the clean-path cost is within
+   noise of a bare `Check` (no regression), and that a repaired call stays
+   under a fixed budget. Perf is an acceptance criterion, not an aspiration.
+
+The design principle: completeness lives entirely on the SLOW (already-broken)
+path; the FAST path is a single cached check. Adding the 6th–20th failure mode
+costs the hot path nothing.

package/dist/bundled-resources/skills/tool-call-repair/references/repair-catalogue.md

@@ -0,0 +1,201 @@
+# Repair catalogue and harness audit map
+
+Source: cross-model repair work on deepseek-flash, deepseek v4 pro, glm, qwen
+(owner, 2026-07) plus the 2026-07-06 pi-adaptative harness audit. Line numbers
+are anchors from that date; trust the named function over the number.
+
+## The repairs, precisely (named registry)
+
+Repairs run ONLY after a failed `Check`, keyed to the validator error at the
+failing instance path. Each candidate is applied on a clone and kept only if
+the sub-schema check passes. One re-Check of the whole args after all repairs;
+still failing means bounce to the model.
+
+Each repair is one registry entry: `{name, errorSignature, transform, guard,
+noteTemplate}`. The registry is the deterministic contract of what pi can and
+will repair; the same entry powers the repair, the teach note, the telemetry
+tag, and the docs table. Adding a repair means adding one entry plus its
+fixtures, nothing else.
+
+### 1. null-for-optional (`nullOptionalDrop`)
+- Error signature: type mismatch at path P, received `null`, P not in the
+  parent's `required` list.
+- Repair: delete key P from its parent object.
+- If P IS required: no repair. Bounce. Inventing `0`/`""`/`false` corrupts
+  intent (`limit: null` becoming `limit: 0` changes the program). This
+  replaces the current `coercePrimitiveByType` null branches.
+
+### 2. json-string-encoded array or object (`jsonStringParse`)
+- Error signature: expected array (or object) at P, received string.
+- Repair: `JSON.parse` the string; keep iff the parsed value is the expected
+  container type AND passes the sub-schema check.
+- MUST be attempted before repair 4 on the same error, or a stringified array
+  gets wrapped instead of parsed.
+
+### 3. single object where array-of-objects expected (`singleObjectWrap`)
+- Error signature: expected array at P, received object.
+- Repair: wrap as `[obj]` iff `obj` passes the array's `items` schema.
+- Covers the "empty placeholder" variant: `{}` where `items` has no required
+  fields wraps legitimately; `{}` where `items` requires fields fails the
+  guard and bounces (relational: the model owes the content).
+
+### 4. bare scalar where array expected (`bareScalarWrap`)
+- Error signature: expected array at P, received string/number/boolean.
+- Repair: wrap as `[v]` iff `v` passes `items`. Runs after repair 2.
+
+### 5. empty-object placeholder (`emptyObjectPlaceholder`)
+- Error signature: expected scalar (number/integer/string/boolean) at P,
+  received `{}`; OR expected array at P, received `{}` that fails repair 3's
+  guard (its `items` requires fields `{}` lacks).
+- Repair: treat `{}` as ABSENT. Optional P: delete the key — a declared
+  schema default then applies naturally (`shell({cmd, {} })` becomes
+  `shell({cmd})` and the default idleTime supplies the value). Required P
+  with a schema `default`: also deletable only if the validator honors the
+  default; otherwise bounce. Required P without default: bounce.
+- The rule that keeps this deterministic: the repair never invents the
+  value; the schema's declared default supplies it, or the model must.
+
+Ordering rule inside one error: parse (2) → wrap (3/4) → treat-as-absent (5).
+Across errors: independent paths are order-free; process in instance-path
+order for determinism.
+
+## Layer architecture (deterministic code, not prompts)
+
+Module: `packages/ai/src/utils/tool-repair/`
+
+| File | Responsibility | Purity contract |
+|---|---|---|
+| `registry.ts` | the named repair entries: `{name, errorSignature, transform, guard, noteTemplate}` as typed data + pure functions | no side effects; enumerable (docs + telemetry tags generate from it) |
+| `analyzer.ts` | validator error list -> classified failure modes at instance paths | pure; same errors, same classification |
+| `repairer.ts` | clone -> transform -> guard-check -> whole-args re-check orchestration | pure; never mutates input; no I/O/clock/randomness |
+| `text-protocol.ts` | ONE grammar definition; primer generator (Tool[] -> primer string) and envelope parser (text -> toolCall blocks) over it | pure; no regex scattered in providers |
+
+`validateToolArguments` is only the thin integration point (Check ->
+analyzer -> repairer -> re-Check -> bounce). Nothing in the repair path
+calls a model. Offline proving ground: `scripts/tool-repair-replay.mjs`
+replays corpus records or session files through analyzer/repairer with no
+LLM and no session, reporting classified | would-repair | would-bounce and
+emitting fixtures - new modes are developed against the script before
+touching the live path.
+
+## Choke-point map (audited 2026-07-06)
+
+| Layer | Anchor | State |
+|---|---|---|
+| Streaming args assembly | each provider, `parseStreamingJson(partialJson)`; e.g. `openai-completions.ts` ~:382, `anthropic.ts` ~:623 | tolerant partial parse; no repair here (correct; keep providers dumb) |
+| Blind pre-repair hook | `Tool.prepareArguments`, only user: `edit.ts` `prepareEditArguments` ~:95 | legacy special case of repair 2 for `edits` only (comment names GLM-5.1); delete once general repair lands |
+| Scalar conversion | `validation.ts` ~:294 `Value.Convert` | fine (string "5" to 5 etc.) |
+| Custom coercion | `validation.ts` `coerceWithJsonSchema` ~:205 | runs ONLY for non-TypeBox schemas (`hasTypeBoxMetadata` guard ~:297): built-ins get fewer repairs, backwards. null-to-zero-value branches ~:80-145 violate the relational rule |
+| Check + error | `validation.ts` ~:311-323 | per-path errors + received args; does NOT echo expected schema fragment |
+| Failure feedback | `agent-loop.ts` ~:700-704 | validation error becomes error tool result; model-side retry is the only recovery today |
+| Check-guarded pattern precedent | `validation.ts` `coerceWithUnionSchema` ~:193 | clone, coerce, Check; reuse this shape for all repairs |
+
+## Adjacent gap backlog (separate items, code-anchored)
+
+1. **Missing tool-call id synthesis.** `openai-completions.ts` ~:254 seeds
+   `id: toolCall.id || ""`. Open-model servers sometimes omit or duplicate
+   ids; an empty id breaks toolResult matching and replay. Synthesize a
+   stable id when absent (e.g. `call_<n>` per message) at assembly time.
+2. **Text tool-call extraction.** No fallback for serving stacks that never
+   emit native `tool_calls` (intent arrives as `<tool_call>{...}</tool_call>`
+   or fenced JSON in content). Models in that population cannot tool-call
+   through pi at all; repairs never see them. Extractor would live at the
+   provider boundary, gated per model/config, off by default.
+3. **Schema echo in validation errors.** The bounce message should include
+   the expected sub-schema fragment (and one valid example) at each failing
+   path; per-path error text alone often reproduces the same retry mistake.
+4. **Truncated-stream guard.** `parseStreamingJson` happily yields a partial
+   object when the stream ends mid-args (finish_reason length). If the
+   partial validates (all lost fields optional), the tool executes with
+   silently missing args. Detect terminal-with-incomplete-json and bounce.
+5. **Name sanitization parity.** `google-shared.ts` ~:95 sanitizes tool names
+   to `[a-zA-Z0-9_-]{1,64}`; the OpenAI-compat path sends names raw. MCP
+   tools with dots/colons 400 on strict backends.
+6. **History replay policy (decision needed).** Execution uses repaired args
+   but the assistant message keeps the model's original emission, and
+   `openai-completions.ts` ~:896 replays that original with a success result.
+   The model is shown that the malformed shape worked, reinforcing it every
+   turn. Options: replay repaired args (transcript diverges from what the
+   model emitted) or keep original (reinforcement). Decide once, document,
+   apply across providers.
+7. **Escalation counter.** N identical validation failures from the same
+   model on the same tool should trigger something better than an identical
+   retry: inject the schema example, or escalate the model tier for one turn
+   (see `model-router/tool-escalation.ts` for the existing escalation shape).
+
+## Teach-back spec (capture -> fix -> recover -> teach)
+
+The repair engine fixes the call; teach-back fixes the MODEL. Three tiers,
+cheapest first:
+
+1. **In-band note (per call).** When a repair fires, append one line to the
+   tool result: `[harness] <repairName>: <what was wrong> -> <the right
+   form>; executed as <repaired call>.` The IN -> OUT echo shows the model
+   exactly what its call became - the strongest teaching signal; the
+   repaired call and the repair note travel together in the same
+   tool-result message. Text comes from the registry entry's noteTemplate.
+   Fire on the FIRST (tool, repairName) occurrence per session; afterwards
+   every Nth occurrence (default 5). One line, no lecture; token cost is
+   the budget being protected.
+2. **Standing per-model rule (persistent).** When telemetry shows a
+   (model, failureMode) pair firing above threshold (default: 3 in one
+   session, or recurring across sessions), inject a standing rule into that
+   model's system prompt via the existing system-prompt builder ("emit arrays
+   as JSON arrays, never as quoted strings"). Persist in the per-model
+   profile. Hard cap (default 5 rules per model); retire any rule after 30
+   days of telemetry silence. Rules are shape rules only, never tool-specific
+   prose walls.
+3. **Teachable-error catalogue (execution level).** Common EXECUTION errors
+   get corrective guidance authored once, centrally: file-not-found suggests
+   listing the directory first; edit text-not-found suggests re-reading the
+   file; identical repeated failing calls escalate wording ("the same call
+   failed twice; change the arguments, do not resend"). Enumerated list, not
+   heuristics; each entry names its trigger error class.
+
+Efficacy is measured or the note dies: recurrence of the same (model, mode)
+after a teach event must drop; a note whose recurrence does not drop gets
+reworded or removed. "Wrong but successful" calls are OUT of mechanical reach
+except enumerated detectable subclasses (edit producing zero net change, read
+of an empty range treated as content, and similar); anything else is review
+territory, not repair territory.
+
+## Telemetry spec
+
+Emit one event per validation outcome: `{model, provider, tool, outcome:
+clean|repaired|bounced, failureModes: [1..5|other], repairsApplied:
+[registry names], taught: none|note|rule}`. Link repair events to the same call's execution
+outcome (did the repaired call succeed?) and compute recurrence-after-teach
+per (model, failureMode). Aggregate per model into the table below. Wire
+through the existing telemetry path (`core/telemetry.ts` / session-analytics)
+rather than a new sink. The "round-trips saved" metric is simply the repaired
+count; the "teach works" metric is recurrence decay.
+
+## Model notes (living table; append, do not rewrite)
+
+| Model | Observed modes | Notes | Date |
+|---|---|---|---|
+| glm (5.1) | 2 | stringified `edits` array on edit tool; was special-cased in `prepareEditArguments` | 2026-07-06 (from code comment) |
+| deepseek-flash | 1,2,3,4 | full catalogue observed in external repair work | 2026-07 |
+| deepseek v4 pro | 1,2,3,4 | same | 2026-07 |
+| qwen | 1,2,3,4 | same | 2026-07 |
+
+## Companion grammars (authoritative)
+
+- `failure-grammar.md` — the `errorSignature → transform → guard → note`
+  table (modes 1–10 + bash/edit/read tool-specific rows). What `analyzer.ts`
+  classifies against and `registry.ts` encodes.
+- `text-protocol-grammar.md` — the envelope EBNF, inbound variants, the
+  schema→primer projection, and the dictionary generated from pi's real
+  tools. What `text-protocol.ts` speaks and parses.
+
+## Acceptance fixtures (minimum set per repair)
+
+Per provider that feeds the choke point (anthropic, openai-completions,
+openai-responses, google, bedrock, mistral): one fixture per failure-grammar
+mode (1–10) proving repair, one proving the required-null bounce, one per
+guard-fails case proving bounce (transform rejected, args untouched), one
+proving well-formed args pass with NO mutation (hot path untouched), the
+ordering fixture `'["a","b"]'` → `["a","b"]` not `['["a","b"]']`, and the
+bash rows (`command` as argv-array → joined string; `command` as `{cmd}` →
+string; `timeout:"30"` → 30; `timeout:{}` → omitted). Plus the microbench:
+clean-path within noise of a bare `Check`; repaired-path under budget.

package/dist/bundled-resources/skills/tool-call-repair/references/text-protocol-grammar.md

@@ -0,0 +1,141 @@
+# Text tool-call protocol grammar (the "phone" language)
+
+The single source of truth for R38 (SPEAK primer + LISTEN parser) and R45
+(calibration). ONE grammar, two consumers: the primer generator emits it to
+the model, the parser recognizes it coming back. `text-protocol.ts` holds this
+as code; this file is the human-readable spec it must match. If the two ever
+disagree, the code's fixtures win and this file is corrected.
+
+Design constraints: unambiguous to parse with a bounded scanner (no regex
+soup, no nesting ambiguity), cheap to emit, and forgiving of the whitespace a
+weak model adds. The envelope is line-orientable but not line-dependent.
+
+## 1. Envelope grammar (EBNF)
+
+```ebnf
+call        = open-tag , ws? , args-json , ws? , close-tag ;
+open-tag    = "<pi:call" , ws , 'name="' , tool-name , '"' , ws? , ">" ;
+close-tag   = "</pi:call>" ;
+tool-name   = ident ;                         (* must match a known tool *)
+args-json   = json-object ;                   (* strict JSON, RFC 8259 *)
+ident       = (letter | "_") , { letter | digit | "_" } ;
+ws          = { " " | "\t" | "\n" | "\r" } ;
+```
+
+- `args-json` is a COMPLETE JSON object (`{...}`), UTF-8, double-quoted keys.
+  It is NOT the harness's job to be a lenient JSON parser here — malformed
+  inner JSON is a LISTEN failure that flows into the R31 repair pipeline
+  (which owns JSON tolerance), not a grammar concern.
+- One `<pi:call>...</pi:call>` per tool invocation. Multiple calls in one
+  turn = multiple envelopes; the parser extracts each independently in
+  document order.
+- Text outside envelopes is prose (reasoning, explanation) and is preserved
+  as the assistant's text content — never discarded, never parsed as a call.
+- The tag prefix `pi:` is deliberate: it is vanishingly unlikely to collide
+  with prose or code the model quotes, which keeps extraction unambiguous.
+
+Why `<pi:call name="X">{...}</pi:call>` and not bare JSON or `X({...})`:
+- an explicit open/close pair lets the scanner find exact boundaries even
+  when args-json contains `}` inside strings (scan to `</pi:call>`, then
+  parse the interior as JSON) — no brace-counting heuristics;
+- `name=` as an attribute (not the JSON) means a malformed args body still
+  tells us WHICH tool was intended, so the R31 bounce/repair note can be
+  tool-specific;
+- it is visually distinct from the code models love to emit, so calibration
+  (R45) can tell "spoke the protocol" from "wrote about the protocol".
+
+## 2. Recognized inbound variants (LISTEN tolerance)
+
+The parser accepts, in priority order, and normalizes all to the canonical
+form above. Recognizing more than we emit is deliberate: open models arrive
+pre-trained on other stacks' conventions.
+
+1. Canonical `<pi:call name="X"> {json} </pi:call>`.
+2. `<tool_call>{"name":"X","arguments":{...}}</tool_call>` (common OSS
+   convention; `arguments` may itself be a JSON STRING — that is exactly
+   R31 mode 2, handed straight to the repairer).
+3. Fenced block tagged `tool`/`tool_call`:
+   ```` ```tool\n{"name":"X","arguments":{...}}\n``` ````
+Everything else is prose. Ambiguous text is NEVER guessed into a call
+(doctrine: no heuristic soup). Unknown `tool-name` → not a call; it becomes a
+bounce with the "unknown tool" note listing valid names.
+
+## 3. Schema -> primer projection (how the dictionary is generated)
+
+The primer is GENERATED from the live `Tool[]`, never hand-written, so adding
+a tool updates the dictionary for free. Projection rules per tool:
+
+- one line: `tool-name(arg:type[?], ...) - <one-line purpose from schema
+  description>`;
+- `?` suffix marks Optional; enums render as `a|b|c`; arrays as `type[]`;
+  nested objects as `{k:type,...}`;
+- types collapse to the five the model needs: `string`, `number`, `bool`,
+  `T[]`, `{...}`. No JSON-Schema keywords leak into the primer;
+- required-args-first ordering; default values shown as `=default` when the
+  schema declares one;
+- two worked examples per primer TOTAL (not per tool): one simplest call,
+  one call with an array arg (the shape open models most often break),
+  chosen from the actual tool set.
+
+The primer header (fixed text):
+
+```
+To use a tool, reply with EXACTLY this and nothing else around it:
+<pi:call name="TOOL">{ "arg": value }</pi:call>
+Rules: arguments is ONE JSON object. Arrays are JSON arrays [ ], never
+quoted strings. Omit optional args you do not need - do not send null.
+Put any reasoning BEFORE the tag, not inside it.
+```
+
+## 4. The dictionary for pi's core tools (generated 2026-07-06)
+
+Verbatim projection of the real schemas (`bash.ts`, `read.ts`, `edit.ts`,
+`write.ts`, `ls.ts`, `grep.ts`, `find.ts`). This is what a text-only model
+sees; regenerate whenever a tool schema changes (a test asserts this table
+matches the projection).
+
+```
+bash(command:string, timeout:number?) - run a bash command
+read(path:string, offset:number?, limit:number?, lineNumbers:bool?, tail:number?, filter:none|minimal|aggressive?) - read a file
+edit(path:string, edits:{oldText:string,newText:string}[]) - apply targeted text replacements to a file
+write(path:string, content:string) - write (create/overwrite) a file
+ls(path:string?, limit:number?, metadata:bool?) - list a directory
+grep(pattern:string, path:string?, glob:string?, ignoreCase:bool?, literal:bool?, context:number?, limit:number?) - search file contents
+find(pattern:string, path:string?, limit:number?, ignoreCase:bool?) - find files by glob
+```
+
+Worked examples (the two shipped in the primer):
+
+```
+Read a file:
+<pi:call name="read">{ "path": "src/index.ts" }</pi:call>
+
+Replace text (note edits is a JSON ARRAY of objects):
+<pi:call name="edit">{ "path": "src/app.ts", "edits": [ { "oldText": "foo", "newText": "bar" } ] }</pi:call>
+```
+
+The `edit` example is deliberate: `edits` is the array field open models most
+often send as a stringified array (`"[{...}]"`) or a bare object (`{...}`) —
+showing the correct shape here, and repairing+teaching it via R31/R40 when
+they still get it wrong, is the whole loop in one arg.
+
+## 5. Parser output contract
+
+`parseTextToolCalls(text, knownTools) -> { calls: ToolCallBlock[], text:
+string }` where:
+- `calls` are canonical toolCall blocks (name + parsed-or-raw args), each
+  tagged `origin: "text-protocol"` so R35 telemetry attributes them and R31
+  knows the args came through the phone;
+- `text` is the input with every recognized envelope removed (the surviving
+  prose);
+- args that fail JSON parse are passed to R31 as a raw string under the named
+  tool (repairer owns tolerance); the parser itself never invents args.
+
+## 6. Calibration trials (R45) use this grammar
+
+The trial tool is `echo(data:string)` (harness-provided, side-effect-free).
+Calibration asks the model to `echo` a known token via the protocol and
+checks the parser round-trips it. Grammar variants tried on failure, in
+order: (a) restate header + one example; (b) drop to fenced-block variant 3
+if angle-bracket tags fail; (c) shrink the dictionary to the single tool
+under test. The variant that first round-trips is persisted per model (R46).