pi-braid 0.43.9 → 0.43.12
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 +48 -0
- package/build-info.json +4 -4
- package/dist/extensions/core/skills-tool/index.d.ts +11 -3
- package/dist/extensions/core/skills-tool/index.js +27 -3
- package/dist/extensions/core/skills-tool/loading-guidance.d.ts +2 -2
- package/dist/extensions/core/skills-tool/loading-guidance.js +2 -2
- package/dist/extensions/core/skills-tool/skill-triggers.d.ts +22 -0
- package/dist/extensions/core/skills-tool/skill-triggers.js +29 -4
- package/dist/lib/memory/decision-grammar.d.ts +94 -0
- package/dist/lib/memory/decision-grammar.js +348 -0
- package/dist/lib/memory/index.d.ts +1 -0
- package/dist/lib/memory/index.js +1 -0
- package/dist/lib/orchestrator/owner-speech.d.ts +114 -0
- package/dist/lib/orchestrator/owner-speech.js +234 -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/index.ts +34 -6
- package/src/extensions/core/skills-tool/loading-guidance.ts +2 -2
- package/src/extensions/core/skills-tool/skill-triggers.ts +43 -4
- package/src/lib/memory/decision-grammar.ts +405 -0
- package/src/lib/memory/index.ts +10 -0
- package/src/lib/orchestrator/owner-speech.ts +286 -0
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Owner speech: the braid half of the ruling write path.
|
|
3
|
+
*
|
|
4
|
+
* Two jobs, both of them specific to this deployment:
|
|
5
|
+
*
|
|
6
|
+
* - **Decide whether a turn is the owner speaking at all.** The corpus holds
|
|
7
|
+
* every user-role turn, and in this transcript tree that includes the
|
|
8
|
+
* system's own voice: dispatch prompts the seat writes to a running agent,
|
|
9
|
+
* and whisper envelopes from braid's subsystems. A directive-language
|
|
10
|
+
* classifier over that input files the seat's own brief text as an owner
|
|
11
|
+
* ruling, with a pointer into a worker session - a store that looks like
|
|
12
|
+
* provenance and is self-quotation. A telegram envelope is the exception:
|
|
13
|
+
* its body is the owner's message in a transport wrapper, so the wrapper is
|
|
14
|
+
* stripped and the body is what gets classified.
|
|
15
|
+
* - **File a ruling in braid's store.** The label stamped into `source`, the
|
|
16
|
+
* pointer shape, the duplicate key and the fixed tags are braid's filing
|
|
17
|
+
* convention, not English grammar, so they live here and the script that
|
|
18
|
+
* writes them carries no domain string of its own.
|
|
19
|
+
*
|
|
20
|
+
* The classification itself is `classifyRulingBody()` in the generic layer.
|
|
21
|
+
* This module supplies the vocabulary that layer cannot know - what a ruling
|
|
22
|
+
* can be about, and which words describe braid's own machinery - and removes
|
|
23
|
+
* the envelope before it ever reaches the grammar.
|
|
24
|
+
*
|
|
25
|
+
* Pure by construction: no I/O, no clock, no randomness.
|
|
26
|
+
*/
|
|
27
|
+
import { classifyRulingBody, } from "../memory/decision-grammar.js";
|
|
28
|
+
/**
|
|
29
|
+
* The label every filed ruling carries at the front of `source`, and the only
|
|
30
|
+
* handle a later run greps for. It is a constant here because the store's
|
|
31
|
+
* retention policy keys on the same prefix: a second spelling would be a class
|
|
32
|
+
* of entry the prune could not see.
|
|
33
|
+
*/
|
|
34
|
+
export const OWNER_RULING_LABEL = "owner ruling";
|
|
35
|
+
/**
|
|
36
|
+
* A whisper envelope header. The transport line is not speech: for a telegram
|
|
37
|
+
* envelope the body beneath it is the owner's message, and for every other
|
|
38
|
+
* subsystem it is braid talking to itself.
|
|
39
|
+
*/
|
|
40
|
+
const WHISPER_HEADER = /^\s*\[braid-whisper - ([a-z0-9-]+)(?: @ [^\]]*)?\](.*)$/i;
|
|
41
|
+
/** The envelope's closing marker. */
|
|
42
|
+
const WHISPER_END = /^\s*\[braid-whisper-end\]\s*$/i;
|
|
43
|
+
/**
|
|
44
|
+
* Transport lines inside a telegram envelope: the sender line, and the
|
|
45
|
+
* sub-header a coalesced batch puts above each message. Neither is the owner's
|
|
46
|
+
* words.
|
|
47
|
+
*/
|
|
48
|
+
const TELEGRAM_TRANSPORT = /^\s*(?:from @\S+ .*in chat \d+\S*|\[\d+\/\d+\s@ [^\]]*\](?:\s+from @\S+.*)?|-{3,})$/i;
|
|
49
|
+
/**
|
|
50
|
+
* How a dispatch prompt opens. These are turns the seat wrote to a running
|
|
51
|
+
* agent; they carry imperatives because that is what a dispatch is.
|
|
52
|
+
*/
|
|
53
|
+
const SEAT_OPENER = /^\s*(?:you are\b|your (?:branch|task|brief|report|cwd|job|pane|mission)\b|read your brief in full|read the brief\b|read (?:the )?(?:\/|~|[\w-]+\.md)|begin backlog item|your task:|mission:|task:|authori[sz]ed (?:execution )?brief|re-?read\b|acknowledge\b|this is a fresh session|first: )/i;
|
|
54
|
+
/**
|
|
55
|
+
* Words a dispatch prompt tends to carry: the seat's own shorthands, which the
|
|
56
|
+
* owner does not use when he states a ruling. One in a turn is enough, because
|
|
57
|
+
* none of them is owner vocabulary.
|
|
58
|
+
*/
|
|
59
|
+
const SEAT_ANATOMY = [
|
|
60
|
+
/\bAUTHORITATIVE BRIEF\b/i,
|
|
61
|
+
/\bAUTHORISED BRIEF\b/i,
|
|
62
|
+
/\bresult block\b/i,
|
|
63
|
+
/check-result\.mjs/,
|
|
64
|
+
/\bConfirm receipt\b/i,
|
|
65
|
+
/\bPI_SESSION_FILE\b/i,
|
|
66
|
+
/\bEnd it with the result block\b/i,
|
|
67
|
+
/\bDispatch facts\b/i,
|
|
68
|
+
/\bRead your brief\b/i,
|
|
69
|
+
];
|
|
70
|
+
/** Pasted-brief structure: headings that only a dispatch prompt carries. */
|
|
71
|
+
const BRIEF_HEADINGS = /^\s*#{2,}\s/m;
|
|
72
|
+
/** Sends a turn from the seat to a running agent. */
|
|
73
|
+
const STEER_OPENER = /^\s*(?:steer(?:,| from| to|:)|seat to |\[agent:|dispatch(?:ed)?:|correction to|status check|reminder:)/i;
|
|
74
|
+
/**
|
|
75
|
+
* Session machinery. A message about a timer, a poller, a pane or a
|
|
76
|
+
* predecessor's transcript is braid talking to a process; the owner states
|
|
77
|
+
* rules about how braid behaves, not about which lock file the previous
|
|
78
|
+
* occupant held.
|
|
79
|
+
*/
|
|
80
|
+
const SESSION_MACHINERY = /\b(?:timer|poller|polling|pane|worktree|predecessor|successor|lock (?:file|PID)|transcript|session file|placement section|check-result|result block|ci:check)\b/i;
|
|
81
|
+
/**
|
|
82
|
+
* What a ruling is about when it does not open with the owner's own voice: the
|
|
83
|
+
* system, its agents, its tools. A bare directive with none of this and no
|
|
84
|
+
* first person ("Do not read or write files.") is an instruction aimed at the
|
|
85
|
+
* reader, not a decision about braid.
|
|
86
|
+
*/
|
|
87
|
+
const SYSTEM_SCOPE = /\b(?:braid|agent|agents|worker|workers|writer|writers|reader|readers|seat|seats|system|prompt|memory|store|skill|skills|tool|tools|model|models|subscription|subscri\w*|session|sessions|orchestrator|identity|layer|layers|gate|gates|report|reports|brief|briefs|docs?|telegram|context|queue|pipeline|repo|repository|codebase|website|app|product)\b/i;
|
|
88
|
+
/**
|
|
89
|
+
* Explicit generalization. A rule aimed at any instance is a rule; one aimed
|
|
90
|
+
* at the agent reading it is a steer, and the escape hatch has to be stated.
|
|
91
|
+
*/
|
|
92
|
+
const GENERALIZED = /\b(?:any (?:instance|agent|worker|seat|one)|every (?:agent|instance|worker|seat)|generically?|whichever|regardless)\b/i;
|
|
93
|
+
/**
|
|
94
|
+
* The vocabulary this deployment hands the generic grammar. It is the only
|
|
95
|
+
* braid-specific input `classifyRulingBody()` takes, and it is a value rather
|
|
96
|
+
* than a parameter chain so a fixture can classify the same body with and
|
|
97
|
+
* without an envelope and compare.
|
|
98
|
+
*/
|
|
99
|
+
export const BRAID_VOCABULARY = {
|
|
100
|
+
namesSubject: (text) => SYSTEM_SCOPE.test(text),
|
|
101
|
+
talksProcess: (text) => SESSION_MACHINERY.test(text),
|
|
102
|
+
generalizes: (text) => GENERALIZED.test(text),
|
|
103
|
+
};
|
|
104
|
+
/**
|
|
105
|
+
* The owner's words inside a turn, or `null` when the turn is not the owner's
|
|
106
|
+
* speech.
|
|
107
|
+
*
|
|
108
|
+
* Stripping happens line by line, and the kept lines are the original lines, so
|
|
109
|
+
* a quote later cut from the body is still a contiguous slice of the stored
|
|
110
|
+
* turn - the pointer resolves either way. A turn that carries any non-telegram
|
|
111
|
+
* envelope is refused whole: a subsystem whisper and an owner tail can share
|
|
112
|
+
* one turn, and no mechanical rule here can say which sentence is whose.
|
|
113
|
+
*/
|
|
114
|
+
function ownerSpeech(body) {
|
|
115
|
+
const lines = body.split("\n");
|
|
116
|
+
const headers = lines.map((line) => WHISPER_HEADER.exec(line)).filter(Boolean);
|
|
117
|
+
if (headers.length > 0) {
|
|
118
|
+
const foreign = headers.find((header) => header[1].toLowerCase() !== "telegram");
|
|
119
|
+
if (foreign)
|
|
120
|
+
return null;
|
|
121
|
+
}
|
|
122
|
+
if (headers.length === 0)
|
|
123
|
+
return body;
|
|
124
|
+
const kept = [];
|
|
125
|
+
let inside = false;
|
|
126
|
+
for (const line of lines) {
|
|
127
|
+
if (WHISPER_HEADER.test(line)) {
|
|
128
|
+
inside = true;
|
|
129
|
+
continue;
|
|
130
|
+
}
|
|
131
|
+
if (WHISPER_END.test(line)) {
|
|
132
|
+
inside = false;
|
|
133
|
+
continue;
|
|
134
|
+
}
|
|
135
|
+
if (inside && TELEGRAM_TRANSPORT.test(line))
|
|
136
|
+
continue;
|
|
137
|
+
if (inside)
|
|
138
|
+
kept.push(line);
|
|
139
|
+
}
|
|
140
|
+
const stripped = kept.join("\n").trim();
|
|
141
|
+
return stripped || null;
|
|
142
|
+
}
|
|
143
|
+
/** Is this turn a dispatch prompt rather than the owner speaking? */
|
|
144
|
+
function looksLikeSeatPrompt(body) {
|
|
145
|
+
const firstLine = body.split("\n").find((line) => line.trim()) ?? "";
|
|
146
|
+
if (SEAT_OPENER.test(firstLine))
|
|
147
|
+
return true;
|
|
148
|
+
if (STEER_OPENER.test(firstLine))
|
|
149
|
+
return true;
|
|
150
|
+
for (const pattern of SEAT_ANATOMY)
|
|
151
|
+
if (pattern.test(body))
|
|
152
|
+
return true;
|
|
153
|
+
return BRIEF_HEADINGS.test(body) && /\bbrief\b/i.test(body);
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Classify one user turn.
|
|
157
|
+
*
|
|
158
|
+
* Refuses everything that is not owner speech before the grammar runs, then
|
|
159
|
+
* hands the body to the generic classifier with this deployment's vocabulary,
|
|
160
|
+
* and stamps the provenance the pointer and the duplicate key are built from.
|
|
161
|
+
*/
|
|
162
|
+
export function classifyOwnerRuling(turn) {
|
|
163
|
+
if (!turn || typeof turn.text !== "string")
|
|
164
|
+
return null;
|
|
165
|
+
const raw = turn.text.trim();
|
|
166
|
+
if (!raw)
|
|
167
|
+
return null;
|
|
168
|
+
const speech = ownerSpeech(raw);
|
|
169
|
+
if (!speech)
|
|
170
|
+
return null;
|
|
171
|
+
if (looksLikeSeatPrompt(speech))
|
|
172
|
+
return null;
|
|
173
|
+
const shape = classifyRulingBody(speech, BRAID_VOCABULARY);
|
|
174
|
+
if (!shape)
|
|
175
|
+
return null;
|
|
176
|
+
return {
|
|
177
|
+
class: shape.class,
|
|
178
|
+
quote: shape.quote,
|
|
179
|
+
session: turn.session,
|
|
180
|
+
session_id: turn.session_id,
|
|
181
|
+
project: turn.project,
|
|
182
|
+
ts: turn.ts,
|
|
183
|
+
line: turn.line,
|
|
184
|
+
};
|
|
185
|
+
}
|
|
186
|
+
/**
|
|
187
|
+
* The pointer the store carries in `source`, in one fixed shape:
|
|
188
|
+
* `owner ruling: <session path>:<line> (<iso ts>, <project>)`.
|
|
189
|
+
*
|
|
190
|
+
* Greppable by prefix, and it resolves: the path and line address the turn the
|
|
191
|
+
* quote came from, so `sed -n '<line>p' '<session path>'` prints the words.
|
|
192
|
+
*/
|
|
193
|
+
export function rulingPointer(candidate) {
|
|
194
|
+
return `${OWNER_RULING_LABEL}: ${candidate.session}:${candidate.line} (${candidate.ts}, ${candidate.project})`;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* The pointer as a pattern, so a caller that scans a store for filed rulings
|
|
198
|
+
* reads the label from the same place it writes it instead of spelling it a
|
|
199
|
+
* second time. Groups: 1 the session path, 2 the line number.
|
|
200
|
+
*/
|
|
201
|
+
export function rulingPointerPattern() {
|
|
202
|
+
const escaped = OWNER_RULING_LABEL.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
|
203
|
+
return new RegExp(`^${escaped}: (.+):(\\d+) \\(`);
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* The duplicate key: one turn is one ruling, so `<session_id>:<line>` names it
|
|
207
|
+
* whether the entry was written by this script, by hand, or by a later run.
|
|
208
|
+
*/
|
|
209
|
+
export function rulingDuplicateKey(candidate) {
|
|
210
|
+
return `${candidate.session_id}:${candidate.line}`;
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* A project label as a tag token: lowercase alphanumerics, single hyphens, no
|
|
214
|
+
* leading/trailing hyphen. `projects/agents/pi-braid` becomes
|
|
215
|
+
* `projects-agents-pi-braid`, which is greppable and cannot collide with a
|
|
216
|
+
* different project's label through punctuation alone.
|
|
217
|
+
*/
|
|
218
|
+
export function projectTag(label) {
|
|
219
|
+
const slug = label
|
|
220
|
+
.toLowerCase()
|
|
221
|
+
.replace(/[^a-z0-9]+/g, "-")
|
|
222
|
+
.replace(/^-+|-+$/g, "");
|
|
223
|
+
return slug || "unknown-project";
|
|
224
|
+
}
|
|
225
|
+
/**
|
|
226
|
+
* The fixed handles every filed ruling carries: the class a reader filters on,
|
|
227
|
+
* and the project it came from. The quote's own words are added beside these by
|
|
228
|
+
* `deriveTopicTags()`, because a handle names the entry while a topic word is
|
|
229
|
+
* what a later question arrives through.
|
|
230
|
+
*/
|
|
231
|
+
export function rulingBaseTags(candidate) {
|
|
232
|
+
return ["owner-ruling", candidate.class, projectTag(candidate.project)];
|
|
233
|
+
}
|
|
234
|
+
//# sourceMappingURL=owner-speech.js.map
|
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -138,7 +138,7 @@ before and after a full run. A non-zero delta is the leak this rule prevents.
|
|
|
138
138
|
### New fixtures: use `node:test`
|
|
139
139
|
|
|
140
140
|
A new fixture is written on `node:test`. The runner does not care which style a
|
|
141
|
-
file uses -
|
|
141
|
+
file uses - 98 of the core suite's 333 fixtures already use `node:test` - so the
|
|
142
142
|
reason is the failure the other style produces. A hand-rolled helper that calls
|
|
143
143
|
`fn()` without awaiting it discards the case's promise, so an `async` case runs
|
|
144
144
|
detached and the file can print its green tally before that case settles, with
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
3
|
+
"version": "0.43.12",
|
|
4
4
|
"description": "🥨 Braid - Metacognitive extension suite for pi coding agent: Adds memory, plan tracking, structured cognitive signals and completion checks on top of pi core loop, so long sessions keep their context and stop claiming unfinished work.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -33,6 +33,7 @@ Two surfaces in `skills-tool/` put a skill body in front of the agent: the auto-
|
|
|
33
33
|
- **Conversion is a detected read.** The whisper asks the agent to open the SKILL.md; the conversion signal is the `read` tool_result (`actual`), which is also what sets `hadSkillLoad` in the durable session record. The retired LOADED/SKIP reply is no longer solicited; `claimed` keeps its historical honor-system meaning and stays monotone.
|
|
34
34
|
- **The trigger has a mechanical form.** `skills-tool/loading-guidance.ts` carries both the judgment form (the task entered a listed skill's domain) and the mechanical form (about to call a tool family whose word appears in a skill's name). `prompt-builder` renders that text through the `skillsLoadingText` builder as the `skills-loading` section and holds no copy of the rules; the trigger's worked examples are derived at assembly from the live tool and skill names, so the text names no pair that the running session does not have. The identity's skills prose stays one sentence.
|
|
35
35
|
- **The catalog is in the prompt.** The same section renders every visible skill as one `- name: description` row, with the read path derived from the skills' own file paths (one root for a single pack, a directory heading per pack when a catalog is installed from several). A tool call is no longer the way the agent learns which skills exist: the floor exists because the prompt that opens a resumed session carries no domain vocabulary for a matcher to rank against. `list_skills` remains the price tool (reach, headings, ranking) rather than the catalog.
|
|
36
|
+
- **A retired skill is not advertised.** A SKILL.md whose frontmatter declares `status: merged`, `archived` or `deprecated` stops being advertised and matched, and the file stays on disk as history. The exclusion rides the flag `disable-model-invocation` already owns (derived at cache time in `index.ts`), so the catalog, the suggestion whisper, the at-use line, the accessor and `list_skills` agree without a second concept. The row stays in the unfiltered cache, so a read of the file still resolves.
|
|
36
37
|
- **Drift re-points at the floor.** When the session's own path-taking calls (`read`/`edit`/`write`) accumulate entries in a work area the floor was not rendered against, one steer line names that area and points back at the catalog. The rule and its bounds (two entries, one fire per twelve calls, three per session, quiet for the same window after any skill surface) live in `loading-guidance.ts` beside the floor text; the wiring is the `tool_result` handler in `auto-inject.ts`. Bounds are the whole design: the line is only worth its noise if it stays rare.
|
|
37
38
|
- **The at-use line is observed, never enforced.** With `braid.skills.inform` set to `inform` (default `off`), a `tool_result` whose call **succeeded**, whose tool name yields a family token some visible cached skill declares with `governs:`, and whose obligation row carries no `read` leg emits one steer line naming the file path and the family. It runs after the result exists, returns no replacement, and refuses, delays and rewrites nothing: any gating change can only make it quieter, which is the property that separates it from a refusal gate. The payload is derived from the declaration and the catalogue entry only (the skill's own `filePath`, the token the call's name yields), so no skill name is invented in code and no tool argument is echoed. Once per session per skill, suppressed by the same obligation record the legs write (its `informed` leg), silenced by a read at any point, and hidden skills are never named. `skill_stats` reports it as `inform` from the store: `undecided` below twenty informs, `beats` only when the lower Wilson bound clears the suggestion channel's 18.8% pair conversion, `noise` otherwise.
|
|
38
39
|
- **Applicability is recorded, never enforced.** The counters cannot tell a skill that applied and was ignored from one that never applied, and the sessions that read nothing are mostly sessions no phrase matches. `skills-tool/applicability.ts` decides that difference from the skill's own declaration (the trigger phrases its file carries: frontmatter `trigger:`/`triggers:`, a `## trigger:` body heading, a description `Triggers:` tail), never from the ranking heuristic, with the injector's occurrence boundary and a clause-scoped negation read, so a phrase inside "do not research this" is not a condition met. The verdict is `read` (condition held and a detected read followed), `ignored` (condition held and no read followed), or `not-applicable` (derived: the census's `evaluated` minus the verdict rows); a skill whose file declares no phrase is named `undeclared` rather than judged either way. It reaches disk as `kind: "applicability"` rows in the per-session store (one verdict row per applicable skill keyed on `sessionId` + `skill`, one census row per session) and out through `skill_stats`. It is an observer: it writes no delivery, slot, cooldown, counter or prompt, and it owns no compliance leg. `suggested`/`listed`/`informed`/`read`/`applied` belong to the record that owns each skill's declared tool family; the verdict row joins it on the skill name.
|
|
@@ -48,7 +48,7 @@ import {
|
|
|
48
48
|
rankSkillsDeterministic,
|
|
49
49
|
} from "./auto-inject.js";
|
|
50
50
|
import type { DeterministicRanking, RankedSkill, RelevanceReason } from "./auto-inject.js";
|
|
51
|
-
import {
|
|
51
|
+
import { readSkillFrontmatter } from "./skill-triggers.js";
|
|
52
52
|
import type { TriggerSource } from "./skill-triggers.js";
|
|
53
53
|
import { readGovernedFamilies } from "./skill-families.js";
|
|
54
54
|
import {
|
|
@@ -78,9 +78,10 @@ interface CachedSkill {
|
|
|
78
78
|
baseDir: string;
|
|
79
79
|
sourceInfo?: { source?: string; package?: string };
|
|
80
80
|
/**
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
81
|
+
* Excluded from model selection: pi's own frontmatter flag, or a status this
|
|
82
|
+
* cache reads as retired (see RETIRED_STATUSES). Either way braid keeps the
|
|
83
|
+
* skill out of the surfaces that advertise skills to the model, while the
|
|
84
|
+
* file stays on disk and an explicit read of it still resolves.
|
|
84
85
|
*/
|
|
85
86
|
disableModelInvocation?: boolean;
|
|
86
87
|
/** Frontmatter trigger phrases, resolved from SKILL.md at cache time. */
|
|
@@ -91,17 +92,40 @@ interface CachedSkill {
|
|
|
91
92
|
|
|
92
93
|
let cachedSkills: CachedSkill[] = [];
|
|
93
94
|
|
|
95
|
+
/**
|
|
96
|
+
* Statuses that mean the skill is no longer the place to look: its content
|
|
97
|
+
* lives in a successor, or the file is kept as history. The vocabulary is the
|
|
98
|
+
* pack's (a `status:` frontmatter key), and the exclusion is this module's:
|
|
99
|
+
* no file is deleted, renamed or edited to make a skill stop being advertised.
|
|
100
|
+
*/
|
|
101
|
+
const RETIRED_STATUSES = new Set(["merged", "archived", "deprecated"]);
|
|
102
|
+
|
|
103
|
+
/** Whether a declared status retires the skill from model selection. */
|
|
104
|
+
function isRetiredStatus(status: string): boolean {
|
|
105
|
+
return RETIRED_STATUSES.has(status);
|
|
106
|
+
}
|
|
107
|
+
|
|
94
108
|
/**
|
|
95
109
|
* Called from prompt-builder's before_agent_start to populate the cache.
|
|
96
110
|
* Resolves each skill's frontmatter trigger phrases here, once per turn:
|
|
97
111
|
* the matcher scores triggers, pi's skill objects never carry them (fixed
|
|
98
112
|
* shape), and the memoized read makes repeat turns stat-only.
|
|
113
|
+
*
|
|
114
|
+
* The same read answers the file's `status:`, and a retired status rides the
|
|
115
|
+
* `disableModelInvocation` exclusion rather than a second one: every surface
|
|
116
|
+
* that advertises skills already filters on that flag, so one derived field
|
|
117
|
+
* keeps the catalog, the whisper, the at-use line and the accessors in
|
|
118
|
+
* agreement. The row is still cached, so an explicit read of the file is still
|
|
119
|
+
* recognized — the skill stops being advertised, not becoming unreadable.
|
|
99
120
|
*/
|
|
100
121
|
export function setCachedSkills(skills: CachedSkill[]): void {
|
|
122
|
+
let retired = 0;
|
|
101
123
|
cachedSkills = skills.map((s) => {
|
|
102
|
-
const entries =
|
|
124
|
+
const { entries, status } = readSkillFrontmatter(s.filePath, s.description);
|
|
103
125
|
const triggerSources: Record<string, TriggerSource> = {};
|
|
104
126
|
for (const entry of entries) triggerSources[entry.phrase] = entry.source;
|
|
127
|
+
const isRetired = isRetiredStatus(status);
|
|
128
|
+
if (isRetired) retired++;
|
|
105
129
|
return {
|
|
106
130
|
...s,
|
|
107
131
|
triggers: entries.map((entry) => entry.phrase),
|
|
@@ -110,11 +134,15 @@ export function setCachedSkills(skills: CachedSkill[]): void {
|
|
|
110
134
|
// frontmatter read the phrases come from (one extra parse per file per
|
|
111
135
|
// process). An empty list is a declaration of no family, not a miss.
|
|
112
136
|
families: readGovernedFamilies(s.filePath),
|
|
137
|
+
disableModelInvocation: s.disableModelInvocation === true || isRetired,
|
|
113
138
|
};
|
|
114
139
|
});
|
|
115
140
|
// Sync with auto-inject subsystem (enriched cache — triggers ride along)
|
|
116
141
|
updateSkillCache(cachedSkills);
|
|
117
|
-
log.debug(
|
|
142
|
+
log.debug(
|
|
143
|
+
`Cached ${skills.length} skills for list_skills tool` +
|
|
144
|
+
(retired ? ` (${retired} retired by status)` : ""),
|
|
145
|
+
);
|
|
118
146
|
}
|
|
119
147
|
|
|
120
148
|
/**
|
|
@@ -64,8 +64,8 @@ export function skillsCatalogRule(readRoot: string, grouped = false): string {
|
|
|
64
64
|
return `This catalog is every installed skill: one row per skill, name and description.${readPath} When the task enters a listed skill's domain, read the WHOLE SKILL.md before acting in that domain; never act from memory of a skill's contents.`;
|
|
65
65
|
}
|
|
66
66
|
|
|
67
|
-
/** Paragraph 2: the pointer rule
|
|
68
|
-
export const SKILLS_POINTER_RULE = `Pointer rule: the catalog one-liner is metadata, not content — the SKILL.md path is the knowledge.
|
|
67
|
+
/** Paragraph 2: the pointer rule, exported so a fixture can pin its text. */
|
|
68
|
+
export const SKILLS_POINTER_RULE = `Pointer rule: the catalog one-liner is metadata, not content — the SKILL.md path is the knowledge. If the body itself is already in this prompt you have read it; if you have only a description or an excerpt, you have not.`;
|
|
69
69
|
|
|
70
70
|
const MECHANICAL_TRIGGER_LEAD = `Mechanical trigger, no judgment call: about to use a tool family whose word appears in a skill's name`;
|
|
71
71
|
const MECHANICAL_TRIGGER_TAIL = `→ read that SKILL.md before the first call in the family.`;
|
|
@@ -28,6 +28,12 @@
|
|
|
28
28
|
* capitalized ("MASTERSHIP TRANSFER: …"), and a phrase that only matched
|
|
29
29
|
* lowercase text would be dead in production while a lowercase-only unit
|
|
30
30
|
* fixture kept the suite green.
|
|
31
|
+
*
|
|
32
|
+
* The same parse also returns the file's declared lifecycle `status`, which is
|
|
33
|
+
* NOT matcher input: the skills-tool needs it once per file, at cache time, to
|
|
34
|
+
* decide whether the skill is still advertised. It rides this read because the
|
|
35
|
+
* file is already open here — a reader of its own would be a third read of the
|
|
36
|
+
* same bytes per process, and a status is not worth one.
|
|
31
37
|
*/
|
|
32
38
|
|
|
33
39
|
import { statSync, readFileSync } from "node:fs";
|
|
@@ -65,6 +71,18 @@ interface TriggerCacheEntry {
|
|
|
65
71
|
/** The description the entries were merged with: a different one is a miss. */
|
|
66
72
|
description: string;
|
|
67
73
|
entries: TriggerEntry[];
|
|
74
|
+
/** The declared lifecycle status, lowercased; "" when the file declares none. */
|
|
75
|
+
status: string;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* One SKILL.md's trigger phrases plus the lifecycle status its frontmatter
|
|
80
|
+
* declares — everything one parse of the file answers.
|
|
81
|
+
*/
|
|
82
|
+
export interface SkillFrontmatterRead {
|
|
83
|
+
entries: TriggerEntry[];
|
|
84
|
+
/** Lowercased `status:` token, or "" when the file declares none. */
|
|
85
|
+
status: string;
|
|
68
86
|
}
|
|
69
87
|
|
|
70
88
|
const cache = new Map<string, TriggerCacheEntry>();
|
|
@@ -102,6 +120,15 @@ export function readSkillTriggers(filePath: string, description?: string): strin
|
|
|
102
120
|
return readSkillTriggerEntries(filePath, description).map((entry) => entry.phrase);
|
|
103
121
|
}
|
|
104
122
|
|
|
123
|
+
/**
|
|
124
|
+
* Normalize a frontmatter `status` value into the token a caller matches on.
|
|
125
|
+
* Only a string is a declaration: a missing key, a null, or a nested shape is
|
|
126
|
+
* the absence of one. Pure.
|
|
127
|
+
*/
|
|
128
|
+
function normalizeSkillStatus(value: unknown): string {
|
|
129
|
+
return typeof value === "string" ? value.trim().toLowerCase() : "";
|
|
130
|
+
}
|
|
131
|
+
|
|
105
132
|
/**
|
|
106
133
|
* Read a skill's authored phrases WITH their provenance, merged in priority
|
|
107
134
|
* order: frontmatter (`trigger` or `triggers`), then a `## trigger:` body
|
|
@@ -112,13 +139,23 @@ export function readSkillTriggers(filePath: string, description?: string): strin
|
|
|
112
139
|
* a miss, because the merged list depends on it).
|
|
113
140
|
*/
|
|
114
141
|
export function readSkillTriggerEntries(filePath: string, description?: string): TriggerEntry[] {
|
|
142
|
+
return readSkillFrontmatter(filePath, description).entries;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* Read a skill's trigger phrases WITH their provenance plus its declared
|
|
147
|
+
* lifecycle status, from one memoized parse. Same sources, precedence and
|
|
148
|
+
* memoization as readSkillTriggerEntries; the status is the frontmatter key of
|
|
149
|
+
* that name, lowercased, "" when absent or unreadable.
|
|
150
|
+
*/
|
|
151
|
+
export function readSkillFrontmatter(filePath: string, description?: string): SkillFrontmatterRead {
|
|
115
152
|
const desc = description ?? "";
|
|
116
153
|
let st;
|
|
117
154
|
try {
|
|
118
155
|
st = statSync(filePath);
|
|
119
156
|
} catch {
|
|
120
157
|
cache.delete(filePath);
|
|
121
|
-
return [];
|
|
158
|
+
return { entries: [], status: "" };
|
|
122
159
|
}
|
|
123
160
|
const cached = cache.get(filePath);
|
|
124
161
|
if (
|
|
@@ -127,13 +164,15 @@ export function readSkillTriggerEntries(filePath: string, description?: string):
|
|
|
127
164
|
cached.size === st.size &&
|
|
128
165
|
cached.description === desc
|
|
129
166
|
) {
|
|
130
|
-
return cached.entries;
|
|
167
|
+
return { entries: cached.entries, status: cached.status };
|
|
131
168
|
}
|
|
132
169
|
const sources: TriggerEntry[][] = [];
|
|
170
|
+
let status = "";
|
|
133
171
|
try {
|
|
134
172
|
const { frontmatter, body } = parseFrontmatter(readFileSync(filePath, "utf-8"));
|
|
135
173
|
const fm = frontmatter as Record<string, unknown>;
|
|
136
174
|
const label = (source: TriggerSource) => (phrase: string) => ({ phrase, source });
|
|
175
|
+
status = normalizeSkillStatus(fm.status);
|
|
137
176
|
sources.push(
|
|
138
177
|
normalizeTriggers(fm.trigger).map(label("frontmatter")),
|
|
139
178
|
normalizeTriggers(fm.triggers).map(label("frontmatter")),
|
|
@@ -148,8 +187,8 @@ export function readSkillTriggerEntries(filePath: string, description?: string):
|
|
|
148
187
|
parseDescriptionTriggers(desc).map((phrase) => ({ phrase, source: "description" })),
|
|
149
188
|
);
|
|
150
189
|
const entries = mergeTriggerEntries(sources);
|
|
151
|
-
cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, description: desc, entries });
|
|
152
|
-
return entries;
|
|
190
|
+
cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, description: desc, entries, status });
|
|
191
|
+
return { entries, status };
|
|
153
192
|
}
|
|
154
193
|
|
|
155
194
|
/**
|