pi-braid 0.43.7 → 0.43.9

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 (64) hide show
  1. package/CHANGELOG.md +72 -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 +44 -0
  28. package/dist/lib/config/braid-settings.js +41 -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/memory/constants.d.ts +38 -0
  32. package/dist/lib/memory/constants.js +196 -0
  33. package/dist/lib/memory/index.js +49 -10
  34. package/dist/lib/memory/lifecycle.d.ts +8 -0
  35. package/dist/lib/memory/lifecycle.js +43 -18
  36. package/dist/lib/reasoning/dreamer.d.ts +2 -1
  37. package/dist/lib/reasoning/dreamer.js +12 -7
  38. package/docs/LOCAL_DEV.md +1 -1
  39. package/docs/SETUP.md +2 -0
  40. package/package.json +1 -1
  41. package/src/extensions/core/AGENTS.md +3 -2
  42. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  43. package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
  44. package/src/extensions/core/skills-tool/index.ts +21 -1
  45. package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
  46. package/src/extensions/core/skills-tool/session-records.ts +201 -9
  47. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
  48. package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
  49. package/src/extensions/enforcement/verification-judge.ts +32 -25
  50. package/src/extensions/memory/AGENTS.md +2 -2
  51. package/src/extensions/memory/session-recall/AGENTS.md +92 -18
  52. package/src/extensions/memory/session-recall/ask.ts +435 -0
  53. package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
  54. package/src/extensions/memory/session-recall/index.ts +202 -21
  55. package/src/extensions/memory/session-recall/search.ts +61 -10
  56. package/src/lib/ai/payload-hygiene.ts +47 -3
  57. package/src/lib/config/braid-paths.ts +7 -0
  58. package/src/lib/config/braid-settings.ts +93 -3
  59. package/src/lib/detection/AGENTS.md +8 -7
  60. package/src/lib/detection/tool-loop-detector.ts +339 -195
  61. package/src/lib/memory/constants.ts +202 -0
  62. package/src/lib/memory/index.ts +59 -8
  63. package/src/lib/memory/lifecycle.ts +50 -16
  64. package/src/lib/reasoning/dreamer.ts +13 -6
@@ -33,8 +33,10 @@ import { Type } from "typebox";
33
33
  import { basename } from "node:path";
34
34
  import { asyncExists } from "../../../lib/utils/async-fs.js";
35
35
  import * as import_textUtils from "./text-utils.js";
36
- import { getSessionsDir, projectFromPath, pathMatchesProject, dateFromPath, searchFiles, searchFilesWithInfo, searchLines, walkJsonlFiles, tokenizeQuery, labelFromCwd, messagesMatchingTerms, MAX_SEARCH_RESULTS, MAX_SNIPPETS_PER_SESSION, } from "./search.js";
36
+ import { getSessionsDir, projectFromPath, pathMatchesProject, dateFromPath, searchFiles, searchFilesWithInfo, searchLineHits, excludeSessionPath, walkJsonlFiles, tokenizeQuery, labelFromCwd, messagesMatchingTerms, MAX_SEARCH_RESULTS, MAX_SNIPPETS_PER_SESSION, } from "./search.js";
37
37
  import { rankSearchResults } from "./rank.js";
38
+ import { corpusIndexFreshness, loadCorpusIndex } from "./corpus-index.js";
39
+ import { askCorpusIndex, formatAskResult, MAX_ASK_HITS } from "./ask.js";
38
40
  import { loadSessionMessages, serializeSession, QUERY_SYSTEM_PROMPT } from "./query.js";
39
41
  import { collectSessionStats } from "./stats.js";
40
42
  import { summarizeSession, buildAnalysisInput, ANALYZE_SYSTEM_PROMPT } from "./analyze.js";
@@ -52,17 +54,19 @@ const MAX_ARCHIVE_MESSAGES = import_textUtils.MAX_ARCHIVE_MESSAGES;
52
54
  const sessionSchema = Type.Object({
53
55
  action: Type.Union([
54
56
  Type.Literal("search"),
57
+ Type.Literal("ask"),
55
58
  Type.Literal("query"),
56
59
  Type.Literal("batch"),
57
60
  Type.Literal("stats"),
58
61
  Type.Literal("analyze"),
59
62
  Type.Literal("context"),
60
63
  ], {
61
- description: "Action: search | query | batch | stats | analyze | context",
64
+ description: "Action: search | ask | query | batch | stats | analyze | context",
62
65
  }),
63
- // search-only
66
+ // search/ask
64
67
  query: Type.Optional(Type.String({
65
- description: "Search terms, space-separated; a file matching any term is returned and files carrying the whole phrase rank first. action=search.",
68
+ description: "Search terms, space-separated; a file matching any term is returned and files carrying the whole phrase rank first. action=search. " +
69
+ "For action=ask, the question in words: it is scored against the corpus index of user turns and the top turns are cited.",
66
70
  })),
67
71
  // query-only
68
72
  sessionPath: Type.Optional(Type.String({ description: "Full path to .jsonl session file (action=query)" })),
@@ -93,6 +97,67 @@ const sessionSchema = Type.Object({
93
97
  function positiveLimit(value) {
94
98
  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
95
99
  }
100
+ // Helpers the search, ask and batch actions share
101
+ /** Passages one `batch` result renders across all its sessions. */
102
+ const MAX_BATCH_LINES = 20;
103
+ /**
104
+ * The session file this call runs in.
105
+ *
106
+ * A session must never match its own transcript: the current turn's own words
107
+ * are the query, so it would outrank the earlier evidence it is looking for.
108
+ * pi exposes the file on the session manager; the environment carries it for a
109
+ * context without one.
110
+ */
111
+ function callingSessionFile(ctx) {
112
+ const manager = ctx?.sessionManager;
113
+ const fromManager = manager?.getSessionFile?.() ?? manager?.sessionFile;
114
+ if (typeof fromManager === "string" && fromManager)
115
+ return fromManager;
116
+ const fromEnv = process.env.PI_SESSION_FILE;
117
+ return typeof fromEnv === "string" && fromEnv ? fromEnv : null;
118
+ }
119
+ /**
120
+ * One matched JSONL line as a readable passage, or null when the line carries
121
+ * no message text. A compaction envelope holds many messages in one physical
122
+ * line, so the messages carrying the pattern are preferred over the first.
123
+ */
124
+ function linePassage(rawLine, query) {
125
+ const parsed = extractLineMessages(rawLine);
126
+ const terms = tokenizeQuery(query);
127
+ const shown = parsed.isArchive && terms.length > 0
128
+ ? messagesMatchingTerms(parsed.messages, terms)
129
+ : parsed.messages;
130
+ const first = shown[0] ?? parsed.messages[0];
131
+ if (!first)
132
+ return null;
133
+ const text = snippetAround(first.text, query, 110).replace(/\s+/g, " ").trim();
134
+ return ` [${first.role}] ${text}`;
135
+ }
136
+ /**
137
+ * Ranked passages across matched sessions: term coverage first, then recency,
138
+ * capped at MAX_BATCH_LINES. One read per session, and only for the sessions
139
+ * the caller's limit already selected.
140
+ */
141
+ async function batchPassages(sessions, pattern) {
142
+ const scored = [];
143
+ for (const session of sessions) {
144
+ if (scored.length >= MAX_BATCH_LINES)
145
+ break;
146
+ const hits = await searchLineHits(pattern, session.path, MAX_SNIPPETS_PER_SESSION);
147
+ for (const hit of hits) {
148
+ const passage = linePassage(hit.text, pattern);
149
+ if (!passage)
150
+ continue;
151
+ scored.push({
152
+ weight: hit.hits,
153
+ when: dateFromPath(session.path),
154
+ text: `${passage} \`${basename(session.path)}:${hit.line}\``,
155
+ });
156
+ }
157
+ }
158
+ scored.sort((a, b) => b.weight - a.weight || b.when.localeCompare(a.when));
159
+ return scored.slice(0, MAX_BATCH_LINES).map((entry) => entry.text);
160
+ }
96
161
  // Extension
97
162
  export default function sessionRecallExtension(pi) {
98
163
  let currentModel;
@@ -102,9 +167,10 @@ export default function sessionRecallExtension(pi) {
102
167
  pi.registerTool({
103
168
  name: "session",
104
169
  label: "Session",
105
- promptSnippet: "Access past session history — search, query, analyze, stats, or context",
106
- description: "Access past session history: search, query a specific session, analyze multiple, batch across sessions, stats, or context (cross-session §8 adoption aggregate). " +
107
- "LLM-driven except search, batch, stats, and context.",
170
+ promptSnippet: "Access past session history — search, ask, query, analyze, stats, or context",
171
+ description: "Access past session history: search, ask, query a specific session, analyze multiple, batch across sessions, stats, or context (cross-session §8 adoption aggregate). " +
172
+ "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. " +
173
+ "LLM-driven except search, ask, batch, stats, and context.",
108
174
  parameters: sessionSchema,
109
175
  execute: async (_toolCallId, params, signal, _onUpdate, _ctx) => {
110
176
  try {
@@ -126,12 +192,15 @@ export default function sessionRecallExtension(pi) {
126
192
  };
127
193
  }
128
194
  const currentProject = _ctx?.cwd ? labelFromCwd(_ctx.cwd) : undefined;
195
+ const ownSession = callingSessionFile(_ctx);
129
196
  // The four-signal ranker also picks the bounded candidate set the
130
- // role signal is refined on; see search.ts ROLE_REFINE_LIMIT.
197
+ // role signal is refined on; see search.ts ROLE_REFINE_LIMIT. The
198
+ // caller's own session is dropped before either read, so a session
199
+ // can never match itself (search.ts excludeSessionPath).
131
200
  const info = await searchFilesWithInfo(params.query, sessionsDir, {
132
- rankCandidates: (matches) => rankSearchResults(matches, { currentProject }),
201
+ rankCandidates: (matches) => rankSearchResults(excludeSessionPath(matches, ownSession), { currentProject }),
133
202
  });
134
- const allMatches = info.matches;
203
+ const allMatches = excludeSessionPath(info.matches, ownSession);
135
204
  if (allMatches.length === 0) {
136
205
  return {
137
206
  content: [
@@ -153,14 +222,14 @@ export default function sessionRecallExtension(pi) {
153
222
  const fileMatches = rankSearchResults(allMatches, { currentProject }).slice(0, MAX_SEARCH_RESULTS);
154
223
  const results = [];
155
224
  const queryTerms = tokenizeQuery(params.query);
156
- for (const { path: filePath, count } of fileMatches) {
225
+ for (const { path: filePath } of fileMatches) {
157
226
  const project = projectFromPath(filePath);
158
227
  const date = dateFromPath(filePath);
159
- const matchLines = await searchLines(params.query, filePath, MAX_SNIPPETS_PER_SESSION);
228
+ const matchLines = await searchLineHits(params.query, filePath, MAX_SNIPPETS_PER_SESSION);
160
229
  const snippets = [];
161
230
  let archiveNote = "";
162
- for (const line of matchLines) {
163
- const parsed = extractLineMessages(line);
231
+ for (const hit of matchLines) {
232
+ const parsed = extractLineMessages(hit.text);
164
233
  // A live line carries one message. A compaction envelope carries
165
234
  // the whole archived batch inside its `originals` string, and the
166
235
  // one physical line matches if the query is anywhere in that
@@ -174,7 +243,7 @@ export default function sessionRecallExtension(pi) {
174
243
  for (const msg of shown) {
175
244
  if (snippets.length >= MAX_SNIPPETS_PER_SESSION)
176
245
  break;
177
- snippets.push(` [${msg.role}] ${snippetAround(msg.text, params.query)}`);
246
+ snippets.push(` [${msg.role}] L${hit.line}: ${snippetAround(msg.text, params.query)}`);
178
247
  }
179
248
  if (parsed.isArchive) {
180
249
  const parts = [
@@ -200,7 +269,7 @@ export default function sessionRecallExtension(pi) {
200
269
  // matches.
201
270
  if (snippets.length === 0 && !archiveNote)
202
271
  continue;
203
- results.push(`**${date}** - \`${project}\` - ${count} match${count > 1 ? "es" : ""}\n` +
272
+ results.push(`**${date}** - \`${project}\`\n` +
204
273
  `Session: \`${filePath}\`\n` +
205
274
  [...snippets, archiveNote].filter(Boolean).join("\n"));
206
275
  }
@@ -215,7 +284,7 @@ export default function sessionRecallExtension(pi) {
215
284
  details: { matchCount: 0 },
216
285
  };
217
286
  }
218
- const output = `Found ${results.length} session${results.length > 1 ? "s" : ""} matching "${params.query}":\n\n` +
287
+ const output = `**Search:** "${params.query}" - matched lines from ${results.length} session${results.length > 1 ? "s" : ""}, ranked:\n\n` +
219
288
  results.join("\n\n---\n\n");
220
289
  return {
221
290
  content: [{ type: "text", text: output }],
@@ -225,6 +294,73 @@ export default function sessionRecallExtension(pi) {
225
294
  backend: info.backend,
226
295
  elapsedMs: info.elapsedMs,
227
296
  roleRefined: info.roleRefined,
297
+ selfSessionExcluded: Boolean(ownSession),
298
+ },
299
+ };
300
+ }
301
+ case "ask": {
302
+ if (!params.query) {
303
+ return {
304
+ content: [{ type: "text", text: "action=ask requires 'query' parameter" }],
305
+ details: { error: true, action: "ask" },
306
+ };
307
+ }
308
+ const projectFilter = params.project === "all"
309
+ ? null
310
+ : (params.project ?? (_ctx?.cwd ? labelFromCwd(_ctx.cwd) : null));
311
+ const loaded = await loadCorpusIndex(projectFilter ? { project: projectFilter } : {});
312
+ if (!loaded.ok) {
313
+ const hint = projectFilter ? ` Pass project=all to query every project's shard.` : "";
314
+ return {
315
+ content: [
316
+ {
317
+ type: "text",
318
+ text: `The corpus index cannot answer: ${loaded.reason}.${hint} ` +
319
+ `Index directory: \`${loaded.dir}\`. Build it with ` +
320
+ `\`node packages/core/scripts/build-corpus-index.mjs\` (one pass over the ` +
321
+ `session files), then ask again.`,
322
+ },
323
+ ],
324
+ details: {
325
+ error: true,
326
+ action: "ask",
327
+ indexDir: loaded.dir,
328
+ reason: loaded.reason,
329
+ shards: loaded.shards,
330
+ },
331
+ };
332
+ }
333
+ // The answer states its own freshness: a shard is derived data, so
334
+ // the drift is measured and printed rather than assumed away.
335
+ const freshness = await corpusIndexFreshness(loaded.shards, getSessionsDir(_ctx));
336
+ const result = askCorpusIndex(loaded.shards, params.query, {
337
+ project: projectFilter,
338
+ since: params.since ?? null,
339
+ limit: positiveLimit(params.limit) ?? MAX_ASK_HITS,
340
+ excludeSession: callingSessionFile(_ctx),
341
+ freshness,
342
+ });
343
+ return {
344
+ content: [{ type: "text", text: formatAskResult(result) }],
345
+ details: {
346
+ action: "ask",
347
+ answered: result.answered,
348
+ query: params.query,
349
+ terms: result.terms,
350
+ matchedTerms: result.matched_terms,
351
+ unmatchedTerms: result.unmatched_terms,
352
+ hits: result.hits.map((hit) => ({
353
+ project: hit.turn.project,
354
+ session: hit.turn.session,
355
+ sessionId: hit.turn.session_id,
356
+ line: hit.turn.line,
357
+ ts: hit.turn.ts,
358
+ score: Number(hit.score.toFixed(3)),
359
+ })),
360
+ population: result.population,
361
+ freshness,
362
+ indexDir: loaded.dir,
363
+ selfSessionExcluded: result.self_excluded,
228
364
  },
229
365
  };
230
366
  }
@@ -358,7 +494,8 @@ export default function sessionRecallExtension(pi) {
358
494
  details: { error: true, matchCount: 0 },
359
495
  };
360
496
  }
361
- const allMatches = await searchFiles(params.pattern, sessionsDir);
497
+ const ownSession = callingSessionFile(_ctx);
498
+ const allMatches = excludeSessionPath(await searchFiles(params.pattern, sessionsDir), ownSession);
362
499
  if (allMatches.length === 0) {
363
500
  return {
364
501
  content: [
@@ -421,12 +558,25 @@ export default function sessionRecallExtension(pi) {
421
558
  // never as the old unbounded mode.
422
559
  const limit = positiveLimit(params.limit) ?? 10;
423
560
  const topSessions = filtered.slice(0, limit);
561
+ // The result leads with passages, not a count: aggregate numbers
562
+ // say how much matched, never what matched. Reads are bounded by
563
+ // the session limit above and MAX_BATCH_LINES below.
564
+ const passages = await batchPassages(topSessions, params.pattern);
424
565
  const lines = [
425
566
  `## Batch: "${params.pattern}"`,
426
567
  ``, //
427
- `**Total matches:** ${totalMatches} in ${filtered.length} session${filtered.length === 1 ? "" : "s"}`,
428
- ``, //
429
568
  ];
569
+ if (passages.length > 0) {
570
+ lines.push(`**Matched lines** (${passages.length} of ${totalMatches} matches, ranked):`);
571
+ lines.push(...passages);
572
+ }
573
+ else {
574
+ lines.push(`**Matched lines:** none rendered - the matching sessions carry the pattern only in ` +
575
+ `text this reader does not extract (tool results, metadata).`);
576
+ }
577
+ lines.push("");
578
+ lines.push(`**Aggregates:** ${totalMatches} match${totalMatches === 1 ? "" : "es"} in ${filtered.length} session${filtered.length === 1 ? "" : "s"}`);
579
+ lines.push("");
430
580
  // By project
431
581
  const projectEntries = Object.entries(byProject).sort((a, b) => b[1] - a[1]);
432
582
  lines.push("**By project:**");
@@ -456,6 +606,8 @@ export default function sessionRecallExtension(pi) {
456
606
  pattern: params.pattern,
457
607
  totalMatches,
458
608
  sessionCount: filtered.length,
609
+ renderedPassages: passages.length,
610
+ selfSessionExcluded: Boolean(ownSession),
459
611
  byProject: projectEntries,
460
612
  byMonth: monthEntries,
461
613
  topSessions: topSessions.map((m) => ({
@@ -767,7 +919,7 @@ export default function sessionRecallExtension(pi) {
767
919
  };
768
920
  }
769
921
  default:
770
- throw new Error(`Unknown session action: ${params?.action}. Use: search, query, batch, stats, analyze, context.`);
922
+ throw new Error(`Unknown session action: ${params?.action}. Use: search, ask, query, batch, stats, analyze, context.`);
771
923
  }
772
924
  }
773
925
  catch (err) {
@@ -156,4 +156,33 @@ export declare function messagesMatchingTerms<T extends {
156
156
  text: string;
157
157
  }>(messages: T[], queryTerms: string[]): T[];
158
158
  export declare function searchLines(query: string, filePath: string, limit: number): Promise<string[]>;
159
+ /** A matching line with the line number a citation needs. */
160
+ export interface LineHit {
161
+ /** 1-based line number in the session file. */
162
+ line: number;
163
+ /** The raw JSONL line, as read. */
164
+ text: string;
165
+ /** Distinct query terms the line carries. */
166
+ hits: number;
167
+ }
168
+ /**
169
+ * Matching lines with their line numbers, ranked.
170
+ *
171
+ * Ranked the same way as file order: lines carrying more query terms first, and
172
+ * the stable sort keeps the earliest occurrence first inside a tie. The line
173
+ * number is what makes a rendered snippet citable - a passage an agent cannot
174
+ * point back to is a claim, not evidence.
175
+ */
176
+ export declare function searchLineHits(query: string, filePath: string, limit: number): Promise<LineHit[]>;
177
+ /**
178
+ * Drop the calling session's own file from a match list.
179
+ *
180
+ * A session that matches its own transcript first is the shape that made the
181
+ * archive unreadable: the agent's current words crowd out the human's earlier
182
+ * ones. The comparison resolves symlinked spellings of the same file, so a
183
+ * match reached through another path cannot slip past it.
184
+ */
185
+ export declare function excludeSessionPath<T extends {
186
+ path: string;
187
+ }>(matches: T[], sessionFile: string | null | undefined): T[];
159
188
  //# sourceMappingURL=search.d.ts.map
@@ -5,7 +5,7 @@
5
5
  * Supports rg, grep, and Node.js fallback backends.
6
6
  */
7
7
  import { execFileSync } from "node:child_process";
8
- import { closeSync, openSync, readSync, readdirSync, statSync } from "node:fs";
8
+ import { closeSync, openSync, readSync, readdirSync, realpathSync, statSync } from "node:fs";
9
9
  import { readdir, readFile } from "node:fs/promises";
10
10
  import { basename, dirname, join } from "node:path";
11
11
  import { homedir } from "node:os";
@@ -646,29 +646,62 @@ export function messagesMatchingTerms(messages, queryTerms) {
646
646
  .map((candidate) => candidate.msg);
647
647
  }
648
648
  export async function searchLines(query, filePath, limit) {
649
+ return (await searchLineHits(query, filePath, limit)).map((hit) => hit.text);
650
+ }
651
+ /**
652
+ * Matching lines with their line numbers, ranked.
653
+ *
654
+ * Ranked the same way as file order: lines carrying more query terms first, and
655
+ * the stable sort keeps the earliest occurrence first inside a tie. The line
656
+ * number is what makes a rendered snippet citable - a passage an agent cannot
657
+ * point back to is a claim, not evidence.
658
+ */
659
+ export async function searchLineHits(query, filePath, limit) {
649
660
  const results = [];
650
661
  const queryTerms = terms(query);
651
662
  const needles = queryTerms.length > 1 ? queryTerms : [query.toLowerCase()];
652
663
  try {
653
664
  const content = await readFile(filePath, "utf-8");
654
- for (const line of content.split("\n")) {
665
+ const lines = content.split("\n");
666
+ for (let i = 0; i < lines.length; i++) {
667
+ const line = lines[i];
655
668
  const hits = hitsFor(line, needles);
656
669
  if (hits > 0)
657
- results.push({ line, hits });
670
+ results.push({ line: i + 1, text: line, hits });
658
671
  }
659
672
  }
660
673
  catch {
661
- // Unreadable session file — partial results are still useful for recall.
674
+ // Unreadable session file - partial results are still useful for recall.
662
675
  }
663
676
  // A file can be in the result set on one term alone, so snippet order is
664
677
  // ranked the same way as file order: lines matching more terms first, and
665
678
  // the stable sort keeps the earliest occurrence first inside a tie.
666
679
  if (needles.length <= 1)
667
- return results.slice(0, limit).map((c) => c.line);
668
- return results
669
- .sort((a, b) => b.hits - a.hits)
670
- .slice(0, limit)
671
- .map((candidate) => candidate.line);
680
+ return results.slice(0, limit);
681
+ return results.sort((a, b) => b.hits - a.hits).slice(0, limit);
682
+ }
683
+ /**
684
+ * Drop the calling session's own file from a match list.
685
+ *
686
+ * A session that matches its own transcript first is the shape that made the
687
+ * archive unreadable: the agent's current words crowd out the human's earlier
688
+ * ones. The comparison resolves symlinked spellings of the same file, so a
689
+ * match reached through another path cannot slip past it.
690
+ */
691
+ export function excludeSessionPath(matches, sessionFile) {
692
+ if (!sessionFile)
693
+ return matches;
694
+ const target = resolveReal(sessionFile);
695
+ return matches.filter((match) => resolveReal(match.path) !== target);
696
+ }
697
+ /** A path with its symlinks resolved where it exists, else its lexical form. */
698
+ function resolveReal(filePath) {
699
+ try {
700
+ return realpathSync(filePath);
701
+ }
702
+ catch {
703
+ return filePath;
704
+ }
672
705
  }
673
706
  function hitsFor(line, needles) {
674
707
  const lower = line.toLowerCase();
@@ -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
@@ -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
@@ -46,6 +49,8 @@
46
49
  * its own response handling and does not route through callLlm's
47
50
  * error-sanitization path.
48
51
  */
52
+ import { createLogger } from "../core/logger.js";
53
+ const log = createLogger("payload-hygiene");
49
54
  /** A page open: the marker that turns the rest of the text into a body. */
50
55
  const HTML_START_PATTERN = /<!doctype\s+html|<html[\s>]/i;
51
56
  /** Status code at the head of a provider error ("403 …", "HTTP 502 …"). */
@@ -164,13 +169,34 @@ const REQUEST_EDGE_MARKERS = [
164
169
  */
165
170
  const REQUEST_DUMP_MAX_CHARS = 262_144;
166
171
  const REQUEST_DUMP_HEAD_CHARS = 2000;
167
- /** First page span (`<!doctype html`/`<html` … `</html>` or EOF), if any. */
172
+ /**
173
+ * A page fragment with no closing tag ends at its own line or at this cap.
174
+ * The cap is far above any observed page (the largest live block page seen is
175
+ * ~12KB), so it binds only on a single-line dump.
176
+ */
177
+ const REQUEST_PAGE_MAX_CHARS = 65_536;
178
+ /**
179
+ * First page span, if any. A page that carries its closing tag ends there.
180
+ * A fragment that does not (a clipped tool result, a truncated dump) ends at
181
+ * the smaller of its enclosing line's end and REQUEST_PAGE_MAX_CHARS: the
182
+ * fragment is a piece of one line, so the next line is no longer part of it,
183
+ * and an unterminated span must never run to end-of-input: that deletes the
184
+ * payload behind the page, which is the bytes this sanitizer exists to keep
185
+ * (it classified the page, not the tail).
186
+ */
168
187
  function findPageSpan(text) {
169
188
  const start = text.search(HTML_START_PATTERN);
170
189
  if (start < 0)
171
190
  return null;
172
191
  const closeAt = text.toLowerCase().lastIndexOf("</html>");
173
- return { start, end: closeAt >= start ? closeAt + "</html>".length : text.length };
192
+ if (closeAt >= start)
193
+ return { start, end: closeAt + "</html>".length, bound: "closing-tag" };
194
+ const newlineAt = text.indexOf("\n", start);
195
+ const atLineEnd = newlineAt < 0 ? text.length : newlineAt;
196
+ const atCap = start + REQUEST_PAGE_MAX_CHARS;
197
+ const end = Math.min(atLineEnd, atCap);
198
+ const bound = end === atCap ? "cap" : end === text.length ? "end-of-input" : "line-end";
199
+ return { start, end, bound };
174
200
  }
175
201
  /**
176
202
  * Request-side edge-filter trigger: the gateway host rejects a body that
@@ -220,6 +246,12 @@ export function sanitizeLlmRequestText(text) {
220
246
  const hasAsset = REQUEST_BASE64_RUN_PATTERN.test(page);
221
247
  if (!hasEdgeMarker && !hasAsset)
222
248
  break;
249
+ if (span.bound !== "closing-tag") {
250
+ // A silent tail loss becomes a visible one: the span had no closing tag,
251
+ // so the bound decided where it stopped, and the byte count says how much
252
+ // the page claimed. Bytes after it are kept.
253
+ log.warn(`page span without a closing tag: ${span.end - span.start} chars redacted (${span.bound}); bytes after it are kept`);
254
+ }
223
255
  const marker = `[redacted edge/WAF page fragment: ${page.length} chars]`;
224
256
  out = `${out.slice(0, span.start)}${marker}${out.slice(span.end)}`;
225
257
  redactions++;
@@ -71,6 +71,10 @@ export declare function snapshotDir(): string;
71
71
  /** Per-project store root (locks, workers, timers, module overrides,
72
72
  * deliverables), resolved on every call. */
73
73
  export declare function projectsDir(): string;
74
+ /** Derived-store root for the session corpus index (one shard per project),
75
+ * resolved on every call. Derived data: deleting this directory only costs a
76
+ * rebuild from the session files. */
77
+ export declare function corpusIndexDir(): string;
74
78
  /** lib/memory semantic + episodic store */
75
79
  export declare const SEMANTIC_MEMORY_FILE: string;
76
80
  /** Semantic store, resolved on every call (durable-write base). */
@@ -135,6 +135,12 @@ export function snapshotDir() {
135
135
  export function projectsDir() {
136
136
  return path.join(braidDir(), "projects");
137
137
  }
138
+ /** Derived-store root for the session corpus index (one shard per project),
139
+ * resolved on every call. Derived data: deleting this directory only costs a
140
+ * rebuild from the session files. */
141
+ export function corpusIndexDir() {
142
+ return path.join(braidDir(), "corpus-index");
143
+ }
138
144
  // ── File paths ─────────────────────────────────────────────────────────────
139
145
  /** lib/memory semantic + episodic store */
140
146
  export const SEMANTIC_MEMORY_FILE = path.join(MEMORY_DIR, "semantic.json");
@@ -140,6 +140,28 @@ interface RawWriteGateBlock {
140
140
  * is unit-testable without touching live settings.json.
141
141
  */
142
142
  export declare function resolveMemoryWriteGateConfig(raw?: RawWriteGateBlock): MemoryWriteGateConfig;
143
+ /** A reserved partition: which source prefix is protected, and for how many slots. */
144
+ export interface ReservedProvenanceConfig {
145
+ prefix: string;
146
+ slots: number;
147
+ }
148
+ /**
149
+ * Pure resolver for the braid.memory.reservedProvenance block. Absent or
150
+ * malformed fields fall back to RESERVED_PROVENANCE_DEFAULTS (partition off),
151
+ * so a typo cannot start holding slots for a class nobody named. `slots` is
152
+ * clamped to MAX_ENTRIES: a reservation at or above the cap would leave the
153
+ * general pool no room at all. Kept pure so the merge is testable without
154
+ * touching live settings.json.
155
+ */
156
+ export declare function resolveReservedProvenance(raw?: {
157
+ prefix?: unknown;
158
+ slots?: unknown;
159
+ }): ReservedProvenanceConfig;
160
+ /**
161
+ * Read braid.memory.reservedProvenance from settings.json, fresh on every call
162
+ * (no caching), like the other readers. Default: no partition.
163
+ */
164
+ export declare function getMemoryReservedProvenance(): ReservedProvenanceConfig;
143
165
  /**
144
166
  * The owner time zone for all braid-facing time rendering (lib/utils/local-time.ts).
145
167
  * braid.timezone in settings.json when set to a non-empty string; otherwise
@@ -169,6 +191,28 @@ export declare const SKILLS_RANKING_DEFAULT: SkillsRankingMode;
169
191
  export declare function resolveSkillsRankingMode(raw: unknown): SkillsRankingMode;
170
192
  /** Read braid.skills.ranking from settings.json (default: "keyword"). */
171
193
  export declare function getSkillsRankingMode(): SkillsRankingMode;
194
+ /**
195
+ * What the skills module does when a completed call lands in a tool family a
196
+ * visible skill's file declares with `governs:` and no read of that body is on
197
+ * the session record.
198
+ *
199
+ * off - nothing. The declaration still feeds the applied leg of the
200
+ * session record; it is never spoken about. The default, because a
201
+ * skill body already has a voice in the suggestion whisper and a
202
+ * second one must be asked for.
203
+ * inform - one steer line per session per skill: the file path and the
204
+ * obligation. It observes a call that already ran; it never
205
+ * refuses, delays or rewrites one.
206
+ */
207
+ export type SkillsInformMode = "off" | "inform";
208
+ export declare const SKILLS_INFORM_DEFAULT: SkillsInformMode;
209
+ /**
210
+ * Resolve the inform mode from a raw setting value. Unknown or malformed
211
+ * values fall back to the default: a typo must never turn a whisper on. Pure.
212
+ */
213
+ export declare function resolveSkillsInformMode(raw: unknown): SkillsInformMode;
214
+ /** Read braid.skills.inform from settings.json (default: "off"). */
215
+ export declare function getSkillsInformMode(): SkillsInformMode;
172
216
  /**
173
217
  * Sane defaults for the optional staleToolResultOffload params (defined next
174
218
  * to the schema per the design contract). Investigation suggests a size
@@ -9,6 +9,7 @@ import { existsSync, readFileSync } from "node:fs";
9
9
  import { createLogger } from "../core/logger.js";
10
10
  import { USAGE_COMPACT_MEDIUM, USAGE_WHISPER_CRITICAL, USAGE_WHISPER_WARNING, } from "../detection/context-thresholds.js";
11
11
  import { MEMORY_WRITE_GATE_DEFAULTS, WRITE_GATE_SITES, } from "../memory/write-quality.js";
12
+ import { MAX_ENTRIES, RESERVED_PROVENANCE_DEFAULTS } from "../memory/constants.js";
12
13
  import { getSettingsPath } from "./per-tool-settings.js";
13
14
  const _log = createLogger("braid-settings");
14
15
  /** Read and parse settings.json. Not cached - always reads fresh to respect runtime changes. */
@@ -185,6 +186,31 @@ function normalizeWriteGateSites(raw) {
185
186
  }
186
187
  return sites;
187
188
  }
189
+ /**
190
+ * Pure resolver for the braid.memory.reservedProvenance block. Absent or
191
+ * malformed fields fall back to RESERVED_PROVENANCE_DEFAULTS (partition off),
192
+ * so a typo cannot start holding slots for a class nobody named. `slots` is
193
+ * clamped to MAX_ENTRIES: a reservation at or above the cap would leave the
194
+ * general pool no room at all. Kept pure so the merge is testable without
195
+ * touching live settings.json.
196
+ */
197
+ export function resolveReservedProvenance(raw) {
198
+ const prefixValue = typeof raw?.prefix === "string" ? raw.prefix.trim() : "";
199
+ const prefix = prefixValue || RESERVED_PROVENANCE_DEFAULTS.prefix;
200
+ const slotsValue = raw?.slots;
201
+ const slots = typeof slotsValue === "number" && Number.isInteger(slotsValue) && slotsValue >= 0
202
+ ? Math.min(slotsValue, MAX_ENTRIES)
203
+ : RESERVED_PROVENANCE_DEFAULTS.slots;
204
+ return { prefix, slots };
205
+ }
206
+ /**
207
+ * Read braid.memory.reservedProvenance from settings.json, fresh on every call
208
+ * (no caching), like the other readers. Default: no partition.
209
+ */
210
+ export function getMemoryReservedProvenance() {
211
+ const settings = readSettings();
212
+ return resolveReservedProvenance(settings.braid?.memory?.reservedProvenance);
213
+ }
188
214
  /**
189
215
  * The owner time zone for all braid-facing time rendering (lib/utils/local-time.ts).
190
216
  * braid.timezone in settings.json when set to a non-empty string; otherwise
@@ -213,6 +239,21 @@ export function resolveSkillsRankingMode(raw) {
213
239
  export function getSkillsRankingMode() {
214
240
  return resolveSkillsRankingMode(readSettings().braid?.skills?.ranking);
215
241
  }
242
+ export const SKILLS_INFORM_DEFAULT = "off";
243
+ /**
244
+ * Resolve the inform mode from a raw setting value. Unknown or malformed
245
+ * values fall back to the default: a typo must never turn a whisper on. Pure.
246
+ */
247
+ export function resolveSkillsInformMode(raw) {
248
+ const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
249
+ return value === "inform" || value === "off"
250
+ ? value
251
+ : SKILLS_INFORM_DEFAULT;
252
+ }
253
+ /** Read braid.skills.inform from settings.json (default: "off"). */
254
+ export function getSkillsInformMode() {
255
+ return resolveSkillsInformMode(readSettings().braid?.skills?.inform);
256
+ }
216
257
  // ── stale toolResult offload (braid.context.staleToolResultOffload) ────
217
258
  /**
218
259
  * Sane defaults for the optional staleToolResultOffload params (defined next