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,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
+ }
package/src/index.d.ts CHANGED
@@ -2,6 +2,8 @@ import type { Context } from '@deepseek-ai/cordis';
2
2
  import type z from '@deepseek-ai/schemastery';
3
3
  import type { RuntimePolicyOptions } from './runtime-policy.d.ts';
4
4
  import type { FileMutationPolicyOptions } from './file-mutation-policy.d.ts';
5
+ import type { EditRecoveryOptions } from './edit-recovery.d.ts';
6
+ import type { ReadGuardOptions } from './read-guard.d.ts';
5
7
  import type { CompositeToolsOptions } from './composite-tools.d.ts';
6
8
  import type { PersistentEvalOptions, PersistentEvalService } from './persistent-eval/index.d.ts';
7
9
  import type { ConvergenceOptions } from './convergence.d.ts';
@@ -15,6 +17,8 @@ export interface AgentOptimizerConfig {
15
17
  fileMutationPolicy?: FileMutationPolicyOptions;
16
18
  mutationPolicy?: FileMutationPolicyOptions;
17
19
  recoverFailedWrites?: boolean;
20
+ editRecovery?: EditRecoveryOptions;
21
+ readGuard?: ReadGuardOptions;
18
22
  compositeTools?: CompositeToolsOptions;
19
23
  persistentEval?: PersistentEvalOptions;
20
24
  convergence?: ConvergenceOptions;
@@ -56,11 +60,39 @@ export {
56
60
  type FailureRecoveryService
57
61
  } from './failure-recovery.d.ts';
58
62
  export {
59
- READ_BATCH_TOOL,
63
+ EditRecoveryConfig,
64
+ isEditMatchFailure,
65
+ findBestEditMatch,
66
+ buildEditFailureHint,
67
+ applyEditRecovery,
68
+ type EditRecoveryOptions,
69
+ type EditRecoveryStats,
70
+ type EditMatchLocation,
71
+ type EditMatchResult,
72
+ type EditRecoveryService
73
+ } from './edit-recovery.d.ts';
74
+ export {
75
+ READ_GUARD_SOURCE,
76
+ ReadGuardConfig,
77
+ truncateLongLines,
78
+ extractCodeOutline,
79
+ formatCodeOutline,
80
+ applyReadGuard,
81
+ type ReadGuardOptions,
82
+ type ReadGuardStats,
83
+ type ReadGuardService,
84
+ type OutlineEntry
85
+ } from './read-guard.d.ts';
86
+ export {
87
+ FIND_AND_READ_TOOL,
60
88
  EDIT_BATCH_TOOL,
89
+ parseGrepOutput,
90
+ mergeMatchWindows,
61
91
  type CompositeToolsOptions,
62
92
  type CompositeToolsStats,
63
- type CompositeToolsService
93
+ type CompositeToolsService,
94
+ type ParsedGrepMatch,
95
+ type MergedMatchWindow
64
96
  } from './composite-tools.d.ts';
65
97
  export {
66
98
  SOURCE as CONVERGENCE_SOURCE,
package/src/index.js CHANGED
@@ -2,7 +2,10 @@ import z from '@deepseek-ai/schemastery';
2
2
  import { applyRuntimePolicy, RuntimePolicyConfig, RuntimePolicyManager, POLICY_SOURCE } from './runtime-policy.js';
3
3
  import { applyFileMutationPolicy, FileMutationPolicyConfig, FileMutationPolicyManager, MUTATION_SOURCE } from './file-mutation-policy.js';
4
4
  import { applyFailureRecovery, RecoveryRecord, RECOVERY_SOURCE, RETRY_TOOL, PAIRING_ERROR } from './failure-recovery.js';
5
- import { applyCompositeTools, CompositeToolsConfig, READ_BATCH_TOOL, EDIT_BATCH_TOOL } from './composite-tools.js';
5
+ import { applyEditRecovery, EditRecoveryConfig, isEditMatchFailure, findBestEditMatch, buildEditFailureHint } from './edit-recovery.js';
6
+ import { applyCompositeTools, CompositeToolsConfig, FIND_AND_READ_TOOL, EDIT_BATCH_TOOL, parseGrepOutput, mergeMatchWindows } from './composite-tools.js';
7
+ import { applyReadGuard, ReadGuardConfig, READ_GUARD_SOURCE, truncateLongLines } from './read-guard.js';
8
+ import { extractCodeOutline, formatCodeOutline } from './code-outline.js';
6
9
  import { applyPersistentEval, PersistentEvalConfig, EVAL_PYTHON_TOOL, EVAL_NODE_TOOL, formatEvalOutput, StdioWorkerRunner, DaemonPool } from './persistent-eval/index.js';
7
10
  import { applyConvergence, ConvergenceConfig, SOURCE as CONVERGENCE_SOURCE, GUIDANCE, REMINDER } from './convergence.js';
8
11
  import { applyCustomPrompt, CustomPromptConfig, CustomPromptManager, SECTION_NAME as CUSTOM_PROMPT_SECTION, ENVIRONMENT_FACTS_SECTION, formatEnvironmentFacts, detectPythonEnv, resetPythonCacheForTesting } from './custom-prompt.js';
@@ -20,6 +23,8 @@ export const Config = z.object({
20
23
  fileMutationPolicy: FileMutationPolicyConfig.default({}),
21
24
  mutationPolicy: FileMutationPolicyConfig.default({}),
22
25
  recoverFailedWrites: z.boolean().default(true),
26
+ editRecovery: EditRecoveryConfig.default({}),
27
+ readGuard: ReadGuardConfig.default({}),
23
28
  compositeTools: CompositeToolsConfig.default({}),
24
29
  persistentEval: PersistentEvalConfig.default({}),
25
30
  convergence: ConvergenceConfig.default({}),
@@ -53,6 +58,14 @@ export function apply(ctx, raw = {}) {
53
58
  if (recoveryService) ctx.provide('failureRecovery', recoveryService);
54
59
  }
55
60
 
61
+ const editRecoveryConfig = raw.editRecovery ?? config.editRecovery ?? {};
62
+ const editRecoveryService = applyEditRecovery(ctx, editRecoveryConfig);
63
+ if (editRecoveryService) ctx.provide('editRecovery', editRecoveryService);
64
+
65
+ const readGuardConfig = raw.readGuard ?? config.readGuard ?? {};
66
+ const readGuardService = applyReadGuard(ctx, readGuardConfig);
67
+ if (readGuardService) ctx.provide('readGuard', readGuardService);
68
+
56
69
  const compositeConfig = raw.compositeTools ?? config.compositeTools ?? {};
57
70
  const compositeService = applyCompositeTools(ctx, compositeConfig);
58
71
  if (compositeService) ctx.provide('compositeTools', compositeService);
@@ -60,10 +73,8 @@ export function apply(ctx, raw = {}) {
60
73
  const evalConfig = raw.persistentEval ?? config.persistentEval ?? {};
61
74
  const evalService = applyPersistentEval(ctx, evalConfig);
62
75
  if (evalService) {
63
- ctx.provide('persistentEval');
64
- ctx.persistentEval = evalService;
76
+ ctx.provide('persistentEval', evalService);
65
77
  }
66
-
67
78
  const convergenceConfig = raw.convergence ?? config.convergence ?? {};
68
79
  const convergenceService = applyConvergence(ctx, convergenceConfig);
69
80
  if (convergenceService) ctx.provide('convergenceGuidance', convergenceService);
@@ -83,8 +94,16 @@ export {
83
94
  RecoveryRecord,
84
95
  AgentTelemetryManager,
85
96
  compareTurnSummaries,
86
- READ_BATCH_TOOL,
97
+ FIND_AND_READ_TOOL,
87
98
  EDIT_BATCH_TOOL,
99
+ parseGrepOutput,
100
+ mergeMatchWindows,
101
+ truncateLongLines,
102
+ applyReadGuard,
103
+ ReadGuardConfig,
104
+ READ_GUARD_SOURCE,
105
+ extractCodeOutline,
106
+ formatCodeOutline,
88
107
  EVAL_PYTHON_TOOL,
89
108
  EVAL_NODE_TOOL,
90
109
  formatEvalOutput,
@@ -94,6 +113,11 @@ export {
94
113
  DaemonPool,
95
114
  RETRY_TOOL,
96
115
  PAIRING_ERROR,
116
+ applyEditRecovery,
117
+ EditRecoveryConfig,
118
+ isEditMatchFailure,
119
+ findBestEditMatch,
120
+ buildEditFailureHint,
97
121
  CONVERGENCE_SOURCE,
98
122
  RECOVERY_SOURCE,
99
123
  POLICY_SOURCE,
@@ -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
+ }
@@ -1,7 +1,7 @@
1
1
  import path from 'node:path';
2
2
  import { fileURLToPath } from 'node:url';
3
+ import { detectPythonEnv } from '../custom-prompt.js';
3
4
  import { StdioWorkerRunner } from './stdio-runner.js';
4
-
5
5
  const __filename = fileURLToPath(import.meta.url);
6
6
  const __dirname = path.dirname(__filename);
7
7
 
@@ -36,8 +36,9 @@ export class DaemonPool {
36
36
  }
37
37
 
38
38
  if (!sessionMap.python || sessionMap.python.isDestroyed) {
39
+ const pythonBin = this.config.pythonCommand || detectPythonEnv()?.bin || 'python';
39
40
  sessionMap.python = new StdioWorkerRunner({
40
- command: 'python',
41
+ command: pythonBin,
41
42
  args: ['-u', PY_WORKER_SCRIPT],
42
43
  timeoutMs: this.config.timeoutMs,
43
44
  maxOutputBytes: this.config.maxOutputBytes
@@ -8,6 +8,7 @@ export interface PersistentEvalOptions {
8
8
  enabled?: boolean;
9
9
  python?: boolean;
10
10
  node?: boolean;
11
+ pythonCommand?: string;
11
12
  timeoutMs?: number;
12
13
  maxOutputBytes?: number;
13
14
  }
@@ -28,25 +29,51 @@ export interface PersistentEvalResponse {
28
29
  export declare function formatEvalOutput(resp: PersistentEvalResponse | null | undefined): string;
29
30
 
30
31
  export interface PersistentEvalService {
31
- pool: any;
32
+ pool: DaemonPool;
32
33
  config: PersistentEvalOptions;
33
34
  prewarm(session?: unknown): Promise<void>;
34
35
  destroy(): void;
35
36
  }
36
37
 
38
+ export interface StdioWorkerRunnerOptions {
39
+ command: string;
40
+ args?: string[];
41
+ timeoutMs?: number;
42
+ maxOutputBytes?: number;
43
+ env?: Record<string, string | undefined>;
44
+ }
45
+
46
+ export interface StdioWorkerExecuteOptions {
47
+ action?: 'eval' | 'ping' | 'reset';
48
+ /** Session working directory to apply before reset or evaluation. */
49
+ cwd?: string;
50
+ reset?: boolean;
51
+ timeoutMs?: number;
52
+ signal?: AbortSignal;
53
+ }
54
+
55
+ export interface DaemonPoolConfig {
56
+ pythonCommand?: string;
57
+ timeoutMs?: number;
58
+ maxOutputBytes?: number;
59
+ }
60
+
37
61
  export declare class StdioWorkerRunner {
38
- constructor(options: any);
62
+ isReady: boolean;
63
+ isDestroyed: boolean;
64
+ launchCount: number;
65
+ constructor(options: StdioWorkerRunnerOptions);
39
66
  ensureStarted(): Promise<void>;
40
- execute(code: string, options?: any): Promise<PersistentEvalResponse>;
67
+ execute(code: string, options?: StdioWorkerExecuteOptions): Promise<PersistentEvalResponse>;
41
68
  destroy(): void;
42
69
  }
43
70
 
44
71
  export declare class DaemonPool {
45
- constructor(config?: any);
46
- prewarm(session?: any, options?: { python?: boolean; node?: boolean }): Promise<void>;
47
- getPythonRunner(session?: any): StdioWorkerRunner;
48
- getNodeRunner(session?: any): StdioWorkerRunner;
49
- destroySession(session?: any): void;
72
+ constructor(config?: DaemonPoolConfig);
73
+ prewarm(session?: unknown, options?: { python?: boolean; node?: boolean }): Promise<void>;
74
+ getPythonRunner(session?: unknown): StdioWorkerRunner;
75
+ getNodeRunner(session?: unknown): StdioWorkerRunner;
76
+ destroySession(session?: unknown): void;
50
77
  destroyAll(): void;
51
78
  }
52
79
 
@@ -10,6 +10,7 @@ export const PersistentEvalConfig = z.object({
10
10
  enabled: z.boolean().default(true),
11
11
  python: z.boolean().default(true),
12
12
  node: z.boolean().default(true),
13
+ pythonCommand: z.string(),
13
14
  timeoutMs: z.number().step(1).min(50).max(120000).default(15000),
14
15
  maxOutputBytes: z.number().step(1).min(64).max(65536).default(8192)
15
16
  });
@@ -72,30 +73,52 @@ export function applyPersistentEval(ctx, rawConfig = {}) {
72
73
  if (!config.enabled) return null;
73
74
 
74
75
  const pool = new DaemonPool({
76
+ pythonCommand: config.pythonCommand,
75
77
  timeoutMs: config.timeoutMs,
76
78
  maxOutputBytes: config.maxOutputBytes
77
79
  });
78
80
 
81
+ const workingDirectories = new Map();
82
+ const sessionKey = session => session?.id || session || '__global__';
83
+ function getWorkingDirectory(session) {
84
+ const key = sessionKey(session);
85
+ if (!workingDirectories.has(key)) {
86
+ const service = typeof ctx.get === 'function' ? ctx.get('workingDirectory') : ctx.workingDirectory;
87
+ const cwd = service?.get?.(session);
88
+ if (cwd !== undefined) workingDirectories.set(key, cwd);
89
+ }
90
+ return workingDirectories.get(key);
91
+ }
92
+ function destroySession(session) {
93
+ workingDirectories.delete(sessionKey(session));
94
+ pool.destroySession(session);
95
+ }
96
+ function destroy() {
97
+ workingDirectories.clear();
98
+ pool.destroyAll();
99
+ }
100
+
79
101
  // Clean up session workers when session ends & prewarm on session/turn starts
80
102
  ctx.on('session/event', (session, event) => {
81
103
  if (event?.type === 'session/destroy' || event?.type === 'session/close') {
82
- pool.destroySession(session);
104
+ destroySession(session);
105
+ } else if (event?.type === 'working-directory/change') {
106
+ workingDirectories.set(sessionKey(session), event.data.cwd);
83
107
  } else if (event?.type === 'turn/start' || event?.type === 'session/start' || event?.type === 'session/create') {
84
108
  pool.prewarm(session, { python: config.python, node: config.node });
85
109
  }
86
110
  });
87
111
 
112
+ ctx.on('session/disposed', destroySession);
113
+
88
114
  // Pre-warm on turn/start event so worker processes are already hot during model inference
89
115
  ctx.on('turn/start', (turn) => {
90
- const session = turn?.session;
116
+ const session = turn?.agent?.session ?? turn?.session;
91
117
  pool.prewarm(session, { python: config.python, node: config.node });
92
118
  });
93
-
94
119
  // Clean up all daemon workers when plugin context is disposed
95
120
  if (typeof ctx.effect === 'function') {
96
- ctx.effect(() => () => {
97
- pool.destroyAll();
98
- });
121
+ ctx.effect(() => destroy);
99
122
  }
100
123
 
101
124
  if (config.python) {
@@ -104,8 +127,9 @@ export function applyPersistentEval(ctx, rawConfig = {}) {
104
127
  description: [
105
128
  'Execute Python code inside a persistent stateful kernel.',
106
129
  'Variables, functions, imports, and state persist across calls within the session.',
107
- 'Standard modules (math, re, json, time, collections, itertools) are eagerly pre-imported in scope.',
108
- 'Use for exploratory calculations, data processing, kinematic/algorithmic solving, and intermediate analysis without writing temp files to disk.'
130
+ 'Standard modules (math, re, json, time, collections, itertools, pathlib, difflib, csv) are eagerly pre-imported in scope.',
131
+ 'The session working directory is synchronized before execution and exposed as CWD.',
132
+ 'Use for exploratory calculations, data processing, and read-only project analysis (e.g. i18n key alignment or code metrics); return compact summaries without writing temp files to disk.'
109
133
  ].join(' '),
110
134
  parameters: {
111
135
  type: 'object',
@@ -129,11 +153,17 @@ export function applyPersistentEval(ctx, rawConfig = {}) {
129
153
  isConcurrencySafe: () => false,
130
154
  async execute(args, exec) {
131
155
  exec?.signal?.throwIfAborted();
132
- const runner = pool.getPythonRunner(exec?.session);
156
+ const session = exec?.agent?.session ?? exec?.session;
157
+ const runner = pool.getPythonRunner(session);
133
158
  const code = args?.code || '';
134
159
  const reset = Boolean(args?.reset);
135
160
 
136
- const response = await runner.execute(code, { reset, timeoutMs: config.timeoutMs });
161
+ const response = await runner.execute(code, {
162
+ cwd: getWorkingDirectory(session),
163
+ reset,
164
+ timeoutMs: config.timeoutMs,
165
+ signal: exec?.signal
166
+ });
137
167
  return formatEvalOutput(response);
138
168
  }
139
169
  });
@@ -144,7 +174,8 @@ export function applyPersistentEval(ctx, rawConfig = {}) {
144
174
  name: EVAL_NODE_TOOL,
145
175
  description: [
146
176
  'Execute JavaScript code inside a persistent stateful Node.js VM context.',
147
- 'Variables, functions, and state persist across calls within the session. Supports top-level await.',
177
+ 'Top-level declarations persist across synchronous calls; when using top-level await, assign shared state to globalThis (e.g. globalThis.x = await ...) to persist across turns.',
178
+ 'The session working directory is synchronized before execution and exposed as CWD.',
148
179
  'Use for rapid expression evaluation, AST exploration, and data transformations without writing temp files to disk.'
149
180
  ].join(' '),
150
181
  parameters: {
@@ -169,11 +200,17 @@ export function applyPersistentEval(ctx, rawConfig = {}) {
169
200
  isConcurrencySafe: () => false,
170
201
  async execute(args, exec) {
171
202
  exec?.signal?.throwIfAborted();
172
- const runner = pool.getNodeRunner(exec?.session);
203
+ const session = exec?.agent?.session ?? exec?.session;
204
+ const runner = pool.getNodeRunner(session);
173
205
  const code = args?.code || '';
174
206
  const reset = Boolean(args?.reset);
175
207
 
176
- const response = await runner.execute(code, { reset, timeoutMs: config.timeoutMs });
208
+ const response = await runner.execute(code, {
209
+ cwd: getWorkingDirectory(session),
210
+ reset,
211
+ timeoutMs: config.timeoutMs,
212
+ signal: exec?.signal
213
+ });
177
214
  return formatEvalOutput(response);
178
215
  }
179
216
  });
@@ -185,8 +222,6 @@ export function applyPersistentEval(ctx, rawConfig = {}) {
185
222
  prewarm(session) {
186
223
  return pool.prewarm(session, { python: config.python, node: config.node });
187
224
  },
188
- destroy() {
189
- pool.destroyAll();
190
- }
225
+ destroy
191
226
  };
192
227
  }