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.
- package/CHANGELOG.md +39 -0
- package/TOOLS.md +1 -1
- package/build-info.json +4 -4
- package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +21 -0
- package/dist/extensions/core/skills-tool/auto-inject.js +105 -1
- package/dist/extensions/core/skills-tool/index.js +20 -2
- package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
- package/dist/extensions/core/skills-tool/loading-guidance.js +4 -1
- package/dist/extensions/core/skills-tool/session-records.d.ts +107 -9
- package/dist/extensions/core/skills-tool/session-records.js +141 -5
- package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
- package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
- package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
- package/dist/extensions/enforcement/verification-judge.js +28 -21
- package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
- package/dist/extensions/memory/session-recall/ask.js +376 -0
- package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
- package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
- package/dist/extensions/memory/session-recall/index.js +173 -21
- package/dist/extensions/memory/session-recall/search.d.ts +29 -0
- package/dist/extensions/memory/session-recall/search.js +42 -9
- package/dist/lib/ai/payload-hygiene.d.ts +3 -0
- package/dist/lib/ai/payload-hygiene.js +34 -2
- package/dist/lib/config/braid-paths.d.ts +4 -0
- package/dist/lib/config/braid-paths.js +6 -0
- package/dist/lib/config/braid-settings.d.ts +22 -0
- package/dist/lib/config/braid-settings.js +15 -0
- package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
- package/dist/lib/detection/tool-loop-detector.js +288 -180
- package/dist/lib/reasoning/dreamer.d.ts +2 -1
- package/dist/lib/reasoning/dreamer.js +12 -7
- package/docs/LOCAL_DEV.md +1 -1
- package/docs/SETUP.md +1 -0
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +3 -2
- package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
- package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
- package/src/extensions/core/skills-tool/index.ts +21 -1
- package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
- package/src/extensions/core/skills-tool/session-records.ts +201 -9
- package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
- package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
- package/src/extensions/enforcement/verification-judge.ts +32 -25
- package/src/extensions/memory/AGENTS.md +2 -2
- package/src/extensions/memory/session-recall/AGENTS.md +92 -18
- package/src/extensions/memory/session-recall/ask.ts +435 -0
- package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
- package/src/extensions/memory/session-recall/index.ts +202 -21
- package/src/extensions/memory/session-recall/search.ts +61 -10
- package/src/lib/ai/payload-hygiene.ts +47 -3
- package/src/lib/config/braid-paths.ts +7 -0
- package/src/lib/config/braid-settings.ts +42 -3
- package/src/lib/detection/AGENTS.md +8 -7
- package/src/lib/detection/tool-loop-detector.ts +339 -195
- 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,
|
|
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
|
|
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
|
-
"
|
|
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
|
|
225
|
+
for (const { path: filePath } of fileMatches) {
|
|
157
226
|
const project = projectFromPath(filePath);
|
|
158
227
|
const date = dateFromPath(filePath);
|
|
159
|
-
const matchLines = await
|
|
228
|
+
const matchLines = await searchLineHits(params.query, filePath, MAX_SNIPPETS_PER_SESSION);
|
|
160
229
|
const snippets = [];
|
|
161
230
|
let archiveNote = "";
|
|
162
|
-
for (const
|
|
163
|
-
const parsed = extractLineMessages(
|
|
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}
|
|
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 =
|
|
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
|
|
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
|
-
|
|
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
|
|
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)
|
|
668
|
-
return results
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|