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 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`). The six former names (`/modules-enable`, `/modules-disable`, `/modules-toggle`, `/modules-list`, `/modules-status`, `/modules-reset`) forward to it for one release.
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-*`) → `braid.modules` from two sources, the later
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`, the `/modules-*` family in `SETUP.md`.
91
-
92
- | Command | Registered by | What it does |
93
- | --------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
94
- | `/analytics` | analytics (heartbeat module) | Show tool analytics for the current session. |
95
- | `/analytics:all` | analytics (heartbeat module) | Show tool analytics across all historical sessions. |
96
- | `/analytics:ab` | analytics (heartbeat module) | Show A/B experiment results across variants. |
97
- | `/context-stats` | context-manager (memory module) | Show context pruning statistics. |
98
- | `/rate-cancel` | rate-limiter (contrib) | Cancel the rate limiter wait and reset its state. |
99
- | `/tool-status` | tool-config (contrib) | Show current tool configuration. |
100
- | `/browser-start` | browser (contrib) | Spawn Chrome with remote debugging; `--profile` syncs cookies and logins. |
101
- | `/browser-connect` | browser (contrib) | Connect to Chrome at :9222 (auto-starts if not running). |
102
- | `/browser-disconnect` | browser (contrib) | Disconnect from the browser session. |
103
- | `/utility-model` | polyfill (core) | Set or show the utility model for classification tasks; accepts one model or an ordered list (comma-separated), tried in order until the provider layer reports a route usable. |
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.41",
4
- "sha": "3caa82c28469ebde9b6110fccf75e676fdc51194",
5
- "shaShort": "3caa82c2",
3
+ "version": "0.43.43",
4
+ "sha": "faafcad8ff2d1ffaa02e18245e334016e5be6e95",
5
+ "shaShort": "faafcad8",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-11-09T22:40:43.361Z"
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 whisper carries a BOUNDED
58
- * excerpt of the matching skill's SKILL.md body (frontmatter stripped,
59
- * ≤ MAX_EXCERPT_CHARS) plus an explicit read pointer to the full file —
60
- * so skill content actually reaches the agent's view at the moment a
61
- * domain matches, not just a truncated description. Best-effort: an
62
- * unreadable file falls back to the description.
63
- * 6. No reply ritual: the whisper points at the SKILL.md read and stops
64
- * there — a read is the conversion signal, and the solicited one-line
65
- * reply is honored 2% of the time (channel noise, not information).
66
- * 7. Adoption counter: per-skill `suggested`/`loaded` counters,
67
- * incremented on delivery and on load, surfaced by the `skill_stats`
68
- * tool. `suggested` counts DELIVERED suggestions: the counter increments
69
- * only after `sendTrackedMessage` reports the whisper was accepted, so
70
- * the number measures the suggestion channel rather than the intent to
71
- * use it. A load has two evidence grades — a verbal claim (the LOADED
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 suggestion whisper,
143
- * per skill. Bounded so the steer stays a whisper (~2 skills × 300 chars +
144
- * boilerplate). The whisper always points at the full file for the rest.
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
- * Each bullet carries a BOUNDED excerpt of the SKILL.md body (frontmatter
420
- * stripped, ≤ MAX_EXCERPT_CHARS, collapsed to one line) plus an explicit
421
- * read pointer to the full file — the agent sees real skill content at the
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). */