pi-braid 0.40.3 → 0.40.6

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.
Files changed (85) hide show
  1. package/AGENTS.md +17 -18
  2. package/README.md +116 -130
  3. package/TOOLS.md +35 -35
  4. package/build-info.json +4 -4
  5. package/dist/extensions/core/agent-environment/index.js +4 -3
  6. package/dist/extensions/core/prompt-builder/index.js +12 -7
  7. package/dist/extensions/core/prompt-builder/instance-composition.d.ts +51 -10
  8. package/dist/extensions/core/prompt-builder/instance-composition.js +87 -14
  9. package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +3 -3
  10. package/dist/extensions/core/prompt-builder/system-info-tool.js +3 -3
  11. package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
  12. package/dist/extensions/core/skills-tool/auto-inject.d.ts +178 -17
  13. package/dist/extensions/core/skills-tool/auto-inject.js +264 -23
  14. package/dist/extensions/core/skills-tool/index.d.ts +70 -2
  15. package/dist/extensions/core/skills-tool/index.js +149 -15
  16. package/dist/extensions/core/skills-tool/reach.d.ts +119 -0
  17. package/dist/extensions/core/skills-tool/reach.js +213 -0
  18. package/dist/extensions/core/skills-tool/skill-triggers.d.ts +74 -13
  19. package/dist/extensions/core/skills-tool/skill-triggers.js +105 -24
  20. package/dist/extensions/enforcement/handlers/register-session-compact.js +12 -1
  21. package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +15 -34
  22. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +2 -1
  23. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +55 -28
  24. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +14 -10
  25. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +88 -82
  26. package/dist/extensions/enforcement/resume-state.d.ts +76 -0
  27. package/dist/extensions/enforcement/resume-state.js +90 -0
  28. package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +9 -0
  29. package/dist/extensions/enforcement/substate/context-hygiene-state.js +8 -0
  30. package/dist/extensions/enforcement/whisper.d.ts +12 -0
  31. package/dist/extensions/enforcement/whisper.js +16 -1
  32. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +14 -6
  33. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +7 -0
  34. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +372 -0
  35. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +8 -2
  36. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +54 -21
  37. package/dist/lib/config/braid-paths.d.ts +14 -0
  38. package/dist/lib/config/braid-paths.js +18 -0
  39. package/dist/lib/config/braid-settings.d.ts +21 -0
  40. package/dist/lib/config/braid-settings.js +16 -0
  41. package/dist/lib/detection/context-tiers.d.ts +47 -3
  42. package/dist/lib/detection/context-tiers.js +122 -13
  43. package/dist/lib/events/turn-boundary.d.ts +78 -0
  44. package/dist/lib/events/turn-boundary.js +91 -0
  45. package/dist/lib/orchestrator/workers.d.ts +3 -2
  46. package/dist/lib/orchestrator/workers.js +22 -4
  47. package/dist/lib/state/global-state.d.ts +1 -1
  48. package/docs/CONTEXT-POLICY.md +8 -0
  49. package/docs/LOCAL_DEV.md +0 -1
  50. package/docs/ROADMAP.md +5 -5
  51. package/docs/SETUP.md +19 -18
  52. package/package.json +2 -1
  53. package/skills/herdr-topology/SKILL.md +6 -1
  54. package/skills/research/SKILL.md +32 -0
  55. package/skills/subagent-orchestration/SKILL.md +2 -2
  56. package/src/extensions/core/agent-environment/index.ts +4 -3
  57. package/src/extensions/core/prompt-builder/AGENTS.md +8 -4
  58. package/src/extensions/core/prompt-builder/index.ts +12 -7
  59. package/src/extensions/core/prompt-builder/instance-composition.ts +98 -14
  60. package/src/extensions/core/prompt-builder/system-info-tool.ts +3 -3
  61. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  62. package/src/extensions/core/skills-tool/auto-inject.ts +350 -27
  63. package/src/extensions/core/skills-tool/index.ts +217 -15
  64. package/src/extensions/core/skills-tool/reach.ts +256 -0
  65. package/src/extensions/core/skills-tool/skill-triggers.ts +130 -23
  66. package/src/extensions/enforcement/handlers/register-session-compact.ts +12 -1
  67. package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +23 -36
  68. package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +59 -29
  69. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +101 -81
  70. package/src/extensions/enforcement/resume-state.ts +127 -0
  71. package/src/extensions/enforcement/substate/context-hygiene-state.ts +17 -0
  72. package/src/extensions/enforcement/whisper.ts +21 -1
  73. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +20 -5
  74. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +370 -0
  75. package/src/extensions/memory/AGENTS.md +25 -1
  76. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +80 -27
  77. package/src/lib/config/braid-paths.ts +20 -0
  78. package/src/lib/config/braid-settings.ts +46 -0
  79. package/src/lib/detection/context-tiers.ts +186 -13
  80. package/src/lib/events/AGENTS.md +1 -0
  81. package/src/lib/events/turn-boundary.ts +115 -0
  82. package/src/lib/orchestrator/workers.ts +33 -12
  83. package/src/lib/state/global-state.ts +1 -0
  84. package/src/lib/utils/AGENTS.md +1 -1
  85. 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
@@ -21,8 +33,10 @@
21
33
  */
22
34
  import { Type } from "typebox";
23
35
  import { createLogger } from "../../../lib/core/logger.js";
24
- import { registerAutoInject, updateSkillCache, getSkillStats, getDurableSkillStats, resolveDiscoveryMode, } from "./auto-inject.js";
25
- import { readSkillTriggers } from "./skill-triggers.js";
36
+ import { getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
37
+ import { registerAutoInject, updateSkillCache, getSkillStats, getDurableSkillStats, resolveDiscoveryMode, rankSkillsDeterministic, } from "./auto-inject.js";
38
+ import { readSkillTriggerEntries } from "./skill-triggers.js";
39
+ import { clampSectionsMax, DEFAULT_SECTIONS_MAX, SECTIONS_MAX_LIMIT, readSkillReach, } from "./reach.js";
26
40
  import { getMonthlyAdoptionRollup } from "./session-records.js";
27
41
  const log = createLogger("skills-tool");
28
42
  let cachedSkills = [];
@@ -33,10 +47,13 @@ let cachedSkills = [];
33
47
  * shape), and the memoized read makes repeat turns stat-only.
34
48
  */
35
49
  export function setCachedSkills(skills) {
36
- cachedSkills = skills.map((s) => ({
37
- ...s,
38
- triggers: readSkillTriggers(s.filePath, s.description),
39
- }));
50
+ cachedSkills = skills.map((s) => {
51
+ const entries = readSkillTriggerEntries(s.filePath, s.description);
52
+ const triggerSources = {};
53
+ for (const entry of entries)
54
+ triggerSources[entry.phrase] = entry.source;
55
+ return { ...s, triggers: entries.map((entry) => entry.phrase), triggerSources };
56
+ });
40
57
  // Sync with auto-inject subsystem (enriched cache — triggers ride along)
41
58
  updateSkillCache(cachedSkills);
42
59
  log.debug(`Cached ${skills.length} skills for list_skills tool`);
@@ -64,16 +81,100 @@ function formatSource(skill) {
64
81
  return "project";
65
82
  return src;
66
83
  }
84
+ /**
85
+ * The current task text: the newest user message on the live branch.
86
+ *
87
+ * A tool call carries no prompt of its own and pi hands tools no turn prompt,
88
+ * but the branch does — and its newest user message is the task the agent is
89
+ * working on. A resumed session therefore ranks against its real task even
90
+ * though this process never saw the prompt arrive. Best-effort: no branch, an
91
+ * unreadable entry, or a non-text message yields "", and the caller then
92
+ * returns the catalog order rather than inventing a task.
93
+ */
94
+ export function currentTaskText(ctx) {
95
+ try {
96
+ const sm = ctx.sessionManager;
97
+ const branch = sm?.getBranch?.() ?? [];
98
+ for (let i = branch.length - 1; i >= 0; i--) {
99
+ const entry = branch[i];
100
+ if (entry?.type !== "message" || entry.message?.role !== "user")
101
+ continue;
102
+ const content = entry.message.content;
103
+ if (typeof content === "string")
104
+ return content;
105
+ if (Array.isArray(content)) {
106
+ return content
107
+ .map((part) => part)
108
+ .filter((part) => part?.type === "text" && typeof part.text === "string")
109
+ .map((part) => part.text)
110
+ .join("\n");
111
+ }
112
+ return "";
113
+ }
114
+ }
115
+ catch {
116
+ // Best-effort: a stale ctx or an absent tree yields no text.
117
+ }
118
+ return "";
119
+ }
120
+ /** Reorder `skills` by `names`, appending everything the list did not mention. */
121
+ function orderByNames(skills, names) {
122
+ const byName = new Map(skills.map((s) => [s.name, s]));
123
+ const out = [];
124
+ for (const name of names) {
125
+ const skill = byName.get(name);
126
+ if (!skill)
127
+ continue;
128
+ byName.delete(name);
129
+ out.push(skill);
130
+ }
131
+ for (const skill of skills)
132
+ if (byName.has(skill.name))
133
+ out.push(skill);
134
+ return out;
135
+ }
136
+ /**
137
+ * Resolve the catalog order for one read.
138
+ *
139
+ * `keyword` and `catalog` are the two answers: the deterministic ranking (with
140
+ * its verdict on how confident that ranking is), or the plain catalog. A
141
+ * missing task text is nobody's question, so the catalog order stands and the
142
+ * report says `no-task` rather than pretending to rank.
143
+ */
144
+ export function resolveRanking(ctx, skills, options) {
145
+ if (options.rank === "catalog")
146
+ return { order: skills, relevance: new Map() };
147
+ const det = rankSkillsDeterministic(skills, currentTaskText(ctx));
148
+ const relevance = new Map();
149
+ for (const row of det.ranked)
150
+ relevance.set(row.skill.name, rowOf(row));
151
+ const order = det.basis === "no-task"
152
+ ? skills
153
+ : orderByNames(skills, det.ranked.map((row) => row.skill.name));
154
+ return {
155
+ order,
156
+ ranking: {
157
+ tier: "keyword",
158
+ basis: det.basis,
159
+ policy: options.policy ?? getSkillsRankingMode(),
160
+ },
161
+ relevance,
162
+ };
163
+ }
164
+ /** A ranked row as the response reports it (only rows with evidence get here). */
165
+ function rowOf(row) {
166
+ return { score: row.score, reason: row.reason ?? "description" };
167
+ }
67
168
  // Extension factory:
68
169
  export default function skillsToolExtension(pi) {
69
170
  registerAutoInject(pi);
70
171
  pi.registerTool({
71
172
  name: "list_skills",
72
173
  label: "List Skills",
73
- description: "Discover skills on demand: paginated catalog (name, filePath, description, source); `read` a SKILL.md to load it.",
174
+ description: "Discover skills on demand: paginated catalog (name, filePath, description, source) plus each skill's reach (reachable, lines, bytes, chars, estTokens, sectionCount, section headings with line numbers), so the price of a read is visible before the read. Rows are ordered by relevance to the current task; a row with match evidence carries relevance {score, reason}, and the response carries ranking {tier, basis, policy}. Pass rank: 'catalog' for the plain catalog order. `read` a SKILL.md to load it.",
74
175
  parameters: Type.Object({
75
176
  action: Type.Literal("list", {
76
- description: "list = paginated catalog (name, filePath, description, source)",
177
+ description: "list = paginated catalog with per-skill reach (reachable, lines, bytes, chars, estTokens, sectionCount, sections)",
77
178
  }),
78
179
  page: Type.Optional(Type.Number({
79
180
  minimum: 1,
@@ -86,32 +187,65 @@ export default function skillsToolExtension(pi) {
86
187
  default: 10,
87
188
  description: "Entries per page for list",
88
189
  })),
190
+ sectionsMax: Type.Optional(Type.Number({
191
+ minimum: 0,
192
+ maximum: SECTIONS_MAX_LIMIT,
193
+ default: DEFAULT_SECTIONS_MAX,
194
+ description: "Headings reported per skill; 0 omits the section list and keeps sectionCount",
195
+ })),
196
+ rank: Type.Optional(Type.Union([Type.Literal("relevance"), Type.Literal("catalog")], {
197
+ default: "relevance",
198
+ description: "relevance (default) = order by fit to the current task; catalog = the plain catalog order, with no ranking fields",
199
+ })),
89
200
  }),
90
- execute: async (_id, params, _signal, _onUpdate, _ctx) => {
201
+ execute: async (_id, params, signal, _onUpdate, ctx) => {
91
202
  const page = params.page ?? 1;
92
203
  const pageSize = params.pageSize ?? 10;
93
- const start = (page - 1) * pageSize;
204
+ const sectionsMax = clampSectionsMax(params.sectionsMax);
205
+ const rank = params.rank ?? "relevance";
94
206
  // Explicit-invocation-only skills stay out of the catalog; the cache
95
207
  // itself stays unfiltered for the read-detector that counts explicit
96
208
  // loads.
97
209
  const visible = cachedSkills.filter((s) => !s.disableModelInvocation);
98
- const slice = visible.slice(start, start + pageSize);
99
- const total = visible.length;
210
+ const answer = resolveRanking(ctx, visible, { rank });
211
+ const total = answer.order.length;
212
+ const start = (page - 1) * pageSize;
213
+ const slice = answer.order.slice(start, start + pageSize);
100
214
  const hasMore = start + pageSize < total;
101
215
  const skills = slice.map((s) => ({
102
216
  name: s.name,
103
217
  filePath: s.filePath,
104
218
  description: (s.description ?? "").slice(0, 280),
105
219
  source: formatSource(s),
220
+ ...readSkillReach(s.filePath, sectionsMax),
221
+ // Evidence where it exists: a row with no match carries no relevance
222
+ // field. Every row paying ~60 bytes for "nothing matched" pushed the
223
+ // shipped page past its measured prompt budget (12.0KB -> 12.8KB), and
224
+ // the empty object carried no information the absence does not.
225
+ ...(answer.relevance.has(s.name) ? { relevance: answer.relevance.get(s.name) } : {}),
106
226
  }));
107
227
  return {
108
228
  content: [
109
229
  {
110
230
  type: "text",
111
- text: JSON.stringify({ page, pageSize, total, hasMore, skills }, null, 2),
231
+ text: JSON.stringify({
232
+ page,
233
+ pageSize,
234
+ total,
235
+ hasMore,
236
+ ...(answer.ranking ? { ranking: answer.ranking } : {}),
237
+ skills,
238
+ }, null, 2),
112
239
  },
113
240
  ],
114
- details: { total, page, pageSize, hasMore, returned: skills.length },
241
+ details: {
242
+ total,
243
+ page,
244
+ pageSize,
245
+ hasMore,
246
+ returned: skills.length,
247
+ ...(answer.ranking ? { tier: answer.ranking.tier, basis: answer.ranking.basis } : {}),
248
+ },
115
249
  };
116
250
  },
117
251
  });
@@ -0,0 +1,119 @@
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
+ * Characters per token. The same divisor the pre-send guard uses
51
+ * (`packages/providers/presend-guard.ts`, `CHARS_PER_TOKEN`) and the one
52
+ * pi-core's `estimateTokens` applies, so a reach estimate and a payload
53
+ * estimate are comparable numbers rather than two private conventions.
54
+ * Declared here instead of imported: providers is a standalone package with no
55
+ * import path into core.
56
+ */
57
+ export declare const CHARS_PER_TOKEN = 4;
58
+ /**
59
+ * Headings reported per skill when the caller does not ask for another cap.
60
+ *
61
+ * Six is a prompt-budget number, not a taste one: over the shipped pack the
62
+ * heaviest ten-row page of the pretty-printed catalog measures 11984 bytes at
63
+ * six headings, 304 bytes under the 12KB bound, and 13568 at eight, where it
64
+ * crosses. Callers who want the full contents pass `sectionsMax` (up to
65
+ * SECTIONS_MAX_LIMIT).
66
+ */
67
+ export declare const DEFAULT_SECTIONS_MAX = 6;
68
+ /**
69
+ * Upper bound on the per-skill heading cap - a request above it is a bug.
70
+ * `list_skills` declares this same value as its schema maximum, so the ceiling
71
+ * a caller meets through the tool and the ceiling `clampSectionsMax` enforces
72
+ * cannot drift into two numbers.
73
+ */
74
+ export declare const SECTIONS_MAX_LIMIT = 64;
75
+ export interface SkillSection {
76
+ /** 1-indexed line the heading sits on. */
77
+ line: number;
78
+ /** Heading text with its leading `#`s stripped, trimmed, capped. */
79
+ text: string;
80
+ }
81
+ export interface SkillReach {
82
+ reachable: true;
83
+ lines: number;
84
+ bytes: number;
85
+ /** `String.length`: UTF-16 code units, so astral-plane text counts twice. */
86
+ chars: number;
87
+ estTokens: number;
88
+ /** Total headings in the file, independent of the per-call report cap. */
89
+ sectionCount: number;
90
+ /** Omitted when the caller asked for no section list. */
91
+ sections?: SkillSection[];
92
+ }
93
+ export interface UnreachableReach {
94
+ reachable: false;
95
+ /** Stat size when stat() succeeded and the read failed; absent otherwise. */
96
+ bytes?: number;
97
+ }
98
+ export type Reach = SkillReach | UnreachableReach;
99
+ /**
100
+ * Lines in a file's text: a trailing newline ends the last line rather than
101
+ * opening a blank one, an empty file has no lines, and a final line with no
102
+ * terminating newline counts, because the partial line is content the read
103
+ * pays for.
104
+ */
105
+ export declare function countLines(text: string): number;
106
+ /** Clamp a caller-supplied heading cap into range; 0 means "no list". */
107
+ export declare function clampSectionsMax(value: unknown): number;
108
+ /**
109
+ * Reach for one SKILL.md. A file that cannot be stat'ed or read answers
110
+ * `reachable: false` instead of throwing: the catalog has to render, and one
111
+ * unreadable skill must not take the page down with it.
112
+ *
113
+ * `sectionsMax` caps the returned heading list; the cached parse keeps the
114
+ * whole list, so two callers asking for different caps share one read.
115
+ */
116
+ export declare function readSkillReach(filePath: string, sectionsMax?: number): Reach;
117
+ /** Test seam: forget every memoized reach measurement. */
118
+ export declare function clearReachCache(): void;
119
+ //# sourceMappingURL=reach.d.ts.map
@@ -0,0 +1,213 @@
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
+ import { readFileSync, statSync } from "node:fs";
50
+ import { resolve } from "node:path";
51
+ /**
52
+ * Characters per token. The same divisor the pre-send guard uses
53
+ * (`packages/providers/presend-guard.ts`, `CHARS_PER_TOKEN`) and the one
54
+ * pi-core's `estimateTokens` applies, so a reach estimate and a payload
55
+ * estimate are comparable numbers rather than two private conventions.
56
+ * Declared here instead of imported: providers is a standalone package with no
57
+ * import path into core.
58
+ */
59
+ export const CHARS_PER_TOKEN = 4;
60
+ /**
61
+ * Headings reported per skill when the caller does not ask for another cap.
62
+ *
63
+ * Six is a prompt-budget number, not a taste one: over the shipped pack the
64
+ * heaviest ten-row page of the pretty-printed catalog measures 11984 bytes at
65
+ * six headings, 304 bytes under the 12KB bound, and 13568 at eight, where it
66
+ * crosses. Callers who want the full contents pass `sectionsMax` (up to
67
+ * SECTIONS_MAX_LIMIT).
68
+ */
69
+ export const DEFAULT_SECTIONS_MAX = 6;
70
+ /** A heading is a table-of-contents entry, not a paragraph. */
71
+ const SECTION_TEXT_MAX = 80;
72
+ /**
73
+ * Upper bound on the per-skill heading cap - a request above it is a bug.
74
+ * `list_skills` declares this same value as its schema maximum, so the ceiling
75
+ * a caller meets through the tool and the ceiling `clampSectionsMax` enforces
76
+ * cannot drift into two numbers.
77
+ */
78
+ export const SECTIONS_MAX_LIMIT = 64;
79
+ /**
80
+ * ATX heading: up to three spaces of indent (four would be an indented code
81
+ * block), one to six `#`, then a space or the end of the line - so `#region`
82
+ * in a TypeScript sample is not a heading.
83
+ */
84
+ const ATX_HEADING = /^ {0,3}(#{1,6})(?:[ \t]+(.*))?$/;
85
+ /**
86
+ * A heading's optional closing sequence: `## Title ##`, trailing whitespace
87
+ * allowed - `## Title ## ` closes the same way, and the spaces after the run
88
+ * are not part of the text.
89
+ */
90
+ const CLOSING_HASHES = /[ \t]+#+[ \t]*$/;
91
+ /** A fence line: up to three spaces of indent, then three or more backticks or tildes. */
92
+ const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
93
+ const cache = new Map();
94
+ /**
95
+ * Lines in a file's text: a trailing newline ends the last line rather than
96
+ * opening a blank one, an empty file has no lines, and a final line with no
97
+ * terminating newline counts, because the partial line is content the read
98
+ * pays for.
99
+ */
100
+ export function countLines(text) {
101
+ if (text === "")
102
+ return 0;
103
+ let newlines = 0;
104
+ for (let i = 0; i < text.length; i++)
105
+ if (text[i] === "\n")
106
+ newlines++;
107
+ return text.endsWith("\n") ? newlines : newlines + 1;
108
+ }
109
+ /**
110
+ * Headings in document order, skipping fenced blocks. A fence opens on a run
111
+ * of backticks or tildes (with or without an info string) and closes only on a
112
+ * run of the same character at least as long, so a `~~~` sample inside a
113
+ * backtick fence is content, not a delimiter. A backtick run followed by more
114
+ * backticks (` ```a`` `) is not a fence at all, per CommonMark.
115
+ */
116
+ function scanHeadings(text) {
117
+ const headings = [];
118
+ let fence = null;
119
+ const lines = text.split("\n");
120
+ for (let i = 0; i < lines.length; i++) {
121
+ const line = lines[i].endsWith("\r") ? lines[i].slice(0, -1) : lines[i];
122
+ const fenceLine = FENCE.exec(line);
123
+ if (fence) {
124
+ if (fenceLine &&
125
+ fenceLine[1][0] === fence.marker &&
126
+ fenceLine[1].length >= fence.length &&
127
+ fenceLine[2].trim() === "") {
128
+ fence = null;
129
+ }
130
+ continue;
131
+ }
132
+ if (fenceLine && !(fenceLine[1][0] === "`" && fenceLine[2].includes("`"))) {
133
+ fence = { marker: fenceLine[1][0], length: fenceLine[1].length };
134
+ continue;
135
+ }
136
+ const heading = ATX_HEADING.exec(line);
137
+ if (!heading)
138
+ continue;
139
+ const text = (heading[2] ?? "").replace(CLOSING_HASHES, "").trim();
140
+ headings.push({
141
+ line: i + 1,
142
+ text: text.length > SECTION_TEXT_MAX ? text.slice(0, SECTION_TEXT_MAX) : text,
143
+ });
144
+ }
145
+ return headings;
146
+ }
147
+ /** Clamp a caller-supplied heading cap into range; 0 means "no list". */
148
+ export function clampSectionsMax(value) {
149
+ const n = typeof value === "number" && Number.isFinite(value) ? Math.floor(value) : NaN;
150
+ if (Number.isNaN(n))
151
+ return DEFAULT_SECTIONS_MAX;
152
+ if (n <= 0)
153
+ return 0;
154
+ return Math.min(n, SECTIONS_MAX_LIMIT);
155
+ }
156
+ /**
157
+ * Reach for one SKILL.md. A file that cannot be stat'ed or read answers
158
+ * `reachable: false` instead of throwing: the catalog has to render, and one
159
+ * unreadable skill must not take the page down with it.
160
+ *
161
+ * `sectionsMax` caps the returned heading list; the cached parse keeps the
162
+ * whole list, so two callers asking for different caps share one read.
163
+ */
164
+ export function readSkillReach(filePath, sectionsMax = DEFAULT_SECTIONS_MAX) {
165
+ const key = resolve(filePath);
166
+ let size;
167
+ let mtimeMs;
168
+ try {
169
+ const stat = statSync(key);
170
+ size = stat.size;
171
+ mtimeMs = stat.mtimeMs;
172
+ }
173
+ catch {
174
+ cache.delete(key);
175
+ return { reachable: false };
176
+ }
177
+ let entry = cache.get(key);
178
+ if (!entry || entry.mtimeMs !== mtimeMs || entry.size !== size) {
179
+ let text;
180
+ try {
181
+ text = readFileSync(key, "utf-8");
182
+ }
183
+ catch {
184
+ cache.delete(key);
185
+ return { reachable: false, bytes: size };
186
+ }
187
+ const headings = scanHeadings(text);
188
+ entry = {
189
+ mtimeMs,
190
+ size,
191
+ reach: {
192
+ reachable: true,
193
+ lines: countLines(text),
194
+ bytes: size,
195
+ chars: text.length,
196
+ estTokens: Math.ceil(text.length / CHARS_PER_TOKEN),
197
+ sectionCount: headings.length,
198
+ sections: headings,
199
+ },
200
+ };
201
+ cache.set(key, entry);
202
+ }
203
+ const { sections: all = [], ...scalars } = entry.reach;
204
+ const cap = clampSectionsMax(sectionsMax);
205
+ if (cap === 0)
206
+ return scalars;
207
+ return { ...scalars, sections: cap >= all.length ? all : all.slice(0, cap) };
208
+ }
209
+ /** Test seam: forget every memoized reach measurement. */
210
+ export function clearReachCache() {
211
+ cache.clear();
212
+ }
213
+ //# sourceMappingURL=reach.js.map
@@ -1,21 +1,56 @@
1
1
  /**
2
- * Frontmatter `triggers:` phrases for the suggestion matcher.
2
+ * Curated trigger phrases for the suggestion matcher.
3
3
  *
4
4
  * pi's skill objects carry a fixed shape (name, description, path, source),
5
5
  * so curated trigger phrases never reach braid through the prompt-builder
6
- * cache — read them from the SKILL.md frontmatter directly. Reads are
7
- * memoized by file mtime + size: repeated turns stat, only changed or
8
- * first-seen files parse.
6
+ * cache — read them from the SKILL.md itself. Reads are memoized by file
7
+ * mtime + size: repeated turns stat, only changed or first-seen files parse.
8
+ *
9
+ * Authors wrote the phrases in three places, and all three are read:
10
+ * 1. frontmatter, under `trigger:` (a comma-separated string) or
11
+ * `triggers:` (a YAML list) — the canonical field;
12
+ * 2. a `## trigger:` body heading, quoted or bare (9 of core's 22 skills
13
+ * carry the phrases here and nowhere else);
14
+ * 3. the description's trailing "Triggers: …" segment, the pack's older
15
+ * convention.
16
+ * A file may use any of them, and every source that yields phrases is read:
17
+ * the lists are MERGED in that order, so a phrase an author put in the body
18
+ * heading survives when frontmatter also declares some, and the frontmatter
19
+ * still outranks the rest. First-wins was the defect: agent-testing declares
20
+ * seven phrases in its description tail and five in its body heading, and
21
+ * precedence let the tail replace the heading, so the five never reached the
22
+ * matcher while the file said they had.
9
23
  *
10
24
  * A trigger hit scores like a name hit and qualifies a skill whose
11
25
  * description alone would stay under the qualification bar — the phrase is
12
26
  * the author's own signal of when the skill applies, sharper than any
13
- * description keyword.
27
+ * description keyword. Matching is case-insensitive: prompts arrive
28
+ * capitalized ("MASTERSHIP TRANSFER: …"), and a phrase that only matched
29
+ * lowercase text would be dead in production while a lowercase-only unit
30
+ * fixture kept the suite green.
31
+ */
32
+ /**
33
+ * Max trigger phrases read per skill — a longer list is an authoring bug, not a
34
+ * matcher input. Three authored lists reach the cap: braid-reference (16
35
+ * phrases), pi-reference (15), and agent-testing, which fills it exactly (7 in
36
+ * the description tail + 5 in the body heading) now that the sources merge.
37
+ * The cap assertion lives in test-skill-triggers-body.mjs; raising the number
38
+ * means changing it there.
14
39
  */
15
- /** Max trigger phrases read per skill — a longer list is an authoring bug, not a matcher input. */
16
40
  export declare const MAX_TRIGGERS = 12;
17
41
  /** Max characters of one trigger phrase. */
18
42
  export declare const MAX_TRIGGER_CHARS = 64;
43
+ /**
44
+ * Where an authored phrase came from. Precedence (frontmatter, heading,
45
+ * description) orders the merged list and decides which source the cap cuts
46
+ * last; the label itself is what a ranking row reports as its evidence.
47
+ */
48
+ export type TriggerSource = "frontmatter" | "heading" | "description";
49
+ /** One authored phrase and the source that declared it. */
50
+ export interface TriggerEntry {
51
+ phrase: string;
52
+ source: TriggerSource;
53
+ }
19
54
  /**
20
55
  * Normalize a frontmatter `triggers` value into clean phrases. Accepts a YAML
21
56
  * list or a comma-separated string; drops empty, overlong, and surplus
@@ -23,14 +58,39 @@ export declare const MAX_TRIGGER_CHARS = 64;
23
58
  */
24
59
  export declare function normalizeTriggers(value: unknown): string[];
25
60
  /**
26
- * Read a skill's trigger phrases: frontmatter `triggers:` first (canonical),
27
- * then the description's trailing "Triggers: …" segment — the pack's existing
28
- * convention (7 of 32 skills carry one) predates the frontmatter field, and
29
- * the matcher should honor what authors already wrote. Missing/unreadable
30
- * file or malformed YAML → no triggers (the matcher falls back to
31
- * name/description scoring alone). Memoized: unchanged files never re-read.
61
+ * Read a skill's trigger phrases from every source the file uses, merged in
62
+ * priority order: frontmatter (`trigger` or `triggers`), then a `## trigger:`
63
+ * body heading, then the description's trailing "Triggers: …" segment.
64
+ * Missing/unreadable file or malformed YAML → no frontmatter phrases, and the
65
+ * description tail is still read.
66
+ * Memoized: unchanged files never re-read.
32
67
  */
33
68
  export declare function readSkillTriggers(filePath: string, description?: string): string[];
69
+ /**
70
+ * Read a skill's authored phrases WITH their provenance, merged in priority
71
+ * order: frontmatter (`trigger` or `triggers`), then a `## trigger:` body
72
+ * heading, then the description's trailing "Triggers: …" segment.
73
+ * Missing/unreadable file or malformed YAML → no frontmatter phrases, and the
74
+ * description tail is still read.
75
+ * Memoized: unchanged files never re-read (a different description argument is
76
+ * a miss, because the merged list depends on it).
77
+ */
78
+ export declare function readSkillTriggerEntries(filePath: string, description?: string): TriggerEntry[];
79
+ /**
80
+ * Merge authored phrase sources into one bounded list, in priority order.
81
+ *
82
+ * The cap is a budget spent down the list, so when it binds the LOWEST
83
+ * priority source is the one that loses phrases — a higher-priority source is
84
+ * never cut to make room for a later one. A phrase repeated by two sources
85
+ * keeps its first (highest-priority) source. Pure.
86
+ */
87
+ export declare function mergeTriggerEntries(sources: TriggerEntry[][]): TriggerEntry[];
88
+ /**
89
+ * Trigger phrases from a body `## trigger: "a, b, c"` heading. The FIRST such
90
+ * heading is the whole input: a body with several is an authoring error, not
91
+ * extra matcher input. Quotes around the value are stripped. Pure.
92
+ */
93
+ export declare function parseBodyTriggers(body: string): string[];
34
94
  /**
35
95
  * Trigger phrases from a description's trailing "Triggers: …" segment —
36
96
  * the contrib pack convention ("… Use when X. Triggers: meme, image macro.").
@@ -42,7 +102,8 @@ export declare function clearSkillTriggerCache(): void;
42
102
  /**
43
103
  * True when the phrase occurs in the prompt on word boundaries ("pane" does
44
104
  * not match "paneled"). Multi-word phrases match literally; hyphenated
45
- * prompt tokens count as boundaries.
105
+ * prompt tokens count as boundaries. Phrases are normalized to lowercase, so
106
+ * the prompt is folded to match: the boundary classes stay lowercase-only.
46
107
  */
47
108
  export declare function triggerMatches(phrase: string, promptText: string): boolean;
48
109
  //# sourceMappingURL=skill-triggers.d.ts.map