dsh-awesome-optimizer 2.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.
Files changed (42) hide show
  1. package/README.md +29 -35
  2. package/README.zh.md +29 -35
  3. package/cache-diagnostics.md +19 -0
  4. package/cordis.patch.yml +14 -2
  5. package/outline-benchmark.md +37 -0
  6. package/outline-benchmark.windows.json +184 -0
  7. package/package.json +15 -2
  8. package/scripts/benchmark-outline.mjs +100 -0
  9. package/scripts/benchmark.mjs +33 -26
  10. package/scripts/typecheck.mjs +37 -18
  11. package/src/ast-outline-config.yml +1 -0
  12. package/src/ast-outline.js +143 -0
  13. package/src/cache-diagnostics.js +218 -0
  14. package/src/code-lexical.js +131 -0
  15. package/src/code-outline.js +171 -0
  16. package/src/composite-tools.d.ts +36 -8
  17. package/src/composite-tools.js +538 -194
  18. package/src/convergence.js +3 -3
  19. package/src/custom-prompt.d.ts +7 -1
  20. package/src/custom-prompt.js +53 -18
  21. package/src/edit-recovery.d.ts +59 -0
  22. package/src/edit-recovery.js +524 -0
  23. package/src/failure-recovery.js +1 -1
  24. package/src/file-mutation-policy.js +0 -8
  25. package/src/find-read-output.js +175 -0
  26. package/src/find-read-ranking.js +63 -0
  27. package/src/index.d.ts +34 -2
  28. package/src/index.js +29 -5
  29. package/src/outline-cache.js +36 -0
  30. package/src/persistent-eval/daemon-pool.js +3 -2
  31. package/src/persistent-eval/index.d.ts +35 -8
  32. package/src/persistent-eval/index.js +51 -16
  33. package/src/persistent-eval/stdio-runner.js +209 -30
  34. package/src/persistent-eval/workers/node_worker.mjs +42 -31
  35. package/src/persistent-eval/workers/py_worker.py +47 -24
  36. package/src/prompt-linter.js +43 -26
  37. package/src/read-guard.d.ts +80 -0
  38. package/src/read-guard.js +336 -0
  39. package/src/runtime-policy.d.ts +1 -0
  40. package/src/runtime-policy.js +35 -15
  41. package/src/telemetry.d.ts +4 -0
  42. package/src/telemetry.js +27 -8
@@ -18,9 +18,9 @@ const CLI_REQUIRE_PATTERNS = [
18
18
  ];
19
19
 
20
20
  const WEAK_MODALS = [
21
- { pattern: /\b[Bb]ias(?:ed)?\s+toward\b/g, suggestion: 'Prioritize' },
22
- { pattern: /\b[Tt]ry\s+to\b/g, suggestion: 'Use direct imperative verbs' },
23
- { pattern: /\b[Pp]lease\b/g, suggestion: 'Omit conversational politeness filler' }
21
+ { pattern: /\b[Bb]ias(?:ed)?\s+toward\b/g, suggestion: 'Prioritize', fixable: true },
22
+ { pattern: /\b[Tt]ry\s+to\b/g, suggestion: 'Use direct imperative verbs', fixable: false },
23
+ { pattern: /\b[Pp]lease\b/g, suggestion: 'Omit conversational politeness filler', fixable: false }
24
24
  ];
25
25
 
26
26
  const LEGACY_JARGON = [
@@ -183,7 +183,7 @@ export function lintPrompt(content = '', options = {}) {
183
183
  severity: 'info',
184
184
  line: lineNum,
185
185
  message: `Weak modal or soft preference detected. Suggestion: ${wm.suggestion}.`,
186
- fixable: true
186
+ fixable: wm.fixable
187
187
  });
188
188
  wm.pattern.lastIndex = 0;
189
189
  }
@@ -270,34 +270,51 @@ export function lintPrompt(content = '', options = {}) {
270
270
  export function fixPrompt(content = '', options = {}) {
271
271
  if (typeof content !== 'string') return '';
272
272
 
273
- let fixed = content;
273
+ const activeTools = resolveActiveToolNames(options);
274
+ const lines = content.split('\n');
275
+ let inCodeBlock = false;
274
276
 
275
- // 1. Remove obsolete jargon / ralph
276
- fixed = fixed.replace(/\s*\(no workflows,\s*ralph(?:,\s*or delegation)?\)/gi, '');
277
- fixed = fixed.replace(/\b(?:no workflows,\s*)?ralph(?:,\s*or delegation)?\b/gi, '');
277
+ const fixedLines = lines.map((line) => {
278
+ if (line.trim().startsWith('```')) {
279
+ inCodeBlock = !inCodeBlock;
280
+ return line;
281
+ }
282
+ if (inCodeBlock) return line;
278
283
 
279
- // 2. Fix weak modals
280
- fixed = fixed.replace(/\bBias toward\b/g, 'Prioritize');
281
- fixed = fixed.replace(/\bbias toward\b/g, 'prioritize');
284
+ let fixedLine = line;
282
285
 
283
- // 3. Clean up tool phrasing if tools are not loaded in preset (or by default cleanup)
284
- const activeTools = resolveActiveToolNames(options);
285
- if (!activeTools || !activeTools.has('tool-pwsh')) {
286
- fixed = fixed.replace(/-\s*Shell:\s*harness\s*`bash`\s*only\s*\(`tool-pwsh`\s*disabled\)\.\s*Launch\s*`pwsh\.exe`\s*from\s*`bash`\s*when\s*needed\./gi,
287
- '- Shell: ONLY `bash`. Launch `pwsh.exe` from `bash` when needed.');
288
- }
286
+ // 1. Remove obsolete jargon / ralph
287
+ fixedLine = fixedLine.replace(/\s*\(no workflows,\s*ralph(?:,\s*or delegation)?\)/gi, '');
288
+ fixedLine = fixedLine.replace(/\b(?:no workflows,\s*)?ralph(?:,\s*or delegation)?\b/gi, '');
289
289
 
290
- if (!activeTools || (!activeTools.has('web-search-deepseek') && !activeTools.has('tool-web'))) {
291
- fixed = fixed.replace(/-\s*Web:\s*harness\s*`web-search-deepseek`,\s*`web-fetch-http`,\s*and\s*`tool-web`\s*are\s*disabled\.\s*Research\/fetch\s*STRICTLY\s*via\s*skills\s*\(([^)]+)\)\s*or\s*bash\s*CLIs\./gi,
292
- '- Web: Research/fetch STRICTLY via skills ($1) or bash CLIs.');
293
- }
290
+ // 2. Fix weak modals
291
+ fixedLine = fixedLine.replace(/\bBias toward\b/g, 'Prioritize');
292
+ fixedLine = fixedLine.replace(/\bbias toward\b/g, 'prioritize');
294
293
 
295
- // 4. Uppercase directive constraints
296
- for (const dc of DIRECTIVE_CASING) {
297
- fixed = fixed.replace(dc.pattern, dc.replacement);
298
- }
294
+ // 3. Clean up tool phrasing if tools are not loaded in preset (or by default cleanup)
295
+ if (!activeTools || !activeTools.has('tool-pwsh')) {
296
+ fixedLine = fixedLine.replace(
297
+ /-\s*Shell:\s*harness\s*`bash`\s*only\s*\(`tool-pwsh`\s*disabled\)\.\s*Launch\s*`pwsh\.exe`\s*from\s*`bash`\s*when\s*needed\./gi,
298
+ '- Shell: ONLY `bash`. Launch `pwsh.exe` from `bash` when needed.'
299
+ );
300
+ }
301
+
302
+ if (!activeTools || (!activeTools.has('web-search-deepseek') && !activeTools.has('tool-web'))) {
303
+ fixedLine = fixedLine.replace(
304
+ /-\s*Web:\s*harness\s*`web-search-deepseek`,\s*`web-fetch-http`,\s*and\s*`tool-web`\s*are\s*disabled\.\s*Research\/fetch\s*STRICTLY\s*via\s*skills\s*\(([^)]+)\)\s*or\s*bash\s*CLIs\./gi,
305
+ '- Web: Research/fetch STRICTLY via skills ($1) or bash CLIs.'
306
+ );
307
+ }
308
+
309
+ // 4. Uppercase directive constraints
310
+ for (const dc of DIRECTIVE_CASING) {
311
+ fixedLine = fixedLine.replace(dc.pattern, dc.replacement);
312
+ }
313
+
314
+ return fixedLine;
315
+ });
299
316
 
300
- return fixed;
317
+ return fixedLines.join('\n');
301
318
  }
302
319
 
303
320
  /**
@@ -0,0 +1,80 @@
1
+ import type { Context } from '@deepseek-ai/cordis';
2
+ import type z from '@deepseek-ai/schemastery';
3
+
4
+ export interface ReadGuardOptions {
5
+ enabled?: boolean;
6
+ maxLineChars?: number;
7
+ injectTailOutline?: boolean;
8
+ maxOutlineEntries?: number;
9
+ maxOutlineBytes?: number;
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;
23
+ }
24
+
25
+ export interface ReadGuardStats {
26
+ inspected: number;
27
+ linesTruncated: number;
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;
44
+ }
45
+
46
+ export interface ReadGuardService {
47
+ /** Detached per-turn snapshot; caches may survive turn boundaries. */
48
+ getStats(session: unknown): ReadGuardStats;
49
+ }
50
+
51
+ export interface OutlineEntry {
52
+ line: number;
53
+ text: string;
54
+ nested: boolean;
55
+ }
56
+
57
+ export declare const READ_GUARD_SOURCE: 'optimizer-read-guard';
58
+ export declare const ReadGuardConfig: z<ReadGuardOptions>;
59
+ export declare function truncateLongLines(text: string, maxLineChars?: number): string;
60
+ export declare function extractCodeOutline(
61
+ content: string,
62
+ options?: { filePath?: string; startLine?: number; endLine?: number }
63
+ ): OutlineEntry[];
64
+ export declare function formatCodeOutline(
65
+ content: string,
66
+ options?: {
67
+ filePath?: string;
68
+ startLine?: number;
69
+ endLine?: number;
70
+ maxEntries?: number;
71
+ maxBytes?: number;
72
+ }
73
+ ): string;
74
+ export declare function applyReadGuard(ctx: Context, rawConfig?: ReadGuardOptions): ReadGuardService | null;
75
+ export declare const name: string;
76
+ export declare const inject: string[];
77
+ export declare const Config: z<ReadGuardOptions>;
78
+ export declare function apply(ctx: Context, config?: ReadGuardOptions): void;
79
+ declare const plugin: { name: typeof name; inject: typeof inject; Config: typeof Config; apply: typeof apply };
80
+ export default plugin;
@@ -0,0 +1,336 @@
1
+ import fs from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import z from '@deepseek-ai/schemastery';
4
+ import { formatOutlineEntries, supportsCodeOutline } from './code-outline.js';
5
+ import { buildAdaptiveOutline } from './ast-outline.js';
6
+ import { OutlineCache } from './outline-cache.js';
7
+
8
+ export const READ_GUARD_SOURCE = 'optimizer-read-guard';
9
+
10
+ export const ReadGuardConfig = z.object({
11
+ enabled: z.boolean().default(true),
12
+ maxLineChars: z.number().step(1).min(100).max(50000).default(1500),
13
+ injectTailOutline: z.boolean().default(true),
14
+ maxOutlineEntries: z.number().step(1).min(3).max(60).default(20),
15
+ maxOutlineBytes: z.number().step(1).min(256).max(8192).default(1536),
16
+ maxInspectBytes: z.number().step(1).min(4096).max(4 * 1024 * 1024).default(512 * 1024),
17
+ maxCacheEntries: z.number().step(1).min(0).max(256).default(32),
18
+ maxCacheBytes: z.number().step(1).min(1024).max(8 * 1024 * 1024).default(256 * 1024),
19
+ astOutline: z.union(['off', 'auto', 'always']).default('auto'),
20
+ astGrepCommand: z.string().default('ast-grep'),
21
+ astTimeoutMs: z.number().step(1).min(1).max(5000).default(750),
22
+ astMaxOutputBytes: z.number().step(1).min(1024).max(1024 * 1024).default(256 * 1024)
23
+ });
24
+
25
+ export function truncateLongLines(text, maxLineChars = 1500) {
26
+ if (typeof text !== 'string' || !maxLineChars || maxLineChars <= 0) return text;
27
+ const lines = text.split('\n');
28
+ let modified = false;
29
+ const out = lines.map(line => {
30
+ if (line.length <= maxLineChars) return line;
31
+ modified = true;
32
+ return `${line.slice(0, maxLineChars)}... [line truncated: +${line.length - maxLineChars} chars]`;
33
+ });
34
+ return modified ? out.join('\n') : text;
35
+ }
36
+
37
+ function splitEnvelope(text) {
38
+ const match = text.match(/^([\s\S]*?<content>\n)([\s\S]*)(\n<\/content>[\s\S]*)$/);
39
+ if (!match) {
40
+ return { prefix: '', body: text, suffix: '' };
41
+ }
42
+ return { prefix: match[1], body: match[2], suffix: match[3] };
43
+ }
44
+
45
+ function detectTruncation(body, meta) {
46
+ if (meta && Array.isArray(meta.lines) && typeof meta.totalLines === 'number') {
47
+ const endLine = meta.lines.at(-1)?.number ?? 0;
48
+ if (endLine > 0 && endLine < meta.totalLines) {
49
+ return { endLine, totalLines: meta.totalLines };
50
+ }
51
+ }
52
+ const footerMatch = body.match(/\((?:Output capped\.\s*)?Showing lines \d+-(\d+)(?:\s+of\s+(\d+))?\.\s*Use offset=(\d+) to continue\.\)/);
53
+ if (footerMatch) {
54
+ const endLine = Number(footerMatch[1]);
55
+ const totalLines = footerMatch[2] ? Number(footerMatch[2]) : undefined;
56
+ if (Number.isInteger(endLine) && endLine > 0) {
57
+ return { endLine, totalLines };
58
+ }
59
+ }
60
+ return null;
61
+ }
62
+
63
+ async function readTargetSafely(filePath, cwd, fsService, signal, config, cache, stats) {
64
+ const { maxInspectBytes } = config;
65
+ if (signal?.aborted) return null;
66
+ const generation = cache?.generation;
67
+
68
+ if (fsService) {
69
+ // A service failure is authoritative; never retry through another backend.
70
+ try {
71
+ if (typeof fsService.resolve !== 'function' || typeof fsService.stat !== 'function') return null;
72
+ const target = await fsService.resolve(filePath, { cwd, signal });
73
+ const info = await fsService.stat(target, signal);
74
+ if (signal?.aborted || cache?.generation !== generation || info?.type !== 'file' || !Number.isFinite(info.size) || info.size < 0 || info.size > maxInspectBytes) return null;
75
+ const key = typeof target?.targetKey === 'string' && target.targetKey ? JSON.stringify([target.targetKey, path.extname(filePath).toLowerCase()]) : null;
76
+ const version = typeof info.version === 'string' && info.version ? info.version : null;
77
+ if (cache?.maxEntries > 0 && key && version) {
78
+ if (stats) stats.outlineCacheLookups++;
79
+ const cached = cache.get(key, version);
80
+ if (cached) {
81
+ if (stats) stats.outlineCacheHits++;
82
+ return cached;
83
+ }
84
+ if (stats) stats.outlineCacheMisses++;
85
+ } else if (stats) {
86
+ stats.outlineCacheBypasses++;
87
+ }
88
+ let content;
89
+ if (typeof fsService.readBytes === 'function') {
90
+ const bytes = await fsService.readBytes(target, signal, maxInspectBytes);
91
+ if (signal?.aborted || bytes.byteLength > maxInspectBytes) return null;
92
+ content = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
93
+ } else if (typeof fsService.streamText === 'function') {
94
+ const chunks = [];
95
+ let size = 0;
96
+ for await (const chunk of await fsService.streamText(target, signal)) {
97
+ if (signal?.aborted || typeof chunk !== 'string') return null;
98
+ size += Buffer.byteLength(chunk, 'utf8');
99
+ if (size > maxInspectBytes) return null;
100
+ chunks.push(chunk);
101
+ }
102
+ content = chunks.join('');
103
+ } else if (typeof fsService.readText === 'function') {
104
+ // Compatibility with older services: only after a successful size preflight.
105
+ content = await fsService.readText(target, signal);
106
+ } else {
107
+ return null;
108
+ }
109
+ if (signal?.aborted || cache?.generation !== generation || typeof content !== 'string' || Buffer.byteLength(content, 'utf8') > maxInspectBytes) return null;
110
+ const outline = await buildAdaptiveOutline(content, filePath, config, signal, stats);
111
+ if (signal?.aborted || cache?.generation !== generation) return null;
112
+ if (key && version) {
113
+ const after = await fsService.stat(target, signal);
114
+ if (signal?.aborted || cache?.generation !== generation || after?.type !== 'file' || after.version !== version || after.size !== info.size) return null;
115
+ cache?.set(key, version, outline);
116
+ }
117
+ return outline;
118
+ } catch {
119
+ return null;
120
+ }
121
+ }
122
+
123
+ // Standalone hosts without an fs service still get a bounded local read.
124
+ let handle;
125
+ try {
126
+ const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(cwd || process.cwd(), filePath);
127
+ handle = await fs.open(resolved, 'r');
128
+ const stat = await handle.stat();
129
+ if (!stat.isFile() || stat.size > maxInspectBytes || signal?.aborted || cache?.generation !== generation) return null;
130
+ if (stats) stats.outlineCacheBypasses++;
131
+ const buffer = Buffer.alloc(maxInspectBytes + 1);
132
+ let size = 0;
133
+ while (size < buffer.length) {
134
+ if (signal?.aborted) return null;
135
+ const { bytesRead } = await handle.read(buffer, size, buffer.length - size, null);
136
+ if (!bytesRead) break;
137
+ size += bytesRead;
138
+ }
139
+ if (signal?.aborted || cache?.generation !== generation || size > maxInspectBytes) return null;
140
+ const outline = await buildAdaptiveOutline(new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size)), filePath, config, signal, stats);
141
+ return signal?.aborted || cache?.generation !== generation ? null : outline;
142
+ } catch {
143
+ return null;
144
+ } finally {
145
+ await handle?.close().catch(() => {});
146
+ }
147
+ }
148
+
149
+ /**
150
+ * Protect direct `read` calls against giant minified lines and blind large-file truncation
151
+ * by enforcing single-line caps and appending a compact structural outline of unread tail lines.
152
+ */
153
+ function emptyStats() {
154
+ return {
155
+ inspected: 0, linesTruncated: 0, outlinesInjected: 0,
156
+ outlineCacheLookups: 0, outlineCacheHits: 0, outlineCacheMisses: 0,
157
+ outlineCacheBypasses: 0, outlineCacheInvalidations: 0,
158
+ astAttempts: 0, astSucceeded: 0, astFallbacks: 0, astTimeouts: 0
159
+ };
160
+ }
161
+
162
+ export function applyReadGuard(ctx, rawConfig = {}) {
163
+ const config = ReadGuardConfig(rawConfig);
164
+ if (!config.enabled) return null;
165
+
166
+ const statsBySession = new WeakMap();
167
+ const cachesBySession = new WeakMap();
168
+ const disposedSessions = new WeakSet();
169
+ let disposed = false;
170
+ const anonymousSession = {};
171
+ const localBackend = {};
172
+ const allCaches = new Set();
173
+ const clearCaches = session => {
174
+ const caches = cachesBySession.get(session ?? anonymousSession);
175
+ for (const cache of caches?.values() ?? []) { cache.clear(); allCaches.delete(cache); }
176
+ cachesBySession.delete(session ?? anonymousSession);
177
+ return Boolean(caches?.size);
178
+ };
179
+ const cacheFor = (session, backend) => {
180
+ const key = session ?? anonymousSession;
181
+ let caches = cachesBySession.get(key);
182
+ if (!caches) {
183
+ caches = new Map();
184
+ cachesBySession.set(key, caches);
185
+ }
186
+ let cache = caches.get(backend ?? localBackend);
187
+ if (!cache) {
188
+ cache = new OutlineCache(config.maxCacheEntries, config.maxCacheBytes);
189
+ caches.set(backend ?? localBackend, cache);
190
+ allCaches.add(cache);
191
+ }
192
+ return cache;
193
+ };
194
+ ctx.on('dispose', () => {
195
+ disposed = true;
196
+ for (const cache of allCaches) cache.clear();
197
+ allCaches.clear();
198
+ });
199
+ const statsFor = session => {
200
+ if (disposed || !session || disposedSessions.has(session)) return null;
201
+ let s = statsBySession.get(session);
202
+ if (!s) {
203
+ s = emptyStats();
204
+ statsBySession.set(session, s);
205
+ }
206
+ return s;
207
+ };
208
+
209
+ ctx.on('session/disposed', session => {
210
+ if (!session) return;
211
+ disposedSessions.add(session);
212
+ clearCaches(session);
213
+ statsBySession.delete(session);
214
+ });
215
+ ctx.on('session/event', (session, event) => {
216
+ if (!disposed && session && !disposedSessions.has(session) && event?.type === 'turn/start') {
217
+ statsBySession.set(session, emptyStats());
218
+ }
219
+ });
220
+
221
+ ctx.on('tools/post-execute', async (exec, result, next) => {
222
+ const decision = await next();
223
+ const session = exec.agent?.session;
224
+ if (disposed || (session && disposedSessions.has(session))) return decision;
225
+ // Invalidate conservatively even for failed/partially successful composite mutations.
226
+ if (['write', 'edit', 'edit_batch', 'bash', 'eval_node', 'eval_python'].includes(exec?.name)) {
227
+ if (clearCaches(session)) {
228
+ const stats = statsFor(session);
229
+ if (stats) stats.outlineCacheInvalidations++;
230
+ }
231
+ }
232
+ if (
233
+ decision?.kind === 'block' ||
234
+ exec?.name !== 'read' ||
235
+ exec.parent !== undefined ||
236
+ result?.isError ||
237
+ exec.signal?.aborted
238
+ ) {
239
+ return decision;
240
+ }
241
+
242
+ const baseBlocks = decision?.content ?? result.content;
243
+ if (!Array.isArray(baseBlocks) || baseBlocks.length === 0) return decision;
244
+
245
+ const stats = statsFor(session);
246
+ if (stats) stats.inspected++;
247
+
248
+ let changed = false;
249
+ const updatedBlocks = baseBlocks.map(block => ({ ...block }));
250
+
251
+ // 1. Single-line cap on text blocks (preserves DSH <content>...</content> wrapper if present)
252
+ for (let i = 0; i < updatedBlocks.length; i++) {
253
+ const block = updatedBlocks[i];
254
+ if (block.type !== 'text' || typeof block.text !== 'string') continue;
255
+ const { prefix, body, suffix } = splitEnvelope(block.text);
256
+ const truncatedBody = truncateLongLines(body, config.maxLineChars);
257
+ if (truncatedBody !== body) {
258
+ block.text = `${prefix}${truncatedBody}${suffix}`;
259
+ changed = true;
260
+ if (stats) stats.linesTruncated++;
261
+ }
262
+ }
263
+
264
+ // 2. Blind-read tail outline injection (only when caller omitted both offset & limit and hit truncation)
265
+ const args = exec.arguments ?? {};
266
+ const isBlindRead = args.offset === undefined && args.limit === undefined && typeof args.file_path === 'string' && args.file_path.trim().length > 0;
267
+ if (config.injectTailOutline && isBlindRead && supportsCodeOutline(args.file_path)) {
268
+ const firstTextIdx = updatedBlocks.findIndex(b => b.type === 'text' && typeof b.text === 'string');
269
+ if (firstTextIdx !== -1) {
270
+ const { prefix, body, suffix } = splitEnvelope(updatedBlocks[firstTextIdx].text);
271
+ const trunc = detectTruncation(body, result.meta);
272
+ if (trunc) {
273
+ let cwd = '';
274
+ try {
275
+ cwd = ctx.get('workingDirectory')?.get?.(session) ?? '';
276
+ } catch {
277
+ cwd = '';
278
+ }
279
+ const fsService = (() => {
280
+ try {
281
+ return ctx.get('fs');
282
+ } catch {
283
+ // An unavailable/denied service is not permission to bypass it.
284
+ return {};
285
+ }
286
+ })();
287
+
288
+ const parsed = await readTargetSafely(args.file_path, cwd, fsService, exec.signal, config, cacheFor(session, fsService), stats);
289
+ if (parsed !== null && !exec.signal?.aborted && !disposed && !(session && disposedSessions.has(session))) {
290
+ const { totalLines } = parsed;
291
+ if (totalLines > trunc.endLine) {
292
+ const outline = formatOutlineEntries(parsed.entries, {
293
+ startLine: trunc.endLine + 1,
294
+ endLine: totalLines,
295
+ maxEntries: config.maxOutlineEntries,
296
+ maxBytes: config.maxOutlineBytes
297
+ });
298
+ if (outline) {
299
+ const note = `[${READ_GUARD_SOURCE}] Remaining file outline (lines ${trunc.endLine + 1}-${totalLines}):\n${outline}\nUse read(file_path, offset=..., limit=...) to jump directly.`;
300
+ updatedBlocks[firstTextIdx].text = `${prefix}${body}\n\n${note}${suffix}`;
301
+ changed = true;
302
+ if (stats) stats.outlinesInjected++;
303
+ }
304
+ }
305
+ }
306
+ }
307
+ }
308
+ }
309
+
310
+ if (!changed) return decision;
311
+ return {
312
+ kind: 'accept',
313
+ content: updatedBlocks,
314
+ ...(decision?.additionalContexts ? { additionalContexts: decision.additionalContexts } : {})
315
+ };
316
+ });
317
+
318
+ return {
319
+ getStats(session) {
320
+ const stats = statsFor(session) ?? emptyStats();
321
+ return {
322
+ ...stats,
323
+ outlineCacheHitRate: stats.outlineCacheLookups ? stats.outlineCacheHits / stats.outlineCacheLookups : null
324
+ };
325
+ }
326
+ };
327
+ }
328
+
329
+ export const name = 'agent-optimizer-read-guard';
330
+ export const inject = ['tools'];
331
+ export const Config = ReadGuardConfig;
332
+ export function apply(ctx, config = {}) {
333
+ const service = applyReadGuard(ctx, config);
334
+ if (service) ctx.provide('readGuard', service);
335
+ }
336
+ export default { name, inject, Config, apply };
@@ -11,6 +11,7 @@ export interface RuntimePolicyOptions {
11
11
  maxShellCommandBytes?: number;
12
12
  maxInlineScriptBytes?: number;
13
13
  disallowChainedNetworkCommands?: boolean;
14
+ disallowChainedHeavyCommands?: boolean;
14
15
  }
15
16
 
16
17
  export interface ToolFingerprintInput {
@@ -11,7 +11,8 @@ export const RuntimePolicyConfig = z.object({
11
11
  minLargeWriteBytes: z.number().step(1).min(1).default(8192),
12
12
  maxShellCommandBytes: z.number().step(1).min(256).default(4096),
13
13
  maxInlineScriptBytes: z.number().step(1).min(128).default(512),
14
- disallowChainedNetworkCommands: z.boolean().default(true)
14
+ disallowChainedNetworkCommands: z.boolean().default(true),
15
+ disallowChainedHeavyCommands: z.boolean()
15
16
  });
16
17
 
17
18
  /**
@@ -108,16 +109,32 @@ export function classifyToolCall(name, args = {}, cwd = '') {
108
109
  const newLen = typeof args.new_string === 'string' ? Buffer.byteLength(args.new_string, 'utf8') : 0;
109
110
  const oldLen = typeof args.old_string === 'string' ? Buffer.byteLength(args.old_string, 'utf8') : 0;
110
111
  byteLength = newLen + oldLen;
112
+ } else if (name === 'edit_batch') {
113
+ opClass = 'edit';
114
+ const items = Array.isArray(args.edits) ? args.edits : [];
115
+ targetPath = Array.from(new Set(
116
+ items.map(item => (typeof item?.file_path === 'string' ? item.file_path : '')).filter(Boolean)
117
+ )).join(',');
118
+ byteLength = items.reduce((sum, item) => {
119
+ const newLen = typeof item?.new_string === 'string' ? Buffer.byteLength(item.new_string, 'utf8') : 0;
120
+ const oldLen = typeof item?.old_string === 'string' ? Buffer.byteLength(item.old_string, 'utf8') : 0;
121
+ return sum + newLen + oldLen;
122
+ }, 0);
111
123
  } else if (name === 'read' || name === 'read_image') {
112
124
  opClass = 'read';
113
125
  targetPath = typeof args.file_path === 'string' ? args.file_path : '';
114
- } else if (name === 'read_batch') {
115
- opClass = 'read';
116
- const items = Array.isArray(args.files) ? args.files : [];
117
- targetPath = items.map(item => (typeof item?.file_path === 'string' ? item.file_path : '')).filter(Boolean).join(',');
126
+ } else if (name === 'find_and_read') {
127
+ opClass = 'search';
128
+ targetPath = typeof args.path === 'string' ? args.path : '';
118
129
  } else if (name === 'glob' || name === 'grep') {
119
130
  opClass = 'search';
120
131
  targetPath = typeof args.path === 'string' ? args.path : '';
132
+ } else if (name === 'eval_python' || name === 'eval_node') {
133
+ opClass = 'eval';
134
+ targetPath = args.reset ? 'reset' : 'kernel';
135
+ if (typeof args.code === 'string') {
136
+ byteLength = Buffer.byteLength(args.code, 'utf8');
137
+ }
121
138
  } else if (name === 'bash') {
122
139
  opClass = 'shell';
123
140
  targetPath = typeof args.workdir === 'string' ? args.workdir : (cwd || '');
@@ -125,7 +142,6 @@ export function classifyToolCall(name, args = {}, cwd = '') {
125
142
  byteLength = Buffer.byteLength(args.command, 'utf8');
126
143
  }
127
144
  }
128
-
129
145
  return { name, opClass, targetPath, byteLength };
130
146
  }
131
147
 
@@ -203,7 +219,7 @@ export class RuntimePolicyManager {
203
219
  }
204
220
 
205
221
  recordExecution(session, exec, result) {
206
- if (!session || !exec) return null;
222
+ if (!session || !exec || exec.parent !== undefined) return null;
207
223
  const existing = this.sessionStates.get(session);
208
224
  const state = existing ?? this.stateFor(session, 1);
209
225
  if (!state) return null;
@@ -299,7 +315,7 @@ export class RuntimePolicyManager {
299
315
  }
300
316
 
301
317
  evaluatePreExecute(session, exec) {
302
- if (this.config.mode !== 'enforce' || !session || !exec) return { kind: 'allow' };
318
+ if (this.config.mode !== 'enforce' || !session || !exec || exec.parent !== undefined) return { kind: 'allow' };
303
319
  const state = this.stateFor(session);
304
320
  if (!state) return { kind: 'allow' };
305
321
  const classified = classifyToolCall(exec.name, exec.arguments, state.cwd);
@@ -318,8 +334,12 @@ export class RuntimePolicyManager {
318
334
  if (name === 'bash' && exec.arguments && typeof exec.arguments.command === 'string') {
319
335
  const cmd = exec.arguments.command;
320
336
  const cmdBytes = Buffer.byteLength(cmd, 'utf8');
321
- const isHeredoc = /(?:cat|type)\s*<<\s*['"]?EOF/i.test(cmd);
322
- const isInlineScript = /(?:python|python3|node|pwsh|powershell)\s+(?:-c|-e|-Command)\s+['"][\s\S]+/i.test(cmd);
337
+ // Strip quoted string literals to prevent false positives in commit messages / echo args
338
+ const unquoted = cmd
339
+ .replace(/"[^"\\]*(?:\\.[^"\\]*)*"/g, '""')
340
+ .replace(/'[^'\\]*(?:\\.[^'\\]*)*'/g, "''");
341
+ const isHeredoc = /(?:^|[\s;&|])(?:cat|type)\s*<<\s*(?:''|""|[A-Za-z_])/i.test(unquoted);
342
+ const isInlineScript = /(?:^|[\s;&|])(?:python|python3|node|pwsh|powershell)(?:\s+-[\w-]+)*\s+(?:-c|-e|-Command)\s+(?:""|''|\S)/i.test(unquoted);
323
343
 
324
344
  const maxBytes = this.config.maxShellCommandBytes ?? 4096;
325
345
  const maxScriptBytes = this.config.maxInlineScriptBytes ?? 512;
@@ -355,7 +375,8 @@ export class RuntimePolicyManager {
355
375
  }
356
376
 
357
377
  // Guard against blocked file:// URLs in playwright-cli
358
- const isPlaywrightFileUrl = /\bplaywright-cli\s+(?:open|goto)\s+['"]?file:/i.test(cmd);
378
+ const isPlaywrightCmd = /(?:^|[\s;&|])playwright-cli\b/i.test(unquoted);
379
+ const isPlaywrightFileUrl = isPlaywrightCmd && /\bplaywright-cli\s+(?:open|goto)\s+['"]?file:/i.test(cmd);
359
380
  if (isPlaywrightFileUrl) {
360
381
  state.shellPayloadBlocks++;
361
382
  state.policyDenials++;
@@ -372,11 +393,10 @@ export class RuntimePolicyManager {
372
393
  }
373
394
 
374
395
  // Guard against dangerous heavy concurrent or publishing command chaining on Windows
375
- if (this.config.disallowChainedNetworkCommands) {
376
- const hasCompoundOperator = /(&&|;)/.test(cmd);
396
+ const blockChainedHeavy = this.config.disallowChainedHeavyCommands ?? this.config.disallowChainedNetworkCommands;
397
+ if (blockChainedHeavy) {
398
+ const hasCompoundOperator = /(&&|;)/.test(unquoted);
377
399
  if (hasCompoundOperator) {
378
- // Strip quoted string literals to prevent false positives in commit messages / echo args
379
- const unquoted = cmd.replace(/"[^"\\]*(?:\\.[^"\\]*)*"/g, '""').replace(/'[^'\\]*(?:\\.[^'\\]*)*'/g, "''");
380
400
  const hasBlockedCompoundAction = /(?:^|[\s;&|])(?:npm\s+(?:test|t|run\s+build|publish)|vitest)\b/i.test(unquoted);
381
401
  if (hasBlockedCompoundAction) {
382
402
  state.shellPayloadBlocks++;
@@ -4,10 +4,13 @@ import type { RuntimePolicySummary } from './runtime-policy.d.ts';
4
4
  import type { FileMutationPolicySummary } from './file-mutation-policy.d.ts';
5
5
  import type { FailureRecoveryStats } from './failure-recovery.d.ts';
6
6
  import type { CompositeToolsStats } from './composite-tools.d.ts';
7
+ import type { ReadGuardStats } from './read-guard.d.ts';
7
8
 
8
9
  export interface TelemetryOptions {
9
10
  enabled?: boolean;
10
11
  trackStreams?: boolean;
12
+ /** Opt-in HTTP diagnostics JSONL path; absolute, bounded to 8 MiB. */
13
+ cacheDiagnosticsPath?: string;
11
14
  onTurnSummary?: (summary: TurnTelemetrySummary, session: unknown) => void;
12
15
  }
13
16
 
@@ -42,6 +45,7 @@ export interface TurnTelemetrySummary {
42
45
  fileMutationPolicy: FileMutationPolicySummary | null;
43
46
  failureRecovery: FailureRecoveryStats | null;
44
47
  compositeTools: CompositeToolsStats | null;
48
+ readGuard: ReadGuardStats | null;
45
49
  }
46
50
 
47
51
  export interface TurnComparisonDelta {