pi-braid 0.40.0 → 0.40.2
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/CONTRIBUTING.md +27 -3
- package/README.md +39 -33
- package/TOOLS.md +27 -3
- package/build-info.json +9 -0
- package/dist/extensions/cognitive/metacognition/handlers/hypothesize.d.ts +9 -0
- package/dist/extensions/cognitive/metacognition/handlers/hypothesize.js +13 -1
- package/dist/extensions/cognitive/metacognition/handlers/verify.js +35 -4
- package/dist/extensions/core/prompt-builder/inspect.js +9 -3
- package/dist/extensions/enforcement/handlers/register-tool-result-formatting.d.ts +1 -1
- package/dist/extensions/enforcement/handlers/register-tool-result-formatting.js +1 -1
- package/dist/extensions/enforcement/handlers/turn-end-handler.js +1 -1
- package/dist/extensions/enforcement/self-state-claims.d.ts +1 -1
- package/dist/extensions/enforcement/self-state-claims.js +3 -2
- package/dist/extensions/manifest.js +2 -2
- package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.d.ts +22 -5
- package/dist/extensions/memory/context-manager/handlers/tool-batch-boundary.js +43 -11
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +174 -50
- package/dist/extensions/memory/context-manager/handlers/tools/context-navigate.js +4 -1
- package/dist/extensions/memory/memory-agent-bridge/memory-store-tool.js +16 -0
- package/dist/extensions/memory/memory-agent-bridge/memory-tool.js +21 -9
- package/dist/extensions/memory/scratchpad/format.js +8 -2
- package/dist/extensions/memory/scratchpad/index.js +11 -2
- package/dist/extensions/memory/session-recall/index.js +19 -6
- package/dist/extensions/memory/three-memory-stores/episodes.d.ts +1 -1
- package/dist/extensions/memory/three-memory-stores/episodes.js +2 -2
- package/dist/extensions/orchestrator/index.js +73 -8
- package/dist/extensions/self/health-maintenance/index.js +112 -9
- package/dist/lib/config/braid-settings.d.ts +21 -0
- package/dist/lib/config/braid-settings.js +36 -0
- package/dist/lib/constants/session-thresholds.d.ts +2 -3
- package/dist/lib/constants/session-thresholds.js +2 -3
- package/dist/lib/enforcement/turn-dedup.d.ts +2 -2
- package/dist/lib/enforcement/turn-dedup.js +2 -2
- package/dist/lib/harness/index.d.ts +1 -1
- package/dist/lib/harness/index.js +1 -1
- package/dist/lib/harness/types.d.ts +1 -1
- package/dist/lib/harness/types.js +1 -1
- package/dist/lib/orchestrator/index.d.ts +2 -2
- package/dist/lib/orchestrator/index.js +1 -1
- package/dist/lib/orchestrator/workers.d.ts +184 -2
- package/dist/lib/orchestrator/workers.js +521 -6
- package/dist/lib/utils/injection-tracker.js +1 -1
- package/docs/BEGINNERS.md +22 -0
- package/docs/CONTEXT-POLICY.md +13 -5
- package/docs/LOCAL_DEV.md +31 -5
- package/docs/ROADMAP.md +10 -7
- package/docs/SETUP.md +86 -42
- package/package.json +11 -8
- package/skills/braid-reference/SKILL.md +23 -23
- package/skills/release-pipeline/SKILL.md +46 -37
- package/skills/subagent-orchestration/SKILL.md +51 -1
- package/src/extensions/cognitive/metacognition/handlers/hypothesize.ts +14 -1
- package/src/extensions/cognitive/metacognition/handlers/verify.ts +39 -5
- package/src/extensions/core/prompt-builder/inspect.ts +10 -3
- package/src/extensions/enforcement/AGENTS.md +25 -19
- package/src/extensions/enforcement/handlers/register-tool-result-formatting.ts +1 -1
- package/src/extensions/enforcement/handlers/turn-end-handler.ts +1 -1
- package/src/extensions/enforcement/self-state-claims.ts +3 -2
- package/src/extensions/heartbeat/heartbeat-scheduler/AGENTS.md +6 -3
- package/src/extensions/manifest.ts +2 -2
- package/src/extensions/memory/AGENTS.md +13 -5
- package/src/extensions/memory/context-manager/handlers/tool-batch-boundary.ts +45 -11
- package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +202 -60
- package/src/extensions/memory/context-manager/handlers/tools/context-navigate.ts +4 -1
- package/src/extensions/memory/memory-agent-bridge/memory-store-tool.ts +16 -0
- package/src/extensions/memory/memory-agent-bridge/memory-tool.ts +22 -9
- package/src/extensions/memory/scratchpad/format.ts +8 -2
- package/src/extensions/memory/scratchpad/index.ts +12 -2
- package/src/extensions/memory/session-recall/index.ts +20 -8
- package/src/extensions/memory/three-memory-stores/episodes.ts +2 -2
- package/src/extensions/orchestrator/index.ts +100 -11
- package/src/extensions/scheduling/timer/AGENTS.md +7 -0
- package/src/extensions/self/health-maintenance/index.ts +143 -14
- package/src/extensions/self/watchdog/AGENTS.md +1 -0
- package/src/lib/AGENTS.md +21 -21
- package/src/lib/config/braid-settings.ts +74 -0
- package/src/lib/constants/session-thresholds.ts +2 -3
- package/src/lib/enforcement/turn-dedup.ts +2 -2
- package/src/lib/harness/AGENTS.md +1 -1
- package/src/lib/harness/index.ts +1 -1
- package/src/lib/harness/types.ts +1 -1
- package/src/lib/orchestrator/index.ts +26 -0
- package/src/lib/orchestrator/workers.ts +705 -7
- package/src/lib/utils/AGENTS.md +1 -1
- package/src/lib/utils/injection-tracker.ts +1 -1
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -16,8 +16,10 @@ For one-time setup, the full install-path catalog, and module toggling see
|
|
|
16
16
|
| git | any | `git --version` |
|
|
17
17
|
| pi | peer-resolved | `which pi && pi --version` |
|
|
18
18
|
|
|
19
|
-
The Node floor is the `engines` field in every workspace manifest;
|
|
20
|
-
|
|
19
|
+
The Node floor is the `engines` field in every workspace manifest; the pi floor
|
|
20
|
+
is the `@earendil-works/*` peer range in the same manifests (a caret on the
|
|
21
|
+
family the seat runs, kept moving by the update pipeline). If this table and a
|
|
22
|
+
manifest ever disagree, trust the manifest.
|
|
21
23
|
|
|
22
24
|
## Monorepo layout
|
|
23
25
|
|
|
@@ -136,6 +138,26 @@ Example: `0.40.0-main.17`. When `package.json` already carries a full
|
|
|
136
138
|
versioned release string (e.g. `0.40.0-main.17`), it is used verbatim instead
|
|
137
139
|
of being double-suffixed.
|
|
138
140
|
|
|
141
|
+
### Provenance in the tarball
|
|
142
|
+
|
|
143
|
+
Every artifact carries `build-info.json` - package name, packed version, commit
|
|
144
|
+
sha and branch, dirty flag, pack time (`scripts/build-info.mjs` is the one
|
|
145
|
+
generator). It is written by each workspace's `prepack` (`scripts/pack-provenance.mjs`),
|
|
146
|
+
expanded into the `files` allowlist of every package, and removed by `postpack`,
|
|
147
|
+
so an `npm publish` pays the same step a plain `npm pack` does and the checkout
|
|
148
|
+
ends as it started. `publish-local` reads git before the version bump and
|
|
149
|
+
writes the record from that read, so the recorded `dirty` is the pre-bump
|
|
150
|
+
state; it carries the `BRAID_PROVENANCE_DEFER` marker into the pack, and the
|
|
151
|
+
prepack step keeps a record only under that marker, because the temporary bump
|
|
152
|
+
would otherwise read as a dirty tree. A record a killed pack left
|
|
153
|
+
behind is regenerated from a fresh read - a matching version and commit are not
|
|
154
|
+
enough to defer to.
|
|
155
|
+
|
|
156
|
+
Read the record to tell two builds of the same version apart, and to check what
|
|
157
|
+
a stranger installed: `sha` plus `dirty == false` is the pair that means the
|
|
158
|
+
tarball is a clean checkout of a named commit - a version string identifies
|
|
159
|
+
neither.
|
|
160
|
+
|
|
139
161
|
## Upstream pi update pipeline
|
|
140
162
|
|
|
141
163
|
`update-pipeline.mjs` codifies the full update run for the pair - the braid
|
|
@@ -151,11 +173,15 @@ npm run release:update:runtime -- --yes # real sequence plus `pi update` (last)
|
|
|
151
173
|
Default mode writes nothing. It resolves the upstream pi version, compares it
|
|
152
174
|
against the repo pins and the local-packages resolution, and prints the target
|
|
153
175
|
version, every pin it would change (file, field, from -> to), the braid version
|
|
154
|
-
bump, the publish commands, the runtime command, and the rollback commands.
|
|
176
|
+
bump, the publish commands, the runtime command, and the rollback commands. The
|
|
177
|
+
host-family peers are pins here too: each workspace manifest declares the
|
|
178
|
+
`@earendil-works/*` peers (and `typebox`) as an explicit caret floor, and the
|
|
179
|
+
plan rewrites those ranges alongside the exact pins, so the floor moves with
|
|
180
|
+
the runtime instead of drifting behind it.
|
|
155
181
|
|
|
156
182
|
The local-packages trap: braid resolves the pi family from
|
|
157
|
-
`~/.pi/agent/local-packages`, and
|
|
158
|
-
|
|
183
|
+
`~/.pi/agent/local-packages`, and those resolutions are not what its peer ranges
|
|
184
|
+
control. Installing a new braid tarball NEVER moves those copies - the
|
|
159
185
|
explicit pins in `local-packages/package.json` must be realigned to the
|
|
160
186
|
upstream version as their own step. That is why `--apply` aligns both sides,
|
|
161
187
|
then republishes braid, and why the runtime update is always last and only runs
|
package/docs/ROADMAP.md
CHANGED
|
@@ -51,16 +51,19 @@ provenance; they are no longer work.
|
|
|
51
51
|
2. **Version-drift cleanup** - RESOLVED: the four workspace packages declare
|
|
52
52
|
the pi peer as `"*"`; the root manifest pins the installed version
|
|
53
53
|
(`package.json`, the `@earendil-works/*` deps).
|
|
54
|
-
3. **Tag-scheme unification** - RESOLVED: two tag roles
|
|
55
|
-
the root `CHANGELOG.md` - iteration tags `v0.40.0-main.N
|
|
56
|
-
`0.40.0-main.N
|
|
54
|
+
3. **Tag-scheme unification** - RESOLVED: two tag roles, one namespace per package, recorded in
|
|
55
|
+
the root `CHANGELOG.md` - core keeps the bare `v` (iteration tags `v0.40.0-main.N`,
|
|
56
|
+
`package.json` `0.40.0-main.N`; release tag `v0.40.0`), every sibling tags as
|
|
57
|
+
`<workspace>-v<version>` (`telegram-v0.1.4`).
|
|
57
58
|
4. **CI private-data gate** - RESOLVED: `check-private-data.mjs` is a CI step
|
|
58
59
|
and scans the whole tree by default (tracked plus untracked); the
|
|
59
60
|
staged-file checks are a local pre-commit convenience.
|
|
60
|
-
5. **Skills pack** - finish validating the
|
|
61
|
+
5. **Skills pack** - finish validating the five skills still marked
|
|
61
62
|
`verdict: UNVALIDATED` (`braid-reference`, `misdirection-audit`,
|
|
62
|
-
`placement-discipline`, `probe-evaluation`, `
|
|
63
|
-
|
|
63
|
+
`placement-discipline`, `probe-evaluation`, `voice-replies`); keep the pack
|
|
64
|
+
catalog fresh as decision rows land. The machine-local `tunnel-control`
|
|
65
|
+
skill is `KEEP` with its v2RayTun arm validated; its Happ and Incy arms
|
|
66
|
+
stay unvalidated until a host installs those clients.
|
|
64
67
|
6. **Extension surface** - ongoing de-bloat of tool/extension counts;
|
|
65
68
|
subagent-RPC hardening. Worker-stats reporting shipped (`list-workers`
|
|
66
69
|
`includeStats`); the orchestrator's metrics-emission half (writing
|
|
@@ -79,7 +82,7 @@ knowledge base.
|
|
|
79
82
|
8. **Small-correctness batch** - RESOLVED: the `prompt_inspect` exclusion is
|
|
80
83
|
pinned by `test-prompt-inspect-exclusion.mjs`; the watchdog tunnel-counter
|
|
81
84
|
canary is a getMe-based liveness probe
|
|
82
|
-
(`telegram/src/lib/inbound-poller.ts`); the
|
|
85
|
+
(`telegram/src/lib/inbound-poller.ts`); the tunnel status description is
|
|
83
86
|
complete in the shipped skill. Effort S.
|
|
84
87
|
9. **Cross-provider fallback on quota death** - RESOLVED: the route-order
|
|
85
88
|
engine walks to the next route, with bounded turn-level fail-back
|
package/docs/SETUP.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
|
|
6
6
|
Complete reference for installing braid, configuring pi to load it, enabling companion skill packs, and troubleshooting common setup issues.
|
|
7
7
|
|
|
8
|
-
> **TL;DR for new users.**
|
|
8
|
+
> **TL;DR for new users.** `pi install npm:pi-braid` → done. See the [Fast start](#fast-start) section.
|
|
9
9
|
|
|
10
10
|
---
|
|
11
11
|
|
|
@@ -33,7 +33,8 @@ Complete reference for installing braid, configuring pi to load it, enabling com
|
|
|
33
33
|
|
|
34
34
|
The Node floor is the `engines` field in `package.json` (mirrored by every
|
|
35
35
|
workspace manifest); if this table and `engines` ever disagree, trust
|
|
36
|
-
`engines`.
|
|
36
|
+
`engines`. git is only needed for the checkout install paths - `pi install`
|
|
37
|
+
from npm needs no checkout at all.
|
|
37
38
|
|
|
38
39
|
**How the pi version resolves.** braid declares the `@earendil-works/pi-*`
|
|
39
40
|
packages as peer dependencies with unconstrained (`*`) ranges. npm resolves
|
|
@@ -47,33 +48,32 @@ version your install resolved to rather than pinning its own;
|
|
|
47
48
|
|
|
48
49
|
## Fast start
|
|
49
50
|
|
|
50
|
-
The
|
|
51
|
+
The minimum, for most users:
|
|
51
52
|
|
|
52
53
|
```bash
|
|
53
|
-
# 1.
|
|
54
|
-
|
|
55
|
-
cd ~/pi-braid && npm install && npm run build
|
|
54
|
+
# 1. Install braid from npm (user-global - applies to every pi session)
|
|
55
|
+
pi install npm:pi-braid
|
|
56
56
|
|
|
57
|
-
# 2.
|
|
58
|
-
cat > ~/.pi/agent/settings.json <<'JSON'
|
|
59
|
-
{
|
|
60
|
-
"packages": [
|
|
61
|
-
"file:~/pi-braid/packages/core"
|
|
62
|
-
]
|
|
63
|
-
}
|
|
64
|
-
JSON
|
|
65
|
-
|
|
66
|
-
# 3. Use pi as normal
|
|
57
|
+
# 2. Use pi as normal
|
|
67
58
|
pi
|
|
68
59
|
```
|
|
69
60
|
|
|
70
61
|
That's it. Now every `pi` invocation will load braid alongside pi-core.
|
|
62
|
+
`pi install` writes the declaration to `~/.pi/agent/settings.json` and installs
|
|
63
|
+
the package under pi's npm directory - no clone, no build step. `pi list` shows
|
|
64
|
+
the configured packages.
|
|
71
65
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
66
|
+
Add-ons, each its own install:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
pi install npm:pi-braid-skills # the on-demand skill pack (per project)
|
|
70
|
+
pi install npm:pi-braid-contrib # standalone tool extensions
|
|
71
|
+
pi install npm:pi-braid-providers # extra LLM providers + the key ring
|
|
72
|
+
pi install npm:pi-braid-telegram # bidirectional Telegram channel
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
To work on braid itself instead, see [§ Install paths](#install-paths) option 2
|
|
76
|
+
(checkout).
|
|
77
77
|
|
|
78
78
|
### Verify
|
|
79
79
|
|
|
@@ -83,9 +83,27 @@ Inside pi, the `<available_skills>` block in the system prompt lists the core sk
|
|
|
83
83
|
|
|
84
84
|
## Install paths
|
|
85
85
|
|
|
86
|
-
### 1.
|
|
86
|
+
### 1. npm install (recommended)
|
|
87
87
|
|
|
88
|
-
|
|
88
|
+
One command, applies to every pi session across all projects:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
pi install npm:pi-braid
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
`pi install` writes the package declaration to `~/.pi/agent/settings.json` and
|
|
95
|
+
installs the package under pi's npm directory (`~/.pi/agent/npm/`), so there is
|
|
96
|
+
no clone and no build step. `pi list` shows the configured packages;
|
|
97
|
+
`pi remove npm:pi-braid` removes this one; `pi update --extensions` reconciles
|
|
98
|
+
package installs (see pi's own package docs for the full command set).
|
|
99
|
+
|
|
100
|
+
Add `--local` (or `-l`) to write the declaration to `<project>/.pi/settings.json`
|
|
101
|
+
instead - the natural fit for the per-project [skill pack](#skills).
|
|
102
|
+
|
|
103
|
+
### 2. User-global checkout (working on braid)
|
|
104
|
+
|
|
105
|
+
For running braid from source - to modify it, or to track `main`. Build the
|
|
106
|
+
checkout, then register the `file:` paths:
|
|
89
107
|
|
|
90
108
|
```bash
|
|
91
109
|
git clone https://github.com/kifirkin/pi-braid.git ~/pi-braid
|
|
@@ -103,7 +121,13 @@ Settings:
|
|
|
103
121
|
}
|
|
104
122
|
```
|
|
105
123
|
|
|
106
|
-
|
|
124
|
+
> **Register `packages/core`, not the repo root.** The root `package.json` has
|
|
125
|
+
> no `pi` field, so `file:~/pi-braid` loads nothing. `packages/core` declares
|
|
126
|
+
> both `pi.extensions` (the braid extensions) and `pi.skills` (the core skill
|
|
127
|
+
> set, which ships inside the package). `packages/skills` carries the on-demand
|
|
128
|
+
> set, registered per project - see [§ Skills](#skills).
|
|
129
|
+
|
|
130
|
+
### 3. Local-packages install (maintainer)
|
|
107
131
|
|
|
108
132
|
The maintainer path: publish braid into `~/.pi/agent/local-packages`, then
|
|
109
133
|
register the installed path. `npm run publish:local` packs `packages/core` into
|
|
@@ -133,10 +157,19 @@ project that wants it - see [§ Skills](#skills).
|
|
|
133
157
|
See [`LOCAL_DEV.md`](LOCAL_DEV.md) for the full publish/link flow, the version
|
|
134
158
|
scheme, and the skills-collision rule.
|
|
135
159
|
|
|
136
|
-
###
|
|
160
|
+
### 4. Project-scoped install (per-project isolation)
|
|
137
161
|
|
|
138
162
|
For projects that should always have braid regardless of the user's global config:
|
|
139
163
|
|
|
164
|
+
```bash
|
|
165
|
+
pi install --local npm:pi-braid
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
`--local` writes the declaration to `<project>/.pi/settings.json`; pi reads
|
|
169
|
+
that file only after project trust is granted.
|
|
170
|
+
|
|
171
|
+
To pin a checkout into the project instead:
|
|
172
|
+
|
|
140
173
|
```bash
|
|
141
174
|
git clone https://github.com/kifirkin/pi-braid.git <project>/.pi/extensions/pi-braid
|
|
142
175
|
cd <project>/.pi/extensions/pi-braid
|
|
@@ -155,19 +188,20 @@ Settings:
|
|
|
155
188
|
|
|
156
189
|
Project-scoped wins on collision with user-global (per pi's resolution order), and a project-scoped `braid.modules` block is not read by braid at all: pi owns that file and applies it only for a trusted project, so pin braid's module state in `~/.pi/agent/settings.json` or toggle it (which persists under `~/.pi/agent/braid/`).
|
|
157
190
|
|
|
158
|
-
###
|
|
191
|
+
### 5. Once-per-session flag (no install)
|
|
159
192
|
|
|
160
193
|
If you don't want to commit braid to either config - useful for trying it on one task:
|
|
161
194
|
|
|
162
195
|
```bash
|
|
163
|
-
pi -e
|
|
196
|
+
pi -e npm:pi-braid # from npm
|
|
197
|
+
pi -e /path/to/pi-braid/packages/core # from a checkout
|
|
164
198
|
```
|
|
165
199
|
|
|
166
|
-
`pi -e <path>` adds an extension
|
|
200
|
+
`pi -e <source|path>` adds an extension for that session only. No clone required; a checkout path must point to a built package (i.e. you've already run `npm install && npm run build`).
|
|
167
201
|
|
|
168
|
-
###
|
|
202
|
+
### 6. Direct path from a clone anywhere
|
|
169
203
|
|
|
170
|
-
Same idea as option
|
|
204
|
+
Same idea as option 2 but the path can be anywhere on disk:
|
|
171
205
|
|
|
172
206
|
```bash
|
|
173
207
|
git clone https://github.com/kifirkin/pi-braid.git /some/other/path
|
|
@@ -183,15 +217,16 @@ cd /some/other/path && npm install && npm run build
|
|
|
183
217
|
|
|
184
218
|
### Choosing an install path
|
|
185
219
|
|
|
186
|
-
| Path | Pros | Cons
|
|
187
|
-
| ------------------------- | ---------------------------------------------------------- |
|
|
188
|
-
| 1.
|
|
189
|
-
| 2.
|
|
190
|
-
| 3.
|
|
191
|
-
| 4.
|
|
192
|
-
| 5.
|
|
220
|
+
| Path | Pros | Cons |
|
|
221
|
+
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------- |
|
|
222
|
+
| 1. npm install | One command, no clone or build; all projects | Needs network access for the install |
|
|
223
|
+
| 2. User-global checkout | Run the source; edit and rebuild in place | You own the build; affects every project |
|
|
224
|
+
| 3. Local-packages install | Versioned tgz or live symlink; matches the maintainer flow | Requires the publish/link step |
|
|
225
|
+
| 4. Project-scoped install | Per-project isolation; version-pinned | A checkout needs a rebuild after `git pull` |
|
|
226
|
+
| 5. `-e` flag | Zero config; try one session | Must be passed every time |
|
|
227
|
+
| 6. Direct path | Same as #2 with arbitrary location | Same |
|
|
193
228
|
|
|
194
|
-
The recommended default is **option 1
|
|
229
|
+
The recommended default is **option 1**. Options 2 and 6 are checkout variants for working on braid or tracking `main`; option 3 is the maintainer flow; option 4 isolates one project; option 5 tries it once.
|
|
195
230
|
|
|
196
231
|
---
|
|
197
232
|
|
|
@@ -205,7 +240,8 @@ braid's skills come in two tiers.
|
|
|
205
240
|
- **On-demand set** - the separate `pi-braid-skills` pack
|
|
206
241
|
(`packages/skills/skills/`: eight `SKILL.md` plus shared content under
|
|
207
242
|
`skills/_shared/`), registered in the settings file of the project that wants
|
|
208
|
-
it
|
|
243
|
+
it (`pi install --local npm:pi-braid-skills`, or a `file:` spec from a
|
|
244
|
+
checkout).
|
|
209
245
|
|
|
210
246
|
Every skill is one `SKILL.md`. The catalog table (one row per skill, with its
|
|
211
247
|
verdict and one-line description, covering both tiers) is
|
|
@@ -221,7 +257,14 @@ Skills in a registered package are listed in the system prompt's
|
|
|
221
257
|
|
|
222
258
|
`pi-braid-skills` and `pi-braid-contrib` are not separate repositories - since
|
|
223
259
|
the monorepo migration they are in-repo workspaces
|
|
224
|
-
(`packages/skills`, `packages/contrib`).
|
|
260
|
+
(`packages/skills`, `packages/contrib`). From npm:
|
|
261
|
+
|
|
262
|
+
```bash
|
|
263
|
+
pi install npm:pi-braid-contrib # the code-only extension workspace
|
|
264
|
+
pi install npm:pi-braid-skills # the on-demand skill set, per project
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
From a checkout, register the workspace paths you want:
|
|
225
268
|
|
|
226
269
|
```jsonc
|
|
227
270
|
// ~/.pi/agent/settings.json
|
|
@@ -260,7 +303,7 @@ The user-global file always exists; the project one is optional and belongs to p
|
|
|
260
303
|
| `braid.modules.<ref>` | boolean | per manifest | Force-enable (`true`) or disable (`false`) an extension id or module group (`memory`, `heartbeat`); a persisted `false` removes a default-enabled extension from the boot set (see [§ Module toggling](#module-toggling)). |
|
|
261
304
|
| `braid.suppressNudges` | boolean | `false` | Silence all cognitive nudges (enforcement whispers, heartbeat suggestions, feedback reminders). |
|
|
262
305
|
| `braid.timezone` | IANA name | `Europe/Moscow` | Time zone for all braid-facing time rendering. |
|
|
263
|
-
| `braid.enforcement.nudgeConfigs.<type>` | object | built-in per-type defaults | Per-nudge-type overrides with fields `baseCooldownMs` (number), `escalateAfter` (number), `deduplicate` (boolean). Types: `validation`, `recordFailure`, `malformed`, `memory`, `scratchpad`, `context`, `sessionSignals`. Invalid entries are logged and dropped.
|
|
306
|
+
| `braid.enforcement.nudgeConfigs.<type>` | object | built-in per-type defaults | Per-nudge-type overrides with leaf shape `braid.enforcement.nudgeConfigs.<type>.<key>`; accepted fields are `baseCooldownMs` (number), `escalateAfter` (number), and `deduplicate` (boolean). Types: `validation`, `recordFailure`, `malformed`, `memory`, `scratchpad`, `context`, `sessionSignals`. Invalid entries are logged and dropped. |
|
|
264
307
|
| `braid.memory.writeGate` | object | gate ON, 20-min cooldown, `enforce` | Review-before-write gate on episode writes; `mode: "warn"` logs decisions and writes anyway; `sites` opts individual writers out. |
|
|
265
308
|
| `braid.timers.maxWakeAttempts` | integer 1..10 | `3` | Redelivery cap for a failed timer wake before it is dropped with a visible notice. |
|
|
266
309
|
| `braid.timers.wakeAlert` | object | ON, `outcomeTimeouts: 2` | Dead-wake page: repeated outcome timeouts / exhausted redeliveries feed the watchdog's wake-delivery condition, which pages the owner out of band (telegram) once per episode plus one recovery line. `mode: "off"` disables the feed (delivery itself is unchanged); `outcomeTimeouts` is an integer 2..10 (1 would page on every normal long turn). |
|
|
@@ -272,6 +315,7 @@ The user-global file always exists; the project one is optional and belongs to p
|
|
|
272
315
|
| `braid.telegram.notifyMaxChars` | positive number | `1200` | Craft target and guard for turn-end notifications. |
|
|
273
316
|
| `braid.telegram.pauseStateFile` | path string | built-in default | Override for the `/telegram` pause-state file path. |
|
|
274
317
|
| `braid.contrib.<name>` | boolean or object | enabled / per-extension | Per-contrib-extension config - see [§ Contrib extensions](#contrib-extensions). |
|
|
318
|
+
| `braid.contrib.<extensionName>.enabled` | string[] | unset | Generic per-extension tool-enable list. The shared helper reads and writes string entries; the `/tools` surface stores its shared list in `braid.contrib._global.enabled`. |
|
|
275
319
|
|
|
276
320
|
### Worked example
|
|
277
321
|
|
|
@@ -305,7 +349,7 @@ The 12 contrib extension names: `browser`, `codebase`, `diff`, `healthcheck`, `n
|
|
|
305
349
|
- `braid.contrib.browserAdvanced: true` - the 7 advanced browser tools (opt-in).
|
|
306
350
|
- `braid.contrib.pathSecurity.block: true` - hard-block dangerous operations instead of soft-warn.
|
|
307
351
|
- `braid.contrib.observatory.record: true` - record session lifecycle events.
|
|
308
|
-
- `braid.contrib.networkMonitor` - `{ profileName, reachabilityUrl, curlTimeoutSecs, disconnectDelayMs, connectTimeoutMs, pollIntervalMs, cooldownMs, autoReconnect, autoWatch, probeIntervalMs, maxAttemptsPerOutage, reconnectCooldownMs }`.
|
|
352
|
+
- `braid.contrib.networkMonitor` - `{ client, profileName, reachabilityUrl, curlTimeoutSecs, disconnectDelayMs, connectTimeoutMs, pollIntervalMs, cooldownMs, autoReconnect, autoWatch, probeIntervalMs, outageThreshold, maxAttemptsPerOutage, reconnectCooldownMs, logFile }`. The watcher toggles only after `outageThreshold` consecutive failed probes (default 3, probes spaced by `probeIntervalMs`); the toggle mechanism comes from the client adapter (app deep links, or the NE profile via `scutil --nc stop|start`), and settings are re-read while the extension runs.
|
|
309
353
|
- `braid.contrib["rate-limiter"]` - `{ rpm, tpm, providers: { <provider>: { rpm, tpm } } }` ceilings; note the hyphenated key (the bundle toggle name for the extension itself is `rateLimiter`).
|
|
310
354
|
- `braid.contrib._global.enabled: [...]` - global tool list managed by the tool-config extension.
|
|
311
355
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.40.
|
|
3
|
+
"version": "0.40.2",
|
|
4
4
|
"description": "Metacognitive extension suite for pi-coding-agent: enforcement, memory, reasoning, self-improvement, and structured cognitive signals.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -19,7 +19,8 @@
|
|
|
19
19
|
"LICENSE",
|
|
20
20
|
"AGENTS.md",
|
|
21
21
|
"CONTRIBUTING.md",
|
|
22
|
-
"TOOLS.md"
|
|
22
|
+
"TOOLS.md",
|
|
23
|
+
"build-info.json"
|
|
23
24
|
],
|
|
24
25
|
"repository": {
|
|
25
26
|
"type": "git",
|
|
@@ -56,11 +57,13 @@
|
|
|
56
57
|
"check:instruction-strings": "node scripts/check-instruction-strings.mjs",
|
|
57
58
|
"check:doc-index": "node scripts/check-doc-index.mjs",
|
|
58
59
|
"check:schema": "node scripts/check-braid-schema.mjs",
|
|
60
|
+
"check:settings-docs": "node scripts/check-settings-doc-coverage.mjs",
|
|
59
61
|
"ci:check": "npm run check:docs && npm run check:doc-drift && npm run check:instruction-strings && npm run check:doc-index && npm run check:deps && npm run check:labels && npx tsc --noEmit && npm test",
|
|
60
62
|
"release:local": "node scripts/publish-local.mjs",
|
|
61
63
|
"publish:local": "node scripts/publish-local.mjs",
|
|
62
64
|
"dev:link": "npm link && cd ~/.pi/agent/local-packages && npm link pi-braid",
|
|
63
|
-
"prepack": "npm run build"
|
|
65
|
+
"prepack": "npm run build && node scripts/pack-provenance.mjs write",
|
|
66
|
+
"postpack": "node scripts/pack-provenance.mjs remove"
|
|
64
67
|
},
|
|
65
68
|
"devDependencies": {
|
|
66
69
|
"@eslint/js": "10.0.1",
|
|
@@ -73,11 +76,11 @@
|
|
|
73
76
|
"typescript-eslint": "8.59.1"
|
|
74
77
|
},
|
|
75
78
|
"peerDependencies": {
|
|
76
|
-
"@earendil-works/pi-agent-core": "
|
|
77
|
-
"@earendil-works/pi-ai": "
|
|
78
|
-
"@earendil-works/pi-coding-agent": "
|
|
79
|
-
"@earendil-works/pi-tui": "
|
|
80
|
-
"typebox": "
|
|
79
|
+
"@earendil-works/pi-agent-core": "^1.2.0",
|
|
80
|
+
"@earendil-works/pi-ai": "^1.2.0",
|
|
81
|
+
"@earendil-works/pi-coding-agent": "^1.2.0",
|
|
82
|
+
"@earendil-works/pi-tui": "^1.2.0",
|
|
83
|
+
"typebox": "^1.1.38"
|
|
81
84
|
},
|
|
82
85
|
"keywords": [
|
|
83
86
|
"pi-package",
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: braid-reference
|
|
3
3
|
description: "Find braid's own documentation: context policy and compaction, timers and wakes, workers and the orchestrator registry, the Telegram channel, prompt and discipline rules, memory stores, the skills catalog, release and install paths, health maintenance, extensions and the polyfill. Use when a question is about braid internals, before editing braid, or when a braid behavior needs its owning doc named instead of guessed."
|
|
4
|
-
validated: 2026-10-
|
|
4
|
+
validated: 2026-10-18
|
|
5
5
|
verdict: KEEP
|
|
6
6
|
---
|
|
7
7
|
|
|
@@ -21,7 +21,7 @@ Braid ships as separate packages, and docs live under each package root. Find th
|
|
|
21
21
|
| `skills` | the on-demand pack: `skills/<name>/SKILL.md`, `README.md`, `AGENTS.md` |
|
|
22
22
|
| `telegram` | `README.md`, `docs/` |
|
|
23
23
|
|
|
24
|
-
This file sits at `<core>/skills/braid-reference/SKILL.md`, so the core root is two levels up. The core skill set ships with the core package; the `skills` package root carries only the on-demand pack; machine-local skills such as `
|
|
24
|
+
This file sits at `<core>/skills/braid-reference/SKILL.md`, so the core root is two levels up. The core skill set ships with the core package; the `skills` package root carries only the on-demand pack; machine-local skills such as `tunnel-control` live in `~/.pi/agent/skills/`.
|
|
25
25
|
|
|
26
26
|
```bash
|
|
27
27
|
# 1. core root — two levels above this SKILL.md
|
|
@@ -40,27 +40,27 @@ In the monorepo the roots are `packages/core`, `packages/skills`, `packages/tele
|
|
|
40
40
|
|
|
41
41
|
Paths below are checkout paths: strip the leading `packages/<name>/` and prepend that package's root. The `Shipped` column says whether the file is in the published tarball (`npm`) or exists only in a checkout (`checkout`).
|
|
42
42
|
|
|
43
|
-
| Topic | Doc
|
|
44
|
-
| --------------------------------------------------------------------------------- |
|
|
45
|
-
| What braid is, install paths, module toggling, storage | `packages/core/README.md`, `packages/core/docs/SETUP.md`
|
|
46
|
-
| First walkthrough: anatomy of an extension, writing one | `packages/core/docs/BEGINNERS.md`
|
|
47
|
-
| Context policy: window, reserve, bands, caps, offload | `packages/core/docs/CONTEXT-POLICY.md`
|
|
48
|
-
| Context map: contexts, owners, seam registry, where state lives | `packages/core/docs/CONTEXT-MAP.md`
|
|
49
|
-
| Context automation: proposals, policy engine, cooldown | `packages/core/src/extensions/memory/context-lifecycle/AGENTS.md`
|
|
50
|
-
| What compaction loses and which guards exist | `packages/core/docs/COMPACTION-LOSS-INVESTIGATION.md`
|
|
51
|
-
| Timers, wakes, wake retry, wake-delivery alerts | `packages/core/src/extensions/scheduling/timer/AGENTS.md`
|
|
52
|
-
| Workers, the `orchestrate` tool, locks, merge verification | `packages/core/skills/subagent-orchestration/SKILL.md`
|
|
53
|
-
| Telegram channel: live update, pause control | `packages/telegram/docs/live-update.md`, `packages/telegram/docs/pause-control.md`
|
|
54
|
-
| Telegram package overview: tools, env vars, components; turn-complete auto-notify | `packages/telegram/README.md`, `packages/telegram/docs/turn-complete-notify.md`
|
|
55
|
-
| System prompt composition, identity, whisper sections | `packages/core/src/extensions/core/prompt-builder/AGENTS.md`
|
|
56
|
-
| Enforcement: whisper cap, dedup, nudges, verification judge | `packages/core/src/extensions/enforcement/AGENTS.md`
|
|
57
|
-
| Memory stores: episodes, semantic, heuristics | `packages/core/src/extensions/memory/three-memory-stores/AGENTS.md`, `packages/core/src/extensions/memory/AGENTS.md`
|
|
58
|
-
| Skills: the core set and the on-demand pack, catalog, adding a skill | `packages/skills/README.md`, `packages/skills/AGENTS.md`
|
|
59
|
-
| Release, publish, install paths, upstream pi updates | `packages/core/skills/release-pipeline/SKILL.md
|
|
60
|
-
| Health maintenance, checkpoints, self-repair | `packages/core/src/extensions/self/health-maintenance/AGENTS.md`
|
|
61
|
-
| Extension loading, manifest, module toggles, the polyfill | `packages/core/AGENTS.md`, `packages/core/src/AGENTS.md`, `packages/core/src/extensions/core/AGENTS.md`
|
|
62
|
-
| Every tool and command braid adds | `packages/core/TOOLS.md`
|
|
63
|
-
| Roadmap (forward-looking) and history | `packages/core/docs/ROADMAP.md`, `packages/core/docs/HISTORY.md`
|
|
43
|
+
| Topic | Doc | Shipped |
|
|
44
|
+
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------- |
|
|
45
|
+
| What braid is, install paths, module toggling, storage | `packages/core/README.md`, `packages/core/docs/SETUP.md` | npm |
|
|
46
|
+
| First walkthrough: anatomy of an extension, writing one | `packages/core/docs/BEGINNERS.md` | npm |
|
|
47
|
+
| Context policy: window, reserve, bands, caps, offload | `packages/core/docs/CONTEXT-POLICY.md` | npm |
|
|
48
|
+
| Context map: contexts, owners, seam registry, where state lives | `packages/core/docs/CONTEXT-MAP.md` | npm |
|
|
49
|
+
| Context automation: proposals, policy engine, cooldown | `packages/core/src/extensions/memory/context-lifecycle/AGENTS.md` | npm |
|
|
50
|
+
| What compaction loses and which guards exist | `packages/core/docs/COMPACTION-LOSS-INVESTIGATION.md` | npm |
|
|
51
|
+
| Timers, wakes, wake retry, wake-delivery alerts | `packages/core/src/extensions/scheduling/timer/AGENTS.md` | npm |
|
|
52
|
+
| Workers, the `orchestrate` tool, locks, merge verification | `packages/core/skills/subagent-orchestration/SKILL.md` | npm |
|
|
53
|
+
| Telegram channel: live update, pause control | `packages/telegram/docs/live-update.md`, `packages/telegram/docs/pause-control.md` | npm |
|
|
54
|
+
| Telegram package overview: tools, env vars, components; turn-complete auto-notify | `packages/telegram/README.md`, `packages/telegram/docs/turn-complete-notify.md` | npm |
|
|
55
|
+
| System prompt composition, identity, whisper sections | `packages/core/src/extensions/core/prompt-builder/AGENTS.md` | npm |
|
|
56
|
+
| Enforcement: whisper cap, dedup, nudges, verification judge | `packages/core/src/extensions/enforcement/AGENTS.md` | npm |
|
|
57
|
+
| Memory stores: episodes, semantic, heuristics | `packages/core/src/extensions/memory/three-memory-stores/AGENTS.md`, `packages/core/src/extensions/memory/AGENTS.md` | npm |
|
|
58
|
+
| Skills: the core set and the on-demand pack, catalog, adding a skill | `packages/skills/README.md`, `packages/skills/AGENTS.md` | npm |
|
|
59
|
+
| Release, publish, install paths, upstream pi updates | `packages/core/skills/release-pipeline/SKILL.md` (local release and remote npm publication through GitHub Actions OIDC) | npm |
|
|
60
|
+
| Health maintenance, checkpoints, self-repair | `packages/core/src/extensions/self/health-maintenance/AGENTS.md` | npm |
|
|
61
|
+
| Extension loading, manifest, module toggles, the polyfill | `packages/core/AGENTS.md`, `packages/core/src/AGENTS.md`, `packages/core/src/extensions/core/AGENTS.md` | npm |
|
|
62
|
+
| Every tool and command braid adds | `packages/core/TOOLS.md` | npm |
|
|
63
|
+
| Roadmap (forward-looking) and history | `packages/core/docs/ROADMAP.md`, `packages/core/docs/HISTORY.md` | npm |
|
|
64
64
|
|
|
65
65
|
Related skills in the core set: `dox` (the AGENTS.md tree), `placement-discipline` (which layer owns a fact), `release-pipeline` (the local publish flow), `skill-usage` (adoption measurement), `pi-reference` (pi core, the layer braid extends).
|
|
66
66
|
|
|
@@ -1,21 +1,21 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: release-pipeline
|
|
3
|
-
description: "
|
|
3
|
+
description: "Release pipeline for braid packages: local builds, packing, installs, and verification; remote npm publication through GitHub Actions OIDC."
|
|
4
4
|
trigger: "releasing packages, npm publish, local package install, building packages, packing npm packages, package verification"
|
|
5
|
-
validated: 2026-
|
|
5
|
+
validated: 2026-10-18
|
|
6
6
|
verdict: IMPROVE
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# Release Pipeline
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
Local package release and install flow, with remote npm publication through GitHub Actions OIDC.
|
|
12
12
|
|
|
13
13
|
## Principles
|
|
14
14
|
|
|
15
15
|
1. **Isolation** - workers operate on git worktrees, never the live repo
|
|
16
16
|
2. **Hygiene** - worktrees and .tgz files are cleaned up after release
|
|
17
17
|
3. **Traceability** - every release has a version, commit, and timestamp
|
|
18
|
-
4. **
|
|
18
|
+
4. **Separation** - local package installs use this pipeline; npm publication runs in a separate GitHub Actions OIDC workflow
|
|
19
19
|
|
|
20
20
|
## Worktree Management
|
|
21
21
|
|
|
@@ -48,12 +48,9 @@ clean apart from a symlinked `node_modules` - and remove any resurrected path (`
|
|
|
48
48
|
|
|
49
49
|
### Step 1: Build
|
|
50
50
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
Verify: `npm run typecheck` (or `npx tsc --noEmit`).
|
|
51
|
+
From `<package-dir>`, run `npm run build` when the package defines a build
|
|
52
|
+
script. Run `npm run typecheck` or `npx tsc --noEmit` when the package has a
|
|
53
|
+
TypeScript check.
|
|
57
54
|
|
|
58
55
|
### Step 2: Pack
|
|
59
56
|
|
|
@@ -144,25 +141,30 @@ Rules the script enforces:
|
|
|
144
141
|
`npm --prefix <global-prefix> install -g @earendil-works/pi-coding-agent@<version>`.
|
|
145
142
|
- **Publish, do not repack.** `--apply` composes `publish-local.mjs` per braid
|
|
146
143
|
package; it never packs inline.
|
|
147
|
-
- **Verify
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
144
|
+
- **Verify does not start a pi session.** `--verify` reads installed package
|
|
145
|
+
files and settings, evaluates every item, and exits non-zero if any item
|
|
146
|
+
fails. It resolves the current upstream version with `npm view`; live-session
|
|
147
|
+
checks remain a human checklist. It is standalone and refuses
|
|
148
|
+
`--apply`/`--runtime`.
|
|
151
149
|
|
|
152
150
|
## Remote Publication
|
|
153
151
|
|
|
154
|
-
|
|
152
|
+
Remote publication uses `.github/workflows/publish.yml`, separate from the
|
|
153
|
+
local install path. A bare core release tag (`v<core version>`) runs the
|
|
154
|
+
workflow. To publish one sibling package, dispatch it from `main` with
|
|
155
|
+
`only=<package>`; sibling tags do not run this release workflow, and iteration
|
|
156
|
+
tags are refused by its job condition. A release-tag run publishes each stable
|
|
157
|
+
workspace version not already present on npm through trusted publishing (OIDC);
|
|
158
|
+
the workflow uses no npm token.
|
|
155
159
|
|
|
156
|
-
|
|
157
|
-
npm publish
|
|
158
|
-
```
|
|
160
|
+
Preparation:
|
|
159
161
|
|
|
160
|
-
|
|
162
|
+
- Commit the intended stable package versions. Refresh `package-lock.json` as
|
|
163
|
+
a release convention, as described in `CONTRIBUTING.md`.
|
|
164
|
+
- Configure trusted publishing for the package on npmjs.com.
|
|
161
165
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
- CHANGELOG.md updated
|
|
165
|
-
- Git tag created (`git tag v<version>`)
|
|
166
|
+
Local CLI publishing is not a fallback: `npm publish` needs 2FA, and this
|
|
167
|
+
account's passkey second factor leaves the CLI OTP prompt nothing to answer.
|
|
166
168
|
|
|
167
169
|
## Disk Hygiene
|
|
168
170
|
|
|
@@ -175,17 +177,24 @@ After release:
|
|
|
175
177
|
|
|
176
178
|
## Version Convention
|
|
177
179
|
|
|
178
|
-
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
180
|
+
- `publish-local.mjs` normally derives `<base>-<branch>.<iteration>` from the
|
|
181
|
+
workspace version; if that version already carries a prerelease, it uses it
|
|
182
|
+
verbatim. The script restores the original manifest after packing.
|
|
183
|
+
- Commit stable package versions before remote npm publication. Local snapshots
|
|
184
|
+
use the derived iteration version instead.
|
|
185
|
+
- Use `npm version` for semver bumps in the target workspace.
|
|
186
|
+
- A bare core release tag (`v<core version>`) runs the publish workflow. Publish
|
|
187
|
+
a sibling package by dispatching from `main` with `only=<package>`.
|
|
188
|
+
`tag-prerelease.mjs` creates package-scoped iteration tags; they do not
|
|
189
|
+
publish.
|
|
190
|
+
|
|
191
|
+
## Timer and Artifact Locations
|
|
192
|
+
|
|
193
|
+
Timer files are project-scoped at
|
|
194
|
+
`<braid-home>/projects/<canonical-sanitized-cwd>/pending-timers.jsonl`; the
|
|
195
|
+
default braid home is `~/.pi/agent/braid`, and `BRAID_HOME` can override it.
|
|
196
|
+
|
|
197
|
+
`publish-local.mjs` creates a tarball in the workspace directory, copies it
|
|
198
|
+
to `~/.pi/agent/local-packages` (or `LOCAL_PKG`), then removes the workspace
|
|
199
|
+
copy. The installed package and retained tarball use the destination, not the
|
|
200
|
+
project CWD.
|