@hy-sde-org/dsh-code-runtime-kernels 0.2.1-rc.3 → 0.2.2-rc.1
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/README.md +15 -6
- package/README.zh.md +15 -6
- package/dist/core/kernel.d.ts +53 -12
- package/dist/core/kernel.d.ts.map +1 -1
- package/dist/core/kernel.js +224 -43
- package/dist/core/kernel.js.map +1 -1
- package/dist/core/protocol.d.ts +12 -0
- package/dist/core/protocol.d.ts.map +1 -1
- package/dist/core/python-discovery.d.ts +52 -0
- package/dist/core/python-discovery.d.ts.map +1 -0
- package/dist/core/python-discovery.js +142 -0
- package/dist/core/python-discovery.js.map +1 -0
- package/dist/core/session.d.ts +17 -5
- package/dist/core/session.d.ts.map +1 -1
- package/dist/core/session.js +108 -58
- package/dist/core/session.js.map +1 -1
- package/dist/index.d.ts +54 -28
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +328 -129
- package/dist/index.js.map +1 -1
- package/dist/nodejs/runner.js +69 -43
- package/dist/nodejs/runner.js.map +1 -1
- package/dist/python/runner.d.ts.map +1 -1
- package/dist/python/runner.js +42 -11
- package/dist/python/runner.js.map +1 -1
- package/package.json +22 -19
package/dist/index.js
CHANGED
|
@@ -14,11 +14,13 @@ import { createHash, randomUUID } from 'node:crypto';
|
|
|
14
14
|
import { homedir } from 'node:os';
|
|
15
15
|
import { join, resolve, sep } from 'node:path';
|
|
16
16
|
import { inspect } from 'node:util';
|
|
17
|
+
import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess';
|
|
17
18
|
import z from '@deepseek-ai/schemastery';
|
|
18
19
|
import { DUNDER_MEMBER, PORTABLE_RESERVED_WORDS, RESERVED_BINDING_GLOBALS, RESERVED_ERROR_MEMBERS, } from '@deepseek-ai/dsh-ptc-runtime';
|
|
19
20
|
import { defineTool } from '@deepseek-ai/dsh-tools';
|
|
20
21
|
import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout';
|
|
21
22
|
import { KernelHost, nodejsKernelProfile } from "./core/kernel.js";
|
|
23
|
+
import { enumeratePythonCandidates, resolvePythonCommand } from "./core/python-discovery.js";
|
|
22
24
|
import { SessionRegistry } from "./core/session.js";
|
|
23
25
|
import { PYTHON_RUNNER } from "./python/runner.js";
|
|
24
26
|
/** Cordis plugin name for loader diagnostics. */
|
|
@@ -29,6 +31,7 @@ export const inject = ['tools', 'systemPrompt'];
|
|
|
29
31
|
export const Config = z.object({
|
|
30
32
|
languages: z.array(z.union(['python', 'typescript'])).default(['python', 'typescript']),
|
|
31
33
|
pythonPath: z.string(),
|
|
34
|
+
pythonProbeTimeoutMs: z.number().default(5_000),
|
|
32
35
|
pythonImpl: z.union(['stdlib', 'ipykernel']).default('stdlib'),
|
|
33
36
|
nodePath: z.string(),
|
|
34
37
|
toolTimeoutMs: z.number().default(30_000),
|
|
@@ -101,34 +104,70 @@ class OutputLedger {
|
|
|
101
104
|
/** Finalize a successful absent-or-JSON completion against the combined cap. */
|
|
102
105
|
success(logs, value) {
|
|
103
106
|
const clipped = this.clipLogs(logs);
|
|
104
|
-
if (value === undefined)
|
|
107
|
+
if (value === undefined) {
|
|
108
|
+
if (this.logBytes(clipped) > this.maxBytes)
|
|
109
|
+
return this.outputLimit(clipped);
|
|
105
110
|
return { logs: clipped };
|
|
111
|
+
}
|
|
106
112
|
const valueBytes = this.compactJsonBytes(value);
|
|
107
113
|
if (valueBytes === undefined || valueBytes > this.maxBytes)
|
|
108
|
-
return this.
|
|
109
|
-
|
|
114
|
+
return this.outputLimit(clipped);
|
|
115
|
+
if (this.logBytes(clipped) + valueBytes <= this.maxBytes)
|
|
116
|
+
return { logs: clipped, value };
|
|
117
|
+
return this.outputLimit(clipped);
|
|
110
118
|
}
|
|
111
|
-
/**
|
|
119
|
+
/**
|
|
120
|
+
* Finalize a failure diagnostic against the combined cap. A diagnostic that
|
|
121
|
+
* fits outranks logs; any combined overflow becomes `output-limit`.
|
|
122
|
+
*/
|
|
112
123
|
failure(logs, error) {
|
|
113
124
|
const clipped = this.clipLogs(logs);
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
125
|
+
const message = this.clipText(error.message, Math.max(0, this.maxBytes - 2));
|
|
126
|
+
if (this.textBytes(message) + this.logBytes(clipped) <= this.maxBytes) {
|
|
127
|
+
return { logs: clipped, error: { ...error, message } };
|
|
128
|
+
}
|
|
129
|
+
return this.outputLimit(clipped);
|
|
130
|
+
}
|
|
131
|
+
/** Build an output-limit result while retaining as many leading logs as fit. */
|
|
132
|
+
outputLimit(logs) {
|
|
133
|
+
const message = this.clipText(`outer output exceeded ${this.maxBytes} bytes`, Math.max(0, this.maxBytes - 2));
|
|
134
|
+
return this.fit(this.clipLogs(logs), { kind: 'output-limit', message });
|
|
135
|
+
}
|
|
136
|
+
/** UTF-8 byte total of a clipped logs array using its compact JSON encoding. */
|
|
137
|
+
logBytes(logs) {
|
|
138
|
+
return this.textBytes(JSON.stringify(logs));
|
|
139
|
+
}
|
|
140
|
+
/** Keep the mandatory diagnostic, then admit leading log entries that fit. */
|
|
141
|
+
fit(logs, error) {
|
|
142
|
+
const fixedBytes = this.textBytes(error.message);
|
|
122
143
|
const retained = [];
|
|
123
144
|
let retainedBytes = 2;
|
|
124
145
|
for (const text of logs) {
|
|
125
146
|
const separatorBytes = retained.length > 0 ? 1 : 0;
|
|
126
|
-
|
|
147
|
+
const entryBytes = this.textBytes(JSON.stringify(text));
|
|
148
|
+
if (fixedBytes + retainedBytes + separatorBytes + entryBytes > this.maxBytes)
|
|
127
149
|
break;
|
|
128
150
|
retained.push(text);
|
|
129
|
-
retainedBytes +=
|
|
151
|
+
retainedBytes += separatorBytes + entryBytes;
|
|
130
152
|
}
|
|
131
|
-
return { logs: retained, error
|
|
153
|
+
return { logs: retained, error };
|
|
154
|
+
}
|
|
155
|
+
/** Byte-budget clip for a single text (diagnostics), with a `…` marker. */
|
|
156
|
+
clipText(text, maxBytes) {
|
|
157
|
+
if (this.textBytes(text) <= maxBytes)
|
|
158
|
+
return text;
|
|
159
|
+
const marker = '…';
|
|
160
|
+
const markerBytes = this.textBytes(marker);
|
|
161
|
+
if (maxBytes < markerBytes)
|
|
162
|
+
return '';
|
|
163
|
+
const source = Buffer.from(text, 'utf8');
|
|
164
|
+
let end = Math.max(0, maxBytes - markerBytes);
|
|
165
|
+
let clipped = source.subarray(0, end).toString('utf8');
|
|
166
|
+
while (end > 0 && this.textBytes(clipped) + markerBytes > maxBytes) {
|
|
167
|
+
end -= 1;
|
|
168
|
+
clipped = source.subarray(0, end).toString('utf8');
|
|
169
|
+
}
|
|
170
|
+
return `${clipped}${marker}`;
|
|
132
171
|
}
|
|
133
172
|
compactJsonBytes(value) {
|
|
134
173
|
let text;
|
|
@@ -152,8 +191,16 @@ export class KernelManager {
|
|
|
152
191
|
#config;
|
|
153
192
|
#registries = new Map();
|
|
154
193
|
#ledgerFactory;
|
|
194
|
+
/** Async confinement seam (matches the real sandbox provider; see kernel.ts). */
|
|
155
195
|
#confine;
|
|
196
|
+
/** In-flight one-shot kernels: every admitted run is tracked so teardown quiesces them too. */
|
|
197
|
+
#oneshots = new Set();
|
|
198
|
+
/** Every admitted run's abort source; teardown aborts the set before draining it. */
|
|
199
|
+
#runControllers = new Set();
|
|
200
|
+
/** Python commands whose probe already passed this manager's lifetime; failures are never cached. */
|
|
201
|
+
#verifiedPython = new Set();
|
|
156
202
|
#disposed = false;
|
|
203
|
+
#teardownPromise;
|
|
157
204
|
constructor(config) {
|
|
158
205
|
// Fill defaults here too: the plugin path gets them from the schemastery
|
|
159
206
|
// schema, but programmatic callers (tests, tooling) may pass a partial
|
|
@@ -161,6 +208,7 @@ export class KernelManager {
|
|
|
161
208
|
const resolved = {
|
|
162
209
|
languages: config.languages ?? ['python', 'typescript'],
|
|
163
210
|
...config.pythonPath !== undefined ? { pythonPath: config.pythonPath } : {},
|
|
211
|
+
pythonProbeTimeoutMs: config.pythonProbeTimeoutMs ?? 5_000,
|
|
164
212
|
pythonImpl: config.pythonImpl ?? 'stdlib',
|
|
165
213
|
...config.nodePath !== undefined ? { nodePath: config.nodePath } : {},
|
|
166
214
|
toolTimeoutMs: config.toolTimeoutMs ?? 30_000,
|
|
@@ -182,7 +230,7 @@ export class KernelManager {
|
|
|
182
230
|
sandboxMode: config.sandboxMode ?? 'workspace-write',
|
|
183
231
|
};
|
|
184
232
|
const numericKeys = ['maxWallMs', 'maxOutputBytes', 'maxOutputLineChars', 'sessionIdleMs',
|
|
185
|
-
'interruptEscalationMs', 'startupTimeoutMs', 'shutdownGraceMs',
|
|
233
|
+
'interruptEscalationMs', 'startupTimeoutMs', 'shutdownGraceMs', 'pythonProbeTimeoutMs',
|
|
186
234
|
'snapshotMaxBytes', 'snapshotMaxEntryBytes'];
|
|
187
235
|
for (const key of numericKeys) {
|
|
188
236
|
const value = resolved[key];
|
|
@@ -228,15 +276,26 @@ export class KernelManager {
|
|
|
228
276
|
if (resolved.sandboxConfinement && resolved.sandboxProvider !== undefined) {
|
|
229
277
|
const provider = resolved.sandboxProvider;
|
|
230
278
|
const root = resolve(resolved.sandboxWorkspaceRoot);
|
|
231
|
-
|
|
279
|
+
// The real sandbox seam is async and fail-closed (see KernelStartConfig).
|
|
280
|
+
// The DSH session id owns sandbox policy; kernel sub-session ids do not.
|
|
281
|
+
this.#confine = (argv, signal, sessionId) => provider.confine(argv, {
|
|
282
|
+
mode: resolved.sandboxMode,
|
|
283
|
+
workspaceRoot: root,
|
|
284
|
+
...sessionId !== undefined ? { sessionId } : {},
|
|
285
|
+
}, signal);
|
|
232
286
|
}
|
|
233
287
|
this.#config = resolved;
|
|
234
288
|
this.#ledgerFactory = () => new OutputLedger(resolved.maxOutputBytes, resolved.maxOutputLineChars);
|
|
235
289
|
for (const language of resolved.languages) {
|
|
236
290
|
this.#registries.set(language, new SessionRegistry({
|
|
237
291
|
label: language === 'python' ? 'python kernel' : 'nodejs kernel',
|
|
238
|
-
start: () => this.#startKernel(language === 'python' ? 'python' : 'typescript'),
|
|
292
|
+
start: (signal, sandboxSessionId) => this.#startKernel(language === 'python' ? 'python' : 'typescript', signal, sandboxSessionId),
|
|
239
293
|
sessionIdleMs: resolved.sessionIdleMs,
|
|
294
|
+
// The JavaScript runner's cancellation leaves the abandoned cell
|
|
295
|
+
// evaluating as a ghost inside the kernel, so an aborted JS run
|
|
296
|
+
// retires (and awaits) its kernel instead of reusing it. The Python
|
|
297
|
+
// runner's SIGINT cancellation is clean — its kernel is reused.
|
|
298
|
+
retireOnCancel: language !== 'python',
|
|
240
299
|
snapshot: sessionId => this.#snapshotSpecFor(language === 'python' ? 'python' : 'typescript', sessionId),
|
|
241
300
|
preload: () => resolved.preload[language],
|
|
242
301
|
}));
|
|
@@ -258,10 +317,26 @@ export class KernelManager {
|
|
|
258
317
|
maxEntryBytes: this.#config.snapshotMaxEntryBytes,
|
|
259
318
|
};
|
|
260
319
|
}
|
|
261
|
-
/**
|
|
262
|
-
|
|
320
|
+
/** Abort admitted work, then terminate every session and one-shot kernel. */
|
|
321
|
+
teardown() {
|
|
322
|
+
this.#teardownPromise ??= this.#drain();
|
|
323
|
+
return this.#teardownPromise;
|
|
324
|
+
}
|
|
325
|
+
async #drain() {
|
|
263
326
|
this.#disposed = true;
|
|
327
|
+
for (const controller of this.#runControllers) {
|
|
328
|
+
controller.abort(new Error('dsh-code-runtime-kernels: plugin teardown'));
|
|
329
|
+
}
|
|
264
330
|
await Promise.allSettled([...this.#registries.values()].map(registry => registry.disposeAll()));
|
|
331
|
+
await Promise.allSettled([...this.#oneshots]);
|
|
332
|
+
}
|
|
333
|
+
/**
|
|
334
|
+
* The surface-visible fields of the resolved config (the same defaults the
|
|
335
|
+
* constructor applies), so the tool guide can promise exactly what this
|
|
336
|
+
* deployment enables — no more.
|
|
337
|
+
*/
|
|
338
|
+
static resolvedSurface(config) {
|
|
339
|
+
return { snapshot: config.snapshot ?? true, sessionIdleMs: config.sessionIdleMs ?? 0 };
|
|
265
340
|
}
|
|
266
341
|
/**
|
|
267
342
|
* Execute one program. Program outcomes resolve with `error` as a result
|
|
@@ -270,14 +345,8 @@ export class KernelManager {
|
|
|
270
345
|
* `sessionId` the program runs in that session's persistent kernel and
|
|
271
346
|
* `executionCount` is reported; `reset: true` discards prior state first.
|
|
272
347
|
*
|
|
273
|
-
* `onOutputLimit`
|
|
274
|
-
*
|
|
275
|
-
* output (the same bytes that just overflowed the result budget) and may
|
|
276
|
-
* persist them somewhere recoverable. Returning a retrieval hint rewrites
|
|
277
|
-
* the `output-limit` message so the caller can recover the dropped tail;
|
|
278
|
-
* returning `undefined` (no backend, no owner, storage failure) keeps the
|
|
279
|
-
* truncated result untouched. The manager never awaits this beyond a
|
|
280
|
-
* best-effort `catch` — spill failure cannot fail the program.
|
|
348
|
+
* `onOutputLimit` keeps its original content-first callback and receives
|
|
349
|
+
* additive metadata describing whether host capture retained the full text.
|
|
281
350
|
*/
|
|
282
351
|
async run(request, onOutputLimit) {
|
|
283
352
|
if (this.#disposed)
|
|
@@ -290,9 +359,8 @@ export class KernelManager {
|
|
|
290
359
|
if (request.signal?.aborted) {
|
|
291
360
|
return this.#ledgerFactory().failure([], { kind: 'abort', message: String(request.signal.reason) });
|
|
292
361
|
}
|
|
293
|
-
// Wall-clock budget: this run's abort source. The kernel turns it into
|
|
294
|
-
// SIGINT (and escalation), so a busy cell is interrupted hard.
|
|
295
362
|
const controller = new AbortController();
|
|
363
|
+
this.#runControllers.add(controller);
|
|
296
364
|
let timedOut = false;
|
|
297
365
|
const timer = setTimeout(() => {
|
|
298
366
|
timedOut = true;
|
|
@@ -306,25 +374,41 @@ export class KernelManager {
|
|
|
306
374
|
const outcome = sessionId !== undefined && sessionId.length > 0
|
|
307
375
|
? await registry.executeOnSession(sessionId, request.code, bindings, {
|
|
308
376
|
...request.reset !== undefined ? { reset: request.reset } : {},
|
|
377
|
+
...request.cwd !== undefined ? { cwd: request.cwd } : {},
|
|
378
|
+
...request.sandboxSessionId !== undefined ? { sandboxSessionId: request.sandboxSessionId } : {},
|
|
309
379
|
signal: controller.signal,
|
|
310
380
|
})
|
|
311
|
-
: await this.#runOneShot(request.language, request.code, bindings, controller.signal);
|
|
381
|
+
: await this.#runOneShot(request.language, request.code, bindings, controller.signal, request.cwd, request.sandboxSessionId);
|
|
312
382
|
return await this.finalize(outcome, timedOut, onOutputLimit);
|
|
313
383
|
}
|
|
384
|
+
catch (error) {
|
|
385
|
+
if (!controller.signal.aborted)
|
|
386
|
+
throw error;
|
|
387
|
+
return await this.finalize({
|
|
388
|
+
status: 'error',
|
|
389
|
+
logs: [],
|
|
390
|
+
cancelled: true,
|
|
391
|
+
invalidOutput: false,
|
|
392
|
+
message: String(controller.signal.reason ?? error),
|
|
393
|
+
killed: false,
|
|
394
|
+
}, timedOut, onOutputLimit);
|
|
395
|
+
}
|
|
314
396
|
finally {
|
|
315
397
|
clearTimeout(timer);
|
|
316
398
|
request.signal?.removeEventListener('abort', onOuter);
|
|
399
|
+
this.#runControllers.delete(controller);
|
|
317
400
|
}
|
|
318
401
|
}
|
|
319
|
-
#startKernel(language) {
|
|
402
|
+
#startKernel(language, signal, sandboxSessionId) {
|
|
320
403
|
return language === 'python'
|
|
321
|
-
? this.#startPython()
|
|
322
|
-
: this.#startNodejs();
|
|
404
|
+
? this.#startPython(signal, sandboxSessionId)
|
|
405
|
+
: this.#startNodejs(signal, sandboxSessionId);
|
|
323
406
|
}
|
|
324
|
-
#startPython() {
|
|
407
|
+
async #startPython(signal, sandboxSessionId) {
|
|
408
|
+
const command = await this.#resolvePythonCommand();
|
|
325
409
|
const profile = {
|
|
326
410
|
key: 'python',
|
|
327
|
-
command
|
|
411
|
+
command,
|
|
328
412
|
argvPrefix: ['-u'],
|
|
329
413
|
stagedSource: PYTHON_RUNNER,
|
|
330
414
|
stagedSuffix: '.py',
|
|
@@ -339,26 +423,55 @@ export class KernelManager {
|
|
|
339
423
|
idPrefix: 'py-',
|
|
340
424
|
label: 'python kernel',
|
|
341
425
|
};
|
|
342
|
-
return KernelHost.start(profile, this.#startConfig());
|
|
426
|
+
return KernelHost.start(profile, this.#startConfig(signal, sandboxSessionId));
|
|
343
427
|
}
|
|
344
|
-
|
|
345
|
-
|
|
428
|
+
/** Resolve the python command for a kernel start (config.pythonPath first, then PATH candidates). */
|
|
429
|
+
#resolvePythonCommand() {
|
|
430
|
+
return resolvePythonCommand(enumeratePythonCandidates(this.#config.pythonPath), {
|
|
431
|
+
probeTimeoutMs: this.#config.pythonProbeTimeoutMs,
|
|
432
|
+
verified: this.#verifiedPython,
|
|
433
|
+
});
|
|
346
434
|
}
|
|
347
|
-
#
|
|
435
|
+
#startNodejs(signal, sandboxSessionId) {
|
|
436
|
+
return KernelHost.start(nodejsKernelProfile(this.#config.nodePath ?? 'node'), this.#startConfig(signal, sandboxSessionId));
|
|
437
|
+
}
|
|
438
|
+
#startConfig(signal, sandboxSessionId) {
|
|
348
439
|
return {
|
|
349
440
|
cwd: process.cwd(),
|
|
350
|
-
|
|
441
|
+
// DSH owns the credential-safe parent environment policy. Deliberate
|
|
442
|
+
// runner controls are merged from the profile after this scrub.
|
|
443
|
+
env: scrubbedParentEnv(),
|
|
351
444
|
startupTimeoutMs: this.#config.startupTimeoutMs,
|
|
352
445
|
interruptEscalationMs: this.#config.interruptEscalationMs,
|
|
353
446
|
shutdownGraceMs: this.#config.shutdownGraceMs,
|
|
447
|
+
...signal !== undefined ? { signal } : {},
|
|
448
|
+
...sandboxSessionId !== undefined ? { sandboxSessionId } : {},
|
|
449
|
+
// Host-side per-run capture cap: the kernel log ring is bounded by the
|
|
450
|
+
// same byte budget as the result envelope, so a log bomb cannot balloon
|
|
451
|
+
// host memory before the ledger clips the result.
|
|
452
|
+
captureCapBytes: this.#config.maxOutputBytes,
|
|
354
453
|
...this.#confine !== undefined ? { confine: this.#confine } : {},
|
|
355
454
|
};
|
|
356
455
|
}
|
|
357
|
-
/** One fresh kernel for exactly one program: the one-shot path. */
|
|
358
|
-
async #runOneShot(language, code, bindings, signal) {
|
|
359
|
-
const
|
|
456
|
+
/** One fresh kernel for exactly one program: the tracked one-shot path. */
|
|
457
|
+
async #runOneShot(language, code, bindings, signal, cwd, sandboxSessionId) {
|
|
458
|
+
const run = this.#oneShotRun(language, code, bindings, signal, cwd, sandboxSessionId);
|
|
459
|
+
// Track the admitted run so teardown() quiesces its kernel.
|
|
460
|
+
this.#oneshots.add(run);
|
|
461
|
+
try {
|
|
462
|
+
return await run;
|
|
463
|
+
}
|
|
464
|
+
finally {
|
|
465
|
+
this.#oneshots.delete(run);
|
|
466
|
+
}
|
|
467
|
+
}
|
|
468
|
+
async #oneShotRun(language, code, bindings, signal, cwd, sandboxSessionId) {
|
|
469
|
+
const kernel = await this.#startKernel(language, signal, sandboxSessionId);
|
|
360
470
|
try {
|
|
361
|
-
return await kernel.execute(randomUUID(), code, bindings, {
|
|
471
|
+
return await kernel.execute(randomUUID(), code, bindings, {
|
|
472
|
+
signal,
|
|
473
|
+
...cwd !== undefined ? { cwd } : {},
|
|
474
|
+
});
|
|
362
475
|
}
|
|
363
476
|
catch (error) {
|
|
364
477
|
return { status: 'error', logs: [], cancelled: false, invalidOutput: false, message: String(error), killed: false };
|
|
@@ -368,76 +481,80 @@ export class KernelManager {
|
|
|
368
481
|
}
|
|
369
482
|
}
|
|
370
483
|
/**
|
|
371
|
-
* Map
|
|
372
|
-
*
|
|
373
|
-
* kernel survived to acknowledge it); everything else interrupted is an
|
|
374
|
-
* abort; a died kernel is an abort unless the budget already owns the run.
|
|
375
|
-
*/
|
|
376
|
-
/**
|
|
377
|
-
* Map a kernel outcome onto the failure taxonomy through the output ledger.
|
|
378
|
-
* Budget expiry owns a run that hit the wall clock (whether or not the
|
|
379
|
-
* kernel survived to acknowledge it); everything else interrupted is an
|
|
380
|
-
* abort; a died kernel is an abort unless the budget already owns the run.
|
|
381
|
-
*
|
|
382
|
-
* An `output-limit` outcome additionally consults `onOutputLimit` to spill
|
|
383
|
-
* the full captured output, best-effort (never awaited past a catch).
|
|
484
|
+
* Map one kernel outcome onto the PTC failure taxonomy. Capture truncation
|
|
485
|
+
* takes precedence because the discarded tail prevents a complete result.
|
|
384
486
|
*/
|
|
385
487
|
async finalize(outcome, timedOut, onOutputLimit) {
|
|
386
488
|
const ledger = this.#ledgerFactory();
|
|
387
489
|
const logs = outcome.logs.map(entry => entry.text);
|
|
388
|
-
|
|
389
|
-
|
|
490
|
+
let spillDiagnostic;
|
|
491
|
+
let result;
|
|
492
|
+
if (outcome.captureTruncated === true) {
|
|
493
|
+
result = ledger.outputLimit(logs);
|
|
494
|
+
}
|
|
495
|
+
else if (timedOut) {
|
|
496
|
+
spillDiagnostic = outcome.killed
|
|
390
497
|
? `wall-clock ceiling reached (${this.#config.maxWallMs}ms); kernel killed after unresponsive interrupt`
|
|
391
498
|
: `wall-clock ceiling reached (${this.#config.maxWallMs}ms)`;
|
|
392
|
-
|
|
499
|
+
result = ledger.failure(logs, { kind: 'timeout', message: spillDiagnostic });
|
|
393
500
|
}
|
|
394
|
-
if (outcome.
|
|
395
|
-
|
|
501
|
+
else if (outcome.crashed === true && !outcome.cancelled) {
|
|
502
|
+
spillDiagnostic = `${outcome.message || 'the kernel worker exited before completing this run'}; the kernel was retired and this run was NOT retried — external effects (file writes, network calls) it completed before exiting remain`;
|
|
503
|
+
result = ledger.failure(logs, { kind: 'worker-exit', message: spillDiagnostic });
|
|
396
504
|
}
|
|
397
|
-
if (outcome.cancelled) {
|
|
398
|
-
|
|
505
|
+
else if (outcome.killed || outcome.cancelled) {
|
|
506
|
+
spillDiagnostic = outcome.message || 'run interrupted';
|
|
507
|
+
result = ledger.failure(logs, { kind: 'abort', message: spillDiagnostic });
|
|
399
508
|
}
|
|
400
|
-
if (outcome.status === 'error') {
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
509
|
+
else if (outcome.status === 'error') {
|
|
510
|
+
spillDiagnostic = outcome.message || (outcome.invalidOutput
|
|
511
|
+
? 'program completion must be lossless JSON'
|
|
512
|
+
: 'program failed');
|
|
513
|
+
result = ledger.failure(logs, {
|
|
514
|
+
kind: outcome.invalidOutput ? 'invalid-output' : 'exception',
|
|
515
|
+
message: spillDiagnostic,
|
|
516
|
+
});
|
|
517
|
+
}
|
|
518
|
+
else {
|
|
519
|
+
result = outcome.value === undefined
|
|
520
|
+
? ledger.success(logs)
|
|
521
|
+
: ledger.success(logs, outcome.value);
|
|
405
522
|
}
|
|
406
|
-
const result = outcome.value === undefined
|
|
407
|
-
? ledger.success(logs)
|
|
408
|
-
: ledger.success(logs, outcome.value);
|
|
409
523
|
const settled = {
|
|
410
524
|
...result,
|
|
411
525
|
...outcome.executionCount !== undefined ? { executionCount: outcome.executionCount } : {},
|
|
526
|
+
...outcome.persistence !== undefined ? { persistence: outcome.persistence } : {},
|
|
412
527
|
};
|
|
413
|
-
if (settled.error?.kind
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
let valueText;
|
|
418
|
-
if (outcome.value !== undefined) {
|
|
419
|
-
try {
|
|
420
|
-
valueText = JSON.stringify(outcome.value);
|
|
421
|
-
}
|
|
422
|
-
catch {
|
|
423
|
-
// JSON.stringify rejected the value (circular reference, exotic
|
|
424
|
-
// object); a structural inspection is the best text we still have.
|
|
425
|
-
valueText = inspect(outcome.value, { depth: 8, maxArrayLength: 200, breakLength: 100 });
|
|
426
|
-
}
|
|
427
|
-
}
|
|
428
|
-
const spillContent = valueText === undefined
|
|
429
|
-
? logs.join('\n')
|
|
430
|
-
: `${logs.join('\n')}\n[completion value]\n${valueText}`;
|
|
528
|
+
if (settled.error?.kind !== 'output-limit' || onOutputLimit === undefined)
|
|
529
|
+
return settled;
|
|
530
|
+
let valueText;
|
|
531
|
+
if (outcome.value !== undefined) {
|
|
431
532
|
try {
|
|
432
|
-
|
|
433
|
-
if (hint !== undefined && hint.length > 0) {
|
|
434
|
-
return { ...settled, error: { ...settled.error, message: `${settled.error.message} — full program output preserved at ${hint}` } };
|
|
435
|
-
}
|
|
533
|
+
valueText = JSON.stringify(outcome.value);
|
|
436
534
|
}
|
|
437
535
|
catch {
|
|
438
|
-
|
|
536
|
+
valueText = inspect(outcome.value, { depth: 8, maxArrayLength: 200, breakLength: 100 });
|
|
537
|
+
}
|
|
538
|
+
}
|
|
539
|
+
const parts = [logs.join('\n')];
|
|
540
|
+
if (valueText !== undefined)
|
|
541
|
+
parts.push(`[completion value]\n${valueText}`);
|
|
542
|
+
if (spillDiagnostic !== undefined)
|
|
543
|
+
parts.push(`[program failure]\n${spillDiagnostic}`);
|
|
544
|
+
const content = parts.filter(part => part.length > 0).join('\n');
|
|
545
|
+
const info = { complete: outcome.captureTruncated !== true };
|
|
546
|
+
try {
|
|
547
|
+
const hint = await onOutputLimit(content, info);
|
|
548
|
+
if (hint !== undefined && hint.length > 0) {
|
|
549
|
+
const preserved = info.complete
|
|
550
|
+
? `full program output preserved at ${hint}`
|
|
551
|
+
: `captured output prefix preserved at ${hint}; discarded tail unavailable`;
|
|
552
|
+
return { ...settled, error: { ...settled.error, message: `${settled.error.message} — ${preserved}` } };
|
|
439
553
|
}
|
|
440
554
|
}
|
|
555
|
+
catch {
|
|
556
|
+
// Best effort: spill storage cannot change the program outcome.
|
|
557
|
+
}
|
|
441
558
|
return settled;
|
|
442
559
|
}
|
|
443
560
|
/** Reject malformed binding globals or typed-error declarations as contract misuse. */
|
|
@@ -472,17 +589,44 @@ export class KernelManager {
|
|
|
472
589
|
return bindings;
|
|
473
590
|
}
|
|
474
591
|
}
|
|
475
|
-
/**
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
592
|
+
/**
|
|
593
|
+
* Model-facing guide for when and how to use `run_kernel_code`, conditioned on
|
|
594
|
+
* the active config: snapshot and idle-reap sentences are only promised when
|
|
595
|
+
* the plugin actually enables them (truthful-surface rule).
|
|
596
|
+
*/
|
|
597
|
+
function toolGuide(config) {
|
|
598
|
+
const lines = [
|
|
599
|
+
'Prefer run_kernel_code to reading/writing scratch files when the work is computation with intermediate results',
|
|
600
|
+
'— sessions keep kernel state (variables, imports, working data) across calls'
|
|
601
|
+
+ (config.snapshot
|
|
602
|
+
? ', AND snapshot it to disk after every successful run, so state survives a kernel crash or restart (the'
|
|
603
|
+
+ ' first run after a restore reports what was restored and what could not be). Note: shared objects bound to'
|
|
604
|
+
+ ' several names are restored as independent copies — object identity across names is not preserved'
|
|
605
|
+
: '. Snapshots are disabled in this deployment; a dead kernel starts its session EMPTY on the next call'),
|
|
606
|
+
'. Omit `session` for one-off computations; give related calls the same',
|
|
607
|
+
'`session` id to carry state forward, and pass `reset: true` when the session\'s state is corrupted or unwanted.',
|
|
608
|
+
'Python programs persist module-level variables and functions; JavaScript programs persist via `state` and',
|
|
609
|
+
'top-level assignments.',
|
|
610
|
+
...(config.sessionIdleMs > 0
|
|
611
|
+
? [
|
|
612
|
+
`A session reaps idle kernels after ${config.sessionIdleMs}ms without work;`,
|
|
613
|
+
config.snapshot
|
|
614
|
+
? 'a reaped session resumes from its snapshot on the next call with the same id.'
|
|
615
|
+
: 'a reaped session starts EMPTY on the next call with the same id (snapshots are disabled).',
|
|
616
|
+
]
|
|
617
|
+
: ['Kernels stay resident for the session\'s lifetime; there is no idle reaping in this deployment.']),
|
|
618
|
+
];
|
|
619
|
+
return lines.join(' ');
|
|
620
|
+
}
|
|
621
|
+
/**
|
|
622
|
+
* Bounded preview of a persistence lost-name list: first PERSISTENCE_PREVIEW
|
|
623
|
+
* names plus the remainder count (the runners' own notice caps at 12).
|
|
624
|
+
*/
|
|
625
|
+
function previewNames(names) {
|
|
626
|
+
const LIMIT = 12;
|
|
627
|
+
const head = names.slice(0, LIMIT).join(', ');
|
|
628
|
+
return names.length > LIMIT ? `${head}, … (+${names.length - LIMIT} more)` : head;
|
|
629
|
+
}
|
|
486
630
|
/** Render the result for the model: successful value, or the failure line. */
|
|
487
631
|
function renderResult(value) {
|
|
488
632
|
const head = [];
|
|
@@ -498,19 +642,46 @@ function renderResult(value) {
|
|
|
498
642
|
}
|
|
499
643
|
if (value.executionCount !== undefined)
|
|
500
644
|
head.push(`execution_count: ${value.executionCount}`);
|
|
645
|
+
if (value.persistence !== undefined) {
|
|
646
|
+
// The runners may report dozens of skipped names (unpicklable/cap-hit
|
|
647
|
+
// namespaces); render a bounded preview so a heavy session cannot turn
|
|
648
|
+
// every run's tool text into multi-KB noise.
|
|
649
|
+
const bits = [
|
|
650
|
+
...value.persistence.saveError !== undefined ? [`save error: ${value.persistence.saveError}`] : [],
|
|
651
|
+
...(value.persistence.saveLost ?? []).length > 0
|
|
652
|
+
? [`lost at save: ${previewNames(value.persistence.saveLost ?? [])}`] : [],
|
|
653
|
+
...(value.persistence.restoreLost ?? []).length > 0
|
|
654
|
+
? [`lost at restore: ${previewNames(value.persistence.restoreLost ?? [])}`] : [],
|
|
655
|
+
];
|
|
656
|
+
if (bits.length > 0)
|
|
657
|
+
head.push(`persistence: ${bits.join('; ')}`);
|
|
658
|
+
}
|
|
501
659
|
return head.length > 0 ? head.join('\n') : '(no output)';
|
|
502
660
|
}
|
|
503
661
|
/** Project the durable, replayable presentation payload for a completed run. */
|
|
504
662
|
export function runKernelCodeMeta(value) {
|
|
505
|
-
|
|
663
|
+
const meta = {
|
|
506
664
|
summary: value.error === undefined
|
|
507
665
|
? (value.value === undefined ? 'completed with no value' : 'completed')
|
|
508
666
|
: 'failed',
|
|
509
|
-
...value.value !== undefined ? { value: value.value } : {},
|
|
510
|
-
...value.error !== undefined ? { error: { kind: value.error.kind, message: value.error.message } } : {},
|
|
511
|
-
...value.executionCount !== undefined ? { executionCount: value.executionCount } : {},
|
|
512
667
|
logs: value.logs.slice(-20),
|
|
513
668
|
};
|
|
669
|
+
if (value.value !== undefined)
|
|
670
|
+
meta.value = value.value;
|
|
671
|
+
if (value.error !== undefined)
|
|
672
|
+
meta.error = { kind: value.error.kind, message: value.error.message };
|
|
673
|
+
if (value.executionCount !== undefined)
|
|
674
|
+
meta.executionCount = value.executionCount;
|
|
675
|
+
if (value.persistence !== undefined) {
|
|
676
|
+
// Cap the lost-name lists too: the replay payload is persisted and
|
|
677
|
+
// re-sent every turn, so a heavy namespace must not bloat it.
|
|
678
|
+
meta.persistence = {
|
|
679
|
+
...value.persistence,
|
|
680
|
+
...(value.persistence.saveLost !== undefined ? { saveLost: value.persistence.saveLost.slice(0, 12) } : {}),
|
|
681
|
+
...(value.persistence.restoreLost !== undefined ? { restoreLost: value.persistence.restoreLost.slice(0, 12) } : {}),
|
|
682
|
+
};
|
|
683
|
+
}
|
|
684
|
+
return meta;
|
|
514
685
|
}
|
|
515
686
|
/** Present a pending `run_kernel_code` call as a terminal card (a cell is a foreground command). */
|
|
516
687
|
export function presentRunKernelCodeCall(args) {
|
|
@@ -551,11 +722,13 @@ export function apply(ctx, config) {
|
|
|
551
722
|
throw new Error(`dsh-code-runtime-kernels: config.toolTimeoutMs must be no greater than ${MAX_TIMER_DELAY_MS}`);
|
|
552
723
|
}
|
|
553
724
|
const manager = new KernelManager(config);
|
|
554
|
-
|
|
725
|
+
// An async disposer: cordis awaits it, so unloading no longer returns while
|
|
726
|
+
// kernels are still alive (session registries + tracked one-shots).
|
|
727
|
+
ctx.effect(() => () => manager.teardown());
|
|
555
728
|
ctx.systemPrompt.section({
|
|
556
729
|
name: 'tool:code-runtime-kernels',
|
|
557
730
|
order: 106,
|
|
558
|
-
text:
|
|
731
|
+
text: toolGuide(KernelManager.resolvedSurface(config)),
|
|
559
732
|
});
|
|
560
733
|
const tool = defineTool({
|
|
561
734
|
name: 'run_kernel_code',
|
|
@@ -570,9 +743,9 @@ export function apply(ctx, config) {
|
|
|
570
743
|
+ '`reset: true` to discard the session\'s prior kernel state before this run '
|
|
571
744
|
+ '(one reset instead of endless retries after state corruption).',
|
|
572
745
|
parameters: {
|
|
573
|
-
language: { type: 'string', enum: ['python', 'typescript'], required: true, description: 'Which runtime executes the code.' },
|
|
574
|
-
code: { type: 'string', required: true, description: 'The program source.
|
|
575
|
-
session: { type: 'string', description: 'Optional persistent-kernel identity: runs sharing a session id keep kernel state. Omit for one-shot.' },
|
|
746
|
+
language: { type: 'string', enum: [...(config.languages ?? ['python', 'typescript'])], required: true, description: 'Which runtime executes the code (only enabled languages are listed).' },
|
|
747
|
+
code: { type: 'string', required: true, description: 'The program source. TypeScript: an async function body — top-level `await` and `return` are available; erasable type annotations (variables, params, returns, interfaces) are stripped, but non-erasable TS (enums, namespaces, parameter properties) is rejected. `await import(...)` resolves node: builtins and packages from the run\'s working directory. Python: a module body — statements persist into the session namespace, the LAST expression is the completion value, and a top-level `return` is invalid Python.' },
|
|
748
|
+
session: { type: 'string', description: 'Optional persistent-kernel identity, scoped to THIS harness conversation: runs sharing a session id (within the same conversation) keep kernel state; the same id in a different conversation gets a separate kernel. Omit for one-shot.' },
|
|
576
749
|
reset: { type: 'boolean', description: 'Discard the session\'s prior kernel state (variables, imports) before this run. Costs one reset instead of many retries; requires `session` to be meaningful.' },
|
|
577
750
|
},
|
|
578
751
|
timeoutMs: toolTimeoutMs,
|
|
@@ -584,6 +757,18 @@ export function apply(ctx, config) {
|
|
|
584
757
|
value: { type: 'json', description: 'The program\'s completion value (JSON), when it returned one.' },
|
|
585
758
|
logs: { type: 'array', items: { type: 'string' }, required: true, description: 'Program output lines, in emission order.' },
|
|
586
759
|
executionCount: { type: 'integer', description: 'The session\'s execution count after this run (persistent sessions only).' },
|
|
760
|
+
persistence: {
|
|
761
|
+
type: 'object',
|
|
762
|
+
additionalProperties: false,
|
|
763
|
+
description: 'Snapshot persistence outcome for this run, when snapshots are on.',
|
|
764
|
+
properties: {
|
|
765
|
+
saved: { type: 'integer', description: 'Names written to the snapshot.' },
|
|
766
|
+
saveLost: { type: 'array', items: { type: 'string' }, description: 'Names dropped at save (size caps).' },
|
|
767
|
+
saveError: { type: 'string', description: 'Why the snapshot write failed, when it did.' },
|
|
768
|
+
restored: { type: 'integer', description: 'Names restored from the snapshot before this run.' },
|
|
769
|
+
restoreLost: { type: 'array', items: { type: 'string' }, description: 'Names dropped at restore (size caps).' },
|
|
770
|
+
},
|
|
771
|
+
},
|
|
587
772
|
error: {
|
|
588
773
|
type: 'object',
|
|
589
774
|
additionalProperties: false,
|
|
@@ -598,19 +783,18 @@ export function apply(ctx, config) {
|
|
|
598
783
|
presentationMeta: (_args, value) => runKernelCodeMeta(value),
|
|
599
784
|
},
|
|
600
785
|
async execute(args, exec) {
|
|
601
|
-
// Best-effort recovery for output overruns
|
|
602
|
-
//
|
|
603
|
-
|
|
604
|
-
// leaves the truncated `output-limit` result intact.
|
|
605
|
-
const sessionId = exec.agent?.session.header.id;
|
|
786
|
+
// Best-effort recovery for output overruns. Capture truncation is
|
|
787
|
+
// labeled as a prefix so the spill never claims a discarded tail exists.
|
|
788
|
+
const dshSessionId = exec.agent?.session.header.id;
|
|
606
789
|
const spillStore = ctx.get('spillStore');
|
|
607
|
-
const onOutputLimit = async (content) => {
|
|
608
|
-
if (
|
|
790
|
+
const onOutputLimit = async (content, info) => {
|
|
791
|
+
if (dshSessionId === undefined || spillStore === undefined)
|
|
609
792
|
return undefined;
|
|
793
|
+
const label = info.complete ? 'kernel-output' : 'kernel-output-prefix';
|
|
610
794
|
const save = {
|
|
611
|
-
owner: { sessionId },
|
|
612
|
-
source: { kind: 'tool', toolName: 'run_kernel_code', callId: exec.callId, label
|
|
613
|
-
suggestedName:
|
|
795
|
+
owner: { sessionId: dshSessionId },
|
|
796
|
+
source: { kind: 'tool', toolName: 'run_kernel_code', callId: exec.callId, label },
|
|
797
|
+
suggestedName: `${label}.txt`,
|
|
614
798
|
content,
|
|
615
799
|
};
|
|
616
800
|
try {
|
|
@@ -621,14 +805,29 @@ export function apply(ctx, config) {
|
|
|
621
805
|
return undefined;
|
|
622
806
|
}
|
|
623
807
|
};
|
|
624
|
-
|
|
808
|
+
// A model-chosen id is namespaced by the DSH conversation id for kernel
|
|
809
|
+
// persistence. Sandbox ownership separately receives only the DSH id.
|
|
810
|
+
const kernelSessionId = args.session !== undefined && args.session.length > 0
|
|
811
|
+
? `${dshSessionId ?? 'orphan-conversation'}:${args.session}`
|
|
812
|
+
: undefined;
|
|
813
|
+
// Resolve per call because the conversation may move. A mounted service
|
|
814
|
+
// owns failures; absence falls back to the session header's cwd.
|
|
815
|
+
let initialDir = exec.agent?.session.header.cwd;
|
|
816
|
+
if (exec.agent !== undefined) {
|
|
817
|
+
const workingDirectory = ctx.get('workingDirectory');
|
|
818
|
+
if (workingDirectory !== undefined) {
|
|
819
|
+
initialDir = await workingDirectory.ensure(exec.agent, exec.signal);
|
|
820
|
+
}
|
|
821
|
+
}
|
|
822
|
+
return await manager.run({
|
|
625
823
|
language: args.language,
|
|
626
824
|
code: args.code,
|
|
627
|
-
...
|
|
825
|
+
...kernelSessionId !== undefined ? { sessionId: kernelSessionId } : {},
|
|
826
|
+
...dshSessionId !== undefined ? { sandboxSessionId: dshSessionId } : {},
|
|
628
827
|
...args.reset !== undefined ? { reset: args.reset } : {},
|
|
828
|
+
...initialDir !== undefined ? { cwd: initialDir } : {},
|
|
629
829
|
signal: exec.signal,
|
|
630
830
|
}, onOutputLimit);
|
|
631
|
-
return result;
|
|
632
831
|
},
|
|
633
832
|
presentCall: presentRunKernelCodeCall,
|
|
634
833
|
presentResult: presentRunKernelCodeResult,
|