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.
- package/AGENTS.md +17 -18
- package/README.md +128 -130
- package/TOOLS.md +35 -35
- package/build-info.json +4 -4
- package/dist/extensions/core/agent-environment/index.js +4 -3
- package/dist/extensions/core/prompt-builder/index.js +12 -7
- package/dist/extensions/core/prompt-builder/instance-composition.d.ts +51 -10
- package/dist/extensions/core/prompt-builder/instance-composition.js +87 -14
- package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +3 -3
- package/dist/extensions/core/prompt-builder/system-info-tool.js +3 -3
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +89 -10
- package/dist/extensions/core/skills-tool/auto-inject.js +150 -21
- package/dist/extensions/core/skills-tool/index.d.ts +70 -2
- package/dist/extensions/core/skills-tool/index.js +149 -15
- package/dist/extensions/core/skills-tool/reach.d.ts +119 -0
- package/dist/extensions/core/skills-tool/reach.js +213 -0
- package/dist/extensions/core/skills-tool/skill-triggers.d.ts +47 -10
- package/dist/extensions/core/skills-tool/skill-triggers.js +66 -23
- package/dist/extensions/enforcement/handlers/register-session-compact.js +12 -1
- package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +15 -34
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +2 -1
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +55 -28
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +14 -10
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +88 -82
- package/dist/extensions/enforcement/resume-state.d.ts +76 -0
- package/dist/extensions/enforcement/resume-state.js +90 -0
- package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +9 -0
- package/dist/extensions/enforcement/substate/context-hygiene-state.js +8 -0
- package/dist/extensions/enforcement/whisper.d.ts +12 -0
- package/dist/extensions/enforcement/whisper.js +16 -1
- package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +14 -6
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +7 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +372 -0
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +8 -2
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +54 -21
- package/dist/lib/config/braid-paths.d.ts +14 -0
- package/dist/lib/config/braid-paths.js +18 -0
- package/dist/lib/config/braid-settings.d.ts +21 -0
- package/dist/lib/config/braid-settings.js +16 -0
- package/dist/lib/detection/context-tiers.d.ts +47 -3
- package/dist/lib/detection/context-tiers.js +122 -13
- package/dist/lib/events/turn-boundary.d.ts +78 -0
- package/dist/lib/events/turn-boundary.js +91 -0
- package/dist/lib/orchestrator/workers.d.ts +3 -2
- package/dist/lib/orchestrator/workers.js +22 -4
- package/dist/lib/state/global-state.d.ts +1 -1
- package/docs/CONTEXT-MAP.md +1 -1
- package/docs/CONTEXT-POLICY.md +8 -0
- package/docs/FLEET.md +99 -0
- package/docs/LOCAL_DEV.md +0 -1
- package/docs/ROADMAP.md +5 -5
- package/docs/SETUP.md +19 -18
- package/package.json +5 -1
- package/scripts/fleet/cli.mjs +499 -0
- package/scripts/fleet/driver-rpc.mjs +376 -0
- package/scripts/fleet/driver-scripted.mjs +239 -0
- package/scripts/fleet/journal.mjs +994 -0
- package/scripts/fleet/procs.mjs +76 -0
- package/scripts/fleet/supervisor.mjs +1494 -0
- package/scripts/fleet/tool-guard.mjs +467 -0
- package/skills/herdr-topology/SKILL.md +6 -1
- package/skills/release-pipeline/SKILL.md +20 -4
- package/skills/research/SKILL.md +32 -0
- package/skills/subagent-orchestration/SKILL.md +2 -2
- package/src/extensions/core/agent-environment/index.ts +4 -3
- package/src/extensions/core/prompt-builder/AGENTS.md +8 -4
- package/src/extensions/core/prompt-builder/index.ts +12 -7
- package/src/extensions/core/prompt-builder/instance-composition.ts +98 -14
- package/src/extensions/core/prompt-builder/system-info-tool.ts +3 -3
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
- package/src/extensions/core/skills-tool/auto-inject.ts +196 -24
- package/src/extensions/core/skills-tool/index.ts +217 -15
- package/src/extensions/core/skills-tool/reach.ts +256 -0
- package/src/extensions/core/skills-tool/skill-triggers.ts +90 -20
- package/src/extensions/enforcement/handlers/register-session-compact.ts +12 -1
- package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +23 -36
- package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +59 -29
- package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +101 -81
- package/src/extensions/enforcement/resume-state.ts +127 -0
- package/src/extensions/enforcement/substate/context-hygiene-state.ts +17 -0
- package/src/extensions/enforcement/whisper.ts +21 -1
- package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +20 -5
- package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +370 -0
- package/src/extensions/memory/AGENTS.md +25 -1
- package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +80 -27
- package/src/lib/config/braid-paths.ts +20 -0
- package/src/lib/config/braid-settings.ts +46 -0
- package/src/lib/detection/context-tiers.ts +186 -13
- package/src/lib/events/AGENTS.md +1 -0
- package/src/lib/events/turn-boundary.ts +115 -0
- package/src/lib/orchestrator/workers.ts +33 -12
- package/src/lib/state/global-state.ts +1 -0
- package/src/lib/utils/AGENTS.md +1 -1
- 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
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
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
|
-
|
|
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
|
|
315
|
-
* +2 skill name
|
|
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
|
|
327
|
-
*
|
|
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
|
-
|
|
360
|
-
|
|
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
|
-
//
|
|
368
|
-
|
|
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(
|
|
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 {
|
|
25
|
-
import {
|
|
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
|
-
|
|
38
|
-
|
|
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 (
|
|
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,
|
|
201
|
+
execute: async (_id, params, signal, _onUpdate, ctx) => {
|
|
91
202
|
const page = params.page ?? 1;
|
|
92
203
|
const pageSize = params.pageSize ?? 10;
|
|
93
|
-
const
|
|
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
|
|
99
|
-
const total =
|
|
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({
|
|
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: {
|
|
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
|
});
|