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.
@@ -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
- - **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. The retired LOADED/SKIP reply is no longer solicited; `claimed` keeps its historical honor-system meaning and stays monotone.
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 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
@@ -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 suggestion whisper,
188
- * per skill. Bounded so the steer stays a whisper (~2 skills × 300 chars +
189
- * boilerplate). The whisper always points at the full file for the rest.
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
- * Bounded excerpt of a skill body: strip frontmatter, trim, cap at maxChars,
874
- * mark truncation. Pure.
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 extractSkillExcerpt(content: string, maxChars: number = MAX_EXCERPT_CHARS): string {
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
- const slice = (boundary > maxChars * 0.6 ? cut.slice(0, boundary) : cut).trimEnd();
883
- return slice + "…";
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
- * Each bullet carries a BOUNDED excerpt of the SKILL.md body (frontmatter
908
- * stripped, ≤ MAX_EXCERPT_CHARS, collapsed to one line) plus an explicit
909
- * read pointer to the full file — the agent sees real skill content at the
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
- const lines = skills.map((s) => {
915
- const excerpt = readSkillExcerpt(s.filePath) || s.description;
916
- // Strip the truncation mark (if any) — the read pointer follows immediately.
917
- const lead = toOneLine(excerpt)
918
- .slice(0, MAX_EXCERPT_CHARS)
919
- .replace(/\.\.\.$/, "")
920
- .replace(/…$/, "");
921
- return `- ${s.name}: ${lead} — read \`${s.filePath}\` for the full skill.`;
922
- });
923
- return (
924
- `[SKILL SUGGESTION] These skills match your current task; their content is excerpted below:\n` +
925
- lines.join("\n") +
926
- `\n(Use \`list_skills\` to see all available skills; read a SKILL.md file for full context.)`
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
- const text = formatWhisper(skillsToInject);
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
  }
@@ -30,8 +30,8 @@ and emits alerts on degradation/anomaly.
30
30
 
31
31
  _(None - both `get_session_metrics` and `get_tool_reliability` removed in <!-- doc-ref-exempt: removed tool named as history -->
32
32
  2026-06 tool-inventory audit. They were passive observability with no
33
- internal consumers. Background tracking and the `analytics:all` slash
34
- command remain.)_
33
+ internal consumers. Background tracking and the `/analytics all` scope
34
+ remain.)_
35
35
 
36
36
  ## Event-bus contract
37
37
 
@@ -17,7 +17,7 @@ import {
17
17
  } from "../../../lib/state/session-start-queue.js";
18
18
  import { existsSync, mkdirSync } from "node:fs";
19
19
  import { metricsDir, metricsFilePath } from "../../../lib/config/braid-paths.js";
20
- import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
20
+ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
21
21
  import { safeSessionManagerTyped } from "../../../lib/state/extension-state.js";
22
22
  import { emitSignal } from "../../../lib/reasoning/belief-policy-engine.js";
23
23
  import { eventBus } from "../../../lib/events/event-bus.js";
@@ -53,6 +53,40 @@ import {
53
53
 
54
54
  const log = createLogger("analytics");
55
55
 
56
+ /** The three reports one command prints, keyed by the verb a script types. */
57
+ const ANALYTICS_SCOPES: Record<
58
+ string,
59
+ { label: string; render: (ctx: ExtensionCommandContext) => string }
60
+ > = {
61
+ session: {
62
+ label: "This session",
63
+ render: (ctx) => formatCurrentSession(getAnalyticsStateInternal(ctx)),
64
+ },
65
+ all: { label: "All sessions", render: () => formatAllSessions() },
66
+ ab: { label: "A/B variants", render: () => formatABResults() },
67
+ };
68
+
69
+ /** Print one scope through the formatter that scope already owned. */
70
+ function showAnalyticsScope(scope: string, ctx: ExtensionCommandContext): void {
71
+ ctx.ui.notify(ANALYTICS_SCOPES[scope].render(ctx), "info");
72
+ }
73
+
74
+ /** No argument: ask the scope in the TUI; headless prints the default scope. */
75
+ async function pickAnalyticsScope(ctx: ExtensionCommandContext): Promise<void> {
76
+ if (ctx.mode !== "tui") {
77
+ ctx.ui.notify(
78
+ `${ANALYTICS_SCOPES.session.render(ctx)}\n\nOther scopes: /analytics all, /analytics ab`,
79
+ "info",
80
+ );
81
+ return;
82
+ }
83
+ const labels = Object.values(ANALYTICS_SCOPES).map((scope) => scope.label);
84
+ const chosen = await ctx.ui.select("Analytics scope", labels);
85
+ if (chosen === undefined) return;
86
+ const scope = Object.keys(ANALYTICS_SCOPES).find((key) => ANALYTICS_SCOPES[key].label === chosen);
87
+ if (scope) showAnalyticsScope(scope, ctx);
88
+ }
89
+
56
90
  export default function analyticsExtension(pi: ExtensionAPI) {
57
91
  registerSessionStartHandler(pi, SessionPhase.MemoryState, async (_event, ctx) => {
58
92
  resetCriticStats();
@@ -344,30 +378,27 @@ export default function analyticsExtension(pi: ExtensionAPI) {
344
378
  });
345
379
 
346
380
  pi.registerCommand("analytics", {
347
- description: "Show tool analytics for the current session",
348
- handler: async (_args, ctx) => {
349
- ctx.ui.notify(formatCurrentSession(getAnalyticsStateInternal(ctx)), "info");
350
- },
351
- });
352
- pi.registerCommand("analytics:all", {
353
- description: "Show tool analytics across all historical sessions",
354
- handler: async (_args, _ctx) => {
355
- _ctx.ui.notify(formatAllSessions(), "info");
356
- },
357
- });
358
- // The A/B variant is set through the tool below, not a slash command, so
359
- // the agent can set its own variant without a human-typed command.
360
- pi.registerCommand("analytics:ab", {
361
- description: "Show A/B experiment results across variants",
362
- handler: async (_args, ctx) => {
363
- ctx.ui.notify(formatABResults(), "info");
381
+ description:
382
+ "Show tool analytics. No argument asks the scope in the TUI. " +
383
+ "Usage: /analytics [session|all|ab]",
384
+ handler: async (args, ctx) => {
385
+ const scope = (args ?? "").trim().toLowerCase();
386
+ if (scope === "") {
387
+ await pickAnalyticsScope(ctx);
388
+ return;
389
+ }
390
+ if (!(scope in ANALYTICS_SCOPES)) {
391
+ ctx.ui.notify(`Unknown scope "${scope}". Usage: /analytics [session|all|ab]`, "warning");
392
+ return;
393
+ }
394
+ showAnalyticsScope(scope, ctx);
364
395
  },
365
396
  });
366
397
 
367
398
  // No agent-callable observability tools here (session metrics / tool
368
399
  // reliability): the agent rarely needs self-observability and no internal
369
400
  // caller used them. Background tracking (toolMetrics, sessionStartTime)
370
- // still runs and feeds event-bus alerts and the analytics:all command; the
401
+ // still runs and feeds event-bus alerts and the analytics scopes; the
371
402
  // A/B variant is set programmatically via
372
403
  // getAnalyticsStateInternal(ctx).abVariant.
373
404
  }
package/src/index.ts CHANGED
@@ -18,8 +18,6 @@
18
18
  * Subagent API:
19
19
  * Researcher subagents can call `/modules` (verbs: on, off, toggle, reset,
20
20
  * all on|off, list) to control extension loading during benchmark experiments.
21
- * The six former names (modules-enable, modules-disable, modules-toggle,
22
- * modules-reset, modules-list, modules-status) forward to it for one release.
23
21
  */
24
22
 
25
23
  import { readFileSync } from "node:fs";
@@ -12,10 +12,10 @@ that it contains the **loader** (and the related subagent API), not
12
12
 
13
13
  ## Files
14
14
 
15
- | File | Purpose |
16
- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
17
- | `loader.ts` | Resolves `BRAID_MODULES` / `braid.modules` (pi global, pi project, braid's store) / runtime overrides into an enabled set, topologically sorts by dependency, and invokes each factory. |
18
- | `api.ts` | Registers `/modules` (verbs: `on`, `off`, `toggle`, `reset`, `all on | off`, `list`) for the subagent API, plus the six former command names as forwarding aliases. |
15
+ | File | Purpose |
16
+ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
17
+ | `loader.ts` | Resolves `BRAID_MODULES` / `braid.modules` (pi global, pi project, braid's store) / runtime overrides into an enabled set, topologically sorts by dependency, and invokes each factory. |
18
+ | `api.ts` | Registers `/modules` (verbs: `on`, `off`, `toggle`, `reset`, `all on` / `off`, `list`) for the subagent API, and states that a contrib extension is toggled through `braid.contrib`, not from this list. |
19
19
 
20
20
  ## Layer position
21
21