pi-braid 0.43.6 → 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 (62) hide show
  1. package/CHANGELOG.md +83 -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/applicability.d.ts +134 -0
  6. package/dist/extensions/core/skills-tool/applicability.js +161 -0
  7. package/dist/extensions/core/skills-tool/auto-inject.d.ts +31 -0
  8. package/dist/extensions/core/skills-tool/auto-inject.js +320 -1
  9. package/dist/extensions/core/skills-tool/index.js +83 -4
  10. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
  11. package/dist/extensions/core/skills-tool/loading-guidance.js +6 -2
  12. package/dist/extensions/core/skills-tool/session-records.d.ts +395 -8
  13. package/dist/extensions/core/skills-tool/session-records.js +645 -5
  14. package/dist/extensions/core/skills-tool/skill-families.d.ts +60 -0
  15. package/dist/extensions/core/skills-tool/skill-families.js +105 -0
  16. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
  17. package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
  18. package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
  19. package/dist/extensions/enforcement/verification-judge.js +28 -21
  20. package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
  21. package/dist/extensions/memory/session-recall/ask.js +376 -0
  22. package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
  23. package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
  24. package/dist/extensions/memory/session-recall/index.js +173 -21
  25. package/dist/extensions/memory/session-recall/search.d.ts +29 -0
  26. package/dist/extensions/memory/session-recall/search.js +42 -9
  27. package/dist/lib/ai/payload-hygiene.d.ts +3 -0
  28. package/dist/lib/ai/payload-hygiene.js +34 -2
  29. package/dist/lib/config/braid-paths.d.ts +4 -0
  30. package/dist/lib/config/braid-paths.js +6 -0
  31. package/dist/lib/config/braid-settings.d.ts +22 -0
  32. package/dist/lib/config/braid-settings.js +15 -0
  33. package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
  34. package/dist/lib/detection/tool-loop-detector.js +288 -180
  35. package/dist/lib/reasoning/dreamer.d.ts +2 -1
  36. package/dist/lib/reasoning/dreamer.js +12 -7
  37. package/docs/LOCAL_DEV.md +1 -1
  38. package/docs/SETUP.md +1 -0
  39. package/package.json +1 -1
  40. package/src/extensions/core/AGENTS.md +3 -1
  41. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  42. package/src/extensions/core/skills-tool/applicability.ts +220 -0
  43. package/src/extensions/core/skills-tool/auto-inject.ts +391 -0
  44. package/src/extensions/core/skills-tool/index.ts +96 -3
  45. package/src/extensions/core/skills-tool/loading-guidance.ts +6 -2
  46. package/src/extensions/core/skills-tool/session-records.ts +932 -5
  47. package/src/extensions/core/skills-tool/skill-families.ts +112 -0
  48. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
  49. package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
  50. package/src/extensions/enforcement/verification-judge.ts +32 -25
  51. package/src/extensions/memory/AGENTS.md +2 -2
  52. package/src/extensions/memory/session-recall/AGENTS.md +92 -18
  53. package/src/extensions/memory/session-recall/ask.ts +435 -0
  54. package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
  55. package/src/extensions/memory/session-recall/index.ts +202 -21
  56. package/src/extensions/memory/session-recall/search.ts +61 -10
  57. package/src/lib/ai/payload-hygiene.ts +47 -3
  58. package/src/lib/config/braid-paths.ts +7 -0
  59. package/src/lib/config/braid-settings.ts +42 -3
  60. package/src/lib/detection/AGENTS.md +8 -7
  61. package/src/lib/detection/tool-loop-detector.ts +339 -195
  62. 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");
@@ -169,6 +169,28 @@ export declare const SKILLS_RANKING_DEFAULT: SkillsRankingMode;
169
169
  export declare function resolveSkillsRankingMode(raw: unknown): SkillsRankingMode;
170
170
  /** Read braid.skills.ranking from settings.json (default: "keyword"). */
171
171
  export declare function getSkillsRankingMode(): SkillsRankingMode;
172
+ /**
173
+ * What the skills module does when a completed call lands in a tool family a
174
+ * visible skill's file declares with `governs:` and no read of that body is on
175
+ * the session record.
176
+ *
177
+ * off - nothing. The declaration still feeds the applied leg of the
178
+ * session record; it is never spoken about. The default, because a
179
+ * skill body already has a voice in the suggestion whisper and a
180
+ * second one must be asked for.
181
+ * inform - one steer line per session per skill: the file path and the
182
+ * obligation. It observes a call that already ran; it never
183
+ * refuses, delays or rewrites one.
184
+ */
185
+ export type SkillsInformMode = "off" | "inform";
186
+ export declare const SKILLS_INFORM_DEFAULT: SkillsInformMode;
187
+ /**
188
+ * Resolve the inform mode from a raw setting value. Unknown or malformed
189
+ * values fall back to the default: a typo must never turn a whisper on. Pure.
190
+ */
191
+ export declare function resolveSkillsInformMode(raw: unknown): SkillsInformMode;
192
+ /** Read braid.skills.inform from settings.json (default: "off"). */
193
+ export declare function getSkillsInformMode(): SkillsInformMode;
172
194
  /**
173
195
  * Sane defaults for the optional staleToolResultOffload params (defined next
174
196
  * to the schema per the design contract). Investigation suggests a size
@@ -213,6 +213,21 @@ export function resolveSkillsRankingMode(raw) {
213
213
  export function getSkillsRankingMode() {
214
214
  return resolveSkillsRankingMode(readSettings().braid?.skills?.ranking);
215
215
  }
216
+ export const SKILLS_INFORM_DEFAULT = "off";
217
+ /**
218
+ * Resolve the inform mode from a raw setting value. Unknown or malformed
219
+ * values fall back to the default: a typo must never turn a whisper on. Pure.
220
+ */
221
+ export function resolveSkillsInformMode(raw) {
222
+ const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
223
+ return value === "inform" || value === "off"
224
+ ? value
225
+ : SKILLS_INFORM_DEFAULT;
226
+ }
227
+ /** Read braid.skills.inform from settings.json (default: "off"). */
228
+ export function getSkillsInformMode() {
229
+ return resolveSkillsInformMode(readSettings().braid?.skills?.inform);
230
+ }
216
231
  // ── stale toolResult offload (braid.context.staleToolResultOffload) ────
217
232
  /**
218
233
  * Sane defaults for the optional staleToolResultOffload params (defined next