dsh-awesome-optimizer 3.1.0 → 3.3.0

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.
@@ -6,6 +6,11 @@ import { ToolExecutionPipeline } from '@deepseek-ai/dsh-tools/pipeline';
6
6
  import { normalizePath } from './runtime-policy.js';
7
7
  import { buildEditFailureHint } from './edit-recovery.js';
8
8
  import { truncateLongLines } from './read-guard.js';
9
+ import { selectReadWindows } from './find-read-ranking.js';
10
+ import {
11
+ FindOutput, appendSearchNotices, searchStatus, splitWindows,
12
+ appendSlice, appendMatchListing, finishFindOutput
13
+ } from './find-read-output.js';
9
14
 
10
15
  export const FIND_AND_READ_TOOL = 'find_and_read';
11
16
  export const EDIT_BATCH_TOOL = 'edit_batch';
@@ -20,6 +25,9 @@ export const CompositeToolsConfig = z.object({
20
25
  defaultContextLines: z.number().step(1).min(0).max(25).default(5),
21
26
  maxFiles: z.number().step(1).min(1).max(12).default(5),
22
27
  maxWindows: z.number().step(1).min(1).max(25).default(10),
28
+ maxWindowLines: z.number().step(1).min(1).max(1000).default(120),
29
+ maxReadLines: z.number().step(1).min(1).max(10000).default(600),
30
+ readConcurrency: z.number().step(1).min(1).max(8).default(3),
23
31
  maxBatchEdits: z.number().step(1).min(1).max(25).default(10),
24
32
  maxLineChars: z.number().step(1).min(100).max(50000).default(1500),
25
33
  maxTotalBytes: z.number().step(1).min(512).max(1024 * 1024).default(24576),
@@ -31,10 +39,23 @@ export const CompositeToolsConfig = z.object({
31
39
  * or structured `meta.matches` into flat `{ path, lineNumber, line }` records.
32
40
  */
33
41
  export function parseGrepOutput(text, meta) {
34
- if (meta && Array.isArray(meta.matches)) {
35
- return meta.matches
36
- .filter(m => m && typeof m.path === 'string' && Number.isInteger(m.lineNumber) && m.lineNumber >= 1)
37
- .map(m => ({ path: m.path, lineNumber: m.lineNumber, line: String(m.line ?? '') }));
42
+ if (meta && (Array.isArray(meta.matches) || Array.isArray(meta.files))) {
43
+ const structured = [
44
+ ...(Array.isArray(meta.matches) ? meta.matches : []),
45
+ ...(Array.isArray(meta.files) ? meta.files.flatMap(file =>
46
+ Array.isArray(file?.matches) ? file.matches.map(match => ({ ...match, path: file.path })) : []
47
+ ) : [])
48
+ ];
49
+ // Meta has its own retention cap; union with rendered text rather than hiding text-only hits.
50
+ const matches = [...structured, ...parseGrepOutput(text)];
51
+ const seen = new Set();
52
+ return matches.filter(m => {
53
+ if (!m || typeof m.path !== 'string' || !Number.isInteger(m.lineNumber) || m.lineNumber < 1) return false;
54
+ const key = JSON.stringify([m.path, m.lineNumber]);
55
+ if (seen.has(key)) return false;
56
+ seen.add(key);
57
+ return true;
58
+ }).map(m => ({ path: m.path, lineNumber: m.lineNumber, line: String(m.line ?? '') }));
38
59
  }
39
60
  if (typeof text !== 'string' || !text.trim() || /^No matches found\b/i.test(text.trim())) {
40
61
  return [];
@@ -113,20 +134,6 @@ function stripReadEnvelope(rawText) {
113
134
  return text.trimEnd();
114
135
  }
115
136
 
116
- function formatSliceText(sliceText, matchedLines, maxLineChars) {
117
- const matchedSet = new Set(matchedLines);
118
- const capped = truncateLongLines(sliceText, maxLineChars);
119
- return capped
120
- .split('\n')
121
- .map(line => {
122
- const m = line.match(/^(\d+):\s?(.*)$/);
123
- if (!m) return ` ${line}`;
124
- const lineNum = Number(m[1]);
125
- return `${matchedSet.has(lineNum) ? '>' : ' '} ${line}`;
126
- })
127
- .join('\n');
128
- }
129
-
130
137
  function countOccurrences(haystack, needle) {
131
138
  if (!needle) return 0;
132
139
  let count = 0;
@@ -221,6 +228,8 @@ function emptyStats() {
221
228
  findExecuted: 0,
222
229
  findPatternsSearched: 0,
223
230
  findWindowsRead: 0,
231
+ findLinesRequested: 0,
232
+ findReadBatches: 0,
224
233
  findFilesMatched: 0,
225
234
  editBatchesExecuted: 0,
226
235
  editsRequested: 0,
@@ -352,7 +361,7 @@ export function applyCompositeTools(ctx, rawConfig = {}) {
352
361
  const rawPatterns = [
353
362
  ...(typeof args?.pattern === 'string' ? [args.pattern] : []),
354
363
  ...(Array.isArray(args?.patterns) ? args.patterns : [])
355
- ].map(p => (typeof p === 'string' ? p.trim() : '')).filter(Boolean);
364
+ ].filter(p => typeof p === 'string' && p.length > 0);
356
365
 
357
366
  const uniquePatterns = [...new Set(rawPatterns)];
358
367
  if (uniquePatterns.length === 0) {
@@ -396,45 +405,41 @@ export function applyCompositeTools(ctx, rawConfig = {}) {
396
405
  return { pattern, result };
397
406
  }));
398
407
 
399
- const allGrepErrored = grepRuns.every(r => r.result.isError);
400
- if (allGrepErrored) {
401
- const errors = grepRuns.map(({ pattern, result }) => {
402
- const msg = result.error?.message
403
- ?? result.content?.filter(b => b.type === 'text').map(b => b.text).join('\n')
404
- ?? 'grep failed';
405
- return `[${pattern}] ${msg}`;
406
- }).join('\n');
407
- throw new HarnessError(errors, 'FIND_AND_READ_GREP_FAILED');
408
+ const runs = grepRuns.map(({ pattern, result }, index) => {
409
+ const text = (result.content ?? []).filter(b => b.type === 'text').map(b => b.text).join('\n');
410
+ const parsed = result.isError ? [] : parseGrepOutput(text, result.meta);
411
+ return { pattern, result, index, text, parsed, status: searchStatus(text, result.meta, parsed.length) };
412
+ });
413
+ const output = new FindOutput(config.maxTotalBytes);
414
+ appendSearchNotices(output, runs);
415
+ if (runs.every(run => run.result.isError)) {
416
+ throw new HarnessError(output.finish('All grep patterns failed.'), 'FIND_AND_READ_GREP_FAILED');
408
417
  }
409
418
 
410
419
  // Aggregate and deduplicate matches by normalized file path + line number
411
420
  const filesMap = new Map();
412
- const grepWarnings = [];
413
421
  let firstSeenOrder = 0;
414
422
 
415
- for (const { pattern, result } of grepRuns) {
416
- if (result.isError) {
417
- const msg = result.error?.message
418
- ?? result.content?.filter(b => b.type === 'text').map(b => b.text).join('\n')
419
- ?? 'grep error';
420
- grepWarnings.push(`Pattern "${pattern}" failed: ${msg}`);
421
- continue;
422
- }
423
- const text = (result.content ?? []).filter(b => b.type === 'text').map(b => b.text).join('\n');
424
- const parsed = parseGrepOutput(text, result.meta);
423
+ for (const { pattern, result, parsed } of runs) {
424
+ if (result.isError) continue;
425
425
  for (const m of parsed) {
426
426
  const norm = normalizePath(m.path, cwd) || m.path;
427
427
  let entry = filesMap.get(norm);
428
428
  if (!entry) {
429
429
  entry = {
430
430
  displayPath: m.path,
431
+ sortPath: norm,
432
+ linePatterns: new Map(),
431
433
  order: firstSeenOrder++,
432
434
  patterns: new Set(),
433
- lines: new Map()
435
+ lines: new Map(),
436
+ shown: new Set()
434
437
  };
435
438
  filesMap.set(norm, entry);
436
439
  }
437
440
  entry.patterns.add(pattern);
441
+ if (!entry.linePatterns.has(m.lineNumber)) entry.linePatterns.set(m.lineNumber, new Set());
442
+ entry.linePatterns.get(m.lineNumber).add(pattern);
438
443
  if (!entry.lines.has(m.lineNumber)) {
439
444
  entry.lines.set(m.lineNumber, m.line);
440
445
  }
@@ -442,8 +447,9 @@ export function applyCompositeTools(ctx, rawConfig = {}) {
442
447
  }
443
448
 
444
449
  if (filesMap.size === 0) {
445
- const base = `No matches found for pattern(s): ${uniquePatterns.join(', ')}`;
446
- return grepWarnings.length > 0 ? `${base}\n\n${grepWarnings.join('\n')}` : base;
450
+ const incomplete = runs.some(run => run.result.isError || run.status.truncated);
451
+ output.appendClipped(`${incomplete ? 'No retained matches available' : 'No matches found'} for pattern(s): ${uniquePatterns.join(', ')}`);
452
+ return output.finish(output.reduced ? '[Query text truncated to fit byte budget.]' : '');
447
453
  }
448
454
 
449
455
  if (state) {
@@ -457,117 +463,55 @@ export function applyCompositeTools(ctx, rawConfig = {}) {
457
463
  || (a.order - b.order)
458
464
  );
459
465
 
466
+ output.append(`Found retained matches across ${filesMap.size} file(s):`);
460
467
  const canRead = contextLines > 0 && ctx.tools.get('read', exec.agent) !== undefined;
461
468
  if (!canRead) {
462
- const sections = [];
463
- let usedBytes = 0;
464
- let omitted = 0;
465
- for (const file of rankedFiles) {
466
- const rows = [...file.lines.entries()]
467
- .sort((a, b) => a[0] - b[0])
468
- .map(([ln, lineText]) => ` ${ln}: ${truncateLongLines(lineText, config.maxLineChars)}`);
469
- const block = `=== ${file.displayPath} (${file.lines.size} matches) ===\n${rows.join('\n')}`;
470
- const bLen = Buffer.byteLength(block, 'utf8') + 2;
471
- if (usedBytes + bLen <= config.maxTotalBytes) {
472
- sections.push(block);
473
- usedBytes += bLen;
474
- } else {
475
- omitted++;
476
- }
477
- }
478
- if (omitted > 0) {
479
- sections.push(`[find_and_read budget: omitted ${omitted} additional matched file(s) to stay within maxTotalBytes=${config.maxTotalBytes}]`);
480
- }
481
- if (grepWarnings.length > 0) sections.push(grepWarnings.join('\n'));
482
- return sections.join('\n\n');
469
+ appendMatchListing(output, rankedFiles, config.maxLineChars);
470
+ return finishFindOutput(output, rankedFiles);
483
471
  }
484
472
 
485
- // Build merged windows per top file and select round-robin up to maxWindows
486
- const selectedFiles = rankedFiles.slice(0, maxFiles);
487
- const fileWindows = selectedFiles.map(file => ({
488
- file,
489
- windows: mergeMatchWindows([...file.lines.keys()], contextLines),
490
- cursor: 0
491
- }));
492
-
493
- const chosenTasks = [];
494
- let progress = true;
495
- while (chosenTasks.length < maxWindows && progress) {
496
- progress = false;
497
- for (const fw of fileWindows) {
498
- if (chosenTasks.length >= maxWindows) break;
499
- if (fw.cursor < fw.windows.length) {
500
- chosenTasks.push({ file: fw.file, win: fw.windows[fw.cursor++] });
501
- progress = true;
502
- }
503
- }
504
- }
505
-
506
- if (state) {
507
- state.findWindowsRead += chosenTasks.length;
508
- }
473
+ const candidates = rankedFiles.flatMap(file =>
474
+ splitWindows(mergeMatchWindows([...file.lines.keys()], contextLines), config.maxWindowLines)
475
+ .map(win => ({ file, win }))
476
+ );
477
+ const chosenTasks = selectReadWindows(candidates, { maxFiles, maxWindows, maxReadLines: config.maxReadLines });
509
478
 
510
- const readResults = await Promise.all(chosenTasks.map(async (task, idx) => {
479
+ // Complete a bounded batch before spending more of the output or I/O budget.
480
+ let cursor = 0;
481
+ while (cursor < chosenTasks.length && output.remaining() >= 128) {
511
482
  exec.signal.throwIfAborted();
512
- const limit = task.win.end - task.win.start + 1;
513
- const result = await dispatchSubCall(
514
- exec,
515
- 'read',
516
- { file_path: task.file.displayPath, offset: task.win.start, limit },
517
- `${exec.callId}:find-read-${idx}`
518
- );
519
- return { ...task, result };
520
- }));
521
-
522
- const renderedBlocks = [];
523
- const overflowIndex = [];
524
- let usedBytes = 0;
525
-
526
- for (const item of readResults) {
527
- let block;
528
- if (item.result.isError) {
529
- const msg = item.result.error?.message
530
- ?? item.result.content?.filter(b => b.type === 'text').map(b => b.text).join('\n')
531
- ?? 'Read failed';
532
- block = `=== ${item.file.displayPath}:${item.win.start}-${item.win.end} [READ ERROR] ===\n${msg}`;
533
- } else {
534
- const rawText = (item.result.content ?? []).filter(b => b.type === 'text').map(b => b.text).join('\n');
535
- const cleanText = stripReadEnvelope(rawText);
536
- const formatted = formatSliceText(cleanText, item.win.matchedLines, config.maxLineChars);
537
- block = `=== ${item.file.displayPath}:${item.win.start}-${item.win.end} ===\n${formatted}`;
483
+ const slots = Math.min(config.readConcurrency, Math.max(1, Math.floor(output.remaining() / 1024)));
484
+ const batch = chosenTasks.slice(cursor, cursor + slots);
485
+ const previousBytes = output.bytes;
486
+ if (state) {
487
+ state.findReadBatches++;
488
+ state.findWindowsRead += batch.length;
489
+ state.findLinesRequested += batch.reduce((sum, task) => sum + task.win.end - task.win.start + 1, 0);
538
490
  }
539
-
540
- const bytes = Buffer.byteLength(block, 'utf8') + 2;
541
- if (renderedBlocks.length === 0 || usedBytes + bytes <= config.maxTotalBytes) {
542
- renderedBlocks.push(block);
543
- usedBytes += bytes;
544
- } else {
545
- overflowIndex.push(`${item.file.displayPath}: L${item.win.matchedLines.join(', L')}`);
546
- }
547
- }
548
-
549
- // Index any windows/files skipped due to maxWindows or maxFiles
550
- for (const fw of fileWindows) {
551
- for (let i = fw.cursor; i < fw.windows.length; i++) {
552
- overflowIndex.push(`${fw.file.displayPath}: L${fw.windows[i].matchedLines.join(', L')}`);
491
+ const readResults = await Promise.all(batch.map(async (task, index) => {
492
+ exec.signal.throwIfAborted();
493
+ const result = await dispatchSubCall(
494
+ exec, 'read',
495
+ { file_path: task.file.displayPath, offset: task.win.start, limit: task.win.end - task.win.start + 1 },
496
+ `${exec.callId}:find-read-${cursor + index}`
497
+ );
498
+ return { ...task, result };
499
+ }));
500
+ exec.signal.throwIfAborted();
501
+ for (const item of readResults) {
502
+ if (item.result.isError) {
503
+ const message = item.result.error?.message
504
+ ?? (item.result.content ?? []).filter(b => b.type === 'text').map(b => b.text).join('\n');
505
+ output.appendClipped(`=== ${item.file.displayPath}:${item.win.start}-${item.win.end} [READ ERROR] ===\n${message}`);
506
+ } else {
507
+ const rawText = (item.result.content ?? []).filter(b => b.type === 'text').map(b => b.text).join('\n');
508
+ appendSlice(output, item, stripReadEnvelope(rawText), config.maxLineChars);
509
+ }
553
510
  }
511
+ cursor += batch.length;
512
+ if (output.bytes === previousBytes) break;
554
513
  }
555
- for (let i = maxFiles; i < rankedFiles.length; i++) {
556
- const f = rankedFiles[i];
557
- const lineList = [...f.lines.keys()].sort((a, b) => a - b).slice(0, 6);
558
- const suffix = f.lines.size > 6 ? `, ... (${f.lines.size} total)` : '';
559
- overflowIndex.push(`${f.displayPath}: L${lineList.join(', L')}${suffix}`);
560
- }
561
-
562
- const header = `Found matches across ${filesMap.size} file(s) (showing ${renderedBlocks.length} merged slice(s)):`;
563
- const parts = [header, ...renderedBlocks];
564
- if (overflowIndex.length > 0) {
565
- parts.push(`--- Additional matches (index only) ---\n${overflowIndex.join('\n')}`);
566
- }
567
- if (grepWarnings.length > 0) {
568
- parts.push(grepWarnings.join('\n'));
569
- }
570
- return parts.join('\n\n');
514
+ return finishFindOutput(output, rankedFiles);
571
515
  }
572
516
  }, { when: ({ agent }) => ctx.tools.get('grep', agent) !== undefined });
573
517
  }
@@ -668,6 +612,10 @@ export function applyCompositeTools(ctx, rawConfig = {}) {
668
612
  invalidEntries.set(index, 'Invalid edit entry: file_path, old_string, and new_string must be strings.');
669
613
  continue;
670
614
  }
615
+ if (!item.old_string || item.old_string === item.new_string) {
616
+ invalidEntries.set(index, 'Invalid edit entry: old_string must be non-empty and differ from new_string.');
617
+ continue;
618
+ }
671
619
  const pathKey = normalizePath(item.file_path, cwd) || item.file_path.trim();
672
620
  if (!editsByPath.has(pathKey)) editsByPath.set(pathKey, []);
673
621
  editsByPath.get(pathKey).push({ index, item });
@@ -15,7 +15,7 @@ export const GUIDANCE = [
15
15
  'This efficiency guidance NEVER overrides the user, correctness, permission checks, required verification, or cancellation.'
16
16
  ].join('\n');
17
17
 
18
- export const REMINDER = 'Accelerate execution: batch remaining actions and conclude if criteria are met; NEVER omit verification.';
18
+ export const REMINDER = 'Batch remaining actions; conclude only if criteria are met; NEVER omit verification.';
19
19
 
20
20
  export const ConvergenceConfig = z.object({
21
21
  enabled: z.boolean().default(true),
@@ -146,7 +146,7 @@ export function applyConvergence(ctx, raw = {}) {
146
146
  source: {
147
147
  kind: SOURCE,
148
148
  form: 'notice',
149
- summary: 'Accelerate execution and conclude when criteria are met.'
149
+ summary: 'Batch remaining actions; conclude only if criteria are met.'
150
150
  }
151
151
  });
152
152
  return { ...decision, messages: [...decision.messages, reminder] };
@@ -0,0 +1,175 @@
1
+ import { Buffer } from 'node:buffer';
2
+ import { truncateLongLines } from './read-guard.js';
3
+
4
+ const byteLength = text => Buffer.byteLength(text, 'utf8');
5
+
6
+ export function clipUtf8(text, maxBytes, suffix = ' ... [truncated]') {
7
+ if (byteLength(text) <= maxBytes) return text;
8
+ if (maxBytes <= byteLength(suffix)) return '';
9
+ const buffer = Buffer.from(text, 'utf8');
10
+ let end = maxBytes - byteLength(suffix);
11
+ while (end > 0 && (buffer[end] & 0xc0) === 0x80) end--;
12
+ return buffer.subarray(0, end).toString('utf8') + suffix;
13
+ }
14
+
15
+ /** Reserve room for recovery indexes and a final omission notice. */
16
+ export class FindOutput {
17
+ constructor(maxBytes) {
18
+ this.maxBytes = maxBytes;
19
+ this.reserve = Math.min(2048, Math.floor(maxBytes / 3));
20
+ this.parts = [];
21
+ this.bytes = 0;
22
+ this.reduced = false;
23
+ }
24
+
25
+ remaining() {
26
+ return Math.max(0, this.maxBytes - this.reserve - this.bytes - (this.parts.length ? 2 : 0));
27
+ }
28
+
29
+ append(text) {
30
+ if (!text) return true;
31
+ if (byteLength(text) > this.remaining()) return false;
32
+ this.bytes += byteLength(text) + (this.parts.length ? 2 : 0);
33
+ this.parts.push(text);
34
+ return true;
35
+ }
36
+
37
+ appendClipped(text, cap = this.remaining()) {
38
+ const clipped = clipUtf8(text, Math.min(cap, this.remaining()));
39
+ if (clipped !== text) this.reduced = true;
40
+ return this.append(clipped);
41
+ }
42
+
43
+ finish(note = '') {
44
+ this.reserve = 0;
45
+ if (note) this.appendClipped(note);
46
+ return this.parts.join('\n\n');
47
+ }
48
+ }
49
+
50
+ export function searchStatus(text, meta, retainedCount) {
51
+ const header = text.match(/^Found (\d+) of (\d+) matches\s*$/m);
52
+ const recovery = text.match(/^\(?Full grep result stored at:[^\r\n]+/m)?.[0]?.replace(/\)$/, '')
53
+ ?? text.match(/^\(?The complete result could not be saved[^\r\n]+/m)?.[0]?.replace(/\)$/, '')
54
+ ?? '';
55
+ const total = header ? Number(header[2]) : (Number.isFinite(meta?.total) ? meta.total : undefined);
56
+ const truncated = Boolean(header || meta?.truncated || (total !== undefined && total > retainedCount));
57
+ return { truncated, total, retained: header ? Number(header[1]) : retainedCount, recovery };
58
+ }
59
+
60
+ export function appendSearchNotices(output, runs) {
61
+ const incomplete = runs.filter(run => run.result.isError || run.status.truncated);
62
+ if (!incomplete.length) return;
63
+ const summary = incomplete.map(run => `#${run.index + 1} ${run.result.isError ? 'failed' : 'truncated'}`).join(', ');
64
+ output.append(`Search incomplete: ${summary}. Counts below cover retained matches only.`);
65
+ const cap = Math.floor(Math.min(4096, output.remaining() / 2) / incomplete.length);
66
+ for (const run of incomplete) {
67
+ let detail;
68
+ if (run.result.isError) {
69
+ const message = run.result.error?.message || run.text || 'grep failed';
70
+ detail = `Pattern #${run.index + 1} failed: ${message}`;
71
+ } else {
72
+ const counts = run.status.total === undefined ? 'partial results' : `${run.status.retained} of ${run.status.total} matches`;
73
+ const recovery = run.status.recovery.includes('could not be saved')
74
+ ? 'spill could not be saved; narrow search.'
75
+ : (run.status.recovery || 'narrow search.');
76
+ detail = `#${run.index + 1}: ${counts}; ${recovery}`;
77
+ }
78
+ output.appendClipped(detail, cap);
79
+ }
80
+ }
81
+
82
+ /** Split chained merges before dispatch; each returned window contains a hit. */
83
+ export function splitWindows(windows, maxLines) {
84
+ const bounded = [];
85
+ for (const window of windows) {
86
+ for (let start = window.start; start <= window.end; start += maxLines) {
87
+ const end = Math.min(window.end, start + maxLines - 1);
88
+ const matchedLines = window.matchedLines.filter(line => line >= start && line <= end);
89
+ if (matchedLines.length) bounded.push({ start, end, matchedLines });
90
+ }
91
+ }
92
+ return bounded;
93
+ }
94
+
95
+ export function appendSlice(output, task, cleanText, maxLineChars) {
96
+ const matched = new Set(task.win.matchedLines);
97
+ const rows = truncateLongLines(cleanText, maxLineChars).split('\n').map(text => {
98
+ const line = text.match(/^(\d+):\s?(.*)$/);
99
+ const number = line ? Number(line[1]) : undefined;
100
+ return { number, text: `${matched.has(number) ? '>' : ' '} ${text}` };
101
+ });
102
+ const header = `=== ${task.file.displayPath}:${task.win.start}-${task.win.end} ===`;
103
+ const full = `${header}\n${rows.map(row => row.text).join('\n')}`;
104
+ if (output.append(full)) {
105
+ for (const row of rows) if (matched.has(row.number)) task.file.shown.add(row.number);
106
+ return;
107
+ }
108
+
109
+ output.reduced = true;
110
+ const note = ' ... [context omitted to fit byte budget]';
111
+ let block = header;
112
+ const shown = [];
113
+ for (const row of rows.filter(row => matched.has(row.number))) {
114
+ const available = output.remaining() - byteLength(block) - byteLength(note) - 2;
115
+ const text = clipUtf8(row.text, available);
116
+ if (!text || !text.startsWith(`> ${row.number}:`)) break;
117
+ block += `\n${text}`;
118
+ shown.push(row.number);
119
+ if (text !== row.text) break;
120
+ }
121
+ if (shown.length && output.append(`${block}\n${note}`)) {
122
+ for (const line of shown) task.file.shown.add(line);
123
+ }
124
+ }
125
+
126
+ export function appendMatchListing(output, files, maxLineChars) {
127
+ for (const file of files) {
128
+ const header = `=== ${file.displayPath} (${file.lines.size} matches) ===`;
129
+ let block = header;
130
+ const shown = [];
131
+ for (const [line, text] of [...file.lines.entries()].sort((a, b) => a[0] - b[0])) {
132
+ const row = ` ${line}: ${truncateLongLines(text, maxLineChars)}`;
133
+ const available = output.remaining() - byteLength(block) - 1;
134
+ const clipped = clipUtf8(row, available);
135
+ if (!clipped || !clipped.startsWith(` ${line}:`)) break;
136
+ block += `\n${clipped}`;
137
+ shown.push(line);
138
+ if (clipped !== row) { output.reduced = true; break; }
139
+ }
140
+ if (shown.length && output.append(block)) {
141
+ for (const line of shown) file.shown.add(line);
142
+ }
143
+ }
144
+ }
145
+
146
+ function compactLines(lines) {
147
+ const runs = [];
148
+ for (const line of lines) {
149
+ const last = runs.at(-1);
150
+ if (last && last[1] + 1 === line) last[1] = line;
151
+ else runs.push([line, line]);
152
+ }
153
+ const text = runs.slice(0, 6).map(([start, end]) => start === end ? `L${start}` : `L${start}-${end}`).join(', ');
154
+ return `${text}${runs.length > 6 ? ', ...' : ''}`;
155
+ }
156
+
157
+ export function finishFindOutput(output, files) {
158
+ output.reserve = Math.min(128, Math.floor(output.maxBytes / 5));
159
+ let missing = 0;
160
+ let unindexed = 0;
161
+ let hasIndex = false;
162
+ for (const file of files) {
163
+ const lines = [...file.lines.keys()].filter(line => !file.shown.has(line)).sort((a, b) => a - b);
164
+ if (!lines.length) continue;
165
+ missing += lines.length;
166
+ const row = `${file.displayPath}: ${compactLines(lines)}`;
167
+ const block = `${hasIndex ? '' : '--- Additional matches (index only) ---\n'}${row}`;
168
+ if (output.append(block)) hasIndex = true;
169
+ else unindexed++;
170
+ }
171
+ const note = missing || output.reduced
172
+ ? `[find_and_read: ${missing} code match(es), ${unindexed} file index(es) omitted; narrow search or read by line.]`
173
+ : '';
174
+ return output.finish(note);
175
+ }
@@ -0,0 +1,63 @@
1
+ /** Choose bounded windows by marginal pattern coverage, then diverse information per line. */
2
+ export function selectReadWindows(candidates, { maxFiles, maxWindows, maxReadLines }) {
3
+ const pending = [...candidates];
4
+ const chosen = [];
5
+ const coverage = new Map();
6
+ const files = new Set();
7
+ let lines = 0;
8
+ while (pending.length && chosen.length < maxWindows && lines < maxReadLines) {
9
+ let best;
10
+ for (let index = 0; index < pending.length; index++) {
11
+ const candidate = pending[index];
12
+ if (!files.has(candidate.file) && files.size >= maxFiles) continue;
13
+ const win = fitWindow(candidate, maxReadLines - lines, coverage);
14
+ const patterns = patternsFor(candidate.file, win.matchedLines);
15
+ const gain = [...patterns].filter(pattern => !coverage.has(pattern)).length;
16
+ const value = [...patterns].reduce((sum, pattern) => sum + 1 / (1 + (coverage.get(pattern) ?? 0)), 0);
17
+ const cost = win.end - win.start + 1;
18
+ const score = [gain, value / Math.sqrt(cost), files.has(candidate.file) ? 0 : 1, Math.min(10, win.matchedLines.length) / cost];
19
+ const contender = { index, file: candidate.file, win, patterns, score };
20
+ if (!best || compare(contender, best) < 0) best = contender;
21
+ }
22
+ if (!best) break;
23
+ pending.splice(best.index, 1);
24
+ chosen.push({ file: best.file, win: best.win });
25
+ files.add(best.file);
26
+ lines += best.win.end - best.win.start + 1;
27
+ for (const pattern of best.patterns) coverage.set(pattern, (coverage.get(pattern) ?? 0) + 1);
28
+ }
29
+ return chosen;
30
+ }
31
+
32
+ function compare(a, b) {
33
+ for (let i = 0; i < a.score.length; i++) {
34
+ if (a.score[i] !== b.score[i]) return b.score[i] - a.score[i];
35
+ }
36
+ const pathA = a.file.sortPath ?? a.file.displayPath;
37
+ const pathB = b.file.sortPath ?? b.file.displayPath;
38
+ return (pathA < pathB ? -1 : pathA > pathB ? 1 : 0) || a.win.start - b.win.start;
39
+ }
40
+
41
+ function patternsFor(file, lines) {
42
+ const patterns = new Set();
43
+ for (const line of lines) for (const pattern of file.linePatterns.get(line) ?? []) patterns.add(pattern);
44
+ return patterns;
45
+ }
46
+
47
+ function fitWindow({ file, win }, remaining, coverage) {
48
+ if (win.end - win.start + 1 <= remaining) return win;
49
+ // A small final line budget must retain the most informative hits, not just the first hit.
50
+ let best;
51
+ for (const line of win.matchedLines) {
52
+ const start = Math.max(win.start, Math.min(line, win.end - remaining + 1));
53
+ const end = start + remaining - 1;
54
+ const matchedLines = win.matchedLines.filter(hit => hit >= start && hit <= end);
55
+ const patterns = patternsFor(file, matchedLines);
56
+ const gain = [...patterns].filter(pattern => !coverage.has(pattern)).length;
57
+ const value = [...patterns].reduce((sum, pattern) => sum + 1 / (1 + (coverage.get(pattern) ?? 0)), 0);
58
+ if (!best || gain > best.gain || (gain === best.gain && value > best.value)) {
59
+ best = { start, end, matchedLines, gain, value };
60
+ }
61
+ }
62
+ return best;
63
+ }
@@ -0,0 +1,36 @@
1
+ /** Bounded LRU of parsed symbols, scoped by session and filesystem backend. */
2
+ export class OutlineCache {
3
+ constructor(maxEntries, maxBytes) {
4
+ this.maxEntries = maxEntries;
5
+ this.maxBytes = maxBytes;
6
+ this.entries = new Map();
7
+ this.bytes = 0;
8
+ this.generation = 0;
9
+ }
10
+
11
+ get(key, version) {
12
+ const entry = this.entries.get(key);
13
+ if (!entry) return null;
14
+ if (entry.version !== version) { this.delete(key); return null; }
15
+ this.entries.delete(key);
16
+ this.entries.set(key, entry);
17
+ return entry.value;
18
+ }
19
+
20
+ set(key, version, value) {
21
+ this.delete(key);
22
+ const bytes = Buffer.byteLength(JSON.stringify(value), 'utf8') + Buffer.byteLength(key, 'utf8') + Buffer.byteLength(version, 'utf8');
23
+ if (!this.maxEntries || bytes > this.maxBytes) return;
24
+ while (this.entries.size >= this.maxEntries || this.bytes + bytes > this.maxBytes) this.delete(this.entries.keys().next().value);
25
+ this.entries.set(key, { version, value, bytes });
26
+ this.bytes += bytes;
27
+ }
28
+
29
+ delete(key) {
30
+ const entry = this.entries.get(key);
31
+ if (entry) this.bytes -= entry.bytes;
32
+ this.entries.delete(key);
33
+ }
34
+
35
+ clear() { this.entries.clear(); this.bytes = 0; this.generation++; }
36
+ }
@@ -8,15 +8,43 @@ export interface ReadGuardOptions {
8
8
  maxOutlineEntries?: number;
9
9
  maxOutlineBytes?: number;
10
10
  maxInspectBytes?: number;
11
+ /** Parsed-outline LRU entries per session/backend; 0 disables caching. Default: 32. */
12
+ maxCacheEntries?: number;
13
+ /** Maximum serialized cache payload per session/backend. Default: 262144. */
14
+ maxCacheBytes?: number;
15
+ /** auto: parse TSX/JSX and known lexical gaps on demand; off disables the CLI. */
16
+ astOutline?: 'off' | 'auto' | 'always';
17
+ /** Executable name or absolute path; executed without a shell. Default: ast-grep. */
18
+ astGrepCommand?: string;
19
+ /** CLI deadline in milliseconds. Default: 750. */
20
+ astTimeoutMs?: number;
21
+ /** Maximum CLI stdout bytes. Default: 262144. */
22
+ astMaxOutputBytes?: number;
11
23
  }
12
24
 
13
25
  export interface ReadGuardStats {
14
26
  inspected: number;
15
27
  linesTruncated: number;
16
28
  outlinesInjected: number;
29
+ /** Per-turn enabled lookups with a valid identity/version after successful preflight. */
30
+ outlineCacheLookups: number;
31
+ outlineCacheHits: number;
32
+ /** Includes absent, stale, and evicted entries, even if subsequent parsing fails. */
33
+ outlineCacheMisses: number;
34
+ /** Successful preflights without caching: disabled, unversioned, or local-only backend. */
35
+ outlineCacheBypasses: number;
36
+ /** Mutation events clearing an existing session cache group, including in-flight work. */
37
+ outlineCacheInvalidations: number;
38
+ /** Hits / lookups in [0, 1]; null when no lookup occurred. */
39
+ outlineCacheHitRate: number | null;
40
+ astAttempts: number;
41
+ astSucceeded: number;
42
+ astFallbacks: number;
43
+ astTimeouts: number;
17
44
  }
18
45
 
19
46
  export interface ReadGuardService {
47
+ /** Detached per-turn snapshot; caches may survive turn boundaries. */
20
48
  getStats(session: unknown): ReadGuardStats;
21
49
  }
22
50