pi-braid 0.43.42 → 0.43.44
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 +35 -0
- 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/docs/LOCAL_DEV.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/CHANGELOG.md
CHANGED
|
@@ -80,6 +80,23 @@ record; the tag scheme above applies unchanged.
|
|
|
80
80
|
contract; a new fixture covers both trees, the scoping and the absent-versus-empty
|
|
81
81
|
populations.
|
|
82
82
|
|
|
83
|
+
## Core — 0.43.44 (2026-11-10: the version that carries the telegram release)
|
|
84
|
+
|
|
85
|
+
No core change. The `pi-braid-telegram` bump to 0.1.9 rides on a core version so the release line
|
|
86
|
+
stays ordered; the fix itself is described in the Telegram section below.
|
|
87
|
+
|
|
88
|
+
## Telegram — 0.1.9 (2026-11-10: the lock names the boot by the kernel's id, not the clock)
|
|
89
|
+
|
|
90
|
+
`kern.boottime` is the wall clock minus uptime, so a clock step moves it and two processes on one
|
|
91
|
+
boot compute different instance identities. A handover then reads the lock as held across
|
|
92
|
+
namespaces and the channel cannot be taken: measured twice, the second time after a restart moved
|
|
93
|
+
the boot time by two seconds. The lock now prefers `/proc/sys/kernel/random/boot_id`, then
|
|
94
|
+
`kern.bootsessionuuid` on darwin, and keeps `kern.boottime` only as the documented last resort.
|
|
95
|
+
|
|
96
|
+
The fix was written and has been carried inside core since 0.43.30, but the standalone extension
|
|
97
|
+
the agent loads is this package, and it had not been published since 0.1.8: the running poller's
|
|
98
|
+
lock still carried a boottime identity. This release is the fix reaching the process that uses it.
|
|
99
|
+
|
|
83
100
|
## Telegram — 0.1.8 (2026-11-04: a pre-identity lock is judged by its pid, so a dead holder cannot wedge the channel)
|
|
84
101
|
|
|
85
102
|
- **The legacy arm has three outcomes instead of a permanent refusal.** A lock
|
|
@@ -96,6 +113,24 @@ record; the tag scheme above applies unchanged.
|
|
|
96
113
|
note that a clean disable releases it, because a refusal an operator cannot act on
|
|
97
114
|
is a support ticket.
|
|
98
115
|
|
|
116
|
+
## Core — 0.43.43 (2026-11-10: the matched skill arrives whole, once)
|
|
117
|
+
|
|
118
|
+
The auto-inject whisper used to carry a 300-character excerpt of the best-matching skill and a
|
|
119
|
+
pointer to the file, so a session that never followed the pointer had three hundred characters of a
|
|
120
|
+
skill that is often twenty kilobytes. The best match now arrives whole: its body is delivered in the
|
|
121
|
+
whisper up to `FULL_BODY_MAX_CHARS` (12,000 characters, about 3,000 tokens at the pack's divisor),
|
|
122
|
+
frontmatter stripped, cut once at a word boundary when the body runs past the cap, with a line that
|
|
123
|
+
names the file and the remainder. Ranks two and three stay bounded at `MAX_EXCERPT_CHARS`, so the
|
|
124
|
+
whisper cannot grow with the number of matches, and a skill delivered in full once is not delivered
|
|
125
|
+
again in the same session.
|
|
126
|
+
|
|
127
|
+
Measured, not estimated: the payload at the cap is 11,880 characters and 2,970 estimated tokens over
|
|
128
|
+
the pointer row it replaces. The delivery is counted beside `suggested` in the session counters and
|
|
129
|
+
in `skills-usage.json`, so the effect is readable from the counters rather than felt.
|
|
130
|
+
|
|
131
|
+
The identity paragraph in `loading-guidance.ts` is unchanged: it remains the fallback for a skill no
|
|
132
|
+
trigger matched.
|
|
133
|
+
|
|
99
134
|
## Core — 0.43.42 (2026-11-10: ten commands, one per object)
|
|
100
135
|
|
|
101
136
|
- **The six `/modules-*` names are gone.** They forwarded to `/modules` for three releases (0.43.39 to
|
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.44",
|
|
4
|
+
"sha": "ced405d5d39735e56ba7b2079c95b75371153e99",
|
|
5
|
+
"shaShort": "ced405d5",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-11-
|
|
8
|
+
"packedAt": "2026-11-10T18:51:20.198Z"
|
|
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). */
|
|
@@ -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
|
|
@@ -154,11 +163,31 @@ export const LOADED_COOLDOWN_TURNS = 30;
|
|
|
154
163
|
/** Minimum keyword length to consider significant. */
|
|
155
164
|
const MIN_KEYWORD_LENGTH = 4;
|
|
156
165
|
/**
|
|
157
|
-
* Max characters of SKILL.md body content carried in a
|
|
158
|
-
*
|
|
159
|
-
*
|
|
166
|
+
* Max characters of SKILL.md body content carried in a POINTER row, per
|
|
167
|
+
* skill: the excerpt every match below the top rank gets, and the fallback
|
|
168
|
+
* for a top match whose file cannot be read (~2 rows × 300 chars +
|
|
169
|
+
* boilerplate). Unchanged by the body tier below; the row always points at
|
|
170
|
+
* the full file for the rest.
|
|
160
171
|
*/
|
|
161
172
|
export const MAX_EXCERPT_CHARS = 300;
|
|
173
|
+
/**
|
|
174
|
+
* Max characters of a SKILL.md body delivered first-class: the whole text of
|
|
175
|
+
* the whisper's best match, frontmatter stripped.
|
|
176
|
+
*
|
|
177
|
+
* The number is measured against the shipped pack, not picked. The 34 skill
|
|
178
|
+
* bodies run 385 to 29,997 characters, median 6,614, and 23 of them fit
|
|
179
|
+
* inside 12,000 whole; the ones past it are reference documents whose
|
|
180
|
+
* remainder is one read away and now named at the cut. Under the divisor the
|
|
181
|
+
* rest of the surface prices a read with (CHARS_PER_TOKEN = 4, also pi-core's
|
|
182
|
+
* estimateTokens), a body at the cap is 3,000 estTokens.
|
|
183
|
+
*
|
|
184
|
+
* That is the payload of one delivery: a body, plus at most MAX_EXCERPT_CHARS
|
|
185
|
+
* per other row, at most MAX_INJECTED rows. The read it stands in for costs
|
|
186
|
+
* the same body characters plus a tool call and a round trip, so a body
|
|
187
|
+
* delivered whole is never dearer than the conversion it removes; a body past
|
|
188
|
+
* the cap costs the cap and says where the rest is.
|
|
189
|
+
*/
|
|
190
|
+
export const FULL_BODY_MAX_CHARS = 12_000;
|
|
162
191
|
/**
|
|
163
192
|
* Minimum score for a skill whose match never touches its NAME (description
|
|
164
193
|
* and/or filePath keyword hits only). Name matches qualify at any score.
|
|
@@ -272,6 +301,7 @@ function getState(ctx) {
|
|
|
272
301
|
drift: initialDrift(),
|
|
273
302
|
applicability: initialApplicability(),
|
|
274
303
|
obligations: initialObligations(),
|
|
304
|
+
fullBodies: new Set(),
|
|
275
305
|
}));
|
|
276
306
|
}
|
|
277
307
|
// Shared module-level variable rather than a per-module copy: the import
|
|
@@ -654,18 +684,27 @@ export function stripSkillFrontmatter(content) {
|
|
|
654
684
|
return text; // no closing delimiter — treat the whole doc as body
|
|
655
685
|
}
|
|
656
686
|
/**
|
|
657
|
-
*
|
|
658
|
-
* mark
|
|
687
|
+
* Whole body when it fits, else a cut at a word boundary with the truncation
|
|
688
|
+
* mark. Pure.
|
|
689
|
+
*
|
|
690
|
+
* One rule for both tiers: a pointer row's 300-character excerpt and a
|
|
691
|
+
* first-class body at FULL_BODY_MAX_CHARS cut the same way, so a body ending
|
|
692
|
+
* mid-word reads as a cut in either, and the cut lands at whitespace whenever
|
|
693
|
+
* the text carries any in the last stretch before the cap.
|
|
659
694
|
*/
|
|
660
|
-
export function
|
|
661
|
-
const body = stripSkillFrontmatter(content).trim();
|
|
695
|
+
export function cutSkillBody(body, maxChars) {
|
|
662
696
|
if (body.length <= maxChars)
|
|
663
697
|
return body;
|
|
664
698
|
const cut = body.slice(0, maxChars);
|
|
665
|
-
// Cut at a word boundary when possible; always collapse trailing whitespace.
|
|
666
699
|
const boundary = cut.lastIndexOf(" ");
|
|
667
|
-
|
|
668
|
-
|
|
700
|
+
return (boundary > maxChars * 0.6 ? cut.slice(0, boundary) : cut).trimEnd() + "…";
|
|
701
|
+
}
|
|
702
|
+
/**
|
|
703
|
+
* Bounded excerpt of a skill body: strip frontmatter, trim, cap at maxChars,
|
|
704
|
+
* mark truncation. Pure.
|
|
705
|
+
*/
|
|
706
|
+
export function extractSkillExcerpt(content, maxChars = MAX_EXCERPT_CHARS) {
|
|
707
|
+
return cutSkillBody(stripSkillFrontmatter(content).trim(), maxChars);
|
|
669
708
|
}
|
|
670
709
|
/**
|
|
671
710
|
* Read a SKILL.md from disk and return a bounded body excerpt.
|
|
@@ -680,32 +719,109 @@ export function readSkillExcerpt(filePath, maxChars = MAX_EXCERPT_CHARS) {
|
|
|
680
719
|
return "";
|
|
681
720
|
}
|
|
682
721
|
}
|
|
722
|
+
/**
|
|
723
|
+
* Read a SKILL.md into a deliverable body at the body-tier cap.
|
|
724
|
+
* Returns undefined on any error (missing file, unreadable) AND on an empty
|
|
725
|
+
* body: the caller stays on the pointer tier, because a body that never
|
|
726
|
+
* arrived must not be counted as delivered.
|
|
727
|
+
*/
|
|
728
|
+
export function readSkillBody(filePath, maxChars = FULL_BODY_MAX_CHARS) {
|
|
729
|
+
try {
|
|
730
|
+
const body = stripSkillFrontmatter(readFileSync(filePath, "utf-8")).trim();
|
|
731
|
+
if (!body)
|
|
732
|
+
return undefined;
|
|
733
|
+
return { text: cutSkillBody(body, maxChars), truncated: body.length > maxChars };
|
|
734
|
+
}
|
|
735
|
+
catch {
|
|
736
|
+
return undefined;
|
|
737
|
+
}
|
|
738
|
+
}
|
|
683
739
|
/** Collapse whitespace/newlines to single spaces for a one-line whisper bullet. */
|
|
684
740
|
function toOneLine(text) {
|
|
685
741
|
return text.replace(/\s+/g, " ").trim();
|
|
686
742
|
}
|
|
743
|
+
/** The whisper's opening line when every row is a pointer. */
|
|
744
|
+
const WHISPER_HEADER = "[SKILL SUGGESTION] These skills match your current task; their content is excerpted below:";
|
|
745
|
+
/** The closing catalog pointer every message carries. */
|
|
746
|
+
const WHISPER_TRAILER = "(Use `list_skills` to see all available skills; read a SKILL.md file for full context.)";
|
|
747
|
+
/**
|
|
748
|
+
* One pointer row: a bounded body excerpt (or the description when the file
|
|
749
|
+
* is unreadable), collapsed to one line, followed by the read pointer.
|
|
750
|
+
*/
|
|
751
|
+
function pointerRow(skill) {
|
|
752
|
+
const excerpt = readSkillExcerpt(skill.filePath) || skill.description;
|
|
753
|
+
// Strip the truncation mark (if any) — the read pointer follows immediately.
|
|
754
|
+
const lead = toOneLine(excerpt)
|
|
755
|
+
.slice(0, MAX_EXCERPT_CHARS)
|
|
756
|
+
.replace(/\.\.\.$/, "")
|
|
757
|
+
.replace(/…$/, "");
|
|
758
|
+
return `- ${skill.name}: ${lead} — read \`${skill.filePath}\` for the full skill.`;
|
|
759
|
+
}
|
|
760
|
+
/**
|
|
761
|
+
* Format the steer whisper for a recommendation, in two tiers.
|
|
762
|
+
*
|
|
763
|
+
* `fullBodySkill` names the one skill whose SKILL.md body the message carries
|
|
764
|
+
* first-class. The caller decides it from the session's already-delivered set
|
|
765
|
+
* (see pickFullBodySkill), so a re-match, an unreadable file or a skill this
|
|
766
|
+
* session already received leaves the message on the pointer tier.
|
|
767
|
+
*
|
|
768
|
+
* A body inside the cap is delivered whole and the message says so, which is
|
|
769
|
+
* what makes the read call unnecessary for that skill; a body past it is cut
|
|
770
|
+
* once at a word boundary, the file is named, and the message says the rest
|
|
771
|
+
* is there. Every other row keeps the pointer tier: MAX_EXCERPT_CHARS of
|
|
772
|
+
* body, one line, plus the path.
|
|
773
|
+
*
|
|
774
|
+
* The returned `body` is the fact the counter and the once-per-session record
|
|
775
|
+
* are written from, and it is present only when a body actually landed.
|
|
776
|
+
*/
|
|
777
|
+
export function formatWhisperContent(skills, fullBodySkill) {
|
|
778
|
+
const lead = fullBodySkill ? skills.find((s) => s.name === fullBodySkill) : undefined;
|
|
779
|
+
const body = lead ? readSkillBody(lead.filePath) : undefined;
|
|
780
|
+
if (!lead || !body) {
|
|
781
|
+
return { text: `${WHISPER_HEADER}\n${skills.map(pointerRow).join("\n")}\n${WHISPER_TRAILER}` };
|
|
782
|
+
}
|
|
783
|
+
const rows = skills.filter((s) => s.name !== lead.name).map(pointerRow);
|
|
784
|
+
const parts = [
|
|
785
|
+
body.truncated
|
|
786
|
+
? `[SKILL SUGGESTION] ${lead.name} is the best match for this task; its text is included below up to ${FULL_BODY_MAX_CHARS} characters.`
|
|
787
|
+
: `[SKILL SUGGESTION] ${lead.name} is the best match for this task; its full text is included below, so no read call is needed for it.`,
|
|
788
|
+
"",
|
|
789
|
+
body.truncated
|
|
790
|
+
? `## ${lead.name} (first ${FULL_BODY_MAX_CHARS} characters, \`${lead.filePath}\`)`
|
|
791
|
+
: `## ${lead.name} (full text, \`${lead.filePath}\`)`,
|
|
792
|
+
body.text,
|
|
793
|
+
];
|
|
794
|
+
if (body.truncated) {
|
|
795
|
+
parts.push("", `The rest of ${lead.name} is in \`${lead.filePath}\`; read it for the remainder.`);
|
|
796
|
+
}
|
|
797
|
+
if (rows.length)
|
|
798
|
+
parts.push("", rows.join("\n"));
|
|
799
|
+
parts.push("", WHISPER_TRAILER);
|
|
800
|
+
return { text: parts.join("\n"), body: { name: lead.name, truncated: body.truncated } };
|
|
801
|
+
}
|
|
687
802
|
/**
|
|
688
803
|
* Format the steer whisper content for a set of recommended skills.
|
|
689
804
|
*
|
|
690
|
-
*
|
|
691
|
-
*
|
|
692
|
-
*
|
|
693
|
-
* moment of domain match, not just a truncated description. Unreadable
|
|
694
|
-
* files fall back to the description (also bounded, one line).
|
|
805
|
+
* `skills` arrives ranked (best first). The text is the pointer tier for
|
|
806
|
+
* every row; pass `fullBodySkill` to deliver one body first-class — see
|
|
807
|
+
* formatWhisperContent, which this delegates to.
|
|
695
808
|
*/
|
|
696
|
-
export function formatWhisper(skills) {
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
809
|
+
export function formatWhisper(skills, fullBodySkill) {
|
|
810
|
+
return formatWhisperContent(skills, fullBodySkill).text;
|
|
811
|
+
}
|
|
812
|
+
/**
|
|
813
|
+
* Which skill the whisper may carry first-class: the best-ranked match, and
|
|
814
|
+
* only while this session has not delivered that skill's body already.
|
|
815
|
+
*
|
|
816
|
+
* The rule fixes the payload at one body per message and one per skill per
|
|
817
|
+
* session. A re-match is a pointer because the body is in context; a lower
|
|
818
|
+
* rank is never expanded because the rank is what the body tier is for. Pure.
|
|
819
|
+
*/
|
|
820
|
+
export function pickFullBodySkill(ranked, delivered) {
|
|
821
|
+
const top = ranked[0];
|
|
822
|
+
if (!top)
|
|
823
|
+
return undefined;
|
|
824
|
+
return delivered.has(top.name) ? undefined : top.name;
|
|
709
825
|
}
|
|
710
826
|
const STATS_KEY = "skills-usage-stats";
|
|
711
827
|
function getStats(ctx) {
|
|
@@ -720,7 +836,7 @@ export function getSkillStats(ctx) {
|
|
|
720
836
|
export function recordSkillSuggestion(ctx, names) {
|
|
721
837
|
const stats = getStats(ctx);
|
|
722
838
|
for (const name of names) {
|
|
723
|
-
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0 });
|
|
839
|
+
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0, fullBody: 0 });
|
|
724
840
|
s.suggested++;
|
|
725
841
|
recordDurable(name, "suggested");
|
|
726
842
|
}
|
|
@@ -735,7 +851,7 @@ export function recordSkillLoad(ctx, name) {
|
|
|
735
851
|
if (!name)
|
|
736
852
|
return;
|
|
737
853
|
const stats = getStats(ctx);
|
|
738
|
-
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0 });
|
|
854
|
+
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0, fullBody: 0 });
|
|
739
855
|
s.loaded++;
|
|
740
856
|
s.actual++;
|
|
741
857
|
recordDurable(name, "actual");
|
|
@@ -751,11 +867,29 @@ export function recordSkillClaim(ctx, name) {
|
|
|
751
867
|
if (!name)
|
|
752
868
|
return;
|
|
753
869
|
const stats = getStats(ctx);
|
|
754
|
-
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0 });
|
|
870
|
+
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0, fullBody: 0 });
|
|
755
871
|
s.loaded++;
|
|
756
872
|
s.claimed++;
|
|
757
873
|
recordDurable(name, "claim");
|
|
758
874
|
}
|
|
875
|
+
/**
|
|
876
|
+
* Record a FIRST-CLASS BODY delivery: the whisper carried this skill's body as
|
|
877
|
+
* its payload rather than a bounded excerpt.
|
|
878
|
+
*
|
|
879
|
+
* `suggested` moved for the same message, so the pair reads "of the
|
|
880
|
+
* suggestions delivered, how many arrived whole" without a second channel to
|
|
881
|
+
* instrument later. Only a body that actually landed in a delivered message is
|
|
882
|
+
* recorded: a suppressed whisper moves neither counter, and an unreadable file
|
|
883
|
+
* leaves the message on the pointer tier.
|
|
884
|
+
*/
|
|
885
|
+
export function recordSkillFullDelivery(ctx, name) {
|
|
886
|
+
if (!name)
|
|
887
|
+
return;
|
|
888
|
+
const stats = getStats(ctx);
|
|
889
|
+
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0, fullBody: 0 });
|
|
890
|
+
s.fullBody++;
|
|
891
|
+
recordDurable(name, "fullBody");
|
|
892
|
+
}
|
|
759
893
|
let _durableStore;
|
|
760
894
|
/** Normalize one raw file entry; undefined when the entry is not usable. */
|
|
761
895
|
function normalizeDurableEntry(raw) {
|
|
@@ -770,11 +904,15 @@ function normalizeDurableEntry(raw) {
|
|
|
770
904
|
const actual = typeof r.actual === "number" && Number.isFinite(r.actual)
|
|
771
905
|
? r.actual
|
|
772
906
|
: Math.max(0, loaded - claimed);
|
|
907
|
+
// Rows written before the body tier carry no fullBody: the count starts at
|
|
908
|
+
// zero for them, the same way a legacy row's claimed starts at zero.
|
|
909
|
+
const fullBody = typeof r.fullBody === "number" && Number.isFinite(r.fullBody) ? r.fullBody : 0;
|
|
773
910
|
return {
|
|
774
911
|
suggested,
|
|
775
912
|
loaded,
|
|
776
913
|
claimed,
|
|
777
914
|
actual,
|
|
915
|
+
fullBody,
|
|
778
916
|
lastAt: typeof r.lastAt === "string" ? r.lastAt : "",
|
|
779
917
|
// Rows without an epoch predate the split: their `suggested` may mix
|
|
780
918
|
// pre-delivery-regime increments with delivered ones.
|
|
@@ -849,12 +987,16 @@ function recordDurable(name, kind) {
|
|
|
849
987
|
loaded: 0,
|
|
850
988
|
claimed: 0,
|
|
851
989
|
actual: 0,
|
|
990
|
+
fullBody: 0,
|
|
852
991
|
lastAt: "",
|
|
853
992
|
epoch: "delivered",
|
|
854
993
|
});
|
|
855
994
|
if (kind === "suggested") {
|
|
856
995
|
entry.suggested++;
|
|
857
996
|
}
|
|
997
|
+
else if (kind === "fullBody") {
|
|
998
|
+
entry.fullBody++;
|
|
999
|
+
}
|
|
858
1000
|
else {
|
|
859
1001
|
entry.loaded++;
|
|
860
1002
|
if (kind === "claim")
|
|
@@ -1211,6 +1353,10 @@ function stepInform(pi, ctx, state, ev) {
|
|
|
1211
1353
|
const held = state.obligations.legs.get(skill.name);
|
|
1212
1354
|
if (held?.read)
|
|
1213
1355
|
continue; // the body is in context; the obligation is met
|
|
1356
|
+
// The body arrived first-class in this session's whisper: the line's
|
|
1357
|
+
// premise (a body whose file was never opened) is false, so it stays shut.
|
|
1358
|
+
if (state.fullBodies.has(skill.name))
|
|
1359
|
+
continue;
|
|
1214
1360
|
if (held?.informed)
|
|
1215
1361
|
continue; // one line per session per skill
|
|
1216
1362
|
const delivered = sendTrackedMessage(pi, {
|
|
@@ -1412,7 +1558,11 @@ export function registerAutoInject(pi) {
|
|
|
1412
1558
|
return;
|
|
1413
1559
|
}
|
|
1414
1560
|
const skillsToInject = toInject.map((s) => s.skill);
|
|
1415
|
-
|
|
1561
|
+
// The body tier is the best match's, and only while this session has not
|
|
1562
|
+
// already received that body: the decision is the session's, the render
|
|
1563
|
+
// is the formatter's.
|
|
1564
|
+
const content = formatWhisperContent(skillsToInject, pickFullBodySkill(skillsToInject, state.fullBodies));
|
|
1565
|
+
const text = content.text;
|
|
1416
1566
|
// Delivery first, bookkeeping second: a suggestion that a suppression
|
|
1417
1567
|
// path drops must neither consume its cooldown slot nor move a counter.
|
|
1418
1568
|
// See the module header for why the cap is bypassed here.
|
|
@@ -1424,6 +1574,7 @@ export function registerAutoInject(pi) {
|
|
|
1424
1574
|
[BRAID_INJECTED]: true,
|
|
1425
1575
|
[BRAID_SOURCE]: "skills-auto-inject",
|
|
1426
1576
|
skills: skillsToInject.map((s) => s.name),
|
|
1577
|
+
...(content.body ? { fullBody: content.body.name } : {}),
|
|
1427
1578
|
},
|
|
1428
1579
|
}, { delivery: "park", deliverAs: "steer" }, { type: "context", source: "skills-auto-inject" }, { bypassFloodCap: true });
|
|
1429
1580
|
if (!delivered) {
|
|
@@ -1451,6 +1602,14 @@ export function registerAutoInject(pi) {
|
|
|
1451
1602
|
recordSkillSuggestion(ctx, skillsToInject.map((s) => s.name));
|
|
1452
1603
|
// The same delivery is an obligation leg: the body was offered here.
|
|
1453
1604
|
noteObligationSuggested(ctx, skillsToInject.map((s) => s.name));
|
|
1605
|
+
// The body tier is counted BESIDE the suggestion, not instead of it, and
|
|
1606
|
+
// only now that the message is in the stream: the pair is what makes the
|
|
1607
|
+
// effect measurable from the store. The session set is written with it,
|
|
1608
|
+
// so the next match of the same skill is a pointer.
|
|
1609
|
+
if (content.body) {
|
|
1610
|
+
state.fullBodies.add(content.body.name);
|
|
1611
|
+
recordSkillFullDelivery(ctx, content.body.name);
|
|
1612
|
+
}
|
|
1454
1613
|
}
|
|
1455
1614
|
catch (err) {
|
|
1456
1615
|
log.debug(`[skills-auto-inject] Error in before_agent_start: ${err}`);
|
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -138,7 +138,7 @@ before and after a full run. A non-zero delta is the leak this rule prevents.
|
|
|
138
138
|
### New fixtures: use `node:test`
|
|
139
139
|
|
|
140
140
|
A new fixture is written on `node:test`. The runner does not care which style a
|
|
141
|
-
file uses -
|
|
141
|
+
file uses - 118 of the core suite's 354 fixtures already use `node:test` - so the
|
|
142
142
|
reason is the failure the other style produces. A hand-rolled helper that calls
|
|
143
143
|
`fn()` without awaiting it discards the case's promise, so an `async` case runs
|
|
144
144
|
detached and the file can print its green tally before that case settles, with
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
3
|
+
"version": "0.43.44",
|
|
4
4
|
"description": "🥨 Braid - Metacognitive extension suite for pi coding agent: Adds memory, plan tracking, structured cognitive signals and completion checks on top of pi core loop, so long sessions keep their context and stop claiming unfinished work.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -30,10 +30,11 @@ Two surfaces in `skills-tool/` put a skill body in front of the agent: the auto-
|
|
|
30
30
|
|
|
31
31
|
- **Delivery is observable.** `sendTrackedMessage` returns a boolean: `true` when the message was handed to `pi.sendMessage` (immediately or on the deferred triggerTurn macrotask), `false` when a suppression path dropped it (cognitive nudges disabled, per-turn/per-source flood cap, reprime cooldown). A suggestion is delivered with the park class (`delivery: "park", deliverAs: "steer"`) at source `skills-auto-inject`, which pi-core appends to the session stream - immediately when the session is idle, at the turn's end when a run is active. Both land in the session JSONL; a suppression upstream of `pi.sendMessage` reaches no stream at all.
|
|
32
32
|
- **Counters move after delivery.** `recordSkillSuggestion` runs only on a `true` return, and the cooldown/LRU bookkeeping runs after the send too, so `suggested` counts arrivals and an undelivered suggestion consumes no slot. The suggestion bypasses the per-turn whisper cap (`bypassFloodCap: true`) because prompt-builder's once-per-session hygiene whisper fires earlier in the same `before_agent_start` at the same priority and would otherwise spend the only advisory slot; the module's own budget (cooldown turns, max active suggestions, one send per turn) is the bound that keeps the whisper a whisper.
|
|
33
|
-
- **
|
|
33
|
+
- **The best match's body arrives, once.** The auto-inject whisper carries the whole SKILL.md body (frontmatter stripped) of its best-ranked match, capped at `FULL_BODY_MAX_CHARS`; a body past the cap is cut once at a word boundary, and the message names the file and says the rest is there, so a cut is never silent. Every lower rank stays on the pointer tier (`MAX_EXCERPT_CHARS` of body plus the read path). A body is delivered at most once per skill per session: the session's `fullBodies` set is written with the delivery, and a skill that matches again is a pointer. `fullBody` moves only for the message that carried a body while `suggested` moves for every delivered suggestion, so the share of bodies among deliveries is computable from `skills-usage.json` alone.
|
|
34
|
+
- **Conversion is a detected read.** The whisper asks the agent to open the SKILL.md; the conversion signal is the `read` tool_result (`actual`), which is also what sets `hadSkillLoad` in the durable session record. A skill whose body the whisper already carried needs no read, and that delivery is counted as `fullBody`; the read stays the signal for the rows the message signposted instead. The retired LOADED/SKIP reply is no longer solicited; `claimed` keeps its historical honor-system meaning and stays monotone.
|
|
34
35
|
- **The trigger has a mechanical form.** `skills-tool/loading-guidance.ts` carries both the judgment form (the task entered a listed skill's domain) and the mechanical form (about to call a tool family whose word appears in a skill's name). `prompt-builder` renders that text through the `skillsLoadingText` builder as the `skills-loading` section and holds no copy of the rules; the trigger's worked examples are derived at assembly from the live tool and skill names, so the text names no pair that the running session does not have. The identity's skills prose stays one sentence.
|
|
35
36
|
- **The catalog is in the prompt.** The same section renders every visible skill as one `- name: description` row, with the read path derived from the skills' own file paths (one root for a single pack, a directory heading per pack when a catalog is installed from several). A tool call is no longer the way the agent learns which skills exist: the floor exists because the prompt that opens a resumed session carries no domain vocabulary for a matcher to rank against. `list_skills` remains the price tool (reach, headings, ranking) rather than the catalog.
|
|
36
37
|
- **A retired skill is not advertised.** A SKILL.md whose frontmatter declares `status: merged`, `archived` or `deprecated` stops being advertised and matched, and the file stays on disk as history. The exclusion rides the flag `disable-model-invocation` already owns (derived at cache time in `index.ts`), so the catalog, the suggestion whisper, the at-use line, the accessor and `list_skills` agree without a second concept. The row stays in the unfiltered cache, so a read of the file still resolves.
|
|
37
38
|
- **Drift re-points at the floor.** When the session's own path-taking calls (`read`/`edit`/`write`) accumulate entries in a work area the floor was not rendered against, one steer line names that area and points back at the catalog. The rule and its bounds (two entries, one fire per twelve calls, three per session, quiet for the same window after any skill surface) live in `loading-guidance.ts` beside the floor text; the wiring is the `tool_result` handler in `auto-inject.ts`. Bounds are the whole design: the line is only worth its noise if it stays rare.
|
|
38
|
-
- **The at-use line is observed, never enforced.** With `braid.skills.inform` set to `inform` (default `off`), a `tool_result` whose call **succeeded**, whose tool name yields a family token some visible cached skill declares with `governs:`, and whose obligation row carries no `read` leg emits one steer line naming the file path and the family. It runs after the result exists, returns no replacement, and refuses, delays and rewrites nothing: any gating change can only make it quieter, which is the property that separates it from a refusal gate. The payload is derived from the declaration and the catalogue entry only (the skill's own `filePath`, the token the call's name yields), so no skill name is invented in code and no tool argument is echoed. Once per session per skill, suppressed by the same obligation record the legs write (its `informed` leg), silenced by a read at any point, and hidden skills are never named. `skill_stats` reports it as `inform` from the store: `undecided` below twenty informs, `beats` only when the lower Wilson bound clears the suggestion channel's 18.8% pair conversion, `noise` otherwise.
|
|
39
|
+
- **The at-use line is observed, never enforced.** With `braid.skills.inform` set to `inform` (default `off`), a `tool_result` whose call **succeeded**, whose tool name yields a family token some visible cached skill declares with `governs:`, and whose obligation row carries no `read` leg emits one steer line naming the file path and the family. It runs after the result exists, returns no replacement, and refuses, delays and rewrites nothing: any gating change can only make it quieter, which is the property that separates it from a refusal gate. The payload is derived from the declaration and the catalogue entry only (the skill's own `filePath`, the token the call's name yields), so no skill name is invented in code and no tool argument is echoed. Once per session per skill, suppressed by the same obligation record the legs write (its `informed` leg), silenced by a read or by a first-class body delivery at any point, and hidden skills are never named. `skill_stats` reports it as `inform` from the store: `undecided` below twenty informs, `beats` only when the lower Wilson bound clears the suggestion channel's 18.8% pair conversion, `noise` otherwise.
|
|
39
40
|
- **Applicability is recorded, never enforced.** The counters cannot tell a skill that applied and was ignored from one that never applied, and the sessions that read nothing are mostly sessions no phrase matches. `skills-tool/applicability.ts` decides that difference from the skill's own declaration (the trigger phrases its file carries: frontmatter `trigger:`/`triggers:`, a `## trigger:` body heading, a description `Triggers:` tail), never from the ranking heuristic, with the injector's occurrence boundary and a clause-scoped negation read, so a phrase inside "do not research this" is not a condition met. The verdict is `read` (condition held and a detected read followed), `ignored` (condition held and no read followed), or `not-applicable` (derived: the census's `evaluated` minus the verdict rows); a skill whose file declares no phrase is named `undeclared` rather than judged either way. It reaches disk as `kind: "applicability"` rows in the per-session store (one verdict row per applicable skill keyed on `sessionId` + `skill`, one census row per session) and out through `skill_stats`. It is an observer: it writes no delivery, slot, cooldown, counter or prompt, and it owns no compliance leg. `suggested`/`listed`/`informed`/`read`/`applied` belong to the record that owns each skill's declared tool family; the verdict row joins it on the skill name.
|
|
@@ -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
|
|
@@ -184,12 +193,33 @@ export const LOADED_COOLDOWN_TURNS = 30;
|
|
|
184
193
|
const MIN_KEYWORD_LENGTH = 4;
|
|
185
194
|
|
|
186
195
|
/**
|
|
187
|
-
* Max characters of SKILL.md body content carried in a
|
|
188
|
-
*
|
|
189
|
-
*
|
|
196
|
+
* Max characters of SKILL.md body content carried in a POINTER row, per
|
|
197
|
+
* skill: the excerpt every match below the top rank gets, and the fallback
|
|
198
|
+
* for a top match whose file cannot be read (~2 rows × 300 chars +
|
|
199
|
+
* boilerplate). Unchanged by the body tier below; the row always points at
|
|
200
|
+
* the full file for the rest.
|
|
190
201
|
*/
|
|
191
202
|
export const MAX_EXCERPT_CHARS = 300;
|
|
192
203
|
|
|
204
|
+
/**
|
|
205
|
+
* Max characters of a SKILL.md body delivered first-class: the whole text of
|
|
206
|
+
* the whisper's best match, frontmatter stripped.
|
|
207
|
+
*
|
|
208
|
+
* The number is measured against the shipped pack, not picked. The 34 skill
|
|
209
|
+
* bodies run 385 to 29,997 characters, median 6,614, and 23 of them fit
|
|
210
|
+
* inside 12,000 whole; the ones past it are reference documents whose
|
|
211
|
+
* remainder is one read away and now named at the cut. Under the divisor the
|
|
212
|
+
* rest of the surface prices a read with (CHARS_PER_TOKEN = 4, also pi-core's
|
|
213
|
+
* estimateTokens), a body at the cap is 3,000 estTokens.
|
|
214
|
+
*
|
|
215
|
+
* That is the payload of one delivery: a body, plus at most MAX_EXCERPT_CHARS
|
|
216
|
+
* per other row, at most MAX_INJECTED rows. The read it stands in for costs
|
|
217
|
+
* the same body characters plus a tool call and a round trip, so a body
|
|
218
|
+
* delivered whole is never dearer than the conversion it removes; a body past
|
|
219
|
+
* the cap costs the cap and says where the rest is.
|
|
220
|
+
*/
|
|
221
|
+
export const FULL_BODY_MAX_CHARS = 12_000;
|
|
222
|
+
|
|
193
223
|
/**
|
|
194
224
|
* Minimum score for a skill whose match never touches its NAME (description
|
|
195
225
|
* and/or filePath keyword hits only). Name matches qualify at any score.
|
|
@@ -314,6 +344,12 @@ interface AutoInjectState {
|
|
|
314
344
|
applicability: ApplicabilityState;
|
|
315
345
|
/** What the session did with each skill body it met (see ObligationState). */
|
|
316
346
|
obligations: ObligationState;
|
|
347
|
+
/**
|
|
348
|
+
* Skills whose body the whisper already delivered first-class this session.
|
|
349
|
+
* The same answer obligations.legs gives for the read leg: a body that
|
|
350
|
+
* landed is in context, so the next match is a pointer.
|
|
351
|
+
*/
|
|
352
|
+
fullBodies: Set<string>;
|
|
317
353
|
/**
|
|
318
354
|
* The resolved `braid.skills.inform` policy, read once per session. A
|
|
319
355
|
* settings edit takes effect in the next session, the same way the session
|
|
@@ -373,6 +409,7 @@ function getState(ctx: ExtensionContext): AutoInjectState {
|
|
|
373
409
|
drift: initialDrift(),
|
|
374
410
|
applicability: initialApplicability(),
|
|
375
411
|
obligations: initialObligations(),
|
|
412
|
+
fullBodies: new Set<string>(),
|
|
376
413
|
}));
|
|
377
414
|
}
|
|
378
415
|
|
|
@@ -870,17 +907,27 @@ export function stripSkillFrontmatter(content: string): string {
|
|
|
870
907
|
}
|
|
871
908
|
|
|
872
909
|
/**
|
|
873
|
-
*
|
|
874
|
-
* mark
|
|
910
|
+
* Whole body when it fits, else a cut at a word boundary with the truncation
|
|
911
|
+
* mark. Pure.
|
|
912
|
+
*
|
|
913
|
+
* One rule for both tiers: a pointer row's 300-character excerpt and a
|
|
914
|
+
* first-class body at FULL_BODY_MAX_CHARS cut the same way, so a body ending
|
|
915
|
+
* mid-word reads as a cut in either, and the cut lands at whitespace whenever
|
|
916
|
+
* the text carries any in the last stretch before the cap.
|
|
875
917
|
*/
|
|
876
|
-
export function
|
|
877
|
-
const body = stripSkillFrontmatter(content).trim();
|
|
918
|
+
export function cutSkillBody(body: string, maxChars: number): string {
|
|
878
919
|
if (body.length <= maxChars) return body;
|
|
879
920
|
const cut = body.slice(0, maxChars);
|
|
880
|
-
// Cut at a word boundary when possible; always collapse trailing whitespace.
|
|
881
921
|
const boundary = cut.lastIndexOf(" ");
|
|
882
|
-
|
|
883
|
-
|
|
922
|
+
return (boundary > maxChars * 0.6 ? cut.slice(0, boundary) : cut).trimEnd() + "…";
|
|
923
|
+
}
|
|
924
|
+
|
|
925
|
+
/**
|
|
926
|
+
* Bounded excerpt of a skill body: strip frontmatter, trim, cap at maxChars,
|
|
927
|
+
* mark truncation. Pure.
|
|
928
|
+
*/
|
|
929
|
+
export function extractSkillExcerpt(content: string, maxChars: number = MAX_EXCERPT_CHARS): string {
|
|
930
|
+
return cutSkillBody(stripSkillFrontmatter(content).trim(), maxChars);
|
|
884
931
|
}
|
|
885
932
|
|
|
886
933
|
/**
|
|
@@ -896,35 +943,145 @@ export function readSkillExcerpt(filePath: string, maxChars: number = MAX_EXCERP
|
|
|
896
943
|
}
|
|
897
944
|
}
|
|
898
945
|
|
|
946
|
+
/** A SKILL.md body as the whisper carries it, and whether the cap cut it. */
|
|
947
|
+
export interface SkillBody {
|
|
948
|
+
text: string;
|
|
949
|
+
truncated: boolean;
|
|
950
|
+
}
|
|
951
|
+
|
|
952
|
+
/**
|
|
953
|
+
* Read a SKILL.md into a deliverable body at the body-tier cap.
|
|
954
|
+
* Returns undefined on any error (missing file, unreadable) AND on an empty
|
|
955
|
+
* body: the caller stays on the pointer tier, because a body that never
|
|
956
|
+
* arrived must not be counted as delivered.
|
|
957
|
+
*/
|
|
958
|
+
export function readSkillBody(
|
|
959
|
+
filePath: string,
|
|
960
|
+
maxChars: number = FULL_BODY_MAX_CHARS,
|
|
961
|
+
): SkillBody | undefined {
|
|
962
|
+
try {
|
|
963
|
+
const body = stripSkillFrontmatter(readFileSync(filePath, "utf-8")).trim();
|
|
964
|
+
if (!body) return undefined;
|
|
965
|
+
return { text: cutSkillBody(body, maxChars), truncated: body.length > maxChars };
|
|
966
|
+
} catch {
|
|
967
|
+
return undefined;
|
|
968
|
+
}
|
|
969
|
+
}
|
|
970
|
+
|
|
899
971
|
/** Collapse whitespace/newlines to single spaces for a one-line whisper bullet. */
|
|
900
972
|
function toOneLine(text: string): string {
|
|
901
973
|
return text.replace(/\s+/g, " ").trim();
|
|
902
974
|
}
|
|
903
975
|
|
|
976
|
+
/** The whisper's opening line when every row is a pointer. */
|
|
977
|
+
const WHISPER_HEADER =
|
|
978
|
+
"[SKILL SUGGESTION] These skills match your current task; their content is excerpted below:";
|
|
979
|
+
|
|
980
|
+
/** The closing catalog pointer every message carries. */
|
|
981
|
+
const WHISPER_TRAILER =
|
|
982
|
+
"(Use `list_skills` to see all available skills; read a SKILL.md file for full context.)";
|
|
983
|
+
|
|
984
|
+
/**
|
|
985
|
+
* One pointer row: a bounded body excerpt (or the description when the file
|
|
986
|
+
* is unreadable), collapsed to one line, followed by the read pointer.
|
|
987
|
+
*/
|
|
988
|
+
function pointerRow(skill: CachedSkill): string {
|
|
989
|
+
const excerpt = readSkillExcerpt(skill.filePath) || skill.description;
|
|
990
|
+
// Strip the truncation mark (if any) — the read pointer follows immediately.
|
|
991
|
+
const lead = toOneLine(excerpt)
|
|
992
|
+
.slice(0, MAX_EXCERPT_CHARS)
|
|
993
|
+
.replace(/\.\.\.$/, "")
|
|
994
|
+
.replace(/…$/, "");
|
|
995
|
+
return `- ${skill.name}: ${lead} — read \`${skill.filePath}\` for the full skill.`;
|
|
996
|
+
}
|
|
997
|
+
|
|
998
|
+
/** The body a whisper carried first-class, and whether the cap cut it. */
|
|
999
|
+
export interface DeliveredBody {
|
|
1000
|
+
name: string;
|
|
1001
|
+
truncated: boolean;
|
|
1002
|
+
}
|
|
1003
|
+
|
|
1004
|
+
export interface WhisperContent {
|
|
1005
|
+
/** The message text. */
|
|
1006
|
+
text: string;
|
|
1007
|
+
/** The body carried first-class; absent when the message carried pointers only. */
|
|
1008
|
+
body?: DeliveredBody;
|
|
1009
|
+
}
|
|
1010
|
+
|
|
1011
|
+
/**
|
|
1012
|
+
* Format the steer whisper for a recommendation, in two tiers.
|
|
1013
|
+
*
|
|
1014
|
+
* `fullBodySkill` names the one skill whose SKILL.md body the message carries
|
|
1015
|
+
* first-class. The caller decides it from the session's already-delivered set
|
|
1016
|
+
* (see pickFullBodySkill), so a re-match, an unreadable file or a skill this
|
|
1017
|
+
* session already received leaves the message on the pointer tier.
|
|
1018
|
+
*
|
|
1019
|
+
* A body inside the cap is delivered whole and the message says so, which is
|
|
1020
|
+
* what makes the read call unnecessary for that skill; a body past it is cut
|
|
1021
|
+
* once at a word boundary, the file is named, and the message says the rest
|
|
1022
|
+
* is there. Every other row keeps the pointer tier: MAX_EXCERPT_CHARS of
|
|
1023
|
+
* body, one line, plus the path.
|
|
1024
|
+
*
|
|
1025
|
+
* The returned `body` is the fact the counter and the once-per-session record
|
|
1026
|
+
* are written from, and it is present only when a body actually landed.
|
|
1027
|
+
*/
|
|
1028
|
+
export function formatWhisperContent(
|
|
1029
|
+
skills: CachedSkill[],
|
|
1030
|
+
fullBodySkill?: string,
|
|
1031
|
+
): WhisperContent {
|
|
1032
|
+
const lead = fullBodySkill ? skills.find((s) => s.name === fullBodySkill) : undefined;
|
|
1033
|
+
const body = lead ? readSkillBody(lead.filePath) : undefined;
|
|
1034
|
+
if (!lead || !body) {
|
|
1035
|
+
return { text: `${WHISPER_HEADER}\n${skills.map(pointerRow).join("\n")}\n${WHISPER_TRAILER}` };
|
|
1036
|
+
}
|
|
1037
|
+
const rows = skills.filter((s) => s.name !== lead.name).map(pointerRow);
|
|
1038
|
+
const parts = [
|
|
1039
|
+
body.truncated
|
|
1040
|
+
? `[SKILL SUGGESTION] ${lead.name} is the best match for this task; its text is included below up to ${FULL_BODY_MAX_CHARS} characters.`
|
|
1041
|
+
: `[SKILL SUGGESTION] ${lead.name} is the best match for this task; its full text is included below, so no read call is needed for it.`,
|
|
1042
|
+
"",
|
|
1043
|
+
body.truncated
|
|
1044
|
+
? `## ${lead.name} (first ${FULL_BODY_MAX_CHARS} characters, \`${lead.filePath}\`)`
|
|
1045
|
+
: `## ${lead.name} (full text, \`${lead.filePath}\`)`,
|
|
1046
|
+
body.text,
|
|
1047
|
+
];
|
|
1048
|
+
if (body.truncated) {
|
|
1049
|
+
parts.push(
|
|
1050
|
+
"",
|
|
1051
|
+
`The rest of ${lead.name} is in \`${lead.filePath}\`; read it for the remainder.`,
|
|
1052
|
+
);
|
|
1053
|
+
}
|
|
1054
|
+
if (rows.length) parts.push("", rows.join("\n"));
|
|
1055
|
+
parts.push("", WHISPER_TRAILER);
|
|
1056
|
+
return { text: parts.join("\n"), body: { name: lead.name, truncated: body.truncated } };
|
|
1057
|
+
}
|
|
1058
|
+
|
|
904
1059
|
/**
|
|
905
1060
|
* Format the steer whisper content for a set of recommended skills.
|
|
906
1061
|
*
|
|
907
|
-
*
|
|
908
|
-
*
|
|
909
|
-
*
|
|
910
|
-
* moment of domain match, not just a truncated description. Unreadable
|
|
911
|
-
* files fall back to the description (also bounded, one line).
|
|
1062
|
+
* `skills` arrives ranked (best first). The text is the pointer tier for
|
|
1063
|
+
* every row; pass `fullBodySkill` to deliver one body first-class — see
|
|
1064
|
+
* formatWhisperContent, which this delegates to.
|
|
912
1065
|
*/
|
|
913
|
-
export function formatWhisper(skills: CachedSkill[]): string {
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
1066
|
+
export function formatWhisper(skills: CachedSkill[], fullBodySkill?: string): string {
|
|
1067
|
+
return formatWhisperContent(skills, fullBodySkill).text;
|
|
1068
|
+
}
|
|
1069
|
+
|
|
1070
|
+
/**
|
|
1071
|
+
* Which skill the whisper may carry first-class: the best-ranked match, and
|
|
1072
|
+
* only while this session has not delivered that skill's body already.
|
|
1073
|
+
*
|
|
1074
|
+
* The rule fixes the payload at one body per message and one per skill per
|
|
1075
|
+
* session. A re-match is a pointer because the body is in context; a lower
|
|
1076
|
+
* rank is never expanded because the rank is what the body tier is for. Pure.
|
|
1077
|
+
*/
|
|
1078
|
+
export function pickFullBodySkill(
|
|
1079
|
+
ranked: readonly CachedSkill[],
|
|
1080
|
+
delivered: ReadonlySet<string>,
|
|
1081
|
+
): string | undefined {
|
|
1082
|
+
const top = ranked[0];
|
|
1083
|
+
if (!top) return undefined;
|
|
1084
|
+
return delivered.has(top.name) ? undefined : top.name;
|
|
928
1085
|
}
|
|
929
1086
|
|
|
930
1087
|
// Adoption counters
|
|
@@ -939,6 +1096,8 @@ export interface SkillStats {
|
|
|
939
1096
|
claimed: number;
|
|
940
1097
|
/** Loads detected by the read tool (SKILL.md read via tool_result). */
|
|
941
1098
|
actual: number;
|
|
1099
|
+
/** Whispers that carried this skill's body first-class (whole or capped). */
|
|
1100
|
+
fullBody: number;
|
|
942
1101
|
}
|
|
943
1102
|
|
|
944
1103
|
const STATS_KEY = "skills-usage-stats";
|
|
@@ -957,7 +1116,7 @@ export function getSkillStats(ctx: ExtensionContext): Record<string, SkillStats>
|
|
|
957
1116
|
export function recordSkillSuggestion(ctx: ExtensionContext, names: string[]): void {
|
|
958
1117
|
const stats = getStats(ctx);
|
|
959
1118
|
for (const name of names) {
|
|
960
|
-
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0 });
|
|
1119
|
+
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0, fullBody: 0 });
|
|
961
1120
|
s.suggested++;
|
|
962
1121
|
recordDurable(name, "suggested");
|
|
963
1122
|
}
|
|
@@ -972,7 +1131,7 @@ export function recordSkillSuggestion(ctx: ExtensionContext, names: string[]): v
|
|
|
972
1131
|
export function recordSkillLoad(ctx: ExtensionContext, name: string): void {
|
|
973
1132
|
if (!name) return;
|
|
974
1133
|
const stats = getStats(ctx);
|
|
975
|
-
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0 });
|
|
1134
|
+
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0, fullBody: 0 });
|
|
976
1135
|
s.loaded++;
|
|
977
1136
|
s.actual++;
|
|
978
1137
|
recordDurable(name, "actual");
|
|
@@ -988,12 +1147,30 @@ export function recordSkillLoad(ctx: ExtensionContext, name: string): void {
|
|
|
988
1147
|
export function recordSkillClaim(ctx: ExtensionContext, name: string): void {
|
|
989
1148
|
if (!name) return;
|
|
990
1149
|
const stats = getStats(ctx);
|
|
991
|
-
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0 });
|
|
1150
|
+
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0, fullBody: 0 });
|
|
992
1151
|
s.loaded++;
|
|
993
1152
|
s.claimed++;
|
|
994
1153
|
recordDurable(name, "claim");
|
|
995
1154
|
}
|
|
996
1155
|
|
|
1156
|
+
/**
|
|
1157
|
+
* Record a FIRST-CLASS BODY delivery: the whisper carried this skill's body as
|
|
1158
|
+
* its payload rather than a bounded excerpt.
|
|
1159
|
+
*
|
|
1160
|
+
* `suggested` moved for the same message, so the pair reads "of the
|
|
1161
|
+
* suggestions delivered, how many arrived whole" without a second channel to
|
|
1162
|
+
* instrument later. Only a body that actually landed in a delivered message is
|
|
1163
|
+
* recorded: a suppressed whisper moves neither counter, and an unreadable file
|
|
1164
|
+
* leaves the message on the pointer tier.
|
|
1165
|
+
*/
|
|
1166
|
+
export function recordSkillFullDelivery(ctx: ExtensionContext, name: string): void {
|
|
1167
|
+
if (!name) return;
|
|
1168
|
+
const stats = getStats(ctx);
|
|
1169
|
+
const s = (stats[name] ??= { suggested: 0, loaded: 0, claimed: 0, actual: 0, fullBody: 0 });
|
|
1170
|
+
s.fullBody++;
|
|
1171
|
+
recordDurable(name, "fullBody");
|
|
1172
|
+
}
|
|
1173
|
+
|
|
997
1174
|
// Durable adoption counters (cross-session)
|
|
998
1175
|
|
|
999
1176
|
/**
|
|
@@ -1024,6 +1201,8 @@ export interface DurableSkillStats {
|
|
|
1024
1201
|
claimed: number;
|
|
1025
1202
|
/** All-time count of detected loads (SKILL.md read via the read tool). */
|
|
1026
1203
|
actual: number;
|
|
1204
|
+
/** All-time count of first-class body deliveries (see recordSkillFullDelivery). */
|
|
1205
|
+
fullBody: number;
|
|
1027
1206
|
/** ISO timestamp of the most recent recorded event. */
|
|
1028
1207
|
lastAt: string;
|
|
1029
1208
|
/** Which counting regime `suggested` mixes (see SuggestedEpoch). */
|
|
@@ -1046,11 +1225,15 @@ function normalizeDurableEntry(raw: unknown): DurableSkillStats | undefined {
|
|
|
1046
1225
|
typeof r.actual === "number" && Number.isFinite(r.actual)
|
|
1047
1226
|
? r.actual
|
|
1048
1227
|
: Math.max(0, loaded - claimed);
|
|
1228
|
+
// Rows written before the body tier carry no fullBody: the count starts at
|
|
1229
|
+
// zero for them, the same way a legacy row's claimed starts at zero.
|
|
1230
|
+
const fullBody = typeof r.fullBody === "number" && Number.isFinite(r.fullBody) ? r.fullBody : 0;
|
|
1049
1231
|
return {
|
|
1050
1232
|
suggested,
|
|
1051
1233
|
loaded,
|
|
1052
1234
|
claimed,
|
|
1053
1235
|
actual,
|
|
1236
|
+
fullBody,
|
|
1054
1237
|
lastAt: typeof r.lastAt === "string" ? r.lastAt : "",
|
|
1055
1238
|
// Rows without an epoch predate the split: their `suggested` may mix
|
|
1056
1239
|
// pre-delivery-regime increments with delivered ones.
|
|
@@ -1117,7 +1300,7 @@ function reportDurableFailure(action: string, err: unknown): void {
|
|
|
1117
1300
|
}
|
|
1118
1301
|
|
|
1119
1302
|
/** Record one durable event and flush to disk (best-effort). */
|
|
1120
|
-
function recordDurable(name: string, kind: "suggested" | "claim" | "actual"): void {
|
|
1303
|
+
function recordDurable(name: string, kind: "suggested" | "claim" | "actual" | "fullBody"): void {
|
|
1121
1304
|
try {
|
|
1122
1305
|
const store = getDurableStore();
|
|
1123
1306
|
const entry = (store[name] ??= {
|
|
@@ -1125,11 +1308,14 @@ function recordDurable(name: string, kind: "suggested" | "claim" | "actual"): vo
|
|
|
1125
1308
|
loaded: 0,
|
|
1126
1309
|
claimed: 0,
|
|
1127
1310
|
actual: 0,
|
|
1311
|
+
fullBody: 0,
|
|
1128
1312
|
lastAt: "",
|
|
1129
1313
|
epoch: "delivered",
|
|
1130
1314
|
});
|
|
1131
1315
|
if (kind === "suggested") {
|
|
1132
1316
|
entry.suggested++;
|
|
1317
|
+
} else if (kind === "fullBody") {
|
|
1318
|
+
entry.fullBody++;
|
|
1133
1319
|
} else {
|
|
1134
1320
|
entry.loaded++;
|
|
1135
1321
|
if (kind === "claim") entry.claimed++;
|
|
@@ -1527,6 +1713,9 @@ function stepInform(
|
|
|
1527
1713
|
if (!skill.families?.length || !skill.families.includes(family)) continue;
|
|
1528
1714
|
const held = state.obligations.legs.get(skill.name);
|
|
1529
1715
|
if (held?.read) continue; // the body is in context; the obligation is met
|
|
1716
|
+
// The body arrived first-class in this session's whisper: the line's
|
|
1717
|
+
// premise (a body whose file was never opened) is false, so it stays shut.
|
|
1718
|
+
if (state.fullBodies.has(skill.name)) continue;
|
|
1530
1719
|
if (held?.informed) continue; // one line per session per skill
|
|
1531
1720
|
const delivered = sendTrackedMessage(
|
|
1532
1721
|
pi,
|
|
@@ -1768,7 +1957,14 @@ export function registerAutoInject(pi: ExtensionAPI): void {
|
|
|
1768
1957
|
}
|
|
1769
1958
|
|
|
1770
1959
|
const skillsToInject = toInject.map((s) => s.skill);
|
|
1771
|
-
|
|
1960
|
+
// The body tier is the best match's, and only while this session has not
|
|
1961
|
+
// already received that body: the decision is the session's, the render
|
|
1962
|
+
// is the formatter's.
|
|
1963
|
+
const content = formatWhisperContent(
|
|
1964
|
+
skillsToInject,
|
|
1965
|
+
pickFullBodySkill(skillsToInject, state.fullBodies),
|
|
1966
|
+
);
|
|
1967
|
+
const text = content.text;
|
|
1772
1968
|
|
|
1773
1969
|
// Delivery first, bookkeeping second: a suggestion that a suppression
|
|
1774
1970
|
// path drops must neither consume its cooldown slot nor move a counter.
|
|
@@ -1783,6 +1979,7 @@ export function registerAutoInject(pi: ExtensionAPI): void {
|
|
|
1783
1979
|
[BRAID_INJECTED]: true,
|
|
1784
1980
|
[BRAID_SOURCE]: "skills-auto-inject",
|
|
1785
1981
|
skills: skillsToInject.map((s) => s.name),
|
|
1982
|
+
...(content.body ? { fullBody: content.body.name } : {}),
|
|
1786
1983
|
},
|
|
1787
1984
|
},
|
|
1788
1985
|
{ delivery: "park", deliverAs: "steer" },
|
|
@@ -1830,6 +2027,14 @@ export function registerAutoInject(pi: ExtensionAPI): void {
|
|
|
1830
2027
|
ctx,
|
|
1831
2028
|
skillsToInject.map((s) => s.name),
|
|
1832
2029
|
);
|
|
2030
|
+
// The body tier is counted BESIDE the suggestion, not instead of it, and
|
|
2031
|
+
// only now that the message is in the stream: the pair is what makes the
|
|
2032
|
+
// effect measurable from the store. The session set is written with it,
|
|
2033
|
+
// so the next match of the same skill is a pointer.
|
|
2034
|
+
if (content.body) {
|
|
2035
|
+
state.fullBodies.add(content.body.name);
|
|
2036
|
+
recordSkillFullDelivery(ctx, content.body.name);
|
|
2037
|
+
}
|
|
1833
2038
|
} catch (err) {
|
|
1834
2039
|
log.debug(`[skills-auto-inject] Error in before_agent_start: ${err}`);
|
|
1835
2040
|
}
|