@hy-sde-org/dsh-code-runtime-kernels 0.2.1-rc.3 → 0.2.2-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -6,7 +6,7 @@ English | [中文](README.zh.md)
6
6
 
7
7
  Two long-lived kernel subprocesses share one host driver:
8
8
 
9
- - **Python** — a long-lived `python3` subprocess running a [self-contained kernel](./src/python/runner.ts) (standard library only — no venv, no pip). Module-level variables and one asyncio event loop persist across cells; top-level `await` works; the last expression is the cell's value.
9
+ - **Python** — a long-lived Python subprocess running a [self-contained kernel](./src/python/runner.ts) (standard library only — no venv, no pip), booted from the first healthy interpreter candidate: `config.pythonPath` probed first, then every `python`/`python3` on PATH. Module-level variables and one asyncio event loop persist across cells; top-level `await` works; the last expression is the cell's value.
10
10
  - **JavaScript** — a long-lived `node` subprocess running a [self-contained kernel](./src/nodejs/runner.ts) (Node builtins only). A persistent `state` object plus the process-global object carry values across cells; every cell runs as an async function body, so top-level `await` and `return` work; `return <json>` carries the completion value.
11
11
 
12
12
  The wire protocol, kernel host driver (spawn + handshake, serialized writes, hostile-peer parsing, SIGINT with SIGTERM/SIGKILL escalation, stdin pipe-failure settlement, shutdown-to-exit), session registry, binding validation, and output ledger are shared (`src/core/`), so both languages behave identically.
@@ -36,16 +36,21 @@ Add the bundle row (or a similar row in any `cordis.yml`):
36
36
 
37
37
  All row ids carry the `hy-sde-` prefix so they never clash with shipped rows (a duplicate loader id fails the boot). Then the model sees the `run_kernel_code` tool.
38
38
 
39
+ ## Upgrading from 0.2.1-rc.5
40
+
41
+ Standalone installations must satisfy the new `@deepseek-ai/dsh-subprocess` peer; supported DSH profiles already provide it. `KernelManager.run` keeps the output-limit callback's first `content` argument and adds an optional second `{ complete }` argument, so existing callbacks need no source change.
42
+
39
43
  ## Config
40
44
 
41
45
  | Key | Default | Meaning |
42
46
  |---|---|---|
43
47
  | `languages` | `['python', 'typescript']` | Enabled languages; a call to a disabled language is refused at call time. |
44
- | `pythonPath` | `python3` | Explicit python executable (PATH discovery by default; fails loud at first spawn when absent). |
48
+ | `pythonPath` | PATH discovery | Explicit python interpreter, probed first; then every `python`/`python3` on PATH in PATH order (first healthy candidate wins; fails loud with per-candidate reasons when none works). |
49
+ | `pythonProbeTimeoutMs` | `5000` | Per-candidate probe budget (a `-c` version check) while resolving the python interpreter. |
45
50
  | `nodePath` | `node` | Explicit node executable (PATH discovery by default). |
46
51
  | `toolTimeoutMs` | `30000` | Cooperative tool-call timeout (`exec.signal` becomes the per-run abort). |
47
52
  | `maxWallMs` | `600000` | Per-run wall-clock budget; interrupt gradates SIGINT → SIGTERM → SIGKILL when the kernel does not respond. |
48
- | `maxOutputBytes` | `67108864` | Combined serialized log-, completion-, and failure-message byte cap (an `'output-limit'` failure). |
53
+ | `maxOutputBytes` | `67108864` | Combined serialized log-, completion-, and failure-message byte cap (an `'output-limit'` failure). A host-capture overflow can spill only its retained prefix and says that the discarded tail is unavailable. |
49
54
  | `maxOutputLineChars` | `4096` | Per-line output cap (chars): a longer line is clipped with a `…` marker so one log bomb cannot own the budget. |
50
55
  | `sessionIdleMs` | `0` | Reap a session whose kernel sits unused for this long (`0` disables; state loss is the explicit cost). |
51
56
  | `interruptEscalationMs` | `5000` | Wait after SIGINT before SIGTERM, then the same again before SIGKILL. |
@@ -55,10 +60,10 @@ All row ids carry the `hy-sde-` prefix so they never clash with shipped rows (a
55
60
  | `snapshotDir` | `~/.dsh/code-runtime-kernels/state` | Snapshot root; files live under `<language>/<session-id-hash>.snapshot`. |
56
61
  | `snapshotMaxBytes` | `134217728` | Combined byte cap for one snapshot file; entries past it are skipped by name. |
57
62
  | `snapshotMaxEntryBytes` | `8388608` | Per-entry byte cap; an entry larger than this is skipped and named. |
58
- | `preload` | `{}` | Session "toolbox": `{ python?: string; typescript?: string }` sources run as one hidden first cell of every fresh session kernel (before the snapshot restores, so a restored name shadows a same-named helper). A preload failure fails the triggering run like an exception. |
63
+ | `preload` | `{}` | Session "toolbox": `{ python?: string; typescript?: string }` sources run as one hidden first cell of every fresh session kernel, with the triggering call's cwd and environment, before snapshot restore. A preload failure fails the triggering run like an exception. |
59
64
  | `pythonImpl` | `'stdlib'` | Python execution semantics: `stdlib` (self-contained runner) or `ipykernel` (a real IPython shell: magics, `!cmd`, display — the interpreter pointed at by `pythonPath` must have IPython installed; the kernel fails loud at boot otherwise). |
60
65
  | `sandboxConfinement` | `false` | Route kernel subprocess spawns through the sandbox seam (structural `confine` capability, see `SandboxProvider` in `@deepseek-ai/dsh-sandbox`) instead of `spawn`ing the interpreter directly. |
61
- | `sandboxProvider` | — | The confinement capability; required when `sandboxConfinement` is `true` (fail closed). |
66
+ | `sandboxProvider` | — | The confinement capability; required when `sandboxConfinement` is `true` (fail closed). Policy receives the owning DSH session id, never the model-chosen kernel sub-session id. |
62
67
  | `sandboxWorkspaceRoot` | `process.cwd()` | Writable root under `workspace-write` confinement. |
63
68
  | `sandboxMode` | `'workspace-write'` | File-effect mode for confined kernels (`'read-only'` or `'workspace-write'`). |
64
69
 
@@ -98,10 +103,13 @@ It resolves the seam's result envelope — `value` (JSON completion), `logs`, `e
98
103
 
99
104
  - **Sessions.** A call with a non-empty `session` runs in that session's kernel; `executionCount` reports the running count. `reset: true` shuts the old kernel down before a fresh one answers.
100
105
  - **One-shot.** Without `session`, a fresh kernel is spawned, exactly one program runs, and the kernel is shut down.
106
+ - **Working directory.** Every tool call resolves the conversation's current working directory. Resolution failures fail the call; a fresh kernel's preload and user cell receive the same directory.
107
+ - **Child environment.** Kernel processes use DSH's credential-safe parent-environment scrub, then add only deliberate runner controls. Ambient credential-shaped and `DSH_*` entries do not reach model code.
101
108
  - **Persistence.** Python: module-level variables and loop state survive across cells. JavaScript: `state` (a long-lived shared object) and sloppy-mode global assignments survive; `const`/`let`/`function`/`class` at cell top level are per-cell (async body), so persistent definitions go on `state`. A cell completes `return <json>` for a completion value, or with no `return` for a no-value run; non-lossless completions (cycles, `BigInt`, sets) are `'invalid-output'`.
109
+ - **JavaScript imports.** Dynamic imports use Node's native ESM loader from the call's working directory, including `exports` import conditions, package `imports`, import attributes, and absolute filesystem paths.
102
110
  - **Snapshots.** After each successful run the namespace is saved (Python: `pickle` + `marshal` for bytecode, per-name loss reporting; JavaScript: V8 binary serialization, so `Map`/`Set`/`Date`/cyclic values survive but function-valued keys are named as lost). A fresh kernel for the session restores the last snapshot once — the restoring run's logs carry `[dsh-kernels] restored N names from snapshot (could not restore: …)`. `reset: true` deletes the snapshot first, so it never resurrects discarded state. Python bytecode is `marshal`-format-dependent: restoring across a Python minor-version upgrade should be expected to lose function/class entries (named in the notice), not data.
103
111
  - **Toolbox.** With `preload` set, every fresh session kernel runs the language's source as one hidden first cell before the snapshot restores: helpers behave like any other session state (they ride snapshots; a restored name shadows a same-named helper). Its output is hidden from the model; a preload failure fails the run it triggered.
104
- - **Budgets and failure kinds.** Wall-clock expiry → `'timeout'`; cancellation or a kernel that had to die → `'abort'`; thrown exceptions → `'exception'`; non-JSON completions → `'invalid-output'`; combined output overflow → `'output-limit'`; kernel death → the session registry replaces the kernel and retries once. All are result FIELDS, never rejections of the tool.
112
+ - **Budgets and failure kinds.** Wall-clock expiry → `'timeout'`; cancellation or a kernel that had to die → `'abort'`; thrown exceptions → `'exception'`; non-JSON completions → `'invalid-output'`; combined output overflow → `'output-limit'`; spontaneous kernel death → `'worker-exit'`. A dead kernel is retired without replaying the failed cell; the next call starts fresh. All are result fields, never tool-call rejections.
105
113
 
106
114
  ## Model experience
107
115
 
@@ -110,6 +118,7 @@ The system-prompt guide tells the model to prefer `run_kernel_code` over scratch
110
118
  ## Known limitations
111
119
 
112
120
  - **A busy synchronous cell resists SIGINT.** A `while (true) {}`/`while True:` loop never yields to the event loop, so the interrupt handler cannot run and the escalation ladder (SIGTERM then SIGKILL) is what actually stops it — costing the kernel's state, hence the session. Cells that yield (async `await` on timers/I/O/tool calls) cancel cleanly and the kernel survives (the wall-clock/timeout tests cover this split).
121
+ - **Capture truncation is irreversible.** When one kernel frame crosses the host capture cap, the result and spill metadata identify the spill as a retained prefix; the discarded tail is not claimed as recoverable.
113
122
  - **State can be poisoned.** A buggy program can corrupt the session's state at any time; `reset: true` is the intended recovery primitive (it also deletes the snapshot, so the corruption cannot come back).
114
123
  - **No security boundary.** Kernel code has bash-equivalent trust, matching the harness's own process backends — and so do snapshot files (`pickle`/`marshal` are not safe to read from untrusted input). Keep `snapshotDir` user-private; a planted snapshot executes as the host.
115
124
  - **Snapshot granularity is per-name.** Python: data, modules, importable callables, and `__main__`-defined functions/classes are saved by value; user-class instances, closures over non-picklables, and entries past the caps are named as lost on the next restore. JavaScript: `state` and sloppy-mode global assignments are saved per key; a function anywhere inside a key's value discards that whole key (named).
package/README.zh.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  两个长期存活的 kernel 子进程共享同一个 host 驱动:
8
8
 
9
- - **Python** —— 一个长寿命 `python3` 子进程,运行[自包含内核](./src/python/runner.ts)(仅标准库,无需 venv/pip)。模块级变量与一个 asyncio 事件循环跨 cell 保留;支持顶层 `await`;最后一个表达式即 cell 的值。
9
+ - **Python** —— 一个长寿命 Python 子进程,运行[自包含内核](./src/python/runner.ts)(仅标准库,无需 venv/pip),从第一个健康的解释器候选启动:先探测 `config.pythonPath`,再探测 PATH 上的每个 `python`/`python3`。模块级变量与一个 asyncio 事件循环跨 cell 保留;支持顶层 `await`;最后一个表达式即 cell 的值。
10
10
  - **JavaScript** —— 一个长寿命 `node` 子进程,运行[自包含内核](./src/nodejs/runner.ts)(仅 Node 内置)。持久 `state` 对象与进程全局对象携带跨 cell 的值;每个 cell 以 async 函数体运行,支持顶层 `await`/`return`;`return <json>` 携带完成值。
11
11
 
12
12
  线上协议、kernel host 驱动(spawn + 握手、串行写入、敌对对端解析、SIGINT→SIGTERM→SIGKILL 升级、stdin 管道失败结算、退出握手)、会话注册表、绑定校验与输出账本全部共享(`src/core/`),两个语言的语义完全一致。
@@ -34,16 +34,21 @@
34
34
 
35
35
  所有行 id 带 `hy-sde-` 前缀以避免与内置行冲突(重复的 loader id 会导致启动失败)。随后模型即看到 `run_kernel_code` 工具。
36
36
 
37
+ ## 从 0.2.1-rc.5 升级
38
+
39
+ 独立安装需满足新增的 `@deepseek-ai/dsh-subprocess` peer;受支持的 DSH profile 已自带该包。`KernelManager.run` 保留 output-limit 回调的首个 `content` 参数,并新增可选的第二个 `{ complete }` 参数,现有回调无需改源码。
40
+
37
41
  ## 配置
38
42
 
39
43
  | 键 | 默认 | 含义 |
40
44
  |---|---|---|
41
45
  | `languages` | `['python', 'typescript']` | 启用的语言;调用未启用语言会被拒绝。 |
42
- | `pythonPath` | `python3` | 显式 python 可执行文件(默认走 PATH 发现;缺失时首次 spawn 即失败)。 |
46
+ | `pythonPath` | PATH 发现 | 显式 python 解释器,最先探测;然后按 PATH 顺序探测每个 `python`/`python3`(第一个健康候选胜出;全部失败时携带逐候选原因失败)。 |
47
+ | `pythonProbeTimeoutMs` | `5000` | 解析 python 解释器时每个候选的探测预算(一次 `-c` 版本检查)。 |
43
48
  | `nodePath` | `node` | 显式 node 可执行文件(默认走 PATH 发现)。 |
44
49
  | `toolTimeoutMs` | `30000` | 协作式工具调用超时(`exec.signal` 变为每次运行的 abort 源)。 |
45
50
  | `maxWallMs` | `600000` | 每次运行的墙钟预算;中断按 SIGINT→SIGTERM→SIGKILL 升级。 |
46
- | `maxOutputBytes` | `67108864` | 日志、完成值与失败消息合并后的字节上限(触发 `'output-limit'`)。 |
51
+ | `maxOutputBytes` | `67108864` | 日志、完成值与失败消息合并后的字节上限(触发 `'output-limit'`)。若 host 捕获上限先溢出,spill 只能保存已保留前缀,并明确说明尾部不可恢复。 |
47
52
  | `maxOutputLineChars` | `4096` | 单行输出上限(字符):更长行以 `…` 截断,防止一条日志炸弹独占预算。 |
48
53
  | `sessionIdleMs` | `0` | 空闲超过该毫秒数的会话被回收(`0` 禁用;状态丢失是显式代价)。 |
49
54
  | `interruptEscalationMs` | `5000` | SIGINT 后等待再发 SIGTERM,再等同样时长发 SIGKILL。 |
@@ -53,10 +58,10 @@
53
58
  | `snapshotDir` | `~/.dsh/code-runtime-kernels/state` | 快照根目录;文件位于 `<language>/<session-id-hash>.snapshot`。 |
54
59
  | `snapshotMaxBytes` | `134217728` | 单个快照文件的合并字节上限;超出的条目按名跳过。 |
55
60
  | `snapshotMaxEntryBytes` | `8388608` | 单条字节上限;超出的条目按名跳过。 |
56
- | `preload` | `{}` | 会话“工具箱”:`{ python?: string; typescript?: string }`,在每个新会话 kernel 上先作为隐藏首 cell 运行(快照恢复之前;同名恢复值会遮蔽助手)。preload 失败则本次运行报错。 |
61
+ | `preload` | `{}` | 会话“工具箱”:`{ python?: string; typescript?: string }`,在每个新会话 kernel 上以触发调用的 cwd 与环境作为隐藏首 cell 运行,再恢复快照。preload 失败则本次运行报错。 |
57
62
  | `pythonImpl` | `'stdlib'` | Python 执行语义:`stdlib`(自包含 runner)或 `ipykernel`(真实 IPython shell:魔法命令、`!cmd`、display——`pythonPath` 指向的解释器需装有 IPython,否则启动即报错)。 |
58
63
  | `sandboxConfinement` | `false` | 将 kernel 子进程经沙箱接缝启动(结构式 `confine` 能力,见 `@deepseek-ai/dsh-sandbox` 的 `SandboxProvider`)而非直接 spawn。 |
59
- | `sandboxProvider` | — | 约束能力;`sandboxConfinement: true` 时必须提供(fail closed)。 |
64
+ | `sandboxProvider` | — | 约束能力;`sandboxConfinement: true` 时必须提供(fail closed)。策略接收所属 DSH 会话 id,绝不接收模型选择的 kernel 子会话 id。 |
60
65
  | `sandboxWorkspaceRoot` | `process.cwd()` | `workspace-write` 模式下的可写根目录。 |
61
66
  | `sandboxMode` | `'workspace-write'` | 被约束 kernel 的文件效应模式(`'read-only'` 或 `'workspace-write'`)。 |
62
67
 
@@ -95,10 +100,13 @@ runner 不自带 Python——它 spawn `pythonPath` 指向的解释器。要用
95
100
 
96
101
  - **会话**。带非空 `session` 的调用运行于该会话的 kernel;`executionCount` 报告累计次数。`reset: true` 先关旧 kernel 再开新 kernel 响应。
97
102
  - **一次性**。没有 `session` 时,spawn 一个新 kernel,恰好运行一个程序后关闭。
103
+ - **工作目录**。每次工具调用都解析会话当前工作目录;解析失败即令调用失败。新 kernel 的 preload 与用户 cell 使用同一目录。
104
+ - **子进程环境**。kernel 使用 DSH 统一的凭据安全父环境清除策略,再加入显式 runner 控制项;环境中的凭据型变量与 `DSH_*` 不会进入模型代码。
98
105
  - **持久化**。Python:模块级变量与循环状态跨 cell 保留。JavaScript:`state`(长寿命共享对象)与 sloppy 全局赋值跨 cell 保留;cell 顶层的 `const`/`let`/`function`/`class` 是每 cell 作用域(async 函数体),持久定义请放 `state`。cell 以 `return <json>` 携带完成值,或以无 `return` 结束为无值运行;非 lossless JSON 完成值(环、`BigInt`、集合)判为 `'invalid-output'`。
106
+ - **JavaScript 导入**。动态导入从调用工作目录使用 Node 原生 ESM loader,支持 `exports` import 条件、package `imports`、import attributes 与绝对文件路径。
99
107
  - **快照**。每次成功运行后保存命名空间(Python:`pickle` + `marshal` 字节码,逐名报告丢失;JavaScript:V8 二进制序列化,`Map`/`Set`/`Date`/环可保留,函数值键按名判丢)。该会话的新 kernel 只恢复一次最近快照——恢复运行日志中带 `[dsh-kernels] restored N names from snapshot (could not restore: …)`。`reset: true` 先删除快照,杜绝回魂。Python 字节码依赖 `marshal` 格式:跨 Python 小版本升级恢复时函数/类条目可能报丢(指名),数据不受影响。
100
108
  - **工具箱**。配置 `preload` 后,每个新会话 kernel 会先把该语言的源码作为隐藏首 cell 运行(先于快照恢复):助手与普通会话状态一样参与快照,同名恢复值遮蔽同名助手。其输出对模型隐藏;preload 失败则本次运行报错。
101
- - **预算与失败种类**。墙钟超时 → `'timeout'`;取消或被迫终止 → `'abort'`;抛异常 → `'exception'`;非 JSON 完成 → `'invalid-output'`;合并输出溢出 → `'output-limit'`;kernel 死亡 → 会话注册表替换 kernel 并重试一次。全部是结果字段,绝不会 reject 工具调用。
109
+ - **预算与失败种类**。墙钟超时 → `'timeout'`;取消或被迫终止 → `'abort'`;抛异常 → `'exception'`;非 JSON 完成 → `'invalid-output'`;合并输出溢出 → `'output-limit'`;kernel 自发死亡 → `'worker-exit'`。死亡 kernel 会被退役,但失败 cell 不会重放;下一次调用启动新 kernel。全部是结果字段,绝不会 reject 工具调用。
102
110
 
103
111
  ## 模型体验
104
112
 
@@ -107,6 +115,7 @@ runner 不自带 Python——它 spawn `pythonPath` 指向的解释器。要用
107
115
  ## 已知限制
108
116
 
109
117
  - **同步忙循环抗拒 SIGINT**。`while (true) {}` / `while True:` 永不交还事件循环,中断处理器无法运行,实际由升级梯(SIGTERM 再 SIGKILL)终止——代价是会话状态与 kernel。会让出事件循环的 cell(对定时器/IO/工具调用的 `await`)可被干净取消,kernel 存活(墙钟/中止测试即覆盖这一分界)。
118
+ - **捕获截断不可逆**。单个 kernel 帧越过 host 捕获上限时,结果与 spill 元数据会把保存内容标为已保留前缀,不会声称被丢弃尾部可恢复。
110
119
  - **状态可能被污染**。错误程序随时可能弄坏会话状态;`reset: true` 是设计的恢复原语(同时删除快照,污染不会复活)。
111
120
  - **无安全边界**。kernel 代码拥有与内置 process 后端相同的 bash 级信任——快照文件同理(`pickle`/`marshal` 不可用于不可信输入);请保持 `snapshotDir` 为用户私有。
112
121
  - **快照按名粒度**。Python:数据、模块、可导入调用及 `__main__` 内定义的函数/类按值保存;用户类实例、含不可 pickle 闭包者、超限条目在下次恢复时点名报告。JavaScript:`state` 与 sloppy 全局赋值按键保存;键值内任意位置出现函数即丢弃整键(点名)。
@@ -10,6 +10,7 @@
10
10
  * @module @hy-sde-org/dsh-code-runtime-kernels/src/core/kernel
11
11
  */
12
12
  import type { PtcBindingNamespace, PtcJsonValue } from '@deepseek-ai/dsh-ptc-runtime';
13
+ import type { SessionId } from '@deepseek-ai/dsh-session';
13
14
  import type { DoneFrame, KernelFrame, KernelHostMessage, SnapshotSpec } from './protocol.ts';
14
15
  export type { DoneFrame, KernelFrame, KernelHostMessage, SnapshotSpec };
15
16
  /** How to spawn and label one language's kernel. */
@@ -49,29 +50,63 @@ export interface KernelStartConfig {
49
50
  shutdownGraceMs: number;
50
51
  /**
51
52
  * Confinement wrapper applied to the fully-assembled argv (command +
52
- * argvPrefix + runner) just before spawn — e.g. the output of
53
+ * argvPrefix + runner) just before spawn — e.g. wrapping
53
54
  * {@link KernelSandboxProvider.confine} so the kernel launches under real
54
55
  * filesystem confinement (bwrap / landlock-run / seatbelt). Must fail
55
- * closed: a non-enforcing return is the provider's bug, not a fallback.
56
- * The wrapper becomes the process-group leader; the escalation ladder
57
- * unwinds through it.
56
+ * closed: a rejection or a non-enforcing return is the provider's bug, not
57
+ * a fallback. The wrapper becomes the process-group leader; the escalation
58
+ * ladder unwinds through it.
58
59
  */
59
- confine?: (argv: readonly string[]) => {
60
+ confine?: (argv: readonly string[], signal?: AbortSignal, sessionId?: SessionId) => Promise<{
60
61
  argv: string[];
61
- };
62
+ }>;
63
+ /**
64
+ * Cancellation for the confinement call itself (the triggering run's
65
+ * signal): an aborted or failing confine fails the start structured, never
66
+ * the host process.
67
+ */
68
+ signal?: AbortSignal;
69
+ /**
70
+ * Owning DSH session id, when the run belongs to one — forwarded into the
71
+ * confinement policy so per-session sandbox grants apply.
72
+ */
73
+ sandboxSessionId?: SessionId;
74
+ /**
75
+ * Upper bound on captured log bytes per run. On overflow the host retains a
76
+ * UTF-8-safe prefix and marks the missing tail; `undefined` disables the cap.
77
+ */
78
+ captureCapBytes?: number;
62
79
  }
63
80
  /**
64
81
  * The sandbox seam's confine capability, structurally typed (no runtime
65
82
  * dependency on `@deepseek-ai/dsh-sandbox`): wrap exact argv under a
66
- * file-effect policy, or fail closed. See the published seam for the contract.
83
+ * file-effect policy, or fail closed. ASYNC, matching the real harness
84
+ * provider (`confine(…): Promise<ConfinedArgv>`) — a synchronous stand-in is
85
+ * still accepted structurally only by tests; production providers resolve.
67
86
  */
87
+ export interface KernelSandboxPolicy {
88
+ mode: 'read-only' | 'workspace-write';
89
+ workspaceRoot: string;
90
+ /** Owning DSH session, when the run has one (forwarded to the provider). */
91
+ sessionId?: SessionId;
92
+ }
68
93
  export interface KernelSandboxProvider {
69
- confine(argv: readonly string[], policy: {
70
- mode: 'read-only' | 'workspace-write';
71
- workspaceRoot: string;
72
- }): {
94
+ confine(argv: readonly string[], policy: KernelSandboxPolicy, signal?: AbortSignal): Promise<{
73
95
  argv: string[];
74
- };
96
+ }>;
97
+ }
98
+ /** Structured snapshot/persistence status reported by the runners. */
99
+ export interface KernelPersistenceStatus {
100
+ /** Names persisted by the last successful run's save. */
101
+ saved?: number;
102
+ /** Names dropped by the save (over the per-entry/total caps). */
103
+ saveLost?: string[];
104
+ /** Save failure cause, when the snapshot could not be written at all. */
105
+ saveError?: string;
106
+ /** Names restored from the snapshot at kernel start. */
107
+ restored?: number;
108
+ /** Snapshot names that could not be restored. */
109
+ restoreLost?: string[];
75
110
  }
76
111
  /** The outcome of one kernel execution; budgets and kind mapping stay with the provider. */
77
112
  export interface KernelExecResult {
@@ -93,6 +128,12 @@ export interface KernelExecResult {
93
128
  message: string;
94
129
  /** True when the kernel had to be terminated to settle this run. */
95
130
  killed: boolean;
131
+ /** True when the kernel process died without host-initiated termination (maps to `worker-exit`). */
132
+ crashed?: boolean;
133
+ /** True when host-side capture discarded an output tail. */
134
+ captureTruncated?: boolean;
135
+ /** Snapshot persistence status when the run carried a snapshot spec. */
136
+ persistence?: KernelPersistenceStatus;
96
137
  }
97
138
  /** The Node.js runner shipped as a package file (raw source in development, compiled ESM in the output). */
98
139
  declare const RUNNER_PATH: string;
@@ -1 +1 @@
1
- {"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../../src/core/kernel.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"kernel.d.ts","sourceRoot":"","sources":["../../src/core/kernel.ts"],"names":[],"mappings":"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"}