{"_id":"@buddhilive/dsh-win32-process","name":"@buddhilive/dsh-win32-process","dist-tags":{"alpha":"0.1.2-alpha.3","latest":"0.1.2-alpha.3"},"versions":{"0.1.2-alpha.3":{"name":"@buddhilive/dsh-win32-process","description":"Low-level Win32 process, stdio, and Job Object primitives for the DeepSeek Harness Windows sandbox","version":"0.1.2-alpha.3","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/subprocess/win32-process"},"type":"module","main":"lib/index.js","types":"lib/types/index.d.ts","exports":{".":{"types":"./lib/types/index.d.ts","default":"./lib/index.js"},"./invariant":{"types":"./lib/types/invariant.d.ts","default":"./lib/invariant.js"},"./src/*":"./src/*","./package.json":"./package.json"},"license":"MIT","peerDependencies":{"@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"dependencies":{"koffi":"^3.1.0"},"devDependencies":{"@buddhilive/dsh-invariants":"^0.1.2-alpha.3","@deepseek-ai/cordis":"^4.0.2"},"_id":"@buddhilive/dsh-win32-process@0.1.2-alpha.3","bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","_integrity":"sha512-Z8glIeSPcNxHGjWvSe5c+oHSqNRgttLEkLo/0Wr12CdmTFDRoP8MKT3JI+scxGSwuQo//QOlLpvyVNb8DsmPdw==","_resolved":"C:\\DevDojo\\Buddhi\\buddhi-ai-harness\\dist\\npm\\buddhilive-dsh-win32-process-0.1.2-alpha.3.tgz","_from":"file:C:/DevDojo/Buddhi/buddhi-ai-harness/dist/npm/buddhilive-dsh-win32-process-0.1.2-alpha.3.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-Z8glIeSPcNxHGjWvSe5c+oHSqNRgttLEkLo/0Wr12CdmTFDRoP8MKT3JI+scxGSwuQo//QOlLpvyVNb8DsmPdw==","shasum":"75b8156abb032f3935e1ea2aac50e3a55c16f42f","tarball":"https://registry.npmjs.org/@buddhilive/dsh-win32-process/-/dsh-win32-process-0.1.2-alpha.3.tgz","fileCount":13,"unpackedSize":45704,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHpZ/9DDkNRf+bwhmA9MQJkgeG5eBPNJfC01353zlYQUAiA15vJmi7u6v6Xv7dpddWk16IV+4Gydo+py1YCJoZpXhg=="}]},"_npmUser":{"name":"buddhilive","email":"visitbudkavin@gmail.com"},"directories":{},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/dsh-win32-process_0.1.2-alpha.3_1788165701277_0.7908104515545775"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T08:41:41.076Z","0.1.2-alpha.3":"2026-08-31T08:41:41.411Z","modified":"2026-08-31T08:41:41.690Z"},"maintainers":[{"name":"buddhilive","email":"visitbudkavin@gmail.com"}],"description":"Low-level Win32 process, stdio, and Job Object primitives for the DeepSeek Harness Windows sandbox","homepage":"https://github.com/Buddhilive/buddhi-ai-harness#readme","repository":{"type":"git","url":"git+https://github.com/Buddhilive/buddhi-ai-harness.git","directory":"packages/subprocess/win32-process"},"bugs":{"url":"https://github.com/Buddhilive/buddhi-ai-harness/issues"},"license":"MIT","readme":"---\ndescription: \"面向实现或排查 Windows ACL 沙箱的维护者，说明底层 Win32 进程原语。\"\nkind: \"package-library\"\n---\n\n# @buddhilive/dsh-win32-process\n\n[English](README.md) | 中文\n\n## 概述\n\n供 Windows ACL 沙箱消费的底层 Win32 进程库。它唯一拥有仓库中可复用 restricted-process、stdio 与 Job Object 操作的 Koffi 绑定表；它不是 Cordis 服务，也不决定沙箱策略或公共 child 行为。维护沙箱原生进程路径或检查 handle 生命周期限制时，请阅读本页。\n\n## 目录\n\n- [Behavior](#behavior)\n- [头部验证](#header-verification)\n- [Model Experience](#model-experience)\n- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)\n- [开发备注](#dev-note)\n\n-----\n\n<a id=\"behavior\"></a>\n## Behavior\n\n- **唯一可复用 ABI owner** — `abi.ts` 拥有 sandbox process 路径消费的 Win32 常量与 x64 布局值。`ffi.ts` 懒加载 `kernel32.dll` 与 `advapi32.dll`，核验 `STARTUPINFOW` 和 `PROCESS_INFORMATION`，提供带类型的操作与错误格式化，并让 sandbox policy 通过同一组已加载库绑定剩余 API。\n- **restricted-token 创建** — `RestrictedProcessSpawnOptions` 要求 sandbox 的 primary token，并使用 `CreateProcessAsUserW`。pipe 与 inherited-stdio 路径共用命令行引用、cwd、继承环境块、返回值检查与句柄清理。\n- **管道进程原语** — `spawnPipedProcess()` 创建匿名 stdin/stdout/stderr 管道，立即关闭 stdin，并返回两个读取端；调用方负责等待进程与排空管道。任一局部失败都会关闭该操作已经拥有的句柄，并在各自 Win32 生命周期结束后释放每个 Koffi 输出槽与结构体分配。\n- **继承 stdio 的 Job 原语** — `spawnInheritedJobProcess()` 创建一个 kill-on-close Job，临时把当前 stdio 句柄设为可继承，以 suspended 状态创建 restricted child，把它分配给 Job，再恢复初始线程。目标代码不会在 Job 分配前运行；受控的分配或恢复失败会终止 suspended child，或在释放全部已拥有句柄前关闭已分配的 Job。\n- **显式结算归属** — `waitForProcessExit()` 等待并关闭进程句柄。`drainPipe()` 在排空期间复用一个 native count slot，释放该分配并关闭管道读取句柄。sandbox 保留既有调度、result 组合与调用方拥有的 Job 关闭行为。\n\nWindows ACL 沙箱在这些原语上增加 SID、DACL、grant、workspace 与公共 child policy。\n\n<a id=\"header-verification\"></a>\n\n<a id=\"header-verification\"></a>\n## 头部验证\n\nprocess、stdio 与 Job 的常量以及选定结构体的大小和偏移由 [`verify/abi-probe.cpp`](verify/abi-probe.cpp) 对照 MinGW Windows 头文件检查：\n\n```sh\ng++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp && ./abi-probe.exe\n```\n\nKoffi 的 `STARTUPINFOW` 与 `PROCESS_INFORMATION` 定义还会在模块加载时断言各自的 64 位大小；其余已记录偏移和常量由该探针提供证据。\n\n<a id=\"model-experience\"></a>\n## Model Experience\n\n### 进程原语\n\n#### 模型看到什么\n\n没有直接内容。本包向 sandbox 提供 `Win32ProcessBindings` 与进程原语；sandbox 拥有全部模型可见工具、输出与诊断，本包不贡献提示词或工具 schema。\n\n#### Token 影响\n\n没有直接影响。消费方决定进程输出是否进入工具结果或后续模型请求。\n\n#### KV Cache 影响\n\n本包不贡献稳定请求前缀，因此不会使模型 KV Cache 失效。\n\n## Known Limitations and Deferred Work\n\n<a id=\"known-limitations-and-deferred-work\"></a>\n\n- **仅在 Windows 原生加载** — 导入通用类型可跨平台进行，但解析绑定表会加载 Windows DLL，并在其他宿主失败。跨平台测试注入绑定表，不加载原生 API。\n- **没有公共进程服务** — 本包刻意不把原语包装成 Cordis 或 Node streams。消费方必须拥有自己的策略、异步调度、输出上限、取消与最终句柄关闭。\n- **只继承环境** — 进程创建传入空环境块。sandbox 会先通过 `SetEnvironmentVariableW` 建立改动，因为经 Koffi 传入显式环境块会使 `CreateProcessAsUserW` 以 `ERROR_INVALID_PARAMETER` 失败。其他需要改写环境的调用方必须在调用原语前建立环境，或使用自己的 runner 进程。\n- **只有 restricted-token 消费方** — ordinary `CreateProcessW`、精确 `applicationName`、parent-stdio release 与 whole-Job settlement 在 ordinary process 消费方出现前均不提供。\n- **创建到分配之间的中断** — 目标以 suspended 状态启动，不能在 Job 分配前执行，但 runner 若在进程创建到分配之间的极窄区间被外力终止，可能留下 suspended target。本包不声明原子 Job 附加保证。\n- **header 证据限定架构** — 已提交的 ABI probe 与布局常量覆盖仓库当前 64 位 Windows 目标。支持新的指针宽度或不兼容 Windows ABI 前，必须先更新 probe。\n\n\n<a id=\"dev-note\"></a>\n### 开发备注\n\n<details>\n<summary>维护者工作上下文——点击展开</summary>\n\n无。\n\n</details>\n","readmeFilename":"README.zh.md","_rev":"1-9902cde53b2f63fcc1be27dc3bfea1a0"}