pi-braid 0.43.5 → 0.43.7
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 +95 -7
- package/build-info.json +4 -4
- package/dist/extensions/core/prompt-builder/surface-discipline-section.d.ts +1 -1
- package/dist/extensions/core/prompt-builder/surface-discipline-section.js +1 -1
- package/dist/extensions/core/skills-tool/applicability.d.ts +134 -0
- package/dist/extensions/core/skills-tool/applicability.js +161 -0
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +10 -0
- package/dist/extensions/core/skills-tool/auto-inject.js +216 -1
- package/dist/extensions/core/skills-tool/index.js +64 -3
- package/dist/extensions/core/skills-tool/loading-guidance.js +2 -1
- package/dist/extensions/core/skills-tool/session-records.d.ts +297 -8
- package/dist/extensions/core/skills-tool/session-records.js +509 -5
- package/dist/extensions/core/skills-tool/skill-families.d.ts +60 -0
- package/dist/extensions/core/skills-tool/skill-families.js +105 -0
- package/dist/extensions/orchestrator/index.js +11 -1
- package/docs/LOCAL_DEV.md +1 -1
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +1 -0
- package/src/extensions/core/prompt-builder/surface-discipline-section.ts +1 -1
- package/src/extensions/core/skills-tool/applicability.ts +220 -0
- package/src/extensions/core/skills-tool/auto-inject.ts +274 -0
- package/src/extensions/core/skills-tool/index.ts +75 -2
- package/src/extensions/core/skills-tool/loading-guidance.ts +2 -1
- package/src/extensions/core/skills-tool/session-records.ts +740 -5
- package/src/extensions/core/skills-tool/skill-families.ts +112 -0
- package/src/extensions/orchestrator/index.ts +13 -1
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The tool families a skill declares it governs.
|
|
3
|
+
*
|
|
4
|
+
* A trigger phrase says WHEN to open a skill file; nothing in the file says
|
|
5
|
+
* what the file's advice is then used FOR. `governs:` closes that: the tool
|
|
6
|
+
* families whose calls the body is written to direct. A family is the tool
|
|
7
|
+
* name's first underscore-delimited segment (`search_documents` → `search`),
|
|
8
|
+
* the same token `loading-guidance.ts` pairs with a skill name in the
|
|
9
|
+
* mechanical trigger, so "before the first call in the family" in the prompt
|
|
10
|
+
* and "a call in a declared family" in the record cannot mean two things.
|
|
11
|
+
*
|
|
12
|
+
* The declaration is authored data in the skill's own frontmatter — pi's
|
|
13
|
+
* parser already returns it, and the pack's authoring contract already admits
|
|
14
|
+
* any YAML-valid extra key. No new file format and no new field parser is
|
|
15
|
+
* needed, which is why this module only reads.
|
|
16
|
+
*
|
|
17
|
+
* Most skills govern nothing: advice about prose, a palette or a checklist
|
|
18
|
+
* directs no tool, and a file without the key is read as declaring no family.
|
|
19
|
+
* The absence is a fact, not a gap — an obligation that names no family is
|
|
20
|
+
* satisfied by the read alone.
|
|
21
|
+
*
|
|
22
|
+
* A declared family may not be the detector's own tool (`read`): a call to it
|
|
23
|
+
* IS the read leg, so counting it as an applied call would let an obligation
|
|
24
|
+
* satisfy itself. The parser drops such an entry; the shipped pack's contract
|
|
25
|
+
* refuses it by name so an author sees the problem before a release.
|
|
26
|
+
*
|
|
27
|
+
* Nothing here names a skill, a package or a path. Reads are memoized by file
|
|
28
|
+
* mtime + size, so a turn pays one stat per skill file and a parse only when
|
|
29
|
+
* a file changed.
|
|
30
|
+
*/
|
|
31
|
+
|
|
32
|
+
import { readFileSync, statSync } from "node:fs";
|
|
33
|
+
import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Max families read from one declaration. A body that directs more than four
|
|
37
|
+
* tool families is not one skill's job, and the record's per-session rows are
|
|
38
|
+
* bounded by the same number. The pack's contract mirrors this cap.
|
|
39
|
+
*/
|
|
40
|
+
export const MAX_GOVERNED_FAMILIES = 4;
|
|
41
|
+
|
|
42
|
+
/** The token shape a declaration must use: a tool name's first segment. */
|
|
43
|
+
export const GOVERNED_FAMILY_SHAPE = /^[a-z][a-z0-9]*$/;
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* The tool whose call is the read leg itself. Never a declarable family: see
|
|
47
|
+
* the module header.
|
|
48
|
+
*/
|
|
49
|
+
export const DETECTOR_TOOL = "read";
|
|
50
|
+
|
|
51
|
+
/** The family a tool name belongs to: its first underscore-delimited segment. */
|
|
52
|
+
export function toolFamilyToken(toolName: string): string {
|
|
53
|
+
return (toolName ?? "").split("_")[0].toLowerCase();
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Normalize a frontmatter `governs` value into family tokens. Accepts a YAML
|
|
58
|
+
* list or a comma-separated string, lowercases, drops malformed, detector, and
|
|
59
|
+
* surplus entries, and dedupes in authored order. Pure.
|
|
60
|
+
*/
|
|
61
|
+
export function parseGovernedFamilies(value: unknown): string[] {
|
|
62
|
+
const raw = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
|
|
63
|
+
const families: string[] = [];
|
|
64
|
+
for (const item of raw) {
|
|
65
|
+
if (typeof item !== "string") continue;
|
|
66
|
+
const family = item.trim().toLowerCase();
|
|
67
|
+
if (!GOVERNED_FAMILY_SHAPE.test(family) || family === DETECTOR_TOOL) continue;
|
|
68
|
+
if (families.includes(family)) continue;
|
|
69
|
+
families.push(family);
|
|
70
|
+
if (families.length >= MAX_GOVERNED_FAMILIES) break;
|
|
71
|
+
}
|
|
72
|
+
return families;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
interface FamilyCacheEntry {
|
|
76
|
+
mtimeMs: number;
|
|
77
|
+
size: number;
|
|
78
|
+
families: string[];
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
const cache = new Map<string, FamilyCacheEntry>();
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Read the families a skill file declares. Missing or unreadable file, or
|
|
85
|
+
* malformed frontmatter, yields an empty list (a declaration that cannot be
|
|
86
|
+
* read is not a declaration). Memoized: an unchanged file never re-reads.
|
|
87
|
+
*/
|
|
88
|
+
export function readGovernedFamilies(filePath: string): string[] {
|
|
89
|
+
let st;
|
|
90
|
+
try {
|
|
91
|
+
st = statSync(filePath);
|
|
92
|
+
} catch {
|
|
93
|
+
cache.delete(filePath);
|
|
94
|
+
return [];
|
|
95
|
+
}
|
|
96
|
+
const cached = cache.get(filePath);
|
|
97
|
+
if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size) return cached.families;
|
|
98
|
+
let families: string[] = [];
|
|
99
|
+
try {
|
|
100
|
+
const { frontmatter } = parseFrontmatter(readFileSync(filePath, "utf-8"));
|
|
101
|
+
families = parseGovernedFamilies((frontmatter as Record<string, unknown>).governs);
|
|
102
|
+
} catch {
|
|
103
|
+
// Unreadable or unparseable: no declared family, and no throw on a turn.
|
|
104
|
+
}
|
|
105
|
+
cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, families });
|
|
106
|
+
return families;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** Test seam: forget every memoized read. */
|
|
110
|
+
export function clearGovernedFamilyCache(): void {
|
|
111
|
+
cache.clear();
|
|
112
|
+
}
|
|
@@ -324,7 +324,19 @@ function verifyAndMergeBase(
|
|
|
324
324
|
`NOT merged: worktree on ${base} has uncommitted changes; refusing to merge over them. Base unchanged at ${short(baseBefore)}. Locks and branch kept.`,
|
|
325
325
|
);
|
|
326
326
|
}
|
|
327
|
-
|
|
327
|
+
// Git derives a merge subject from the branch name, so a merge out of a
|
|
328
|
+
// worker branch would publish that branch's namespace in the one part of a
|
|
329
|
+
// commit a reader keeps. The subject states what landed instead. A tip
|
|
330
|
+
// whose subject cannot be read (missing, or empty) refuses the merge: the
|
|
331
|
+
// fallback is precisely the derived subject this avoids, so a silent
|
|
332
|
+
// fallback would put the leak back.
|
|
333
|
+
const landed = git(repoRoot, ["log", "-1", "--format=%s", workerBranch]);
|
|
334
|
+
if (!landed) {
|
|
335
|
+
return nothingMerged(
|
|
336
|
+
`NOT merged: cannot read the subject of ${workerBranch} at ${short(tip)}; refusing to merge without an explicit subject, since git would derive the merge subject from that branch name. Base unchanged at ${short(baseBefore)}. Locks and branch kept.`,
|
|
337
|
+
);
|
|
338
|
+
}
|
|
339
|
+
if (git(repoRoot, ["merge", "--no-edit", "-m", landed, workerBranch]) === undefined) {
|
|
328
340
|
return nothingMerged(
|
|
329
341
|
`NOT merged: git merge ${workerBranch} into ${base} failed (conflict or refusal). Base unchanged at ${short(baseBefore)}. Locks and branch kept.`,
|
|
330
342
|
);
|