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
|
@@ -27,6 +27,11 @@ import { consolidatedClaimCritique } from "../../../../lib/ai/consolidated-claim
|
|
|
27
27
|
|
|
28
28
|
const log = createLogger("metacognition:claim-verification");
|
|
29
29
|
|
|
30
|
+
/** A blank string is "not provided": a client that emits every schema key sends "" for the unused ones. */
|
|
31
|
+
function optionalString(v: unknown): string | undefined {
|
|
32
|
+
return typeof v === "string" && v.trim().length > 0 ? v : undefined;
|
|
33
|
+
}
|
|
34
|
+
|
|
30
35
|
function truncate(text: string, maxLen: number): string {
|
|
31
36
|
return text.length > maxLen ? text.slice(0, maxLen) + "..." : text;
|
|
32
37
|
}
|
|
@@ -166,7 +171,9 @@ export function createVerifyClaimTool(): ToolDefinition<any, any, any> {
|
|
|
166
171
|
if (!p.claim || !Array.isArray(p.context)) {
|
|
167
172
|
throw new Error("verify_claim requires 'claim' (string) and 'context' (string array)");
|
|
168
173
|
}
|
|
169
|
-
|
|
174
|
+
// A blank claimId is no id: it would become the tracking key of every
|
|
175
|
+
// such call for the rest of the session.
|
|
176
|
+
const claimId = optionalString(p.claimId) ?? `claim-${Date.now()}`;
|
|
170
177
|
const issues: Record<string, unknown>[] = [];
|
|
171
178
|
|
|
172
179
|
// PRIMARY PATH: consolidated single-LLM-call
|
|
@@ -528,6 +528,27 @@ finalize(completed=true, summary="Fixed the bug", tasksRemaining=["write tests"]
|
|
|
528
528
|
};
|
|
529
529
|
}
|
|
530
530
|
|
|
531
|
+
// A blank summary names nothing. The `=== undefined` check above lets it
|
|
532
|
+
// through, and the summary lands in the memory episode, the session label
|
|
533
|
+
// and the deliverables manifest -- an unfindable task recorded as done.
|
|
534
|
+
if (typeof params.summary !== "string" || params.summary.trim().length === 0) {
|
|
535
|
+
return {
|
|
536
|
+
content: [
|
|
537
|
+
{
|
|
538
|
+
type: "text" as const,
|
|
539
|
+
text: `**FINALIZE REQUIRES A SUMMARY**
|
|
540
|
+
|
|
541
|
+
finalize was called with summary ${JSON.stringify(params.summary ?? null)}, which names nothing to record.
|
|
542
|
+
Provide the summary text: what was accomplished, or what is still open with completed: false.
|
|
543
|
+
|
|
544
|
+
Example:
|
|
545
|
+
finalize(completed=true, summary="Fixed the parser offset clamp", tasksRemaining=["add fixture"])`,
|
|
546
|
+
},
|
|
547
|
+
],
|
|
548
|
+
details: { finalized: false, blocked: true, error: "missing_summary" },
|
|
549
|
+
};
|
|
550
|
+
}
|
|
551
|
+
|
|
531
552
|
// Pre-flight check: verify must have passed
|
|
532
553
|
if (_ctx && !params.completed) {
|
|
533
554
|
const lastVerification = getLastVerification(_ctx);
|
|
@@ -29,6 +29,11 @@ import { BRAID_INJECTED, BRAID_SOURCE } from "../../../lib/constants/injection-d
|
|
|
29
29
|
|
|
30
30
|
const log = createLogger("topic-drift");
|
|
31
31
|
|
|
32
|
+
/** A blank string is "not provided": a client that emits every schema key sends "" for the unused ones. */
|
|
33
|
+
function optionalString(v: unknown): string | undefined {
|
|
34
|
+
return typeof v === "string" && v.trim().length > 0 ? v : undefined;
|
|
35
|
+
}
|
|
36
|
+
|
|
32
37
|
interface DriftState {
|
|
33
38
|
/** The original request text (used by critics directly - no token extraction needed). */
|
|
34
39
|
originalRequest: string;
|
|
@@ -348,7 +353,20 @@ export default function topicDriftExtension(pi: ExtensionAPI) {
|
|
|
348
353
|
switch (params?.action) {
|
|
349
354
|
case "check": {
|
|
350
355
|
const state = getExtensionState(ctx, "topic-drift", createDriftState);
|
|
351
|
-
const output = params.output
|
|
356
|
+
const output = optionalString(params.output);
|
|
357
|
+
if (output === undefined) {
|
|
358
|
+
// "" would be measured as an empty response and answered
|
|
359
|
+
// "No topic drift" -- a pass for a check that never ran.
|
|
360
|
+
return {
|
|
361
|
+
content: [
|
|
362
|
+
{
|
|
363
|
+
type: "text" as const,
|
|
364
|
+
text: `topic_drift action=check requires a non-empty 'output': the response text to test against the anchored request.`,
|
|
365
|
+
},
|
|
366
|
+
],
|
|
367
|
+
details: { error: "missing_output", action: "check" },
|
|
368
|
+
};
|
|
369
|
+
}
|
|
352
370
|
let drifted = false;
|
|
353
371
|
let similarity = 1.0;
|
|
354
372
|
let missingAnchors: string[] = [];
|
|
@@ -397,7 +415,7 @@ export default function topicDriftExtension(pi: ExtensionAPI) {
|
|
|
397
415
|
}
|
|
398
416
|
case "reset": {
|
|
399
417
|
const state = getExtensionState(ctx, "topic-drift", createDriftState);
|
|
400
|
-
const request = params.newRequest ?? state.originalRequest;
|
|
418
|
+
const request = optionalString(params.newRequest) ?? state.originalRequest;
|
|
401
419
|
resetAnchors(state, request);
|
|
402
420
|
return {
|
|
403
421
|
content: [
|
|
@@ -25,7 +25,7 @@ Every file in this folder either:
|
|
|
25
25
|
| `identity.ts` | Framing constants: `IDENTITY_INTRO` (generalist identity), `DISCOVERY` (D1 guarded exploration stance), `WORK_ETHIC` (methodical precision, signal-not-noise), `REPAIR_DISCIPLINE` (root cause named falsifiably before repair; re-derivation of claims that are not yours; weighted repair decisions), `SELF_MANAGEMENT` (memory workspace, evidence-carrying done items, known-open-check done gate), `COMMUNICATION` (conclusion-first, output style), `EPISTEMIC_STANCE` (identity-core: claim gate, self-state gate, retrieved-context preference), `SELF_AUDIT` (symmetric doubt; handoff ends with the unverified), `PHILOSOPHY` (character-level stance - silence, calm strategist, precise self-irony). |
|
|
26
26
|
| `surface-discipline-section.ts` | `SURFACE_DISCIPLINE` (signal discipline across code, commits, tests, docs, reports, logs) + `surfaceDisciplineSection()` - its own section, rendered between the identity and identity-core blocks. Text pinned verbatim by test-prompt-budget.mjs. |
|
|
27
27
|
| `instance-composition.ts` | **v3.8** Instance (consolidated): agent identity + pi-core version + root (pi-core npm package folder) + cwd + userland settings dir + os/pid + session (id + elapsed/last-event/turns/tool-avg) + top-level pi extension packages (settings-driven, scope-tagged `project` or `user-global`). Full block rendered on demand via the `system_info` tool; the prompt carries only the compact orientation line. |
|
|
28
|
-
| `top-level-extensions.ts` | **v3.8** Discovery logic for top-level pi extension PACKAGES. Reads pi-core's `packages` field from `<cwd>/.pi/settings.json` (project) and `~/.pi/agent/settings.json` (user-global); project wins on collision. Resolves `npm:` specs
|
|
28
|
+
| `top-level-extensions.ts` | **v3.8** Discovery logic for top-level pi extension PACKAGES. Reads pi-core's `packages` field from `<cwd>/.pi/settings.json` (project) and `~/.pi/agent/settings.json` (user-global); project wins on collision. Resolves `npm:` specs in pi's managed install tree (`<agentDir>/npm/node_modules`) first, falling back to the global npm root (`npm root -g`); resolves local paths in place. Source tags: `project` / `user-global`. |
|
|
29
29
|
| `project-docs-section.ts` | Project docs (AGENTS.md / CLAUDE.md) pointer-only rendering as plain-text bullets (`- <basename> at <path>`). Mirrors the skills discoverability model but uses plain text (no XML tags) so the system prompt stays prose. Includes fingerprint cache and `RESOURCES_DISCOVER` invalidation. |
|
|
30
30
|
| `memory-section.ts` | Memory store pointer block (episodes + semantic + heuristics) as plain-text bullets (`- episodes at PATH`; count-free - per-store counts go stale at print time and are not rendered). Mirrors project-docs. Cached per session (static content, no fingerprint needed); invalidated on `RESOURCES_DISCOVER`. |
|
|
31
31
|
| `context-section.ts` | **v3.6** body fragment for the unified context block: context %, session health, steps-since-checkpoint. Returns `""` when nothing to surface. Composer (`index.ts`) joins this with project-docs and memory bodies. No heading. (Memory stores render pointer-only: per-store entry counts are not rendered; the whisper carries token counts, not memory counts.) |
|
|
@@ -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
|
*/
|
|
@@ -137,8 +138,9 @@ function basename(p: string): string {
|
|
|
137
138
|
* source is unsupported or cannot be located on disk.
|
|
138
139
|
*
|
|
139
140
|
* Supported shapes:
|
|
140
|
-
* - `npm:<spec>` (e.g. `npm:pi-web-access`) -- looks in
|
|
141
|
-
*
|
|
141
|
+
* - `npm:<spec>` (e.g. `npm:pi-web-access`) -- looks in pi's
|
|
142
|
+
* managed install tree, then the global npm root, under each
|
|
143
|
+
* scoped directory.
|
|
142
144
|
* - absolute local path (starts with `/`) -- used as-is.
|
|
143
145
|
* - relative local path -- resolved relative to `cwd`.
|
|
144
146
|
*/
|
|
@@ -150,7 +152,7 @@ function resolveEntryToPackage(
|
|
|
150
152
|
const trimmed = source.trim();
|
|
151
153
|
if (!trimmed) return null;
|
|
152
154
|
|
|
153
|
-
// npm:<spec> -- find in global node_modules.
|
|
155
|
+
// npm:<spec> -- find in the managed install tree, then global node_modules.
|
|
154
156
|
if (trimmed.startsWith("npm:")) {
|
|
155
157
|
const spec = trimmed.slice("npm:".length).trim();
|
|
156
158
|
const at = spec.lastIndexOf("@");
|
|
@@ -195,34 +197,73 @@ function expandHome(p: string): string {
|
|
|
195
197
|
}
|
|
196
198
|
|
|
197
199
|
/**
|
|
198
|
-
*
|
|
199
|
-
*
|
|
200
|
-
*
|
|
201
|
-
*
|
|
200
|
+
* Resolve pi's agent directory. `PI_CODING_AGENT_DIR` relocates the whole
|
|
201
|
+
* agent home when set and non-empty; otherwise the default is `~/.pi/agent`.
|
|
202
|
+
* Both the user-global settings file and the managed npm install tree live
|
|
203
|
+
* under this one directory, so they are resolved from this one function.
|
|
204
|
+
*/
|
|
205
|
+
function resolveAgentDir(): string {
|
|
206
|
+
const override = process.env.PI_CODING_AGENT_DIR?.trim();
|
|
207
|
+
if (override) return expandHome(override);
|
|
208
|
+
return join(process.env.HOME ?? "~", ".pi", "agent");
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
/**
|
|
212
|
+
* Locate an installed npm package by name, searching pi's managed install
|
|
213
|
+
* tree before the global npm root. Managed first because that is where pi
|
|
214
|
+
* installs a settings-declared `npm:` entry (`<agentDir>/npm/node_modules`)
|
|
215
|
+
* and it consults a legacy global install only when the managed copy is
|
|
216
|
+
* absent -- so the managed copy is the one pi actually loads. The global
|
|
217
|
+
* root stays as that same fallback, for packages installed by hand.
|
|
202
218
|
*
|
|
203
|
-
*
|
|
219
|
+
* Optional `version` filters to a directory whose `package.json` version
|
|
220
|
+
* matches; if absent, the first matching directory wins. Returns the
|
|
221
|
+
* absolute directory path, or null if not found in any root.
|
|
204
222
|
*/
|
|
205
223
|
function findNpmPackageDir(name: string, version: string | undefined): string | null {
|
|
224
|
+
for (const root of getNpmSearchRoots()) {
|
|
225
|
+
const dir = findPackageInNpmRoot(root, name, version);
|
|
226
|
+
if (dir) return dir;
|
|
227
|
+
}
|
|
228
|
+
return null;
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/** The npm roots searched for an `npm:` entry, in precedence order. */
|
|
232
|
+
function getNpmSearchRoots(): string[] {
|
|
233
|
+
const roots = [join(resolveAgentDir(), "npm", "node_modules")];
|
|
206
234
|
const globalRoot = getGlobalNpmRoot();
|
|
207
|
-
if (
|
|
208
|
-
|
|
235
|
+
if (globalRoot) roots.push(globalRoot);
|
|
236
|
+
return roots;
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/**
|
|
240
|
+
* Find the package directory for `name` inside one npm root.
|
|
241
|
+
*
|
|
242
|
+
* Scoped package: @scope/name -> look directly under `<root>/@scope/name`.
|
|
243
|
+
* Unscoped: scan the root's own directories for a package.json whose `name`
|
|
244
|
+
* matches -- npm installs both flat and nested layouts. A directory with no
|
|
245
|
+
* readable package.json is skipped, never fatal.
|
|
246
|
+
*/
|
|
247
|
+
function findPackageInNpmRoot(
|
|
248
|
+
root: string,
|
|
249
|
+
name: string,
|
|
250
|
+
version: string | undefined,
|
|
251
|
+
): string | null {
|
|
252
|
+
if (!existsSync(root)) return null;
|
|
209
253
|
|
|
210
|
-
// Scoped package: @scope/name -> look under globalRoot/@scope/name.
|
|
211
254
|
if (name.startsWith("@")) {
|
|
212
|
-
const dir = join(
|
|
255
|
+
const dir = join(root, name);
|
|
213
256
|
return packageDirMatches(dir, version) ? dir : null;
|
|
214
257
|
}
|
|
215
258
|
|
|
216
|
-
// Unscoped: scan globalRoot itself for a directory whose
|
|
217
|
-
// package.json `name` matches. npm installs both flat and nested layouts.
|
|
218
259
|
let entries: string[];
|
|
219
260
|
try {
|
|
220
|
-
entries = readdirSync(
|
|
261
|
+
entries = readdirSync(root);
|
|
221
262
|
} catch {
|
|
222
263
|
return null;
|
|
223
264
|
}
|
|
224
265
|
for (const entry of entries) {
|
|
225
|
-
const dir = join(
|
|
266
|
+
const dir = join(root, entry);
|
|
226
267
|
let isDir: boolean;
|
|
227
268
|
try {
|
|
228
269
|
isDir = statSync(dir).isDirectory();
|
|
@@ -259,10 +300,11 @@ function packageDirMatches(dir: string, expectedVersion?: string, expectedName?:
|
|
|
259
300
|
|
|
260
301
|
/**
|
|
261
302
|
* Resolve the global npm root via `npm root -g`. Returns null if
|
|
262
|
-
* the command fails or produces no output.
|
|
263
|
-
*
|
|
264
|
-
*
|
|
265
|
-
*
|
|
303
|
+
* the command fails or produces no output. This is the fallback root
|
|
304
|
+
* only -- pi's managed install tree is searched first (see
|
|
305
|
+
* `findNpmPackageDir`). Cached after first successful call so the
|
|
306
|
+
* (slow) `npm root -g` invocation runs at most once per process --
|
|
307
|
+
* the value never changes inside one pi session.
|
|
266
308
|
*
|
|
267
309
|
* Implemented as an IIFE-wrapped closure so the cache `let`
|
|
268
310
|
* stays function-scoped (the project's no-module-level-let
|
|
@@ -297,8 +339,8 @@ const getGlobalNpmRoot = ((): (() => string | null) => {
|
|
|
297
339
|
*
|
|
298
340
|
* Settings-file paths:
|
|
299
341
|
* - project: `<cwd>/.pi/settings.json`
|
|
300
|
-
* - user-global:
|
|
301
|
-
*
|
|
342
|
+
* - user-global: `<agentDir>/settings.json`, where the agent dir is
|
|
343
|
+
* `PI_CODING_AGENT_DIR` when set, else `~/.pi/agent`.
|
|
302
344
|
*/
|
|
303
345
|
export function discoverTopLevelExtensions(
|
|
304
346
|
cwd: string = process.cwd(),
|
|
@@ -308,10 +350,7 @@ export function discoverTopLevelExtensions(
|
|
|
308
350
|
},
|
|
309
351
|
): TopLevelExtension[] {
|
|
310
352
|
const projectPath = options?.projectSettingsPath ?? join(cwd, ".pi", "settings.json");
|
|
311
|
-
const userPath =
|
|
312
|
-
options?.userSettingsPath ??
|
|
313
|
-
process.env.PI_CODING_AGENT_DIR ??
|
|
314
|
-
join(process.env.HOME ?? "~", ".pi", "agent", "settings.json");
|
|
353
|
+
const userPath = options?.userSettingsPath ?? join(resolveAgentDir(), "settings.json");
|
|
315
354
|
|
|
316
355
|
const seen = new Set<string>();
|
|
317
356
|
const out: ResolvedPackage[] = [];
|
|
@@ -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
|
|
@@ -145,6 +155,33 @@ export const MAX_EXCERPT_CHARS = 300;
|
|
|
145
155
|
*/
|
|
146
156
|
export const MIN_NON_NAME_SCORE = 2;
|
|
147
157
|
|
|
158
|
+
/**
|
|
159
|
+
* A keyword present in this many skill documents or more is corpus-common: it
|
|
160
|
+
* appears in a large share of the catalog (5 of 22 skills = 23%), so it cannot
|
|
161
|
+
* distinguish one skill from another and contributes NOTHING to the weak legs
|
|
162
|
+
* (description, catalog path).
|
|
163
|
+
*
|
|
164
|
+
* The number is measured, not guessed. Two measurements, one threshold:
|
|
165
|
+
*
|
|
166
|
+
* Corpus mass. Over 400 recorded prompts against the 22-skill catalog, the
|
|
167
|
+
* weak-leg points awarded to words by document frequency are df1 17.0%,
|
|
168
|
+
* df2 22.4%, df3 20.9%, df4 13.3%, df5 7.8%, df6 4.1%, df7 9.1%, df9 0.4%,
|
|
169
|
+
* df22 5.1%. Words at df ≥ 5 carry 26.4% of every weak-leg point the matcher
|
|
170
|
+
* awards; df ≥ 4 carries 39.7%, df ≥ 6 carries 18.6%. The catalog's generic
|
|
171
|
+
* vocabulary starts here (skill, read, prompt, text, build, change, agent,
|
|
172
|
+
* line); below it the words still describe work types (review, check, test,
|
|
173
|
+
* edit, documentation).
|
|
174
|
+
*
|
|
175
|
+
* Labelled set. 26 recorded prompts, recall@2 by threshold: df ≥ 4 → 12/23,
|
|
176
|
+
* df ≥ 5 → 13/23, df ≥ 6 → 13/23, df ≥ 7 → 14/23, no gate at all → 12/23.
|
|
177
|
+
* Recall alone cannot choose the number: every step that weakens the gate
|
|
178
|
+
* admits more skills (45, 54, 67, 71, 106 admissions) and admitting more can
|
|
179
|
+
* only raise a top-2 recall figure. 5 is where the gate removes a quarter of
|
|
180
|
+
* the corpus-common mass without also deleting the work-type words that are
|
|
181
|
+
* sometimes a skill's only reachable evidence.
|
|
182
|
+
*/
|
|
183
|
+
export const COMMON_KEYWORD_DF = 5;
|
|
184
|
+
|
|
148
185
|
/**
|
|
149
186
|
* Common English words to exclude from keyword matching.
|
|
150
187
|
* Kept small — only the most frequent noise words that would
|
|
@@ -296,92 +333,202 @@ export function extractKeywords(text: string): string[] {
|
|
|
296
333
|
|
|
297
334
|
// Relevance Scoring
|
|
298
335
|
|
|
336
|
+
/**
|
|
337
|
+
* The text a skill contributes to the corpus-frequency count: its description
|
|
338
|
+
* plus its own catalog path (`<dir>/skill.md`). Deliberately NOT the absolute
|
|
339
|
+
* path: a checkout root puts its own directory names ("private", "packages",
|
|
340
|
+
* a worktree name) in every one of the 22 documents — measured at df 22 for
|
|
341
|
+
* `private`, `package`, `pack` and `core`, and different on every machine the
|
|
342
|
+
* agent runs on. On description plus the skill's own directory those four
|
|
343
|
+
* measure df 0, 1, 1 and 2; `skill` and `kill` stay catalog-wide because the
|
|
344
|
+
* file itself is named SKILL.md, and the rarity gate is what removes them.
|
|
345
|
+
* Lowercased; the matcher tests substrings. Pure.
|
|
346
|
+
*/
|
|
347
|
+
export function skillCorpusDocument(skill: CachedSkill): string {
|
|
348
|
+
const tail = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
|
|
349
|
+
return `${skill.description.toLowerCase()} ${tail}`;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* Document frequency of each keyword across the cached skills: how many skill
|
|
354
|
+
* documents contain it as a substring (the test every weak leg performs).
|
|
355
|
+
* Computed once per turn from the cache, for the prompt's keywords only. Pure
|
|
356
|
+
* given the cache.
|
|
357
|
+
*/
|
|
358
|
+
export function corpusKeywordFrequency(
|
|
359
|
+
keywords: string[],
|
|
360
|
+
skills: CachedSkill[],
|
|
361
|
+
): Map<string, number> {
|
|
362
|
+
const docs = skills.map(skillCorpusDocument);
|
|
363
|
+
const freq = new Map<string, number>();
|
|
364
|
+
for (const kw of keywords) {
|
|
365
|
+
let n = 0;
|
|
366
|
+
for (const doc of docs) if (doc.includes(kw)) n++;
|
|
367
|
+
freq.set(kw, n);
|
|
368
|
+
}
|
|
369
|
+
return freq;
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
/** One skill's match against a prompt: points, distinct signals, evidence rarity. */
|
|
373
|
+
export interface SkillMatch {
|
|
374
|
+
/** Score the qualification bar and the ranking read (same scale as before). */
|
|
375
|
+
score: number;
|
|
376
|
+
/** Distinct matched signals: each trigger phrase, each distinct keyword. */
|
|
377
|
+
signals: number;
|
|
378
|
+
/** Summed document frequency of the matched keywords — lower is rarer. */
|
|
379
|
+
evidenceDf: number;
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
const NO_MATCH: SkillMatch = { score: 0, signals: 0, evidenceDf: 0 };
|
|
383
|
+
|
|
299
384
|
/**
|
|
300
385
|
* Score a skill against a set of keywords.
|
|
301
386
|
*
|
|
302
387
|
* Scoring rules:
|
|
303
388
|
* +3 skill name contains a keyword (exact match)
|
|
304
389
|
* +2 skill name contains a keyword as substring
|
|
305
|
-
* +2 a
|
|
390
|
+
* +2 a trigger phrase occurs in the prompt (word-bounded)
|
|
306
391
|
* +1 skill description contains a keyword
|
|
307
|
-
* +1 skill
|
|
392
|
+
* +1 the skill's own catalog path contains a keyword (e.g. "research" in
|
|
393
|
+
* "research/skill.md")
|
|
308
394
|
*
|
|
309
395
|
* A trigger hit counts as a name hit: the phrase is the skill author's own
|
|
310
396
|
* relevance signal, so it qualifies the skill the same way a name match does.
|
|
311
397
|
*
|
|
398
|
+
* `keywordDf` is the corpus document frequency of the prompt's keywords (see
|
|
399
|
+
* corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
|
|
400
|
+
* nothing on the weak legs; passing no map scores every keyword at full weight
|
|
401
|
+
* (the pre-rarity behavior, which the unit fixtures pin).
|
|
402
|
+
*
|
|
312
403
|
* Qualification bar: a skill whose match never touches its NAME (description
|
|
313
404
|
* and/or filePath hits only) must reach a total score of at least
|
|
314
405
|
* MIN_NON_NAME_SCORE — one description keyword is too weak a signal and
|
|
315
406
|
* lets generic skills fire on almost any prompt. Name and trigger matches
|
|
316
407
|
* always qualify.
|
|
317
408
|
*
|
|
318
|
-
* `promptText`
|
|
319
|
-
* on our side) enables trigger matching; omit it where the raw prompt is not
|
|
409
|
+
* `promptText` enables trigger matching; omit it where the raw prompt is not
|
|
320
410
|
* available and only keyword scoring should run.
|
|
321
411
|
*
|
|
322
|
-
* Returns
|
|
412
|
+
* Returns the zero match if the skill does not qualify.
|
|
323
413
|
*/
|
|
324
|
-
export function
|
|
414
|
+
export function matchSkill(
|
|
415
|
+
skill: CachedSkill,
|
|
416
|
+
keywords: string[],
|
|
417
|
+
promptText?: string,
|
|
418
|
+
keywordDf?: ReadonlyMap<string, number>,
|
|
419
|
+
): SkillMatch {
|
|
325
420
|
let score = 0;
|
|
421
|
+
let signals = 0;
|
|
422
|
+
let evidenceDf = 0;
|
|
326
423
|
let nameHit = false;
|
|
327
424
|
const name = skill.name.toLowerCase();
|
|
328
425
|
const desc = skill.description.toLowerCase();
|
|
329
|
-
const path = skill.filePath.toLowerCase();
|
|
426
|
+
const path = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
|
|
427
|
+
const dfOf = (kw: string) => keywordDf?.get(kw) ?? 0;
|
|
330
428
|
|
|
331
429
|
for (const trig of skill.triggers ?? []) {
|
|
332
430
|
if (triggerMatches(trig, promptText ?? "")) {
|
|
333
431
|
score += 2;
|
|
432
|
+
signals++;
|
|
334
433
|
nameHit = true;
|
|
434
|
+
// A curated phrase is the rarest evidence a skill can offer: df 0.
|
|
335
435
|
}
|
|
336
436
|
}
|
|
337
437
|
|
|
338
438
|
for (const kw of keywords) {
|
|
439
|
+
const df = dfOf(kw);
|
|
339
440
|
// Exact token match in name
|
|
340
441
|
if (name.split(/[^a-z0-9]+/).includes(kw)) {
|
|
341
442
|
score += 3;
|
|
443
|
+
signals++;
|
|
342
444
|
nameHit = true;
|
|
445
|
+
evidenceDf += df;
|
|
343
446
|
continue;
|
|
344
447
|
}
|
|
345
448
|
// Substring match in name (catches compound names like "code-search")
|
|
346
449
|
if (name.includes(kw)) {
|
|
347
450
|
score += 2;
|
|
451
|
+
signals++;
|
|
348
452
|
nameHit = true;
|
|
453
|
+
evidenceDf += df;
|
|
349
454
|
continue;
|
|
350
455
|
}
|
|
351
|
-
//
|
|
456
|
+
// Corpus-common keyword: the weak legs score nothing for it, so a prompt
|
|
457
|
+
// full of generic vocabulary cannot buy a slot.
|
|
458
|
+
if (df >= COMMON_KEYWORD_DF) continue;
|
|
459
|
+
let weakHit = false;
|
|
352
460
|
if (desc.includes(kw)) {
|
|
353
461
|
score += 1;
|
|
354
|
-
|
|
462
|
+
weakHit = true;
|
|
355
463
|
}
|
|
356
464
|
// File path matches (e.g. "research" in "research/SKILL.md")
|
|
357
465
|
if (path.includes(kw)) {
|
|
358
466
|
score += 1;
|
|
467
|
+
weakHit = true;
|
|
468
|
+
}
|
|
469
|
+
// One signal per distinct keyword: a word present in both the description
|
|
470
|
+
// and the path is one piece of evidence, not two.
|
|
471
|
+
if (weakHit) {
|
|
472
|
+
signals++;
|
|
473
|
+
evidenceDf += df;
|
|
359
474
|
}
|
|
360
475
|
}
|
|
361
476
|
|
|
362
|
-
if (!nameHit && score < MIN_NON_NAME_SCORE) return
|
|
363
|
-
return score;
|
|
477
|
+
if (!nameHit && score < MIN_NON_NAME_SCORE) return NO_MATCH;
|
|
478
|
+
return { score, signals, evidenceDf };
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
/** The score alone (see matchSkill for the rules and the rarity gate). */
|
|
482
|
+
export function scoreSkill(
|
|
483
|
+
skill: CachedSkill,
|
|
484
|
+
keywords: string[],
|
|
485
|
+
promptText?: string,
|
|
486
|
+
keywordDf?: ReadonlyMap<string, number>,
|
|
487
|
+
): number {
|
|
488
|
+
return matchSkill(skill, keywords, promptText, keywordDf).score;
|
|
489
|
+
}
|
|
490
|
+
|
|
491
|
+
/**
|
|
492
|
+
* A skill with its match evidence, as the selection step consumes it. The
|
|
493
|
+
* evidence fields are optional so a caller holding only a score still selects;
|
|
494
|
+
* they then default to zero and the name stays the tie-breaker.
|
|
495
|
+
*/
|
|
496
|
+
export interface ScoredSkill {
|
|
497
|
+
skill: CachedSkill;
|
|
498
|
+
score: number;
|
|
499
|
+
signals?: number;
|
|
500
|
+
evidenceDf?: number;
|
|
364
501
|
}
|
|
365
502
|
|
|
366
503
|
/**
|
|
367
504
|
* Decide which scored skills to suggest given the session injection state.
|
|
368
505
|
* Pure — mirrors the handler's decision path so it can be unit-tested:
|
|
369
|
-
* sort (score desc,
|
|
370
|
-
* loaded extension) → slot budget
|
|
371
|
-
* released its slot) → top-N slice.
|
|
506
|
+
* sort (score desc, distinct signals desc, evidence df asc, name asc) →
|
|
507
|
+
* cooldown filter (global floor + per-skill loaded extension) → slot budget
|
|
508
|
+
* over ACTIVE held slots (a loaded skill released its slot) → top-N slice.
|
|
509
|
+
*
|
|
510
|
+
* The rank order is the fix for alphabetical slot allocation: two skills with
|
|
511
|
+
* equal points used to be ordered by name, so a broadly-matching skill took
|
|
512
|
+
* the slot from one whose evidence was the prompt's actual subject. Distinct
|
|
513
|
+
* signals separate breadth of match; evidence df separates a match on the
|
|
514
|
+
* prompt's distinctive words from one on its filler.
|
|
372
515
|
*
|
|
373
516
|
* Returns the chosen scored items (empty when nothing qualifies). The
|
|
374
517
|
* caller is responsible for recording the picks in session state.
|
|
375
518
|
*/
|
|
376
519
|
export function selectSuggestions(
|
|
377
|
-
scored:
|
|
520
|
+
scored: ScoredSkill[],
|
|
378
521
|
injected: InjectedSkill[],
|
|
379
522
|
currentTurn: number,
|
|
380
|
-
):
|
|
523
|
+
): ScoredSkill[] {
|
|
381
524
|
if (!scored.length) return [];
|
|
382
525
|
|
|
383
526
|
const sorted = [...scored].sort(
|
|
384
|
-
(a, b) =>
|
|
527
|
+
(a, b) =>
|
|
528
|
+
b.score - a.score ||
|
|
529
|
+
(b.signals ?? 0) - (a.signals ?? 0) ||
|
|
530
|
+
(a.evidenceDf ?? 0) - (b.evidenceDf ?? 0) ||
|
|
531
|
+
a.skill.name.localeCompare(b.skill.name),
|
|
385
532
|
);
|
|
386
533
|
|
|
387
534
|
const available = sorted.filter((s) => !onCooldown(s.skill.name, injected, currentTurn));
|
|
@@ -928,9 +1075,13 @@ export function registerAutoInject(pi: ExtensionAPI): void {
|
|
|
928
1075
|
return; // No significant keywords to match
|
|
929
1076
|
}
|
|
930
1077
|
|
|
1078
|
+
// Corpus-common words cannot tell skills apart. Their document frequency
|
|
1079
|
+
// is measured once per turn from the same cache the scorer reads.
|
|
1080
|
+
const keywordDf = corpusKeywordFrequency(keywords, skills);
|
|
1081
|
+
|
|
931
1082
|
// Score each skill. The raw prompt rides along for trigger matching.
|
|
932
1083
|
const scored = skills
|
|
933
|
-
.map((s) => ({ skill: s,
|
|
1084
|
+
.map((s) => ({ skill: s, ...matchSkill(s, keywords, prompt, keywordDf) }))
|
|
934
1085
|
.filter((s) => s.score > 0);
|
|
935
1086
|
|
|
936
1087
|
if (!scored.length) {
|