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.
- package/AGENTS.md +17 -18
- package/README.md +116 -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 +178 -17
- package/dist/extensions/core/skills-tool/auto-inject.js +264 -23
- 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 +74 -13
- package/dist/extensions/core/skills-tool/skill-triggers.js +105 -24
- 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-POLICY.md +8 -0
- package/docs/LOCAL_DEV.md +0 -1
- package/docs/ROADMAP.md +5 -5
- package/docs/SETUP.md +19 -18
- package/package.json +2 -1
- package/skills/herdr-topology/SKILL.md +6 -1
- 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 +350 -27
- 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 +130 -23
- 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
|
@@ -8,13 +8,27 @@
|
|
|
8
8
|
*
|
|
9
9
|
* Design:
|
|
10
10
|
* 1. Relevance detection: keyword match of skill name/description plus
|
|
11
|
-
*
|
|
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
|
|
@@ -99,6 +113,7 @@ import {
|
|
|
99
113
|
recordSessionStart,
|
|
100
114
|
} from "./session-records.js";
|
|
101
115
|
import { triggerMatches } from "./skill-triggers.js";
|
|
116
|
+
import type { TriggerSource } from "./skill-triggers.js";
|
|
102
117
|
|
|
103
118
|
const log = createLogger("skills-auto-inject");
|
|
104
119
|
|
|
@@ -145,6 +160,34 @@ export const MAX_EXCERPT_CHARS = 300;
|
|
|
145
160
|
*/
|
|
146
161
|
export const MIN_NON_NAME_SCORE = 2;
|
|
147
162
|
|
|
163
|
+
/**
|
|
164
|
+
* A keyword present in this many skill documents or more is corpus-common: it
|
|
165
|
+
* appears in a large share of the catalog (5 of 22 skills = 23%), so it cannot
|
|
166
|
+
* distinguish one skill from another and contributes NOTHING to the weak legs
|
|
167
|
+
* (description, catalog path) — or to the name leg's token-prefix rule, the one
|
|
168
|
+
* name hit that can rest on a shared word.
|
|
169
|
+
*
|
|
170
|
+
* The number is measured, not guessed. Two measurements, one threshold:
|
|
171
|
+
*
|
|
172
|
+
* Corpus mass. Over 400 recorded prompts against the 22-skill catalog, the
|
|
173
|
+
* weak-leg points awarded to words by document frequency are df1 17.0%,
|
|
174
|
+
* df2 22.4%, df3 20.9%, df4 13.3%, df5 7.8%, df6 4.1%, df7 9.1%, df9 0.4%,
|
|
175
|
+
* df22 5.1%. Words at df ≥ 5 carry 26.4% of every weak-leg point the matcher
|
|
176
|
+
* awards; df ≥ 4 carries 39.7%, df ≥ 6 carries 18.6%. The catalog's generic
|
|
177
|
+
* vocabulary starts here (skill, read, prompt, text, build, change, agent,
|
|
178
|
+
* line); below it the words still describe work types (review, check, test,
|
|
179
|
+
* edit, documentation).
|
|
180
|
+
*
|
|
181
|
+
* Labelled set. 26 recorded prompts, recall@2 by threshold: df ≥ 4 → 12/23,
|
|
182
|
+
* df ≥ 5 → 13/23, df ≥ 6 → 13/23, df ≥ 7 → 14/23, no gate at all → 12/23.
|
|
183
|
+
* Recall alone cannot choose the number: every step that weakens the gate
|
|
184
|
+
* admits more skills (45, 54, 67, 71, 106 admissions) and admitting more can
|
|
185
|
+
* only raise a top-2 recall figure. 5 is where the gate removes a quarter of
|
|
186
|
+
* the corpus-common mass without also deleting the work-type words that are
|
|
187
|
+
* sometimes a skill's only reachable evidence.
|
|
188
|
+
*/
|
|
189
|
+
export const COMMON_KEYWORD_DF = 5;
|
|
190
|
+
|
|
148
191
|
/**
|
|
149
192
|
* Common English words to exclude from keyword matching.
|
|
150
193
|
* Kept small — only the most frequent noise words that would
|
|
@@ -249,6 +292,8 @@ export interface CachedSkill {
|
|
|
249
292
|
disableModelInvocation?: boolean;
|
|
250
293
|
/** Frontmatter trigger phrases (setCachedSkills resolves them from SKILL.md). */
|
|
251
294
|
triggers?: string[];
|
|
295
|
+
/** Which source authored each phrase (the row's evidence label). */
|
|
296
|
+
triggerSources?: Record<string, TriggerSource>;
|
|
252
297
|
}
|
|
253
298
|
|
|
254
299
|
// Shared module-level variable rather than a per-module copy: the import
|
|
@@ -296,93 +341,267 @@ export function extractKeywords(text: string): string[] {
|
|
|
296
341
|
|
|
297
342
|
// Relevance Scoring
|
|
298
343
|
|
|
344
|
+
/**
|
|
345
|
+
* The text a skill contributes to the corpus-frequency count: its description
|
|
346
|
+
* plus its own catalog path (`<dir>/skill.md`). Deliberately NOT the absolute
|
|
347
|
+
* path: a checkout root puts its own directory names ("private", "packages",
|
|
348
|
+
* a worktree name) in every one of the 22 documents — measured at df 22 for
|
|
349
|
+
* `private`, `package`, `pack` and `core`, and different on every machine the
|
|
350
|
+
* agent runs on. On description plus the skill's own directory those four
|
|
351
|
+
* measure df 0, 1, 1 and 2; `skill` and `kill` stay catalog-wide because the
|
|
352
|
+
* file itself is named SKILL.md, and the rarity gate is what removes them.
|
|
353
|
+
* Lowercased; the matcher tests substrings. Pure.
|
|
354
|
+
*/
|
|
355
|
+
export function skillCorpusDocument(skill: CachedSkill): string {
|
|
356
|
+
const tail = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
|
|
357
|
+
return `${skill.description.toLowerCase()} ${tail}`;
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
/**
|
|
361
|
+
* Document frequency of each keyword across the cached skills: how many skill
|
|
362
|
+
* documents contain it as a substring (the test every weak leg performs).
|
|
363
|
+
* Computed once per turn from the cache, for the prompt's keywords only. Pure
|
|
364
|
+
* given the cache.
|
|
365
|
+
*/
|
|
366
|
+
export function corpusKeywordFrequency(
|
|
367
|
+
keywords: string[],
|
|
368
|
+
skills: CachedSkill[],
|
|
369
|
+
): Map<string, number> {
|
|
370
|
+
const docs = skills.map(skillCorpusDocument);
|
|
371
|
+
const freq = new Map<string, number>();
|
|
372
|
+
for (const kw of keywords) {
|
|
373
|
+
let n = 0;
|
|
374
|
+
for (const doc of docs) if (doc.includes(kw)) n++;
|
|
375
|
+
freq.set(kw, n);
|
|
376
|
+
}
|
|
377
|
+
return freq;
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
/** One skill's match against a prompt: points, distinct signals, evidence rarity. */
|
|
381
|
+
export interface SkillMatch {
|
|
382
|
+
/** Score the qualification bar and the ranking read (same scale as before). */
|
|
383
|
+
score: number;
|
|
384
|
+
/** Distinct matched signals: each trigger phrase, each distinct keyword. */
|
|
385
|
+
signals: number;
|
|
386
|
+
/** Summed document frequency of the matched keywords — lower is rarer. */
|
|
387
|
+
evidenceDf: number;
|
|
388
|
+
/** Strongest evidence behind the score; null when the skill did not qualify. */
|
|
389
|
+
reason: RelevanceReason | null;
|
|
390
|
+
}
|
|
391
|
+
|
|
392
|
+
/**
|
|
393
|
+
* What the strongest evidence for a row was. Short on purpose: a ranking row
|
|
394
|
+
* says "trigger", not a sentence — the reader is choosing a read, not reading
|
|
395
|
+
* an explanation.
|
|
396
|
+
*
|
|
397
|
+
* trigger — an authored phrase from frontmatter or the description tail
|
|
398
|
+
* heading — an authored phrase from a `## trigger:` body heading
|
|
399
|
+
* name — a keyword in the skill's own name
|
|
400
|
+
* description — a description or catalog-path keyword (the weak legs)
|
|
401
|
+
*/
|
|
402
|
+
export type RelevanceReason = "trigger" | "heading" | "name" | "description";
|
|
403
|
+
|
|
404
|
+
/** Evidence strength for the row's single `reason` field. */
|
|
405
|
+
const REASON_STRENGTH: Record<RelevanceReason, number> = {
|
|
406
|
+
trigger: 4,
|
|
407
|
+
heading: 3,
|
|
408
|
+
name: 2,
|
|
409
|
+
description: 1,
|
|
410
|
+
};
|
|
411
|
+
|
|
412
|
+
/**
|
|
413
|
+
* How a keyword occurs in a skill name: as a whole token, as the start of a
|
|
414
|
+
* longer token, or not at all.
|
|
415
|
+
*
|
|
416
|
+
* The third answer is the fix: the name leg used to award points to any
|
|
417
|
+
* substring anywhere in the name, so a corpus-common word ("line", df 7 of 22)
|
|
418
|
+
* scored +2 for placement-disc**line** and release-pi**peline** and carried the
|
|
419
|
+
* name-hit exemption from the qualification bar with it. A word buried inside
|
|
420
|
+
* a coined token names the author's coinage, not the prompt's subject; a word
|
|
421
|
+
* that starts a token still reads as the author's own vocabulary ("engine" in
|
|
422
|
+
* software-engineer).
|
|
423
|
+
*/
|
|
424
|
+
function nameOccurrence(tokens: string[], kw: string): "token" | "prefix" | null {
|
|
425
|
+
if (tokens.includes(kw)) return "token";
|
|
426
|
+
for (const token of tokens) if (token.length > kw.length && token.startsWith(kw)) return "prefix";
|
|
427
|
+
return null;
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
const NO_MATCH: SkillMatch = { score: 0, signals: 0, evidenceDf: 0, reason: null };
|
|
431
|
+
|
|
299
432
|
/**
|
|
300
433
|
* Score a skill against a set of keywords.
|
|
301
434
|
*
|
|
302
435
|
* Scoring rules:
|
|
303
|
-
* +3 skill name
|
|
304
|
-
* +2 skill name
|
|
305
|
-
* +2 a
|
|
436
|
+
* +3 skill name carries a keyword as a whole token (exact match)
|
|
437
|
+
* +2 skill name starts a token with a keyword, below the frequency gate
|
|
438
|
+
* +2 a trigger phrase occurs in the prompt (word-bounded)
|
|
306
439
|
* +1 skill description contains a keyword
|
|
307
|
-
* +1 skill
|
|
440
|
+
* +1 the skill's own catalog path contains a keyword (e.g. "research" in
|
|
441
|
+
* "research/skill.md")
|
|
308
442
|
*
|
|
309
443
|
* A trigger hit counts as a name hit: the phrase is the skill author's own
|
|
310
444
|
* relevance signal, so it qualifies the skill the same way a name match does.
|
|
311
445
|
*
|
|
446
|
+
* `keywordDf` is the corpus document frequency of the prompt's keywords (see
|
|
447
|
+
* corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
|
|
448
|
+
* nothing on the weak legs, and nothing on the name leg's token-prefix rule:
|
|
449
|
+
* a common word that only starts a token ("line" in "line-counting") is
|
|
450
|
+
* vocabulary the catalog shares, not the skill's own. Passing no map scores
|
|
451
|
+
* every keyword at full weight (the pre-rarity behavior, which the unit
|
|
452
|
+
* fixtures pin).
|
|
453
|
+
*
|
|
312
454
|
* Qualification bar: a skill whose match never touches its NAME (description
|
|
313
455
|
* and/or filePath hits only) must reach a total score of at least
|
|
314
456
|
* MIN_NON_NAME_SCORE — one description keyword is too weak a signal and
|
|
315
457
|
* lets generic skills fire on almost any prompt. Name and trigger matches
|
|
316
458
|
* always qualify.
|
|
317
459
|
*
|
|
318
|
-
* `promptText`
|
|
319
|
-
* on our side) enables trigger matching; omit it where the raw prompt is not
|
|
460
|
+
* `promptText` enables trigger matching; omit it where the raw prompt is not
|
|
320
461
|
* available and only keyword scoring should run.
|
|
321
462
|
*
|
|
322
|
-
* Returns
|
|
463
|
+
* Returns the zero match if the skill does not qualify.
|
|
323
464
|
*/
|
|
324
|
-
export function
|
|
465
|
+
export function matchSkill(
|
|
466
|
+
skill: CachedSkill,
|
|
467
|
+
keywords: string[],
|
|
468
|
+
promptText?: string,
|
|
469
|
+
keywordDf?: ReadonlyMap<string, number>,
|
|
470
|
+
): SkillMatch {
|
|
325
471
|
let score = 0;
|
|
472
|
+
let signals = 0;
|
|
473
|
+
let evidenceDf = 0;
|
|
326
474
|
let nameHit = false;
|
|
475
|
+
let reason: RelevanceReason | null = null;
|
|
476
|
+
const noteReason = (candidate: RelevanceReason) => {
|
|
477
|
+
if (!reason || REASON_STRENGTH[candidate] > REASON_STRENGTH[reason]) reason = candidate;
|
|
478
|
+
};
|
|
327
479
|
const name = skill.name.toLowerCase();
|
|
480
|
+
const nameTokens = name.split(/[^a-z0-9]+/).filter(Boolean);
|
|
328
481
|
const desc = skill.description.toLowerCase();
|
|
329
|
-
const path = skill.filePath.toLowerCase();
|
|
482
|
+
const path = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
|
|
483
|
+
const dfOf = (kw: string) => keywordDf?.get(kw) ?? 0;
|
|
330
484
|
|
|
331
485
|
for (const trig of skill.triggers ?? []) {
|
|
332
486
|
if (triggerMatches(trig, promptText ?? "")) {
|
|
333
487
|
score += 2;
|
|
488
|
+
signals++;
|
|
334
489
|
nameHit = true;
|
|
490
|
+
// A curated phrase is the rarest evidence a skill can offer: df 0. Its
|
|
491
|
+
// provenance is what the row reports as its evidence label.
|
|
492
|
+
noteReason(skill.triggerSources?.[trig] === "heading" ? "heading" : "trigger");
|
|
335
493
|
}
|
|
336
494
|
}
|
|
337
495
|
|
|
338
496
|
for (const kw of keywords) {
|
|
339
|
-
|
|
340
|
-
|
|
497
|
+
const df = dfOf(kw);
|
|
498
|
+
const occurrence = nameOccurrence(nameTokens, kw);
|
|
499
|
+
// Exact token match in name: the skill's own identity vocabulary, never gated.
|
|
500
|
+
if (occurrence === "token") {
|
|
341
501
|
score += 3;
|
|
502
|
+
signals++;
|
|
342
503
|
nameHit = true;
|
|
504
|
+
evidenceDf += df;
|
|
505
|
+
noteReason("name");
|
|
343
506
|
continue;
|
|
344
507
|
}
|
|
345
|
-
//
|
|
346
|
-
|
|
508
|
+
// Token-prefix match in name ("engine" in "software-engineer"): name
|
|
509
|
+
// evidence, but only while the word is distinctive enough to mean it.
|
|
510
|
+
if (occurrence === "prefix" && df < COMMON_KEYWORD_DF) {
|
|
347
511
|
score += 2;
|
|
512
|
+
signals++;
|
|
348
513
|
nameHit = true;
|
|
514
|
+
evidenceDf += df;
|
|
515
|
+
noteReason("name");
|
|
349
516
|
continue;
|
|
350
517
|
}
|
|
351
|
-
//
|
|
518
|
+
// Corpus-common keyword: the weak legs score nothing for it, so a prompt
|
|
519
|
+
// full of generic vocabulary cannot buy a slot.
|
|
520
|
+
if (df >= COMMON_KEYWORD_DF) continue;
|
|
521
|
+
let weakHit = false;
|
|
352
522
|
if (desc.includes(kw)) {
|
|
353
523
|
score += 1;
|
|
354
|
-
|
|
524
|
+
weakHit = true;
|
|
355
525
|
}
|
|
356
526
|
// File path matches (e.g. "research" in "research/SKILL.md")
|
|
357
527
|
if (path.includes(kw)) {
|
|
358
528
|
score += 1;
|
|
529
|
+
weakHit = true;
|
|
530
|
+
}
|
|
531
|
+
// One signal per distinct keyword: a word present in both the description
|
|
532
|
+
// and the path is one piece of evidence, not two.
|
|
533
|
+
if (weakHit) {
|
|
534
|
+
signals++;
|
|
535
|
+
evidenceDf += df;
|
|
536
|
+
noteReason("description");
|
|
359
537
|
}
|
|
360
538
|
}
|
|
361
539
|
|
|
362
|
-
if (!nameHit && score < MIN_NON_NAME_SCORE) return
|
|
363
|
-
return score;
|
|
540
|
+
if (!nameHit && score < MIN_NON_NAME_SCORE) return NO_MATCH;
|
|
541
|
+
return { score, signals, evidenceDf, reason };
|
|
542
|
+
}
|
|
543
|
+
|
|
544
|
+
/** The score alone (see matchSkill for the rules and the rarity gate). */
|
|
545
|
+
export function scoreSkill(
|
|
546
|
+
skill: CachedSkill,
|
|
547
|
+
keywords: string[],
|
|
548
|
+
promptText?: string,
|
|
549
|
+
keywordDf?: ReadonlyMap<string, number>,
|
|
550
|
+
): number {
|
|
551
|
+
return matchSkill(skill, keywords, promptText, keywordDf).score;
|
|
552
|
+
}
|
|
553
|
+
|
|
554
|
+
/**
|
|
555
|
+
* A skill with its match evidence, as the selection step consumes it. The
|
|
556
|
+
* evidence fields are optional so a caller holding only a score still selects;
|
|
557
|
+
* they then default to zero and the name stays the tie-breaker.
|
|
558
|
+
*/
|
|
559
|
+
export interface ScoredSkill {
|
|
560
|
+
skill: CachedSkill;
|
|
561
|
+
score: number;
|
|
562
|
+
signals?: number;
|
|
563
|
+
evidenceDf?: number;
|
|
564
|
+
}
|
|
565
|
+
|
|
566
|
+
/**
|
|
567
|
+
* The ranking comparator, shared by the whisper's selection and the catalog
|
|
568
|
+
* read: score, then breadth of match (distinct signals), then rarity of the
|
|
569
|
+
* evidence (summed document frequency), then name. Pure.
|
|
570
|
+
*/
|
|
571
|
+
function compareScored(a: ScoredSkill, b: ScoredSkill): number {
|
|
572
|
+
return (
|
|
573
|
+
b.score - a.score ||
|
|
574
|
+
(b.signals ?? 0) - (a.signals ?? 0) ||
|
|
575
|
+
(a.evidenceDf ?? 0) - (b.evidenceDf ?? 0) ||
|
|
576
|
+
a.skill.name.localeCompare(b.skill.name)
|
|
577
|
+
);
|
|
364
578
|
}
|
|
365
579
|
|
|
366
580
|
/**
|
|
367
581
|
* Decide which scored skills to suggest given the session injection state.
|
|
582
|
+
*
|
|
368
583
|
* Pure — mirrors the handler's decision path so it can be unit-tested:
|
|
369
|
-
* sort (score desc,
|
|
370
|
-
* loaded extension) → slot budget
|
|
371
|
-
* released its slot) → top-N slice.
|
|
584
|
+
* sort (score desc, distinct signals desc, evidence df asc, name asc) →
|
|
585
|
+
* cooldown filter (global floor + per-skill loaded extension) → slot budget
|
|
586
|
+
* over ACTIVE held slots (a loaded skill released its slot) → top-N slice.
|
|
587
|
+
*
|
|
588
|
+
* The rank order is the fix for alphabetical slot allocation: two skills with
|
|
589
|
+
* equal points used to be ordered by name, so a broadly-matching skill took
|
|
590
|
+
* the slot from one whose evidence was the prompt's actual subject. Distinct
|
|
591
|
+
* signals separate breadth of match; evidence df separates a match on the
|
|
592
|
+
* prompt's distinctive words from one on its filler.
|
|
372
593
|
*
|
|
373
594
|
* Returns the chosen scored items (empty when nothing qualifies). The
|
|
374
595
|
* caller is responsible for recording the picks in session state.
|
|
375
596
|
*/
|
|
376
597
|
export function selectSuggestions(
|
|
377
|
-
scored:
|
|
598
|
+
scored: ScoredSkill[],
|
|
378
599
|
injected: InjectedSkill[],
|
|
379
600
|
currentTurn: number,
|
|
380
|
-
):
|
|
601
|
+
): ScoredSkill[] {
|
|
381
602
|
if (!scored.length) return [];
|
|
382
603
|
|
|
383
|
-
const sorted = [...scored].sort(
|
|
384
|
-
(a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name),
|
|
385
|
-
);
|
|
604
|
+
const sorted = [...scored].sort(compareScored);
|
|
386
605
|
|
|
387
606
|
const available = sorted.filter((s) => !onCooldown(s.skill.name, injected, currentTurn));
|
|
388
607
|
if (!available.length) return [];
|
|
@@ -396,6 +615,106 @@ export function selectSuggestions(
|
|
|
396
615
|
return available.slice(0, slotBudget);
|
|
397
616
|
}
|
|
398
617
|
|
|
618
|
+
// Deterministic ranking for the catalog read
|
|
619
|
+
|
|
620
|
+
/**
|
|
621
|
+
* Declared margin: a gap smaller than this between the first and second
|
|
622
|
+
* qualified skill means the top is a coin flip, and the read says so
|
|
623
|
+
* (`thin-margin`) instead of presenting the order as a decision. The number is
|
|
624
|
+
* deliberate, not measured: one description keyword (+1) is exactly the
|
|
625
|
+
* distance the scorer says is too weak to qualify a skill on its own
|
|
626
|
+
* (MIN_NON_NAME_SCORE), so a lead that one extra weak hit could erase is not a
|
|
627
|
+
* lead.
|
|
628
|
+
*/
|
|
629
|
+
export const RANK_MARGIN_THRESHOLD = 2;
|
|
630
|
+
|
|
631
|
+
/**
|
|
632
|
+
* A task text shorter than this cannot carry a ranking signal: a greeting or a
|
|
633
|
+
* two-word nudge names no domain, so the deterministic tier reports itself
|
|
634
|
+
* short rather than confidently wrong.
|
|
635
|
+
*/
|
|
636
|
+
export const RANK_SHORT_TASK_CHARS = 24;
|
|
637
|
+
|
|
638
|
+
/** Why the deterministic tier answered the way it did. */
|
|
639
|
+
export type RankingBasis =
|
|
640
|
+
| "no-task"
|
|
641
|
+
| "short-task"
|
|
642
|
+
| "no-score"
|
|
643
|
+
| "unambiguous"
|
|
644
|
+
| "tie"
|
|
645
|
+
| "thin-margin";
|
|
646
|
+
|
|
647
|
+
/** One skill as the ranking read consumes it: match evidence plus its label. */
|
|
648
|
+
export interface RankedSkill {
|
|
649
|
+
skill: CachedSkill;
|
|
650
|
+
score: number;
|
|
651
|
+
signals: number;
|
|
652
|
+
evidenceDf: number;
|
|
653
|
+
reason: RelevanceReason | null;
|
|
654
|
+
}
|
|
655
|
+
|
|
656
|
+
/** The deterministic tier's whole answer: an ordered list and a verdict on it. */
|
|
657
|
+
export interface DeterministicRanking {
|
|
658
|
+
/** Qualified skills only, best first (the order the whisper ranks by). */
|
|
659
|
+
ranked: RankedSkill[];
|
|
660
|
+
/** True when the list cannot separate its own top — the escalation trigger. */
|
|
661
|
+
ambiguous: boolean;
|
|
662
|
+
basis: RankingBasis;
|
|
663
|
+
}
|
|
664
|
+
|
|
665
|
+
/**
|
|
666
|
+
* Rank the catalog against a task text without a model. Pure given the cache.
|
|
667
|
+
*
|
|
668
|
+
* Ordering is the whisper's comparator (score, then distinct signals, then
|
|
669
|
+
* summed evidence df, then name) so the two surfaces can never disagree about
|
|
670
|
+
* which skill is better. `ambiguous` is the one thing the whisper does not
|
|
671
|
+
* need: it decides every turn with slots and cooldowns, while a catalog read
|
|
672
|
+
* shows the whole list and therefore must say when its own top is not decided
|
|
673
|
+
* (a tie or a thin margin) or when the task text could not inform it at all.
|
|
674
|
+
*
|
|
675
|
+
* The verdict:
|
|
676
|
+
* no-task — no task text at all; nothing to rank.
|
|
677
|
+
* short-task — the text carries no significant keyword, or is shorter than
|
|
678
|
+
* RANK_SHORT_TASK_CHARS: nothing here can rank a catalog.
|
|
679
|
+
* no-score — every skill scored zero: unambiguous (nothing applies).
|
|
680
|
+
* tie — the top two score the same: ambiguous.
|
|
681
|
+
* thin-margin — the top two sit closer than RANK_MARGIN_THRESHOLD: ambiguous.
|
|
682
|
+
* unambiguous — one skill leads the field by at least the margin.
|
|
683
|
+
*/
|
|
684
|
+
export function rankSkillsDeterministic(
|
|
685
|
+
skills: CachedSkill[],
|
|
686
|
+
taskText: string,
|
|
687
|
+
): DeterministicRanking {
|
|
688
|
+
const text = (taskText ?? "").trim();
|
|
689
|
+
if (!text) return { ranked: [], ambiguous: false, basis: "no-task" };
|
|
690
|
+
const keywords = extractKeywords(text);
|
|
691
|
+
const ranked: RankedSkill[] = [];
|
|
692
|
+
if (keywords.length) {
|
|
693
|
+
const keywordDf = corpusKeywordFrequency(keywords, skills);
|
|
694
|
+
for (const skill of skills) {
|
|
695
|
+
const match = matchSkill(skill, keywords, text, keywordDf);
|
|
696
|
+
if (match.score <= 0) continue;
|
|
697
|
+
ranked.push({
|
|
698
|
+
skill,
|
|
699
|
+
score: match.score,
|
|
700
|
+
signals: match.signals,
|
|
701
|
+
evidenceDf: match.evidenceDf,
|
|
702
|
+
reason: match.reason,
|
|
703
|
+
});
|
|
704
|
+
}
|
|
705
|
+
}
|
|
706
|
+
ranked.sort(compareScored);
|
|
707
|
+
if (text.length < RANK_SHORT_TASK_CHARS || !keywords.length) {
|
|
708
|
+
return { ranked, ambiguous: true, basis: "short-task" };
|
|
709
|
+
}
|
|
710
|
+
if (!ranked.length) return { ranked, ambiguous: false, basis: "no-score" };
|
|
711
|
+
if (ranked.length === 1) return { ranked, ambiguous: false, basis: "unambiguous" };
|
|
712
|
+
const margin = ranked[0].score - ranked[1].score;
|
|
713
|
+
if (margin === 0) return { ranked, ambiguous: true, basis: "tie" };
|
|
714
|
+
if (margin < RANK_MARGIN_THRESHOLD) return { ranked, ambiguous: true, basis: "thin-margin" };
|
|
715
|
+
return { ranked, ambiguous: false, basis: "unambiguous" };
|
|
716
|
+
}
|
|
717
|
+
|
|
399
718
|
/**
|
|
400
719
|
* Cooldown gate: the global floor applies to every injection; a skill that
|
|
401
720
|
* was loaded after its injection additionally cools down for
|
|
@@ -928,9 +1247,13 @@ export function registerAutoInject(pi: ExtensionAPI): void {
|
|
|
928
1247
|
return; // No significant keywords to match
|
|
929
1248
|
}
|
|
930
1249
|
|
|
1250
|
+
// Corpus-common words cannot tell skills apart. Their document frequency
|
|
1251
|
+
// is measured once per turn from the same cache the scorer reads.
|
|
1252
|
+
const keywordDf = corpusKeywordFrequency(keywords, skills);
|
|
1253
|
+
|
|
931
1254
|
// Score each skill. The raw prompt rides along for trigger matching.
|
|
932
1255
|
const scored = skills
|
|
933
|
-
.map((s) => ({ skill: s,
|
|
1256
|
+
.map((s) => ({ skill: s, ...matchSkill(s, keywords, prompt, keywordDf) }))
|
|
934
1257
|
.filter((s) => s.score > 0);
|
|
935
1258
|
|
|
936
1259
|
if (!scored.length) {
|