pi-braid 0.42.0 → 0.43.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/CHANGELOG.md +1077 -0
  2. package/README.md +61 -228
  3. package/TOOLS.md +12 -14
  4. package/build-info.json +4 -4
  5. package/dist/extensions/cognitive/metacognition/handlers/think.js +9 -0
  6. package/dist/extensions/core/polyfill/index.d.ts +3 -4
  7. package/dist/extensions/core/polyfill/index.js +34 -131
  8. package/dist/extensions/core/skills-tool/index.js +47 -26
  9. package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +13 -0
  10. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +8 -3
  11. package/dist/extensions/enforcement/session-health.d.ts +52 -4
  12. package/dist/extensions/enforcement/session-health.js +75 -5
  13. package/dist/extensions/enforcement/whisper.js +15 -1
  14. package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +17 -0
  15. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +40 -78
  16. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +2 -1
  17. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +26 -28
  18. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +62 -31
  19. package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +130 -55
  20. package/dist/extensions/manifest.js +6 -0
  21. package/dist/extensions/memory/context-lifecycle/index.js +11 -10
  22. package/dist/extensions/memory/context-manager/analysis.d.ts +2 -0
  23. package/dist/extensions/memory/context-manager/analysis.js +6 -2
  24. package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +3 -3
  25. package/dist/extensions/memory/context-manager/handlers/events.js +13 -1
  26. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +10 -14
  27. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +62 -88
  28. package/dist/extensions/self/path-miss/detect.d.ts +30 -0
  29. package/dist/extensions/self/path-miss/detect.js +67 -0
  30. package/dist/extensions/self/path-miss/index.d.ts +33 -0
  31. package/dist/extensions/self/path-miss/index.js +118 -0
  32. package/dist/extensions/self/watchdog/engine.d.ts +8 -1
  33. package/dist/extensions/self/watchdog/engine.js +25 -2
  34. package/dist/extensions/self/watchdog/index.js +14 -1
  35. package/dist/lib/ai/llm-call.js +23 -0
  36. package/dist/lib/ai/model-resolver.d.ts +11 -10
  37. package/dist/lib/ai/model-resolver.js +16 -19
  38. package/dist/lib/ai/presend-budget.d.ts +68 -0
  39. package/dist/lib/ai/presend-budget.js +83 -0
  40. package/dist/lib/config/braid-settings.d.ts +38 -0
  41. package/dist/lib/config/braid-settings.js +84 -0
  42. package/dist/lib/config/per-tool-settings.d.ts +4 -4
  43. package/dist/lib/config/per-tool-settings.js +4 -4
  44. package/dist/lib/core/event-names.d.ts +1 -0
  45. package/dist/lib/core/event-names.js +1 -0
  46. package/dist/lib/detection/context-tiers.d.ts +18 -5
  47. package/dist/lib/detection/context-tiers.js +51 -33
  48. package/dist/lib/detection/context-usage.d.ts +62 -1
  49. package/dist/lib/detection/context-usage.js +158 -1
  50. package/dist/lib/errors/llm-error.d.ts +14 -0
  51. package/dist/lib/errors/llm-error.js +44 -1
  52. package/dist/lib/state/global-state.d.ts +4 -8
  53. package/dist/lib/state/global-state.js +11 -28
  54. package/dist/lib/telemetry/context-heartbeat.d.ts +9 -0
  55. package/dist/lib/telemetry/context-heartbeat.js +18 -8
  56. package/dist/lib/utils/argument-report.d.ts +41 -0
  57. package/dist/lib/utils/argument-report.js +95 -0
  58. package/dist/lib/utils/wake-gate.d.ts +6 -0
  59. package/dist/lib/utils/wake-gate.js +52 -4
  60. package/docs/SETUP.md +7 -6
  61. package/package.json +11 -13
  62. package/src/extensions/cognitive/metacognition/handlers/think.ts +9 -0
  63. package/src/extensions/core/polyfill/index.ts +29 -157
  64. package/src/extensions/core/skills-tool/index.ts +60 -37
  65. package/src/extensions/enforcement/AGENTS.md +38 -1
  66. package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +13 -0
  67. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +8 -2
  68. package/src/extensions/enforcement/session-health.ts +94 -5
  69. package/src/extensions/enforcement/whisper.ts +15 -1
  70. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +53 -80
  71. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +34 -43
  72. package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +154 -52
  73. package/src/extensions/manifest.ts +6 -0
  74. package/src/extensions/memory/AGENTS.md +37 -38
  75. package/src/extensions/memory/context-lifecycle/index.ts +11 -10
  76. package/src/extensions/memory/context-manager/analysis.ts +8 -1
  77. package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +3 -3
  78. package/src/extensions/memory/context-manager/handlers/events.ts +18 -1
  79. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +81 -115
  80. package/src/extensions/scheduling/timer/AGENTS.md +14 -4
  81. package/src/extensions/self/AGENTS.md +2 -1
  82. package/src/extensions/self/path-miss/AGENTS.md +39 -0
  83. package/src/extensions/self/path-miss/detect.ts +78 -0
  84. package/src/extensions/self/path-miss/index.ts +135 -0
  85. package/src/extensions/self/watchdog/AGENTS.md +36 -18
  86. package/src/extensions/self/watchdog/engine.ts +30 -2
  87. package/src/extensions/self/watchdog/index.ts +13 -1
  88. package/src/lib/ai/AGENTS.md +2 -0
  89. package/src/lib/ai/llm-call.ts +30 -0
  90. package/src/lib/ai/model-resolver.ts +16 -19
  91. package/src/lib/ai/presend-budget.ts +117 -0
  92. package/src/lib/config/braid-settings.ts +125 -0
  93. package/src/lib/config/per-tool-settings.ts +4 -4
  94. package/src/lib/core/event-names.ts +1 -0
  95. package/src/lib/detection/context-tiers.ts +52 -41
  96. package/src/lib/detection/context-usage.ts +211 -2
  97. package/src/lib/errors/llm-error.ts +55 -1
  98. package/src/lib/state/global-state.ts +11 -29
  99. package/src/lib/telemetry/context-heartbeat.ts +27 -7
  100. package/src/lib/utils/AGENTS.md +1 -0
  101. package/src/lib/utils/argument-report.ts +105 -0
  102. package/src/lib/utils/wake-gate.ts +59 -4
package/README.md CHANGED
@@ -1,16 +1,15 @@
1
1
  <!-- status: current -->
2
2
 
3
- # pi-braid 🥨
3
+ # pi-braid
4
4
 
5
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
- [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg)](https://www.typescriptlang.org/)
7
6
  [![pi-coding-agent ^1.2.0](https://img.shields.io/badge/pi--coding--agent-%5E1.2.0-blueviolet)](https://github.com/earendil-works/pi)
8
7
 
9
- Honest self-aware agent with a metacognitive suite and extras on top of [pi-coding-agent](https://github.com/earendil-works/pi). The suite adds enforcement, memory, reasoning, self-improvement, and structured cognitive signals on top of the pi agent session.
8
+ Memory, plan tracking, and completion checks for the [pi](https://github.com/earendil-works/pi)
9
+ coding agent. A long session keeps what it learned, keeps its working state across compaction, and
10
+ has to show evidence before it calls a task done.
10
11
 
11
- > **⚠️ Early-stage software.** APIs may change. Not production-hardened.
12
-
13
- ---
12
+ > **Early-stage software.** APIs may change. Not production-hardened.
14
13
 
15
14
  ## Install
16
15
 
@@ -18,247 +17,81 @@ Honest self-aware agent with a metacognitive suite and extras on top of [pi-codi
18
17
  pi install npm:pi-braid
19
18
  ```
20
19
 
21
- One command, no clone, no build: `pi install` registers the package with pi,
22
- writes the declaration to `~/.pi/agent/settings.json`, and installs it under
23
- pi's npm directory. It carries the suite and the core skill set that ships with
24
- it. The on-demand skill pack and the other companions are add-ons, each its own
25
- install: `pi install npm:pi-braid-skills`,
26
- `pi install npm:pi-braid-contrib`, `pi install npm:pi-braid-providers`,
27
- `pi install npm:pi-braid-telegram`.
28
-
29
- The core package also installs one command, `pi-braid-fleet`, the operator
30
- surface of braid's **supervisor fleet**: one supervisor process driving local
31
- node sessions against a single SQLite journal. It is not the worker registry
32
- `orchestrate` keeps for parallel agents, which is a worker pool (see below).
33
- `pi-braid-fleet --help` prints the four commands and exits 0;
34
- [`docs/FLEET.md`](docs/FLEET.md) is the guide to the fleet and its journal.
35
-
36
- To enable braid for one project only, or to use all five workspaces, see
37
- [docs/SETUP.md](docs/SETUP.md) § Install paths. For the full setup reference
38
- (per-project installs, skills, module toggles, troubleshooting) see
39
- **[`docs/SETUP.md`](docs/SETUP.md)**; new to pi and braid, start with
40
- **[`docs/BEGINNERS.md`](docs/BEGINNERS.md)**.
41
-
42
- ### From a checkout (working on braid)
43
-
44
- Build the workspace and point pi at the local path:
45
-
46
- ```bash
47
- git clone https://github.com/kifirkin/pi-braid.git ~/pi-braid
48
- cd ~/pi-braid && npm install && npm run build
49
- ```
50
-
51
- Register `packages/core` (plus `packages/skills` for the pack) under `packages`
52
- in pi's settings; the root `package.json` has no `pi` field, so `file:~/pi-braid`
53
- loads nothing. Each workspace is loaded through the `pi.extensions` /
54
- `pi.skills` fields in its `package.json` (no workspaces auto-discovery). The
55
- install-path reference is [`docs/SETUP.md`](docs/SETUP.md);
56
- [`examples/`](https://github.com/kifirkin/pi-braid/tree/main/examples) carries
57
- copy-ready settings.
58
-
59
- ## What this does not do
60
-
61
- - It is not a standalone agent. pi-coding-agent is the runtime; braid is a layer loaded into it.
62
- - It does not replace pi's native tools. braid-registered tools sit alongside `read`/`bash`/`edit`.
63
- - It does not run outside a pi session. Loading, state, and enforcement are per session.
64
- - It contacts no third-party analytics or crash-reporting service. State lives on disk under `~/.pi/agent/`.
65
-
66
- ## Activation preconditions
67
-
68
- - pi-coding-agent installed (the `@earendil-works/pi-*` peers are declared as `*` and resolve
69
- against the pi in your tree at install time - see [`docs/SETUP.md`](docs/SETUP.md)).
70
- - Node.js 22+ (pi's own floor).
71
- - The package registered under `packages` (or installed with `pi install`) so pi loads `pi.extensions`.
72
-
73
- ---
74
-
75
- ## How it fits pi
76
-
77
- pi loads extensions from a `packages` entry in `<cwd>/.pi/settings.json` (project) or `~/.pi/agent/settings.json` (user-global). braid is a regular extension package - point pi at it via a `file:` or `git+https:` spec.
78
-
79
- This package is the **core** workspace. The monorepo also contains four
80
- sibling packages (see the root [`README.md`](https://github.com/kifirkin/pi-braid/blob/main/README.md) for the full map):
81
-
82
- | Package | Role |
83
- | ------------- | -------------------------------------------------------------------- |
84
- | `core` (this) | Metacognitive extension suite - memory, enforcement, cognitive, self |
85
- | `skills` | Content-only skill pack (`SKILL.md` catalog, no runtime code) |
86
- | `contrib` | Standalone code-only extension modules (browser, codebase, diff, …) |
87
- | `providers` | Venice (agent-zero proxy) provider + multi-key ring |
88
- | `telegram` | Bidirectional Telegram channel (send, inbound, voice, pause) |
89
-
90
- ---
91
-
92
- ## What it does
93
-
94
- 28 extensions ship; `health-maintenance` and `error-tracking` are off by
95
- default, and the flat list is
96
- [`src/extensions/manifest.ts`](src/extensions/manifest.ts). They cover:
97
-
98
- - **Enforcement** - the turn pipeline: turn validation, signal delivery, sycophancy and verification nudges, behavior patterns
99
- - **Reasoning** - topic-drift detection, claim tracking, bidirectional verification, contradiction detection
100
- - **Self-improvement** - heuristic evolution, reflection, offline consolidation
101
- - **Utilities** - health, timers, workspace snapshots, context lifecycle
20
+ `pi install` registers the package with pi, writes the declaration to
21
+ `~/.pi/agent/settings.json`, and unpacks it under pi's npm directory. The next `pi` start loads the
22
+ suite and the 22 skills that ship with it.
102
23
 
103
- Five capabilities explain the rest of the file:
24
+ The package also installs one command, `pi-braid-fleet`: a supervisor process that drives local node
25
+ sessions against a single SQLite journal. [docs/FLEET.md](docs/FLEET.md) is its guide.
104
26
 
105
- ### The prompt builder
27
+ Working on braid itself, or tracking `main`? [CONTRIBUTING.md](CONTRIBUTING.md) has the checkout and
28
+ build flow; [docs/SETUP.md](docs/SETUP.md) covers every install path.
106
29
 
107
- The system prompt is assembled, not written once: named sections are composed
108
- as `PromptSection` fragments
109
- ([`section.ts`](src/extensions/core/prompt-builder/section.ts)) and published
110
- through pi's section seam, so a section that changes re-sends alone instead of
111
- the whole head prompt
112
- ([`section-publish.ts`](src/extensions/core/prompt-builder/section-publish.ts)).
113
- Sections a host or an earlier handler supplies on the prompt options are
114
- rendered as their own blocks
115
- ([`custom-sections.ts`](src/extensions/core/prompt-builder/custom-sections.ts)),
116
- and because braid renders the whole prompt it suppresses pi's native preamble,
117
- tool list, rules and docs. `prompt_inspect` prints the assembled result at any
118
- point in a session, which is the point: most of braid's behavior is inspectable
119
- prompt text rather than hardcoded replies.
30
+ ## What it adds
120
31
 
121
- ### Memory as a system
32
+ | Capability | What changes in the session |
33
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
34
+ | Memory | Three stores hold different kinds of memory: episodes (what happened), semantic entries (what it learned), and heuristics (rules it applies). The scratchpad is working memory that survives compaction, and a resume file hands the open plan to a fresh session. |
35
+ | Work discipline | `think`, `hypothesize`, `verify` and `finalize` make reasoning and completion explicit; a task closes with evidence, not with a claim. Behavior patterns switch the working mode. |
36
+ | Context lifecycle | Usage bands fire pruning, archiving and compaction; a reserve keeps headroom for the next turn; oversized tool results are offloaded to disk and stubbed. The numbers are owned by [docs/CONTEXT-POLICY.md](docs/CONTEXT-POLICY.md). |
37
+ | Subagents | `orchestrate` keeps a per-project worker registry with admission, lifecycle, one branch per worker, file locks, conflict detection, and merge verification. |
38
+ | Prompt assembly | The system prompt is composed from named sections and published through pi's section seam, so a changed section re-sends alone. `prompt_inspect` prints the assembled prompt at any point. |
122
39
 
123
- Three stores hold different kinds of memory: episodes (what happened, per
124
- session, promoted to semantic when the agent keeps referencing them), semantic
125
- entries (what it learned, written on shutdown and loaded next session), and the
126
- heuristics (procedural rules) it applies while working. The scratchpad is working memory that
127
- survives compaction, and a resume file hands the open plan to a fresh seat at
128
- session start
129
- ([`resume-state.ts`](src/extensions/enforcement/resume-state.ts)). `memory`
130
- reads across the stores; `session` reads across past sessions. Deep source:
131
- [`src/extensions/memory/AGENTS.md`](src/extensions/memory/AGENTS.md).
40
+ The suite is 29 extensions; `health-maintenance` and `error-tracking` are off by default, and the
41
+ list is [src/extensions/manifest.ts](src/extensions/manifest.ts). `set_tool_profile` switches the
42
+ active tool set to a curated profile.
132
43
 
133
- ### A worker pool
44
+ ## Highlights
134
45
 
135
- `orchestrate` coordinates parallel agent workers: a per-project worker registry
136
- with admission and lifecycle, one branch per worker, file locks, conflict
137
- detection, close gates, and merge verification. Branch handling is git-optional:
138
- with no repository it falls back to lock-only coordination. The working
139
- procedure is the [`subagent-orchestration`](skills/subagent-orchestration/SKILL.md)
140
- skill; the registry is
141
- [`src/extensions/orchestrator/index.ts`](src/extensions/orchestrator/index.ts).
46
+ | Tool | What it adds |
47
+ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
48
+ | `think`, `hypothesize`, `verify`, `verify_claim`, `finalize` | Structured reflection, root-cause hypotheses, work verification, claim checks, task closure |
49
+ | `scratchpad` | Goal, plan, decisions and learnings that survive compaction |
50
+ | `memory`, `memory_store`, `session` | Three-store recall; cross-session context search |
51
+ | `orchestrate` | Parallel worker registry: admission, locks, close gates, merge verification |
52
+ | `context_compress`, `context_inspect`, `context_navigate` | Archive, compact and inspect the session's own context |
53
+ | `timer`, `workspace_snapshot`, `topic_drift` | Non-blocking timers, file time travel, drift detection against an anchored topic |
142
54
 
143
- This is a pool of workers, not a fleet: the package's `pi-braid-fleet` command,
144
- described in Install above, is the supervisor fleet, and the two share no code,
145
- journal or lifecycle.
146
-
147
- ### Context lifecycle
148
-
149
- braid manages its own window: usage bands fire pruning, archiving and
150
- compaction; a compaction reserve keeps headroom for the next turn;
151
- auto-compaction arms on usage; oversized tool results are offloaded to disk and
152
- stubbed. A failed compaction walks retries, then a bounded summarizer, then a
153
- deterministic cut that needs no provider, so the session keeps compressing even
154
- when the model stops answering. The
155
- numbers are owned by [`docs/CONTEXT-POLICY.md`](docs/CONTEXT-POLICY.md); the
156
- tools are `context_compress`, `context_inspect` and `context_navigate`.
157
-
158
- ### Highlights
159
-
160
- | Tool / Extension | What it adds |
161
- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
162
- | `think`, `verify`, `hypothesize`, `finalize` | Metacognitive tools (always-on). Use `think` for non-trivial reflection; `verify` to check work; `finalize` to close a task with evidence. |
163
- | `scratchpad` | Goal/plan/decision/learning tracker that survives context compaction |
164
- | `memory`, `memory_store`, `conflict_qa` | Three-store recall (episodes / semantic / heuristics) cross-searched; conflict resolution between sources |
165
- | `session` | Cross-session context recall (search / query past sessions) |
166
- | `topic_drift` | Anchor tracking + drift detection |
167
- | `behavior` | Activate / deactivate behavior patterns |
168
- | `timer` | Non-blocking session-scoped timers |
169
- | `workspace_snapshot` | Capture / diff / restore workspace state for time-travel debugging |
170
-
171
- [`TOOLS.md`](TOOLS.md) is the catalog: every tool this package registers, pi's
172
- own builtins, and the cold tools that stay undeclared until `tool_search` loads
173
- them. `set_tool_profile` switches the active set to a curated profile.
174
-
175
- ---
55
+ [TOOLS.md](TOOLS.md) is the catalog: every tool this package registers, pi's own builtins, and the
56
+ cold tools that stay undeclared until `tool_search` loads them.
176
57
 
177
58
  ## Configuration
178
59
 
179
- ### Module toggling
180
-
181
- braid's loader follows a **four-tier precedence** (high → low):
182
-
183
- 1. Runtime API (`/modules-toggle`, `/modules-enable`, `/modules-disable`)
184
- 2. `~/.pi/agent/settings.json` → `braid.modules`
185
- 3. `BRAID_MODULES` env var
186
- 4. Defaults - all non-opt-in extensions enabled
187
-
188
- A ref is either an **extension id** (`enforcement`, `error-tracking`) or a
189
- **module group name** (`heartbeat`, `core`, `memory`), prefixed `+` to enable or
190
- `-` to disable: `BRAID_MODULES="all,-error-tracking"`. Settings win over the env
191
- var; the runtime API wins over both. Worked patterns are in
192
- [`AGENTS.md`](AGENTS.md) § Common `BRAID_MODULES` patterns.
193
-
194
- ### Settings
195
-
196
- `braid.modules` is one leaf of the settings surface. The source is
197
- `schema/braid.schema.json`, [`docs/SETUP.md`](docs/SETUP.md) § Configuration
198
- reference lists every path with its default, and
199
- [`examples/full-config.settings.json`](https://github.com/kifirkin/pi-braid/blob/main/examples/full-config.settings.json)
200
- is copy-ready.
201
-
202
- ### Storage
203
-
204
- All braid-specific data goes under `~/.pi/agent/braid/`. Use the constants in [`src/lib/config/braid-paths.ts`](src/lib/config/braid-paths.ts) - never hardcode paths.
205
-
206
- ---
60
+ Settings live in `~/.pi/agent/settings.json` under `braid.*`. [docs/SETUP.md](docs/SETUP.md) is the
61
+ reference: every key, its default, and worked examples. Module toggling has its own precedence
62
+ (runtime API, then settings, then the `BRAID_MODULES` environment variable, then defaults), and
63
+ `docs/SETUP.md` states it with the patterns people actually use.
207
64
 
208
65
  ## Skills
209
66
 
210
- Skills come in two tiers: the core set ships inside this package (`skills/`,
211
- declared by `pi.skills` in `package.json`), and the on-demand pack is the
212
- content-only **`../skills`** workspace. Every skill is a `SKILL.md` with a
213
- `name` / `description` frontmatter header.
67
+ 22 skills ship in this package under `skills/`, declared by `pi.skills` in `package.json`. The
68
+ separate `pi-braid-skills` package carries eight more for project-scoped loading. Skills are read on
69
+ demand, not pasted into the prompt: `list_skills` ranks the catalog against the current task and
70
+ prices each read, `skill_stats` counts what was suggested and what was actually opened.
214
71
 
215
- Discovery is on demand, not in the prompt: `list_skills` returns the catalog
216
- ranked against the current task, each row priced by what the read will cost
217
- (lines, bytes, token estimate, headings). When a skill's triggers match the
218
- task, an excerpt is steered into the session, and `skill_stats` counts which
219
- skills were suggested and which were actually read.
72
+ ## Limits
220
73
 
221
- The catalog table (one row per skill, with its verdict and one-line
222
- description, covering both tiers) lives in
223
- **[`packages/skills/README.md`](https://github.com/kifirkin/pi-braid/blob/main/packages/skills/README.md)**, and
224
- `find packages/core/skills -name SKILL.md | wc -l` counts the core set at any
225
- time (`find packages/skills/skills -name SKILL.md | wc -l` counts the pack).
226
-
227
- ---
74
+ - It is not an agent of its own: pi is the runtime, and braid is a layer loaded into it.
75
+ - It does not replace pi's native tools. braid's tools sit alongside `read`, `bash` and `edit`.
76
+ - It does not run outside a pi session. Loading, state and enforcement are per session.
77
+ - Braid's own data lives under `~/.pi/agent/braid/`. The provider package keeps its key-ring and
78
+ route-state files directly under `~/.pi/agent/`.
79
+ - It contacts no third-party analytics or crash-reporting service.
228
80
 
229
81
  ## Documentation
230
82
 
231
- | Doc | For |
232
- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
233
- | [`docs/BEGINNERS.md`](docs/BEGINNERS.md) | **First walkthrough**: install → how agents use braid → first extension |
234
- | [`docs/SETUP.md`](docs/SETUP.md) | **Full setup reference**, install paths, troubleshooting |
235
- | [`TOOLS.md`](TOOLS.md) | Tool catalog: registered tools, pi builtins, cold tools |
236
- | [`docs/CONTEXT-POLICY.md`](docs/CONTEXT-POLICY.md) | Window, usage bands, compaction reserve, caps, offload, archiving |
237
- | [`docs/FLEET.md`](docs/FLEET.md) | The `pi-braid-fleet` supervisor fleet: commands, tiers, journal |
238
- | [`docs/ROADMAP.md`](docs/ROADMAP.md) | Active roadmap + shipped milestones + open themes |
239
- | [`README.md`](README.md) | This overview |
240
- | [`AGENTS.md`](AGENTS.md) | Repository structure, DOX contract, conventions |
241
- | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Development setup, code style, PR workflow, release |
242
- | [`docs/HISTORY.md`](docs/HISTORY.md) | Consolidated project history, archived roadmap, research |
243
- | [`CHANGELOG.md`](https://github.com/kifirkin/pi-braid/blob/main/CHANGELOG.md) | Release notes (curated) |
244
-
245
- ---
246
-
247
- ## Development
248
-
249
- ```bash
250
- git clone https://github.com/kifirkin/pi-braid.git
251
- cd pi-braid
252
- npm install
253
- npm run typecheck # TypeScript check
254
- npm run build # Compile to dist/
255
- npm run test # Build + run the runtime test suite
256
- npm run lint # ESLint
257
- ```
258
-
259
- For the full development guide - extension anatomy, manifest model, testing bar, release process - see **[`CONTRIBUTING.md`](CONTRIBUTING.md)** and **[`AGENTS.md`](AGENTS.md)**.
260
-
261
- ---
83
+ | Doc | For |
84
+ | --------------------------------------------------------------------------- | ------------------------------------------------------------------- |
85
+ | [docs/BEGINNERS.md](docs/BEGINNERS.md) | First walkthrough: install, first session, first extension |
86
+ | [docs/SETUP.md](docs/SETUP.md) | Full setup reference: install paths, configuration, troubleshooting |
87
+ | [docs/CONTEXT-POLICY.md](docs/CONTEXT-POLICY.md) | Window, usage bands, compaction reserve, caps, offload, archiving |
88
+ | [docs/FLEET.md](docs/FLEET.md) | The `pi-braid-fleet` supervisor: commands, tiers, journal |
89
+ | [docs/ROADMAP.md](docs/ROADMAP.md) | Shipped milestones and open themes |
90
+ | [docs/HISTORY.md](docs/HISTORY.md) | Project history and archived research |
91
+ | [TOOLS.md](TOOLS.md) | Tool catalog |
92
+ | [AGENTS.md](AGENTS.md) | Repository structure and conventions |
93
+ | [CONTRIBUTING.md](CONTRIBUTING.md) | Development flow, tests, release |
94
+ | [CHANGELOG.md](https://github.com/kifirkin/pi-braid/blob/main/CHANGELOG.md) | Release notes, newest first |
262
95
 
263
96
  ## License
264
97
 
package/TOOLS.md CHANGED
@@ -89,20 +89,18 @@ the core and contrib extensions and named in no other document. A command with
89
89
  a home beside its extension is not repeated here - `/watchdog-status` lives in
90
90
  the watchdog `AGENTS.md`, the `/modules-*` family in `SETUP.md`.
91
91
 
92
- | Command | Registered by | What it does |
93
- | --------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
94
- | `/analytics` | analytics (heartbeat module) | Show tool analytics for the current session. |
95
- | `/analytics:all` | analytics (heartbeat module) | Show tool analytics across all historical sessions. |
96
- | `/analytics:ab` | analytics (heartbeat module) | Show A/B experiment results across variants. |
97
- | `/context-stats` | context-manager (memory module) | Show context pruning statistics. |
98
- | `/rate-cancel` | rate-limiter (contrib) | Cancel the rate limiter wait and reset its state. |
99
- | `/tool-status` | tool-config (contrib) | Show current tool configuration. |
100
- | `/browser-start` | browser (contrib) | Spawn Chrome with remote debugging; `--profile` syncs cookies and logins. |
101
- | `/browser-connect` | browser (contrib) | Connect to Chrome at :9222 (auto-starts if not running). |
102
- | `/browser-disconnect` | browser (contrib) | Disconnect from the browser session. |
103
- | `/utility-model` | polyfill (core) | Set or show the utility model for classification tasks; accepts one model or an ordered list (comma-separated), tried in order until the provider layer reports a route usable. |
104
- | `/vision-model` | polyfill (core) | Set or show the vision model (every entry must accept image input); deprecated - image analysis falls back to the utility list's first image-capable model, and the command is removed next release. |
105
- | `/max-power-model` | polyfill (core) | Deprecated alias of `/utility-model`: the max-power role merged into the utility role; set/show/clear operate on the canonical utility setting, and the alias is removed next release. |
92
+ | Command | Registered by | What it does |
93
+ | --------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
94
+ | `/analytics` | analytics (heartbeat module) | Show tool analytics for the current session. |
95
+ | `/analytics:all` | analytics (heartbeat module) | Show tool analytics across all historical sessions. |
96
+ | `/analytics:ab` | analytics (heartbeat module) | Show A/B experiment results across variants. |
97
+ | `/context-stats` | context-manager (memory module) | Show context pruning statistics. |
98
+ | `/rate-cancel` | rate-limiter (contrib) | Cancel the rate limiter wait and reset its state. |
99
+ | `/tool-status` | tool-config (contrib) | Show current tool configuration. |
100
+ | `/browser-start` | browser (contrib) | Spawn Chrome with remote debugging; `--profile` syncs cookies and logins. |
101
+ | `/browser-connect` | browser (contrib) | Connect to Chrome at :9222 (auto-starts if not running). |
102
+ | `/browser-disconnect` | browser (contrib) | Disconnect from the browser session. |
103
+ | `/utility-model` | polyfill (core) | Set or show the utility model for classification tasks; accepts one model or an ordered list (comma-separated), tried in order until the provider layer reports a route usable. |
106
104
 
107
105
  ## Appendix: standalone packages surfaced into the braid prompt
108
106
 
package/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.42.0",
4
- "sha": "3da226d9dabfa6ae49fd9bab96a212e9deeac423",
5
- "shaShort": "3da226d",
3
+ "version": "0.43.0",
4
+ "sha": "8bcc102091d7985fac259eaeafbf2c4c79544e51",
5
+ "shaShort": "8bcc102",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-10-25T19:39:54.582Z"
8
+ "packedAt": "2026-10-28T06:49:51.536Z"
9
9
  }
@@ -5,6 +5,7 @@ import { Type } from "typebox";
5
5
  import { resolveUtilityModel, tryModelChain } from "../../../../lib/ai/model-resolver.js";
6
6
  import { estimateComplexity, complexityToDepth, getBudget, getCalibrationStats, computeCalibrationError, THINK_TYPES, DEFAULT_THINK_TYPE, DEPTH_LEVELS, } from "./think-budget.js";
7
7
  import { criticGate } from "../../../../lib/ai/critic-gate.js";
8
+ import { checkArgumentValues } from "../../../../lib/utils/argument-report.js";
8
9
  import { getExtensionState } from "../../../../lib/state/extension-state.js";
9
10
  import { createLogger } from "../../../../lib/core/logger.js";
10
11
  const log = createLogger("metacognition");
@@ -128,6 +129,14 @@ export function createThinkTool() {
128
129
  description: "Think deeply with structured reasoning before making high-stakes decisions.",
129
130
  promptSnippet: "Think deeply with structured reasoning before decisions",
130
131
  parameters: thinkSchema,
132
+ // pi validates arguments before `execute` is reached, and its own refusal
133
+ // for a guessed enum or a missing field names neither. This hook runs
134
+ // first, inside the same guarded block, and refuses with the values the
135
+ // schema above already declares.
136
+ prepareArguments: (args) => {
137
+ checkArgumentValues("think", thinkSchema, args);
138
+ return args;
139
+ },
131
140
  execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
132
141
  const observation = params.observation ?? params.decision ?? "";
133
142
  const decision = params.decision ?? "";
@@ -3,10 +3,9 @@
3
3
  *
4
4
  * Three concerns:
5
5
  * 1. Model selection: /utility-model (the merged role) opens the
6
- * ModelSelectorComponent UI; /max-power-model is a deprecated alias of it
7
- * and /vision-model is a deprecated alias kept for one release. Model
8
- * resolution is handled by src/lib/ai/model-resolver.ts (used by
9
- * vision/metacognition tools directly).
6
+ * ModelSelectorComponent UI. Model resolution is handled by
7
+ * src/lib/ai/model-resolver.ts (used by vision/metacognition tools
8
+ * directly).
10
9
  * 2. Session manager patches: context_navigate and context_compress tools
11
10
  * need SessionManager methods in --no-session mode.
12
11
  * 3. Context window plumb: the session model reports braid's configured