pi-braid 0.40.6 → 0.41.1
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/README.md +13 -1
- package/build-info.json +4 -4
- package/docs/CONTEXT-MAP.md +1 -1
- package/docs/FLEET.md +134 -0
- package/package.json +5 -1
- package/scripts/fleet/cli.mjs +540 -0
- package/scripts/fleet/driver-rpc.mjs +376 -0
- package/scripts/fleet/driver-scripted.mjs +239 -0
- package/scripts/fleet/journal.mjs +1124 -0
- package/scripts/fleet/procs.mjs +76 -0
- package/scripts/fleet/supervisor.mjs +1649 -0
- package/scripts/fleet/tool-guard.mjs +467 -0
- package/skills/release-pipeline/SKILL.md +20 -4
package/README.md
CHANGED
|
@@ -26,6 +26,13 @@ install: `pi install npm:pi-braid-skills`,
|
|
|
26
26
|
`pi install npm:pi-braid-contrib`, `pi install npm:pi-braid-providers`,
|
|
27
27
|
`pi install npm:pi-braid-telegram`.
|
|
28
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
|
+
|
|
29
36
|
To enable braid for one project only, or to use all five workspaces, see
|
|
30
37
|
[docs/SETUP.md](docs/SETUP.md) § Install paths. For the full setup reference
|
|
31
38
|
(per-project installs, skills, module toggles, troubleshooting) see
|
|
@@ -123,7 +130,7 @@ session start
|
|
|
123
130
|
reads across the stores; `session` reads across past sessions. Deep source:
|
|
124
131
|
[`src/extensions/memory/AGENTS.md`](src/extensions/memory/AGENTS.md).
|
|
125
132
|
|
|
126
|
-
### A worker
|
|
133
|
+
### A worker pool
|
|
127
134
|
|
|
128
135
|
`orchestrate` coordinates parallel agent workers: a per-project worker registry
|
|
129
136
|
with admission and lifecycle, one branch per worker, file locks, conflict
|
|
@@ -133,6 +140,10 @@ procedure is the [`subagent-orchestration`](skills/subagent-orchestration/SKILL.
|
|
|
133
140
|
skill; the registry is
|
|
134
141
|
[`src/extensions/orchestrator/index.ts`](src/extensions/orchestrator/index.ts).
|
|
135
142
|
|
|
143
|
+
This is a pool of workers, not a fleet: the package's `pi-braid-fleet` command,
|
|
144
|
+
described in Install above, is the supervisor fleet, and the two share no code,
|
|
145
|
+
journal or lifecycle.
|
|
146
|
+
|
|
136
147
|
### Context lifecycle
|
|
137
148
|
|
|
138
149
|
braid manages its own window: usage bands fire pruning, archiving and
|
|
@@ -223,6 +234,7 @@ time (`find packages/skills/skills -name SKILL.md | wc -l` counts the pack).
|
|
|
223
234
|
| [`docs/SETUP.md`](docs/SETUP.md) | **Full setup reference**, install paths, troubleshooting |
|
|
224
235
|
| [`TOOLS.md`](TOOLS.md) | Tool catalog: registered tools, pi builtins, cold tools |
|
|
225
236
|
| [`docs/CONTEXT-POLICY.md`](docs/CONTEXT-POLICY.md) | Window, usage bands, compaction reserve, caps, offload, archiving |
|
|
237
|
+
| [`docs/FLEET.md`](docs/FLEET.md) | The `pi-braid-fleet` supervisor fleet: commands, tiers, journal |
|
|
226
238
|
| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Active roadmap + shipped milestones + open themes |
|
|
227
239
|
| [`README.md`](README.md) | This overview |
|
|
228
240
|
| [`AGENTS.md`](AGENTS.md) | Repository structure, DOX contract, conventions |
|
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.41.1",
|
|
4
|
+
"sha": "a585e2e45dac38920c4269a23409355da8266c2d",
|
|
5
|
+
"shaShort": "a585e2e",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-10-
|
|
8
|
+
"packedAt": "2026-10-25T06:35:32.607Z"
|
|
9
9
|
}
|
package/docs/CONTEXT-MAP.md
CHANGED
|
@@ -161,7 +161,7 @@ produced it.
|
|
|
161
161
|
|
|
162
162
|
| Field | Aggregate / registry | path:line | Written by | Why durable |
|
|
163
163
|
| ------------------------ | --------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
164
|
-
| `spawnedAt` | worker entry, `workers.json` | `src/lib/orchestrator/workers.ts:90` (decl), `:630` (write) | `registerWorker` | admission time is the left end of the spawn-to-result latency the
|
|
164
|
+
| `spawnedAt` | worker entry, `workers.json` | `src/lib/orchestrator/workers.ts:90` (decl), `:630` (write) | `registerWorker` | admission time is the left end of the spawn-to-result latency the worker registry reports (`workers.ts:1166`) |
|
|
165
165
|
| `resultAt` | worker entry | `workers.ts:92` (decl), `:703` and `:736` (writes) | `recordWorkerMerge`, `closeWorker` | a successor session computes latency from the row after the writer is gone (`workers.ts:1166-1168`) |
|
|
166
166
|
| `mergedAt` | worker entry | `workers.ts:96` (decl), `:701` (write) | `recordWorkerMerge` | the merge mark is verdict evidence, and the row outlives the merged branch (`workers.ts:1029`) |
|
|
167
167
|
| `closedAt` | worker entry | `workers.ts:97` (decl), `:734` (write) | `closeWorker` | terminal state: a closed row is no obstacle to admission (`workers.ts:539`) and is hidden from `list-workers` unless asked (`src/extensions/orchestrator/index.ts:883`) |
|
package/docs/FLEET.md
ADDED
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
<!-- status: current -->
|
|
2
|
+
|
|
3
|
+
# The supervisor fleet (`pi-braid-fleet`)
|
|
4
|
+
|
|
5
|
+
`pi-braid-fleet` is the one command this package installs. It operates a
|
|
6
|
+
**supervisor fleet**: a single supervisor process, with no model of its own,
|
|
7
|
+
keeping a cap of local node sessions running against one SQLite journal in a
|
|
8
|
+
fleet root.
|
|
9
|
+
|
|
10
|
+
The word "fleet" names this subsystem and nothing else. The worker registry that
|
|
11
|
+
`orchestrate` keeps for parallel agents is a pool of workers with its own
|
|
12
|
+
registry and lifecycle; the [README](../README.md) calls it a worker pool, and
|
|
13
|
+
the two share no journal, no code and no state.
|
|
14
|
+
|
|
15
|
+
## Install and help
|
|
16
|
+
|
|
17
|
+
`npm install pi-braid` puts the command at `node_modules/.bin/pi-braid-fleet`.
|
|
18
|
+
`pi-braid-fleet --help` prints the command list on stdout and exits 0; a bare
|
|
19
|
+
`pi-braid-fleet` does the same. An unknown command prints the usage on stderr
|
|
20
|
+
and exits 2, so a script can tell a refusal from an answer.
|
|
21
|
+
|
|
22
|
+
## The four commands
|
|
23
|
+
|
|
24
|
+
| Command | What it does |
|
|
25
|
+
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
26
|
+
| `spawn <parent\|-> <charter> [flags]` | Registers a node from a charter file and makes sure one supervisor runs. `-` means no parent. |
|
|
27
|
+
| `status [--json]` | The fleet as the journal and the process table report it: supervisors, nodes, open asks, fences, resident memory. `--json` is the whole record. |
|
|
28
|
+
| `inject <node> <text> [--token <ask-token>]` | Delivers a message to a node. With `--token` it answers the ask that token belongs to. |
|
|
29
|
+
| `ask <node> <question> [--default A] [--priority N] [--ttl-seconds N]` | Records a question with a token, a default answer and a deadline; the answer path is `inject --token`. |
|
|
30
|
+
|
|
31
|
+
Every command takes `--root <fleet-root>`, defaulting to `$PI_FLEET_ROOT` or
|
|
32
|
+
`<cwd>/.fleet`. The journal lives in that root, so two commands are looking at
|
|
33
|
+
the same fleet exactly when they were given the same root.
|
|
34
|
+
|
|
35
|
+
`spawn` forwards `--cap`, `--model`, `--pi-bin`, `--extension`,
|
|
36
|
+
`--supervisor-driver` and `--idle-exit-ms` to the supervisor it starts. A
|
|
37
|
+
supervisor that is already answering keeps the flags it was started with, and
|
|
38
|
+
`spawn` says so in its output instead of pretending the flags took. `--cap 0`
|
|
39
|
+
admits nodes and drives none of them, which is how a fleet can be populated
|
|
40
|
+
without a model.
|
|
41
|
+
|
|
42
|
+
## Delivery tiers
|
|
43
|
+
|
|
44
|
+
A queued message is never reported as a delivery. `inject` prints which tier it
|
|
45
|
+
used, and the inbox row records it:
|
|
46
|
+
|
|
47
|
+
- **A** - a turn was in flight and the child ran the steered text inside that
|
|
48
|
+
turn (`delivered_tier = 'A'`). Written only from the driver's own
|
|
49
|
+
`steer_delivered` event, because pi's acknowledgement means the text was
|
|
50
|
+
queued, not delivered.
|
|
51
|
+
- **B** - the supervisor was up but the node was not streaming, so the message
|
|
52
|
+
waits for the node's next turn.
|
|
53
|
+
- **C** - no supervisor was running; the message waits in the journal for the
|
|
54
|
+
next supervisor that drives the node.
|
|
55
|
+
|
|
56
|
+
A turn retires a message only when the section the turn appends carries it: the
|
|
57
|
+
supervisor takes the ids from that section, and checks them against the prompt
|
|
58
|
+
before it writes anything. A charter that repeats the operator's instruction
|
|
59
|
+
word for word is therefore not read as a delivery - the coincidence is the one
|
|
60
|
+
thing this cannot be - and the message keeps waiting for a turn that really
|
|
61
|
+
carries it.
|
|
62
|
+
|
|
63
|
+
When a turn cannot carry a message at all (the node is done, or failed at its
|
|
64
|
+
attempt bound), the supervisor stamps the row `undeliverable` and `status`
|
|
65
|
+
counts it, rather than leaving a promise nobody keeps.
|
|
66
|
+
|
|
67
|
+
## Leases
|
|
68
|
+
|
|
69
|
+
A node is leased to one supervisor epoch at a time, so two supervisors never
|
|
70
|
+
drive the same node. The lease is held for as long as its owner answers for it:
|
|
71
|
+
exclusivity is the owner's liveness, not a clock, and reconciliation ends a
|
|
72
|
+
predecessor's lease only once that owner is gone. A supervisor whose turn runs
|
|
73
|
+
long - a tick under write contention can - keeps its node, which is the property
|
|
74
|
+
a wall-clock expiry would have broken.
|
|
75
|
+
|
|
76
|
+
The lease row therefore carries an `expires_at` column that means nothing. It is
|
|
77
|
+
kept because the build that shipped schema version 1 writes it by name, so a
|
|
78
|
+
store without it is a store that build cannot open; this build neither reads nor
|
|
79
|
+
writes it, and a store from the previous version has the column relaxed to
|
|
80
|
+
nullable with its stale values cleared the first time it is opened here. Read no
|
|
81
|
+
expiry into it.
|
|
82
|
+
|
|
83
|
+
## Asks and deadlines
|
|
84
|
+
|
|
85
|
+
An ask is a question a human can answer, with a deadline and a default. When the
|
|
86
|
+
deadline passes, the drain answers the ask from its own default and queues that
|
|
87
|
+
default as an ordinary message, so the node moves again. The claim and the queue
|
|
88
|
+
are one transaction: a supervisor killed between them leaves either both or
|
|
89
|
+
neither, and the drain is what a restart runs to recover.
|
|
90
|
+
|
|
91
|
+
Two supervisors may drain the same root: the claim is a conditional update, so
|
|
92
|
+
each overdue ask is answered exactly once and queued exactly once. If the store's
|
|
93
|
+
write lock is held by someone else, the drain waits and retries; a pass that
|
|
94
|
+
cannot finish is recorded as `store_deferred` (with the pass's name, the
|
|
95
|
+
attempts, the wait and the error) and only reported, never thrown at the
|
|
96
|
+
process. Because the store is exactly what cannot take that record, it is also
|
|
97
|
+
written to `<fleet-root>/store-deferred.json` while the lock is held and moved
|
|
98
|
+
into the journal by the first pass that gets through, so a supervisor killed with
|
|
99
|
+
the fact in hand still leaves it where `status` reads it. `status` prints both
|
|
100
|
+
facts when they exist.
|
|
101
|
+
|
|
102
|
+
## The journal
|
|
103
|
+
|
|
104
|
+
One file per fleet root, `<fleet-root>/fleet.sqlite`, in WAL mode with
|
|
105
|
+
`synchronous = FULL`. The tables, their columns, the invariants they hold and the
|
|
106
|
+
failure each column prevents are documented where they are defined -
|
|
107
|
+
[`../scripts/fleet/journal.mjs`](../scripts/fleet/journal.mjs) - and this page
|
|
108
|
+
does not restate them. Read them there before writing to a journal by hand.
|
|
109
|
+
|
|
110
|
+
The store records the schema version that wrote it. Opening a store that records
|
|
111
|
+
a version above the running build's is refused with one sentence naming both
|
|
112
|
+
numbers, rather than opened and left to fail inside a statement: that store's
|
|
113
|
+
shape belongs to a newer build, and the way forward is that build or a new root.
|
|
114
|
+
Opening an older store migrates it and records the new version, and the previous
|
|
115
|
+
build keeps its access: a rollback can open and write a store this build created,
|
|
116
|
+
because the column it needs was kept rather than dropped.
|
|
117
|
+
|
|
118
|
+
## Where the code is
|
|
119
|
+
|
|
120
|
+
| File | What it owns |
|
|
121
|
+
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
|
|
122
|
+
| [`../scripts/fleet/cli.mjs`](../scripts/fleet/cli.mjs) | The four commands, argv, the help text, the tier reporting. |
|
|
123
|
+
| [`../scripts/fleet/journal.mjs`](../scripts/fleet/journal.mjs) | The schema, the claim, the transaction, the busy timeout. |
|
|
124
|
+
| [`../scripts/fleet/supervisor.mjs`](../scripts/fleet/supervisor.mjs) | The loop, reconciliation, the drain, leases, the control socket. |
|
|
125
|
+
| [`../scripts/fleet/driver-rpc.mjs`](../scripts/fleet/driver-rpc.mjs) | The driver that runs a node through a real pi child. |
|
|
126
|
+
| [`../scripts/fleet/driver-scripted.mjs`](../scripts/fleet/driver-scripted.mjs) | The deterministic driver the crash drill uses. |
|
|
127
|
+
| [`../scripts/fleet/tool-guard.mjs`](../scripts/fleet/tool-guard.mjs) | The pre-execution guard that refuses a repeated effect on resume. |
|
|
128
|
+
| [`../scripts/fleet/procs.mjs`](../scripts/fleet/procs.mjs) | Process liveness and resident memory, read from the kernel. |
|
|
129
|
+
|
|
130
|
+
The guarantee the supervisor is built around is narrower than "it resumes": no
|
|
131
|
+
completed effect is repeated and no node is silently lost, across a crash. The
|
|
132
|
+
tests that hold it are in
|
|
133
|
+
[`../test/runtime/fleet/`](../test/runtime/fleet/), and the crash drill is
|
|
134
|
+
[`../test/runtime/fleet/drill.mjs`](../test/runtime/fleet/drill.mjs).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.41.1",
|
|
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",
|
|
@@ -9,12 +9,16 @@
|
|
|
9
9
|
".": "./dist/index.js",
|
|
10
10
|
"./lib": "./dist/lib/public.js"
|
|
11
11
|
},
|
|
12
|
+
"bin": {
|
|
13
|
+
"pi-braid-fleet": "./scripts/fleet/cli.mjs"
|
|
14
|
+
},
|
|
12
15
|
"files": [
|
|
13
16
|
"dist/**/*.js",
|
|
14
17
|
"dist/**/*.d.ts",
|
|
15
18
|
"src/",
|
|
16
19
|
"docs/",
|
|
17
20
|
"skills/",
|
|
21
|
+
"scripts/fleet/**",
|
|
18
22
|
"README.md",
|
|
19
23
|
"LICENSE",
|
|
20
24
|
"AGENTS.md",
|