Merge pull request #5738 from deepseek-harness/worktree/python-ptc-sandbox

fix(ptc): apply shared sandbox policy to Python execution
This commit is contained in:
Tianyi Cui authored and GitHub committed 2026-10-05 19:29:24 +08:00
commit 2de9059b4f
35 files changed
+1054 -524

No files matched your search

@@ -12,8 +12,8 @@
en: f0d0d5ba5a9066ad
zh: fbdab3731c33eb26
/agent-note-the-ptc-runtime-python-fd-3-frame-protocol/wire-contract:
en: 913f9465320dc191
zh: f8e0338645d6c204
en: 1225a32af91fcf84
zh: 1dab4ecbd9ff7e34
/agent-note-the-ptc-runtime-python-fd-3-frame-protocol/mirror-alignment:
en: 26128b65f2763920
zh: df24359faebcbfed
@@ -26,7 +26,7 @@ The package ships the runtime alongside the protocol; it remains independently b
## Wire contract
Frames are JSON-lines on fd 3, one object per line, leaving stdout/stderr free for the program's own output. Child → host: `boot-ack`, `call`, `log`, `done`. Host → child: `boot` (first frame), `run` (after `boot-ack`), and one `reply` per `call`. The `log` frame's `truncated` flag marks the frame that IS the child ledger's own truncation marker, so the host stops capturing at the same point the child did instead of inferring it from its own budget. The `log` frame's `open` flag marks an unterminated line committed by an explicit flush: the host holds it and appends the next frame to the same entry, so an explicit flush followed by more text reads back as one line rather than a fake newline. The one exception is truncation: when a later over-budget frame trips the ledger, the already-billed prefix is committed as its own entry and the truncation marker follows it (marker last, no re-charge). The merged entry's wire cost is billed exactly once, split incrementally across its fragments on both sides (O(k) for k fragments, never a re-walk of the whole hold): the FIRST fragment pays the full JSON-string cost plus the separator, each continuation and the closing frame pay only their content; the host's exact-cost caps are `logBudget - 1` for a first fragment (the ledger's reserved byte, matching `admit`) and `logBudget + 2` for a continuation or closing frame (billed without the two quotes), and `jsonStringCostUpTo` returns `undefined` below a 2-byte cap; the child keys its split billing off `_open_started` alone, so a closing frame bills as the merged tail. `done.error.kind` is one of `exception`, `invalid-output`, `output-limit`; wall/CPU budgets, aborts, and substrate death are observed host-side, not carried as frames.
Frames are JSON-lines on fd 3, one object per line, leaving stdout/stderr free for the program's own output. Child → host: `boot-ack`, `call`, `log`, `done`. Host → child: `boot` (first frame), `run` (after `boot-ack`), and one `reply` per `call`. The `log` frame's `truncated` flag marks the frame that IS the child ledger's own truncation marker, so the host stops capturing at the same point the child did instead of inferring it from its own budget. The `log` frame's `open` flag marks an unterminated line committed by an explicit flush: the host holds it and appends the next frame to the same entry, so an explicit flush followed by more text reads back as one line rather than a fake newline. The one exception is truncation: when a later over-budget frame trips the ledger, the already-billed prefix is committed as its own entry and the truncation marker follows it (marker last, no re-charge). The merged entry's wire cost is billed exactly once, split incrementally across its fragments on both sides (O(k) for k fragments, never a re-walk of the whole hold): the FIRST fragment pays the full JSON-string cost plus the separator, each continuation and the closing frame pay only their content; the host's exact-cost caps are `logBudget - 1` for a first fragment (the ledger's reserved byte, matching `admit`) and `logBudget + 2` for a continuation or closing frame (billed without the two quotes), and `jsonStringCostUpTo` returns `undefined` below a 2-byte cap; the child keys its split billing off `_open_started` alone, so a closing frame bills as the merged tail. `done.error.kind` is one of `exception`, `invalid-output`, `output-limit`, or `timeout` from the CPU check after model code returns; wall deadlines, aborts, and substrate death are observed host-side. The post-return CPU check attempts a diagnostic on fd 3 before mandatory signal termination because a sandbox launcher can convert that signal into an ambiguous exit code. Ordinary soft-limit expiry retains default `SIGXCPU` termination without a Python handler, so native calls cannot postpone enforcement until Python resumes. These frames remain untrusted outcome reports; kernel resource limits enforce the CPU ceiling independently.
## Mirror alignment
@@ -26,7 +26,7 @@ CPython PTC 运行时位于 `packages/experimental/ptc-runtime-python`,以 `@d
## Wire contract
帧是 fd 3 上的 JSON-lines,每行一个对象,让 stdout/stderr 空出给程序自己的输出。Child → host:`boot-ack`、`call`、`log`、`done`。Host → child:`boot`(首帧)、`run`(在 `boot-ack` 之后)、以及每个 `call` 对应一个 `reply`。`log` 帧的 `truncated` 标志标记那个本身就是子进程 ledger 截断标记的帧,使 host 在与子进程相同的点停止捕获,而不是从自己的预算去推断。`log` 帧的 `open` 标志标记由显式 flush 提交的未结束行:宿主持有它并把下一个帧追加到同一条目,因此显式 flush 后接更多文本读回为一行而不是假换行。唯一例外是截断:当后续超预算帧触发账本时,已计费的前缀作为独立条目先提交,截断 marker 跟在后面(marker 保持末位,无重复计费)。合并条目的线上成本恰好计费一次,在两侧按片段增量分摊(k 个片段 O(k),绝不对整个持有重走):首片段付完整 JSON 字符串成本加分隔符,每个续接与闭合帧只付内容;宿主精确成本 cap 是首片段 `logBudget - 1`(账本预留字节,与 `admit` 一致)、续接或闭合帧 `logBudget + 2`(不含两个引号计费),且 `jsonStringCostUpTo` 在低于 2 字节 cap 时返回 `undefined`;子进程按 `_open_started` 单独键控拆分计费,因此闭合帧按合并尾部计费。`done.error.kind` 是 `exception`、`invalid-output`、`output-limit` 之一;wall/CPU 预算、abort、substrate 死亡都在 host 侧观测,不作为帧携带。
帧是 fd 3 上的 JSON-lines,每行一个对象,让 stdout/stderr 空出给程序自己的输出。Child → host:`boot-ack`、`call`、`log`、`done`。Host → child:`boot`(首帧)、`run`(在 `boot-ack` 之后)、以及每个 `call` 对应一个 `reply`。`log` 帧的 `truncated` 标志标记那个本身就是子进程 ledger 截断标记的帧,使 host 在与子进程相同的点停止捕获,而不是从自己的预算去推断。`log` 帧的 `open` 标志标记由显式 flush 提交的未结束行:宿主持有它并把下一个帧追加到同一条目,因此显式 flush 后接更多文本读回为一行而不是假换行。唯一例外是截断:当后续超预算帧触发账本时,已计费的前缀作为独立条目先提交,截断 marker 跟在后面(marker 保持末位,无重复计费)。合并条目的线上成本恰好计费一次,在两侧按片段增量分摊(k 个片段 O(k),绝不对整个持有重走):首片段付完整 JSON 字符串成本加分隔符,每个续接与闭合帧只付内容;宿主精确成本 cap 是首片段 `logBudget - 1`(账本预留字节,与 `admit` 一致)、续接或闭合帧 `logBudget + 2`(不含两个引号计费),且 `jsonStringCostUpTo` 在低于 2 字节 cap 时返回 `undefined`;子进程按 `_open_started` 单独键控拆分计费,因此闭合帧按合并尾部计费。`done.error.kind` 是 `exception`、`invalid-output`、`output-limit` 或模型代码返回后 CPU 检查产生的 `timeout` 之一;wall 截止、abort 和 substrate 死亡在 host 侧观测。返回后的 CPU 检查会在强制信号终止前尝试通过 fd 3 报告诊断,因为沙箱 launcher 可能把该信号转换为有歧义的退出码。普通软限制到期保留默认的 `SIGXCPU` 终止行为,不安装 Python handler,因此原生调用不能把强制执行延后到 Python 恢复运行。这些帧仍是不可信的结果报告;内核资源限制独立强制执行 CPU 上限。
## Mirror alignment
@@ -12,8 +12,8 @@
en: cf072f53de09faca
zh: 9edd5c4a2bfaae5a
/agent-note-sandboxed-node-execution-for-ptc/decision/resolved-inputs-and-policy:
en: e93df995efab569a
zh: 850daf02d1207028
en: 3aef37bb4f8a8e53
zh: a7b477324d486ab3
/agent-note-sandboxed-node-execution-for-ptc/decision/control-and-lifetime:
en: 2c7a694b04951772
zh: 133b95b0477b127f
@@ -22,7 +22,7 @@ The host preserves `ELECTRON_RUN_AS_NODE` for child startup; the bootstrap remov
File mode, observed denial and enforcement completeness travel in `PtcRunResult.sandbox` separately from the program outcome. Restricted execution fails if the required sandbox backend cannot launch. Full access is an explicit policy mode. Program success does not prove full enforcement, and neither the `process` descriptor nor the extra control pipe claims multi-tenant isolation.
The private Python provider keeps its existing execution implementation and configured wall deadline. Its resolver accepts cwd but rejects an explicit file policy or per-call timeout override; a capability descriptor never silently grants unsupported protection.
The [experimental Python provider](../../../../packages/experimental/ptc-runtime-python/README.md) shares the resolved file policy and sandbox diagnostics while retaining its local Unix execution and configured wall deadline. Per-call timeout overrides remain unsupported.
### Control and lifetime
@@ -22,7 +22,7 @@ Host 在子进程启动时保留 `ELECTRON_RUN_AS_NODE`;bootstrap 在求值前
文件模式、观察到的拒绝与强制完整性通过 `PtcRunResult.sandbox` 独立于程序结果传递。所需沙箱后端无法启动时,受限执行失败。完整访问是显式策略模式。程序成功不证明完整强制能力,`process` 描述符与额外控制管道也不声明多租户隔离。
私有 Python 提供方保留现有执行实现与配置的经过时间截止。其解析器接受 cwd,但拒绝显式文件策略或单次 timeout 覆盖;能力描述符不会静默授予不受支持的保护。
[实验性 Python 提供方](../../../../packages/experimental/ptc-runtime-python/README.zh.md)共享已解析文件策略与沙箱诊断,同时保留本地 Unix 执行和配置的经过时间截止。仍不支持单次 timeout 覆盖。
### 控制与生命周期
+2 -1
View File
@@ -1063,7 +1063,8 @@ export interface InspectorOptions {
## `@deepseek-ai/dsh-experimental-ptc-runtime-python`
- `source`: [`packages/experimental/ptc-runtime-python/src/index.ts:42`](../packages/experimental/ptc-runtime-python/src/index.ts)
- `inject`: `sandbox` · `sandboxPolicy`
- `source`: [`packages/experimental/ptc-runtime-python/src/index.ts:45`](../packages/experimental/ptc-runtime-python/src/index.ts)
```ts config-catalog
/** Plugin config: every cap, changeable from `cordis.yml` (no hardcoded tunables). */
+2 -1
View File
@@ -1065,7 +1065,8 @@ export interface InspectorOptions {
## `@deepseek-ai/dsh-experimental-ptc-runtime-python`
- `source`: [`packages/experimental/ptc-runtime-python/src/index.ts:42`](../packages/experimental/ptc-runtime-python/src/index.ts)
- `inject`: `sandbox` · `sandboxPolicy`
- `source`: [`packages/experimental/ptc-runtime-python/src/index.ts:45`](../packages/experimental/ptc-runtime-python/src/index.ts)
```ts config-catalog
/** Plugin config: every cap, changeable from `cordis.yml` (no hardcoded tunables). */
+6 -4
View File
@@ -590,9 +590,6 @@ flowchart TD
pkg_config_editor --> pkg_hmr
pkg_experimental_api_speech_to_text --> pkg_experimental_speech_to_text
pkg_experimental_api_speech_to_text --> pkg_typert_protocol
pkg_experimental_ptc_runtime_python --> pkg_ptc_runtime
pkg_experimental_ptc_runtime_python --> pkg_timeout
pkg_experimental_ptc_runtime_python --> pkg_util_values
pkg_experimental_speech_to_text_sensevoice --> pkg_experimental_speech_to_text
pkg_experimental_speech_to_text_sensevoice --> pkg_subprocess
pkg_lsp_stdio --> pkg_brand
@@ -724,6 +721,11 @@ flowchart TD
pkg_deepseek_account_platform --> pkg_credentials
pkg_deepseek_account_platform --> pkg_deepseek_account
pkg_deepseek_account_platform --> pkg_host_webserver
pkg_experimental_ptc_runtime_python --> pkg_ptc_runtime
pkg_experimental_ptc_runtime_python --> pkg_sandbox
pkg_experimental_ptc_runtime_python --> pkg_sandbox_policy
pkg_experimental_ptc_runtime_python --> pkg_timeout
pkg_experimental_ptc_runtime_python --> pkg_util_values
pkg_command_feedback --> pkg_anonymous_user_id
pkg_command_feedback --> pkg_commands
pkg_command_feedback --> pkg_session
@@ -1562,7 +1564,6 @@ flowchart TD
| [`api-workspace-controller`](../packages/api/workspace-controller) | `api` | [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`host-directory-picker`](../packages/host/directory-picker), [`session`](../packages/core/session), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol), [`workspace`](../packages/workspace/workspace) |
| [`config-editor`](../packages/boot/config-editor) | `boot` | [`app-boot`](../packages/boot/app-boot), [`hmr`](../packages/boot/hmr) |
| [`experimental-api-speech-to-text`](../packages/experimental/api-speech-to-text) | `experimental` | [`experimental-speech-to-text`](../packages/experimental/speech-to-text), [`typert-protocol`](../packages/typert/protocol) |
| [`experimental-ptc-runtime-python`](../packages/experimental/ptc-runtime-python) | `experimental` | [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`timeout`](../packages/util/timeout), [`util-values`](../packages/util/values) |
| [`experimental-speech-to-text-sensevoice`](../packages/experimental/speech-to-text-sensevoice) | `experimental` | [`experimental-speech-to-text`](../packages/experimental/speech-to-text), [`subprocess`](../packages/subprocess/subprocess) |
| [`lsp-stdio`](../packages/lsp/lsp-stdio) | `lsp` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
| [`bash-local`](../packages/shell/bash-local) | `shell` | [`shell`](../packages/shell/shell), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1594,6 +1595,7 @@ flowchart TD
| [`api-account-controller`](../packages/api/account-controller) | `api` | [`agent`](../packages/core/agent), [`deepseek-account`](../packages/credentials/deepseek-account), [`typert-protocol`](../packages/typert/protocol) |
| [`compaction`](../packages/compaction/compaction) | `compaction` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`deepseek-account-platform`](../packages/credentials/deepseek-account-platform) | `credentials` | [`authorization`](../packages/credentials/authorization), [`credentials`](../packages/credentials/credentials), [`deepseek-account`](../packages/credentials/deepseek-account), [`host-webserver`](../packages/host/webserver) |
| [`experimental-ptc-runtime-python`](../packages/experimental/ptc-runtime-python) | `experimental` | [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`timeout`](../packages/util/timeout), [`util-values`](../packages/util/values) |
| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`commands`](../packages/interaction/commands), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) |
| [`permission-presets`](../packages/interaction/permission-presets) | `interaction` | [`commands`](../packages/interaction/commands), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`shell`](../packages/shell/shell), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval) |
| [`jobs-local`](../packages/jobs/jobs-local) | `jobs` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`scope`](../packages/core/scope), [`timeout`](../packages/util/timeout) |
+6 -4
View File
@@ -592,9 +592,6 @@ flowchart TD
pkg_config_editor --> pkg_hmr
pkg_experimental_api_speech_to_text --> pkg_experimental_speech_to_text
pkg_experimental_api_speech_to_text --> pkg_typert_protocol
pkg_experimental_ptc_runtime_python --> pkg_ptc_runtime
pkg_experimental_ptc_runtime_python --> pkg_timeout
pkg_experimental_ptc_runtime_python --> pkg_util_values
pkg_experimental_speech_to_text_sensevoice --> pkg_experimental_speech_to_text
pkg_experimental_speech_to_text_sensevoice --> pkg_subprocess
pkg_lsp_stdio --> pkg_brand
@@ -726,6 +723,11 @@ flowchart TD
pkg_deepseek_account_platform --> pkg_credentials
pkg_deepseek_account_platform --> pkg_deepseek_account
pkg_deepseek_account_platform --> pkg_host_webserver
pkg_experimental_ptc_runtime_python --> pkg_ptc_runtime
pkg_experimental_ptc_runtime_python --> pkg_sandbox
pkg_experimental_ptc_runtime_python --> pkg_sandbox_policy
pkg_experimental_ptc_runtime_python --> pkg_timeout
pkg_experimental_ptc_runtime_python --> pkg_util_values
pkg_command_feedback --> pkg_anonymous_user_id
pkg_command_feedback --> pkg_commands
pkg_command_feedback --> pkg_session
@@ -1564,7 +1566,6 @@ flowchart TD
| [`api-workspace-controller`](../packages/api/workspace-controller) | `api` | [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`host-directory-picker`](../packages/host/directory-picker), [`session`](../packages/core/session), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol), [`workspace`](../packages/workspace/workspace) |
| [`config-editor`](../packages/boot/config-editor) | `boot` | [`app-boot`](../packages/boot/app-boot), [`hmr`](../packages/boot/hmr) |
| [`experimental-api-speech-to-text`](../packages/experimental/api-speech-to-text) | `experimental` | [`experimental-speech-to-text`](../packages/experimental/speech-to-text), [`typert-protocol`](../packages/typert/protocol) |
| [`experimental-ptc-runtime-python`](../packages/experimental/ptc-runtime-python) | `experimental` | [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`timeout`](../packages/util/timeout), [`util-values`](../packages/util/values) |
| [`experimental-speech-to-text-sensevoice`](../packages/experimental/speech-to-text-sensevoice) | `experimental` | [`experimental-speech-to-text`](../packages/experimental/speech-to-text), [`subprocess`](../packages/subprocess/subprocess) |
| [`lsp-stdio`](../packages/lsp/lsp-stdio) | `lsp` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
| [`bash-local`](../packages/shell/bash-local) | `shell` | [`shell`](../packages/shell/shell), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1596,6 +1597,7 @@ flowchart TD
| [`api-account-controller`](../packages/api/account-controller) | `api` | [`agent`](../packages/core/agent), [`deepseek-account`](../packages/credentials/deepseek-account), [`typert-protocol`](../packages/typert/protocol) |
| [`compaction`](../packages/compaction/compaction) | `compaction` | [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`deepseek-account-platform`](../packages/credentials/deepseek-account-platform) | `credentials` | [`authorization`](../packages/credentials/authorization), [`credentials`](../packages/credentials/credentials), [`deepseek-account`](../packages/credentials/deepseek-account), [`host-webserver`](../packages/host/webserver) |
| [`experimental-ptc-runtime-python`](../packages/experimental/ptc-runtime-python) | `experimental` | [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`timeout`](../packages/util/timeout), [`util-values`](../packages/util/values) |
| [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`anonymous-user-id`](../packages/identity/anonymous-user-id), [`commands`](../packages/interaction/commands), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) |
| [`permission-presets`](../packages/interaction/permission-presets) | `interaction` | [`commands`](../packages/interaction/commands), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`shell`](../packages/shell/shell), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval) |
| [`jobs-local`](../packages/jobs/jobs-local) | `jobs` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`scope`](../packages/core/scope), [`timeout`](../packages/util/timeout) |
@@ -0,0 +1,16 @@
# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
# After editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-alpha.1/python-ptc-sandbox/guide.md
/:
en: 37441fc2c29e3ee9
zh: de434de0f9da7d40
/python-ptc-applies-the-shared-file-sandbox:
en: 655754b417fa8699
zh: 5571cb25b6621c07
/python-ptc-applies-the-shared-file-sandbox/change:
en: a4575a117b53ce7c
zh: 2ea9f832b2179537
/python-ptc-applies-the-shared-file-sandbox/migration:
en: faaefac69870d31f
zh: 08398580b7e3ac62
@@ -0,0 +1,21 @@
---
kind: upgrade-guide
description: "Python PTC compositions require sandbox services, and direct Python file operations follow the resolved file policy."
---
# Python PTC applies the shared file sandbox
English | [中文](guide.zh.md)
## Change
`@deepseek-ai/dsh-experimental-ptc-runtime-python` requires `sandbox` and `sandboxPolicy`. Previously, direct Python file operations ran without confinement and the provider rejected explicit `sandboxPolicy` inputs. It now applies the shared policy to each program and reports confinement in `PtcRunResult.sandbox`. A restricted run fails with `sandbox-unavailable` when confinement cannot be established.
This affects custom compositions that select the Python runtime. Shipped profiles continue to use the Node runtime. Python remains local to macOS or Linux; its configured resource budgets and unsupported per-call timeout overrides remain unchanged.
## Migration
1. In the `cordis.yml` or profile patch that selects the Python runtime, retain the existing shared sandbox services. If they are absent, mount `@deepseek-ai/dsh-sandbox-local` and `@deepseek-ai/dsh-sandbox-policy` with its required `@deepseek-ai/dsh-session-projection` service. See the [Python runtime requirements](../../../../packages/experimental/ptc-runtime-python/README.md#use-this-package).
2. Set the shared `sandbox-policy` row's `mode` and `workspaceRoot` for agentless calls. Its default mode is `read-only`; `workspace-write` permits workspace writes. PTC tool calls use the Session's resolved policy and directory. Do not add a separate Python-only sandbox setting.
3. Direct service callers use `runtime.run(runtime.resolve(request))`; pass a trusted `sandboxPolicy` only when an explicit override is required. Model-facing `run_code` uses the existing approval flow for a one-call wider mode, without changing nested tools' permissions or replaying the program automatically.
4. Verify a program can write inside the intended workspace under `workspace-write`, fails to write outside it, and returns `result.sandbox.mode` and `result.sandbox.enforcement`. Under `read-only`, direct file writes fail. Inspect `sandbox-unavailable` separately from a denied file operation and repair the local sandbox installation before retrying.
@@ -0,0 +1,21 @@
---
kind: upgrade-guide
description: "Python PTC 组合需要沙箱服务,且直接 Python 文件操作遵循已解析文件策略。"
---
# Python PTC 应用共享文件沙箱
[English](guide.md) | 中文
## 变更
`@deepseek-ai/dsh-experimental-ptc-runtime-python` 需要 `sandbox` 和 `sandboxPolicy`。此前,直接 Python 文件操作不受约束,提供方拒绝显式 `sandboxPolicy` 输入。现在,它为每个程序应用共享策略,并通过 `PtcRunResult.sandbox` 报告约束情况。无法建立约束时,受限运行以 `sandbox-unavailable` 失败。
这影响选择 Python 运行时的自定义组合。已发布 profile 继续使用 Node 运行时。Python 仍限于本地 macOS 或 Linux;其配置的资源预算保持不变,仍不支持单次 timeout 覆盖。
## 迁移
1. 在选择 Python 运行时的 `cordis.yml` 或 profile patch 中,保留已有共享沙箱服务。若尚未提供,挂载 `@deepseek-ai/dsh-sandbox-local` 和 `@deepseek-ai/dsh-sandbox-policy`,以及后者所需的 `@deepseek-ai/dsh-session-projection` 服务。参见 [Python 运行时要求](../../../../packages/experimental/ptc-runtime-python/README.zh.md#use-this-package)。
2. 为无 Agent 调用设置共享 `sandbox-policy` 行的 `mode` 和 `workspaceRoot`。默认模式是 `read-only`;`workspace-write` 允许工作区写入。PTC 工具调用使用 Session 的已解析策略和目录。不要新增 Python 专用沙箱设置。
3. 直接服务调用方使用 `runtime.run(runtime.resolve(request))`;仅在需要显式覆盖时传入可信 `sandboxPolicy`。面向模型的 `run_code` 通过现有审批流程为一次调用扩大权限,不改变嵌套工具的权限,也不自动重放程序。
4. 验证程序在 `workspace-write` 下可以写入预期工作区、写入工作区外时失败,并返回 `result.sandbox.mode` 和 `result.sandbox.enforcement`。在 `read-only` 下,直接文件写入失败。将 `sandbox-unavailable` 与文件操作被拒绝区分处理,修复本地沙箱安装后再重试。
@@ -3,20 +3,20 @@
# After editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/experimental/ptc-runtime-python/README.md
/:
en: 21d67ee6d4caef1e
zh: 815c36a37b8a2c3e
en: d9caf4b17c0e6fe4
zh: 7233b09cfb890559
/deepseek-ai-dsh-experimental-ptc-runtime-python:
en: 98894607ad9de9bf
zh: 068899d3766c2628
/deepseek-ai-dsh-experimental-ptc-runtime-python/summary:
en: a7dc02100b3d90ba
zh: 5f80610b0bf84d84
en: bdcd4f38f97a3bab
zh: d93074f86ac2b9f5
/deepseek-ai-dsh-experimental-ptc-runtime-python/table-of-contents:
en: d152484eb41ac6b4
zh: 09388d293f9be9cb
/deepseek-ai-dsh-experimental-ptc-runtime-python/use-this-package:
en: d8db36ca3f32afeb
zh: fec311dea315aac4
en: 4695160db934a010
zh: 90dcd69e2aab43b3
/deepseek-ai-dsh-experimental-ptc-runtime-python/use-this-package/what-you-get:
en: ca7b9cc958069c7f
zh: 8a4ac72d02ad76eb
@@ -24,17 +24,17 @@
en: e690628dc6197c3b
zh: 2b9cdad8b41dcde5
/deepseek-ai-dsh-experimental-ptc-runtime-python/use-this-package/what-can-go-wrong:
en: d43927c607a9855f
zh: e1dd1643bebfd647
en: 9a0c3294b510cd22
zh: 5635886060044ae3
/deepseek-ai-dsh-experimental-ptc-runtime-python/understand-the-implementation:
en: 7824816505e2b844
zh: 3603d1c332c2ed5d
/deepseek-ai-dsh-experimental-ptc-runtime-python/understand-the-implementation/design-concept:
en: 9339b0800d70be48
zh: 71a9a3d3eea86050
en: 706fb5750d6e766f
zh: b8f054bffb4c1ff2
/deepseek-ai-dsh-experimental-ptc-runtime-python/understand-the-implementation/wire-contract:
en: 586d320cd7ef9974
zh: ccf4e4f9fb230eb8
en: 56cb353442d0aa01
zh: bcb13e5dc761af4a
/deepseek-ai-dsh-experimental-ptc-runtime-python/understand-the-implementation/lossless-json-crossing:
en: 6252e86fa10e9dd0
zh: 9b95b033ea0b5463
@@ -54,8 +54,8 @@
en: 40294c1c31b74824
zh: d805c6bd7270505e
/deepseek-ai-dsh-experimental-ptc-runtime-python/known-limitations-and-deferred-work:
en: 9177182ef230c99e
zh: 2a15994203ad325c
en: 5d62ed07fefbefc4
zh: 2a03d9bc9265a200
/deepseek-ai-dsh-experimental-ptc-runtime-python/known-limitations-and-deferred-work/dev-note:
en: e67f633dc6fe7773
zh: 3bb0c20c93f16f98
@@ -1,5 +1,5 @@
---
description: "CPython-subprocess PTC runtime: the dsh-ptc-runtime seam implementation for Python model code, with the fd-3 wire protocol it speaks."
description: "Run Python model code in fresh CPython processes under the shared filesystem sandbox, with configured resource budgets and async host bindings."
kind: "package-reference"
---
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
## Summary
This experimental package lets explicit compositions run model-generated Python in a fresh CPython 3.10+ subprocess for each request. Programs can use top-level `await` and `return`, call configured bindings, and write normal stdout/stderr while receiving explicit completion or failure results. Resource budgets and process-group teardown contain runaway work, but the subprocess is not a security boundary: direct Python operations have no filesystem sandbox, no state persists across runs, and no shipped profile enables this runtime.
Run model-generated Python in a fresh CPython 3.10+ process on macOS or Linux under the same file policy as TypeScript PTC. Programs can use top-level `await` and `return`, call configured bindings, and write normal stdout/stderr. Direct file operations follow the selected sandbox policy; resource budgets and process-group teardown bound execution. No state persists across runs, and no shipped profile enables this experimental runtime.
## Table of Contents
@@ -25,9 +25,19 @@ This experimental package lets explicit compositions run model-generated Python
<a id="use-this-package"></a>
## Use this package
Choose this published experimental package only in an explicit composition. Register `PythonPtcRuntime` beside `dsh-tools`; `run(resolve(request))` executes each program in a fresh CPython 3.10+ subprocess, resolving with `result.value` on success and `result.error` on failure (the orthogonal `PtcRunFailure.kind` taxonomy classifies parse failures, thrown exceptions, invalid completions, output overflows, budget expiry, aborts, and substrate death). It rejects only for seam misuse — a malformed binding namespace, or a call after disposal. Configuration is rejected at load: a non-Unix platform; an explicit `pythonBin` that is not an executable regular file or a bare name that does not resolve on `PATH`; a non-CPython, pre-3.10, or probe-failing interpreter; a non-positive or non-integer budget; a `maxLogBytes` below the truncation-marker floor (64); a timer value `setTimeout` would clamp; a budget larger than the effective fd-3 frame cap (lowered when the host heap cannot safely parse a near-cap frame); or an `addressSpaceMb`/output-budget pair whose worst-case peak would breach `RLIMIT_AS`.
Choose this published experimental package only in an explicit composition. Register `PythonPtcRuntime` beside `dsh-tools`; `run(resolve(request))` executes each program in a fresh CPython 3.10+ subprocess, resolving with `result.value` on success and `result.error` on failure (the orthogonal `PtcRunFailure.kind` taxonomy classifies parse failures, thrown exceptions, invalid completions, output overflows, budget expiry, aborts, unavailable confinement, and substrate death). It rejects only for caller misuse, such as malformed bindings, unresolved execution options, or a call after disposal. Configuration is rejected at load: a non-Unix platform; an explicit `pythonBin` that is not an executable regular file or a bare name that does not resolve on `PATH`; a non-CPython, pre-3.10, or probe-failing interpreter; a non-positive or non-integer budget; a `maxLogBytes` below the truncation-marker floor (64); a timer value `setTimeout` would clamp; a budget larger than the effective fd-3 frame cap (lowered when the host heap cannot safely parse a near-cap frame); or an `addressSpaceMb`/output-budget pair whose worst-case peak would breach `RLIMIT_AS`.
`resolve(request)` accepts an absolute `cwd` and uses the provider's configured `maxWallMs` deadline (600,000 ms by default). Explicit `timeoutMs` overrides and sandbox policies are unsupported and reject before execution. This provider does not advertise `sandboxMode` or return confinement facts.
The composition must supply `sandbox` and `sandboxPolicy` for this local execution host. `resolve(request)` accepts an explicit `sandboxPolicy` or resolves the shared deployment policy, and defaults `cwd` to that policy's workspace root. PTC mode supplies the calling Session's policy and directory. The configured `maxWallMs` remains the execution deadline; explicit `timeoutMs` overrides are unsupported.
`read-only` and `workspace-write` execute through the configured sandbox provider; `danger-full-access` explicitly bypasses confinement. `result.sandbox` reports the mode, observed denial, and the backend's full or partial enforcement separately from the program outcome. The [sandbox service](../../sandbox/sandbox/README.md) defines the file restrictions and backend limits; these modes do not restrict network access or arbitrary file reads.
The runtime advertises file confinement so `run_code` exposes `sandbox_permissions` and `justification`. Approval widens access for that complete program once; nested tools retain their own policies and approvals. Programs are never replayed automatically after a denial. See [PTC mode](../../core/tools/README.md#ptc-mode) for the consumer's escalation instructions.
The runtime supplies these execution instructions:
```text
Each call runs in a fresh Python process. Relative paths use the supplied working directory; only TMPDIR is set in the environment. Direct filesystem access follows this execution's sandbox policy.
```
### What you get
@@ -39,6 +49,8 @@ Frames travel on the child's fd 3 as JSON-lines — one object per line — so s
### What can go wrong
Required confinement that cannot be established returns `sandbox-unavailable`; the runtime never retries unconfined. An operation denied by a working sandbox remains a program failure with `sandbox.denied` set when its diagnostic matches the selected backend. A caught denial need not appear in this diagnostic flag.
Host-side validation drops junk without throwing, so a malformed or forged frame never crashes the host process: `validateChildFrame` returns `undefined` for anything that does not rebuild cleanly, a non-number call id can never be echoed into a reply, and forged extra fields never ride along. A completion value that is not lossless JSON, or that exceeds the configured byte budget, is rejected explicitly (`non-lossless` / `over-budget`) rather than silently rounded or truncated. An fd-3 frame whose raw length exceeds the effective frame parse cap (64 MiB, or lower when the host's configured heap cannot safely parse a near-cap frame — see `hostFrameParseCeiling`) settles the run as a `worker-exit` (the receive path caps raw frames before `toString`/`JSON.parse` so a compact wide frame cannot decode to far more host memory than its wire bytes admitted).
-----
@@ -55,9 +67,11 @@ This section explains the design behind the backend; observable behavior is full
One direction of trust: the host treats every inbound frame as hostile (model code can forge anything on fd 3) and REBUILDS it field by field before reading; the Python side trusts host replies. The bootstrap (`py/bootstrap.py`) runs the program as the body of an async function, so top-level `await` and `return` work; binding calls travel over fd 3 as JSON-lines and replies are paced across the pump so a flood of large replies cannot pin the host's fd-3 write buffer.
The shipped bootstrap and protocol sources reach the interpreter as UTF-8 JSON on trusted binary stdin, independently of sandbox temporary-directory mounts and locale text encoding. Model programs and binding traffic use fd 3. The host resolves the sandbox runner before spawning with only `TMPDIR` in the child environment. The wall deadline includes sandbox setup. The configured interpreter's load-time version probe runs outside confinement and executes no model code.
### Wire contract
The frames are `boot` / `run` (host → child) and `boot-ack` / `call` / `log` / `done` plus one `reply` per call (child → host). The `log` frame's `truncated` flag marks the frame that IS the child ledger's truncation marker, so the host stops capturing at the same point the child did instead of inferring it from its own budget. The `log` frame's `open` flag marks an unterminated line committed by an explicit flush: the host merges the next log frame into the same entry, so `print('a', end='', flush=True); print('b')` reads back as one `'ab'` entry rather than a fake newline (the split-billing arithmetic lives in the fd-3 protocol Agent Note's wire-contract section). The one exception to merging is truncation: the already-billed prefix is committed as its own entry and the truncation marker follows it (marker last, no re-charge). `done.error.kind` is one of `exception`, `invalid-output`, `output-limit`; wall/CPU budgets, aborts, and substrate death are observed host-side, not carried as frames.
The frames are `boot` / `run` (host → child) and `boot-ack` / `call` / `log` / `done` plus one `reply` per call (child → host). The `log` frame's `truncated` flag marks the frame that IS the child ledger's truncation marker, so the host stops capturing at the same point the child did instead of inferring it from its own budget. The `log` frame's `open` flag marks an unterminated line committed by an explicit flush: the host merges the next log frame into the same entry, so `print('a', end='', flush=True); print('b')` reads back as one `'ab'` entry rather than a fake newline (the split-billing arithmetic lives in the fd-3 protocol Agent Note's wire-contract section). The one exception to merging is truncation: the already-billed prefix is committed as its own entry and the truncation marker follows it (marker last, no re-charge). `done.error.kind` is one of `exception`, `invalid-output`, `output-limit`, or `timeout` from the CPU check after model code returns; wall deadlines, aborts, and substrate death are observed host-side.
### Lossless JSON crossing
@@ -119,13 +133,16 @@ These limits define what the package does and does not cover; they are current p
- **Workflow execution requires Node** — compositions using this Python provider disable `workflow-ptc`, `tool-workflow`, and `tool-ralph`; the workflow provider rejects an incompatible runtime when loaded.
- **Cross-channel log interleaving is backend-dependent** — Python stdout, stderr, and fd-3 log frames travel independently; each channel preserves its own order, while their total order in `result.logs` may differ.
- **CPython 3.10 or newer is required** — the configured executable is resolved and version-probed at load; unsupported interpreters fail before `ctx.ptcRuntime` is registered.
- **Diagnostic and temporary-directory prefixes omit the package's experimental qualifier** — the marker `[dsh-ptc-runtime-python] log capture truncated at <N> bytes` and the `dsh-ptc-runtime-python-` directory prefix identify this provider independently of its npm package name. The protocol mirror verifies identical marker bytes in TypeScript and Python.
- **Execution is local and Unix-only** — the interpreter, working directory, and sandbox runner must belong to the host running this plugin. The provider uses POSIX resource limits and process-group signals; it does not support Windows or remote execution providers.
- **Sandbox enforcement inherits backend limits** — a successful program can report partial enforcement, and file confinement does not establish multi-tenant isolation or complete descendant cleanup.
- **Diagnostic prefixes omit the package's experimental qualifier** — the marker `[dsh-ptc-runtime-python] log capture truncated at <N> bytes` identifies this provider independently of its npm package name. The protocol mirror verifies identical marker bytes in TypeScript and Python.
- **`run()` is one-shot** — `logs` become available only after `PtcRunResult` resolves; there is no streaming-log or progress interface for output produced by a running program.
- **No state persists across runs** — every request executes in a fresh subprocess; a persistent REPL-style kernel stays deferred until a backend brings its own logging scheme.
- **An fd-3 frame whose raw length exceeds the effective frame parse cap settles the run as a worker-exit** — the cap is 64 MiB, or lower when the host's configured heap cannot safely parse a near-cap frame (`hostFrameParseCeiling`); `maxLogBytes`/`maxValueBytes` are load-bounded to the same cap so an honest child's frames always fit; a model-constructed binding ARGUMENT above the cap (a value with no seam-level budget) trips it too — an accepted residual of the OOM guard.
- **A child that stops reading its replies settles the run as a worker-exit once the reply backlog passes 1024 frames** — the host writes replies one at a time, waiting for `drain` when the pipe is full; a child that keeps sending calls without consuming replies would otherwise grow the retained backlog (and the binding results it pins) until the wall clock, so the backlog cap fails the run early. Binding results carry no seam-level byte cap, so this is a count bound, not a byte bound.
- **A child that floods calls against a binding that never settles settles the run as a worker-exit once 1024 calls are in flight** — binding calls are counted before dispatch and released when the async body settles, so a binding whose promise never resolves would otherwise accumulate one async closure per call frame until the wall clock. Like the reply backlog, this is a count bound, not a byte bound.
- **A combined log-and-value peak is not modelled by the load gate** — a model daemon thread that keeps writing while the completion value is metered and framed can add the two peaks in a way no gate admits or rejects; the run dies as `worker-exit`, containment holds, and only the failure classification is degraded.
- **CPU signal classification depends on the launcher** — the soft limit retains default `SIGXCPU` termination, including during native calls. A launcher such as bwrap can convert that signal into an ambiguous exit code, reported as `worker-exit`; a directly observed `SIGXCPU` is `timeout`. Only the CPU check after model code returns attempts a `timeout` frame before termination, and a busy or backpressured control channel can prevent that report. Kernel limits and the wall deadline remain in force.
- **A 1-second dual-limit `ulimit -t 1` CPU overrun is reported as `worker-exit`, not a timeout** — when the host starts under a hard CPU limit equal to the soft and that limit is 1, `_clamped` cannot lower the soft, so the kernel SIGKILLs the busy loop and SIGXCPU is never delivered; containment holds, only the classification is degraded.
- **No byte cap on intermediate binding values** — the implementation remains bounded by the lossless-JSON serialization cost and process memory, and a provider or executor may apply its own fetch cap.
@@ -1,5 +1,5 @@
---
description: "CPython 子进程 PTC 运行时:为 Python 模型代码实现 dsh-ptc-runtime seam,及其使用的 fd-3 wire 协议。"
description: "在共享文件系统沙箱下以全新 CPython 进程运行 Python 模型代码,提供可配置的资源预算与异步宿主绑定。"
kind: "package-reference"
---
@@ -9,7 +9,7 @@ kind: "package-reference"
## 概述
这个实验包可让显式组合在每次请求时都用全新的 CPython 3.10+ 子进程运行模型生成的 Python。程序可以使用顶层 `await` 和 `return`、调用已配置的 binding、正常写入 stdout/stderr,并获得明确的完成或失败结果。资源预算和进程组拆卸会约束失控的工作,但子进程不是安全边界:直接 Python 操作没有文件系统沙箱,运行之间不保留状态,且没有已发布 profile 启用此 runtime。
在 macOS 或 Linux 上,以全新的 CPython 3.10+ 进程运行模型生成的 Python,并遵循与 TypeScript PTC 相同的文件策略。程序可以使用顶层 `await` 和 `return`、调用已配置的 binding,并正常写入 stdout/stderr。直接文件操作遵循所选沙箱策略;资源预算和进程组拆卸约束执行。运行之间不保留状态,且没有已发布 profile 启用这个实验性 runtime。
## 目录
@@ -25,9 +25,19 @@ kind: "package-reference"
<a id="use-this-package"></a>
## 使用本包
仅在显式组合中选择这个已发布的实验包。将 `PythonPtcRuntime` 与 `dsh-tools` 一起注册后,`run(resolve(request))` 会在全新的 CPython 3.10+ 子进程中执行每个程序;成功时以 `result.value` resolve,失败时以 `result.error` resolve(正交的 `PtcRunFailure.kind` 分类涵盖解析失败、抛出异常、无效完成值、输出溢出、预算到期、中止与执行基底终止)。仅有 seam 误用会 reject——binding 命名空间不合法,或在 dispose 后调用。配置在加载期拒绝:非 Unix 平台;不是可执行普通文件的显式 `pythonBin`,或无法在 `PATH` 上解析的裸名;非 CPython、低于 3.10 或探测失败的解释器;非正或非整数预算;低于截断标记下限(64)的 `maxLogBytes`;会被 `setTimeout` 截断的定时器值;超过有效 fd-3 帧上限的预算(宿主堆无法安全解析接近上限的帧时,该上限会降低);或最坏峰值会突破 `RLIMIT_AS` 的 `addressSpaceMb`/输出预算组合。
仅在显式组合中选择这个已发布的实验包。将 `PythonPtcRuntime` 与 `dsh-tools` 一起注册后,`run(resolve(request))` 会在全新的 CPython 3.10+ 子进程中执行每个程序;成功时以 `result.value` resolve,失败时以 `result.error` resolve(正交的 `PtcRunFailure.kind` 分类涵盖解析失败、抛出异常、无效完成值、输出溢出、预算到期、中止、约束不可用与执行基底终止)。仅有调用方误用会 reject,例如 binding 不合法、执行选项未解析,或在 dispose 后调用。配置在加载期拒绝:非 Unix 平台;不是可执行普通文件的显式 `pythonBin`,或无法在 `PATH` 上解析的裸名;非 CPython、低于 3.10 或探测失败的解释器;非正或非整数预算;低于截断标记下限(64)的 `maxLogBytes`;会被 `setTimeout` 截断的定时器值;超过有效 fd-3 帧上限的预算(宿主堆无法安全解析接近上限的帧时,该上限会降低);或最坏峰值会突破 `RLIMIT_AS` 的 `addressSpaceMb`/输出预算组合。
`resolve(request)` 接受绝对 `cwd`,并使用提供方配置的 `maxWallMs` 截止时间(默认 600,000 ms)。显式 `timeoutMs` 覆盖与沙箱策略不受支持,会在执行前拒绝。本提供方不声明 `sandboxMode`,也不返回约束事实。
组合必须为此本地执行宿主提供 `sandbox` 和 `sandboxPolicy`。`resolve(request)` 接受显式 `sandboxPolicy`,或解析共享部署策略,并将 `cwd` 默认设为该策略的工作区根目录。PTC mode 提供调用 Session 的策略和目录。配置的 `maxWallMs` 仍是执行截止时间;不支持显式 `timeoutMs` 覆盖。
`read-only` 和 `workspace-write` 通过配置的沙箱提供方执行;`danger-full-access` 显式绕过约束。`result.sandbox` 独立于程序结果报告模式、观察到的拒绝,以及后端的完整或部分强制能力。[沙箱服务](../../sandbox/sandbox/README.zh.md)定义文件限制与后端局限;这些模式不限制网络访问或任意文件读取。
运行时声明文件约束,因此 `run_code` 暴露 `sandbox_permissions` 和 `justification`。审批只为完整程序的一次执行扩大访问权限;嵌套工具保留各自的策略与审批。程序在拒绝后绝不自动重放。消费方的升级权限指引见 [PTC mode](../../core/tools/README.zh.md#ptc-mode)。
运行时提供以下执行指引:
```text
Each call runs in a fresh Python process. Relative paths use the supplied working directory; only TMPDIR is set in the environment. Direct filesystem access follows this execution's sandbox policy.
```
### 你得到什么
@@ -39,6 +49,8 @@ kind: "package-reference"
### 可能出错的地方
无法建立所需约束时返回 `sandbox-unavailable`;运行时绝不在无约束状态下重试。工作正常的沙箱拒绝某个操作时,它仍属于程序失败;当诊断与所选后端匹配时,设置 `sandbox.denied`。被程序捕获的拒绝不一定体现在这个诊断标志中。
宿主侧校验在不抛异常的情况下丢弃垃圾,因此畸形或伪造帧永远不会让宿主进程崩溃:`validateChildFrame` 对任何不能干净重建的内容返回 `undefined`,非数字的 call id 永远不会被回显进 reply,伪造的额外字段永远不会被带走。非无损 JSON 或超过配置字节预算的完成值会被显式拒绝(`non-lossless`/`over-budget`),而不是被静默取整或截断。原始长度超过有效帧解析上限(64 MiB,或当宿主的配置堆无法安全解析接近上限的帧时更低——见 `hostFrameParseCeiling`)的 fd-3 帧会让本次运行以 `worker-exit` 结算(接收路径在 `toString`/`JSON.parse` 之前限制原始帧,紧凑宽帧不能解码出远超其线上字节的宿主内存)。
-----
@@ -55,9 +67,11 @@ kind: "package-reference"
单向信任:宿主把每条入站帧都视为敌意(模型代码可以在 fd 3 上伪造任何内容)并逐字段重建后才读取;Python 侧信任宿主回复。bootstrap(`py/bootstrap.py`)把程序作为 async 函数体执行,因此顶层 `await` 与 `return` 都可用;binding 调用经 fd 3 以 JSON-lines 往返,回复在 pump 中限速,以免大量大回复钉住宿主的 fd-3 可写缓冲。
已发布的 bootstrap 与 protocol 源码以 UTF-8 JSON 通过可信二进制 stdin 传入解释器,不依赖沙箱中的临时目录挂载或 locale 文本编码。模型程序与 binding 通信使用 fd 3。宿主在启动前解析沙箱 runner,子进程环境中只保留 `TMPDIR`。经过时间截止包含沙箱准备。所配置解释器的加载期版本探测在约束之外运行,不执行模型代码。
### wire 契约
帧为 `boot`/`run`(宿主 → 子进程)与 `boot-ack`/`call`/`log`/`done` (子进程 → 宿主),以及每个 `call` 对应一个 `reply`(宿主 → 子进程)。`log` 帧的 `truncated` 标志标记的就是子进程账本自己的截断标记帧,因此宿主在与子进程相同的点停止捕获,而不是从自己的预算推断。`log` 帧的 `open` 标志标记由显式 flush 提交的未结束行:宿主把下一个 log 帧合并进同一条目,因此 `print('a', end='', flush=True); print('b')` 读回为一条 `'ab'` 条目而不是假换行(拆分计费算术在 fd-3 协议 Agent Note 的 wire-contract 段)。合并的唯一例外是截断:当后续超预算帧触发账本时,已计费的前缀作为独立条目先提交,截断 marker 跟在后面(marker 保持末位,无重复计费)。`done.error.kind` 为 `exception`、`invalid-output`、`output-limit` 之一;墙钟/CPU 预算、中止与基底死亡在宿主侧观察,不以帧形式携带。
帧为 `boot`/`run`(宿主 → 子进程)与 `boot-ack`/`call`/`log`/`done` (子进程 → 宿主),以及每个 `call` 对应一个 `reply`(宿主 → 子进程)。`log` 帧的 `truncated` 标志标记的就是子进程账本自己的截断标记帧,因此宿主在与子进程相同的点停止捕获,而不是从自己的预算推断。`log` 帧的 `open` 标志标记由显式 flush 提交的未结束行:宿主把下一个 log 帧合并进同一条目,因此 `print('a', end='', flush=True); print('b')` 读回为一条 `'ab'` 条目而不是假换行(拆分计费算术在 fd-3 协议 Agent Note 的 wire-contract 段)。合并的唯一例外是截断:当后续超预算帧触发账本时,已计费的前缀作为独立条目先提交,截断 marker 跟在后面(marker 保持末位,无重复计费)。`done.error.kind` 为 `exception`、`invalid-output`、`output-limit` 或模型代码返回后 CPU 检查产生的 `timeout` 之一;墙钟截止、中止与基底死亡在宿主侧观察。
### 无损 JSON 跨越
@@ -119,13 +133,16 @@ kind: "package-reference"
- **工作流执行需要 Node**——使用本 Python 提供方的组合禁用 `workflow-ptc`、`tool-workflow` 和 `tool-ralph`;工作流提供方在加载时拒绝不兼容的运行时。
- **跨通道日志交错由后端决定**——Python stdout、stderr 与 fd-3 日志帧彼此独立传输;每个通道保留自身顺序,但它们在 `result.logs` 中的总顺序可能不同。
- **需要 CPython 3.10 或更高版本**——配置的可执行文件会在加载期完成解析与版本探测;不受支持的解释器会在 `ctx.ptcRuntime` 注册前失败。
- **诊断与临时目录前缀省略包名中的 experimental 限定词**——标记 `[dsh-ptc-runtime-python] log capture truncated at <N> bytes` 与 `dsh-ptc-runtime-python-` 目录前缀独立于 npm 包名来标识本提供方。协议镜像检查 TypeScript 与 Python 的标记字节完全相同。
- **执行限于本地 Unix 宿主**——解释器、工作目录与沙箱 runner 必须位于运行本插件的宿主上。提供方使用 POSIX 资源限制和进程组信号;不支持 Windows 或远程执行提供方。
- **沙箱强制能力继承后端限制**——成功的程序也可能报告部分强制能力,文件约束不构成多租户隔离或完整的后代清理保证。
- **诊断前缀省略包名中的 experimental 限定词**——标记 `[dsh-ptc-runtime-python] log capture truncated at <N> bytes` 独立于 npm 包名来标识本提供方。协议镜像检查 TypeScript 与 Python 的标记字节完全相同。
- **`run()` 是一次性的**——`logs` 只有在 `PtcRunResult` resolve 后才能获得;没有为运行中程序产生的输出提供流式日志或进度接口。
- **运行之间不保留状态**——每次请求都在全新子进程中执行;持久 REPL 风格内核在某个后端带来自己的日志方案之前保持延期。
- **原始长度超过有效帧解析上限的 fd-3 帧会让本次运行以 worker-exit 结算**——上限为 64 MiB,或当宿主的配置堆无法安全解析接近上限的帧时更低(`hostFrameParseCeiling`);`maxLogBytes`/`maxValueBytes` 在加载期被限制到同一上限,因此诚实子进程的帧总能放得下;模型构造的超过该上限的 binding 实参(一个在 seam 层没有预算的值)会触发同一上限——这是该 OOM 防护的已接受残余。
- **停止读取回复的子进程会在回复积压超过 1024 帧时以 worker-exit 结算运行**——宿主每次写一条回复,管道满时等待 `drain`;只持续发送调用而不消费回复的子进程会让保留的积压(及其钉住的 binding 结果)一直增长到墙钟,因此积压上限让运行提前失败。binding 结果在 seam 层没有字节上限,所以这是计数上限而非字节上限。
- **向永不结算的 binding 洪泛调用的子进程会在 1024 个调用在途时以 worker-exit 结算运行**——binding 调用在分发前计数、异步体结算时释放,否则 promise 永不 resolve 的 binding 会让每个调用帧累积一个异步闭包直到墙钟。与回复积压一样,这是计数上限而非字节上限。
- **组合日志与值的峰值不被加载门建模**——持续写入的模型 daemon 线程与完成值计量、分帧相加的峰值没有任何门会放行或拒绝;运行以 `worker-exit` 告终,隔离成立,只有失败分类降级。
- **CPU 信号的分类取决于 launcher**——软限制保留默认的 `SIGXCPU` 终止行为,包括执行原生调用期间。bwrap 等 launcher 可能将该信号转换为有歧义的退出码,此时报告 `worker-exit`;直接观察到的 `SIGXCPU` 则为 `timeout`。仅模型代码返回后的 CPU 检查会在终止前尝试发送 `timeout` 帧,繁忙或反压中的控制通道可能阻止该报告。内核限制与墙钟截止仍然生效。
- **1 秒双限 `ulimit -t 1` CPU 超限被报告为 `worker-exit` 而非 timeout**——当宿主在一个与软限相等的硬 CPU 限下启动且该限为 1 时,`_clamped` 无法下调软限,内核在同一 tick SIGKILL 忙循环,SIGXCPU 永远不会送达;隔离成立,只有分类降级。
- **中间 binding 值没有字节上限**——实现仍受无损 JSON 序列化成本与进程内存约束,提供方或执行器可能应用自己的获取上限。
@@ -27,13 +27,20 @@
"@deepseek-ai/dsh-ptc-runtime": "workspace:*",
"@deepseek-ai/dsh-timeout": "workspace:*",
"@deepseek-ai/cordis": "workspace:~",
"@deepseek-ai/dsh-util-values": "workspace:*"
"@deepseek-ai/dsh-util-values": "workspace:*",
"@deepseek-ai/dsh-sandbox": "workspace:*",
"@deepseek-ai/dsh-sandbox-policy": "workspace:*"
},
"devDependencies": {
"@deepseek-ai/dsh-ptc-runtime": "workspace:*",
"@deepseek-ai/dsh-timeout": "workspace:*",
"@deepseek-ai/cordis": "workspace:~",
"@deepseek-ai/dsh-util-values": "workspace:*"
"@deepseek-ai/dsh-util-values": "workspace:*",
"@deepseek-ai/dsh-sandbox": "workspace:*",
"@deepseek-ai/dsh-sandbox-policy": "workspace:*",
"@deepseek-ai/dsh-sandbox-local": "workspace:*",
"@deepseek-ai/dsh-session-projection": "workspace:*",
"@deepseek-ai/dsh-session": "workspace:*"
},
"dependencies": {
"@deepseek-ai/schemastery": "workspace:~"
@@ -7,8 +7,8 @@ the completion), and posts a terminal :class:`DoneMessage`. The program calls
host functions through the ``tools`` (or other namespace) proxy, whose attribute
and subscript access return awaitables that ride binding messages over fd 3.
This module runs under ``python3 -I`` with only ``TMPDIR`` in its environment
and ``sys.path`` containing only its own directory.
This module runs under ``python3 -I`` with only ``TMPDIR`` in its environment.
The trusted stdin loader supplies this module and its ``protocol`` dependency.
"""
from __future__ import annotations
@@ -34,14 +34,8 @@ from decimal import Context, Decimal
# prec=28 (more than the 17 significant digits a double needs) makes the
# normalize() spelling decision context-independent.
_FLOAT_CONTEXT = Context(prec=28)
from pathlib import Path
from typing import Any
# ``python3 -I`` (isolated) drops the script directory from ``sys.path`` so
# the sibling ``protocol.py`` is invisible by default. Restore it explicitly
# before importing.
sys.path.insert(0, str(Path(__file__).resolve().parent))
from protocol import PROTOCOL_FD, log_truncation_marker # noqa: E402
# Read size for the async fd-3 reader. One `os.read` returns whatever the pipe
@@ -1020,6 +1014,8 @@ async def _run(channel: ProtocolChannel) -> None:
if boot is None or boot.get("type") != "boot":
raise RuntimeError("bootstrap: expected boot frame on fd 3")
report_cpu_timeout = _make_cpu_timeout_reporter(channel, boot["cpuSeconds"])
# A limit that cannot be applied must fail the run as a diagnosable done
# frame, not a bare traceback + exit(1): running the program UNCAPPED would
# silently void the containment contract, and the host can only relay what
@@ -1030,8 +1026,7 @@ async def _run(channel: ProtocolChannel) -> None:
# timeout would otherwise write a large memory-bearing core file into
# the workspace. Forbid core dumps first so the timeout path leaves none.
resource.setrlimit(resource.RLIMIT_CORE, (0, 0))
# Soft limit at cpuSeconds fires SIGXCPU (its default disposition
# terminates the child; the host classifies that close as a timeout).
# SIG_DFL terminates at the soft limit even inside a long native C call.
# Hard limit at +1s is a SIGKILL backstop for a program that traps
# SIGXCPU and keeps burning CPU.
cpu_soft, cpu_hard = _clamped(
@@ -1388,7 +1383,7 @@ async def _run(channel: ProtocolChannel) -> None:
code = compile(wrapped, "<model>", "exec", dont_inherit=True)
exec(code, ns) # noqa: S102 -- defines __dsh_main__; executing model code is the point
value = await ns["__dsh_main__"]()
die_if_cpu_exhausted(cpu_seconds)
die_if_cpu_exhausted(cpu_seconds, report_cpu_timeout)
# Flush the log buffers BEFORE metering and framing the completion value.
# `_done_with_value` materializes the value's escaped JSON form to meter
# it and then pre-encodes the admitted value into its frame (see its
@@ -2130,6 +2125,42 @@ def _lossless_json_violation(value: Any) -> str | None:
return None
def _make_cpu_timeout_reporter(channel: ProtocolChannel, cpu_seconds: int) -> Any:
"""Report the post-return CPU check before mandatory SIGXCPU termination.
Reporting never waits for a busy writer or a backpressured channel. The
caller immediately terminates the process; fd 3 remains nonblocking.
"""
acquire, release = channel._write_lock.acquire, channel._write_lock.release
write, set_blocking, view_of, fd = os.write, os.set_blocking, memoryview, channel._fd
caught = BaseException
message = (
"CPU time exhausted (limit at most the configured %ss; "
"a stricter inherited RLIMIT_CPU can fire sooner)" % cpu_seconds
)
payload = (
_encode_json_plain({"type": "done", "error": {"kind": "timeout", "message": message}})
+ "\n"
).encode("utf-8")
def report() -> None:
if not acquire(False):
return
try:
set_blocking(fd, False)
remaining = view_of(payload)
while remaining:
remaining = remaining[write(fd, remaining):]
except caught as _error:
# Closed or backpressured transport cannot carry the report; termination still runs.
pass
finally:
release()
return report
def _make_cpu_enforcer() -> Any:
"""Build the CPU post-check over closure-held primitives.
@@ -2160,7 +2191,7 @@ def _make_cpu_enforcer() -> Any:
charged to this process — from a reported SUCCESS into the same `timeout`
an untrapped program gets.
@returns The one-argument enforcement callable, taking `cpuSeconds`.
@returns The enforcement callable, taking the CPU ceiling and timeout reporter.
"""
getrusage = resource.getrusage
@@ -2180,7 +2211,7 @@ def _make_cpu_enforcer() -> Any:
pthread_sigmask = getattr(signal, "pthread_sigmask", None)
sig_unblock = getattr(signal, "SIG_UNBLOCK", None)
def die_if_cpu_exhausted(cpu_seconds: int) -> None:
def die_if_cpu_exhausted(cpu_seconds: int, report_timeout: Any) -> None:
"""Die by re-delivered SIGXCPU when the CPU budget is already spent.
Two cases reach here as a would-be SUCCESS. A model program can trap
@@ -2195,11 +2226,10 @@ def _make_cpu_enforcer() -> Any:
own aggregate, which accumulates the CPU of every REAPED descendant
(grandchildren included, verified).
``getrusage`` is the kernel's own meter (unforgeable from model code),
and dying by SIGXCPU with the default disposition restored gives the
host the same kernel-authoritative close signal as the untrapped soft
limit — classified as `timeout`, after which the host's process-group
SIGTERM/SIGKILL teardown reaches any surviving descendants. Runs AFTER
``getrusage`` supplies the kernel CPU meter. An exhausted budget is
reported before SIGXCPU terminates the process, so launchers that map
signals to exit codes retain the timeout diagnostic. Host process-group
teardown reaches surviving descendants. Runs AFTER
the model program settled, so a program can re-trap SIGXCPU between
this SIG_DFL and the kill only by running more code, which it no longer
does. A program that tampers with this callable instead (see
@@ -2224,12 +2254,14 @@ def _make_cpu_enforcer() -> Any:
0.0).
@param cpu_seconds The `cpuSeconds` budget the soft RLIMIT_CPU used.
@param report_timeout The captured writer for the CPU timeout diagnostic.
"""
own = getrusage(rusage_self)
kids = getrusage(rusage_children)
spent = own.ru_utime + own.ru_stime + kids.ru_utime + kids.ru_stime
if spent >= cpu_seconds:
report_timeout()
# A program can mask SIGXCPU (``pthread_sigmask(SIG_BLOCK, ...)``),
# burn past the soft limit, and return during the soft-to-hard gap;
# the re-delivered SIGXCPU below would then stay PENDING and the
@@ -90,9 +90,9 @@ class LogMessage(_LogMessageRequired, total=False):
class DoneErrorField(TypedDict):
"""Child → host: the failure carried on a ``done`` frame. ``kind`` is one of
the three the host validates; ``message`` is the traceback or diagnostic."""
the host-validated failure classes; ``message`` is the traceback or diagnostic."""
kind: Literal["exception", "invalid-output", "output-limit"]
kind: Literal["exception", "invalid-output", "output-limit", "timeout"]
message: str
@@ -1,9 +1,9 @@
/**
* CPython subprocess PTC runtime: a fresh `python3` process runs each model program under an
* asyncio event loop with top-level ``await``. Binding calls travel on fd 3 as JSON-lines,
* leaving stdout/stderr free for the program's own output. This is containment, not a security
* boundary: model code has bash-equivalent trust, contained by a tempdir-only environment,
* RLIMIT_CPU + RLIMIT_AS, wall-clock timeout, and SIGTERM→grace→SIGKILL on the process group.
* leaving stdout/stderr free for the program's own output. Direct file effects follow the
* shared sandbox policy; CPU, address-space, output, and wall-clock budgets bound each run.
* Process-group teardown sends SIGTERM followed by SIGKILL after the configured grace.
*
* The package also owns the versionless fd-3 wire protocol itself; its host-side codec and
* hostile-frame validators are re-exported so every consumer of the wire shares one vocabulary.
@@ -11,18 +11,21 @@
*/
import { execFileSync, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
import { accessSync, copyFileSync, constants as fsConstants, mkdtempSync, readFileSync, rmSync, statSync } from 'node:fs'
import { accessSync, constants as fsConstants, readFileSync, statSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path'
import { fileURLToPath } from 'node:url'
import { delimiter, isAbsolute, join, resolve } from 'node:path'
import { getHeapStatistics } from 'node:v8'
import type { Duplex } from 'node:stream'
import { Context } from '@deepseek-ai/cordis'
import z from '@deepseek-ai/schemastery'
import { PtcRuntime, DUNDER_MEMBER, PORTABLE_RESERVED_WORDS, RESERVED_BINDING_GLOBALS, RESERVED_ERROR_MEMBERS } from '@deepseek-ai/dsh-ptc-runtime'
import type { PtcBindingErrorClass, PtcBindingFunction, PtcJsonValue, PtcRunFailure, PtcRunRequest, PtcRunResult, PtcRunSpec } from '@deepseek-ai/dsh-ptc-runtime'
import type { PtcBindingErrorClass, PtcBindingFunction, PtcJsonValue, PtcRunFailure, PtcRunRequest, PtcRunResult, PtcRunSandbox, PtcRunSpec } from '@deepseek-ai/dsh-ptc-runtime'
import { snapshotJsonValue } from '@deepseek-ai/dsh-util-values'
import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
import { SandboxUnavailableError, classifyRunnerFailure, isRunnerSpawnFailure } from '@deepseek-ai/dsh-sandbox'
import type { ConfinedArgv, SandboxMode } from '@deepseek-ai/dsh-sandbox'
import type {} from '@deepseek-ai/dsh-sandbox-policy'
import { bootstrapInput, PYTHON_BOOTSTRAP_LOADER } from './launch.ts'
import type { BootMessage, ChildToHost, ReplyMessage } from './protocol.ts'
import { checkDoneValue, encodeJsonPlain, hasUnsafeIntegerToken, logTruncationMarker, validateChildFrame } from './protocol.ts'
@@ -134,68 +137,6 @@ const EXCEPTION_RESERVED_MEMBERS = RESERVED_ERROR_MEMBERS
const DUNDER = DUNDER_MEMBER
/**
* The `py/` scripts the interpreter must be able to open: the entry script plus
* every module it imports from its own directory. Kept beside the built JS so a
* consumer package with `files: ['lib', 'py']` ships both.
*/
const PY_SCRIPTS = ['bootstrap.py', 'protocol.py']
/**
* Copy the `py/` scripts to a real filesystem directory and return the entry
* script's path there.
*
* The interpreter is an EXTERNAL process, so it can only open paths the OS
* resolves. Inside the single-file Python-SDK executable, `import.meta.url`
* resolves into pkg's virtual filesystem, which Node reads through its patched
* `fs` but `python3` cannot see at all — the spawn fails with ENOENT on a path
* that exists as far as the host is concerned. `bootstrap.py` additionally
* inserts its own directory on `sys.path` to import the sibling `protocol.py`,
* so both files must land in the SAME real directory.
*
* The copy is unconditional rather than gated on a bundled-runtime probe: the
* read goes through Node's `fs` either way, and one code path means the
* packaged deployment runs what the tests exercise. Placement is under
* `os.tmpdir()` with `0o700` keeps the scripts off other users' reach, but NOT
* the model's: the child runs as the same UID as the host, so a program can
* rewrite the very files it was started from. Hence one copy per RUN, discarded
* at settlement — a rewrite then damages only the run that performed it, which
* is what fresh-subprocess-per-run already promises. Sharing one copy across
* runs made an overwritten `bootstrap.py` break the next run.
*
* Deliberately SYNCHRONOUS. An `await` here would open an async boundary in
* `execute` before the run is registered in `live` and before the abort
* listener is installed, so a disposal or an abort landing in that window would
* be missed: `teardown` would see no runs and return while the continuation
* went on to spawn a subprocess, and an `addEventListener('abort')` installed
* afterwards does not replay an event that already fired. Three small
* filesystem operations per run are not worth that class of race, and `execute`
* already runs synchronously up to `spawn`.
*
* A failed copy removes the directory here, so a partial attempt never outlives
* the call that made it; a successful one is the caller's to remove, which it
* derives from the returned path.
*
* @returns the absolute path of the materialized entry script.
*/
function materializePyScripts(): string {
const dir = mkdtempSync(join(tmpdir(), 'dsh-ptc-runtime-python-'))
const source = fileURLToPath(new URL('../py/', import.meta.url))
try {
for (const name of PY_SCRIPTS) copyFileSync(join(source, name), join(dir, name))
} catch (error: unknown) {
try {
rmSync(dir, { recursive: true, force: true })
} catch {
// Swallows only a failure to remove the partial staging directory. The
// caller reports the copy failure that got us here, which is the
// diagnosable one; nothing else can act on a temp dir we cannot unlink.
}
throw error
}
return join(dir, 'bootstrap.py')
}
/**
* A frame's RAW length is capped before JSON.parse: the 64 MiB fd-3 frame
* parse cap bounds the bytes, not the decoded structure, and a compact wide
@@ -791,17 +732,17 @@ interface ValidatedNamespace {
* fail every live run as `abort` and AWAIT each child's exit.
*/
interface LiveRun {
kill(sig: NodeJS.Signals): void
settle(failure: PtcRunFailure): void
controller: AbortController
finished: Promise<void>
}
/**
* The experimental {@link PtcRuntime} backend (private, not released) registering as `ptcRuntime`. Every
* The experimental {@link PtcRuntime} backend registering as `ptcRuntime`. Every
* cap is validated config; every long-running operation honors the request's
* `AbortSignal`; every disposer awaits child-process exit.
*/
export class PythonPtcRuntime extends PtcRuntime {
static inject = ['sandbox', 'sandboxPolicy']
static Config: z<Config> = z.object({
cpuSeconds: z.number().default(60),
maxWallMs: z.number().default(600_000),
@@ -815,6 +756,12 @@ export class PythonPtcRuntime extends PtcRuntime {
readonly language = 'python'
readonly isolation = 'process'
override get sandboxMode(): SandboxMode { return this.ctx.sandboxPolicy.defaultMode }
override get executionInstructions(): string {
return 'Each call runs in a fresh Python process. Relative paths use the supplied working directory; only TMPDIR is set in the environment. Direct filesystem access follows this execution\'s sandbox policy.'
}
private readonly config: ResolvedConfig
private readonly pythonBin: string
// The frame cap this instance enforces: the protocol cap, or the host's
@@ -1019,56 +966,93 @@ export class PythonPtcRuntime extends PtcRuntime {
private async teardown(): Promise<void> {
this.disposed = true
const runs = [...this.live]
for (const run of runs) run.settle({ kind: 'abort', message: 'runtime disposed' })
// Awaiting `finished` is also what clears staging: that promise resolves
// inside the run's own `settle`, which removes its directory first. So there
// is deliberately no sweep here — a second pass could only ever find an
// empty set, and an unreachable cleanup path is worse than none, since it
// reads as the real guarantee while never running.
for (const run of runs) run.controller.abort({ kind: 'abort', message: 'runtime disposed' } satisfies PtcRunFailure)
await Promise.all(runs.map(run => run.finished))
}
/**
* Resolve directory and the experimental provider's configured wall deadline.
* @param request - Program inputs; explicit sandbox or timeout overrides are unsupported.
* Resolve authority, directory, and the configured wall deadline.
* @param request - Program inputs and optional resolved sandbox authority; timeout overrides are unsupported.
* @returns Complete inputs for the provider's run method.
* @throws When a requested override is unsupported or cwd is relative.
* @throws When a requested timeout is unsupported, cwd is relative, or the provider is disposed.
*/
resolve(request: PtcRunRequest): PtcRunSpec {
if (request.sandboxPolicy !== undefined) throw new Error('dsh-ptc-runtime-python: sandbox policy is unsupported')
if (this.disposed) throw new Error('dsh-ptc-runtime-python: resolve() after disposal')
if (request.timeoutMs !== undefined) throw new Error('dsh-ptc-runtime-python: per-call timeout is unsupported')
const cwd = request.cwd ?? process.cwd()
const sandboxPolicy = request.sandboxPolicy ?? this.ctx.sandboxPolicy.resolve()
const cwd = request.cwd ?? sandboxPolicy.workspaceRoot
if (!isAbsolute(cwd)) throw new Error('dsh-ptc-runtime-python: cwd must be absolute')
return { ...request, cwd, timeoutMs: this.config.maxWallMs }
return { ...request, cwd, sandboxPolicy, timeoutMs: this.config.maxWallMs }
}
/**
* Execute a resolved Python program; this experimental provider has no file confinement.
* @param request - Resolved cwd, provider deadline, program and bindings.
* @returns Captured output and the program outcome.
* Execute a resolved Python program under its file policy and configured resource budgets.
* @param request - Resolved authority, cwd, provider deadline, program, and bindings.
* @returns Captured output, confinement facts, and the program outcome.
*/
async run(request: PtcRunSpec): Promise<PtcRunResult> {
if (request.sandboxPolicy !== undefined || request.timeoutMs !== this.config.maxWallMs) throw new Error('dsh-ptc-runtime-python: unsupported execution policy or timeout')
if (request.sandboxPolicy === undefined) throw new Error('dsh-ptc-runtime-python: run requires a resolved sandbox policy')
if (request.timeoutMs !== this.config.maxWallMs) throw new Error('dsh-ptc-runtime-python: unsupported execution timeout')
if (!isAbsolute(request.cwd)) throw new Error('dsh-ptc-runtime-python: cwd must be absolute')
if (this.disposed) throw new Error('dsh-ptc-runtime-python: run() after disposal')
const bindings = this.validateBindings(request)
if (request.signal?.aborted) {
return { logs: [], error: { kind: 'abort', message: messageOf(request.signal.reason) } }
const policy = request.sandboxPolicy
const sandbox: PtcRunSandbox = { mode: policy.mode, denied: false }
const controller = new AbortController()
const completion = Promise.withResolvers<void>()
const live: LiveRun = { controller, finished: completion.promise }
const complete = (): void => {
this.live.delete(live)
completion.resolve()
}
let bootstrapPath: string
this.live.add(live)
const onAbort = (): void => {
controller.abort({ kind: 'abort', message: messageOf(request.signal?.reason) } satisfies PtcRunFailure)
}
request.signal?.addEventListener('abort', onAbort, { once: true })
if (request.signal?.aborted) onAbort()
const wallTimer = setTimeout(() => {
controller.abort({ kind: 'timeout', message: `wall-clock ceiling reached (${this.config.maxWallMs}ms)` } satisfies PtcRunFailure)
}, this.config.maxWallMs)
let launched = false
try {
// The interpreter is an external process, so the entry script has to sit
// on the real filesystem; see materializePyScripts. One copy PER RUN,
// synchronously, so no async boundary opens before `execute` registers the
// run and installs the abort listener.
bootstrapPath = materializePyScripts()
controller.signal.throwIfAborted()
let input: string
try {
input = bootstrapInput()
} catch (error: unknown) {
return { logs: [], sandbox, error: { kind: 'worker-exit', message: `failed to read the python bootstrap: ${messageOf(error)}` } }
}
let confined: ConfinedArgv | undefined
// Unbuffered native output stays observable before process-group teardown.
let argv: [string, ...string[]] = [this.pythonBin, '-u', '-I', '-c', PYTHON_BOOTSTRAP_LOADER]
if (policy.mode !== 'danger-full-access') {
confined = await this.ctx.sandbox.confine(argv, { ...policy, mode: policy.mode }, controller.signal)
controller.signal.throwIfAborted()
sandbox.enforcement = confined.enforcement
// The launcher uses the deployment PATH; model code still receives only TMPDIR.
const runner = confined.argv[0]
if (runner === undefined) throw new SandboxUnavailableError(policy.mode, 'sandbox runner argv is empty')
const executable = resolvePythonBin(runner)
if (executable === undefined) throw new SandboxUnavailableError(policy.mode, `sandbox runner is not executable: ${confined.argv[0]}`)
argv = [executable, ...confined.argv.slice(1)]
confined = { ...confined, argv }
}
controller.signal.throwIfAborted()
const pending = this.execute({ ...request, signal: controller.signal }, bindings, argv, input, sandbox, confined, complete)
launched = true
return await pending
} catch (error: unknown) {
// A full or read-only temp filesystem, or a packaged asset the deployment
// failed to ship, is a SUBSTRATE failure — the same class as a child that
// cannot start. The seam permits rejection only for misuse, so this
// resolves as `worker-exit` rather than throwing out of `run()`.
return { logs: [], error: { kind: 'worker-exit', message: `failed to stage the python bootstrap: ${messageOf(error)}` } }
return {
logs: [], sandbox,
error: controller.signal.aborted ? controller.signal.reason as PtcRunFailure
: { kind: error instanceof SandboxUnavailableError ? 'sandbox-unavailable' : 'worker-exit', message: messageOf(error) },
}
} finally {
clearTimeout(wallTimer)
request.signal?.removeEventListener('abort', onAbort)
if (!launched) complete()
}
return await this.execute(request, bindings, bootstrapPath)
}
/* jscpd:ignore-end */
@@ -1165,69 +1149,36 @@ export class PythonPtcRuntime extends PtcRuntime {
return bindings
}
/** Spawn the child for one validated run and drive it to settlement. */
/** Spawn one confined program and retain ownership until its process group settles. */
private execute(
request: PtcRunSpec,
request: PtcRunSpec & { signal: AbortSignal },
bindings: Map<string, ValidatedNamespace>,
bootstrapPath: string,
argv: [string, ...string[]],
input: string,
sandbox: PtcRunSandbox,
confined: ConfinedArgv | undefined,
complete: () => void,
): Promise<PtcRunResult> {
// This run's own staging directory, removed at settlement.
const bootstrapDir = dirname(bootstrapPath)
// Explicit pipe count of 4 puts the framed-JSON channel at fd 3 in the child.
// The constructor resolved and validated the interpreter once; runs keep that
// exact path even if the host later changes PATH.
// `spawn` can throw SYNCHRONOUSLY — a descriptor-exhausted host (EMFILE) or a
// libuv-level failure surfaces here, before the Promise executor and its
// settlement path exist. Left uncaught it would REJECT run() (the seam
// permits rejection only for misuse) and strand this run's staging directory,
// which only settle() removes. Catch it, unlink the directory, and resolve a
// `worker-exit` — the same class as the async ENOENT `error` event below.
let child: ChildProcessWithoutNullStreams
let proto: Duplex | null
try {
// `-u` keeps the interpreter's own stdout/stderr UNBUFFERED: a program
// that writes through `sys.__stdout__`/`sys.__stderr__` (or C-stdio
// layered on the same fds) must have those bytes visible to the host's
// stray capture immediately — a block-buffered wrapper would otherwise
// hold them until an explicit flush, and the host SIGTERMs the child
// right after the done frame, before any finalization-time flush could
// run. The `_LogStream` replacement of `sys.stdout`/`sys.stderr` is
// unaffected (it is a Python object, not the C-level stdio buffer).
child = spawn(this.pythonBin, ['-u', '-I', bootstrapPath], {
child = spawn(argv[0], argv.slice(1), {
cwd: request.cwd,
// Preserve only the platform temp directory. macOS system Python emits a
// startup warning when TMPDIR is absent; ambient credentials, PATH, HOME,
// and other host state remain unavailable to model code.
env: pythonEnvironment(),
detached: true, // Own process group — kill(-pid, sig) reaches subprocesses the model program spawns.
detached: true, // Own the process group used by termination and exit observation.
stdio: ['pipe', 'pipe', 'pipe', 'pipe'],
})
// Fd 3 is a duplex pipe carrying protocol frames. Node types extra stdio
// entries as `Stream | null`; the runtime shape with `'pipe'` is a duplex,
// so we narrow at the boundary rather than smearing casts below. Stdout
// and stderr are guaranteed non-null under `'pipe'` and typed as such.
proto = child.stdio[3] as Duplex | null
/* v8 ignore next 3 -- `'pipe'` stdio always populates fd 3; guarding Node's `Stream | null` typing widening. */
/* v8 ignore next 3 -- Node's extra-stdio typing includes null; four pipe entries supply fd 3. */
if (proto === null) {
throw new Error('dsh-ptc-runtime-python: python subprocess spawned without a fd-3 pipe')
}
// Close the host's stdin write handle immediately: the program is an
// async body that reads nothing from fd 0, and a live pipe here would
// hold a host-side handle open past the run — a setsid-escaped descendant
// inheriting fd 0 would keep the host process from exiting even after the
// closeDeadline forced settlement. The child (and any descendant) reads
// EOF on fd 0 instead, and no host handle survives.
// oxlint-disable-next-line typescript/no-unnecessary-condition -- the boot-write-failure fake child has no stdin.
child.stdin?.destroy()
} catch (error: unknown) {
try {
rmSync(bootstrapDir, { recursive: true, force: true })
} catch {
// Same swallow as settle()'s removal: `force` already absorbs a missing
// directory, so only a filesystem-level refusal reaches here, and the
// staging copy holds nothing but two checked-in scripts.
}
return Promise.resolve({ logs: [], error: { kind: 'worker-exit' as const, message: `python spawn error: ${messageOf(error)}` } })
complete()
return Promise.resolve({ logs: [], sandbox, error: {
kind: confined !== undefined && isRunnerSpawnFailure(error, argv[0], request.cwd) ? 'sandbox-unavailable' : 'worker-exit',
message: `python spawn error: ${messageOf(error)}`,
} })
}
return new Promise<PtcRunResult>((resolve) => {
@@ -1506,7 +1457,13 @@ export class PythonPtcRuntime extends PtcRuntime {
}
}
child.stdout.on('data', (chunk: Buffer) => { captureStray(strayOut, chunk) })
child.stderr.on('data', (chunk: Buffer) => { captureStray(strayErr, chunk) })
let runnerStderr = Buffer.alloc(0)
child.stderr.on('data', (chunk: Buffer) => {
if (confined !== undefined) {
runnerStderr = Buffer.concat([runnerStderr, chunk]).subarray(-this.config.maxLogBytes)
}
captureStray(strayErr, chunk)
})
child.stdout.on('end', () => { flushStray(strayOut) })
child.stderr.on('end', () => { flushStray(strayErr) })
@@ -1846,6 +1803,11 @@ export class PythonPtcRuntime extends PtcRuntime {
return
}
if (message.error) {
if (confined !== undefined) {
const failure = message.error
sandbox.denied = confined.denialSignatures.some(signature =>
failure.message.toLowerCase().includes(signature.toLowerCase()))
}
finish({ error: { kind: message.error.kind, message: capMessage(message.error.message, this.config.maxValueBytes) } })
return
}
@@ -2181,8 +2143,6 @@ export class PythonPtcRuntime extends PtcRuntime {
}
}
let finishResolve!: () => void
const finished = new Promise<void>((done) => { finishResolve = done })
let resolved = false
// The decided terminal result for a live child, recorded by finish() and
// read by the `close` handler that settles it once the pipes have drained.
@@ -2195,25 +2155,7 @@ export class PythonPtcRuntime extends PtcRuntime {
if (resolved) return
resolved = true
if (closeDeadline !== undefined) clearTimeout(closeDeadline)
// The child has exited by now (settle runs on `close`, or on a spawn
// that produced no pid), so its staging directory is no longer read and
// this run's copy goes away with it. Removed SYNCHRONOUSLY, before
// `resolve` below: a fire-and-forget removal left the directory on disk
// when `run()` resolved, so a caller could not observe the "gone by
// settlement" contract at all. Two files cost nothing to unlink here.
try {
rmSync(bootstrapDir, { recursive: true, force: true })
} catch {
// Swallows only a failure to remove this run's staging directory —
// `force` already absorbs a missing one, so what remains is a
// filesystem-level refusal. The run's own outcome is already decided
// and must still be delivered; the directory holds no secret, only a
// copy of two checked-in scripts. teardown deliberately does not
// sweep staging (its staging is cleared inside each run's settle), so
// a removal failure here is the one case the "gone by settlement"
// contract degrades on.
}
resolve({ ...result, logs })
resolve({ ...result, logs, sandbox: { ...sandbox } })
// Mark the fiber quiescent for THIS run: drop it from `live` and resolve
// `finished` (what teardown awaits). Deferred until the process group is
// actually empty — dropping from `live` before then would let a
@@ -2224,8 +2166,7 @@ export class PythonPtcRuntime extends PtcRuntime {
// JSDoc). Keeping the run in `live` until the group is reaped is exactly
// what makes a concurrent teardown await it.
const finalize = (): void => {
this.live.delete(live)
finishResolve()
complete()
}
// `finished` is what teardown awaits to honor "no same-group subprocess
// outlives the fiber". When no escalation ran (normal completion, no
@@ -2302,8 +2243,7 @@ export class PythonPtcRuntime extends PtcRuntime {
if (settled) return
settled = true
decided = result
clearTimeout(wallTimer)
request.signal?.removeEventListener('abort', onAbort)
request.signal.removeEventListener('abort', onAbort)
// A spawn failure (ENOENT, EACCES) never produced a pid, so there is no
// process to kill: settle now. Its `close` still fires later and reaches
// the idempotent settle() again as a no-op.
@@ -2339,6 +2279,7 @@ export class PythonPtcRuntime extends PtcRuntime {
closeDeadline = setTimeout(() => {
flushStray(strayOut)
flushStray(strayErr)
child.stdin.destroy()
proto.destroy()
child.stdout.destroy()
child.stderr.destroy()
@@ -2348,36 +2289,29 @@ export class PythonPtcRuntime extends PtcRuntime {
}
child.on('error', (error: Error) => {
finish({ error: { kind: 'worker-exit', message: `python spawn error: ${error.message}` } })
finish({ error: { kind: confined !== undefined && isRunnerSpawnFailure(error, argv[0], request.cwd) ? 'sandbox-unavailable' : 'worker-exit', message: `python spawn error: ${error.message}` } })
})
let bootstrapWriteFailed = false
// `close` (not `exit`) is the settlement trigger: it fires only after the
// process exits AND every stdio stream — including the fd-3 protocol pipe —
// has drained, so a `done` frame the child wrote just before exiting is
// always handled before we settle. macOS can deliver `exit` before that
// final fd-3 data; keying off `close` makes the ordering irrelevant.
child.on('close', (code: number | null, signal: NodeJS.Signals | null) => {
// If done/timeout/abort already decided the result, finish() is a no-op
// and `decided` holds it — a SIGXCPU that arrives after a decision does
// not override it. Otherwise the child closed before completing: a
// SIGXCPU close is the kernel's own CPU meter firing — the RLIMIT_CPU
// soft limit, or the bootstrap's post-settlement getrusage check
// re-delivering SIGXCPU when a program trapped the soft limit and
// returned inside the soft-to-hard gap. That kernel-authoritative
// signal is the ONLY basis for the timeout classification: wall time
// is not evidence of CPU burn (a sleeping child SIGKILLed by a cgroup
// OOM killer, an operator, or itself consumed none), so every other
// signal or code — including an unsolicited SIGKILL, even the
// hard-limit one — reports as an opaque worker exit.
//
// The message names `cpuSeconds` as the CONFIGURED ceiling, not "the
// budget that fired": the child clamps RLIMIT_CPU to the stricter of
// `cpuSeconds` and any inherited soft limit, so under a tighter inherited
// cap SIGXCPU arrives before `cpuSeconds` — the host cannot see the
// effective value, so it states the ceiling it set rather than a second
// count it cannot guarantee.
finish(signal === 'SIGXCPU'
? { error: { kind: 'timeout', message: `CPU time exhausted (limit at most the configured ${this.config.cpuSeconds}s; a stricter inherited RLIMIT_CPU can fire sooner)` } }
: { error: { kind: 'worker-exit', message: `python exited (code=${String(code)}, signal=${String(signal)}) before completing` } })
// An existing done/timeout/abort decision wins. Without a CPU report
// frame, only SIGXCPU identifies CPU expiry: launchers can remap signals
// to exit codes that programs can also choose deliberately.
// The configured ceiling may exceed the inherited effective RLIMIT_CPU.
const runnerFailure = confined === undefined ? undefined : classifyRunnerFailure(code, runnerStderr.toString('utf8'), confined.runnerFailureRules)
// A launcher refusal can close stdin before its fatal stderr reaches the host.
if (bootstrapWriteFailed && runnerFailure !== undefined) {
decided = { error: { kind: 'sandbox-unavailable', message: runnerFailure.detail } }
}
finish(runnerFailure !== undefined
? { error: { kind: 'sandbox-unavailable', message: runnerFailure.detail } }
: signal === 'SIGXCPU'
? { error: { kind: 'timeout', message: `CPU time exhausted (limit at most the configured ${this.config.cpuSeconds}s; a stricter inherited RLIMIT_CPU can fire sooner)` } }
: { error: { kind: 'worker-exit', message: `python exited (code=${String(code)}, signal=${String(signal)}) before completing` } })
settle(decided)
})
@@ -2389,30 +2323,24 @@ export class PythonPtcRuntime extends PtcRuntime {
child.stdout.on('error', silenceStreamError)
child.stderr.on('error', silenceStreamError)
/* jscpd:ignore-start -- wall-timer/abort/live-run wiring deliberately parallels ptc-runtime-node; see the constructor note. */
const wallTimer = setTimeout(() => {
finish({ error: { kind: 'timeout', message: `wall-clock ceiling reached (${this.config.maxWallMs}ms)` } })
}, this.config.maxWallMs)
const onAbort = (): void => {
finish({ error: { kind: 'abort', message: messageOf(request.signal?.reason) } })
finish({ error: request.signal.reason as PtcRunFailure })
}
request.signal?.addEventListener('abort', onAbort, { once: true })
const live: LiveRun = {
kill,
finished,
settle: (failure: PtcRunFailure) => { finish({ error: failure }) },
request.signal.addEventListener('abort', onAbort, { once: true })
const failBootstrapWrite = (error: unknown): void => {
if (settled) return
bootstrapWriteFailed = true
finish({ error: { kind: 'worker-exit', message: `failed to load python bootstrap: ${messageOf(error)}` } })
}
child.stdin.on('error', failBootstrapWrite)
try {
child.stdin.end(input)
} catch (error: unknown) {
failBootstrapWrite(error)
return
}
this.live.add(live)
/* jscpd:ignore-end */
// Send the boot frame once fd 3 is writable. This runs LAST in run()'s
// synchronous setup: its failure path calls finish(), which reads
// wallTimer/onAbort and (through settle) live, so those bindings must
// already be initialized — issuing the write earlier hit their
// temporal dead zone and threw a ReferenceError that rejected run()
// instead of resolving the worker-exit it constructs here.
// Protocol writes can fail synchronously; cancellation and settlement must already be installed.
const boot: BootMessage = {
type: 'boot',
cpuSeconds: this.config.cpuSeconds,
@@ -0,0 +1,24 @@
/** Deliver trusted Python bootstrap assets without depending on sandbox-visible temporary files. */
import { readFileSync } from 'node:fs'
/** Small interpreter entry point; bootstrap sources arrive on stdin before model execution. */
export const PYTHON_BOOTSTRAP_LOADER = [
'import json, sys, types',
'_sources = json.load(sys.stdin.buffer)',
'_protocol = types.ModuleType("protocol")',
'_protocol.__file__ = "<dsh-ptc-protocol>"',
'exec(compile(_sources["protocol"], _protocol.__file__, "exec"), _protocol.__dict__)',
'sys.modules["protocol"] = _protocol',
'exec(compile(_sources["bootstrap"], "<dsh-ptc-bootstrap>", "exec"), globals())',
].join('\n')
/**
* Read shipped assets through the host filesystem, including packaged virtual files.
* @returns Trusted sources encoded for the interpreter's stdin loader.
*/
export function bootstrapInput(): string {
return JSON.stringify({
protocol: readFileSync(new URL('../py/protocol.py', import.meta.url), 'utf8'),
bootstrap: readFileSync(new URL('../py/bootstrap.py', import.meta.url), 'utf8'),
})
}
@@ -111,9 +111,9 @@ interface LogMessage {
open?: boolean
}
/** The failure carried on a {@link DoneMessage}: one of three kinds plus text. */
/** The failure carried on a {@link DoneMessage}, including child-observed CPU expiry. */
interface DoneErrorField {
kind: 'exception' | 'invalid-output' | 'output-limit'
kind: 'exception' | 'invalid-output' | 'output-limit' | 'timeout'
message: string
}
@@ -121,7 +121,7 @@ interface DoneErrorField {
* Python → host: the program settled. `error` carries a program exception
* (traceback text), an `invalid-output` (completion value was not lossless
* JSON), or an `output-limit` (serialized completion exceeded the configured
* cap); wall/CPU budgets, aborts, and substrate death are observed host-side.
* cap), or a CPU `timeout`; wall budgets, aborts, and substrate death are observed host-side.
* From the honest child `value` is present only on a clean completion that
* produced one, and crosses as exact lossless JSON — never substituted or
* truncated. A forged frame CAN carry both `value` and `error`;
@@ -707,7 +707,7 @@ export function validateChildFrame(raw: unknown): ChildToHost | undefined {
if (typeof err !== 'object' || err === null) return undefined
const { kind, message } = err as Record<string, unknown>
if (typeof message !== 'string') return undefined
if (kind !== 'exception' && kind !== 'invalid-output' && kind !== 'output-limit') return undefined
if (kind !== 'exception' && kind !== 'invalid-output' && kind !== 'output-limit' && kind !== 'timeout') return undefined
return m.value === undefined
? { type: 'done', error: { kind, message } }
: { type: 'done', value: m.value, error: { kind, message } }
@@ -1,9 +1,7 @@
import { EventEmitter } from 'node:events'
import { existsSync } from 'node:fs'
import { dirname } from 'node:path'
import { PassThrough } from 'node:stream'
import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest'
import { Context } from '@deepseek-ai/cordis'
import { createRuntimeContext } from './setup.ts'
/**
* Mocked subprocess pipes control synchronous write failures and backpressure
@@ -23,21 +21,20 @@ const { PythonPtcRuntime } = await import('../src/index.ts')
function fakeChildWithThrowingFd3(): EventEmitter {
const child = new EventEmitter() as EventEmitter & {
pid?: number
stdin: PassThrough
stdout: PassThrough
stderr: PassThrough
stdio: unknown[]
}
// Leave `pid` absent: `finish()` still runs its `clearTimeout(wallTimer)` /
// `removeEventListener(onAbort)` prologue (the TDZ site) before short-
// circuiting on `child.pid === undefined` to `settle` instead of waiting on a
// `close` this fake never emits, so the run resolves promptly.
// An absent pid settles without waiting for a process-close event that this
// pipe fixture does not emit.
child.stdout = new PassThrough()
child.stderr = new PassThrough()
// A duplex whose `write` throws synchronously, standing in for an fd-3 pipe
// that fails the moment the boot frame is issued.
const proto = new PassThrough()
proto.write = () => { throw Object.assign(new Error('EPIPE: broken pipe, write'), { code: 'EPIPE' }) }
child.stdio = [new PassThrough(), child.stdout, child.stderr, proto]
child.stdio = [child.stdin = new PassThrough(), child.stdout, child.stderr, proto]
return child
}
@@ -50,6 +47,7 @@ afterEach(() => {
function fakeChildWithAsyncSpawnError(): EventEmitter {
const child = new EventEmitter() as EventEmitter & {
pid?: number
stdin: PassThrough
stdout: PassThrough
stderr: PassThrough
stdio: unknown[]
@@ -57,7 +55,7 @@ function fakeChildWithAsyncSpawnError(): EventEmitter {
child.stdout = new PassThrough()
child.stderr = new PassThrough()
const proto = new PassThrough()
child.stdio = [new PassThrough(), child.stdout, child.stderr, proto]
child.stdio = [child.stdin = new PassThrough(), child.stdout, child.stderr, proto]
// `spawn` reports an async failure via the child's `error` event; the run
// settles on it as a worker-exit without waiting for `close`.
setImmediate(() => {
@@ -70,6 +68,7 @@ function fakeChildWithAsyncSpawnError(): EventEmitter {
function fakeChildWithAckThenThrowingFd3(): EventEmitter {
const child = new EventEmitter() as EventEmitter & {
pid?: number
stdin: PassThrough
stdout: PassThrough
stderr: PassThrough
stdio: unknown[]
@@ -83,7 +82,7 @@ function fakeChildWithAckThenThrowingFd3(): EventEmitter {
if (writes === 1) return true // The boot frame goes out.
throw Object.assign(new Error('EPIPE: broken pipe, write'), { code: 'EPIPE' })
}
child.stdio = [new PassThrough(), child.stdout, child.stderr, proto]
child.stdio = [child.stdin = new PassThrough(), child.stdout, child.stderr, proto]
// Emit the boot-ack after the boot write, so the run-frame write fires and
// hits the throwing pipe.
setImmediate(() => proto.emit('data', Buffer.from('{"type":"boot-ack"}\n')))
@@ -100,6 +99,7 @@ function fakeChildWithAckThenThrowingFd3(): EventEmitter {
function fakeChildBackpressuredThenDestroyed(): { child: EventEmitter; proto: PassThrough } {
const child = new EventEmitter() as EventEmitter & {
pid?: number
stdin: PassThrough
stdout: PassThrough
stderr: PassThrough
stdio: unknown[]
@@ -110,7 +110,7 @@ function fakeChildBackpressuredThenDestroyed(): { child: EventEmitter; proto: Pa
// Every write reports backpressure (never a `drain` event): the only way the
// reply drain can proceed is the pipe being destroyed under it.
proto.write = () => false
child.stdio = [new PassThrough(), child.stdout, child.stderr, proto]
child.stdio = [child.stdin = new PassThrough(), child.stdout, child.stderr, proto]
// Boot-ack → run frame → two binding calls whose replies backpressure, then
// destroy the pipe while the host still waits for `drain`: the drain loop
// resumes with a queued reply left and must break on the destroyed pipe.
@@ -126,6 +126,91 @@ function fakeChildBackpressuredThenDestroyed(): { child: EventEmitter; proto: Pa
}
describe('PythonPtcRuntime — controlled subprocess pipes', () => {
it.each([
{ asynchronous: false, runnerEvidence: false },
{ asynchronous: false, runnerEvidence: true },
{ asynchronous: true, runnerEvidence: false },
{ asynchronous: true, runnerEvidence: true },
])('attributes spawn failures only to an identified runner: $asynchronous / $runnerEvidence', async ({ asynchronous, runnerEvidence }) => {
const stdin = new PassThrough()
const stdout = new PassThrough()
const stderr = new PassThrough()
const proto = new PassThrough()
const child = Object.assign(new EventEmitter(), { stdin, stdout, stderr, stdio: [stdin, stdout, stderr, proto] })
onTestFinished(() => { for (const stream of [stdin, stdout, stderr, proto]) stream.destroy() })
const ctx = await createRuntimeContext({ mode: 'read-only' })
vi.spyOn(ctx.sandbox, 'confine').mockImplementation(async argv => ({
argv: [...argv], enforcement: 'partial', denialSignatures: [], runnerFailureRules: [],
}))
spawnMock.mockImplementation((bin: string) => {
const error = Object.assign(new Error('executable disappeared'), {
code: 'ENOENT', path: runnerEvidence ? bin : '/another-program', syscall: 'spawn',
})
if (!asynchronous) throw error
setImmediate(() => child.emit('error', error))
return child
})
await ctx.plugin(PythonPtcRuntime)
const result = await ctx.ptcRuntime.run(ctx.ptcRuntime.resolve({ program: 'return 42', bindings: [] }))
expect(result.error?.kind).toBe(runnerEvidence ? 'sandbox-unavailable' : 'worker-exit')
expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'partial' })
})
it.each(['synchronous', 'asynchronous'] as const)('reports %s bootstrap source transport failure', async (failure) => {
const stdin = new PassThrough()
const stdout = new PassThrough()
const stderr = new PassThrough()
const proto = new PassThrough()
const child = Object.assign(new EventEmitter(), { stdin, stdout, stderr, stdio: [stdin, stdout, stderr, proto] })
onTestFinished(() => { for (const stream of [stdin, stdout, stderr, proto]) stream.destroy() })
const error = Object.assign(new Error('EPIPE: bootstrap source pipe closed'), { code: 'EPIPE' })
if (failure === 'synchronous') stdin.end = () => { throw error }
spawnMock.mockImplementation(() => {
if (failure === 'asynchronous') setImmediate(() => stdin.emit('error', error))
return child
})
const ctx = await createRuntimeContext()
await ctx.plugin(PythonPtcRuntime)
const result = await ctx.ptcRuntime.run(ctx.ptcRuntime.resolve({ program: 'return 42', bindings: [] }))
expect(result.error?.kind).toBe('worker-exit')
expect(result.error?.message).toContain('failed to load python bootstrap')
expect(result.value).toBeUndefined()
stdin.emit('error', error)
})
it('preserves a runner refusal that arrives after the bootstrap source pipe closes', async () => {
const stdin = new PassThrough()
const stdout = new PassThrough()
const stderr = new PassThrough()
const proto = new PassThrough()
const pid = 900001
const child = Object.assign(new EventEmitter(), { pid, stdin, stdout, stderr, stdio: [stdin, stdout, stderr, proto] })
const kill = process.kill.bind(process)
const killGroup = vi.spyOn(process, 'kill').mockImplementation((target, signal) => {
if (target !== -pid) return kill(target, signal)
throw Object.assign(new Error('fixture process group has exited'), { code: 'ESRCH' })
})
onTestFinished(() => { killGroup.mockRestore(); for (const stream of [stdin, stdout, stderr, proto]) stream.destroy() })
const ctx = await createRuntimeContext({ mode: 'read-only' })
vi.spyOn(ctx.sandbox, 'confine').mockImplementation(async argv => ({
argv: [...argv], enforcement: 'full', denialSignatures: ['permission denied'],
runnerFailureRules: [{ allowedExitCodes: [127], fatalSignatures: ['sandbox-fatal:'] }],
}))
spawnMock.mockImplementation(() => {
setImmediate(() => {
stdin.emit('error', Object.assign(new Error('source pipe closed'), { code: 'EPIPE' }))
stderr.emit('data', Buffer.from('sandbox-fatal: permission denied\n'))
child.emit('close', 127, null)
})
return child
})
await ctx.plugin(PythonPtcRuntime)
const result = await ctx.ptcRuntime.run(ctx.ptcRuntime.resolve({ program: 'return 42', bindings: [] }))
expect(result.error?.kind).toBe('sandbox-unavailable')
expect(result.error?.message).toContain('sandbox-fatal: permission denied')
expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'full' })
})
it('preserves pending replies across compaction while the pipe stays backpressured', async () => {
const spawned = Promise.withResolvers<undefined>()
let written = Promise.withResolvers<undefined>()
@@ -134,7 +219,7 @@ describe('PythonPtcRuntime — controlled subprocess pipes', () => {
const stdout = new PassThrough()
const stderr = new PassThrough()
const stdin = new PassThrough()
const child = Object.assign(new EventEmitter(), { stdout, stderr, stdio: [stdin, stdout, stderr, proto] })
const child = Object.assign(new EventEmitter(), { stdin, stdout, stderr, stdio: [stdin, stdout, stderr, proto] })
proto.write = (chunk: unknown) => {
const frame = JSON.parse(String(chunk)) as { type: string }
if (frame.type !== 'reply') return true
@@ -143,7 +228,7 @@ describe('PythonPtcRuntime — controlled subprocess pipes', () => {
return false
}
spawnMock.mockImplementation(() => { spawned.resolve(undefined); return child })
const ctx = new Context()
const ctx = await createRuntimeContext()
const fiber = await ctx.plugin(PythonPtcRuntime)
const runtime = ctx.ptcRuntime as InstanceType<typeof PythonPtcRuntime>
const run = runtime.run(runtime.resolve({
@@ -187,7 +272,7 @@ describe('PythonPtcRuntime — controlled subprocess pipes', () => {
})
it('force-kills a version probe that exceeds its load-time deadline', async () => {
const ctx = new Context()
const ctx = await createRuntimeContext()
const fiber = await ctx.plugin(PythonPtcRuntime)
expect(execFileSyncMock).toHaveBeenCalledWith(
@@ -206,7 +291,7 @@ describe('PythonPtcRuntime — controlled subprocess pipes', () => {
// executor and REJECTED run() instead of resolving the worker-exit the catch
// constructs. This test would see that rejection; the fix makes it resolve.
spawnMock.mockImplementation(() => fakeChildWithThrowingFd3())
const ctx = new Context()
const ctx = await createRuntimeContext()
const fiber = await ctx.plugin(PythonPtcRuntime)
const runtime = ctx.ptcRuntime as InstanceType<typeof PythonPtcRuntime>
@@ -217,35 +302,16 @@ describe('PythonPtcRuntime — controlled subprocess pipes', () => {
await fiber.dispose()
})
it('resolves a worker-exit and removes the staging dir when spawn throws synchronously', async () => {
// `spawn` can throw same-tick — EMFILE on a descriptor-exhausted host, or a
// libuv-level failure — before the Promise executor and its settlement path
// exist. Left uncaught it rejected run() (the seam permits rejection only for
// misuse) and stranded the staging directory materializePyScripts had just
// written, which only settle() removes. The fix catches it, unlinks the
// directory, and resolves the same `worker-exit` class as an async ENOENT.
//
// Capture THIS run's exact staging dir from the argv the mocked spawn
// received (`['-I', <dir>/bootstrap.py]`) and assert only that path is gone.
// A tmpdir scan — even a set difference against a pre-run snapshot — would
// flake under vitest's forks pool: a sibling worker creating its own
// `dsh-ptc-runtime-python-*` dir in the window reads as a leak here. Keying
// off our own argv is fully isolated from concurrent staging.
let stagedBootstrap: string | undefined
spawnMock.mockImplementation((_bin: string, args: string[]) => {
stagedBootstrap = args[args.length - 1]
it('resolves a worker-exit when spawn throws synchronously', async () => {
spawnMock.mockImplementation(() => {
throw Object.assign(new Error('EMFILE: too many open files'), { code: 'EMFILE' })
})
const ctx = new Context()
const ctx = await createRuntimeContext()
const fiber = await ctx.plugin(PythonPtcRuntime)
const runtime = ctx.ptcRuntime as InstanceType<typeof PythonPtcRuntime>
const result = await runtime.run(runtime.resolve({ program: 'return 1', bindings: [] }))
expect(result.error?.kind).toBe('worker-exit')
expect(result.error?.message).toContain('python spawn error')
expect(stagedBootstrap).toBeDefined()
expect(existsSync(dirname(stagedBootstrap as string))).toBe(false)
await fiber.dispose()
})
@@ -254,7 +320,7 @@ describe('PythonPtcRuntime — controlled subprocess pipes', () => {
// the boot frame but rejects the run write must settle the run as a
// worker-exit rather than reject run() or leave it hanging.
spawnMock.mockImplementation(() => fakeChildWithAckThenThrowingFd3())
const ctx = new Context()
const ctx = await createRuntimeContext()
const fiber = await ctx.plugin(PythonPtcRuntime)
const runtime = ctx.ptcRuntime as InstanceType<typeof PythonPtcRuntime>
@@ -271,7 +337,7 @@ describe('PythonPtcRuntime — controlled subprocess pipes', () => {
// `error` event, not a synchronous throw. The run must settle as a
// worker-exit from that event.
spawnMock.mockImplementation(() => fakeChildWithAsyncSpawnError())
const ctx = new Context()
const ctx = await createRuntimeContext()
const fiber = await ctx.plugin(PythonPtcRuntime)
const runtime = ctx.ptcRuntime as InstanceType<typeof PythonPtcRuntime>
@@ -298,7 +364,7 @@ describe('PythonPtcRuntime — controlled subprocess pipes', () => {
proto = fake.proto
return fake.child
})
const ctx = new Context()
const ctx = await createRuntimeContext()
const fiber = await ctx.plugin(PythonPtcRuntime, { maxWallMs: 3000 })
const runtime = ctx.ptcRuntime as InstanceType<typeof PythonPtcRuntime>
@@ -59,15 +59,16 @@ describe('validateChildFrame', () => {
.toEqual({ type: 'done', error: { kind: 'invalid-output', message: 'lossy' } })
expect(validateChildFrame({ type: 'done', error: { kind: 'output-limit', message: 'big' } }))
.toEqual({ type: 'done', error: { kind: 'output-limit', message: 'big' } })
expect(validateChildFrame({ type: 'done', error: { kind: 'timeout', message: 'CPU time exhausted' } }))
.toEqual({ type: 'done', error: { kind: 'timeout', message: 'CPU time exhausted' } })
expect(validateChildFrame({ type: 'done', value: 1, error: { kind: 'exception', message: 'boom' } }))
.toEqual({ type: 'done', value: 1, error: { kind: 'exception', message: 'boom' } })
// A `value: undefined` field is dropped (JSON never carries it, but a forged
// shape might; the rebuild coalesces to the absent case).
expect(validateChildFrame({ type: 'done', value: undefined })).toEqual({ type: 'done' })
// A missing or unrecognized kind drops the frame: the child always sends
// one of the three, so anything else is a forgery.
// Unknown failure kinds cannot become runtime outcomes.
expect(validateChildFrame({ type: 'done', error: { message: 'boom' } })).toBeUndefined()
expect(validateChildFrame({ type: 'done', error: { kind: 'timeout', message: 'x' } })).toBeUndefined()
expect(validateChildFrame({ type: 'done', error: { kind: 'unknown', message: 'x' } })).toBeUndefined()
})
it('rejects malformed done frames', () => {
@@ -2,9 +2,9 @@ import { execFileSync } from 'node:child_process'
import { existsSync, mkdtempSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { mkdtemp, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { basename, dirname, join, relative, resolve } from 'node:path'
import { join, relative, resolve } from 'node:path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { Context } from '@deepseek-ai/cordis'
import { createRuntimeContext } from './setup.ts'
import { PythonPtcRuntime, hostFrameParseCeiling, readProcessStart, resolvePythonBin } from '../src/index.ts'
import { logTruncationMarker } from '../src/protocol.ts'
import type { Config } from '../src/index.ts'
@@ -15,27 +15,8 @@ import type { Config } from '../src/index.ts'
const PYABS = resolvePythonBin('python3') ?? 'python3'
import type { PtcBindingFunction, PtcJsonValue, PtcRunResult } from '@deepseek-ai/dsh-ptc-runtime'
/**
* Names one `py/` script whose `copyFileSync` must fail, for the partial-staging
* case. A real disk-full or missing-asset failure mid-copy cannot be produced
* from a test, and the leak only shows when `mkdtempSync` has already succeeded.
*
* `stagedDirs` records every staging directory THIS test file creates, so the
* leak assertions check the exact paths instead of a global tmpdir diff: a
* parallel vitest worker running the same prefix could create or remove
* `dsh-ptc-runtime-python-*` directories inside the sampling window, which a
* readdir diff would misattribute to this test. `boot-write-failure.spec.ts`
* records the same race and solves it with argv-based identity; recording the
* mkdtempSync results is the fs-mock equivalent.
*/
const { failNextCopyOf, stagedDirs, tempDirs, tempFiles } = vi.hoisted(() => ({
failNextCopyOf: { value: undefined as string | undefined },
stagedDirs: [] as string[],
// Test-created temp dirs/files, registered by the helpers below and removed
// after each test: a suite run over real python3 subprocesses must not
// permanently accumulate `dsh-*` fixtures in the shared tmpdir (the runtime
// cleans its own per-run staging dir; these are the stubs and wrappers the
// tests themselves build).
const { failNextReadOf, tempDirs, tempFiles } = vi.hoisted(() => ({
failNextReadOf: { value: undefined as string | undefined },
tempDirs: [] as string[],
tempFiles: [] as string[],
}))
@@ -43,29 +24,19 @@ vi.mock('node:fs', async (importOriginal) => {
const actual = await importOriginal<typeof import('node:fs')>()
return {
...actual,
copyFileSync(source: string, destination: string): void {
if (failNextCopyOf.value !== undefined && basename(source) === failNextCopyOf.value) {
failNextCopyOf.value = undefined
throw Object.assign(new Error('simulated ENOSPC on copy'), { code: 'ENOSPC' })
readFileSync(...args: Parameters<typeof actual.readFileSync>) {
if (failNextReadOf.value !== undefined && String(args[0]).endsWith(`/${failNextReadOf.value}`)) {
failNextReadOf.value = undefined
throw Object.assign(new Error('simulated missing packaged script'), { code: 'ENOENT' })
}
actual.copyFileSync(source, destination)
},
mkdtempSync(prefix: string): string {
const dir = actual.mkdtempSync(prefix)
if (basename(prefix).startsWith('dsh-ptc-runtime-python-')) stagedDirs.push(dir)
return dir
return actual.readFileSync(...args)
},
}
})
/**
* Integration suite over REAL python3 subprocesses (no subprocess mocks — it is
* cheap and local, per docs/testing.md's real-over-mock policy; the only mock is
* `node:fs.copyFileSync` for the staging-failure cases). Each test builds a fresh
* runtime so budgets can be tuned per case.
*/
/** Real CPython processes; packaged-source read failures use the narrow fs mock above. */
async function setup(config: Config = {}) {
const ctx = new Context()
const ctx = await createRuntimeContext()
const fiber = await ctx.plugin(PythonPtcRuntime, config)
const runtime = ctx.ptcRuntime as PythonPtcRuntime
return { ctx, fiber, runtime }
@@ -102,14 +73,15 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
const { runtime } = await setup()
expect(runtime.language).toBe('python')
expect(runtime.isolation).toBe('process')
expect(runtime.executionInstructions).toBe('Each call runs in a fresh Python process. Relative paths use the supplied working directory; only TMPDIR is set in the environment. Direct filesystem access follows this execution\'s sandbox policy.')
})
it('resolves its configured deadline and cwd while refusing unsupported execution choices', async () => {
const { runtime, fiber } = await setup({ maxWallMs: 30_000 })
try {
const request = { program: 'return 1', bindings: [] }
expect(runtime.sandboxMode).toBeUndefined()
expect(runtime.resolve(request)).toEqual({ ...request, cwd: process.cwd(), timeoutMs: 30_000 })
expect(runtime.sandboxMode).toBe('danger-full-access')
expect(runtime.resolve(request)).toEqual({ ...request, cwd: process.cwd(), timeoutMs: 30_000, sandboxPolicy: { mode: 'danger-full-access', workspaceRoot: process.cwd() } })
const cwd = await makeTempDir('dsh-py-resolved-cwd-')
const spec = runtime.resolve({ ...request, cwd })
expect(spec.cwd).toBe(cwd)
@@ -117,10 +89,11 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
expect(() => runtime.resolve({ ...request, timeoutMs: 1 })).toThrow('per-call timeout is unsupported')
expect(() => runtime.resolve({ ...request, timeoutMs: null })).toThrow('per-call timeout is unsupported')
const sandboxPolicy = { mode: 'danger-full-access' as const, workspaceRoot: cwd }
expect(() => runtime.resolve({ ...request, sandboxPolicy })).toThrow('sandbox policy is unsupported')
await expect(runtime.run({ ...spec, sandboxPolicy })).rejects.toThrow('unsupported execution policy or timeout')
await expect(runtime.run({ ...spec, timeoutMs: 1 })).rejects.toThrow('unsupported execution policy or timeout')
await expect(runtime.run({ ...spec, timeoutMs: null })).rejects.toThrow('unsupported execution policy or timeout')
expect(runtime.resolve({ ...request, sandboxPolicy }).sandboxPolicy).toBe(sandboxPolicy)
await expect(runtime.run({ ...request, cwd, timeoutMs: 30_000 })).rejects.toThrow('run requires a resolved sandbox policy')
await expect(runtime.run({ ...spec, cwd: 'relative' })).rejects.toThrow('cwd must be absolute')
await expect(runtime.run({ ...spec, timeoutMs: 1 })).rejects.toThrow('unsupported execution timeout')
await expect(runtime.run({ ...spec, timeoutMs: null })).rejects.toThrow('unsupported execution timeout')
const result = await runtime.run(runtime.resolve({ ...request, cwd, program: 'import os\nreturn os.getcwd()' }))
expect(result.error).toBeUndefined()
expect(result.value).toBe(realpathSync(cwd))
@@ -128,7 +101,7 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
})
it('rejects non-positive config as seam misuse', async () => {
const ctx = new Context()
const ctx = await createRuntimeContext()
await expect(ctx.plugin(PythonPtcRuntime, { cpuSeconds: 0 }))
.rejects.toThrow(/cpuSeconds must be a positive number/)
await expect(ctx.plugin(PythonPtcRuntime, { maxWallMs: -1 }))
@@ -136,7 +109,7 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
})
it('rejects a non-integer cpuSeconds at load (setrlimit needs an int)', async () => {
const ctx = new Context()
const ctx = await createRuntimeContext()
await expect(ctx.plugin(PythonPtcRuntime, { cpuSeconds: 1.5 }))
.rejects.toThrow(/cpuSeconds must be a positive integer, got 1.5/)
})
@@ -145,10 +118,10 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
// maxLogBytes/maxValueBytes cross to the child, which reads them through
// int(...): a float would floor there while the host meters the fraction, so
// the two sides would enforce different public config. Reject at load.
const ctxLog = new Context()
const ctxLog = await createRuntimeContext()
await expect(ctxLog.plugin(PythonPtcRuntime, { maxLogBytes: 3.5 }))
.rejects.toThrow(/maxLogBytes must be a positive integer/)
const ctxValue = new Context()
const ctxValue = await createRuntimeContext()
await expect(ctxValue.plugin(PythonPtcRuntime, { maxValueBytes: 1024.5 }))
.rejects.toThrow(/maxValueBytes must be a positive integer/)
})
@@ -161,7 +134,7 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
// far past the safe range, so `setrlimit` receives a different number than was
// configured. Both used to end every run in a bootstrap exception instead of
// failing at load, where a self-contained configuration error belongs.
const ctx = new Context()
const ctx = await createRuntimeContext()
await expect(ctx.plugin(PythonPtcRuntime, { addressSpaceMb: 1e308 }))
.rejects.toThrow(/addressSpaceMb must be at most \d+ .*exact integer/)
await expect(ctx.plugin(PythonPtcRuntime, { cpuSeconds: 1e100 }))
@@ -187,7 +160,7 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
// worker-exit), so a budget above it would admit a config whose honest
// child frames the host then rejects.
const admissible = 64 * 1024 * 1024 - 64
const ctx = new Context()
const ctx = await createRuntimeContext()
await expect(ctx.plugin(PythonPtcRuntime, { maxLogBytes: admissible + 1 }))
.rejects.toThrow(/maxLogBytes must not exceed 67108800/)
await expect(ctx.plugin(PythonPtcRuntime, { maxValueBytes: admissible + 1 }))
@@ -212,6 +185,9 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
"import { Context } from '@deepseek-ai/cordis'",
"import { PythonPtcRuntime } from './packages/experimental/ptc-runtime-python/src/index.ts'",
'const ctx = new Context()',
"await ctx.plugin((await import('./packages/session/session-projection/src/index.ts')).default)",
"await ctx.plugin((await import('./packages/sandbox/sandbox-policy/src/index.ts')).default, { mode: 'danger-full-access' })",
"await ctx.plugin((await import('./packages/sandbox/sandbox-local/src/index.ts')).default, {})",
'try {',
' await ctx.plugin(PythonPtcRuntime, { maxValueBytes: 50 * 1024 * 1024, addressSpaceMb: 1024 })',
" console.log('LOADED')",
@@ -267,7 +243,7 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
// path, ERR_INVALID_ARG_TYPE for the NUL — so run() would REJECT instead of
// resolving the worker-exit the seam promises for a child that cannot
// start. Both are self-contained configuration errors, so they fail here.
const ctx = new Context()
const ctx = await createRuntimeContext()
await expect(ctx.plugin(PythonPtcRuntime, { pythonBin: '' }))
.rejects.toThrow(/pythonBin must be a non-empty path without NUL bytes/)
await expect(ctx.plugin(PythonPtcRuntime, { pythonBin: 'py\u0000thon3' }))
@@ -289,19 +265,19 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
const directory = nodePath.join(dir, 'is-a-directory')
mkdirSync(directory)
try {
const missing = new Context()
const missing = await createRuntimeContext()
await expect(missing.plugin(PythonPtcRuntime, { pythonBin: nodePath.join(dir, 'missing') }))
.rejects.toThrow(/is not an executable regular file/)
const noX = new Context()
const noX = await createRuntimeContext()
await expect(noX.plugin(PythonPtcRuntime, { pythonBin: notExecutable }))
.rejects.toThrow(/is not an executable regular file/)
const isDir = new Context()
const isDir = await createRuntimeContext()
await expect(isDir.plugin(PythonPtcRuntime, { pythonBin: directory }))
.rejects.toThrow(/is not an executable regular file/)
// A relative explicit path fails the same way, resolved against the host
// CWD: `dir` is absolute, so a slash-containing relative form of it is
// the dirname prefix plus the file, which does not exist as such.
const rel = new Context()
const rel = await createRuntimeContext()
await expect(rel.plugin(PythonPtcRuntime, { pythonBin: './definitely-not-there-python' }))
.rejects.toThrow(/is not an executable regular file/)
} finally {
@@ -311,7 +287,7 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
})
it('rejects a non-CPython, outdated, or probe-failing interpreter at load', async () => {
const nonPython = new Context()
const nonPython = await createRuntimeContext()
await expect(nonPython.plugin(PythonPtcRuntime, { pythonBin: '/bin/echo' }))
.rejects.toThrow(/did not report a CPython version/)
@@ -328,19 +304,19 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
await writeFile(failed, '#!/bin/sh\nexit 7\n', { mode: 0o755 })
try {
expect(resolvePythonBin(relative(process.cwd(), old))).toBe(old)
const obsolete = new Context()
const obsolete = await createRuntimeContext()
await expect(obsolete.plugin(PythonPtcRuntime, { pythonBin: oldMajor }))
.rejects.toThrow(/must be CPython 3\.10 or newer, got cpython 2\.99\.0/)
const outdated = new Context()
const outdated = await createRuntimeContext()
await expect(outdated.plugin(PythonPtcRuntime, { pythonBin: old }))
.rejects.toThrow(/must be CPython 3\.10 or newer, got cpython 3\.9\.6/)
const forwardCompatible = new Context()
const forwardCompatible = await createRuntimeContext()
const fiber = await forwardCompatible.plugin(PythonPtcRuntime, { pythonBin: future })
await fiber.dispose()
const alternative = new Context()
const alternative = await createRuntimeContext()
await expect(alternative.plugin(PythonPtcRuntime, { pythonBin: pypy }))
.rejects.toThrow(/must be CPython, got pypy/)
const probeFailure = new Context()
const probeFailure = await createRuntimeContext()
await expect(probeFailure.plugin(PythonPtcRuntime, { pythonBin: failed }))
.rejects.toThrow(/failed the CPython version probe/)
} finally {
@@ -519,7 +495,7 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
// 1 ms for anything larger, inverting the knob's meaning: a huge maxWallMs
// would time every run out at once, and a huge graceMs would SIGKILL one
// millisecond after SIGTERM. Both must fail at load instead.
const ctx = new Context()
const ctx = await createRuntimeContext()
await expect(ctx.plugin(PythonPtcRuntime, { maxWallMs: 2_147_483_648 }))
.rejects.toThrow(/maxWallMs must not exceed 2147483647/)
// graceMs is bounded by the close deadline's added margin, not by the raw
@@ -539,7 +515,7 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
const original = process.platform
Object.defineProperty(process, 'platform', { value: 'win32', configurable: true })
try {
const ctx = new Context()
const ctx = await createRuntimeContext()
await expect(ctx.plugin(PythonPtcRuntime, {})).rejects.toThrow(/requires a Unix platform/)
} finally {
Object.defineProperty(process, 'platform', { value: original, configurable: true })
@@ -571,9 +547,10 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
it('rejects run() after disposal, and unregisters ctx.ptcRuntime', async () => {
const { ctx, fiber, runtime } = await setup()
const spec = runtime.resolve({ program: 'return 1', bindings: [] })
await fiber.dispose()
await expect(runtime.run(runtime.resolve({ program: 'return 1', bindings: [] })))
.rejects.toThrow(/after disposal/)
await expect(runtime.run(spec)).rejects.toThrow(/after disposal/)
expect(() => runtime.resolve({ program: 'return 1', bindings: [] })).toThrow(/after disposal/)
expect(ctx.get('ptcRuntime')).toBeUndefined()
})
@@ -600,101 +577,62 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
expect(result.logs).toEqual([])
})
it('runs the interpreter from materialized scripts outside the package, and removes them per run', async () => {
// The interpreter is an EXTERNAL process, so it can only open paths the OS
// resolves. Inside the single-file Python-SDK executable the packaged `py/`
// directory lives in pkg's virtual filesystem, which Node reads through its
// patched `fs` but `python3` cannot see, so spawning from that path fails
// with ENOENT. The scripts are therefore copied to a real directory first.
//
// The path is read from the child's own `__main__` module, so it proves
// where the interpreter actually loaded the entry script — asserting on a
// host-side constant would only restate the source. The program namespace
// seeds `__name__` but no `__file__`, hence the module lookup.
// `protocol.py` must land in the SAME directory, since `bootstrap.py` puts
// its own directory on `sys.path` to import it; the run completing at all
// already exercises that import.
it('delivers packaged Python modules without exposing a writable bootstrap file', async () => {
const { runtime } = await setup()
const entryOf = async (): Promise<string> => {
const result = await runtime.run(runtime.resolve({ program: 'import sys\nreturn sys.modules["__main__"].__file__', bindings: [] }))
expect(result.error).toBeUndefined()
return result.value as string
}
const entry = await entryOf()
expect(entry.endsWith('/bootstrap.py')).toBe(true)
const dir = dirname(entry)
expect(realpathSync(dirname(dir))).toBe(realpathSync(tmpdir()))
expect(basename(dir)).toMatch(/^dsh-ptc-runtime-python-/)
expect(dir).not.toContain('/packages/')
// Staging is per RUN and removed at settlement, so by the time `run()`
// resolved the directory is already gone — nothing survives to be rewritten
// by a later run. `protocol.py` had to be beside the entry script for the run
// to complete at all, since `bootstrap.py` imports it off `sys.path`.
expect(existsSync(dir)).toBe(false)
// A second run stages its own copy rather than reusing the first.
expect(dirname(await entryOf())).not.toBe(dir)
const result = await runtime.run(runtime.resolve({
program: 'import sys, protocol\nreturn [hasattr(sys.modules["__main__"], "__file__"), protocol.__file__, sys.stdin.read()]',
bindings: [],
}))
expect(result.error).toBeUndefined()
expect(result.value).toEqual([false, '<dsh-ptc-protocol>', ''])
})
it('contains a program that rewrites its own bootstrap to the run that did it', async () => {
// The child runs as the same UID as the host, so `0o700` does not stop model
// code from rewriting the scripts it was started from —
// `sys.modules['__main__'].__file__` names them. While all runs shared one
// staged copy, a program that overwrote `bootstrap.py` broke the NEXT run
// (measured: it settled as `worker-exit`), and substituted code would have
// run before the resource limits were applied.
const { runtime } = await setup({ maxWallMs: 10_000 })
const sabotage = await runtime.run(runtime.resolve({
it('starts a spawn-context ProcessPoolExecutor with an importable function', async () => {
const { runtime } = await setup({ maxWallMs: 30_000 })
const result = await runtime.run(runtime.resolve({
program: [
'import sys',
'path = sys.modules["__main__"].__file__',
'open(path, "w").write("raise SystemExit(1)\\n")',
'return path',
'from concurrent.futures import ProcessPoolExecutor',
'from multiprocessing import get_context',
'with ProcessPoolExecutor(max_workers=1, mp_context=get_context("spawn")) as pool:',
' return pool.submit(abs, -42).result()',
].join('\n'),
bindings: [],
}))
expect(sabotage.error).toBeUndefined()
// The damage stayed inside the run that caused it.
const after = await runtime.run(runtime.resolve({ program: 'return 1 + 1', bindings: [] }))
expect(after.error).toBeUndefined()
expect(after.value).toBe(2)
}, 20_000)
expect(result.error).toBeUndefined()
expect(result.value).toBe(42)
})
it('leaves no subprocess or scripts behind when disposal races the first run', async () => {
// Staging runs SYNCHRONOUSLY so no async boundary opens between `run()` and
// the point where `execute` registers the run in `live` and installs the
// abort listener. With an `await` there, a disposal landing in that window
// saw an empty `live`, returned, removed the script directory, and let the
// continuation spawn a subprocess after the fiber was gone.
//
// `dispose()` is called in the same synchronous turn as `run()`, with no
// `await` between them, so it lands exactly in that window.
//
// The leak assertion checks the EXACT paths this test file staged (recorded
// by the mocked mkdtempSync) rather than diffing a global tmpdir: a
// parallel vitest worker can create or remove same-prefix directories
// inside the sampling window, which a readdir diff would misattribute to
// this test (boot-write-failure.spec.ts records the same race).
const stagedBefore = stagedDirs.length
it('decodes packaged source as UTF-8 when the interpreter stdin uses ASCII', async () => {
const wrapper = join(await makeTempDir('dsh-python-ascii-'), 'python-ascii')
await writeFile(wrapper, `#!/bin/sh\nLC_ALL=C exec "${PYABS}" -X utf8=0 "$@"\n`, { mode: 0o755 })
const { runtime } = await setup({ pythonBin: wrapper })
const result = await runtime.run(runtime.resolve({ program: 'import sys\nreturn [sys.stdin.encoding, "你好"]', bindings: [] }))
expect(result.error).toBeUndefined()
expect(result.value).toEqual(['ascii', '你好'])
})
it('preserves the kernel CPU soft limit while Python is executing native C code', async () => {
const { runtime } = await setup({ cpuSeconds: 1, maxWallMs: 30_000 })
const result = await runtime.run(runtime.resolve({
program: 'import hashlib\nhashlib.pbkdf2_hmac("sha256", b"password", b"salt", 2147483647)\nreturn "escaped"',
bindings: [],
}))
expect(result.error?.kind).toBe('timeout')
expect(result.error?.message).toContain('CPU time exhausted')
expect(result.value).toBeUndefined()
})
it('disposes the first run before any program can outlive its provider', async () => {
const { fiber, runtime } = await setup({ maxWallMs: 8_000 })
const pending = runtime.run(runtime.resolve({ program: 'import time\nwhile True: time.sleep(0.1)', bindings: [] }))
const disposed = fiber.dispose()
const result = await pending
await disposed
// Whatever the run reports, it must be terminal and must not be a success.
expect(result.value).toBeUndefined()
expect(['abort', 'worker-exit', 'timeout']).toContain(result.error?.kind)
// Disposal is to quiescence, so every directory this run staged is gone.
const created = stagedDirs.slice(stagedBefore)
for (const dir of created) expect(existsSync(dir)).toBe(false)
}, 15_000)
expect(result.error?.kind).toBe('abort')
})
it('settles as abort when the signal fires in the same turn as the first run', async () => {
// Same window, the other listener. `addEventListener('abort')` does not
// replay an event that already fired, so an abort landing before the
// listener was installed used to be missed entirely and the program ran to
// success or the wall ceiling instead of resolving as `abort`. Synchronous
// staging keeps the pre-flight check and the listener in one turn, leaving
// no gap for the signal to slip through.
const { runtime } = await setup({ maxWallMs: 4_000, graceMs: 200 })
const controller = new AbortController()
const pending = runtime.run(runtime.resolve({
@@ -706,58 +644,37 @@ describe('PythonPtcRuntime — seam descriptors and misuse', () => {
const result = await pending
expect(result.error?.kind).toBe('abort')
expect(result.error?.message).toContain('same-turn-abort')
}, 15_000)
})
it('reports a staging failure as worker-exit instead of rejecting run()', async () => {
// Staging touches the filesystem, so it can fail for reasons that are not
// the caller's doing: a full or read-only temp filesystem, or a deployment
// that failed to ship the packaged scripts. Those are SUBSTRATE failures,
// the same class as a child that cannot start, and the seam reserves
// rejection for misuse — so `run()` must resolve, not throw.
//
// `TMPDIR` is the honest lever: `mkdtempSync` builds its path from
// `os.tmpdir()`, so pointing it at a path that is not a directory makes the
// real call fail without stubbing the module under test.
it('boots when the host temporary directory cannot hold files', async () => {
const previous = process.env.TMPDIR
const notADirectory = join(await makeTempDir('dsh-staging-'), 'file')
const notADirectory = join(await makeTempDir('dsh-bootstrap-'), 'file')
await writeFile(notADirectory, '')
process.env.TMPDIR = notADirectory
try {
const { runtime } = await setup()
const result = await runtime.run(runtime.resolve({ program: 'return 1', bindings: [] }))
expect(result.error?.kind).toBe('worker-exit')
expect(result.error?.message).toContain('failed to stage the python bootstrap')
expect(result.logs).toEqual([])
const result = await runtime.run(runtime.resolve({ program: 'return 42', bindings: [] }))
expect(result.error).toBeUndefined()
expect(result.value).toBe(42)
} finally {
if (previous === undefined) delete process.env.TMPDIR
else process.env.TMPDIR = previous
}
})
it('leaves no staging directory behind when a script copy fails', async () => {
// `mkdtempSync` succeeding and a later `copyFileSync` failing is its own
// case: the directory exists but is only partially populated. Recording it
// before the copies would leak it, because `run` retries staging on the next
// call and overwrites the single recorded path — teardown could then remove
// only the newest attempt. Staging must clean up its own partial directory.
//
// Only `copyFileSync` is stubbed, and only for the second script, so
// `mkdtempSync` really runs and the directory under assertion is real.
// The assertion checks the exact paths this test staged (see the sibling
// disposal-race test for why a global tmpdir diff races parallel workers).
const stagedBefore = stagedDirs.length
failNextCopyOf.value = 'protocol.py'
it.each(['protocol.py', 'bootstrap.py'])('reports missing packaged %s without launching a program', async (script) => {
failNextReadOf.value = script
try {
const { runtime } = await setup()
const result = await runtime.run(runtime.resolve({ program: 'return 1', bindings: [] }))
const result = await runtime.run(runtime.resolve({ program: 'return 42', bindings: [] }))
expect(result.error?.kind).toBe('worker-exit')
expect(result.error?.message).toContain('failed to stage the python bootstrap')
// The partial directory is gone, so nothing accumulates across retries.
for (const dir of stagedDirs.slice(stagedBefore)) expect(existsSync(dir)).toBe(false)
expect(result.error?.message).toContain('failed to read the python bootstrap')
expect(result.logs).toEqual([])
expect(result.value).toBeUndefined()
} finally {
failNextCopyOf.value = undefined
failNextReadOf.value = undefined
}
}, 15_000)
})
})
describe('PythonPtcRuntime — process identity', () => {
@@ -1485,10 +1402,10 @@ describe('PythonPtcRuntime — programs and bindings', () => {
// (~16 MiB admissible), so a 50 MB cap is far over; the default caps against
// 512 MiB are not. Both budgets are gated symmetrically — the value case sets
// a default-fitting maxLogBytes so the maxValueBytes check is what fires.
const ctxLog = new Context()
const ctxLog = await createRuntimeContext()
await expect(ctxLog.plugin(PythonPtcRuntime, { maxLogBytes: 50_000_000, addressSpaceMb: 256 }))
.rejects.toThrow(/maxLogBytes times the 12x worst-case Unicode expansion must fit/)
const ctxValue = new Context()
const ctxValue = await createRuntimeContext()
await expect(ctxValue.plugin(PythonPtcRuntime, { maxValueBytes: 50_000_000, addressSpaceMb: 256 }))
.rejects.toThrow(/maxValueBytes times the 12x worst-case Unicode expansion must fit/)
// Discriminates 12 from 8: a 48 MiB maxLogBytes against a 512 MiB address
@@ -1498,21 +1415,21 @@ describe('PythonPtcRuntime — programs and bindings', () => {
// string, the line slice, and the encode copy live at once. The settlement
// flush is no longer the binding case: `flush_line` drops the pending chunks
// before its push, so it holds two copies, not three.
const ctxTwelve = new Context()
const ctxTwelve = await createRuntimeContext()
await expect(ctxTwelve.plugin(PythonPtcRuntime, { maxLogBytes: 48 * 1024 * 1024, addressSpaceMb: 512 }))
.rejects.toThrow(/maxLogBytes times the 12x worst-case Unicode expansion must fit/)
// An addressSpaceMb at or below the interpreter baseline leaves nothing
// budgetable, so no budget value can pass. It is rejected on its own terms:
// the budget loop would otherwise report "a limit of -1" (or -2796203 at
// 32 MiB) while naming maxLogBytes, sending the operator to the wrong knob.
const ctxBaseline = new Context()
const ctxBaseline = await createRuntimeContext()
await expect(ctxBaseline.plugin(PythonPtcRuntime, { addressSpaceMb: 64 }))
.rejects.toThrow(/addressSpaceMb must exceed the 67108864-byte interpreter baseline/)
const ctxBelow = new Context()
const ctxBelow = await createRuntimeContext()
await expect(ctxBelow.plugin(PythonPtcRuntime, { addressSpaceMb: 32 }))
.rejects.toThrow(/addressSpaceMb must exceed the 67108864-byte interpreter baseline/)
// The default caps against the default 512 MiB address space load.
const ok = new Context()
const ok = await createRuntimeContext()
const fiber = await ok.plugin(PythonPtcRuntime, { maxLogBytes: 65536, maxValueBytes: 32768, addressSpaceMb: 512 })
await fiber.dispose()
})
@@ -2750,7 +2667,7 @@ describe('PythonPtcRuntime — programs and bindings', () => {
// empty or NUL pythonBin) rather than silently falling to execvp's
// platform default PATH and starting a system interpreter the caller never
// asked for.
const ctx = new Context()
const ctx = await createRuntimeContext()
await expect(ctx.plugin(PythonPtcRuntime, { pythonBin: 'definitely-no-such-python-xyz' }))
.rejects.toThrow(/does not resolve on PATH/)
})
@@ -0,0 +1,344 @@
import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
import { homedir } from 'node:os'
import { createServer, type Socket } from 'node:net'
import { basename, delimiter, join } from 'node:path'
import { Context } from '@deepseek-ai/cordis'
import Sandbox from '@deepseek-ai/dsh-sandbox-local'
import SandboxPolicy from '@deepseek-ai/dsh-sandbox-policy'
import SessionProjections from '@deepseek-ai/dsh-session-projection'
import { SandboxUnavailableError } from '@deepseek-ai/dsh-sandbox'
import { SessionId } from '@deepseek-ai/dsh-session'
import { describe, expect, it, onTestFinished, vi } from 'vitest'
import type { ConfinedArgv, SandboxMode } from '@deepseek-ai/dsh-sandbox'
import type { Config } from '../src/index.ts'
import { PythonPtcRuntime } from '../src/index.ts'
import { createRuntimeContext } from './setup.ts'
/** Probe the provider independently so a Python launch regression cannot skip confinement tests. */
const sandboxUsable = await (async () => {
const ctx = new Context()
try {
await ctx.plugin(Sandbox, {})
await ctx.sandbox.confine([process.execPath, '--version'], { mode: 'read-only', workspaceRoot: process.cwd() })
return true
} catch (error: unknown) {
if (error instanceof SandboxUnavailableError) return false
throw error
} finally { await ctx.fiber.dispose() }
})()
async function setup(mode: SandboxMode = 'read-only', config: Config = {}) {
// A home-directory fixture stays outside the Linux backend's writable /tmp.
const root = await mkdtemp(join(homedir(), '.dsh-python-sandbox-test-'))
const cwd = join(root, 'workspace')
await mkdir(cwd)
const ctx = await createRuntimeContext({ mode, workspaceRoot: cwd })
onTestFinished(async () => { await ctx.fiber.dispose(); await rm(root, { recursive: true, force: true }) })
const fiber = await ctx.plugin(PythonPtcRuntime, config)
const runtime = ctx.ptcRuntime as PythonPtcRuntime
const run = (program: string) => runtime.run(runtime.resolve({ program, bindings: [] }))
return { ctx, fiber, runtime, root, cwd, run }
}
/** Controlled provider response for testing metadata independently of the host backend. */
function confinement(argv: readonly string[]): ConfinedArgv {
return {
argv: [...argv], enforcement: 'partial', denialSignatures: ['permission denied'],
runnerFailureRules: [{ allowedExitCodes: [127], fatalSignatures: ['sandbox-fatal:'] }],
}
}
describe('Python file sandbox', () => {
it.each(['sandbox', 'sandboxPolicy'] as const)('does not register without the required %s service', async (missing) => {
const ctx = new Context()
onTestFinished(async () => { await ctx.fiber.dispose() })
if (missing !== 'sandbox') await ctx.plugin(Sandbox, {})
if (missing !== 'sandboxPolicy') {
await ctx.plugin(SessionProjections)
await ctx.plugin(SandboxPolicy, { mode: 'danger-full-access' })
}
await ctx.plugin(PythonPtcRuntime)
expect(ctx.get('ptcRuntime')).toBeUndefined()
})
it.skipIf(!sandboxUsable)('denies direct Python writes under the standing read-only policy', async () => {
const { run, cwd } = await setup()
const target = join(cwd, 'protected.txt')
await writeFile(target, 'original')
const result = await run(`open(${JSON.stringify(target)}, "w").write("escaped")`)
expect(await readFile(target, 'utf8')).toBe('original')
expect(result.error?.kind).toBe('exception')
expect(result.sandbox).toMatchObject({ mode: 'read-only', denied: true })
})
it.skipIf(!sandboxUsable)('permits workspace writes while denying direct and symlink writes outside it', async () => {
const { run, cwd, root } = await setup('workspace-write')
const allowed = join(cwd, 'allowed.txt')
const result = await run('open("allowed.txt", "w").write("allowed")\nreturn 42')
expect(result.error).toBeUndefined()
expect(result.value).toBe(42)
expect(result.sandbox).toMatchObject({ mode: 'workspace-write', denied: false })
expect(await readFile(allowed, 'utf8')).toBe('allowed')
const outside = join(root, 'outside')
await mkdir(outside)
await symlink(outside, join(cwd, 'escape'))
for (const path of [join(outside, 'denied.txt'), join(cwd, 'escape', 'denied.txt')]) {
const denied = await run(`open(${JSON.stringify(path)}, "w").write("escaped")`)
expect(denied.error?.kind).toBe('exception')
expect(denied.sandbox).toMatchObject({ mode: 'workspace-write', denied: true })
await expect(readFile(join(outside, 'denied.txt'))).rejects.toMatchObject({ code: 'ENOENT' })
}
})
it('forwards a complete explicit policy and defaults cwd to its workspace', async () => {
const { ctx, runtime, root } = await setup()
const selected = { mode: 'workspace-write' as const, workspaceRoot: root, sessionId: SessionId('python-policy-test') }
const wrap = vi.spyOn(ctx.sandbox, 'confine').mockImplementation(async argv => confinement(argv))
const spec = runtime.resolve({ program: 'import os\nreturn os.getcwd()', bindings: [], sandboxPolicy: selected })
expect(spec.sandboxPolicy).toBe(selected)
expect(spec.cwd).toBe(root)
expect((await runtime.run(spec)).value).toBe(root)
expect(wrap).toHaveBeenCalledExactlyOnceWith(expect.any(Array), selected, expect.any(AbortSignal))
expect(runtime.sandboxMode).toBe('read-only')
})
it('honors a one-call full-access override without changing the standing policy', async () => {
const { ctx, runtime, root } = await setup()
const confine = vi.spyOn(ctx.sandbox, 'confine')
const target = join(root, 'outside.txt')
const result = await runtime.run(runtime.resolve({
program: `open(${JSON.stringify(target)}, "w").write("allowed")\nreturn 42`, bindings: [],
sandboxPolicy: { mode: 'danger-full-access', workspaceRoot: root },
}))
expect(result.error).toBeUndefined()
expect(result.sandbox).toEqual({ mode: 'danger-full-access', denied: false })
expect(await readFile(target, 'utf8')).toBe('allowed')
expect(confine).not.toHaveBeenCalled()
expect(runtime.resolve({ program: '', bindings: [] }).sandboxPolicy?.mode).toBe('read-only')
})
it('fails closed when confinement cannot be prepared', async () => {
const { ctx, run, cwd } = await setup()
const target = join(cwd, 'denied.txt')
const confine = vi.spyOn(ctx.sandbox, 'confine').mockRejectedValue(new SandboxUnavailableError('read-only'))
const result = await run(`open(${JSON.stringify(target)}, "w").write("escaped")`)
expect(result.error?.kind).toBe('sandbox-unavailable')
expect(result.sandbox).toEqual({ mode: 'read-only', denied: false })
expect(confine).toHaveBeenCalledTimes(1)
await expect(readFile(target)).rejects.toMatchObject({ code: 'ENOENT' })
})
it('reports an unexpected provider failure without running the program', async () => {
const { ctx, run } = await setup()
vi.spyOn(ctx.sandbox, 'confine').mockRejectedValue(new Error('provider transport failed'))
const result = await run('return 42')
expect(result.error).toEqual({ kind: 'worker-exit', message: 'provider transport failed' })
expect(result.value).toBeUndefined()
})
it.each([{ argv: [] }, { argv: ['/definitely-missing-python-sandbox-runner'] }])('fails closed for unusable runner argv $argv', async ({ argv }) => {
const { ctx, run } = await setup()
vi.spyOn(ctx.sandbox, 'confine').mockResolvedValue(confinement(argv))
const result = await run('return 42')
expect(result.error?.kind).toBe('sandbox-unavailable')
expect(result.value).toBeUndefined()
})
it.skipIf(!sandboxUsable)('finds a confining launcher on the host PATH without exposing PATH to Python', async () => {
const { ctx, run, root } = await setup()
const confine = ctx.sandbox.confine.bind(ctx.sandbox)
const { resolvePythonBin } = await import('../src/index.ts')
const selected = await confine([process.execPath, '--version'], { mode: 'read-only', workspaceRoot: root })
const executable = resolvePythonBin(selected.argv[0]!)
if (executable === undefined) throw new Error('expected an executable sandbox launcher')
const alias = 'python-test-private-sandbox-launcher'
await symlink(executable, join(root, alias))
vi.stubEnv('PATH', `${root}${delimiter}${process.env.PATH ?? ''}`)
onTestFinished(() => { vi.unstubAllEnvs() })
vi.spyOn(ctx.sandbox, 'confine').mockImplementation(async (argv, policy, signal) => {
const confined = await confine(argv, policy, signal)
return { ...confined, argv: [alias, ...confined.argv.slice(1)] }
})
const result = await run('import os\nreturn os.environ.get("PATH")')
expect(result.error).toBeUndefined()
expect(result.value).toBeNull()
})
it('preserves partial enforcement on successful execution', async () => {
const { ctx, run } = await setup()
vi.spyOn(ctx.sandbox, 'confine').mockImplementation(async argv => confinement(argv))
const result = await run('return 42')
expect(result.error).toBeUndefined()
expect(result.value).toBe(42)
expect(result.sandbox).toEqual({ mode: 'read-only', denied: false, enforcement: 'partial' })
})
it.each([
{ program: 'raise PermissionError("permission denied")', denied: true },
{ program: 'raise PermissionError("read-only file system")', denied: false },
{ program: 'print("permission denied")\nreturn 42', denied: false },
])('uses only the selected backend denial dialect for $program', async ({ program, denied }) => {
const { ctx, run } = await setup()
vi.spyOn(ctx.sandbox, 'confine').mockImplementation(async argv => confinement(argv))
expect((await run(program)).sandbox).toEqual({ mode: 'read-only', denied, enforcement: 'partial' })
})
it.each([
{ code: 127, diagnostic: 'sandbox-fatal: permission denied', kind: 'sandbox-unavailable', denied: false },
{ code: 1, diagnostic: 'sandbox-fatal: permission denied', kind: 'worker-exit', denied: false },
{ code: 127, diagnostic: 'ordinary permission denied', kind: 'worker-exit', denied: false },
])('requires runner evidence and its exit-code gate: $diagnostic ($code)', async ({ code, diagnostic, kind, denied }) => {
const { ctx, run } = await setup()
vi.spyOn(ctx.sandbox, 'confine').mockImplementation(async argv => confinement([
argv[0]!, '-I', '-c', `import os,sys; sys.stdin.read(); os.write(2, ${JSON.stringify(`${diagnostic}\n`)}.encode()); os._exit(${code})`,
]))
const result = await run('return 42')
expect(result.error?.kind).toBe(kind)
expect(result.sandbox).toEqual({ mode: 'read-only', denied, enforcement: 'partial' })
})
it.skipIf(!sandboxUsable)('boots under confinement with stdin EOF, fd-3 bindings, resource limits and a scrubbed environment', async () => {
const { runtime } = await setup('read-only', { cpuSeconds: 7 })
vi.stubEnv('DSH_PYTHON_TEST_SECRET', 'must-not-inherit')
onTestFinished(() => { vi.unstubAllEnvs() })
const result = await runtime.run(runtime.resolve({
program: 'import sys, os, resource\nreturn [sys.stdin.read(), await tools.echo(42), resource.getrlimit(resource.RLIMIT_CPU)[0], os.environ.get("DSH_PYTHON_TEST_SECRET")]',
bindings: [{ global: 'tools', functions: { echo: async args => args as number } }],
}))
expect(result.error).toBeUndefined()
expect(result.value).toEqual(['', 42, 7, null])
expect(result.sandbox).toMatchObject({ mode: 'read-only', denied: false })
})
it.skipIf(!sandboxUsable)('retains the read-only policy in Python child processes', async () => {
const { run, cwd } = await setup()
const target = join(cwd, 'protected.txt')
await writeFile(target, 'original')
const child = `open(${JSON.stringify(target)}, "w").write("escaped")`
const result = await run(`import subprocess,sys\nchild = subprocess.run([sys.executable, "-I", "-c", ${JSON.stringify(child)}], capture_output=True, text=True)\nreturn child.returncode`)
expect(result.error).toBeUndefined()
expect(result.value).not.toBe(0)
expect(await readFile(target, 'utf8')).toBe('original')
})
it.skipIf(!sandboxUsable)('reports CPU termination according to the selected launcher signal transport', async () => {
const { ctx, run } = await setup('read-only', { cpuSeconds: 1, maxWallMs: 30_000 })
const confine = ctx.sandbox.confine.bind(ctx.sandbox)
let mapsSignalsToExitCodes = false
vi.spyOn(ctx.sandbox, 'confine').mockImplementation(async (argv, policy, signal) => {
const result = await confine(argv, policy, signal)
mapsSignalsToExitCodes = basename(result.argv[0]!) === 'bwrap'
return result
})
const result = await run('while True: pass')
expect(result.error?.kind).toBe(mapsSignalsToExitCodes ? 'worker-exit' : 'timeout')
expect(result.error?.message).toContain(mapsSignalsToExitCodes ? 'code=152, signal=null' : 'CPU time exhausted')
expect(result.sandbox).toMatchObject({ mode: 'read-only', denied: false })
})
it.each([
{ program: 'while True: pass', kind: 'worker-exit' },
{
program: 'import signal,time\nsignal.signal(signal.SIGXCPU, signal.SIG_IGN)\nend = time.process_time() + 1.05\nwhile time.process_time() < end: pass\nreturn "escaped"',
kind: 'timeout',
},
{ program: 'import os\nos._exit(152)', kind: 'worker-exit' },
])('distinguishes CPU exhaustion from a numeric exit behind a signal-mapping launcher: $kind', async ({ program, kind }) => {
const { ctx, run } = await setup('read-only', { cpuSeconds: 1, maxWallMs: 30_000 })
// Linux bwrap converts a child's signal into a numeric exit; preserve fd 3
// and exercise that launcher behavior independently of the host platform.
const launcher = 'import subprocess,sys\nchild = subprocess.Popen(sys.argv[1:], pass_fds=(3,))\ncode = child.wait()\nsys.exit(128 - code if code < 0 else code)'
vi.spyOn(ctx.sandbox, 'confine').mockImplementation(async argv => confinement([
argv[0]!, '-I', '-c', launcher, ...argv,
]))
const result = await run(program)
expect(result.error?.kind).toBe(kind)
expect(result.value).toBeUndefined()
if (kind === 'timeout') expect(result.error?.message).toContain('CPU time exhausted')
})
it.skipIf(!sandboxUsable).each(['abort', 'dispose', 'timeout'] as const)('closes a running confined program socket on %s', async (stop) => {
const { fiber, runtime } = await setup('read-only', { maxWallMs: stop === 'timeout' ? 5000 : 30_000 })
const connected = Promise.withResolvers<Socket>()
let socket: Socket | undefined
const server = createServer((accepted) => { socket = accepted; connected.resolve(accepted) })
onTestFinished(async () => {
socket?.destroy()
await new Promise<void>((resolve, reject) => {
server.close((error) => { if (error === undefined) resolve(); else reject(error) })
})
})
await new Promise<void>((resolve, reject) => {
server.once('error', reject)
server.listen(0, '127.0.0.1', resolve)
})
const address = server.address()
if (address === null || typeof address === 'string') throw new Error('expected TCP address')
const entered = Promise.withResolvers<undefined>()
const controller = new AbortController()
const pending = runtime.run(runtime.resolve({
program: `import socket,asyncio\nconnection = socket.create_connection(("127.0.0.1", ${address.port}))\nawait tools.ready(None)\nawait asyncio.Event().wait()`,
bindings: [{ global: 'tools', functions: { ready: async () => { entered.resolve(undefined); return null } } }],
signal: controller.signal,
}))
try {
await entered.promise
socket = await connected.promise
const closed = new Promise<void>((resolve) => { socket!.once('close', () => { resolve() }); socket!.resume() })
if (stop === 'abort') controller.abort('stop confined program')
else if (stop === 'dispose') await fiber.dispose()
const result = await pending
await closed
expect(result.error?.kind).toBe(stop === 'timeout' ? 'timeout' : 'abort')
expect(result.sandbox).toMatchObject({ mode: 'read-only', denied: false })
expect(socket.destroyed).toBe(true)
} finally {
controller.abort('test cleanup')
await pending
}
}, 30_000)
it.each(['abort', 'dispose', 'timeout'] as const)('does not start a program when %s wins during confinement', async (stop) => {
const { ctx, fiber, runtime, cwd } = await setup('read-only', { maxWallMs: 5000 })
const entered = Promise.withResolvers<AbortSignal>()
const release = Promise.withResolvers<ConfinedArgv>()
let selectedArgv: readonly string[] = []
const confine = vi.spyOn(ctx.sandbox, 'confine').mockImplementation((argv, _policy, signal) => {
selectedArgv = argv
if (signal === undefined) throw new Error('confinement needs a cancellation signal')
entered.resolve(signal)
return release.promise
})
const target = join(cwd, 'late-program.txt')
const controller = new AbortController()
if (stop === 'timeout') vi.useFakeTimers()
const pending = runtime.run(runtime.resolve({
program: `open(${JSON.stringify(target)}, "w").write("escaped")`, bindings: [], signal: controller.signal,
}))
let disposed: Promise<void> | undefined
try {
const signal = await entered.promise
expect(signal.aborted).toBe(false)
const stopped = new Promise<void>((resolve) => { signal.addEventListener('abort', () => { resolve() }, { once: true }) })
if (stop === 'abort') controller.abort('cancel preparation')
else if (stop === 'dispose') disposed = fiber.dispose()
else await vi.advanceTimersByTimeAsync(5000)
await stopped
expect(signal.aborted).toBe(true)
release.resolve(confinement(selectedArgv))
const result = await pending
await disposed
expect(result.error?.kind).toBe(stop === 'timeout' ? 'timeout' : 'abort')
expect(result.value).toBeUndefined()
expect(result.sandbox).toMatchObject({ mode: 'read-only', denied: false })
expect(confine).toHaveBeenCalledTimes(1)
await expect(readFile(target)).rejects.toMatchObject({ code: 'ENOENT' })
} finally {
vi.useRealTimers()
controller.abort('test cleanup')
release.resolve(confinement(selectedArgv))
await pending
await disposed
}
})
})
@@ -0,0 +1,16 @@
import { Context } from '@deepseek-ai/cordis'
import Sandbox from '@deepseek-ai/dsh-sandbox-local'
import SandboxPolicy from '@deepseek-ai/dsh-sandbox-policy'
import SessionProjections from '@deepseek-ai/dsh-session-projection'
import { onTestFinished } from 'vitest'
import type { SandboxMode } from '@deepseek-ai/dsh-sandbox'
/** Mount the Python runtime's policy and confinement providers with owned teardown. */
export async function createRuntimeContext(policy: { mode?: SandboxMode; workspaceRoot?: string } = {}): Promise<Context> {
const ctx = new Context()
onTestFinished(async () => { await ctx.fiber.dispose() })
await ctx.plugin(Sandbox, {})
await ctx.plugin(SessionProjections)
await ctx.plugin(SandboxPolicy, { mode: 'danger-full-access', ...policy })
return ctx
}
@@ -1,4 +1,4 @@
import { Context } from '@deepseek-ai/cordis'
import { createRuntimeContext } from './setup.ts'
import { expect, it, vi } from 'vitest'
import { logTruncationMarker } from '../src/protocol.ts'
@@ -28,7 +28,7 @@ vi.mock('node:child_process', async (importOriginal) => {
const { PythonPtcRuntime } = await import('../src/index.ts')
it('seals stray fragments without recopying the sealed prefix', async () => {
const ctx = new Context()
const ctx = await createRuntimeContext()
const fiber = await ctx.plugin(PythonPtcRuntime, { maxLogBytes: 200_000, maxWallMs: 30_000 })
const realConcat = Buffer.concat.bind(Buffer)
let copied = 0
@@ -60,7 +60,7 @@ it.each([
{ name: 'illegal UTF-8 bytes', payload: 'b"\\xff" * 3200' },
{ name: 'CESU-8 lone surrogates', payload: 'b"\\xed\\xa0\\x80" * 1100' },
])('bounds $name by their U+FFFD-decoded cost', async ({ payload }) => {
const ctx = new Context()
const ctx = await createRuntimeContext()
const fiber = await ctx.plugin(PythonPtcRuntime, { maxLogBytes: 3072, maxWallMs: 30_000 })
const realConcat = Buffer.concat.bind(Buffer)
let maxConcat = 0
@@ -25,6 +25,12 @@
},
{
"path": "../../util/values"
},
{
"path": "../../sandbox/sandbox"
},
{
"path": "../../sandbox/sandbox-policy"
}
]
}
+15
View File
@@ -8159,6 +8159,21 @@ importers:
'@deepseek-ai/dsh-ptc-runtime':
specifier: workspace:*
version: link:../../ptc-runtime/ptc-runtime
'@deepseek-ai/dsh-sandbox':
specifier: workspace:*
version: link:../../sandbox/sandbox
'@deepseek-ai/dsh-sandbox-local':
specifier: workspace:*
version: link:../../sandbox/sandbox-local
'@deepseek-ai/dsh-sandbox-policy':
specifier: workspace:*
version: link:../../sandbox/sandbox-policy
'@deepseek-ai/dsh-session':
specifier: workspace:*
version: link:../../core/session
'@deepseek-ai/dsh-session-projection':
specifier: workspace:*
version: link:../../session/session-projection
'@deepseek-ai/dsh-timeout':
specifier: workspace:*
version: link:../../util/timeout
@@ -0,0 +1,24 @@
{"type":"session","version":4,"id":"{{session:1}}","createdAt":1785014439563,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":0}
{"type":"permission/preset","data":{"preset":"read-only"}}
{"type":"sandbox/mode","data":{"mode":"read-only"}}
{"type":"approval/policy","data":{"policy":"ask"}}
{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use one Python run_code program to verify direct Python file writes are denied under the current policy, host environment variables are unavailable, and Python uses the same workspace as bash."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}}
{"type":"turn/start","data":{"turn":1}}
{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
{"type":"step/start","data":{"turn":1,"step":1}}
{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"}
{"type":"user/message","data":{"content":[{"type":"text","text":"Use one Python run_code program to verify direct Python file writes are denied under the current policy, host environment variables are unavailable, and Python uses the same workspace as bash."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: read-only. Any available operation enforced by the DSH file sandbox cannot modify files in the standing mode. Do not refuse a required modification from this policy alone: try an available tool normally and follow any denial and escalation guidance it returns.\n\nApproval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}],"source":{"kind":"runtime-context","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: read-only. Any available operation enforced by the DSH file sandbox cannot modify files in the standing mode. Do not refuse a required modification from this policy alone: try an available tool normally and follow any denial and escalation guidance it returns."},{"name":"approval:policy","text":"Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}"},"reason":"initial"}}
{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
{"type":"session/title","data":{"title":"Use one Python run_code program","messageSeqs":[8],"source":{"kind":"fallback"}}}
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"call_python_policy","name":"run_code","arguments":"{\"code\":\"import errno\\nimport os\\nfrom pathlib import Path\\n\\ndenied = False\\ntry:\\n Path('ptc-denied.txt').write_text('forbidden')\\nexcept OSError as error:\\n denied = error.errno in (errno.EPERM, errno.EACCES, errno.EROFS)\\nshell = await tools.bash({'command': 'pwd', 'description': 'Report the current workspace directory'})\\nreturn {'denied': denied, 'environmentScrubbed': 'DSH_PYTHON_PTC_HOST_SECRET' not in os.environ, 'sameWorkspace': os.getcwd() == shell['stdout']['text'].strip()}\",\"description\":\"Verify Python file policy and execution context\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:4}}"},"usage":{"inputTokens":10,"outputTokens":5},"stream":[{"type":"chunk","time":1789141168541,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1789141168541,"index":0,"dt":[],"id":"call_python_policy","name":"run_code","args":["{\"code\":\"import errno\\nimport os\\nfrom pathlib import Path\\n\\ndenied = False\\ntry:\\n Path('ptc-denied.txt').write_text('forbidden')\\nexcept OSError as error:\\n denied = error.errno in (errno.EPERM, errno.EACCES, errno.EROFS)\\nshell = await tools.bash({'command': 'pwd', 'description': 'Report the current workspace directory'})\\nreturn {'denied': denied, 'environmentScrubbed': 'DSH_PYTHON_PTC_HOST_SECRET' not in os.environ, 'sameWorkspace': os.getcwd() == shell['stdout']['text'].strip()}\",\"description\":\"Verify Python file policy and execution context\"}"]},{"type":"chunk","time":1789141168541,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"call_python_policy","name":"run_code","arguments":"{\"code\":\"import errno\\nimport os\\nfrom pathlib import Path\\n\\ndenied = False\\ntry:\\n Path('ptc-denied.txt').write_text('forbidden')\\nexcept OSError as error:\\n denied = error.errno in (errno.EPERM, errno.EACCES, errno.EROFS)\\nshell = await tools.bash({'command': 'pwd', 'description': 'Report the current workspace directory'})\\nreturn {'denied': denied, 'environmentScrubbed': 'DSH_PYTHON_PTC_HOST_SECRET' not in os.environ, 'sameWorkspace': os.getcwd() == shell['stdout']['text'].strip()}\",\"description\":\"Verify Python file policy and execution context\"}"}}},{"type":"chunk","time":1789141168541,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":5}}},{"type":"chunk","time":1789141168541,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
{"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_python_policy","name":"run_code","arguments":"{\"code\":\"import errno\\nimport os\\nfrom pathlib import Path\\n\\ndenied = False\\ntry:\\n Path('ptc-denied.txt').write_text('forbidden')\\nexcept OSError as error:\\n denied = error.errno in (errno.EPERM, errno.EACCES, errno.EROFS)\\nshell = await tools.bash({'command': 'pwd', 'description': 'Report the current workspace directory'})\\nreturn {'denied': denied, 'environmentScrubbed': 'DSH_PYTHON_PTC_HOST_SECRET' not in os.environ, 'sameWorkspace': os.getcwd() == shell['stdout']['text'].strip()}\",\"description\":\"Verify Python file policy and execution context\"}"}}
{"type":"tool/ptc-dispatch-start","data":{"rootCallId":"call_python_policy","parentCallId":"call_python_policy","subCallId":"call_python_policy:ptc:1","name":"bash","arguments":{"command":"pwd","description":"Report the current workspace directory"}}}
{"type":"tool/ptc-dispatch","data":{"rootCallId":"call_python_policy","parentCallId":"call_python_policy","subCallId":"call_python_policy:ptc:1","name":"bash","arguments":{"command":"pwd","description":"Report the current workspace directory"},"isError":false,"content":[{"type":"text","text":"{{cwd}}\n"}]}}
{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"tool","source":{"kind":"tool","callId":"call_python_policy"},"toolCallId":"call_python_policy","content":[{"type":"text","text":"{\n \"denied\": true,\n \"environmentScrubbed\": true,\n \"sameWorkspace\": true\n}"}],"isError":false,"id":"{{message:5}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
{"type":"step/end","data":{"turn":1,"step":1}}
{"type":"step/start","data":{"turn":1,"step":2}}
{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"text","text":"Python policy and execution context verified."}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:6}}"},"usage":{"inputTokens":10,"outputTokens":2},"stream":[{"type":"chunk","time":1789141168696,"chunk":{"type":"block-start","index":0,"blockType":"text"}},{"type":"text-chunks","time0":1789141168697,"index":0,"dt":[],"texts":["Python policy and execution context verified."]},{"type":"chunk","time":1789141168697,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"Python policy and execution context verified."}}},{"type":"chunk","time":1789141168697,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":2}}},{"type":"chunk","time":1789141168697,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
{"type":"step/end","data":{"turn":1,"step":2}}
{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
@@ -0,0 +1,14 @@
version: 1
scenario: ptc-python-read-only
profile: headless
composition: ptc-python
recording: authored
header:
class: ptc-python
platform: posix
permission: read-only
environment:
DSH_PYTHON_PTC_HOST_SECRET: host-only-sentinel
workspace:
final: true
parent: outside-temp
Whitespace-only changes.
@@ -0,0 +1,26 @@
{"type":"session","version":4,"id":"{{session:1}}","createdAt":1785014439563,"cwd":"{{cwd}}","isSeeded":false,"delegationDepth":0}
{"type":"permission/preset","data":{"preset":"danger-full-access"}}
{"type":"sandbox/mode","data":{"mode":"danger-full-access"}}
{"type":"approval/policy","data":{"policy":"never"}}
{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Using ONE Python run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO`. Inside that same program, print exactly `captured output`, then return the two outputs joined with a plus sign. Reply with that joined string only and stop."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}}
{"type":"turn/start","data":{"turn":1}}
{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
{"type":"step/start","data":{"turn":1,"step":1}}
{"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"}
{"type":"user/message","data":{"content":[{"type":"text","text":"Using ONE Python run_code program: call the bash tool twice — exactly `echo CODE_ONE` then exactly `echo CODE_TWO`. Inside that same program, print exactly `captured output`, then return the two outputs joined with a plus sign. Reply with that joined string only and stop."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"}
{"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"runtime-context","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"}
{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}"},"reason":"initial"}}
{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}}
{"type":"session/title","data":{"title":"Using ONE Python run_code program:","messageSeqs":[8],"source":{"kind":"fallback"}}}
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to write a single Python run_code program that:\n1. Calls bash tool twice: `echo CODE_ONE` and `echo CODE_TWO`\n2. print exactly `captured output`\n3. Return the two outputs joined with a plus sign\n\nLet me write this."},{"type":"tool-call","id":"call_00_UiQPVqoELyzBZCY5pm1z7875","name":"run_code","arguments":"{\"code\":\"out1 = await tools.bash({\\\"command\\\": \\\"echo CODE_ONE\\\", \\\"description\\\": \\\"Print CODE_ONE\\\"})\\nout2 = await tools.bash({\\\"command\\\": \\\"echo CODE_TWO\\\", \\\"description\\\": \\\"Print CODE_TWO\\\"})\\nprint(\\\"captured output\\\")\\ntext1 = out1[\\\"stdout\\\"][\\\"text\\\"].strip()\\ntext2 = out2[\\\"stdout\\\"][\\\"text\\\"].strip()\\nreturn text1 + \\\"+\\\" + text2\",\"description\":\"Run two echo commands and join outputs\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:4}}"},"usage":{"inputTokens":6152,"outputTokens":214,"cacheReadTokens":0,"reasoningTokens":60},"stream":[{"type":"chunk","time":1788699504601,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788699504601,"index":0,"dt":[1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The user wants me to write a single Python run_code program that:\n1. Calls bash tool twice: `echo CODE_ONE` and `echo CODE_TWO`\n2. print exactly `captured output`\n3. Return the two outputs joined with a plus sign\n\nLet me write this.","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","",""]},{"type":"chunk","time":1788699504602,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788699504602,"index":1,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"id":"call_00_UiQPVqoELyzBZCY5pm1z7875","name":"run_code","args":["{\"code\":\"out1 = await tools.bash({\\\"command\\\": \\\"echo CODE_ONE\\\", \\\"description\\\": \\\"Print CODE_ONE\\\"})\\nout2 = await tools.bash({\\\"command\\\": \\\"echo CODE_TWO\\\", \\\"description\\\": \\\"Print CODE_TWO\\\"})\\nprint(\\\"captured output\\\")\\ntext1 = out1[\\\"stdout\\\"][\\\"text\\\"].strip()\\ntext2 = out2[\\\"stdout\\\"][\\\"text\\\"].strip()\\nreturn text1 + \\\"+\\\" + text2\",\"description\":\"Run two echo commands and join outputs\"}","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","",""]},{"type":"chunk","time":1788699504603,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The user wants me to write a single Python run_code program that:\n1. Calls bash tool twice: `echo CODE_ONE` and `echo CODE_TWO`\n2. print exactly `captured output`\n3. Return the two outputs joined with a plus sign\n\nLet me write this."}}},{"type":"chunk","time":1788699504603,"chunk":{"type":"block-end","index":1,"block":{"type":"tool-call","id":"call_00_UiQPVqoELyzBZCY5pm1z7875","name":"run_code","arguments":"{\"code\":\"out1 = await tools.bash({\\\"command\\\": \\\"echo CODE_ONE\\\", \\\"description\\\": \\\"Print CODE_ONE\\\"})\\nout2 = await tools.bash({\\\"command\\\": \\\"echo CODE_TWO\\\", \\\"description\\\": \\\"Print CODE_TWO\\\"})\\nprint(\\\"captured output\\\")\\ntext1 = out1[\\\"stdout\\\"][\\\"text\\\"].strip()\\ntext2 = out2[\\\"stdout\\\"][\\\"text\\\"].strip()\\nreturn text1 + \\\"+\\\" + text2\",\"description\":\"Run two echo commands and join outputs\"}"}}},{"type":"chunk","time":1788699504603,"chunk":{"type":"usage","usage":{"inputTokens":6152,"outputTokens":214,"cacheReadTokens":0,"reasoningTokens":60}}},{"type":"chunk","time":1788699504603,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"}
{"type":"tool/call","data":{"turn":1,"step":1,"callId":"call_00_UiQPVqoELyzBZCY5pm1z7875","name":"run_code","arguments":"{\"code\":\"out1 = await tools.bash({\\\"command\\\": \\\"echo CODE_ONE\\\", \\\"description\\\": \\\"Print CODE_ONE\\\"})\\nout2 = await tools.bash({\\\"command\\\": \\\"echo CODE_TWO\\\", \\\"description\\\": \\\"Print CODE_TWO\\\"})\\nprint(\\\"captured output\\\")\\ntext1 = out1[\\\"stdout\\\"][\\\"text\\\"].strip()\\ntext2 = out2[\\\"stdout\\\"][\\\"text\\\"].strip()\\nreturn text1 + \\\"+\\\" + text2\",\"description\":\"Run two echo commands and join outputs\"}"}}
{"type":"tool/ptc-dispatch-start","data":{"rootCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:ptc:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Print CODE_ONE"}}}
{"type":"tool/ptc-dispatch","data":{"rootCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:ptc:1","name":"bash","arguments":{"command":"echo CODE_ONE","description":"Print CODE_ONE"},"isError":false,"content":[{"type":"text","text":"CODE_ONE\n"}]}}
{"type":"tool/ptc-dispatch-start","data":{"rootCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:ptc:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Print CODE_TWO"}}}
{"type":"tool/ptc-dispatch","data":{"rootCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","parentCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","subCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875:ptc:2","name":"bash","arguments":{"command":"echo CODE_TWO","description":"Print CODE_TWO"},"isError":false,"content":[{"type":"text","text":"CODE_TWO\n"}]}}
{"type":"tool/result","data":{"turn":1,"step":1,"message":{"role":"tool","source":{"kind":"tool","callId":"call_00_UiQPVqoELyzBZCY5pm1z7875"},"toolCallId":"call_00_UiQPVqoELyzBZCY5pm1z7875","content":[{"type":"text","text":"captured output\nCODE_ONE+CODE_TWO"}],"isError":false,"id":"{{message:5}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
{"type":"step/end","data":{"turn":1,"step":1}}
{"type":"step/start","data":{"turn":1,"step":2}}
{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"reasoning","text":"The Python program ran successfully. The print output \"captured output\" appeared, and the return value is \"CODE_ONE+CODE_TWO\". The user asked me to reply with that joined string only."},{"type":"text","text":"CODE_ONE+CODE_TWO"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:6}}"},"usage":{"inputTokens":117,"outputTokens":50,"cacheReadTokens":6272,"reasoningTokens":42},"stream":[{"type":"chunk","time":1788699504708,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}},{"type":"reasoning-chunks","time0":1788699504708,"index":0,"dt":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"texts":["The Python program ran successfully. The print output \"captured output\" appeared, and the return value is \"CODE_ONE+CODE_TWO\". The user asked me to reply with that joined string only.","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","","",""]},{"type":"chunk","time":1788699504708,"chunk":{"type":"block-start","index":1,"blockType":"text"}},{"type":"text-chunks","time0":1788699504708,"index":1,"dt":[0,0,0,0,0,0],"texts":["CODE","_","ONE","+","CODE","_T","WO"]},{"type":"chunk","time":1788699504708,"chunk":{"type":"block-end","index":0,"block":{"type":"reasoning","text":"The Python program ran successfully. The print output \"captured output\" appeared, and the return value is \"CODE_ONE+CODE_TWO\". The user asked me to reply with that joined string only."}}},{"type":"chunk","time":1788699504708,"chunk":{"type":"block-end","index":1,"block":{"type":"text","text":"CODE_ONE+CODE_TWO"}}},{"type":"chunk","time":1788699504708,"chunk":{"type":"usage","usage":{"inputTokens":117,"outputTokens":50,"cacheReadTokens":6272,"reasoningTokens":42}}},{"type":"chunk","time":1788699504708,"chunk":{"type":"finish","reason":{"kind":"stop"}}}]},"surfaceOp":"append"}
{"type":"step/end","data":{"turn":1,"step":2}}
{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}}
@@ -2,7 +2,7 @@
"initial": [
{
"name": "run_code",
"description": "Execute a Python program against the available tools. Takes two required arguments: `description`, a short summary of what the program does, and `code`, the BODY of an async function (top-level `await` and `return` work). Call tools as `await tools.name(args)` per the declarations in the system prompt. Use `print(...)` and/or `return <value>` for program output — curate it. Image-bearing subtool results are attached after the run. The working directory is the Session's current directory.",
"description": "Execute a Python program against the available tools. Takes two required arguments: `description`, a short summary of what the program does, and `code`, the BODY of an async function (top-level `await` and `return` work). Call tools as `await tools.name(args)` per the declarations in the system prompt. Use `print(...)` and/or `return <value>` for program output — curate it. Image-bearing subtool results are attached after the run. Each call runs in a fresh Python process. Relative paths use the supplied working directory; only TMPDIR is set in the environment. Direct filesystem access follows this execution's sandbox policy. The working directory is the Session's current directory. A sandbox escalation approves this complete program for one execution only. Nested tools retain their own policies and approvals. Request wider access only after evidence of a denial. Earlier effects may already have completed: inspect them before explicitly retrying. Programs are never replayed automatically.",
"parameters": {
"type": "object",
"properties": {
@@ -13,6 +13,18 @@
"code": {
"type": "string",
"description": "The program: the body of an async Python function."
},
"sandbox_permissions": {
"type": "string",
"description": "Wider sandbox mode for this complete program execution; requires justification and approval.",
"enum": [
"workspace-write",
"danger-full-access"
]
},
"justification": {
"type": "string",
"description": "Reason this complete program needs wider access, shown to the user for approval. Use the language of the user’s current request."
}
},
"required": [