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