pi-braid 0.43.7 → 0.43.8

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 (56) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/TOOLS.md +1 -1
  3. package/build-info.json +4 -4
  4. package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
  5. package/dist/extensions/core/skills-tool/auto-inject.d.ts +21 -0
  6. package/dist/extensions/core/skills-tool/auto-inject.js +105 -1
  7. package/dist/extensions/core/skills-tool/index.js +20 -2
  8. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
  9. package/dist/extensions/core/skills-tool/loading-guidance.js +4 -1
  10. package/dist/extensions/core/skills-tool/session-records.d.ts +107 -9
  11. package/dist/extensions/core/skills-tool/session-records.js +141 -5
  12. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
  13. package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
  14. package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
  15. package/dist/extensions/enforcement/verification-judge.js +28 -21
  16. package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
  17. package/dist/extensions/memory/session-recall/ask.js +376 -0
  18. package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
  19. package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
  20. package/dist/extensions/memory/session-recall/index.js +173 -21
  21. package/dist/extensions/memory/session-recall/search.d.ts +29 -0
  22. package/dist/extensions/memory/session-recall/search.js +42 -9
  23. package/dist/lib/ai/payload-hygiene.d.ts +3 -0
  24. package/dist/lib/ai/payload-hygiene.js +34 -2
  25. package/dist/lib/config/braid-paths.d.ts +4 -0
  26. package/dist/lib/config/braid-paths.js +6 -0
  27. package/dist/lib/config/braid-settings.d.ts +22 -0
  28. package/dist/lib/config/braid-settings.js +15 -0
  29. package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
  30. package/dist/lib/detection/tool-loop-detector.js +288 -180
  31. package/dist/lib/reasoning/dreamer.d.ts +2 -1
  32. package/dist/lib/reasoning/dreamer.js +12 -7
  33. package/docs/LOCAL_DEV.md +1 -1
  34. package/docs/SETUP.md +1 -0
  35. package/package.json +1 -1
  36. package/src/extensions/core/AGENTS.md +3 -2
  37. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  38. package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
  39. package/src/extensions/core/skills-tool/index.ts +21 -1
  40. package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
  41. package/src/extensions/core/skills-tool/session-records.ts +201 -9
  42. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
  43. package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
  44. package/src/extensions/enforcement/verification-judge.ts +32 -25
  45. package/src/extensions/memory/AGENTS.md +2 -2
  46. package/src/extensions/memory/session-recall/AGENTS.md +92 -18
  47. package/src/extensions/memory/session-recall/ask.ts +435 -0
  48. package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
  49. package/src/extensions/memory/session-recall/index.ts +202 -21
  50. package/src/extensions/memory/session-recall/search.ts +61 -10
  51. package/src/lib/ai/payload-hygiene.ts +47 -3
  52. package/src/lib/config/braid-paths.ts +7 -0
  53. package/src/lib/config/braid-settings.ts +42 -3
  54. package/src/lib/detection/AGENTS.md +8 -7
  55. package/src/lib/detection/tool-loop-detector.ts +339 -195
  56. package/src/lib/reasoning/dreamer.ts +13 -6
@@ -45,7 +45,8 @@ import {
45
45
  dateFromPath,
46
46
  searchFiles,
47
47
  searchFilesWithInfo,
48
- searchLines,
48
+ searchLineHits,
49
+ excludeSessionPath,
49
50
  walkJsonlFiles,
50
51
  tokenizeQuery,
51
52
  labelFromCwd,
@@ -54,6 +55,8 @@ import {
54
55
  MAX_SNIPPETS_PER_SESSION,
55
56
  } from "./search.js";
56
57
  import { rankSearchResults } from "./rank.js";
58
+ import { corpusIndexFreshness, loadCorpusIndex } from "./corpus-index.js";
59
+ import { askCorpusIndex, formatAskResult, MAX_ASK_HITS } from "./ask.js";
57
60
  import { loadSessionMessages, serializeSession, QUERY_SYSTEM_PROMPT } from "./query.js";
58
61
  import { collectSessionStats } from "./stats.js";
59
62
  import { summarizeSession, buildAnalysisInput, ANALYZE_SYSTEM_PROMPT } from "./analyze.js";
@@ -75,6 +78,7 @@ const sessionSchema = Type.Object({
75
78
  action: Type.Union(
76
79
  [
77
80
  Type.Literal("search"),
81
+ Type.Literal("ask"),
78
82
  Type.Literal("query"),
79
83
  Type.Literal("batch"),
80
84
  Type.Literal("stats"),
@@ -82,14 +86,15 @@ const sessionSchema = Type.Object({
82
86
  Type.Literal("context"),
83
87
  ],
84
88
  {
85
- description: "Action: search | query | batch | stats | analyze | context",
89
+ description: "Action: search | ask | query | batch | stats | analyze | context",
86
90
  },
87
91
  ),
88
- // search-only
92
+ // search/ask
89
93
  query: Type.Optional(
90
94
  Type.String({
91
95
  description:
92
- "Search terms, space-separated; a file matching any term is returned and files carrying the whole phrase rank first. action=search.",
96
+ "Search terms, space-separated; a file matching any term is returned and files carrying the whole phrase rank first. action=search. " +
97
+ "For action=ask, the question in words: it is scored against the corpus index of user turns and the top turns are cited.",
93
98
  }),
94
99
  ),
95
100
  // query-only
@@ -140,6 +145,81 @@ function positiveLimit(value: unknown): number | undefined {
140
145
  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
141
146
  }
142
147
 
148
+ // Helpers the search, ask and batch actions share
149
+
150
+ /** Passages one `batch` result renders across all its sessions. */
151
+ const MAX_BATCH_LINES = 20;
152
+
153
+ /**
154
+ * The session file this call runs in.
155
+ *
156
+ * A session must never match its own transcript: the current turn's own words
157
+ * are the query, so it would outrank the earlier evidence it is looking for.
158
+ * pi exposes the file on the session manager; the environment carries it for a
159
+ * context without one.
160
+ */
161
+ function callingSessionFile(ctx: unknown): string | null {
162
+ const manager = (
163
+ ctx as
164
+ | {
165
+ sessionManager?: {
166
+ getSessionFile?: () => string | null | undefined;
167
+ sessionFile?: string;
168
+ };
169
+ }
170
+ | undefined
171
+ )?.sessionManager;
172
+ const fromManager = manager?.getSessionFile?.() ?? manager?.sessionFile;
173
+ if (typeof fromManager === "string" && fromManager) return fromManager;
174
+ const fromEnv = process.env.PI_SESSION_FILE;
175
+ return typeof fromEnv === "string" && fromEnv ? fromEnv : null;
176
+ }
177
+
178
+ /**
179
+ * One matched JSONL line as a readable passage, or null when the line carries
180
+ * no message text. A compaction envelope holds many messages in one physical
181
+ * line, so the messages carrying the pattern are preferred over the first.
182
+ */
183
+ function linePassage(rawLine: string, query: string): string | null {
184
+ const parsed = extractLineMessages(rawLine);
185
+ const terms = tokenizeQuery(query);
186
+ const shown =
187
+ parsed.isArchive && terms.length > 0
188
+ ? messagesMatchingTerms(parsed.messages, terms)
189
+ : parsed.messages;
190
+ const first = shown[0] ?? parsed.messages[0];
191
+ if (!first) return null;
192
+ const text = snippetAround(first.text, query, 110).replace(/\s+/g, " ").trim();
193
+ return ` [${first.role}] ${text}`;
194
+ }
195
+
196
+ /**
197
+ * Ranked passages across matched sessions: term coverage first, then recency,
198
+ * capped at MAX_BATCH_LINES. One read per session, and only for the sessions
199
+ * the caller's limit already selected.
200
+ */
201
+ async function batchPassages(
202
+ sessions: Array<{ path: string }>,
203
+ pattern: string,
204
+ ): Promise<string[]> {
205
+ const scored: Array<{ weight: number; when: string; text: string }> = [];
206
+ for (const session of sessions) {
207
+ if (scored.length >= MAX_BATCH_LINES) break;
208
+ const hits = await searchLineHits(pattern, session.path, MAX_SNIPPETS_PER_SESSION);
209
+ for (const hit of hits) {
210
+ const passage = linePassage(hit.text, pattern);
211
+ if (!passage) continue;
212
+ scored.push({
213
+ weight: hit.hits,
214
+ when: dateFromPath(session.path),
215
+ text: `${passage} \`${basename(session.path)}:${hit.line}\``,
216
+ });
217
+ }
218
+ }
219
+ scored.sort((a, b) => b.weight - a.weight || b.when.localeCompare(a.when));
220
+ return scored.slice(0, MAX_BATCH_LINES).map((entry) => entry.text);
221
+ }
222
+
143
223
  // Extension
144
224
 
145
225
  export default function sessionRecallExtension(pi: ExtensionAPI) {
@@ -151,10 +231,11 @@ export default function sessionRecallExtension(pi: ExtensionAPI) {
151
231
  pi.registerTool({
152
232
  name: "session",
153
233
  label: "Session",
154
- promptSnippet: "Access past session history — search, query, analyze, stats, or context",
234
+ promptSnippet: "Access past session history — search, ask, query, analyze, stats, or context",
155
235
  description:
156
- "Access past session history: search, query a specific session, analyze multiple, batch across sessions, stats, or context (cross-session §8 adoption aggregate). " +
157
- "LLM-driven except search, batch, stats, and context.",
236
+ "Access past session history: search, ask, query a specific session, analyze multiple, batch across sessions, stats, or context (cross-session §8 adoption aggregate). " +
237
+ "ask answers a question from the indexed user turns and cites every hit (project, session path, line, timestamp); it refuses when the index cannot answer. " +
238
+ "LLM-driven except search, ask, batch, stats, and context.",
158
239
  parameters: sessionSchema,
159
240
  execute: async (
160
241
  _toolCallId,
@@ -182,12 +263,16 @@ export default function sessionRecallExtension(pi: ExtensionAPI) {
182
263
  };
183
264
  }
184
265
  const currentProject = _ctx?.cwd ? labelFromCwd(_ctx.cwd) : undefined;
266
+ const ownSession = callingSessionFile(_ctx);
185
267
  // The four-signal ranker also picks the bounded candidate set the
186
- // role signal is refined on; see search.ts ROLE_REFINE_LIMIT.
268
+ // role signal is refined on; see search.ts ROLE_REFINE_LIMIT. The
269
+ // caller's own session is dropped before either read, so a session
270
+ // can never match itself (search.ts excludeSessionPath).
187
271
  const info = await searchFilesWithInfo(params.query, sessionsDir, {
188
- rankCandidates: (matches) => rankSearchResults(matches, { currentProject }),
272
+ rankCandidates: (matches) =>
273
+ rankSearchResults(excludeSessionPath(matches, ownSession), { currentProject }),
189
274
  });
190
- const allMatches = info.matches;
275
+ const allMatches = excludeSessionPath(info.matches, ownSession);
191
276
  if (allMatches.length === 0) {
192
277
  return {
193
278
  content: [
@@ -212,18 +297,18 @@ export default function sessionRecallExtension(pi: ExtensionAPI) {
212
297
  );
213
298
  const results: string[] = [];
214
299
  const queryTerms = tokenizeQuery(params.query);
215
- for (const { path: filePath, count } of fileMatches) {
300
+ for (const { path: filePath } of fileMatches) {
216
301
  const project = projectFromPath(filePath);
217
302
  const date = dateFromPath(filePath);
218
- const matchLines = await searchLines(
303
+ const matchLines = await searchLineHits(
219
304
  params.query,
220
305
  filePath,
221
306
  MAX_SNIPPETS_PER_SESSION,
222
307
  );
223
308
  const snippets: string[] = [];
224
309
  let archiveNote = "";
225
- for (const line of matchLines) {
226
- const parsed = extractLineMessages(line);
310
+ for (const hit of matchLines) {
311
+ const parsed = extractLineMessages(hit.text);
227
312
  // A live line carries one message. A compaction envelope carries
228
313
  // the whole archived batch inside its `originals` string, and the
229
314
  // one physical line matches if the query is anywhere in that
@@ -236,7 +321,9 @@ export default function sessionRecallExtension(pi: ExtensionAPI) {
236
321
  : parsed.messages;
237
322
  for (const msg of shown) {
238
323
  if (snippets.length >= MAX_SNIPPETS_PER_SESSION) break;
239
- snippets.push(` [${msg.role}] ${snippetAround(msg.text, params.query)}`);
324
+ snippets.push(
325
+ ` [${msg.role}] L${hit.line}: ${snippetAround(msg.text, params.query)}`,
326
+ );
240
327
  }
241
328
  if (parsed.isArchive) {
242
329
  const parts = [
@@ -263,7 +350,7 @@ export default function sessionRecallExtension(pi: ExtensionAPI) {
263
350
  // matches.
264
351
  if (snippets.length === 0 && !archiveNote) continue;
265
352
  results.push(
266
- `**${date}** - \`${project}\` - ${count} match${count > 1 ? "es" : ""}\n` +
353
+ `**${date}** - \`${project}\`\n` +
267
354
  `Session: \`${filePath}\`\n` +
268
355
  [...snippets, archiveNote].filter(Boolean).join("\n"),
269
356
  );
@@ -280,7 +367,7 @@ export default function sessionRecallExtension(pi: ExtensionAPI) {
280
367
  };
281
368
  }
282
369
  const output =
283
- `Found ${results.length} session${results.length > 1 ? "s" : ""} matching "${params.query}":\n\n` +
370
+ `**Search:** "${params.query}" - matched lines from ${results.length} session${results.length > 1 ? "s" : ""}, ranked:\n\n` +
284
371
  results.join("\n\n---\n\n");
285
372
  return {
286
373
  content: [{ type: "text" as const, text: output }],
@@ -290,6 +377,75 @@ export default function sessionRecallExtension(pi: ExtensionAPI) {
290
377
  backend: info.backend,
291
378
  elapsedMs: info.elapsedMs,
292
379
  roleRefined: info.roleRefined,
380
+ selfSessionExcluded: Boolean(ownSession),
381
+ },
382
+ };
383
+ }
384
+ case "ask": {
385
+ if (!params.query) {
386
+ return {
387
+ content: [{ type: "text" as const, text: "action=ask requires 'query' parameter" }],
388
+ details: { error: true, action: "ask" },
389
+ };
390
+ }
391
+ const projectFilter =
392
+ params.project === "all"
393
+ ? null
394
+ : (params.project ?? (_ctx?.cwd ? labelFromCwd(_ctx.cwd) : null));
395
+ const loaded = await loadCorpusIndex(projectFilter ? { project: projectFilter } : {});
396
+ if (!loaded.ok) {
397
+ const hint = projectFilter ? ` Pass project=all to query every project's shard.` : "";
398
+ return {
399
+ content: [
400
+ {
401
+ type: "text" as const,
402
+ text:
403
+ `The corpus index cannot answer: ${loaded.reason}.${hint} ` +
404
+ `Index directory: \`${loaded.dir}\`. Build it with ` +
405
+ `\`node packages/core/scripts/build-corpus-index.mjs\` (one pass over the ` +
406
+ `session files), then ask again.`,
407
+ },
408
+ ],
409
+ details: {
410
+ error: true,
411
+ action: "ask",
412
+ indexDir: loaded.dir,
413
+ reason: loaded.reason,
414
+ shards: loaded.shards,
415
+ },
416
+ };
417
+ }
418
+ // The answer states its own freshness: a shard is derived data, so
419
+ // the drift is measured and printed rather than assumed away.
420
+ const freshness = await corpusIndexFreshness(loaded.shards, getSessionsDir(_ctx));
421
+ const result = askCorpusIndex(loaded.shards, params.query, {
422
+ project: projectFilter,
423
+ since: params.since ?? null,
424
+ limit: positiveLimit(params.limit) ?? MAX_ASK_HITS,
425
+ excludeSession: callingSessionFile(_ctx),
426
+ freshness,
427
+ });
428
+ return {
429
+ content: [{ type: "text" as const, text: formatAskResult(result) }],
430
+ details: {
431
+ action: "ask",
432
+ answered: result.answered,
433
+ query: params.query,
434
+ terms: result.terms,
435
+ matchedTerms: result.matched_terms,
436
+ unmatchedTerms: result.unmatched_terms,
437
+ hits: result.hits.map((hit) => ({
438
+ project: hit.turn.project,
439
+ session: hit.turn.session,
440
+ sessionId: hit.turn.session_id,
441
+ line: hit.turn.line,
442
+ ts: hit.turn.ts,
443
+ score: Number(hit.score.toFixed(3)),
444
+ })),
445
+ population: result.population,
446
+ freshness,
447
+ indexDir: loaded.dir,
448
+ selfSessionExcluded: result.self_excluded,
293
449
  },
294
450
  };
295
451
  }
@@ -422,7 +578,11 @@ export default function sessionRecallExtension(pi: ExtensionAPI) {
422
578
  details: { error: true, matchCount: 0 },
423
579
  };
424
580
  }
425
- const allMatches = await searchFiles(params.pattern, sessionsDir);
581
+ const ownSession = callingSessionFile(_ctx);
582
+ const allMatches = excludeSessionPath(
583
+ await searchFiles(params.pattern, sessionsDir),
584
+ ownSession,
585
+ );
426
586
  if (allMatches.length === 0) {
427
587
  return {
428
588
  content: [
@@ -494,12 +654,31 @@ export default function sessionRecallExtension(pi: ExtensionAPI) {
494
654
  const limit = positiveLimit(params.limit) ?? 10;
495
655
  const topSessions = filtered.slice(0, limit);
496
656
 
657
+ // The result leads with passages, not a count: aggregate numbers
658
+ // say how much matched, never what matched. Reads are bounded by
659
+ // the session limit above and MAX_BATCH_LINES below.
660
+ const passages = await batchPassages(topSessions, params.pattern);
661
+
497
662
  const lines: string[] = [
498
663
  `## Batch: "${params.pattern}"`,
499
664
  ``, //
500
- `**Total matches:** ${totalMatches} in ${filtered.length} session${filtered.length === 1 ? "" : "s"}`,
501
- ``, //
502
665
  ];
666
+ if (passages.length > 0) {
667
+ lines.push(
668
+ `**Matched lines** (${passages.length} of ${totalMatches} matches, ranked):`,
669
+ );
670
+ lines.push(...passages);
671
+ } else {
672
+ lines.push(
673
+ `**Matched lines:** none rendered - the matching sessions carry the pattern only in ` +
674
+ `text this reader does not extract (tool results, metadata).`,
675
+ );
676
+ }
677
+ lines.push("");
678
+ lines.push(
679
+ `**Aggregates:** ${totalMatches} match${totalMatches === 1 ? "" : "es"} in ${filtered.length} session${filtered.length === 1 ? "" : "s"}`,
680
+ );
681
+ lines.push("");
503
682
 
504
683
  // By project
505
684
  const projectEntries = Object.entries(byProject).sort((a, b) => b[1] - a[1]);
@@ -533,6 +712,8 @@ export default function sessionRecallExtension(pi: ExtensionAPI) {
533
712
  pattern: params.pattern,
534
713
  totalMatches,
535
714
  sessionCount: filtered.length,
715
+ renderedPassages: passages.length,
716
+ selfSessionExcluded: Boolean(ownSession),
536
717
  byProject: projectEntries,
537
718
  byMonth: monthEntries,
538
719
  topSessions: topSessions.map((m) => ({
@@ -892,7 +1073,7 @@ export default function sessionRecallExtension(pi: ExtensionAPI) {
892
1073
  }
893
1074
  default:
894
1075
  throw new Error(
895
- `Unknown session action: ${params?.action}. Use: search, query, batch, stats, analyze, context.`,
1076
+ `Unknown session action: ${params?.action}. Use: search, ask, query, batch, stats, analyze, context.`,
896
1077
  );
897
1078
  }
898
1079
  } catch (err) {
@@ -6,7 +6,7 @@
6
6
  */
7
7
 
8
8
  import { execFileSync } from "node:child_process";
9
- import { closeSync, openSync, readSync, readdirSync, statSync } from "node:fs";
9
+ import { closeSync, openSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
10
10
  import { readdir, readFile } from "node:fs/promises";
11
11
  import { basename, dirname, join } from "node:path";
12
12
  import { homedir } from "node:os";
@@ -767,28 +767,79 @@ export async function searchLines(
767
767
  filePath: string,
768
768
  limit: number,
769
769
  ): Promise<string[]> {
770
- const results: Array<{ line: string; hits: number }> = [];
770
+ return (await searchLineHits(query, filePath, limit)).map((hit) => hit.text);
771
+ }
772
+
773
+ /** A matching line with the line number a citation needs. */
774
+ export interface LineHit {
775
+ /** 1-based line number in the session file. */
776
+ line: number;
777
+ /** The raw JSONL line, as read. */
778
+ text: string;
779
+ /** Distinct query terms the line carries. */
780
+ hits: number;
781
+ }
782
+
783
+ /**
784
+ * Matching lines with their line numbers, ranked.
785
+ *
786
+ * Ranked the same way as file order: lines carrying more query terms first, and
787
+ * the stable sort keeps the earliest occurrence first inside a tie. The line
788
+ * number is what makes a rendered snippet citable - a passage an agent cannot
789
+ * point back to is a claim, not evidence.
790
+ */
791
+ export async function searchLineHits(
792
+ query: string,
793
+ filePath: string,
794
+ limit: number,
795
+ ): Promise<LineHit[]> {
796
+ const results: LineHit[] = [];
771
797
  const queryTerms = terms(query);
772
798
  const needles = queryTerms.length > 1 ? queryTerms : [query.toLowerCase()];
773
799
 
774
800
  try {
775
801
  const content = await readFile(filePath, "utf-8");
776
- for (const line of content.split("\n")) {
802
+ const lines = content.split("\n");
803
+ for (let i = 0; i < lines.length; i++) {
804
+ const line = lines[i] as string;
777
805
  const hits = hitsFor(line, needles);
778
- if (hits > 0) results.push({ line, hits });
806
+ if (hits > 0) results.push({ line: i + 1, text: line, hits });
779
807
  }
780
808
  } catch {
781
- // Unreadable session file — partial results are still useful for recall.
809
+ // Unreadable session file - partial results are still useful for recall.
782
810
  }
783
811
 
784
812
  // A file can be in the result set on one term alone, so snippet order is
785
813
  // ranked the same way as file order: lines matching more terms first, and
786
814
  // the stable sort keeps the earliest occurrence first inside a tie.
787
- if (needles.length <= 1) return results.slice(0, limit).map((c) => c.line);
788
- return results
789
- .sort((a, b) => b.hits - a.hits)
790
- .slice(0, limit)
791
- .map((candidate) => candidate.line);
815
+ if (needles.length <= 1) return results.slice(0, limit);
816
+ return results.sort((a, b) => b.hits - a.hits).slice(0, limit);
817
+ }
818
+
819
+ /**
820
+ * Drop the calling session's own file from a match list.
821
+ *
822
+ * A session that matches its own transcript first is the shape that made the
823
+ * archive unreadable: the agent's current words crowd out the human's earlier
824
+ * ones. The comparison resolves symlinked spellings of the same file, so a
825
+ * match reached through another path cannot slip past it.
826
+ */
827
+ export function excludeSessionPath<T extends { path: string }>(
828
+ matches: T[],
829
+ sessionFile: string | null | undefined,
830
+ ): T[] {
831
+ if (!sessionFile) return matches;
832
+ const target = resolveReal(sessionFile);
833
+ return matches.filter((match) => resolveReal(match.path) !== target);
834
+ }
835
+
836
+ /** A path with its symlinks resolved where it exists, else its lexical form. */
837
+ function resolveReal(filePath: string): string {
838
+ try {
839
+ return realpathSync(filePath);
840
+ } catch {
841
+ return filePath;
842
+ }
792
843
  }
793
844
 
794
845
  function hitsFor(line: string, needles: string[]): number {
@@ -32,6 +32,9 @@
32
32
  * - An embedded HTML page collapses to ONE line: status + first prose
33
33
  * excerpt (≤120 chars; tag, style, script and comment contents stripped)
34
34
  * + content type + size — e.g. `403 Blocked (text/html, ~12KB)`.
35
+ * - A page span ends where the page ends: at its closing tag; for a fragment
36
+ * with no closing tag, at the end of its own line or the page cap,
37
+ * whichever comes first. Nothing after the span is touched.
35
38
  * - Base64-class runs are replaced with a length-only marker.
36
39
  * - The edge filter's request trigger (a dot, the `execSync` identifier, an
37
40
  * open paren) gains a space before the paren: neutralized wherever it
@@ -47,6 +50,10 @@
47
50
  * error-sanitization path.
48
51
  */
49
52
 
53
+ import { createLogger } from "../core/logger.js";
54
+
55
+ const log = createLogger("payload-hygiene");
56
+
50
57
  /** A page open: the marker that turns the rest of the text into a body. */
51
58
  const HTML_START_PATTERN = /<!doctype\s+html|<html[\s>]/i;
52
59
 
@@ -187,12 +194,41 @@ export interface RequestHygieneResult {
187
194
  redactions: number;
188
195
  }
189
196
 
190
- /** First page span (`<!doctype html`/`<html` … `</html>` or EOF), if any. */
191
- function findPageSpan(text: string): { start: number; end: number } | null {
197
+ /** First page span (`<!doctype html`/`<html` … `</html>`), if any. */
198
+ interface PageSpan {
199
+ start: number;
200
+ end: number;
201
+ /** Where the end came from; anything but "closing-tag" means the page was unterminated. */
202
+ bound: "closing-tag" | "line-end" | "cap" | "end-of-input";
203
+ }
204
+
205
+ /**
206
+ * A page fragment with no closing tag ends at its own line or at this cap.
207
+ * The cap is far above any observed page (the largest live block page seen is
208
+ * ~12KB), so it binds only on a single-line dump.
209
+ */
210
+ const REQUEST_PAGE_MAX_CHARS = 65_536;
211
+
212
+ /**
213
+ * First page span, if any. A page that carries its closing tag ends there.
214
+ * A fragment that does not (a clipped tool result, a truncated dump) ends at
215
+ * the smaller of its enclosing line's end and REQUEST_PAGE_MAX_CHARS: the
216
+ * fragment is a piece of one line, so the next line is no longer part of it,
217
+ * and an unterminated span must never run to end-of-input: that deletes the
218
+ * payload behind the page, which is the bytes this sanitizer exists to keep
219
+ * (it classified the page, not the tail).
220
+ */
221
+ function findPageSpan(text: string): PageSpan | null {
192
222
  const start = text.search(HTML_START_PATTERN);
193
223
  if (start < 0) return null;
194
224
  const closeAt = text.toLowerCase().lastIndexOf("</html>");
195
- return { start, end: closeAt >= start ? closeAt + "</html>".length : text.length };
225
+ if (closeAt >= start) return { start, end: closeAt + "</html>".length, bound: "closing-tag" };
226
+ const newlineAt = text.indexOf("\n", start);
227
+ const atLineEnd = newlineAt < 0 ? text.length : newlineAt;
228
+ const atCap = start + REQUEST_PAGE_MAX_CHARS;
229
+ const end = Math.min(atLineEnd, atCap);
230
+ const bound = end === atCap ? "cap" : end === text.length ? "end-of-input" : "line-end";
231
+ return { start, end, bound };
196
232
  }
197
233
 
198
234
  /**
@@ -243,6 +279,14 @@ export function sanitizeLlmRequestText(text: string): RequestHygieneResult {
243
279
  const hasEdgeMarker = REQUEST_EDGE_MARKERS.some((marker) => lower.includes(marker));
244
280
  const hasAsset = REQUEST_BASE64_RUN_PATTERN.test(page);
245
281
  if (!hasEdgeMarker && !hasAsset) break;
282
+ if (span.bound !== "closing-tag") {
283
+ // A silent tail loss becomes a visible one: the span had no closing tag,
284
+ // so the bound decided where it stopped, and the byte count says how much
285
+ // the page claimed. Bytes after it are kept.
286
+ log.warn(
287
+ `page span without a closing tag: ${span.end - span.start} chars redacted (${span.bound}); bytes after it are kept`,
288
+ );
289
+ }
246
290
  const marker = `[redacted edge/WAF page fragment: ${page.length} chars]`;
247
291
  out = `${out.slice(0, span.start)}${marker}${out.slice(span.end)}`;
248
292
  redactions++;
@@ -156,6 +156,13 @@ export function projectsDir(): string {
156
156
  return path.join(braidDir(), "projects");
157
157
  }
158
158
 
159
+ /** Derived-store root for the session corpus index (one shard per project),
160
+ * resolved on every call. Derived data: deleting this directory only costs a
161
+ * rebuild from the session files. */
162
+ export function corpusIndexDir(): string {
163
+ return path.join(braidDir(), "corpus-index");
164
+ }
165
+
159
166
  // ── File paths ─────────────────────────────────────────────────────────────
160
167
 
161
168
  /** lib/memory semantic + episodic store */
@@ -88,13 +88,17 @@ interface BraidConfig {
88
88
  * Skills-layer config. `ranking` picks the tier policy of the `list_skills`
89
89
  * relevance ranking: "auto" (default: the deterministic scorer answers, and
90
90
  * the utility model is asked only when that answer is ambiguous), "keyword"
91
- * (never call the model), "model" (always).
91
+ * (never call the model), "model" (always). `inform` enables the at-use
92
+ * line: after a call in a tool family a visible skill declares with
93
+ * `governs:`, one steer names the file and the obligation to read it.
92
94
  *
93
- * Example: "braid": { "skills": { "ranking": "keyword" } }
95
+ * Example: "braid": { "skills": { "ranking": "keyword", "inform": "inform" } }
94
96
  */
95
97
  skills?: {
96
- /** "auto" | "keyword" | "model" — an unknown value falls back to "auto". */
98
+ /** "auto" | "keyword" | "model" - an unknown value falls back to "auto". */
97
99
  ranking?: string;
100
+ /** "off" (default) | "inform" - an unknown value falls back to "off". */
101
+ inform?: string;
98
102
  };
99
103
  /**
100
104
  * Memory-layer config. Review-before-write quality gate on durable episode
@@ -623,6 +627,41 @@ export function getSkillsRankingMode(): SkillsRankingMode {
623
627
  return resolveSkillsRankingMode(readSettings().braid?.skills?.ranking);
624
628
  }
625
629
 
630
+ // ── skills inform (braid.skills.inform) ────────────────────────────────────
631
+
632
+ /**
633
+ * What the skills module does when a completed call lands in a tool family a
634
+ * visible skill's file declares with `governs:` and no read of that body is on
635
+ * the session record.
636
+ *
637
+ * off - nothing. The declaration still feeds the applied leg of the
638
+ * session record; it is never spoken about. The default, because a
639
+ * skill body already has a voice in the suggestion whisper and a
640
+ * second one must be asked for.
641
+ * inform - one steer line per session per skill: the file path and the
642
+ * obligation. It observes a call that already ran; it never
643
+ * refuses, delays or rewrites one.
644
+ */
645
+ export type SkillsInformMode = "off" | "inform";
646
+
647
+ export const SKILLS_INFORM_DEFAULT: SkillsInformMode = "off";
648
+
649
+ /**
650
+ * Resolve the inform mode from a raw setting value. Unknown or malformed
651
+ * values fall back to the default: a typo must never turn a whisper on. Pure.
652
+ */
653
+ export function resolveSkillsInformMode(raw: unknown): SkillsInformMode {
654
+ const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
655
+ return value === "inform" || value === "off"
656
+ ? (value as SkillsInformMode)
657
+ : SKILLS_INFORM_DEFAULT;
658
+ }
659
+
660
+ /** Read braid.skills.inform from settings.json (default: "off"). */
661
+ export function getSkillsInformMode(): SkillsInformMode {
662
+ return resolveSkillsInformMode(readSettings().braid?.skills?.inform);
663
+ }
664
+
626
665
  // ── stale toolResult offload (braid.context.staleToolResultOffload) ────
627
666
 
628
667
  /**
@@ -6,13 +6,14 @@ Pure-logic detectors used by extensions to identify patterns.
6
6
 
7
7
  ## Files
8
8
 
9
- | File | Purpose |
10
- | ------------------------- | ---------------------------------------------------------------------------------------------------- |
11
- | `degradation-detector.ts` | Tracks analytics metrics and detects degradation (e.g., declining tool-success rate). |
12
- | `topic-drift-detector.ts` | Determines whether the current turn is drifting away from the original task. Used by `enforcement/`. |
13
- | `context-density.ts` | Estimates how "dense" the context is (tokens per turn). Used to predict overflow. |
14
- | `context-thresholds.ts` | Threshold constants and helpers for "context full" signals. |
15
- | `compression-strategy.ts` | Decides which compaction strategy to use when context is full. |
9
+ | File | Purpose |
10
+ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11
+ | `tool-loop-detector.ts` | The one tool-loop detector: is the agent repeating one call? Identity is tool + arguments, so a chain of distinct commands under one tool name is not a loop. Used by `enforcement/`. |
12
+ | `degradation-detector.ts` | Tracks analytics metrics and detects degradation (e.g., declining tool-success rate). |
13
+ | `topic-drift-detector.ts` | Determines whether the current turn is drifting away from the original task. Used by `enforcement/`. |
14
+ | `context-density.ts` | Estimates how "dense" the context is (tokens per turn). Used to predict overflow. |
15
+ | `context-thresholds.ts` | Threshold constants and helpers for "context full" signals. |
16
+ | `compression-strategy.ts` | Decides which compaction strategy to use when context is full. |
16
17
 
17
18
  ## Local Contracts
18
19