dsh-ptc-moejs 0.1.0 → 0.1.2

package/README.md

@@ -1,10 +1,63 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Calcium-Ion/moejs/main/docs/assets/moejs-logo.svg" width="160" alt="moejs">
+
 # dsh-ptc-moejs
 
-[简体中文](README.zh_CN.md)
+A PTC runtime for the DeepSeek Harness that runs the model's programs in moejs, a JavaScript engine written in Go.
+
+<p align="center">
+  <a href="./README.zh_CN.md">简体中文</a> |
+  <strong>English</strong>
+</p>
+
+</div>
+
+In the PTC mode of the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh), the model answers with a TypeScript program that calls tools. This runtime runs each program in a fresh [moejs](https://github.com/Calcium-Ion/moejs) runtime inside one sidecar process that stays up between programs. A program with three tool calls takes 0.18 ms here, and 95 ms on dsh's Node runtime, which starts a Node process for every program.
+
+Everything a program does to the machine is a tool call, which dsh runs with that tool's own policy, approvals and sandbox. A run stops at its deadline, even in an endless loop, and when it goes past its memory budget. The sidecar is a static Go binary that dsh starts as a plain child process, so the runtime also works in containers where bubblewrap cannot run.
+
+## Performance
+
+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.
+
+| 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.
+
+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, which stayed within 0.16 to 0.20 ms for moejs and within 90 to 96 ms for Node.
+
+## Features
+
+### Every effect is a tool call
+
+A program can call the tools dsh gives it and write to `console`. To read a file, run a command or fetch a page, it calls a tool, and dsh runs that call through its tool pipeline with the tool's own policy, approvals and sandbox, as it does for the Node runtime. dsh's session log records each call.
+
+### A fresh runtime for every run
+
+The sidecar starts when the plugin loads and keeps running. Each run gets its own moejs runtime, so every program starts from clean globals, and one sidecar can have several runs in flight at once.
 
-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.
+### Limits on every run
 
-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.
+A run may allocate 512 MiB by default, garbage included. A deadline, an abort from dsh or a profile shutdown stops a run at once. Console output, the returned value and each message to the sidecar have their own size caps, listed under [Configuration](#configuration).
+
+### TypeScript as on the Node runtime
+
+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. A program is the body of an async function, so `await` and `return` work at its top level.
+
+### One static binary
+
+The sidecar is a self-contained Go binary built with `CGO_ENABLED=0`. dsh starts it as a plain child process, and starting that process is all the runtime asks of the host. The package manager installs the binary for your platform as an optional dependency.
+
+## Differences from the Node runtime
+
+Programs get the JavaScript standard library and the tools. `require`, `import`, `process`, `Buffer`, `fs` and `setTimeout` are undefined in a program, and 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.
+
+Every file access of a program happens inside a tool call, and dsh rejects a `run_code` call that carries `sandbox_permissions`. When the file sandbox denies a tool call, the program retries that call with `sandbox_permissions` and `justification` among its arguments, and you approve each such call. On the Node runtime, one approval can also cover the file operations a program does itself through Node APIs.
 
 ## Quick start
 
@@ -54,21 +107,11 @@ Options go on the `ptc-moejs` row of the same patch:
 
 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.
+A program is the body of an async function. Its 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`. The rest is the JavaScript standard library, which in moejs includes `TextEncoder`, `TextDecoder`, `atob`, `btoa`, `structuredClone` and `queueMicrotask`.
 
-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:
+The model writes a program like this one, and the runtime hands the returned value to dsh:
 
 ```ts
 const head = await tools.bash({ description: "Read the last commit", command: "git log -1 --oneline" });
@@ -87,18 +130,6 @@ The returned value goes back to dsh as lossless JSON: plain objects, arrays, str
 | `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.
@@ -107,7 +138,7 @@ A call is one `resolve` and `run`, from the program text to the result. Load to
 - `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.
+- CI runs the tests on Linux x64, Linux arm64, macOS arm64 and Windows x64 for every push. macOS x64 is untested: its binary is cross-compiled from the same source.
 
 ## Development
 

package/README.zh_CN.md

@@ -1,12 +1,65 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Calcium-Ion/moejs/main/docs/assets/moejs-logo.svg" width="160" alt="moejs">
+
 # dsh-ptc-moejs
 
-[English](README.md)
+DeepSeek Harness 的 PTC 运行时，用 Go 写的 JavaScript 引擎 moejs 运行模型写的程序。
+
+<p align="center">
+  <strong>简体中文</strong> |
+  <a href="./README.md">English</a>
+</p>
+
+</div>
+
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）的 PTC 模式下，模型给出一段调用工具的 TypeScript 程序。这个运行时让一个 sidecar 进程常驻，每段程序在里面拿到一个新的 [moejs](https://github.com/Calcium-Ion/moejs) 运行时。调用三次工具的程序在这里用时 0.18 ms。dsh 的 Node 运行时每段程序都要启动一个 Node 进程，同样的程序用时 95 ms。
+
+程序对机器做的每件事都是一次工具调用，dsh 按该工具自己的策略、审批和沙箱执行这次调用。运行到了截止时间就会停下，死循环里也一样，分配的内存超过预算时也会停下。sidecar 是静态链接的 Go 程序，dsh 把它当作普通子进程启动，所以在无法运行 bubblewrap 的容器里也能用。
+
+## 性能
+
+两个运行时通过 dsh 的 `PtcRuntime` 服务接口运行同一段程序：三次工具调用，每次由绑定函数立即返回，最后返回一个对象。
+
+| 运行时 | 每次调用 | 从加载到第一个结果 |
+|---|--:|--:|
+| 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 下直接启动。
+
+每一轮里，每个运行时都在新的 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。表中是各轮中位数的中位数，moejs 的各轮中位数在 0.16 到 0.20 ms 之间，Node 在 90 到 96 ms 之间。
+
+## 功能
+
+### 对机器的每次操作都是工具调用
+
+程序能调用 dsh 提供的工具，能向 `console` 输出。读文件、执行命令、抓取网页都要调用工具，dsh 用工具流水线执行这次调用，由该工具自己的策略、审批和沙箱处理，和 Node 运行时一样。dsh 的会话日志记录每一次调用。
+
+### 每次运行一个新运行时
+
+sidecar 在插件加载时启动，之后一直运行。每次运行拿到自己的 moejs 运行时，每段程序都从干净的全局环境开始，同一个 sidecar 里可以同时进行多次运行。
 
-[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 的容器里也能用。
+一次运行默认可以分配 512 MiB，垃圾也算在内。截止时间到了、dsh 中止或者 profile 关闭时，运行立即停止。console 输出、返回值和发给 sidecar 的每条消息各有大小上限，见[配置](#配置)。
 
-## 快速开始
+### 和 Node 运行时一样的 TypeScript
+
+程序是只用可擦除语法的 TypeScript，规则和 dsh 的 Node 运行时相同：类型标注被删掉，`enum`、带值的 namespace 和参数属性都是语法错误。程序是一个 async 函数的函数体，顶层可以用 `await` 和 `return`。
+
+### 一个静态程序
+
+sidecar 是用 `CGO_ENABLED=0` 构建的自包含 Go 程序。dsh 把它当作普通子进程启动，运行时对宿主机的要求就是能启动这个进程。包管理器以可选依赖的形式安装对应平台的程序。
+
+## 和 Node 运行时的区别
+
+程序能用 JavaScript 标准库和工具。`require`、`import`、`process`、`Buffer`、`fs` 和 `setTimeout` 在程序里都是 undefined，程序要读文件时调用 `read` 工具。如果你的程序要用 Node API，这个 profile 继续用 dsh 的 Node 运行时。
+
+程序的每次文件访问都发生在工具调用里，带 `sandbox_permissions` 的 `run_code` 调用会被 dsh 拒绝。文件沙箱拒绝某次工具调用时，程序在这次调用的参数里带上 `sandbox_permissions` 和 `justification` 重试，每次这样的调用都要你批准。用 Node 运行时的话，程序通过 Node API 自己做的文件操作还能用一次批准全部放行。
+
+## 快速上手
 
 ```sh
 dsh plugin --profile web add dsh-ptc-moejs
@@ -54,21 +107,11 @@ dsh plugin --profile web add dsh-ptc-moejs
 
 截止时间的默认值和 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 运行时。
+程序是一个 async 函数的函数体。函数的参数有 dsh 传入的绑定命名空间（PTC 模式下是 `tools`）、每个命名空间的错误类（`ToolCallError`，`toolName` 属性里是工具名），以及带 `log`、`info`、`warn`、`error`、`debug` 的 `console`。其余是 JavaScript 标准库，moejs 的标准库里有 `TextEncoder`、`TextDecoder`、`atob`、`btoa`、`structuredClone` 和 `queueMicrotask`。
 
-程序自己没有沙箱，所以 `run_code` 不接受 `sandbox_permissions`。文件沙箱拒绝某次工具调用时，程序在这次调用的参数里带上 `sandbox_permissions` 和 `justification` 重试，每次这样的调用都要你批准。用 Node 运行时的话，程序通过 Node API 自己做的文件操作还能用一次批准全部放行。
-
-一次运行是这样的。函数体由模型写，运行时执行它，并把返回值交给 dsh：
+模型写出的程序是这样的，运行时把返回值交给 dsh：
 
 ```ts
 const head = await tools.bash({ description: "Read the last commit", command: "git log -1 --oneline" });
@@ -87,18 +130,6 @@ return { head: head.stdout?.text };
 | `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 模式）计划在以后的版本中加入。
@@ -107,7 +138,7 @@ return { head: head.stdout?.text };
 - `console` 的输出仿照 Node 的 `util.inspect`，覆盖字符串、数字、普通对象、数组、`Map`、`Set`、错误和类的实例，单行超过 72 个字符时换行。
 - moejs 的中断作用于正在运行的 JavaScript，编译一旦开始会一直进行到结束。解析很慢的程序到截止时间时，dsh 一侧照常结束这次运行，sidecar 等解析返回后丢弃它。
 - 程序没有 await 的工具调用如果失败，这个失败只留在那个没人读取的 promise 里。
-- 这个版本在 Linux x64 上测试过。其余四个平台的程序由同一份源码交叉编译。
+- CI 每次推送都在 Linux x64、Linux arm64、macOS arm64 和 Windows x64 上跑测试。macOS x64 还没测过，它的程序由同一份源码交叉编译。
 
 ## 开发
 

package/lib/binary.d.ts

@@ -5,6 +5,15 @@
  */
 /** The platforms that have a binary package. */
 export declare const PLATFORMS: readonly ["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64", "win32-x64"];
+/**
+ * Name the package that holds the sidecar binary for a platform.
+ * npm's spam filter rejects the name dsh-ptc-moejs-win32-x64, so the
+ * Windows package says "windows" where Node says "win32".
+ * @param platform - the Node platform name.
+ * @param arch - the Node architecture name.
+ * @returns the npm package name.
+ */
+export declare function binaryPackage(platform: string, arch: string): string;
 /**
  * Resolve the sidecar binary for this platform.
  * @param platform - the Node platform name.

package/lib/binary.js

@@ -6,6 +6,17 @@
 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'];
+/**
+ * Name the package that holds the sidecar binary for a platform.
+ * npm's spam filter rejects the name dsh-ptc-moejs-win32-x64, so the
+ * Windows package says "windows" where Node says "win32".
+ * @param platform - the Node platform name.
+ * @param arch - the Node architecture name.
+ * @returns the npm package name.
+ */
+export function binaryPackage(platform, arch) {
+    return `dsh-ptc-moejs-${platform === 'win32' ? 'windows' : platform}-${arch}`;
+}
 /**
  * Resolve the sidecar binary for this platform.
  * @param platform - the Node platform name.
@@ -15,7 +26,7 @@ export const PLATFORMS = ['darwin-arm64', 'darwin-x64', 'linux-arm64', 'linux-x6
  */
 export function resolveBinary(platform = process.platform, arch = process.arch) {
     const target = `${platform}-${arch}`;
-    const pkg = `dsh-ptc-moejs-${target}`;
+    const pkg = binaryPackage(platform, arch);
     try {
         return createRequire(import.meta.url).resolve(`${pkg}/bin/moejs-ptc${platform === 'win32' ? '.exe' : ''}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ptc-moejs",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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",
@@ -54,7 +54,7 @@
     "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"
+    "dsh-ptc-moejs-windows-x64": "0.1.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "~4.0.5",