{"_id":"@away_from/pth-sandbox","_rev":"6-733215f0318bdd4bfbb58dfcffc5ef59","name":"@away_from/pth-sandbox","dist-tags":{"latest":"1.7.0"},"versions":{"1.1.3":{"name":"@away_from/pth-sandbox","version":"1.1.3","_id":"@away_from/pth-sandbox@1.1.3","maintainers":[{"name":"phenol1145","email":"alexphenol0725@gmail.com"}],"dist":{"shasum":"5be5774f8f39688e5a5effa28ef4aac0fce94124","tarball":"https://registry.npmjs.org/@away_from/pth-sandbox/-/pth-sandbox-1.1.3.tgz","fileCount":69,"integrity":"sha512-cEe+/Y4MteHwnb/eCj4gvxJzIQXQheXZtYsWx4Fn0yZL0pGrAHr2Kg/hnbRhwI2fDJgQsZU62yKro93z6s+H8Q==","signatures":[{"sig":"MEYCIQCpqiMGbHb04nxaeFu48Y97PbtqXoQ3vvl0hbf6YhUDwwIhAMtpU5mTltNrXTyEPDTlDqIJNMd9u2FE0lDSEMAj7qxA","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":396712},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"015dab6f1d2e1f2d94bcfebd49b49d57b905565a","_npmUser":{"name":"phenol1145","email":"alexphenol0725@gmail.com"},"_npmVersion":"11.11.0","description":"PTH 的**沙箱域 + 内核契约/运行时** workspace 包（单仓拆分决策见 `docs/pth/split-design.md`）。","directories":{},"_nodeVersion":"24.14.1","dependencies":{"fastify":"^5.0.0","@away_from/infra":"^1.1.3","@sinclair/typebox":"^0.34.52","@away_from/pth-memory":"^1.1.3"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/pth-sandbox_1.1.3_1786966988488_0.34325350106106356","host":"s3://npm-registry-packages-npm-production"}},"1.6.0":{"name":"@away_from/pth-sandbox","version":"1.6.0","_id":"@away_from/pth-sandbox@1.6.0","maintainers":[{"name":"phenol1145","email":"alexphenol0725@gmail.com"}],"dist":{"shasum":"2698dba1d815d0b6a67183179dc160f9b927a661","tarball":"https://registry.npmjs.org/@away_from/pth-sandbox/-/pth-sandbox-1.6.0.tgz","fileCount":69,"integrity":"sha512-v51q2fz9HyS/ApJ5xgtvAxxCRtp+8pGCBWGOLeFHxjmFtIoY1XeoOchcrvQyk1WiI1jqx2uk47BkhUPHkhCpag==","signatures":[{"sig":"MEUCIF02PXHcZsZx0GkPWdBXRZD/sViXCwbmNpxKUhO8opoFAiEAh2pykZKt78VP+79CiLPvFk2l+kV5M21niXa2+OVZfqw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":395608},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"57afd5150b6d492c0b595cb94f6dfb7a52318d25","_npmUser":{"name":"phenol1145","email":"alexphenol0725@gmail.com"},"_npmVersion":"11.11.0","description":"PTH 的**沙箱域 + 内核契约/运行时** workspace 包（单仓拆分决策见 `docs/pth/split-design.md`）。","directories":{},"_nodeVersion":"24.14.1","dependencies":{"fastify":"^5.0.0","@away_from/infra":"^1.6.0","@sinclair/typebox":"^0.34.52","@away_from/pth-memory":"^1.6.0"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/pth-sandbox_1.6.0_1787359781161_0.17417514380771926","host":"s3://npm-registry-packages-npm-production"}},"1.6.1":{"name":"@away_from/pth-sandbox","version":"1.6.1","_id":"@away_from/pth-sandbox@1.6.1","maintainers":[{"name":"phenol1145","email":"alexphenol0725@gmail.com"}],"dist":{"shasum":"a90c8c2f9643a9f8c57608e7349b6ca96e55f98f","tarball":"https://registry.npmjs.org/@away_from/pth-sandbox/-/pth-sandbox-1.6.1.tgz","fileCount":72,"integrity":"sha512-6/w1tBbR4k4otw8E7b84AtpxVLA837UsUBC8tRhGpxfaVRNUEn9TEJzGWei6PAkEMdpoUuODQEFBCbKKQgE77w==","signatures":[{"sig":"MEQCIAw9mXNTWKGiZzaXklANe1+fmAghzyP8O6UerRqTJasgAiB3wJDFANELCPRjm3NEjpv4Y6QRPmMzQz0nOlK7hqBLDg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":414128},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"d7b594e4e23676b9c5a3ed62111e5db300557de1","_npmUser":{"name":"phenol1145","email":"alexphenol0725@gmail.com"},"_npmVersion":"11.11.0","description":"PTH 的**沙箱域 + 内核契约/运行时** workspace 包（单仓拆分决策见 `docs/pth/split-design.md`）。","directories":{},"_nodeVersion":"24.14.1","dependencies":{"fastify":"^5.0.0","@away_from/infra":"^1.6.0","@away_from/shared":"^1.7.4","@sinclair/typebox":"^0.34.52","@away_from/pth-memory":"file:../pth-memory"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/pth-sandbox_1.6.1_1787405938826_0.7638453763959665","host":"s3://npm-registry-packages-npm-production"}},"1.6.2":{"name":"@away_from/pth-sandbox","version":"1.6.2","_id":"@away_from/pth-sandbox@1.6.2","maintainers":[{"name":"phenol1145","email":"alexphenol0725@gmail.com"}],"dist":{"shasum":"dd88c4fe1c9d82affc29747afa8406ce094dca48","tarball":"https://registry.npmjs.org/@away_from/pth-sandbox/-/pth-sandbox-1.6.2.tgz","fileCount":72,"integrity":"sha512-QhLQCGwKQCp/cOQX3d5hFM1E+iXc50V0zS22AR8uoAqSIw1iXfSEEo+/hLknXynDnTbS5djmyXEnqoI1ZsiLKA==","signatures":[{"sig":"MEQCIDkoHZLboVRFfbAj70kst8zohAhM/EI3EG+iSy17+geaAiBOlXEa+fz7oEkkQELvBan+7fDogvX2VIZi5b9D8gHmJA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":416765},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"181b690ed90354f97d8f9dbd5ad5de7309d90982","_npmUser":{"name":"phenol1145","email":"alexphenol0725@gmail.com"},"_npmVersion":"11.11.0","description":"PTH 的**沙箱域 + 内核契约/运行时** workspace 包（单仓拆分决策见 `docs/pth/split-design.md`）。","directories":{},"_nodeVersion":"24.14.1","dependencies":{"fastify":"^5.0.0","@away_from/infra":"^1.6.0","@away_from/shared":"^1.7.4","@sinclair/typebox":"^0.34.52","@away_from/pth-memory":"file:../pth-memory"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/pth-sandbox_1.6.2_1787409251212_0.007062983275440082","host":"s3://npm-registry-packages-npm-production"}},"1.6.3":{"name":"@away_from/pth-sandbox","version":"1.6.3","_id":"@away_from/pth-sandbox@1.6.3","maintainers":[{"name":"phenol1145","email":"alexphenol0725@gmail.com"}],"dist":{"shasum":"b7d9e7be5ef3e5a566df0efc7ed89e0c24361165","tarball":"https://registry.npmjs.org/@away_from/pth-sandbox/-/pth-sandbox-1.6.3.tgz","fileCount":72,"integrity":"sha512-A/kDtDhKCQ9Ns2m1iAlsIVt9CLwpmh5nd31kul4eOxzmhPVijHJl46rJr9wVb1Pg8QphVlhxqyJClNXG/rHHDw==","signatures":[{"sig":"MEUCIE5Ifpq891uQHP/PJerrfBqCHD9mZMin3F6mj9w2h7qsAiEA+5gda3rHRQZGNbi5szMZGWKfEwFsJlpQrsqV22/g3+U=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":416710},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"603a837ec376971bf0a07c115b266a7ec4a2a9bc","_npmUser":{"name":"phenol1145","email":"alexphenol0725@gmail.com"},"_npmVersion":"11.11.0","description":"PTH 的**沙箱域 + 内核契约/运行时** workspace 包（单仓拆分决策见 `docs/pth/split-design.md`）。","directories":{},"_nodeVersion":"24.14.1","dependencies":{"fastify":"^5.0.0","@away_from/infra":"^1.6.0","@away_from/shared":"^1.7.6","@sinclair/typebox":"^0.34.52"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/pth-sandbox_1.6.3_1787413181659_0.6374987629930431","host":"s3://npm-registry-packages-npm-production"}},"1.7.0":{"name":"@away_from/pth-sandbox","version":"1.7.0","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"dependencies":{"@away_from/infra":"^1.6.0","@away_from/shared":"^1.7.6","@sinclair/typebox":"^0.34.52","fastify":"^5.0.0"},"gitHead":"911fc14991a6bf3255c53c77e4afc85871aa9bd3","_id":"@away_from/pth-sandbox@1.7.0","description":"PTH 的**沙箱域 + 内核契约/运行时** workspace 包（单仓拆分决策见 `docs/pth/split-design.md`）。","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-NE2+3RwmJUz/inLKb/Et4ue1lTLu0uZKKELupwzFFJqFInbI4QntE6r10iAY74qlmN2DjxBHPq484V1ozakI8g==","shasum":"91b013a8fc70e82948c5c73209a8463944a2117a","tarball":"https://registry.npmjs.org/@away_from/pth-sandbox/-/pth-sandbox-1.7.0.tgz","fileCount":72,"unpackedSize":417145,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGzy4nyDIqLXN4hhvCzYPR0nL2FhTMI2tiEU0OUODUiRAiBq01WYYhptvG1E2I6HPjeZRyCVjiFPkxTj8N8oVOBcUg=="}]},"_npmUser":{"name":"phenol1145","email":"alexphenol0725@gmail.com"},"directories":{},"maintainers":[{"name":"phenol1145","email":"alexphenol0725@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pth-sandbox_1.7.0_1787528540783_0.7443628725314377"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-17T11:43:08.295Z","modified":"2026-08-23T23:42:21.074Z","1.1.3":"2026-08-17T11:43:08.672Z","1.6.0":"2026-08-22T00:49:41.330Z","1.6.1":"2026-08-22T13:38:58.976Z","1.6.2":"2026-08-22T14:34:11.371Z","1.6.3":"2026-08-22T15:39:41.796Z","1.7.0":"2026-08-23T23:42:20.924Z"},"description":"PTH 的**沙箱域 + 内核契约/运行时** workspace 包（单仓拆分决策见 `docs/pth/split-design.md`）。","maintainers":[{"name":"phenol1145","email":"alexphenol0725@gmail.com"}],"readme":"# @away_from/pth-sandbox\n\nPTH 的**沙箱域 + 内核契约/运行时** workspace 包（单仓拆分决策见 `docs/pth/split-design.md`）。\n\n- 生产形态：独立 sandbox 容器（`Dockerfile.sandbox`），只挂 `sandbox-internal` 网络、无宿主机端口映射；控制器 root 仅用于 setuid，工作负载以 UID/GID 2001 运行。\n- PTH 侧通过 `http://sandbox:8080` 调用：无状态执行走 `/exec`（`sandbox-bash.ts` 客户端），持久 REPL 池走 `/kernel/*`（`SandboxKernel` 客户端）。\n- 内核 interpreter 契约（`Interpreter` / `InterpreterResult` / `WorkerKernel`）由本包稳定导出——遵守拆分裁决，不另建 contracts 包。\n\n## 命名对照（易混点）\n\n| 名称 | 形态 | 位置 | 用途 |\n|---|---|---|---|\n| `sandbox-bash.ts` | 无状态客户端 | `src/sandbox-bash.ts` | PTH 侧调 sandbox `/exec` 的转发客户端（含连续失败 → degraded 监控） |\n| `BashKernel` | 本地持久 REPL | `src/bash-kernel.ts` | `PTH_BASH_MODE=kernel` 时在 PTH 容器内运行；生产默认关闭 |\n| `PyKernel` | 本地持久 REPL | `src/py-kernel.ts` | `PTH_PYTHON_MODE=kernel` 时在 PTH 容器内运行；生产默认关闭 |\n| `sandbox-kernel.ts` | 转发代理客户端 | `src/sandbox-kernel.ts` | 生产默认：把 interpreter 接口映射到 sandbox `/kernel/*` lease 协议 |\n| `kernel-host.ts` | Fastify 宿主服务 | `src/kernel-host.ts` | sandbox 容器内：kernel 池 + lease + 编译核 + gdb + 记忆桥转发 |\n| `exec-api.ts` | Fastify 服务 | `src/exec-api.ts` | sandbox 容器内：无状态 `/exec` + SSE，私有工作区/UID 隔离 |\n\n一句话区分：**`sandbox-bash` 是\"把 bash 命令丢给沙箱执行\"的客户端；`BashKernel` 是\"本机持久 bash REPL 解释器\"；`kernel-host` 是两者背后的池化宿主服务。** 生产路径为 `sandbox-bash` + `sandbox-kernel`；本地调试才启用 `BashKernel`/`PyKernel`。\n\n## HTTP 端点\n\n### exec-api（无状态执行，任务级工作区隔离）\n\n| 方法/路径 | 说明 |\n|---|---|\n| `GET /health` | liveness（当前无条件 200；readiness 拆分见模块化 v2 P2-6） |\n| `POST /exec` | 执行 bash/python 命令或 C 编译运行；allowlist env + workload UID + `/srv/workload` 私有拷贝 |\n| `GET /exec/:id` | 任务结果查询（完成后缓存 60s） |\n| `GET /exec/:id/stream` | SSE 流式输出 |\n\n### kernel-host（持久 REPL 池，opaque lease 协议）\n\n| 方法/路径 | 说明 |\n|---|---|\n| `POST /kernel/acquire` | 返回 UUID `SandboxLease`（id+generation+expiresAt）；旧 `kernelId` 协议已退役 |\n| `POST /kernel/execute` / `reset` / `snapshot` / `release` | 全部校验 lease id+generation；release 同 lease 幂等 |\n| `POST /kernel/memory-bridge` | loopback 免密钥只读桥（body.space 被剥除，上游按 bridge token 声明过滤）；外部调用需 `SANDBOX_SHARED_SECRET` |\n| `POST /kernel/compiled` | C 编译+运行（`buildOnly` 可选），持久 cache + 并发信号量 |\n| `POST /kernel/debug/*` | gdb MI 会话（attach/breakpoint/step/continue/stack/variables/evaluate/snapshot/detach） |\n| `GET /kernel/debug/sessions` | 当前调试会话列表 |\n| `GET /kernel/status` | 池容量/指标/编译统计/调试会话 + `degraded`/`reasons`（监控面板与 `obs.kernels` 数据源） |\n\n## 环境变量\n\n| 变量 | 默认 | 说明 |\n|---|---|---|\n| `SANDBOX_SHARED_SECRET` | **compose `:?` 必填** | 控制器间认证（绝不注入 workload） |\n| `PTH_EXECUTION_GRANT_SECRET` | **compose `:?` 必填** | 执行 grant 签名密钥（与 pi-platform 同值；缺失 → acquire fail-closed） |\n| `PTH_MEMORY_BRIDGE_TOKEN` | 空 → memory-bridge fail-closed 503 | 上游 PTH 桥 Bearer token（controller-only） |\n| `PTH_BRIDGE_URL` | `http://pi-platform:3000` | 记忆桥上游 |\n| `PTH_KERNEL_POOL_SIZE` | 24 | 池容量（≥ 并发 worker ×2 建议） |\n| `PTH_KERNEL_ACQUIRE_TIMEOUT_MS` | 10000 | acquire 排队超时 |\n| `PTH_KERNEL_ENTRY_TTL_MS` | 1800000 | lease TTL；过期 `active → cancelling → disposed`，不复用 |\n| `PTH_COMPILED_CACHE_DIR` / `_MAX_MB` / `PTH_COMPILED_MAX_CACHE` | `/data/compiled-cache/c` / 200 / 50 | 编译缓存目录与磁盘/条数上限 |\n| `PTH_COMPILED_TIMEOUT_MS` / `PTH_COMPILED_CONCURRENCY` | 60000 / 4 | 编译超时与并发信号量 |\n| `PTH_DEBUG_SESSIONS` | 4 | gdb 会话数上限 |\n| `PTH_DEBUG_IDLE_MS` | 1800000 | gdb idle detach（30min） |\n| `PTH_DEBUG_WORKDIR` | `/data/workspaces` | gdb 调试工作区根（`.debug/<id>`） |\n| `PTH_EXEC_PRIVATE_ROOT` | 空 | `/exec` 私有工作区根（生产 `/srv/workload`） |\n\n## 安全边界（P0 整改后基线）\n\n- workload env 一律 allowlist 构造；`SANDBOX_SHARED_SECRET` / `PTH_MEMORY_BRIDGE_TOKEN` / DB / LLM key 强制剔除。\n- 工作负载 UID/GID 2001；`/app` root 只读；控制器 root 仅 setuid。\n- kernel 池 TTL 到期先销毁再移出，绝不乐观标 idle。\n- 沙箱无外网（仅 `sandbox-internal`）；`/exec` cwd 白名单 + 私有工作区拷贝。\n- 记忆桥只读三操作（query/retrieve/get），space 只能来自上游 token 声明，body 自报 space 无效。\n\n长尾与加固计划见 `docs/superpowers/plans/2026-08-16-pth-sandbox-hardening.md`。\n","readmeFilename":"README.md"}