pi-braid 0.40.5 → 0.41.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/AGENTS.md +17 -18
- package/README.md +128 -130
- package/TOOLS.md +35 -35
- package/build-info.json +4 -4
- package/dist/extensions/core/agent-environment/index.js +4 -3
- package/dist/extensions/core/prompt-builder/index.js +12 -7
- package/dist/extensions/core/prompt-builder/instance-composition.d.ts +51 -10
- package/dist/extensions/core/prompt-builder/instance-composition.js +87 -14
- package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +3 -3
- package/dist/extensions/core/prompt-builder/system-info-tool.js +3 -3
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +89 -10
- package/dist/extensions/core/skills-tool/auto-inject.js +150 -21
- package/dist/extensions/core/skills-tool/index.d.ts +70 -2
- package/dist/extensions/core/skills-tool/index.js +149 -15
- package/dist/extensions/core/skills-tool/reach.d.ts +119 -0
- package/dist/extensions/core/skills-tool/reach.js +213 -0
- package/dist/extensions/core/skills-tool/skill-triggers.d.ts +47 -10
- package/dist/extensions/core/skills-tool/skill-triggers.js +66 -23
- package/dist/extensions/enforcement/handlers/register-session-compact.js +12 -1
- package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +15 -34
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +2 -1
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +55 -28
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +14 -10
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +88 -82
- package/dist/extensions/enforcement/resume-state.d.ts +76 -0
- package/dist/extensions/enforcement/resume-state.js +90 -0
- package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +9 -0
- package/dist/extensions/enforcement/substate/context-hygiene-state.js +8 -0
- package/dist/extensions/enforcement/whisper.d.ts +12 -0
- package/dist/extensions/enforcement/whisper.js +16 -1
- package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +14 -6
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +7 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +372 -0
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +8 -2
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +54 -21
- package/dist/lib/config/braid-paths.d.ts +14 -0
- package/dist/lib/config/braid-paths.js +18 -0
- package/dist/lib/config/braid-settings.d.ts +21 -0
- package/dist/lib/config/braid-settings.js +16 -0
- package/dist/lib/detection/context-tiers.d.ts +47 -3
- package/dist/lib/detection/context-tiers.js +122 -13
- package/dist/lib/events/turn-boundary.d.ts +78 -0
- package/dist/lib/events/turn-boundary.js +91 -0
- package/dist/lib/orchestrator/workers.d.ts +3 -2
- package/dist/lib/orchestrator/workers.js +22 -4
- package/dist/lib/state/global-state.d.ts +1 -1
- package/docs/CONTEXT-MAP.md +1 -1
- package/docs/CONTEXT-POLICY.md +8 -0
- package/docs/FLEET.md +99 -0
- package/docs/LOCAL_DEV.md +0 -1
- package/docs/ROADMAP.md +5 -5
- package/docs/SETUP.md +19 -18
- package/package.json +5 -1
- package/scripts/fleet/cli.mjs +499 -0
- package/scripts/fleet/driver-rpc.mjs +376 -0
- package/scripts/fleet/driver-scripted.mjs +239 -0
- package/scripts/fleet/journal.mjs +994 -0
- package/scripts/fleet/procs.mjs +76 -0
- package/scripts/fleet/supervisor.mjs +1494 -0
- package/scripts/fleet/tool-guard.mjs +467 -0
- package/skills/herdr-topology/SKILL.md +6 -1
- package/skills/release-pipeline/SKILL.md +20 -4
- package/skills/research/SKILL.md +32 -0
- package/skills/subagent-orchestration/SKILL.md +2 -2
- package/src/extensions/core/agent-environment/index.ts +4 -3
- package/src/extensions/core/prompt-builder/AGENTS.md +8 -4
- package/src/extensions/core/prompt-builder/index.ts +12 -7
- package/src/extensions/core/prompt-builder/instance-composition.ts +98 -14
- package/src/extensions/core/prompt-builder/system-info-tool.ts +3 -3
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
- package/src/extensions/core/skills-tool/auto-inject.ts +196 -24
- package/src/extensions/core/skills-tool/index.ts +217 -15
- package/src/extensions/core/skills-tool/reach.ts +256 -0
- package/src/extensions/core/skills-tool/skill-triggers.ts +90 -20
- package/src/extensions/enforcement/handlers/register-session-compact.ts +12 -1
- package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +23 -36
- package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +59 -29
- package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +101 -81
- package/src/extensions/enforcement/resume-state.ts +127 -0
- package/src/extensions/enforcement/substate/context-hygiene-state.ts +17 -0
- package/src/extensions/enforcement/whisper.ts +21 -1
- package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +20 -5
- package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +370 -0
- package/src/extensions/memory/AGENTS.md +25 -1
- package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +80 -27
- package/src/lib/config/braid-paths.ts +20 -0
- package/src/lib/config/braid-settings.ts +46 -0
- package/src/lib/detection/context-tiers.ts +186 -13
- package/src/lib/events/AGENTS.md +1 -0
- package/src/lib/events/turn-boundary.ts +115 -0
- package/src/lib/orchestrator/workers.ts +33 -12
- package/src/lib/state/global-state.ts +1 -0
- package/src/lib/utils/AGENTS.md +1 -1
- package/src/types/extension-context.d.ts +22 -79
|
@@ -444,8 +444,9 @@ export type PopulationCensus = (revision: string) => number | null;
|
|
|
444
444
|
* Read every gate row for a population stamp and compare the `files` ones
|
|
445
445
|
* against the census the caller supplies for their named revision. Pure: the
|
|
446
446
|
* count is a lookup parameter, so the parse and the comparison are testable
|
|
447
|
-
* without a repository. Rows of another unit are not census subjects
|
|
448
|
-
* left uncompared; an unreadable stamp is named,
|
|
447
|
+
* without a repository. Rows of another unit are not census subjects: they are
|
|
448
|
+
* read, named in the lines, and left uncompared; an unreadable stamp is named,
|
|
449
|
+
* never silently dropped.
|
|
449
450
|
*/
|
|
450
451
|
export declare function readPopulationStamps(gates: unknown, censusAt: PopulationCensus): PopulationRead;
|
|
451
452
|
/**
|
|
@@ -842,8 +842,15 @@ export function productionWriteRefusalDetail(read) {
|
|
|
842
842
|
* Bare-token revision rules: an all-hex token is a sha only at 7-40 chars, so
|
|
843
843
|
* a six-char prefix does not slip through the ref-name alternative as a
|
|
844
844
|
* revision git can never resolve.
|
|
845
|
+
*
|
|
846
|
+
* The unit is one token of lowercase letters and digits, joined by single
|
|
847
|
+
* hyphens or underscores and starting with a letter: a reporter writes
|
|
848
|
+
* `test-files` as readily as `files`, and the earlier letters-only rule threw
|
|
849
|
+
* that evidence away as unreadable. A unit is never a phrase — `scanned 5 test
|
|
850
|
+
* files at main` stays refused, because a two-word unit cannot be told from a
|
|
851
|
+
* malformed stamp.
|
|
845
852
|
*/
|
|
846
|
-
const POPULATION_STAMP_RE = /^scanned (\d+) ([a-z]+) at ([0-9a-fA-F]{7,40}|[A-Za-z0-9][A-Za-z0-9._/-]*)$/;
|
|
853
|
+
const POPULATION_STAMP_RE = /^scanned (\d+) ([a-z][a-z0-9]*(?:[_-][a-z0-9]+)*) at ([0-9a-fA-F]{7,40}|[A-Za-z0-9][A-Za-z0-9._/-]*)$/;
|
|
847
854
|
const ALL_HEX_RE = /^[0-9a-fA-F]+$/;
|
|
848
855
|
/** Parse the stamp shape above; null when the value is not that shape. */
|
|
849
856
|
export function parsePopulationStamp(value) {
|
|
@@ -864,8 +871,18 @@ function populationLines(rows) {
|
|
|
864
871
|
lines.push(`population stamp unreadable: row ${row.row} ${JSON.stringify(row.raw)}`);
|
|
865
872
|
continue;
|
|
866
873
|
}
|
|
867
|
-
if (row.stamp === null
|
|
874
|
+
if (row.stamp === null)
|
|
875
|
+
continue;
|
|
876
|
+
if (row.stamp.unit !== "files") {
|
|
877
|
+
// A stamp names the population it scanned. Only `files` is a census
|
|
878
|
+
// subject here (the tracked-entry count at the revision), so another
|
|
879
|
+
// unit is read and named but never compared — and never dropped as if it
|
|
880
|
+
// had been unreadable, which is what the old unit pattern did to
|
|
881
|
+
// `test-files`.
|
|
882
|
+
lines.push(`population recorded: ${row.stamp.n} ${row.stamp.unit} at ${row.stamp.revision} ` +
|
|
883
|
+
`(row ${row.row}; unit is not the tracked-entry census, not compared)`);
|
|
868
884
|
continue;
|
|
885
|
+
}
|
|
869
886
|
if (row.verdict === "unresolved") {
|
|
870
887
|
lines.push(`population delta: recorded ${row.stamp.n} at ${row.stamp.revision} ` +
|
|
871
888
|
`(row ${row.row}; revision unresolved, not compared)`);
|
|
@@ -884,8 +901,9 @@ function populationLines(rows) {
|
|
|
884
901
|
* Read every gate row for a population stamp and compare the `files` ones
|
|
885
902
|
* against the census the caller supplies for their named revision. Pure: the
|
|
886
903
|
* count is a lookup parameter, so the parse and the comparison are testable
|
|
887
|
-
* without a repository. Rows of another unit are not census subjects
|
|
888
|
-
* left uncompared; an unreadable stamp is named,
|
|
904
|
+
* without a repository. Rows of another unit are not census subjects: they are
|
|
905
|
+
* read, named in the lines, and left uncompared; an unreadable stamp is named,
|
|
906
|
+
* never silently dropped.
|
|
889
907
|
*/
|
|
890
908
|
export function readPopulationStamps(gates, censusAt) {
|
|
891
909
|
const rows = [];
|
|
@@ -297,7 +297,7 @@ export declare function getShownDiscoveryBundles(): Set<string>;
|
|
|
297
297
|
export declare function resetShownDiscoveryBundles(): void;
|
|
298
298
|
/** Signal type identifiers used by the discoverability handler.
|
|
299
299
|
* These are the dedup keys — keep them stable across releases. */
|
|
300
|
-
export type DiscoverySignalType = "scratchpad_prior" | "memory_prior" | "sessions_prior" | "resume" | "tags_prior" | "context_hygiene_tip";
|
|
300
|
+
export type DiscoverySignalType = "scratchpad_prior" | "memory_prior" | "sessions_prior" | "resume" | "tags_prior" | "journal_prior" | "context_hygiene_tip";
|
|
301
301
|
/** Get the shared shown-signal-types set (process-global, survives /reload). */
|
|
302
302
|
export declare function getShownSignals(): Set<DiscoverySignalType>;
|
|
303
303
|
/** Reset the shown-signal set. Test helper. */
|
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/CONTEXT-POLICY.md
CHANGED
|
@@ -35,6 +35,14 @@ arms fire late on large windows, which is why both ladders exist. `CONTEXT_COMPA
|
|
|
35
35
|
mode, guarding against max-call-stack crashes and session corruption at high
|
|
36
36
|
usage; hygiene acts re-arm at most once every three turns.
|
|
37
37
|
|
|
38
|
+
The two ladders arm one enforcement nudge between them, ordered by position on
|
|
39
|
+
the percent axis both units measure: 0.18W, 30%, 0.45W, 50%, 65%, 75%, 80%. The
|
|
40
|
+
highest reached rung renders, so a token arm never shadows a percent tier above
|
|
41
|
+
it (0.45W is 45% of every window). The nudge latch records the rung that fired
|
|
42
|
+
and re-arms on a fall back below that rung, in that rung's own unit - a percent
|
|
43
|
+
bar would clear a 0.45W arm on the very next turn, repeating the same line.
|
|
44
|
+
Owner: [`src/lib/detection/context-tiers.ts`](../src/lib/detection/context-tiers.ts).
|
|
45
|
+
|
|
38
46
|
Owner: [`src/lib/detection/context-thresholds.ts`](../src/lib/detection/context-thresholds.ts)
|
|
39
47
|
(single home; consumers import, never restate).
|
|
40
48
|
|
package/docs/FLEET.md
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
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
|
+
When a turn cannot carry a message at all (the node is done, or failed at its
|
|
57
|
+
attempt bound), the supervisor stamps the row `undeliverable` and `status`
|
|
58
|
+
counts it, rather than leaving a promise nobody keeps.
|
|
59
|
+
|
|
60
|
+
## Asks and deadlines
|
|
61
|
+
|
|
62
|
+
An ask is a question a human can answer, with a deadline and a default. When the
|
|
63
|
+
deadline passes, the drain answers the ask from its own default and queues that
|
|
64
|
+
default as an ordinary message, so the node moves again. The claim and the queue
|
|
65
|
+
are one transaction: a supervisor killed between them leaves either both or
|
|
66
|
+
neither, and the drain is what a restart runs to recover.
|
|
67
|
+
|
|
68
|
+
Two supervisors may drain the same root: the claim is a conditional update, so
|
|
69
|
+
each overdue ask is answered exactly once and queued exactly once. If the store's
|
|
70
|
+
write lock is held by someone else, the drain waits and retries; a drain that
|
|
71
|
+
cannot finish is journalled as `drain_deferred` (with the attempts, the wait and
|
|
72
|
+
the error) and only reported, never thrown at the process. `status` prints both
|
|
73
|
+
facts when they exist.
|
|
74
|
+
|
|
75
|
+
## The journal
|
|
76
|
+
|
|
77
|
+
One file per fleet root, `<fleet-root>/fleet.sqlite`, in WAL mode with
|
|
78
|
+
`synchronous = FULL`. The tables, their columns, the invariants they hold and the
|
|
79
|
+
failure each column prevents are documented where they are defined -
|
|
80
|
+
[`../scripts/fleet/journal.mjs`](../scripts/fleet/journal.mjs) - and this page
|
|
81
|
+
does not restate them. Read them there before writing to a journal by hand.
|
|
82
|
+
|
|
83
|
+
## Where the code is
|
|
84
|
+
|
|
85
|
+
| File | What it owns |
|
|
86
|
+
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
|
|
87
|
+
| [`../scripts/fleet/cli.mjs`](../scripts/fleet/cli.mjs) | The four commands, argv, the help text, the tier reporting. |
|
|
88
|
+
| [`../scripts/fleet/journal.mjs`](../scripts/fleet/journal.mjs) | The schema, the claim, the transaction, the busy timeout. |
|
|
89
|
+
| [`../scripts/fleet/supervisor.mjs`](../scripts/fleet/supervisor.mjs) | The loop, reconciliation, the drain, leases, the control socket. |
|
|
90
|
+
| [`../scripts/fleet/driver-rpc.mjs`](../scripts/fleet/driver-rpc.mjs) | The driver that runs a node through a real pi child. |
|
|
91
|
+
| [`../scripts/fleet/driver-scripted.mjs`](../scripts/fleet/driver-scripted.mjs) | The deterministic driver the crash drill uses. |
|
|
92
|
+
| [`../scripts/fleet/tool-guard.mjs`](../scripts/fleet/tool-guard.mjs) | The pre-execution guard that refuses a repeated effect on resume. |
|
|
93
|
+
| [`../scripts/fleet/procs.mjs`](../scripts/fleet/procs.mjs) | Process liveness and resident memory, read from the kernel. |
|
|
94
|
+
|
|
95
|
+
The guarantee the supervisor is built around is narrower than "it resumes": no
|
|
96
|
+
completed effect is repeated and no node is silently lost, across a crash. The
|
|
97
|
+
tests that hold it are in
|
|
98
|
+
[`../test/runtime/fleet/`](../test/runtime/fleet/), and the crash drill is
|
|
99
|
+
[`../test/runtime/fleet/drill.mjs`](../test/runtime/fleet/drill.mjs).
|
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -53,7 +53,6 @@ npm run format:check # prettier --check .
|
|
|
53
53
|
npm run check:docs # every in-scope .md has a status marker
|
|
54
54
|
npm run check:doc-drift # current-state docs must not reference APIs missing from code
|
|
55
55
|
npm run check:deps # layer-boundary check
|
|
56
|
-
npm run check:private-data # whole-tree private-data scan
|
|
57
56
|
```
|
|
58
57
|
|
|
59
58
|
Per-workspace variants use the workspace flag, e.g.
|
package/docs/ROADMAP.md
CHANGED
|
@@ -46,8 +46,7 @@ provenance; they are no longer work.
|
|
|
46
46
|
1. **Providers de-reference (P10b)** - RESOLVED: the Venice registration is a
|
|
47
47
|
userland catalog seam (`providers/venice-catalog.ts`, resolved from
|
|
48
48
|
`$VENICE_CATALOG_FILE` or `~/.pi/agent/venice-models.json`); the provider
|
|
49
|
-
registers only when that catalog exists
|
|
50
|
-
whole tree in `ci:check`.
|
|
49
|
+
registers only when that catalog exists.
|
|
51
50
|
2. **Version-drift cleanup** - RESOLVED: the four workspace packages declare
|
|
52
51
|
the pi peer as `"*"`; the root manifest pins the installed version
|
|
53
52
|
(`package.json`, the `@earendil-works/*` deps).
|
|
@@ -55,9 +54,10 @@ provenance; they are no longer work.
|
|
|
55
54
|
the root `CHANGELOG.md` - core keeps the bare `v` (iteration tags `v0.40.0-main.N`,
|
|
56
55
|
`package.json` `0.40.0-main.N`; release tag `v0.40.0`), every sibling tags as
|
|
57
56
|
`<workspace>-v<version>` (`telegram-v0.1.4`).
|
|
58
|
-
4. **
|
|
59
|
-
|
|
60
|
-
|
|
57
|
+
4. **Documentation path rule** - RESOLVED: docs may name product paths
|
|
58
|
+
(`~/.pi/agent/…`, `~/pi-braid/…`) and never a private home layout;
|
|
59
|
+
`check-doc-links` fails on the latter, and every in-repo reference must
|
|
60
|
+
resolve.
|
|
61
61
|
5. **Skills pack** - finish validating the five skills still marked
|
|
62
62
|
`verdict: UNVALIDATED` (`braid-reference`, `misdirection-audit`,
|
|
63
63
|
`placement-discipline`, `probe-evaluation`, `voice-replies`); keep the pack
|
package/docs/SETUP.md
CHANGED
|
@@ -298,24 +298,25 @@ The user-global file always exists; the project one is optional and belongs to p
|
|
|
298
298
|
|
|
299
299
|
`packages` is pi-native - what to load as extensions. Everything braid reads sits under the top-level `braid` key. Keys that exist in code today:
|
|
300
300
|
|
|
301
|
-
| Key | Type
|
|
302
|
-
| --------------------------------------- |
|
|
303
|
-
| `braid.modules.<ref>` | boolean
|
|
304
|
-
| `braid.suppressNudges` | boolean
|
|
305
|
-
| `braid.timezone` | IANA name
|
|
306
|
-
| `braid.enforcement.nudgeConfigs.<type>` | object
|
|
307
|
-
| `braid.memory.writeGate` | object
|
|
308
|
-
| `braid.timers.maxWakeAttempts` | integer 1..10
|
|
309
|
-
| `braid.timers.wakeAlert` | object
|
|
310
|
-
| `braid.context.contextLimitTokens` | positive number
|
|
311
|
-
| `braid.context.toolResultSizeCap` | object
|
|
312
|
-
| `braid.context.staleToolResultOffload` | object
|
|
313
|
-
| `braid.context.contextEmergencyOffload` | object
|
|
314
|
-
| `braid.
|
|
315
|
-
| `braid.telegram.
|
|
316
|
-
| `braid.telegram.
|
|
317
|
-
| `braid.
|
|
318
|
-
| `braid.contrib.<
|
|
301
|
+
| Key | Type | Default | Purpose |
|
|
302
|
+
| --------------------------------------- | ------------------------ | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
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)). |
|
|
304
|
+
| `braid.suppressNudges` | boolean | `false` | Silence all cognitive nudges (enforcement whispers, heartbeat suggestions, feedback reminders). |
|
|
305
|
+
| `braid.timezone` | IANA name | `Europe/Moscow` | Time zone for all braid-facing time rendering. |
|
|
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. |
|
|
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. |
|
|
308
|
+
| `braid.timers.maxWakeAttempts` | integer 1..10 | `3` | Redelivery cap for a failed timer wake before it is dropped with a visible notice. |
|
|
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). |
|
|
310
|
+
| `braid.context.contextLimitTokens` | positive number | provider context window | The window every surface computes with (usage math, density, fallbacks, pi-core threshold compaction and overflow detection, TUI footer). A CEILING: min(contextLimitTokens, true window) when known, else the cap; re-plumbed on session start and /reload and never widens a smaller true window. The provider catalog keeps the true size. |
|
|
311
|
+
| `braid.context.toolResultSizeCap` | object | ON, 262144 chars | Capture-time cap: oversized tool results are flushed to disk and replaced by a stub. |
|
|
312
|
+
| `braid.context.staleToolResultOffload` | object | OFF | Opt-in age/size offload of stale large tool results (defaults: `minChars` 4000, `stalenessTurns` 40, `keepRecentTurns` 20, `maxOffloadCharsPerRun` 65536). |
|
|
313
|
+
| `braid.context.contextEmergencyOffload` | object | ON | Emergency offload of the largest tool results when a context-window (413) error fires, then one retry (defaults: `minChars` 262144, `maxCharsPerRun` 1048576, `keepRecentTurns` 1). |
|
|
314
|
+
| `braid.skills.ranking` | `keyword`/`auto`/`model` | `keyword` | Tier policy for the `list_skills` relevance ranking. `keyword` (implemented): the deterministic scorer orders the rows and reports its own verdict (`unambiguous` / `tie` / `thin-margin` / `short-task` / `no-score` / `no-task`) with per-row `relevance {score, reason}`. `auto` and `model` are reserved for a model tier that would answer on an ambiguous verdict; it was measured against the scorer and not kept, so both evaluate to the keyword path and the read echoes the configured value as `ranking.policy`. An unknown value falls back to `keyword`. |
|
|
315
|
+
| `braid.telegram.sendMaxChars` | positive number | `4096` | Plain-text cap for `telegram_send`, re-read per call. |
|
|
316
|
+
| `braid.telegram.notifyMaxChars` | positive number | `1200` | Craft target and guard for turn-end notifications. |
|
|
317
|
+
| `braid.telegram.pauseStateFile` | path string | built-in default | Override for the `/telegram` pause-state file path. |
|
|
318
|
+
| `braid.contrib.<name>` | boolean or object | enabled / per-extension | Per-contrib-extension config - see [§ Contrib extensions](#contrib-extensions). |
|
|
319
|
+
| `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`. |
|
|
319
320
|
|
|
320
321
|
### Worked example
|
|
321
322
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.41.0",
|
|
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",
|