pi-braid 0.40.5 → 0.41.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/AGENTS.md +17 -18
- package/README.md +128 -130
- package/TOOLS.md +35 -35
- package/build-info.json +4 -4
- package/dist/extensions/core/agent-environment/index.js +4 -3
- package/dist/extensions/core/prompt-builder/index.js +12 -7
- package/dist/extensions/core/prompt-builder/instance-composition.d.ts +51 -10
- package/dist/extensions/core/prompt-builder/instance-composition.js +87 -14
- package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +3 -3
- package/dist/extensions/core/prompt-builder/system-info-tool.js +3 -3
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +89 -10
- package/dist/extensions/core/skills-tool/auto-inject.js +150 -21
- package/dist/extensions/core/skills-tool/index.d.ts +70 -2
- package/dist/extensions/core/skills-tool/index.js +149 -15
- package/dist/extensions/core/skills-tool/reach.d.ts +119 -0
- package/dist/extensions/core/skills-tool/reach.js +213 -0
- package/dist/extensions/core/skills-tool/skill-triggers.d.ts +47 -10
- package/dist/extensions/core/skills-tool/skill-triggers.js +66 -23
- package/dist/extensions/enforcement/handlers/register-session-compact.js +12 -1
- package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +15 -34
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +2 -1
- package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +55 -28
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +14 -10
- package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +88 -82
- package/dist/extensions/enforcement/resume-state.d.ts +76 -0
- package/dist/extensions/enforcement/resume-state.js +90 -0
- package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +9 -0
- package/dist/extensions/enforcement/substate/context-hygiene-state.js +8 -0
- package/dist/extensions/enforcement/whisper.d.ts +12 -0
- package/dist/extensions/enforcement/whisper.js +16 -1
- package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +14 -6
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +7 -0
- package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +372 -0
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +8 -2
- package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +54 -21
- package/dist/lib/config/braid-paths.d.ts +14 -0
- package/dist/lib/config/braid-paths.js +18 -0
- package/dist/lib/config/braid-settings.d.ts +21 -0
- package/dist/lib/config/braid-settings.js +16 -0
- package/dist/lib/detection/context-tiers.d.ts +47 -3
- package/dist/lib/detection/context-tiers.js +122 -13
- package/dist/lib/events/turn-boundary.d.ts +78 -0
- package/dist/lib/events/turn-boundary.js +91 -0
- package/dist/lib/orchestrator/workers.d.ts +3 -2
- package/dist/lib/orchestrator/workers.js +22 -4
- package/dist/lib/state/global-state.d.ts +1 -1
- package/docs/CONTEXT-MAP.md +1 -1
- package/docs/CONTEXT-POLICY.md +8 -0
- package/docs/FLEET.md +99 -0
- package/docs/LOCAL_DEV.md +0 -1
- package/docs/ROADMAP.md +5 -5
- package/docs/SETUP.md +19 -18
- package/package.json +5 -1
- package/scripts/fleet/cli.mjs +499 -0
- package/scripts/fleet/driver-rpc.mjs +376 -0
- package/scripts/fleet/driver-scripted.mjs +239 -0
- package/scripts/fleet/journal.mjs +994 -0
- package/scripts/fleet/procs.mjs +76 -0
- package/scripts/fleet/supervisor.mjs +1494 -0
- package/scripts/fleet/tool-guard.mjs +467 -0
- package/skills/herdr-topology/SKILL.md +6 -1
- package/skills/release-pipeline/SKILL.md +20 -4
- package/skills/research/SKILL.md +32 -0
- package/skills/subagent-orchestration/SKILL.md +2 -2
- package/src/extensions/core/agent-environment/index.ts +4 -3
- package/src/extensions/core/prompt-builder/AGENTS.md +8 -4
- package/src/extensions/core/prompt-builder/index.ts +12 -7
- package/src/extensions/core/prompt-builder/instance-composition.ts +98 -14
- package/src/extensions/core/prompt-builder/system-info-tool.ts +3 -3
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
- package/src/extensions/core/skills-tool/auto-inject.ts +196 -24
- package/src/extensions/core/skills-tool/index.ts +217 -15
- package/src/extensions/core/skills-tool/reach.ts +256 -0
- package/src/extensions/core/skills-tool/skill-triggers.ts +90 -20
- package/src/extensions/enforcement/handlers/register-session-compact.ts +12 -1
- package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +23 -36
- package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +59 -29
- package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +101 -81
- package/src/extensions/enforcement/resume-state.ts +127 -0
- package/src/extensions/enforcement/substate/context-hygiene-state.ts +17 -0
- package/src/extensions/enforcement/whisper.ts +21 -1
- package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +20 -5
- package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +370 -0
- package/src/extensions/memory/AGENTS.md +25 -1
- package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +80 -27
- package/src/lib/config/braid-paths.ts +20 -0
- package/src/lib/config/braid-settings.ts +46 -0
- package/src/lib/detection/context-tiers.ts +186 -13
- package/src/lib/events/AGENTS.md +1 -0
- package/src/lib/events/turn-boundary.ts +115 -0
- package/src/lib/orchestrator/workers.ts +33 -12
- package/src/lib/state/global-state.ts +1 -0
- package/src/lib/utils/AGENTS.md +1 -1
- package/src/types/extension-context.d.ts +22 -79
|
@@ -10,7 +10,19 @@
|
|
|
10
10
|
* The cache lives in this module and is reset each session.
|
|
11
11
|
*
|
|
12
12
|
* One action:
|
|
13
|
-
* list — paginated catalog (name, filePath, description, source)
|
|
13
|
+
* list — paginated catalog (name, filePath, description, source, reach),
|
|
14
|
+
* ordered by relevance to the current task unless `rank: "catalog"`.
|
|
15
|
+
*
|
|
16
|
+
* Each row carries the price of the read it names (see reach.ts): reachable,
|
|
17
|
+
* lines, bytes, chars, a token estimate, the file's heading count, and as many
|
|
18
|
+
* of its headings as the caller asked for. Picking a skill is picking a read,
|
|
19
|
+
* and a price is what makes that pick rational.
|
|
20
|
+
*
|
|
21
|
+
* The ordering is the deterministic scorer's answer (see `resolveRanking`):
|
|
22
|
+
* auto-inject.ts owns the ranking, and this handler owns only what needs the
|
|
23
|
+
* extension context — the task text (from the session branch) and the
|
|
24
|
+
* `braid.skills.ranking` policy, which is read and echoed rather than acted on
|
|
25
|
+
* while no model tier exists.
|
|
14
26
|
*
|
|
15
27
|
* Skills discovery (list_skills tool) plus the scoring-based auto-inject
|
|
16
28
|
* whisper supersede an LLM top-N recommender: a second relevance engine
|
|
@@ -20,17 +32,28 @@
|
|
|
20
32
|
* Also registers `skill_stats` — the adoption counter surface.
|
|
21
33
|
*/
|
|
22
34
|
|
|
23
|
-
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
35
|
+
import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
24
36
|
import { Type } from "typebox";
|
|
25
37
|
import { createLogger } from "../../../lib/core/logger.js";
|
|
38
|
+
import { getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
|
|
39
|
+
import type { SkillsRankingMode } from "../../../lib/config/braid-settings.js";
|
|
26
40
|
import {
|
|
27
41
|
registerAutoInject,
|
|
28
42
|
updateSkillCache,
|
|
29
43
|
getSkillStats,
|
|
30
44
|
getDurableSkillStats,
|
|
31
45
|
resolveDiscoveryMode,
|
|
46
|
+
rankSkillsDeterministic,
|
|
32
47
|
} from "./auto-inject.js";
|
|
33
|
-
import {
|
|
48
|
+
import type { DeterministicRanking, RankedSkill, RelevanceReason } from "./auto-inject.js";
|
|
49
|
+
import { readSkillTriggerEntries } from "./skill-triggers.js";
|
|
50
|
+
import type { TriggerSource } from "./skill-triggers.js";
|
|
51
|
+
import {
|
|
52
|
+
clampSectionsMax,
|
|
53
|
+
DEFAULT_SECTIONS_MAX,
|
|
54
|
+
SECTIONS_MAX_LIMIT,
|
|
55
|
+
readSkillReach,
|
|
56
|
+
} from "./reach.js";
|
|
34
57
|
import { getMonthlyAdoptionRollup } from "./session-records.js";
|
|
35
58
|
|
|
36
59
|
const log = createLogger("skills-tool");
|
|
@@ -51,6 +74,8 @@ interface CachedSkill {
|
|
|
51
74
|
disableModelInvocation?: boolean;
|
|
52
75
|
/** Frontmatter trigger phrases, resolved from SKILL.md at cache time. */
|
|
53
76
|
triggers?: string[];
|
|
77
|
+
/** Which source authored each phrase (a ranking row reports it). */
|
|
78
|
+
triggerSources?: Record<string, TriggerSource>;
|
|
54
79
|
}
|
|
55
80
|
|
|
56
81
|
let cachedSkills: CachedSkill[] = [];
|
|
@@ -62,10 +87,12 @@ let cachedSkills: CachedSkill[] = [];
|
|
|
62
87
|
* shape), and the memoized read makes repeat turns stat-only.
|
|
63
88
|
*/
|
|
64
89
|
export function setCachedSkills(skills: CachedSkill[]): void {
|
|
65
|
-
cachedSkills = skills.map((s) =>
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
90
|
+
cachedSkills = skills.map((s) => {
|
|
91
|
+
const entries = readSkillTriggerEntries(s.filePath, s.description);
|
|
92
|
+
const triggerSources: Record<string, TriggerSource> = {};
|
|
93
|
+
for (const entry of entries) triggerSources[entry.phrase] = entry.source;
|
|
94
|
+
return { ...s, triggers: entries.map((entry) => entry.phrase), triggerSources };
|
|
95
|
+
});
|
|
69
96
|
// Sync with auto-inject subsystem (enriched cache — triggers ride along)
|
|
70
97
|
updateSkillCache(cachedSkills);
|
|
71
98
|
log.debug(`Cached ${skills.length} skills for list_skills tool`);
|
|
@@ -92,6 +119,137 @@ function formatSource(skill: CachedSkill): string {
|
|
|
92
119
|
return src;
|
|
93
120
|
}
|
|
94
121
|
|
|
122
|
+
// Relevance ranking: the deterministic order
|
|
123
|
+
//
|
|
124
|
+
// A model tier was built here and measured against this scorer: it never lost
|
|
125
|
+
// a case and won the two prose prompts the scorer misses, but it did not clear
|
|
126
|
+
// its pre-registered bar, and a tier that buys two wins with a call on every
|
|
127
|
+
// ambiguous read is a finding about the scorer, not a feature. So the read is
|
|
128
|
+
// answered by rankSkillsDeterministic() alone: no provider, no cache, no
|
|
129
|
+
// counters. The `braid.skills.ranking` setting and the `ranking` report
|
|
130
|
+
// survive because they are the seam a later tier plugs into.
|
|
131
|
+
|
|
132
|
+
/** The evidence label a row reports (see RelevanceReason in auto-inject.ts). */
|
|
133
|
+
export type RowRelevanceReason = RelevanceReason;
|
|
134
|
+
|
|
135
|
+
/** What a ranked row says about its own position. */
|
|
136
|
+
export interface RowRelevance {
|
|
137
|
+
/** The deterministic score behind the row. */
|
|
138
|
+
score: number;
|
|
139
|
+
reason: RowRelevanceReason;
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** Why the deterministic verdict is what it is, and who answered. */
|
|
143
|
+
export interface RankingReport {
|
|
144
|
+
/** Always "keyword": the deterministic scorer is the only tier. */
|
|
145
|
+
tier: "keyword";
|
|
146
|
+
basis: DeterministicRanking["basis"];
|
|
147
|
+
/**
|
|
148
|
+
* The configured `braid.skills.ranking` value, echoed so an operator can see
|
|
149
|
+
* what the policy asked for. Only "keyword" has an implementation today; the
|
|
150
|
+
* other two are reserved for a model tier that was measured and not kept, and
|
|
151
|
+
* they evaluate to the keyword path.
|
|
152
|
+
*/
|
|
153
|
+
policy: SkillsRankingMode;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/**
|
|
157
|
+
* The current task text: the newest user message on the live branch.
|
|
158
|
+
*
|
|
159
|
+
* A tool call carries no prompt of its own and pi hands tools no turn prompt,
|
|
160
|
+
* but the branch does — and its newest user message is the task the agent is
|
|
161
|
+
* working on. A resumed session therefore ranks against its real task even
|
|
162
|
+
* though this process never saw the prompt arrive. Best-effort: no branch, an
|
|
163
|
+
* unreadable entry, or a non-text message yields "", and the caller then
|
|
164
|
+
* returns the catalog order rather than inventing a task.
|
|
165
|
+
*/
|
|
166
|
+
export function currentTaskText(ctx: ExtensionContext): string {
|
|
167
|
+
try {
|
|
168
|
+
const sm = (ctx as { sessionManager?: { getBranch?: () => unknown[] } }).sessionManager;
|
|
169
|
+
const branch = sm?.getBranch?.() ?? [];
|
|
170
|
+
for (let i = branch.length - 1; i >= 0; i--) {
|
|
171
|
+
const entry = branch[i] as { type?: string; message?: { role?: string; content?: unknown } };
|
|
172
|
+
if (entry?.type !== "message" || entry.message?.role !== "user") continue;
|
|
173
|
+
const content = entry.message.content;
|
|
174
|
+
if (typeof content === "string") return content;
|
|
175
|
+
if (Array.isArray(content)) {
|
|
176
|
+
return content
|
|
177
|
+
.map((part) => part as { type?: string; text?: string })
|
|
178
|
+
.filter((part) => part?.type === "text" && typeof part.text === "string")
|
|
179
|
+
.map((part) => part.text as string)
|
|
180
|
+
.join("\n");
|
|
181
|
+
}
|
|
182
|
+
return "";
|
|
183
|
+
}
|
|
184
|
+
} catch {
|
|
185
|
+
// Best-effort: a stale ctx or an absent tree yields no text.
|
|
186
|
+
}
|
|
187
|
+
return "";
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** Reorder `skills` by `names`, appending everything the list did not mention. */
|
|
191
|
+
function orderByNames(skills: CachedSkill[], names: string[]): CachedSkill[] {
|
|
192
|
+
const byName = new Map(skills.map((s) => [s.name, s]));
|
|
193
|
+
const out: CachedSkill[] = [];
|
|
194
|
+
for (const name of names) {
|
|
195
|
+
const skill = byName.get(name);
|
|
196
|
+
if (!skill) continue;
|
|
197
|
+
byName.delete(name);
|
|
198
|
+
out.push(skill);
|
|
199
|
+
}
|
|
200
|
+
for (const skill of skills) if (byName.has(skill.name)) out.push(skill);
|
|
201
|
+
return out;
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
/** One catalog read's complete ranking answer. */
|
|
205
|
+
export interface RankingAnswer {
|
|
206
|
+
order: CachedSkill[];
|
|
207
|
+
/** Absent for `rank: "catalog"` — an unranked read has no tier or evidence. */
|
|
208
|
+
ranking?: RankingReport;
|
|
209
|
+
relevance: Map<string, RowRelevance>;
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* Resolve the catalog order for one read.
|
|
214
|
+
*
|
|
215
|
+
* `keyword` and `catalog` are the two answers: the deterministic ranking (with
|
|
216
|
+
* its verdict on how confident that ranking is), or the plain catalog. A
|
|
217
|
+
* missing task text is nobody's question, so the catalog order stands and the
|
|
218
|
+
* report says `no-task` rather than pretending to rank.
|
|
219
|
+
*/
|
|
220
|
+
export function resolveRanking(
|
|
221
|
+
ctx: ExtensionContext,
|
|
222
|
+
skills: CachedSkill[],
|
|
223
|
+
options: { rank: "relevance" | "catalog"; policy?: SkillsRankingMode },
|
|
224
|
+
): RankingAnswer {
|
|
225
|
+
if (options.rank === "catalog") return { order: skills, relevance: new Map() };
|
|
226
|
+
|
|
227
|
+
const det = rankSkillsDeterministic(skills, currentTaskText(ctx));
|
|
228
|
+
const relevance = new Map<string, RowRelevance>();
|
|
229
|
+
for (const row of det.ranked) relevance.set(row.skill.name, rowOf(row));
|
|
230
|
+
const order =
|
|
231
|
+
det.basis === "no-task"
|
|
232
|
+
? skills
|
|
233
|
+
: orderByNames(
|
|
234
|
+
skills,
|
|
235
|
+
det.ranked.map((row) => row.skill.name),
|
|
236
|
+
);
|
|
237
|
+
return {
|
|
238
|
+
order,
|
|
239
|
+
ranking: {
|
|
240
|
+
tier: "keyword",
|
|
241
|
+
basis: det.basis,
|
|
242
|
+
policy: options.policy ?? getSkillsRankingMode(),
|
|
243
|
+
},
|
|
244
|
+
relevance,
|
|
245
|
+
};
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/** A ranked row as the response reports it (only rows with evidence get here). */
|
|
249
|
+
function rowOf(row: RankedSkill): RowRelevance {
|
|
250
|
+
return { score: row.score, reason: row.reason ?? "description" };
|
|
251
|
+
}
|
|
252
|
+
|
|
95
253
|
// Extension factory:
|
|
96
254
|
|
|
97
255
|
export default function skillsToolExtension(pi: ExtensionAPI): void {
|
|
@@ -101,10 +259,11 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
|
|
|
101
259
|
name: "list_skills",
|
|
102
260
|
label: "List Skills",
|
|
103
261
|
description:
|
|
104
|
-
"Discover skills on demand: paginated catalog (name, filePath, description, source); `read` a SKILL.md to load it.",
|
|
262
|
+
"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.",
|
|
105
263
|
parameters: Type.Object({
|
|
106
264
|
action: Type.Literal("list", {
|
|
107
|
-
description:
|
|
265
|
+
description:
|
|
266
|
+
"list = paginated catalog with per-skill reach (reachable, lines, bytes, chars, estTokens, sectionCount, sections)",
|
|
108
267
|
}),
|
|
109
268
|
page: Type.Optional(
|
|
110
269
|
Type.Number({
|
|
@@ -121,17 +280,36 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
|
|
|
121
280
|
description: "Entries per page for list",
|
|
122
281
|
}),
|
|
123
282
|
),
|
|
283
|
+
sectionsMax: Type.Optional(
|
|
284
|
+
Type.Number({
|
|
285
|
+
minimum: 0,
|
|
286
|
+
maximum: SECTIONS_MAX_LIMIT,
|
|
287
|
+
default: DEFAULT_SECTIONS_MAX,
|
|
288
|
+
description:
|
|
289
|
+
"Headings reported per skill; 0 omits the section list and keeps sectionCount",
|
|
290
|
+
}),
|
|
291
|
+
),
|
|
292
|
+
rank: Type.Optional(
|
|
293
|
+
Type.Union([Type.Literal("relevance"), Type.Literal("catalog")], {
|
|
294
|
+
default: "relevance",
|
|
295
|
+
description:
|
|
296
|
+
"relevance (default) = order by fit to the current task; catalog = the plain catalog order, with no ranking fields",
|
|
297
|
+
}),
|
|
298
|
+
),
|
|
124
299
|
}),
|
|
125
|
-
execute: async (_id, params,
|
|
300
|
+
execute: async (_id, params, signal, _onUpdate, ctx) => {
|
|
126
301
|
const page = (params.page as number) ?? 1;
|
|
127
302
|
const pageSize = (params.pageSize as number) ?? 10;
|
|
128
|
-
const
|
|
303
|
+
const sectionsMax = clampSectionsMax(params.sectionsMax);
|
|
304
|
+
const rank = (params.rank as "relevance" | "catalog" | undefined) ?? "relevance";
|
|
129
305
|
// Explicit-invocation-only skills stay out of the catalog; the cache
|
|
130
306
|
// itself stays unfiltered for the read-detector that counts explicit
|
|
131
307
|
// loads.
|
|
132
308
|
const visible = cachedSkills.filter((s) => !s.disableModelInvocation);
|
|
133
|
-
const
|
|
134
|
-
const total =
|
|
309
|
+
const answer = resolveRanking(ctx, visible, { rank });
|
|
310
|
+
const total = answer.order.length;
|
|
311
|
+
const start = (page - 1) * pageSize;
|
|
312
|
+
const slice = answer.order.slice(start, start + pageSize);
|
|
135
313
|
const hasMore = start + pageSize < total;
|
|
136
314
|
|
|
137
315
|
const skills = slice.map((s) => ({
|
|
@@ -139,16 +317,40 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
|
|
|
139
317
|
filePath: s.filePath,
|
|
140
318
|
description: (s.description ?? "").slice(0, 280),
|
|
141
319
|
source: formatSource(s),
|
|
320
|
+
...readSkillReach(s.filePath, sectionsMax),
|
|
321
|
+
// Evidence where it exists: a row with no match carries no relevance
|
|
322
|
+
// field. Every row paying ~60 bytes for "nothing matched" pushed the
|
|
323
|
+
// shipped page past its measured prompt budget (12.0KB -> 12.8KB), and
|
|
324
|
+
// the empty object carried no information the absence does not.
|
|
325
|
+
...(answer.relevance.has(s.name) ? { relevance: answer.relevance.get(s.name) } : {}),
|
|
142
326
|
}));
|
|
143
327
|
|
|
144
328
|
return {
|
|
145
329
|
content: [
|
|
146
330
|
{
|
|
147
331
|
type: "text" as const,
|
|
148
|
-
text: JSON.stringify(
|
|
332
|
+
text: JSON.stringify(
|
|
333
|
+
{
|
|
334
|
+
page,
|
|
335
|
+
pageSize,
|
|
336
|
+
total,
|
|
337
|
+
hasMore,
|
|
338
|
+
...(answer.ranking ? { ranking: answer.ranking } : {}),
|
|
339
|
+
skills,
|
|
340
|
+
},
|
|
341
|
+
null,
|
|
342
|
+
2,
|
|
343
|
+
),
|
|
149
344
|
},
|
|
150
345
|
],
|
|
151
|
-
details: {
|
|
346
|
+
details: {
|
|
347
|
+
total,
|
|
348
|
+
page,
|
|
349
|
+
pageSize,
|
|
350
|
+
hasMore,
|
|
351
|
+
returned: skills.length,
|
|
352
|
+
...(answer.ranking ? { tier: answer.ranking.tier, basis: answer.ranking.basis } : {}),
|
|
353
|
+
},
|
|
152
354
|
};
|
|
153
355
|
},
|
|
154
356
|
});
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a SKILL.md costs before it is read.
|
|
3
|
+
*
|
|
4
|
+
* `list_skills` is a choice between reads, and a row that names a path but
|
|
5
|
+
* prices nothing leaves that choice blind: a 650-byte pointer and a 25KB
|
|
6
|
+
* reference look identical until one of them is already in context. The fields
|
|
7
|
+
* here are the price - line count, byte count, character count, a token
|
|
8
|
+
* estimate, and the file's ATX headings with line numbers, which is the
|
|
9
|
+
* cheapest useful table of contents for "read section 88 and stop".
|
|
10
|
+
*
|
|
11
|
+
* Counts are the whole file, frontmatter included: the question a reader is
|
|
12
|
+
* asking is what the `read` call will cost, not what the body costs. `chars`
|
|
13
|
+
* is `String.length`, so it counts UTF-16 code units and not code points: text
|
|
14
|
+
* outside the BMP counts twice, and `estTokens` inherits that over-count. A
|
|
15
|
+
* byte-priced budget is what this row feeds, `chars` is the name callers
|
|
16
|
+
* already read, and the doc block is where the difference is stated.
|
|
17
|
+
* Lines end at a newline; a last line without a terminating newline still
|
|
18
|
+
* counts, because the read pays for it.
|
|
19
|
+
*
|
|
20
|
+
* One read per change. The cache is keyed on mtime + size, the same
|
|
21
|
+
* invalidation `skill-triggers.ts` uses: a page render stats every row, and
|
|
22
|
+
* only a first-seen or changed file is opened and parsed. Failures are not
|
|
23
|
+
* cached, because a chmod that took away read access leaves mtime untouched -
|
|
24
|
+
* a cached failure would outlive the repair.
|
|
25
|
+
*
|
|
26
|
+
* Headings are parsed fence-aware. Skill files carry long fenced blocks of
|
|
27
|
+
* shell, TypeScript and markdown samples whose comment lines start with `#`.
|
|
28
|
+
* Over the 22 skills of the shipped pack, 293 lines are shaped like headings
|
|
29
|
+
* and 248 are headings: 45 phantom entries, 1.18x. The ratio is not the
|
|
30
|
+
* argument, the entries are. Those 45 lines are shell and TypeScript
|
|
31
|
+
* commentary, and a fence-blind parse advertises them as document structure,
|
|
32
|
+
* sending a reader to a line that holds no section.
|
|
33
|
+
*
|
|
34
|
+
* Two fence edges are known limits, not open bugs. A fence opener indented
|
|
35
|
+
* four spaces is not a fence - the fence and ATX rules both stop at three
|
|
36
|
+
* spaces - so `#` lines inside such a block are reported as headings. An
|
|
37
|
+
* unclosed fence swallows every later heading, which is CommonMark's rule too
|
|
38
|
+
* and costs a truncated file its table of contents. Neither occurs in the
|
|
39
|
+
* shipped pack. Fixing either is a behaviour change with its own evidence, so
|
|
40
|
+
* this block is where they are recorded rather than where they are repaired.
|
|
41
|
+
*
|
|
42
|
+
* The default page is a budget, not a ceiling. A row carries at most
|
|
43
|
+
* SECTIONS_MAX_LIMIT headings and `list_skills` serves at most 50 rows per
|
|
44
|
+
* page, so one call can ask for tens of kilobytes: `pageSize: 50` with
|
|
45
|
+
* `sectionsMax: 64` over the shipped pack is 35852 bytes, nearly three times
|
|
46
|
+
* the 12KB default page. That is the caller's choice, priced here so it is not
|
|
47
|
+
* a surprise; the budget below binds on the default arguments only.
|
|
48
|
+
*/
|
|
49
|
+
|
|
50
|
+
import { readFileSync, statSync } from "node:fs";
|
|
51
|
+
import { resolve } from "node:path";
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Characters per token. The same divisor the pre-send guard uses
|
|
55
|
+
* (`packages/providers/presend-guard.ts`, `CHARS_PER_TOKEN`) and the one
|
|
56
|
+
* pi-core's `estimateTokens` applies, so a reach estimate and a payload
|
|
57
|
+
* estimate are comparable numbers rather than two private conventions.
|
|
58
|
+
* Declared here instead of imported: providers is a standalone package with no
|
|
59
|
+
* import path into core.
|
|
60
|
+
*/
|
|
61
|
+
export const CHARS_PER_TOKEN = 4;
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Headings reported per skill when the caller does not ask for another cap.
|
|
65
|
+
*
|
|
66
|
+
* Six is a prompt-budget number, not a taste one: over the shipped pack the
|
|
67
|
+
* heaviest ten-row page of the pretty-printed catalog measures 11984 bytes at
|
|
68
|
+
* six headings, 304 bytes under the 12KB bound, and 13568 at eight, where it
|
|
69
|
+
* crosses. Callers who want the full contents pass `sectionsMax` (up to
|
|
70
|
+
* SECTIONS_MAX_LIMIT).
|
|
71
|
+
*/
|
|
72
|
+
export const DEFAULT_SECTIONS_MAX = 6;
|
|
73
|
+
|
|
74
|
+
/** A heading is a table-of-contents entry, not a paragraph. */
|
|
75
|
+
const SECTION_TEXT_MAX = 80;
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Upper bound on the per-skill heading cap - a request above it is a bug.
|
|
79
|
+
* `list_skills` declares this same value as its schema maximum, so the ceiling
|
|
80
|
+
* a caller meets through the tool and the ceiling `clampSectionsMax` enforces
|
|
81
|
+
* cannot drift into two numbers.
|
|
82
|
+
*/
|
|
83
|
+
export const SECTIONS_MAX_LIMIT = 64;
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* ATX heading: up to three spaces of indent (four would be an indented code
|
|
87
|
+
* block), one to six `#`, then a space or the end of the line - so `#region`
|
|
88
|
+
* in a TypeScript sample is not a heading.
|
|
89
|
+
*/
|
|
90
|
+
const ATX_HEADING = /^ {0,3}(#{1,6})(?:[ \t]+(.*))?$/;
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* A heading's optional closing sequence: `## Title ##`, trailing whitespace
|
|
94
|
+
* allowed - `## Title ## ` closes the same way, and the spaces after the run
|
|
95
|
+
* are not part of the text.
|
|
96
|
+
*/
|
|
97
|
+
const CLOSING_HASHES = /[ \t]+#+[ \t]*$/;
|
|
98
|
+
|
|
99
|
+
/** A fence line: up to three spaces of indent, then three or more backticks or tildes. */
|
|
100
|
+
const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
|
|
101
|
+
|
|
102
|
+
export interface SkillSection {
|
|
103
|
+
/** 1-indexed line the heading sits on. */
|
|
104
|
+
line: number;
|
|
105
|
+
/** Heading text with its leading `#`s stripped, trimmed, capped. */
|
|
106
|
+
text: string;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
export interface SkillReach {
|
|
110
|
+
reachable: true;
|
|
111
|
+
lines: number;
|
|
112
|
+
bytes: number;
|
|
113
|
+
/** `String.length`: UTF-16 code units, so astral-plane text counts twice. */
|
|
114
|
+
chars: number;
|
|
115
|
+
estTokens: number;
|
|
116
|
+
/** Total headings in the file, independent of the per-call report cap. */
|
|
117
|
+
sectionCount: number;
|
|
118
|
+
/** Omitted when the caller asked for no section list. */
|
|
119
|
+
sections?: SkillSection[];
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
export interface UnreachableReach {
|
|
123
|
+
reachable: false;
|
|
124
|
+
/** Stat size when stat() succeeded and the read failed; absent otherwise. */
|
|
125
|
+
bytes?: number;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
export type Reach = SkillReach | UnreachableReach;
|
|
129
|
+
|
|
130
|
+
interface ReachCacheEntry {
|
|
131
|
+
mtimeMs: number;
|
|
132
|
+
size: number;
|
|
133
|
+
reach: SkillReach;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
const cache = new Map<string, ReachCacheEntry>();
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Lines in a file's text: a trailing newline ends the last line rather than
|
|
140
|
+
* opening a blank one, an empty file has no lines, and a final line with no
|
|
141
|
+
* terminating newline counts, because the partial line is content the read
|
|
142
|
+
* pays for.
|
|
143
|
+
*/
|
|
144
|
+
export function countLines(text: string): number {
|
|
145
|
+
if (text === "") return 0;
|
|
146
|
+
let newlines = 0;
|
|
147
|
+
for (let i = 0; i < text.length; i++) if (text[i] === "\n") newlines++;
|
|
148
|
+
return text.endsWith("\n") ? newlines : newlines + 1;
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
/**
|
|
152
|
+
* Headings in document order, skipping fenced blocks. A fence opens on a run
|
|
153
|
+
* of backticks or tildes (with or without an info string) and closes only on a
|
|
154
|
+
* run of the same character at least as long, so a `~~~` sample inside a
|
|
155
|
+
* backtick fence is content, not a delimiter. A backtick run followed by more
|
|
156
|
+
* backticks (` ```a`` `) is not a fence at all, per CommonMark.
|
|
157
|
+
*/
|
|
158
|
+
function scanHeadings(text: string): SkillSection[] {
|
|
159
|
+
const headings: SkillSection[] = [];
|
|
160
|
+
let fence: { marker: string; length: number } | null = null;
|
|
161
|
+
const lines = text.split("\n");
|
|
162
|
+
for (let i = 0; i < lines.length; i++) {
|
|
163
|
+
const line = lines[i].endsWith("\r") ? lines[i].slice(0, -1) : lines[i];
|
|
164
|
+
const fenceLine = FENCE.exec(line);
|
|
165
|
+
if (fence) {
|
|
166
|
+
if (
|
|
167
|
+
fenceLine &&
|
|
168
|
+
fenceLine[1][0] === fence.marker &&
|
|
169
|
+
fenceLine[1].length >= fence.length &&
|
|
170
|
+
fenceLine[2].trim() === ""
|
|
171
|
+
) {
|
|
172
|
+
fence = null;
|
|
173
|
+
}
|
|
174
|
+
continue;
|
|
175
|
+
}
|
|
176
|
+
if (fenceLine && !(fenceLine[1][0] === "`" && fenceLine[2].includes("`"))) {
|
|
177
|
+
fence = { marker: fenceLine[1][0], length: fenceLine[1].length };
|
|
178
|
+
continue;
|
|
179
|
+
}
|
|
180
|
+
const heading = ATX_HEADING.exec(line);
|
|
181
|
+
if (!heading) continue;
|
|
182
|
+
const text = (heading[2] ?? "").replace(CLOSING_HASHES, "").trim();
|
|
183
|
+
headings.push({
|
|
184
|
+
line: i + 1,
|
|
185
|
+
text: text.length > SECTION_TEXT_MAX ? text.slice(0, SECTION_TEXT_MAX) : text,
|
|
186
|
+
});
|
|
187
|
+
}
|
|
188
|
+
return headings;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/** Clamp a caller-supplied heading cap into range; 0 means "no list". */
|
|
192
|
+
export function clampSectionsMax(value: unknown): number {
|
|
193
|
+
const n = typeof value === "number" && Number.isFinite(value) ? Math.floor(value) : NaN;
|
|
194
|
+
if (Number.isNaN(n)) return DEFAULT_SECTIONS_MAX;
|
|
195
|
+
if (n <= 0) return 0;
|
|
196
|
+
return Math.min(n, SECTIONS_MAX_LIMIT);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* Reach for one SKILL.md. A file that cannot be stat'ed or read answers
|
|
201
|
+
* `reachable: false` instead of throwing: the catalog has to render, and one
|
|
202
|
+
* unreadable skill must not take the page down with it.
|
|
203
|
+
*
|
|
204
|
+
* `sectionsMax` caps the returned heading list; the cached parse keeps the
|
|
205
|
+
* whole list, so two callers asking for different caps share one read.
|
|
206
|
+
*/
|
|
207
|
+
export function readSkillReach(
|
|
208
|
+
filePath: string,
|
|
209
|
+
sectionsMax: number = DEFAULT_SECTIONS_MAX,
|
|
210
|
+
): Reach {
|
|
211
|
+
const key = resolve(filePath);
|
|
212
|
+
let size: number;
|
|
213
|
+
let mtimeMs: number;
|
|
214
|
+
try {
|
|
215
|
+
const stat = statSync(key);
|
|
216
|
+
size = stat.size;
|
|
217
|
+
mtimeMs = stat.mtimeMs;
|
|
218
|
+
} catch {
|
|
219
|
+
cache.delete(key);
|
|
220
|
+
return { reachable: false };
|
|
221
|
+
}
|
|
222
|
+
let entry = cache.get(key);
|
|
223
|
+
if (!entry || entry.mtimeMs !== mtimeMs || entry.size !== size) {
|
|
224
|
+
let text: string;
|
|
225
|
+
try {
|
|
226
|
+
text = readFileSync(key, "utf-8");
|
|
227
|
+
} catch {
|
|
228
|
+
cache.delete(key);
|
|
229
|
+
return { reachable: false, bytes: size };
|
|
230
|
+
}
|
|
231
|
+
const headings = scanHeadings(text);
|
|
232
|
+
entry = {
|
|
233
|
+
mtimeMs,
|
|
234
|
+
size,
|
|
235
|
+
reach: {
|
|
236
|
+
reachable: true,
|
|
237
|
+
lines: countLines(text),
|
|
238
|
+
bytes: size,
|
|
239
|
+
chars: text.length,
|
|
240
|
+
estTokens: Math.ceil(text.length / CHARS_PER_TOKEN),
|
|
241
|
+
sectionCount: headings.length,
|
|
242
|
+
sections: headings,
|
|
243
|
+
},
|
|
244
|
+
};
|
|
245
|
+
cache.set(key, entry);
|
|
246
|
+
}
|
|
247
|
+
const { sections: all = [], ...scalars } = entry.reach;
|
|
248
|
+
const cap = clampSectionsMax(sectionsMax);
|
|
249
|
+
if (cap === 0) return scalars;
|
|
250
|
+
return { ...scalars, sections: cap >= all.length ? all : all.slice(0, cap) };
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** Test seam: forget every memoized reach measurement. */
|
|
254
|
+
export function clearReachCache(): void {
|
|
255
|
+
cache.clear();
|
|
256
|
+
}
|