pi-braid 0.43.41 → 0.43.43
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 +37 -0
- package/CONTRIBUTING.md +1 -1
- package/TOOLS.md +10 -15
- package/build-info.json +4 -4
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +126 -24
- package/dist/extensions/core/skills-tool/auto-inject.js +206 -47
- package/dist/extensions/heartbeat/analytics/index.js +41 -18
- package/dist/index.d.ts +0 -2
- package/dist/index.js +0 -2
- package/dist/loader/api.d.ts +2 -5
- package/dist/loader/api.js +7 -48
- package/dist/loader/loader.d.ts +0 -2
- package/dist/loader/loader.js +0 -4
- package/docs/LOCAL_DEV.md +1 -1
- package/docs/SETUP.md +1 -1
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +3 -2
- package/src/extensions/core/skills-tool/auto-inject.ts +255 -50
- package/src/extensions/heartbeat/analytics/AGENTS.md +2 -2
- package/src/extensions/heartbeat/analytics/index.ts +50 -19
- package/src/index.ts +0 -2
- package/src/loader/AGENTS.md +4 -4
- package/src/loader/api.ts +9 -51
- package/src/loader/loader.ts +0 -5
package/CHANGELOG.md
CHANGED
|
@@ -96,6 +96,43 @@ record; the tag scheme above applies unchanged.
|
|
|
96
96
|
note that a clean disable releases it, because a refusal an operator cannot act on
|
|
97
97
|
is a support ticket.
|
|
98
98
|
|
|
99
|
+
## Core — 0.43.43 (2026-11-10: the matched skill arrives whole, once)
|
|
100
|
+
|
|
101
|
+
The auto-inject whisper used to carry a 300-character excerpt of the best-matching skill and a
|
|
102
|
+
pointer to the file, so a session that never followed the pointer had three hundred characters of a
|
|
103
|
+
skill that is often twenty kilobytes. The best match now arrives whole: its body is delivered in the
|
|
104
|
+
whisper up to `FULL_BODY_MAX_CHARS` (12,000 characters, about 3,000 tokens at the pack's divisor),
|
|
105
|
+
frontmatter stripped, cut once at a word boundary when the body runs past the cap, with a line that
|
|
106
|
+
names the file and the remainder. Ranks two and three stay bounded at `MAX_EXCERPT_CHARS`, so the
|
|
107
|
+
whisper cannot grow with the number of matches, and a skill delivered in full once is not delivered
|
|
108
|
+
again in the same session.
|
|
109
|
+
|
|
110
|
+
Measured, not estimated: the payload at the cap is 11,880 characters and 2,970 estimated tokens over
|
|
111
|
+
the pointer row it replaces. The delivery is counted beside `suggested` in the session counters and
|
|
112
|
+
in `skills-usage.json`, so the effect is readable from the counters rather than felt.
|
|
113
|
+
|
|
114
|
+
The identity paragraph in `loading-guidance.ts` is unchanged: it remains the fallback for a skill no
|
|
115
|
+
trigger matched.
|
|
116
|
+
|
|
117
|
+
## Core — 0.43.42 (2026-11-10: ten commands, one per object)
|
|
118
|
+
|
|
119
|
+
- **The six `/modules-*` names are gone.** They forwarded to `/modules` for three releases (0.43.39 to
|
|
120
|
+
0.43.41) and are now deleted, so one object answers to one name. `/modules` keeps its verbs (`on`, `off`,
|
|
121
|
+
`toggle`, `reset`, `all on|off`, `list`) and its text form in RPC mode; its header now says that a contrib
|
|
122
|
+
extension is toggled through `braid.contrib` in settings, because this list reads the core manifest only.
|
|
123
|
+
- **`/browser` replaces `browser-start`, `browser-connect`, `browser-disconnect` and `browser-tabs`.** No
|
|
124
|
+
argument opens one manager: the endpoint, the connection and the active tab as facts, then an action list
|
|
125
|
+
for connect, start, start with a profile, disconnect and the tabs. A headless caller gets the same facts as
|
|
126
|
+
text and never a component. With `braid.contrib.browserAdvanced` off the tab rows are absent by
|
|
127
|
+
configuration, and the manager says that and names the setting instead of leaving the reader to guess.
|
|
128
|
+
- **`/analytics` replaces `analytics`, `analytics:all` and `analytics:ab`.** No argument asks the scope (this
|
|
129
|
+
session, all sessions, A-B) and prints the same block as before; `session`, `all` and `ab` are the verbs a
|
|
130
|
+
script uses. Headless prints the session scope and names the two other verbs.
|
|
131
|
+
- **`/tools status` replaces `tool-status`**, printing exactly the line the old command printed; the
|
|
132
|
+
no-argument `/tools` list is unchanged.
|
|
133
|
+
- **The registered set is 22 names → 10**, and the four objects the inventory found carrying more than one
|
|
134
|
+
command (modules 7, browser 4, analytics 3, tools 2) carry one each.
|
|
135
|
+
|
|
99
136
|
## Core — 0.43.39 (2026-11-09: one command per object, and a menu bar for the services)
|
|
100
137
|
|
|
101
138
|
- **`/modules` replaces six commands.** A registry that offered `modules-list`, `-enable`, `-disable`,
|
package/CONTRIBUTING.md
CHANGED
|
@@ -207,7 +207,7 @@ Extensions are registered in the flat manifest at [`src/extensions/manifest.ts`]
|
|
|
207
207
|
|
|
208
208
|
Config resolution order (highest priority first):
|
|
209
209
|
|
|
210
|
-
1. Runtime subagent API (`/modules on`, `/modules off`, `/modules toggle`).
|
|
210
|
+
1. Runtime subagent API (`/modules on`, `/modules off`, `/modules toggle`). It covers the core manifest; a contrib extension is toggled through `braid.contrib.<name>` in settings.
|
|
211
211
|
2. `~/.pi/agent/settings.json` → `braid.modules`
|
|
212
212
|
3. `BRAID_MODULES` env var
|
|
213
213
|
4. Defaults (all non-opt-in extensions enabled)
|
package/TOOLS.md
CHANGED
|
@@ -35,7 +35,7 @@ fails until the other catches up.
|
|
|
35
35
|
## Enablement reference
|
|
36
36
|
|
|
37
37
|
Braid extension loading is resolved by `src/loader/loader.ts` (`resolveEnabledExtensions`, loader.ts:327)
|
|
38
|
-
with priority: runtime overrides (`/modules
|
|
38
|
+
with priority: runtime overrides (`/modules on|off`) → `braid.modules` from two sources, the later
|
|
39
39
|
winning per id (`~/.pi/agent/settings.json`, then braid's own module-overrides store where those
|
|
40
40
|
toggles persist) → `BRAID_MODULES` env var → manifest defaults (`src/extensions/manifest.ts`). Always-on extensions (`alwaysOn: true`)
|
|
41
41
|
can never be disabled; opt-in extensions (`disabledByDefault: true`) only load when explicitly enabled.
|
|
@@ -87,20 +87,15 @@ enablement (see appendix).
|
|
|
87
87
|
Extension commands the tool catalog does not cover: slash commands registered by
|
|
88
88
|
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
|
-
the watchdog `AGENTS.md`,
|
|
91
|
-
|
|
92
|
-
| Command
|
|
93
|
-
|
|
|
94
|
-
| `/analytics`
|
|
95
|
-
| `/
|
|
96
|
-
| `/
|
|
97
|
-
| `/
|
|
98
|
-
| `/
|
|
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. |
|
|
90
|
+
the watchdog `AGENTS.md`, `/modules` in `SETUP.md`.
|
|
91
|
+
|
|
92
|
+
| Command | Registered by | What it does |
|
|
93
|
+
| ---------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
94
|
+
| `/analytics` | analytics (heartbeat module) | Show tool analytics. No argument asks the scope in the TUI; `session`, `all` and `ab` are the verbs. |
|
|
95
|
+
| `/browser` | browser (contrib) | One manager for Chrome: `connect`, `start [--profile]`, `disconnect`, `tabs`. No argument shows the endpoint, the connection state, the active tab and the actions. |
|
|
96
|
+
| `/context-stats` | context-manager (memory module) | Show context pruning statistics. |
|
|
97
|
+
| `/rate-cancel` | rate-limiter (contrib) | Cancel the rate limiter wait and reset its state. |
|
|
98
|
+
| `/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
99
|
|
|
105
100
|
## Appendix: standalone packages surfaced into the braid prompt
|
|
106
101
|
|
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.43.43",
|
|
4
|
+
"sha": "faafcad8ff2d1ffaa02e18245e334016e5be6e95",
|
|
5
|
+
"shaShort": "faafcad8",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-11-
|
|
8
|
+
"packedAt": "2026-11-10T18:33:21.495Z"
|
|
9
9
|
}
|
|
@@ -54,21 +54,30 @@
|
|
|
54
54
|
* most likely to match.
|
|
55
55
|
* `sendTrackedMessage` reports whether the message was accepted; a
|
|
56
56
|
* suppressed suggestion is neither sent nor counted.
|
|
57
|
-
* 5. Content delivery: the
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
*
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
57
|
+
* 5. Content delivery, two tiers: the best-ranked match arrives WHOLE —
|
|
58
|
+
* its SKILL.md body (frontmatter stripped) as the whisper's first-class
|
|
59
|
+
* payload, up to FULL_BODY_MAX_CHARS, the file named and the remainder
|
|
60
|
+
* pointed at when the body exceeds the cap. Every lower rank stays on
|
|
61
|
+
* the pointer tier: a bounded excerpt (≤ MAX_EXCERPT_CHARS) plus an
|
|
62
|
+
* explicit read pointer. One body per whisper and one per skill per
|
|
63
|
+
* session — a skill whose body already landed is a pointer when it
|
|
64
|
+
* matches again. Best-effort: an unreadable file stays on the pointer
|
|
65
|
+
* tier, because a body that never arrived is not delivered.
|
|
66
|
+
* 6. No reply ritual: the whisper names the SKILL.md path and stops there —
|
|
67
|
+
* a read is the conversion signal where a read is still needed, and the
|
|
68
|
+
* solicited one-line reply is honored 2% of the time (channel noise, not
|
|
69
|
+
* information).
|
|
70
|
+
* 7. Adoption counter: per-skill `suggested`/`loaded`/`fullBody` counters,
|
|
71
|
+
* incremented on delivery, on load, and on a first-class body delivery
|
|
72
|
+
* respectively, surfaced by the `skill_stats` tool. `fullBody` counts
|
|
73
|
+
* deliveries the whisper carried whole (or capped) rather than as an
|
|
74
|
+
* excerpt, so the effect of the body tier is separable from the count
|
|
75
|
+
* of pointers; both move for the same message, so their difference is
|
|
76
|
+
* the pointer-only share. `suggested` counts DELIVERED suggestions: the
|
|
77
|
+
* counter increments only after `sendTrackedMessage` reports the whisper
|
|
78
|
+
* was accepted, so the number measures the suggestion channel rather
|
|
79
|
+
* than the intent to use it. A load has two evidence grades — a verbal
|
|
80
|
+
* claim (the LOADED
|
|
72
81
|
* probe reply, an honor-system grade the whisper does not solicit; the
|
|
73
82
|
* counter stays monotone for the store's series) and a detected actual
|
|
74
83
|
* load (SKILL.md read seen by the tool_result read-detector; failed
|
|
@@ -139,11 +148,31 @@ export declare const COOLDOWN_TURNS = 10;
|
|
|
139
148
|
*/
|
|
140
149
|
export declare const LOADED_COOLDOWN_TURNS = 30;
|
|
141
150
|
/**
|
|
142
|
-
* Max characters of SKILL.md body content carried in a
|
|
143
|
-
*
|
|
144
|
-
*
|
|
151
|
+
* Max characters of SKILL.md body content carried in a POINTER row, per
|
|
152
|
+
* skill: the excerpt every match below the top rank gets, and the fallback
|
|
153
|
+
* for a top match whose file cannot be read (~2 rows × 300 chars +
|
|
154
|
+
* boilerplate). Unchanged by the body tier below; the row always points at
|
|
155
|
+
* the full file for the rest.
|
|
145
156
|
*/
|
|
146
157
|
export declare const MAX_EXCERPT_CHARS = 300;
|
|
158
|
+
/**
|
|
159
|
+
* Max characters of a SKILL.md body delivered first-class: the whole text of
|
|
160
|
+
* the whisper's best match, frontmatter stripped.
|
|
161
|
+
*
|
|
162
|
+
* The number is measured against the shipped pack, not picked. The 34 skill
|
|
163
|
+
* bodies run 385 to 29,997 characters, median 6,614, and 23 of them fit
|
|
164
|
+
* inside 12,000 whole; the ones past it are reference documents whose
|
|
165
|
+
* remainder is one read away and now named at the cut. Under the divisor the
|
|
166
|
+
* rest of the surface prices a read with (CHARS_PER_TOKEN = 4, also pi-core's
|
|
167
|
+
* estimateTokens), a body at the cap is 3,000 estTokens.
|
|
168
|
+
*
|
|
169
|
+
* That is the payload of one delivery: a body, plus at most MAX_EXCERPT_CHARS
|
|
170
|
+
* per other row, at most MAX_INJECTED rows. The read it stands in for costs
|
|
171
|
+
* the same body characters plus a tool call and a round trip, so a body
|
|
172
|
+
* delivered whole is never dearer than the conversion it removes; a body past
|
|
173
|
+
* the cap costs the cap and says where the rest is.
|
|
174
|
+
*/
|
|
175
|
+
export declare const FULL_BODY_MAX_CHARS = 12000;
|
|
147
176
|
/**
|
|
148
177
|
* Minimum score for a skill whose match never touches its NAME (description
|
|
149
178
|
* and/or filePath keyword hits only). Name matches qualify at any score.
|
|
@@ -402,6 +431,16 @@ export declare function rankSkillsDeterministic(skills: CachedSkill[], taskText:
|
|
|
402
431
|
* (or with an unclosed `---` block) are returned as-is.
|
|
403
432
|
*/
|
|
404
433
|
export declare function stripSkillFrontmatter(content: string): string;
|
|
434
|
+
/**
|
|
435
|
+
* Whole body when it fits, else a cut at a word boundary with the truncation
|
|
436
|
+
* mark. Pure.
|
|
437
|
+
*
|
|
438
|
+
* One rule for both tiers: a pointer row's 300-character excerpt and a
|
|
439
|
+
* first-class body at FULL_BODY_MAX_CHARS cut the same way, so a body ending
|
|
440
|
+
* mid-word reads as a cut in either, and the cut lands at whitespace whenever
|
|
441
|
+
* the text carries any in the last stretch before the cap.
|
|
442
|
+
*/
|
|
443
|
+
export declare function cutSkillBody(body: string, maxChars: number): string;
|
|
405
444
|
/**
|
|
406
445
|
* Bounded excerpt of a skill body: strip frontmatter, trim, cap at maxChars,
|
|
407
446
|
* mark truncation. Pure.
|
|
@@ -413,16 +452,64 @@ export declare function extractSkillExcerpt(content: string, maxChars?: number):
|
|
|
413
452
|
* back to the skill description.
|
|
414
453
|
*/
|
|
415
454
|
export declare function readSkillExcerpt(filePath: string, maxChars?: number): string;
|
|
455
|
+
/** A SKILL.md body as the whisper carries it, and whether the cap cut it. */
|
|
456
|
+
export interface SkillBody {
|
|
457
|
+
text: string;
|
|
458
|
+
truncated: boolean;
|
|
459
|
+
}
|
|
460
|
+
/**
|
|
461
|
+
* Read a SKILL.md into a deliverable body at the body-tier cap.
|
|
462
|
+
* Returns undefined on any error (missing file, unreadable) AND on an empty
|
|
463
|
+
* body: the caller stays on the pointer tier, because a body that never
|
|
464
|
+
* arrived must not be counted as delivered.
|
|
465
|
+
*/
|
|
466
|
+
export declare function readSkillBody(filePath: string, maxChars?: number): SkillBody | undefined;
|
|
467
|
+
/** The body a whisper carried first-class, and whether the cap cut it. */
|
|
468
|
+
export interface DeliveredBody {
|
|
469
|
+
name: string;
|
|
470
|
+
truncated: boolean;
|
|
471
|
+
}
|
|
472
|
+
export interface WhisperContent {
|
|
473
|
+
/** The message text. */
|
|
474
|
+
text: string;
|
|
475
|
+
/** The body carried first-class; absent when the message carried pointers only. */
|
|
476
|
+
body?: DeliveredBody;
|
|
477
|
+
}
|
|
478
|
+
/**
|
|
479
|
+
* Format the steer whisper for a recommendation, in two tiers.
|
|
480
|
+
*
|
|
481
|
+
* `fullBodySkill` names the one skill whose SKILL.md body the message carries
|
|
482
|
+
* first-class. The caller decides it from the session's already-delivered set
|
|
483
|
+
* (see pickFullBodySkill), so a re-match, an unreadable file or a skill this
|
|
484
|
+
* session already received leaves the message on the pointer tier.
|
|
485
|
+
*
|
|
486
|
+
* A body inside the cap is delivered whole and the message says so, which is
|
|
487
|
+
* what makes the read call unnecessary for that skill; a body past it is cut
|
|
488
|
+
* once at a word boundary, the file is named, and the message says the rest
|
|
489
|
+
* is there. Every other row keeps the pointer tier: MAX_EXCERPT_CHARS of
|
|
490
|
+
* body, one line, plus the path.
|
|
491
|
+
*
|
|
492
|
+
* The returned `body` is the fact the counter and the once-per-session record
|
|
493
|
+
* are written from, and it is present only when a body actually landed.
|
|
494
|
+
*/
|
|
495
|
+
export declare function formatWhisperContent(skills: CachedSkill[], fullBodySkill?: string): WhisperContent;
|
|
416
496
|
/**
|
|
417
497
|
* Format the steer whisper content for a set of recommended skills.
|
|
418
498
|
*
|
|
419
|
-
*
|
|
420
|
-
*
|
|
421
|
-
*
|
|
422
|
-
* moment of domain match, not just a truncated description. Unreadable
|
|
423
|
-
* files fall back to the description (also bounded, one line).
|
|
499
|
+
* `skills` arrives ranked (best first). The text is the pointer tier for
|
|
500
|
+
* every row; pass `fullBodySkill` to deliver one body first-class — see
|
|
501
|
+
* formatWhisperContent, which this delegates to.
|
|
424
502
|
*/
|
|
425
|
-
export declare function formatWhisper(skills: CachedSkill[]): string;
|
|
503
|
+
export declare function formatWhisper(skills: CachedSkill[], fullBodySkill?: string): string;
|
|
504
|
+
/**
|
|
505
|
+
* Which skill the whisper may carry first-class: the best-ranked match, and
|
|
506
|
+
* only while this session has not delivered that skill's body already.
|
|
507
|
+
*
|
|
508
|
+
* The rule fixes the payload at one body per message and one per skill per
|
|
509
|
+
* session. A re-match is a pointer because the body is in context; a lower
|
|
510
|
+
* rank is never expanded because the rank is what the body tier is for. Pure.
|
|
511
|
+
*/
|
|
512
|
+
export declare function pickFullBodySkill(ranked: readonly CachedSkill[], delivered: ReadonlySet<string>): string | undefined;
|
|
426
513
|
/** Per-skill usage counters, session-scoped (a durable cross-session copy is mirrored below). */
|
|
427
514
|
export interface SkillStats {
|
|
428
515
|
/** Times this skill was suggested via the auto-inject whisper. */
|
|
@@ -433,6 +520,8 @@ export interface SkillStats {
|
|
|
433
520
|
claimed: number;
|
|
434
521
|
/** Loads detected by the read tool (SKILL.md read via tool_result). */
|
|
435
522
|
actual: number;
|
|
523
|
+
/** Whispers that carried this skill's body first-class (whole or capped). */
|
|
524
|
+
fullBody: number;
|
|
436
525
|
}
|
|
437
526
|
/** Read the session's per-skill usage counters (for the skill_stats tool). */
|
|
438
527
|
export declare function getSkillStats(ctx: ExtensionContext): Record<string, SkillStats>;
|
|
@@ -453,6 +542,17 @@ export declare function recordSkillLoad(ctx: ExtensionContext, name: string): vo
|
|
|
453
542
|
* durable store's published series. Increments `loaded` + `claimed`.
|
|
454
543
|
*/
|
|
455
544
|
export declare function recordSkillClaim(ctx: ExtensionContext, name: string): void;
|
|
545
|
+
/**
|
|
546
|
+
* Record a FIRST-CLASS BODY delivery: the whisper carried this skill's body as
|
|
547
|
+
* its payload rather than a bounded excerpt.
|
|
548
|
+
*
|
|
549
|
+
* `suggested` moved for the same message, so the pair reads "of the
|
|
550
|
+
* suggestions delivered, how many arrived whole" without a second channel to
|
|
551
|
+
* instrument later. Only a body that actually landed in a delivered message is
|
|
552
|
+
* recorded: a suppressed whisper moves neither counter, and an unreadable file
|
|
553
|
+
* leaves the message on the pointer tier.
|
|
554
|
+
*/
|
|
555
|
+
export declare function recordSkillFullDelivery(ctx: ExtensionContext, name: string): void;
|
|
456
556
|
/**
|
|
457
557
|
* Which counting regime produced an entry's `suggested` number:
|
|
458
558
|
* "delivered" — every increment counted a whisper ACCEPTED for delivery
|
|
@@ -480,6 +580,8 @@ export interface DurableSkillStats {
|
|
|
480
580
|
claimed: number;
|
|
481
581
|
/** All-time count of detected loads (SKILL.md read via the read tool). */
|
|
482
582
|
actual: number;
|
|
583
|
+
/** All-time count of first-class body deliveries (see recordSkillFullDelivery). */
|
|
584
|
+
fullBody: number;
|
|
483
585
|
/** ISO timestamp of the most recent recorded event. */
|
|
484
586
|
lastAt: string;
|
|
485
587
|
/** Which counting regime `suggested` mixes (see SuggestedEpoch). */
|