pi-braid 0.40.3 → 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 +178 -17
  13. package/dist/extensions/core/skills-tool/auto-inject.js +264 -23
  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 +74 -13
  19. package/dist/extensions/core/skills-tool/skill-triggers.js +105 -24
  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 +2 -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 +350 -27
  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 +130 -23
  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
@@ -8,13 +8,27 @@
8
8
  *
9
9
  * Design:
10
10
  * 1. Relevance detection: keyword match of skill name/description plus
11
- * frontmatter trigger phrases against the user's current prompt.
11
+ * curated trigger phrases against the user's current prompt.
12
12
  * Qualification bar: a skill whose match never touches its NAME (name
13
13
  * token or trigger phrase) must reach a score of at least
14
14
  * MIN_NON_NAME_SCORE — a lone description/path keyword hit is too weak
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 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.
27
+ * 1b. Ranking: equal scores compare by more distinct matched signals, then
28
+ * by rarer evidence (lower summed document frequency), then by name.
29
+ * Alphabetical order alone decided which of two equally-scored skills
30
+ * took a slot, which is how a broadly-matching skill outranked the one
31
+ * whose evidence was the prompt's actual subject.
18
32
  * 2. Session-scoped state: track which skills were injected on which turn.
19
33
  * Cooldown is per-skill on top of the global floor: an injected skill
20
34
  * cools down at least COOLDOWN_TURNS, and once it was actually loaded
@@ -130,6 +144,33 @@ export const MAX_EXCERPT_CHARS = 300;
130
144
  * and/or filePath keyword hits only). Name matches qualify at any score.
131
145
  */
132
146
  export const MIN_NON_NAME_SCORE = 2;
147
+ /**
148
+ * A keyword present in this many skill documents or more is corpus-common: it
149
+ * appears in a large share of the catalog (5 of 22 skills = 23%), so it cannot
150
+ * distinguish one skill from another and contributes NOTHING to the weak legs
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.
153
+ *
154
+ * The number is measured, not guessed. Two measurements, one threshold:
155
+ *
156
+ * Corpus mass. Over 400 recorded prompts against the 22-skill catalog, the
157
+ * weak-leg points awarded to words by document frequency are df1 17.0%,
158
+ * df2 22.4%, df3 20.9%, df4 13.3%, df5 7.8%, df6 4.1%, df7 9.1%, df9 0.4%,
159
+ * df22 5.1%. Words at df ≥ 5 carry 26.4% of every weak-leg point the matcher
160
+ * awards; df ≥ 4 carries 39.7%, df ≥ 6 carries 18.6%. The catalog's generic
161
+ * vocabulary starts here (skill, read, prompt, text, build, change, agent,
162
+ * line); below it the words still describe work types (review, check, test,
163
+ * edit, documentation).
164
+ *
165
+ * Labelled set. 26 recorded prompts, recall@2 by threshold: df ≥ 4 → 12/23,
166
+ * df ≥ 5 → 13/23, df ≥ 6 → 13/23, df ≥ 7 → 14/23, no gate at all → 12/23.
167
+ * Recall alone cannot choose the number: every step that weakens the gate
168
+ * admits more skills (45, 54, 67, 71, 106 admissions) and admitting more can
169
+ * only raise a top-2 recall figure. 5 is where the gate removes a quarter of
170
+ * the corpus-common mass without also deleting the work-type words that are
171
+ * sometimes a skill's only reachable evidence.
172
+ */
173
+ export const COMMON_KEYWORD_DF = 5;
133
174
  /**
134
175
  * Common English words to exclude from keyword matching.
135
176
  * Kept small — only the most frequent noise words that would
@@ -237,76 +278,201 @@ export function extractKeywords(text) {
237
278
  return [...new Set(words)];
238
279
  }
239
280
  // Relevance Scoring
281
+ /**
282
+ * The text a skill contributes to the corpus-frequency count: its description
283
+ * plus its own catalog path (`<dir>/skill.md`). Deliberately NOT the absolute
284
+ * path: a checkout root puts its own directory names ("private", "packages",
285
+ * a worktree name) in every one of the 22 documents — measured at df 22 for
286
+ * `private`, `package`, `pack` and `core`, and different on every machine the
287
+ * agent runs on. On description plus the skill's own directory those four
288
+ * measure df 0, 1, 1 and 2; `skill` and `kill` stay catalog-wide because the
289
+ * file itself is named SKILL.md, and the rarity gate is what removes them.
290
+ * Lowercased; the matcher tests substrings. Pure.
291
+ */
292
+ export function skillCorpusDocument(skill) {
293
+ const tail = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
294
+ return `${skill.description.toLowerCase()} ${tail}`;
295
+ }
296
+ /**
297
+ * Document frequency of each keyword across the cached skills: how many skill
298
+ * documents contain it as a substring (the test every weak leg performs).
299
+ * Computed once per turn from the cache, for the prompt's keywords only. Pure
300
+ * given the cache.
301
+ */
302
+ export function corpusKeywordFrequency(keywords, skills) {
303
+ const docs = skills.map(skillCorpusDocument);
304
+ const freq = new Map();
305
+ for (const kw of keywords) {
306
+ let n = 0;
307
+ for (const doc of docs)
308
+ if (doc.includes(kw))
309
+ n++;
310
+ freq.set(kw, n);
311
+ }
312
+ return freq;
313
+ }
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 };
240
342
  /**
241
343
  * Score a skill against a set of keywords.
242
344
  *
243
345
  * Scoring rules:
244
- * +3 skill name contains a keyword (exact match)
245
- * +2 skill name contains a keyword as substring
246
- * +2 a frontmatter trigger phrase occurs in the prompt (word-bounded)
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
348
+ * +2 a trigger phrase occurs in the prompt (word-bounded)
247
349
  * +1 skill description contains a keyword
248
- * +1 skill filePath contains a keyword (e.g. "research" in "research/SKILL.md")
350
+ * +1 the skill's own catalog path contains a keyword (e.g. "research" in
351
+ * "research/skill.md")
249
352
  *
250
353
  * A trigger hit counts as a name hit: the phrase is the skill author's own
251
354
  * relevance signal, so it qualifies the skill the same way a name match does.
252
355
  *
356
+ * `keywordDf` is the corpus document frequency of the prompt's keywords (see
357
+ * corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
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).
363
+ *
253
364
  * Qualification bar: a skill whose match never touches its NAME (description
254
365
  * and/or filePath hits only) must reach a total score of at least
255
366
  * MIN_NON_NAME_SCORE — one description keyword is too weak a signal and
256
367
  * lets generic skills fire on almost any prompt. Name and trigger matches
257
368
  * always qualify.
258
369
  *
259
- * `promptText` (lowercased by the caller or raw — matching is case-insensitive
260
- * on our side) enables trigger matching; omit it where the raw prompt is not
370
+ * `promptText` enables trigger matching; omit it where the raw prompt is not
261
371
  * available and only keyword scoring should run.
262
372
  *
263
- * Returns 0 if the skill does not qualify.
373
+ * Returns the zero match if the skill does not qualify.
264
374
  */
265
- export function scoreSkill(skill, keywords, promptText) {
375
+ export function matchSkill(skill, keywords, promptText, keywordDf) {
266
376
  let score = 0;
377
+ let signals = 0;
378
+ let evidenceDf = 0;
267
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
+ };
268
385
  const name = skill.name.toLowerCase();
386
+ const nameTokens = name.split(/[^a-z0-9]+/).filter(Boolean);
269
387
  const desc = skill.description.toLowerCase();
270
- const path = skill.filePath.toLowerCase();
388
+ const path = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
389
+ const dfOf = (kw) => keywordDf?.get(kw) ?? 0;
271
390
  for (const trig of skill.triggers ?? []) {
272
391
  if (triggerMatches(trig, promptText ?? "")) {
273
392
  score += 2;
393
+ signals++;
274
394
  nameHit = true;
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");
275
398
  }
276
399
  }
277
400
  for (const kw of keywords) {
278
- // Exact token match in name
279
- if (name.split(/[^a-z0-9]+/).includes(kw)) {
401
+ const df = dfOf(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") {
280
405
  score += 3;
406
+ signals++;
281
407
  nameHit = true;
408
+ evidenceDf += df;
409
+ noteReason("name");
282
410
  continue;
283
411
  }
284
- // Substring match in name (catches compound names like "code-search")
285
- 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) {
286
415
  score += 2;
416
+ signals++;
287
417
  nameHit = true;
418
+ evidenceDf += df;
419
+ noteReason("name");
288
420
  continue;
289
421
  }
290
- // Description contains keyword
422
+ // Corpus-common keyword: the weak legs score nothing for it, so a prompt
423
+ // full of generic vocabulary cannot buy a slot.
424
+ if (df >= COMMON_KEYWORD_DF)
425
+ continue;
426
+ let weakHit = false;
291
427
  if (desc.includes(kw)) {
292
428
  score += 1;
293
- continue;
429
+ weakHit = true;
294
430
  }
295
431
  // File path matches (e.g. "research" in "research/SKILL.md")
296
432
  if (path.includes(kw)) {
297
433
  score += 1;
434
+ weakHit = true;
435
+ }
436
+ // One signal per distinct keyword: a word present in both the description
437
+ // and the path is one piece of evidence, not two.
438
+ if (weakHit) {
439
+ signals++;
440
+ evidenceDf += df;
441
+ noteReason("description");
298
442
  }
299
443
  }
300
444
  if (!nameHit && score < MIN_NON_NAME_SCORE)
301
- return 0;
302
- return score;
445
+ return NO_MATCH;
446
+ return { score, signals, evidenceDf, reason };
447
+ }
448
+ /** The score alone (see matchSkill for the rules and the rarity gate). */
449
+ export function scoreSkill(skill, keywords, promptText, keywordDf) {
450
+ return matchSkill(skill, keywords, promptText, keywordDf).score;
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));
303
462
  }
304
463
  /**
305
464
  * Decide which scored skills to suggest given the session injection state.
465
+ *
306
466
  * Pure — mirrors the handler's decision path so it can be unit-tested:
307
- * sort (score desc, name asc) → cooldown filter (global floor + per-skill
308
- * loaded extension) → slot budget over ACTIVE held slots (a loaded skill
309
- * released its slot) → top-N slice.
467
+ * sort (score desc, distinct signals desc, evidence df asc, name asc) →
468
+ * cooldown filter (global floor + per-skill loaded extension) → slot budget
469
+ * over ACTIVE held slots (a loaded skill released its slot) → top-N slice.
470
+ *
471
+ * The rank order is the fix for alphabetical slot allocation: two skills with
472
+ * equal points used to be ordered by name, so a broadly-matching skill took
473
+ * the slot from one whose evidence was the prompt's actual subject. Distinct
474
+ * signals separate breadth of match; evidence df separates a match on the
475
+ * prompt's distinctive words from one on its filler.
310
476
  *
311
477
  * Returns the chosen scored items (empty when nothing qualifies). The
312
478
  * caller is responsible for recording the picks in session state.
@@ -314,7 +480,7 @@ export function scoreSkill(skill, keywords, promptText) {
314
480
  export function selectSuggestions(scored, injected, currentTurn) {
315
481
  if (!scored.length)
316
482
  return [];
317
- const sorted = [...scored].sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name));
483
+ const sorted = [...scored].sort(compareScored);
318
484
  const available = sorted.filter((s) => !onCooldown(s.skill.name, injected, currentTurn));
319
485
  if (!available.length)
320
486
  return [];
@@ -326,6 +492,78 @@ export function selectSuggestions(scored, injected, currentTurn) {
326
492
  return [];
327
493
  return available.slice(0, slotBudget);
328
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
+ }
329
567
  /**
330
568
  * Cooldown gate: the global floor applies to every injection; a skill that
331
569
  * was loaded after its injection additionally cools down for
@@ -762,9 +1000,12 @@ export function registerAutoInject(pi) {
762
1000
  if (!keywords.length) {
763
1001
  return; // No significant keywords to match
764
1002
  }
1003
+ // Corpus-common words cannot tell skills apart. Their document frequency
1004
+ // is measured once per turn from the same cache the scorer reads.
1005
+ const keywordDf = corpusKeywordFrequency(keywords, skills);
765
1006
  // Score each skill. The raw prompt rides along for trigger matching.
766
1007
  const scored = skills
767
- .map((s) => ({ skill: s, score: scoreSkill(s, keywords, prompt) }))
1008
+ .map((s) => ({ skill: s, ...matchSkill(s, keywords, prompt, keywordDf) }))
768
1009
  .filter((s) => s.score > 0);
769
1010
  if (!scored.length) {
770
1011
  return; // No relevant skills found
@@ -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