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.
package/src/read-guard.js CHANGED
@@ -1,7 +1,9 @@
1
1
  import fs from 'node:fs/promises';
2
2
  import path from 'node:path';
3
3
  import z from '@deepseek-ai/schemastery';
4
- import { formatCodeOutline } from './code-outline.js';
4
+ import { formatOutlineEntries, supportsCodeOutline } from './code-outline.js';
5
+ import { buildAdaptiveOutline } from './ast-outline.js';
6
+ import { OutlineCache } from './outline-cache.js';
5
7
 
6
8
  export const READ_GUARD_SOURCE = 'optimizer-read-guard';
7
9
 
@@ -11,7 +13,13 @@ export const ReadGuardConfig = z.object({
11
13
  injectTailOutline: z.boolean().default(true),
12
14
  maxOutlineEntries: z.number().step(1).min(3).max(60).default(20),
13
15
  maxOutlineBytes: z.number().step(1).min(256).max(8192).default(1536),
14
- maxInspectBytes: z.number().step(1).min(4096).max(4 * 1024 * 1024).default(512 * 1024)
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)
15
23
  });
16
24
 
17
25
  export function truncateLongLines(text, maxLineChars = 1500) {
@@ -52,42 +60,89 @@ function detectTruncation(body, meta) {
52
60
  return null;
53
61
  }
54
62
 
55
- async function readTargetSafely(filePath, cwd, fsService, signal, maxInspectBytes) {
63
+ async function readTargetSafely(filePath, cwd, fsService, signal, config, cache, stats) {
64
+ const { maxInspectBytes } = config;
56
65
  if (signal?.aborted) return null;
66
+ const generation = cache?.generation;
57
67
 
58
68
  if (fsService) {
59
- if (typeof fsService.readFile === 'function') {
60
- try {
61
- const content = await fsService.readFile(filePath, { cwd, signal });
62
- if (typeof content === 'string') {
63
- return Buffer.byteLength(content, 'utf8') <= maxInspectBytes ? content : null;
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;
64
83
  }
65
- } catch {
66
- // Fall through
84
+ if (stats) stats.outlineCacheMisses++;
85
+ } else if (stats) {
86
+ stats.outlineCacheBypasses++;
67
87
  }
68
- }
69
- if (typeof fsService.readText === 'function') {
70
- try {
71
- const target = typeof fsService.resolve === 'function'
72
- ? await fsService.resolve(filePath, { cwd, signal })
73
- : filePath;
74
- const content = await fsService.readText(target, signal);
75
- if (typeof content !== 'string') return null;
76
- return Buffer.byteLength(content, 'utf8') <= maxInspectBytes ? content : null;
77
- } catch {
78
- // Fall through to disk
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);
79
116
  }
117
+ return outline;
118
+ } catch {
119
+ return null;
80
120
  }
81
121
  }
82
122
 
123
+ // Standalone hosts without an fs service still get a bounded local read.
124
+ let handle;
83
125
  try {
84
126
  const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(cwd || process.cwd(), filePath);
85
- const stat = await fs.stat(resolved);
86
- if (!stat.isFile() || stat.size > maxInspectBytes) return null;
87
- if (signal?.aborted) return null;
88
- return await fs.readFile(resolved, 'utf8');
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;
89
142
  } catch {
90
143
  return null;
144
+ } finally {
145
+ await handle?.close().catch(() => {});
91
146
  }
92
147
  }
93
148
 
@@ -95,29 +150,85 @@ async function readTargetSafely(filePath, cwd, fsService, signal, maxInspectByte
95
150
  * Protect direct `read` calls against giant minified lines and blind large-file truncation
96
151
  * by enforcing single-line caps and appending a compact structural outline of unread tail lines.
97
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
+
98
162
  export function applyReadGuard(ctx, rawConfig = {}) {
99
163
  const config = ReadGuardConfig(rawConfig);
100
164
  if (!config.enabled) return null;
101
165
 
102
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
+ });
103
199
  const statsFor = session => {
104
- if (!session) return null;
200
+ if (disposed || !session || disposedSessions.has(session)) return null;
105
201
  let s = statsBySession.get(session);
106
202
  if (!s) {
107
- s = { inspected: 0, linesTruncated: 0, outlinesInjected: 0 };
203
+ s = emptyStats();
108
204
  statsBySession.set(session, s);
109
205
  }
110
206
  return s;
111
207
  };
112
208
 
209
+ ctx.on('session/disposed', session => {
210
+ if (!session) return;
211
+ disposedSessions.add(session);
212
+ clearCaches(session);
213
+ statsBySession.delete(session);
214
+ });
113
215
  ctx.on('session/event', (session, event) => {
114
- if (event?.type === 'turn/start') {
115
- statsBySession.set(session, { inspected: 0, linesTruncated: 0, outlinesInjected: 0 });
216
+ if (!disposed && session && !disposedSessions.has(session) && event?.type === 'turn/start') {
217
+ statsBySession.set(session, emptyStats());
116
218
  }
117
219
  });
118
220
 
119
221
  ctx.on('tools/post-execute', async (exec, result, next) => {
120
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
+ }
121
232
  if (
122
233
  decision?.kind === 'block' ||
123
234
  exec?.name !== 'read' ||
@@ -131,7 +242,6 @@ export function applyReadGuard(ctx, rawConfig = {}) {
131
242
  const baseBlocks = decision?.content ?? result.content;
132
243
  if (!Array.isArray(baseBlocks) || baseBlocks.length === 0) return decision;
133
244
 
134
- const session = exec.agent?.session;
135
245
  const stats = statsFor(session);
136
246
  if (stats) stats.inspected++;
137
247
 
@@ -154,7 +264,7 @@ export function applyReadGuard(ctx, rawConfig = {}) {
154
264
  // 2. Blind-read tail outline injection (only when caller omitted both offset & limit and hit truncation)
155
265
  const args = exec.arguments ?? {};
156
266
  const isBlindRead = args.offset === undefined && args.limit === undefined && typeof args.file_path === 'string' && args.file_path.trim().length > 0;
157
- if (config.injectTailOutline && isBlindRead) {
267
+ if (config.injectTailOutline && isBlindRead && supportsCodeOutline(args.file_path)) {
158
268
  const firstTextIdx = updatedBlocks.findIndex(b => b.type === 'text' && typeof b.text === 'string');
159
269
  if (firstTextIdx !== -1) {
160
270
  const { prefix, body, suffix } = splitEnvelope(updatedBlocks[firstTextIdx].text);
@@ -170,16 +280,16 @@ export function applyReadGuard(ctx, rawConfig = {}) {
170
280
  try {
171
281
  return ctx.get('fs');
172
282
  } catch {
173
- return undefined;
283
+ // An unavailable/denied service is not permission to bypass it.
284
+ return {};
174
285
  }
175
286
  })();
176
287
 
177
- const fullText = await readTargetSafely(args.file_path, cwd, fsService, exec.signal, config.maxInspectBytes);
178
- if (fullText !== null && !exec.signal?.aborted) {
179
- const totalLines = fullText.replace(/\r\n/g, '\n').split('\n').length;
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;
180
291
  if (totalLines > trunc.endLine) {
181
- const outline = formatCodeOutline(fullText, {
182
- filePath: args.file_path,
292
+ const outline = formatOutlineEntries(parsed.entries, {
183
293
  startLine: trunc.endLine + 1,
184
294
  endLine: totalLines,
185
295
  maxEntries: config.maxOutlineEntries,
@@ -207,7 +317,11 @@ export function applyReadGuard(ctx, rawConfig = {}) {
207
317
 
208
318
  return {
209
319
  getStats(session) {
210
- return statsFor(session) ?? { inspected: 0, linesTruncated: 0, outlinesInjected: 0 };
320
+ const stats = statsFor(session) ?? emptyStats();
321
+ return {
322
+ ...stats,
323
+ outlineCacheHitRate: stats.outlineCacheLookups ? stats.outlineCacheHits / stats.outlineCacheLookups : null
324
+ };
211
325
  }
212
326
  };
213
327
  }
@@ -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 {
package/src/telemetry.js CHANGED
@@ -1,11 +1,13 @@
1
1
  import { createHash } from 'node:crypto';
2
+ import { CacheDiagnostics } from './cache-diagnostics.js';
2
3
  import z from '@deepseek-ai/schemastery';
3
4
  import { SOURCE as CONVERGENCE_SOURCE } from './convergence.js';
4
5
  import { RECOVERY_SOURCE } from './failure-recovery.js';
5
6
  export const TelemetryConfig = z.object({
6
7
  enabled: z.boolean().default(true),
7
8
  trackStreams: z.boolean().default(true),
8
- onTurnSummary: z.any()
9
+ onTurnSummary: z.any(),
10
+ cacheDiagnosticsPath: z.string()
9
11
  });
10
12
 
11
13
  function computeQuantile(sortedNumbers, p) {
@@ -85,16 +87,12 @@ export class AgentTelemetryManager {
85
87
  this.sessionStates = new WeakMap();
86
88
  this.sessionsById = new Map();
87
89
  this.activeSession = null;
88
- this.messageDigestCache = new WeakMap();
90
+ this.previousHistories = new WeakMap();
89
91
  }
90
92
 
91
93
  #digestMessage(message) {
92
94
  if (message && typeof message === 'object') {
93
- const cached = this.messageDigestCache.get(message);
94
- if (cached !== undefined) return cached;
95
- const digest = createHash('sha256').update(JSON.stringify(message)).digest('hex');
96
- this.messageDigestCache.set(message, digest);
97
- return digest;
95
+ return createHash('sha256').update(JSON.stringify(message)).digest('hex');
98
96
  }
99
97
  return createHash('sha256').update(String(message)).digest('hex');
100
98
  }
@@ -114,7 +112,6 @@ export class AgentTelemetryManager {
114
112
  recoveryNotices: 0,
115
113
  turnOutcome: null,
116
114
  streamAttempts: [],
117
- previousHistory: null,
118
115
  prefixChanges: 0
119
116
  };
120
117
  }
@@ -177,6 +174,7 @@ export class AgentTelemetryManager {
177
174
  }
178
175
 
179
176
  onSessionDisposed(session) {
177
+ if (session) this.previousHistories.delete(session);
180
178
  if (session?.id !== undefined && this.sessionsById.get(session.id) === session) {
181
179
  this.sessionsById.delete(session.id);
182
180
  }
@@ -192,10 +190,10 @@ export class AgentTelemetryManager {
192
190
 
193
191
  if (Array.isArray(options?.messages)) {
194
192
  const history = options.messages.map(message => this.#digestMessage(message));
195
- if (state.previousHistory?.some((msg, idx) => history[idx] !== msg)) {
193
+ if (this.previousHistories.get(session)?.some((msg, idx) => history[idx] !== msg)) {
196
194
  state.prefixChanges++;
197
195
  }
198
- state.previousHistory = history;
196
+ this.previousHistories.set(session, history);
199
197
  }
200
198
 
201
199
  const attempt = {
@@ -252,7 +250,8 @@ export class AgentTelemetryManager {
252
250
  runtimePolicy: null,
253
251
  fileMutationPolicy: null,
254
252
  failureRecovery: null,
255
- compositeTools: null
253
+ compositeTools: null,
254
+ readGuard: null
256
255
  };
257
256
  }
258
257
 
@@ -310,7 +309,8 @@ export class AgentTelemetryManager {
310
309
  runtimePolicy: this.ctx?.get?.('runtimePolicy')?.getSummary(targetSession, state.turn) ?? null,
311
310
  fileMutationPolicy: this.ctx?.get?.('fileMutationPolicy')?.getSummary(targetSession, state.turn) ?? null,
312
311
  failureRecovery: this.ctx?.get?.('failureRecovery')?.getStats(targetSession) ?? null,
313
- compositeTools: this.ctx?.get?.('compositeTools')?.getStats(targetSession) ?? null
312
+ compositeTools: this.ctx?.get?.('compositeTools')?.getStats(targetSession) ?? null,
313
+ readGuard: this.ctx?.get?.('readGuard')?.getStats(targetSession) ?? null
314
314
  };
315
315
  }
316
316
  }
@@ -320,6 +320,14 @@ export function applyTelemetry(ctx, rawConfig = {}) {
320
320
  if (!config.enabled) return null;
321
321
 
322
322
  const manager = new AgentTelemetryManager(ctx, config);
323
+ if (config.cacheDiagnosticsPath) {
324
+ const warn = reason => { try { ctx.logger?.warn?.(`Cache diagnostics disabled: ${reason}`); } catch {} };
325
+ try {
326
+ const diagnostics = new CacheDiagnostics(config.cacheDiagnosticsPath, { onStop: warn });
327
+ ctx.on('llm/stream', (options, next) => diagnostics.wrap(options?.sessionId, next));
328
+ ctx.on('dispose', () => diagnostics.dispose());
329
+ } catch { warn('initialization-failed'); }
330
+ }
323
331
 
324
332
  ctx.on('session/event', (session, event) => {
325
333
  manager.onSessionEvent(session, event);