pi-braid 0.43.6 → 0.43.7
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/CHANGELOG.md +44 -0
- package/build-info.json +4 -4
- package/dist/extensions/core/skills-tool/applicability.d.ts +134 -0
- package/dist/extensions/core/skills-tool/applicability.js +161 -0
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +10 -0
- package/dist/extensions/core/skills-tool/auto-inject.js +216 -1
- package/dist/extensions/core/skills-tool/index.js +64 -3
- package/dist/extensions/core/skills-tool/loading-guidance.js +2 -1
- package/dist/extensions/core/skills-tool/session-records.d.ts +297 -8
- package/dist/extensions/core/skills-tool/session-records.js +509 -5
- package/dist/extensions/core/skills-tool/skill-families.d.ts +60 -0
- package/dist/extensions/core/skills-tool/skill-families.js +105 -0
- package/docs/LOCAL_DEV.md +1 -1
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +1 -0
- package/src/extensions/core/skills-tool/applicability.ts +220 -0
- package/src/extensions/core/skills-tool/auto-inject.ts +274 -0
- package/src/extensions/core/skills-tool/index.ts +75 -2
- package/src/extensions/core/skills-tool/loading-guidance.ts +2 -1
- package/src/extensions/core/skills-tool/session-records.ts +740 -5
- package/src/extensions/core/skills-tool/skill-families.ts +112 -0
package/CHANGELOG.md
CHANGED
|
@@ -53,6 +53,50 @@ record; the tag scheme above applies unchanged.
|
|
|
53
53
|
|
|
54
54
|
---
|
|
55
55
|
|
|
56
|
+
## Core — 0.43.7 (2026-10-30: an ignored skill is visible, and two rates say whether the obligation held)
|
|
57
|
+
|
|
58
|
+
- **A skill that applied and was ignored is now distinguishable from one that never applied.** The
|
|
59
|
+
subsystem could tell whether an agent read a skill and could not tell whether it should have. It now
|
|
60
|
+
records, per session and per skill, a verdict with the phrase that decided it and where the skill
|
|
61
|
+
declares it: `read`, `ignored`, or `not-applicable`, plus a census row naming the installed skills whose
|
|
62
|
+
files declare no condition at all. The record is additive by construction: a new record kind on the
|
|
63
|
+
existing store, refused by the adoption reader so the two cannot silently merge, and an existing
|
|
64
|
+
reader's output is byte-identical when the record is absent. `ignored` over `read + ignored` is the
|
|
65
|
+
rate nobody could compute before, and it is computable from the record alone.
|
|
66
|
+
- **The condition is the author's own declaration, not a coincidence.** Applicability reads the trigger
|
|
67
|
+
phrases the injector already matches, with the injector's own word-boundary rule, so the verdict can
|
|
68
|
+
never disagree with the whisper about whether a phrase is present; 1,098 phrase/text pairs over both
|
|
69
|
+
installed packs were checked for that agreement. The addition is polarity: "do not research this" is a
|
|
70
|
+
session where research did not apply. The negation rule is one cue, not a composed one, so a double
|
|
71
|
+
negative reads as negation and the ignored rate is a lower bound; that is pinned by a test with its
|
|
72
|
+
reason rather than left as a surprise.
|
|
73
|
+
- **A skill declares the tool family its body directs, and the session records what it did with it.** Three
|
|
74
|
+
of the shipped skills declare a family, five declare none because a body that governs no tool family
|
|
75
|
+
genuinely has none, and the contract reports both numbers rather than padding the count. The per-session
|
|
76
|
+
leg records `suggested`, `listed`, `read`, `called`, `applied`, where `applied` is ordered: a call made
|
|
77
|
+
before the read cannot be credited, and a read with no call still satisfies. An applicable skill with no
|
|
78
|
+
leg row is counted unsatisfied rather than dropped, which keeps the ignored population inside the
|
|
79
|
+
denominator.
|
|
80
|
+
- **The obligation rate ships with its own falsifier.** `allSatisfied` over the sessions that carry both a
|
|
81
|
+
verdict and a leg row, reported beside the read rate with that denominator stated rather than implied,
|
|
82
|
+
and a gap below five points marks the metric as non-discriminating. On a constructed population the two
|
|
83
|
+
rates separate three satisfied sessions from four that all read, so the number distinguishes what it
|
|
84
|
+
claims to.
|
|
85
|
+
- **The label vocabulary refuses both spellings on both surfaces.** The source gate's vocabulary was
|
|
86
|
+
uppercase while the spelling seats actually typed was lowercase, so 73 handles sat in 22 fixture files
|
|
87
|
+
the gate never saw, plus 23 glued spellings inside them and 11 more in two files the sweep could not
|
|
88
|
+
name. They are renamed to the fixtures' own subjects, the shared set now matches either case, and the
|
|
89
|
+
history gate's two redundant patterns are gone so one subject yields one problem line. A planted token
|
|
90
|
+
reddens the gate at a named line and column; a word character before a handle, two digits, four digits,
|
|
91
|
+
and an ISO calendar week are none of them hits.
|
|
92
|
+
- **A refusal was designed, measured, and killed by its own test.** The candidate enforcement was to refuse
|
|
93
|
+
the first call in a declared family once when the body was never read. Simulated over 703 sessions and
|
|
94
|
+
107,463 tool calls with the production functions imported, 2 of 30 refused calls changed course (6.7%,
|
|
95
|
+
interval 1.8 to 21.3%), 0 of 30 on a stricter reading, and the gate could reach at most 8% of the calls
|
|
96
|
+
it governs. The best case in the data refutes the shape: the model read the body when the body mattered,
|
|
97
|
+
after the work it needed, without a gate. What ships is the measurement that makes that answer
|
|
98
|
+
possible; what does not ship is the gate.
|
|
99
|
+
|
|
56
100
|
## Core — 0.43.6 (2026-10-29: the rule says one thing, and a merge states what landed)
|
|
57
101
|
|
|
58
102
|
- **The identity block contradicted itself, and the contradiction is gone.** One sentence forbade
|
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.43.7",
|
|
4
|
+
"sha": "202c7b26bdcfe036b330cde4d98470951553502f",
|
|
5
|
+
"shaShort": "202c7b26",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-10-
|
|
8
|
+
"packedAt": "2026-10-30T08:48:55.796Z"
|
|
9
9
|
}
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Skill applicability — did a skill's own declared condition hold for the task?
|
|
3
|
+
*
|
|
4
|
+
* The suggestion whisper, the catalog ranking and the adoption counters all
|
|
5
|
+
* answer "might this skill help?". None answers the question the counters
|
|
6
|
+
* cannot: of the sessions that read nothing, which of them had a skill whose
|
|
7
|
+
* stated condition the task text actually met? A suggestion that was ignored
|
|
8
|
+
* and a skill that never applied looked identical in `suggested`/`loaded`.
|
|
9
|
+
* This module decides that difference and keeps its evidence.
|
|
10
|
+
*
|
|
11
|
+
* The condition is the skill's OWN declaration, never a heuristic invented
|
|
12
|
+
* here: the trigger phrases its file declares — frontmatter `trigger:` /
|
|
13
|
+
* `triggers:`, a `## trigger:` body heading, the description's `Triggers:`
|
|
14
|
+
* tail — the same entries `skill-triggers.ts` reads and the same provenance
|
|
15
|
+
* labels it records. The shipped pack's contract already treats that list as
|
|
16
|
+
* the machine-readable form of applicability ("a description that cannot fire
|
|
17
|
+
* is indistinguishable from one that fires"), so a skill file needs no new
|
|
18
|
+
* field for this module to see it. A file that declares no phrase yields no
|
|
19
|
+
* verdict at all; the caller reports it as undeclared rather than asserting
|
|
20
|
+
* "does not apply" on no evidence.
|
|
21
|
+
*
|
|
22
|
+
* Matching mirrors the injector on purpose. The occurrence boundary is the one
|
|
23
|
+
* `triggerMatches` uses (a phrase occurs where neither neighbour is a letter or
|
|
24
|
+
* digit, so "pane" is not an occurrence in "paneled"), because a verdict that
|
|
25
|
+
* disagreed with the whisper would be worse than no verdict: the suite pins
|
|
26
|
+
* the two answers equal over the installed catalog. What this module adds is
|
|
27
|
+
* polarity — a phrase inside a negated clause ("do not research this") is not
|
|
28
|
+
* the author's condition holding, so the clause is read and the phrase is
|
|
29
|
+
* dropped as evidence.
|
|
30
|
+
*
|
|
31
|
+
* What this module does NOT do: it decides nothing about delivery, slots,
|
|
32
|
+
* cooldowns, counters or ranking. It returns a classification and the caller
|
|
33
|
+
* records it. Nothing here reads the session, writes a file or sends a
|
|
34
|
+
* message.
|
|
35
|
+
*
|
|
36
|
+
* Cost: one pass over the task text per phrase of the cached catalog, with the
|
|
37
|
+
* native substring scan as the cheap reject before any boundary work. The
|
|
38
|
+
* caller holds the prompt in memory already (the injector matches against the
|
|
39
|
+
* same string), so no I/O is added per turn.
|
|
40
|
+
*/
|
|
41
|
+
import type { TriggerSource } from "./skill-triggers.js";
|
|
42
|
+
/**
|
|
43
|
+
* A skill as the applicability read consumes it: its name and the phrase list
|
|
44
|
+
* the cache resolved from its file. `triggers` and `triggerSources` are the
|
|
45
|
+
* fields `setCachedSkills` fills, so this read never touches the disk — the
|
|
46
|
+
* phrases and their provenance are the ones the injector matched against.
|
|
47
|
+
*/
|
|
48
|
+
export interface ConditionalSkill {
|
|
49
|
+
name: string;
|
|
50
|
+
/** Authored phrases (lowercased, deduped, capped) — empty when the file declares none. */
|
|
51
|
+
triggers?: string[];
|
|
52
|
+
/** Which authored source declared each phrase. */
|
|
53
|
+
triggerSources?: Record<string, TriggerSource>;
|
|
54
|
+
}
|
|
55
|
+
/** One authored phrase that matched, with the place in the file that declares it. */
|
|
56
|
+
export interface ApplicabilityEvidence {
|
|
57
|
+
/** The authored phrase, as the reader normalized it. */
|
|
58
|
+
phrase: string;
|
|
59
|
+
/**
|
|
60
|
+
* frontmatter | heading | description — absent only when the cached skill
|
|
61
|
+
* carried no provenance map (an unenriched cache, never a production one).
|
|
62
|
+
*/
|
|
63
|
+
source?: TriggerSource;
|
|
64
|
+
}
|
|
65
|
+
/**
|
|
66
|
+
* One skill's verdict for a session.
|
|
67
|
+
*
|
|
68
|
+
* `ignored` is the evaluation's answer: the declared condition held and no
|
|
69
|
+
* detected read followed. `read` is the read-detector's upgrade of the same
|
|
70
|
+
* row. The third class, not-applicable, is never a row — it is a skill that
|
|
71
|
+
* declared a condition and did not meet the task text, so a reader derives it
|
|
72
|
+
* from the record's census (`evaluated` minus the verdict rows).
|
|
73
|
+
*/
|
|
74
|
+
export interface SkillApplicabilityVerdict {
|
|
75
|
+
name: string;
|
|
76
|
+
verdict: "read" | "ignored";
|
|
77
|
+
evidence: ApplicabilityEvidence[];
|
|
78
|
+
}
|
|
79
|
+
/** Max evidence rows carried per skill: enough to review, bounded like every other surface. */
|
|
80
|
+
export declare const MAX_APPLICABILITY_EVIDENCE = 4;
|
|
81
|
+
/**
|
|
82
|
+
* Word tokens a negation cue may sit before the phrase and still negate it.
|
|
83
|
+
* "do not research this" (0) and "no need to research" (2) are negated;
|
|
84
|
+
* "do not stop, then research it later" puts the cue past the clauseless
|
|
85
|
+
* distance and reads as the assertion it is. Four is the smallest window that
|
|
86
|
+
* covers the "no need to"/"there is no reason to" shapes without reaching
|
|
87
|
+
* across a clause.
|
|
88
|
+
*/
|
|
89
|
+
export declare const NEGATION_GAP_TOKENS = 4;
|
|
90
|
+
/**
|
|
91
|
+
* Every index in `lowered` where `phrase` occurs as a whole phrase, using the
|
|
92
|
+
* matcher's boundary rule: neither neighbour may be a letter or digit. Phrase
|
|
93
|
+
* must already be lowercase. Pure.
|
|
94
|
+
*/
|
|
95
|
+
export declare function phraseOccurrences(phrase: string, lowered: string): number[];
|
|
96
|
+
/**
|
|
97
|
+
* Index where the clause containing `at` begins: after the nearest sentence
|
|
98
|
+
* terminator. A clause boundary is what stops a negation in one statement from
|
|
99
|
+
* reaching a phrase in the next ("do not use the catalog; research the topic"
|
|
100
|
+
* asserts research). Pure.
|
|
101
|
+
*/
|
|
102
|
+
export declare function clauseStart(lowered: string, at: number): number;
|
|
103
|
+
/**
|
|
104
|
+
* True when the clause text preceding a phrase carries a negation cue close
|
|
105
|
+
* enough to negate it. The LAST cue decides, so "not only did we not ask" is
|
|
106
|
+
* read by its nearest cue rather than its first. Pure.
|
|
107
|
+
*/
|
|
108
|
+
export declare function isNegatedPrefix(prefix: string): boolean;
|
|
109
|
+
/**
|
|
110
|
+
* The evidence for one skill's declared condition holding on `taskText`.
|
|
111
|
+
*
|
|
112
|
+
* A phrase is evidence when at least one of its occurrences is asserted:
|
|
113
|
+
* negating one occurrence does not erase another ("do not skip research" and
|
|
114
|
+
* "research this" in the same text both count). Phrases are evidence at most
|
|
115
|
+
* MAX_APPLICABILITY_EVIDENCE times per skill, in authored order. An empty
|
|
116
|
+
* return means the condition did not hold. Pure.
|
|
117
|
+
*/
|
|
118
|
+
export declare function skillApplicability(skill: ConditionalSkill, taskText: string): ApplicabilityEvidence[];
|
|
119
|
+
/** The whole catalog's answer for one task text. */
|
|
120
|
+
export interface ApplicabilityEvaluation {
|
|
121
|
+
/** Skills whose declared condition held, each still an `ignored` verdict. */
|
|
122
|
+
applicable: SkillApplicabilityVerdict[];
|
|
123
|
+
/** Installed skills that declare at least one condition phrase. */
|
|
124
|
+
evaluated: number;
|
|
125
|
+
/** Installed skills that declare none — no condition, so no verdict either way. */
|
|
126
|
+
undeclared: string[];
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Classify every installed skill against one task text. Pure: the catalog
|
|
130
|
+
* arrives as the cache already resolved it, and the text is the prompt the
|
|
131
|
+
* injector matched against.
|
|
132
|
+
*/
|
|
133
|
+
export declare function evaluateApplicability(skills: ConditionalSkill[], taskText: string): ApplicabilityEvaluation;
|
|
134
|
+
//# sourceMappingURL=applicability.d.ts.map
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Skill applicability — did a skill's own declared condition hold for the task?
|
|
3
|
+
*
|
|
4
|
+
* The suggestion whisper, the catalog ranking and the adoption counters all
|
|
5
|
+
* answer "might this skill help?". None answers the question the counters
|
|
6
|
+
* cannot: of the sessions that read nothing, which of them had a skill whose
|
|
7
|
+
* stated condition the task text actually met? A suggestion that was ignored
|
|
8
|
+
* and a skill that never applied looked identical in `suggested`/`loaded`.
|
|
9
|
+
* This module decides that difference and keeps its evidence.
|
|
10
|
+
*
|
|
11
|
+
* The condition is the skill's OWN declaration, never a heuristic invented
|
|
12
|
+
* here: the trigger phrases its file declares — frontmatter `trigger:` /
|
|
13
|
+
* `triggers:`, a `## trigger:` body heading, the description's `Triggers:`
|
|
14
|
+
* tail — the same entries `skill-triggers.ts` reads and the same provenance
|
|
15
|
+
* labels it records. The shipped pack's contract already treats that list as
|
|
16
|
+
* the machine-readable form of applicability ("a description that cannot fire
|
|
17
|
+
* is indistinguishable from one that fires"), so a skill file needs no new
|
|
18
|
+
* field for this module to see it. A file that declares no phrase yields no
|
|
19
|
+
* verdict at all; the caller reports it as undeclared rather than asserting
|
|
20
|
+
* "does not apply" on no evidence.
|
|
21
|
+
*
|
|
22
|
+
* Matching mirrors the injector on purpose. The occurrence boundary is the one
|
|
23
|
+
* `triggerMatches` uses (a phrase occurs where neither neighbour is a letter or
|
|
24
|
+
* digit, so "pane" is not an occurrence in "paneled"), because a verdict that
|
|
25
|
+
* disagreed with the whisper would be worse than no verdict: the suite pins
|
|
26
|
+
* the two answers equal over the installed catalog. What this module adds is
|
|
27
|
+
* polarity — a phrase inside a negated clause ("do not research this") is not
|
|
28
|
+
* the author's condition holding, so the clause is read and the phrase is
|
|
29
|
+
* dropped as evidence.
|
|
30
|
+
*
|
|
31
|
+
* What this module does NOT do: it decides nothing about delivery, slots,
|
|
32
|
+
* cooldowns, counters or ranking. It returns a classification and the caller
|
|
33
|
+
* records it. Nothing here reads the session, writes a file or sends a
|
|
34
|
+
* message.
|
|
35
|
+
*
|
|
36
|
+
* Cost: one pass over the task text per phrase of the cached catalog, with the
|
|
37
|
+
* native substring scan as the cheap reject before any boundary work. The
|
|
38
|
+
* caller holds the prompt in memory already (the injector matches against the
|
|
39
|
+
* same string), so no I/O is added per turn.
|
|
40
|
+
*/
|
|
41
|
+
/** Max evidence rows carried per skill: enough to review, bounded like every other surface. */
|
|
42
|
+
export const MAX_APPLICABILITY_EVIDENCE = 4;
|
|
43
|
+
/**
|
|
44
|
+
* Word tokens a negation cue may sit before the phrase and still negate it.
|
|
45
|
+
* "do not research this" (0) and "no need to research" (2) are negated;
|
|
46
|
+
* "do not stop, then research it later" puts the cue past the clauseless
|
|
47
|
+
* distance and reads as the assertion it is. Four is the smallest window that
|
|
48
|
+
* covers the "no need to"/"there is no reason to" shapes without reaching
|
|
49
|
+
* across a clause.
|
|
50
|
+
*/
|
|
51
|
+
export const NEGATION_GAP_TOKENS = 4;
|
|
52
|
+
/**
|
|
53
|
+
* Negation cues, matched in the clause text BEFORE a phrase. The `-n't`
|
|
54
|
+
* alternative is spelled out rather than listed per verb so a contraction the
|
|
55
|
+
* list forgot ("won't", "shouldn't") still counts.
|
|
56
|
+
*/
|
|
57
|
+
const NEGATION_CUE = /\b(?:not|never|no|nor|without|avoid|avoiding|skip|skipping)\b|\b[a-z]+n['\u2019]t\b/gi;
|
|
58
|
+
/** True when `char` continues a word (the boundary rule `triggerMatches` uses). */
|
|
59
|
+
function isWordChar(char) {
|
|
60
|
+
return char !== undefined && /[a-z0-9]/.test(char);
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Every index in `lowered` where `phrase` occurs as a whole phrase, using the
|
|
64
|
+
* matcher's boundary rule: neither neighbour may be a letter or digit. Phrase
|
|
65
|
+
* must already be lowercase. Pure.
|
|
66
|
+
*/
|
|
67
|
+
export function phraseOccurrences(phrase, lowered) {
|
|
68
|
+
if (!phrase)
|
|
69
|
+
return [];
|
|
70
|
+
const out = [];
|
|
71
|
+
let from = 0;
|
|
72
|
+
for (;;) {
|
|
73
|
+
const at = lowered.indexOf(phrase, from);
|
|
74
|
+
if (at < 0)
|
|
75
|
+
break;
|
|
76
|
+
if (!isWordChar(lowered[at - 1]) && !isWordChar(lowered[at + phrase.length]))
|
|
77
|
+
out.push(at);
|
|
78
|
+
from = at + 1;
|
|
79
|
+
}
|
|
80
|
+
return out;
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* Index where the clause containing `at` begins: after the nearest sentence
|
|
84
|
+
* terminator. A clause boundary is what stops a negation in one statement from
|
|
85
|
+
* reaching a phrase in the next ("do not use the catalog; research the topic"
|
|
86
|
+
* asserts research). Pure.
|
|
87
|
+
*/
|
|
88
|
+
export function clauseStart(lowered, at) {
|
|
89
|
+
for (let i = at - 1; i >= 0; i--) {
|
|
90
|
+
const char = lowered[i];
|
|
91
|
+
if (char === "." || char === "!" || char === "?" || char === ";" || char === "\n")
|
|
92
|
+
return i + 1;
|
|
93
|
+
}
|
|
94
|
+
return 0;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* True when the clause text preceding a phrase carries a negation cue close
|
|
98
|
+
* enough to negate it. The LAST cue decides, so "not only did we not ask" is
|
|
99
|
+
* read by its nearest cue rather than its first. Pure.
|
|
100
|
+
*/
|
|
101
|
+
export function isNegatedPrefix(prefix) {
|
|
102
|
+
const cue = new RegExp(NEGATION_CUE.source, "gi");
|
|
103
|
+
let last = null;
|
|
104
|
+
let match;
|
|
105
|
+
while ((match = cue.exec(prefix)))
|
|
106
|
+
last = match;
|
|
107
|
+
if (!last)
|
|
108
|
+
return false;
|
|
109
|
+
const gap = prefix.slice(last.index + last[0].length);
|
|
110
|
+
return (gap.match(/[a-z0-9]+/g) ?? []).length <= NEGATION_GAP_TOKENS;
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* The evidence for one skill's declared condition holding on `taskText`.
|
|
114
|
+
*
|
|
115
|
+
* A phrase is evidence when at least one of its occurrences is asserted:
|
|
116
|
+
* negating one occurrence does not erase another ("do not skip research" and
|
|
117
|
+
* "research this" in the same text both count). Phrases are evidence at most
|
|
118
|
+
* MAX_APPLICABILITY_EVIDENCE times per skill, in authored order. An empty
|
|
119
|
+
* return means the condition did not hold. Pure.
|
|
120
|
+
*/
|
|
121
|
+
export function skillApplicability(skill, taskText) {
|
|
122
|
+
const lowered = taskText.toLowerCase();
|
|
123
|
+
const evidence = [];
|
|
124
|
+
for (const authored of skill.triggers ?? []) {
|
|
125
|
+
if (evidence.length >= MAX_APPLICABILITY_EVIDENCE)
|
|
126
|
+
break;
|
|
127
|
+
const phrase = authored.toLowerCase();
|
|
128
|
+
// Cheap reject first: most phrases are absent from most prompts.
|
|
129
|
+
if (!phrase || !lowered.includes(phrase))
|
|
130
|
+
continue;
|
|
131
|
+
const asserted = phraseOccurrences(phrase, lowered).some((at) => !isNegatedPrefix(lowered.slice(clauseStart(lowered, at), at)));
|
|
132
|
+
if (!asserted)
|
|
133
|
+
continue;
|
|
134
|
+
const source = skill.triggerSources?.[authored] ?? skill.triggerSources?.[phrase];
|
|
135
|
+
evidence.push(source ? { phrase, source } : { phrase });
|
|
136
|
+
}
|
|
137
|
+
return evidence;
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Classify every installed skill against one task text. Pure: the catalog
|
|
141
|
+
* arrives as the cache already resolved it, and the text is the prompt the
|
|
142
|
+
* injector matched against.
|
|
143
|
+
*/
|
|
144
|
+
export function evaluateApplicability(skills, taskText) {
|
|
145
|
+
const applicable = [];
|
|
146
|
+
const undeclared = [];
|
|
147
|
+
let evaluated = 0;
|
|
148
|
+
const text = taskText ?? "";
|
|
149
|
+
for (const skill of skills) {
|
|
150
|
+
if (!skill.triggers?.length) {
|
|
151
|
+
undeclared.push(skill.name);
|
|
152
|
+
continue;
|
|
153
|
+
}
|
|
154
|
+
evaluated++;
|
|
155
|
+
const evidence = skillApplicability(skill, text);
|
|
156
|
+
if (evidence.length)
|
|
157
|
+
applicable.push({ name: skill.name, verdict: "ignored", evidence });
|
|
158
|
+
}
|
|
159
|
+
return { applicable, evaluated, undeclared };
|
|
160
|
+
}
|
|
161
|
+
//# sourceMappingURL=applicability.js.map
|
|
@@ -189,6 +189,8 @@ export interface CachedSkill {
|
|
|
189
189
|
triggers?: string[];
|
|
190
190
|
/** Which source authored each phrase (the row's evidence label). */
|
|
191
191
|
triggerSources?: Record<string, TriggerSource>;
|
|
192
|
+
/** Tool families the file's `governs:` declaration claims (skill-families.ts). */
|
|
193
|
+
families?: string[];
|
|
192
194
|
}
|
|
193
195
|
/** Called by index.ts's setCachedSkills to keep the auto-inject cache in sync. */
|
|
194
196
|
export declare function updateSkillCache(skills: CachedSkill[]): void;
|
|
@@ -497,6 +499,14 @@ interface DiscoveryState {
|
|
|
497
499
|
* discovery mode. Returns the current record for skill_stats.
|
|
498
500
|
*/
|
|
499
501
|
export declare function resolveDiscoveryMode(ctx: ExtensionContext): DiscoveryState;
|
|
502
|
+
/**
|
|
503
|
+
* Record the skills a delivered suggestion offered this session. Called only
|
|
504
|
+
* after the send was accepted, so the row counts arrivals like the `suggested`
|
|
505
|
+
* counter does. Never throws: a record is not worth a broken turn.
|
|
506
|
+
*/
|
|
507
|
+
export declare function noteObligationSuggested(ctx: ExtensionContext, names: string[]): void;
|
|
508
|
+
/** Record the skills a catalog page listed (called from the list_skills tool). */
|
|
509
|
+
export declare function noteObligationListed(ctx: ExtensionContext, names: string[]): void;
|
|
500
510
|
/**
|
|
501
511
|
* Register the auto-inject handler on before_agent_start, the read-tool load
|
|
502
512
|
* detector and the drift trigger on tool_result.
|
|
@@ -112,8 +112,10 @@ import { getExtensionState } from "../../../lib/state/extension-state.js";
|
|
|
112
112
|
import { BRAID_INJECTED, BRAID_SOURCE } from "../../../lib/constants/injection-details.js";
|
|
113
113
|
import { getSkillsUsageFilePath } from "../../../lib/config/braid-paths.js";
|
|
114
114
|
import { SESSION_COMPACT, AGENT_SETTLED } from "../../../lib/core/event-names.js";
|
|
115
|
-
import { getSessionProfile, recordSessionSkillLoad, recordSessionStart, } from "./session-records.js";
|
|
115
|
+
import { getSessionProfile, recordApplicabilityCensus, recordApplicabilityVerdict, recordObligationLegs, recordSessionSkillLoad, recordSessionStart, } from "./session-records.js";
|
|
116
|
+
import { evaluateApplicability } from "./applicability.js";
|
|
116
117
|
import { triggerMatches } from "./skill-triggers.js";
|
|
118
|
+
import { toolFamilyToken } from "./skill-families.js";
|
|
117
119
|
import { advanceDrift, driftDirectoryFor, driftPayload, initialDrift, noteDriftSurface, recordDriftDrop, recordDriftFire, skillReadRoot, } from "./loading-guidance.js";
|
|
118
120
|
const log = createLogger("skills-auto-inject");
|
|
119
121
|
// Constants
|
|
@@ -238,6 +240,12 @@ const KEYWORD_STOP_WORDS = new Set([
|
|
|
238
240
|
"need",
|
|
239
241
|
"look",
|
|
240
242
|
]);
|
|
243
|
+
function initialObligations() {
|
|
244
|
+
return { legs: new Map(), called: new Set(), written: new Map() };
|
|
245
|
+
}
|
|
246
|
+
function initialApplicability() {
|
|
247
|
+
return { censusWritten: false, verdicts: new Map(), evaluated: 0, undeclared: [], taskChars: 0 };
|
|
248
|
+
}
|
|
241
249
|
const STATE_KEY = "skills-auto-inject";
|
|
242
250
|
function getState(ctx) {
|
|
243
251
|
return getExtensionState(ctx, STATE_KEY, () => ({
|
|
@@ -245,6 +253,8 @@ function getState(ctx) {
|
|
|
245
253
|
currentTurn: 0,
|
|
246
254
|
hintSent: false,
|
|
247
255
|
drift: initialDrift(),
|
|
256
|
+
applicability: initialApplicability(),
|
|
257
|
+
obligations: initialObligations(),
|
|
248
258
|
}));
|
|
249
259
|
}
|
|
250
260
|
// Shared module-level variable rather than a per-module copy: the import
|
|
@@ -910,6 +920,159 @@ export function resolveDiscoveryMode(ctx) {
|
|
|
910
920
|
}
|
|
911
921
|
return state;
|
|
912
922
|
}
|
|
923
|
+
// Applicability verdict (recorded, never enforced)
|
|
924
|
+
/**
|
|
925
|
+
* Classify the catalog against this turn's task text and record what changed.
|
|
926
|
+
*
|
|
927
|
+
* Two writes, both append-only:
|
|
928
|
+
* - the session's census row, once, retried until it lands. It is what makes
|
|
929
|
+
* "not-applicable" derivable (evaluated minus the verdict rows) and what
|
|
930
|
+
* names the skills whose files state no condition at all.
|
|
931
|
+
* - one verdict row per skill whose declared condition held, and never twice
|
|
932
|
+
* for the same (session, skill): the set only grows because the verdict is
|
|
933
|
+
* per-session — a skill whose condition held on any turn applied to the
|
|
934
|
+
* session.
|
|
935
|
+
*
|
|
936
|
+
* The row shape is the joint the sibling compliance record expects: it joins on
|
|
937
|
+
* (sessionId, skill) and adds its own `suggested`/`listed`/`read`/`applied`
|
|
938
|
+
* beside this verdict, so `ignored / (read + ignored)` becomes computable. This
|
|
939
|
+
* module writes no `applied` leg: a tool belong to a skill's family only once
|
|
940
|
+
* the skill declares that family, and no skill does yet.
|
|
941
|
+
*
|
|
942
|
+
* Reads only — it never touches `injected`, a counter or a send. That is the
|
|
943
|
+
* whole point of the ordering in before_agent_start: this step cannot move the
|
|
944
|
+
* suggestion, and the suggestion cannot move the verdict.
|
|
945
|
+
*/
|
|
946
|
+
function stepApplicability(ctx, state, skills, prompt) {
|
|
947
|
+
const evaluation = evaluateApplicability(skills, prompt);
|
|
948
|
+
const app = state.applicability;
|
|
949
|
+
const fresh = evaluation.applicable.filter((verdict) => !app.verdicts.has(verdict.name));
|
|
950
|
+
for (const verdict of fresh)
|
|
951
|
+
app.verdicts.set(verdict.name, verdict);
|
|
952
|
+
app.evaluated = evaluation.evaluated;
|
|
953
|
+
app.undeclared = evaluation.undeclared;
|
|
954
|
+
app.taskChars = prompt.length;
|
|
955
|
+
if (!app.censusWritten) {
|
|
956
|
+
const wrote = recordApplicabilityCensus(ctx, {
|
|
957
|
+
taskChars: app.taskChars,
|
|
958
|
+
evaluated: app.evaluated,
|
|
959
|
+
undeclared: app.undeclared,
|
|
960
|
+
});
|
|
961
|
+
// A session without an id, or a refused store: retry on the next turn.
|
|
962
|
+
if (wrote)
|
|
963
|
+
app.censusWritten = true;
|
|
964
|
+
}
|
|
965
|
+
if (!fresh.length)
|
|
966
|
+
return;
|
|
967
|
+
log.debug(`[skills-auto-inject] applicability: ${fresh.length} newly applicable, ` +
|
|
968
|
+
`${evaluation.evaluated} evaluated, ${evaluation.undeclared.length} undeclared`);
|
|
969
|
+
for (const verdict of fresh) {
|
|
970
|
+
recordApplicabilityVerdict(ctx, {
|
|
971
|
+
skill: verdict.name,
|
|
972
|
+
applicability: verdict.verdict,
|
|
973
|
+
evidence: verdict.evidence,
|
|
974
|
+
});
|
|
975
|
+
// The obligation row lands with the verdict, not with the first leg: a
|
|
976
|
+
// session that is merely told which body it owes, and then does nothing,
|
|
977
|
+
// is the population the rate exists to count. Without this row that
|
|
978
|
+
// session would be mistaken for one the instrument never saw.
|
|
979
|
+
legsFor(state, verdict.name);
|
|
980
|
+
appendObligationRow(ctx, state, verdict.name);
|
|
981
|
+
}
|
|
982
|
+
}
|
|
983
|
+
/**
|
|
984
|
+
* Upgrade an applicable skill to `read` and append its verdict row. A read of a
|
|
985
|
+
* skill whose declared condition never held gets no row: the three classes are
|
|
986
|
+
* about skills that applied, and a read is not a fourth one.
|
|
987
|
+
*/
|
|
988
|
+
function markApplicabilityRead(ctx, state, name) {
|
|
989
|
+
const app = state.applicability;
|
|
990
|
+
const held = app.verdicts.get(name);
|
|
991
|
+
if (!held || held.verdict === "read")
|
|
992
|
+
return;
|
|
993
|
+
app.verdicts.set(name, { ...held, verdict: "read" });
|
|
994
|
+
recordApplicabilityVerdict(ctx, {
|
|
995
|
+
skill: name,
|
|
996
|
+
applicability: "read",
|
|
997
|
+
evidence: held.evidence,
|
|
998
|
+
});
|
|
999
|
+
}
|
|
1000
|
+
// Obligation rows (the applied leg)
|
|
1001
|
+
/**
|
|
1002
|
+
* The session's legs for one skill, created on first sight. The object is the
|
|
1003
|
+
* snapshot every row carries, so a row states all five legs as of the moment
|
|
1004
|
+
* the leg changed rather than the single delta that triggered the write.
|
|
1005
|
+
*/
|
|
1006
|
+
function legsFor(state, name) {
|
|
1007
|
+
let legs = state.obligations.legs.get(name);
|
|
1008
|
+
if (!legs) {
|
|
1009
|
+
legs = {
|
|
1010
|
+
skill: name,
|
|
1011
|
+
suggested: false,
|
|
1012
|
+
listed: false,
|
|
1013
|
+
read: false,
|
|
1014
|
+
called: false,
|
|
1015
|
+
applied: false,
|
|
1016
|
+
};
|
|
1017
|
+
state.obligations.legs.set(name, legs);
|
|
1018
|
+
}
|
|
1019
|
+
return legs;
|
|
1020
|
+
}
|
|
1021
|
+
/**
|
|
1022
|
+
* Append the skill's legs when they changed since the last row. One row per
|
|
1023
|
+
* distinct state rather than one per event: a session that reads the same body
|
|
1024
|
+
* three times, or lists it on every turn, writes one line. A refused write
|
|
1025
|
+
* leaves the signature unset, so the next leg change retries.
|
|
1026
|
+
*/
|
|
1027
|
+
function appendObligationRow(ctx, state, name) {
|
|
1028
|
+
const legs = state.obligations.legs.get(name);
|
|
1029
|
+
if (!legs)
|
|
1030
|
+
return;
|
|
1031
|
+
const signature = [legs.suggested, legs.listed, legs.read, legs.called, legs.applied]
|
|
1032
|
+
.map((flag) => (flag ? "1" : "0"))
|
|
1033
|
+
.join("");
|
|
1034
|
+
if (state.obligations.written.get(name) === signature)
|
|
1035
|
+
return;
|
|
1036
|
+
if (!recordObligationLegs(ctx, legs))
|
|
1037
|
+
return;
|
|
1038
|
+
state.obligations.written.set(name, signature);
|
|
1039
|
+
}
|
|
1040
|
+
/** Note one observed leg for a skill and record the row it changed. */
|
|
1041
|
+
function noteObligationLeg(ctx, state, name, leg) {
|
|
1042
|
+
if (!name)
|
|
1043
|
+
return;
|
|
1044
|
+
const legs = legsFor(state, name);
|
|
1045
|
+
if (legs[leg])
|
|
1046
|
+
return;
|
|
1047
|
+
legs[leg] = true;
|
|
1048
|
+
appendObligationRow(ctx, state, name);
|
|
1049
|
+
}
|
|
1050
|
+
/**
|
|
1051
|
+
* Record the skills a delivered suggestion offered this session. Called only
|
|
1052
|
+
* after the send was accepted, so the row counts arrivals like the `suggested`
|
|
1053
|
+
* counter does. Never throws: a record is not worth a broken turn.
|
|
1054
|
+
*/
|
|
1055
|
+
export function noteObligationSuggested(ctx, names) {
|
|
1056
|
+
try {
|
|
1057
|
+
const state = getState(ctx);
|
|
1058
|
+
for (const name of names)
|
|
1059
|
+
noteObligationLeg(ctx, state, name, "suggested");
|
|
1060
|
+
}
|
|
1061
|
+
catch (err) {
|
|
1062
|
+
log.debug(`[skills-auto-inject] obligation suggested leg failed (best-effort): ${err}`);
|
|
1063
|
+
}
|
|
1064
|
+
}
|
|
1065
|
+
/** Record the skills a catalog page listed (called from the list_skills tool). */
|
|
1066
|
+
export function noteObligationListed(ctx, names) {
|
|
1067
|
+
try {
|
|
1068
|
+
const state = getState(ctx);
|
|
1069
|
+
for (const name of names)
|
|
1070
|
+
noteObligationLeg(ctx, state, name, "listed");
|
|
1071
|
+
}
|
|
1072
|
+
catch (err) {
|
|
1073
|
+
log.debug(`[skills-auto-inject] obligation listed leg failed (best-effort): ${err}`);
|
|
1074
|
+
}
|
|
1075
|
+
}
|
|
913
1076
|
/**
|
|
914
1077
|
* Count a SKILL.md read (the list→read load path) and mark the matching
|
|
915
1078
|
* injection loaded (releases its slot and extends its cooldown: the skill is
|
|
@@ -932,9 +1095,44 @@ function detectSkillLoad(ev, ctx, state) {
|
|
|
932
1095
|
if (held)
|
|
933
1096
|
held.loadedTurn = state.currentTurn;
|
|
934
1097
|
recordSkillLoad(ctx, name);
|
|
1098
|
+
// The load counters say a read happened; this says whether the session was
|
|
1099
|
+
// one where the skill applied. Independent writes, independent failures.
|
|
1100
|
+
markApplicabilityRead(ctx, state, name);
|
|
1101
|
+
noteObligationLeg(ctx, state, name, "read");
|
|
935
1102
|
log.debug(`[skills-auto-inject] counted actual load of "${name}" via read`);
|
|
936
1103
|
return name;
|
|
937
1104
|
}
|
|
1105
|
+
/**
|
|
1106
|
+
* Record a call into a declared family (the applied leg).
|
|
1107
|
+
*
|
|
1108
|
+
* The FIRST call per (session, skill) decides it: a read already on record
|
|
1109
|
+
* means the body came first and the call applies what it says; no read means
|
|
1110
|
+
* the call came first, and no later read can turn that into satisfaction — the
|
|
1111
|
+
* ordering is a fact about what happened, not a state that improves.
|
|
1112
|
+
*
|
|
1113
|
+
* A failed call still counts: a refusal would fire before the tool ran and
|
|
1114
|
+
* could not know the outcome. Skills that declare no family are never reached
|
|
1115
|
+
* here, which is most of them.
|
|
1116
|
+
*/
|
|
1117
|
+
function stepFamilyCalls(ctx, state, event) {
|
|
1118
|
+
const toolName = event?.toolName;
|
|
1119
|
+
if (!toolName)
|
|
1120
|
+
return;
|
|
1121
|
+
const family = toolFamilyToken(toolName);
|
|
1122
|
+
if (!family)
|
|
1123
|
+
return;
|
|
1124
|
+
for (const skill of _skillsCache) {
|
|
1125
|
+
if (!skill.families?.length || !skill.families.includes(family))
|
|
1126
|
+
continue;
|
|
1127
|
+
if (state.obligations.called.has(skill.name))
|
|
1128
|
+
continue;
|
|
1129
|
+
const legs = legsFor(state, skill.name);
|
|
1130
|
+
state.obligations.called.add(skill.name);
|
|
1131
|
+
legs.called = true;
|
|
1132
|
+
legs.applied = legs.read;
|
|
1133
|
+
appendObligationRow(ctx, state, skill.name);
|
|
1134
|
+
}
|
|
1135
|
+
}
|
|
938
1136
|
/**
|
|
939
1137
|
* Fire the drift line when the work has moved into a new work area (the rule
|
|
940
1138
|
* and its bounds live in loading-guidance.ts, beside the floor text the line
|
|
@@ -993,6 +1191,10 @@ export function registerAutoInject(pi) {
|
|
|
993
1191
|
const state = getState(ctx);
|
|
994
1192
|
if (detectSkillLoad(ev, ctx, state))
|
|
995
1193
|
noteDriftSurface(state.drift);
|
|
1194
|
+
// A call in a declared family is the applied leg. It runs after the load
|
|
1195
|
+
// detector so a SKILL.md read of the very tool call in flight is already
|
|
1196
|
+
// on record when the family is looked up.
|
|
1197
|
+
stepFamilyCalls(ctx, state, ev);
|
|
996
1198
|
stepDrift(pi, ctx, state, ev);
|
|
997
1199
|
}
|
|
998
1200
|
catch {
|
|
@@ -1044,6 +1246,17 @@ export function registerAutoInject(pi) {
|
|
|
1044
1246
|
if (!prompt.trim()) {
|
|
1045
1247
|
return; // No user input to match against
|
|
1046
1248
|
}
|
|
1249
|
+
// Applicability is recorded BEFORE every scoring early-return below.
|
|
1250
|
+
// Most sessions match no skill, and those are exactly the sessions the
|
|
1251
|
+
// adoption counters cannot explain: the returns would erase them. The
|
|
1252
|
+
// step reads the catalog and the prompt only, so the suggestion decision
|
|
1253
|
+
// below is untouched by it (and its failure cannot cost a suggestion).
|
|
1254
|
+
try {
|
|
1255
|
+
stepApplicability(ctx, state, skills, prompt);
|
|
1256
|
+
}
|
|
1257
|
+
catch (err) {
|
|
1258
|
+
log.debug(`[skills-auto-inject] applicability step failed (best-effort): ${err}`);
|
|
1259
|
+
}
|
|
1047
1260
|
// One-shot profile hint: the first non-empty prompt of a session whose
|
|
1048
1261
|
// configured profile carries a hint gets exactly one steer — the hint
|
|
1049
1262
|
// text itself, byte-for-byte. Profiles without a hint and sessions
|
|
@@ -1125,6 +1338,8 @@ export function registerAutoInject(pi) {
|
|
|
1125
1338
|
(i.loadedTurn !== undefined && state.currentTurn - i.loadedTurn < LOADED_COOLDOWN_TURNS));
|
|
1126
1339
|
// E3: per-skill suggestion counter — counts deliveries, not intent.
|
|
1127
1340
|
recordSkillSuggestion(ctx, skillsToInject.map((s) => s.name));
|
|
1341
|
+
// The same delivery is an obligation leg: the body was offered here.
|
|
1342
|
+
noteObligationSuggested(ctx, skillsToInject.map((s) => s.name));
|
|
1128
1343
|
}
|
|
1129
1344
|
catch (err) {
|
|
1130
1345
|
log.debug(`[skills-auto-inject] Error in before_agent_start: ${err}`);
|