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.
- package/CHANGELOG.md +1077 -0
- package/README.md +61 -228
- package/TOOLS.md +12 -14
- package/build-info.json +4 -4
- package/dist/extensions/cognitive/metacognition/handlers/think.js +9 -0
- package/dist/extensions/core/polyfill/index.d.ts +3 -4
- package/dist/extensions/core/polyfill/index.js +34 -131
- package/dist/extensions/core/skills-tool/index.js +47 -26
- package/dist/extensions/enforcement/handlers/register-agent-end-api-error.js +13 -0
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +8 -3
- package/dist/extensions/enforcement/session-health.d.ts +52 -4
- package/dist/extensions/enforcement/session-health.js +75 -5
- package/dist/extensions/enforcement/whisper.js +15 -1
- package/dist/extensions/heartbeat/heartbeat-scheduler/index.d.ts +17 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +40 -78
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +2 -1
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +26 -28
- package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.d.ts +62 -31
- package/dist/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.js +130 -55
- package/dist/extensions/manifest.js +6 -0
- package/dist/extensions/memory/context-lifecycle/index.js +11 -10
- package/dist/extensions/memory/context-manager/analysis.d.ts +2 -0
- package/dist/extensions/memory/context-manager/analysis.js +6 -2
- package/dist/extensions/memory/context-manager/handlers/compaction-retry.js +3 -3
- package/dist/extensions/memory/context-manager/handlers/events.js +13 -1
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +10 -14
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +62 -88
- package/dist/extensions/self/path-miss/detect.d.ts +30 -0
- package/dist/extensions/self/path-miss/detect.js +67 -0
- package/dist/extensions/self/path-miss/index.d.ts +33 -0
- package/dist/extensions/self/path-miss/index.js +118 -0
- package/dist/extensions/self/watchdog/engine.d.ts +8 -1
- package/dist/extensions/self/watchdog/engine.js +25 -2
- package/dist/extensions/self/watchdog/index.js +14 -1
- package/dist/lib/ai/llm-call.js +23 -0
- package/dist/lib/ai/model-resolver.d.ts +11 -10
- package/dist/lib/ai/model-resolver.js +16 -19
- package/dist/lib/ai/presend-budget.d.ts +68 -0
- package/dist/lib/ai/presend-budget.js +83 -0
- package/dist/lib/config/braid-settings.d.ts +38 -0
- package/dist/lib/config/braid-settings.js +84 -0
- package/dist/lib/config/per-tool-settings.d.ts +4 -4
- package/dist/lib/config/per-tool-settings.js +4 -4
- package/dist/lib/core/event-names.d.ts +1 -0
- package/dist/lib/core/event-names.js +1 -0
- package/dist/lib/detection/context-tiers.d.ts +18 -5
- package/dist/lib/detection/context-tiers.js +51 -33
- package/dist/lib/detection/context-usage.d.ts +62 -1
- package/dist/lib/detection/context-usage.js +158 -1
- package/dist/lib/errors/llm-error.d.ts +14 -0
- package/dist/lib/errors/llm-error.js +44 -1
- package/dist/lib/state/global-state.d.ts +4 -8
- package/dist/lib/state/global-state.js +11 -28
- package/dist/lib/telemetry/context-heartbeat.d.ts +9 -0
- package/dist/lib/telemetry/context-heartbeat.js +18 -8
- package/dist/lib/utils/argument-report.d.ts +41 -0
- package/dist/lib/utils/argument-report.js +95 -0
- package/dist/lib/utils/wake-gate.d.ts +6 -0
- package/dist/lib/utils/wake-gate.js +52 -4
- package/docs/SETUP.md +7 -6
- package/package.json +11 -13
- package/src/extensions/cognitive/metacognition/handlers/think.ts +9 -0
- package/src/extensions/core/polyfill/index.ts +29 -157
- package/src/extensions/core/skills-tool/index.ts +60 -37
- package/src/extensions/enforcement/AGENTS.md +38 -1
- package/src/extensions/enforcement/handlers/register-agent-end-api-error.ts +13 -0
- package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +8 -2
- package/src/extensions/enforcement/session-health.ts +94 -5
- package/src/extensions/enforcement/whisper.ts +15 -1
- package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +53 -80
- package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +34 -43
- package/src/extensions/heartbeat/heartbeat-scheduler/whisper-batcher.ts +154 -52
- package/src/extensions/manifest.ts +6 -0
- package/src/extensions/memory/AGENTS.md +37 -38
- package/src/extensions/memory/context-lifecycle/index.ts +11 -10
- package/src/extensions/memory/context-manager/analysis.ts +8 -1
- package/src/extensions/memory/context-manager/handlers/compaction-retry.ts +3 -3
- package/src/extensions/memory/context-manager/handlers/events.ts +18 -1
- package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +81 -115
- package/src/extensions/scheduling/timer/AGENTS.md +14 -4
- package/src/extensions/self/AGENTS.md +2 -1
- package/src/extensions/self/path-miss/AGENTS.md +39 -0
- package/src/extensions/self/path-miss/detect.ts +78 -0
- package/src/extensions/self/path-miss/index.ts +135 -0
- package/src/extensions/self/watchdog/AGENTS.md +36 -18
- package/src/extensions/self/watchdog/engine.ts +30 -2
- package/src/extensions/self/watchdog/index.ts +13 -1
- package/src/lib/ai/AGENTS.md +2 -0
- package/src/lib/ai/llm-call.ts +30 -0
- package/src/lib/ai/model-resolver.ts +16 -19
- package/src/lib/ai/presend-budget.ts +117 -0
- package/src/lib/config/braid-settings.ts +125 -0
- package/src/lib/config/per-tool-settings.ts +4 -4
- package/src/lib/core/event-names.ts +1 -0
- package/src/lib/detection/context-tiers.ts +52 -41
- package/src/lib/detection/context-usage.ts +211 -2
- package/src/lib/errors/llm-error.ts +55 -1
- package/src/lib/state/global-state.ts +11 -29
- package/src/lib/telemetry/context-heartbeat.ts +27 -7
- package/src/lib/utils/AGENTS.md +1 -0
- package/src/lib/utils/argument-report.ts +105 -0
- 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
|
[](https://opensource.org/licenses/MIT)
|
|
6
|
-
[](https://www.typescriptlang.org/)
|
|
7
6
|
[](https://github.com/earendil-works/pi)
|
|
8
7
|
|
|
9
|
-
|
|
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
|
-
>
|
|
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
|
-
|
|
22
|
-
|
|
23
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
124
|
-
|
|
125
|
-
|
|
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
|
-
|
|
44
|
+
## Highlights
|
|
134
45
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
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
|
-
|
|
144
|
-
|
|
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
|
-
|
|
180
|
-
|
|
181
|
-
|
|
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
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
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
|
-
|
|
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
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
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
|
|
232
|
-
|
|
|
233
|
-
| [
|
|
234
|
-
| [
|
|
235
|
-
| [
|
|
236
|
-
| [
|
|
237
|
-
| [
|
|
238
|
-
| [
|
|
239
|
-
| [
|
|
240
|
-
| [
|
|
241
|
-
| [
|
|
242
|
-
| [
|
|
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.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.43.0",
|
|
4
|
+
"sha": "8bcc102091d7985fac259eaeafbf2c4c79544e51",
|
|
5
|
+
"shaShort": "8bcc102",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-10-
|
|
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
|
|
7
|
-
*
|
|
8
|
-
*
|
|
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
|