@hy-sde-org/dsh-code-runtime-kernels 0.2.1-rc.5 → 0.2.2-rc.3
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 +12 -4
- package/README.zh.md +12 -4
- 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/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 +47 -27
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +313 -127
- 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,6 +14,7 @@ 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';
|
|
@@ -103,34 +104,70 @@ class OutputLedger {
|
|
|
103
104
|
/** Finalize a successful absent-or-JSON completion against the combined cap. */
|
|
104
105
|
success(logs, value) {
|
|
105
106
|
const clipped = this.clipLogs(logs);
|
|
106
|
-
if (value === undefined)
|
|
107
|
+
if (value === undefined) {
|
|
108
|
+
if (this.logBytes(clipped) > this.maxBytes)
|
|
109
|
+
return this.outputLimit(clipped);
|
|
107
110
|
return { logs: clipped };
|
|
111
|
+
}
|
|
108
112
|
const valueBytes = this.compactJsonBytes(value);
|
|
109
113
|
if (valueBytes === undefined || valueBytes > this.maxBytes)
|
|
110
|
-
return this.
|
|
111
|
-
|
|
114
|
+
return this.outputLimit(clipped);
|
|
115
|
+
if (this.logBytes(clipped) + valueBytes <= this.maxBytes)
|
|
116
|
+
return { logs: clipped, value };
|
|
117
|
+
return this.outputLimit(clipped);
|
|
112
118
|
}
|
|
113
|
-
/**
|
|
119
|
+
/**
|
|
120
|
+
* Finalize a failure diagnostic against the combined cap. A diagnostic that
|
|
121
|
+
* fits outranks logs; any combined overflow becomes `output-limit`.
|
|
122
|
+
*/
|
|
114
123
|
failure(logs, error) {
|
|
115
124
|
const clipped = this.clipLogs(logs);
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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);
|
|
124
143
|
const retained = [];
|
|
125
144
|
let retainedBytes = 2;
|
|
126
145
|
for (const text of logs) {
|
|
127
146
|
const separatorBytes = retained.length > 0 ? 1 : 0;
|
|
128
|
-
|
|
147
|
+
const entryBytes = this.textBytes(JSON.stringify(text));
|
|
148
|
+
if (fixedBytes + retainedBytes + separatorBytes + entryBytes > this.maxBytes)
|
|
129
149
|
break;
|
|
130
150
|
retained.push(text);
|
|
131
|
-
retainedBytes +=
|
|
151
|
+
retainedBytes += separatorBytes + entryBytes;
|
|
132
152
|
}
|
|
133
|
-
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}`;
|
|
134
171
|
}
|
|
135
172
|
compactJsonBytes(value) {
|
|
136
173
|
let text;
|
|
@@ -154,10 +191,16 @@ export class KernelManager {
|
|
|
154
191
|
#config;
|
|
155
192
|
#registries = new Map();
|
|
156
193
|
#ledgerFactory;
|
|
194
|
+
/** Async confinement seam (matches the real sandbox provider; see kernel.ts). */
|
|
157
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();
|
|
158
200
|
/** Python commands whose probe already passed this manager's lifetime; failures are never cached. */
|
|
159
201
|
#verifiedPython = new Set();
|
|
160
202
|
#disposed = false;
|
|
203
|
+
#teardownPromise;
|
|
161
204
|
constructor(config) {
|
|
162
205
|
// Fill defaults here too: the plugin path gets them from the schemastery
|
|
163
206
|
// schema, but programmatic callers (tests, tooling) may pass a partial
|
|
@@ -233,15 +276,26 @@ export class KernelManager {
|
|
|
233
276
|
if (resolved.sandboxConfinement && resolved.sandboxProvider !== undefined) {
|
|
234
277
|
const provider = resolved.sandboxProvider;
|
|
235
278
|
const root = resolve(resolved.sandboxWorkspaceRoot);
|
|
236
|
-
|
|
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);
|
|
237
286
|
}
|
|
238
287
|
this.#config = resolved;
|
|
239
288
|
this.#ledgerFactory = () => new OutputLedger(resolved.maxOutputBytes, resolved.maxOutputLineChars);
|
|
240
289
|
for (const language of resolved.languages) {
|
|
241
290
|
this.#registries.set(language, new SessionRegistry({
|
|
242
291
|
label: language === 'python' ? 'python kernel' : 'nodejs kernel',
|
|
243
|
-
start: () => this.#startKernel(language === 'python' ? 'python' : 'typescript'),
|
|
292
|
+
start: (signal, sandboxSessionId) => this.#startKernel(language === 'python' ? 'python' : 'typescript', signal, sandboxSessionId),
|
|
244
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',
|
|
245
299
|
snapshot: sessionId => this.#snapshotSpecFor(language === 'python' ? 'python' : 'typescript', sessionId),
|
|
246
300
|
preload: () => resolved.preload[language],
|
|
247
301
|
}));
|
|
@@ -263,10 +317,26 @@ export class KernelManager {
|
|
|
263
317
|
maxEntryBytes: this.#config.snapshotMaxEntryBytes,
|
|
264
318
|
};
|
|
265
319
|
}
|
|
266
|
-
/**
|
|
267
|
-
|
|
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() {
|
|
268
326
|
this.#disposed = true;
|
|
327
|
+
for (const controller of this.#runControllers) {
|
|
328
|
+
controller.abort(new Error('dsh-code-runtime-kernels: plugin teardown'));
|
|
329
|
+
}
|
|
269
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 };
|
|
270
340
|
}
|
|
271
341
|
/**
|
|
272
342
|
* Execute one program. Program outcomes resolve with `error` as a result
|
|
@@ -275,14 +345,8 @@ export class KernelManager {
|
|
|
275
345
|
* `sessionId` the program runs in that session's persistent kernel and
|
|
276
346
|
* `executionCount` is reported; `reset: true` discards prior state first.
|
|
277
347
|
*
|
|
278
|
-
* `onOutputLimit`
|
|
279
|
-
*
|
|
280
|
-
* output (the same bytes that just overflowed the result budget) and may
|
|
281
|
-
* persist them somewhere recoverable. Returning a retrieval hint rewrites
|
|
282
|
-
* the `output-limit` message so the caller can recover the dropped tail;
|
|
283
|
-
* returning `undefined` (no backend, no owner, storage failure) keeps the
|
|
284
|
-
* truncated result untouched. The manager never awaits this beyond a
|
|
285
|
-
* 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.
|
|
286
350
|
*/
|
|
287
351
|
async run(request, onOutputLimit) {
|
|
288
352
|
if (this.#disposed)
|
|
@@ -295,9 +359,8 @@ export class KernelManager {
|
|
|
295
359
|
if (request.signal?.aborted) {
|
|
296
360
|
return this.#ledgerFactory().failure([], { kind: 'abort', message: String(request.signal.reason) });
|
|
297
361
|
}
|
|
298
|
-
// Wall-clock budget: this run's abort source. The kernel turns it into
|
|
299
|
-
// SIGINT (and escalation), so a busy cell is interrupted hard.
|
|
300
362
|
const controller = new AbortController();
|
|
363
|
+
this.#runControllers.add(controller);
|
|
301
364
|
let timedOut = false;
|
|
302
365
|
const timer = setTimeout(() => {
|
|
303
366
|
timedOut = true;
|
|
@@ -311,22 +374,37 @@ export class KernelManager {
|
|
|
311
374
|
const outcome = sessionId !== undefined && sessionId.length > 0
|
|
312
375
|
? await registry.executeOnSession(sessionId, request.code, bindings, {
|
|
313
376
|
...request.reset !== undefined ? { reset: request.reset } : {},
|
|
377
|
+
...request.cwd !== undefined ? { cwd: request.cwd } : {},
|
|
378
|
+
...request.sandboxSessionId !== undefined ? { sandboxSessionId: request.sandboxSessionId } : {},
|
|
314
379
|
signal: controller.signal,
|
|
315
380
|
})
|
|
316
|
-
: 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);
|
|
317
382
|
return await this.finalize(outcome, timedOut, onOutputLimit);
|
|
318
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
|
+
}
|
|
319
396
|
finally {
|
|
320
397
|
clearTimeout(timer);
|
|
321
398
|
request.signal?.removeEventListener('abort', onOuter);
|
|
399
|
+
this.#runControllers.delete(controller);
|
|
322
400
|
}
|
|
323
401
|
}
|
|
324
|
-
#startKernel(language) {
|
|
402
|
+
#startKernel(language, signal, sandboxSessionId) {
|
|
325
403
|
return language === 'python'
|
|
326
|
-
? this.#startPython()
|
|
327
|
-
: this.#startNodejs();
|
|
404
|
+
? this.#startPython(signal, sandboxSessionId)
|
|
405
|
+
: this.#startNodejs(signal, sandboxSessionId);
|
|
328
406
|
}
|
|
329
|
-
async #startPython() {
|
|
407
|
+
async #startPython(signal, sandboxSessionId) {
|
|
330
408
|
const command = await this.#resolvePythonCommand();
|
|
331
409
|
const profile = {
|
|
332
410
|
key: 'python',
|
|
@@ -345,7 +423,7 @@ export class KernelManager {
|
|
|
345
423
|
idPrefix: 'py-',
|
|
346
424
|
label: 'python kernel',
|
|
347
425
|
};
|
|
348
|
-
return KernelHost.start(profile, this.#startConfig());
|
|
426
|
+
return KernelHost.start(profile, this.#startConfig(signal, sandboxSessionId));
|
|
349
427
|
}
|
|
350
428
|
/** Resolve the python command for a kernel start (config.pythonPath first, then PATH candidates). */
|
|
351
429
|
#resolvePythonCommand() {
|
|
@@ -354,24 +432,46 @@ export class KernelManager {
|
|
|
354
432
|
verified: this.#verifiedPython,
|
|
355
433
|
});
|
|
356
434
|
}
|
|
357
|
-
#startNodejs() {
|
|
358
|
-
return KernelHost.start(nodejsKernelProfile(this.#config.nodePath ?? 'node'), this.#startConfig());
|
|
435
|
+
#startNodejs(signal, sandboxSessionId) {
|
|
436
|
+
return KernelHost.start(nodejsKernelProfile(this.#config.nodePath ?? 'node'), this.#startConfig(signal, sandboxSessionId));
|
|
359
437
|
}
|
|
360
|
-
#startConfig() {
|
|
438
|
+
#startConfig(signal, sandboxSessionId) {
|
|
361
439
|
return {
|
|
362
440
|
cwd: process.cwd(),
|
|
363
|
-
|
|
441
|
+
// DSH owns the credential-safe parent environment policy. Deliberate
|
|
442
|
+
// runner controls are merged from the profile after this scrub.
|
|
443
|
+
env: scrubbedParentEnv(),
|
|
364
444
|
startupTimeoutMs: this.#config.startupTimeoutMs,
|
|
365
445
|
interruptEscalationMs: this.#config.interruptEscalationMs,
|
|
366
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,
|
|
367
453
|
...this.#confine !== undefined ? { confine: this.#confine } : {},
|
|
368
454
|
};
|
|
369
455
|
}
|
|
370
|
-
/** One fresh kernel for exactly one program: the one-shot path. */
|
|
371
|
-
async #runOneShot(language, code, bindings, signal) {
|
|
372
|
-
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);
|
|
373
470
|
try {
|
|
374
|
-
return await kernel.execute(randomUUID(), code, bindings, {
|
|
471
|
+
return await kernel.execute(randomUUID(), code, bindings, {
|
|
472
|
+
signal,
|
|
473
|
+
...cwd !== undefined ? { cwd } : {},
|
|
474
|
+
});
|
|
375
475
|
}
|
|
376
476
|
catch (error) {
|
|
377
477
|
return { status: 'error', logs: [], cancelled: false, invalidOutput: false, message: String(error), killed: false };
|
|
@@ -381,76 +481,80 @@ export class KernelManager {
|
|
|
381
481
|
}
|
|
382
482
|
}
|
|
383
483
|
/**
|
|
384
|
-
* Map
|
|
385
|
-
*
|
|
386
|
-
* kernel survived to acknowledge it); everything else interrupted is an
|
|
387
|
-
* abort; a died kernel is an abort unless the budget already owns the run.
|
|
388
|
-
*/
|
|
389
|
-
/**
|
|
390
|
-
* Map a kernel outcome onto the failure taxonomy through the output ledger.
|
|
391
|
-
* Budget expiry owns a run that hit the wall clock (whether or not the
|
|
392
|
-
* kernel survived to acknowledge it); everything else interrupted is an
|
|
393
|
-
* abort; a died kernel is an abort unless the budget already owns the run.
|
|
394
|
-
*
|
|
395
|
-
* An `output-limit` outcome additionally consults `onOutputLimit` to spill
|
|
396
|
-
* 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.
|
|
397
486
|
*/
|
|
398
487
|
async finalize(outcome, timedOut, onOutputLimit) {
|
|
399
488
|
const ledger = this.#ledgerFactory();
|
|
400
489
|
const logs = outcome.logs.map(entry => entry.text);
|
|
401
|
-
|
|
402
|
-
|
|
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
|
|
403
497
|
? `wall-clock ceiling reached (${this.#config.maxWallMs}ms); kernel killed after unresponsive interrupt`
|
|
404
498
|
: `wall-clock ceiling reached (${this.#config.maxWallMs}ms)`;
|
|
405
|
-
|
|
499
|
+
result = ledger.failure(logs, { kind: 'timeout', message: spillDiagnostic });
|
|
406
500
|
}
|
|
407
|
-
if (outcome.
|
|
408
|
-
|
|
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 });
|
|
409
504
|
}
|
|
410
|
-
if (outcome.cancelled) {
|
|
411
|
-
|
|
505
|
+
else if (outcome.killed || outcome.cancelled) {
|
|
506
|
+
spillDiagnostic = outcome.message || 'run interrupted';
|
|
507
|
+
result = ledger.failure(logs, { kind: 'abort', message: spillDiagnostic });
|
|
412
508
|
}
|
|
413
|
-
if (outcome.status === 'error') {
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
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);
|
|
418
522
|
}
|
|
419
|
-
const result = outcome.value === undefined
|
|
420
|
-
? ledger.success(logs)
|
|
421
|
-
: ledger.success(logs, outcome.value);
|
|
422
523
|
const settled = {
|
|
423
524
|
...result,
|
|
424
525
|
...outcome.executionCount !== undefined ? { executionCount: outcome.executionCount } : {},
|
|
526
|
+
...outcome.persistence !== undefined ? { persistence: outcome.persistence } : {},
|
|
425
527
|
};
|
|
426
|
-
if (settled.error?.kind
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
let valueText;
|
|
431
|
-
if (outcome.value !== undefined) {
|
|
432
|
-
try {
|
|
433
|
-
valueText = JSON.stringify(outcome.value);
|
|
434
|
-
}
|
|
435
|
-
catch {
|
|
436
|
-
// JSON.stringify rejected the value (circular reference, exotic
|
|
437
|
-
// object); a structural inspection is the best text we still have.
|
|
438
|
-
valueText = inspect(outcome.value, { depth: 8, maxArrayLength: 200, breakLength: 100 });
|
|
439
|
-
}
|
|
440
|
-
}
|
|
441
|
-
const spillContent = valueText === undefined
|
|
442
|
-
? logs.join('\n')
|
|
443
|
-
: `${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) {
|
|
444
532
|
try {
|
|
445
|
-
|
|
446
|
-
if (hint !== undefined && hint.length > 0) {
|
|
447
|
-
return { ...settled, error: { ...settled.error, message: `${settled.error.message} — full program output preserved at ${hint}` } };
|
|
448
|
-
}
|
|
533
|
+
valueText = JSON.stringify(outcome.value);
|
|
449
534
|
}
|
|
450
535
|
catch {
|
|
451
|
-
|
|
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}` } };
|
|
452
553
|
}
|
|
453
554
|
}
|
|
555
|
+
catch {
|
|
556
|
+
// Best effort: spill storage cannot change the program outcome.
|
|
557
|
+
}
|
|
454
558
|
return settled;
|
|
455
559
|
}
|
|
456
560
|
/** Reject malformed binding globals or typed-error declarations as contract misuse. */
|
|
@@ -485,17 +589,44 @@ export class KernelManager {
|
|
|
485
589
|
return bindings;
|
|
486
590
|
}
|
|
487
591
|
}
|
|
488
|
-
/**
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
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
|
+
}
|
|
499
630
|
/** Render the result for the model: successful value, or the failure line. */
|
|
500
631
|
function renderResult(value) {
|
|
501
632
|
const head = [];
|
|
@@ -511,19 +642,46 @@ function renderResult(value) {
|
|
|
511
642
|
}
|
|
512
643
|
if (value.executionCount !== undefined)
|
|
513
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
|
+
}
|
|
514
659
|
return head.length > 0 ? head.join('\n') : '(no output)';
|
|
515
660
|
}
|
|
516
661
|
/** Project the durable, replayable presentation payload for a completed run. */
|
|
517
662
|
export function runKernelCodeMeta(value) {
|
|
518
|
-
|
|
663
|
+
const meta = {
|
|
519
664
|
summary: value.error === undefined
|
|
520
665
|
? (value.value === undefined ? 'completed with no value' : 'completed')
|
|
521
666
|
: 'failed',
|
|
522
|
-
...value.value !== undefined ? { value: value.value } : {},
|
|
523
|
-
...value.error !== undefined ? { error: { kind: value.error.kind, message: value.error.message } } : {},
|
|
524
|
-
...value.executionCount !== undefined ? { executionCount: value.executionCount } : {},
|
|
525
667
|
logs: value.logs.slice(-20),
|
|
526
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;
|
|
527
685
|
}
|
|
528
686
|
/** Present a pending `run_kernel_code` call as a terminal card (a cell is a foreground command). */
|
|
529
687
|
export function presentRunKernelCodeCall(args) {
|
|
@@ -564,11 +722,13 @@ export function apply(ctx, config) {
|
|
|
564
722
|
throw new Error(`dsh-code-runtime-kernels: config.toolTimeoutMs must be no greater than ${MAX_TIMER_DELAY_MS}`);
|
|
565
723
|
}
|
|
566
724
|
const manager = new KernelManager(config);
|
|
567
|
-
|
|
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());
|
|
568
728
|
ctx.systemPrompt.section({
|
|
569
729
|
name: 'tool:code-runtime-kernels',
|
|
570
730
|
order: 106,
|
|
571
|
-
text:
|
|
731
|
+
text: toolGuide(KernelManager.resolvedSurface(config)),
|
|
572
732
|
});
|
|
573
733
|
const tool = defineTool({
|
|
574
734
|
name: 'run_kernel_code',
|
|
@@ -583,9 +743,9 @@ export function apply(ctx, config) {
|
|
|
583
743
|
+ '`reset: true` to discard the session\'s prior kernel state before this run '
|
|
584
744
|
+ '(one reset instead of endless retries after state corruption).',
|
|
585
745
|
parameters: {
|
|
586
|
-
language: { type: 'string', enum: ['python', 'typescript'], required: true, description: 'Which runtime executes the code.' },
|
|
587
|
-
code: { type: 'string', required: true, description: 'The program source.
|
|
588
|
-
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.' },
|
|
589
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.' },
|
|
590
750
|
},
|
|
591
751
|
timeoutMs: toolTimeoutMs,
|
|
@@ -597,6 +757,18 @@ export function apply(ctx, config) {
|
|
|
597
757
|
value: { type: 'json', description: 'The program\'s completion value (JSON), when it returned one.' },
|
|
598
758
|
logs: { type: 'array', items: { type: 'string' }, required: true, description: 'Program output lines, in emission order.' },
|
|
599
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
|
+
},
|
|
600
772
|
error: {
|
|
601
773
|
type: 'object',
|
|
602
774
|
additionalProperties: false,
|
|
@@ -611,19 +783,18 @@ export function apply(ctx, config) {
|
|
|
611
783
|
presentationMeta: (_args, value) => runKernelCodeMeta(value),
|
|
612
784
|
},
|
|
613
785
|
async execute(args, exec) {
|
|
614
|
-
// Best-effort recovery for output overruns
|
|
615
|
-
//
|
|
616
|
-
|
|
617
|
-
// leaves the truncated `output-limit` result intact.
|
|
618
|
-
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;
|
|
619
789
|
const spillStore = ctx.get('spillStore');
|
|
620
|
-
const onOutputLimit = async (content) => {
|
|
621
|
-
if (
|
|
790
|
+
const onOutputLimit = async (content, info) => {
|
|
791
|
+
if (dshSessionId === undefined || spillStore === undefined)
|
|
622
792
|
return undefined;
|
|
793
|
+
const label = info.complete ? 'kernel-output' : 'kernel-output-prefix';
|
|
623
794
|
const save = {
|
|
624
|
-
owner: { sessionId },
|
|
625
|
-
source: { kind: 'tool', toolName: 'run_kernel_code', callId: exec.callId, label
|
|
626
|
-
suggestedName:
|
|
795
|
+
owner: { sessionId: dshSessionId },
|
|
796
|
+
source: { kind: 'tool', toolName: 'run_kernel_code', callId: exec.callId, label },
|
|
797
|
+
suggestedName: `${label}.txt`,
|
|
627
798
|
content,
|
|
628
799
|
};
|
|
629
800
|
try {
|
|
@@ -634,14 +805,29 @@ export function apply(ctx, config) {
|
|
|
634
805
|
return undefined;
|
|
635
806
|
}
|
|
636
807
|
};
|
|
637
|
-
|
|
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({
|
|
638
823
|
language: args.language,
|
|
639
824
|
code: args.code,
|
|
640
|
-
...
|
|
825
|
+
...kernelSessionId !== undefined ? { sessionId: kernelSessionId } : {},
|
|
826
|
+
...dshSessionId !== undefined ? { sandboxSessionId: dshSessionId } : {},
|
|
641
827
|
...args.reset !== undefined ? { reset: args.reset } : {},
|
|
828
|
+
...initialDir !== undefined ? { cwd: initialDir } : {},
|
|
642
829
|
signal: exec.signal,
|
|
643
830
|
}, onOutputLimit);
|
|
644
|
-
return result;
|
|
645
831
|
},
|
|
646
832
|
presentCall: presentRunKernelCodeCall,
|
|
647
833
|
presentResult: presentRunKernelCodeResult,
|