@draht/coding-agent 2026.7.30 → 2026.9.5-1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (459) hide show
  1. package/CHANGELOG.md +154 -0
  2. package/README.md +46 -2
  3. package/agents/debugger.md +12 -1
  4. package/agents/git-committer.md +1 -0
  5. package/agents/implementer.md +20 -0
  6. package/agents/investigator.md +75 -0
  7. package/agents/reviewer.md +7 -0
  8. package/agents/spec-reviewer.md +66 -0
  9. package/agents/verifier.md +4 -3
  10. package/bin/draht-tools.cjs +472 -41
  11. package/dist/agents/debugger.md +12 -1
  12. package/dist/agents/git-committer.md +1 -0
  13. package/dist/agents/implementer.md +20 -0
  14. package/dist/agents/investigator.md +75 -0
  15. package/dist/agents/reviewer.md +7 -0
  16. package/dist/agents/spec-reviewer.md +66 -0
  17. package/dist/agents/verifier.md +4 -3
  18. package/dist/cli/args.d.ts +10 -0
  19. package/dist/cli/args.d.ts.map +1 -1
  20. package/dist/cli/args.js +69 -2
  21. package/dist/cli/args.js.map +1 -1
  22. package/dist/cli/attach-mode.d.ts +61 -0
  23. package/dist/cli/attach-mode.d.ts.map +1 -1
  24. package/dist/cli/attach-mode.js +243 -5
  25. package/dist/cli/attach-mode.js.map +1 -1
  26. package/dist/cli/credential-print.d.ts +1 -1
  27. package/dist/cli/credential-print.d.ts.map +1 -1
  28. package/dist/cli/credential-print.js +5 -4
  29. package/dist/cli/credential-print.js.map +1 -1
  30. package/dist/config.d.ts +9 -0
  31. package/dist/config.d.ts.map +1 -1
  32. package/dist/config.js +31 -4
  33. package/dist/config.js.map +1 -1
  34. package/dist/core/agent-session-runtime.d.ts +17 -1
  35. package/dist/core/agent-session-runtime.d.ts.map +1 -1
  36. package/dist/core/agent-session-runtime.js +87 -30
  37. package/dist/core/agent-session-runtime.js.map +1 -1
  38. package/dist/core/agent-session-services.d.ts +1 -1
  39. package/dist/core/agent-session-services.d.ts.map +1 -1
  40. package/dist/core/agent-session-services.js +1 -0
  41. package/dist/core/agent-session-services.js.map +1 -1
  42. package/dist/core/agent-session.d.ts +35 -16
  43. package/dist/core/agent-session.d.ts.map +1 -1
  44. package/dist/core/agent-session.js +149 -64
  45. package/dist/core/agent-session.js.map +1 -1
  46. package/dist/core/auth-storage.d.ts +5 -1
  47. package/dist/core/auth-storage.d.ts.map +1 -1
  48. package/dist/core/auth-storage.js +72 -15
  49. package/dist/core/auth-storage.js.map +1 -1
  50. package/dist/core/builtins/checkpoints.d.ts +20 -0
  51. package/dist/core/builtins/checkpoints.d.ts.map +1 -0
  52. package/dist/core/builtins/checkpoints.js +161 -0
  53. package/dist/core/builtins/checkpoints.js.map +1 -0
  54. package/dist/core/builtins/duet.d.ts +26 -0
  55. package/dist/core/builtins/duet.d.ts.map +1 -0
  56. package/dist/core/builtins/duet.js +660 -0
  57. package/dist/core/builtins/duet.js.map +1 -0
  58. package/dist/core/builtins/index.d.ts.map +1 -1
  59. package/dist/core/builtins/index.js +7 -1
  60. package/dist/core/builtins/index.js.map +1 -1
  61. package/dist/core/builtins/subagent.d.ts +24 -4
  62. package/dist/core/builtins/subagent.d.ts.map +1 -1
  63. package/dist/core/builtins/subagent.js +278 -35
  64. package/dist/core/builtins/subagent.js.map +1 -1
  65. package/dist/core/checkpoints/checkpoint-cli.d.ts +17 -0
  66. package/dist/core/checkpoints/checkpoint-cli.d.ts.map +1 -0
  67. package/dist/core/checkpoints/checkpoint-cli.js +78 -0
  68. package/dist/core/checkpoints/checkpoint-cli.js.map +1 -0
  69. package/dist/core/checkpoints/checkpoint-manager.d.ts +294 -0
  70. package/dist/core/checkpoints/checkpoint-manager.d.ts.map +1 -0
  71. package/dist/core/checkpoints/checkpoint-manager.js +865 -0
  72. package/dist/core/checkpoints/checkpoint-manager.js.map +1 -0
  73. package/dist/core/checkpoints/rewind.d.ts +141 -0
  74. package/dist/core/checkpoints/rewind.d.ts.map +1 -0
  75. package/dist/core/checkpoints/rewind.js +246 -0
  76. package/dist/core/checkpoints/rewind.js.map +1 -0
  77. package/dist/core/compaction/branch-summarization.d.ts +1 -1
  78. package/dist/core/compaction/branch-summarization.d.ts.map +1 -1
  79. package/dist/core/compaction/branch-summarization.js +9 -4
  80. package/dist/core/compaction/branch-summarization.js.map +1 -1
  81. package/dist/core/compaction/compaction.d.ts +5 -0
  82. package/dist/core/compaction/compaction.d.ts.map +1 -1
  83. package/dist/core/compaction/compaction.js +25 -4
  84. package/dist/core/compaction/compaction.js.map +1 -1
  85. package/dist/core/extensions/index.d.ts +1 -1
  86. package/dist/core/extensions/index.d.ts.map +1 -1
  87. package/dist/core/extensions/index.js.map +1 -1
  88. package/dist/core/extensions/loader.d.ts.map +1 -1
  89. package/dist/core/extensions/loader.js +83 -20
  90. package/dist/core/extensions/loader.js.map +1 -1
  91. package/dist/core/extensions/runner.d.ts +13 -2
  92. package/dist/core/extensions/runner.d.ts.map +1 -1
  93. package/dist/core/extensions/runner.js +37 -2
  94. package/dist/core/extensions/runner.js.map +1 -1
  95. package/dist/core/extensions/types.d.ts +189 -6
  96. package/dist/core/extensions/types.d.ts.map +1 -1
  97. package/dist/core/extensions/types.js.map +1 -1
  98. package/dist/core/http-dispatcher.d.ts.map +1 -1
  99. package/dist/core/http-dispatcher.js +7 -0
  100. package/dist/core/http-dispatcher.js.map +1 -1
  101. package/dist/core/index.d.ts +1 -1
  102. package/dist/core/index.d.ts.map +1 -1
  103. package/dist/core/index.js.map +1 -1
  104. package/dist/core/keybindings.d.ts +5 -0
  105. package/dist/core/keybindings.d.ts.map +1 -1
  106. package/dist/core/keybindings.js +1 -0
  107. package/dist/core/keybindings.js.map +1 -1
  108. package/dist/core/model-registry.d.ts +3 -2
  109. package/dist/core/model-registry.d.ts.map +1 -1
  110. package/dist/core/model-registry.js +8 -8
  111. package/dist/core/model-registry.js.map +1 -1
  112. package/dist/core/model-resolver.d.ts.map +1 -1
  113. package/dist/core/model-resolver.js +34 -7
  114. package/dist/core/model-resolver.js.map +1 -1
  115. package/dist/core/model-runtime.d.ts +7 -1
  116. package/dist/core/model-runtime.d.ts.map +1 -1
  117. package/dist/core/model-runtime.js +30 -10
  118. package/dist/core/model-runtime.js.map +1 -1
  119. package/dist/core/multi-agent/permission-gate.d.ts.map +1 -1
  120. package/dist/core/multi-agent/permission-gate.js +4 -3
  121. package/dist/core/multi-agent/permission-gate.js.map +1 -1
  122. package/dist/core/multi-agent/worktree.d.ts +2 -0
  123. package/dist/core/multi-agent/worktree.d.ts.map +1 -1
  124. package/dist/core/multi-agent/worktree.js +2 -2
  125. package/dist/core/multi-agent/worktree.js.map +1 -1
  126. package/dist/core/package-manager.d.ts +7 -1
  127. package/dist/core/package-manager.d.ts.map +1 -1
  128. package/dist/core/package-manager.js +21 -44
  129. package/dist/core/package-manager.js.map +1 -1
  130. package/dist/core/permission-relay/index.d.ts +19 -0
  131. package/dist/core/permission-relay/index.d.ts.map +1 -0
  132. package/dist/core/permission-relay/index.js +49 -0
  133. package/dist/core/permission-relay/index.js.map +1 -0
  134. package/dist/core/permission-relay/relay-ui-context.d.ts +39 -0
  135. package/dist/core/permission-relay/relay-ui-context.d.ts.map +1 -0
  136. package/dist/core/permission-relay/relay-ui-context.js +788 -0
  137. package/dist/core/permission-relay/relay-ui-context.js.map +1 -0
  138. package/dist/core/permission-relay/types.d.ts +222 -0
  139. package/dist/core/permission-relay/types.d.ts.map +1 -0
  140. package/dist/core/permission-relay/types.js +15 -0
  141. package/dist/core/permission-relay/types.js.map +1 -0
  142. package/dist/core/pi-manifest.d.ts +14 -0
  143. package/dist/core/pi-manifest.d.ts.map +1 -0
  144. package/dist/core/pi-manifest.js +35 -0
  145. package/dist/core/pi-manifest.js.map +1 -0
  146. package/dist/core/project-trust.js +2 -2
  147. package/dist/core/project-trust.js.map +1 -1
  148. package/dist/core/resource-loader.d.ts +21 -0
  149. package/dist/core/resource-loader.d.ts.map +1 -1
  150. package/dist/core/resource-loader.js +101 -24
  151. package/dist/core/resource-loader.js.map +1 -1
  152. package/dist/core/sandbox/bash-operations.d.ts +149 -0
  153. package/dist/core/sandbox/bash-operations.d.ts.map +1 -0
  154. package/dist/core/sandbox/bash-operations.js +163 -0
  155. package/dist/core/sandbox/bash-operations.js.map +1 -0
  156. package/dist/core/sandbox/env.d.ts +83 -0
  157. package/dist/core/sandbox/env.d.ts.map +1 -0
  158. package/dist/core/sandbox/env.js +123 -0
  159. package/dist/core/sandbox/env.js.map +1 -0
  160. package/dist/core/sandbox/executor.d.ts +104 -0
  161. package/dist/core/sandbox/executor.d.ts.map +1 -0
  162. package/dist/core/sandbox/executor.js +92 -0
  163. package/dist/core/sandbox/executor.js.map +1 -0
  164. package/dist/core/sandbox/index.d.ts +36 -0
  165. package/dist/core/sandbox/index.d.ts.map +1 -0
  166. package/dist/core/sandbox/index.js +36 -0
  167. package/dist/core/sandbox/index.js.map +1 -0
  168. package/dist/core/sandbox/linux.d.ts +121 -0
  169. package/dist/core/sandbox/linux.d.ts.map +1 -0
  170. package/dist/core/sandbox/linux.js +260 -0
  171. package/dist/core/sandbox/linux.js.map +1 -0
  172. package/dist/core/sandbox/policy.d.ts +142 -0
  173. package/dist/core/sandbox/policy.d.ts.map +1 -0
  174. package/dist/core/sandbox/policy.js +297 -0
  175. package/dist/core/sandbox/policy.js.map +1 -0
  176. package/dist/core/sandbox/real-path.d.ts +112 -0
  177. package/dist/core/sandbox/real-path.d.ts.map +1 -0
  178. package/dist/core/sandbox/real-path.js +158 -0
  179. package/dist/core/sandbox/real-path.js.map +1 -0
  180. package/dist/core/sandbox/seatbelt-profile.d.ts +95 -0
  181. package/dist/core/sandbox/seatbelt-profile.d.ts.map +1 -0
  182. package/dist/core/sandbox/seatbelt-profile.js +239 -0
  183. package/dist/core/sandbox/seatbelt-profile.js.map +1 -0
  184. package/dist/core/sandbox/seatbelt.d.ts +95 -0
  185. package/dist/core/sandbox/seatbelt.d.ts.map +1 -0
  186. package/dist/core/sandbox/seatbelt.js +154 -0
  187. package/dist/core/sandbox/seatbelt.js.map +1 -0
  188. package/dist/core/sandbox/self-test.d.ts +109 -0
  189. package/dist/core/sandbox/self-test.d.ts.map +1 -0
  190. package/dist/core/sandbox/self-test.js +369 -0
  191. package/dist/core/sandbox/self-test.js.map +1 -0
  192. package/dist/core/sandbox/spawn.d.ts +33 -0
  193. package/dist/core/sandbox/spawn.d.ts.map +1 -0
  194. package/dist/core/sandbox/spawn.js +87 -0
  195. package/dist/core/sandbox/spawn.js.map +1 -0
  196. package/dist/core/sdk.d.ts.map +1 -1
  197. package/dist/core/sdk.js +3 -1
  198. package/dist/core/sdk.js.map +1 -1
  199. package/dist/core/session-manager.d.ts +60 -1
  200. package/dist/core/session-manager.d.ts.map +1 -1
  201. package/dist/core/session-manager.js +53 -6
  202. package/dist/core/session-manager.js.map +1 -1
  203. package/dist/core/settings-manager.d.ts +21 -0
  204. package/dist/core/settings-manager.d.ts.map +1 -1
  205. package/dist/core/settings-manager.js +36 -16
  206. package/dist/core/settings-manager.js.map +1 -1
  207. package/dist/core/skills.d.ts +3 -1
  208. package/dist/core/skills.d.ts.map +1 -1
  209. package/dist/core/skills.js +19 -6
  210. package/dist/core/skills.js.map +1 -1
  211. package/dist/core/slash-commands.d.ts.map +1 -1
  212. package/dist/core/slash-commands.js +1 -0
  213. package/dist/core/slash-commands.js.map +1 -1
  214. package/dist/core/soak/soak-log.d.ts +298 -0
  215. package/dist/core/soak/soak-log.d.ts.map +1 -0
  216. package/dist/core/soak/soak-log.js +660 -0
  217. package/dist/core/soak/soak-log.js.map +1 -0
  218. package/dist/core/soak/soak-reader.d.ts +60 -0
  219. package/dist/core/soak/soak-reader.d.ts.map +1 -0
  220. package/dist/core/soak/soak-reader.js +106 -0
  221. package/dist/core/soak/soak-reader.js.map +1 -0
  222. package/dist/core/socket-server/discovery.d.ts +78 -1
  223. package/dist/core/socket-server/discovery.d.ts.map +1 -1
  224. package/dist/core/socket-server/discovery.js +356 -37
  225. package/dist/core/socket-server/discovery.js.map +1 -1
  226. package/dist/core/socket-server/index.d.ts +10 -4
  227. package/dist/core/socket-server/index.d.ts.map +1 -1
  228. package/dist/core/socket-server/index.js +6 -3
  229. package/dist/core/socket-server/index.js.map +1 -1
  230. package/dist/core/socket-server/permission-delivery.d.ts +125 -0
  231. package/dist/core/socket-server/permission-delivery.d.ts.map +1 -0
  232. package/dist/core/socket-server/permission-delivery.js +152 -0
  233. package/dist/core/socket-server/permission-delivery.js.map +1 -0
  234. package/dist/core/socket-server/permission-registry.d.ts +301 -0
  235. package/dist/core/socket-server/permission-registry.d.ts.map +1 -0
  236. package/dist/core/socket-server/permission-registry.js +410 -0
  237. package/dist/core/socket-server/permission-registry.js.map +1 -0
  238. package/dist/core/socket-server/permission-relay.d.ts +81 -0
  239. package/dist/core/socket-server/permission-relay.d.ts.map +1 -0
  240. package/dist/core/socket-server/permission-relay.js +528 -0
  241. package/dist/core/socket-server/permission-relay.js.map +1 -0
  242. package/dist/core/socket-server/safe-text.d.ts +83 -0
  243. package/dist/core/socket-server/safe-text.d.ts.map +1 -0
  244. package/dist/core/socket-server/safe-text.js +277 -0
  245. package/dist/core/socket-server/safe-text.js.map +1 -0
  246. package/dist/core/socket-server/session-integration.d.ts +65 -2
  247. package/dist/core/socket-server/session-integration.d.ts.map +1 -1
  248. package/dist/core/socket-server/session-integration.js +434 -32
  249. package/dist/core/socket-server/session-integration.js.map +1 -1
  250. package/dist/core/socket-server/socket-client.d.ts +21 -2
  251. package/dist/core/socket-server/socket-client.d.ts.map +1 -1
  252. package/dist/core/socket-server/socket-client.js +52 -1
  253. package/dist/core/socket-server/socket-client.js.map +1 -1
  254. package/dist/core/socket-server/socket-server.d.ts +152 -1
  255. package/dist/core/socket-server/socket-server.d.ts.map +1 -1
  256. package/dist/core/socket-server/socket-server.js +775 -26
  257. package/dist/core/socket-server/socket-server.js.map +1 -1
  258. package/dist/core/socket-server/types.d.ts +106 -2
  259. package/dist/core/socket-server/types.d.ts.map +1 -1
  260. package/dist/core/socket-server/types.js +13 -1
  261. package/dist/core/socket-server/types.js.map +1 -1
  262. package/dist/core/system-prompt.d.ts.map +1 -1
  263. package/dist/core/system-prompt.js +8 -9
  264. package/dist/core/system-prompt.js.map +1 -1
  265. package/dist/core/tools/bash.d.ts +1 -1
  266. package/dist/core/tools/bash.d.ts.map +1 -1
  267. package/dist/core/tools/bash.js +5 -2
  268. package/dist/core/tools/bash.js.map +1 -1
  269. package/dist/core/tools/edit.d.ts.map +1 -1
  270. package/dist/core/tools/edit.js +17 -2
  271. package/dist/core/tools/edit.js.map +1 -1
  272. package/dist/core/tools/find.d.ts +3 -0
  273. package/dist/core/tools/find.d.ts.map +1 -1
  274. package/dist/core/tools/find.js +11 -18
  275. package/dist/core/tools/find.js.map +1 -1
  276. package/dist/core/trust-manager.d.ts +6 -4
  277. package/dist/core/trust-manager.d.ts.map +1 -1
  278. package/dist/core/trust-manager.js +55 -21
  279. package/dist/core/trust-manager.js.map +1 -1
  280. package/dist/extensions/index.d.ts.map +1 -1
  281. package/dist/extensions/index.js +5 -1
  282. package/dist/extensions/index.js.map +1 -1
  283. package/dist/extensions/llama/provider.d.ts.map +1 -1
  284. package/dist/extensions/llama/provider.js +5 -1
  285. package/dist/extensions/llama/provider.js.map +1 -1
  286. package/dist/extensions/stub-provider/index.d.ts +9 -0
  287. package/dist/extensions/stub-provider/index.d.ts.map +1 -0
  288. package/dist/extensions/stub-provider/index.js +13 -0
  289. package/dist/extensions/stub-provider/index.js.map +1 -0
  290. package/dist/extensions/stub-provider/provider.d.ts +77 -0
  291. package/dist/extensions/stub-provider/provider.d.ts.map +1 -0
  292. package/dist/extensions/stub-provider/provider.js +193 -0
  293. package/dist/extensions/stub-provider/provider.js.map +1 -0
  294. package/dist/hooks/gsd/draht-quality-gate.js +3 -3
  295. package/dist/index.d.ts +1 -1
  296. package/dist/index.d.ts.map +1 -1
  297. package/dist/index.js.map +1 -1
  298. package/dist/main.d.ts.map +1 -1
  299. package/dist/main.js +242 -45
  300. package/dist/main.js.map +1 -1
  301. package/dist/modes/interactive/components/config-selector.d.ts.map +1 -1
  302. package/dist/modes/interactive/components/config-selector.js +3 -2
  303. package/dist/modes/interactive/components/config-selector.js.map +1 -1
  304. package/dist/modes/interactive/components/extension-selector.d.ts +49 -0
  305. package/dist/modes/interactive/components/extension-selector.d.ts.map +1 -1
  306. package/dist/modes/interactive/components/extension-selector.js +202 -5
  307. package/dist/modes/interactive/components/extension-selector.js.map +1 -1
  308. package/dist/modes/interactive/components/session-selector.d.ts.map +1 -1
  309. package/dist/modes/interactive/components/session-selector.js +10 -2
  310. package/dist/modes/interactive/components/session-selector.js.map +1 -1
  311. package/dist/modes/interactive/components/settings-selector.d.ts +2 -0
  312. package/dist/modes/interactive/components/settings-selector.d.ts.map +1 -1
  313. package/dist/modes/interactive/components/settings-selector.js +10 -0
  314. package/dist/modes/interactive/components/settings-selector.js.map +1 -1
  315. package/dist/modes/interactive/components/tool-execution.d.ts.map +1 -1
  316. package/dist/modes/interactive/components/tool-execution.js +10 -1
  317. package/dist/modes/interactive/components/tool-execution.js.map +1 -1
  318. package/dist/modes/interactive/components/tree-selector.d.ts +20 -2
  319. package/dist/modes/interactive/components/tree-selector.d.ts.map +1 -1
  320. package/dist/modes/interactive/components/tree-selector.js +21 -5
  321. package/dist/modes/interactive/components/tree-selector.js.map +1 -1
  322. package/dist/modes/interactive/interactive-mode.d.ts +97 -3
  323. package/dist/modes/interactive/interactive-mode.d.ts.map +1 -1
  324. package/dist/modes/interactive/interactive-mode.js +394 -24
  325. package/dist/modes/interactive/interactive-mode.js.map +1 -1
  326. package/dist/modes/rpc/rpc-mode.d.ts.map +1 -1
  327. package/dist/modes/rpc/rpc-mode.js +165 -7
  328. package/dist/modes/rpc/rpc-mode.js.map +1 -1
  329. package/dist/modes/rpc/rpc-types.d.ts +68 -1
  330. package/dist/modes/rpc/rpc-types.d.ts.map +1 -1
  331. package/dist/modes/rpc/rpc-types.js.map +1 -1
  332. package/dist/prompts/commands/atomic-commit.md +1 -12
  333. package/dist/prompts/commands/brainstorm.md +12 -15
  334. package/dist/prompts/commands/create-verification-skill.md +108 -0
  335. package/dist/prompts/commands/discuss-phase.md +3 -14
  336. package/dist/prompts/commands/execute-phase.md +3 -11
  337. package/dist/prompts/commands/fix.md +41 -18
  338. package/dist/prompts/commands/grill.md +66 -0
  339. package/dist/prompts/commands/init-project.md +5 -15
  340. package/dist/prompts/commands/map-codebase.md +1 -13
  341. package/dist/prompts/commands/new-project.md +5 -15
  342. package/dist/prompts/commands/next-milestone.md +1 -13
  343. package/dist/prompts/commands/orchestrate.md +1 -1
  344. package/dist/prompts/commands/pause-work.md +1 -13
  345. package/dist/prompts/commands/plan-phase.md +2 -11
  346. package/dist/prompts/commands/progress.md +0 -13
  347. package/dist/prompts/commands/quick.md +3 -11
  348. package/dist/prompts/commands/resolve-conflicts.md +71 -0
  349. package/dist/prompts/commands/resume-work.md +0 -13
  350. package/dist/prompts/commands/review.md +4 -13
  351. package/dist/prompts/commands/triage.md +159 -0
  352. package/dist/prompts/commands/verify-work.md +4 -14
  353. package/dist/prompts/commands/why.md +135 -0
  354. package/dist/skills/atomic-reasoning/SKILL.md +115 -0
  355. package/dist/skills/blast-radius/SKILL.md +55 -0
  356. package/dist/skills/epistemics/SKILL.md +99 -0
  357. package/dist/skills/hexagon-animation/SKILL.md +49 -0
  358. package/dist/skills/hexagon-animation/generate.mjs +81 -0
  359. package/dist/skills/hexagon-animation/template.html +361 -0
  360. package/dist/skills/typescript-discipline/SKILL.md +50 -0
  361. package/dist/skills/typescript-discipline/references/patterns.md +294 -0
  362. package/dist/skills/unslop/SKILL.md +101 -0
  363. package/dist/utils/canonical-path.d.ts +28 -0
  364. package/dist/utils/canonical-path.d.ts.map +1 -0
  365. package/dist/utils/canonical-path.js +90 -0
  366. package/dist/utils/canonical-path.js.map +1 -0
  367. package/dist/utils/child-process.d.ts +12 -1
  368. package/dist/utils/child-process.d.ts.map +1 -1
  369. package/dist/utils/child-process.js +25 -8
  370. package/dist/utils/child-process.js.map +1 -1
  371. package/dist/utils/clipboard.d.ts +1 -1
  372. package/dist/utils/clipboard.d.ts.map +1 -1
  373. package/dist/utils/clipboard.js +22 -2
  374. package/dist/utils/clipboard.js.map +1 -1
  375. package/dist/utils/exif-orientation.d.ts.map +1 -1
  376. package/dist/utils/exif-orientation.js +2 -3
  377. package/dist/utils/exif-orientation.js.map +1 -1
  378. package/dist/utils/paths.d.ts +2 -7
  379. package/dist/utils/paths.d.ts.map +1 -1
  380. package/dist/utils/paths.js +13 -15
  381. package/dist/utils/paths.js.map +1 -1
  382. package/dist/utils/shell.d.ts.map +1 -1
  383. package/dist/utils/shell.js +6 -4
  384. package/dist/utils/shell.js.map +1 -1
  385. package/dist/utils/tools-manager.d.ts.map +1 -1
  386. package/dist/utils/tools-manager.js +3 -5
  387. package/dist/utils/tools-manager.js.map +1 -1
  388. package/docs/attachable-sessions.md +79 -0
  389. package/docs/compaction.md +21 -21
  390. package/docs/containerization.md +23 -23
  391. package/docs/custom-provider.md +16 -16
  392. package/docs/development.md +9 -9
  393. package/docs/docs.json +6 -2
  394. package/docs/duet.md +42 -0
  395. package/docs/extensions.md +58 -58
  396. package/docs/index.md +10 -10
  397. package/docs/json.md +7 -7
  398. package/docs/keybindings.md +6 -5
  399. package/docs/llama-cpp.md +6 -6
  400. package/docs/models.md +6 -6
  401. package/docs/packages.md +43 -43
  402. package/docs/prompt-templates.md +4 -4
  403. package/docs/providers.md +12 -12
  404. package/docs/quickstart.md +32 -32
  405. package/docs/rpc.md +83 -12
  406. package/docs/sdk.md +15 -15
  407. package/docs/security.md +18 -18
  408. package/docs/session-format.md +35 -13
  409. package/docs/sessions.md +17 -14
  410. package/docs/settings.md +25 -18
  411. package/docs/shell-aliases.md +2 -2
  412. package/docs/skills.md +12 -11
  413. package/docs/terminal-setup.md +12 -12
  414. package/docs/termux.md +6 -6
  415. package/docs/themes.md +11 -11
  416. package/docs/tmux.md +4 -4
  417. package/docs/tui.md +5 -5
  418. package/docs/usage.md +50 -50
  419. package/docs/windows.md +2 -2
  420. package/examples/extensions/overlay-qa-tests.ts +3 -3
  421. package/hooks/gsd/draht-quality-gate.js +3 -3
  422. package/package.json +11 -10
  423. package/prompts/commands/atomic-commit.md +1 -12
  424. package/prompts/commands/brainstorm.md +12 -15
  425. package/prompts/commands/create-verification-skill.md +108 -0
  426. package/prompts/commands/discuss-phase.md +3 -14
  427. package/prompts/commands/execute-phase.md +3 -11
  428. package/prompts/commands/fix.md +41 -18
  429. package/prompts/commands/grill.md +66 -0
  430. package/prompts/commands/init-project.md +5 -15
  431. package/prompts/commands/map-codebase.md +1 -13
  432. package/prompts/commands/new-project.md +5 -15
  433. package/prompts/commands/next-milestone.md +1 -13
  434. package/prompts/commands/orchestrate.md +1 -1
  435. package/prompts/commands/pause-work.md +1 -13
  436. package/prompts/commands/plan-phase.md +2 -11
  437. package/prompts/commands/progress.md +0 -13
  438. package/prompts/commands/quick.md +3 -11
  439. package/prompts/commands/resolve-conflicts.md +71 -0
  440. package/prompts/commands/resume-work.md +0 -13
  441. package/prompts/commands/review.md +4 -13
  442. package/prompts/commands/triage.md +159 -0
  443. package/prompts/commands/verify-work.md +4 -14
  444. package/prompts/commands/why.md +135 -0
  445. package/skills/atomic-reasoning/SKILL.md +115 -0
  446. package/skills/blast-radius/SKILL.md +55 -0
  447. package/skills/epistemics/SKILL.md +99 -0
  448. package/skills/hexagon-animation/SKILL.md +49 -0
  449. package/skills/hexagon-animation/generate.mjs +81 -0
  450. package/skills/hexagon-animation/template.html +361 -0
  451. package/skills/typescript-discipline/SKILL.md +50 -0
  452. package/skills/typescript-discipline/references/patterns.md +294 -0
  453. package/skills/unslop/SKILL.md +101 -0
  454. package/dist/prompts/agents/build.md +0 -86
  455. package/dist/prompts/agents/plan.md +0 -79
  456. package/dist/prompts/agents/verify.md +0 -69
  457. package/prompts/agents/build.md +0 -86
  458. package/prompts/agents/plan.md +0 -79
  459. package/prompts/agents/verify.md +0 -69
@@ -0,0 +1,163 @@
1
+ /**
2
+ * The `BashOperations` wrapper (R44-SBX.6).
3
+ *
4
+ * This is the only place the sandbox meets the agent's bash tool. It implements
5
+ * the existing `BashOperations` seam in `../tools/bash.ts` -- the same interface
6
+ * an SSH or container backend would implement -- so the bash tool itself needs
7
+ * no change: `createBashTool(cwd, { operations })` is the whole integration.
8
+ *
9
+ * ## Three states, and the rule that separates them
10
+ *
11
+ * | sandboxing | backend | what runs |
12
+ * |------------|------------|---------------------------------------------|
13
+ * | off | (not asked)| the wrapped local backend, untouched |
14
+ * | on | available | the command, confined by the policy |
15
+ * | on | unavailable| the wrapped local backend, announced once |
16
+ *
17
+ * **Off must be invisible.** Sandboxing off is the default and is what every
18
+ * existing session is: the wrapper forwards `command`, `cwd` and the *same
19
+ * options object* to the wrapped backend and returns its result. It does not
20
+ * resolve a policy, does not construct an env, does not so much as ask the
21
+ * executor whether it exists -- because asking runs a self-test, which spawns
22
+ * processes. The bash tool is the agent's primary limb; a wrapper that subtly
23
+ * changed its timing, its environment or its error text while claiming to be
24
+ * disabled would be a regression paid for by every user who never turned the
25
+ * sandbox on.
26
+ *
27
+ * ## Why `unavailable` falls back, when the rest of this module never does
28
+ *
29
+ * Everywhere else in `src/core/sandbox/`, "cannot confine" means "do not run".
30
+ * Here it means "run the way this product ran yesterday". That inversion is
31
+ * deliberate and is the spec's one explicit departure from Phase 28
32
+ * (`.planning/specs/2026-07-12-bash-sandbox-confinement.md`): the RLM sandbox
33
+ * exists to contain untrusted generated code, so refusing to start is the safe
34
+ * answer; the bash tool *is* the agent, so hard-failing every command on a host
35
+ * without a working backend bricks the product rather than protecting it. The
36
+ * documented posture is to fall back to the permission gate exactly as it works
37
+ * today (R45-SBM.5), which is a strictly-unchanged security posture, not a
38
+ * weakened one.
39
+ *
40
+ * What makes that safe rather than merely convenient is that the fallback is
41
+ * **loud and whole-session**:
42
+ *
43
+ * - It is announced through `onNotice` **once**, not once per command. A
44
+ * per-command warning is noise, and noise is how a security notice gets
45
+ * trained away.
46
+ * - The decision is taken from `SandboxExecutor.status()`, which is asked once
47
+ * and memoised, so a session is either sandboxed or it is not. There is no
48
+ * command-by-command drift where some commands were confined and nobody can
49
+ * say which.
50
+ * - The fallback child is the *ordinary* child: it carries no `DRAHT_SANDBOX`
51
+ * marker and gets no filtered env, so nothing downstream -- a prompt, a
52
+ * script, a future permission decision -- can mistake it for a confined one.
53
+ * The test suite asserts this by checking that an escape write actually
54
+ * *succeeds* in fallback: a fallback that happened to block it would be
55
+ * indistinguishable from confinement the session never had.
56
+ *
57
+ * ## What does *not* fall back
58
+ *
59
+ * Once the backend has reported `available`, a single invocation that cannot be
60
+ * confined -- an unrenderable policy, a cwd that no longer resolves -- is an
61
+ * error, not a fallback. It rejects with `SandboxUnavailableError`. Silently
62
+ * running that one command unconfined in an otherwise-sandboxed session is the
63
+ * exact hole this phase exists to close: the caller believes confinement holds,
64
+ * and the one command that escaped it is the one nobody was told about. Phase 45
65
+ * turns that rejection into the "rerun unsandboxed?" approval prompt, which is
66
+ * the same decision made *in the open*.
67
+ *
68
+ * ## Layering note
69
+ *
70
+ * This is the only file in `src/core/sandbox/` that imports from `../tools/`,
71
+ * which is why it is deliberately absent from `./index.ts`: the barrel stays
72
+ * usable by anything that just wants the policy model, without dragging the tool
73
+ * and render layers in behind it -- and a future `bash.ts` that wants to import
74
+ * the sandbox barrel cannot create a cycle.
75
+ */
76
+ import { createLocalBashOperations } from "../tools/bash.js";
77
+ import { createSandboxExecutor, SandboxUnavailableError, } from "./executor.js";
78
+ import { resolveSandboxPolicy } from "./policy.js";
79
+ /**
80
+ * Wraps a local `BashOperations` with OS-level confinement.
81
+ *
82
+ * The returned object is a drop-in for `createLocalBashOperations()`; with
83
+ * `enabled` false (the default) it *is* that backend, one function call deeper.
84
+ */
85
+ export function createSandboxedBashOperations(options = {}) {
86
+ const fallback = options.operations ?? createLocalBashOperations({ shellPath: options.shellPath });
87
+ const executor = options.executor ?? createSandboxExecutor();
88
+ const enabledSource = options.enabled ?? false;
89
+ const policySource = options.policy ?? {};
90
+ const onNotice = options.onNotice;
91
+ const isEnabled = () => (typeof enabledSource === "function" ? enabledSource() : enabledSource);
92
+ let unavailableAnnounced = false;
93
+ const announcedRejections = new Set();
94
+ const announceUnavailable = (reason) => {
95
+ if (unavailableAnnounced)
96
+ return;
97
+ unavailableAnnounced = true;
98
+ onNotice?.({ kind: "unavailable", backend: executor.name, reason });
99
+ };
100
+ const announceRejection = (input, reason) => {
101
+ const key = JSON.stringify([input, reason]);
102
+ if (announcedRejections.has(key))
103
+ return;
104
+ announcedRejections.add(key);
105
+ onNotice?.({ kind: "write-path-rejected", input, reason });
106
+ };
107
+ let statusPromise;
108
+ const sandboxStatus = () => {
109
+ // `Promise.resolve().then(...)` rather than a bare call: `status()` is
110
+ // documented never to throw, but a caller-supplied executor is not bound by
111
+ // our documentation, and a synchronous throw here would escape as an
112
+ // exception from the *bash tool* rather than as "we could not confine".
113
+ statusPromise ??= Promise.resolve()
114
+ .then(() => executor.status())
115
+ .catch((err) => ({
116
+ available: false,
117
+ reason: `sandbox backend ${JSON.stringify(executor.name)} could not report its status: ${err instanceof Error ? err.message : String(err)}`,
118
+ }));
119
+ return statusPromise;
120
+ };
121
+ /**
122
+ * Resolved fresh for every invocation, not cached by cwd.
123
+ *
124
+ * Real-path resolution is a claim about the filesystem *now*: a directory in
125
+ * the allowlist can be replaced by a symlink between two commands in the same
126
+ * session, and a policy cached from before that swap would authorise a path
127
+ * that no longer means what it meant. It matches the backends, which
128
+ * regenerate their profile per invocation for the same reason. Phase 46 owns
129
+ * the spawn-overhead budget and can revisit this with numbers.
130
+ */
131
+ const policyFor = (cwd) => {
132
+ const overrides = typeof policySource === "function" ? policySource() : policySource;
133
+ let resolution;
134
+ try {
135
+ resolution = resolveSandboxPolicy({ ...overrides, cwd });
136
+ }
137
+ catch (err) {
138
+ // The policy is what confinement *is*. Not being able to build one is not
139
+ // a reason to run without one.
140
+ throw new SandboxUnavailableError(`cannot resolve a sandbox policy for ${JSON.stringify(cwd)}: ${err instanceof Error ? err.message : String(err)}`);
141
+ }
142
+ for (const rejection of resolution.rejected)
143
+ announceRejection(rejection.input, rejection.reason);
144
+ return resolution.policy;
145
+ };
146
+ return {
147
+ backendName: executor.name,
148
+ sandboxStatus,
149
+ exec: async (command, cwd, execOptions) => {
150
+ // Sandboxing off: hand the call straight through. Same arguments, same
151
+ // options object, same promise -- nothing to diverge from.
152
+ if (!isEnabled())
153
+ return fallback.exec(command, cwd, execOptions);
154
+ const status = await sandboxStatus();
155
+ if (!status.available) {
156
+ announceUnavailable(status.reason);
157
+ return fallback.exec(command, cwd, execOptions);
158
+ }
159
+ return executor.exec(command, cwd, policyFor(cwd), execOptions);
160
+ },
161
+ };
162
+ }
163
+ //# sourceMappingURL=bash-operations.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bash-operations.js","sourceRoot":"","sources":["../../../src/core/sandbox/bash-operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AAEH,OAAO,EAAuB,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,EACN,qBAAqB,EAGrB,uBAAuB,GACvB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAA+C,MAAM,aAAa,CAAC;AAyEhG;;;;;GAKG;AACH,MAAM,UAAU,6BAA6B,CAAC,OAAO,GAAmC,EAAE;IACzF,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,IAAI,yBAAyB,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IACnG,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,qBAAqB,EAAE,CAAC;IAC7D,MAAM,aAAa,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC;IAC/C,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;IAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IAElC,MAAM,SAAS,GAAG,GAAY,EAAE,CAAC,CAAC,OAAO,aAAa,KAAK,UAAU,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;IAEzG,IAAI,oBAAoB,GAAG,KAAK,CAAC;IACjC,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAAU,CAAC;IAE9C,MAAM,mBAAmB,GAAG,CAAC,MAAc,EAAQ,EAAE;QACpD,IAAI,oBAAoB;YAAE,OAAO;QACjC,oBAAoB,GAAG,IAAI,CAAC;QAC5B,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACrE,CAAC,CAAC;IAEF,MAAM,iBAAiB,GAAG,CAAC,KAAa,EAAE,MAAc,EAAQ,EAAE;QACjE,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;QAC5C,IAAI,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO;QACzC,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC;IAEF,IAAI,aAAiD,CAAC;IACtD,MAAM,aAAa,GAAG,GAA2B,EAAE;QAClD,uEAAuE;QACvE,4EAA4E;QAC5E,qEAAqE;QACrE,wEAAwE;QACxE,aAAa,KAAK,OAAO,CAAC,OAAO,EAAE;aACjC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;aAC7B,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAChB,SAAS,EAAE,KAAc;YACzB,MAAM,EAAE,mBAAmB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,iCACvD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAChD,EAAE;SACF,CAAC,CAAC,CAAC;QACL,OAAO,aAAa,CAAC;IACtB,CAAC,CAAC;IAEF;;;;;;;;;OASG;IACH,MAAM,SAAS,GAAG,CAAC,GAAW,EAAiB,EAAE;QAChD,MAAM,SAAS,GAAG,OAAO,YAAY,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC;QACrF,IAAI,UAAmD,CAAC;QACxD,IAAI,CAAC;YACJ,UAAU,GAAG,oBAAoB,CAAC,EAAE,GAAG,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;QAC1D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,0EAA0E;YAC1E,+BAA+B;YAC/B,MAAM,IAAI,uBAAuB,CAChC,uCAAuC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KACzD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAChD,EAAE,CACF,CAAC;QACH,CAAC;QACD,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,QAAQ;YAAE,iBAAiB,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;QAClG,OAAO,UAAU,CAAC,MAAM,CAAC;IAC1B,CAAC,CAAC;IAEF,OAAO;QACN,WAAW,EAAE,QAAQ,CAAC,IAAI;QAC1B,aAAa;QACb,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE;YACzC,uEAAuE;YACvE,2DAA2D;YAC3D,IAAI,CAAC,SAAS,EAAE;gBAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;YAElE,MAAM,MAAM,GAAG,MAAM,aAAa,EAAE,CAAC;YACrC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;gBACvB,mBAAmB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACnC,OAAO,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;YACjD,CAAC;YAED,OAAO,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,CAAC;QACjE,CAAC;KACD,CAAC;AACH,CAAC","sourcesContent":["/**\n * The `BashOperations` wrapper (R44-SBX.6).\n *\n * This is the only place the sandbox meets the agent's bash tool. It implements\n * the existing `BashOperations` seam in `../tools/bash.ts` -- the same interface\n * an SSH or container backend would implement -- so the bash tool itself needs\n * no change: `createBashTool(cwd, { operations })` is the whole integration.\n *\n * ## Three states, and the rule that separates them\n *\n * | sandboxing | backend | what runs |\n * |------------|------------|---------------------------------------------|\n * | off | (not asked)| the wrapped local backend, untouched |\n * | on | available | the command, confined by the policy |\n * | on | unavailable| the wrapped local backend, announced once |\n *\n * **Off must be invisible.** Sandboxing off is the default and is what every\n * existing session is: the wrapper forwards `command`, `cwd` and the *same\n * options object* to the wrapped backend and returns its result. It does not\n * resolve a policy, does not construct an env, does not so much as ask the\n * executor whether it exists -- because asking runs a self-test, which spawns\n * processes. The bash tool is the agent's primary limb; a wrapper that subtly\n * changed its timing, its environment or its error text while claiming to be\n * disabled would be a regression paid for by every user who never turned the\n * sandbox on.\n *\n * ## Why `unavailable` falls back, when the rest of this module never does\n *\n * Everywhere else in `src/core/sandbox/`, \"cannot confine\" means \"do not run\".\n * Here it means \"run the way this product ran yesterday\". That inversion is\n * deliberate and is the spec's one explicit departure from Phase 28\n * (`.planning/specs/2026-07-12-bash-sandbox-confinement.md`): the RLM sandbox\n * exists to contain untrusted generated code, so refusing to start is the safe\n * answer; the bash tool *is* the agent, so hard-failing every command on a host\n * without a working backend bricks the product rather than protecting it. The\n * documented posture is to fall back to the permission gate exactly as it works\n * today (R45-SBM.5), which is a strictly-unchanged security posture, not a\n * weakened one.\n *\n * What makes that safe rather than merely convenient is that the fallback is\n * **loud and whole-session**:\n *\n * - It is announced through `onNotice` **once**, not once per command. A\n * per-command warning is noise, and noise is how a security notice gets\n * trained away.\n * - The decision is taken from `SandboxExecutor.status()`, which is asked once\n * and memoised, so a session is either sandboxed or it is not. There is no\n * command-by-command drift where some commands were confined and nobody can\n * say which.\n * - The fallback child is the *ordinary* child: it carries no `DRAHT_SANDBOX`\n * marker and gets no filtered env, so nothing downstream -- a prompt, a\n * script, a future permission decision -- can mistake it for a confined one.\n * The test suite asserts this by checking that an escape write actually\n * *succeeds* in fallback: a fallback that happened to block it would be\n * indistinguishable from confinement the session never had.\n *\n * ## What does *not* fall back\n *\n * Once the backend has reported `available`, a single invocation that cannot be\n * confined -- an unrenderable policy, a cwd that no longer resolves -- is an\n * error, not a fallback. It rejects with `SandboxUnavailableError`. Silently\n * running that one command unconfined in an otherwise-sandboxed session is the\n * exact hole this phase exists to close: the caller believes confinement holds,\n * and the one command that escaped it is the one nobody was told about. Phase 45\n * turns that rejection into the \"rerun unsandboxed?\" approval prompt, which is\n * the same decision made *in the open*.\n *\n * ## Layering note\n *\n * This is the only file in `src/core/sandbox/` that imports from `../tools/`,\n * which is why it is deliberately absent from `./index.ts`: the barrel stays\n * usable by anything that just wants the policy model, without dragging the tool\n * and render layers in behind it -- and a future `bash.ts` that wants to import\n * the sandbox barrel cannot create a cycle.\n */\n\nimport { type BashOperations, createLocalBashOperations } from \"../tools/bash.ts\";\nimport {\n\tcreateSandboxExecutor,\n\ttype SandboxExecutor,\n\ttype SandboxStatus,\n\tSandboxUnavailableError,\n} from \"./executor.ts\";\nimport { resolveSandboxPolicy, type SandboxPolicy, type SandboxPolicyInput } from \"./policy.ts\";\n\n/** Static, or read per invocation so a `/sandbox` toggle takes effect on the next command. */\nexport type SandboxEnabledSource = boolean | (() => boolean);\n\n/**\n * Everything about the policy except `cwd`.\n *\n * `cwd` is not configurable here on purpose: the policy's project root is always\n * the directory the command actually runs in, taken from the `exec` call itself.\n * A separately-configured root could drift from the real working directory, and\n * a write allowlist that does not contain the cwd is the kind of mismatch that\n * gets \"fixed\" by widening the allowlist. Anything else that must be writable is\n * `extraWritePaths`, which is explicit and visible.\n */\nexport type SandboxPolicyOverrides = Omit<SandboxPolicyInput, \"cwd\">;\n\n/** Static, or read per invocation so settings changes take effect without a restart. */\nexport type SandboxPolicySource = SandboxPolicyOverrides | (() => SandboxPolicyOverrides);\n\n/**\n * Something the caller must be able to show the user. Both kinds are emitted at\n * most once per distinct fact per wrapper, never once per command.\n */\nexport type SandboxNotice =\n\t| {\n\t\t\treadonly kind: \"unavailable\";\n\t\t\t/** Backend that could not confine, for diagnostics (`\"seatbelt\"`, `\"unavailable\"`, ...). */\n\t\t\treadonly backend: string;\n\t\t\treadonly reason: string;\n\t }\n\t| {\n\t\t\t/** A configured write path was dropped from the policy. Narrowing, but never silent. */\n\t\t\treadonly kind: \"write-path-rejected\";\n\t\t\t/** The entry exactly as configured, so the user can find it in their settings. */\n\t\t\treadonly input: string;\n\t\t\treadonly reason: string;\n\t };\n\nexport interface SandboxedBashOperationsOptions {\n\t/**\n\t * The unsandboxed backend, used when sandboxing is off or unavailable.\n\t * Defaults to `createLocalBashOperations({ shellPath })` -- the same call the\n\t * bash tool makes for itself, so the fallback path is not a reimplementation\n\t * of local execution but literally the existing one.\n\t */\n\toperations?: BashOperations;\n\t/** Explicit shell path from settings, forwarded to the default local backend. */\n\tshellPath?: string;\n\t/** Defaults to `createSandboxExecutor()` (platform backend, or an unavailable one with a reason). */\n\texecutor?: SandboxExecutor;\n\t/** Session sandbox state. Defaults to `false`: nothing becomes sandboxed by accident. */\n\tenabled?: SandboxEnabledSource;\n\t/** Policy inputs other than `cwd`. */\n\tpolicy?: SandboxPolicySource;\n\t/** Where user-visible sandbox facts go. Phase 45 wires this to the UI. */\n\tonNotice?: (notice: SandboxNotice) => void;\n}\n\nexport interface SandboxedBashOperations extends BashOperations {\n\t/** Backend identity for diagnostics. */\n\treadonly backendName: string;\n\t/**\n\t * The backend's status, asked once and memoised.\n\t *\n\t * Answers \"*can* this session sandbox?\", which is a different question from\n\t * \"is sandboxing on?\" -- Phase 45 needs the former to decide whether to offer\n\t * `/sandbox on` at all. Calling it runs the R44-SBX.4 self-test, so it is not\n\t * called implicitly while sandboxing is off.\n\t */\n\tsandboxStatus(): Promise<SandboxStatus>;\n}\n\n/**\n * Wraps a local `BashOperations` with OS-level confinement.\n *\n * The returned object is a drop-in for `createLocalBashOperations()`; with\n * `enabled` false (the default) it *is* that backend, one function call deeper.\n */\nexport function createSandboxedBashOperations(options: SandboxedBashOperationsOptions = {}): SandboxedBashOperations {\n\tconst fallback = options.operations ?? createLocalBashOperations({ shellPath: options.shellPath });\n\tconst executor = options.executor ?? createSandboxExecutor();\n\tconst enabledSource = options.enabled ?? false;\n\tconst policySource = options.policy ?? {};\n\tconst onNotice = options.onNotice;\n\n\tconst isEnabled = (): boolean => (typeof enabledSource === \"function\" ? enabledSource() : enabledSource);\n\n\tlet unavailableAnnounced = false;\n\tconst announcedRejections = new Set<string>();\n\n\tconst announceUnavailable = (reason: string): void => {\n\t\tif (unavailableAnnounced) return;\n\t\tunavailableAnnounced = true;\n\t\tonNotice?.({ kind: \"unavailable\", backend: executor.name, reason });\n\t};\n\n\tconst announceRejection = (input: string, reason: string): void => {\n\t\tconst key = JSON.stringify([input, reason]);\n\t\tif (announcedRejections.has(key)) return;\n\t\tannouncedRejections.add(key);\n\t\tonNotice?.({ kind: \"write-path-rejected\", input, reason });\n\t};\n\n\tlet statusPromise: Promise<SandboxStatus> | undefined;\n\tconst sandboxStatus = (): Promise<SandboxStatus> => {\n\t\t// `Promise.resolve().then(...)` rather than a bare call: `status()` is\n\t\t// documented never to throw, but a caller-supplied executor is not bound by\n\t\t// our documentation, and a synchronous throw here would escape as an\n\t\t// exception from the *bash tool* rather than as \"we could not confine\".\n\t\tstatusPromise ??= Promise.resolve()\n\t\t\t.then(() => executor.status())\n\t\t\t.catch((err) => ({\n\t\t\t\tavailable: false as const,\n\t\t\t\treason: `sandbox backend ${JSON.stringify(executor.name)} could not report its status: ${\n\t\t\t\t\terr instanceof Error ? err.message : String(err)\n\t\t\t\t}`,\n\t\t\t}));\n\t\treturn statusPromise;\n\t};\n\n\t/**\n\t * Resolved fresh for every invocation, not cached by cwd.\n\t *\n\t * Real-path resolution is a claim about the filesystem *now*: a directory in\n\t * the allowlist can be replaced by a symlink between two commands in the same\n\t * session, and a policy cached from before that swap would authorise a path\n\t * that no longer means what it meant. It matches the backends, which\n\t * regenerate their profile per invocation for the same reason. Phase 46 owns\n\t * the spawn-overhead budget and can revisit this with numbers.\n\t */\n\tconst policyFor = (cwd: string): SandboxPolicy => {\n\t\tconst overrides = typeof policySource === \"function\" ? policySource() : policySource;\n\t\tlet resolution: ReturnType<typeof resolveSandboxPolicy>;\n\t\ttry {\n\t\t\tresolution = resolveSandboxPolicy({ ...overrides, cwd });\n\t\t} catch (err) {\n\t\t\t// The policy is what confinement *is*. Not being able to build one is not\n\t\t\t// a reason to run without one.\n\t\t\tthrow new SandboxUnavailableError(\n\t\t\t\t`cannot resolve a sandbox policy for ${JSON.stringify(cwd)}: ${\n\t\t\t\t\terr instanceof Error ? err.message : String(err)\n\t\t\t\t}`,\n\t\t\t);\n\t\t}\n\t\tfor (const rejection of resolution.rejected) announceRejection(rejection.input, rejection.reason);\n\t\treturn resolution.policy;\n\t};\n\n\treturn {\n\t\tbackendName: executor.name,\n\t\tsandboxStatus,\n\t\texec: async (command, cwd, execOptions) => {\n\t\t\t// Sandboxing off: hand the call straight through. Same arguments, same\n\t\t\t// options object, same promise -- nothing to diverge from.\n\t\t\tif (!isEnabled()) return fallback.exec(command, cwd, execOptions);\n\n\t\t\tconst status = await sandboxStatus();\n\t\t\tif (!status.available) {\n\t\t\t\tannounceUnavailable(status.reason);\n\t\t\t\treturn fallback.exec(command, cwd, execOptions);\n\t\t\t}\n\n\t\t\treturn executor.exec(command, cwd, policyFor(cwd), execOptions);\n\t\t},\n\t};\n}\n"]}
@@ -0,0 +1,83 @@
1
+ /**
2
+ * Environment hygiene for the sandboxed child (R44-SBX.5).
3
+ *
4
+ * The child gets a **constructed** environment, never `{ ...process.env }` and
5
+ * never the caller's env object passed straight through. The caller's env is
6
+ * treated as a *source of values*; the allowlist below is the *gate*.
7
+ *
8
+ * ## Why an allowlist and not a denylist
9
+ *
10
+ * A denylist has to enumerate every secret-bearing variable that exists, which
11
+ * is unbounded and grows with every tool a user installs -- `ANTHROPIC_API_KEY`,
12
+ * `AWS_SECRET_ACCESS_KEY`, `GH_TOKEN`, `NPM_TOKEN`, `OP_SERVICE_ACCOUNT_TOKEN`,
13
+ * whatever tomorrow ships. Getting a denylist wrong leaks a credential; getting
14
+ * an allowlist wrong breaks a build, loudly, and the user tells us. Only one of
15
+ * those two failure modes is recoverable.
16
+ *
17
+ * This matters *more* here than it did in Phase 28, not less. Phase 28's RLM
18
+ * sandbox denies network outright, so a leaked key could at worst be written
19
+ * into the session workdir. The bash sandbox's network is **on by default**
20
+ * (R44-SBX.2 -- dev workflows need `npm install` and `git fetch`), so a variable
21
+ * that reaches the child is a variable that can leave the machine. The write
22
+ * allowlist bounds what a command can *destroy*; only this list bounds what it
23
+ * can *disclose*.
24
+ *
25
+ * ## What is on the list, and why
26
+ *
27
+ * Everything here is either (a) needed to make a shell and a toolchain behave
28
+ * like the user's own shell -- `PATH`, `HOME`, `SHELL`, `TMPDIR`, locale, `TERM`
29
+ * -- or (b) a `DRAHT_*` session variable the bash tool sets deliberately for
30
+ * user scripts to read (see `resolveSpawnContext` in `../tools/bash.ts`), none
31
+ * of which carry credentials.
32
+ *
33
+ * Deliberately **absent**, and worth stating because each is a thing somebody
34
+ * will eventually ask for:
35
+ *
36
+ * - `SSH_AUTH_SOCK` / `GPG_AGENT_INFO` -- handles to an agent holding live
37
+ * private keys. Forwarding one lets anything in the sandbox sign and
38
+ * authenticate as the user; the filesystem allowlist does not bound that at
39
+ * all. `git push` over SSH therefore does not work inside the sandbox, which
40
+ * is the correct default (the spec keeps outward-facing operations prompting
41
+ * in Phase 45 anyway).
42
+ * - `*_TOKEN`, `*_API_KEY`, `AWS_*`, `NPM_TOKEN`, ... -- the whole point.
43
+ * - `NODE_OPTIONS`, `BASH_ENV`, `ENV`, `LD_PRELOAD`, `DYLD_INSERT_LIBRARIES` --
44
+ * these inject code into the child before its first line runs. They are not
45
+ * secrets, they are execution vectors, and inheriting them silently would let
46
+ * the *parent's* configuration decide what the sandboxed shell actually does.
47
+ *
48
+ * A project that genuinely needs one of these passes it through
49
+ * `extraAllowedNames` (Phase 45 wires that to settings) -- an explicit, visible,
50
+ * per-project decision rather than an accident of inheritance.
51
+ */
52
+ /** Set in every sandboxed child, so scripts and prompts can detect confinement. */
53
+ export declare const SANDBOX_ENV_MARKER = "DRAHT_SANDBOX";
54
+ /**
55
+ * The only variable names that may reach a sandboxed child by default.
56
+ * See the module doc for the reasoning and for what is deliberately missing.
57
+ */
58
+ export declare const SANDBOX_ENV_ALLOWLIST: readonly string[];
59
+ export interface BuildSandboxEnvOptions {
60
+ /**
61
+ * Where values are read from. Defaults to `process.env`. The bash tool passes
62
+ * its own prepared env here; passing it does **not** widen what is exported,
63
+ * it only changes the values the allowlist picks up.
64
+ */
65
+ source?: NodeJS.ProcessEnv;
66
+ /** Additional names to admit, from project settings. Explicit by construction. */
67
+ extraAllowedNames?: readonly string[];
68
+ /**
69
+ * Values forced after filtering, regardless of the source. Used for variables
70
+ * the sandbox itself decides (a `TMPDIR` that is inside the write allowlist,
71
+ * for instance).
72
+ */
73
+ overrides?: NodeJS.ProcessEnv;
74
+ }
75
+ /**
76
+ * Builds the child environment from the allowlist.
77
+ *
78
+ * A name absent from the source stays absent from the result -- the function
79
+ * never invents a default, because a fabricated `HOME` or `PATH` is a behaviour
80
+ * difference that would be blamed on the sandbox rather than on the caller.
81
+ */
82
+ export declare function buildSandboxEnv(options?: BuildSandboxEnvOptions): NodeJS.ProcessEnv;
83
+ //# sourceMappingURL=env.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,mFAAmF;AACnF,eAAO,MAAM,kBAAkB,kBAAkB,CAAC;AAElD;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAuCjD,CAAC;AAEH,MAAM,WAAW,sBAAsB;IACtC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAC3B,kFAAkF;IAClF,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAAC,UAAU,CAevF"}
@@ -0,0 +1,123 @@
1
+ /**
2
+ * Environment hygiene for the sandboxed child (R44-SBX.5).
3
+ *
4
+ * The child gets a **constructed** environment, never `{ ...process.env }` and
5
+ * never the caller's env object passed straight through. The caller's env is
6
+ * treated as a *source of values*; the allowlist below is the *gate*.
7
+ *
8
+ * ## Why an allowlist and not a denylist
9
+ *
10
+ * A denylist has to enumerate every secret-bearing variable that exists, which
11
+ * is unbounded and grows with every tool a user installs -- `ANTHROPIC_API_KEY`,
12
+ * `AWS_SECRET_ACCESS_KEY`, `GH_TOKEN`, `NPM_TOKEN`, `OP_SERVICE_ACCOUNT_TOKEN`,
13
+ * whatever tomorrow ships. Getting a denylist wrong leaks a credential; getting
14
+ * an allowlist wrong breaks a build, loudly, and the user tells us. Only one of
15
+ * those two failure modes is recoverable.
16
+ *
17
+ * This matters *more* here than it did in Phase 28, not less. Phase 28's RLM
18
+ * sandbox denies network outright, so a leaked key could at worst be written
19
+ * into the session workdir. The bash sandbox's network is **on by default**
20
+ * (R44-SBX.2 -- dev workflows need `npm install` and `git fetch`), so a variable
21
+ * that reaches the child is a variable that can leave the machine. The write
22
+ * allowlist bounds what a command can *destroy*; only this list bounds what it
23
+ * can *disclose*.
24
+ *
25
+ * ## What is on the list, and why
26
+ *
27
+ * Everything here is either (a) needed to make a shell and a toolchain behave
28
+ * like the user's own shell -- `PATH`, `HOME`, `SHELL`, `TMPDIR`, locale, `TERM`
29
+ * -- or (b) a `DRAHT_*` session variable the bash tool sets deliberately for
30
+ * user scripts to read (see `resolveSpawnContext` in `../tools/bash.ts`), none
31
+ * of which carry credentials.
32
+ *
33
+ * Deliberately **absent**, and worth stating because each is a thing somebody
34
+ * will eventually ask for:
35
+ *
36
+ * - `SSH_AUTH_SOCK` / `GPG_AGENT_INFO` -- handles to an agent holding live
37
+ * private keys. Forwarding one lets anything in the sandbox sign and
38
+ * authenticate as the user; the filesystem allowlist does not bound that at
39
+ * all. `git push` over SSH therefore does not work inside the sandbox, which
40
+ * is the correct default (the spec keeps outward-facing operations prompting
41
+ * in Phase 45 anyway).
42
+ * - `*_TOKEN`, `*_API_KEY`, `AWS_*`, `NPM_TOKEN`, ... -- the whole point.
43
+ * - `NODE_OPTIONS`, `BASH_ENV`, `ENV`, `LD_PRELOAD`, `DYLD_INSERT_LIBRARIES` --
44
+ * these inject code into the child before its first line runs. They are not
45
+ * secrets, they are execution vectors, and inheriting them silently would let
46
+ * the *parent's* configuration decide what the sandboxed shell actually does.
47
+ *
48
+ * A project that genuinely needs one of these passes it through
49
+ * `extraAllowedNames` (Phase 45 wires that to settings) -- an explicit, visible,
50
+ * per-project decision rather than an accident of inheritance.
51
+ */
52
+ /** Set in every sandboxed child, so scripts and prompts can detect confinement. */
53
+ export const SANDBOX_ENV_MARKER = "DRAHT_SANDBOX";
54
+ /**
55
+ * The only variable names that may reach a sandboxed child by default.
56
+ * See the module doc for the reasoning and for what is deliberately missing.
57
+ */
58
+ export const SANDBOX_ENV_ALLOWLIST = Object.freeze([
59
+ // Shell and toolchain basics.
60
+ "PATH",
61
+ "HOME",
62
+ "SHELL",
63
+ "USER",
64
+ "LOGNAME",
65
+ // Kept deliberately: the unsandboxed backend inherits it too, and bash
66
+ // overrides a stale value against the real cwd (verified). Dropping it would
67
+ // make `$PWD` report the physical path where the unsandboxed shell reports
68
+ // the logical one -- a gratuitous behaviour difference, not a safety gain.
69
+ "PWD",
70
+ "TMPDIR",
71
+ "TMP",
72
+ "TEMP",
73
+ // Terminal presentation. Without these, tools that colourise or wrap output
74
+ // behave differently inside the sandbox than outside it, which reads as the
75
+ // sandbox "breaking" things it did not break.
76
+ "TERM",
77
+ "COLORTERM",
78
+ "COLUMNS",
79
+ "LINES",
80
+ // Locale. Absent these, some toolchains fall back to ASCII and mangle output.
81
+ "LANG",
82
+ "LANGUAGE",
83
+ "LC_ALL",
84
+ "LC_COLLATE",
85
+ "LC_CTYPE",
86
+ "LC_MESSAGES",
87
+ "LC_MONETARY",
88
+ "LC_NUMERIC",
89
+ "LC_TIME",
90
+ "TZ",
91
+ // Session metadata the bash tool sets on purpose for user scripts.
92
+ "DRAHT_SESSION_ID",
93
+ "DRAHT_SESSION_FILE",
94
+ "DRAHT_PROVIDER",
95
+ "DRAHT_MODEL",
96
+ "DRAHT_REASONING_LEVEL",
97
+ ]);
98
+ /**
99
+ * Builds the child environment from the allowlist.
100
+ *
101
+ * A name absent from the source stays absent from the result -- the function
102
+ * never invents a default, because a fabricated `HOME` or `PATH` is a behaviour
103
+ * difference that would be blamed on the sandbox rather than on the caller.
104
+ */
105
+ export function buildSandboxEnv(options = {}) {
106
+ const source = options.source ?? process.env;
107
+ const allowed = new Set(SANDBOX_ENV_ALLOWLIST);
108
+ for (const name of options.extraAllowedNames ?? [])
109
+ allowed.add(name);
110
+ const env = {};
111
+ for (const name of allowed) {
112
+ const value = source[name];
113
+ if (value !== undefined)
114
+ env[name] = value;
115
+ }
116
+ for (const [name, value] of Object.entries(options.overrides ?? {})) {
117
+ if (value !== undefined)
118
+ env[name] = value;
119
+ }
120
+ env[SANDBOX_ENV_MARKER] = "1";
121
+ return env;
122
+ }
123
+ //# sourceMappingURL=env.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/core/sandbox/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,mFAAmF;AACnF,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC;AAElD;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACrE,8BAA8B;IAC9B,MAAM;IACN,MAAM;IACN,OAAO;IACP,MAAM;IACN,SAAS;IACT,uEAAuE;IACvE,6EAA6E;IAC7E,2EAA2E;IAC3E,2EAA2E;IAC3E,KAAK;IACL,QAAQ;IACR,KAAK;IACL,MAAM;IACN,4EAA4E;IAC5E,4EAA4E;IAC5E,8CAA8C;IAC9C,MAAM;IACN,WAAW;IACX,SAAS;IACT,OAAO;IACP,8EAA8E;IAC9E,MAAM;IACN,UAAU;IACV,QAAQ;IACR,YAAY;IACZ,UAAU;IACV,aAAa;IACb,aAAa;IACb,YAAY;IACZ,SAAS;IACT,IAAI;IACJ,mEAAmE;IACnE,kBAAkB;IAClB,oBAAoB;IACpB,gBAAgB;IAChB,aAAa;IACb,uBAAuB;CACvB,CAAC,CAAC;AAmBH;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,OAAO,GAA2B,EAAE;IACnE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC;IAC7C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,qBAAqB,CAAC,CAAC;IACvD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,iBAAiB,IAAI,EAAE;QAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAEtE,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IAC5C,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,CAAC;QACrE,IAAI,KAAK,KAAK,SAAS;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IAC5C,CAAC;IACD,GAAG,CAAC,kBAAkB,CAAC,GAAG,GAAG,CAAC;IAC9B,OAAO,GAAG,CAAC;AACZ,CAAC","sourcesContent":["/**\n * Environment hygiene for the sandboxed child (R44-SBX.5).\n *\n * The child gets a **constructed** environment, never `{ ...process.env }` and\n * never the caller's env object passed straight through. The caller's env is\n * treated as a *source of values*; the allowlist below is the *gate*.\n *\n * ## Why an allowlist and not a denylist\n *\n * A denylist has to enumerate every secret-bearing variable that exists, which\n * is unbounded and grows with every tool a user installs -- `ANTHROPIC_API_KEY`,\n * `AWS_SECRET_ACCESS_KEY`, `GH_TOKEN`, `NPM_TOKEN`, `OP_SERVICE_ACCOUNT_TOKEN`,\n * whatever tomorrow ships. Getting a denylist wrong leaks a credential; getting\n * an allowlist wrong breaks a build, loudly, and the user tells us. Only one of\n * those two failure modes is recoverable.\n *\n * This matters *more* here than it did in Phase 28, not less. Phase 28's RLM\n * sandbox denies network outright, so a leaked key could at worst be written\n * into the session workdir. The bash sandbox's network is **on by default**\n * (R44-SBX.2 -- dev workflows need `npm install` and `git fetch`), so a variable\n * that reaches the child is a variable that can leave the machine. The write\n * allowlist bounds what a command can *destroy*; only this list bounds what it\n * can *disclose*.\n *\n * ## What is on the list, and why\n *\n * Everything here is either (a) needed to make a shell and a toolchain behave\n * like the user's own shell -- `PATH`, `HOME`, `SHELL`, `TMPDIR`, locale, `TERM`\n * -- or (b) a `DRAHT_*` session variable the bash tool sets deliberately for\n * user scripts to read (see `resolveSpawnContext` in `../tools/bash.ts`), none\n * of which carry credentials.\n *\n * Deliberately **absent**, and worth stating because each is a thing somebody\n * will eventually ask for:\n *\n * - `SSH_AUTH_SOCK` / `GPG_AGENT_INFO` -- handles to an agent holding live\n * private keys. Forwarding one lets anything in the sandbox sign and\n * authenticate as the user; the filesystem allowlist does not bound that at\n * all. `git push` over SSH therefore does not work inside the sandbox, which\n * is the correct default (the spec keeps outward-facing operations prompting\n * in Phase 45 anyway).\n * - `*_TOKEN`, `*_API_KEY`, `AWS_*`, `NPM_TOKEN`, ... -- the whole point.\n * - `NODE_OPTIONS`, `BASH_ENV`, `ENV`, `LD_PRELOAD`, `DYLD_INSERT_LIBRARIES` --\n * these inject code into the child before its first line runs. They are not\n * secrets, they are execution vectors, and inheriting them silently would let\n * the *parent's* configuration decide what the sandboxed shell actually does.\n *\n * A project that genuinely needs one of these passes it through\n * `extraAllowedNames` (Phase 45 wires that to settings) -- an explicit, visible,\n * per-project decision rather than an accident of inheritance.\n */\n\n/** Set in every sandboxed child, so scripts and prompts can detect confinement. */\nexport const SANDBOX_ENV_MARKER = \"DRAHT_SANDBOX\";\n\n/**\n * The only variable names that may reach a sandboxed child by default.\n * See the module doc for the reasoning and for what is deliberately missing.\n */\nexport const SANDBOX_ENV_ALLOWLIST: readonly string[] = Object.freeze([\n\t// Shell and toolchain basics.\n\t\"PATH\",\n\t\"HOME\",\n\t\"SHELL\",\n\t\"USER\",\n\t\"LOGNAME\",\n\t// Kept deliberately: the unsandboxed backend inherits it too, and bash\n\t// overrides a stale value against the real cwd (verified). Dropping it would\n\t// make `$PWD` report the physical path where the unsandboxed shell reports\n\t// the logical one -- a gratuitous behaviour difference, not a safety gain.\n\t\"PWD\",\n\t\"TMPDIR\",\n\t\"TMP\",\n\t\"TEMP\",\n\t// Terminal presentation. Without these, tools that colourise or wrap output\n\t// behave differently inside the sandbox than outside it, which reads as the\n\t// sandbox \"breaking\" things it did not break.\n\t\"TERM\",\n\t\"COLORTERM\",\n\t\"COLUMNS\",\n\t\"LINES\",\n\t// Locale. Absent these, some toolchains fall back to ASCII and mangle output.\n\t\"LANG\",\n\t\"LANGUAGE\",\n\t\"LC_ALL\",\n\t\"LC_COLLATE\",\n\t\"LC_CTYPE\",\n\t\"LC_MESSAGES\",\n\t\"LC_MONETARY\",\n\t\"LC_NUMERIC\",\n\t\"LC_TIME\",\n\t\"TZ\",\n\t// Session metadata the bash tool sets on purpose for user scripts.\n\t\"DRAHT_SESSION_ID\",\n\t\"DRAHT_SESSION_FILE\",\n\t\"DRAHT_PROVIDER\",\n\t\"DRAHT_MODEL\",\n\t\"DRAHT_REASONING_LEVEL\",\n]);\n\nexport interface BuildSandboxEnvOptions {\n\t/**\n\t * Where values are read from. Defaults to `process.env`. The bash tool passes\n\t * its own prepared env here; passing it does **not** widen what is exported,\n\t * it only changes the values the allowlist picks up.\n\t */\n\tsource?: NodeJS.ProcessEnv;\n\t/** Additional names to admit, from project settings. Explicit by construction. */\n\textraAllowedNames?: readonly string[];\n\t/**\n\t * Values forced after filtering, regardless of the source. Used for variables\n\t * the sandbox itself decides (a `TMPDIR` that is inside the write allowlist,\n\t * for instance).\n\t */\n\toverrides?: NodeJS.ProcessEnv;\n}\n\n/**\n * Builds the child environment from the allowlist.\n *\n * A name absent from the source stays absent from the result -- the function\n * never invents a default, because a fabricated `HOME` or `PATH` is a behaviour\n * difference that would be blamed on the sandbox rather than on the caller.\n */\nexport function buildSandboxEnv(options: BuildSandboxEnvOptions = {}): NodeJS.ProcessEnv {\n\tconst source = options.source ?? process.env;\n\tconst allowed = new Set<string>(SANDBOX_ENV_ALLOWLIST);\n\tfor (const name of options.extraAllowedNames ?? []) allowed.add(name);\n\n\tconst env: NodeJS.ProcessEnv = {};\n\tfor (const name of allowed) {\n\t\tconst value = source[name];\n\t\tif (value !== undefined) env[name] = value;\n\t}\n\tfor (const [name, value] of Object.entries(options.overrides ?? {})) {\n\t\tif (value !== undefined) env[name] = value;\n\t}\n\tenv[SANDBOX_ENV_MARKER] = \"1\";\n\treturn env;\n}\n"]}
@@ -0,0 +1,104 @@
1
+ /**
2
+ * The `SandboxExecutor` seam (R44-SBX.1).
3
+ *
4
+ * One interface, one status question, one execute path. Platform backends
5
+ * (macOS Seatbelt, Linux Landlock/namespaces) implement it; unsupported
6
+ * platforms get `createUnavailableSandboxExecutor`.
7
+ *
8
+ * ## The status contract
9
+ *
10
+ * `status()` answers `available` **only** with evidence -- for a real backend
11
+ * that means a passing startup self-test (R44-SBX.4). It never throws: a status
12
+ * call that blew up would be indistinguishable at the call site from "we do not
13
+ * know", and "we do not know" must read as `unavailable`.
14
+ *
15
+ * A sandbox that reports `available` while not confining is worse than no
16
+ * sandbox: it converts a known risk into a false guarantee, and every downstream
17
+ * permission decision inherits the lie. So `unavailable` is the only degraded
18
+ * state there is. There is no "available but partially confining", and no path
19
+ * anywhere in this module that runs a command unconfined.
20
+ *
21
+ * ## Why `exec` rejects instead of falling back
22
+ *
23
+ * `exec` on an unavailable executor rejects with `SandboxUnavailableError`. It
24
+ * cannot run the command -- running it would run it unconfined, which is the one
25
+ * thing this module must never do. Callers check `status()` first and, when it
26
+ * is `unavailable`, take the *documented* fallback (Phase 45: the permission
27
+ * gate exactly as it works today, with a one-time notice). That fallback is a
28
+ * decision made in the open by the caller, not a silent slide inside the
29
+ * sandbox.
30
+ */
31
+ import type { SandboxPolicy } from "./policy.ts";
32
+ export type SandboxStatus = {
33
+ readonly available: true;
34
+ } | {
35
+ readonly available: false;
36
+ readonly reason: string;
37
+ };
38
+ export interface SandboxExecOptions {
39
+ /** Streamed stdout+stderr, matching `BashOperations.exec` (R44-SBX.6). */
40
+ readonly onData: (data: Buffer) => void;
41
+ readonly signal?: AbortSignal;
42
+ /** Seconds, matching the bash tool's units. */
43
+ readonly timeout?: number;
44
+ /**
45
+ * Environment for the sandboxed child. Backends apply env hygiene
46
+ * (R44-SBX.5) on top: the child never receives the full parent environment.
47
+ */
48
+ readonly env?: NodeJS.ProcessEnv;
49
+ }
50
+ export interface SandboxExecResult {
51
+ /** `null` when the process was killed. */
52
+ readonly exitCode: number | null;
53
+ }
54
+ export interface SandboxExecutor {
55
+ /** Backend identity for diagnostics, e.g. `"seatbelt"`, `"landlock"`, `"unavailable"`. */
56
+ readonly name: string;
57
+ /** Never throws. Backends cache their self-test result behind this. */
58
+ status(): Promise<SandboxStatus>;
59
+ /**
60
+ * Runs `command` confined by `policy`. Rejects with `SandboxUnavailableError`
61
+ * when the backend cannot confine -- never runs the command unconfined.
62
+ */
63
+ exec(command: string, cwd: string, policy: SandboxPolicy, options: SandboxExecOptions): Promise<SandboxExecResult>;
64
+ }
65
+ /** Thrown by `exec` when confinement cannot be established. Carries the same reason `status()` reports. */
66
+ export declare class SandboxUnavailableError extends Error {
67
+ readonly reason: string;
68
+ constructor(reason: string);
69
+ }
70
+ /** Platforms a backend can exist for. Everything else is `unavailable` by construction. */
71
+ export declare const SUPPORTED_SANDBOX_PLATFORMS: readonly NodeJS.Platform[];
72
+ export interface SandboxBackendFactory {
73
+ readonly platform: NodeJS.Platform;
74
+ create(): SandboxExecutor;
75
+ }
76
+ /**
77
+ * Backends registered for the current build.
78
+ *
79
+ * Registration says a backend *exists* for the platform, nothing more. Both
80
+ * entries construct an executor whose `status()` still has to pass the
81
+ * R44-SBX.4 self-test before it will run anything, so appearing in this list is
82
+ * never itself a claim of confinement -- which is what makes it safe to register
83
+ * the Linux backend from a machine that cannot run it.
84
+ *
85
+ * `create()` is a thunk, so the platform module is only instantiated for the
86
+ * platform actually in use and a factory that throws is caught below.
87
+ */
88
+ export declare const BUILTIN_SANDBOX_BACKENDS: readonly SandboxBackendFactory[];
89
+ /** An executor that is permanently unavailable for a stated reason. */
90
+ export declare function createUnavailableSandboxExecutor(reason: string, name?: string): SandboxExecutor;
91
+ export interface CreateSandboxExecutorOptions {
92
+ /** Defaults to `process.platform`. */
93
+ platform?: NodeJS.Platform;
94
+ /** Defaults to `BUILTIN_SANDBOX_BACKENDS`. */
95
+ backends?: readonly SandboxBackendFactory[];
96
+ }
97
+ /**
98
+ * Picks the backend for `platform`, or an unavailable executor with a reason.
99
+ *
100
+ * Never throws -- a backend factory that throws while constructing is itself a
101
+ * reason to report `unavailable`.
102
+ */
103
+ export declare function createSandboxExecutor(options?: CreateSandboxExecutorOptions): SandboxExecutor;
104
+ //# sourceMappingURL=executor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/core/sandbox/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElH,MAAM,WAAW,kBAAkB;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC/B,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IACjC;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACnH;AAED,2GAA2G;AAC3G,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,YAAY,MAAM,EAAE,MAAM,EAIzB;CACD;AAED,2FAA2F;AAC3F,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,CAAC,QAAQ,EAAwB,CAAC;AAE3F,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IACnC,MAAM,IAAI,eAAe,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,EAAE,SAAS,qBAAqB,EAGpE,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,SAAgB,GAAG,eAAe,CAQtG;AAED,MAAM,WAAW,4BAA4B;IAC5C,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC5C;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,4BAAiC,GAAG,eAAe,CA0BjG"}
@@ -0,0 +1,92 @@
1
+ /**
2
+ * The `SandboxExecutor` seam (R44-SBX.1).
3
+ *
4
+ * One interface, one status question, one execute path. Platform backends
5
+ * (macOS Seatbelt, Linux Landlock/namespaces) implement it; unsupported
6
+ * platforms get `createUnavailableSandboxExecutor`.
7
+ *
8
+ * ## The status contract
9
+ *
10
+ * `status()` answers `available` **only** with evidence -- for a real backend
11
+ * that means a passing startup self-test (R44-SBX.4). It never throws: a status
12
+ * call that blew up would be indistinguishable at the call site from "we do not
13
+ * know", and "we do not know" must read as `unavailable`.
14
+ *
15
+ * A sandbox that reports `available` while not confining is worse than no
16
+ * sandbox: it converts a known risk into a false guarantee, and every downstream
17
+ * permission decision inherits the lie. So `unavailable` is the only degraded
18
+ * state there is. There is no "available but partially confining", and no path
19
+ * anywhere in this module that runs a command unconfined.
20
+ *
21
+ * ## Why `exec` rejects instead of falling back
22
+ *
23
+ * `exec` on an unavailable executor rejects with `SandboxUnavailableError`. It
24
+ * cannot run the command -- running it would run it unconfined, which is the one
25
+ * thing this module must never do. Callers check `status()` first and, when it
26
+ * is `unavailable`, take the *documented* fallback (Phase 45: the permission
27
+ * gate exactly as it works today, with a one-time notice). That fallback is a
28
+ * decision made in the open by the caller, not a silent slide inside the
29
+ * sandbox.
30
+ */
31
+ import { createLinuxSandboxExecutor } from "./linux.js";
32
+ import { createSeatbeltSandboxExecutor } from "./seatbelt.js";
33
+ /** Thrown by `exec` when confinement cannot be established. Carries the same reason `status()` reports. */
34
+ export class SandboxUnavailableError extends Error {
35
+ constructor(reason) {
36
+ super(`sandbox unavailable: ${reason}`);
37
+ this.name = "SandboxUnavailableError";
38
+ this.reason = reason;
39
+ }
40
+ }
41
+ /** Platforms a backend can exist for. Everything else is `unavailable` by construction. */
42
+ export const SUPPORTED_SANDBOX_PLATFORMS = ["darwin", "linux"];
43
+ /**
44
+ * Backends registered for the current build.
45
+ *
46
+ * Registration says a backend *exists* for the platform, nothing more. Both
47
+ * entries construct an executor whose `status()` still has to pass the
48
+ * R44-SBX.4 self-test before it will run anything, so appearing in this list is
49
+ * never itself a claim of confinement -- which is what makes it safe to register
50
+ * the Linux backend from a machine that cannot run it.
51
+ *
52
+ * `create()` is a thunk, so the platform module is only instantiated for the
53
+ * platform actually in use and a factory that throws is caught below.
54
+ */
55
+ export const BUILTIN_SANDBOX_BACKENDS = [
56
+ { platform: "darwin", create: () => createSeatbeltSandboxExecutor() },
57
+ { platform: "linux", create: () => createLinuxSandboxExecutor() },
58
+ ];
59
+ /** An executor that is permanently unavailable for a stated reason. */
60
+ export function createUnavailableSandboxExecutor(reason, name = "unavailable") {
61
+ return {
62
+ name,
63
+ status: async () => ({ available: false, reason }),
64
+ exec: async () => {
65
+ throw new SandboxUnavailableError(reason);
66
+ },
67
+ };
68
+ }
69
+ /**
70
+ * Picks the backend for `platform`, or an unavailable executor with a reason.
71
+ *
72
+ * Never throws -- a backend factory that throws while constructing is itself a
73
+ * reason to report `unavailable`.
74
+ */
75
+ export function createSandboxExecutor(options = {}) {
76
+ const platform = options.platform ?? process.platform;
77
+ const backends = options.backends ?? BUILTIN_SANDBOX_BACKENDS;
78
+ if (!SUPPORTED_SANDBOX_PLATFORMS.includes(platform)) {
79
+ return createUnavailableSandboxExecutor(`no sandbox backend exists for platform ${JSON.stringify(platform)} (supported: ${SUPPORTED_SANDBOX_PLATFORMS.join(", ")})`);
80
+ }
81
+ const factory = backends.find((backend) => backend.platform === platform);
82
+ if (!factory) {
83
+ return createUnavailableSandboxExecutor(`no sandbox backend is registered for platform ${JSON.stringify(platform)} in this build`);
84
+ }
85
+ try {
86
+ return factory.create();
87
+ }
88
+ catch (err) {
89
+ return createUnavailableSandboxExecutor(`sandbox backend for platform ${JSON.stringify(platform)} failed to initialize: ${err instanceof Error ? err.message : String(err)}`);
90
+ }
91
+ }
92
+ //# sourceMappingURL=executor.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"executor.js","sourceRoot":"","sources":["../../../src/core/sandbox/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AAkC9D,2GAA2G;AAC3G,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAEjD,YAAY,MAAc;QACzB,KAAK,CAAC,wBAAwB,MAAM,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD;AAED,2FAA2F;AAC3F,MAAM,CAAC,MAAM,2BAA2B,GAA+B,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAO3F;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAqC;IACzE,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,6BAA6B,EAAE,EAAE;IACrE,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,0BAA0B,EAAE,EAAE;CACjE,CAAC;AAEF,uEAAuE;AACvE,MAAM,UAAU,gCAAgC,CAAC,MAAc,EAAE,IAAI,GAAG,aAAa;IACpF,OAAO;QACN,IAAI;QACJ,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAClD,IAAI,EAAE,KAAK,IAAI,EAAE;YAChB,MAAM,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAC;QAC3C,CAAC;KACD,CAAC;AACH,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAO,GAAiC,EAAE;IAC/E,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IACtD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,wBAAwB,CAAC;IAE9D,IAAI,CAAC,2BAA2B,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrD,OAAO,gCAAgC,CACtC,0CAA0C,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC3H,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC;IAC1E,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,OAAO,gCAAgC,CACtC,iDAAiD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CACzF,CAAC;IACH,CAAC;IAED,IAAI,CAAC;QACJ,OAAO,OAAO,CAAC,MAAM,EAAE,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,OAAO,gCAAgC,CACtC,gCAAgC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,0BACvD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAChD,EAAE,CACF,CAAC;IACH,CAAC;AACF,CAAC","sourcesContent":["/**\n * The `SandboxExecutor` seam (R44-SBX.1).\n *\n * One interface, one status question, one execute path. Platform backends\n * (macOS Seatbelt, Linux Landlock/namespaces) implement it; unsupported\n * platforms get `createUnavailableSandboxExecutor`.\n *\n * ## The status contract\n *\n * `status()` answers `available` **only** with evidence -- for a real backend\n * that means a passing startup self-test (R44-SBX.4). It never throws: a status\n * call that blew up would be indistinguishable at the call site from \"we do not\n * know\", and \"we do not know\" must read as `unavailable`.\n *\n * A sandbox that reports `available` while not confining is worse than no\n * sandbox: it converts a known risk into a false guarantee, and every downstream\n * permission decision inherits the lie. So `unavailable` is the only degraded\n * state there is. There is no \"available but partially confining\", and no path\n * anywhere in this module that runs a command unconfined.\n *\n * ## Why `exec` rejects instead of falling back\n *\n * `exec` on an unavailable executor rejects with `SandboxUnavailableError`. It\n * cannot run the command -- running it would run it unconfined, which is the one\n * thing this module must never do. Callers check `status()` first and, when it\n * is `unavailable`, take the *documented* fallback (Phase 45: the permission\n * gate exactly as it works today, with a one-time notice). That fallback is a\n * decision made in the open by the caller, not a silent slide inside the\n * sandbox.\n */\n\nimport { createLinuxSandboxExecutor } from \"./linux.ts\";\nimport type { SandboxPolicy } from \"./policy.ts\";\nimport { createSeatbeltSandboxExecutor } from \"./seatbelt.ts\";\n\nexport type SandboxStatus = { readonly available: true } | { readonly available: false; readonly reason: string };\n\nexport interface SandboxExecOptions {\n\t/** Streamed stdout+stderr, matching `BashOperations.exec` (R44-SBX.6). */\n\treadonly onData: (data: Buffer) => void;\n\treadonly signal?: AbortSignal;\n\t/** Seconds, matching the bash tool's units. */\n\treadonly timeout?: number;\n\t/**\n\t * Environment for the sandboxed child. Backends apply env hygiene\n\t * (R44-SBX.5) on top: the child never receives the full parent environment.\n\t */\n\treadonly env?: NodeJS.ProcessEnv;\n}\n\nexport interface SandboxExecResult {\n\t/** `null` when the process was killed. */\n\treadonly exitCode: number | null;\n}\n\nexport interface SandboxExecutor {\n\t/** Backend identity for diagnostics, e.g. `\"seatbelt\"`, `\"landlock\"`, `\"unavailable\"`. */\n\treadonly name: string;\n\t/** Never throws. Backends cache their self-test result behind this. */\n\tstatus(): Promise<SandboxStatus>;\n\t/**\n\t * Runs `command` confined by `policy`. Rejects with `SandboxUnavailableError`\n\t * when the backend cannot confine -- never runs the command unconfined.\n\t */\n\texec(command: string, cwd: string, policy: SandboxPolicy, options: SandboxExecOptions): Promise<SandboxExecResult>;\n}\n\n/** Thrown by `exec` when confinement cannot be established. Carries the same reason `status()` reports. */\nexport class SandboxUnavailableError extends Error {\n\treadonly reason: string;\n\tconstructor(reason: string) {\n\t\tsuper(`sandbox unavailable: ${reason}`);\n\t\tthis.name = \"SandboxUnavailableError\";\n\t\tthis.reason = reason;\n\t}\n}\n\n/** Platforms a backend can exist for. Everything else is `unavailable` by construction. */\nexport const SUPPORTED_SANDBOX_PLATFORMS: readonly NodeJS.Platform[] = [\"darwin\", \"linux\"];\n\nexport interface SandboxBackendFactory {\n\treadonly platform: NodeJS.Platform;\n\tcreate(): SandboxExecutor;\n}\n\n/**\n * Backends registered for the current build.\n *\n * Registration says a backend *exists* for the platform, nothing more. Both\n * entries construct an executor whose `status()` still has to pass the\n * R44-SBX.4 self-test before it will run anything, so appearing in this list is\n * never itself a claim of confinement -- which is what makes it safe to register\n * the Linux backend from a machine that cannot run it.\n *\n * `create()` is a thunk, so the platform module is only instantiated for the\n * platform actually in use and a factory that throws is caught below.\n */\nexport const BUILTIN_SANDBOX_BACKENDS: readonly SandboxBackendFactory[] = [\n\t{ platform: \"darwin\", create: () => createSeatbeltSandboxExecutor() },\n\t{ platform: \"linux\", create: () => createLinuxSandboxExecutor() },\n];\n\n/** An executor that is permanently unavailable for a stated reason. */\nexport function createUnavailableSandboxExecutor(reason: string, name = \"unavailable\"): SandboxExecutor {\n\treturn {\n\t\tname,\n\t\tstatus: async () => ({ available: false, reason }),\n\t\texec: async () => {\n\t\t\tthrow new SandboxUnavailableError(reason);\n\t\t},\n\t};\n}\n\nexport interface CreateSandboxExecutorOptions {\n\t/** Defaults to `process.platform`. */\n\tplatform?: NodeJS.Platform;\n\t/** Defaults to `BUILTIN_SANDBOX_BACKENDS`. */\n\tbackends?: readonly SandboxBackendFactory[];\n}\n\n/**\n * Picks the backend for `platform`, or an unavailable executor with a reason.\n *\n * Never throws -- a backend factory that throws while constructing is itself a\n * reason to report `unavailable`.\n */\nexport function createSandboxExecutor(options: CreateSandboxExecutorOptions = {}): SandboxExecutor {\n\tconst platform = options.platform ?? process.platform;\n\tconst backends = options.backends ?? BUILTIN_SANDBOX_BACKENDS;\n\n\tif (!SUPPORTED_SANDBOX_PLATFORMS.includes(platform)) {\n\t\treturn createUnavailableSandboxExecutor(\n\t\t\t`no sandbox backend exists for platform ${JSON.stringify(platform)} (supported: ${SUPPORTED_SANDBOX_PLATFORMS.join(\", \")})`,\n\t\t);\n\t}\n\n\tconst factory = backends.find((backend) => backend.platform === platform);\n\tif (!factory) {\n\t\treturn createUnavailableSandboxExecutor(\n\t\t\t`no sandbox backend is registered for platform ${JSON.stringify(platform)} in this build`,\n\t\t);\n\t}\n\n\ttry {\n\t\treturn factory.create();\n\t} catch (err) {\n\t\treturn createUnavailableSandboxExecutor(\n\t\t\t`sandbox backend for platform ${JSON.stringify(platform)} failed to initialize: ${\n\t\t\t\terr instanceof Error ? err.message : String(err)\n\t\t\t}`,\n\t\t);\n\t}\n}\n"]}