pi-braid 0.42.1 → 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 +71 -0
- package/README.md +61 -228
- package/TOOLS.md +12 -14
- package/build-info.json +4 -4
- package/dist/extensions/core/polyfill/index.d.ts +3 -4
- package/dist/extensions/core/polyfill/index.js +34 -131
- 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/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/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/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/wake-gate.d.ts +6 -0
- package/dist/lib/utils/wake-gate.js +52 -4
- package/docs/SETUP.md +7 -6
- package/package.json +8 -11
- package/src/extensions/core/polyfill/index.ts +29 -157
- 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/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/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/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/wake-gate.ts +59 -4
package/CHANGELOG.md
CHANGED
|
@@ -43,6 +43,77 @@ reader-facing record; the tag scheme above applies unchanged.
|
|
|
43
43
|
|
|
44
44
|
---
|
|
45
45
|
|
|
46
|
+
## Core — 0.43.0 (2026-10-28: a long session stops killing itself, and the pages stop describing what is not there)
|
|
47
|
+
|
|
48
|
+
One release for everything after `0.42.1`. The versions between were base bumps: they were never tagged, so no reader
|
|
49
|
+
could install them, and their sections are folded here.
|
|
50
|
+
|
|
51
|
+
### Core
|
|
52
|
+
|
|
53
|
+
- **The context meter measures what the provider counts.** It reported "the tokens that will be sent on the next
|
|
54
|
+
request" while computing a character walk at four characters per token over a partial span. A live session read 51%
|
|
55
|
+
while the wire carried 1,147,002 tokens against a 1,048,576 window, so the arm thresholds, the 0.90W backstop and the
|
|
56
|
+
emergency offload were all reading a number that could not reach them. The estimate now calibrates against the
|
|
57
|
+
provider's own usage (median of the last eight pairs, ratio clamped) and every rendered number carries its
|
|
58
|
+
provenance, `measured` or `estimated`. The measured error: 78.9% of the branch's mass outside the walk, 2.55
|
|
59
|
+
characters per token against the assumed 4.00, and 14 image blocks counted as zero.
|
|
60
|
+
- **A request that cannot fit is refused before it is sent.** `presend-budget` compares the calibrated payload plus the
|
|
61
|
+
requested output budget against the resolved window and refuses with one line naming the numbers, the window, the
|
|
62
|
+
overage and the remedy. It runs the chunked compaction once, re-measures, and only then allows the send. A
|
|
63
|
+
context-length 400 is classified as request-shape and is never retried as transient.
|
|
64
|
+
- **The compaction queue drains only where the loop cannot dispatch.** The `turn_end` drain and the arm-time fire are
|
|
65
|
+
gone; arming only queues, and `agent_settled` is the unconditional drain. Below the 0.90W backstop a queued steer at
|
|
66
|
+
a turn boundary started a request the armed drain then aborted, which the session reported as an API error. The
|
|
67
|
+
0.90W backstop survives as the one deliberate exception, because a run kept alive by continuous steers never settles
|
|
68
|
+
and overflow costs more than the turn the deliberate abort can lose.
|
|
69
|
+
- **A self-started wake stops feeding a failing route.** A monotonic per-session counter of consecutive run-ending
|
|
70
|
+
provider errors is asked through the existing turn-start predicate; above the threshold, timer wakes, watchdog
|
|
71
|
+
escalations and waking whispers are demoted to non-waking delivery. The content still arrives and one line announces
|
|
72
|
+
the episode. Five existing signals re-open the gate, plus a floor sparser than the observed retry cadence.
|
|
73
|
+
- **One delivery prints one snapshot.** A heartbeat could print a configured tier boundary (`Context at 30%`) beside a
|
|
74
|
+
live measurement, and an agent then repeated the contradiction in its own reasoning. A delivery now carries a single
|
|
75
|
+
measurement taken at delivery, its label is that measurement, percentages carry the meter's provenance word, numbers
|
|
76
|
+
that change no decision are dropped, and a collapsed family is re-labelled from the newest arrival rather than the
|
|
77
|
+
first.
|
|
78
|
+
- **The publish step compares the artifact it served.** `pack-compare` unpacks the checkout's pack and the registry
|
|
79
|
+
tarball for the same version and reports what differs. The step reads the registry, never a rendering surface: its
|
|
80
|
+
first version inferred from the job's step summary and reported success while comparing nothing.
|
|
81
|
+
- **Gates report the population they actually scanned.** `check-placement` and `check-doc-links` skipped their own
|
|
82
|
+
file, so the first printed `1017 of 1018` and a worker transcribing that line into gate evidence was refused by the
|
|
83
|
+
merge rule. Both now count their own file and list it as a documented exclusion from matching, and a fixture asserts
|
|
84
|
+
the two numbers stay equal.
|
|
85
|
+
|
|
86
|
+
### The package surface
|
|
87
|
+
|
|
88
|
+
- **The skills README describes the skills that ship.** It documented a 31-row catalogue while the package carries
|
|
89
|
+
eight, so most of the page described another package's files and one row described a skill that exists in no tree.
|
|
90
|
+
The page now has one row per shipped skill, taken from each `SKILL.md`'s own trigger, and it names which three carry
|
|
91
|
+
`status: deprecated` and where their successors live.
|
|
92
|
+
- **Descriptions say what a reader can do.** "Standalone", "markdown-only" and "no runtime dependencies" are true of
|
|
93
|
+
every package in the catalogue and useful to no reader; the private gateway no longer appears in published metadata.
|
|
94
|
+
Internal material left the public pages rather than being softened in place.
|
|
95
|
+
- **Every count on the surface is derived.** Where a README states a number, the report carries the command that
|
|
96
|
+
produced it.
|
|
97
|
+
- **Two skills could not fire, and now they can.** `adversarial-engagement` and `socratic-irony` carried trigger tails
|
|
98
|
+
of 222 and 212 characters against the trigger parser's 200-character cutoff, so both loaded with zero triggers.
|
|
99
|
+
Rewritten, they parse ten and six phrases, and a pack fixture fails on a description that cannot fire or on a tool
|
|
100
|
+
name no installed package declares.
|
|
101
|
+
- **`design-system` uses the CLI it had called aspirational.** `@google/design.md` is published; the skill had been
|
|
102
|
+
building a manual workaround around its supposed absence.
|
|
103
|
+
|
|
104
|
+
### Removed
|
|
105
|
+
|
|
106
|
+
- **`/vision-model` and `/max-power-model` are removed.** Both shipped with a one-release warning and two have passed
|
|
107
|
+
since. Image analysis resolves through the current model when it accepts images, else the merged role's first
|
|
108
|
+
image-capable entry, and `model-resolver` no longer reads the vision key at all.
|
|
109
|
+
|
|
110
|
+
### Also in this line
|
|
111
|
+
|
|
112
|
+
- **`SETUP.md` told readers the pi peers were unconstrained.** All five manifests carry `^1.2.0`; a wildcard accepts
|
|
113
|
+
any pi, a caret says which SDK surface the extension was written against.
|
|
114
|
+
- **A test fixture no longer hangs instead of reporting.** `fleet/test-drain-atomicity` attached its exit listener after
|
|
115
|
+
the kill, so a child that finished first left the promise unsettled and node exited 13 with every assertion green.
|
|
116
|
+
|
|
46
117
|
## Core — 0.42.1 (2026-10-27: the package carries its changelog, a publish checks what it served, and two measured friction classes lose their cause)
|
|
47
118
|
|
|
48
119
|
### Core
|
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
|
}
|
|
@@ -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
|