@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/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.limit(clipped);
111
- return { logs: clipped, value };
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
- /** Finalize a failure diagnostic, with output-limit taking precedence over the cap. */
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
- if (this.textBytes(error.message) <= this.maxBytes)
117
- return { logs: clipped, error };
118
- return this.limit(clipped);
119
- }
120
- /** Build the explicit output-limit failure while retaining fitting logs. */
121
- limit(logs) {
122
- const fullMessage = `outer output exceeded ${this.maxBytes} bytes`;
123
- const messageBytes = this.textBytes(fullMessage);
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
- if (retainedBytes + this.textBytes(text) + separatorBytes + messageBytes > this.maxBytes)
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 += this.textBytes(text) + separatorBytes;
151
+ retainedBytes += separatorBytes + entryBytes;
132
152
  }
133
- return { logs: retained, error: { kind: 'output-limit', message: fullMessage } };
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
- this.#confine = argv => provider.confine(argv, { mode: resolved.sandboxMode, workspaceRoot: root });
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
- /** Terminate every session kernel to quiescence (plugin teardown). */
267
- async teardown() {
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` is a best-effort spill hook called only when the run's
279
- * output crosses `maxOutputBytes`: it receives the FULL captured program
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
- env: process.env,
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 kernel = await this.#startKernel(language);
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, { signal });
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 a kernel outcome onto the failure taxonomy through the output ledger.
385
- * Budget expiry owns a run that hit the wall clock (whether or not the
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
- if (timedOut) {
402
- const message = outcome.killed
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
- return ledger.failure(logs, { kind: 'timeout', message });
499
+ result = ledger.failure(logs, { kind: 'timeout', message: spillDiagnostic });
406
500
  }
407
- if (outcome.killed) {
408
- return ledger.failure(logs, { kind: 'abort', message: outcome.message || 'run interrupted' });
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
- return ledger.failure(logs, { kind: 'abort', message: outcome.message || 'run interrupted' });
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
- if (outcome.invalidOutput) {
415
- return ledger.failure(logs, { kind: 'invalid-output', message: outcome.message || 'program completion must be lossless JSON' });
416
- }
417
- return ledger.failure(logs, { kind: 'exception', message: outcome.message || 'program failed' });
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 === 'output-limit' && onOutputLimit !== undefined) {
427
- // The overflow was either captured logs or (for a clean run) a
428
- // completion value too large to survive the JSON serialization budget —
429
- // spill whatever full text we still hold so the caller can recover it.
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
- const hint = await onOutputLimit(spillContent);
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
- // Best-effort by contract: a spill failure keeps the truncated result.
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
- /** Model-facing guide for when and how to use `run_kernel_code`. */
489
- const TOOL_GUIDE = [
490
- 'Prefer run_kernel_code to reading/writing scratch files when the work is computation with intermediate results',
491
- '— sessions keep kernel state (variables, imports, working data) across calls, AND snapshot it to disk after',
492
- 'every successful run, so state survives a kernel crash or restart (the first run after a restore reports what',
493
- 'was restored and what could not be). Omit `session` for one-off computations; give related calls the same',
494
- '`session` id to carry state forward, and pass `reset: true` when the session\'s state is corrupted or unwanted.',
495
- 'Python programs persist module-level variables and functions; JavaScript programs persist via `state` and',
496
- 'top-level assignments. A session reaps idle kernels after the configured timeout; a reaped session resumes',
497
- 'from its snapshot on the next call with the same id.',
498
- ].join(' ');
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
- return {
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
- ctx.effect(() => () => { void manager.teardown().catch(() => { }); });
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: TOOL_GUIDE,
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. Runs as the body of an async function: top-level `await` and `return` are available; return a JSON value to surface it as the result value.' },
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: persist the full captured
615
- // output through ctx.spillStore so an oversized dataframe dump survives
616
- // the result budget. No store, no session owner, or a storage failure
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 (sessionId === undefined || spillStore === undefined)
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: 'kernel-output' },
626
- suggestedName: 'kernel-output.txt',
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
- const result = await manager.run({
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
- ...args.session !== undefined ? { sessionId: args.session } : {},
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,