dsh-ptc-moejs 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Calcium-Ion
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
+# dsh-ptc-moejs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[简体中文](README.zh_CN.md)
+
+A PTC runtime for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh). It runs the model's programs in [moejs](https://github.com/Calcium-Ion/moejs), a JavaScript engine written in Go.
+
+In dsh's PTC mode the model answers with a TypeScript program that calls tools, and dsh hands that program to the loaded runtime. A run of three tool calls takes 0.18 ms here; dsh's Node runtime takes 95 ms for the same program (see [Measurements](#measurements)). Each run gets a fresh moejs runtime inside one sidecar process, which stays up between runs, and a memory budget, 512 MiB by default; a deadline or an abort stops a run at once, an endless loop included. The sidecar is a static Go binary that dsh starts as a plain child process. Starting that process is all the runtime asks of the host, so it also works in containers where bubblewrap cannot run.
+
+## Quick start
+
+```sh
+dsh plugin --profile web add dsh-ptc-moejs
+```
+
+Use the name of the profile you run in place of `web`. The sidecar binary comes as an optional dependency for darwin-arm64, darwin-x64, linux-arm64, linux-x64 and win32-x64, so install with optional dependencies enabled.
+
+Installing adds a disabled `ptc-moejs` row to the profile. To select it, add this patch to the profile's `cordis.patch.yml`, which is `~/.dsh/profiles/<name>/cordis.patch.yml` (or the same path under `$DSH_HOME`):
+
+```yaml
+# Replace the Node PTC runtime with moejs.
+- id: ptc-runtime
+  disabled: true
+- id: ptc-moejs
+  disabled: false
+# Turn PTC mode on.
+- id: tools
+  config:
+    mode: ptc
+```
+
+`dsh --profile web --dump-config` prints the composed rows. In the web and headless profiles, `DSH_TOOLS_MODE=ptc` also turns PTC mode on for one launch, in place of the `tools` entry. To go back to the Node runtime, delete the first two entries.
+
+## Configuration
+
+Options go on the `ptc-moejs` row of the same patch:
+
+```yaml
+- id: ptc-moejs
+  disabled: false
+  config:
+    memoryLimitMb: 1024
+    timeoutMs: 300000
+```
+
+| Option | Default | Meaning |
+|---|--:|---|
+| `timeoutMs` | 120000 | Deadline of a run in milliseconds when the model asks for none. Tool calls and approvals count toward it. |
+| `maxTimeoutMs` | 600000 | The longest deadline a run may ask for. |
+| `memoryLimitMb` | 512 | MiB a run may allocate over its whole life, garbage included. Past it the run stops with `timeout` and a message that names the budget. |
+| `maxLogBytes` | 16 MiB | Bytes of console output a run keeps, counted as the JSON array dsh stores. Output past it is dropped, a marker line ends the logs, and the run goes on. |
+| `maxValueBytes` | 16 MiB | Bytes of the returned value as JSON. A larger value fails the run with `output-limit`. Error messages are cut to this size. |
+| `maxPendingCalls` | 128 | Tool calls a run may have in flight at once. One more fails the run with `protocol`. |
+| `maxFrameBytes` | 64 MiB | The largest message between dsh and the sidecar: a program, the arguments of a tool call or one tool result. A larger tool result reaches the program as a rejected call. |
+
+The deadline defaults follow dsh's Node runtime. dsh spills tool results longer than 12,500 tokens to a file, so the log and value budgets are limits on memory use.
+
+## How it works
+
+A program in this runtime can call the tools dsh gives it and write to `console`. To read a file or run a command it calls a tool, and each tool call goes through dsh's tool pipeline with that tool's own policy, approvals and sandbox, as it does with the Node runtime. Every effect a program has on the machine is one of those tool calls.
+
+## What a program sees
+
+A program is the body of an async function, so `await` and `return` work at its top level. The function's parameters are the binding namespaces dsh passes (`tools` in PTC mode), the error class of each namespace (`ToolCallError`, which carries the tool's name in `toolName`) and `console` with `log`, `info`, `warn`, `error` and `debug`.
+
+Programs are TypeScript with erasable syntax, the rule dsh's Node runtime applies: the types are removed, and `enum`, namespaces with values and parameter properties are syntax errors.
+
+The rest is the JavaScript standard library, which in moejs includes `TextEncoder`, `TextDecoder`, `atob`, `btoa`, `structuredClone` and `queueMicrotask`. Node's APIs are absent: `require`, `import`, `process`, `Buffer`, `fs` and `setTimeout` are undefined in a program. A program that needs a file asks the `read` tool for it. If your programs use Node APIs, keep dsh's Node runtime for that profile.
+
+The program has no sandbox of its own, so `run_code` takes no `sandbox_permissions` argument. When the file sandbox denies a tool call, the program retries that call with `sandbox_permissions` and `justification` among the arguments, and each such call asks you for approval. On the Node runtime, the file operations a program performs itself through Node APIs can be approved once for the whole run.
+
+A run looks like this. The model writes the body; the runtime executes it and hands the returned value to dsh:
+
+```ts
+const head = await tools.bash({ description: "Read the last commit", command: "git log -1 --oneline" });
+return { head: head.stdout?.text };
+```
+
+The returned value goes back to dsh as lossless JSON: plain objects, arrays, strings, finite numbers, booleans and `null`. A value that holds `undefined`, a function, a `BigInt`, a cycle, `NaN`, `Infinity`, `-0`, a `Date`, a `Map` or a class instance fails the run with `invalid-output`, and the message gives the path of the first such member, for example `a BigInt at $.items[3].size`. A program that returns nothing completes with no value. Tool arguments follow the same rule, and a call with arguments that are not lossless JSON rejects inside the program before dsh sees it.
+
+| Failure kind | When |
+|---|---|
+| `exception` | The program throws, has a syntax error, or uses TypeScript that changes run-time behaviour, such as `enum`. |
+| `timeout` | The deadline passes, or the program allocates more than `memoryLimitMb`. |
+| `abort` | dsh cancels the run, or the profile shuts the runtime down. |
+| `invalid-output` | The returned value is not lossless JSON. |
+| `output-limit` | The returned value is larger than `maxValueBytes`. |
+| `protocol` | More than `maxPendingCalls` tool calls are in flight, or the sidecar sent a malformed message. |
+| `worker-exit` | The sidecar process died. The next run starts a new one. |
+
+## Measurements
+
+Both runtimes ran the same program through dsh's `PtcRuntime` service API: three tool calls, each answered at once by its binding, and a returned object. Every round started each runtime in a fresh Node process. The 5 rounds alternated the order of the runtimes on 8 cores of an Intel Core i5-13500H, with Linux 6.18, Node 24.22.1, Go 1.26.6, dsh 0.2.1-rc.2 and moejs v0.1.0-alpha.9. The table gives the median of the round medians.
+
+| Runtime | Per call | Load to first result |
+|---|--:|--:|
+| dsh-ptc-moejs | 0.18 ms | 5.8 ms |
+| dsh-ptc-runtime-node, workspace-write | 94.8 ms | 131.7 ms |
+| dsh-ptc-runtime-node, danger-full-access | 91.2 ms | 135.0 ms |
+
+A call is one `resolve` and `run`, from the program text to the result. Load to first result runs from mounting the plugin to the end of its first run, and for moejs it includes starting the sidecar. Workspace-write is the default file policy of a dsh Session, under which the Node runtime starts each program inside bubblewrap. Danger-full-access starts it directly. The round medians stayed within 0.16 to 0.20 ms for moejs and within 90 to 96 ms for Node.
+
+## Limitations
+
+- Every call starts with a fresh runtime. A persistent mode that keeps variables between calls, like the Node runtime's REPL mode, is planned for a later version.
+- The memory budget counts what a run allocates, garbage included. A long run that builds and drops a lot of data can stop before its live data reaches the budget.
+- Values nest up to 10,000 levels deep in both directions, the depth moejs's JSON reader and writer handle.
+- `console` output imitates Node's `util.inspect` for strings, numbers, plain objects, arrays, `Map`, `Set`, errors and class instances, and breaks a line at 72 characters.
+- moejs interrupts running JavaScript, and a compile runs to its end once it starts. A program that takes long to parse still ends at its deadline for dsh, and the sidecar drops the run once the parse returns.
+- If a tool call that the program never awaits fails, the failure stays in that unread promise.
+- This version has been tested on Linux x64. The other four binaries are cross-compiled from the same source.
+
+## Development
+
+```sh
+pnpm install
+pnpm run build:sidecar   # the sidecar for this machine, into npm/<package>/bin
+pnpm run build           # lib/
+pnpm test                # unit tests and the behaviour suite against the sidecar
+go test ./...            # the sidecar's Go tests
+DSH_REPO=/path/to/deepseek-harness pnpm run e2e     # headless dsh with dsh's mock LLM
+DSH_REPO=/path/to/deepseek-harness pnpm run bench   # the measurements above
+pnpm run build:binaries  # all five platform binaries
+```
+
+Building the sidecar takes Go 1.25 or later, with `CGO_ENABLED=0`. `DSH_REPO` is a dsh checkout after `pnpm install` and `pnpm run build`. The e2e test installs this checkout into a temporary profile with `dsh plugin add`, runs one headless task in which the mock model calls `run_code`, and compares the Session log with the same task on the Node runtime.
+
+## License
+
+MIT. The sidecar binary in each platform package also contains moejs (Apache License 2.0) and the Go standard library (BSD 3-Clause License). Their license texts are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md), which ships with each platform package.

package/README.zh_CN.md

@@ -0,0 +1,129 @@
+# dsh-ptc-moejs
+
+[English](README.md)
+
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）的 PTC 运行时，用 Go 写的 JavaScript 引擎 [moejs](https://github.com/Calcium-Ion/moejs) 运行模型的程序。
+
+dsh 的 PTC 模式下，模型给出一段调用工具的 TypeScript 程序，dsh 把程序交给当前加载的运行时执行。这个运行时把程序放进 [moejs](https://github.com/Calcium-Ion/moejs) 里运行。调用三次工具的程序在这里一次运行用时 0.18 ms，dsh 的 Node 运行时跑同样的程序用时 95 ms（见[测量](#测量)）。每次运行都在一个 sidecar 进程里新建 moejs 运行时，sidecar 在多次运行之间一直保留；每次运行还有内存预算，默认 512 MiB，截止时间到了或者被中止时运行立即停止，死循环也一样。sidecar 是静态链接的 Go 程序，dsh 把它当作普通子进程启动。运行时对宿主机的要求就是能启动这个进程，所以在无法运行 bubblewrap 的容器里也能用。
+
+## 快速开始
+
+```sh
+dsh plugin --profile web add dsh-ptc-moejs
+```
+
+把 `web` 换成你使用的 profile 名。sidecar 程序以可选依赖的形式提供，覆盖 darwin-arm64、darwin-x64、linux-arm64、linux-x64 和 win32-x64，安装时需要启用可选依赖。
+
+安装后 profile 里多出一行处于禁用状态的 `ptc-moejs`。要启用它，把下面的补丁加进 profile 的 `cordis.patch.yml`，路径是 `~/.dsh/profiles/<name>/cordis.patch.yml`（设置了 `$DSH_HOME` 时在它下面的同一路径）：
+
+```yaml
+# 用 moejs 替换 Node PTC 运行时。
+- id: ptc-runtime
+  disabled: true
+- id: ptc-moejs
+  disabled: false
+# 打开 PTC 模式。
+- id: tools
+  config:
+    mode: ptc
+```
+
+`dsh --profile web --dump-config` 会打印组合后的配置行。在 web 和 headless profile 里，也可以用 `DSH_TOOLS_MODE=ptc` 在单次启动时打开 PTC 模式，代替 `tools` 那一项。要换回 Node 运行时，删掉前两项。
+
+## 配置
+
+选项写在同一个补丁的 `ptc-moejs` 行上：
+
+```yaml
+- id: ptc-moejs
+  disabled: false
+  config:
+    memoryLimitMb: 1024
+    timeoutMs: 300000
+```
+
+| 选项 | 默认值 | 含义 |
+|---|--:|---|
+| `timeoutMs` | 120000 | 模型没有指定时，一次运行的截止时间（毫秒）。工具调用和审批的时间都算在内。 |
+| `maxTimeoutMs` | 600000 | 一次运行可以请求的最长截止时间。 |
+| `memoryLimitMb` | 512 | 一次运行在整个生命周期里可以分配的 MiB 数，垃圾也算在内。超过后运行以 `timeout` 停止，消息里写明是哪个预算。 |
+| `maxLogBytes` | 16 MiB | 一次运行保留的 console 输出字节数，按 dsh 存储的 JSON 数组计算。超出部分被丢弃，日志以一行标记结尾，运行继续。 |
+| `maxValueBytes` | 16 MiB | 返回值序列化成 JSON 后的字节数。更大的值让运行以 `output-limit` 失败。错误消息也截断到这个长度。 |
+| `maxPendingCalls` | 128 | 一次运行同时进行中的工具调用数。再多一个，运行以 `protocol` 失败。 |
+| `maxFrameBytes` | 64 MiB | dsh 和 sidecar 之间单条消息的上限：一段程序、一次工具调用的参数或一个工具结果。更大的工具结果在程序里表现为被拒绝的调用。 |
+
+截止时间的默认值和 dsh 的 Node 运行时一致。dsh 会把超过 12,500 token 的工具结果转存到文件，所以日志和返回值的预算用来限制内存占用。
+
+## 工作方式
+
+程序能调用 dsh 提供的工具，能向 `console` 输出。读文件、执行命令都要调用工具，每次工具调用都走 dsh 的工具流水线，由该工具自己的策略、审批和沙箱处理，和 Node 运行时一样。程序对机器的每一次影响都是这样一次工具调用。
+
+## 程序能看到什么
+
+程序是一个 async 函数的函数体，顶层可以用 `await` 和 `return`。函数的参数有 dsh 传入的绑定命名空间（PTC 模式下是 `tools`）、每个命名空间的错误类（`ToolCallError`，`toolName` 属性里是工具名），以及带 `log`、`info`、`warn`、`error`、`debug` 的 `console`。
+
+程序是只用可擦除语法的 TypeScript，规则和 dsh 的 Node 运行时相同：类型标注被删掉，`enum`、带值的 namespace 和参数属性都是语法错误。
+
+其余是 JavaScript 标准库，moejs 的标准库里有 `TextEncoder`、`TextDecoder`、`atob`、`btoa`、`structuredClone` 和 `queueMicrotask`。Node 的 API 在程序里都是 undefined，包括 `require`、`import`、`process`、`Buffer`、`fs` 和 `setTimeout`。程序要读文件时调用 `read` 工具。如果你的程序要用 Node API，这个 profile 继续用 dsh 的 Node 运行时。
+
+程序自己没有沙箱，所以 `run_code` 不接受 `sandbox_permissions`。文件沙箱拒绝某次工具调用时，程序在这次调用的参数里带上 `sandbox_permissions` 和 `justification` 重试，每次这样的调用都要你批准。用 Node 运行时的话，程序通过 Node API 自己做的文件操作还能用一次批准全部放行。
+
+一次运行是这样的。函数体由模型写，运行时执行它，并把返回值交给 dsh：
+
+```ts
+const head = await tools.bash({ description: "Read the last commit", command: "git log -1 --oneline" });
+return { head: head.stdout?.text };
+```
+
+返回值以无损 JSON 的形式交给 dsh：普通对象、数组、字符串、有限数字、布尔值和 `null`。值里含有 `undefined`、函数、`BigInt`、循环引用、`NaN`、`Infinity`、`-0`、`Date`、`Map` 或类的实例时，运行以 `invalid-output` 失败，消息给出第一个这样的成员的路径，例如 `a BigInt at $.items[3].size`。程序没有返回值时，运行正常结束，结果里没有值。工具参数遵守同样的规则，参数不是无损 JSON 的调用在发给 dsh 之前就在程序内部被拒绝。
+
+| 失败类型 | 什么时候出现 |
+|---|---|
+| `exception` | 程序抛出异常、有语法错误，或者用了会改变运行行为的 TypeScript，例如 `enum`。 |
+| `timeout` | 超过截止时间，或者分配的内存超过 `memoryLimitMb`。 |
+| `abort` | dsh 取消了这次运行，或者 profile 关闭了运行时。 |
+| `invalid-output` | 返回值不是无损 JSON。 |
+| `output-limit` | 返回值大于 `maxValueBytes`。 |
+| `protocol` | 同时进行中的工具调用超过 `maxPendingCalls`，或者 sidecar 发来了格式错误的消息。 |
+| `worker-exit` | sidecar 进程退出了。下一次运行会启动新的进程。 |
+
+## 测量
+
+两个运行时通过 dsh 的 `PtcRuntime` 服务接口运行同一段程序：三次工具调用，每次由绑定函数立即返回，最后返回一个对象。每一轮里，每个运行时都在新的 Node 进程中启动。5 轮交替顺序运行，绑定在 Intel Core i5-13500H 的 8 个核上，环境是 Linux 6.18、Node 24.22.1、Go 1.26.6、dsh 0.2.1-rc.2 和 moejs v0.1.0-alpha.9。表中是各轮中位数的中位数。
+
+| 运行时 | 每次调用 | 从加载到第一个结果 |
+|---|--:|--:|
+| dsh-ptc-moejs | 0.18 ms | 5.8 ms |
+| dsh-ptc-runtime-node，workspace-write | 94.8 ms | 131.7 ms |
+| dsh-ptc-runtime-node，danger-full-access | 91.2 ms | 135.0 ms |
+
+一次调用是一次 `resolve` 加一次 `run`，从程序文本到结果。从加载到第一个结果是从挂载插件到第一次运行结束，moejs 的这段时间包含启动 sidecar。workspace-write 是 dsh 会话的默认文件策略，这时 Node 运行时在 bubblewrap 里启动每段程序。danger-full-access 下直接启动。各轮中位数里，moejs 在 0.16 到 0.20 ms 之间，Node 在 90 到 96 ms 之间。
+
+## 限制
+
+- 每次调用都从新的运行时开始。在调用之间保留变量的持久模式（类似 Node 运行时的 REPL 模式）计划在以后的版本中加入。
+- 内存预算统计的是一次运行分配的内存，垃圾也算在内。一次运行如果反复创建又丢弃大量数据，可能在存活数据达到预算之前就被停止。
+- 两个方向的值最多嵌套 10,000 层，这是 moejs 的 JSON 读写能处理的深度。
+- `console` 的输出仿照 Node 的 `util.inspect`，覆盖字符串、数字、普通对象、数组、`Map`、`Set`、错误和类的实例，单行超过 72 个字符时换行。
+- moejs 的中断作用于正在运行的 JavaScript，编译一旦开始会一直进行到结束。解析很慢的程序到截止时间时，dsh 一侧照常结束这次运行，sidecar 等解析返回后丢弃它。
+- 程序没有 await 的工具调用如果失败，这个失败只留在那个没人读取的 promise 里。
+- 这个版本在 Linux x64 上测试过。其余四个平台的程序由同一份源码交叉编译。
+
+## 开发
+
+```sh
+pnpm install
+pnpm run build:sidecar   # 为本机构建 sidecar，放到 npm/<package>/bin
+pnpm run build           # lib/
+pnpm test                # 单元测试，以及针对 sidecar 的行为测试
+go test ./...            # sidecar 的 Go 测试
+DSH_REPO=/path/to/deepseek-harness pnpm run e2e     # 用 dsh 的 mock LLM 跑 headless dsh
+DSH_REPO=/path/to/deepseek-harness pnpm run bench   # 上面的测量
+pnpm run build:binaries  # 五个平台的程序
+```
+
+构建 sidecar 需要 Go 1.25 或更新版本，使用 `CGO_ENABLED=0`。`DSH_REPO` 是执行过 `pnpm install` 和 `pnpm run build` 的 dsh 源码目录。端到端测试用 `dsh plugin add` 把这个目录装进临时 profile，跑一个 headless 任务，让 mock 模型调用 `run_code`，再和 Node 运行时跑同一任务的会话日志做比较。
+
+## 许可证
+
+MIT。各平台包里的常驻进程二进制还包含 moejs（Apache License 2.0）和 Go 标准库（BSD 3-Clause License），它们的许可证原文在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 里，随每个平台包一起发布。

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# The dsh-ptc-moejs bundle layer: it mounts the moejs PTC runtime as a
+# disabled row, so installing the package changes nothing on its own. A
+# profile selects it with a patch that disables the ptc-runtime row (the Node
+# runtime) and enables this one; see the README.
+
+- insert:
+    - id: ptc-moejs
+      name: dsh-ptc-moejs
+      disabled: true

package/lib/binary.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Finds the sidecar binary. Each supported platform has its own package,
+ * installed as an optional dependency, as esbuild ships its binary.
+ * @module dsh-ptc-moejs/binary
+ */
+/** The platforms that have a binary package. */
+export declare const PLATFORMS: readonly ["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64", "win32-x64"];
+/**
+ * Resolve the sidecar binary for this platform.
+ * @param platform - the Node platform name.
+ * @param arch - the Node architecture name.
+ * @returns the absolute path of the binary.
+ * @throws When no binary package for the platform is installed.
+ */
+export declare function resolveBinary(platform?: string, arch?: string): string;

package/lib/binary.js

@@ -0,0 +1,28 @@
+/**
+ * Finds the sidecar binary. Each supported platform has its own package,
+ * installed as an optional dependency, as esbuild ships its binary.
+ * @module dsh-ptc-moejs/binary
+ */
+import { createRequire } from 'node:module';
+/** The platforms that have a binary package. */
+export const PLATFORMS = ['darwin-arm64', 'darwin-x64', 'linux-arm64', 'linux-x64', 'win32-x64'];
+/**
+ * Resolve the sidecar binary for this platform.
+ * @param platform - the Node platform name.
+ * @param arch - the Node architecture name.
+ * @returns the absolute path of the binary.
+ * @throws When no binary package for the platform is installed.
+ */
+export function resolveBinary(platform = process.platform, arch = process.arch) {
+    const target = `${platform}-${arch}`;
+    const pkg = `dsh-ptc-moejs-${target}`;
+    try {
+        return createRequire(import.meta.url).resolve(`${pkg}/bin/moejs-ptc${platform === 'win32' ? '.exe' : ''}`);
+    }
+    catch {
+        const supported = PLATFORMS.includes(target);
+        throw new Error(supported
+            ? `dsh-ptc-moejs: the sidecar package ${pkg} is not installed; reinstall with optional dependencies enabled`
+            : `dsh-ptc-moejs: no sidecar binary for ${target} (supported: ${PLATFORMS.join(', ')})`);
+    }
+}

package/lib/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A PTC runtime for the DeepSeek Harness that runs each program in a fresh
+ * moejs runtime inside one long-lived sidecar process. A program's effects on
+ * the machine are its tool calls, which dsh's tool pipeline confines.
+ * @module dsh-ptc-moejs
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { PtcRuntime } from '@deepseek-ai/dsh-ptc-runtime';
+import type { PtcBindingNamespace, PtcRunRequest, PtcRunResult, PtcRunSpec } from '@deepseek-ai/dsh-ptc-runtime';
+import z from '@deepseek-ai/schemastery';
+import type { Namespace } from './sidecar.ts';
+/** Plugin configuration. */
+export interface Config {
+    /** Default elapsed deadline of a run in milliseconds, tool calls included. */
+    timeoutMs?: number;
+    /** Largest deadline a run may request. */
+    maxTimeoutMs?: number;
+    /** MiB one run may allocate in total, garbage included, before it is stopped. */
+    memoryLimitMb?: number;
+    /** Bytes of serialized logs a run keeps; capture stops at the budget. */
+    maxLogBytes?: number;
+    /** Bytes of serialized completion value; a larger value fails as output-limit. */
+    maxValueBytes?: number;
+    /** Tool calls one run may have in flight at once. */
+    maxPendingCalls?: number;
+    /** Bytes of one frame between host and sidecar: a program, a tool result or tool arguments. */
+    maxFrameBytes?: number;
+}
+/** Configuration with every default filled in. */
+export type ResolvedConfig = Required<Config>;
+/** The defaults, with the Node runtime's 120 s and 600 s deadlines. */
+export declare const MoejsConfig: z<Config>;
+/**
+ * Fill in defaults and validate the configuration.
+ * @param config - configuration as given.
+ * @returns the complete configuration.
+ * @throws When a value is out of range.
+ */
+export declare function resolveConfig(config?: Config): ResolvedConfig;
+/**
+ * Validate the binding namespaces of a request and read each function once.
+ * Names follow the rules dsh shares across PTC runtimes, so a namespace list
+ * valid here is valid on every runtime.
+ * @param bindings - the request's namespaces.
+ * @returns the namespaces keyed by their global.
+ * @throws When a name is unusable, reserved or used twice.
+ */
+export declare function validateBindings(bindings: readonly PtcBindingNamespace[]): Map<string, Namespace>;
+/** The moejs PTC runtime: `ctx.ptcRuntime` backed by one moejs-ptc sidecar. */
+export declare class MoejsPtcRuntime extends PtcRuntime {
+    static Config: z<Config>;
+    readonly language = "typescript";
+    readonly isolation = "process";
+    private readonly config;
+    private readonly sidecar;
+    private disposed;
+    constructor(ctx: Context, config: Config);
+    get executionInstructions(): string;
+    get timeout(): {
+        defaultMs: number;
+        maxMs: number;
+    };
+    /**
+     * Fill in the working directory and deadline of a request.
+     * @param request - program, bindings and optional choices.
+     * @returns the request with a cwd and a capped deadline, or null for none.
+     * @throws When the request names a sandbox policy, a relative cwd or an invalid timeout.
+     */
+    resolve(request: PtcRunRequest): PtcRunSpec;
+    /**
+     * Run a resolved program. Its outcome is a field of the result.
+     * @param spec - what resolve returned.
+     * @returns the program's logs and its value or failure.
+     * @throws When the spec was not resolved or its bindings break the seam's rules.
+     */
+    run(spec: PtcRunSpec): Promise<PtcRunResult>;
+}
+export default MoejsPtcRuntime;

package/lib/index.js

@@ -0,0 +1,189 @@
+/**
+ * A PTC runtime for the DeepSeek Harness that runs each program in a fresh
+ * moejs runtime inside one long-lived sidecar process. A program's effects on
+ * the machine are its tool calls, which dsh's tool pipeline confines.
+ * @module dsh-ptc-moejs
+ */
+import { isAbsolute } from 'node:path';
+import { DUNDER_MEMBER, PORTABLE_RESERVED_WORDS, PtcRuntime, RESERVED_BINDING_GLOBALS, RESERVED_ERROR_MEMBERS } from '@deepseek-ai/dsh-ptc-runtime';
+import z from '@deepseek-ai/schemastery';
+import { resolveBinary } from "./binary.js";
+import { FRAME_ENVELOPE, messageOf } from "./protocol.js";
+import { Sidecar } from "./sidecar.js";
+/** The defaults, with the Node runtime's 120 s and 600 s deadlines. */
+export const MoejsConfig = z.object({
+    timeoutMs: z.number().default(120_000).description('Default elapsed deadline of a run in milliseconds, tool calls included.'),
+    maxTimeoutMs: z.number().default(600_000).description('Largest deadline a run may request, in milliseconds.'),
+    memoryLimitMb: z.number().default(512).description('MiB one run may allocate in total, garbage included, before it is stopped.'),
+    maxLogBytes: z.number().default(16 * 1024 * 1024).description('Bytes of serialized logs a run keeps; capture stops at the budget.'),
+    maxValueBytes: z.number().default(16 * 1024 * 1024).description('Bytes of serialized completion value; a larger value fails as output-limit.'),
+    maxPendingCalls: z.number().default(128).description('Tool calls one run may have in flight at once.'),
+    maxFrameBytes: z.number().default(64 * 1024 * 1024).description('Bytes of one frame between host and sidecar: a program, a tool result or tool arguments.'),
+});
+/** setTimeout's largest delay. */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** A frame becomes one JavaScript string, so it stays well below V8's string limit. */
+const MAX_FRAME_BYTES = 512 * 1024 * 1024;
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Fill in defaults and validate the configuration.
+ * @param config - configuration as given.
+ * @returns the complete configuration.
+ * @throws When a value is out of range.
+ */
+export function resolveConfig(config = {}) {
+    const resolved = MoejsConfig(config);
+    for (const [key, value] of Object.entries(resolved)) {
+        if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+            throw new Error(`dsh-ptc-moejs: ${key} must be a positive finite number`);
+        }
+    }
+    for (const key of ['timeoutMs', 'maxTimeoutMs']) {
+        if (resolved[key] > MAX_TIMER_DELAY_MS)
+            throw new Error(`dsh-ptc-moejs: ${key} must be at most ${MAX_TIMER_DELAY_MS}`);
+    }
+    for (const key of ['memoryLimitMb', 'maxLogBytes', 'maxValueBytes', 'maxPendingCalls', 'maxFrameBytes']) {
+        if (!Number.isSafeInteger(resolved[key]))
+            throw new Error(`dsh-ptc-moejs: ${key} must be an integer`);
+    }
+    if (!Number.isSafeInteger(resolved.memoryLimitMb * 1024 * 1024))
+        throw new Error('dsh-ptc-moejs: memoryLimitMb is too large');
+    if (resolved.maxFrameBytes > MAX_FRAME_BYTES)
+        throw new Error(`dsh-ptc-moejs: maxFrameBytes must be at most ${MAX_FRAME_BYTES}`);
+    for (const key of ['maxLogBytes', 'maxValueBytes']) {
+        if (resolved[key] > resolved.maxFrameBytes - FRAME_ENVELOPE) {
+            throw new Error(`dsh-ptc-moejs: ${key} must fit in a frame: at most maxFrameBytes - ${FRAME_ENVELOPE}`);
+        }
+    }
+    return resolved;
+}
+/**
+ * Validate the binding namespaces of a request and read each function once.
+ * Names follow the rules dsh shares across PTC runtimes, so a namespace list
+ * valid here is valid on every runtime.
+ * @param bindings - the request's namespaces.
+ * @returns the namespaces keyed by their global.
+ * @throws When a name is unusable, reserved or used twice.
+ */
+export function validateBindings(bindings) {
+    const namespaces = new Map();
+    const injected = new Set();
+    const claim = (name, role) => {
+        if (typeof name !== 'string' || !IDENTIFIER.test(name) || PORTABLE_RESERVED_WORDS.has(name)) {
+            throw new Error(`dsh-ptc-moejs: ${role} ${JSON.stringify(name)} is not a usable identifier`);
+        }
+        if (RESERVED_BINDING_GLOBALS.has(name))
+            throw new Error(`dsh-ptc-moejs: reserved binding global ${JSON.stringify(name)}`);
+        if (injected.has(name))
+            throw new Error(`dsh-ptc-moejs: duplicate injected global ${JSON.stringify(name)}`);
+        injected.add(name);
+        return name;
+    };
+    for (const namespace of bindings) {
+        const global = claim(namespace.global, 'binding global');
+        let errorClass;
+        if (namespace.errorClass !== undefined) {
+            const name = claim(namespace.errorClass.name, 'binding error class');
+            const member = namespace.errorClass.memberNameProperty;
+            if (typeof member !== 'string' || member.length === 0 || RESERVED_ERROR_MEMBERS.has(member) || DUNDER_MEMBER.test(member)) {
+                throw new Error(`dsh-ptc-moejs: binding error member property ${JSON.stringify(member)} is not usable`);
+            }
+            errorClass = { name, memberNameProperty: member };
+        }
+        // Null prototype: `__proto__` and `constructor` are ordinary names.
+        const functions = Object.create(null);
+        for (const name of Object.keys(namespace.functions)) {
+            const fn = namespace.functions[name];
+            if (typeof fn === 'function')
+                Object.defineProperty(functions, name, { value: fn, enumerable: true });
+        }
+        namespaces.set(global, { global, functions, ...errorClass === undefined ? {} : { errorClass } });
+    }
+    return namespaces;
+}
+/** The moejs PTC runtime: `ctx.ptcRuntime` backed by one moejs-ptc sidecar. */
+export class MoejsPtcRuntime extends PtcRuntime {
+    static Config = MoejsConfig;
+    language = 'typescript';
+    isolation = 'process';
+    config;
+    sidecar;
+    disposed = false;
+    constructor(ctx, config) {
+        super(ctx);
+        this.config = resolveConfig(config);
+        const budgets = {
+            memoryLimitBytes: this.config.memoryLimitMb * 1024 * 1024,
+            maxLogBytes: this.config.maxLogBytes,
+            maxValueBytes: this.config.maxValueBytes,
+            maxPendingCalls: this.config.maxPendingCalls,
+            maxFrameBytes: this.config.maxFrameBytes,
+        };
+        this.sidecar = new Sidecar(resolveBinary(), budgets);
+        ctx.effect(() => {
+            this.sidecar.start();
+            return async () => {
+                this.disposed = true;
+                await this.sidecar.close('runtime disposed');
+            };
+        }, 'moejs ptc-runtime sidecar');
+    }
+    get executionInstructions() {
+        return 'The program is the body of an async TypeScript function with erasable syntax: enum and namespaces with values are syntax errors, and type annotations are not checked. '
+            + 'Top-level await and return are supported. '
+            + 'The program runs in moejs with the JavaScript standard library, the tool bindings and console.log, info, warn, error and debug. '
+            + 'Node APIs, require, import, process, timers and direct file or network access are absent: use the tools for files, commands and the network. '
+            + 'run_code takes no sandbox_permissions or justification with this runtime. '
+            + 'When the sandbox denies a tool call, retry that call with sandbox_permissions and justification in its own arguments. The user approves each such call. '
+            + 'Emit output with console.log(...) or return a lossless JSON value: plain objects, arrays, strings, finite numbers, booleans and null. '
+            + 'Only printed values and the returned value become program output. '
+            + `Each call starts a fresh runtime that may allocate ${this.config.memoryLimitMb} MiB in total, and variables from earlier calls are gone.`;
+    }
+    get timeout() {
+        return { defaultMs: Math.min(this.config.timeoutMs, this.config.maxTimeoutMs), maxMs: this.config.maxTimeoutMs };
+    }
+    /**
+     * Fill in the working directory and deadline of a request.
+     * @param request - program, bindings and optional choices.
+     * @returns the request with a cwd and a capped deadline, or null for none.
+     * @throws When the request names a sandbox policy, a relative cwd or an invalid timeout.
+     */
+    resolve(request) {
+        if (this.disposed)
+            throw new Error('dsh-ptc-moejs: resolve after disposal');
+        if (request.sandboxPolicy !== undefined) {
+            throw new Error('dsh-ptc-moejs rejects an explicit sandboxPolicy: its programs reach files through tools, which apply their own policy');
+        }
+        const cwd = request.cwd ?? process.cwd();
+        if (!isAbsolute(cwd))
+            throw new Error('dsh-ptc-moejs: cwd must be absolute');
+        const requested = request.timeoutMs;
+        if (requested !== undefined && requested !== null && (!Number.isFinite(requested) || requested <= 0)) {
+            throw new Error('dsh-ptc-moejs: timeoutMs must be a positive finite number');
+        }
+        const timeoutMs = requested === null ? null : Math.min(requested ?? this.config.timeoutMs, this.config.maxTimeoutMs);
+        return { ...request, cwd, timeoutMs };
+    }
+    /**
+     * Run a resolved program. Its outcome is a field of the result.
+     * @param spec - what resolve returned.
+     * @returns the program's logs and its value or failure.
+     * @throws When the spec was not resolved or its bindings break the seam's rules.
+     */
+    async run(spec) {
+        if (this.disposed)
+            throw new Error('dsh-ptc-moejs: run after disposal');
+        if (spec.sandboxPolicy !== undefined)
+            throw new Error('dsh-ptc-moejs: this runtime rejects an explicit sandboxPolicy');
+        const timeout = spec.timeoutMs;
+        if (typeof spec.program !== 'string' || !isAbsolute(spec.cwd)
+            || (timeout !== null && (!Number.isFinite(timeout) || timeout <= 0 || timeout > this.config.maxTimeoutMs))) {
+            throw new Error('dsh-ptc-moejs: run requires a resolved program, cwd and timeout');
+        }
+        const namespaces = validateBindings(spec.bindings);
+        if (spec.signal?.aborted === true)
+            return { logs: [], error: { kind: 'abort', message: messageOf(spec.signal.reason) } };
+        return await this.sidecar.execute(spec.program, namespaces, { timeoutMs: timeout, signal: spec.signal });
+    }
+}
+export default MoejsPtcRuntime;

package/lib/protocol.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The host side of the sidecar protocol: validation of every frame the
+ * sidecar sends, the log ledger, and the result of a run. Frame shapes are
+ * described in the sidecar's package documentation (internal/sidecar).
+ * @module dsh-ptc-moejs/protocol
+ */
+import type { PtcJsonValue, PtcRunFailure, PtcRunResult } from '@deepseek-ai/dsh-ptc-runtime';
+/** The wire version this host speaks. */
+export declare const PROTOCOL = 1;
+/** Bytes around a value in one frame, reserved out of the frame budget. */
+export declare const FRAME_ENVELOPE = 256;
+/** One frame from the sidecar, rebuilt field by field. */
+export type SidecarFrame = {
+    type: 'boot-ack';
+    protocol: number;
+} | {
+    type: 'call';
+    run: number;
+    id: number;
+    global: string;
+    name: string;
+    args: PtcJsonValue;
+} | {
+    type: 'log';
+    run: number;
+    text: string;
+    truncated: boolean;
+} | {
+    type: 'done';
+    run: number;
+    value?: PtcJsonValue;
+    error?: PtcRunFailure;
+};
+/**
+ * Parse and validate one line from the sidecar.
+ * @param line - one JSON line, without its newline.
+ * @returns the rebuilt frame, or a string that says what is wrong with it.
+ */
+export declare function parseFrame(line: string): SidecarFrame | string;
+/** UTF-8 bytes of the JSON text of a value, which the log and value budgets count. */
+export declare function jsonBytes(value: PtcJsonValue): number;
+/** The marker ending a diagnostic cut to its budget. */
+export declare const TRUNCATION_MARKER = "\u2026 [truncated]";
+/**
+ * Cap a diagnostic at maxBytes of serialized JSON, marker included.
+ * @param message - the failure message.
+ * @param maxBytes - the value budget, which diagnostics share.
+ * @returns the message, or a prefix of it that ends with the marker.
+ */
+export declare function capMessage(message: string, maxBytes: number): string;
+/**
+ * The logs of one run under the log budget. The budget counts the logs as
+ * dsh serializes them, a JSON array of strings. The marker line that ends a
+ * cut run is outside the budget.
+ */
+export declare class LogLedger {
+    private readonly maxBytes;
+    readonly logs: string[];
+    private left;
+    private cut;
+    constructor(maxBytes: number);
+    /** The line marking where capture stopped. */
+    static marker(maxBytes: number): string;
+    /**
+     * Admit one entry, or stop capture when it does not fit.
+     * @param text - one console line.
+     */
+    admit(text: string): void;
+    /** Stop capture and append the marker once. */
+    truncate(): void;
+}
+/**
+ * The result of a run that completed.
+ * @param ledger - the run's logs.
+ * @param value - the completion value, if any.
+ * @param maxValueBytes - the value budget.
+ * @returns the seam result, with output-limit for a value over the budget.
+ */
+export declare function successResult(ledger: LogLedger, value: PtcJsonValue | undefined, maxValueBytes: number): PtcRunResult;
+/**
+ * The result of a run that failed.
+ * @param ledger - the run's logs.
+ * @param failure - why it failed.
+ * @param maxValueBytes - the budget the message is capped at.
+ * @returns the seam result.
+ */
+export declare function failureResult(ledger: LogLedger, failure: PtcRunFailure, maxValueBytes: number): PtcRunResult;
+/** The text of an error or any thrown value. */
+export declare function messageOf(error: unknown): string;

package/lib/protocol.js

@@ -0,0 +1,180 @@
+/**
+ * The host side of the sidecar protocol: validation of every frame the
+ * sidecar sends, the log ledger, and the result of a run. Frame shapes are
+ * described in the sidecar's package documentation (internal/sidecar).
+ * @module dsh-ptc-moejs/protocol
+ */
+import { isJsonValue } from '@deepseek-ai/dsh-util-values';
+/** The wire version this host speaks. */
+export const PROTOCOL = 1;
+/** Bytes around a value in one frame, reserved out of the frame budget. */
+export const FRAME_ENVELOPE = 256;
+/** The failure kinds a done frame may carry. A timeout here is the memory budget, which the sidecar enforces. */
+const SIDECAR_KINDS = new Set(['exception', 'invalid-output', 'output-limit', 'timeout', 'protocol', 'worker-exit']);
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function positiveInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+/**
+ * Parse and validate one line from the sidecar.
+ * @param line - one JSON line, without its newline.
+ * @returns the rebuilt frame, or a string that says what is wrong with it.
+ */
+export function parseFrame(line) {
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch {
+        return 'a frame is not JSON';
+    }
+    if (!record(raw))
+        return 'a frame is not an object';
+    if (raw.type === 'boot-ack') {
+        return typeof raw.protocol === 'number' ? { type: 'boot-ack', protocol: raw.protocol } : 'invalid boot-ack frame';
+    }
+    if (!positiveInteger(raw.run))
+        return 'a frame has no valid run id';
+    const run = raw.run;
+    switch (raw.type) {
+        case 'call':
+            if (!positiveInteger(raw.id) || typeof raw.global !== 'string' || typeof raw.name !== 'string')
+                return 'invalid call frame';
+            // JSON.parse turns "-0" into -0 and "1e400" into Infinity, and isJsonValue rejects both.
+            if (!Object.hasOwn(raw, 'args') || !isJsonValue(raw.args))
+                return 'call arguments are not lossless JSON';
+            return { type: 'call', run, id: raw.id, global: raw.global, name: raw.name, args: raw.args };
+        case 'log':
+            if (typeof raw.text !== 'string')
+                return 'invalid log frame';
+            return { type: 'log', run, text: raw.text, truncated: raw.truncated === true };
+        case 'done': {
+            const hasValue = Object.hasOwn(raw, 'value');
+            if (hasValue && !isJsonValue(raw.value))
+                return 'a completion value is not lossless JSON';
+            if (raw.error === undefined) {
+                return hasValue ? { type: 'done', run, value: raw.value } : { type: 'done', run };
+            }
+            const error = raw.error;
+            if (hasValue || !record(error) || typeof error.message !== 'string' || typeof error.kind !== 'string' || !SIDECAR_KINDS.has(error.kind)) {
+                return 'invalid done frame';
+            }
+            return { type: 'done', run, error: { kind: error.kind, message: error.message } };
+        }
+        default:
+            return 'a frame has an unknown type';
+    }
+}
+/** UTF-8 bytes of the JSON text of a value, which the log and value budgets count. */
+export function jsonBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value), 'utf8');
+}
+/** The marker ending a diagnostic cut to its budget. */
+export const TRUNCATION_MARKER = '… [truncated]';
+/**
+ * Cap a diagnostic at maxBytes of serialized JSON, marker included.
+ * @param message - the failure message.
+ * @param maxBytes - the value budget, which diagnostics share.
+ * @returns the message, or a prefix of it that ends with the marker.
+ */
+export function capMessage(message, maxBytes) {
+    if (message.length * 6 + 2 <= maxBytes || jsonBytes(message) <= maxBytes)
+        return message;
+    let low = 0;
+    let high = Math.min(message.length, maxBytes);
+    // The longest prefix whose JSON, with the marker, fits.
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (jsonBytes(message.slice(0, middle) + TRUNCATION_MARKER) <= maxBytes)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    let end = low;
+    // Never split a surrogate pair.
+    const code = message.charCodeAt(end - 1);
+    if (end > 0 && code >= 0xd800 && code <= 0xdbff)
+        end -= 1;
+    return message.slice(0, end) + TRUNCATION_MARKER;
+}
+/**
+ * The logs of one run under the log budget. The budget counts the logs as
+ * dsh serializes them, a JSON array of strings. The marker line that ends a
+ * cut run is outside the budget.
+ */
+export class LogLedger {
+    maxBytes;
+    logs = [];
+    left;
+    cut = false;
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+        // Each entry pays for its JSON string and the "[" or "," before it, so
+        // one byte stays for the closing "]".
+        this.left = maxBytes - 1;
+    }
+    /** The line marking where capture stopped. */
+    static marker(maxBytes) {
+        return `[dsh-ptc-moejs] log capture truncated at ${maxBytes} bytes`;
+    }
+    /**
+     * Admit one entry, or stop capture when it does not fit.
+     * @param text - one console line.
+     */
+    admit(text) {
+        if (this.cut)
+            return;
+        const cost = text.length + 3 > this.left ? undefined : jsonBytes(text) + 1;
+        if (cost === undefined || cost > this.left) {
+            this.truncate();
+            return;
+        }
+        this.left -= cost;
+        this.logs.push(text);
+    }
+    /** Stop capture and append the marker once. */
+    truncate() {
+        if (this.cut)
+            return;
+        this.cut = true;
+        this.logs.push(LogLedger.marker(this.maxBytes));
+    }
+}
+/**
+ * The result of a run that completed.
+ * @param ledger - the run's logs.
+ * @param value - the completion value, if any.
+ * @param maxValueBytes - the value budget.
+ * @returns the seam result, with output-limit for a value over the budget.
+ */
+export function successResult(ledger, value, maxValueBytes) {
+    if (value === undefined)
+        return { logs: ledger.logs };
+    if (jsonBytes(value) > maxValueBytes) {
+        return { logs: ledger.logs, error: { kind: 'output-limit', message: `completion value exceeded ${maxValueBytes} bytes` } };
+    }
+    return { logs: ledger.logs, value };
+}
+/**
+ * The result of a run that failed.
+ * @param ledger - the run's logs.
+ * @param failure - why it failed.
+ * @param maxValueBytes - the budget the message is capped at.
+ * @returns the seam result.
+ */
+export function failureResult(ledger, failure, maxValueBytes) {
+    return { logs: ledger.logs, error: { kind: failure.kind, message: capMessage(failure.message, maxValueBytes) } };
+}
+/** The text of an error or any thrown value. */
+export function messageOf(error) {
+    if (error instanceof Error)
+        return error.message;
+    try {
+        return String(error);
+    }
+    catch {
+        return 'unrenderable error';
+    }
+}

package/lib/sidecar.d.ts

@@ -0,0 +1,60 @@
+/**
+ * One long-lived moejs-ptc process and the runs in flight on it. Each run is
+ * a fresh moejs runtime inside the process. The host keeps the deadlines,
+ * aborts and binding calls, and validates every frame the process sends.
+ * @module dsh-ptc-moejs/sidecar
+ */
+import type { PtcBindingErrorClass, PtcBindingFunction, PtcRunResult } from '@deepseek-ai/dsh-ptc-runtime';
+/** The budgets the sidecar enforces, sent in its boot frame. */
+export interface Budgets {
+    memoryLimitBytes: number;
+    maxLogBytes: number;
+    maxValueBytes: number;
+    maxPendingCalls: number;
+    maxFrameBytes: number;
+}
+/** A binding namespace after validation: its functions read once. */
+export interface Namespace {
+    global: string;
+    functions: Record<string, PtcBindingFunction>;
+    errorClass?: PtcBindingErrorClass;
+}
+/** Options of one execution. */
+export interface ExecuteOptions {
+    timeoutMs: number | null;
+    signal?: AbortSignal | undefined;
+}
+/** The moejs-ptc process of one provider instance. */
+export declare class Sidecar {
+    private readonly binary;
+    private readonly budgets;
+    private child;
+    private exited;
+    private readonly runs;
+    private nextRun;
+    private booted;
+    private partial;
+    private partialBytes;
+    private stderrTail;
+    private closed;
+    constructor(binary: string, budgets: Budgets);
+    /** Start the process now rather than on the first run. */
+    start(): void;
+    /**
+     * Run one program and settle with its result.
+     * @param program - the program text.
+     * @param namespaces - the validated bindings, keyed by global.
+     * @param options - deadline and cancellation.
+     * @returns the program's logs and outcome.
+     */
+    execute(program: string, namespaces: Map<string, Namespace>, options: ExecuteOptions): Promise<PtcRunResult>;
+    /** Abort every run, end the process and wait until it has exited. */
+    close(reason: string): Promise<void>;
+    private send;
+    /** The process ended or broke: fail its runs; the next run starts a new one. */
+    private lost;
+    private onData;
+    private onLine;
+    /** An idle sidecar does not keep the host process alive. */
+    private updateRef;
+}

package/lib/sidecar.js

@@ -0,0 +1,282 @@
+/**
+ * One long-lived moejs-ptc process and the runs in flight on it. Each run is
+ * a fresh moejs runtime inside the process. The host keeps the deadlines,
+ * aborts and binding calls, and validates every frame the process sends.
+ * @module dsh-ptc-moejs/sidecar
+ */
+import { spawn } from 'node:child_process';
+import { snapshotJsonValue } from '@deepseek-ai/dsh-util-values';
+import { FRAME_ENVELOPE, LogLedger, PROTOCOL, capMessage, failureResult, messageOf, parseFrame, successResult } from "./protocol.js";
+/** How long a closing process may take before it is killed. */
+const CLOSE_GRACE_MS = 2_000;
+/** How much of the process's stderr a worker-exit message quotes. */
+const STDERR_TAIL = 4_096;
+const fatalUtf8 = new TextDecoder('utf-8', { fatal: true });
+/** One run on the sidecar: its logs, its calls and how it ends. */
+class Execution {
+    id;
+    namespaces;
+    budgets;
+    send;
+    ledger;
+    result;
+    settle;
+    settled = false;
+    nextCall = 1;
+    pending = 0;
+    constructor(id, namespaces, budgets, send) {
+        this.id = id;
+        this.namespaces = namespaces;
+        this.budgets = budgets;
+        this.send = send;
+        this.ledger = new LogLedger(budgets.maxLogBytes);
+        this.result = new Promise((resolve) => { this.settle = resolve; });
+    }
+    get done() { return this.settled; }
+    finish(result) {
+        if (this.settled)
+            return;
+        this.settled = true;
+        this.settle(result);
+    }
+    fail(failure) {
+        this.finish(failureResult(this.ledger, failure, this.budgets.maxValueBytes));
+    }
+    /** Stop the program on the sidecar and settle with the failure. */
+    stop(failure) {
+        if (this.settled)
+            return;
+        this.fail(failure);
+        this.send(JSON.stringify({ type: 'cancel', run: this.id }));
+    }
+    handle(frame) {
+        switch (frame.type) {
+            case 'log':
+                if (frame.truncated)
+                    this.ledger.truncate();
+                else
+                    this.ledger.admit(frame.text);
+                return;
+            case 'done':
+                if (frame.error !== undefined)
+                    this.fail(frame.error);
+                else
+                    this.finish(successResult(this.ledger, frame.value, this.budgets.maxValueBytes));
+                return;
+            case 'call':
+                this.call(frame);
+        }
+    }
+    call(frame) {
+        const functions = this.namespaces.get(frame.global)?.functions;
+        const fn = functions !== undefined && Object.hasOwn(functions, frame.name) ? functions[frame.name] : undefined;
+        const problem = frame.id !== this.nextCall ? `call ${frame.id} arrived out of sequence`
+            : fn === undefined ? `a call named the undeclared binding ${frame.global}.${frame.name}`
+                : this.pending >= this.budgets.maxPendingCalls ? `more than ${this.budgets.maxPendingCalls} calls were pending` : undefined;
+        if (problem !== undefined || fn === undefined) {
+            this.stop({ kind: 'protocol', message: `invalid call from the moejs sidecar: ${problem}` });
+            return;
+        }
+        this.nextCall += 1;
+        this.pending += 1;
+        void this.reply(frame.id, fn, frame.args).then((line) => {
+            this.pending -= 1;
+            if (!this.settled)
+                this.send(line);
+        });
+    }
+    async reply(id, fn, args) {
+        try {
+            const value = snapshotJsonValue(await fn(args));
+            if (value === undefined)
+                throw new Error('binding resolution must be lossless JSON');
+            const text = JSON.stringify(value);
+            const limit = this.budgets.maxFrameBytes - FRAME_ENVELOPE;
+            if (Buffer.byteLength(text, 'utf8') > limit)
+                throw new Error(`binding resolution exceeds ${limit} bytes of JSON`);
+            return `{"type":"reply","run":${this.id},"id":${id},"ok":true,"value":${text}}`;
+        }
+        catch (error) {
+            // The cap keeps the reply inside one frame.
+            return JSON.stringify({ type: 'reply', run: this.id, id, ok: false, message: capMessage(messageOf(error), this.budgets.maxValueBytes) });
+        }
+    }
+}
+/** The moejs-ptc process of one provider instance. */
+export class Sidecar {
+    binary;
+    budgets;
+    child;
+    exited = Promise.resolve();
+    runs = new Map();
+    nextRun = 1;
+    booted = false;
+    partial = [];
+    partialBytes = 0;
+    stderrTail = '';
+    closed = false;
+    constructor(binary, budgets) {
+        this.binary = binary;
+        this.budgets = budgets;
+    }
+    /** Start the process now rather than on the first run. */
+    start() {
+        if (this.child !== undefined || this.closed)
+            return;
+        const child = spawn(this.binary, [], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+        this.child = child;
+        this.booted = false;
+        this.partial = [];
+        this.partialBytes = 0;
+        this.stderrTail = '';
+        let markExited;
+        this.exited = new Promise((resolve) => { markExited = resolve; });
+        child.stdout.on('data', (chunk) => { this.onData(child, chunk); });
+        child.stderr.on('data', (chunk) => {
+            this.stderrTail = (this.stderrTail + chunk.toString('utf8')).slice(-STDERR_TAIL);
+        });
+        // A write to a process that died fails here. Its exit settles the runs.
+        child.stdin.on('error', () => { });
+        child.on('error', (error) => {
+            this.lost(child, { kind: 'worker-exit', message: `the moejs sidecar could not run: ${error.message}` });
+            markExited();
+        });
+        child.on('exit', (code, signal) => {
+            const stderr = this.stderrTail.trim();
+            const how = signal === null ? `with code ${code}` : `on signal ${signal}`;
+            this.lost(child, { kind: 'worker-exit', message: `the moejs sidecar exited ${how}${stderr === '' ? '' : `: ${stderr}`}` });
+            markExited();
+        });
+        child.stdin.write(JSON.stringify({ type: 'boot', protocol: PROTOCOL, ...this.budgets }) + '\n');
+        this.updateRef();
+    }
+    /**
+     * Run one program and settle with its result.
+     * @param program - the program text.
+     * @param namespaces - the validated bindings, keyed by global.
+     * @param options - deadline and cancellation.
+     * @returns the program's logs and outcome.
+     */
+    execute(program, namespaces, options) {
+        const run = new Execution(this.nextRun++, namespaces, this.budgets, line => this.send(line));
+        if (this.closed) {
+            run.fail({ kind: 'abort', message: 'runtime disposed' });
+            return run.result;
+        }
+        this.start();
+        const frame = JSON.stringify({
+            type: 'run',
+            run: run.id,
+            program,
+            namespaces: [...namespaces.values()].map(ns => ({
+                global: ns.global,
+                names: Object.keys(ns.functions),
+                ...ns.errorClass === undefined ? {} : { errorClass: ns.errorClass },
+            })),
+        });
+        if (Buffer.byteLength(frame, 'utf8') > this.budgets.maxFrameBytes) {
+            run.fail({ kind: 'exception', message: `the program and its bindings exceed ${this.budgets.maxFrameBytes} bytes (maxFrameBytes)` });
+            return run.result;
+        }
+        this.runs.set(run.id, run);
+        const timer = options.timeoutMs === null ? undefined : setTimeout(() => {
+            run.stop({ kind: 'timeout', message: `execution deadline reached (${options.timeoutMs}ms)` });
+        }, options.timeoutMs);
+        const signal = options.signal;
+        const onAbort = () => { run.stop({ kind: 'abort', message: messageOf(signal?.reason) }); };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        this.send(frame);
+        this.updateRef();
+        return run.result.finally(() => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            this.runs.delete(run.id);
+            this.updateRef();
+        });
+    }
+    /** Abort every run, end the process and wait until it has exited. */
+    async close(reason) {
+        this.closed = true;
+        for (const run of this.runs.values())
+            run.stop({ kind: 'abort', message: reason });
+        const child = this.child;
+        const killer = child === undefined ? undefined : setTimeout(() => { child.kill('SIGKILL'); }, CLOSE_GRACE_MS);
+        child?.stdin.end();
+        await this.exited;
+        clearTimeout(killer);
+    }
+    send(line) {
+        this.child?.stdin.write(line + '\n');
+    }
+    /** The process ended or broke: fail its runs; the next run starts a new one. */
+    lost(child, failure) {
+        if (this.child !== child)
+            return;
+        this.child = undefined;
+        for (const run of this.runs.values())
+            run.fail(failure);
+        if (child.exitCode === null && child.signalCode === null)
+            child.kill('SIGKILL');
+    }
+    onData(child, chunk) {
+        let start = 0;
+        for (let newline = chunk.indexOf(10); newline !== -1; newline = chunk.indexOf(10, start)) {
+            const piece = chunk.subarray(start, newline);
+            const line = this.partial.length === 0 ? piece : Buffer.concat([...this.partial, piece]);
+            this.partial = [];
+            this.partialBytes = 0;
+            start = newline + 1;
+            this.onLine(child, line);
+            if (this.child !== child)
+                return;
+        }
+        if (start < chunk.length) {
+            this.partialBytes += chunk.length - start;
+            if (this.partialBytes > this.budgets.maxFrameBytes) {
+                this.lost(child, { kind: 'protocol', message: `the moejs sidecar sent a frame longer than ${this.budgets.maxFrameBytes} bytes` });
+                return;
+            }
+            this.partial.push(Buffer.from(chunk.subarray(start)));
+        }
+    }
+    onLine(child, bytes) {
+        let frame;
+        try {
+            frame = parseFrame(fatalUtf8.decode(bytes));
+        }
+        catch {
+            frame = 'a frame is not valid UTF-8';
+        }
+        if (typeof frame !== 'string' && frame.type === 'boot-ack') {
+            if (frame.protocol === PROTOCOL && !this.booted) {
+                this.booted = true;
+                return;
+            }
+            frame = this.booted ? 'a second boot-ack' : `the sidecar speaks protocol ${frame.protocol}, this host ${PROTOCOL}`;
+        }
+        else if (!this.booted) {
+            frame = 'a frame came before the boot-ack';
+        }
+        if (typeof frame === 'string') {
+            this.lost(child, { kind: 'protocol', message: `invalid frame from the moejs sidecar: ${frame}` });
+            return;
+        }
+        // A cancel can cross a run's frames on the wire, so frames of a run that has ended are dropped.
+        const run = this.runs.get(frame.run);
+        if (run !== undefined && !run.done)
+            run.handle(frame);
+    }
+    /** An idle sidecar does not keep the host process alive. */
+    updateRef() {
+        const child = this.child;
+        if (child === undefined)
+            return;
+        const busy = this.runs.size > 0;
+        for (const handle of [child, child.stdout, child.stderr, child.stdin]) {
+            if (busy)
+                handle.ref();
+            else
+                handle.unref();
+        }
+    }
+}

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "dsh-ptc-moejs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "PTC runtime for the DeepSeek Harness that runs model-written programs in moejs, a pure-Go JavaScript engine, inside one long-lived sidecar process",
+  "keywords": [
+    "dsh-plugin",
+    "dsh",
+    "deepseek-harness",
+    "ptc",
+    "moejs",
+    "javascript",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Calcium-Ion/dsh-ptc-moejs.git"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.zh_CN.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": ">=0.2.1-rc.2 <0.3.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-ptc-runtime": ">=0.2.1-rc.2 <0.3.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-util-values": ">=0.2.1-rc.2 <0.3.0",
+    "@deepseek-ai/schemastery": "~3.18.5"
+  },
+  "optionalDependencies": {
+    "dsh-ptc-moejs-darwin-arm64": "0.1.0",
+    "dsh-ptc-moejs-darwin-x64": "0.1.0",
+    "dsh-ptc-moejs-linux-arm64": "0.1.0",
+    "dsh-ptc-moejs-linux-x64": "0.1.0",
+    "dsh-ptc-moejs-win32-x64": "0.1.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.1-rc.2",
+    "@types/node": "^22.20.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:sidecar": "node scripts/build-binaries.mjs --host",
+    "build:binaries": "node scripts/build-binaries.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:go": "go test ./...",
+    "e2e": "node e2e/run.mjs",
+    "bench": "node bench/bench.mjs"
+  }
 }