pi-braid 0.41.2 → 0.42.1
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 +1006 -0
- package/build-info.json +4 -4
- package/dist/extensions/cognitive/metacognition/handlers/think.js +9 -0
- package/dist/extensions/core/prompt-builder/index.js +10 -11
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +17 -2
- package/dist/extensions/core/skills-tool/auto-inject.js +100 -24
- package/dist/extensions/core/skills-tool/index.js +47 -26
- package/dist/extensions/core/skills-tool/loading-guidance.d.ts +149 -28
- package/dist/extensions/core/skills-tool/loading-guidance.js +257 -29
- package/dist/extensions/manifest.js +6 -0
- package/dist/extensions/self/path-miss/detect.d.ts +30 -0
- package/dist/extensions/self/path-miss/detect.js +67 -0
- package/dist/extensions/self/path-miss/index.d.ts +33 -0
- package/dist/extensions/self/path-miss/index.js +118 -0
- package/dist/lib/core/event-names.d.ts +1 -0
- package/dist/lib/core/event-names.js +1 -0
- package/dist/lib/utils/argument-report.d.ts +41 -0
- package/dist/lib/utils/argument-report.js +95 -0
- package/package.json +4 -3
- package/src/extensions/cognitive/metacognition/handlers/think.ts +9 -0
- package/src/extensions/core/AGENTS.md +8 -6
- package/src/extensions/core/prompt-builder/AGENTS.md +2 -2
- package/src/extensions/core/prompt-builder/index.ts +10 -14
- package/src/extensions/core/skills-tool/auto-inject.ts +138 -26
- package/src/extensions/core/skills-tool/index.ts +60 -37
- package/src/extensions/core/skills-tool/loading-guidance.ts +303 -29
- package/src/extensions/manifest.ts +6 -0
- package/src/extensions/self/AGENTS.md +2 -1
- package/src/extensions/self/path-miss/AGENTS.md +39 -0
- package/src/extensions/self/path-miss/detect.ts +78 -0
- package/src/extensions/self/path-miss/index.ts +135 -0
- package/src/lib/core/event-names.ts +1 -0
- package/src/lib/utils/AGENTS.md +1 -0
- package/src/lib/utils/argument-report.ts +105 -0
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.42.1",
|
|
4
|
+
"sha": "b16fdbb3b1f434c2807942412b899a9ca674cfe2",
|
|
5
|
+
"shaShort": "b16fdbb",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-10-
|
|
8
|
+
"packedAt": "2026-10-27T11:16:21.651Z"
|
|
9
9
|
}
|
|
@@ -5,6 +5,7 @@ import { Type } from "typebox";
|
|
|
5
5
|
import { resolveUtilityModel, tryModelChain } from "../../../../lib/ai/model-resolver.js";
|
|
6
6
|
import { estimateComplexity, complexityToDepth, getBudget, getCalibrationStats, computeCalibrationError, THINK_TYPES, DEFAULT_THINK_TYPE, DEPTH_LEVELS, } from "./think-budget.js";
|
|
7
7
|
import { criticGate } from "../../../../lib/ai/critic-gate.js";
|
|
8
|
+
import { checkArgumentValues } from "../../../../lib/utils/argument-report.js";
|
|
8
9
|
import { getExtensionState } from "../../../../lib/state/extension-state.js";
|
|
9
10
|
import { createLogger } from "../../../../lib/core/logger.js";
|
|
10
11
|
const log = createLogger("metacognition");
|
|
@@ -128,6 +129,14 @@ export function createThinkTool() {
|
|
|
128
129
|
description: "Think deeply with structured reasoning before making high-stakes decisions.",
|
|
129
130
|
promptSnippet: "Think deeply with structured reasoning before decisions",
|
|
130
131
|
parameters: thinkSchema,
|
|
132
|
+
// pi validates arguments before `execute` is reached, and its own refusal
|
|
133
|
+
// for a guessed enum or a missing field names neither. This hook runs
|
|
134
|
+
// first, inside the same guarded block, and refuses with the values the
|
|
135
|
+
// schema above already declares.
|
|
136
|
+
prepareArguments: (args) => {
|
|
137
|
+
checkArgumentValues("think", thinkSchema, args);
|
|
138
|
+
return args;
|
|
139
|
+
},
|
|
131
140
|
execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
|
|
132
141
|
const observation = params.observation ?? params.decision ?? "";
|
|
133
142
|
const decision = params.decision ?? "";
|
|
@@ -19,7 +19,8 @@ import { IDENTITY_INTRO, DISCOVERY, WORK_ETHIC, REPAIR_DISCIPLINE, SELF_MANAGEME
|
|
|
19
19
|
import { surfaceDisciplineSection } from "./surface-discipline-section.js";
|
|
20
20
|
import { skillsLoadingText } from "../skills-tool/loading-guidance.js";
|
|
21
21
|
import { reconstructProjectDocsSection, resetProjectDocsSectionCache, } from "./project-docs-section.js";
|
|
22
|
-
import { setCachedSkills
|
|
22
|
+
import { setCachedSkills } from "../skills-tool/index.js";
|
|
23
|
+
import { getCachedVisibleSkills } from "../skills-tool/auto-inject.js";
|
|
23
24
|
import { reconstructMemorySection, resetMemorySectionCache } from "./memory-section.js";
|
|
24
25
|
import { gatherInstanceData, renderCompactInstance } from "./instance-composition.js";
|
|
25
26
|
import { sendTrackedMessage } from "../../../lib/utils/injection-tracker.js";
|
|
@@ -431,18 +432,16 @@ export default function promptBuilderExtension(pi) {
|
|
|
431
432
|
identitySection(),
|
|
432
433
|
surfaceDisciplineSection(),
|
|
433
434
|
simpleSection("identity-core", [EPISTEMIC_STANCE, SELF_AUDIT, PHILOSOPHY].join("\n\n")),
|
|
434
|
-
// 2. Skills
|
|
435
|
+
// 2. Skills floor (before guidelines, before tools).
|
|
435
436
|
// Owned by the skills-tool module (loading-guidance.ts) and rendered
|
|
436
|
-
// here
|
|
437
|
-
//
|
|
438
|
-
//
|
|
439
|
-
//
|
|
440
|
-
//
|
|
441
|
-
//
|
|
437
|
+
// here: the visible catalog itself, one row per skill, plus the
|
|
438
|
+
// read rule and the mechanical trigger. Guarded by read AND
|
|
439
|
+
// list_skills availability — the rule instructs a full-file read and
|
|
440
|
+
// the trigger names the catalog, so both tools must be present. The
|
|
441
|
+
// rows and the read root come from the live cache (setCachedSkills
|
|
442
|
+
// above); an empty catalog renders no section at all.
|
|
442
443
|
...(hasRead && hasListSkills
|
|
443
|
-
? [
|
|
444
|
-
simpleSection("skills-loading", skillsLoadingText(toolNames, getCachedVisibleSkillNames())),
|
|
445
|
-
]
|
|
444
|
+
? [simpleSection("skills-loading", skillsLoadingText(toolNames, getCachedVisibleSkills()))]
|
|
446
445
|
: []),
|
|
447
446
|
// 3. Guidelines (before tools, pi-core native pattern).
|
|
448
447
|
// Order: file tools → communication → context navigation.
|
|
@@ -88,6 +88,13 @@
|
|
|
88
88
|
* and surfaces the state through skill_stats instead of mutating the
|
|
89
89
|
* transcript.
|
|
90
90
|
* 9. Best-effort: failures are non-fatal, logged at debug level.
|
|
91
|
+
* 10. Drift trigger: the visible catalog in the prompt is a snapshot of the
|
|
92
|
+
* work's directory, not of the session. When the path-taking tools
|
|
93
|
+
* accumulate entries in a new work area, one steer line re-points at the
|
|
94
|
+
* catalog (at most DRIFT_MAX_FIRES a session, DRIFT_WINDOW_CALLS apart,
|
|
95
|
+
* and never within that window of a suggestion or a SKILL.md read). The
|
|
96
|
+
* rule and its bounds live in loading-guidance.ts beside the floor text
|
|
97
|
+
* the line points at; this module only wires them to tool results.
|
|
91
98
|
*
|
|
92
99
|
* Structure matches the existing steer whisper pattern used by topic-drift,
|
|
93
100
|
* turn-outcome, compaction-retry, context-lifecycle, and others.
|
|
@@ -99,6 +106,7 @@
|
|
|
99
106
|
*/
|
|
100
107
|
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
101
108
|
import type { TriggerSource } from "./skill-triggers.js";
|
|
109
|
+
import type { CatalogEntry } from "./loading-guidance.js";
|
|
102
110
|
/**
|
|
103
111
|
* Max skill suggestions holding a slot at any time.
|
|
104
112
|
*
|
|
@@ -184,6 +192,13 @@ export interface CachedSkill {
|
|
|
184
192
|
}
|
|
185
193
|
/** Called by index.ts's setCachedSkills to keep the auto-inject cache in sync. */
|
|
186
194
|
export declare function updateSkillCache(skills: CachedSkill[]): void;
|
|
195
|
+
/**
|
|
196
|
+
* The visible catalog as the prompt floor renders it (see loading-guidance.ts):
|
|
197
|
+
* every cached skill model selection may route to, with the description and
|
|
198
|
+
* path the row needs. Read from this module because the cache lives here; the
|
|
199
|
+
* floor's read root is derived from the paths, never hardcoded.
|
|
200
|
+
*/
|
|
201
|
+
export declare function getCachedVisibleSkills(): CatalogEntry[];
|
|
187
202
|
/**
|
|
188
203
|
* One-rule stemmer: strip a trailing plural s/es so "skills" matches the
|
|
189
204
|
* "skill" name token. Kept deliberately crude — one suffix rule, no
|
|
@@ -483,8 +498,8 @@ interface DiscoveryState {
|
|
|
483
498
|
*/
|
|
484
499
|
export declare function resolveDiscoveryMode(ctx: ExtensionContext): DiscoveryState;
|
|
485
500
|
/**
|
|
486
|
-
* Register the auto-inject handler on before_agent_start
|
|
487
|
-
*
|
|
501
|
+
* Register the auto-inject handler on before_agent_start, the read-tool load
|
|
502
|
+
* detector and the drift trigger on tool_result.
|
|
488
503
|
*
|
|
489
504
|
* Call this from the skills-tool extension factory, after registering
|
|
490
505
|
* the list_skills tool.
|
|
@@ -88,6 +88,13 @@
|
|
|
88
88
|
* and surfaces the state through skill_stats instead of mutating the
|
|
89
89
|
* transcript.
|
|
90
90
|
* 9. Best-effort: failures are non-fatal, logged at debug level.
|
|
91
|
+
* 10. Drift trigger: the visible catalog in the prompt is a snapshot of the
|
|
92
|
+
* work's directory, not of the session. When the path-taking tools
|
|
93
|
+
* accumulate entries in a new work area, one steer line re-points at the
|
|
94
|
+
* catalog (at most DRIFT_MAX_FIRES a session, DRIFT_WINDOW_CALLS apart,
|
|
95
|
+
* and never within that window of a suggestion or a SKILL.md read). The
|
|
96
|
+
* rule and its bounds live in loading-guidance.ts beside the floor text
|
|
97
|
+
* the line points at; this module only wires them to tool results.
|
|
91
98
|
*
|
|
92
99
|
* Structure matches the existing steer whisper pattern used by topic-drift,
|
|
93
100
|
* turn-outcome, compaction-retry, context-lifecycle, and others.
|
|
@@ -107,6 +114,7 @@ import { getSkillsUsageFilePath } from "../../../lib/config/braid-paths.js";
|
|
|
107
114
|
import { SESSION_COMPACT, AGENT_SETTLED } from "../../../lib/core/event-names.js";
|
|
108
115
|
import { getSessionProfile, recordSessionSkillLoad, recordSessionStart, } from "./session-records.js";
|
|
109
116
|
import { triggerMatches } from "./skill-triggers.js";
|
|
117
|
+
import { advanceDrift, driftDirectoryFor, driftPayload, initialDrift, noteDriftSurface, recordDriftDrop, recordDriftFire, skillReadRoot, } from "./loading-guidance.js";
|
|
110
118
|
const log = createLogger("skills-auto-inject");
|
|
111
119
|
// Constants
|
|
112
120
|
/**
|
|
@@ -236,6 +244,7 @@ function getState(ctx) {
|
|
|
236
244
|
injected: [],
|
|
237
245
|
currentTurn: 0,
|
|
238
246
|
hintSent: false,
|
|
247
|
+
drift: initialDrift(),
|
|
239
248
|
}));
|
|
240
249
|
}
|
|
241
250
|
// Shared module-level variable rather than a per-module copy: the import
|
|
@@ -246,6 +255,17 @@ let _skillsCache = [];
|
|
|
246
255
|
export function updateSkillCache(skills) {
|
|
247
256
|
_skillsCache = skills;
|
|
248
257
|
}
|
|
258
|
+
/**
|
|
259
|
+
* The visible catalog as the prompt floor renders it (see loading-guidance.ts):
|
|
260
|
+
* every cached skill model selection may route to, with the description and
|
|
261
|
+
* path the row needs. Read from this module because the cache lives here; the
|
|
262
|
+
* floor's read root is derived from the paths, never hardcoded.
|
|
263
|
+
*/
|
|
264
|
+
export function getCachedVisibleSkills() {
|
|
265
|
+
return _skillsCache
|
|
266
|
+
.filter((s) => !s.disableModelInvocation)
|
|
267
|
+
.map((s) => ({ name: s.name, description: s.description, filePath: s.filePath }));
|
|
268
|
+
}
|
|
249
269
|
// Keyword Extraction
|
|
250
270
|
/**
|
|
251
271
|
* One-rule stemmer: strip a trailing plural s/es so "skills" matches the
|
|
@@ -890,41 +910,93 @@ export function resolveDiscoveryMode(ctx) {
|
|
|
890
910
|
}
|
|
891
911
|
return state;
|
|
892
912
|
}
|
|
893
|
-
// Main Handler
|
|
894
913
|
/**
|
|
895
|
-
*
|
|
896
|
-
*
|
|
914
|
+
* Count a SKILL.md read (the list→read load path) and mark the matching
|
|
915
|
+
* injection loaded (releases its slot and extends its cooldown: the skill is
|
|
916
|
+
* in the agent's context now). Returns the skill name when the read was one,
|
|
917
|
+
* so the caller can treat it as a skill surface.
|
|
918
|
+
*/
|
|
919
|
+
function detectSkillLoad(ev, ctx, state) {
|
|
920
|
+
if (ev?.toolName !== "read")
|
|
921
|
+
return undefined;
|
|
922
|
+
// A failed read returns the error text, not the file — counting it
|
|
923
|
+
// inflated `loaded` with phantom loads (the read-detector never saw
|
|
924
|
+
// the skill content, and no SKILL.md was opened).
|
|
925
|
+
if (ev.isError)
|
|
926
|
+
return undefined;
|
|
927
|
+
const text = (ev.content ?? []).map((c) => c.text ?? "").join("\n");
|
|
928
|
+
const name = skillNameFromRead(ev.input?.path, text);
|
|
929
|
+
if (!name)
|
|
930
|
+
return undefined;
|
|
931
|
+
const held = state.injected.find((i) => i.name === name && i.loadedTurn === undefined);
|
|
932
|
+
if (held)
|
|
933
|
+
held.loadedTurn = state.currentTurn;
|
|
934
|
+
recordSkillLoad(ctx, name);
|
|
935
|
+
log.debug(`[skills-auto-inject] counted actual load of "${name}" via read`);
|
|
936
|
+
return name;
|
|
937
|
+
}
|
|
938
|
+
/**
|
|
939
|
+
* Fire the drift line when the work has moved into a new work area (the rule
|
|
940
|
+
* and its bounds live in loading-guidance.ts, beside the floor text the line
|
|
941
|
+
* points at). The floor is the catalog against the prompt that was in view;
|
|
942
|
+
* a session now reading and writing elsewhere has its catalog in the prompt
|
|
943
|
+
* and its task text elsewhere, and one line re-points at it.
|
|
944
|
+
*
|
|
945
|
+
* Guarded like the floor section itself: without read and list_skills there is
|
|
946
|
+
* no catalog in the prompt to point at, so nothing fires.
|
|
947
|
+
*/
|
|
948
|
+
function stepDrift(pi, ctx, state, ev) {
|
|
949
|
+
const target = advanceDrift(state.drift, driftDirectoryFor(ev?.toolName, ev?.input?.path, ctx.cwd ?? ""));
|
|
950
|
+
if (!target)
|
|
951
|
+
return;
|
|
952
|
+
const toolNames = new Set(pi.getAllTools().map((t) => t.name));
|
|
953
|
+
if (!toolNames.has("read") || !toolNames.has("list_skills")) {
|
|
954
|
+
recordDriftDrop(state.drift);
|
|
955
|
+
return;
|
|
956
|
+
}
|
|
957
|
+
const delivered = sendTrackedMessage(pi, {
|
|
958
|
+
customType: "skills-drift",
|
|
959
|
+
content: [{ type: "text", text: driftPayload(target, skillReadRoot(_skillsCache)) }],
|
|
960
|
+
display: true,
|
|
961
|
+
details: {
|
|
962
|
+
[BRAID_INJECTED]: true,
|
|
963
|
+
[BRAID_SOURCE]: "skills-auto-inject",
|
|
964
|
+
directory: target,
|
|
965
|
+
},
|
|
966
|
+
}, { delivery: "park", deliverAs: "steer" }, { type: "context", source: "skills-auto-inject" },
|
|
967
|
+
// The module's own budget is the bound (DRIFT_MAX_FIRES a session,
|
|
968
|
+
// DRIFT_WINDOW_CALLS between fires), so a suppression cap must not drop
|
|
969
|
+
// the line in a busy turn: that is exactly when the work is moving and
|
|
970
|
+
// the floor's snapshot goes stale.
|
|
971
|
+
{ bypassFloodCap: true });
|
|
972
|
+
if (!delivered) {
|
|
973
|
+
recordDriftDrop(state.drift);
|
|
974
|
+
return;
|
|
975
|
+
}
|
|
976
|
+
recordDriftFire(state.drift, target);
|
|
977
|
+
log.info(`[skills-auto-inject] drift line for ${target} (fire ${state.drift.fires}, call ${state.drift.calls})`);
|
|
978
|
+
}
|
|
979
|
+
/**
|
|
980
|
+
* Register the auto-inject handler on before_agent_start, the read-tool load
|
|
981
|
+
* detector and the drift trigger on tool_result.
|
|
897
982
|
*
|
|
898
983
|
* Call this from the skills-tool extension factory, after registering
|
|
899
984
|
* the list_skills tool.
|
|
900
985
|
*/
|
|
901
986
|
export function registerAutoInject(pi) {
|
|
902
|
-
//
|
|
903
|
-
//
|
|
904
|
-
//
|
|
987
|
+
// Two jobs per tool result. The load detector runs first: a SKILL.md read
|
|
988
|
+
// that just landed is a skill surface, and the drift guard must see it
|
|
989
|
+
// before it decides whether to speak.
|
|
905
990
|
pi.on("tool_result", (event, ctx) => {
|
|
906
991
|
try {
|
|
907
992
|
const ev = event;
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
// the skill content, and no SKILL.md was opened).
|
|
913
|
-
if (ev.isError)
|
|
914
|
-
return;
|
|
915
|
-
const text = (ev.content ?? []).map((c) => c.text ?? "").join("\n");
|
|
916
|
-
const name = skillNameFromRead(ev.input?.path, text);
|
|
917
|
-
if (name) {
|
|
918
|
-
const state = getState(ctx);
|
|
919
|
-
const held = state.injected.find((i) => i.name === name && i.loadedTurn === undefined);
|
|
920
|
-
if (held)
|
|
921
|
-
held.loadedTurn = state.currentTurn;
|
|
922
|
-
recordSkillLoad(ctx, name);
|
|
923
|
-
log.debug(`[skills-auto-inject] counted actual load of "${name}" via read`);
|
|
924
|
-
}
|
|
993
|
+
const state = getState(ctx);
|
|
994
|
+
if (detectSkillLoad(ev, ctx, state))
|
|
995
|
+
noteDriftSurface(state.drift);
|
|
996
|
+
stepDrift(pi, ctx, state, ev);
|
|
925
997
|
}
|
|
926
998
|
catch {
|
|
927
|
-
// best-effort — never break the tool loop over a counter
|
|
999
|
+
// best-effort — never break the tool loop over a counter or a whisper
|
|
928
1000
|
}
|
|
929
1001
|
});
|
|
930
1002
|
// Post-compaction the transcript can regain pi's stock skill catalog (the
|
|
@@ -1036,6 +1108,10 @@ export function registerAutoInject(pi) {
|
|
|
1036
1108
|
}
|
|
1037
1109
|
log.info(`[skills-auto-inject] Suggesting ${skillsToInject.map((s) => s.name).join(", ")} ` +
|
|
1038
1110
|
`(turn ${state.currentTurn}, keywords: ${keywords.slice(0, 5).join(", ")})`);
|
|
1111
|
+
// A delivered suggestion is a skill surface: the drift trigger stays
|
|
1112
|
+
// quiet for its window, because the pointer the trigger exists to
|
|
1113
|
+
// supply has just landed.
|
|
1114
|
+
noteDriftSurface(state.drift);
|
|
1039
1115
|
for (const item of toInject) {
|
|
1040
1116
|
state.injected.push({
|
|
1041
1117
|
name: item.skill.name,
|
|
@@ -38,6 +38,7 @@ import { registerAutoInject, updateSkillCache, getSkillStats, getDurableSkillSta
|
|
|
38
38
|
import { readSkillTriggerEntries } from "./skill-triggers.js";
|
|
39
39
|
import { clampSectionsMax, DEFAULT_SECTIONS_MAX, SECTIONS_MAX_LIMIT, readSkillReach, } from "./reach.js";
|
|
40
40
|
import { getMonthlyAdoptionRollup } from "./session-records.js";
|
|
41
|
+
import { checkArgumentValues } from "../../../lib/utils/argument-report.js";
|
|
41
42
|
const log = createLogger("skills-tool");
|
|
42
43
|
let cachedSkills = [];
|
|
43
44
|
/**
|
|
@@ -166,38 +167,58 @@ function rowOf(row) {
|
|
|
166
167
|
return { score: row.score, reason: row.reason ?? "description" };
|
|
167
168
|
}
|
|
168
169
|
// Extension factory:
|
|
170
|
+
/**
|
|
171
|
+
* `list_skills` arguments: one action, one page of the catalog.
|
|
172
|
+
*
|
|
173
|
+
* The action is named here rather than inferred, because a pager call and a
|
|
174
|
+
* full-catalog call are the same call and the schema is what the model reads
|
|
175
|
+
* before choosing. The tool fills it when the call omits it (`prepareArguments`
|
|
176
|
+
* below), so a bare pager call behaves as the listing it obviously is while an
|
|
177
|
+
* unknown action is still refused.
|
|
178
|
+
*/
|
|
179
|
+
const listSkillsSchema = Type.Object({
|
|
180
|
+
action: Type.Literal("list", {
|
|
181
|
+
description: "list = paginated catalog with per-skill reach (reachable, lines, bytes, chars, estTokens, sectionCount, sections)",
|
|
182
|
+
}),
|
|
183
|
+
page: Type.Optional(Type.Number({
|
|
184
|
+
minimum: 1,
|
|
185
|
+
default: 1,
|
|
186
|
+
description: "Page number for list (1-based)",
|
|
187
|
+
})),
|
|
188
|
+
pageSize: Type.Optional(Type.Number({
|
|
189
|
+
minimum: 1,
|
|
190
|
+
maximum: 50,
|
|
191
|
+
default: 10,
|
|
192
|
+
description: "Entries per page for list",
|
|
193
|
+
})),
|
|
194
|
+
sectionsMax: Type.Optional(Type.Number({
|
|
195
|
+
minimum: 0,
|
|
196
|
+
maximum: SECTIONS_MAX_LIMIT,
|
|
197
|
+
default: DEFAULT_SECTIONS_MAX,
|
|
198
|
+
description: "Headings reported per skill; 0 omits the section list and keeps sectionCount",
|
|
199
|
+
})),
|
|
200
|
+
rank: Type.Optional(Type.Union([Type.Literal("relevance"), Type.Literal("catalog")], {
|
|
201
|
+
default: "relevance",
|
|
202
|
+
description: "relevance (default) = order by fit to the current task; catalog = the plain catalog order, with no ranking fields",
|
|
203
|
+
})),
|
|
204
|
+
});
|
|
169
205
|
export default function skillsToolExtension(pi) {
|
|
170
206
|
registerAutoInject(pi);
|
|
171
207
|
pi.registerTool({
|
|
172
208
|
name: "list_skills",
|
|
173
209
|
label: "List Skills",
|
|
174
210
|
description: "Discover skills on demand: paginated catalog (name, filePath, description, source) plus each skill's reach (reachable, lines, bytes, chars, estTokens, sectionCount, section headings with line numbers), so the price of a read is visible before the read. Rows are ordered by relevance to the current task; a row with match evidence carries relevance {score, reason}, and the response carries ranking {tier, basis, policy}. Pass rank: 'catalog' for the plain catalog order. `read` a SKILL.md to load it.",
|
|
175
|
-
parameters:
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
maximum: 50,
|
|
187
|
-
default: 10,
|
|
188
|
-
description: "Entries per page for list",
|
|
189
|
-
})),
|
|
190
|
-
sectionsMax: Type.Optional(Type.Number({
|
|
191
|
-
minimum: 0,
|
|
192
|
-
maximum: SECTIONS_MAX_LIMIT,
|
|
193
|
-
default: DEFAULT_SECTIONS_MAX,
|
|
194
|
-
description: "Headings reported per skill; 0 omits the section list and keeps sectionCount",
|
|
195
|
-
})),
|
|
196
|
-
rank: Type.Optional(Type.Union([Type.Literal("relevance"), Type.Literal("catalog")], {
|
|
197
|
-
default: "relevance",
|
|
198
|
-
description: "relevance (default) = order by fit to the current task; catalog = the plain catalog order, with no ranking fields",
|
|
199
|
-
})),
|
|
200
|
-
}),
|
|
211
|
+
parameters: listSkillsSchema,
|
|
212
|
+
// Paging without an action is a listing call: fill the action the call
|
|
213
|
+
// implies before pi validates, and refuse a guessed value with the accepted
|
|
214
|
+
// one named. The schema above stays the only description of the contract.
|
|
215
|
+
prepareArguments: (args) => {
|
|
216
|
+
const prepared = args && typeof args === "object" && args.action == null
|
|
217
|
+
? { ...args, action: "list" }
|
|
218
|
+
: args;
|
|
219
|
+
checkArgumentValues("list_skills", listSkillsSchema, prepared);
|
|
220
|
+
return prepared;
|
|
221
|
+
},
|
|
201
222
|
execute: async (_id, params, signal, _onUpdate, ctx) => {
|
|
202
223
|
const page = params.page ?? 1;
|
|
203
224
|
const pageSize = params.pageSize ?? 10;
|
|
@@ -1,36 +1,90 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Skills
|
|
2
|
+
* Skills floor, owned by the skills-tool module: the visible catalog section
|
|
3
|
+
* and the drift trigger that re-points at it.
|
|
3
4
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
5
|
+
* prompt-builder imports the section text and renders it as the
|
|
6
|
+
* "skills-loading" section ONLY when both `read` and `list_skills` are active
|
|
7
|
+
* tools.
|
|
7
8
|
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
9
|
+
* Why the catalog is rendered instead of described. A pointer the model has
|
|
10
|
+
* to redeem with a tool call is a probability, not a mechanism: the first
|
|
11
|
+
* prompt of a resumed session is thin ("let's pick up where we left off"),
|
|
12
|
+
* the catalog is one call away, and nothing in a thin prompt demands it.
|
|
13
|
+
* Rendering every visible skill as one `- name: description` row removes the
|
|
14
|
+
* redemption step, so a domain match needs only the task text in front of the
|
|
15
|
+
* model, not a decision to go look. The row is metadata; the file is still
|
|
16
|
+
* the knowledge, and the rule below says so.
|
|
17
|
+
*
|
|
18
|
+
* The read path is derived from the entries' own paths, never hardcoded: the
|
|
19
|
+
* same text renders for a checkout, an npm install tree, or a worktree. A
|
|
20
|
+
* catalog installed from more than one pack has no single root, so each
|
|
21
|
+
* directory heads its own group of rows instead of one root being named for
|
|
22
|
+
* all of them (a root that resolves for 22 rows and misdirects the other 5 is
|
|
23
|
+
* worse than no root at all).
|
|
16
24
|
*
|
|
17
25
|
* The mechanical trigger's worked examples are derived at assembly time from
|
|
18
|
-
* the live tool and skill names
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
+
* the live tool and skill names: a tool's family token paired with an
|
|
27
|
+
* installed visible skill's dash-token. The text never hardcodes a tool or
|
|
28
|
+
* skill name, so it cannot name a pair that does not exist in the running
|
|
29
|
+
* session; when no pair computes, the sentence renders without a
|
|
30
|
+
* parenthetical.
|
|
31
|
+
*
|
|
32
|
+
* The same module owns the drift trigger (below): work that moves to a new
|
|
33
|
+
* directory is the moment a visible catalog stops matching the task text in
|
|
34
|
+
* view, and the trigger re-points at the catalog with one line. Its state is
|
|
35
|
+
* plain data and its decisions are pure functions, so the wiring lives in
|
|
36
|
+
* auto-inject.ts and the reasoning stays testable here.
|
|
37
|
+
*/
|
|
38
|
+
/** One visible skill as the floor renders it. */
|
|
39
|
+
export interface CatalogEntry {
|
|
40
|
+
name: string;
|
|
41
|
+
description: string;
|
|
42
|
+
filePath: string;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Paragraph 1: what the catalog is, where the bodies live, and the obligation.
|
|
46
|
+
*
|
|
47
|
+
* `readRoot` is the single pack directory the rule can state; `grouped` says
|
|
48
|
+
* the rows are rendered under directory headings instead, so the rule points
|
|
49
|
+
* at the heading rather than at a root that does not exist. Neither given (a
|
|
50
|
+
* catalog whose bodies carry no pack) leaves the location unstated, which is
|
|
51
|
+
* the honest answer when the paths cannot be derived.
|
|
52
|
+
*/
|
|
53
|
+
export declare function skillsCatalogRule(readRoot: string, grouped?: boolean): string;
|
|
26
54
|
/** Paragraph 2: the pointer rule (pinned verbatim by test-prompt-budget.mjs). */
|
|
27
|
-
export declare const SKILLS_POINTER_RULE = "Pointer rule: the catalog one-liner is metadata, not content \u2014 the SKILL.md path is the knowledge.
|
|
55
|
+
export declare const SKILLS_POINTER_RULE = "Pointer rule: the catalog one-liner is metadata, not content \u2014 the SKILL.md path is the knowledge. The prompt already covering the domain is the only reason to skip the read.";
|
|
56
|
+
/** One directory a catalog's bodies live in, with the skills filed under it. */
|
|
57
|
+
export interface CatalogGroup {
|
|
58
|
+
/** The pack directory itself, in forward-slash form. */
|
|
59
|
+
dir: string;
|
|
60
|
+
skills: CatalogEntry[];
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* File the entries by the pack their own SKILL.md lives in: the braid pack
|
|
64
|
+
* plus the user-global directory is two groups in one catalog. Groups and
|
|
65
|
+
* rows are sorted, so identical catalogs render byte-identical text in any
|
|
66
|
+
* cache order. Pure.
|
|
67
|
+
*/
|
|
68
|
+
export declare function catalogGroups(skills: CatalogEntry[]): CatalogGroup[];
|
|
69
|
+
/**
|
|
70
|
+
* The one directory every entry lives under, or "" when they do not share
|
|
71
|
+
* one: a single root is a fact a caller may state, and a common ancestor of
|
|
72
|
+
* two packs is not. Pure.
|
|
73
|
+
*/
|
|
74
|
+
export declare function skillReadRoot(skills: CatalogEntry[]): string;
|
|
75
|
+
/**
|
|
76
|
+
* One row per skill: `- name: description`, whitespace collapsed to a single
|
|
77
|
+
* line. Descriptions are NOT clipped: the row is the whole reason the floor
|
|
78
|
+
* works, and a clipped description is what a model would have to guess from.
|
|
79
|
+
* Pure.
|
|
80
|
+
*/
|
|
81
|
+
export declare function catalogRows(skills: CatalogEntry[]): string[];
|
|
28
82
|
/**
|
|
29
83
|
* Worked examples for the mechanical trigger, derived from the live inputs.
|
|
30
84
|
*
|
|
31
85
|
* A pair exists when a tool's family token (the first underscore-delimited
|
|
32
|
-
* token of the tool name: `
|
|
33
|
-
* token of a skill name (`
|
|
86
|
+
* token of the tool name: `widget_open` → `widget`) equals a dash-delimited
|
|
87
|
+
* token of a skill name (`widget-map` → `widget`), case-insensitively.
|
|
34
88
|
* One example renders per distinct family token: the trigger fires per
|
|
35
89
|
* family ("before the first call in the family"), so enumerating every tool
|
|
36
90
|
* in a family would restate one fact; the representative tool is the
|
|
@@ -41,10 +95,77 @@ export declare const SKILLS_POINTER_RULE = "Pointer rule: the catalog one-liner
|
|
|
41
95
|
*/
|
|
42
96
|
export declare function mechanicalTriggerExamples(toolNames: string[], skillNames: string[]): string[];
|
|
43
97
|
/**
|
|
44
|
-
* The full skills-loading
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
98
|
+
* The full skills-loading section: catalog rule (with the derived read path),
|
|
99
|
+
* pointer rule, one row per visible skill, and the mechanical trigger with
|
|
100
|
+
* only the pairs computed from the given tool and skill names.
|
|
101
|
+
*
|
|
102
|
+
* prompt-builder feeds it the active tool names and the skills-tool module's
|
|
103
|
+
* visible catalog. An empty catalog renders no section: the floor is a
|
|
104
|
+
* catalog, and a section claiming to list every skill while listing none
|
|
105
|
+
* would be a lie the model has no way to check.
|
|
106
|
+
*
|
|
107
|
+
* One pack renders its root in the rule; several packs render a directory
|
|
108
|
+
* heading before each group of rows, because no single root describes them.
|
|
109
|
+
*/
|
|
110
|
+
export declare function skillsLoadingText(toolNames: string[], skills: CatalogEntry[]): string;
|
|
111
|
+
/** The path-taking tools whose calls describe where the work is. */
|
|
112
|
+
export declare const DRIFT_PATH_TOOLS: readonly ["read", "edit", "write"];
|
|
113
|
+
/** Tool calls that must pass between fires, and after any skill surface. */
|
|
114
|
+
export declare const DRIFT_WINDOW_CALLS = 12;
|
|
115
|
+
/** Fires per session. */
|
|
116
|
+
export declare const DRIFT_MAX_FIRES = 3;
|
|
117
|
+
/** Entries in one directory before it counts as where the work is. */
|
|
118
|
+
export declare const DRIFT_ENTRIES = 2;
|
|
119
|
+
/** Directory segments a path must carry before it can name a work area. */
|
|
120
|
+
export declare const DRIFT_MIN_SEGMENTS = 2;
|
|
121
|
+
/** Drift state, session-scoped plain data (see auto-inject.ts for the holder). */
|
|
122
|
+
export interface DriftTracker {
|
|
123
|
+
/** Tool results seen this session: the clock both window guards read. */
|
|
124
|
+
calls: number;
|
|
125
|
+
/** Call index of the last fire; null before the first. */
|
|
126
|
+
lastFire: number | null;
|
|
127
|
+
/** Fires this session. */
|
|
128
|
+
fires: number;
|
|
129
|
+
/** Call index of the last skill surface; null before the first. */
|
|
130
|
+
lastSurface: number | null;
|
|
131
|
+
/** Directory -> entries seen since the last fire. */
|
|
132
|
+
entries: Record<string, number>;
|
|
133
|
+
/** Directories already announced (each is announced once). */
|
|
134
|
+
announced: string[];
|
|
135
|
+
}
|
|
136
|
+
/** Fresh drift state for a session. */
|
|
137
|
+
export declare function initialDrift(): DriftTracker;
|
|
138
|
+
/**
|
|
139
|
+
* The work area a finished tool call touched: the first two directory
|
|
140
|
+
* segments of its path, relative to the session's project root. Undefined for
|
|
141
|
+
* a tool that takes no path, a path outside the project, and a path with
|
|
142
|
+
* fewer than DRIFT_MIN_SEGMENTS directories. Pure.
|
|
143
|
+
*/
|
|
144
|
+
export declare function driftDirectoryFor(toolName: string | undefined, inputPath: string | undefined, cwd: string): string | undefined;
|
|
145
|
+
/**
|
|
146
|
+
* Count one finished tool call and answer whether it is a fire.
|
|
147
|
+
*
|
|
148
|
+
* Returns the work area to announce, or null. The caller fires the line and
|
|
149
|
+
* then calls recordDriftFire (on delivery) or recordDriftDrop (when the
|
|
150
|
+
* whisper was suppressed), so a dropped line never spends the budget. The
|
|
151
|
+
* tracker is the session's own mutable state; the answer is a pure function
|
|
152
|
+
* of its contents.
|
|
153
|
+
*/
|
|
154
|
+
export declare function advanceDrift(tracker: DriftTracker, directory: string | undefined): string | null;
|
|
155
|
+
/** Mark a fire at the current call: spends one fire, announces, restarts counts. */
|
|
156
|
+
export declare function recordDriftFire(tracker: DriftTracker, directory: string): void;
|
|
157
|
+
/**
|
|
158
|
+
* Mark a fire attempt whose whisper was suppressed: no fire is spent and the
|
|
159
|
+
* directory is not announced, but the counts restart and the window opens, so
|
|
160
|
+
* a suppressed line is retried only after the session has done more work.
|
|
161
|
+
*/
|
|
162
|
+
export declare function recordDriftDrop(tracker: DriftTracker): void;
|
|
163
|
+
/** Note that a skill surface (a suggestion or a SKILL.md read) just landed. */
|
|
164
|
+
export declare function noteDriftSurface(tracker: DriftTracker): void;
|
|
165
|
+
/**
|
|
166
|
+
* The one-line steer: the work area and a pointer back at the catalog in the
|
|
167
|
+
* prompt. `readRoot` empty (several packs, see skillReadRoot) drops the path
|
|
168
|
+
* clause instead of naming a path that may not resolve.
|
|
48
169
|
*/
|
|
49
|
-
export declare function
|
|
170
|
+
export declare function driftPayload(directory: string, readRoot: string): string;
|
|
50
171
|
//# sourceMappingURL=loading-guidance.d.ts.map
|