pi-braid 0.41.1 → 0.42.0
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/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/loading-guidance.d.ts +149 -28
- package/dist/extensions/core/skills-tool/loading-guidance.js +257 -29
- package/docs/FLEET.md +21 -0
- package/docs/LOCAL_DEV.md +1 -1
- package/docs/SETUP.md +1 -1
- package/package.json +2 -2
- package/scripts/fleet/journal.mjs +55 -1
- package/scripts/fleet/tool-guard.mjs +1 -2
- 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/loading-guidance.ts +303 -29
|
@@ -1,38 +1,129 @@
|
|
|
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.
|
|
37
|
+
*/
|
|
38
|
+
import { isAbsolute, relative, resolve, sep } from "node:path";
|
|
39
|
+
/**
|
|
40
|
+
* Paragraph 1: what the catalog is, where the bodies live, and the obligation.
|
|
41
|
+
*
|
|
42
|
+
* `readRoot` is the single pack directory the rule can state; `grouped` says
|
|
43
|
+
* the rows are rendered under directory headings instead, so the rule points
|
|
44
|
+
* at the heading rather than at a root that does not exist. Neither given (a
|
|
45
|
+
* catalog whose bodies carry no pack) leaves the location unstated, which is
|
|
46
|
+
* the honest answer when the paths cannot be derived.
|
|
23
47
|
*/
|
|
24
|
-
|
|
25
|
-
|
|
48
|
+
export function skillsCatalogRule(readRoot, grouped = false) {
|
|
49
|
+
const readPath = readRoot
|
|
50
|
+
? ` Each row's body is at \`${readRoot}/<name>/SKILL.md\`.`
|
|
51
|
+
: grouped
|
|
52
|
+
? ` Each row's body is at \`<dir>/<name>/SKILL.md\`, where \`<dir>\` is the row's directory heading.`
|
|
53
|
+
: "";
|
|
54
|
+
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.`;
|
|
55
|
+
}
|
|
26
56
|
/** Paragraph 2: the pointer rule (pinned verbatim by test-prompt-budget.mjs). */
|
|
27
|
-
export const SKILLS_POINTER_RULE = `Pointer rule: the catalog one-liner is metadata, not content — the SKILL.md path is the knowledge.
|
|
57
|
+
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.`;
|
|
28
58
|
const MECHANICAL_TRIGGER_LEAD = `Mechanical trigger, no judgment call: about to use a tool family whose word appears in a skill's name`;
|
|
29
59
|
const MECHANICAL_TRIGGER_TAIL = `→ read that SKILL.md before the first call in the family.`;
|
|
60
|
+
/** Forward-slash form of a path, for segment arithmetic on either platform. */
|
|
61
|
+
function toSlashes(path) {
|
|
62
|
+
return path.replace(/\\/g, "/");
|
|
63
|
+
}
|
|
64
|
+
/** Sorted by name, byte-comparison so the order never depends on the locale. */
|
|
65
|
+
function byName(a, b) {
|
|
66
|
+
return a < b ? -1 : a > b ? 1 : 0;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* The pack directory a skill's body sits in. pi's layout is
|
|
70
|
+
* `<pack>/<skill-name>/SKILL.md`, so the pack is two levels above the file;
|
|
71
|
+
* the row's stated path is `<pack>/<name>/SKILL.md`. A path too short to have
|
|
72
|
+
* a pack reports "", and its group renders without a heading.
|
|
73
|
+
*/
|
|
74
|
+
function packOf(filePath) {
|
|
75
|
+
const parts = toSlashes(filePath ?? "").split("/");
|
|
76
|
+
if (parts.length < 3)
|
|
77
|
+
return "";
|
|
78
|
+
return parts.slice(0, -2).join("/");
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* File the entries by the pack their own SKILL.md lives in: the braid pack
|
|
82
|
+
* plus the user-global directory is two groups in one catalog. Groups and
|
|
83
|
+
* rows are sorted, so identical catalogs render byte-identical text in any
|
|
84
|
+
* cache order. Pure.
|
|
85
|
+
*/
|
|
86
|
+
export function catalogGroups(skills) {
|
|
87
|
+
const byDir = new Map();
|
|
88
|
+
for (const skill of skills) {
|
|
89
|
+
const dir = packOf(skill.filePath ?? "");
|
|
90
|
+
const bucket = byDir.get(dir);
|
|
91
|
+
if (bucket)
|
|
92
|
+
bucket.push(skill);
|
|
93
|
+
else
|
|
94
|
+
byDir.set(dir, [skill]);
|
|
95
|
+
}
|
|
96
|
+
return [...byDir.keys()].sort(byName).map((dir) => ({ dir, skills: byDir.get(dir) ?? [] }));
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* The one directory every entry lives under, or "" when they do not share
|
|
100
|
+
* one: a single root is a fact a caller may state, and a common ancestor of
|
|
101
|
+
* two packs is not. Pure.
|
|
102
|
+
*/
|
|
103
|
+
export function skillReadRoot(skills) {
|
|
104
|
+
const groups = catalogGroups(skills);
|
|
105
|
+
return groups.length === 1 ? groups[0].dir : "";
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* One row per skill: `- name: description`, whitespace collapsed to a single
|
|
109
|
+
* line. Descriptions are NOT clipped: the row is the whole reason the floor
|
|
110
|
+
* works, and a clipped description is what a model would have to guess from.
|
|
111
|
+
* Pure.
|
|
112
|
+
*/
|
|
113
|
+
export function catalogRows(skills) {
|
|
114
|
+
return [...skills]
|
|
115
|
+
.sort((a, b) => byName(a.name, b.name))
|
|
116
|
+
.map((s) => {
|
|
117
|
+
const description = (s.description ?? "").replace(/\s+/g, " ").trim();
|
|
118
|
+
return description ? `- ${s.name}: ${description}` : `- ${s.name}`;
|
|
119
|
+
});
|
|
120
|
+
}
|
|
30
121
|
/**
|
|
31
122
|
* Worked examples for the mechanical trigger, derived from the live inputs.
|
|
32
123
|
*
|
|
33
124
|
* A pair exists when a tool's family token (the first underscore-delimited
|
|
34
|
-
* token of the tool name: `
|
|
35
|
-
* token of a skill name (`
|
|
125
|
+
* token of the tool name: `widget_open` → `widget`) equals a dash-delimited
|
|
126
|
+
* token of a skill name (`widget-map` → `widget`), case-insensitively.
|
|
36
127
|
* One example renders per distinct family token: the trigger fires per
|
|
37
128
|
* family ("before the first call in the family"), so enumerating every tool
|
|
38
129
|
* in a family would restate one fact; the representative tool is the
|
|
@@ -72,16 +163,153 @@ export function mechanicalTriggerExamples(toolNames, skillNames) {
|
|
|
72
163
|
.map(([family, { casing }]) => `\`${familyTool.get(family)}\` → ${casing}`);
|
|
73
164
|
}
|
|
74
165
|
/**
|
|
75
|
-
* The full skills-loading
|
|
76
|
-
*
|
|
77
|
-
*
|
|
78
|
-
*
|
|
166
|
+
* The full skills-loading section: catalog rule (with the derived read path),
|
|
167
|
+
* pointer rule, one row per visible skill, and the mechanical trigger with
|
|
168
|
+
* only the pairs computed from the given tool and skill names.
|
|
169
|
+
*
|
|
170
|
+
* prompt-builder feeds it the active tool names and the skills-tool module's
|
|
171
|
+
* visible catalog. An empty catalog renders no section: the floor is a
|
|
172
|
+
* catalog, and a section claiming to list every skill while listing none
|
|
173
|
+
* would be a lie the model has no way to check.
|
|
174
|
+
*
|
|
175
|
+
* One pack renders its root in the rule; several packs render a directory
|
|
176
|
+
* heading before each group of rows, because no single root describes them.
|
|
79
177
|
*/
|
|
80
|
-
export function skillsLoadingText(toolNames,
|
|
81
|
-
|
|
178
|
+
export function skillsLoadingText(toolNames, skills) {
|
|
179
|
+
if (!skills.length)
|
|
180
|
+
return "";
|
|
181
|
+
const examples = mechanicalTriggerExamples(toolNames, skills.map((s) => s.name));
|
|
82
182
|
const trigger = examples.length > 0
|
|
83
183
|
? `${MECHANICAL_TRIGGER_LEAD} (${examples.join(", ")}) ${MECHANICAL_TRIGGER_TAIL}`
|
|
84
184
|
: `${MECHANICAL_TRIGGER_LEAD} ${MECHANICAL_TRIGGER_TAIL}`;
|
|
85
|
-
|
|
185
|
+
const groups = catalogGroups(skills);
|
|
186
|
+
const grouped = groups.length > 1;
|
|
187
|
+
const rows = grouped
|
|
188
|
+
? groups
|
|
189
|
+
.map((g) => g.dir
|
|
190
|
+
? `${g.dir}\n${catalogRows(g.skills).join("\n")}`
|
|
191
|
+
: catalogRows(g.skills).join("\n"))
|
|
192
|
+
.join("\n\n")
|
|
193
|
+
: catalogRows(groups[0].skills).join("\n");
|
|
194
|
+
return `${skillsCatalogRule(skillReadRoot(skills), grouped)}\n\n${SKILLS_POINTER_RULE}\n\n${rows}\n\n${trigger}\n`;
|
|
195
|
+
}
|
|
196
|
+
// Drift trigger
|
|
197
|
+
//
|
|
198
|
+
// The floor is a snapshot: the catalog does not change mid-session, but the
|
|
199
|
+
// work does. A session that starts in one directory and moves to another has
|
|
200
|
+
// its catalog in view and its task text elsewhere, which is the same silent
|
|
201
|
+
// prompt the floor exists for. The trigger watches where the path-taking
|
|
202
|
+
// tools actually write and reads, and when a new directory accumulates
|
|
203
|
+
// entries it says so in one line, pointing back at the catalog.
|
|
204
|
+
//
|
|
205
|
+
// Bounds, all deliberate:
|
|
206
|
+
// - two entries in one directory before it counts: a single stray read is
|
|
207
|
+
// not where the work is.
|
|
208
|
+
// - at most one fire per DRIFT_WINDOW_CALLS tool calls, and quiet for the
|
|
209
|
+
// same window after any skill surface (a suggestion or a SKILL.md read),
|
|
210
|
+
// because a surface that just landed is the pointer the trigger exists to
|
|
211
|
+
// supply.
|
|
212
|
+
// - at most DRIFT_MAX_FIRES per session, so the line stays a signal.
|
|
213
|
+
// - a directory is announced once; the entry counts restart after a fire,
|
|
214
|
+
// so the budget is spent on directories the session has not been told
|
|
215
|
+
// about.
|
|
216
|
+
// - paths with fewer than two directory segments are ignored: repo-root
|
|
217
|
+
// files and top-level directories are where a session starts, not where
|
|
218
|
+
// it moved to.
|
|
219
|
+
/** The path-taking tools whose calls describe where the work is. */
|
|
220
|
+
export const DRIFT_PATH_TOOLS = ["read", "edit", "write"];
|
|
221
|
+
/** Tool calls that must pass between fires, and after any skill surface. */
|
|
222
|
+
export const DRIFT_WINDOW_CALLS = 12;
|
|
223
|
+
/** Fires per session. */
|
|
224
|
+
export const DRIFT_MAX_FIRES = 3;
|
|
225
|
+
/** Entries in one directory before it counts as where the work is. */
|
|
226
|
+
export const DRIFT_ENTRIES = 2;
|
|
227
|
+
/** Directory segments a path must carry before it can name a work area. */
|
|
228
|
+
export const DRIFT_MIN_SEGMENTS = 2;
|
|
229
|
+
/** Fresh drift state for a session. */
|
|
230
|
+
export function initialDrift() {
|
|
231
|
+
return { calls: 0, lastFire: null, fires: 0, lastSurface: null, entries: {}, announced: [] };
|
|
232
|
+
}
|
|
233
|
+
/**
|
|
234
|
+
* The work area a finished tool call touched: the first two directory
|
|
235
|
+
* segments of its path, relative to the session's project root. Undefined for
|
|
236
|
+
* a tool that takes no path, a path outside the project, and a path with
|
|
237
|
+
* fewer than DRIFT_MIN_SEGMENTS directories. Pure.
|
|
238
|
+
*/
|
|
239
|
+
export function driftDirectoryFor(toolName, inputPath, cwd) {
|
|
240
|
+
if (!toolName || !DRIFT_PATH_TOOLS.includes(toolName))
|
|
241
|
+
return undefined;
|
|
242
|
+
if (!inputPath || !cwd)
|
|
243
|
+
return undefined;
|
|
244
|
+
const root = resolve(cwd);
|
|
245
|
+
const absolute = isAbsolute(inputPath) ? resolve(inputPath) : resolve(root, inputPath);
|
|
246
|
+
const inside = relative(root, absolute);
|
|
247
|
+
const segments = inside.split(sep).filter(Boolean);
|
|
248
|
+
if (!segments.length || segments[0] === "..")
|
|
249
|
+
return undefined;
|
|
250
|
+
const directories = segments.slice(0, -1);
|
|
251
|
+
if (directories.length < DRIFT_MIN_SEGMENTS)
|
|
252
|
+
return undefined;
|
|
253
|
+
return directories.slice(0, DRIFT_MIN_SEGMENTS).join("/");
|
|
254
|
+
}
|
|
255
|
+
/**
|
|
256
|
+
* Count one finished tool call and answer whether it is a fire.
|
|
257
|
+
*
|
|
258
|
+
* Returns the work area to announce, or null. The caller fires the line and
|
|
259
|
+
* then calls recordDriftFire (on delivery) or recordDriftDrop (when the
|
|
260
|
+
* whisper was suppressed), so a dropped line never spends the budget. The
|
|
261
|
+
* tracker is the session's own mutable state; the answer is a pure function
|
|
262
|
+
* of its contents.
|
|
263
|
+
*/
|
|
264
|
+
export function advanceDrift(tracker, directory) {
|
|
265
|
+
tracker.calls++;
|
|
266
|
+
if (!directory)
|
|
267
|
+
return null;
|
|
268
|
+
if (tracker.fires >= DRIFT_MAX_FIRES)
|
|
269
|
+
return null;
|
|
270
|
+
const entries = (tracker.entries[directory] ?? 0) + 1;
|
|
271
|
+
tracker.entries[directory] = entries;
|
|
272
|
+
if (entries < DRIFT_ENTRIES)
|
|
273
|
+
return null;
|
|
274
|
+
if (tracker.announced.includes(directory))
|
|
275
|
+
return null;
|
|
276
|
+
if (tracker.lastFire !== null && tracker.calls - tracker.lastFire < DRIFT_WINDOW_CALLS)
|
|
277
|
+
return null;
|
|
278
|
+
if (tracker.lastSurface !== null && tracker.calls - tracker.lastSurface < DRIFT_WINDOW_CALLS) {
|
|
279
|
+
return null;
|
|
280
|
+
}
|
|
281
|
+
return directory;
|
|
282
|
+
}
|
|
283
|
+
/** Mark a fire at the current call: spends one fire, announces, restarts counts. */
|
|
284
|
+
export function recordDriftFire(tracker, directory) {
|
|
285
|
+
tracker.fires++;
|
|
286
|
+
tracker.lastFire = tracker.calls;
|
|
287
|
+
if (!tracker.announced.includes(directory))
|
|
288
|
+
tracker.announced.push(directory);
|
|
289
|
+
tracker.entries = {};
|
|
290
|
+
}
|
|
291
|
+
/**
|
|
292
|
+
* Mark a fire attempt whose whisper was suppressed: no fire is spent and the
|
|
293
|
+
* directory is not announced, but the counts restart and the window opens, so
|
|
294
|
+
* a suppressed line is retried only after the session has done more work.
|
|
295
|
+
*/
|
|
296
|
+
export function recordDriftDrop(tracker) {
|
|
297
|
+
tracker.lastFire = tracker.calls;
|
|
298
|
+
tracker.entries = {};
|
|
299
|
+
}
|
|
300
|
+
/** Note that a skill surface (a suggestion or a SKILL.md read) just landed. */
|
|
301
|
+
export function noteDriftSurface(tracker) {
|
|
302
|
+
tracker.lastSurface = tracker.calls;
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* The one-line steer: the work area and a pointer back at the catalog in the
|
|
306
|
+
* prompt. `readRoot` empty (several packs, see skillReadRoot) drops the path
|
|
307
|
+
* clause instead of naming a path that may not resolve.
|
|
308
|
+
*/
|
|
309
|
+
export function driftPayload(directory, readRoot) {
|
|
310
|
+
const pointer = readRoot
|
|
311
|
+
? `read \`${readRoot}/<name>/SKILL.md\``
|
|
312
|
+
: `read the matching skill's SKILL.md`;
|
|
313
|
+
return `[SKILL INDEX] work is in ${directory}. Catalog above; ${pointer}.`;
|
|
86
314
|
}
|
|
87
315
|
//# sourceMappingURL=loading-guidance.js.map
|
package/docs/FLEET.md
CHANGED
|
@@ -115,6 +115,27 @@ Opening an older store migrates it and records the new version, and the previous
|
|
|
115
115
|
build keeps its access: a rollback can open and write a store this build created,
|
|
116
116
|
because the column it needs was kept rather than dropped.
|
|
117
117
|
|
|
118
|
+
## Node versions
|
|
119
|
+
|
|
120
|
+
The journal is reached through one module,
|
|
121
|
+
[`../scripts/fleet/journal.mjs`](../scripts/fleet/journal.mjs), which is also
|
|
122
|
+
where the fleet answers what importing SQLite costs. `node:sqlite` says it is
|
|
123
|
+
experimental on stderr, once per process, at the import: true of every 24 release
|
|
124
|
+
before 24.15, and no longer true from 24.15, where the module became a release
|
|
125
|
+
candidate and stopped saying it. The floor `engines` declares is 24.0.0, so the
|
|
126
|
+
answer is installed at that import - the warning withheld by its own type and
|
|
127
|
+
text, for the length of the import only, with the emitter restored in a `finally`
|
|
128
|
+
so a warning from any other module still reaches stderr. It is not done with
|
|
129
|
+
`--disable-warning` or `NODE_OPTIONS`, which remove the whole
|
|
130
|
+
`ExperimentalWarning` class for the process and hide those along with it, and it
|
|
131
|
+
cannot be done with a `warning` listener at all - Node's default printer is
|
|
132
|
+
registered by the runtime and prints whether or not another listener exists.
|
|
133
|
+
|
|
134
|
+
Both workflows run Node 24, the line `engines` declares, so the gate that reports
|
|
135
|
+
red and the gate that decides a release see the same runtime. The answer costs
|
|
136
|
+
nothing on 24.15 and above, and goes with its test once the whole supported line
|
|
137
|
+
is past it.
|
|
138
|
+
|
|
118
139
|
## Where the code is
|
|
119
140
|
|
|
120
141
|
| File | What it owns |
|
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -11,7 +11,7 @@ For one-time setup, the full install-path catalog, and module toggling see
|
|
|
11
11
|
|
|
12
12
|
| Tool | Version | Verify |
|
|
13
13
|
| ---- | ------------- | -------------------------- |
|
|
14
|
-
| Node | ≥
|
|
14
|
+
| Node | ≥ 24.0 | `node --version` |
|
|
15
15
|
| npm | bundled | `npm --version` |
|
|
16
16
|
| git | any | `git --version` |
|
|
17
17
|
| pi | peer-resolved | `which pi && pi --version` |
|
package/docs/SETUP.md
CHANGED
|
@@ -26,7 +26,7 @@ Complete reference for installing braid, configuring pi to load it, enabling com
|
|
|
26
26
|
|
|
27
27
|
| Tool | Version | Verify |
|
|
28
28
|
| --------------- | ------------- | -------------------------- |
|
|
29
|
-
| Node.js | ≥
|
|
29
|
+
| Node.js | ≥ 24.0 | `node --version` |
|
|
30
30
|
| pi-coding-agent | peer-resolved | `which pi && pi --version` |
|
|
31
31
|
| npm | bundled | `npm --version` |
|
|
32
32
|
| git | any recent | `git --version` |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.42.0",
|
|
4
4
|
"description": "Metacognitive extension suite for pi-coding-agent: enforcement, memory, reasoning, self-improvement, and structured cognitive signals.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -102,6 +102,6 @@
|
|
|
102
102
|
"author": "kifirkin",
|
|
103
103
|
"license": "MIT",
|
|
104
104
|
"engines": {
|
|
105
|
-
"node": ">=
|
|
105
|
+
"node": ">=24.0.0"
|
|
106
106
|
}
|
|
107
107
|
}
|
|
@@ -25,7 +25,61 @@
|
|
|
25
25
|
import { createHash } from "node:crypto";
|
|
26
26
|
import { mkdirSync } from "node:fs";
|
|
27
27
|
import { dirname, isAbsolute, join, resolve } from "node:path";
|
|
28
|
-
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* The fleet's only way in to SQLite, and the answer to what its import costs.
|
|
31
|
+
*
|
|
32
|
+
* `node:sqlite` says it is experimental on stderr, once per process, at the moment
|
|
33
|
+
* it is imported: true of every 24 release up to 24.14, and no longer true from
|
|
34
|
+
* 24.15, where the module became a release candidate and the warning stopped
|
|
35
|
+
* (measured: 24.0.0 and 24.14.0 warn, 24.15.0 and 24.22.1 are silent). The floor
|
|
36
|
+
* `engines` declares is 24.0.0, so without this block a user on the floor meets a
|
|
37
|
+
* warning nobody documented, and every command that asserts an empty stderr - the
|
|
38
|
+
* fleet's own arms among them - fails on a healthy run. Once Node's whole supported
|
|
39
|
+
* line is past 24.15 this block answers nothing and can be deleted with its test.
|
|
40
|
+
*
|
|
41
|
+
* Every process that opens a journal pays it: the four commands, the supervisor
|
|
42
|
+
* they start, the drivers, and the guard extension. One import, answered once, is
|
|
43
|
+
* why they do not each need their own handling - `DatabaseSync` is re-exported for
|
|
44
|
+
* the guard rather than imported there a second time.
|
|
45
|
+
*
|
|
46
|
+
* The answer is matched on the warning's own type and text, and it lasts for the
|
|
47
|
+
* length of that import only: the original emitter is restored in `finally`, so a
|
|
48
|
+
* warning from any other module - another experimental API, a deprecation -
|
|
49
|
+
* reaches stderr exactly as it would without this file. The flags that would also
|
|
50
|
+
* remove this line, `--disable-warning` and `NODE_OPTIONS`, silence the whole
|
|
51
|
+
* ExperimentalWarning class for the entire process, which would hide those.
|
|
52
|
+
*
|
|
53
|
+
* A `warning` listener is not an alternative: it cannot suppress anything. Node's
|
|
54
|
+
* default printer is registered by the runtime, and it prints whether or not
|
|
55
|
+
* another listener exists (measured on 22.19.0, 22.23.4 and 24.0.0 - the listener
|
|
56
|
+
* sees the warning and stderr gets it too), so the emitter call itself is answered
|
|
57
|
+
* here, inside an import nobody else can route around.
|
|
58
|
+
*/
|
|
59
|
+
const SQLITE_WARNING_TYPE = "ExperimentalWarning";
|
|
60
|
+
const SQLITE_WARNING_TEXT = "SQLite is an experimental feature and might change at any time";
|
|
61
|
+
|
|
62
|
+
/** The runtime's emitter, with the SQLite import's one warning withheld. */
|
|
63
|
+
function answerSqliteWarning(emit) {
|
|
64
|
+
return function (warning, type, ...rest) {
|
|
65
|
+
const text = typeof warning === "string" ? warning : warning?.message;
|
|
66
|
+
const name = type ?? warning?.name;
|
|
67
|
+
if (text === SQLITE_WARNING_TEXT && name === SQLITE_WARNING_TYPE) return undefined;
|
|
68
|
+
return emit.call(process, warning, type, ...rest);
|
|
69
|
+
};
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
async function importSqlite() {
|
|
73
|
+
const emit = process.emitWarning;
|
|
74
|
+
process.emitWarning = answerSqliteWarning(emit);
|
|
75
|
+
try {
|
|
76
|
+
return await import("node:sqlite");
|
|
77
|
+
} finally {
|
|
78
|
+
process.emitWarning = emit;
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
export const { DatabaseSync } = await importSqlite();
|
|
29
83
|
|
|
30
84
|
/**
|
|
31
85
|
* The shape a store has once `openJournal` returns.
|
|
@@ -97,9 +97,8 @@
|
|
|
97
97
|
|
|
98
98
|
import { appendFileSync, existsSync } from "node:fs";
|
|
99
99
|
import { join, resolve } from "node:path";
|
|
100
|
-
import { DatabaseSync } from "node:sqlite";
|
|
101
100
|
|
|
102
|
-
import { effectKey, journalPath, replayPolicy } from "./journal.mjs";
|
|
101
|
+
import { DatabaseSync, effectKey, journalPath, replayPolicy } from "./journal.mjs";
|
|
103
102
|
|
|
104
103
|
/** The names the child reads. `off` is the switch, not an identifier. */
|
|
105
104
|
export const GUARD_ENV = {
|
|
@@ -7,12 +7,12 @@ environmental awareness, and system prompt assembly.
|
|
|
7
7
|
|
|
8
8
|
## Sub-extensions
|
|
9
9
|
|
|
10
|
-
| Path | Purpose
|
|
11
|
-
| -------------------- |
|
|
12
|
-
| `polyfill/` | Polyfills for missing pi core features.
|
|
13
|
-
| `agent-environment/` | L1 environmental awareness: working dir, time, machine info.
|
|
14
|
-
| `prompt-builder/` | Builds the agent's system prompt. Composes sections; orchestrates once-per-session whisper deliveries from `memory/` and `cognitive/`.
|
|
15
|
-
| `skills-tool/` |
|
|
10
|
+
| Path | Purpose | Depended on by |
|
|
11
|
+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
|
|
12
|
+
| `polyfill/` | Polyfills for missing pi core features. | (foundation) |
|
|
13
|
+
| `agent-environment/` | L1 environmental awareness: working dir, time, machine info. | `prompt-builder` |
|
|
14
|
+
| `prompt-builder/` | Builds the agent's system prompt. Composes sections; orchestrates once-per-session whisper deliveries from `memory/` and `cognitive/`. | (final assembly) |
|
|
15
|
+
| `skills-tool/` | Skill surface: `list_skills` catalog (on-demand reach and ranking) + `skill_stats` counters, the auto-inject whisper, the skills floor (visible catalog) and drift trigger text rendered by `prompt-builder`. | (tool surface) |
|
|
16
16
|
|
|
17
17
|
## Local Contracts
|
|
18
18
|
|
|
@@ -32,3 +32,5 @@ The auto-inject whisper in `skills-tool/` is the only channel that surfaces a ma
|
|
|
32
32
|
- **Counters move after delivery.** `recordSkillSuggestion` runs only on a `true` return, and the cooldown/LRU bookkeeping runs after the send too, so `suggested` counts arrivals and an undelivered suggestion consumes no slot. The suggestion bypasses the per-turn whisper cap (`bypassFloodCap: true`) because prompt-builder's once-per-session hygiene whisper fires earlier in the same `before_agent_start` at the same priority and would otherwise spend the only advisory slot; the module's own budget (cooldown turns, max active suggestions, one send per turn) is the bound that keeps the whisper a whisper.
|
|
33
33
|
- **Conversion is a detected read.** The whisper asks the agent to open the SKILL.md; the conversion signal is the `read` tool_result (`actual`), which is also what sets `hadSkillLoad` in the durable session record. The retired LOADED/SKIP reply is no longer solicited; `claimed` keeps its historical honor-system meaning and stays monotone.
|
|
34
34
|
- **The trigger has a mechanical form.** `skills-tool/loading-guidance.ts` carries both the judgment form (the task entered a listed skill's domain) and the mechanical form (about to call a tool family whose word appears in a skill's name). `prompt-builder` renders that text through the `skillsLoadingText` builder as the `skills-loading` section and holds no copy of the rules; the trigger's worked examples are derived at assembly from the live tool and skill names, so the text names no pair that the running session does not have. The identity's skills prose stays one sentence.
|
|
35
|
+
- **The catalog is in the prompt.** The same section renders every visible skill as one `- name: description` row, with the read path derived from the skills' own file paths (one root for a single pack, a directory heading per pack when a catalog is installed from several). A tool call is no longer the way the agent learns which skills exist: the floor exists because the prompt that opens a resumed session carries no domain vocabulary for a matcher to rank against. `list_skills` remains the price tool (reach, headings, ranking) rather than the catalog.
|
|
36
|
+
- **Drift re-points at the floor.** When the session's own path-taking calls (`read`/`edit`/`write`) accumulate entries in a work area the floor was not rendered against, one steer line names that area and points back at the catalog. The rule and its bounds (two entries, one fire per twelve calls, three per session, quiet for the same window after any skill surface) live in `loading-guidance.ts` beside the floor text; the wiring is the `tool_result` handler in `auto-inject.ts`. Bounds are the whole design: the line is only worth its noise if it stays rare.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
<!-- status: current -->
|
|
2
|
-
<!-- Status note: identity compressed + PHILOSOPHY block added after EPISTEMIC_STANCE; the placement-discipline block and the PHILOSOPHY senior-craft line were reverted after the prompt re-probe failed its keep rule, REPAIR_DISCIPLINE stays; Resources section deleted; context guidelines reduced to the two policy sentences; pipelines cover 2 domains; tool guideline lines trimmed. Skills
|
|
2
|
+
<!-- Status note: identity compressed + PHILOSOPHY block added after EPISTEMIC_STANCE; the placement-discipline block and the PHILOSOPHY senior-craft line were reverted after the prompt re-probe failed its keep rule, REPAIR_DISCIPLINE stays; Resources section deleted; context guidelines reduced to the two policy sentences; pipelines cover 2 domains; tool guideline lines trimmed. Skills render in the prompt as the skills floor: every visible skill is one `- name: description` row, with the read path derived from the skills' own file paths (one root for a single pack, a directory heading per pack for several) and the mechanical trigger last; `list_skills` stays the price tool (reach, headings, ranking). The pi docs seat is a pointer to the pi-reference skill (the native `<docs>` region is not re-emitted). Policy relocation: the skills floor text and its drift trigger live in the skills-tool module (`loading-guidance.ts`); SURFACE_DISCIPLINE is its own section file; REPAIR_DISCIPLINE and SELF_AUDIT are identity blocks. The multi-agent message-contract constant is removed: the `[agent:…]` tag contract named a message format with no producer in any shipped mechanism, so the standing prompt asserted a channel that does not exist. The floor's rows and the trigger's worked examples are derived at assembly from the live cache, tool names and skill names (`skillsLoadingText` in skills-tool/loading-guidance.ts); no tool, skill or install path is hardcoded in prompt text. -->
|
|
3
3
|
|
|
4
4
|
# src/extensions/core/prompt-builder/ - System Prompt Composition
|
|
5
5
|
|
|
@@ -20,7 +20,7 @@ Every file in this folder either:
|
|
|
20
20
|
|
|
21
21
|
| File | Purpose |
|
|
22
22
|
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
23
|
-
| `index.ts` | Main handler. Wires `before_agent_start`, calls the 4 `deliver*` functions, composes the final prompt.
|
|
23
|
+
| `index.ts` | Main handler. Wires `before_agent_start`, calls the 4 `deliver*` functions, composes the final prompt. Renders the skills floor as its own guarded section (`skillsLoadingText` over the live visible catalog), after the identity seats and before the guidelines. |
|
|
24
24
|
| `section.ts` | The `PromptSection` primitive + `composeSections` joiner + `simpleSection`, `linesSection`, `headingSection` builders. |
|
|
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. |
|
|
@@ -38,7 +38,8 @@ import {
|
|
|
38
38
|
reconstructProjectDocsSection,
|
|
39
39
|
resetProjectDocsSectionCache,
|
|
40
40
|
} from "./project-docs-section.js";
|
|
41
|
-
import { setCachedSkills
|
|
41
|
+
import { setCachedSkills } from "../skills-tool/index.js";
|
|
42
|
+
import { getCachedVisibleSkills } from "../skills-tool/auto-inject.js";
|
|
42
43
|
import { reconstructMemorySection, resetMemorySectionCache } from "./memory-section.js";
|
|
43
44
|
import { gatherInstanceData, renderCompactInstance } from "./instance-composition.js";
|
|
44
45
|
import { sendTrackedMessage } from "../../../lib/utils/injection-tracker.js";
|
|
@@ -523,21 +524,16 @@ export default function promptBuilderExtension(pi: ExtensionAPI) {
|
|
|
523
524
|
surfaceDisciplineSection(),
|
|
524
525
|
simpleSection("identity-core", [EPISTEMIC_STANCE, SELF_AUDIT, PHILOSOPHY].join("\n\n")),
|
|
525
526
|
|
|
526
|
-
// 2. Skills
|
|
527
|
+
// 2. Skills floor (before guidelines, before tools).
|
|
527
528
|
// Owned by the skills-tool module (loading-guidance.ts) and rendered
|
|
528
|
-
// here
|
|
529
|
-
//
|
|
530
|
-
//
|
|
531
|
-
//
|
|
532
|
-
//
|
|
533
|
-
//
|
|
529
|
+
// here: the visible catalog itself, one row per skill, plus the
|
|
530
|
+
// read rule and the mechanical trigger. Guarded by read AND
|
|
531
|
+
// list_skills availability — the rule instructs a full-file read and
|
|
532
|
+
// the trigger names the catalog, so both tools must be present. The
|
|
533
|
+
// rows and the read root come from the live cache (setCachedSkills
|
|
534
|
+
// above); an empty catalog renders no section at all.
|
|
534
535
|
...(hasRead && hasListSkills
|
|
535
|
-
? [
|
|
536
|
-
simpleSection(
|
|
537
|
-
"skills-loading",
|
|
538
|
-
skillsLoadingText(toolNames, getCachedVisibleSkillNames()),
|
|
539
|
-
),
|
|
540
|
-
]
|
|
536
|
+
? [simpleSection("skills-loading", skillsLoadingText(toolNames, getCachedVisibleSkills()))]
|
|
541
537
|
: []),
|
|
542
538
|
|
|
543
539
|
// 3. Guidelines (before tools, pi-core native pattern).
|