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
|
@@ -1,42 +1,151 @@
|
|
|
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
|
-
*
|
|
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.
|
|
23
37
|
*/
|
|
24
38
|
|
|
25
|
-
|
|
26
|
-
|
|
39
|
+
import { isAbsolute, relative, resolve, sep } from "node:path";
|
|
40
|
+
|
|
41
|
+
/** One visible skill as the floor renders it. */
|
|
42
|
+
export interface CatalogEntry {
|
|
43
|
+
name: string;
|
|
44
|
+
description: string;
|
|
45
|
+
filePath: string;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Paragraph 1: what the catalog is, where the bodies live, and the obligation.
|
|
50
|
+
*
|
|
51
|
+
* `readRoot` is the single pack directory the rule can state; `grouped` says
|
|
52
|
+
* the rows are rendered under directory headings instead, so the rule points
|
|
53
|
+
* at the heading rather than at a root that does not exist. Neither given (a
|
|
54
|
+
* catalog whose bodies carry no pack) leaves the location unstated, which is
|
|
55
|
+
* the honest answer when the paths cannot be derived.
|
|
56
|
+
*/
|
|
57
|
+
export function skillsCatalogRule(readRoot: string, grouped = false): string {
|
|
58
|
+
const readPath = readRoot
|
|
59
|
+
? ` Each row's body is at \`${readRoot}/<name>/SKILL.md\`.`
|
|
60
|
+
: grouped
|
|
61
|
+
? ` Each row's body is at \`<dir>/<name>/SKILL.md\`, where \`<dir>\` is the row's directory heading.`
|
|
62
|
+
: "";
|
|
63
|
+
return `This catalog is every installed skill: one row per skill, name and description.${readPath} When the task enters a listed skill's domain, read the WHOLE SKILL.md before acting in that domain; never act from memory of a skill's contents.`;
|
|
64
|
+
}
|
|
27
65
|
|
|
28
66
|
/** Paragraph 2: the pointer rule (pinned verbatim by test-prompt-budget.mjs). */
|
|
29
|
-
export const SKILLS_POINTER_RULE = `Pointer rule: the catalog one-liner is metadata, not content — the SKILL.md path is the knowledge.
|
|
67
|
+
export const SKILLS_POINTER_RULE = `Pointer rule: the catalog one-liner is metadata, not content — the SKILL.md path is the knowledge. The prompt already covering the domain is the only reason to skip the read.`;
|
|
30
68
|
|
|
31
69
|
const MECHANICAL_TRIGGER_LEAD = `Mechanical trigger, no judgment call: about to use a tool family whose word appears in a skill's name`;
|
|
32
70
|
const MECHANICAL_TRIGGER_TAIL = `→ read that SKILL.md before the first call in the family.`;
|
|
33
71
|
|
|
72
|
+
/** Forward-slash form of a path, for segment arithmetic on either platform. */
|
|
73
|
+
function toSlashes(path: string): string {
|
|
74
|
+
return path.replace(/\\/g, "/");
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** Sorted by name, byte-comparison so the order never depends on the locale. */
|
|
78
|
+
function byName(a: string, b: string): number {
|
|
79
|
+
return a < b ? -1 : a > b ? 1 : 0;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** One directory a catalog's bodies live in, with the skills filed under it. */
|
|
83
|
+
export interface CatalogGroup {
|
|
84
|
+
/** The pack directory itself, in forward-slash form. */
|
|
85
|
+
dir: string;
|
|
86
|
+
skills: CatalogEntry[];
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* The pack directory a skill's body sits in. pi's layout is
|
|
91
|
+
* `<pack>/<skill-name>/SKILL.md`, so the pack is two levels above the file;
|
|
92
|
+
* the row's stated path is `<pack>/<name>/SKILL.md`. A path too short to have
|
|
93
|
+
* a pack reports "", and its group renders without a heading.
|
|
94
|
+
*/
|
|
95
|
+
function packOf(filePath: string): string {
|
|
96
|
+
const parts = toSlashes(filePath ?? "").split("/");
|
|
97
|
+
if (parts.length < 3) return "";
|
|
98
|
+
return parts.slice(0, -2).join("/");
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* File the entries by the pack their own SKILL.md lives in: the braid pack
|
|
103
|
+
* plus the user-global directory is two groups in one catalog. Groups and
|
|
104
|
+
* rows are sorted, so identical catalogs render byte-identical text in any
|
|
105
|
+
* cache order. Pure.
|
|
106
|
+
*/
|
|
107
|
+
export function catalogGroups(skills: CatalogEntry[]): CatalogGroup[] {
|
|
108
|
+
const byDir = new Map<string, CatalogEntry[]>();
|
|
109
|
+
for (const skill of skills) {
|
|
110
|
+
const dir = packOf(skill.filePath ?? "");
|
|
111
|
+
const bucket = byDir.get(dir);
|
|
112
|
+
if (bucket) bucket.push(skill);
|
|
113
|
+
else byDir.set(dir, [skill]);
|
|
114
|
+
}
|
|
115
|
+
return [...byDir.keys()].sort(byName).map((dir) => ({ dir, skills: byDir.get(dir) ?? [] }));
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* The one directory every entry lives under, or "" when they do not share
|
|
120
|
+
* one: a single root is a fact a caller may state, and a common ancestor of
|
|
121
|
+
* two packs is not. Pure.
|
|
122
|
+
*/
|
|
123
|
+
export function skillReadRoot(skills: CatalogEntry[]): string {
|
|
124
|
+
const groups = catalogGroups(skills);
|
|
125
|
+
return groups.length === 1 ? groups[0].dir : "";
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* One row per skill: `- name: description`, whitespace collapsed to a single
|
|
130
|
+
* line. Descriptions are NOT clipped: the row is the whole reason the floor
|
|
131
|
+
* works, and a clipped description is what a model would have to guess from.
|
|
132
|
+
* Pure.
|
|
133
|
+
*/
|
|
134
|
+
export function catalogRows(skills: CatalogEntry[]): string[] {
|
|
135
|
+
return [...skills]
|
|
136
|
+
.sort((a, b) => byName(a.name, b.name))
|
|
137
|
+
.map((s) => {
|
|
138
|
+
const description = (s.description ?? "").replace(/\s+/g, " ").trim();
|
|
139
|
+
return description ? `- ${s.name}: ${description}` : `- ${s.name}`;
|
|
140
|
+
});
|
|
141
|
+
}
|
|
142
|
+
|
|
34
143
|
/**
|
|
35
144
|
* Worked examples for the mechanical trigger, derived from the live inputs.
|
|
36
145
|
*
|
|
37
146
|
* A pair exists when a tool's family token (the first underscore-delimited
|
|
38
|
-
* token of the tool name: `
|
|
39
|
-
* token of a skill name (`
|
|
147
|
+
* token of the tool name: `widget_open` → `widget`) equals a dash-delimited
|
|
148
|
+
* token of a skill name (`widget-map` → `widget`), case-insensitively.
|
|
40
149
|
* One example renders per distinct family token: the trigger fires per
|
|
41
150
|
* family ("before the first call in the family"), so enumerating every tool
|
|
42
151
|
* in a family would restate one fact; the representative tool is the
|
|
@@ -74,16 +183,181 @@ export function mechanicalTriggerExamples(toolNames: string[], skillNames: strin
|
|
|
74
183
|
}
|
|
75
184
|
|
|
76
185
|
/**
|
|
77
|
-
* The full skills-loading
|
|
78
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
186
|
+
* The full skills-loading section: catalog rule (with the derived read path),
|
|
187
|
+
* pointer rule, one row per visible skill, and the mechanical trigger with
|
|
188
|
+
* only the pairs computed from the given tool and skill names.
|
|
189
|
+
*
|
|
190
|
+
* prompt-builder feeds it the active tool names and the skills-tool module's
|
|
191
|
+
* visible catalog. An empty catalog renders no section: the floor is a
|
|
192
|
+
* catalog, and a section claiming to list every skill while listing none
|
|
193
|
+
* would be a lie the model has no way to check.
|
|
194
|
+
*
|
|
195
|
+
* One pack renders its root in the rule; several packs render a directory
|
|
196
|
+
* heading before each group of rows, because no single root describes them.
|
|
81
197
|
*/
|
|
82
|
-
export function skillsLoadingText(toolNames: string[],
|
|
83
|
-
|
|
198
|
+
export function skillsLoadingText(toolNames: string[], skills: CatalogEntry[]): string {
|
|
199
|
+
if (!skills.length) return "";
|
|
200
|
+
const examples = mechanicalTriggerExamples(
|
|
201
|
+
toolNames,
|
|
202
|
+
skills.map((s) => s.name),
|
|
203
|
+
);
|
|
84
204
|
const trigger =
|
|
85
205
|
examples.length > 0
|
|
86
206
|
? `${MECHANICAL_TRIGGER_LEAD} (${examples.join(", ")}) ${MECHANICAL_TRIGGER_TAIL}`
|
|
87
207
|
: `${MECHANICAL_TRIGGER_LEAD} ${MECHANICAL_TRIGGER_TAIL}`;
|
|
88
|
-
|
|
208
|
+
const groups = catalogGroups(skills);
|
|
209
|
+
const grouped = groups.length > 1;
|
|
210
|
+
const rows = grouped
|
|
211
|
+
? groups
|
|
212
|
+
.map((g) =>
|
|
213
|
+
g.dir
|
|
214
|
+
? `${g.dir}\n${catalogRows(g.skills).join("\n")}`
|
|
215
|
+
: catalogRows(g.skills).join("\n"),
|
|
216
|
+
)
|
|
217
|
+
.join("\n\n")
|
|
218
|
+
: catalogRows(groups[0].skills).join("\n");
|
|
219
|
+
return `${skillsCatalogRule(skillReadRoot(skills), grouped)}\n\n${SKILLS_POINTER_RULE}\n\n${rows}\n\n${trigger}\n`;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
// Drift trigger
|
|
223
|
+
//
|
|
224
|
+
// The floor is a snapshot: the catalog does not change mid-session, but the
|
|
225
|
+
// work does. A session that starts in one directory and moves to another has
|
|
226
|
+
// its catalog in view and its task text elsewhere, which is the same silent
|
|
227
|
+
// prompt the floor exists for. The trigger watches where the path-taking
|
|
228
|
+
// tools actually write and reads, and when a new directory accumulates
|
|
229
|
+
// entries it says so in one line, pointing back at the catalog.
|
|
230
|
+
//
|
|
231
|
+
// Bounds, all deliberate:
|
|
232
|
+
// - two entries in one directory before it counts: a single stray read is
|
|
233
|
+
// not where the work is.
|
|
234
|
+
// - at most one fire per DRIFT_WINDOW_CALLS tool calls, and quiet for the
|
|
235
|
+
// same window after any skill surface (a suggestion or a SKILL.md read),
|
|
236
|
+
// because a surface that just landed is the pointer the trigger exists to
|
|
237
|
+
// supply.
|
|
238
|
+
// - at most DRIFT_MAX_FIRES per session, so the line stays a signal.
|
|
239
|
+
// - a directory is announced once; the entry counts restart after a fire,
|
|
240
|
+
// so the budget is spent on directories the session has not been told
|
|
241
|
+
// about.
|
|
242
|
+
// - paths with fewer than two directory segments are ignored: repo-root
|
|
243
|
+
// files and top-level directories are where a session starts, not where
|
|
244
|
+
// it moved to.
|
|
245
|
+
|
|
246
|
+
/** The path-taking tools whose calls describe where the work is. */
|
|
247
|
+
export const DRIFT_PATH_TOOLS = ["read", "edit", "write"] as const;
|
|
248
|
+
|
|
249
|
+
/** Tool calls that must pass between fires, and after any skill surface. */
|
|
250
|
+
export const DRIFT_WINDOW_CALLS = 12;
|
|
251
|
+
|
|
252
|
+
/** Fires per session. */
|
|
253
|
+
export const DRIFT_MAX_FIRES = 3;
|
|
254
|
+
|
|
255
|
+
/** Entries in one directory before it counts as where the work is. */
|
|
256
|
+
export const DRIFT_ENTRIES = 2;
|
|
257
|
+
|
|
258
|
+
/** Directory segments a path must carry before it can name a work area. */
|
|
259
|
+
export const DRIFT_MIN_SEGMENTS = 2;
|
|
260
|
+
|
|
261
|
+
/** Drift state, session-scoped plain data (see auto-inject.ts for the holder). */
|
|
262
|
+
export interface DriftTracker {
|
|
263
|
+
/** Tool results seen this session: the clock both window guards read. */
|
|
264
|
+
calls: number;
|
|
265
|
+
/** Call index of the last fire; null before the first. */
|
|
266
|
+
lastFire: number | null;
|
|
267
|
+
/** Fires this session. */
|
|
268
|
+
fires: number;
|
|
269
|
+
/** Call index of the last skill surface; null before the first. */
|
|
270
|
+
lastSurface: number | null;
|
|
271
|
+
/** Directory -> entries seen since the last fire. */
|
|
272
|
+
entries: Record<string, number>;
|
|
273
|
+
/** Directories already announced (each is announced once). */
|
|
274
|
+
announced: string[];
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
/** Fresh drift state for a session. */
|
|
278
|
+
export function initialDrift(): DriftTracker {
|
|
279
|
+
return { calls: 0, lastFire: null, fires: 0, lastSurface: null, entries: {}, announced: [] };
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/**
|
|
283
|
+
* The work area a finished tool call touched: the first two directory
|
|
284
|
+
* segments of its path, relative to the session's project root. Undefined for
|
|
285
|
+
* a tool that takes no path, a path outside the project, and a path with
|
|
286
|
+
* fewer than DRIFT_MIN_SEGMENTS directories. Pure.
|
|
287
|
+
*/
|
|
288
|
+
export function driftDirectoryFor(
|
|
289
|
+
toolName: string | undefined,
|
|
290
|
+
inputPath: string | undefined,
|
|
291
|
+
cwd: string,
|
|
292
|
+
): string | undefined {
|
|
293
|
+
if (!toolName || !(DRIFT_PATH_TOOLS as readonly string[]).includes(toolName)) return undefined;
|
|
294
|
+
if (!inputPath || !cwd) return undefined;
|
|
295
|
+
const root = resolve(cwd);
|
|
296
|
+
const absolute = isAbsolute(inputPath) ? resolve(inputPath) : resolve(root, inputPath);
|
|
297
|
+
const inside = relative(root, absolute);
|
|
298
|
+
const segments = inside.split(sep).filter(Boolean);
|
|
299
|
+
if (!segments.length || segments[0] === "..") return undefined;
|
|
300
|
+
const directories = segments.slice(0, -1);
|
|
301
|
+
if (directories.length < DRIFT_MIN_SEGMENTS) return undefined;
|
|
302
|
+
return directories.slice(0, DRIFT_MIN_SEGMENTS).join("/");
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
/**
|
|
306
|
+
* Count one finished tool call and answer whether it is a fire.
|
|
307
|
+
*
|
|
308
|
+
* Returns the work area to announce, or null. The caller fires the line and
|
|
309
|
+
* then calls recordDriftFire (on delivery) or recordDriftDrop (when the
|
|
310
|
+
* whisper was suppressed), so a dropped line never spends the budget. The
|
|
311
|
+
* tracker is the session's own mutable state; the answer is a pure function
|
|
312
|
+
* of its contents.
|
|
313
|
+
*/
|
|
314
|
+
export function advanceDrift(tracker: DriftTracker, directory: string | undefined): string | null {
|
|
315
|
+
tracker.calls++;
|
|
316
|
+
if (!directory) return null;
|
|
317
|
+
if (tracker.fires >= DRIFT_MAX_FIRES) return null;
|
|
318
|
+
const entries = (tracker.entries[directory] ?? 0) + 1;
|
|
319
|
+
tracker.entries[directory] = entries;
|
|
320
|
+
if (entries < DRIFT_ENTRIES) return null;
|
|
321
|
+
if (tracker.announced.includes(directory)) return null;
|
|
322
|
+
if (tracker.lastFire !== null && tracker.calls - tracker.lastFire < DRIFT_WINDOW_CALLS)
|
|
323
|
+
return null;
|
|
324
|
+
if (tracker.lastSurface !== null && tracker.calls - tracker.lastSurface < DRIFT_WINDOW_CALLS) {
|
|
325
|
+
return null;
|
|
326
|
+
}
|
|
327
|
+
return directory;
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
/** Mark a fire at the current call: spends one fire, announces, restarts counts. */
|
|
331
|
+
export function recordDriftFire(tracker: DriftTracker, directory: string): void {
|
|
332
|
+
tracker.fires++;
|
|
333
|
+
tracker.lastFire = tracker.calls;
|
|
334
|
+
if (!tracker.announced.includes(directory)) tracker.announced.push(directory);
|
|
335
|
+
tracker.entries = {};
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
/**
|
|
339
|
+
* Mark a fire attempt whose whisper was suppressed: no fire is spent and the
|
|
340
|
+
* directory is not announced, but the counts restart and the window opens, so
|
|
341
|
+
* a suppressed line is retried only after the session has done more work.
|
|
342
|
+
*/
|
|
343
|
+
export function recordDriftDrop(tracker: DriftTracker): void {
|
|
344
|
+
tracker.lastFire = tracker.calls;
|
|
345
|
+
tracker.entries = {};
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
/** Note that a skill surface (a suggestion or a SKILL.md read) just landed. */
|
|
349
|
+
export function noteDriftSurface(tracker: DriftTracker): void {
|
|
350
|
+
tracker.lastSurface = tracker.calls;
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
/**
|
|
354
|
+
* The one-line steer: the work area and a pointer back at the catalog in the
|
|
355
|
+
* prompt. `readRoot` empty (several packs, see skillReadRoot) drops the path
|
|
356
|
+
* clause instead of naming a path that may not resolve.
|
|
357
|
+
*/
|
|
358
|
+
export function driftPayload(directory: string, readRoot: string): string {
|
|
359
|
+
const pointer = readRoot
|
|
360
|
+
? `read \`${readRoot}/<name>/SKILL.md\``
|
|
361
|
+
: `read the matching skill's SKILL.md`;
|
|
362
|
+
return `[SKILL INDEX] work is in ${directory}. Catalog above; ${pointer}.`;
|
|
89
363
|
}
|
|
@@ -49,6 +49,7 @@ import errorCaptureFn from "./self/error-tracking/index.js";
|
|
|
49
49
|
import watchdogFn from "./self/watchdog/index.js";
|
|
50
50
|
import autoRecoveryFn from "./self/auto-recovery/index.js";
|
|
51
51
|
import latentActivatorFn from "./self/latent-activator/index.js";
|
|
52
|
+
import pathMissFn from "./self/path-miss/index.js";
|
|
52
53
|
|
|
53
54
|
// enforcement (turn pipeline: handlers, detection, substate)
|
|
54
55
|
import enforcementFn from "./enforcement/index.js";
|
|
@@ -224,6 +225,11 @@ export const MANIFEST: ManifestEntry[] = [
|
|
|
224
225
|
fn: latentActivatorFn,
|
|
225
226
|
desc: "Latent behavior activator",
|
|
226
227
|
},
|
|
228
|
+
{
|
|
229
|
+
id: "path-miss",
|
|
230
|
+
fn: pathMissFn,
|
|
231
|
+
desc: "Path-miss steer — name the listing that answers a missing path",
|
|
232
|
+
},
|
|
227
233
|
|
|
228
234
|
// Watchdog (default-ON — liveness/stall state machine)
|
|
229
235
|
// Default-ON per TG-HEARTBEAT-WATCHDOG-DESIGN.md ("default ON, NO new env
|
|
@@ -14,11 +14,12 @@ because they're specialized tools the user enables when they want them.
|
|
|
14
14
|
| `watchdog/` | (TUI command) | Passive session monitor: uptime, idle time, message count. No LLM tool. |
|
|
15
15
|
| `auto-recovery/` | (whisper-only) | On turn_start, checks for system degradation and suggests recovery. |
|
|
16
16
|
| `latent-activator/` | `behavior` | Activates atomic behavior modes (planner, executor, reviewer, etc). |
|
|
17
|
+
| `path-miss/` | (whisper-only) | On a tool result that missed a path, names the listing that finds it. |
|
|
17
18
|
|
|
18
19
|
## Local Contracts
|
|
19
20
|
|
|
20
21
|
- Most are **opt-in** (`disabledByDefault: true` in the manifest).
|
|
21
|
-
- `auto-recovery` and `
|
|
22
|
+
- `auto-recovery`, `latent-activator` and `path-miss` are always-on.
|
|
22
23
|
- These extensions manipulate the agent's own state, not external state.
|
|
23
24
|
|
|
24
25
|
## Distinction from related categories
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
<!-- status: current -->
|
|
2
|
+
|
|
3
|
+
# src/extensions/self/path-miss/ - Path-Miss Steer
|
|
4
|
+
|
|
5
|
+
When a tool result reports a missing path, one whisper says which move would
|
|
6
|
+
have found it. The failure is the moment the cheaper instrument is obvious;
|
|
7
|
+
without it the agent guesses again.
|
|
8
|
+
|
|
9
|
+
## Files
|
|
10
|
+
|
|
11
|
+
| File | Purpose |
|
|
12
|
+
| ----------- | ---------------------------------------------------------------------------------------------------- |
|
|
13
|
+
| `index.ts` | The emitter: subscribes to tool results, holds the budget, sends through `sendTrackedMessage`. |
|
|
14
|
+
| `detect.ts` | Recognises a missing-path failure and names the path. Pure: no state, no delivery, no extension API. |
|
|
15
|
+
|
|
16
|
+
## Local Contracts
|
|
17
|
+
|
|
18
|
+
- **One line per turn, at most one line per path per session.** The turn flag
|
|
19
|
+
is reset by the `input` handler (the same boundary the whisper family uses);
|
|
20
|
+
the per-path set is keyed on the session id and bounded.
|
|
21
|
+
- **No new event registration.** The emitter rides pi's existing `tool_result`
|
|
22
|
+
event, the only seat that carries both the failure text and the call's own
|
|
23
|
+
arguments - the call's `path` is stronger evidence than a parse of the
|
|
24
|
+
message.
|
|
25
|
+
- **Delivered as a live steer** (`delivery: "live"`), so it reaches a running
|
|
26
|
+
loop and never wakes one by itself.
|
|
27
|
+
- **A suppressed send does not spend the path's budget.** If the whisper funnel
|
|
28
|
+
drops the line, the path stays steerable.
|
|
29
|
+
- **Only a missing path is a path miss.** `EACCES`, an unreadable file and a
|
|
30
|
+
failed assertion each call for a different next move.
|
|
31
|
+
- Tool coverage: `read`, `edit`, `write`, `bash`. A failure from any other tool
|
|
32
|
+
is not classified, whatever its text says.
|
|
33
|
+
|
|
34
|
+
## Related modules
|
|
35
|
+
|
|
36
|
+
- `lib/utils/injection-tracker.ts` - `sendTrackedMessage`, the delivery trunk
|
|
37
|
+
(envelope, flood cap, delivery class).
|
|
38
|
+
- `extensions/self/auto-recovery/` and `extensions/self/watchdog/` - the
|
|
39
|
+
neighbouring whisper emitters.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Recognition of a missing-path tool failure, and the path it names.
|
|
3
|
+
*
|
|
4
|
+
* The shapes below are the ones the tools actually emit on this platform,
|
|
5
|
+
* measured rather than invented:
|
|
6
|
+
*
|
|
7
|
+
* read ENOENT: no such file or directory, access '/x/y.ts'
|
|
8
|
+
* edit Could not edit file: /x/y.ts. Error code: ENOENT.
|
|
9
|
+
* bash ls: /x/y: No such file or directory
|
|
10
|
+
* bash /bin/bash: line 0: cd: /x/y: No such file or directory
|
|
11
|
+
*
|
|
12
|
+
* Two of those carry a usable path in the call and the rest only in the text,
|
|
13
|
+
* so the call wins when it has one: a path the model asked for is the path the
|
|
14
|
+
* whisper should name, even when the tool's own wording echoes it loosely.
|
|
15
|
+
*
|
|
16
|
+
* Only a missing path is a path miss. A permission error, an unreadable file
|
|
17
|
+
* or a failed assertion is a different failure with a different next move, and
|
|
18
|
+
* steering toward `ls` there would cost a call without teaching anything.
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
/** Tools whose failure can mean "the path was a guess". */
|
|
22
|
+
const PATH_BEARING_TOOLS = new Set(["read", "edit", "write", "bash"]);
|
|
23
|
+
|
|
24
|
+
/** The two spellings of "this path is not there" the tools emit. */
|
|
25
|
+
const MISSING_PATH = /ENOENT|no such file or directory/i;
|
|
26
|
+
|
|
27
|
+
/** A path quoted by a Node error: `ENOENT: ..., access '/x/y'`. */
|
|
28
|
+
const QUOTED_AFTER_SYSCALL =
|
|
29
|
+
/\b(?:access|open|stat|lstat|scandir|opendir|unlink|readlink)\s+'([^']+)'/;
|
|
30
|
+
|
|
31
|
+
/** A shell builtin naming the directory it could not enter. */
|
|
32
|
+
const BASH_CD_TARGET = /(?:^|[:\s])cd:\s+(.+?):\s*no such file/i;
|
|
33
|
+
|
|
34
|
+
/** A program naming the operand it could not find: `ls: /x/y: No such file`. */
|
|
35
|
+
const PROGRAM_OPERAND = /([^\s:]+):\s*no such file or directory/i;
|
|
36
|
+
|
|
37
|
+
/** A bare errno (`ENOENT`), not a path. */
|
|
38
|
+
const ERRNO_ONLY = /^[A-Z][A-Z0-9_]*$/;
|
|
39
|
+
|
|
40
|
+
export interface PathMiss {
|
|
41
|
+
/** The tool whose call missed. */
|
|
42
|
+
tool: string;
|
|
43
|
+
/** The path that was not there, as the tool or the call reported it. */
|
|
44
|
+
path: string;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** The path the call itself asked for, when the tool takes one. */
|
|
48
|
+
function pathFromCall(input: unknown): string | undefined {
|
|
49
|
+
if (!input || typeof input !== "object") return undefined;
|
|
50
|
+
const path = (input as { path?: unknown }).path;
|
|
51
|
+
return typeof path === "string" && path.length > 0 ? path : undefined;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** The path an error message names, when the call did not carry one. */
|
|
55
|
+
function pathFromText(text: string): string | undefined {
|
|
56
|
+
const candidates = [
|
|
57
|
+
QUOTED_AFTER_SYSCALL.exec(text)?.[1],
|
|
58
|
+
BASH_CD_TARGET.exec(text)?.[1],
|
|
59
|
+
PROGRAM_OPERAND.exec(text)?.[1],
|
|
60
|
+
];
|
|
61
|
+
for (const candidate of candidates) {
|
|
62
|
+
const path = candidate?.trim();
|
|
63
|
+
if (!path || ERRNO_ONLY.test(path)) continue;
|
|
64
|
+
return path;
|
|
65
|
+
}
|
|
66
|
+
return undefined;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* The path a failed call missed, or null when this result is not a path miss.
|
|
71
|
+
*/
|
|
72
|
+
export function detectPathMiss(toolName: string, input: unknown, text: string): PathMiss | null {
|
|
73
|
+
if (!PATH_BEARING_TOOLS.has(toolName)) return null;
|
|
74
|
+
if (!text || !MISSING_PATH.test(text)) return null;
|
|
75
|
+
const path = pathFromCall(input) ?? pathFromText(text);
|
|
76
|
+
if (!path) return null;
|
|
77
|
+
return { tool: toolName, path };
|
|
78
|
+
}
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Path-miss steer — the tool failure that says what would have worked.
|
|
3
|
+
*
|
|
4
|
+
* A turn that guesses paths spends calls discovering a layout a listing would
|
|
5
|
+
* have named. The failure itself is the one moment the cheaper move is
|
|
6
|
+
* obvious, so it is where the line belongs: one steer per turn, the path that
|
|
7
|
+
* missed, and the three instruments that answer it (`ls`, `find`,
|
|
8
|
+
* `explore_paths`).
|
|
9
|
+
*
|
|
10
|
+
* Delivery is the standard whisper funnel (`sendTrackedMessage`), so this
|
|
11
|
+
* emitter inherits the envelope, the flood cap and the live-steer resolution
|
|
12
|
+
* every other whisper uses. The event is pi's existing `tool_result`, the only
|
|
13
|
+
* seat that carries both the failure text and the arguments the call made —
|
|
14
|
+
* the call's own `path` is more reliable than parsing the error wording.
|
|
15
|
+
*
|
|
16
|
+
* Budget: one line per turn, at most one line per path per session. A path
|
|
17
|
+
* already steered is not steered again, because a repeat tells the agent
|
|
18
|
+
* nothing it was not told, and the second occurrence usually means the agent
|
|
19
|
+
* chose to proceed rather than that it failed to read.
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
import { dirname } from "node:path";
|
|
23
|
+
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
24
|
+
import { createLogger } from "../../../lib/core/logger.js";
|
|
25
|
+
import { INPUT, TOOL_RESULT } from "../../../lib/core/event-names.js";
|
|
26
|
+
import { sendTrackedMessage } from "../../../lib/utils/injection-tracker.js";
|
|
27
|
+
import { detectPathMiss } from "./detect.js";
|
|
28
|
+
|
|
29
|
+
const log = createLogger("path-miss");
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Sessions whose steered paths are remembered. A session id is stable for the
|
|
33
|
+
* life of a session and a long-lived process can host more than one, so the
|
|
34
|
+
* map is bounded rather than trusted to stay small.
|
|
35
|
+
*/
|
|
36
|
+
const MAX_TRACKED_SESSIONS = 16;
|
|
37
|
+
|
|
38
|
+
/** Paths already steered, per session. */
|
|
39
|
+
const steeredPaths = new Map<string, Set<string>>();
|
|
40
|
+
|
|
41
|
+
/** Turn-scoped: the first path miss of a turn is the one worth a line. */
|
|
42
|
+
let steeredThisTurn = false;
|
|
43
|
+
|
|
44
|
+
function sessionKey(ctx: ExtensionContext | undefined): string {
|
|
45
|
+
const manager = ctx?.sessionManager as
|
|
46
|
+
| { getSessionId?: () => string; getSessionFile?: () => string | undefined }
|
|
47
|
+
| undefined;
|
|
48
|
+
return manager?.getSessionId?.() ?? manager?.getSessionFile?.() ?? "unknown";
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
function remember(session: string, path: string): void {
|
|
52
|
+
const paths = steeredPaths.get(session) ?? new Set<string>();
|
|
53
|
+
paths.add(path);
|
|
54
|
+
steeredPaths.set(session, paths);
|
|
55
|
+
if (steeredPaths.size > MAX_TRACKED_SESSIONS) {
|
|
56
|
+
// Insertion order: the oldest session is the first key.
|
|
57
|
+
const oldest = steeredPaths.keys().next().value;
|
|
58
|
+
if (oldest !== undefined && oldest !== session) steeredPaths.delete(oldest);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
function alreadySteered(session: string, path: string): boolean {
|
|
63
|
+
return steeredPaths.get(session)?.has(path) ?? false;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** The error text of a tool result, with any non-text parts ignored. */
|
|
67
|
+
function resultText(content: unknown): string {
|
|
68
|
+
if (typeof content === "string") return content;
|
|
69
|
+
if (!Array.isArray(content)) return "";
|
|
70
|
+
return content
|
|
71
|
+
.map((part) =>
|
|
72
|
+
part && typeof part === "object" && typeof (part as { text?: unknown }).text === "string"
|
|
73
|
+
? (part as { text: string }).text
|
|
74
|
+
: "",
|
|
75
|
+
)
|
|
76
|
+
.join("\n");
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* One line: the path, and the cheaper moves next to it.
|
|
81
|
+
*
|
|
82
|
+
* The parent is named when the path has one, because `ls` needs an operand and
|
|
83
|
+
* a model that guessed a leaf usually had the parent wrong too — listing the
|
|
84
|
+
* parent is what tells it which of the two it got wrong.
|
|
85
|
+
*/
|
|
86
|
+
export function pathMissLine(path: string): string {
|
|
87
|
+
const parent = dirname(path);
|
|
88
|
+
const listing = parent && parent !== "." && parent !== "/" ? `ls ${parent}` : "ls on its parent";
|
|
89
|
+
return `path miss: ${path} — ${listing} names the layout in one call; find and explore_paths when the parent is unknown too`;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** Test hook: forget every steered path and the current turn's budget. */
|
|
93
|
+
export function _resetForTests(): void {
|
|
94
|
+
steeredPaths.clear();
|
|
95
|
+
steeredThisTurn = false;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
export default function pathMissExtension(pi: ExtensionAPI): void {
|
|
99
|
+
// The same turn boundary the whisper family uses: a new user input opens a
|
|
100
|
+
// new turn, and a turn that has already been steered is done.
|
|
101
|
+
pi.on(INPUT, () => {
|
|
102
|
+
steeredThisTurn = false;
|
|
103
|
+
});
|
|
104
|
+
|
|
105
|
+
pi.on(TOOL_RESULT, (event, ctx) => {
|
|
106
|
+
if (steeredThisTurn) return;
|
|
107
|
+
if (!event?.isError) return;
|
|
108
|
+
const miss = detectPathMiss(event.toolName, event.input, resultText(event.content));
|
|
109
|
+
if (!miss) return;
|
|
110
|
+
|
|
111
|
+
const session = sessionKey(ctx);
|
|
112
|
+
if (alreadySteered(session, miss.path)) return;
|
|
113
|
+
|
|
114
|
+
steeredThisTurn = true;
|
|
115
|
+
const delivered = sendTrackedMessage(
|
|
116
|
+
pi,
|
|
117
|
+
{
|
|
118
|
+
customType: "path-miss",
|
|
119
|
+
content: [{ type: "text" as const, text: pathMissLine(miss.path) }],
|
|
120
|
+
display: true,
|
|
121
|
+
},
|
|
122
|
+
{ delivery: "live" },
|
|
123
|
+
{ type: "enforcement", source: "path-miss/steer" },
|
|
124
|
+
);
|
|
125
|
+
// A suppressed send must not spend the path's budget: the line did not
|
|
126
|
+
// arrive, so the next turn is still the first place the agent can read it.
|
|
127
|
+
if (!delivered) {
|
|
128
|
+
steeredThisTurn = false;
|
|
129
|
+
log.debug(`[path-miss] suppressed by the whisper funnel: ${miss.path}`);
|
|
130
|
+
return;
|
|
131
|
+
}
|
|
132
|
+
remember(session, miss.path);
|
|
133
|
+
log.debug(`[path-miss] steered ${miss.path} (${miss.tool})`);
|
|
134
|
+
});
|
|
135
|
+
}
|
|
@@ -23,6 +23,7 @@ export const MESSAGE_START = "message_start" as const;
|
|
|
23
23
|
export const MESSAGE_END = "message_end" as const;
|
|
24
24
|
export const TOOL_EXECUTION_START = "tool_execution_start" as const;
|
|
25
25
|
export const TOOL_EXECUTION_END = "tool_execution_end" as const;
|
|
26
|
+
export const TOOL_RESULT = "tool_result" as const;
|
|
26
27
|
export const AGENT_SETTLED = "agent_settled" as const;
|
|
27
28
|
|
|
28
29
|
// ── Extension Communication ─────────────────────────────────────────────────
|