pi-braid 0.41.2 → 0.42.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/CHANGELOG.md +1006 -0
  2. package/build-info.json +4 -4
  3. package/dist/extensions/cognitive/metacognition/handlers/think.js +9 -0
  4. package/dist/extensions/core/prompt-builder/index.js +10 -11
  5. package/dist/extensions/core/skills-tool/auto-inject.d.ts +17 -2
  6. package/dist/extensions/core/skills-tool/auto-inject.js +100 -24
  7. package/dist/extensions/core/skills-tool/index.js +47 -26
  8. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +149 -28
  9. package/dist/extensions/core/skills-tool/loading-guidance.js +257 -29
  10. package/dist/extensions/manifest.js +6 -0
  11. package/dist/extensions/self/path-miss/detect.d.ts +30 -0
  12. package/dist/extensions/self/path-miss/detect.js +67 -0
  13. package/dist/extensions/self/path-miss/index.d.ts +33 -0
  14. package/dist/extensions/self/path-miss/index.js +118 -0
  15. package/dist/lib/core/event-names.d.ts +1 -0
  16. package/dist/lib/core/event-names.js +1 -0
  17. package/dist/lib/utils/argument-report.d.ts +41 -0
  18. package/dist/lib/utils/argument-report.js +95 -0
  19. package/package.json +4 -3
  20. package/src/extensions/cognitive/metacognition/handlers/think.ts +9 -0
  21. package/src/extensions/core/AGENTS.md +8 -6
  22. package/src/extensions/core/prompt-builder/AGENTS.md +2 -2
  23. package/src/extensions/core/prompt-builder/index.ts +10 -14
  24. package/src/extensions/core/skills-tool/auto-inject.ts +138 -26
  25. package/src/extensions/core/skills-tool/index.ts +60 -37
  26. package/src/extensions/core/skills-tool/loading-guidance.ts +303 -29
  27. package/src/extensions/manifest.ts +6 -0
  28. package/src/extensions/self/AGENTS.md +2 -1
  29. package/src/extensions/self/path-miss/AGENTS.md +39 -0
  30. package/src/extensions/self/path-miss/detect.ts +78 -0
  31. package/src/extensions/self/path-miss/index.ts +135 -0
  32. package/src/lib/core/event-names.ts +1 -0
  33. package/src/lib/utils/AGENTS.md +1 -0
  34. package/src/lib/utils/argument-report.ts +105 -0
package/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.41.2",
4
- "sha": "b46aa4f474e84f5394ddcbc4feb549181b0c6c8e",
5
- "shaShort": "b46aa4f",
3
+ "version": "0.42.1",
4
+ "sha": "b16fdbb3b1f434c2807942412b899a9ca674cfe2",
5
+ "shaShort": "b16fdbb",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-10-25T10:56:25.509Z"
8
+ "packedAt": "2026-10-27T11:16:21.651Z"
9
9
  }
@@ -5,6 +5,7 @@ import { Type } from "typebox";
5
5
  import { resolveUtilityModel, tryModelChain } from "../../../../lib/ai/model-resolver.js";
6
6
  import { estimateComplexity, complexityToDepth, getBudget, getCalibrationStats, computeCalibrationError, THINK_TYPES, DEFAULT_THINK_TYPE, DEPTH_LEVELS, } from "./think-budget.js";
7
7
  import { criticGate } from "../../../../lib/ai/critic-gate.js";
8
+ import { checkArgumentValues } from "../../../../lib/utils/argument-report.js";
8
9
  import { getExtensionState } from "../../../../lib/state/extension-state.js";
9
10
  import { createLogger } from "../../../../lib/core/logger.js";
10
11
  const log = createLogger("metacognition");
@@ -128,6 +129,14 @@ export function createThinkTool() {
128
129
  description: "Think deeply with structured reasoning before making high-stakes decisions.",
129
130
  promptSnippet: "Think deeply with structured reasoning before decisions",
130
131
  parameters: thinkSchema,
132
+ // pi validates arguments before `execute` is reached, and its own refusal
133
+ // for a guessed enum or a missing field names neither. This hook runs
134
+ // first, inside the same guarded block, and refuses with the values the
135
+ // schema above already declares.
136
+ prepareArguments: (args) => {
137
+ checkArgumentValues("think", thinkSchema, args);
138
+ return args;
139
+ },
131
140
  execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
132
141
  const observation = params.observation ?? params.decision ?? "";
133
142
  const decision = params.decision ?? "";
@@ -19,7 +19,8 @@ import { IDENTITY_INTRO, DISCOVERY, WORK_ETHIC, REPAIR_DISCIPLINE, SELF_MANAGEME
19
19
  import { surfaceDisciplineSection } from "./surface-discipline-section.js";
20
20
  import { skillsLoadingText } from "../skills-tool/loading-guidance.js";
21
21
  import { reconstructProjectDocsSection, resetProjectDocsSectionCache, } from "./project-docs-section.js";
22
- import { setCachedSkills, getCachedVisibleSkillNames } from "../skills-tool/index.js";
22
+ import { setCachedSkills } from "../skills-tool/index.js";
23
+ import { getCachedVisibleSkills } from "../skills-tool/auto-inject.js";
23
24
  import { reconstructMemorySection, resetMemorySectionCache } from "./memory-section.js";
24
25
  import { gatherInstanceData, renderCompactInstance } from "./instance-composition.js";
25
26
  import { sendTrackedMessage } from "../../../lib/utils/injection-tracker.js";
@@ -431,18 +432,16 @@ export default function promptBuilderExtension(pi) {
431
432
  identitySection(),
432
433
  surfaceDisciplineSection(),
433
434
  simpleSection("identity-core", [EPISTEMIC_STANCE, SELF_AUDIT, PHILOSOPHY].join("\n\n")),
434
- // 2. Skills-loading directive (before guidelines, before tools).
435
+ // 2. Skills floor (before guidelines, before tools).
435
436
  // Owned by the skills-tool module (loading-guidance.ts) and rendered
436
- // here. Guarded by read AND list_skills availability — the directive
437
- // instructs list_skills discovery + full-file read, so both tools
438
- // must be present. The trigger's worked examples are derived here
439
- // from the active tool names and the visible skill catalog (the
440
- // cache setCachedSkills populated above is the catalog's source of
441
- // truth); the text itself never hardcodes a tool or skill name.
437
+ // here: the visible catalog itself, one row per skill, plus the
438
+ // read rule and the mechanical trigger. Guarded by read AND
439
+ // list_skills availability — the rule instructs a full-file read and
440
+ // the trigger names the catalog, so both tools must be present. The
441
+ // rows and the read root come from the live cache (setCachedSkills
442
+ // above); an empty catalog renders no section at all.
442
443
  ...(hasRead && hasListSkills
443
- ? [
444
- simpleSection("skills-loading", skillsLoadingText(toolNames, getCachedVisibleSkillNames())),
445
- ]
444
+ ? [simpleSection("skills-loading", skillsLoadingText(toolNames, getCachedVisibleSkills()))]
446
445
  : []),
447
446
  // 3. Guidelines (before tools, pi-core native pattern).
448
447
  // Order: file tools → communication → context navigation.
@@ -88,6 +88,13 @@
88
88
  * and surfaces the state through skill_stats instead of mutating the
89
89
  * transcript.
90
90
  * 9. Best-effort: failures are non-fatal, logged at debug level.
91
+ * 10. Drift trigger: the visible catalog in the prompt is a snapshot of the
92
+ * work's directory, not of the session. When the path-taking tools
93
+ * accumulate entries in a new work area, one steer line re-points at the
94
+ * catalog (at most DRIFT_MAX_FIRES a session, DRIFT_WINDOW_CALLS apart,
95
+ * and never within that window of a suggestion or a SKILL.md read). The
96
+ * rule and its bounds live in loading-guidance.ts beside the floor text
97
+ * the line points at; this module only wires them to tool results.
91
98
  *
92
99
  * Structure matches the existing steer whisper pattern used by topic-drift,
93
100
  * turn-outcome, compaction-retry, context-lifecycle, and others.
@@ -99,6 +106,7 @@
99
106
  */
100
107
  import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
101
108
  import type { TriggerSource } from "./skill-triggers.js";
109
+ import type { CatalogEntry } from "./loading-guidance.js";
102
110
  /**
103
111
  * Max skill suggestions holding a slot at any time.
104
112
  *
@@ -184,6 +192,13 @@ export interface CachedSkill {
184
192
  }
185
193
  /** Called by index.ts's setCachedSkills to keep the auto-inject cache in sync. */
186
194
  export declare function updateSkillCache(skills: CachedSkill[]): void;
195
+ /**
196
+ * The visible catalog as the prompt floor renders it (see loading-guidance.ts):
197
+ * every cached skill model selection may route to, with the description and
198
+ * path the row needs. Read from this module because the cache lives here; the
199
+ * floor's read root is derived from the paths, never hardcoded.
200
+ */
201
+ export declare function getCachedVisibleSkills(): CatalogEntry[];
187
202
  /**
188
203
  * One-rule stemmer: strip a trailing plural s/es so "skills" matches the
189
204
  * "skill" name token. Kept deliberately crude — one suffix rule, no
@@ -483,8 +498,8 @@ interface DiscoveryState {
483
498
  */
484
499
  export declare function resolveDiscoveryMode(ctx: ExtensionContext): DiscoveryState;
485
500
  /**
486
- * Register the auto-inject handler on before_agent_start plus the
487
- * read-tool load detector on tool_result.
501
+ * Register the auto-inject handler on before_agent_start, the read-tool load
502
+ * detector and the drift trigger on tool_result.
488
503
  *
489
504
  * Call this from the skills-tool extension factory, after registering
490
505
  * the list_skills tool.
@@ -88,6 +88,13 @@
88
88
  * and surfaces the state through skill_stats instead of mutating the
89
89
  * transcript.
90
90
  * 9. Best-effort: failures are non-fatal, logged at debug level.
91
+ * 10. Drift trigger: the visible catalog in the prompt is a snapshot of the
92
+ * work's directory, not of the session. When the path-taking tools
93
+ * accumulate entries in a new work area, one steer line re-points at the
94
+ * catalog (at most DRIFT_MAX_FIRES a session, DRIFT_WINDOW_CALLS apart,
95
+ * and never within that window of a suggestion or a SKILL.md read). The
96
+ * rule and its bounds live in loading-guidance.ts beside the floor text
97
+ * the line points at; this module only wires them to tool results.
91
98
  *
92
99
  * Structure matches the existing steer whisper pattern used by topic-drift,
93
100
  * turn-outcome, compaction-retry, context-lifecycle, and others.
@@ -107,6 +114,7 @@ import { getSkillsUsageFilePath } from "../../../lib/config/braid-paths.js";
107
114
  import { SESSION_COMPACT, AGENT_SETTLED } from "../../../lib/core/event-names.js";
108
115
  import { getSessionProfile, recordSessionSkillLoad, recordSessionStart, } from "./session-records.js";
109
116
  import { triggerMatches } from "./skill-triggers.js";
117
+ import { advanceDrift, driftDirectoryFor, driftPayload, initialDrift, noteDriftSurface, recordDriftDrop, recordDriftFire, skillReadRoot, } from "./loading-guidance.js";
110
118
  const log = createLogger("skills-auto-inject");
111
119
  // Constants
112
120
  /**
@@ -236,6 +244,7 @@ function getState(ctx) {
236
244
  injected: [],
237
245
  currentTurn: 0,
238
246
  hintSent: false,
247
+ drift: initialDrift(),
239
248
  }));
240
249
  }
241
250
  // Shared module-level variable rather than a per-module copy: the import
@@ -246,6 +255,17 @@ let _skillsCache = [];
246
255
  export function updateSkillCache(skills) {
247
256
  _skillsCache = skills;
248
257
  }
258
+ /**
259
+ * The visible catalog as the prompt floor renders it (see loading-guidance.ts):
260
+ * every cached skill model selection may route to, with the description and
261
+ * path the row needs. Read from this module because the cache lives here; the
262
+ * floor's read root is derived from the paths, never hardcoded.
263
+ */
264
+ export function getCachedVisibleSkills() {
265
+ return _skillsCache
266
+ .filter((s) => !s.disableModelInvocation)
267
+ .map((s) => ({ name: s.name, description: s.description, filePath: s.filePath }));
268
+ }
249
269
  // Keyword Extraction
250
270
  /**
251
271
  * One-rule stemmer: strip a trailing plural s/es so "skills" matches the
@@ -890,41 +910,93 @@ export function resolveDiscoveryMode(ctx) {
890
910
  }
891
911
  return state;
892
912
  }
893
- // Main Handler
894
913
  /**
895
- * Register the auto-inject handler on before_agent_start plus the
896
- * read-tool load detector on tool_result.
914
+ * Count a SKILL.md read (the list→read load path) and mark the matching
915
+ * injection loaded (releases its slot and extends its cooldown: the skill is
916
+ * in the agent's context now). Returns the skill name when the read was one,
917
+ * so the caller can treat it as a skill surface.
918
+ */
919
+ function detectSkillLoad(ev, ctx, state) {
920
+ if (ev?.toolName !== "read")
921
+ return undefined;
922
+ // A failed read returns the error text, not the file — counting it
923
+ // inflated `loaded` with phantom loads (the read-detector never saw
924
+ // the skill content, and no SKILL.md was opened).
925
+ if (ev.isError)
926
+ return undefined;
927
+ const text = (ev.content ?? []).map((c) => c.text ?? "").join("\n");
928
+ const name = skillNameFromRead(ev.input?.path, text);
929
+ if (!name)
930
+ return undefined;
931
+ const held = state.injected.find((i) => i.name === name && i.loadedTurn === undefined);
932
+ if (held)
933
+ held.loadedTurn = state.currentTurn;
934
+ recordSkillLoad(ctx, name);
935
+ log.debug(`[skills-auto-inject] counted actual load of "${name}" via read`);
936
+ return name;
937
+ }
938
+ /**
939
+ * Fire the drift line when the work has moved into a new work area (the rule
940
+ * and its bounds live in loading-guidance.ts, beside the floor text the line
941
+ * points at). The floor is the catalog against the prompt that was in view;
942
+ * a session now reading and writing elsewhere has its catalog in the prompt
943
+ * and its task text elsewhere, and one line re-points at it.
944
+ *
945
+ * Guarded like the floor section itself: without read and list_skills there is
946
+ * no catalog in the prompt to point at, so nothing fires.
947
+ */
948
+ function stepDrift(pi, ctx, state, ev) {
949
+ const target = advanceDrift(state.drift, driftDirectoryFor(ev?.toolName, ev?.input?.path, ctx.cwd ?? ""));
950
+ if (!target)
951
+ return;
952
+ const toolNames = new Set(pi.getAllTools().map((t) => t.name));
953
+ if (!toolNames.has("read") || !toolNames.has("list_skills")) {
954
+ recordDriftDrop(state.drift);
955
+ return;
956
+ }
957
+ const delivered = sendTrackedMessage(pi, {
958
+ customType: "skills-drift",
959
+ content: [{ type: "text", text: driftPayload(target, skillReadRoot(_skillsCache)) }],
960
+ display: true,
961
+ details: {
962
+ [BRAID_INJECTED]: true,
963
+ [BRAID_SOURCE]: "skills-auto-inject",
964
+ directory: target,
965
+ },
966
+ }, { delivery: "park", deliverAs: "steer" }, { type: "context", source: "skills-auto-inject" },
967
+ // The module's own budget is the bound (DRIFT_MAX_FIRES a session,
968
+ // DRIFT_WINDOW_CALLS between fires), so a suppression cap must not drop
969
+ // the line in a busy turn: that is exactly when the work is moving and
970
+ // the floor's snapshot goes stale.
971
+ { bypassFloodCap: true });
972
+ if (!delivered) {
973
+ recordDriftDrop(state.drift);
974
+ return;
975
+ }
976
+ recordDriftFire(state.drift, target);
977
+ log.info(`[skills-auto-inject] drift line for ${target} (fire ${state.drift.fires}, call ${state.drift.calls})`);
978
+ }
979
+ /**
980
+ * Register the auto-inject handler on before_agent_start, the read-tool load
981
+ * detector and the drift trigger on tool_result.
897
982
  *
898
983
  * Call this from the skills-tool extension factory, after registering
899
984
  * the list_skills tool.
900
985
  */
901
986
  export function registerAutoInject(pi) {
902
- // Count SKILL.md reads (the list→read load path) via the read tool, and
903
- // per-skill: mark the matching injection as loaded (releases its slot and
904
- // extends its cooldown — the skill is in the agent's context now).
987
+ // Two jobs per tool result. The load detector runs first: a SKILL.md read
988
+ // that just landed is a skill surface, and the drift guard must see it
989
+ // before it decides whether to speak.
905
990
  pi.on("tool_result", (event, ctx) => {
906
991
  try {
907
992
  const ev = event;
908
- if (ev?.toolName !== "read")
909
- return;
910
- // A failed read returns the error text, not the file — counting it
911
- // inflated `loaded` with phantom loads (the read-detector never saw
912
- // the skill content, and no SKILL.md was opened).
913
- if (ev.isError)
914
- return;
915
- const text = (ev.content ?? []).map((c) => c.text ?? "").join("\n");
916
- const name = skillNameFromRead(ev.input?.path, text);
917
- if (name) {
918
- const state = getState(ctx);
919
- const held = state.injected.find((i) => i.name === name && i.loadedTurn === undefined);
920
- if (held)
921
- held.loadedTurn = state.currentTurn;
922
- recordSkillLoad(ctx, name);
923
- log.debug(`[skills-auto-inject] counted actual load of "${name}" via read`);
924
- }
993
+ const state = getState(ctx);
994
+ if (detectSkillLoad(ev, ctx, state))
995
+ noteDriftSurface(state.drift);
996
+ stepDrift(pi, ctx, state, ev);
925
997
  }
926
998
  catch {
927
- // best-effort — never break the tool loop over a counter
999
+ // best-effort — never break the tool loop over a counter or a whisper
928
1000
  }
929
1001
  });
930
1002
  // Post-compaction the transcript can regain pi's stock skill catalog (the
@@ -1036,6 +1108,10 @@ export function registerAutoInject(pi) {
1036
1108
  }
1037
1109
  log.info(`[skills-auto-inject] Suggesting ${skillsToInject.map((s) => s.name).join(", ")} ` +
1038
1110
  `(turn ${state.currentTurn}, keywords: ${keywords.slice(0, 5).join(", ")})`);
1111
+ // A delivered suggestion is a skill surface: the drift trigger stays
1112
+ // quiet for its window, because the pointer the trigger exists to
1113
+ // supply has just landed.
1114
+ noteDriftSurface(state.drift);
1039
1115
  for (const item of toInject) {
1040
1116
  state.injected.push({
1041
1117
  name: item.skill.name,
@@ -38,6 +38,7 @@ import { registerAutoInject, updateSkillCache, getSkillStats, getDurableSkillSta
38
38
  import { readSkillTriggerEntries } from "./skill-triggers.js";
39
39
  import { clampSectionsMax, DEFAULT_SECTIONS_MAX, SECTIONS_MAX_LIMIT, readSkillReach, } from "./reach.js";
40
40
  import { getMonthlyAdoptionRollup } from "./session-records.js";
41
+ import { checkArgumentValues } from "../../../lib/utils/argument-report.js";
41
42
  const log = createLogger("skills-tool");
42
43
  let cachedSkills = [];
43
44
  /**
@@ -166,38 +167,58 @@ function rowOf(row) {
166
167
  return { score: row.score, reason: row.reason ?? "description" };
167
168
  }
168
169
  // Extension factory:
170
+ /**
171
+ * `list_skills` arguments: one action, one page of the catalog.
172
+ *
173
+ * The action is named here rather than inferred, because a pager call and a
174
+ * full-catalog call are the same call and the schema is what the model reads
175
+ * before choosing. The tool fills it when the call omits it (`prepareArguments`
176
+ * below), so a bare pager call behaves as the listing it obviously is while an
177
+ * unknown action is still refused.
178
+ */
179
+ const listSkillsSchema = Type.Object({
180
+ action: Type.Literal("list", {
181
+ description: "list = paginated catalog with per-skill reach (reachable, lines, bytes, chars, estTokens, sectionCount, sections)",
182
+ }),
183
+ page: Type.Optional(Type.Number({
184
+ minimum: 1,
185
+ default: 1,
186
+ description: "Page number for list (1-based)",
187
+ })),
188
+ pageSize: Type.Optional(Type.Number({
189
+ minimum: 1,
190
+ maximum: 50,
191
+ default: 10,
192
+ description: "Entries per page for list",
193
+ })),
194
+ sectionsMax: Type.Optional(Type.Number({
195
+ minimum: 0,
196
+ maximum: SECTIONS_MAX_LIMIT,
197
+ default: DEFAULT_SECTIONS_MAX,
198
+ description: "Headings reported per skill; 0 omits the section list and keeps sectionCount",
199
+ })),
200
+ rank: Type.Optional(Type.Union([Type.Literal("relevance"), Type.Literal("catalog")], {
201
+ default: "relevance",
202
+ description: "relevance (default) = order by fit to the current task; catalog = the plain catalog order, with no ranking fields",
203
+ })),
204
+ });
169
205
  export default function skillsToolExtension(pi) {
170
206
  registerAutoInject(pi);
171
207
  pi.registerTool({
172
208
  name: "list_skills",
173
209
  label: "List Skills",
174
210
  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.",
175
- parameters: Type.Object({
176
- action: Type.Literal("list", {
177
- description: "list = paginated catalog with per-skill reach (reachable, lines, bytes, chars, estTokens, sectionCount, sections)",
178
- }),
179
- page: Type.Optional(Type.Number({
180
- minimum: 1,
181
- default: 1,
182
- description: "Page number for list (1-based)",
183
- })),
184
- pageSize: Type.Optional(Type.Number({
185
- minimum: 1,
186
- maximum: 50,
187
- default: 10,
188
- description: "Entries per page for list",
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
- })),
200
- }),
211
+ parameters: listSkillsSchema,
212
+ // Paging without an action is a listing call: fill the action the call
213
+ // implies before pi validates, and refuse a guessed value with the accepted
214
+ // one named. The schema above stays the only description of the contract.
215
+ prepareArguments: (args) => {
216
+ const prepared = args && typeof args === "object" && args.action == null
217
+ ? { ...args, action: "list" }
218
+ : args;
219
+ checkArgumentValues("list_skills", listSkillsSchema, prepared);
220
+ return prepared;
221
+ },
201
222
  execute: async (_id, params, signal, _onUpdate, ctx) => {
202
223
  const page = params.page ?? 1;
203
224
  const pageSize = params.pageSize ?? 10;
@@ -1,36 +1,90 @@
1
1
  /**
2
- * Skills-loading directive, owned by the skills-tool module.
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
- * The skills-tool module owns the strategy text for using its own tool;
5
- * prompt-builder imports it and renders it as the "skills-loading" section
6
- * ONLY when both `read` and `list_skills` are active tools.
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
- * Current rule: task-start list_skills puts the full catalog (name, path,
9
- * purpose) in view so the domain-match trigger is decidable; the catalog
10
- * one-liner is metadata, the SKILL.md path is the knowledge — no skill
11
- * content is injected into the prompt. The trigger has a mechanical form
12
- * (a tool call whose family word appears in a skill's name) because the
13
- * judgment form loses sessions that are inside a skill's domain by
14
- * construction. Decision logic lives in the prompt, mechanics in tool
15
- * descriptions (strategy-only contract; each fact in exactly one place).
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 (mechanicalTriggerExamples): a tool's family
19
- * token paired with an installed visible skill's dash-token. The text never
20
- * hardcodes a tool or skill name, so it cannot name a pair that does not
21
- * exist in the running session; when no pair computes, the sentence renders
22
- * without a parenthetical.
23
- */
24
- /** Paragraph 1: the discovery rule (pinned verbatim by test-prompt-budget.mjs). */
25
- export declare const SKILLS_DISCOVERY_RULE = "You discover skills on demand, not in advance: at the start of a task, call list_skills once to see the catalog (name, path, purpose). 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.";
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
+ /** One visible skill as the floor renders it. */
39
+ export interface CatalogEntry {
40
+ name: string;
41
+ description: string;
42
+ filePath: string;
43
+ }
44
+ /**
45
+ * Paragraph 1: what the catalog is, where the bodies live, and the obligation.
46
+ *
47
+ * `readRoot` is the single pack directory the rule can state; `grouped` says
48
+ * the rows are rendered under directory headings instead, so the rule points
49
+ * at the heading rather than at a root that does not exist. Neither given (a
50
+ * catalog whose bodies carry no pack) leaves the location unstated, which is
51
+ * the honest answer when the paths cannot be derived.
52
+ */
53
+ export declare function skillsCatalogRule(readRoot: string, grouped?: boolean): string;
26
54
  /** Paragraph 2: the pointer rule (pinned verbatim by test-prompt-budget.mjs). */
27
- export declare const SKILLS_POINTER_RULE = "Pointer rule: the catalog one-liner is metadata, not content \u2014 the SKILL.md path is the knowledge. Mid-task, enter a domain absent from the visible catalog \u2192 call list_skills again (catalog is paginated). The prompt already covering the domain is the only reason to skip the read.";
55
+ export declare const SKILLS_POINTER_RULE = "Pointer rule: the catalog one-liner is metadata, not content \u2014 the SKILL.md path is the knowledge. The prompt already covering the domain is the only reason to skip the read.";
56
+ /** One directory a catalog's bodies live in, with the skills filed under it. */
57
+ export interface CatalogGroup {
58
+ /** The pack directory itself, in forward-slash form. */
59
+ dir: string;
60
+ skills: CatalogEntry[];
61
+ }
62
+ /**
63
+ * File the entries by the pack their own SKILL.md lives in: the braid pack
64
+ * plus the user-global directory is two groups in one catalog. Groups and
65
+ * rows are sorted, so identical catalogs render byte-identical text in any
66
+ * cache order. Pure.
67
+ */
68
+ export declare function catalogGroups(skills: CatalogEntry[]): CatalogGroup[];
69
+ /**
70
+ * The one directory every entry lives under, or "" when they do not share
71
+ * one: a single root is a fact a caller may state, and a common ancestor of
72
+ * two packs is not. Pure.
73
+ */
74
+ export declare function skillReadRoot(skills: CatalogEntry[]): string;
75
+ /**
76
+ * One row per skill: `- name: description`, whitespace collapsed to a single
77
+ * line. Descriptions are NOT clipped: the row is the whole reason the floor
78
+ * works, and a clipped description is what a model would have to guess from.
79
+ * Pure.
80
+ */
81
+ export declare function catalogRows(skills: CatalogEntry[]): string[];
28
82
  /**
29
83
  * Worked examples for the mechanical trigger, derived from the live inputs.
30
84
  *
31
85
  * A pair exists when a tool's family token (the first underscore-delimited
32
- * token of the tool name: `herdr_layout` → `herdr`) equals a dash-delimited
33
- * token of a skill name (`herdr-topology` → `herdr`), case-insensitively.
86
+ * token of the tool name: `widget_open` → `widget`) equals a dash-delimited
87
+ * token of a skill name (`widget-map` → `widget`), case-insensitively.
34
88
  * One example renders per distinct family token: the trigger fires per
35
89
  * family ("before the first call in the family"), so enumerating every tool
36
90
  * in a family would restate one fact; the representative tool is the
@@ -41,10 +95,77 @@ export declare const SKILLS_POINTER_RULE = "Pointer rule: the catalog one-liner
41
95
  */
42
96
  export declare function mechanicalTriggerExamples(toolNames: string[], skillNames: string[]): string[];
43
97
  /**
44
- * The full skills-loading text: discovery rule, pointer rule, and the
45
- * mechanical trigger with only the pairs computed from the given tool and
46
- * skill names. prompt-builder feeds it the active tool names and the
47
- * skills-tool module's visible-catalog names.
98
+ * The full skills-loading section: catalog rule (with the derived read path),
99
+ * pointer rule, one row per visible skill, and the mechanical trigger with
100
+ * only the pairs computed from the given tool and skill names.
101
+ *
102
+ * prompt-builder feeds it the active tool names and the skills-tool module's
103
+ * visible catalog. An empty catalog renders no section: the floor is a
104
+ * catalog, and a section claiming to list every skill while listing none
105
+ * would be a lie the model has no way to check.
106
+ *
107
+ * One pack renders its root in the rule; several packs render a directory
108
+ * heading before each group of rows, because no single root describes them.
109
+ */
110
+ export declare function skillsLoadingText(toolNames: string[], skills: CatalogEntry[]): string;
111
+ /** The path-taking tools whose calls describe where the work is. */
112
+ export declare const DRIFT_PATH_TOOLS: readonly ["read", "edit", "write"];
113
+ /** Tool calls that must pass between fires, and after any skill surface. */
114
+ export declare const DRIFT_WINDOW_CALLS = 12;
115
+ /** Fires per session. */
116
+ export declare const DRIFT_MAX_FIRES = 3;
117
+ /** Entries in one directory before it counts as where the work is. */
118
+ export declare const DRIFT_ENTRIES = 2;
119
+ /** Directory segments a path must carry before it can name a work area. */
120
+ export declare const DRIFT_MIN_SEGMENTS = 2;
121
+ /** Drift state, session-scoped plain data (see auto-inject.ts for the holder). */
122
+ export interface DriftTracker {
123
+ /** Tool results seen this session: the clock both window guards read. */
124
+ calls: number;
125
+ /** Call index of the last fire; null before the first. */
126
+ lastFire: number | null;
127
+ /** Fires this session. */
128
+ fires: number;
129
+ /** Call index of the last skill surface; null before the first. */
130
+ lastSurface: number | null;
131
+ /** Directory -> entries seen since the last fire. */
132
+ entries: Record<string, number>;
133
+ /** Directories already announced (each is announced once). */
134
+ announced: string[];
135
+ }
136
+ /** Fresh drift state for a session. */
137
+ export declare function initialDrift(): DriftTracker;
138
+ /**
139
+ * The work area a finished tool call touched: the first two directory
140
+ * segments of its path, relative to the session's project root. Undefined for
141
+ * a tool that takes no path, a path outside the project, and a path with
142
+ * fewer than DRIFT_MIN_SEGMENTS directories. Pure.
143
+ */
144
+ export declare function driftDirectoryFor(toolName: string | undefined, inputPath: string | undefined, cwd: string): string | undefined;
145
+ /**
146
+ * Count one finished tool call and answer whether it is a fire.
147
+ *
148
+ * Returns the work area to announce, or null. The caller fires the line and
149
+ * then calls recordDriftFire (on delivery) or recordDriftDrop (when the
150
+ * whisper was suppressed), so a dropped line never spends the budget. The
151
+ * tracker is the session's own mutable state; the answer is a pure function
152
+ * of its contents.
153
+ */
154
+ export declare function advanceDrift(tracker: DriftTracker, directory: string | undefined): string | null;
155
+ /** Mark a fire at the current call: spends one fire, announces, restarts counts. */
156
+ export declare function recordDriftFire(tracker: DriftTracker, directory: string): void;
157
+ /**
158
+ * Mark a fire attempt whose whisper was suppressed: no fire is spent and the
159
+ * directory is not announced, but the counts restart and the window opens, so
160
+ * a suppressed line is retried only after the session has done more work.
161
+ */
162
+ export declare function recordDriftDrop(tracker: DriftTracker): void;
163
+ /** Note that a skill surface (a suggestion or a SKILL.md read) just landed. */
164
+ export declare function noteDriftSurface(tracker: DriftTracker): void;
165
+ /**
166
+ * The one-line steer: the work area and a pointer back at the catalog in the
167
+ * prompt. `readRoot` empty (several packs, see skillReadRoot) drops the path
168
+ * clause instead of naming a path that may not resolve.
48
169
  */
49
- export declare function skillsLoadingText(toolNames: string[], skillNames: string[]): string;
170
+ export declare function driftPayload(directory: string, readRoot: string): string;
50
171
  //# sourceMappingURL=loading-guidance.d.ts.map