From 053d17f6a1de0fcc4df3af8b259f4ee76705ca45 Mon Sep 17 00:00:00 2001 From: Chinesezjc Date: Fri, 28 Aug 2026 13:08:11 +0800 Subject: [PATCH] refactor(code-runtime-python): move the package into packages/experimental The CPython code runtime's complete public contract is experimental, so it moves to packages/experimental per the experimental-packages rules: npm name @deepseek-ai/dsh-experimental-code-runtime-python, private: true, no publishConfig. All references updated (code-runtime READMEs, config-catalog and module-graph regenerated with zh alignment, tsconfig paths, doc-standard and workspace-constraints scripts, the fd-3 and settlement Agent Notes, and the package README links); md-links and translation pairing pass, and the suite still runs green. --- ...code-runtime-python-fd3-protocol.i18n.yaml | 4 +- ...-07-31-code-runtime-python-fd3-protocol.md | 4 +- ...-31-code-runtime-python-fd3-protocol.zh.md | 4 +- ...-runtime-python-settlement-fixes.i18n.yaml | 4 +- ...31-code-runtime-python-settlement-fixes.md | 14 +-- ...code-runtime-python-settlement-fixes.zh.md | 14 +-- docs/config-catalog.i18n.yaml | 4 +- docs/config-catalog.md | 118 +++++++++--------- docs/config-catalog.zh.md | 6 +- docs/module-graph.i18n.yaml | 4 +- docs/module-graph.md | 12 +- docs/module-graph.zh.md | 12 +- packages/code-runtime/README.i18n.yaml | 4 +- packages/code-runtime/README.md | 2 +- packages/code-runtime/README.zh.md | 2 +- .../code-runtime/README.i18n.yaml | 4 +- packages/code-runtime/code-runtime/README.md | 6 +- .../code-runtime/code-runtime/README.zh.md | 8 +- .../code-runtime-python/README.i18n.yaml | 6 +- .../code-runtime-python/README.md | 8 +- .../code-runtime-python/README.zh.md | 8 +- .../code-runtime-python/package.json | 10 +- .../code-runtime-python/py/bootstrap.py | 0 .../code-runtime-python/py/protocol.py | 0 .../code-runtime-python/src/index.ts | 0 .../code-runtime-python/src/invariant.ts | 0 .../code-runtime-python/src/protocol.ts | 0 .../tests/boot-write-failure.spec.ts | 0 .../tests/protocol-mirror.e2e.ts | 0 .../tests/protocol.spec.ts | 0 .../tests/residual-detach.spec.ts | 0 .../code-runtime-python/tests/runtime.spec.ts | 0 .../code-runtime-python/tsconfig.json | 2 +- .../code-runtime-python/tsdown.config.ts | 0 pnpm-lock.yaml | 44 +++---- scripts/check-workspace-constraints.ts | 2 +- .../verify-package-readme-model-experience.ts | 2 +- tsconfig.host.json | 2 +- 38 files changed, 154 insertions(+), 156 deletions(-) rename packages/{code-runtime => experimental}/code-runtime-python/README.i18n.yaml (54%) rename packages/{code-runtime => experimental}/code-runtime-python/README.md (91%) rename packages/{code-runtime => experimental}/code-runtime-python/README.zh.md (91%) rename packages/{code-runtime => experimental}/code-runtime-python/package.json (89%) rename packages/{code-runtime => experimental}/code-runtime-python/py/bootstrap.py (100%) rename packages/{code-runtime => experimental}/code-runtime-python/py/protocol.py (100%) rename packages/{code-runtime => experimental}/code-runtime-python/src/index.ts (100%) rename packages/{code-runtime => experimental}/code-runtime-python/src/invariant.ts (100%) rename packages/{code-runtime => experimental}/code-runtime-python/src/protocol.ts (100%) rename packages/{code-runtime => experimental}/code-runtime-python/tests/boot-write-failure.spec.ts (100%) rename packages/{code-runtime => experimental}/code-runtime-python/tests/protocol-mirror.e2e.ts (100%) rename packages/{code-runtime => experimental}/code-runtime-python/tests/protocol.spec.ts (100%) rename packages/{code-runtime => experimental}/code-runtime-python/tests/residual-detach.spec.ts (100%) rename packages/{code-runtime => experimental}/code-runtime-python/tests/runtime.spec.ts (100%) rename packages/{code-runtime => experimental}/code-runtime-python/tsconfig.json (91%) rename packages/{code-runtime => experimental}/code-runtime-python/tsdown.config.ts (100%) diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.i18n.yaml index 996543474e..6117fd79c3 100644 --- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.md -2026-07-31-code-runtime-python-fd3-protocol.md: 90f648e837094c16ff1c5a4cabe9bfe73801ae71 -2026-07-31-code-runtime-python-fd3-protocol.zh.md: a547fb1d3620f66a064d4f19e7d9c7d12183f7f5 +2026-07-31-code-runtime-python-fd3-protocol.md: 6f687683666d32bffb423c697fac4d8f576b0a6a +2026-07-31-code-runtime-python-fd3-protocol.zh.md: 8b7fd110ae99b7f2d15aba87968dc0acc911d17f diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.md index 90f648e837..6f68768366 100644 --- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.md +++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.md @@ -6,9 +6,9 @@ English | [中文](2026-07-31-code-runtime-python-fd3-protocol.zh.md) ## Problem -`@deepseek-ai/dsh-code-runtime-python` owns the wire protocol intended for a CPython code-runtime provider. Such a provider runs each model program in a fresh `python3 -I` subprocess and bridges binding calls and completion values over the child's fd 3. The host cannot trust that channel: model code has full access to fd 3 and can forge any frame, so every inbound frame is hostile input that the host must validate and rebuild before reading. The protocol also has to carry lossless JSON without the depth limit `JSON.stringify` and `json.dumps` impose, because the seam's `CodeJsonValue` is depth-unbounded. +`@deepseek-ai/dsh-experimental-code-runtime-python` owns the wire protocol intended for a CPython code-runtime provider. Such a provider runs each model program in a fresh `python3 -I` subprocess and bridges binding calls and completion values over the child's fd 3. The host cannot trust that channel: model code has full access to fd 3 and can forge any frame, so every inbound frame is hostile input that the host must validate and rebuild before reading. The protocol also has to carry lossless JSON without the depth limit `JSON.stringify` and `json.dumps` impose, because the seam's `CodeJsonValue` is depth-unbounded. -The package ships the protocol AND the runtime implementation: `PythonCodeRuntime` (the plugin's default export), the `python3 -I` subprocess path, and the Python-side JSON codec all live in `@deepseek-ai/dsh-code-runtime-python`. The protocol builds on the [portable identifier seam](2026-07-31-code-runtime-portable-identifier-seam.md). +The package ships the protocol AND the runtime implementation: `PythonCodeRuntime` (the plugin's default export), the `python3 -I` subprocess path, and the Python-side JSON codec all live in `@deepseek-ai/dsh-experimental-code-runtime-python`. The protocol builds on the [portable identifier seam](2026-07-31-code-runtime-portable-identifier-seam.md). ## Decision diff --git a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.zh.md index a547fb1d36..8b7fd110ae 100644 --- a/.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.zh.md @@ -6,9 +6,9 @@ Status: implemented ## Problem -`@deepseek-ai/dsh-code-runtime-python` 负责供 CPython code-runtime 提供方使用的 wire protocol。这样的提供方会在全新的 `python3 -I` 子进程中运行每个模型程序，并通过子进程 fd 3 桥接 binding 调用与完成值。Host 不能信任这条通道：模型代码可以完全访问 fd 3 并伪造任意帧，因此 host 必须把每个入站帧视为敌意输入，先校验并重建后才能读取。协议还必须承载无深度限制的 lossless JSON，因为 seam 的 `CodeJsonValue` 深度无界，而 `JSON.stringify` 和 `json.dumps` 都有递归深度限制。 +`@deepseek-ai/dsh-experimental-code-runtime-python` 负责供 CPython code-runtime 提供方使用的 wire protocol。这样的提供方会在全新的 `python3 -I` 子进程中运行每个模型程序，并通过子进程 fd 3 桥接 binding 调用与完成值。Host 不能信任这条通道：模型代码可以完全访问 fd 3 并伪造任意帧，因此 host 必须把每个入站帧视为敌意输入，先校验并重建后才能读取。协议还必须承载无深度限制的 lossless JSON，因为 seam 的 `CodeJsonValue` 深度无界，而 `JSON.stringify` 和 `json.dumps` 都有递归深度限制。 -该包同时交付协议与 runtime 实现：`PythonCodeRuntime`（插件的默认导出）、`python3 -I` 子进程路径与 Python 侧 JSON codec 都在 `@deepseek-ai/dsh-code-runtime-python` 中。协议建立在[可移植标识符 seam](2026-07-31-code-runtime-portable-identifier-seam.zh.md)之上。 +该包同时交付协议与 runtime 实现：`PythonCodeRuntime`（插件的默认导出）、`python3 -I` 子进程路径与 Python 侧 JSON codec 都在 `@deepseek-ai/dsh-experimental-code-runtime-python` 中。协议建立在[可移植标识符 seam](2026-07-31-code-runtime-portable-identifier-seam.zh.md)之上。 ## Decision diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.i18n.yaml index 5cf6d46043..c083ad28a8 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.md -2026-07-31-code-runtime-python-settlement-fixes.md: f98d9f4a21c8a50f7e978826d7788f6aa69baf70 -2026-07-31-code-runtime-python-settlement-fixes.zh.md: 4a1aa138aaedfb6302b4c9108b1834dcfedcadc9 +2026-07-31-code-runtime-python-settlement-fixes.md: acedb62882864301bda55366031a2981209a0629 +2026-07-31-code-runtime-python-settlement-fixes.zh.md: 5919d4db95245565afa75500bcdadb9e6082b6da diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.md b/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.md index f98d9f4a21..acedb62882 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.md +++ b/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.md @@ -22,11 +22,11 @@ An explicit `flush()` of an unterminated line emits a `log` frame with `open: tr ### Boot-write failure no longer rejects run() -In [`src/index.ts`](../../../../packages/code-runtime/code-runtime-python/src/index.ts) the fd-3 boot-frame write is the last statement of `run()`'s synchronous setup. Its `catch` calls `finish()`, and `finish()` reads `wallTimer` and `onAbort` and — through `settle()` — `live`. Those bindings are `const` and were declared AFTER the boot-write, so on a synchronous write failure `finish()` touched them in their temporal dead zone and threw a `ReferenceError`. That escaped the Promise executor and REJECTED `run()`, violating the seam's "outcomes resolve" contract: the caller saw a thrown error instead of the `worker-exit` the catch constructs. The boot-write block is now emitted after `wallTimer`, `onAbort`, and `live` are initialized, and the `/* v8 ignore */` that had hidden the branch from coverage is removed so the catch is measured. +In [`src/index.ts`](../../../../packages/experimental/code-runtime-python/src/index.ts) the fd-3 boot-frame write is the last statement of `run()`'s synchronous setup. Its `catch` calls `finish()`, and `finish()` reads `wallTimer` and `onAbort` and — through `settle()` — `live`. Those bindings are `const` and were declared AFTER the boot-write, so on a synchronous write failure `finish()` touched them in their temporal dead zone and threw a `ReferenceError`. That escaped the Promise executor and REJECTED `run()`, violating the seam's "outcomes resolve" contract: the caller saw a thrown error instead of the `worker-exit` the catch constructs. The boot-write block is now emitted after `wallTimer`, `onAbort`, and `live` are initialized, and the `/* v8 ignore */` that had hidden the branch from coverage is removed so the catch is measured. ### Log capture is serialized against settlement -In [`py/bootstrap.py`](../../../../packages/code-runtime/code-runtime-python/py/bootstrap.py) the settlement `flush_out()`/`flush_err()` on the main coroutine read and clear each stream's `_pending` list and mutate the shared `LogBuffer` ledger. Model code may start daemon threads whose `print`/`write` mutate the same state concurrently. Capturing the bound method (`out_stream.flush_line`) fixed only WHICH callable settlement invokes, not what it reads mid-flight: an interleaved flush could join a `_pending` list being mutated under it, corrupting the ledger and costing the `done` frame — stranding the run to the wall clock. `LogBuffer` now owns one re-entrant lock shared by both streams; `_LogStream.write` and `flush_line`, and `LogBuffer.push`, take it, so the whole read-modify-write is atomic across threads. +In [`py/bootstrap.py`](../../../../packages/experimental/code-runtime-python/py/bootstrap.py) the settlement `flush_out()`/`flush_err()` on the main coroutine read and clear each stream's `_pending` list and mutate the shared `LogBuffer` ledger. Model code may start daemon threads whose `print`/`write` mutate the same state concurrently. Capturing the bound method (`out_stream.flush_line`) fixed only WHICH callable settlement invokes, not what it reads mid-flight: an interleaved flush could join a `_pending` list being mutated under it, corrupting the ledger and costing the `done` frame — stranding the run to the wall clock. `LogBuffer` now owns one re-entrant lock shared by both streams; `_LogStream.write` and `flush_line`, and `LogBuffer.push`, take it, so the whole read-modify-write is atomic across threads. ### Fd-3 residual is copied, not viewed @@ -48,7 +48,7 @@ The reap poll also handles a host event loop BLOCKED past both timers. If a sync ### RLIMIT clamps against the inherited soft limit, not only the hard -In [`py/bootstrap.py`](../../../../packages/code-runtime/code-runtime-python/py/bootstrap.py) `_clamped` bounded a requested `(soft, hard)` rlimit pair by the inherited HARD limit alone. A deployment that inherited a soft limit below the requested one — say inherited `(100, 200)`, requested `(150, 160)` — got back `(150, 160)`, RAISING the effective soft from 100 to 150: for `RLIMIT_AS` that loosens the memory ceiling, for `RLIMIT_CPU` it defers SIGXCPU, both violating "strictest of configured and inherited". `_clamped` now clamps each side against its own inherited counterpart (`RLIM_INFINITY` imposing no ceiling), then pins soft under hard so `setrlimit` never sees an inverted pair. The settlement-time CPU recheck (`die_if_cpu_exhausted`) follows the same rule: it compares spent CPU against the EFFECTIVE clamped `cpu_soft`, not the configured `cpuSeconds`, so a program that traps SIGXCPU and burns past a stricter inherited soft before returning is reported as a timeout rather than a false success. The recheck restores SIG_DFL BEFORE unblocking a program-masked SIGXCPU (`pthread_sigmask(SIG_UNBLOCK, ...)`, captured at import): a program that installed a custom handler AND masked the signal would otherwise have that pending handler run at the unblock — in model code, able to re-mask or raise — so the disposition must already be SIG_DFL when the signal is released; with SIG_DFL first the pending signal kills inside the kernel with no bytecode window, and the `kill` re-raise is the fallback for the never-pending case. The SIGXCPU diagnostic no longer names the configured `cpuSeconds` as the effective budget — under a stricter inherited soft that number is wrong — and instead reports that CPU time was exhausted at "at most the configured N seconds", which holds whichever limit fired. +In [`py/bootstrap.py`](../../../../packages/experimental/code-runtime-python/py/bootstrap.py) `_clamped` bounded a requested `(soft, hard)` rlimit pair by the inherited HARD limit alone. A deployment that inherited a soft limit below the requested one — say inherited `(100, 200)`, requested `(150, 160)` — got back `(150, 160)`, RAISING the effective soft from 100 to 150: for `RLIMIT_AS` that loosens the memory ceiling, for `RLIMIT_CPU` it defers SIGXCPU, both violating "strictest of configured and inherited". `_clamped` now clamps each side against its own inherited counterpart (`RLIM_INFINITY` imposing no ceiling), then pins soft under hard so `setrlimit` never sees an inverted pair. The settlement-time CPU recheck (`die_if_cpu_exhausted`) follows the same rule: it compares spent CPU against the EFFECTIVE clamped `cpu_soft`, not the configured `cpuSeconds`, so a program that traps SIGXCPU and burns past a stricter inherited soft before returning is reported as a timeout rather than a false success. The recheck restores SIG_DFL BEFORE unblocking a program-masked SIGXCPU (`pthread_sigmask(SIG_UNBLOCK, ...)`, captured at import): a program that installed a custom handler AND masked the signal would otherwise have that pending handler run at the unblock — in model code, able to re-mask or raise — so the disposition must already be SIG_DFL when the signal is released; with SIG_DFL first the pending signal kills inside the kernel with no bytecode window, and the `kill` re-raise is the fallback for the never-pending case. The SIGXCPU diagnostic no longer names the configured `cpuSeconds` as the effective budget — under a stricter inherited soft that number is wrong — and instead reports that CPU time was exhausted at "at most the configured N seconds", which holds whichever limit fired. ### Concurrent binding replies are paced against fd 3 @@ -74,7 +74,7 @@ Also in `src/index.ts`, native stdout/stderr bytes (C-extension writes, `os.writ ### An incompatible output-budget/addressSpaceMb pair is rejected at load -The child ([`py/bootstrap.py`](../../../../packages/code-runtime/code-runtime-python/py/bootstrap.py)) builds, charges, and frames a `maxLogBytes` log entry or a `maxValueBytes` completion value under `RLIMIT_AS`, and both ledgers trigger on CHARACTER count against a serialized-BYTE budget. An astral character is one character but four bytes of CPython `str` storage and four UTF-8 bytes, and the heaviest path holds THREE such copies at once: a single `sys.stdout.write(line + "\n")` keeps the caller's `text` argument (alive for the whole `write` call, ~4×), the line slice handed to `LogBuffer.push` (~4×), and the `text.encode("utf-8")` copy `_push_locked` takes to charge and ship it (~4×) — a peak of ~12× the budget. The settlement `flush_line` path holds only two (its `"".join(...)` and that encode copy — it drops the pending chunks before pushing), so the newline path is the binding worst case. When a budget approaches `addressSpaceMb`, a LEGITIMATE near-budget output breaches the address space during that build-and-encode and dies as `worker-exit` instead of truncating (log) or failing as `output-limit` (value). Metering every child write against the address space at runtime is the wrong fix: an exact serialized-cost check on the hot path is either a full `encode` (the allocation being avoided) or a per-character Python loop (which burns the CPU budget — a 10 MB legitimate write hits SIGXCPU under `cpuSeconds: 1`). Both trade one resource bound for another. Instead [`src/index.ts`](../../../../packages/code-runtime/code-runtime-python/src/index.ts) rejects the incompatible pair at LOAD: each budget times `OUTPUT_BUDGET_WORST_CASE_ADDRESS_SPACE_MULTIPLE` (twelve — the three simultaneous ~4× copies of the newline path) must fit the address space LEFT after a fixed `INTERPRETER_BASELINE_BYTES` reservation for the interpreter's own footprint, with a `>=` so a budget whose worst-case peak exactly equals that room is rejected (that peak plus the reserved baseline is the whole address space, the `RLIMIT_AS` edge). `flush_line` was also made to drop the pending chunks BEFORE its push, matching the newline path's join-clear-push order, so it holds at most the join and its encode rather than three copies. The baseline is reserved SEPARATELY from the multiple because it is a fixed cost, not one that scales with the budget: folding it into the multiple would leave a budget sized right at `addressSpaceMb / 12` admitted while its peak plus the interpreter still overran. Both `maxLogBytes` and `maxValueBytes` are gated symmetrically; the value path's build-and-encode is the same shape. The check runs on every platform, not just where `RLIMIT_AS` is enforced: the incompatibility is a property of the config values, so a Linux deployment OOMs regardless of the host that assembled the config, and a uniform load-time rejection is the fail-loud contract (Darwin skips only the runtime `setrlimit`). This eliminates the class at the config seam rather than patching the write path, so `_LogStream` keeps its original character-count buffering (a valid lower bound on serialized cost, memory-safe once the budget fits the address space). The value path enforces the same discipline in a second place: `_check_done_value` (the byte meter) and `_encode_json_plain` (the frame encoder) walk in O(DEPTH), not O(width). Each container pushes ONE cursor frame that pulls its children one at a time rather than one traversal tuple or stack entry per child — a flat `[0] * 6_000_000` serializes to ~12 MB but a per-element walk allocates ~400 MB of bookkeeping (~28× the serialized size, far past the 12× the gate reserves), so a value the meter admits could OOM on the walk's own frames. With the cursor, the only width-proportional allocation is the output string the meter already bounded. +The child ([`py/bootstrap.py`](../../../../packages/experimental/code-runtime-python/py/bootstrap.py)) builds, charges, and frames a `maxLogBytes` log entry or a `maxValueBytes` completion value under `RLIMIT_AS`, and both ledgers trigger on CHARACTER count against a serialized-BYTE budget. An astral character is one character but four bytes of CPython `str` storage and four UTF-8 bytes, and the heaviest path holds THREE such copies at once: a single `sys.stdout.write(line + "\n")` keeps the caller's `text` argument (alive for the whole `write` call, ~4×), the line slice handed to `LogBuffer.push` (~4×), and the `text.encode("utf-8")` copy `_push_locked` takes to charge and ship it (~4×) — a peak of ~12× the budget. The settlement `flush_line` path holds only two (its `"".join(...)` and that encode copy — it drops the pending chunks before pushing), so the newline path is the binding worst case. When a budget approaches `addressSpaceMb`, a LEGITIMATE near-budget output breaches the address space during that build-and-encode and dies as `worker-exit` instead of truncating (log) or failing as `output-limit` (value). Metering every child write against the address space at runtime is the wrong fix: an exact serialized-cost check on the hot path is either a full `encode` (the allocation being avoided) or a per-character Python loop (which burns the CPU budget — a 10 MB legitimate write hits SIGXCPU under `cpuSeconds: 1`). Both trade one resource bound for another. Instead [`src/index.ts`](../../../../packages/experimental/code-runtime-python/src/index.ts) rejects the incompatible pair at LOAD: each budget times `OUTPUT_BUDGET_WORST_CASE_ADDRESS_SPACE_MULTIPLE` (twelve — the three simultaneous ~4× copies of the newline path) must fit the address space LEFT after a fixed `INTERPRETER_BASELINE_BYTES` reservation for the interpreter's own footprint, with a `>=` so a budget whose worst-case peak exactly equals that room is rejected (that peak plus the reserved baseline is the whole address space, the `RLIMIT_AS` edge). `flush_line` was also made to drop the pending chunks BEFORE its push, matching the newline path's join-clear-push order, so it holds at most the join and its encode rather than three copies. The baseline is reserved SEPARATELY from the multiple because it is a fixed cost, not one that scales with the budget: folding it into the multiple would leave a budget sized right at `addressSpaceMb / 12` admitted while its peak plus the interpreter still overran. Both `maxLogBytes` and `maxValueBytes` are gated symmetrically; the value path's build-and-encode is the same shape. The check runs on every platform, not just where `RLIMIT_AS` is enforced: the incompatibility is a property of the config values, so a Linux deployment OOMs regardless of the host that assembled the config, and a uniform load-time rejection is the fail-loud contract (Darwin skips only the runtime `setrlimit`). This eliminates the class at the config seam rather than patching the write path, so `_LogStream` keeps its original character-count buffering (a valid lower bound on serialized cost, memory-safe once the budget fits the address space). The value path enforces the same discipline in a second place: `_check_done_value` (the byte meter) and `_encode_json_plain` (the frame encoder) walk in O(DEPTH), not O(width). Each container pushes ONE cursor frame that pulls its children one at a time rather than one traversal tuple or stack entry per child — a flat `[0] * 6_000_000` serializes to ~12 MB but a per-element walk allocates ~400 MB of bookkeeping (~28× the serialized size, far past the 12× the gate reserves), so a value the meter admits could OOM on the walk's own frames. With the cursor, the only width-proportional allocation is the output string the meter already bounded. The host gate validates against the CONFIGURED `addressSpaceMb`, but a launch environment can inherit a STRICTER `RLIMIT_AS` (a `ulimit -v` wrapper below `addressSpaceMb`), which the bootstrap's `_clamped` correctly lowers the EFFECTIVE limit to — leaving the budgets sized for a ceiling the child never gets. So `bootstrap.py` re-checks both budgets against the effective clamped soft limit after applying it, mirroring the host gate's multiple and baseline, and raises at boot (caught by the setrlimit-phase handler and reported as `exception`, the same class as any other resource-limit-application failure) rather than letting a near-budget output OOM mid-run. The two child constants are kept in step with the host's by the shared reasoning, not a wire field. @@ -82,13 +82,13 @@ One residual write-path copy is fixed alongside, independent of the config gate: ### The completion value and error are pre-encoded at their validation point -In [`py/bootstrap.py`](../../../../packages/code-runtime/code-runtime-python/py/bootstrap.py), `_done_with_value` now returns the whole terminal frame as a PRE-ENCODED JSON string on the success path: the admitted value is serialized once here, at the validation point inside `_run`'s `try`, as `'{"type": "done", "value": ' + _encode_json_plain(value) + "}"`. The program can keep mutating a returned list/dict from a daemon thread or signal handler after it returns, so a second traversal held at a later point would be a TOCTOU — a concurrent mutation into a non-JSON type would let that later encode throw outside the settlement handler and downgrade a settled run host-side to `worker-exit`. Serializing once, inside the `try` that wraps this call, closes the window: if a concurrent mutation makes the encode throw, the exception handler classifies it as an `exception`, and once the string is produced the frame is written verbatim with no further touching of the live value. `_run` binds the `_done_with_value` ENTRY NAME into a local (`done_with_value_bound`) before the program runs, and `_done_with_value` itself binds `_check_done_value` and `_encode_json_plain` as DEF-TIME default arguments — so a `__main__` rebind of the entry name or those two names after model execution cannot rewrite a legitimate success into an `exception`. The log ledgers (host `logBudget` and child `_remaining`) start ONE byte below the budget, reserving the serialized outer-array envelope (two brackets and n-1 commas over n entries' separators), so a result that exactly exhausts the ledger still serializes within the configured cap; the truncation marker remains envelope, not payload. Once a ledger has truncated, the host clears both stray pipes' buffered output wholesale (every later byte would be no-op'd by `admit`, so retaining it would spend host memory on output that can never be admitted); the child runs `-u` so `sys.__stdout__`/`sys.__stderr__` writes are visible to stray capture immediately, and the settlement flush still drains the original std streams before the done frame (a guard against a buffered wrapper surviving a `sys.__stdout__ = boom` rebind). The constructor rejects a `maxLogBytes` below 64 (the smallest budget with one byte of room for the truncation marker's own serialized form); `maxValueBytes` keeps only the positive-integer requirement, since a completion can be a single byte and the done-frame envelope is seam protocol cost. The marker remains envelope, so a truncated run with admitted entries serializes to at most `maxLogBytes + marker + envelope` (recorded in the package README). A rebind of a transitive dep the encoder reaches (e.g. `_dump_scalar`/`_dump_string`/`json`/`io` — a non-exhaustive set) can still make the encode throw and downgrade a success to an `exception`, which is registered as an accepted residual in the package README. +In [`py/bootstrap.py`](../../../../packages/experimental/code-runtime-python/py/bootstrap.py), `_done_with_value` now returns the whole terminal frame as a PRE-ENCODED JSON string on the success path: the admitted value is serialized once here, at the validation point inside `_run`'s `try`, as `'{"type": "done", "value": ' + _encode_json_plain(value) + "}"`. The program can keep mutating a returned list/dict from a daemon thread or signal handler after it returns, so a second traversal held at a later point would be a TOCTOU — a concurrent mutation into a non-JSON type would let that later encode throw outside the settlement handler and downgrade a settled run host-side to `worker-exit`. Serializing once, inside the `try` that wraps this call, closes the window: if a concurrent mutation makes the encode throw, the exception handler classifies it as an `exception`, and once the string is produced the frame is written verbatim with no further touching of the live value. `_run` binds the `_done_with_value` ENTRY NAME into a local (`done_with_value_bound`) before the program runs, and `_done_with_value` itself binds `_check_done_value` and `_encode_json_plain` as DEF-TIME default arguments — so a `__main__` rebind of the entry name or those two names after model execution cannot rewrite a legitimate success into an `exception`. The log ledgers (host `logBudget` and child `_remaining`) start ONE byte below the budget, reserving the serialized outer-array envelope (two brackets and n-1 commas over n entries' separators), so a result that exactly exhausts the ledger still serializes within the configured cap; the truncation marker remains envelope, not payload. Once a ledger has truncated, the host clears both stray pipes' buffered output wholesale (every later byte would be no-op'd by `admit`, so retaining it would spend host memory on output that can never be admitted); the child runs `-u` so `sys.__stdout__`/`sys.__stderr__` writes are visible to stray capture immediately, and the settlement flush still drains the original std streams before the done frame (a guard against a buffered wrapper surviving a `sys.__stdout__ = boom` rebind). The constructor rejects a `maxLogBytes` below 64 (the smallest budget with one byte of room for the truncation marker's own serialized form); `maxValueBytes` keeps only the positive-integer requirement, since a completion can be a single byte and the done-frame envelope is seam protocol cost. The marker remains envelope, so a truncated run with admitted entries serializes to at most `maxLogBytes + marker + envelope` (recorded in the package README). A rebind of a transitive dep the encoder reaches (e.g. `_dump_scalar`/`_dump_string`/`json`/`io` — a non-exhaustive set) can still make the encode throw and downgrade a success to an `exception`, which is registered as an accepted residual in the package README. `send_done` (a local function inside `_run`) writes the pre-encoded string through a BOUND `channel.write_encoded`, and encodes a dict error frame through a bound `_encode_json_plain` before writing it — it never calls `channel.send_sync`, whose body re-resolves `self.write_encoded` and the module-level `_encode_json_plain` at call time. `_encode_json_plain` and `channel.write_encoded` are bound into locals before the program runs, for the same reason `flush_out`/`flush_err`/`safe_model_traceback` are: the program runs as `__main__`, so `import __main__; __main__.ProtocolChannel.send_sync = boom` or `__main__._encode_json_plain = boom` would otherwise re-resolve the send/encode to a rebranded callable at call time and, when that replacement raises, skip the `done` frame and downgrade a settled verdict to a host-side `worker-exit`. ### A budget flush retains an unfinished trailing multibyte sequence -Also in [`src/index.ts`](../../../../packages/code-runtime/code-runtime-python/src/index.ts), `flushStray(stray, retainPartialTail)` withholds an unfinished multibyte tail from the decode on the BUDGET-triggered flush (the combined-cost threshold in `captureStray`): when the residual ends on a partial UTF-8 lead sequence (`stray.utf8.expected > 0`), the leading byte plus the continuations consumed so far (≤3 bytes) are detached from the frame as the new residual, and only the complete prefix is admitted and decoded. Nothing is admitted when the whole residual is a single unfinished sequence, so a legal, un-finished character is never rendered as U+FFFD in a released, un-truncated entry, and no bogus empty entry is pushed. The withheld tail is re-accrued from a FRESH `stray.utf8` state — metering it against the post-flush `expected > 0` state would charge the carried lead byte as an illegal continuation — so the next chunk continues the walk correctly and the pipe's cost/UTF-8 state is rebuilt over the retained tail. The `end`/`closeDeadline` paths pass `false` and decode the FULL residual unchanged, because there a trailing incomplete sequence is real truncated input and the U+FFFD is the honest render. +Also in [`src/index.ts`](../../../../packages/experimental/code-runtime-python/src/index.ts), `flushStray(stray, retainPartialTail)` withholds an unfinished multibyte tail from the decode on the BUDGET-triggered flush (the combined-cost threshold in `captureStray`): when the residual ends on a partial UTF-8 lead sequence (`stray.utf8.expected > 0`), the leading byte plus the continuations consumed so far (≤3 bytes) are detached from the frame as the new residual, and only the complete prefix is admitted and decoded. Nothing is admitted when the whole residual is a single unfinished sequence, so a legal, un-finished character is never rendered as U+FFFD in a released, un-truncated entry, and no bogus empty entry is pushed. The withheld tail is re-accrued from a FRESH `stray.utf8` state — metering it against the post-flush `expected > 0` state would charge the carried lead byte as an illegal continuation — so the next chunk continues the walk correctly and the pipe's cost/UTF-8 state is rebuilt over the retained tail. The `end`/`closeDeadline` paths pass `false` and decode the FULL residual unchanged, because there a trailing incomplete sequence is real truncated input and the U+FFFD is the honest render. ### A late binding rejection returns before formatting the error @@ -96,7 +96,7 @@ Also in `src/index.ts`, the binding-rejection catch branch now checks `settled` ### A newline-free drip seals its fragments; the CPU soft limit is kept below the hard; the done frame falls back to a fixed literal; the reply queue clears consumed slots -In [`py/bootstrap.py`](../../../../packages/code-runtime/code-runtime-python/py/bootstrap.py), `_LogStream` now seals the pending-fragment list past a cap: a newline-free drip of one character per `write` would otherwise accumulate one list slot (and one str object) per call, and under a large `maxLogBytes` a 25 M single-character flood OOMs on its own accounting (plus the same-size list `_push_bounded_prefix` then builds) before the byte budget is reached. Past `_PENDING_MAX_CHUNKS` the current fragments are joined into ONE block moved to a `_pending_blocks` list (the character count is unchanged), bounding the live fragment count exactly as the host-side `captureStray` seal does; the join is only the ≤cap current fragments, never the whole accumulated buffer, so a large drip stays O(B) rather than re-copying the growing block O(B²/cap) times. The HOST-side open hold mirrors the same seal: a budget-sized single-character open flood (`print('x', end='', flush=True)` in a loop is an honest-child path) would otherwise accumulate one fragment array slot plus string object header per frame — ~30× overhead the byte cap cannot see, up to ~2 GB of host auxiliary heap near the `maxLogBytes` load ceiling. Past `MAX_PENDING_CHUNKS` the held fragments coalesce into `openSealed`; the closing-frame merge, `truncateLogs`, and the `finish` residual all read sealed + current fragments and clear the seal. +In [`py/bootstrap.py`](../../../../packages/experimental/code-runtime-python/py/bootstrap.py), `_LogStream` now seals the pending-fragment list past a cap: a newline-free drip of one character per `write` would otherwise accumulate one list slot (and one str object) per call, and under a large `maxLogBytes` a 25 M single-character flood OOMs on its own accounting (plus the same-size list `_push_bounded_prefix` then builds) before the byte budget is reached. Past `_PENDING_MAX_CHUNKS` the current fragments are joined into ONE block moved to a `_pending_blocks` list (the character count is unchanged), bounding the live fragment count exactly as the host-side `captureStray` seal does; the join is only the ≤cap current fragments, never the whole accumulated buffer, so a large drip stays O(B) rather than re-copying the growing block O(B²/cap) times. The HOST-side open hold mirrors the same seal: a budget-sized single-character open flood (`print('x', end='', flush=True)` in a loop is an honest-child path) would otherwise accumulate one fragment array slot plus string object header per frame — ~30× overhead the byte cap cannot see, up to ~2 GB of host auxiliary heap near the `maxLogBytes` load ceiling. Past `MAX_PENDING_CHUNKS` the held fragments coalesce into `openSealed`; the closing-frame merge, `truncateLogs`, and the `finish` residual all read sealed + current fragments and clear the seal. `_clamped` also lowers a clamped RLIMIT_CPU soft limit that EQUALS the hard by one unit (when the hard is at least 2). A `ulimit -t N` sets both, and with soft == hard the kernel checks the hard limit in the same tick and SIGKILLs a busy loop directly, so SIGXCPU is never delivered — and the host classifies a CPU overrun ONLY on `signal === 'SIGXCPU'`, so a definite budget exhaustion would be misreported as a `worker-exit`. Lowering the soft one unit gives SIGXCPU a window to fire, so the overrun is reported as a timeout. This is scoped to RLIMIT_CPU (a one-byte soft differential on RLIMIT_AS would only misalign the child's applied limit with the host budget gate, with no signal to preserve). The `hard >= 2` guard leaves a `hard == 1` blind spot — a 1-second dual limit cannot lower the soft to 0, so a definite overrun there is still reported as `worker-exit`. diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.zh.md index 4a1aa138aa..5919d4db95 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.zh.md @@ -22,11 +22,11 @@ unknown-binding 回复用 `JSON.stringify` 对完整的限幅 target（`global` ### Boot-write failure no longer rejects run() -在 [`src/index.ts`](../../../../packages/code-runtime/code-runtime-python/src/index.ts) 中，fd-3 引导帧写入是 `run()` 同步初始化阶段的最后一条语句。它的 `catch` 会调用 `finish()`，而 `finish()` 读取 `wallTimer` 和 `onAbort`，并通过 `settle()` 读取 `live`。这些绑定是 `const`，且声明在引导写入之后，因此在同步写入失败时，`finish()` 会在它们处于暂时性死区（temporal dead zone）时访问它们，从而抛出一个 `ReferenceError`。该错误逃出了 Promise executor 并 reject 了 `run()`，违反了 seam 的"结果一律 resolve"契约：调用方看到的是一个被抛出的错误，而不是 catch 构造的 `worker-exit`。现在引导写入代码块被放到 `wallTimer`、`onAbort` 和 `live` 初始化之后，并且那处曾把该分支从覆盖率中隐藏的 `/* v8 ignore */` 已被移除，从而使该 catch 被纳入度量。 +在 [`src/index.ts`](../../../../packages/experimental/code-runtime-python/src/index.ts) 中，fd-3 引导帧写入是 `run()` 同步初始化阶段的最后一条语句。它的 `catch` 会调用 `finish()`，而 `finish()` 读取 `wallTimer` 和 `onAbort`，并通过 `settle()` 读取 `live`。这些绑定是 `const`，且声明在引导写入之后，因此在同步写入失败时，`finish()` 会在它们处于暂时性死区（temporal dead zone）时访问它们，从而抛出一个 `ReferenceError`。该错误逃出了 Promise executor 并 reject 了 `run()`，违反了 seam 的"结果一律 resolve"契约：调用方看到的是一个被抛出的错误，而不是 catch 构造的 `worker-exit`。现在引导写入代码块被放到 `wallTimer`、`onAbort` 和 `live` 初始化之后，并且那处曾把该分支从覆盖率中隐藏的 `/* v8 ignore */` 已被移除，从而使该 catch 被纳入度量。 ### Log capture is serialized against settlement -在 [`py/bootstrap.py`](../../../../packages/code-runtime/code-runtime-python/py/bootstrap.py) 中，主协程上的结算 `flush_out()`／`flush_err()` 会读取并清空各个流的 `_pending` 列表，并修改共享的 `LogBuffer` 账本。模型代码可能启动一些 daemon 线程，其 `print`／`write` 会并发地修改同一状态。捕获绑定方法（`out_stream.flush_line`）只解决了结算调用哪个可调用对象的问题，而没有解决它在执行途中读取什么的问题：一次交错的 flush 可能拼接一个正在其下被修改的 `_pending` 列表，从而破坏账本并丢失 `done` 帧，使该次运行一直拖到墙钟超时。现在 `LogBuffer` 持有一把由两个流共享的可重入锁；`_LogStream.write` 和 `flush_line`，以及 `LogBuffer.push`，都会获取该锁，因此整个读-改-写过程在多线程间是原子的。 +在 [`py/bootstrap.py`](../../../../packages/experimental/code-runtime-python/py/bootstrap.py) 中，主协程上的结算 `flush_out()`／`flush_err()` 会读取并清空各个流的 `_pending` 列表，并修改共享的 `LogBuffer` 账本。模型代码可能启动一些 daemon 线程，其 `print`／`write` 会并发地修改同一状态。捕获绑定方法（`out_stream.flush_line`）只解决了结算调用哪个可调用对象的问题，而没有解决它在执行途中读取什么的问题：一次交错的 flush 可能拼接一个正在其下被修改的 `_pending` 列表，从而破坏账本并丢失 `done` 帧，使该次运行一直拖到墙钟超时。现在 `LogBuffer` 持有一把由两个流共享的可重入锁；`_LogStream.write` 和 `flush_line`，以及 `LogBuffer.push`，都会获取该锁，因此整个读-改-写过程在多线程间是原子的。 ### Fd-3 residual is copied, not viewed @@ -48,7 +48,7 @@ unknown-binding 回复用 `JSON.stringify` 对完整的限幅 target（`global` ### RLIMIT clamps against the inherited soft limit, not only the hard -在 [`py/bootstrap.py`](../../../../packages/code-runtime/code-runtime-python/py/bootstrap.py) 中，`_clamped` 仅用继承而来的 HARD 限制来约束一个请求的 `(soft, hard)` rlimit 对。一个继承了低于请求值的软限制的部署——比如继承 `(100, 200)`、请求 `(150, 160)`——会拿回 `(150, 160)`，把有效软限制从 100 抬高到 150：对 `RLIMIT_AS` 而言这放松了内存上限，对 `RLIMIT_CPU` 而言它推迟了 SIGXCPU，两者都违反了"取配置值与继承值中最严格者"。现在 `_clamped` 用每一侧各自继承而来的对应值来约束该侧（`RLIM_INFINITY` 不施加任何上限），随后把 soft 钉在 hard 之下，因此 `setrlimit` 绝不会看到一个倒置的对。结算时的 CPU 复查（`die_if_cpu_exhausted`）遵循同一规则：它把已消耗的 CPU 与实际生效的、被夹紧的 `cpu_soft` 比较，而不是与配置的 `cpuSeconds` 比较，因此一个捕获 SIGXCPU、在返回前消耗超过更严格的继承软限制的程序会被报告为 timeout，而非误判为成功。 复查会在解除程序屏蔽的 SIGXCPU（`pthread_sigmask(SIG_UNBLOCK, ...)`，import 期捕获）之前先恢复 SIG_DFL：一个既安装自定义 handler 又屏蔽信号的程序，否则会在 unblock 的瞬间让那个挂起的 handler 以模型代码身份运行（可重新屏蔽或抛出），所以信号被释放时处置必须已是 SIG_DFL；SIG_DFL 在前时，挂起的信号在内核内直接致死、无字节码窗口，而 `kill` 重投递是给从未挂起情形的兜底。SIGXCPU 诊断不再把配置的 `cpuSeconds` 说成实际生效的预算——在一个更严格的继承软限制之下那个数字是错的——而是报告 CPU 时间是在"至多配置的 N 秒"处被耗尽，这一表述无论哪个限制先触发都成立。 +在 [`py/bootstrap.py`](../../../../packages/experimental/code-runtime-python/py/bootstrap.py) 中，`_clamped` 仅用继承而来的 HARD 限制来约束一个请求的 `(soft, hard)` rlimit 对。一个继承了低于请求值的软限制的部署——比如继承 `(100, 200)`、请求 `(150, 160)`——会拿回 `(150, 160)`，把有效软限制从 100 抬高到 150：对 `RLIMIT_AS` 而言这放松了内存上限，对 `RLIMIT_CPU` 而言它推迟了 SIGXCPU，两者都违反了"取配置值与继承值中最严格者"。现在 `_clamped` 用每一侧各自继承而来的对应值来约束该侧（`RLIM_INFINITY` 不施加任何上限），随后把 soft 钉在 hard 之下，因此 `setrlimit` 绝不会看到一个倒置的对。结算时的 CPU 复查（`die_if_cpu_exhausted`）遵循同一规则：它把已消耗的 CPU 与实际生效的、被夹紧的 `cpu_soft` 比较，而不是与配置的 `cpuSeconds` 比较，因此一个捕获 SIGXCPU、在返回前消耗超过更严格的继承软限制的程序会被报告为 timeout，而非误判为成功。 复查会在解除程序屏蔽的 SIGXCPU（`pthread_sigmask(SIG_UNBLOCK, ...)`，import 期捕获）之前先恢复 SIG_DFL：一个既安装自定义 handler 又屏蔽信号的程序，否则会在 unblock 的瞬间让那个挂起的 handler 以模型代码身份运行（可重新屏蔽或抛出），所以信号被释放时处置必须已是 SIG_DFL；SIG_DFL 在前时，挂起的信号在内核内直接致死、无字节码窗口，而 `kill` 重投递是给从未挂起情形的兜底。SIGXCPU 诊断不再把配置的 `cpuSeconds` 说成实际生效的预算——在一个更严格的继承软限制之下那个数字是错的——而是报告 CPU 时间是在"至多配置的 N 秒"处被耗尽，这一表述无论哪个限制先触发都成立。 ### 并发 binding 回复对 fd 3 做节流 @@ -74,7 +74,7 @@ unknown-binding 回复用 `JSON.stringify` 对完整的限幅 target（`global` ### An incompatible output-budget/addressSpaceMb pair is rejected at load -子进程（[`py/bootstrap.py`](../../../../packages/code-runtime/code-runtime-python/py/bootstrap.py)）在 `RLIMIT_AS` 之下构建、计费并分帧一条 `maxLogBytes` 的日志条目或一个 `maxValueBytes` 的完成值，而两个账本都是按字符计数、对照一个序列化字节预算触发的。一个星芒面字符是一个字符，但占 CPython `str` 存储的四个字节以及四个 UTF-8 字节，且最重的路径峰值时有三份这样的副本同时存活：一次 `sys.stdout.write(line + "\n")` 会持有调用方的 `text` 实参（在整个 `write` 调用期间存活，约 4 倍）、交给 `LogBuffer.push` 的行切片（约 4 倍）、以及 `_push_locked` 为计费和发送而取的 `text.encode("utf-8")` 副本（约 4 倍）——峰值约为预算的 12 倍。结算期的 `flush_line` 路径只持有两份（它的 `"".join(...)` 与那份 encode 副本——它在 push 之前先丢弃 pending 分块），因此换行路径才是起约束作用的最坏情况。当一项预算逼近 `addressSpaceMb` 时，一次合法的、接近预算的输出会在那次构建加编码期间突破地址空间，并作为 `worker-exit`（日志）而不是截断而终止，或作为 `output-limit`（值）而失败。在运行时对每次子进程写入按地址空间计量是错误的修复：热路径上一次精确的序列化开销检查，要么是一次完整的 `encode`（正是要避免的那次分配），要么是一个逐字符的 Python 循环（它会烧掉 CPU 预算——一次 10 MB 的合法写入会在 `cpuSeconds: 1` 之下触发 SIGXCPU）。两者都是拿一种资源界限换另一种。取而代之，[`src/index.ts`](../../../../packages/code-runtime/code-runtime-python/src/index.ts) 在加载期（LOAD）拒绝这个不兼容的组合：每项预算乘以 `OUTPUT_BUDGET_WORST_CASE_ADDRESS_SPACE_MULTIPLE`（十二——换行路径三份同时存在的约 4 倍副本）必须放得进为解释器自身占用预留一份固定的 `INTERPRETER_BASELINE_BYTES` 之后剩下的地址空间，并用一个 `>=`，使得一项其最坏情况峰值恰好等于那片余量的预算也会被拒绝（该峰值加上预留的基线正好是整个地址空间，即 `RLIMIT_AS` 边界）。`flush_line` 也被改为在 push 之前先丢弃 pending 分块，与换行路径的 join-清空-push 顺序一致，使它至多只持有 join 及其 encode 副本，而非三份副本。该基线是与倍数分开（SEPARATELY）预留的，因为它是一项固定开销，而非随预算伸缩的开销：把它折进倍数会让一项恰好为 `addressSpaceMb / 12` 大小的预算被放行，而其峰值加上解释器仍会越界。`maxLogBytes` 和 `maxValueBytes` 都被对称地门控；值路径的构建加编码是同一形态。该检查在每个平台上都运行，而不仅在强制 `RLIMIT_AS` 的平台上：这种不兼容是那些配置值的属性，因此一个 Linux 部署无论由哪个宿主组装配置都会 OOM，而一致的加载期拒绝正是 fail-loud 契约（Darwin 仅跳过运行时的 `setrlimit`）。这在配置 seam 处消除了这一类问题，而不是给写入路径打补丁，因此 `_LogStream` 保留它原有的按字符计数的缓冲（一个对序列化开销有效的下界，一旦预算放进地址空间就是内存安全的）。值路径在第二处施加同样的纪律：`_check_done_value`（字节计量器）与 `_encode_json_plain`（帧编码器）都以 O(DEPTH) 而非 O(width) 遍历。每个容器只压入一个游标帧、逐个拉取子元素，而不是每个子元素一个遍历元组或栈条目——一个扁平的 `[0] * 6_000_000` 序列化后约 12 MB，但逐元素遍历会分配约 400 MB 的簿记（约为序列化尺寸的 28 倍，远超门预留的 12 倍），于是一个被计量器放行的值可能因遍历自身的帧而 OOM。改用游标后，唯一与宽度成正比的分配就是计量器已界定的输出字符串。 +子进程（[`py/bootstrap.py`](../../../../packages/experimental/code-runtime-python/py/bootstrap.py)）在 `RLIMIT_AS` 之下构建、计费并分帧一条 `maxLogBytes` 的日志条目或一个 `maxValueBytes` 的完成值，而两个账本都是按字符计数、对照一个序列化字节预算触发的。一个星芒面字符是一个字符，但占 CPython `str` 存储的四个字节以及四个 UTF-8 字节，且最重的路径峰值时有三份这样的副本同时存活：一次 `sys.stdout.write(line + "\n")` 会持有调用方的 `text` 实参（在整个 `write` 调用期间存活，约 4 倍）、交给 `LogBuffer.push` 的行切片（约 4 倍）、以及 `_push_locked` 为计费和发送而取的 `text.encode("utf-8")` 副本（约 4 倍）——峰值约为预算的 12 倍。结算期的 `flush_line` 路径只持有两份（它的 `"".join(...)` 与那份 encode 副本——它在 push 之前先丢弃 pending 分块），因此换行路径才是起约束作用的最坏情况。当一项预算逼近 `addressSpaceMb` 时，一次合法的、接近预算的输出会在那次构建加编码期间突破地址空间，并作为 `worker-exit`（日志）而不是截断而终止，或作为 `output-limit`（值）而失败。在运行时对每次子进程写入按地址空间计量是错误的修复：热路径上一次精确的序列化开销检查，要么是一次完整的 `encode`（正是要避免的那次分配），要么是一个逐字符的 Python 循环（它会烧掉 CPU 预算——一次 10 MB 的合法写入会在 `cpuSeconds: 1` 之下触发 SIGXCPU）。两者都是拿一种资源界限换另一种。取而代之，[`src/index.ts`](../../../../packages/experimental/code-runtime-python/src/index.ts) 在加载期（LOAD）拒绝这个不兼容的组合：每项预算乘以 `OUTPUT_BUDGET_WORST_CASE_ADDRESS_SPACE_MULTIPLE`（十二——换行路径三份同时存在的约 4 倍副本）必须放得进为解释器自身占用预留一份固定的 `INTERPRETER_BASELINE_BYTES` 之后剩下的地址空间，并用一个 `>=`，使得一项其最坏情况峰值恰好等于那片余量的预算也会被拒绝（该峰值加上预留的基线正好是整个地址空间，即 `RLIMIT_AS` 边界）。`flush_line` 也被改为在 push 之前先丢弃 pending 分块，与换行路径的 join-清空-push 顺序一致，使它至多只持有 join 及其 encode 副本，而非三份副本。该基线是与倍数分开（SEPARATELY）预留的，因为它是一项固定开销，而非随预算伸缩的开销：把它折进倍数会让一项恰好为 `addressSpaceMb / 12` 大小的预算被放行，而其峰值加上解释器仍会越界。`maxLogBytes` 和 `maxValueBytes` 都被对称地门控；值路径的构建加编码是同一形态。该检查在每个平台上都运行，而不仅在强制 `RLIMIT_AS` 的平台上：这种不兼容是那些配置值的属性，因此一个 Linux 部署无论由哪个宿主组装配置都会 OOM，而一致的加载期拒绝正是 fail-loud 契约（Darwin 仅跳过运行时的 `setrlimit`）。这在配置 seam 处消除了这一类问题，而不是给写入路径打补丁，因此 `_LogStream` 保留它原有的按字符计数的缓冲（一个对序列化开销有效的下界，一旦预算放进地址空间就是内存安全的）。值路径在第二处施加同样的纪律：`_check_done_value`（字节计量器）与 `_encode_json_plain`（帧编码器）都以 O(DEPTH) 而非 O(width) 遍历。每个容器只压入一个游标帧、逐个拉取子元素，而不是每个子元素一个遍历元组或栈条目——一个扁平的 `[0] * 6_000_000` 序列化后约 12 MB，但逐元素遍历会分配约 400 MB 的簿记（约为序列化尺寸的 28 倍，远超门预留的 12 倍），于是一个被计量器放行的值可能因遍历自身的帧而 OOM。改用游标后，唯一与宽度成正比的分配就是计量器已界定的输出字符串。 宿主门控是对照配置的（CONFIGURED）`addressSpaceMb` 校验的，但一个启动环境可能继承一个更严格的（STRICTER）`RLIMIT_AS`（一个低于 `addressSpaceMb` 的 `ulimit -v` 包装层），而 bootstrap 的 `_clamped` 会正确地把有效（EFFECTIVE）限制降到该值——从而让这些预算是按一个子进程永远得不到的上限来定尺寸的。因此 `bootstrap.py` 在应用该有效被夹紧的软限制之后，会对照它重新检查两项预算，镜像宿主门控的倍数与基线，并在引导期抛出（被 setrlimit 阶段的处理器捕获，并作为 `exception` 上报——与任何其他资源限制应用失败同属一类），而不是任由一次接近预算的输出在运行途中 OOM。这两个子进程侧常量与宿主侧的保持一致，靠的是共享的推理，而不是一个 wire 字段。 @@ -82,13 +82,13 @@ unknown-binding 回复用 `JSON.stringify` 对完整的限幅 target（`global` ### 完成值与错误在其校验点处预编码 -在 [`py/bootstrap.py`](../../../../packages/code-runtime/code-runtime-python/py/bootstrap.py) 中，`_done_with_value` 现在会在成功路径上把整个终止帧作为一个已预编码的 JSON 字符串返回：被准入的值在这里、在 `_run` 的 `try` 之内的校验点处恰好序列化一次，即 `'{"type": "done", "value": ' + _encode_json_plain(value) + "}"`。程序在返回之后仍可能从 daemon 线程或信号处理器继续变异它返回的 list／dict，因此在一个更晚的点上做第二次遍历会构成一次 TOCTOU——如果一次变异让一个并发变异的后续编码在结算处理器之外抛出，就会把一次已结算的运行在宿主侧降级成 `worker-exit`。在这里、在包裹该调用的 `try` 之内恰好序列化一次，就关上了这个窗口：如果一次并发变异导致编码抛出，异常处理器会把它如实分类为 `exception`；一旦字符串产生出来，该帧就会被逐字写走、不再触碰任何活对象。`_run` 在程序运行前把 `_done_with_value` 的入口名绑成局部（`done_with_value_bound`），而 `_done_with_value` 自身把 `_check_done_value` 与 `_encode_json_plain` 绑定为 def 期默认参数——因此模型执行后对入口名或这两个名字的 `__main__` 重绑无法把一个合法成功改写为 `exception`。日志账本（宿主 `logBudget` 与子进程 `_remaining`）从预算低 1 字节起算，预留序列化外层数组的外壳（两条括号与 n-1 个逗号，覆盖 n 条目的分隔符），因此恰好耗尽账本的结果序列化后仍在配置上限之内。 一旦账本已截断，宿主会整体清空两条 stray 管道的缓冲输出（之后的每个字节都会被 `admit` 变成 no-op，保留它只会把宿主内存花在永远无法准入的输出上）；子进程以 `-u` 运行，使 `sys.__stdout__`/`sys.__stderr__` 的写入对 stray 捕获立即可见，而结算 flush 仍在 done 帧前排空原始 std 流（防御 `sys.__stdout__ = boom` 重绑后残留的缓冲包装）。构造器拒绝低于 64 的 `maxLogBytes`（能为截断标记自身序列化形式留出一字节余量的最小预算）；`maxValueBytes` 只保留正整数要求，因为完成值可以只有一字节、且 done 帧外壳是 seam 协议成本。标记仍是 envelope，因此带已放行条目的截断运行序列化后至多为 `maxLogBytes + marker + envelope`（已记录在包 README）。但编码器到达的一个传递依赖（例如 `_dump_scalar`/`_dump_string`/`json`/`io`——非穷举清单）重绑仍可让编码抛出、把成功降级为 `exception`，这在包 README 中被登记为已接受残余。 +在 [`py/bootstrap.py`](../../../../packages/experimental/code-runtime-python/py/bootstrap.py) 中，`_done_with_value` 现在会在成功路径上把整个终止帧作为一个已预编码的 JSON 字符串返回：被准入的值在这里、在 `_run` 的 `try` 之内的校验点处恰好序列化一次，即 `'{"type": "done", "value": ' + _encode_json_plain(value) + "}"`。程序在返回之后仍可能从 daemon 线程或信号处理器继续变异它返回的 list／dict，因此在一个更晚的点上做第二次遍历会构成一次 TOCTOU——如果一次变异让一个并发变异的后续编码在结算处理器之外抛出，就会把一次已结算的运行在宿主侧降级成 `worker-exit`。在这里、在包裹该调用的 `try` 之内恰好序列化一次，就关上了这个窗口：如果一次并发变异导致编码抛出，异常处理器会把它如实分类为 `exception`；一旦字符串产生出来，该帧就会被逐字写走、不再触碰任何活对象。`_run` 在程序运行前把 `_done_with_value` 的入口名绑成局部（`done_with_value_bound`），而 `_done_with_value` 自身把 `_check_done_value` 与 `_encode_json_plain` 绑定为 def 期默认参数——因此模型执行后对入口名或这两个名字的 `__main__` 重绑无法把一个合法成功改写为 `exception`。日志账本（宿主 `logBudget` 与子进程 `_remaining`）从预算低 1 字节起算，预留序列化外层数组的外壳（两条括号与 n-1 个逗号，覆盖 n 条目的分隔符），因此恰好耗尽账本的结果序列化后仍在配置上限之内。 一旦账本已截断，宿主会整体清空两条 stray 管道的缓冲输出（之后的每个字节都会被 `admit` 变成 no-op，保留它只会把宿主内存花在永远无法准入的输出上）；子进程以 `-u` 运行，使 `sys.__stdout__`/`sys.__stderr__` 的写入对 stray 捕获立即可见，而结算 flush 仍在 done 帧前排空原始 std 流（防御 `sys.__stdout__ = boom` 重绑后残留的缓冲包装）。构造器拒绝低于 64 的 `maxLogBytes`（能为截断标记自身序列化形式留出一字节余量的最小预算）；`maxValueBytes` 只保留正整数要求，因为完成值可以只有一字节、且 done 帧外壳是 seam 协议成本。标记仍是 envelope，因此带已放行条目的截断运行序列化后至多为 `maxLogBytes + marker + envelope`（已记录在包 README）。但编码器到达的一个传递依赖（例如 `_dump_scalar`/`_dump_string`/`json`/`io`——非穷举清单）重绑仍可让编码抛出、把成功降级为 `exception`，这在包 README 中被登记为已接受残余。 `send_done`（`_run` 内部的一个局部函数）通过绑定的 `channel.write_encoded` 写出已预编码的字符串，并在写之前用绑定的 `_encode_json_plain` 编码一个 dict 错误帧——它绝不经 `channel.send_sync`，因为后者的函数体会在调用时刻重新解析 `self.write_encoded` 和模块级的 `_encode_json_plain`。`_encode_json_plain` 与 `channel.write_encoded` 在程序运行前就被绑定进局部变量，理由与 `flush_out`／`flush_err`／`safe_model_traceback` 被绑定相同：程序以 `__main__` 运行，因此 `import __main__; __main__.ProtocolChannel.send_sync = boom` 或 `__main__._encode_json_plain = boom` 本会在调用时刻把发送／编码重新解析成被替换的可调用对象，当该替换抛出时跳过 `done` 帧、把已结算的结论降级成宿主侧的 `worker-exit`。 ### 预算触发的冲刷会扣留下一个未完成的多字节尾序列 -同样在 [`src/index.ts`](../../../../packages/code-runtime/code-runtime-python/src/index.ts) 中，`flushStray(stray, retainPartialTail)` 在预算触发的冲刷（`captureStray` 中的合并成本阈值）上会把一个未完成的多字节尾部从解码中扣留：当残余以部分 UTF-8 前导序列结束（`stray.utf8.expected > 0`）时，前导字节加上迄今已消耗的续字节（≤3 字节）会从该帧中分离出来作为新的残余，只有完整的前缀被准入并解码。当整个残余就是单个未完序列时什么都不准入，因此一个合法、未完成的字符绝不会在一个被放行、未截断的条目里被渲染成 U+FFFD，也不会推进一条虚假的空条目。被扣留的尾部会从一个全新的 `stray.utf8` 状态重新累计——若用冲刷后 `expected > 0` 的状态来计量它，会把那些被承载下来的前导字节当作非法续字节计费——从而下一个分块能正确地继续推进，且该管道在保留的尾部之上重建其成本／UTF-8 状态。`end`／`closeDeadline` 路径传入 `false`，原样解码整个残余，因为在那里一个不完整的尾序列是真实的坏输入，U+FFFD 才是如实呈现。 +同样在 [`src/index.ts`](../../../../packages/experimental/code-runtime-python/src/index.ts) 中，`flushStray(stray, retainPartialTail)` 在预算触发的冲刷（`captureStray` 中的合并成本阈值）上会把一个未完成的多字节尾部从解码中扣留：当残余以部分 UTF-8 前导序列结束（`stray.utf8.expected > 0`）时，前导字节加上迄今已消耗的续字节（≤3 字节）会从该帧中分离出来作为新的残余，只有完整的前缀被准入并解码。当整个残余就是单个未完序列时什么都不准入，因此一个合法、未完成的字符绝不会在一个被放行、未截断的条目里被渲染成 U+FFFD，也不会推进一条虚假的空条目。被扣留的尾部会从一个全新的 `stray.utf8` 状态重新累计——若用冲刷后 `expected > 0` 的状态来计量它，会把那些被承载下来的前导字节当作非法续字节计费——从而下一个分块能正确地继续推进，且该管道在保留的尾部之上重建其成本／UTF-8 状态。`end`／`closeDeadline` 路径传入 `false`，原样解码整个残余，因为在那里一个不完整的尾序列是真实的坏输入，U+FFFD 才是如实呈现。 ### 迟到的 binding 拒绝在格式化错误之前就返回 @@ -96,7 +96,7 @@ unknown-binding 回复用 `JSON.stringify` 对完整的限幅 target（`global` ### 无换行滴灌会封存其分片；CPU 软限制保持在硬限制之下；done 帧回退到固定字面量；回复队列清空已消费槽位 -在 [`py/bootstrap.py`](../../../../packages/code-runtime/code-runtime-python/py/bootstrap.py) 中，`_LogStream` 现在会在待处理分片列表越过一个上限时封存它：无换行、每次 `write` 一个字符的滴灌会每次调用累积一个 list 槽位（以及一个 str 对象），在一个大的 `maxLogBytes` 下，25 M 次单字符洪泛会在字节预算达到之前，于其自身记账上 OOM（加上 `_push_bounded_prefix` 随后构造的同规模列表）。越过 `_PENDING_MAX_CHUNKS` 后，当前分片被 join 成一个块并移入 `_pending_blocks` 列表（字符数不变），把存活的碎片数量限制在宿主侧 `captureStray` 封存所做的同等水平；该 join 只针对 ≤cap 的当前分片，从不针对整个累积缓冲，因此大的滴灌保持 O(B)，而不是以 O(B²/cap) 次反复复制不断增长的块。宿主侧 open hold 镜像同样的封存：预算内的单字符 open 洪泛（`print('x', end='', flush=True)` 循环是诚实子进程可达路径）否则会为每帧累积一个片段数组槽位加字符串对象头——约 30× 字节计数看不到的开销，在 `maxLogBytes` 装载上限附近最高约 2 GB 宿主辅助堆。越过 `MAX_PENDING_CHUNKS` 后持有的片段并入 `openSealed`；闭合帧合并、`truncateLogs` 与 `finish` 残段都读取 sealed 加当前片段并清空封存。 +在 [`py/bootstrap.py`](../../../../packages/experimental/code-runtime-python/py/bootstrap.py) 中，`_LogStream` 现在会在待处理分片列表越过一个上限时封存它：无换行、每次 `write` 一个字符的滴灌会每次调用累积一个 list 槽位（以及一个 str 对象），在一个大的 `maxLogBytes` 下，25 M 次单字符洪泛会在字节预算达到之前，于其自身记账上 OOM（加上 `_push_bounded_prefix` 随后构造的同规模列表）。越过 `_PENDING_MAX_CHUNKS` 后，当前分片被 join 成一个块并移入 `_pending_blocks` 列表（字符数不变），把存活的碎片数量限制在宿主侧 `captureStray` 封存所做的同等水平；该 join 只针对 ≤cap 的当前分片，从不针对整个累积缓冲，因此大的滴灌保持 O(B)，而不是以 O(B²/cap) 次反复复制不断增长的块。宿主侧 open hold 镜像同样的封存：预算内的单字符 open 洪泛（`print('x', end='', flush=True)` 循环是诚实子进程可达路径）否则会为每帧累积一个片段数组槽位加字符串对象头——约 30× 字节计数看不到的开销，在 `maxLogBytes` 装载上限附近最高约 2 GB 宿主辅助堆。越过 `MAX_PENDING_CHUNKS` 后持有的片段并入 `openSealed`；闭合帧合并、`truncateLogs` 与 `finish` 残段都读取 sealed 加当前片段并清空封存。 `_clamped` 还会把钳制出的、与硬限制相等的 RLIMIT_CPU 软限制降低一个单位（当硬限制至少为 2 时）。`ulimit -t N` 会同时设置两者，而当 soft == hard 时，内核会在同一 tick 检查硬限制并直接 SIGKILL 一个忙循环，因此 SIGXCPU 永远不会送达——而宿主只在 `signal === 'SIGXCPU'` 时把 CPU 超限分类为超时，所以一次确定的预算耗尽会被误报为 `worker-exit`。把软限制降低一个单位给 SIGXCPU 一个触发窗口，因此超限会被报告为超时。这仅限定于 RLIMIT_CPU（在 RLIMIT_AS 上的一字节软差异只会让子进程实际应用的限制与宿主预算门失步，没有需要保留的信号）。`hard >= 2` 守卫留下了 `hard == 1` 盲区——一个 1 秒的双限制无法把软限制降到 0，因此那里的确定超限仍被报告为 `worker-exit`。 diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 546e29133c..52c36fb647 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/config-catalog.md -config-catalog.md: f49a76e01e2fceac0e306eeb1e714024d4006ff0 -config-catalog.zh.md: 357f32e2a5fb4dde4555f6b012b902a7ffd902d5 +config-catalog.md: 31a3d6370111b3b992a8b212bb54ea5ee694572e +config-catalog.zh.md: 66dfef15b30fdb3f62a6e41eabee34dddf8f1fa3 diff --git a/docs/config-catalog.md b/docs/config-catalog.md index f49a76e01e..31a3d63701 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -356,65 +356,6 @@ export interface Config { Source: [`packages/client/hmr/src/index.ts:31`](../packages/client/hmr/src/index.ts) - - -## `@deepseek-ai/dsh-code-runtime-python` - -```ts config-catalog -/** Plugin config: every cap, changeable from `cordis.yml` (no hardcoded tunables). */ -export interface Config { - /** - * RLIMIT_CPU in whole seconds (a positive integer — `setrlimit` in the child - * rejects a float). The child sets the soft limit to `cpuSeconds` and the - * hard limit to `cpuSeconds + 1`: the kernel delivers SIGXCPU at the soft - * limit, which the host classifies as a `timeout`; the +1s hard limit is a - * SIGKILL backstop for a program that traps SIGXCPU. Granularity is seconds — - * a coarser counterpart to the worker backend's millisecond `computeMs`. - */ - cpuSeconds?: number - /** Wall-clock ceiling in milliseconds; backstops CPU time for programs awaiting a promise nobody resolves. */ - maxWallMs?: number - /** - * RLIMIT_AS in mebibytes; caps address space so a runaway allocation fails - * cleanly. Not applied on Darwin, where the dyld shared cache mapped into - * every process at exec exceeds any practical cap and the kernel rejects - * the call; `cpuSeconds` and `maxWallMs` still bound the run there. Bounds - * `maxLogBytes`/`maxValueBytes` at load on EVERY platform (this static check - * runs on Darwin too, where only the runtime `setrlimit` is skipped): each - * budget times a worst-case Unicode expansion must fit this byte count minus a - * fixed interpreter baseline, so a near-budget output cannot breach the address - * space during the child's build-and-encode. - */ - addressSpaceMb?: number - /** - * Shared byte budget for captured log text (host-side ledger). Bounded at load - * against `addressSpaceMb`: the child builds and encodes a near-budget entry - * under RLIMIT_AS with several copies live at once, so this cap times the - * worst-case Unicode expansion must fit the address space left after the - * interpreter baseline (see `addressSpaceMb`) — a load-time rejection, not a - * runtime clamp. - */ - maxLogBytes?: number - /** - * Byte cap for the completion value. Bounded at load against `addressSpaceMb` - * the same way `maxLogBytes` is: the child builds and encodes a near-budget - * value under RLIMIT_AS with several copies live at once, so this cap times the - * worst-case Unicode expansion must fit the address space left after the - * interpreter baseline. - */ - maxValueBytes?: number - /** SIGTERM→SIGKILL grace period on kill, matching bash-local's default. */ - graceMs?: number - /** - * Absolute path or basename of the CPython interpreter to spawn. Resolved - * through `PATH` when a basename is given. - */ - pythonBin?: string -} -``` - -Source: [`packages/code-runtime/code-runtime-python/src/index.ts:44`](../packages/code-runtime/code-runtime-python/src/index.ts) - ## `@deepseek-ai/dsh-code-runtime-worker-thread` @@ -596,6 +537,65 @@ export interface Config { Source: [`packages/experimental/agent-team/src/types.ts:131`](../packages/experimental/agent-team/src/types.ts) + + +## `@deepseek-ai/dsh-experimental-code-runtime-python` + +```ts config-catalog +/** Plugin config: every cap, changeable from `cordis.yml` (no hardcoded tunables). */ +export interface Config { + /** + * RLIMIT_CPU in whole seconds (a positive integer — `setrlimit` in the child + * rejects a float). The child sets the soft limit to `cpuSeconds` and the + * hard limit to `cpuSeconds + 1`: the kernel delivers SIGXCPU at the soft + * limit, which the host classifies as a `timeout`; the +1s hard limit is a + * SIGKILL backstop for a program that traps SIGXCPU. Granularity is seconds — + * a coarser counterpart to the worker backend's millisecond `computeMs`. + */ + cpuSeconds?: number + /** Wall-clock ceiling in milliseconds; backstops CPU time for programs awaiting a promise nobody resolves. */ + maxWallMs?: number + /** + * RLIMIT_AS in mebibytes; caps address space so a runaway allocation fails + * cleanly. Not applied on Darwin, where the dyld shared cache mapped into + * every process at exec exceeds any practical cap and the kernel rejects + * the call; `cpuSeconds` and `maxWallMs` still bound the run there. Bounds + * `maxLogBytes`/`maxValueBytes` at load on EVERY platform (this static check + * runs on Darwin too, where only the runtime `setrlimit` is skipped): each + * budget times a worst-case Unicode expansion must fit this byte count minus a + * fixed interpreter baseline, so a near-budget output cannot breach the address + * space during the child's build-and-encode. + */ + addressSpaceMb?: number + /** + * Shared byte budget for captured log text (host-side ledger). Bounded at load + * against `addressSpaceMb`: the child builds and encodes a near-budget entry + * under RLIMIT_AS with several copies live at once, so this cap times the + * worst-case Unicode expansion must fit the address space left after the + * interpreter baseline (see `addressSpaceMb`) — a load-time rejection, not a + * runtime clamp. + */ + maxLogBytes?: number + /** + * Byte cap for the completion value. Bounded at load against `addressSpaceMb` + * the same way `maxLogBytes` is: the child builds and encodes a near-budget + * value under RLIMIT_AS with several copies live at once, so this cap times the + * worst-case Unicode expansion must fit the address space left after the + * interpreter baseline. + */ + maxValueBytes?: number + /** SIGTERM→SIGKILL grace period on kill, matching bash-local's default. */ + graceMs?: number + /** + * Absolute path or basename of the CPython interpreter to spawn. Resolved + * through `PATH` when a basename is given. + */ + pythonBin?: string +} +``` + +Source: [`packages/experimental/code-runtime-python/src/index.ts:44`](../packages/experimental/code-runtime-python/src/index.ts) + ## `@deepseek-ai/dsh-experimental-inspector` diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index 357f32e2a5..66dfef15b3 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -358,9 +358,9 @@ export interface Config { 来源：[`packages/client/hmr/src/index.ts:31`](../packages/client/hmr/src/index.ts) - + -## `@deepseek-ai/dsh-code-runtime-python` +## `@deepseek-ai/dsh-experimental-code-runtime-python` ```ts config-catalog /** Plugin config: every cap, changeable from `cordis.yml` (no hardcoded tunables). */ @@ -415,7 +415,7 @@ export interface Config { } ``` -来源：[`packages/code-runtime/code-runtime-python/src/index.ts:44`](../packages/code-runtime/code-runtime-python/src/index.ts) +来源：[`packages/experimental/code-runtime-python/src/index.ts:44`](../packages/experimental/code-runtime-python/src/index.ts) diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index 79103c7341..16c4e94879 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/module-graph.md -module-graph.md: 41289fce09b82cdf81aa3c3450ee367be15a10c1 -module-graph.zh.md: 5f8797315daaac35411f41dfcf244c6689540512 +module-graph.md: 6f576cbfe72b2b7895d2e350f8f80d51048cd6df +module-graph.zh.md: 77094944c733ea07b178d6600d185f90ba10d2c8 diff --git a/docs/module-graph.md b/docs/module-graph.md index 41289fce09..6f576cbfe7 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -178,7 +178,6 @@ flowchart TD end subgraph group_code_runtime["packages/code-runtime"] pkg_code_runtime["code-runtime"] - pkg_code_runtime_python["code-runtime-python"] pkg_code_runtime_worker_thread["code-runtime-worker-thread"] end subgraph group_compaction["packages/compaction"] @@ -210,6 +209,7 @@ flowchart TD pkg_experimental_agent_team_profile["experimental-agent-team-profile"] pkg_experimental_agent_team_web_profile["experimental-agent-team-web-profile"] pkg_experimental_client_ui_agent_team["experimental-client-ui-agent-team"] + pkg_experimental_code_runtime_python["experimental-code-runtime-python"] pkg_experimental_inspector["experimental-inspector"] pkg_experimental_tool_agent_team["experimental-tool-agent-team"] pkg_experimental_webworker_packer["experimental-webworker-packer"] @@ -471,14 +471,14 @@ flowchart TD pkg_app_boot --> pkg_invariants pkg_app_boot --> pkg_launch_environment pkg_app_boot --> pkg_system_prompt - pkg_code_runtime_python --> pkg_code_runtime - pkg_code_runtime_python --> pkg_invariants - pkg_code_runtime_python --> pkg_session - pkg_code_runtime_python --> pkg_timeout pkg_code_runtime_worker_thread --> pkg_code_runtime pkg_code_runtime_worker_thread --> pkg_invariants pkg_code_runtime_worker_thread --> pkg_session pkg_code_runtime_worker_thread --> pkg_timeout + pkg_experimental_code_runtime_python --> pkg_code_runtime + pkg_experimental_code_runtime_python --> pkg_invariants + pkg_experimental_code_runtime_python --> pkg_session + pkg_experimental_code_runtime_python --> pkg_timeout pkg_persona --> pkg_invariants pkg_persona --> pkg_system_prompt pkg_sandbox --> pkg_invariants @@ -1417,8 +1417,8 @@ flowchart TD | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`attachment-local`](../packages/attachment/attachment-local) | `attachment` | [`attachment`](../packages/attachment/attachment), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`app-boot`](../packages/boot/app-boot) | `boot` | [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`system-prompt`](../packages/core/system-prompt) | -| [`code-runtime-python`](../packages/code-runtime/code-runtime-python) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | | [`code-runtime-worker-thread`](../packages/code-runtime/code-runtime-worker-thread) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | +| [`experimental-code-runtime-python`](../packages/experimental/code-runtime-python) | `experimental` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | | [`persona`](../packages/preset/persona) | `preset` | [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt) | | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`session-log-deepseek`](../packages/session/session-log-deepseek) | `session` | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index 5f8797315d..77094944c7 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -180,7 +180,6 @@ flowchart TD end subgraph group_code_runtime["packages/code-runtime"] pkg_code_runtime["code-runtime"] - pkg_code_runtime_python["code-runtime-python"] pkg_code_runtime_worker_thread["code-runtime-worker-thread"] end subgraph group_compaction["packages/compaction"] @@ -212,6 +211,7 @@ flowchart TD pkg_experimental_agent_team_profile["experimental-agent-team-profile"] pkg_experimental_agent_team_web_profile["experimental-agent-team-web-profile"] pkg_experimental_client_ui_agent_team["experimental-client-ui-agent-team"] + pkg_experimental_code_runtime_python["experimental-code-runtime-python"] pkg_experimental_inspector["experimental-inspector"] pkg_experimental_tool_agent_team["experimental-tool-agent-team"] pkg_experimental_webworker_packer["experimental-webworker-packer"] @@ -473,14 +473,14 @@ flowchart TD pkg_app_boot --> pkg_invariants pkg_app_boot --> pkg_launch_environment pkg_app_boot --> pkg_system_prompt - pkg_code_runtime_python --> pkg_code_runtime - pkg_code_runtime_python --> pkg_invariants - pkg_code_runtime_python --> pkg_session - pkg_code_runtime_python --> pkg_timeout pkg_code_runtime_worker_thread --> pkg_code_runtime pkg_code_runtime_worker_thread --> pkg_invariants pkg_code_runtime_worker_thread --> pkg_session pkg_code_runtime_worker_thread --> pkg_timeout + pkg_experimental_code_runtime_python --> pkg_code_runtime + pkg_experimental_code_runtime_python --> pkg_invariants + pkg_experimental_code_runtime_python --> pkg_session + pkg_experimental_code_runtime_python --> pkg_timeout pkg_persona --> pkg_invariants pkg_persona --> pkg_system_prompt pkg_sandbox --> pkg_invariants @@ -1419,8 +1419,8 @@ flowchart TD | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`attachment-local`](../packages/attachment/attachment-local) | `attachment` | [`attachment`](../packages/attachment/attachment), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`app-boot`](../packages/boot/app-boot) | `boot` | [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`system-prompt`](../packages/core/system-prompt) | -| [`code-runtime-python`](../packages/code-runtime/code-runtime-python) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | | [`code-runtime-worker-thread`](../packages/code-runtime/code-runtime-worker-thread) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | +| [`experimental-code-runtime-python`](../packages/experimental/code-runtime-python) | `experimental` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | | [`persona`](../packages/preset/persona) | `preset` | [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt) | | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`session-log-deepseek`](../packages/session/session-log-deepseek) | `session` | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | diff --git a/packages/code-runtime/README.i18n.yaml b/packages/code-runtime/README.i18n.yaml index b3d5e56e92..996968bad1 100644 --- a/packages/code-runtime/README.i18n.yaml +++ b/packages/code-runtime/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/code-runtime/README.md -README.md: 165727f8b57d5392cca0fc8bc028f6b39efe35b2 -README.zh.md: c3c2cf04dac91d40d5a748ad58a359fa3b60e27c +README.md: 7319f9d2d44554312b71a6eabf4e3822bae3ec42 +README.zh.md: 9bfc7cfe5f660faaa475dc62588ad1a1dc6cd9da diff --git a/packages/code-runtime/README.md b/packages/code-runtime/README.md index 165727f8b5..7319f9d2d4 100644 --- a/packages/code-runtime/README.md +++ b/packages/code-runtime/README.md @@ -28,7 +28,7 @@ These three packages together provide program execution; each README describes w |---|---|---| | [`code-runtime/`](code-runtime/README.md) | Defines what a code runtime does: run one program against host-provided bindings and report what it printed and returned | `ctx.codeRuntime` | | [`code-runtime-worker-thread/`](code-runtime-worker-thread/README.md) | Executes TypeScript programs, each in a fresh Node worker thread | registers `ctx.codeRuntime` | -| [`code-runtime-python/`](code-runtime-python/README.md) | Owns the fd-3 wire protocol between a Node host and a CPython subprocess, the Python backend's protocol layer | — | +| [`code-runtime-python/`](../experimental/code-runtime-python/README.md) | Owns the fd-3 wire protocol between a Node host and a CPython subprocess, the Python backend's protocol layer | — | ----- diff --git a/packages/code-runtime/README.zh.md b/packages/code-runtime/README.zh.md index c3c2cf04da..9bfc7cfe5f 100644 --- a/packages/code-runtime/README.zh.md +++ b/packages/code-runtime/README.zh.md @@ -28,7 +28,7 @@ kind: "package-group" |---|---|---| | [`code-runtime/`](code-runtime/README.zh.md) | 定义代码运行时做什么：针对宿主提供的绑定运行一个程序，并报告其打印和返回的内容 | `ctx.codeRuntime` | | [`code-runtime-worker-thread/`](code-runtime-worker-thread/README.zh.md) | 在全新的 Node Worker 线程中执行 TypeScript 程序 | 注册 `ctx.codeRuntime` | -| [`code-runtime-python/`](code-runtime-python/README.zh.md) | 持有 Node host 与 CPython 子进程之间的 fd-3 协议格式，即 Python 后端的协议层 | — | +| [`code-runtime-python/`](../experimental/code-runtime-python/README.zh.md) | 持有 Node host 与 CPython 子进程之间的 fd-3 协议格式，即 Python 后端的协议层 | — | ----- diff --git a/packages/code-runtime/code-runtime/README.i18n.yaml b/packages/code-runtime/code-runtime/README.i18n.yaml index f3b029d313..9f872c5e7c 100644 --- a/packages/code-runtime/code-runtime/README.i18n.yaml +++ b/packages/code-runtime/code-runtime/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime/README.md -README.md: 4e53febeb3f3db967420e2eec363e83132669dbc -README.zh.md: fc7127e2d03d88baacde725d7cbaa1f05327a1f7 +README.md: b33fec41abe516a047ea52112888bc165a63dffa +README.zh.md: ac548f8318fb82c5e68558d1e638193738125d46 diff --git a/packages/code-runtime/code-runtime/README.md b/packages/code-runtime/code-runtime/README.md index 4e53febeb3..b33fec41ab 100644 --- a/packages/code-runtime/code-runtime/README.md +++ b/packages/code-runtime/code-runtime/README.md @@ -41,7 +41,7 @@ const result = await ctx.codeRuntime.run({ ### Choose a backend -Backends declare two descriptors you can rely on: `language` — what the program must be written in, with `'typescript'` and `'python'` as the well-known values and both backed by published providers — and `isolation` — the execution substrate (`'worker-thread'`, `'process'`, `'container'`), a label for deployments and diagnostics, not a security claim. [`dsh-code-runtime-worker-thread`](../code-runtime-worker-thread/README.md) executes TypeScript in a fresh Node worker thread; [`dsh-code-runtime-python`](../code-runtime-python/README.md) executes Python in a fresh CPython subprocess. +Backends declare two descriptors you can rely on: `language` — what the program must be written in, with `'typescript'` and `'python'` as the well-known values — and `isolation` — the execution substrate (`'worker-thread'`, `'process'`, `'container'`), a label for deployments and diagnostics, not a security claim. [`dsh-code-runtime-worker-thread`](../code-runtime-worker-thread/README.md) executes TypeScript in a fresh Node worker thread; the private [`dsh-experimental-code-runtime-python`](../../experimental/code-runtime-python/README.md) package executes Python in a fresh CPython subprocess for opt-in compositions. ### Name your bindings portably @@ -98,7 +98,7 @@ Read these when the package-level contract is not enough. They move from the PTC - [PTC mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-ptc.md) — how the tool registry consumes `ctx.codeRuntime` and presents `run_code` to the model. - [Worker-thread backend](../code-runtime-worker-thread/README.md) — the shipped TypeScript execution backend. -- [Python backend](../code-runtime-python/README.md) — the CPython subprocess execution provider and its fd-3 protocol. +- [Experimental Python backend](../../experimental/code-runtime-python/README.md) — the private CPython subprocess provider and its fd-3 protocol. - [Code runtime subsystem reference](../../../docs/subsystems/code-runtime.md) — request/result vocabulary, bindings, and the `ctx.codeRuntime` cordis surface. - [Capability seams](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) — the Service Definition / Service Provider / Consumer split. @@ -122,7 +122,7 @@ These limits define what the seam cannot do; they are current package constraint - **`run()` is one-shot** — `logs` arrive only on the resolved `CodeRunResult`; the seam exposes no streaming-log or progress API for a live program's output. - **No state survives between runs** — every request runs against a fresh world; a persistent REPL-style kernel is deferred until a backend brings its own logging story. -- **The worker-thread and Python (process) backends ship; `'container'` does not** — `'container'` is a declared well-known `isolation` value with no implementation; a hard security boundary awaits a container backend. +- **The worker-thread backend ships; the Python process backend is private experimental; `'container'` has no implementation** — a hard security boundary awaits a container backend. - **Intermediate binding values have no byte cap** — implementations remain subject to structured-clone cost and process memory, while a provider or executor may already have imposed its own acquisition bound. diff --git a/packages/code-runtime/code-runtime/README.zh.md b/packages/code-runtime/code-runtime/README.zh.md index fc7127e2d0..ac548f8318 100644 --- a/packages/code-runtime/code-runtime/README.zh.md +++ b/packages/code-runtime/code-runtime/README.zh.md @@ -41,7 +41,7 @@ const result = await ctx.codeRuntime.run({ ### 选择后端 -后端声明两个你可以依赖的描述符：`language`——程序必须使用的源语言，已知值为 `'typescript'` 与 `'python'`，两者都有已发布的提供方——以及 `isolation`——执行基底（`'worker-thread'`、`'process'`、`'container'`），仅供部署与诊断使用，不构成安全声明。[`dsh-code-runtime-worker-thread`](../code-runtime-worker-thread/README.zh.md) 在全新的 Node Worker 线程中执行 TypeScript；[`dsh-code-runtime-python`](../code-runtime-python/README.zh.md) 在全新的 CPython 子进程中执行 Python。 +后端声明两个你可以依赖的描述符：`language`——程序必须使用的源语言，已知值为 `'typescript'` 与 `'python'`——以及 `isolation`——执行基底（`'worker-thread'`、`'process'`、`'container'`），仅供部署与诊断使用，不构成安全声明。[`dsh-code-runtime-worker-thread`](../code-runtime-worker-thread/README.zh.md) 在全新的 Node Worker 线程中执行 TypeScript；私有的 [`dsh-experimental-code-runtime-python`](../../experimental/code-runtime-python/README.zh.md) 包在全新的 CPython 子进程中执行 Python，供选择性组合使用。 ### 可移植地命名绑定 @@ -98,7 +98,7 @@ binding-global 与 error-class 名称是语言可移植的：必须匹配标识 - [PTC mode Agent Note](../../../.agents/notes/implemented/feature/2026-06-15-ptc.zh.md)——工具注册表如何消费 `ctx.codeRuntime` 并把 `run_code` 呈现给模型。 - [Worker 线程后端](../code-runtime-worker-thread/README.zh.md)——已发布的 TypeScript 执行后端。 -- [Python 后端](../code-runtime-python/README.zh.md)——CPython 子进程执行提供方及其 fd-3 协议。 +- [实验性 Python 后端](../../experimental/code-runtime-python/README.zh.md)——私有的 CPython 子进程提供方及其 fd-3 协议。 - [代码运行时子系统参考](../../../docs/subsystems/code-runtime.zh.md)——请求／结果词汇、绑定与 `ctx.codeRuntime` 的 cordis 接口面。 - [能力 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)——Service Definition / Service Provider / Consumer 拆分。 @@ -122,8 +122,8 @@ binding-global 与 error-class 名称是语言可移植的：必须匹配标识 - **`run()` 是一次性的**——`logs` 只有在 `CodeRunResult` resolve 后才能获得；seam 不提供正在运行的程序所产生输出的流式日志或进度接口。 - **运行之间不保留状态**——每次请求都在全新环境中运行；持久 REPL 风格内核在某个后端带来自己的日志方案之前保持延期。 -- **目前提供 worker 线程与 Python（process）后端；`'container'` 没有实现**——`'container'` 是已声明但没有实现的已知 `isolation` 值；强安全边界需要等待容器后端。 -- **中间绑定值没有字节上限**——实现仍受 structured-clone 成本与进程内存约束，而提供方或执行器可能已经应用自己的获取上限。 +- **worker 线程后端已发布；Python process 后端是私有实验包；`'container'` 没有实现**——强安全边界需要等待容器后端。 +- **中间 binding 值没有字节上限**——实现仍受 structured-clone 成本与进程内存约束，而提供方或执行器可能已经应用自己的获取上限。 ### 开发备注 diff --git a/packages/code-runtime/code-runtime-python/README.i18n.yaml b/packages/experimental/code-runtime-python/README.i18n.yaml similarity index 54% rename from packages/code-runtime/code-runtime-python/README.i18n.yaml rename to packages/experimental/code-runtime-python/README.i18n.yaml index b7c7787871..7619df00c2 100644 --- a/packages/code-runtime/code-runtime-python/README.i18n.yaml +++ b/packages/experimental/code-runtime-python/README.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: -# pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime-python/README.md -README.md: 51a45f8effa03ae3aec977329f44c233f060a850 -README.zh.md: 2b710aefba147c566b973572a0b609e0a9d2c9fc +# pnpm run verify-translation-pairing --write packages/experimental/code-runtime-python/README.md +README.md: 2fc78c0a8066886114600e4f3bab6a56521563e5 +README.zh.md: c2ec5ca81e5b8a7ee50658663484981699aa9687 diff --git a/packages/code-runtime/code-runtime-python/README.md b/packages/experimental/code-runtime-python/README.md similarity index 91% rename from packages/code-runtime/code-runtime-python/README.md rename to packages/experimental/code-runtime-python/README.md index 51a45f8eff..2fc78c0a80 100644 --- a/packages/code-runtime/code-runtime-python/README.md +++ b/packages/experimental/code-runtime-python/README.md @@ -3,13 +3,13 @@ description: "CPython-subprocess code runtime: the dsh-code-runtime seam impleme kind: "package-reference" --- -# @deepseek-ai/dsh-code-runtime-python +# @deepseek-ai/dsh-experimental-code-runtime-python English | [中文](README.zh.md) ## Summary -`dsh-code-runtime-python` ships `PythonCodeRuntime`, the CPython-subprocess implementation of the [`dsh-code-runtime`](../code-runtime/README.md) seam: it registers as `codeRuntime` with `language: 'python'` and `isolation: 'process'`, spawning a fresh `python3 -I` child per `run()` and executing the program as an async function body over a versionless JSON-lines protocol on the child's fd 3 (stdout/stderr stay free for the program's own output). The host side (`src/protocol.ts`) treats every inbound frame as hostile and rebuilds it before reading; the Python side (`py/protocol.py`) mirrors the message vocabulary. Containment — not a security boundary, model code has bash-equivalent trust — comes from an empty environment, `RLIMIT_CPU`/`RLIMIT_AS`, a wall-clock ceiling, and `SIGTERM`→grace→`SIGKILL` process-group teardown, with all caps validated at plugin load. +`dsh-experimental-code-runtime-python` ships `PythonCodeRuntime`, the CPython-subprocess implementation of the [`dsh-code-runtime`](../../code-runtime/code-runtime/README.md) seam: it registers as `codeRuntime` with `language: 'python'` and `isolation: 'process'`, spawning a fresh `python3 -I` child per `run()` and executing the program as an async function body over a versionless JSON-lines protocol on the child's fd 3 (stdout/stderr stay free for the program's own output). The host side (`src/protocol.ts`) treats every inbound frame as hostile and rebuilds it before reading; the Python side (`py/protocol.py`) mirrors the message vocabulary. Containment — not a security boundary, model code has bash-equivalent trust — comes from an empty environment, `RLIMIT_CPU`/`RLIMIT_AS`, a wall-clock ceiling, and `SIGTERM`→grace→`SIGKILL` process-group teardown, with all caps validated at plugin load. ## Table of Contents @@ -86,10 +86,10 @@ Completion values and binding arguments cross as exact JSON: values serialize wi Read these when the runtime contract is not enough. They move from the seam definition to the design record and the companion backend. -- [Code runtime seam](../code-runtime/README.md) — the abstract contract this backend implements. +- [Code runtime seam](../../code-runtime/code-runtime/README.md) — the abstract contract this backend implements. - [fd-3 protocol Agent Note](../../../.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.md) — design rationale and wire contract. - [Settlement-fixes Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.md) — settlement, metering, and containment fixes and their regression cases. -- [Worker-thread backend](../code-runtime-worker-thread/README.md) — the shipped TypeScript sibling. +- [Worker-thread backend](../../code-runtime/code-runtime-worker-thread/README.md) — the shipped TypeScript sibling. - [Code runtime subsystem reference](../../../docs/subsystems/code-runtime.md) — request/result vocabulary, bindings, and failure taxonomy. ----- diff --git a/packages/code-runtime/code-runtime-python/README.zh.md b/packages/experimental/code-runtime-python/README.zh.md similarity index 91% rename from packages/code-runtime/code-runtime-python/README.zh.md rename to packages/experimental/code-runtime-python/README.zh.md index 2b710aefba..c2ec5ca81e 100644 --- a/packages/code-runtime/code-runtime-python/README.zh.md +++ b/packages/experimental/code-runtime-python/README.zh.md @@ -3,13 +3,13 @@ description: "CPython 子进程代码 runtime：为 Python 模型代码实现 ds kind: "package-reference" --- -# @deepseek-ai/dsh-code-runtime-python +# @deepseek-ai/dsh-experimental-code-runtime-python [English](README.md) | 中文 ## 概述 -`dsh-code-runtime-python` 交付 `PythonCodeRuntime`——[`dsh-code-runtime`](../code-runtime/README.zh.md) seam 的 CPython 子进程实现：它以 `language: 'python'`、`isolation: 'process'` 注册为 `codeRuntime`，每次 `run()` 启动一个全新的 `python3 -I` 子进程，把程序作为 async 函数体执行，通过子进程 fd 3 上的无版本 JSON-lines 协议通信（stdout/stderr 留给程序自己的输出）。宿主侧（`src/protocol.ts`）把每条入站帧都视为敌意并逐字段重建后才读取；Python 侧（`py/protocol.py`）镜像消息词汇。隔离（不是安全边界——模型代码与 bash 同等的信任）来自空环境、`RLIMIT_CPU`/`RLIMIT_AS`、墙钟上限与 `SIGTERM`→宽限→`SIGKILL` 进程组拆卸，所有上限都在插件加载期校验。 +`dsh-experimental-code-runtime-python` 交付 `PythonCodeRuntime`——[`dsh-code-runtime`](../../code-runtime/code-runtime/README.zh.md) seam 的 CPython 子进程实现：它以 `language: 'python'`、`isolation: 'process'` 注册为 `codeRuntime`，每次 `run()` 启动一个全新的 `python3 -I` 子进程，把程序作为 async 函数体执行，通过子进程 fd 3 上的无版本 JSON-lines 协议通信（stdout/stderr 留给程序自己的输出）。宿主侧（`src/protocol.ts`）把每条入站帧都视为敌意并逐字段重建后才读取；Python 侧（`py/protocol.py`）镜像消息词汇。隔离（不是安全边界——模型代码与 bash 同等的信任）来自空环境、`RLIMIT_CPU`/`RLIMIT_AS`、墙钟上限与 `SIGTERM`→宽限→`SIGKILL` 进程组拆卸，所有上限都在插件加载期校验。 ## 目录 @@ -86,10 +86,10 @@ kind: "package-reference" 当 runtime 契约不够时阅读这些。它们从 seam 定义走向设计记录与配套后端。 -- [Code runtime seam](../code-runtime/README.zh.md) — 本后端实现的抽象契约。 +- [Code runtime seam](../../code-runtime/code-runtime/README.zh.md) — 本后端实现的抽象契约。 - [fd-3 协议 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-31-code-runtime-python-fd3-protocol.zh.md) — 设计理由与 wire 契约。 - [结算修复 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-31-code-runtime-python-settlement-fixes.zh.md) — 结算、计量与隔离修复及其回归用例。 -- [Worker 线程后端](../code-runtime-worker-thread/README.zh.md) — 已发布的 TypeScript 兄弟。 +- [Worker 线程后端](../../code-runtime/code-runtime-worker-thread/README.zh.md) — 已发布的 TypeScript 兄弟。 - [Code runtime 子系统参考](../../../docs/subsystems/code-runtime.zh.md) — 请求／结果词汇、binding 与失败分类。 ----- diff --git a/packages/code-runtime/code-runtime-python/package.json b/packages/experimental/code-runtime-python/package.json similarity index 89% rename from packages/code-runtime/code-runtime-python/package.json rename to packages/experimental/code-runtime-python/package.json index 97bcc57447..239dd6c744 100644 --- a/packages/code-runtime/code-runtime-python/package.json +++ b/packages/experimental/code-runtime-python/package.json @@ -1,14 +1,11 @@ { - "name": "@deepseek-ai/dsh-code-runtime-python", + "name": "@deepseek-ai/dsh-experimental-code-runtime-python", "description": "CPython subprocess implementation of the DeepSeek Harness code-execution seam", "version": "0.1.2-alpha.2", - "publishConfig": { - "access": "public" - }, "repository": { "type": "git", "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", - "directory": "packages/code-runtime/code-runtime-python" + "directory": "packages/experimental/code-runtime-python" }, "type": "module", "main": "lib/index.js", @@ -47,5 +44,6 @@ }, "dependencies": { "@deepseek-ai/schemastery": "workspace:^" - } + }, + "private": true } diff --git a/packages/code-runtime/code-runtime-python/py/bootstrap.py b/packages/experimental/code-runtime-python/py/bootstrap.py similarity index 100% rename from packages/code-runtime/code-runtime-python/py/bootstrap.py rename to packages/experimental/code-runtime-python/py/bootstrap.py diff --git a/packages/code-runtime/code-runtime-python/py/protocol.py b/packages/experimental/code-runtime-python/py/protocol.py similarity index 100% rename from packages/code-runtime/code-runtime-python/py/protocol.py rename to packages/experimental/code-runtime-python/py/protocol.py diff --git a/packages/code-runtime/code-runtime-python/src/index.ts b/packages/experimental/code-runtime-python/src/index.ts similarity index 100% rename from packages/code-runtime/code-runtime-python/src/index.ts rename to packages/experimental/code-runtime-python/src/index.ts diff --git a/packages/code-runtime/code-runtime-python/src/invariant.ts b/packages/experimental/code-runtime-python/src/invariant.ts similarity index 100% rename from packages/code-runtime/code-runtime-python/src/invariant.ts rename to packages/experimental/code-runtime-python/src/invariant.ts diff --git a/packages/code-runtime/code-runtime-python/src/protocol.ts b/packages/experimental/code-runtime-python/src/protocol.ts similarity index 100% rename from packages/code-runtime/code-runtime-python/src/protocol.ts rename to packages/experimental/code-runtime-python/src/protocol.ts diff --git a/packages/code-runtime/code-runtime-python/tests/boot-write-failure.spec.ts b/packages/experimental/code-runtime-python/tests/boot-write-failure.spec.ts similarity index 100% rename from packages/code-runtime/code-runtime-python/tests/boot-write-failure.spec.ts rename to packages/experimental/code-runtime-python/tests/boot-write-failure.spec.ts diff --git a/packages/code-runtime/code-runtime-python/tests/protocol-mirror.e2e.ts b/packages/experimental/code-runtime-python/tests/protocol-mirror.e2e.ts similarity index 100% rename from packages/code-runtime/code-runtime-python/tests/protocol-mirror.e2e.ts rename to packages/experimental/code-runtime-python/tests/protocol-mirror.e2e.ts diff --git a/packages/code-runtime/code-runtime-python/tests/protocol.spec.ts b/packages/experimental/code-runtime-python/tests/protocol.spec.ts similarity index 100% rename from packages/code-runtime/code-runtime-python/tests/protocol.spec.ts rename to packages/experimental/code-runtime-python/tests/protocol.spec.ts diff --git a/packages/code-runtime/code-runtime-python/tests/residual-detach.spec.ts b/packages/experimental/code-runtime-python/tests/residual-detach.spec.ts similarity index 100% rename from packages/code-runtime/code-runtime-python/tests/residual-detach.spec.ts rename to packages/experimental/code-runtime-python/tests/residual-detach.spec.ts diff --git a/packages/code-runtime/code-runtime-python/tests/runtime.spec.ts b/packages/experimental/code-runtime-python/tests/runtime.spec.ts similarity index 100% rename from packages/code-runtime/code-runtime-python/tests/runtime.spec.ts rename to packages/experimental/code-runtime-python/tests/runtime.spec.ts diff --git a/packages/code-runtime/code-runtime-python/tsconfig.json b/packages/experimental/code-runtime-python/tsconfig.json similarity index 91% rename from packages/code-runtime/code-runtime-python/tsconfig.json rename to packages/experimental/code-runtime-python/tsconfig.json index d5083e4474..6703a4b90d 100644 --- a/packages/code-runtime/code-runtime-python/tsconfig.json +++ b/packages/experimental/code-runtime-python/tsconfig.json @@ -18,7 +18,7 @@ "path": "../../../vendor/schemastery" }, { - "path": "../code-runtime" + "path": "../../code-runtime/code-runtime" }, { "path": "../../core/session" diff --git a/packages/code-runtime/code-runtime-python/tsdown.config.ts b/packages/experimental/code-runtime-python/tsdown.config.ts similarity index 100% rename from packages/code-runtime/code-runtime-python/tsdown.config.ts rename to packages/experimental/code-runtime-python/tsdown.config.ts diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9df1171843..7a20a8ca82 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -3953,28 +3953,6 @@ importers: specifier: workspace:^ version: link:../../runtime-diagnostics/invariants - packages/code-runtime/code-runtime-python: - dependencies: - '@deepseek-ai/schemastery': - specifier: link:../../../vendor/schemastery - version: link:../../../vendor/schemastery - devDependencies: - '@deepseek-ai/cordis': - specifier: workspace:^ - version: link:../../../vendor/cordis - '@deepseek-ai/dsh-code-runtime': - specifier: workspace:^ - version: link:../code-runtime - '@deepseek-ai/dsh-invariants': - specifier: workspace:^ - version: link:../../runtime-diagnostics/invariants - '@deepseek-ai/dsh-session': - specifier: workspace:^ - version: link:../../core/session - '@deepseek-ai/dsh-timeout': - specifier: workspace:^ - version: link:../../util/timeout - packages/code-runtime/code-runtime-worker-thread: dependencies: '@deepseek-ai/dsh-util-values': @@ -4927,6 +4905,28 @@ importers: specifier: ^18.2.0 version: 18.3.1(react@18.3.1) + packages/experimental/code-runtime-python: + dependencies: + '@deepseek-ai/schemastery': + specifier: link:../../../vendor/schemastery + version: link:../../../vendor/schemastery + devDependencies: + '@deepseek-ai/cordis': + specifier: workspace:^ + version: link:../../../vendor/cordis + '@deepseek-ai/dsh-code-runtime': + specifier: workspace:^ + version: link:../../code-runtime/code-runtime + '@deepseek-ai/dsh-invariants': + specifier: workspace:^ + version: link:../../runtime-diagnostics/invariants + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + '@deepseek-ai/dsh-timeout': + specifier: workspace:^ + version: link:../../util/timeout + packages/experimental/inspector: dependencies: '@deepseek-ai/dsh-brand': diff --git a/scripts/check-workspace-constraints.ts b/scripts/check-workspace-constraints.ts index f7491f709b..b339e7560b 100644 --- a/scripts/check-workspace-constraints.ts +++ b/scripts/check-workspace-constraints.ts @@ -150,7 +150,7 @@ const packageFileExtras: Readonly> = { '@deepseek-ai/dsh-client-web': ['lib/**/*.css'], '@deepseek-ai/dsh-client-ui-theme': ['lib/styles'], // The CPython side ships as source .py files, published as-is rather than built. - '@deepseek-ai/dsh-code-runtime-python': ['py/**/*.py'], + '@deepseek-ai/dsh-experimental-code-runtime-python': ['py/**/*.py'], // The shipped preset compositions travel inside the roster package. '@deepseek-ai/dsh-agent-presets': ['presets'], // The Web Host mounts the default-off settings owner independently of each diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts index cb30c6a387..6cedeb9c16 100644 --- a/scripts/verify-package-readme-model-experience.ts +++ b/scripts/verify-package-readme-model-experience.ts @@ -53,7 +53,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly> = { 'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to PTC mode in dsh-tools.' }, 'packages/core/agent-tool-presentation': { kind: 'indirect', reason: 'The row only selects between the two projections dsh-tools owns; it registers no prompt, schema, or result of its own.' }, 'packages/code-runtime/code-runtime-worker-thread': { kind: 'indirect', reason: 'The worker backend delegates model rendering to PTC mode in dsh-tools.' }, - 'packages/code-runtime/code-runtime-python': { kind: 'indirect', reason: 'The CPython subprocess backend delegates model rendering to PTC mode in dsh-tools.' }, + 'packages/experimental/code-runtime-python': { kind: 'indirect', reason: 'The CPython subprocess backend delegates model rendering to PTC mode in dsh-tools.' }, 'packages/client/ui-agent-preset': { kind: 'indirect', reason: 'Browser-side settings row; the preset it selects owns every model-facing effect.' }, 'packages/util/crypto': { kind: 'indirect', reason: 'Pure identifier minting; the ids consumers mint with it never enter prompts as semantic content.' }, 'packages/util/deque': { kind: 'none', reason: 'In-process collection primitive; registers nothing model-facing.' }, diff --git a/tsconfig.host.json b/tsconfig.host.json index e21c47c805..208473611c 100644 --- a/tsconfig.host.json +++ b/tsconfig.host.json @@ -223,7 +223,7 @@ { "path": "./packages/shell/tool-pwsh-persistent" }, { "path": "./packages/terminal/tool-terminal" }, { "path": "./packages/code-runtime/code-runtime" }, - { "path": "./packages/code-runtime/code-runtime-python" }, + { "path": "./packages/experimental/code-runtime-python" }, { "path": "./packages/code-runtime/code-runtime-worker-thread" }, { "path": "./packages/llm/llm-deepseek" }, { "path": "./packages/llm/llm-pi-ai" },