pi-braid 0.40.2 → 0.40.5
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/build-info.json +4 -4
- package/dist/extensions/cognitive/metacognition/handlers/claim-verification.js +7 -1
- package/dist/extensions/cognitive/metacognition/handlers/finalize.js +20 -0
- package/dist/extensions/cognitive/topic-drift/index.js +19 -2
- package/dist/extensions/core/prompt-builder/top-level-extensions.d.ts +6 -5
- package/dist/extensions/core/prompt-builder/top-level-extensions.js +64 -29
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +99 -17
- package/dist/extensions/core/skills-tool/auto-inject.js +129 -17
- package/dist/extensions/core/skills-tool/skill-triggers.d.ts +37 -13
- package/dist/extensions/core/skills-tool/skill-triggers.js +54 -16
- package/dist/extensions/memory/context-manager/handlers/tools/context-inspect.js +7 -1
- package/dist/extensions/memory/memory-agent-bridge/explore-paths.d.ts +2 -24
- package/dist/extensions/memory/memory-agent-bridge/explore-paths.js +33 -2
- package/dist/extensions/scheduling/timer/index.js +9 -1
- package/dist/extensions/self/error-tracking/index.js +8 -1
- package/dist/extensions/self/health-maintenance/handlers/session-health-tool.js +9 -2
- package/package.json +2 -1
- package/src/extensions/cognitive/metacognition/handlers/claim-verification.ts +8 -1
- package/src/extensions/cognitive/metacognition/handlers/finalize.ts +21 -0
- package/src/extensions/cognitive/topic-drift/index.ts +20 -2
- package/src/extensions/core/prompt-builder/AGENTS.md +1 -1
- package/src/extensions/core/prompt-builder/top-level-extensions.ts +68 -29
- package/src/extensions/core/skills-tool/auto-inject.ts +170 -19
- package/src/extensions/core/skills-tool/skill-triggers.ts +53 -16
- package/src/extensions/memory/context-manager/handlers/tools/context-inspect.ts +8 -1
- package/src/extensions/memory/memory-agent-bridge/explore-paths.ts +37 -3
- package/src/extensions/scheduling/timer/index.ts +10 -1
- package/src/extensions/self/error-tracking/index.ts +9 -1
- package/src/extensions/self/health-maintenance/handlers/session-health-tool.ts +10 -2
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.40.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.40.5",
|
|
4
|
+
"sha": "5302e19de5f827e43f8e88ae90adef379842a002",
|
|
5
|
+
"shaShort": "5302e19",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-10-
|
|
8
|
+
"packedAt": "2026-10-20T14:50:06.898Z"
|
|
9
9
|
}
|
|
@@ -19,6 +19,10 @@ import { classify } from "../../../../lib/ai/text-classifier.js";
|
|
|
19
19
|
import { CRITICS } from "../../../../lib/ai/critic-registry.js";
|
|
20
20
|
import { consolidatedClaimCritique } from "../../../../lib/ai/consolidated-claim-critic.js";
|
|
21
21
|
const log = createLogger("metacognition:claim-verification");
|
|
22
|
+
/** A blank string is "not provided": a client that emits every schema key sends "" for the unused ones. */
|
|
23
|
+
function optionalString(v) {
|
|
24
|
+
return typeof v === "string" && v.trim().length > 0 ? v : undefined;
|
|
25
|
+
}
|
|
22
26
|
function truncate(text, maxLen) {
|
|
23
27
|
return text.length > maxLen ? text.slice(0, maxLen) + "..." : text;
|
|
24
28
|
}
|
|
@@ -116,7 +120,9 @@ export function createVerifyClaimTool() {
|
|
|
116
120
|
if (!p.claim || !Array.isArray(p.context)) {
|
|
117
121
|
throw new Error("verify_claim requires 'claim' (string) and 'context' (string array)");
|
|
118
122
|
}
|
|
119
|
-
|
|
123
|
+
// A blank claimId is no id: it would become the tracking key of every
|
|
124
|
+
// such call for the rest of the session.
|
|
125
|
+
const claimId = optionalString(p.claimId) ?? `claim-${Date.now()}`;
|
|
120
126
|
const issues = [];
|
|
121
127
|
// PRIMARY PATH: consolidated single-LLM-call
|
|
122
128
|
let consolidatedUsed = false;
|
|
@@ -453,6 +453,26 @@ finalize(completed=true, summary="Fixed the bug", tasksRemaining=["write tests"]
|
|
|
453
453
|
details: { finalized: false, blocked: true, error: "missing_params" },
|
|
454
454
|
};
|
|
455
455
|
}
|
|
456
|
+
// A blank summary names nothing. The `=== undefined` check above lets it
|
|
457
|
+
// through, and the summary lands in the memory episode, the session label
|
|
458
|
+
// and the deliverables manifest -- an unfindable task recorded as done.
|
|
459
|
+
if (typeof params.summary !== "string" || params.summary.trim().length === 0) {
|
|
460
|
+
return {
|
|
461
|
+
content: [
|
|
462
|
+
{
|
|
463
|
+
type: "text",
|
|
464
|
+
text: `**FINALIZE REQUIRES A SUMMARY**
|
|
465
|
+
|
|
466
|
+
finalize was called with summary ${JSON.stringify(params.summary ?? null)}, which names nothing to record.
|
|
467
|
+
Provide the summary text: what was accomplished, or what is still open with completed: false.
|
|
468
|
+
|
|
469
|
+
Example:
|
|
470
|
+
finalize(completed=true, summary="Fixed the parser offset clamp", tasksRemaining=["add fixture"])`,
|
|
471
|
+
},
|
|
472
|
+
],
|
|
473
|
+
details: { finalized: false, blocked: true, error: "missing_summary" },
|
|
474
|
+
};
|
|
475
|
+
}
|
|
456
476
|
// Pre-flight check: verify must have passed
|
|
457
477
|
if (_ctx && !params.completed) {
|
|
458
478
|
const lastVerification = getLastVerification(_ctx);
|
|
@@ -21,6 +21,10 @@ import { consolidatedTopicCritique } from "../../../lib/detection/consolidated-t
|
|
|
21
21
|
import { sendTrackedMessage } from "../../../lib/utils/injection-tracker.js";
|
|
22
22
|
import { BRAID_INJECTED, BRAID_SOURCE } from "../../../lib/constants/injection-details.js";
|
|
23
23
|
const log = createLogger("topic-drift");
|
|
24
|
+
/** A blank string is "not provided": a client that emits every schema key sends "" for the unused ones. */
|
|
25
|
+
function optionalString(v) {
|
|
26
|
+
return typeof v === "string" && v.trim().length > 0 ? v : undefined;
|
|
27
|
+
}
|
|
24
28
|
const DRIFT_THRESHOLD = 0.5;
|
|
25
29
|
// ANCHOR_TURNS_BEFORE_RESET comes from lib/constants/session-thresholds.ts —
|
|
26
30
|
// the single source of truth.
|
|
@@ -263,7 +267,20 @@ export default function topicDriftExtension(pi) {
|
|
|
263
267
|
switch (params?.action) {
|
|
264
268
|
case "check": {
|
|
265
269
|
const state = getExtensionState(ctx, "topic-drift", createDriftState);
|
|
266
|
-
const output = params.output
|
|
270
|
+
const output = optionalString(params.output);
|
|
271
|
+
if (output === undefined) {
|
|
272
|
+
// "" would be measured as an empty response and answered
|
|
273
|
+
// "No topic drift" -- a pass for a check that never ran.
|
|
274
|
+
return {
|
|
275
|
+
content: [
|
|
276
|
+
{
|
|
277
|
+
type: "text",
|
|
278
|
+
text: `topic_drift action=check requires a non-empty 'output': the response text to test against the anchored request.`,
|
|
279
|
+
},
|
|
280
|
+
],
|
|
281
|
+
details: { error: "missing_output", action: "check" },
|
|
282
|
+
};
|
|
283
|
+
}
|
|
267
284
|
let drifted = false;
|
|
268
285
|
let similarity = 1.0;
|
|
269
286
|
let missingAnchors = [];
|
|
@@ -313,7 +330,7 @@ export default function topicDriftExtension(pi) {
|
|
|
313
330
|
}
|
|
314
331
|
case "reset": {
|
|
315
332
|
const state = getExtensionState(ctx, "topic-drift", createDriftState);
|
|
316
|
-
const request = params.newRequest ?? state.originalRequest;
|
|
333
|
+
const request = optionalString(params.newRequest) ?? state.originalRequest;
|
|
317
334
|
resetAnchors(state, request);
|
|
318
335
|
return {
|
|
319
336
|
content: [
|
|
@@ -4,9 +4,10 @@
|
|
|
4
4
|
* Discovers pi extension PACKAGES (package.json with a `pi` field)
|
|
5
5
|
* from the settings `packages` field — never a walk over cwd/siblings.
|
|
6
6
|
* Sources in pi-core precedence: project (<cwd>/.pi/settings.json)
|
|
7
|
-
* then user (
|
|
8
|
-
* same identity. Entries: absolute local path, `npm:` (
|
|
9
|
-
*
|
|
7
|
+
* then user (<agentDir>/settings.json); project scope wins for the
|
|
8
|
+
* same identity. Entries: absolute local path, `npm:` (pi's managed
|
|
9
|
+
* install tree first, then the global npm root), or `git:`
|
|
10
|
+
* (best-effort skip), tagged project / user-global.
|
|
10
11
|
* Best-effort: unreadable or missing packages are silently skipped —
|
|
11
12
|
* no "failed to resolve" noise in the prompt.
|
|
12
13
|
*/
|
|
@@ -34,8 +35,8 @@ export interface TopLevelExtension {
|
|
|
34
35
|
*
|
|
35
36
|
* Settings-file paths:
|
|
36
37
|
* - project: `<cwd>/.pi/settings.json`
|
|
37
|
-
* - user-global:
|
|
38
|
-
*
|
|
38
|
+
* - user-global: `<agentDir>/settings.json`, where the agent dir is
|
|
39
|
+
* `PI_CODING_AGENT_DIR` when set, else `~/.pi/agent`.
|
|
39
40
|
*/
|
|
40
41
|
export declare function discoverTopLevelExtensions(cwd?: string, options?: {
|
|
41
42
|
projectSettingsPath?: string;
|
|
@@ -4,9 +4,10 @@
|
|
|
4
4
|
* Discovers pi extension PACKAGES (package.json with a `pi` field)
|
|
5
5
|
* from the settings `packages` field — never a walk over cwd/siblings.
|
|
6
6
|
* Sources in pi-core precedence: project (<cwd>/.pi/settings.json)
|
|
7
|
-
* then user (
|
|
8
|
-
* same identity. Entries: absolute local path, `npm:` (
|
|
9
|
-
*
|
|
7
|
+
* then user (<agentDir>/settings.json); project scope wins for the
|
|
8
|
+
* same identity. Entries: absolute local path, `npm:` (pi's managed
|
|
9
|
+
* install tree first, then the global npm root), or `git:`
|
|
10
|
+
* (best-effort skip), tagged project / user-global.
|
|
10
11
|
* Best-effort: unreadable or missing packages are silently skipped —
|
|
11
12
|
* no "failed to resolve" noise in the prompt.
|
|
12
13
|
*/
|
|
@@ -102,8 +103,9 @@ function basename(p) {
|
|
|
102
103
|
* source is unsupported or cannot be located on disk.
|
|
103
104
|
*
|
|
104
105
|
* Supported shapes:
|
|
105
|
-
* - `npm:<spec>` (e.g. `npm:pi-web-access`) -- looks in
|
|
106
|
-
*
|
|
106
|
+
* - `npm:<spec>` (e.g. `npm:pi-web-access`) -- looks in pi's
|
|
107
|
+
* managed install tree, then the global npm root, under each
|
|
108
|
+
* scoped directory.
|
|
107
109
|
* - absolute local path (starts with `/`) -- used as-is.
|
|
108
110
|
* - relative local path -- resolved relative to `cwd`.
|
|
109
111
|
*/
|
|
@@ -111,7 +113,7 @@ function resolveEntryToPackage(source, scope, cwd) {
|
|
|
111
113
|
const trimmed = source.trim();
|
|
112
114
|
if (!trimmed)
|
|
113
115
|
return null;
|
|
114
|
-
// npm:<spec> -- find in global node_modules.
|
|
116
|
+
// npm:<spec> -- find in the managed install tree, then global node_modules.
|
|
115
117
|
if (trimmed.startsWith("npm:")) {
|
|
116
118
|
const spec = trimmed.slice("npm:".length).trim();
|
|
117
119
|
const at = spec.lastIndexOf("@");
|
|
@@ -158,35 +160,69 @@ function expandHome(p) {
|
|
|
158
160
|
return p;
|
|
159
161
|
}
|
|
160
162
|
/**
|
|
161
|
-
*
|
|
162
|
-
*
|
|
163
|
-
*
|
|
164
|
-
*
|
|
163
|
+
* Resolve pi's agent directory. `PI_CODING_AGENT_DIR` relocates the whole
|
|
164
|
+
* agent home when set and non-empty; otherwise the default is `~/.pi/agent`.
|
|
165
|
+
* Both the user-global settings file and the managed npm install tree live
|
|
166
|
+
* under this one directory, so they are resolved from this one function.
|
|
167
|
+
*/
|
|
168
|
+
function resolveAgentDir() {
|
|
169
|
+
const override = process.env.PI_CODING_AGENT_DIR?.trim();
|
|
170
|
+
if (override)
|
|
171
|
+
return expandHome(override);
|
|
172
|
+
return join(process.env.HOME ?? "~", ".pi", "agent");
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* Locate an installed npm package by name, searching pi's managed install
|
|
176
|
+
* tree before the global npm root. Managed first because that is where pi
|
|
177
|
+
* installs a settings-declared `npm:` entry (`<agentDir>/npm/node_modules`)
|
|
178
|
+
* and it consults a legacy global install only when the managed copy is
|
|
179
|
+
* absent -- so the managed copy is the one pi actually loads. The global
|
|
180
|
+
* root stays as that same fallback, for packages installed by hand.
|
|
165
181
|
*
|
|
166
|
-
*
|
|
182
|
+
* Optional `version` filters to a directory whose `package.json` version
|
|
183
|
+
* matches; if absent, the first matching directory wins. Returns the
|
|
184
|
+
* absolute directory path, or null if not found in any root.
|
|
167
185
|
*/
|
|
168
186
|
function findNpmPackageDir(name, version) {
|
|
187
|
+
for (const root of getNpmSearchRoots()) {
|
|
188
|
+
const dir = findPackageInNpmRoot(root, name, version);
|
|
189
|
+
if (dir)
|
|
190
|
+
return dir;
|
|
191
|
+
}
|
|
192
|
+
return null;
|
|
193
|
+
}
|
|
194
|
+
/** The npm roots searched for an `npm:` entry, in precedence order. */
|
|
195
|
+
function getNpmSearchRoots() {
|
|
196
|
+
const roots = [join(resolveAgentDir(), "npm", "node_modules")];
|
|
169
197
|
const globalRoot = getGlobalNpmRoot();
|
|
170
|
-
if (
|
|
171
|
-
|
|
172
|
-
|
|
198
|
+
if (globalRoot)
|
|
199
|
+
roots.push(globalRoot);
|
|
200
|
+
return roots;
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* Find the package directory for `name` inside one npm root.
|
|
204
|
+
*
|
|
205
|
+
* Scoped package: @scope/name -> look directly under `<root>/@scope/name`.
|
|
206
|
+
* Unscoped: scan the root's own directories for a package.json whose `name`
|
|
207
|
+
* matches -- npm installs both flat and nested layouts. A directory with no
|
|
208
|
+
* readable package.json is skipped, never fatal.
|
|
209
|
+
*/
|
|
210
|
+
function findPackageInNpmRoot(root, name, version) {
|
|
211
|
+
if (!existsSync(root))
|
|
173
212
|
return null;
|
|
174
|
-
// Scoped package: @scope/name -> look under globalRoot/@scope/name.
|
|
175
213
|
if (name.startsWith("@")) {
|
|
176
|
-
const dir = join(
|
|
214
|
+
const dir = join(root, name);
|
|
177
215
|
return packageDirMatches(dir, version) ? dir : null;
|
|
178
216
|
}
|
|
179
|
-
// Unscoped: scan globalRoot itself for a directory whose
|
|
180
|
-
// package.json `name` matches. npm installs both flat and nested layouts.
|
|
181
217
|
let entries;
|
|
182
218
|
try {
|
|
183
|
-
entries = readdirSync(
|
|
219
|
+
entries = readdirSync(root);
|
|
184
220
|
}
|
|
185
221
|
catch {
|
|
186
222
|
return null;
|
|
187
223
|
}
|
|
188
224
|
for (const entry of entries) {
|
|
189
|
-
const dir = join(
|
|
225
|
+
const dir = join(root, entry);
|
|
190
226
|
let isDir;
|
|
191
227
|
try {
|
|
192
228
|
isDir = statSync(dir).isDirectory();
|
|
@@ -228,10 +264,11 @@ function packageDirMatches(dir, expectedVersion, expectedName) {
|
|
|
228
264
|
}
|
|
229
265
|
/**
|
|
230
266
|
* Resolve the global npm root via `npm root -g`. Returns null if
|
|
231
|
-
* the command fails or produces no output.
|
|
232
|
-
*
|
|
233
|
-
*
|
|
234
|
-
*
|
|
267
|
+
* the command fails or produces no output. This is the fallback root
|
|
268
|
+
* only -- pi's managed install tree is searched first (see
|
|
269
|
+
* `findNpmPackageDir`). Cached after first successful call so the
|
|
270
|
+
* (slow) `npm root -g` invocation runs at most once per process --
|
|
271
|
+
* the value never changes inside one pi session.
|
|
235
272
|
*
|
|
236
273
|
* Implemented as an IIFE-wrapped closure so the cache `let`
|
|
237
274
|
* stays function-scoped (the project's no-module-level-let
|
|
@@ -267,14 +304,12 @@ const getGlobalNpmRoot = (() => {
|
|
|
267
304
|
*
|
|
268
305
|
* Settings-file paths:
|
|
269
306
|
* - project: `<cwd>/.pi/settings.json`
|
|
270
|
-
* - user-global:
|
|
271
|
-
*
|
|
307
|
+
* - user-global: `<agentDir>/settings.json`, where the agent dir is
|
|
308
|
+
* `PI_CODING_AGENT_DIR` when set, else `~/.pi/agent`.
|
|
272
309
|
*/
|
|
273
310
|
export function discoverTopLevelExtensions(cwd = process.cwd(), options) {
|
|
274
311
|
const projectPath = options?.projectSettingsPath ?? join(cwd, ".pi", "settings.json");
|
|
275
|
-
const userPath = options?.userSettingsPath ??
|
|
276
|
-
process.env.PI_CODING_AGENT_DIR ??
|
|
277
|
-
join(process.env.HOME ?? "~", ".pi", "agent", "settings.json");
|
|
312
|
+
const userPath = options?.userSettingsPath ?? join(resolveAgentDir(), "settings.json");
|
|
278
313
|
const seen = new Set();
|
|
279
314
|
const out = [];
|
|
280
315
|
const add = (pkg, source) => {
|
|
@@ -8,13 +8,23 @@
|
|
|
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: a word present in
|
|
19
|
+
* COMMON_KEYWORD_DF or more of the cached skills' documents cannot tell
|
|
20
|
+
* skills apart, so description/path hits from it score nothing. Name and
|
|
21
|
+
* trigger hits are never gated — the skill's own identity vocabulary is
|
|
22
|
+
* what a prompt naming it looks like.
|
|
23
|
+
* 1b. Ranking: equal scores compare by more distinct matched signals, then
|
|
24
|
+
* by rarer evidence (lower summed document frequency), then by name.
|
|
25
|
+
* Alphabetical order alone decided which of two equally-scored skills
|
|
26
|
+
* took a slot, which is how a broadly-matching skill outranked the one
|
|
27
|
+
* whose evidence was the prompt's actual subject.
|
|
18
28
|
* 2. Session-scoped state: track which skills were injected on which turn.
|
|
19
29
|
* Cooldown is per-skill on top of the global floor: an injected skill
|
|
20
30
|
* cools down at least COOLDOWN_TURNS, and once it was actually loaded
|
|
@@ -117,6 +127,32 @@ export declare const MAX_EXCERPT_CHARS = 300;
|
|
|
117
127
|
* and/or filePath keyword hits only). Name matches qualify at any score.
|
|
118
128
|
*/
|
|
119
129
|
export declare const MIN_NON_NAME_SCORE = 2;
|
|
130
|
+
/**
|
|
131
|
+
* A keyword present in this many skill documents or more is corpus-common: it
|
|
132
|
+
* appears in a large share of the catalog (5 of 22 skills = 23%), so it cannot
|
|
133
|
+
* distinguish one skill from another and contributes NOTHING to the weak legs
|
|
134
|
+
* (description, catalog path).
|
|
135
|
+
*
|
|
136
|
+
* The number is measured, not guessed. Two measurements, one threshold:
|
|
137
|
+
*
|
|
138
|
+
* Corpus mass. Over 400 recorded prompts against the 22-skill catalog, the
|
|
139
|
+
* weak-leg points awarded to words by document frequency are df1 17.0%,
|
|
140
|
+
* df2 22.4%, df3 20.9%, df4 13.3%, df5 7.8%, df6 4.1%, df7 9.1%, df9 0.4%,
|
|
141
|
+
* df22 5.1%. Words at df ≥ 5 carry 26.4% of every weak-leg point the matcher
|
|
142
|
+
* awards; df ≥ 4 carries 39.7%, df ≥ 6 carries 18.6%. The catalog's generic
|
|
143
|
+
* vocabulary starts here (skill, read, prompt, text, build, change, agent,
|
|
144
|
+
* line); below it the words still describe work types (review, check, test,
|
|
145
|
+
* edit, documentation).
|
|
146
|
+
*
|
|
147
|
+
* Labelled set. 26 recorded prompts, recall@2 by threshold: df ≥ 4 → 12/23,
|
|
148
|
+
* df ≥ 5 → 13/23, df ≥ 6 → 13/23, df ≥ 7 → 14/23, no gate at all → 12/23.
|
|
149
|
+
* Recall alone cannot choose the number: every step that weakens the gate
|
|
150
|
+
* admits more skills (45, 54, 67, 71, 106 admissions) and admitting more can
|
|
151
|
+
* only raise a top-2 recall figure. 5 is where the gate removes a quarter of
|
|
152
|
+
* the corpus-common mass without also deleting the work-type words that are
|
|
153
|
+
* sometimes a skill's only reachable evidence.
|
|
154
|
+
*/
|
|
155
|
+
export declare const COMMON_KEYWORD_DF = 5;
|
|
120
156
|
export interface InjectedSkill {
|
|
121
157
|
name: string;
|
|
122
158
|
turnNumber: number;
|
|
@@ -156,49 +192,95 @@ export declare function stemKeyword(word: string): string;
|
|
|
156
192
|
* bar (stemming "tasks" lands on the noise word "task", which stays out).
|
|
157
193
|
*/
|
|
158
194
|
export declare function extractKeywords(text: string): string[];
|
|
195
|
+
/**
|
|
196
|
+
* The text a skill contributes to the corpus-frequency count: its description
|
|
197
|
+
* plus its own catalog path (`<dir>/skill.md`). Deliberately NOT the absolute
|
|
198
|
+
* path: a checkout root puts its own directory names ("private", "packages",
|
|
199
|
+
* a worktree name) in every one of the 22 documents — measured at df 22 for
|
|
200
|
+
* `private`, `package`, `pack` and `core`, and different on every machine the
|
|
201
|
+
* agent runs on. On description plus the skill's own directory those four
|
|
202
|
+
* measure df 0, 1, 1 and 2; `skill` and `kill` stay catalog-wide because the
|
|
203
|
+
* file itself is named SKILL.md, and the rarity gate is what removes them.
|
|
204
|
+
* Lowercased; the matcher tests substrings. Pure.
|
|
205
|
+
*/
|
|
206
|
+
export declare function skillCorpusDocument(skill: CachedSkill): string;
|
|
207
|
+
/**
|
|
208
|
+
* Document frequency of each keyword across the cached skills: how many skill
|
|
209
|
+
* documents contain it as a substring (the test every weak leg performs).
|
|
210
|
+
* Computed once per turn from the cache, for the prompt's keywords only. Pure
|
|
211
|
+
* given the cache.
|
|
212
|
+
*/
|
|
213
|
+
export declare function corpusKeywordFrequency(keywords: string[], skills: CachedSkill[]): Map<string, number>;
|
|
214
|
+
/** One skill's match against a prompt: points, distinct signals, evidence rarity. */
|
|
215
|
+
export interface SkillMatch {
|
|
216
|
+
/** Score the qualification bar and the ranking read (same scale as before). */
|
|
217
|
+
score: number;
|
|
218
|
+
/** Distinct matched signals: each trigger phrase, each distinct keyword. */
|
|
219
|
+
signals: number;
|
|
220
|
+
/** Summed document frequency of the matched keywords — lower is rarer. */
|
|
221
|
+
evidenceDf: number;
|
|
222
|
+
}
|
|
159
223
|
/**
|
|
160
224
|
* Score a skill against a set of keywords.
|
|
161
225
|
*
|
|
162
226
|
* Scoring rules:
|
|
163
227
|
* +3 skill name contains a keyword (exact match)
|
|
164
228
|
* +2 skill name contains a keyword as substring
|
|
165
|
-
* +2 a
|
|
229
|
+
* +2 a trigger phrase occurs in the prompt (word-bounded)
|
|
166
230
|
* +1 skill description contains a keyword
|
|
167
|
-
* +1 skill
|
|
231
|
+
* +1 the skill's own catalog path contains a keyword (e.g. "research" in
|
|
232
|
+
* "research/skill.md")
|
|
168
233
|
*
|
|
169
234
|
* A trigger hit counts as a name hit: the phrase is the skill author's own
|
|
170
235
|
* relevance signal, so it qualifies the skill the same way a name match does.
|
|
171
236
|
*
|
|
237
|
+
* `keywordDf` is the corpus document frequency of the prompt's keywords (see
|
|
238
|
+
* corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
|
|
239
|
+
* nothing on the weak legs; passing no map scores every keyword at full weight
|
|
240
|
+
* (the pre-rarity behavior, which the unit fixtures pin).
|
|
241
|
+
*
|
|
172
242
|
* Qualification bar: a skill whose match never touches its NAME (description
|
|
173
243
|
* and/or filePath hits only) must reach a total score of at least
|
|
174
244
|
* MIN_NON_NAME_SCORE — one description keyword is too weak a signal and
|
|
175
245
|
* lets generic skills fire on almost any prompt. Name and trigger matches
|
|
176
246
|
* always qualify.
|
|
177
247
|
*
|
|
178
|
-
* `promptText`
|
|
179
|
-
* on our side) enables trigger matching; omit it where the raw prompt is not
|
|
248
|
+
* `promptText` enables trigger matching; omit it where the raw prompt is not
|
|
180
249
|
* available and only keyword scoring should run.
|
|
181
250
|
*
|
|
182
|
-
* Returns
|
|
251
|
+
* Returns the zero match if the skill does not qualify.
|
|
252
|
+
*/
|
|
253
|
+
export declare function matchSkill(skill: CachedSkill, keywords: string[], promptText?: string, keywordDf?: ReadonlyMap<string, number>): SkillMatch;
|
|
254
|
+
/** The score alone (see matchSkill for the rules and the rarity gate). */
|
|
255
|
+
export declare function scoreSkill(skill: CachedSkill, keywords: string[], promptText?: string, keywordDf?: ReadonlyMap<string, number>): number;
|
|
256
|
+
/**
|
|
257
|
+
* A skill with its match evidence, as the selection step consumes it. The
|
|
258
|
+
* evidence fields are optional so a caller holding only a score still selects;
|
|
259
|
+
* they then default to zero and the name stays the tie-breaker.
|
|
183
260
|
*/
|
|
184
|
-
export
|
|
261
|
+
export interface ScoredSkill {
|
|
262
|
+
skill: CachedSkill;
|
|
263
|
+
score: number;
|
|
264
|
+
signals?: number;
|
|
265
|
+
evidenceDf?: number;
|
|
266
|
+
}
|
|
185
267
|
/**
|
|
186
268
|
* Decide which scored skills to suggest given the session injection state.
|
|
187
269
|
* Pure — mirrors the handler's decision path so it can be unit-tested:
|
|
188
|
-
* sort (score desc,
|
|
189
|
-
* loaded extension) → slot budget
|
|
190
|
-
* released its slot) → top-N slice.
|
|
270
|
+
* sort (score desc, distinct signals desc, evidence df asc, name asc) →
|
|
271
|
+
* cooldown filter (global floor + per-skill loaded extension) → slot budget
|
|
272
|
+
* over ACTIVE held slots (a loaded skill released its slot) → top-N slice.
|
|
273
|
+
*
|
|
274
|
+
* The rank order is the fix for alphabetical slot allocation: two skills with
|
|
275
|
+
* equal points used to be ordered by name, so a broadly-matching skill took
|
|
276
|
+
* the slot from one whose evidence was the prompt's actual subject. Distinct
|
|
277
|
+
* signals separate breadth of match; evidence df separates a match on the
|
|
278
|
+
* prompt's distinctive words from one on its filler.
|
|
191
279
|
*
|
|
192
280
|
* Returns the chosen scored items (empty when nothing qualifies). The
|
|
193
281
|
* caller is responsible for recording the picks in session state.
|
|
194
282
|
*/
|
|
195
|
-
export declare function selectSuggestions(scored:
|
|
196
|
-
skill: CachedSkill;
|
|
197
|
-
score: number;
|
|
198
|
-
}>, injected: InjectedSkill[], currentTurn: number): Array<{
|
|
199
|
-
skill: CachedSkill;
|
|
200
|
-
score: number;
|
|
201
|
-
}>;
|
|
283
|
+
export declare function selectSuggestions(scored: ScoredSkill[], injected: InjectedSkill[], currentTurn: number): ScoredSkill[];
|
|
202
284
|
/**
|
|
203
285
|
* Strip YAML frontmatter from a SKILL.md body. Pure.
|
|
204
286
|
*
|