pi-braid 0.40.5 → 0.40.6

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.
Files changed (85) hide show
  1. package/AGENTS.md +17 -18
  2. package/README.md +116 -130
  3. package/TOOLS.md +35 -35
  4. package/build-info.json +4 -4
  5. package/dist/extensions/core/agent-environment/index.js +4 -3
  6. package/dist/extensions/core/prompt-builder/index.js +12 -7
  7. package/dist/extensions/core/prompt-builder/instance-composition.d.ts +51 -10
  8. package/dist/extensions/core/prompt-builder/instance-composition.js +87 -14
  9. package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +3 -3
  10. package/dist/extensions/core/prompt-builder/system-info-tool.js +3 -3
  11. package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
  12. package/dist/extensions/core/skills-tool/auto-inject.d.ts +89 -10
  13. package/dist/extensions/core/skills-tool/auto-inject.js +150 -21
  14. package/dist/extensions/core/skills-tool/index.d.ts +70 -2
  15. package/dist/extensions/core/skills-tool/index.js +149 -15
  16. package/dist/extensions/core/skills-tool/reach.d.ts +119 -0
  17. package/dist/extensions/core/skills-tool/reach.js +213 -0
  18. package/dist/extensions/core/skills-tool/skill-triggers.d.ts +47 -10
  19. package/dist/extensions/core/skills-tool/skill-triggers.js +66 -23
  20. package/dist/extensions/enforcement/handlers/register-session-compact.js +12 -1
  21. package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +15 -34
  22. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +2 -1
  23. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +55 -28
  24. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +14 -10
  25. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +88 -82
  26. package/dist/extensions/enforcement/resume-state.d.ts +76 -0
  27. package/dist/extensions/enforcement/resume-state.js +90 -0
  28. package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +9 -0
  29. package/dist/extensions/enforcement/substate/context-hygiene-state.js +8 -0
  30. package/dist/extensions/enforcement/whisper.d.ts +12 -0
  31. package/dist/extensions/enforcement/whisper.js +16 -1
  32. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +14 -6
  33. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +7 -0
  34. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +372 -0
  35. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +8 -2
  36. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +54 -21
  37. package/dist/lib/config/braid-paths.d.ts +14 -0
  38. package/dist/lib/config/braid-paths.js +18 -0
  39. package/dist/lib/config/braid-settings.d.ts +21 -0
  40. package/dist/lib/config/braid-settings.js +16 -0
  41. package/dist/lib/detection/context-tiers.d.ts +47 -3
  42. package/dist/lib/detection/context-tiers.js +122 -13
  43. package/dist/lib/events/turn-boundary.d.ts +78 -0
  44. package/dist/lib/events/turn-boundary.js +91 -0
  45. package/dist/lib/orchestrator/workers.d.ts +3 -2
  46. package/dist/lib/orchestrator/workers.js +22 -4
  47. package/dist/lib/state/global-state.d.ts +1 -1
  48. package/docs/CONTEXT-POLICY.md +8 -0
  49. package/docs/LOCAL_DEV.md +0 -1
  50. package/docs/ROADMAP.md +5 -5
  51. package/docs/SETUP.md +19 -18
  52. package/package.json +1 -1
  53. package/skills/herdr-topology/SKILL.md +6 -1
  54. package/skills/research/SKILL.md +32 -0
  55. package/skills/subagent-orchestration/SKILL.md +2 -2
  56. package/src/extensions/core/agent-environment/index.ts +4 -3
  57. package/src/extensions/core/prompt-builder/AGENTS.md +8 -4
  58. package/src/extensions/core/prompt-builder/index.ts +12 -7
  59. package/src/extensions/core/prompt-builder/instance-composition.ts +98 -14
  60. package/src/extensions/core/prompt-builder/system-info-tool.ts +3 -3
  61. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  62. package/src/extensions/core/skills-tool/auto-inject.ts +196 -24
  63. package/src/extensions/core/skills-tool/index.ts +217 -15
  64. package/src/extensions/core/skills-tool/reach.ts +256 -0
  65. package/src/extensions/core/skills-tool/skill-triggers.ts +90 -20
  66. package/src/extensions/enforcement/handlers/register-session-compact.ts +12 -1
  67. package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +23 -36
  68. package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +59 -29
  69. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +101 -81
  70. package/src/extensions/enforcement/resume-state.ts +127 -0
  71. package/src/extensions/enforcement/substate/context-hygiene-state.ts +17 -0
  72. package/src/extensions/enforcement/whisper.ts +21 -1
  73. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +20 -5
  74. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +370 -0
  75. package/src/extensions/memory/AGENTS.md +25 -1
  76. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +80 -27
  77. package/src/lib/config/braid-paths.ts +20 -0
  78. package/src/lib/config/braid-settings.ts +46 -0
  79. package/src/lib/detection/context-tiers.ts +186 -13
  80. package/src/lib/events/AGENTS.md +1 -0
  81. package/src/lib/events/turn-boundary.ts +115 -0
  82. package/src/lib/orchestrator/workers.ts +33 -12
  83. package/src/lib/state/global-state.ts +1 -0
  84. package/src/lib/utils/AGENTS.md +1 -1
  85. package/src/types/extension-context.d.ts +22 -79
@@ -96,7 +96,7 @@ export const TOOL_GUIDELINES: Record<string, string> = {
96
96
 
97
97
  // ── skills-tool (default-enabled) ──
98
98
  list_skills:
99
- "when: entering a domain that may have a skill; when-not: after the skill is loaded; args: page/pageSize; caveat: read the WHOLE SKILL.md before acting in the domain",
99
+ "when: entering a domain that may have a skill; when-not: after the skill is loaded; args: page/pageSize/sectionsMax/rank; caveat: rows arrive ordered by relevance to the current task (rows with evidence carry relevance {score, reason}; the response carries ranking {tier, basis, policy}; rank: catalog for the plain order) and reach (reachable, lines, bytes, chars, estTokens, sectionCount, sections) prices the read — read the WHOLE SKILL.md before acting in the domain",
100
100
  skill_stats:
101
101
  "when: measure skill adoption — suggested vs loaded counters; args: none; caveat: session + all-time counters (durable, skills-usage.json)",
102
102
 
@@ -15,11 +15,15 @@
15
15
  * a signal: it fires broad skills on almost any prompt.
16
16
  * Keywords are stemmed with one suffix rule (trailing s/es) so plural
17
17
  * prompts hit singular name tokens ("skills" → "skill").
18
- * Corpus-common words are gated out of the weak legs: a word present in
19
- * COMMON_KEYWORD_DF or more of the cached skills' documents cannot tell
20
- * skills apart, so description/path hits from it score nothing. Name and
21
- * trigger hits are never gated — the skill's own identity vocabulary is
22
- * what a prompt naming it looks like.
18
+ * Corpus-common words are gated out of the weak legs AND out of the
19
+ * name leg's prefix hits: a word present in COMMON_KEYWORD_DF or more of
20
+ * the cached skills' documents cannot tell skills apart, so
21
+ * description/path hits from it score nothing. A name hit is word-shaped
22
+ * by construction — a whole name token, or the start of one — so a word
23
+ * buried inside a coined token ("line" in placement-disc**line**) is not
24
+ * a name hit at all. A whole-name-token hit and a trigger hit are never
25
+ * gated: the skill's own identity vocabulary is what a prompt naming it
26
+ * looks like, and a curated phrase is the author's signal.
23
27
  * 1b. Ranking: equal scores compare by more distinct matched signals, then
24
28
  * by rarer evidence (lower summed document frequency), then by name.
25
29
  * Alphabetical order alone decided which of two equally-scored skills
@@ -109,6 +113,7 @@ import {
109
113
  recordSessionStart,
110
114
  } from "./session-records.js";
111
115
  import { triggerMatches } from "./skill-triggers.js";
116
+ import type { TriggerSource } from "./skill-triggers.js";
112
117
 
113
118
  const log = createLogger("skills-auto-inject");
114
119
 
@@ -159,7 +164,8 @@ export const MIN_NON_NAME_SCORE = 2;
159
164
  * A keyword present in this many skill documents or more is corpus-common: it
160
165
  * appears in a large share of the catalog (5 of 22 skills = 23%), so it cannot
161
166
  * distinguish one skill from another and contributes NOTHING to the weak legs
162
- * (description, catalog path).
167
+ * (description, catalog path) — or to the name leg's token-prefix rule, the one
168
+ * name hit that can rest on a shared word.
163
169
  *
164
170
  * The number is measured, not guessed. Two measurements, one threshold:
165
171
  *
@@ -286,6 +292,8 @@ export interface CachedSkill {
286
292
  disableModelInvocation?: boolean;
287
293
  /** Frontmatter trigger phrases (setCachedSkills resolves them from SKILL.md). */
288
294
  triggers?: string[];
295
+ /** Which source authored each phrase (the row's evidence label). */
296
+ triggerSources?: Record<string, TriggerSource>;
289
297
  }
290
298
 
291
299
  // Shared module-level variable rather than a per-module copy: the import
@@ -377,16 +385,56 @@ export interface SkillMatch {
377
385
  signals: number;
378
386
  /** Summed document frequency of the matched keywords — lower is rarer. */
379
387
  evidenceDf: number;
388
+ /** Strongest evidence behind the score; null when the skill did not qualify. */
389
+ reason: RelevanceReason | null;
380
390
  }
381
391
 
382
- const NO_MATCH: SkillMatch = { score: 0, signals: 0, evidenceDf: 0 };
392
+ /**
393
+ * What the strongest evidence for a row was. Short on purpose: a ranking row
394
+ * says "trigger", not a sentence — the reader is choosing a read, not reading
395
+ * an explanation.
396
+ *
397
+ * trigger — an authored phrase from frontmatter or the description tail
398
+ * heading — an authored phrase from a `## trigger:` body heading
399
+ * name — a keyword in the skill's own name
400
+ * description — a description or catalog-path keyword (the weak legs)
401
+ */
402
+ export type RelevanceReason = "trigger" | "heading" | "name" | "description";
403
+
404
+ /** Evidence strength for the row's single `reason` field. */
405
+ const REASON_STRENGTH: Record<RelevanceReason, number> = {
406
+ trigger: 4,
407
+ heading: 3,
408
+ name: 2,
409
+ description: 1,
410
+ };
411
+
412
+ /**
413
+ * How a keyword occurs in a skill name: as a whole token, as the start of a
414
+ * longer token, or not at all.
415
+ *
416
+ * The third answer is the fix: the name leg used to award points to any
417
+ * substring anywhere in the name, so a corpus-common word ("line", df 7 of 22)
418
+ * scored +2 for placement-disc**line** and release-pi**peline** and carried the
419
+ * name-hit exemption from the qualification bar with it. A word buried inside
420
+ * a coined token names the author's coinage, not the prompt's subject; a word
421
+ * that starts a token still reads as the author's own vocabulary ("engine" in
422
+ * software-engineer).
423
+ */
424
+ function nameOccurrence(tokens: string[], kw: string): "token" | "prefix" | null {
425
+ if (tokens.includes(kw)) return "token";
426
+ for (const token of tokens) if (token.length > kw.length && token.startsWith(kw)) return "prefix";
427
+ return null;
428
+ }
429
+
430
+ const NO_MATCH: SkillMatch = { score: 0, signals: 0, evidenceDf: 0, reason: null };
383
431
 
384
432
  /**
385
433
  * Score a skill against a set of keywords.
386
434
  *
387
435
  * Scoring rules:
388
- * +3 skill name contains a keyword (exact match)
389
- * +2 skill name contains a keyword as substring
436
+ * +3 skill name carries a keyword as a whole token (exact match)
437
+ * +2 skill name starts a token with a keyword, below the frequency gate
390
438
  * +2 a trigger phrase occurs in the prompt (word-bounded)
391
439
  * +1 skill description contains a keyword
392
440
  * +1 the skill's own catalog path contains a keyword (e.g. "research" in
@@ -397,8 +445,11 @@ const NO_MATCH: SkillMatch = { score: 0, signals: 0, evidenceDf: 0 };
397
445
  *
398
446
  * `keywordDf` is the corpus document frequency of the prompt's keywords (see
399
447
  * corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
400
- * nothing on the weak legs; passing no map scores every keyword at full weight
401
- * (the pre-rarity behavior, which the unit fixtures pin).
448
+ * nothing on the weak legs, and nothing on the name leg's token-prefix rule:
449
+ * a common word that only starts a token ("line" in "line-counting") is
450
+ * vocabulary the catalog shares, not the skill's own. Passing no map scores
451
+ * every keyword at full weight (the pre-rarity behavior, which the unit
452
+ * fixtures pin).
402
453
  *
403
454
  * Qualification bar: a skill whose match never touches its NAME (description
404
455
  * and/or filePath hits only) must reach a total score of at least
@@ -421,7 +472,12 @@ export function matchSkill(
421
472
  let signals = 0;
422
473
  let evidenceDf = 0;
423
474
  let nameHit = false;
475
+ let reason: RelevanceReason | null = null;
476
+ const noteReason = (candidate: RelevanceReason) => {
477
+ if (!reason || REASON_STRENGTH[candidate] > REASON_STRENGTH[reason]) reason = candidate;
478
+ };
424
479
  const name = skill.name.toLowerCase();
480
+ const nameTokens = name.split(/[^a-z0-9]+/).filter(Boolean);
425
481
  const desc = skill.description.toLowerCase();
426
482
  const path = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
427
483
  const dfOf = (kw: string) => keywordDf?.get(kw) ?? 0;
@@ -431,26 +487,32 @@ export function matchSkill(
431
487
  score += 2;
432
488
  signals++;
433
489
  nameHit = true;
434
- // A curated phrase is the rarest evidence a skill can offer: df 0.
490
+ // A curated phrase is the rarest evidence a skill can offer: df 0. Its
491
+ // provenance is what the row reports as its evidence label.
492
+ noteReason(skill.triggerSources?.[trig] === "heading" ? "heading" : "trigger");
435
493
  }
436
494
  }
437
495
 
438
496
  for (const kw of keywords) {
439
497
  const df = dfOf(kw);
440
- // Exact token match in name
441
- if (name.split(/[^a-z0-9]+/).includes(kw)) {
498
+ const occurrence = nameOccurrence(nameTokens, kw);
499
+ // Exact token match in name: the skill's own identity vocabulary, never gated.
500
+ if (occurrence === "token") {
442
501
  score += 3;
443
502
  signals++;
444
503
  nameHit = true;
445
504
  evidenceDf += df;
505
+ noteReason("name");
446
506
  continue;
447
507
  }
448
- // Substring match in name (catches compound names like "code-search")
449
- if (name.includes(kw)) {
508
+ // Token-prefix match in name ("engine" in "software-engineer"): name
509
+ // evidence, but only while the word is distinctive enough to mean it.
510
+ if (occurrence === "prefix" && df < COMMON_KEYWORD_DF) {
450
511
  score += 2;
451
512
  signals++;
452
513
  nameHit = true;
453
514
  evidenceDf += df;
515
+ noteReason("name");
454
516
  continue;
455
517
  }
456
518
  // Corpus-common keyword: the weak legs score nothing for it, so a prompt
@@ -471,11 +533,12 @@ export function matchSkill(
471
533
  if (weakHit) {
472
534
  signals++;
473
535
  evidenceDf += df;
536
+ noteReason("description");
474
537
  }
475
538
  }
476
539
 
477
540
  if (!nameHit && score < MIN_NON_NAME_SCORE) return NO_MATCH;
478
- return { score, signals, evidenceDf };
541
+ return { score, signals, evidenceDf, reason };
479
542
  }
480
543
 
481
544
  /** The score alone (see matchSkill for the rules and the rarity gate). */
@@ -500,8 +563,23 @@ export interface ScoredSkill {
500
563
  evidenceDf?: number;
501
564
  }
502
565
 
566
+ /**
567
+ * The ranking comparator, shared by the whisper's selection and the catalog
568
+ * read: score, then breadth of match (distinct signals), then rarity of the
569
+ * evidence (summed document frequency), then name. Pure.
570
+ */
571
+ function compareScored(a: ScoredSkill, b: ScoredSkill): number {
572
+ return (
573
+ b.score - a.score ||
574
+ (b.signals ?? 0) - (a.signals ?? 0) ||
575
+ (a.evidenceDf ?? 0) - (b.evidenceDf ?? 0) ||
576
+ a.skill.name.localeCompare(b.skill.name)
577
+ );
578
+ }
579
+
503
580
  /**
504
581
  * Decide which scored skills to suggest given the session injection state.
582
+ *
505
583
  * Pure — mirrors the handler's decision path so it can be unit-tested:
506
584
  * sort (score desc, distinct signals desc, evidence df asc, name asc) →
507
585
  * cooldown filter (global floor + per-skill loaded extension) → slot budget
@@ -523,13 +601,7 @@ export function selectSuggestions(
523
601
  ): ScoredSkill[] {
524
602
  if (!scored.length) return [];
525
603
 
526
- const sorted = [...scored].sort(
527
- (a, b) =>
528
- b.score - a.score ||
529
- (b.signals ?? 0) - (a.signals ?? 0) ||
530
- (a.evidenceDf ?? 0) - (b.evidenceDf ?? 0) ||
531
- a.skill.name.localeCompare(b.skill.name),
532
- );
604
+ const sorted = [...scored].sort(compareScored);
533
605
 
534
606
  const available = sorted.filter((s) => !onCooldown(s.skill.name, injected, currentTurn));
535
607
  if (!available.length) return [];
@@ -543,6 +615,106 @@ export function selectSuggestions(
543
615
  return available.slice(0, slotBudget);
544
616
  }
545
617
 
618
+ // Deterministic ranking for the catalog read
619
+
620
+ /**
621
+ * Declared margin: a gap smaller than this between the first and second
622
+ * qualified skill means the top is a coin flip, and the read says so
623
+ * (`thin-margin`) instead of presenting the order as a decision. The number is
624
+ * deliberate, not measured: one description keyword (+1) is exactly the
625
+ * distance the scorer says is too weak to qualify a skill on its own
626
+ * (MIN_NON_NAME_SCORE), so a lead that one extra weak hit could erase is not a
627
+ * lead.
628
+ */
629
+ export const RANK_MARGIN_THRESHOLD = 2;
630
+
631
+ /**
632
+ * A task text shorter than this cannot carry a ranking signal: a greeting or a
633
+ * two-word nudge names no domain, so the deterministic tier reports itself
634
+ * short rather than confidently wrong.
635
+ */
636
+ export const RANK_SHORT_TASK_CHARS = 24;
637
+
638
+ /** Why the deterministic tier answered the way it did. */
639
+ export type RankingBasis =
640
+ | "no-task"
641
+ | "short-task"
642
+ | "no-score"
643
+ | "unambiguous"
644
+ | "tie"
645
+ | "thin-margin";
646
+
647
+ /** One skill as the ranking read consumes it: match evidence plus its label. */
648
+ export interface RankedSkill {
649
+ skill: CachedSkill;
650
+ score: number;
651
+ signals: number;
652
+ evidenceDf: number;
653
+ reason: RelevanceReason | null;
654
+ }
655
+
656
+ /** The deterministic tier's whole answer: an ordered list and a verdict on it. */
657
+ export interface DeterministicRanking {
658
+ /** Qualified skills only, best first (the order the whisper ranks by). */
659
+ ranked: RankedSkill[];
660
+ /** True when the list cannot separate its own top — the escalation trigger. */
661
+ ambiguous: boolean;
662
+ basis: RankingBasis;
663
+ }
664
+
665
+ /**
666
+ * Rank the catalog against a task text without a model. Pure given the cache.
667
+ *
668
+ * Ordering is the whisper's comparator (score, then distinct signals, then
669
+ * summed evidence df, then name) so the two surfaces can never disagree about
670
+ * which skill is better. `ambiguous` is the one thing the whisper does not
671
+ * need: it decides every turn with slots and cooldowns, while a catalog read
672
+ * shows the whole list and therefore must say when its own top is not decided
673
+ * (a tie or a thin margin) or when the task text could not inform it at all.
674
+ *
675
+ * The verdict:
676
+ * no-task — no task text at all; nothing to rank.
677
+ * short-task — the text carries no significant keyword, or is shorter than
678
+ * RANK_SHORT_TASK_CHARS: nothing here can rank a catalog.
679
+ * no-score — every skill scored zero: unambiguous (nothing applies).
680
+ * tie — the top two score the same: ambiguous.
681
+ * thin-margin — the top two sit closer than RANK_MARGIN_THRESHOLD: ambiguous.
682
+ * unambiguous — one skill leads the field by at least the margin.
683
+ */
684
+ export function rankSkillsDeterministic(
685
+ skills: CachedSkill[],
686
+ taskText: string,
687
+ ): DeterministicRanking {
688
+ const text = (taskText ?? "").trim();
689
+ if (!text) return { ranked: [], ambiguous: false, basis: "no-task" };
690
+ const keywords = extractKeywords(text);
691
+ const ranked: RankedSkill[] = [];
692
+ if (keywords.length) {
693
+ const keywordDf = corpusKeywordFrequency(keywords, skills);
694
+ for (const skill of skills) {
695
+ const match = matchSkill(skill, keywords, text, keywordDf);
696
+ if (match.score <= 0) continue;
697
+ ranked.push({
698
+ skill,
699
+ score: match.score,
700
+ signals: match.signals,
701
+ evidenceDf: match.evidenceDf,
702
+ reason: match.reason,
703
+ });
704
+ }
705
+ }
706
+ ranked.sort(compareScored);
707
+ if (text.length < RANK_SHORT_TASK_CHARS || !keywords.length) {
708
+ return { ranked, ambiguous: true, basis: "short-task" };
709
+ }
710
+ if (!ranked.length) return { ranked, ambiguous: false, basis: "no-score" };
711
+ if (ranked.length === 1) return { ranked, ambiguous: false, basis: "unambiguous" };
712
+ const margin = ranked[0].score - ranked[1].score;
713
+ if (margin === 0) return { ranked, ambiguous: true, basis: "tie" };
714
+ if (margin < RANK_MARGIN_THRESHOLD) return { ranked, ambiguous: true, basis: "thin-margin" };
715
+ return { ranked, ambiguous: false, basis: "unambiguous" };
716
+ }
717
+
546
718
  /**
547
719
  * Cooldown gate: the global floor applies to every injection; a skill that
548
720
  * was loaded after its injection additionally cools down for
@@ -10,7 +10,19 @@
10
10
  * The cache lives in this module and is reset each session.
11
11
  *
12
12
  * One action:
13
- * list — paginated catalog (name, filePath, description, source)
13
+ * list — paginated catalog (name, filePath, description, source, reach),
14
+ * ordered by relevance to the current task unless `rank: "catalog"`.
15
+ *
16
+ * Each row carries the price of the read it names (see reach.ts): reachable,
17
+ * lines, bytes, chars, a token estimate, the file's heading count, and as many
18
+ * of its headings as the caller asked for. Picking a skill is picking a read,
19
+ * and a price is what makes that pick rational.
20
+ *
21
+ * The ordering is the deterministic scorer's answer (see `resolveRanking`):
22
+ * auto-inject.ts owns the ranking, and this handler owns only what needs the
23
+ * extension context — the task text (from the session branch) and the
24
+ * `braid.skills.ranking` policy, which is read and echoed rather than acted on
25
+ * while no model tier exists.
14
26
  *
15
27
  * Skills discovery (list_skills tool) plus the scoring-based auto-inject
16
28
  * whisper supersede an LLM top-N recommender: a second relevance engine
@@ -20,17 +32,28 @@
20
32
  * Also registers `skill_stats` — the adoption counter surface.
21
33
  */
22
34
 
23
- import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
35
+ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
24
36
  import { Type } from "typebox";
25
37
  import { createLogger } from "../../../lib/core/logger.js";
38
+ import { getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
39
+ import type { SkillsRankingMode } from "../../../lib/config/braid-settings.js";
26
40
  import {
27
41
  registerAutoInject,
28
42
  updateSkillCache,
29
43
  getSkillStats,
30
44
  getDurableSkillStats,
31
45
  resolveDiscoveryMode,
46
+ rankSkillsDeterministic,
32
47
  } from "./auto-inject.js";
33
- import { readSkillTriggers } from "./skill-triggers.js";
48
+ import type { DeterministicRanking, RankedSkill, RelevanceReason } from "./auto-inject.js";
49
+ import { readSkillTriggerEntries } from "./skill-triggers.js";
50
+ import type { TriggerSource } from "./skill-triggers.js";
51
+ import {
52
+ clampSectionsMax,
53
+ DEFAULT_SECTIONS_MAX,
54
+ SECTIONS_MAX_LIMIT,
55
+ readSkillReach,
56
+ } from "./reach.js";
34
57
  import { getMonthlyAdoptionRollup } from "./session-records.js";
35
58
 
36
59
  const log = createLogger("skills-tool");
@@ -51,6 +74,8 @@ interface CachedSkill {
51
74
  disableModelInvocation?: boolean;
52
75
  /** Frontmatter trigger phrases, resolved from SKILL.md at cache time. */
53
76
  triggers?: string[];
77
+ /** Which source authored each phrase (a ranking row reports it). */
78
+ triggerSources?: Record<string, TriggerSource>;
54
79
  }
55
80
 
56
81
  let cachedSkills: CachedSkill[] = [];
@@ -62,10 +87,12 @@ let cachedSkills: CachedSkill[] = [];
62
87
  * shape), and the memoized read makes repeat turns stat-only.
63
88
  */
64
89
  export function setCachedSkills(skills: CachedSkill[]): void {
65
- cachedSkills = skills.map((s) => ({
66
- ...s,
67
- triggers: readSkillTriggers(s.filePath, s.description),
68
- }));
90
+ cachedSkills = skills.map((s) => {
91
+ const entries = readSkillTriggerEntries(s.filePath, s.description);
92
+ const triggerSources: Record<string, TriggerSource> = {};
93
+ for (const entry of entries) triggerSources[entry.phrase] = entry.source;
94
+ return { ...s, triggers: entries.map((entry) => entry.phrase), triggerSources };
95
+ });
69
96
  // Sync with auto-inject subsystem (enriched cache — triggers ride along)
70
97
  updateSkillCache(cachedSkills);
71
98
  log.debug(`Cached ${skills.length} skills for list_skills tool`);
@@ -92,6 +119,137 @@ function formatSource(skill: CachedSkill): string {
92
119
  return src;
93
120
  }
94
121
 
122
+ // Relevance ranking: the deterministic order
123
+ //
124
+ // A model tier was built here and measured against this scorer: it never lost
125
+ // a case and won the two prose prompts the scorer misses, but it did not clear
126
+ // its pre-registered bar, and a tier that buys two wins with a call on every
127
+ // ambiguous read is a finding about the scorer, not a feature. So the read is
128
+ // answered by rankSkillsDeterministic() alone: no provider, no cache, no
129
+ // counters. The `braid.skills.ranking` setting and the `ranking` report
130
+ // survive because they are the seam a later tier plugs into.
131
+
132
+ /** The evidence label a row reports (see RelevanceReason in auto-inject.ts). */
133
+ export type RowRelevanceReason = RelevanceReason;
134
+
135
+ /** What a ranked row says about its own position. */
136
+ export interface RowRelevance {
137
+ /** The deterministic score behind the row. */
138
+ score: number;
139
+ reason: RowRelevanceReason;
140
+ }
141
+
142
+ /** Why the deterministic verdict is what it is, and who answered. */
143
+ export interface RankingReport {
144
+ /** Always "keyword": the deterministic scorer is the only tier. */
145
+ tier: "keyword";
146
+ basis: DeterministicRanking["basis"];
147
+ /**
148
+ * The configured `braid.skills.ranking` value, echoed so an operator can see
149
+ * what the policy asked for. Only "keyword" has an implementation today; the
150
+ * other two are reserved for a model tier that was measured and not kept, and
151
+ * they evaluate to the keyword path.
152
+ */
153
+ policy: SkillsRankingMode;
154
+ }
155
+
156
+ /**
157
+ * The current task text: the newest user message on the live branch.
158
+ *
159
+ * A tool call carries no prompt of its own and pi hands tools no turn prompt,
160
+ * but the branch does — and its newest user message is the task the agent is
161
+ * working on. A resumed session therefore ranks against its real task even
162
+ * though this process never saw the prompt arrive. Best-effort: no branch, an
163
+ * unreadable entry, or a non-text message yields "", and the caller then
164
+ * returns the catalog order rather than inventing a task.
165
+ */
166
+ export function currentTaskText(ctx: ExtensionContext): string {
167
+ try {
168
+ const sm = (ctx as { sessionManager?: { getBranch?: () => unknown[] } }).sessionManager;
169
+ const branch = sm?.getBranch?.() ?? [];
170
+ for (let i = branch.length - 1; i >= 0; i--) {
171
+ const entry = branch[i] as { type?: string; message?: { role?: string; content?: unknown } };
172
+ if (entry?.type !== "message" || entry.message?.role !== "user") continue;
173
+ const content = entry.message.content;
174
+ if (typeof content === "string") return content;
175
+ if (Array.isArray(content)) {
176
+ return content
177
+ .map((part) => part as { type?: string; text?: string })
178
+ .filter((part) => part?.type === "text" && typeof part.text === "string")
179
+ .map((part) => part.text as string)
180
+ .join("\n");
181
+ }
182
+ return "";
183
+ }
184
+ } catch {
185
+ // Best-effort: a stale ctx or an absent tree yields no text.
186
+ }
187
+ return "";
188
+ }
189
+
190
+ /** Reorder `skills` by `names`, appending everything the list did not mention. */
191
+ function orderByNames(skills: CachedSkill[], names: string[]): CachedSkill[] {
192
+ const byName = new Map(skills.map((s) => [s.name, s]));
193
+ const out: CachedSkill[] = [];
194
+ for (const name of names) {
195
+ const skill = byName.get(name);
196
+ if (!skill) continue;
197
+ byName.delete(name);
198
+ out.push(skill);
199
+ }
200
+ for (const skill of skills) if (byName.has(skill.name)) out.push(skill);
201
+ return out;
202
+ }
203
+
204
+ /** One catalog read's complete ranking answer. */
205
+ export interface RankingAnswer {
206
+ order: CachedSkill[];
207
+ /** Absent for `rank: "catalog"` — an unranked read has no tier or evidence. */
208
+ ranking?: RankingReport;
209
+ relevance: Map<string, RowRelevance>;
210
+ }
211
+
212
+ /**
213
+ * Resolve the catalog order for one read.
214
+ *
215
+ * `keyword` and `catalog` are the two answers: the deterministic ranking (with
216
+ * its verdict on how confident that ranking is), or the plain catalog. A
217
+ * missing task text is nobody's question, so the catalog order stands and the
218
+ * report says `no-task` rather than pretending to rank.
219
+ */
220
+ export function resolveRanking(
221
+ ctx: ExtensionContext,
222
+ skills: CachedSkill[],
223
+ options: { rank: "relevance" | "catalog"; policy?: SkillsRankingMode },
224
+ ): RankingAnswer {
225
+ if (options.rank === "catalog") return { order: skills, relevance: new Map() };
226
+
227
+ const det = rankSkillsDeterministic(skills, currentTaskText(ctx));
228
+ const relevance = new Map<string, RowRelevance>();
229
+ for (const row of det.ranked) relevance.set(row.skill.name, rowOf(row));
230
+ const order =
231
+ det.basis === "no-task"
232
+ ? skills
233
+ : orderByNames(
234
+ skills,
235
+ det.ranked.map((row) => row.skill.name),
236
+ );
237
+ return {
238
+ order,
239
+ ranking: {
240
+ tier: "keyword",
241
+ basis: det.basis,
242
+ policy: options.policy ?? getSkillsRankingMode(),
243
+ },
244
+ relevance,
245
+ };
246
+ }
247
+
248
+ /** A ranked row as the response reports it (only rows with evidence get here). */
249
+ function rowOf(row: RankedSkill): RowRelevance {
250
+ return { score: row.score, reason: row.reason ?? "description" };
251
+ }
252
+
95
253
  // Extension factory:
96
254
 
97
255
  export default function skillsToolExtension(pi: ExtensionAPI): void {
@@ -101,10 +259,11 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
101
259
  name: "list_skills",
102
260
  label: "List Skills",
103
261
  description:
104
- "Discover skills on demand: paginated catalog (name, filePath, description, source); `read` a SKILL.md to load it.",
262
+ "Discover skills on demand: paginated catalog (name, filePath, description, source) plus each skill's reach (reachable, lines, bytes, chars, estTokens, sectionCount, section headings with line numbers), so the price of a read is visible before the read. Rows are ordered by relevance to the current task; a row with match evidence carries relevance {score, reason}, and the response carries ranking {tier, basis, policy}. Pass rank: 'catalog' for the plain catalog order. `read` a SKILL.md to load it.",
105
263
  parameters: Type.Object({
106
264
  action: Type.Literal("list", {
107
- description: "list = paginated catalog (name, filePath, description, source)",
265
+ description:
266
+ "list = paginated catalog with per-skill reach (reachable, lines, bytes, chars, estTokens, sectionCount, sections)",
108
267
  }),
109
268
  page: Type.Optional(
110
269
  Type.Number({
@@ -121,17 +280,36 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
121
280
  description: "Entries per page for list",
122
281
  }),
123
282
  ),
283
+ sectionsMax: Type.Optional(
284
+ Type.Number({
285
+ minimum: 0,
286
+ maximum: SECTIONS_MAX_LIMIT,
287
+ default: DEFAULT_SECTIONS_MAX,
288
+ description:
289
+ "Headings reported per skill; 0 omits the section list and keeps sectionCount",
290
+ }),
291
+ ),
292
+ rank: Type.Optional(
293
+ Type.Union([Type.Literal("relevance"), Type.Literal("catalog")], {
294
+ default: "relevance",
295
+ description:
296
+ "relevance (default) = order by fit to the current task; catalog = the plain catalog order, with no ranking fields",
297
+ }),
298
+ ),
124
299
  }),
125
- execute: async (_id, params, _signal, _onUpdate, _ctx) => {
300
+ execute: async (_id, params, signal, _onUpdate, ctx) => {
126
301
  const page = (params.page as number) ?? 1;
127
302
  const pageSize = (params.pageSize as number) ?? 10;
128
- const start = (page - 1) * pageSize;
303
+ const sectionsMax = clampSectionsMax(params.sectionsMax);
304
+ const rank = (params.rank as "relevance" | "catalog" | undefined) ?? "relevance";
129
305
  // Explicit-invocation-only skills stay out of the catalog; the cache
130
306
  // itself stays unfiltered for the read-detector that counts explicit
131
307
  // loads.
132
308
  const visible = cachedSkills.filter((s) => !s.disableModelInvocation);
133
- const slice = visible.slice(start, start + pageSize);
134
- const total = visible.length;
309
+ const answer = resolveRanking(ctx, visible, { rank });
310
+ const total = answer.order.length;
311
+ const start = (page - 1) * pageSize;
312
+ const slice = answer.order.slice(start, start + pageSize);
135
313
  const hasMore = start + pageSize < total;
136
314
 
137
315
  const skills = slice.map((s) => ({
@@ -139,16 +317,40 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
139
317
  filePath: s.filePath,
140
318
  description: (s.description ?? "").slice(0, 280),
141
319
  source: formatSource(s),
320
+ ...readSkillReach(s.filePath, sectionsMax),
321
+ // Evidence where it exists: a row with no match carries no relevance
322
+ // field. Every row paying ~60 bytes for "nothing matched" pushed the
323
+ // shipped page past its measured prompt budget (12.0KB -> 12.8KB), and
324
+ // the empty object carried no information the absence does not.
325
+ ...(answer.relevance.has(s.name) ? { relevance: answer.relevance.get(s.name) } : {}),
142
326
  }));
143
327
 
144
328
  return {
145
329
  content: [
146
330
  {
147
331
  type: "text" as const,
148
- text: JSON.stringify({ page, pageSize, total, hasMore, skills }, null, 2),
332
+ text: JSON.stringify(
333
+ {
334
+ page,
335
+ pageSize,
336
+ total,
337
+ hasMore,
338
+ ...(answer.ranking ? { ranking: answer.ranking } : {}),
339
+ skills,
340
+ },
341
+ null,
342
+ 2,
343
+ ),
149
344
  },
150
345
  ],
151
- details: { total, page, pageSize, hasMore, returned: skills.length },
346
+ details: {
347
+ total,
348
+ page,
349
+ pageSize,
350
+ hasMore,
351
+ returned: skills.length,
352
+ ...(answer.ranking ? { tier: answer.ranking.tier, basis: answer.ranking.basis } : {}),
353
+ },
152
354
  };
153
355
  },
154
356
  });