pi-braid 0.40.5 → 0.41.0

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 (95) hide show
  1. package/AGENTS.md +17 -18
  2. package/README.md +128 -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-MAP.md +1 -1
  49. package/docs/CONTEXT-POLICY.md +8 -0
  50. package/docs/FLEET.md +99 -0
  51. package/docs/LOCAL_DEV.md +0 -1
  52. package/docs/ROADMAP.md +5 -5
  53. package/docs/SETUP.md +19 -18
  54. package/package.json +5 -1
  55. package/scripts/fleet/cli.mjs +499 -0
  56. package/scripts/fleet/driver-rpc.mjs +376 -0
  57. package/scripts/fleet/driver-scripted.mjs +239 -0
  58. package/scripts/fleet/journal.mjs +994 -0
  59. package/scripts/fleet/procs.mjs +76 -0
  60. package/scripts/fleet/supervisor.mjs +1494 -0
  61. package/scripts/fleet/tool-guard.mjs +467 -0
  62. package/skills/herdr-topology/SKILL.md +6 -1
  63. package/skills/release-pipeline/SKILL.md +20 -4
  64. package/skills/research/SKILL.md +32 -0
  65. package/skills/subagent-orchestration/SKILL.md +2 -2
  66. package/src/extensions/core/agent-environment/index.ts +4 -3
  67. package/src/extensions/core/prompt-builder/AGENTS.md +8 -4
  68. package/src/extensions/core/prompt-builder/index.ts +12 -7
  69. package/src/extensions/core/prompt-builder/instance-composition.ts +98 -14
  70. package/src/extensions/core/prompt-builder/system-info-tool.ts +3 -3
  71. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  72. package/src/extensions/core/skills-tool/auto-inject.ts +196 -24
  73. package/src/extensions/core/skills-tool/index.ts +217 -15
  74. package/src/extensions/core/skills-tool/reach.ts +256 -0
  75. package/src/extensions/core/skills-tool/skill-triggers.ts +90 -20
  76. package/src/extensions/enforcement/handlers/register-session-compact.ts +12 -1
  77. package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +23 -36
  78. package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +59 -29
  79. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +101 -81
  80. package/src/extensions/enforcement/resume-state.ts +127 -0
  81. package/src/extensions/enforcement/substate/context-hygiene-state.ts +17 -0
  82. package/src/extensions/enforcement/whisper.ts +21 -1
  83. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +20 -5
  84. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +370 -0
  85. package/src/extensions/memory/AGENTS.md +25 -1
  86. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +80 -27
  87. package/src/lib/config/braid-paths.ts +20 -0
  88. package/src/lib/config/braid-settings.ts +46 -0
  89. package/src/lib/detection/context-tiers.ts +186 -13
  90. package/src/lib/events/AGENTS.md +1 -0
  91. package/src/lib/events/turn-boundary.ts +115 -0
  92. package/src/lib/orchestrator/workers.ts +33 -12
  93. package/src/lib/state/global-state.ts +1 -0
  94. package/src/lib/utils/AGENTS.md +1 -1
  95. package/src/types/extension-context.d.ts +22 -79
@@ -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
@@ -144,7 +148,8 @@ export const MIN_NON_NAME_SCORE = 2;
144
148
  * A keyword present in this many skill documents or more is corpus-common: it
145
149
  * appears in a large share of the catalog (5 of 22 skills = 23%), so it cannot
146
150
  * distinguish one skill from another and contributes NOTHING to the weak legs
147
- * (description, catalog path).
151
+ * (description, catalog path) — or to the name leg's token-prefix rule, the one
152
+ * name hit that can rest on a shared word.
148
153
  *
149
154
  * The number is measured, not guessed. Two measurements, one threshold:
150
155
  *
@@ -306,13 +311,40 @@ export function corpusKeywordFrequency(keywords, skills) {
306
311
  }
307
312
  return freq;
308
313
  }
309
- const NO_MATCH = { score: 0, signals: 0, evidenceDf: 0 };
314
+ /** Evidence strength for the row's single `reason` field. */
315
+ const REASON_STRENGTH = {
316
+ trigger: 4,
317
+ heading: 3,
318
+ name: 2,
319
+ description: 1,
320
+ };
321
+ /**
322
+ * How a keyword occurs in a skill name: as a whole token, as the start of a
323
+ * longer token, or not at all.
324
+ *
325
+ * The third answer is the fix: the name leg used to award points to any
326
+ * substring anywhere in the name, so a corpus-common word ("line", df 7 of 22)
327
+ * scored +2 for placement-disc**line** and release-pi**peline** and carried the
328
+ * name-hit exemption from the qualification bar with it. A word buried inside
329
+ * a coined token names the author's coinage, not the prompt's subject; a word
330
+ * that starts a token still reads as the author's own vocabulary ("engine" in
331
+ * software-engineer).
332
+ */
333
+ function nameOccurrence(tokens, kw) {
334
+ if (tokens.includes(kw))
335
+ return "token";
336
+ for (const token of tokens)
337
+ if (token.length > kw.length && token.startsWith(kw))
338
+ return "prefix";
339
+ return null;
340
+ }
341
+ const NO_MATCH = { score: 0, signals: 0, evidenceDf: 0, reason: null };
310
342
  /**
311
343
  * Score a skill against a set of keywords.
312
344
  *
313
345
  * Scoring rules:
314
- * +3 skill name contains a keyword (exact match)
315
- * +2 skill name contains a keyword as substring
346
+ * +3 skill name carries a keyword as a whole token (exact match)
347
+ * +2 skill name starts a token with a keyword, below the frequency gate
316
348
  * +2 a trigger phrase occurs in the prompt (word-bounded)
317
349
  * +1 skill description contains a keyword
318
350
  * +1 the skill's own catalog path contains a keyword (e.g. "research" in
@@ -323,8 +355,11 @@ const NO_MATCH = { score: 0, signals: 0, evidenceDf: 0 };
323
355
  *
324
356
  * `keywordDf` is the corpus document frequency of the prompt's keywords (see
325
357
  * corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
326
- * nothing on the weak legs; passing no map scores every keyword at full weight
327
- * (the pre-rarity behavior, which the unit fixtures pin).
358
+ * nothing on the weak legs, and nothing on the name leg's token-prefix rule:
359
+ * a common word that only starts a token ("line" in "line-counting") is
360
+ * vocabulary the catalog shares, not the skill's own. Passing no map scores
361
+ * every keyword at full weight (the pre-rarity behavior, which the unit
362
+ * fixtures pin).
328
363
  *
329
364
  * Qualification bar: a skill whose match never touches its NAME (description
330
365
  * and/or filePath hits only) must reach a total score of at least
@@ -342,7 +377,13 @@ export function matchSkill(skill, keywords, promptText, keywordDf) {
342
377
  let signals = 0;
343
378
  let evidenceDf = 0;
344
379
  let nameHit = false;
380
+ let reason = null;
381
+ const noteReason = (candidate) => {
382
+ if (!reason || REASON_STRENGTH[candidate] > REASON_STRENGTH[reason])
383
+ reason = candidate;
384
+ };
345
385
  const name = skill.name.toLowerCase();
386
+ const nameTokens = name.split(/[^a-z0-9]+/).filter(Boolean);
346
387
  const desc = skill.description.toLowerCase();
347
388
  const path = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
348
389
  const dfOf = (kw) => keywordDf?.get(kw) ?? 0;
@@ -351,25 +392,31 @@ export function matchSkill(skill, keywords, promptText, keywordDf) {
351
392
  score += 2;
352
393
  signals++;
353
394
  nameHit = true;
354
- // A curated phrase is the rarest evidence a skill can offer: df 0.
395
+ // A curated phrase is the rarest evidence a skill can offer: df 0. Its
396
+ // provenance is what the row reports as its evidence label.
397
+ noteReason(skill.triggerSources?.[trig] === "heading" ? "heading" : "trigger");
355
398
  }
356
399
  }
357
400
  for (const kw of keywords) {
358
401
  const df = dfOf(kw);
359
- // Exact token match in name
360
- if (name.split(/[^a-z0-9]+/).includes(kw)) {
402
+ const occurrence = nameOccurrence(nameTokens, kw);
403
+ // Exact token match in name: the skill's own identity vocabulary, never gated.
404
+ if (occurrence === "token") {
361
405
  score += 3;
362
406
  signals++;
363
407
  nameHit = true;
364
408
  evidenceDf += df;
409
+ noteReason("name");
365
410
  continue;
366
411
  }
367
- // Substring match in name (catches compound names like "code-search")
368
- if (name.includes(kw)) {
412
+ // Token-prefix match in name ("engine" in "software-engineer"): name
413
+ // evidence, but only while the word is distinctive enough to mean it.
414
+ if (occurrence === "prefix" && df < COMMON_KEYWORD_DF) {
369
415
  score += 2;
370
416
  signals++;
371
417
  nameHit = true;
372
418
  evidenceDf += df;
419
+ noteReason("name");
373
420
  continue;
374
421
  }
375
422
  // Corpus-common keyword: the weak legs score nothing for it, so a prompt
@@ -391,18 +438,31 @@ export function matchSkill(skill, keywords, promptText, keywordDf) {
391
438
  if (weakHit) {
392
439
  signals++;
393
440
  evidenceDf += df;
441
+ noteReason("description");
394
442
  }
395
443
  }
396
444
  if (!nameHit && score < MIN_NON_NAME_SCORE)
397
445
  return NO_MATCH;
398
- return { score, signals, evidenceDf };
446
+ return { score, signals, evidenceDf, reason };
399
447
  }
400
448
  /** The score alone (see matchSkill for the rules and the rarity gate). */
401
449
  export function scoreSkill(skill, keywords, promptText, keywordDf) {
402
450
  return matchSkill(skill, keywords, promptText, keywordDf).score;
403
451
  }
452
+ /**
453
+ * The ranking comparator, shared by the whisper's selection and the catalog
454
+ * read: score, then breadth of match (distinct signals), then rarity of the
455
+ * evidence (summed document frequency), then name. Pure.
456
+ */
457
+ function compareScored(a, b) {
458
+ return (b.score - a.score ||
459
+ (b.signals ?? 0) - (a.signals ?? 0) ||
460
+ (a.evidenceDf ?? 0) - (b.evidenceDf ?? 0) ||
461
+ a.skill.name.localeCompare(b.skill.name));
462
+ }
404
463
  /**
405
464
  * Decide which scored skills to suggest given the session injection state.
465
+ *
406
466
  * Pure — mirrors the handler's decision path so it can be unit-tested:
407
467
  * sort (score desc, distinct signals desc, evidence df asc, name asc) →
408
468
  * cooldown filter (global floor + per-skill loaded extension) → slot budget
@@ -420,10 +480,7 @@ export function scoreSkill(skill, keywords, promptText, keywordDf) {
420
480
  export function selectSuggestions(scored, injected, currentTurn) {
421
481
  if (!scored.length)
422
482
  return [];
423
- const sorted = [...scored].sort((a, b) => b.score - a.score ||
424
- (b.signals ?? 0) - (a.signals ?? 0) ||
425
- (a.evidenceDf ?? 0) - (b.evidenceDf ?? 0) ||
426
- a.skill.name.localeCompare(b.skill.name));
483
+ const sorted = [...scored].sort(compareScored);
427
484
  const available = sorted.filter((s) => !onCooldown(s.skill.name, injected, currentTurn));
428
485
  if (!available.length)
429
486
  return [];
@@ -435,6 +492,78 @@ export function selectSuggestions(scored, injected, currentTurn) {
435
492
  return [];
436
493
  return available.slice(0, slotBudget);
437
494
  }
495
+ // Deterministic ranking for the catalog read
496
+ /**
497
+ * Declared margin: a gap smaller than this between the first and second
498
+ * qualified skill means the top is a coin flip, and the read says so
499
+ * (`thin-margin`) instead of presenting the order as a decision. The number is
500
+ * deliberate, not measured: one description keyword (+1) is exactly the
501
+ * distance the scorer says is too weak to qualify a skill on its own
502
+ * (MIN_NON_NAME_SCORE), so a lead that one extra weak hit could erase is not a
503
+ * lead.
504
+ */
505
+ export const RANK_MARGIN_THRESHOLD = 2;
506
+ /**
507
+ * A task text shorter than this cannot carry a ranking signal: a greeting or a
508
+ * two-word nudge names no domain, so the deterministic tier reports itself
509
+ * short rather than confidently wrong.
510
+ */
511
+ export const RANK_SHORT_TASK_CHARS = 24;
512
+ /**
513
+ * Rank the catalog against a task text without a model. Pure given the cache.
514
+ *
515
+ * Ordering is the whisper's comparator (score, then distinct signals, then
516
+ * summed evidence df, then name) so the two surfaces can never disagree about
517
+ * which skill is better. `ambiguous` is the one thing the whisper does not
518
+ * need: it decides every turn with slots and cooldowns, while a catalog read
519
+ * shows the whole list and therefore must say when its own top is not decided
520
+ * (a tie or a thin margin) or when the task text could not inform it at all.
521
+ *
522
+ * The verdict:
523
+ * no-task — no task text at all; nothing to rank.
524
+ * short-task — the text carries no significant keyword, or is shorter than
525
+ * RANK_SHORT_TASK_CHARS: nothing here can rank a catalog.
526
+ * no-score — every skill scored zero: unambiguous (nothing applies).
527
+ * tie — the top two score the same: ambiguous.
528
+ * thin-margin — the top two sit closer than RANK_MARGIN_THRESHOLD: ambiguous.
529
+ * unambiguous — one skill leads the field by at least the margin.
530
+ */
531
+ export function rankSkillsDeterministic(skills, taskText) {
532
+ const text = (taskText ?? "").trim();
533
+ if (!text)
534
+ return { ranked: [], ambiguous: false, basis: "no-task" };
535
+ const keywords = extractKeywords(text);
536
+ const ranked = [];
537
+ if (keywords.length) {
538
+ const keywordDf = corpusKeywordFrequency(keywords, skills);
539
+ for (const skill of skills) {
540
+ const match = matchSkill(skill, keywords, text, keywordDf);
541
+ if (match.score <= 0)
542
+ continue;
543
+ ranked.push({
544
+ skill,
545
+ score: match.score,
546
+ signals: match.signals,
547
+ evidenceDf: match.evidenceDf,
548
+ reason: match.reason,
549
+ });
550
+ }
551
+ }
552
+ ranked.sort(compareScored);
553
+ if (text.length < RANK_SHORT_TASK_CHARS || !keywords.length) {
554
+ return { ranked, ambiguous: true, basis: "short-task" };
555
+ }
556
+ if (!ranked.length)
557
+ return { ranked, ambiguous: false, basis: "no-score" };
558
+ if (ranked.length === 1)
559
+ return { ranked, ambiguous: false, basis: "unambiguous" };
560
+ const margin = ranked[0].score - ranked[1].score;
561
+ if (margin === 0)
562
+ return { ranked, ambiguous: true, basis: "tie" };
563
+ if (margin < RANK_MARGIN_THRESHOLD)
564
+ return { ranked, ambiguous: true, basis: "thin-margin" };
565
+ return { ranked, ambiguous: false, basis: "unambiguous" };
566
+ }
438
567
  /**
439
568
  * Cooldown gate: the global floor applies to every injection; a skill that
440
569
  * 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
@@ -19,7 +31,10 @@
19
31
  *
20
32
  * Also registers `skill_stats` — the adoption counter surface.
21
33
  */
22
- import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
34
+ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
35
+ import type { SkillsRankingMode } from "../../../lib/config/braid-settings.js";
36
+ import type { DeterministicRanking, RelevanceReason } from "./auto-inject.js";
37
+ import type { TriggerSource } from "./skill-triggers.js";
23
38
  interface CachedSkill {
24
39
  name: string;
25
40
  filePath: string;
@@ -37,6 +52,8 @@ interface CachedSkill {
37
52
  disableModelInvocation?: boolean;
38
53
  /** Frontmatter trigger phrases, resolved from SKILL.md at cache time. */
39
54
  triggers?: string[];
55
+ /** Which source authored each phrase (a ranking row reports it). */
56
+ triggerSources?: Record<string, TriggerSource>;
40
57
  }
41
58
  /**
42
59
  * Called from prompt-builder's before_agent_start to populate the cache.
@@ -51,6 +68,57 @@ export declare function setCachedSkills(skills: CachedSkill[]): void;
51
68
  * prompt text that must name only skills the catalog actually shows.
52
69
  */
53
70
  export declare function getCachedVisibleSkillNames(): string[];
71
+ /** The evidence label a row reports (see RelevanceReason in auto-inject.ts). */
72
+ export type RowRelevanceReason = RelevanceReason;
73
+ /** What a ranked row says about its own position. */
74
+ export interface RowRelevance {
75
+ /** The deterministic score behind the row. */
76
+ score: number;
77
+ reason: RowRelevanceReason;
78
+ }
79
+ /** Why the deterministic verdict is what it is, and who answered. */
80
+ export interface RankingReport {
81
+ /** Always "keyword": the deterministic scorer is the only tier. */
82
+ tier: "keyword";
83
+ basis: DeterministicRanking["basis"];
84
+ /**
85
+ * The configured `braid.skills.ranking` value, echoed so an operator can see
86
+ * what the policy asked for. Only "keyword" has an implementation today; the
87
+ * other two are reserved for a model tier that was measured and not kept, and
88
+ * they evaluate to the keyword path.
89
+ */
90
+ policy: SkillsRankingMode;
91
+ }
92
+ /**
93
+ * The current task text: the newest user message on the live branch.
94
+ *
95
+ * A tool call carries no prompt of its own and pi hands tools no turn prompt,
96
+ * but the branch does — and its newest user message is the task the agent is
97
+ * working on. A resumed session therefore ranks against its real task even
98
+ * though this process never saw the prompt arrive. Best-effort: no branch, an
99
+ * unreadable entry, or a non-text message yields "", and the caller then
100
+ * returns the catalog order rather than inventing a task.
101
+ */
102
+ export declare function currentTaskText(ctx: ExtensionContext): string;
103
+ /** One catalog read's complete ranking answer. */
104
+ export interface RankingAnswer {
105
+ order: CachedSkill[];
106
+ /** Absent for `rank: "catalog"` — an unranked read has no tier or evidence. */
107
+ ranking?: RankingReport;
108
+ relevance: Map<string, RowRelevance>;
109
+ }
110
+ /**
111
+ * Resolve the catalog order for one read.
112
+ *
113
+ * `keyword` and `catalog` are the two answers: the deterministic ranking (with
114
+ * its verdict on how confident that ranking is), or the plain catalog. A
115
+ * missing task text is nobody's question, so the catalog order stands and the
116
+ * report says `no-task` rather than pretending to rank.
117
+ */
118
+ export declare function resolveRanking(ctx: ExtensionContext, skills: CachedSkill[], options: {
119
+ rank: "relevance" | "catalog";
120
+ policy?: SkillsRankingMode;
121
+ }): RankingAnswer;
54
122
  export default function skillsToolExtension(pi: ExtensionAPI): void;
55
123
  export {};
56
124
  //# sourceMappingURL=index.d.ts.map
@@ -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
@@ -21,8 +33,10 @@
21
33
  */
22
34
  import { Type } from "typebox";
23
35
  import { createLogger } from "../../../lib/core/logger.js";
24
- import { registerAutoInject, updateSkillCache, getSkillStats, getDurableSkillStats, resolveDiscoveryMode, } from "./auto-inject.js";
25
- import { readSkillTriggers } from "./skill-triggers.js";
36
+ import { getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
37
+ import { registerAutoInject, updateSkillCache, getSkillStats, getDurableSkillStats, resolveDiscoveryMode, rankSkillsDeterministic, } from "./auto-inject.js";
38
+ import { readSkillTriggerEntries } from "./skill-triggers.js";
39
+ import { clampSectionsMax, DEFAULT_SECTIONS_MAX, SECTIONS_MAX_LIMIT, readSkillReach, } from "./reach.js";
26
40
  import { getMonthlyAdoptionRollup } from "./session-records.js";
27
41
  const log = createLogger("skills-tool");
28
42
  let cachedSkills = [];
@@ -33,10 +47,13 @@ let cachedSkills = [];
33
47
  * shape), and the memoized read makes repeat turns stat-only.
34
48
  */
35
49
  export function setCachedSkills(skills) {
36
- cachedSkills = skills.map((s) => ({
37
- ...s,
38
- triggers: readSkillTriggers(s.filePath, s.description),
39
- }));
50
+ cachedSkills = skills.map((s) => {
51
+ const entries = readSkillTriggerEntries(s.filePath, s.description);
52
+ const triggerSources = {};
53
+ for (const entry of entries)
54
+ triggerSources[entry.phrase] = entry.source;
55
+ return { ...s, triggers: entries.map((entry) => entry.phrase), triggerSources };
56
+ });
40
57
  // Sync with auto-inject subsystem (enriched cache — triggers ride along)
41
58
  updateSkillCache(cachedSkills);
42
59
  log.debug(`Cached ${skills.length} skills for list_skills tool`);
@@ -64,16 +81,100 @@ function formatSource(skill) {
64
81
  return "project";
65
82
  return src;
66
83
  }
84
+ /**
85
+ * The current task text: the newest user message on the live branch.
86
+ *
87
+ * A tool call carries no prompt of its own and pi hands tools no turn prompt,
88
+ * but the branch does — and its newest user message is the task the agent is
89
+ * working on. A resumed session therefore ranks against its real task even
90
+ * though this process never saw the prompt arrive. Best-effort: no branch, an
91
+ * unreadable entry, or a non-text message yields "", and the caller then
92
+ * returns the catalog order rather than inventing a task.
93
+ */
94
+ export function currentTaskText(ctx) {
95
+ try {
96
+ const sm = ctx.sessionManager;
97
+ const branch = sm?.getBranch?.() ?? [];
98
+ for (let i = branch.length - 1; i >= 0; i--) {
99
+ const entry = branch[i];
100
+ if (entry?.type !== "message" || entry.message?.role !== "user")
101
+ continue;
102
+ const content = entry.message.content;
103
+ if (typeof content === "string")
104
+ return content;
105
+ if (Array.isArray(content)) {
106
+ return content
107
+ .map((part) => part)
108
+ .filter((part) => part?.type === "text" && typeof part.text === "string")
109
+ .map((part) => part.text)
110
+ .join("\n");
111
+ }
112
+ return "";
113
+ }
114
+ }
115
+ catch {
116
+ // Best-effort: a stale ctx or an absent tree yields no text.
117
+ }
118
+ return "";
119
+ }
120
+ /** Reorder `skills` by `names`, appending everything the list did not mention. */
121
+ function orderByNames(skills, names) {
122
+ const byName = new Map(skills.map((s) => [s.name, s]));
123
+ const out = [];
124
+ for (const name of names) {
125
+ const skill = byName.get(name);
126
+ if (!skill)
127
+ continue;
128
+ byName.delete(name);
129
+ out.push(skill);
130
+ }
131
+ for (const skill of skills)
132
+ if (byName.has(skill.name))
133
+ out.push(skill);
134
+ return out;
135
+ }
136
+ /**
137
+ * Resolve the catalog order for one read.
138
+ *
139
+ * `keyword` and `catalog` are the two answers: the deterministic ranking (with
140
+ * its verdict on how confident that ranking is), or the plain catalog. A
141
+ * missing task text is nobody's question, so the catalog order stands and the
142
+ * report says `no-task` rather than pretending to rank.
143
+ */
144
+ export function resolveRanking(ctx, skills, options) {
145
+ if (options.rank === "catalog")
146
+ return { order: skills, relevance: new Map() };
147
+ const det = rankSkillsDeterministic(skills, currentTaskText(ctx));
148
+ const relevance = new Map();
149
+ for (const row of det.ranked)
150
+ relevance.set(row.skill.name, rowOf(row));
151
+ const order = det.basis === "no-task"
152
+ ? skills
153
+ : orderByNames(skills, det.ranked.map((row) => row.skill.name));
154
+ return {
155
+ order,
156
+ ranking: {
157
+ tier: "keyword",
158
+ basis: det.basis,
159
+ policy: options.policy ?? getSkillsRankingMode(),
160
+ },
161
+ relevance,
162
+ };
163
+ }
164
+ /** A ranked row as the response reports it (only rows with evidence get here). */
165
+ function rowOf(row) {
166
+ return { score: row.score, reason: row.reason ?? "description" };
167
+ }
67
168
  // Extension factory:
68
169
  export default function skillsToolExtension(pi) {
69
170
  registerAutoInject(pi);
70
171
  pi.registerTool({
71
172
  name: "list_skills",
72
173
  label: "List Skills",
73
- description: "Discover skills on demand: paginated catalog (name, filePath, description, source); `read` a SKILL.md to load it.",
174
+ description: "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.",
74
175
  parameters: Type.Object({
75
176
  action: Type.Literal("list", {
76
- description: "list = paginated catalog (name, filePath, description, source)",
177
+ description: "list = paginated catalog with per-skill reach (reachable, lines, bytes, chars, estTokens, sectionCount, sections)",
77
178
  }),
78
179
  page: Type.Optional(Type.Number({
79
180
  minimum: 1,
@@ -86,32 +187,65 @@ export default function skillsToolExtension(pi) {
86
187
  default: 10,
87
188
  description: "Entries per page for list",
88
189
  })),
190
+ sectionsMax: Type.Optional(Type.Number({
191
+ minimum: 0,
192
+ maximum: SECTIONS_MAX_LIMIT,
193
+ default: DEFAULT_SECTIONS_MAX,
194
+ description: "Headings reported per skill; 0 omits the section list and keeps sectionCount",
195
+ })),
196
+ rank: Type.Optional(Type.Union([Type.Literal("relevance"), Type.Literal("catalog")], {
197
+ default: "relevance",
198
+ description: "relevance (default) = order by fit to the current task; catalog = the plain catalog order, with no ranking fields",
199
+ })),
89
200
  }),
90
- execute: async (_id, params, _signal, _onUpdate, _ctx) => {
201
+ execute: async (_id, params, signal, _onUpdate, ctx) => {
91
202
  const page = params.page ?? 1;
92
203
  const pageSize = params.pageSize ?? 10;
93
- const start = (page - 1) * pageSize;
204
+ const sectionsMax = clampSectionsMax(params.sectionsMax);
205
+ const rank = params.rank ?? "relevance";
94
206
  // Explicit-invocation-only skills stay out of the catalog; the cache
95
207
  // itself stays unfiltered for the read-detector that counts explicit
96
208
  // loads.
97
209
  const visible = cachedSkills.filter((s) => !s.disableModelInvocation);
98
- const slice = visible.slice(start, start + pageSize);
99
- const total = visible.length;
210
+ const answer = resolveRanking(ctx, visible, { rank });
211
+ const total = answer.order.length;
212
+ const start = (page - 1) * pageSize;
213
+ const slice = answer.order.slice(start, start + pageSize);
100
214
  const hasMore = start + pageSize < total;
101
215
  const skills = slice.map((s) => ({
102
216
  name: s.name,
103
217
  filePath: s.filePath,
104
218
  description: (s.description ?? "").slice(0, 280),
105
219
  source: formatSource(s),
220
+ ...readSkillReach(s.filePath, sectionsMax),
221
+ // Evidence where it exists: a row with no match carries no relevance
222
+ // field. Every row paying ~60 bytes for "nothing matched" pushed the
223
+ // shipped page past its measured prompt budget (12.0KB -> 12.8KB), and
224
+ // the empty object carried no information the absence does not.
225
+ ...(answer.relevance.has(s.name) ? { relevance: answer.relevance.get(s.name) } : {}),
106
226
  }));
107
227
  return {
108
228
  content: [
109
229
  {
110
230
  type: "text",
111
- text: JSON.stringify({ page, pageSize, total, hasMore, skills }, null, 2),
231
+ text: JSON.stringify({
232
+ page,
233
+ pageSize,
234
+ total,
235
+ hasMore,
236
+ ...(answer.ranking ? { ranking: answer.ranking } : {}),
237
+ skills,
238
+ }, null, 2),
112
239
  },
113
240
  ],
114
- details: { total, page, pageSize, hasMore, returned: skills.length },
241
+ details: {
242
+ total,
243
+ page,
244
+ pageSize,
245
+ hasMore,
246
+ returned: skills.length,
247
+ ...(answer.ranking ? { tier: answer.ranking.tier, basis: answer.ranking.basis } : {}),
248
+ },
115
249
  };
116
250
  },
117
251
  });