@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/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.limit(clipped);
109
- 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);
110
118
  }
111
- /** 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
+ */
112
123
  failure(logs, error) {
113
124
  const clipped = this.clipLogs(logs);
114
- if (this.textBytes(error.message) <= this.maxBytes)
115
- return { logs: clipped, error };
116
- return this.limit(clipped);
117
- }
118
- /** Build the explicit output-limit failure while retaining fitting logs. */
119
- limit(logs) {
120
- const fullMessage = `outer output exceeded ${this.maxBytes} bytes`;
121
- 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);
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
- 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)
127
149
  break;
128
150
  retained.push(text);
129
- retainedBytes += this.textBytes(text) + separatorBytes;
151
+ retainedBytes += separatorBytes + entryBytes;
130
152
  }
131
- 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}`;
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
- 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);
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
- /** Terminate every session kernel to quiescence (plugin teardown). */
262
- 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() {
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` is a best-effort spill hook called only when the run's
274
- * output crosses `maxOutputBytes`: it receives the FULL captured program
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: this.#config.pythonPath ?? 'python3',
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
- #startNodejs() {
345
- return KernelHost.start(nodejsKernelProfile(this.#config.nodePath ?? 'node'), this.#startConfig());
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
- #startConfig() {
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
- 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(),
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 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);
360
470
  try {
361
- return await kernel.execute(randomUUID(), code, bindings, { signal });
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 a kernel outcome onto the failure taxonomy through the output ledger.
372
- * Budget expiry owns a run that hit the wall clock (whether or not the
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
- if (timedOut) {
389
- 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
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
- return ledger.failure(logs, { kind: 'timeout', message });
499
+ result = ledger.failure(logs, { kind: 'timeout', message: spillDiagnostic });
393
500
  }
394
- if (outcome.killed) {
395
- 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 });
396
504
  }
397
- if (outcome.cancelled) {
398
- 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 });
399
508
  }
400
- if (outcome.status === 'error') {
401
- if (outcome.invalidOutput) {
402
- return ledger.failure(logs, { kind: 'invalid-output', message: outcome.message || 'program completion must be lossless JSON' });
403
- }
404
- 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);
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 === 'output-limit' && onOutputLimit !== undefined) {
414
- // The overflow was either captured logs or (for a clean run) a
415
- // completion value too large to survive the JSON serialization budget —
416
- // spill whatever full text we still hold so the caller can recover it.
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
- const hint = await onOutputLimit(spillContent);
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
- // 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}` } };
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
- /** Model-facing guide for when and how to use `run_kernel_code`. */
476
- const TOOL_GUIDE = [
477
- 'Prefer run_kernel_code to reading/writing scratch files when the work is computation with intermediate results',
478
- '— sessions keep kernel state (variables, imports, working data) across calls, AND snapshot it to disk after',
479
- 'every successful run, so state survives a kernel crash or restart (the first run after a restore reports what',
480
- 'was restored and what could not be). Omit `session` for one-off computations; give related calls the same',
481
- '`session` id to carry state forward, and pass `reset: true` when the session\'s state is corrupted or unwanted.',
482
- 'Python programs persist module-level variables and functions; JavaScript programs persist via `state` and',
483
- 'top-level assignments. A session reaps idle kernels after the configured timeout; a reaped session resumes',
484
- 'from its snapshot on the next call with the same id.',
485
- ].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
+ }
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
- return {
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
- 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());
555
728
  ctx.systemPrompt.section({
556
729
  name: 'tool:code-runtime-kernels',
557
730
  order: 106,
558
- text: TOOL_GUIDE,
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. 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.' },
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: persist the full captured
602
- // output through ctx.spillStore so an oversized dataframe dump survives
603
- // the result budget. No store, no session owner, or a storage failure
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 (sessionId === undefined || spillStore === undefined)
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: 'kernel-output' },
613
- suggestedName: 'kernel-output.txt',
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
- 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({
625
823
  language: args.language,
626
824
  code: args.code,
627
- ...args.session !== undefined ? { sessionId: args.session } : {},
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,