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
@@ -0,0 +1,100 @@
1
+ import assert from 'node:assert/strict';
2
+ import fs from 'node:fs/promises';
3
+ import os from 'node:os';
4
+ import { applyReadGuard } from '../src/read-guard.js';
5
+
6
+ const samples = 20;
7
+ const source = [
8
+ 'import React from "react";',
9
+ ...Array.from({ length: 40 }, (_, i) => `export const Panel${i} = () => <section data-id="${i}">Panel ${i}</section>;`),
10
+ 'export class Controller {',
11
+ ' async render(value: string) { return value; }',
12
+ '}'
13
+ ].join('\n');
14
+
15
+ const ordinarySource = [
16
+ 'export interface Value { id: string; }',
17
+ ...Array.from({ length: 40 }, (_, i) => `export function value${i}(item: Value): string { return item.id; }`)
18
+ ].join('\n');
19
+
20
+ function host(astOutline, maxCacheEntries, content) {
21
+ const hooks = new Map();
22
+ const session = {};
23
+ let reads = 0;
24
+ let stats = 0;
25
+ const filesystem = {
26
+ resolve: async () => ({ targetKey: 'benchmark:panel.tsx' }),
27
+ stat: async () => { stats++; return { type: 'file', size: Buffer.byteLength(content), version: 'fixture-v1' }; },
28
+ readBytes: async () => { reads++; return Buffer.from(content); }
29
+ };
30
+ const guard = applyReadGuard({
31
+ on(name, callback) { hooks.set(name, callback); },
32
+ get(name) { return name === 'fs' ? filesystem : undefined; }
33
+ }, { astOutline, maxCacheEntries, astTimeoutMs: 2000 });
34
+ return {
35
+ async inspect(filePath = 'panel.tsx') {
36
+ const result = { content: [{ type: 'text', text: `<content>\n1: import\n\n(Showing lines 1-1 of ${content.split('\n').length}. Use offset=2 to continue.)\n</content>` }] };
37
+ const started = performance.now();
38
+ const decision = await hooks.get('tools/post-execute')({ name: 'read', arguments: { file_path: filePath }, agent: { session } }, result, async () => undefined);
39
+ const durationMs = performance.now() - started;
40
+ const text = decision?.content?.[0]?.text ?? '';
41
+ assert.match(text, /Remaining file outline/);
42
+ assert.match(text, /Panel0|value0/);
43
+ return durationMs;
44
+ },
45
+ counts: () => ({ contentReads: reads, statCalls: stats, ...guard.getStats(session) }),
46
+ dispose() { hooks.get('dispose')(); }
47
+ };
48
+ }
49
+
50
+ function summarize(durations) {
51
+ const sorted = [...durations].sort((a, b) => a - b);
52
+ const rounded = number => Number(number.toFixed(3));
53
+ return {
54
+ samples: sorted.length, minMs: rounded(sorted[0]),
55
+ medianMs: rounded(sorted[Math.floor(sorted.length / 2)]),
56
+ p95Ms: rounded(sorted[Math.ceil(sorted.length * 0.95) - 1]),
57
+ maxMs: rounded(sorted.at(-1))
58
+ };
59
+ }
60
+
61
+ async function measure(astOutline, cacheEntries, filePath, content = source) {
62
+ const fixture = host(astOutline, cacheEntries, content);
63
+ try {
64
+ const firstMs = await fixture.inspect(filePath);
65
+ const firstCounts = fixture.counts();
66
+ const durations = [];
67
+ for (let i = 0; i < samples; i++) durations.push(await fixture.inspect(filePath));
68
+ return { firstMs: Number(firstMs.toFixed(3)), firstCounts, repeated: summarize(durations), finalCounts: fixture.counts() };
69
+ } finally { fixture.dispose(); }
70
+ }
71
+
72
+ // First measurement is the first ast-grep launch in this benchmark process.
73
+ const astUncached = await measure('always', 0, 'panel.tsx');
74
+ const lexical = await measure('off', 0, 'panel.tsx');
75
+ const autoOrdinary = await measure('auto', 0, 'ordinary.ts', ordinarySource);
76
+ const astCached = await measure('auto', 32, 'panel.tsx');
77
+ const largeSource = `${'// source padding to measure a larger authorized snapshot\n'.repeat(2400)}${source}`;
78
+ const astLarge = await measure('auto', 32, 'large-panel.tsx', largeSource);
79
+ assert.equal(astUncached.finalCounts.astSucceeded, samples + 1);
80
+ assert.equal(astUncached.finalCounts.contentReads, samples + 1);
81
+ assert.equal(lexical.finalCounts.astAttempts, 0);
82
+ assert.equal(autoOrdinary.finalCounts.astAttempts, 0);
83
+ assert.equal(astCached.finalCounts.astSucceeded, 1);
84
+ assert.equal(astCached.finalCounts.contentReads, 1);
85
+ assert.equal(astCached.finalCounts.outlineCacheHits, samples);
86
+ assert.equal(astLarge.finalCounts.astSucceeded, 1);
87
+ assert.equal(astLarge.finalCounts.outlineCacheHits, samples);
88
+ const report = {
89
+ measuredAt: new Date().toISOString(),
90
+ platform: process.platform, architecture: process.arch,
91
+ osRelease: os.release(), node: process.version,
92
+ sourceBytes: Buffer.byteLength(source), sourceLines: source.split('\n').length,
93
+ ordinarySourceBytes: Buffer.byteLength(ordinarySource), ordinarySourceLines: ordinarySource.split('\n').length,
94
+ methodology: 'Real ast-grep CLI over stdin; in-memory versioned fs isolates parsing/spawn cost. First invocation is process-cold, not a flushed OS disk cache. Repeated uncached samples launch a fresh CLI each time. Cache hits include resolve/stat and rendering but no content read or process. No network or model calls.',
95
+ astUncached, lexical, autoOrdinary, astCached,
96
+ astLarge: { sourceBytes: Buffer.byteLength(largeSource), sourceLines: largeSource.split('\n').length, ...astLarge }
97
+ };
98
+ const outputPath = process.argv[2];
99
+ if (outputPath) await fs.writeFile(outputPath, JSON.stringify(report, null, 2) + '\n', 'utf8');
100
+ console.log(JSON.stringify(report, null, 2));
@@ -5,14 +5,25 @@ import { compareTurnSummaries, PAIRING_ERROR, StdioWorkerRunner } from '../src/i
5
5
  import { PY_WORKER_SCRIPT } from '../src/persistent-eval/daemon-pool.js';
6
6
 
7
7
  // Run deterministic A/B verification scenarios over the unchanged official @deepseek-ai/dsh-agent-loop.
8
- async function runBatchReadScenario() {
8
+ async function runFindAndReadScenario() {
9
9
  const files = {
10
- 'a.txt': 'Alpha content line 1\nAlpha content line 2',
11
- 'b.txt': 'Beta content line 1\nBeta content line 2',
12
- 'c.txt': 'Gamma content line 1\nGamma content line 2'
10
+ 'src/auth.ts': [
11
+ ...Array.from({ length: 20 }, (_, i) => `const padAuth${i} = ${i};`),
12
+ 'export function verifyToken(token: string) {',
13
+ ' return token.startsWith("dsh_");',
14
+ '}',
15
+ ...Array.from({ length: 20 }, (_, i) => `const tailAuth${i} = ${i};`)
16
+ ].join('\n'),
17
+ 'src/session.ts': [
18
+ ...Array.from({ length: 20 }, (_, i) => `const padSess${i} = ${i};`),
19
+ 'export function openSession(token: string) {',
20
+ ' return verifyToken(token);',
21
+ '}',
22
+ ...Array.from({ length: 20 }, (_, i) => `const tailSess${i} = ${i};`)
23
+ ].join('\n')
13
24
  };
14
25
 
15
- // Baseline: sequential single-file reads across 3 steps + final answer (4 model requests)
26
+ // Baseline: grep -> wait -> parallel reads -> final answer (3 model requests)
16
27
  const baselineHost = await createTestRuntime({
17
28
  optimizerEnabled: true,
18
29
  optimizerConfig: {
@@ -21,44 +32,40 @@ async function runBatchReadScenario() {
21
32
  },
22
33
  files,
23
34
  script: [
24
- [call('r1', 'read', { file_path: 'a.txt' })],
25
- [call('r2', 'read', { file_path: 'b.txt' })],
26
- [call('r3', 'read', { file_path: 'c.txt' })],
27
- [{ type: 'text', text: 'Synthesized alpha, beta, gamma.' }]
35
+ [call('g1', 'grep', { pattern: 'verifyToken' })],
36
+ [
37
+ call('r1', 'read', { file_path: 'src/auth.ts', offset: 18, limit: 10 }),
38
+ call('r2', 'read', { file_path: 'src/session.ts', offset: 18, limit: 10 })
39
+ ],
40
+ [{ type: 'text', text: 'Located verifyToken definition and caller.' }]
28
41
  ]
29
42
  });
30
43
 
31
- // Candidate: read_batch collapses 3 file reads into 1 round-trip + final answer (2 model requests)
44
+ // Candidate: find_and_read collapses grep + merged context reads into 1 round-trip (2 model requests)
32
45
  const candidateHost = await createTestRuntime({
33
46
  optimizerEnabled: true,
34
47
  files,
35
48
  script: [
36
- [call('rb1', 'read_batch', {
37
- files: [
38
- { file_path: 'a.txt' },
39
- { file_path: 'b.txt' },
40
- { file_path: 'c.txt' }
41
- ]
42
- })],
43
- [{ type: 'text', text: 'Synthesized alpha, beta, gamma.' }]
49
+ [call('fr1', 'find_and_read', { pattern: 'verifyToken', contextLines: 4 })],
50
+ [{ type: 'text', text: 'Located verifyToken definition and caller.' }]
44
51
  ]
45
52
  });
46
53
 
47
54
  try {
48
- await baselineHost.run('Read a.txt, b.txt, and c.txt and summarize.');
49
- await candidateHost.run('Read a.txt, b.txt, and c.txt and summarize.');
55
+ await baselineHost.run('Find verifyToken definition and call sites.');
56
+ await candidateHost.run('Find verifyToken definition and call sites.');
50
57
 
51
58
  const baseSummary = baselineHost.telemetry.getSummary(baselineHost.agent.session);
52
59
  const candSummary = candidateHost.telemetry.getSummary(candidateHost.agent.session);
53
60
  const comparison = compareTurnSummaries(baseSummary, candSummary);
54
61
 
55
- assert.equal(baseSummary.modelRequests, 4);
62
+ assert.equal(baseSummary.modelRequests, 3);
56
63
  assert.equal(candSummary.modelRequests, 2);
57
- assert.equal(candSummary.ptcSubCalls, 3);
58
- assert.equal(comparison.modelRequests.delta, -2);
64
+ assert.equal(candSummary.ptcSubCalls, 3); // 1 grep + 2 merged window reads
65
+ assert.equal(comparison.modelRequests.delta, -1);
59
66
 
60
67
  return {
61
- scenario: 'multi-file-read-collapse',
68
+ scenario: 'find-and-read-collapse',
62
69
  baseline: baseSummary,
63
70
  candidate: candSummary,
64
71
  comparison
@@ -151,7 +158,7 @@ async function runPersistentEvalBenchmarkScenario() {
151
158
  };
152
159
  }
153
160
 
154
- const batchScenario = await runBatchReadScenario();
161
+ const findScenario = await runFindAndReadScenario();
155
162
  const recoveryScenario = await runWriteRecoveryScenario();
156
163
  const persistentEvalScenario = await runPersistentEvalBenchmarkScenario();
157
164
 
@@ -160,5 +167,5 @@ console.log(JSON.stringify({
160
167
  officialLoopReplaced: false,
161
168
  networkRequests: 0,
162
169
  note: 'Offline scripted verification proves mechanism and telemetry fidelity. Run identical live tasks to evaluate model-specific round-trip reductions.',
163
- scenarios: [batchScenario, recoveryScenario, persistentEvalScenario]
170
+ scenarios: [findScenario, recoveryScenario, persistentEvalScenario]
164
171
  }, null, 2));
@@ -8,13 +8,22 @@ const root = fileURLToPath(new URL('../', import.meta.url));
8
8
  const require = createRequire(import.meta.url);
9
9
 
10
10
  function findTsc() {
11
- const searchBases = [
12
- root,
13
- path.resolve(root, '../Awesome-Canvas/web'),
14
- path.resolve(root, '../threejs-projects'),
15
- 'D:/nodejs/node_global/node_modules/@deepseek-ai/dsh',
16
- 'D:/nodejs/node_global'
17
- ];
11
+ const searchBases = [root];
12
+ if (process.env.DSH_IMPLEMENTATION_ROOT) {
13
+ searchBases.push(path.resolve(process.env.DSH_IMPLEMENTATION_ROOT));
14
+ }
15
+ try {
16
+ const res = spawnSync('npm root -g', {
17
+ encoding: 'utf8',
18
+ timeout: 3000,
19
+ windowsHide: true,
20
+ shell: true
21
+ });
22
+ if (res.status === 0 && res.stdout?.trim()) {
23
+ const globalRoot = res.stdout.trim();
24
+ searchBases.push(path.join(globalRoot, '@deepseek-ai/dsh'), globalRoot);
25
+ }
26
+ } catch {}
18
27
  for (const base of searchBases) {
19
28
  try {
20
29
  const baseReq = createRequire(path.join(base, 'package.json'));
@@ -40,18 +49,28 @@ if (tscBin) {
40
49
  if (res.error) throw res.error;
41
50
  process.exitCode = res.status ?? 1;
42
51
  } else {
43
- // Verify all declared .d.ts files exist and match package.json exports
44
- const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
45
- for (const [subpath, entry] of Object.entries(pkg.exports)) {
46
- if (typeof entry === 'object' && entry !== null && entry.types) {
47
- const resolved = path.resolve(root, entry.types);
48
- if (!fs.existsSync(resolved)) {
49
- console.error(`Missing declaration file for export "${subpath}": ${entry.types}`);
50
- process.exitCode = 1;
52
+ const pathTsc = spawnSync(`tsc --project "${path.join(root, 'tsconfig.json')}" --noEmit`, {
53
+ cwd: root,
54
+ stdio: 'inherit',
55
+ windowsHide: true,
56
+ shell: true
57
+ });
58
+ if (!pathTsc.error && pathTsc.status !== null) {
59
+ process.exitCode = pathTsc.status;
60
+ } else {
61
+ // Verify all declared .d.ts files exist and match package.json exports
62
+ const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
63
+ for (const [subpath, entry] of Object.entries(pkg.exports)) {
64
+ if (typeof entry === 'object' && entry !== null && entry.types) {
65
+ const resolved = path.resolve(root, entry.types);
66
+ if (!fs.existsSync(resolved)) {
67
+ console.error(`Missing declaration file for export "${subpath}": ${entry.types}`);
68
+ process.exitCode = 1;
69
+ }
51
70
  }
52
71
  }
53
- }
54
- if (!process.exitCode) {
55
- console.log('Verified all package.json TypeScript declaration entrypoints exist.');
72
+ if (!process.exitCode) {
73
+ console.log('Verified all package.json TypeScript declaration entrypoints exist.');
74
+ }
56
75
  }
57
76
  }
@@ -0,0 +1 @@
1
+ ruleDirs: []
@@ -0,0 +1,143 @@
1
+ import { spawn } from 'node:child_process';
2
+ import path from 'node:path';
3
+ import { fileURLToPath } from 'node:url';
4
+ import { buildCodeOutline } from './code-outline.js';
5
+
6
+ const CONFIG_PATH = fileURLToPath(new URL('./ast-outline-config.yml', import.meta.url));
7
+ const CLI_CWD = path.dirname(CONFIG_PATH);
8
+ const LANGUAGES = new Map([
9
+ ...['.js', '.mjs', '.cjs', '.jsx'].map(ext => [ext, 'javascript']),
10
+ ...['.ts', '.mts', '.cts'].map(ext => [ext, 'typescript']),
11
+ ['.tsx', 'tsx'], ['.py', 'python'], ['.pyw', 'python'], ['.go', 'go'], ['.rs', 'rust']
12
+ ]);
13
+
14
+ export function needsAstOutline(content, filePath, lexical, mode) {
15
+ if (mode === 'off' || !LANGUAGES.has(path.extname(filePath).toLowerCase())) return false;
16
+ if (mode === 'always') return true;
17
+ const ext = path.extname(filePath).toLowerCase();
18
+ // Known weak areas of the bounded lexical scanner, without a repository-wide scan.
19
+ if (['.tsx', '.jsx'].includes(ext)) return true;
20
+ if (['.ts', '.mts', '.cts'].includes(ext) && /^\s*(?:@|export\s+(?:declare\s+)?(?:namespace|module)\b)/m.test(content)) return true;
21
+ return lexical.entries.length === 0 && /^\s*(?:(?:export|pub|async|unsafe)\s+)*(?:function|class|def|fn|func|impl|trait|interface)\b/m.test(content);
22
+ }
23
+
24
+ /** Parse only the authorized snapshot. Never pass a model-controlled path to the CLI. */
25
+ export function runAstOutline(content, filePath, {
26
+ command = 'ast-grep', timeoutMs = 750, maxOutputBytes = 256 * 1024, signal
27
+ } = {}) {
28
+ const language = LANGUAGES.get(path.extname(filePath).toLowerCase());
29
+ if (!language || signal?.aborted) return Promise.resolve({ status: signal?.aborted ? 'aborted' : 'unsupported' });
30
+ return new Promise(resolve => {
31
+ let child;
32
+ let settled = false;
33
+ let failure;
34
+ let bytes = 0;
35
+ const chunks = [];
36
+ const finish = result => {
37
+ if (settled) return;
38
+ settled = true;
39
+ clearTimeout(timer);
40
+ clearTimeout(killTimer);
41
+ signal?.removeEventListener('abort', abort);
42
+ resolve(result);
43
+ };
44
+ let killTimer;
45
+ const stop = status => {
46
+ if (settled || failure) return;
47
+ failure = status;
48
+ child?.kill('SIGKILL');
49
+ // Do not hold a read hook indefinitely if the platform never emits close.
50
+ killTimer = setTimeout(() => finish({ status }), 100);
51
+ };
52
+ const abort = () => stop('aborted');
53
+ const timer = setTimeout(() => stop('timeout'), timeoutMs);
54
+ signal?.addEventListener('abort', abort, { once: true });
55
+ try {
56
+ const env = Object.fromEntries(Object.entries(process.env).filter(([name, value]) =>
57
+ value !== undefined && !/KEY|PASSWORD|SECRET|TOKEN/i.test(name) && !/^DSH_/i.test(name)
58
+ ));
59
+ child = spawn(command, [
60
+ 'outline', '--stdin', '--lang', language, '--json=compact', '--view', 'expanded', '--items', 'structure',
61
+ '--config', CONFIG_PATH, '--custom-languages', 'ignore', '--color', 'never', '--threads', '1'
62
+ ], { cwd: CLI_CWD, env, shell: false, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] });
63
+ child.once('error', error => finish({ status: error.code === 'ENOENT' ? 'unavailable' : 'error' }));
64
+ child.stdin.on('error', () => {});
65
+ child.stdout.on('data', chunk => {
66
+ bytes += chunk.length;
67
+ if (bytes > maxOutputBytes) stop('output-limit');
68
+ else chunks.push(chunk);
69
+ });
70
+ // Drain diagnostics without retaining or exposing source excerpts.
71
+ child.stderr.on('data', () => {});
72
+ child.once('close', code => {
73
+ if (failure) return finish({ status: failure });
74
+ if (code !== 0) return finish({ status: 'error' });
75
+ try {
76
+ const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
77
+ const entries = parseAstEntries(value, content.split('\n').length);
78
+ // Bundled outline rules expose TS namespaces without their children.
79
+ // Preserve lexically recognized children inside these AST-confirmed scopes.
80
+ if (language === 'typescript') {
81
+ const modules = value[0].items.filter(item => item.symbolType === 'module');
82
+ if (modules.length) {
83
+ const lexical = buildCodeOutline(content, filePath);
84
+ for (const item of modules) {
85
+ const start = item.range.start.line + 1;
86
+ const end = item.range.end?.line + 1;
87
+ for (const entry of lexical.entries) {
88
+ if (entry.line > start && entry.line <= end && !entries.some(existing => existing.line === entry.line)) {
89
+ entries.push({ ...entry, nested: true });
90
+ }
91
+ }
92
+ }
93
+ entries.sort((a, b) => a.line - b.line);
94
+ }
95
+ }
96
+ finish({ status: 'ok', entries });
97
+ } catch { finish({ status: 'invalid-output' }); }
98
+ });
99
+ child.stdin.end(content, 'utf8');
100
+ if (signal?.aborted) abort();
101
+ } catch { finish({ status: 'error' }); }
102
+ });
103
+ }
104
+
105
+ export function parseAstEntries(value, totalLines) {
106
+ if (!Array.isArray(value) || value.length !== 1 || !Array.isArray(value[0]?.items)) throw new Error('Invalid AST outline shape');
107
+ const entries = [];
108
+ const visit = (items, nested = false, depth = 0) => {
109
+ if (depth > 32) throw new Error('AST outline depth exceeded');
110
+ for (const item of items) {
111
+ if (item.isImport || item.role === 'import') continue;
112
+ const line = item.range?.start?.line;
113
+ if (!Number.isInteger(line) || line < 0 || line >= totalLines || typeof item.signature !== 'string') throw new Error('Invalid AST item');
114
+ let text = item.signature.replace(/\s+/g, ' ').trim();
115
+ if (!text) continue;
116
+ if (item.isExported && !/^(?:export\b|pub\b)/.test(text)) text = `export ${text}`;
117
+ entries.push({ line: line + 1, text: text.length > 96 ? `${text.slice(0, 93)}...` : text, nested });
118
+ if (Array.isArray(item.members)) visit(item.members, true, depth + 1);
119
+ if (Array.isArray(item.children)) visit(item.children, true, depth + 1);
120
+ }
121
+ };
122
+ visit(value[0].items);
123
+ return entries.sort((a, b) => a.line - b.line);
124
+ }
125
+
126
+ export async function buildAdaptiveOutline(content, filePath, options = {}, signal, stats) {
127
+ const lexical = buildCodeOutline(content, filePath);
128
+ if (!needsAstOutline(content, filePath, lexical, options.astOutline ?? 'auto')) return { ...lexical, engine: 'lexical' };
129
+ if (stats) stats.astAttempts++;
130
+ const result = await runAstOutline(content, filePath, {
131
+ command: options.astGrepCommand, timeoutMs: options.astTimeoutMs,
132
+ maxOutputBytes: options.astMaxOutputBytes, signal
133
+ });
134
+ if (result.status === 'ok') {
135
+ if (stats) stats.astSucceeded++;
136
+ return { entries: result.entries, totalLines: lexical.totalLines, engine: 'ast', astStatus: 'ok' };
137
+ }
138
+ if (stats) {
139
+ stats.astFallbacks++;
140
+ if (result.status === 'timeout') stats.astTimeouts++;
141
+ }
142
+ return { ...lexical, engine: 'lexical', astStatus: result.status };
143
+ }
@@ -0,0 +1,218 @@
1
+ import { AsyncLocalStorage } from 'node:async_hooks';
2
+ import { createHash, randomUUID } from 'node:crypto';
3
+ import { mkdirSync, statSync } from 'node:fs';
4
+ import { appendFile } from 'node:fs/promises';
5
+ import path from 'node:path';
6
+
7
+ const scope = new AsyncLocalStorage();
8
+ const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
9
+ let users = 0;
10
+ let originalFetch;
11
+ let wrappedFetch;
12
+ const MAX_EVENT = 1024 * 1024;
13
+
14
+ function numericUsage(value, depth = 0) {
15
+ if (!value || typeof value !== 'object' || depth > 2) return {};
16
+ const out = {};
17
+ for (const key of ['prompt_tokens', 'completion_tokens', 'total_tokens', 'cached_tokens',
18
+ 'prompt_cache_hit_tokens', 'prompt_cache_miss_tokens', 'input_tokens', 'output_tokens',
19
+ 'cache_read_input_tokens', 'cache_creation_input_tokens', 'prompt_tokens_details',
20
+ 'input_tokens_details', 'reasoning_tokens']) {
21
+ const item = value[key];
22
+ if (typeof item === 'number' && Number.isFinite(item)) out[key] = item;
23
+ else if (item && typeof item === 'object') out[key] = numericUsage(item, depth + 1);
24
+ }
25
+ return out;
26
+ }
27
+
28
+ function identifier(value) {
29
+ return typeof value === 'string' && value.length <= 256 && /^[\w.:/-]+$/.test(value) ? value : null;
30
+ }
31
+
32
+ function preserveMetadata(target, source) {
33
+ for (const key of ['url', 'redirected', 'type']) {
34
+ Object.defineProperty(target, key, { value: source[key], configurable: true });
35
+ }
36
+ const clone = target.clone.bind(target);
37
+ Object.defineProperty(target, 'clone', { value: () => preserveMetadata(clone(), source), configurable: true });
38
+ return target;
39
+ }
40
+
41
+ // One transport wrapper; only fetches inside an explicitly enabled LLM scope are observed.
42
+ function acquire() {
43
+ if (users++ !== 0) return;
44
+ originalFetch = globalThis.fetch;
45
+ const delegate = originalFetch;
46
+ wrappedFetch = async function (input, init) {
47
+ const active = scope.getStore();
48
+ if (!active || active.owner.closed || active.owner.stopped) return delegate(input, init);
49
+ let record;
50
+ try {
51
+ const url = new URL(typeof input === 'string' || input instanceof URL ? input : input.url);
52
+ if (!url.pathname.endsWith('/chat/completions') || typeof init?.body !== 'string') {
53
+ return delegate(input, init);
54
+ }
55
+ const body = JSON.parse(init.body);
56
+ if (!Array.isArray(body.messages)) return delegate(input, init);
57
+ record = active.owner.request(active.session, body, url);
58
+ } catch { /* Observation must not fail inference. */ }
59
+ let response;
60
+ try { response = await delegate(input, init); }
61
+ catch (error) {
62
+ if (record) active.owner.emit({ type: 'transport-error', request: record.request });
63
+ throw error;
64
+ }
65
+ if (!record) return response;
66
+ active.owner.emit({ type: 'response', request: record.request, status: response.status,
67
+ requestId: identifier(response.headers.get('x-request-id') ?? response.headers.get('request-id')) });
68
+ if (!response.body) return response;
69
+ const contentType = response.headers.get('content-type') ?? '';
70
+ if (!contentType.includes('text/event-stream') && !contentType.includes('application/json')) return response;
71
+ const decoder = new TextDecoder();
72
+ let pending = '';
73
+ let dropped = false;
74
+ const observe = text => {
75
+ try {
76
+ const event = JSON.parse(text);
77
+ if (event.usage) active.owner.emit({ type: 'usage', request: record.request,
78
+ usage: numericUsage(event.usage), responseId: identifier(event.id),
79
+ model: identifier(event.model), systemFingerprint: identifier(event.system_fingerprint) });
80
+ } catch { /* Ignore non-JSON events such as [DONE]. */ }
81
+ };
82
+ const inspect = (bytes, final = false) => {
83
+ if (dropped) return;
84
+ pending += decoder.decode(bytes, { stream: !final });
85
+ if (pending.length > MAX_EVENT) {
86
+ dropped = true;
87
+ pending = '';
88
+ active.owner.emit({ type: 'capture-gap', request: record.request, reason: 'event-size-limit' });
89
+ return;
90
+ }
91
+ if (contentType.includes('text/event-stream')) {
92
+ pending = pending.replace(/\r\n/g, '\n');
93
+ let end = pending.indexOf('\n\n');
94
+ while (end !== -1) {
95
+ const event = pending.slice(0, end);
96
+ pending = pending.slice(end + 2);
97
+ observe(event.split('\n').filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart()).join('\n'));
98
+ end = pending.indexOf('\n\n');
99
+ }
100
+ } else if (final) observe(pending);
101
+ };
102
+ const stream = response.body.pipeThrough(new TransformStream({
103
+ transform(chunk, controller) {
104
+ try { inspect(chunk); } catch { /* Preserve the original stream. */ }
105
+ controller.enqueue(chunk);
106
+ },
107
+ flush() {
108
+ try { inspect(undefined, true); } catch { /* Preserve stream completion. */ }
109
+ active.owner.emit({ type: 'complete', request: record.request, captureGap: dropped });
110
+ }
111
+ }));
112
+ return preserveMetadata(new Response(stream, { status: response.status, statusText: response.statusText, headers: response.headers }), response);
113
+ };
114
+ globalThis.fetch = wrappedFetch;
115
+ }
116
+
117
+ export class CacheDiagnostics {
118
+ constructor(filePath, { sink, maxBytes = 8 * 1024 * 1024, onStop, maxQueuedBytes = 256 * 1024, writer = appendFile } = {}) {
119
+ this.previous = new Map();
120
+ this.onStop = onStop;
121
+ this.stopped = false;
122
+ this.maxQueuedBytes = maxQueuedBytes;
123
+ this.queuedBytes = 0;
124
+ this.pending = Promise.resolve();
125
+ this.writer = writer;
126
+ this.closed = false;
127
+ this.maxBytes = maxBytes;
128
+ this.bytes = 0;
129
+ this.sink = sink;
130
+ this.filePath = filePath;
131
+ if (!sink) {
132
+ if (!path.isAbsolute(filePath)) throw new Error('Cache diagnostic path must be absolute');
133
+ mkdirSync(path.dirname(filePath), { recursive: true });
134
+ try { this.bytes = statSync(filePath).size; } catch (error) { if (error.code !== 'ENOENT') throw error; }
135
+ }
136
+ acquire();
137
+ }
138
+
139
+ stop(reason) {
140
+ if (this.stopped) return;
141
+ this.stopped = true;
142
+ this.previous.clear();
143
+ try { this.onStop?.(reason); } catch {}
144
+ }
145
+
146
+ flush() { return this.pending; }
147
+
148
+ emit(record) {
149
+ if (this.closed || this.stopped) return;
150
+ try {
151
+ const line = JSON.stringify({ time: new Date().toISOString(), ...record }) + '\n';
152
+ const bytes = Buffer.byteLength(line);
153
+ if (this.bytes + bytes > this.maxBytes) { this.stop('file-size-limit'); return; }
154
+ if (!this.sink && this.queuedBytes + bytes > this.maxQueuedBytes) { this.stop('queue-size-limit'); return; }
155
+ this.bytes += bytes;
156
+ if (this.sink) this.sink(JSON.parse(line));
157
+ else {
158
+ this.queuedBytes += bytes;
159
+ this.pending = this.pending.then(async () => {
160
+ try {
161
+ if (!this.writeFailed) await this.writer(this.filePath, line, { encoding: 'utf8', mode: 0o600 });
162
+ } catch { this.writeFailed = true; this.stop('write-failed'); }
163
+ finally { this.queuedBytes -= bytes; }
164
+ });
165
+ }
166
+ } catch { this.stop('observer-failed'); }
167
+ }
168
+
169
+ request(session, body, url) {
170
+ const messages = body.messages.map(digest);
171
+ const { messages: ignored, ...config } = body;
172
+ const configDigest = digest(config);
173
+ const key = digest([session, url.origin, url.pathname, body.model]);
174
+ const previous = this.previous.get(key);
175
+ let firstDifference = null;
176
+ if (previous) {
177
+ for (let i = 0; i < previous.messages.length; i++) {
178
+ if (messages[i] !== previous.messages[i]) { firstDifference = i; break; }
179
+ }
180
+ }
181
+ const record = { type: 'request', request: randomUUID(), session: digest(session),
182
+ endpoint: digest(url.origin + url.pathname), model: identifier(body.model),
183
+ messages, configDigest, toolsDigest: body.tools === undefined ? null : digest(body.tools),
184
+ cacheKeyDigest: body.prompt_cache_key === undefined ? null : digest(body.prompt_cache_key),
185
+ previousRequest: previous?.request ?? null, firstDifference,
186
+ prefixStable: previous ? firstDifference === null : null,
187
+ configStable: previous ? configDigest === previous.configDigest : null };
188
+ this.previous.delete(key);
189
+ this.previous.set(key, record);
190
+ if (this.previous.size > 128) this.previous.delete(this.previous.keys().next().value);
191
+ this.emit(record);
192
+ return record;
193
+ }
194
+
195
+ wrap(session, next) {
196
+ if (session === undefined || session === null || this.closed) return next();
197
+ const active = { owner: this, session: String(session) };
198
+ return (async function* () {
199
+ const stream = scope.run(active, next);
200
+ const iterator = stream[Symbol.asyncIterator]();
201
+ try {
202
+ while (true) {
203
+ const result = await scope.run(active, () => iterator.next());
204
+ if (result.done) return;
205
+ yield result.value;
206
+ }
207
+ } finally { if (iterator.return) await scope.run(active, () => iterator.return()); }
208
+ })();
209
+ }
210
+
211
+ dispose() {
212
+ if (this.closed) return this.flush();
213
+ this.closed = true;
214
+ this.previous.clear();
215
+ if (--users === 0 && globalThis.fetch === wrappedFetch) globalThis.fetch = originalFetch;
216
+ return this.flush();
217
+ }
218
+ }