@octopi-agent/engine 0.70.7 → 0.90.11

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 (390) hide show
  1. package/LICENSE +201 -201
  2. package/NOTICE +7 -7
  3. package/README.md +64 -26
  4. package/dist/config-schema/agent.d.ts +89 -1
  5. package/dist/config-schema/agent.js +81 -5
  6. package/dist/config-schema/context.d.ts +24 -5
  7. package/dist/config-schema/context.js +28 -1
  8. package/dist/config-schema/engine.d.ts +205 -13
  9. package/dist/config-schema/engine.js +31 -2
  10. package/dist/config-schema/governance.d.ts +95 -0
  11. package/dist/config-schema/governance.js +93 -1
  12. package/dist/config-schema/models.d.ts +3 -3
  13. package/dist/config-schema/observability.d.ts +6 -0
  14. package/dist/config-schema/observability.js +16 -0
  15. package/dist/config-schema/run.d.ts +10 -0
  16. package/dist/config-schema/run.js +18 -0
  17. package/dist/config-schema/shared.d.ts +13 -0
  18. package/dist/config-schema/shared.js +22 -0
  19. package/dist/config-schema/substrate.d.ts +2 -2
  20. package/dist/config-schema/subsystems.d.ts +1 -1
  21. package/dist/config-schema/subsystems.js +2 -1
  22. package/dist/config.d.ts +201 -8
  23. package/dist/config.js +105 -3
  24. package/dist/harness/activation/compiler.js +3 -0
  25. package/dist/harness/activation/runtime.d.ts +7 -0
  26. package/dist/harness/activation/runtime.js +60 -2
  27. package/dist/harness/activation/sources/agent-signal.d.ts +11 -0
  28. package/dist/harness/activation/sources/agent-signal.js +33 -0
  29. package/dist/harness/activation/types.d.ts +6 -1
  30. package/dist/harness/agent/builder.d.ts +50 -5
  31. package/dist/harness/agent/builder.js +189 -59
  32. package/dist/harness/agent/config-bridge.d.ts +33 -25
  33. package/dist/harness/agent/config-bridge.js +84 -291
  34. package/dist/harness/agent/index.d.ts +3 -1
  35. package/dist/harness/agent/index.js +2 -1
  36. package/dist/harness/agent/tool-purpose.d.ts +46 -0
  37. package/dist/harness/agent/tool-purpose.js +127 -0
  38. package/dist/harness/agent/wire-agent-builder.d.ts +133 -0
  39. package/dist/harness/agent/wire-agent-builder.js +370 -0
  40. package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.d.ts +11 -1
  41. package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.js +11 -1
  42. package/dist/harness/collaboration/autonomous-subsystem/loader.d.ts +13 -0
  43. package/dist/harness/collaboration/autonomous-subsystem/loader.js +16 -1
  44. package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +8 -1
  45. package/dist/harness/collaboration/autonomous-subsystem/runtime.js +17 -9
  46. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.d.ts +12 -0
  47. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.js +19 -0
  48. package/dist/harness/collaboration/autonomous-subsystem/sense/session-lifecycle-bridge.d.ts +6 -0
  49. package/dist/harness/collaboration/autonomous-subsystem/sense/session-lifecycle-bridge.js +24 -7
  50. package/dist/harness/collaboration/autonomous-subsystem/think/executor.d.ts +5 -2
  51. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +11 -3
  52. package/dist/harness/collaboration/autonomous-subsystem/think/index.d.ts +1 -1
  53. package/dist/harness/collaboration/autonomous-subsystem/think/index.js +1 -1
  54. package/dist/harness/collaboration/autonomous-subsystem/think/llm-port.d.ts +7 -4
  55. package/dist/harness/collaboration/autonomous-subsystem/think/llm-port.js +8 -9
  56. package/dist/harness/collaboration/autonomous-subsystem/think/model-resolver.d.ts +36 -10
  57. package/dist/harness/collaboration/autonomous-subsystem/think/model-resolver.js +60 -7
  58. package/dist/harness/collaboration/delegation/child-run.d.ts +144 -0
  59. package/dist/harness/collaboration/delegation/child-run.js +241 -0
  60. package/dist/harness/collaboration/delegation/index.d.ts +26 -0
  61. package/dist/harness/collaboration/delegation/index.js +25 -0
  62. package/dist/harness/collaboration/delegation/notifier.d.ts +46 -0
  63. package/dist/harness/collaboration/delegation/notifier.js +84 -0
  64. package/dist/harness/collaboration/delegation/registry-types.d.ts +200 -0
  65. package/dist/harness/collaboration/delegation/registry-types.js +61 -0
  66. package/dist/harness/collaboration/delegation/registry.d.ts +110 -0
  67. package/dist/harness/collaboration/delegation/registry.js +220 -0
  68. package/dist/harness/collaboration/delegation/service.d.ts +249 -0
  69. package/dist/harness/collaboration/delegation/service.js +499 -0
  70. package/dist/harness/collaboration/delegation/store.d.ts +155 -0
  71. package/dist/harness/collaboration/delegation/store.js +271 -0
  72. package/dist/harness/collaboration/delegation/transport.d.ts +73 -0
  73. package/dist/harness/collaboration/delegation/transport.js +61 -0
  74. package/dist/harness/collaboration/delegation/types.d.ts +231 -0
  75. package/dist/harness/collaboration/delegation/types.js +70 -0
  76. package/dist/harness/collaboration/delegation/wiring.d.ts +111 -0
  77. package/dist/harness/collaboration/delegation/wiring.js +145 -0
  78. package/dist/harness/collaboration/orchestration/index.d.ts +11 -13
  79. package/dist/harness/collaboration/orchestration/index.js +11 -11
  80. package/dist/harness/context/assembler.d.ts +2 -2
  81. package/dist/harness/context/assembler.js +12 -7
  82. package/dist/harness/context/capabilities/compact/engine.js +80 -38
  83. package/dist/harness/context/capabilities/compact/types.d.ts +12 -1
  84. package/dist/harness/context/capabilities/summary/registry.js +10 -0
  85. package/dist/harness/context/constitution/default-agents.md +230 -228
  86. package/dist/harness/context/default-context-engine.d.ts +101 -23
  87. package/dist/harness/context/default-context-engine.js +483 -172
  88. package/dist/harness/context/hybrid-compressor.d.ts +3 -3
  89. package/dist/harness/context/hybrid-compressor.js +18 -23
  90. package/dist/harness/context/index.d.ts +5 -1
  91. package/dist/harness/context/index.js +2 -0
  92. package/dist/harness/context/layer-snapshot.d.ts +4 -0
  93. package/dist/harness/context/layer-snapshot.js +30 -18
  94. package/dist/harness/context/layer-types.d.ts +85 -1
  95. package/dist/harness/context/layer-types.js +110 -4
  96. package/dist/harness/context/layers.d.ts +5 -2
  97. package/dist/harness/context/layers.js +11 -5
  98. package/dist/harness/context/llm-summarizer.d.ts +15 -1
  99. package/dist/harness/context/llm-summarizer.js +107 -56
  100. package/dist/harness/context/message-selector.js +6 -2
  101. package/dist/harness/context/root-instructions.d.ts +72 -0
  102. package/dist/harness/context/root-instructions.js +227 -0
  103. package/dist/harness/context/runtime-datetime.d.ts +34 -7
  104. package/dist/harness/context/runtime-datetime.js +66 -10
  105. package/dist/harness/context/smart-router.d.ts +1 -1
  106. package/dist/harness/context/smart-router.js +1 -1
  107. package/dist/harness/context/system-prompt-assembler.d.ts +30 -0
  108. package/dist/harness/context/system-prompt-assembler.js +73 -6
  109. package/dist/harness/context/token-constants.d.ts +2 -2
  110. package/dist/harness/context/token-constants.js +2 -2
  111. package/dist/harness/context/token-estimate-fns.d.ts +1 -3
  112. package/dist/harness/context/token-estimate-fns.js +2 -4
  113. package/dist/harness/context/token-estimator.d.ts +1 -1
  114. package/dist/harness/context/token-estimator.js +14 -6
  115. package/dist/harness/context/tool-result-aging.d.ts +140 -0
  116. package/dist/harness/context/tool-result-aging.js +331 -0
  117. package/dist/harness/context/tool-result-body.d.ts +10 -0
  118. package/dist/harness/context/tool-result-body.js +27 -0
  119. package/dist/harness/context/turn-envelope.d.ts +123 -0
  120. package/dist/harness/context/turn-envelope.js +188 -0
  121. package/dist/harness/context/types.d.ts +35 -47
  122. package/dist/harness/extension/execution-environment/effect-policy.d.ts +258 -0
  123. package/dist/harness/extension/execution-environment/effect-policy.js +358 -0
  124. package/dist/harness/extension/execution-environment/index.d.ts +18 -2
  125. package/dist/harness/extension/execution-environment/index.js +11 -2
  126. package/dist/harness/extension/execution-environment/isolation.js +5 -1
  127. package/dist/harness/extension/execution-environment/memory-undo.d.ts +101 -0
  128. package/dist/harness/extension/execution-environment/memory-undo.js +192 -0
  129. package/dist/harness/extension/execution-environment/process-isolation.d.ts +84 -0
  130. package/dist/harness/extension/execution-environment/process-isolation.js +315 -0
  131. package/dist/harness/extension/execution-environment/resource-limits.d.ts +36 -0
  132. package/dist/harness/extension/execution-environment/resource-limits.js +84 -0
  133. package/dist/harness/extension/execution-environment/sandbox.d.ts +125 -4
  134. package/dist/harness/extension/execution-environment/sandbox.js +521 -51
  135. package/dist/harness/extension/execution-environment/shell-journal.d.ts +100 -0
  136. package/dist/harness/extension/execution-environment/shell-journal.js +299 -0
  137. package/dist/harness/extension/execution-environment/tool-capabilities.d.ts +45 -0
  138. package/dist/harness/extension/execution-environment/tool-capabilities.js +126 -0
  139. package/dist/harness/extension/execution-environment/types.d.ts +67 -39
  140. package/dist/harness/extension/execution-environment/types.js +2 -2
  141. package/dist/harness/extension/execution-environment/undo-log.d.ts +203 -0
  142. package/dist/harness/extension/execution-environment/undo-log.js +627 -0
  143. package/dist/harness/extension/execution-environment/undo-merge.d.ts +40 -0
  144. package/dist/harness/extension/execution-environment/undo-merge.js +167 -0
  145. package/dist/harness/extension/plugin-ecosystem/client-tools/index.d.ts +1 -1
  146. package/dist/harness/extension/plugin-ecosystem/client-tools/types.d.ts +9 -0
  147. package/dist/harness/extension/plugin-ecosystem/mcp/bridge.js +2 -0
  148. package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +1 -6
  149. package/dist/harness/extension/plugin-ecosystem/plugins/api.js +3 -8
  150. package/dist/harness/extension/plugin-ecosystem/plugins/capability.d.ts +0 -3
  151. package/dist/harness/extension/plugin-ecosystem/plugins/capability.js +0 -3
  152. package/dist/harness/extension/plugin-ecosystem/plugins/entry.d.ts +2 -10
  153. package/dist/harness/extension/plugin-ecosystem/plugins/entry.js +2 -9
  154. package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +1 -3
  155. package/dist/harness/extension/plugin-ecosystem/plugins/index.js +1 -3
  156. package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +2 -4
  157. package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +4 -21
  158. package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +3 -9
  159. package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +4 -8
  160. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +1 -4
  161. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +1 -3
  162. package/dist/harness/extension/plugin-ecosystem/skills/manager.d.ts +1 -1
  163. package/dist/harness/extension/plugin-ecosystem/skills/manager.js +1 -1
  164. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.d.ts +51 -0
  165. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.js +153 -0
  166. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +1 -0
  167. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +18 -3
  168. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +277 -81
  169. package/dist/harness/extension/plugin-ecosystem/tools/delegation.d.ts +31 -0
  170. package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +291 -0
  171. package/dist/harness/extension/plugin-ecosystem/tools/document-tools.js +10 -2
  172. package/dist/harness/extension/plugin-ecosystem/tools/env-info.js +1 -0
  173. package/dist/harness/extension/plugin-ecosystem/tools/eol.d.ts +35 -0
  174. package/dist/harness/extension/plugin-ecosystem/tools/eol.js +43 -0
  175. package/dist/harness/extension/plugin-ecosystem/tools/file-edit.js +40 -9
  176. package/dist/harness/extension/plugin-ecosystem/tools/file-ops.d.ts +33 -0
  177. package/dist/harness/extension/plugin-ecosystem/tools/file-ops.js +376 -0
  178. package/dist/harness/extension/plugin-ecosystem/tools/file-search.d.ts +12 -2
  179. package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +241 -70
  180. package/dist/harness/extension/plugin-ecosystem/tools/git-runner.d.ts +31 -0
  181. package/dist/harness/extension/plugin-ecosystem/tools/git-runner.js +104 -0
  182. package/dist/harness/extension/plugin-ecosystem/tools/git-status-snapshot.d.ts +111 -0
  183. package/dist/harness/extension/plugin-ecosystem/tools/git-status-snapshot.js +197 -0
  184. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.d.ts +27 -0
  185. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +463 -0
  186. package/dist/harness/extension/plugin-ecosystem/tools/http.d.ts +10 -6
  187. package/dist/harness/extension/plugin-ecosystem/tools/http.js +41 -47
  188. package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +6 -0
  189. package/dist/harness/extension/plugin-ecosystem/tools/index.js +4 -0
  190. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.js +4 -0
  191. package/dist/harness/extension/plugin-ecosystem/tools/memory.js +25 -1
  192. package/dist/harness/extension/plugin-ecosystem/tools/package-tools.d.ts +13 -0
  193. package/dist/harness/extension/plugin-ecosystem/tools/package-tools.js +391 -0
  194. package/dist/harness/extension/plugin-ecosystem/tools/platform.d.ts +51 -2
  195. package/dist/harness/extension/plugin-ecosystem/tools/platform.js +151 -12
  196. package/dist/harness/extension/plugin-ecosystem/tools/session-history.js +2 -0
  197. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.d.ts +10 -1
  198. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +35 -19
  199. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.d.ts +8 -0
  200. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.js +5 -0
  201. package/dist/harness/extension/plugin-ecosystem/tools/web-search.js +1 -0
  202. package/dist/harness/governance/credentials/index.d.ts +1 -1
  203. package/dist/harness/governance/credentials/store.d.ts +16 -4
  204. package/dist/harness/governance/credentials/store.js +33 -6
  205. package/dist/harness/governance/credentials/types.d.ts +11 -0
  206. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +105 -0
  207. package/dist/harness/governance/human-in-the-loop/decision-cache.js +184 -0
  208. package/dist/harness/governance/human-in-the-loop/index.d.ts +5 -5
  209. package/dist/harness/governance/human-in-the-loop/index.js +3 -3
  210. package/dist/harness/governance/human-in-the-loop/types.d.ts +7 -62
  211. package/dist/harness/governance/human-in-the-loop/types.js +6 -2
  212. package/dist/harness/governance/security/capability-enforcer.d.ts +9 -1
  213. package/dist/harness/governance/security/capability-enforcer.js +31 -8
  214. package/dist/harness/governance/security/degradation.js +5 -7
  215. package/dist/harness/governance/security/risk-evaluator.d.ts +1 -1
  216. package/dist/harness/governance/security/risk-evaluator.js +4 -82
  217. package/dist/harness/governance/security/temp-path.d.ts +41 -0
  218. package/dist/harness/governance/security/temp-path.js +117 -0
  219. package/dist/harness/governance/session-acl/index.d.ts +1 -0
  220. package/dist/harness/governance/session-acl/index.js +1 -0
  221. package/dist/harness/governance/session-acl/rights.d.ts +12 -0
  222. package/dist/harness/governance/session-acl/rights.js +89 -7
  223. package/dist/harness/governance/session-acl/seed-roles.js +9 -1
  224. package/dist/harness/governance/session-acl/service.js +21 -29
  225. package/dist/harness/governance/session-acl/tool-rights.d.ts +81 -0
  226. package/dist/harness/governance/session-acl/tool-rights.js +238 -0
  227. package/dist/harness/governance/session-acl/types.d.ts +22 -0
  228. package/dist/harness/index.d.ts +16 -12
  229. package/dist/harness/index.js +10 -6
  230. package/dist/harness/knowledge/file-identity.d.ts +8 -0
  231. package/dist/harness/knowledge/file-identity.js +26 -1
  232. package/dist/harness/knowledge/file-index-store.js +11 -11
  233. package/dist/harness/knowledge/grounding.d.ts +2 -1
  234. package/dist/harness/knowledge/grounding.js +8 -5
  235. package/dist/harness/knowledge/index-store.d.ts +31 -4
  236. package/dist/harness/knowledge/index-store.js +121 -39
  237. package/dist/harness/knowledge/index.d.ts +2 -2
  238. package/dist/harness/knowledge/index.js +1 -1
  239. package/dist/harness/knowledge/ingest.d.ts +115 -115
  240. package/dist/harness/knowledge/ingest.js +154 -151
  241. package/dist/harness/knowledge/job-control-state.js +4 -4
  242. package/dist/harness/knowledge/job-control.js +11 -11
  243. package/dist/harness/knowledge/knowledge-serve-child.js +1 -1
  244. package/dist/harness/knowledge/membership-store.js +11 -11
  245. package/dist/harness/knowledge/network-guard.d.ts +61 -4
  246. package/dist/harness/knowledge/network-guard.js +390 -113
  247. package/dist/harness/knowledge/purge.js +4 -1
  248. package/dist/harness/knowledge/query-service.js +3 -3
  249. package/dist/harness/knowledge/writer-service.d.ts +2 -0
  250. package/dist/harness/knowledge/writer-service.js +14 -13
  251. package/dist/harness/memory/backfill-coverage.js +3 -1
  252. package/dist/harness/memory/backfill-trigger.d.ts +2 -2
  253. package/dist/harness/memory/backfill-trigger.js +4 -4
  254. package/dist/harness/memory/index.d.ts +1 -0
  255. package/dist/harness/memory/index.js +1 -0
  256. package/dist/harness/memory/sqlite/agent-db.js +2 -0
  257. package/dist/harness/memory/sqlite/memory-store.d.ts +1 -0
  258. package/dist/harness/memory/sqlite/memory-store.js +14 -4
  259. package/dist/harness/memory/sqlite/wisdom-store.js +9 -9
  260. package/dist/harness/memory/store.d.ts +1 -0
  261. package/dist/harness/memory/store.js +3 -0
  262. package/dist/harness/memory/time-format.d.ts +28 -0
  263. package/dist/harness/memory/time-format.js +52 -0
  264. package/dist/harness/memory/types.d.ts +12 -0
  265. package/dist/harness/observability/observer/hub.js +53 -2
  266. package/dist/harness/observability/observer/index.d.ts +2 -2
  267. package/dist/harness/observability/observer/index.js +1 -1
  268. package/dist/harness/observability/observer/types.d.ts +80 -0
  269. package/dist/harness/observability/observer/types.js +118 -9
  270. package/dist/harness/run/agent/agent.d.ts +18 -0
  271. package/dist/harness/run/agent/agent.js +26 -0
  272. package/dist/harness/run/concurrency/tool-loop-detection-core.d.ts +1 -1
  273. package/dist/harness/run/concurrency/tool-loop-detection-core.js +1 -1
  274. package/dist/harness/run/reliability/harness-events.d.ts +4 -0
  275. package/dist/harness/run/reliability/run-agent.js +110 -18
  276. package/dist/harness/run/reliability/run-metrics-collector.d.ts +28 -2
  277. package/dist/harness/run/reliability/run-metrics-collector.js +92 -2
  278. package/dist/harness/run/run-guard/default-run-guard.d.ts +0 -5
  279. package/dist/harness/run/run-guard/default-run-guard.js +104 -44
  280. package/dist/harness/run/run-scope.d.ts +52 -0
  281. package/dist/harness/run/runner.d.ts +117 -16
  282. package/dist/harness/run/runner.js +668 -157
  283. package/dist/harness/session/attachments/llm-intent.js +17 -17
  284. package/dist/harness/session/history/port.js +16 -5
  285. package/dist/harness/session/in-memory-store.d.ts +6 -0
  286. package/dist/harness/session/in-memory-store.js +55 -3
  287. package/dist/harness/session/schedules/index.d.ts +10 -0
  288. package/dist/harness/session/schedules/index.js +10 -0
  289. package/dist/harness/session/schedules/render.d.ts +13 -0
  290. package/dist/harness/session/schedules/render.js +63 -0
  291. package/dist/harness/session/schedules/service.d.ts +179 -0
  292. package/dist/harness/session/schedules/service.js +695 -0
  293. package/dist/harness/session/schedules/store.d.ts +119 -0
  294. package/dist/harness/session/schedules/store.js +323 -0
  295. package/dist/harness/session/schedules/tools.d.ts +39 -0
  296. package/dist/harness/session/schedules/tools.js +442 -0
  297. package/dist/harness/session/schedules/types.d.ts +104 -0
  298. package/dist/harness/session/schedules/types.js +97 -0
  299. package/dist/harness/session/tasks/tools.js +22 -0
  300. package/dist/harness/session/title.js +25 -9
  301. package/dist/harness/session/types.d.ts +35 -0
  302. package/dist/harness/shared/events/agent-event-map.d.ts +39 -0
  303. package/dist/harness/shared/events/agent-event-map.js +2 -0
  304. package/dist/harness/shared/types/agent-definition.d.ts +23 -0
  305. package/dist/index.d.ts +25 -9
  306. package/dist/index.js +11 -2
  307. package/dist/integration/observability/run-telemetry.d.ts +8 -0
  308. package/dist/integration/observability/run-telemetry.js +31 -8
  309. package/dist/integration/observability/trace-collector.js +26 -4
  310. package/dist/integration/observability/trace-events.d.ts +1 -0
  311. package/dist/integration/observability/trace-events.js +2 -0
  312. package/dist/integration/observability/trace-logger.js +27 -17
  313. package/dist/integration/providers/anthropic.d.ts +10 -0
  314. package/dist/integration/providers/anthropic.js +44 -1
  315. package/dist/integration/providers/openai.d.ts +10 -0
  316. package/dist/integration/providers/openai.js +58 -2
  317. package/dist/integration/providers/wire-dump-diff.d.ts +191 -0
  318. package/dist/integration/providers/wire-dump-diff.js +351 -0
  319. package/dist/integration/providers/wire-dump.d.ts +178 -0
  320. package/dist/integration/providers/wire-dump.js +396 -0
  321. package/dist/integration/storage/jsonl.d.ts +29 -0
  322. package/dist/integration/storage/jsonl.js +243 -41
  323. package/dist/integration/storage/session-index.js +63 -8
  324. package/dist/paths.d.ts +19 -0
  325. package/dist/paths.js +38 -1
  326. package/dist/subsystems/cognition-steward/conceptualize/SUBSYSTEM.md +43 -43
  327. package/dist/subsystems/cognition-steward/conceptualize/config.yaml +50 -50
  328. package/dist/subsystems/cognition-steward/consolidate/SUBSYSTEM.md +6 -6
  329. package/dist/subsystems/cognition-steward/consolidate/config.yaml +54 -54
  330. package/dist/subsystems/memory-steward/backfill/handler.js +9 -0
  331. package/dist/subsystems/safety-guard/config.yaml +3 -1
  332. package/dist/subsystems/wisdom-steward/evaluate/config.yaml +50 -50
  333. package/dist/subsystems/wisdom-steward/formation/SUBSYSTEM.md +42 -42
  334. package/dist/subsystems/wisdom-steward/formation/config.yaml +54 -54
  335. package/dist/subsystems/wisdom-steward/govern/config.yaml +55 -55
  336. package/package.json +115 -115
  337. package/dist/harness/collaboration/multi-agent/agent-registry-types.d.ts +0 -144
  338. package/dist/harness/collaboration/multi-agent/agent-registry-types.js +0 -25
  339. package/dist/harness/collaboration/multi-agent/index.d.ts +0 -17
  340. package/dist/harness/collaboration/multi-agent/index.js +0 -15
  341. package/dist/harness/collaboration/multi-agent/process.d.ts +0 -167
  342. package/dist/harness/collaboration/multi-agent/process.js +0 -256
  343. package/dist/harness/collaboration/multi-agent/registry.d.ts +0 -36
  344. package/dist/harness/collaboration/multi-agent/registry.js +0 -137
  345. package/dist/harness/collaboration/multi-agent/swarm.d.ts +0 -135
  346. package/dist/harness/collaboration/multi-agent/swarm.js +0 -317
  347. package/dist/harness/collaboration/multi-agent/types.d.ts +0 -66
  348. package/dist/harness/collaboration/multi-agent/types.js +0 -15
  349. package/dist/harness/collaboration/orchestration/async-task-store.d.ts +0 -107
  350. package/dist/harness/collaboration/orchestration/async-task-store.js +0 -12
  351. package/dist/harness/collaboration/orchestration/async-task.d.ts +0 -156
  352. package/dist/harness/collaboration/orchestration/async-task.js +0 -359
  353. package/dist/harness/collaboration/orchestration/planner/hybrid-planner.d.ts +0 -47
  354. package/dist/harness/collaboration/orchestration/planner/hybrid-planner.js +0 -61
  355. package/dist/harness/collaboration/orchestration/planner/index.d.ts +0 -9
  356. package/dist/harness/collaboration/orchestration/planner/index.js +0 -6
  357. package/dist/harness/collaboration/orchestration/planner/llm-planner.d.ts +0 -54
  358. package/dist/harness/collaboration/orchestration/planner/llm-planner.js +0 -167
  359. package/dist/harness/collaboration/orchestration/planner/rule-planner.d.ts +0 -85
  360. package/dist/harness/collaboration/orchestration/planner/rule-planner.js +0 -175
  361. package/dist/harness/collaboration/orchestration/quality/classifier.d.ts +0 -21
  362. package/dist/harness/collaboration/orchestration/quality/classifier.js +0 -235
  363. package/dist/harness/collaboration/orchestration/quality/gate.d.ts +0 -29
  364. package/dist/harness/collaboration/orchestration/quality/gate.js +0 -409
  365. package/dist/harness/collaboration/orchestration/quality/index.d.ts +0 -9
  366. package/dist/harness/collaboration/orchestration/quality/index.js +0 -8
  367. package/dist/harness/collaboration/orchestration/quality/types.d.ts +0 -159
  368. package/dist/harness/collaboration/orchestration/quality/types.js +0 -33
  369. package/dist/harness/collaboration/orchestration/scheduler/index.d.ts +0 -5
  370. package/dist/harness/collaboration/orchestration/scheduler/index.js +0 -4
  371. package/dist/harness/collaboration/orchestration/scheduler/task-scheduler.d.ts +0 -143
  372. package/dist/harness/collaboration/orchestration/scheduler/task-scheduler.js +0 -297
  373. package/dist/harness/collaboration/orchestration/strategy/classifier.d.ts +0 -12
  374. package/dist/harness/collaboration/orchestration/strategy/classifier.js +0 -81
  375. package/dist/harness/collaboration/orchestration/strategy/index.d.ts +0 -3
  376. package/dist/harness/collaboration/orchestration/strategy/index.js +0 -2
  377. package/dist/harness/collaboration/orchestration/strategy/router.d.ts +0 -28
  378. package/dist/harness/collaboration/orchestration/strategy/router.js +0 -105
  379. package/dist/harness/collaboration/orchestration/strategy/types.d.ts +0 -49
  380. package/dist/harness/collaboration/orchestration/strategy/types.js +0 -4
  381. package/dist/harness/collaboration/orchestration/workflow/engine.d.ts +0 -86
  382. package/dist/harness/collaboration/orchestration/workflow/engine.js +0 -298
  383. package/dist/harness/collaboration/orchestration/workflow/index.d.ts +0 -9
  384. package/dist/harness/collaboration/orchestration/workflow/index.js +0 -7
  385. package/dist/harness/collaboration/orchestration/workflow/types.d.ts +0 -143
  386. package/dist/harness/collaboration/orchestration/workflow/types.js +0 -7
  387. package/dist/harness/governance/human-in-the-loop/approval-manager.d.ts +0 -32
  388. package/dist/harness/governance/human-in-the-loop/approval-manager.js +0 -93
  389. /package/dist/harness/collaboration/{multi-agent → delegation}/message-channel-types.d.ts +0 -0
  390. /package/dist/harness/collaboration/{multi-agent → delegation}/message-channel-types.js +0 -0
@@ -1,87 +1,557 @@
1
1
  /**
2
- * ProcessSandbox — 进程级沙箱
2
+ * Process sandbox — supervised spawn (L1) + optional OS jails (L4 process).
3
3
  *
4
- * 通过 spawn 执行命令,施加资源限制。
5
- * 隔离级别:process(不依赖 Docker)。
4
+ * Never claims isolation it does not enforce. `SupervisedSpawn` is process-tree
5
+ * kill + env scrub + limits only; real jails are `linux-bwrap` / `mac-seatbelt`.
6
+ * Public contract: `docs/process-isolation.md`.
6
7
  */
7
8
  import { spawn } from 'node:child_process';
9
+ import { realpath, unlink, writeFile } from 'node:fs/promises';
10
+ import { homedir, tmpdir } from 'node:os';
11
+ import { join, resolve } from 'node:path';
12
+ import { StringDecoder } from 'node:string_decoder';
13
+ import { assessL4ProcessMinimum, killProcessTree, probeProcessIsolation, scrubEnv, supervisedSpawnProfile, } from './process-isolation.js';
14
+ /**
15
+ * Supervised process runner: tree-killable spawn with scrubbed env.
16
+ * This is NOT a filesystem jail — `isolation.filesystem` stays `cwd-pin`.
17
+ */
8
18
  export class ProcessSandbox {
9
19
  level = 'process';
20
+ cachedProfile;
21
+ forceEnvKeys;
22
+ constructor(options) {
23
+ this.cachedProfile = options?.profile ?? null;
24
+ this.forceEnvKeys = options?.forceEnvKeys;
25
+ }
26
+ async probe() {
27
+ if (this.cachedProfile)
28
+ return this.cachedProfile;
29
+ this.cachedProfile = await probeProcessIsolation();
30
+ return this.cachedProfile;
31
+ }
32
+ async isAvailable() {
33
+ return true;
34
+ }
35
+ /**
36
+ * Execute a shell command line via the platform shell.
37
+ *
38
+ * @param command - shell command line
39
+ * @param config - cwd / env / limits
40
+ * @returns result with honest isolation profile
41
+ */
10
42
  async execute(command, config) {
43
+ const profile = await this.probe();
44
+ const shell = resolveShell();
45
+ return this.run(shell.executable, [...shell.args, command], config, profile);
46
+ }
47
+ /**
48
+ * Execute an argv vector (preferred).
49
+ *
50
+ * @param argv - executable + args
51
+ * @param config - cwd / env / limits
52
+ * @returns result with honest isolation profile
53
+ */
54
+ async executeArgv(argv, config) {
55
+ const profile = await this.probe();
56
+ if (argv.length === 0) {
57
+ throw new Error('sandbox_argv_empty: executeArgv requires at least one token');
58
+ }
59
+ return this.run(argv[0], argv.slice(1), config, profile);
60
+ }
61
+ run(file, args, config, profile) {
11
62
  const cwd = config?.cwd ?? process.cwd();
12
- const env = { ...process.env, ...config?.env };
13
- const timeoutMs = config?.limits?.timeoutMs ?? 30_000;
14
- const maxOutputBytes = config?.limits?.maxOutputBytes ?? 10 * 1024 * 1024; // 10MB
15
- return new Promise((resolve) => {
63
+ const env = scrubEnv(config?.env, { forceKeys: this.forceEnvKeys });
64
+ const timeoutMs = config?.limits?.timeoutMs ?? 60_000;
65
+ const maxOutputBytes = config?.limits?.maxOutputBytes ?? 10 * 1024 * 1024;
66
+ // Jail backends wrap the spawn; fall back to supervised spawn.
67
+ if (profile.backend === 'linux-bwrap' && process.platform === 'linux') {
68
+ return this.runBwrap(file, args, config, profile, { cwd, env, timeoutMs, maxOutputBytes });
69
+ }
70
+ if (profile.backend === 'mac-seatbelt' && process.platform === 'darwin') {
71
+ return this.runSeatbelt(file, args, config, profile, { cwd, env, timeoutMs, maxOutputBytes });
72
+ }
73
+ if (config?.requireJail) {
74
+ return Promise.reject(new Error(`untrusted_jail_failed: no process jail backend (probe=${profile.backend}); refuse unsandboxed execute`));
75
+ }
76
+ return this.runSupervised(file, args, config, profile, { cwd, env, timeoutMs, maxOutputBytes });
77
+ }
78
+ runSupervised(file, args, config, profile, opts) {
79
+ return new Promise((resolve, reject) => {
16
80
  const start = Date.now();
17
81
  let stdout = '';
18
82
  let stderr = '';
83
+ // 输出上限按原始字节计(stdout/stderr 各自独立计):字符数远小于字节数,
84
+ // 旧口径会让上限推迟触发、放走 ~3x 字节。计数含被丢弃块,故已捕获文本恒 ≤
85
+ // 上限;usage().outputBytes 只计已捕获字节(`captured*`,见下方 usage 调用)。
86
+ let stdoutBytes = 0;
87
+ let stderrBytes = 0;
88
+ // 已捕获原始字节:usage 的唯一口径。不能用 byteLength(文本) 代替——被切断的
89
+ // 多字节字符解码后是 3 字节的 U+FFFD,按文本重算会虚高(也说明必须用
90
+ // StringDecoder 跨块解码,逐块 toString 会让 stdout/stderr 文本本身被污染)。
91
+ let stdoutCaptured = 0;
92
+ let stderrCaptured = 0;
93
+ const stdoutDecoder = new StringDecoder('utf8');
94
+ const stderrDecoder = new StringDecoder('utf8');
95
+ let decodersFlushed = false;
96
+ /** 冲刷解码器尾部:未收尾的多字节字符在此输出(截断流输出 U+FFFD 是正确结果)。 */
97
+ const flushDecoders = () => {
98
+ if (decodersFlushed)
99
+ return;
100
+ decodersFlushed = true;
101
+ stdout += stdoutDecoder.end();
102
+ stderr += stderrDecoder.end();
103
+ };
19
104
  let terminated = false;
20
105
  let terminateReason = '';
21
- const proc = spawn('sh', ['-c', command], {
22
- cwd,
23
- env,
106
+ let settled = false;
107
+ const spawnOpts = {
108
+ cwd: opts.cwd,
109
+ env: opts.env,
24
110
  stdio: ['pipe', 'pipe', 'pipe'],
25
- });
26
- // 收集输出
27
- proc.stdout.on('data', (data) => {
28
- if (stdout.length + data.length > maxOutputBytes) {
29
- terminated = true;
30
- terminateReason = 'Output size limit exceeded';
31
- proc.kill('SIGKILL');
111
+ windowsHide: true,
112
+ // POSIX: own process group so we can kill the tree
113
+ ...(process.platform === 'win32' ? {} : { detached: true }),
114
+ };
115
+ const proc = spawn(file, args, spawnOpts);
116
+ const finish = (result) => {
117
+ if (settled)
118
+ return;
119
+ settled = true;
120
+ clearTimeout(timer);
121
+ config?.signal?.removeEventListener('abort', onAbort);
122
+ resolve(result);
123
+ };
124
+ /** Refusal path (requireJail contract: throw, never resolve-as-success). */
125
+ const fail = (err) => {
126
+ if (settled)
127
+ return;
128
+ settled = true;
129
+ clearTimeout(timer);
130
+ config?.signal?.removeEventListener('abort', onAbort);
131
+ reject(err);
132
+ };
133
+ const kill = (reason) => {
134
+ terminated = true;
135
+ terminateReason = reason;
136
+ killProcessTree(proc);
137
+ };
138
+ const onAbort = () => kill('Aborted');
139
+ config?.signal?.addEventListener('abort', onAbort, { once: true });
140
+ proc.stdout?.on('data', (data) => {
141
+ stdoutBytes += data.length;
142
+ if (stdoutBytes > opts.maxOutputBytes) {
143
+ kill('Output size limit exceeded');
32
144
  return;
33
145
  }
34
- stdout += data.toString();
146
+ stdoutCaptured += data.length;
147
+ stdout += stdoutDecoder.write(data);
35
148
  });
36
- proc.stderr.on('data', (data) => {
37
- if (stderr.length + data.length > maxOutputBytes) {
149
+ proc.stderr?.on('data', (data) => {
150
+ stderrBytes += data.length;
151
+ if (stderrBytes > opts.maxOutputBytes) {
152
+ kill('Output size limit exceeded');
38
153
  return;
39
154
  }
40
- stderr += data.toString();
155
+ stderrCaptured += data.length;
156
+ stderr += stderrDecoder.write(data);
41
157
  });
42
- // 超时保护
43
158
  const timer = setTimeout(() => {
44
- terminated = true;
45
- terminateReason = `Execution timeout (${timeoutMs}ms)`;
46
- proc.kill('SIGKILL');
47
- }, timeoutMs);
48
- proc.on('close', (exitCode) => {
49
- clearTimeout(timer);
50
- const elapsedMs = Date.now() - start;
51
- const usage = {
52
- elapsedMs,
53
- peakMemoryBytes: -1, // 需要平台特定实现
54
- cpuTimeMs: -1,
55
- outputBytes: stdout.length + stderr.length,
56
- };
57
- resolve({
58
- exitCode: exitCode ?? -1,
159
+ kill(`Execution timeout (${opts.timeoutMs}ms)`);
160
+ }, opts.timeoutMs);
161
+ proc.on('close', (exitCode, signal) => {
162
+ flushDecoders();
163
+ const usage = this.usage(start, stdoutCaptured, stderrCaptured);
164
+ // null exitCode = signal death; never report that as success (exit 0)
165
+ const code = typeof exitCode === 'number' ? exitCode : -1;
166
+ finish({
167
+ exitCode: code,
59
168
  stdout,
60
- stderr,
61
- terminated,
62
- terminateReason: terminated ? terminateReason : undefined,
169
+ stderr: signal && !terminated ? `${stderr}\n[signal ${signal}]`.trim() : stderr,
170
+ terminated: terminated || signal != null,
171
+ terminateReason: terminated
172
+ ? terminateReason
173
+ : signal
174
+ ? `signal ${signal}`
175
+ : undefined,
63
176
  usage,
177
+ isolation: profile,
64
178
  });
65
179
  });
66
180
  proc.on('error', (err) => {
67
- clearTimeout(timer);
68
- resolve({
181
+ flushDecoders();
182
+ const usage = this.usage(start, stdoutCaptured, stderrCaptured);
183
+ const isJailWrapper = profile.backend === 'linux-bwrap' || profile.backend === 'mac-seatbelt';
184
+ if (config?.requireJail && isJailWrapper) {
185
+ fail(new Error(`untrusted_jail_failed: jail spawn failed: ${err.message} (requireJail=true; refuse unsandboxed execute)`));
186
+ return;
187
+ }
188
+ const honest = isJailWrapper
189
+ ? {
190
+ ...profile,
191
+ filesystem: 'cwd-pin',
192
+ privilege: 'same',
193
+ notes: [...(profile.notes ?? []), `jail spawn failed: ${err.message}`],
194
+ }
195
+ : profile;
196
+ if (isJailWrapper)
197
+ config?.noteSecurityDegraded?.(`jail_spawn_failed: ${err.message}`);
198
+ finish({
69
199
  exitCode: -1,
70
- stdout: '',
200
+ stdout,
71
201
  stderr: err.message,
72
202
  terminated: true,
73
203
  terminateReason: `Process error: ${err.message}`,
74
- usage: {
75
- elapsedMs: Date.now() - start,
76
- peakMemoryBytes: -1,
77
- cpuTimeMs: -1,
78
- outputBytes: 0,
79
- },
204
+ usage,
205
+ isolation: honest,
80
206
  });
81
207
  });
82
208
  });
83
209
  }
84
- async isAvailable() {
85
- return true; // 进程级沙箱始终可用
210
+ async runBwrap(file, args, config, profile, opts) {
211
+ // D4-c: bind every allowRoot; default network deny (--unshare-all).
212
+ const roots = await resolveJailRoots(opts.cwd, config);
213
+ const network = resolveNetworkPolicy(config);
214
+ const bwrapArgs = [
215
+ '--die-with-parent',
216
+ '--unshare-all',
217
+ '--ro-bind',
218
+ '/usr',
219
+ '/usr',
220
+ '--ro-bind',
221
+ '/bin',
222
+ '/bin',
223
+ '--ro-bind',
224
+ '/lib',
225
+ '/lib',
226
+ '--ro-bind-try',
227
+ '/lib64',
228
+ '/lib64',
229
+ '--ro-bind-try',
230
+ '/etc',
231
+ '/etc',
232
+ ];
233
+ if (network === 'open') {
234
+ bwrapArgs.push('--share-net');
235
+ }
236
+ for (const root of roots) {
237
+ // --bind-try: stale pathRoots must not abort the whole command
238
+ bwrapArgs.push('--bind-try', root, root);
239
+ }
240
+ bwrapArgs.push('--chdir', opts.cwd, '--', file, ...args);
241
+ const applied = {
242
+ ...profile,
243
+ network,
244
+ privilege: 'dropped',
245
+ notes: [
246
+ ...(profile.notes ?? []),
247
+ `bwrap roots=${roots.join(',')}`,
248
+ networkPolicyNote(config, network),
249
+ 'privilege=dropped (userns)',
250
+ ],
251
+ };
252
+ const result = await this.runSupervised('bwrap', bwrapArgs, config, applied, opts);
253
+ // D7 runtime case (post-execution): the wrapper failed to establish the
254
+ // jail even though the probe passed. Never re-execute the user command.
255
+ if (isJailWrapperSetupFailure(result, 'bwrap')) {
256
+ return this.jailWrapperRuntimeFailure(result, config, profile, `bwrap setup failed (exit=${result.exitCode}): ${result.stderr.slice(0, 200)}`);
257
+ }
258
+ return result;
259
+ }
260
+ async runSeatbelt(file, args, config, profile, opts) {
261
+ const roots = await resolveJailRoots(opts.cwd, config);
262
+ const network = resolveNetworkPolicy(config);
263
+ // Host override wins; otherwise generate a profile covering allowRoots (D3-b+).
264
+ let profilePath = process.env.OCTOPI_SB_PROFILE;
265
+ let generatedPath;
266
+ if (!profilePath) {
267
+ generatedPath = join(tmpdir(), `octopi-sb-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.sb`);
268
+ try {
269
+ await writeFile(generatedPath, buildSeatbeltProfile(roots, network), { encoding: 'utf8', mode: 0o600 });
270
+ profilePath = generatedPath;
271
+ }
272
+ catch (err) {
273
+ return this.jailSetupFailed(file, args, config, profile, opts, `seatbelt profile generation failed: ${err instanceof Error ? err.message : String(err)}`);
274
+ }
275
+ }
276
+ const applied = {
277
+ ...profile,
278
+ filesystem: 'write-jailed',
279
+ privilege: 'dropped',
280
+ network,
281
+ notes: [
282
+ ...(profile.notes ?? []),
283
+ `seatbelt profile=${profilePath}`,
284
+ `roots=${roots.join(',')}`,
285
+ networkPolicyNote(config, network),
286
+ 'privilege=dropped (ops-denied; uid unchanged)',
287
+ 'tmp writes not journaled (notReversed)',
288
+ ],
289
+ };
290
+ try {
291
+ const result = await this.runSupervised('sandbox-exec', ['-f', profilePath, '--', file, ...args], config, applied, opts);
292
+ // D7 runtime case (post-execution): the wrapper failed to apply the
293
+ // jail even though the probe passed. Never re-execute the user command.
294
+ if (isJailWrapperSetupFailure(result, 'sandbox-exec')) {
295
+ return await this.jailWrapperRuntimeFailure(result, config, profile, `seatbelt apply failed (exit=${result.exitCode}): ${result.stderr.slice(0, 200)}`);
296
+ }
297
+ return result;
298
+ }
299
+ finally {
300
+ if (generatedPath) {
301
+ await unlink(generatedPath).catch(() => undefined);
302
+ }
303
+ }
304
+ }
305
+ /**
306
+ * D7: jail was selected but cannot be applied.
307
+ * requireJail (untrusted) throws; otherwise supervised fallback of the real command + run-level note.
308
+ */
309
+ jailSetupFailed(file, args, config, profile, opts, reason) {
310
+ if (config?.requireJail) {
311
+ return Promise.reject(new Error(`untrusted_jail_failed: ${reason} (requireJail=true; refuse unsandboxed execute)`));
312
+ }
313
+ const degraded = {
314
+ ...profile,
315
+ backend: 'supervised-spawn',
316
+ processTree: 'killable',
317
+ filesystem: 'cwd-pin',
318
+ privilege: 'same',
319
+ network: 'open',
320
+ notes: [...(profile.notes ?? []), `jail_setup_failed: ${reason}; supervised fallback`],
321
+ };
322
+ config?.noteSecurityDegraded?.(`jail_setup_failed: ${reason}`);
323
+ return this.runSupervised(file, args, config, degraded, opts);
324
+ }
325
+ /**
326
+ * D7 runtime case (after the wrapper has run): a jail setup failure is
327
+ * suspected. The user command is **never re-executed** — a forged wrapper
328
+ * error must not buy a second, unsandboxed run. `requireJail` refuses;
329
+ * other modes report the wrapper outcome with downgraded isolation and the
330
+ * run-level `securityDegraded` note (under-claiming is the safe direction).
331
+ *
332
+ * @param result - the wrapper's own outcome (command not re-run)
333
+ * @param config - execute config (requireJail / degradation hook)
334
+ * @param profile - probed isolation profile
335
+ * @param reason - wrapper failure summary for notes
336
+ * @returns the wrapper outcome with honestly downgraded isolation
337
+ */
338
+ jailWrapperRuntimeFailure(result, config, profile, reason) {
339
+ if (config?.requireJail) {
340
+ return Promise.reject(new Error(`untrusted_jail_failed: ${reason} (requireJail=true; refuse unsandboxed execute)`));
341
+ }
342
+ config?.noteSecurityDegraded?.(`jail_setup_failed: ${reason}`);
343
+ return Promise.resolve({
344
+ ...result,
345
+ isolation: {
346
+ ...profile,
347
+ backend: 'supervised-spawn',
348
+ processTree: 'killable',
349
+ filesystem: 'cwd-pin',
350
+ privilege: 'same',
351
+ network: 'open',
352
+ notes: [
353
+ ...(profile.notes ?? []),
354
+ `jail_setup_failed: ${reason}; command not re-executed`,
355
+ ],
356
+ },
357
+ });
358
+ }
359
+ usage(start, stdoutCaptured, stderrCaptured) {
360
+ return {
361
+ elapsedMs: Date.now() - start,
362
+ peakMemoryBytes: -1,
363
+ cpuTimeMs: -1,
364
+ outputBytes: stdoutCaptured + stderrCaptured,
365
+ };
366
+ }
367
+ }
368
+ /** Network posture for this run (D4-c: default deny; allowlist enforced as deny). */
369
+ function resolveNetworkPolicy(config) {
370
+ const policy = config?.networkPolicy ?? 'deny';
371
+ return policy === 'open' ? 'open' : 'deny';
372
+ }
373
+ /**
374
+ * Heuristic: the jail wrapper failed to establish the jail — the user command
375
+ * never ran. Detection only feeds refusal (`requireJail`) or an honest
376
+ * isolation downgrade; the user command is **never re-executed** on it, so a
377
+ * forged stderr cannot buy an unsandboxed run. Wrapper diagnostics carry the
378
+ * argv0 prefix at **line start** (bwrap's uid-map helpers report as
379
+ * `newuidmap:` / `newgidmap:`); bare substrings are not matched, and neither
380
+ * is "operation not permitted": a sandbox write denial of a real user command
381
+ * emits exactly that wording. A terminated run (timeout/abort) is never a
382
+ * setup failure.
383
+ *
384
+ * @param result - wrapper run result
385
+ * @param wrapper - which jail wrapper produced the result
386
+ * @returns true when the jail itself failed to apply
387
+ */
388
+ export function isJailWrapperSetupFailure(result, wrapper) {
389
+ if (result.terminated)
390
+ return false;
391
+ if (result.exitCode === 0)
392
+ return false;
393
+ if (result.stdout.length > 0)
394
+ return false;
395
+ const prefixes = wrapper === 'bwrap' ? ['bwrap:', 'newuidmap:', 'newgidmap:'] : ['sandbox-exec:'];
396
+ return result.stderr.split('\n').some((line) => prefixes.some((p) => line.startsWith(p)));
397
+ }
398
+ /** Extra note when caller asked for allowlist (interface-only). */
399
+ function networkPolicyNote(config, applied) {
400
+ const requested = config?.networkPolicy;
401
+ if (requested === 'allowlist') {
402
+ return `network=${applied} (allowlist requested; interface-only, enforced as deny)`;
403
+ }
404
+ return `network=${applied}`;
405
+ }
406
+ /**
407
+ * Jail write mounts (2a/2b): allowRoots ∪ cwd ∪ tmpdir ∪ shared tmp on POSIX
408
+ * (`/tmp`, `/var/tmp` — always) ∪ home when `config.homeWrite` (project/host).
409
+ * tmp is not journaled (2c).
410
+ *
411
+ * Each root is emitted in its lexical form **and**, when resolvable, its
412
+ * canonical (`realpath`) form: jail backends match canonical paths, so a root
413
+ * given through a symlink alias (macOS `/var` → `/private/var`, `/tmp` →
414
+ * `/private/tmp`) must appear canonicalized or its subpath rule never matches.
415
+ * Roots that fail to resolve keep the lexical form only (stale allowRoots must
416
+ * not abort the command; bwrap uses `--bind-try`).
417
+ *
418
+ * @param cwd - working directory (always a root; also the relative base for root paths)
419
+ * @param config - sandbox config (allowRoots / homeWrite)
420
+ * @returns absolute, deduped root paths (lexical + canonical variants)
421
+ */
422
+ export async function resolveJailRoots(cwd, config) {
423
+ const raw = [cwd, ...(config?.allowRoots ?? []), tmpdir()];
424
+ if (process.platform !== 'win32') {
425
+ // Tools that hardcode /tmp or /var/tmp (ignoring TMPDIR) must keep working
426
+ // inside the jail; the canonical twins (/private/tmp, /private/var/tmp) are
427
+ // emitted by the lexical+realpath loop below. Shared tmp writes stay
428
+ // notReversed (2c) like tmpdir().
429
+ raw.push('/tmp', '/var/tmp');
430
+ }
431
+ if (config?.homeWrite) {
432
+ raw.push(homedir());
433
+ }
434
+ const out = [];
435
+ const seen = new Set();
436
+ const push = (candidate) => {
437
+ // Relative roots resolve against the run cwd, not the host process cwd.
438
+ const s = resolve(cwd, candidate);
439
+ if (!s || s === '.')
440
+ return;
441
+ const key = process.platform === 'win32' ? s.toLowerCase() : s;
442
+ if (seen.has(key))
443
+ return;
444
+ seen.add(key);
445
+ out.push(s);
446
+ };
447
+ for (const p of raw) {
448
+ if (!p || p.trim() === '')
449
+ continue;
450
+ push(p);
451
+ const canonical = await realpathSafe(resolve(cwd, p));
452
+ if (canonical)
453
+ push(canonical);
454
+ }
455
+ return out.length > 0 ? out : [resolve(cwd), resolve(tmpdir())];
456
+ }
457
+ /**
458
+ * Canonicalize a path; null when it cannot be resolved (e.g. stale root).
459
+ *
460
+ * @param p - path to canonicalize
461
+ * @returns realpath or null
462
+ */
463
+ async function realpathSafe(p) {
464
+ try {
465
+ return await realpath(resolve(p));
466
+ }
467
+ catch {
468
+ // Missing/unreadable root: keep the lexical form (bind-try tolerates).
469
+ return null;
470
+ }
471
+ }
472
+ /**
473
+ * Seatbelt profile: default allow, deny writes outside roots (stdio devices
474
+ * excepted), deny network unless open, and deny common privilege-gaining
475
+ * execs (1-B: privilege=dropped means ops-denied, uid unchanged).
476
+ * Paths are quote-escaped for the sb DSL.
477
+ */
478
+ export function buildSeatbeltProfile(roots, network, extra) {
479
+ const esc = (p) => {
480
+ // A newline would break out of the profile's string literal; refuse loudly
481
+ // instead of silently deleting characters from a real path.
482
+ if (p.includes('\n') || p.includes('\r')) {
483
+ throw new Error(`seatbelt_path_invalid: path contains newline: ${JSON.stringify(p)}`);
484
+ }
485
+ // Quote-escape only. () and spaces are inert inside SBPL strings; stripping
486
+ // them would point subpath rules at a different directory.
487
+ return p.split('\\').join('\\\\').split('"').join('\\"');
488
+ };
489
+ const lines = ['(version 1)', '(allow default)'];
490
+ if (network === 'deny') {
491
+ lines.push('(deny network*)');
492
+ }
493
+ // 1-B: deny privilege-gaining helpers (path list is a best-effort allow-deny)
494
+ for (const bin of extra?.privilegeDenyExec ?? DEFAULT_PRIVILEGE_DENY_EXEC) {
495
+ lines.push(`(deny process-exec (literal "${esc(bin)}"))`);
496
+ }
497
+ lines.push('(deny file-write*)');
498
+ for (const root of roots) {
499
+ lines.push(`(allow file-write* (subpath "${esc(root)}"))`);
86
500
  }
501
+ // stdio sinks must stay writable or basic tooling dies (git opens
502
+ // /dev/null O_RDWR; shells redirect > /dev/null). /dev/fd covers dup'd
503
+ // stdio paths (/dev/std{in,out,err} resolve there). Deliberately excludes
504
+ // /dev/ptmx — no TTY allocation inside the jail.
505
+ for (const dev of SEATBELT_DEVICE_WRITE_ALLOW) {
506
+ lines.push(`(allow file-write* (literal "${esc(dev)}"))`);
507
+ }
508
+ lines.push('(allow file-write* (subpath "/dev/fd"))');
509
+ return lines.join('\n') + '\n';
87
510
  }
511
+ /**
512
+ * POSIX stdio devices the jail must keep writable (macOS Seatbelt only;
513
+ * bwrap supplies its own /dev). Character sinks cannot escape the jail.
514
+ */
515
+ export const SEATBELT_DEVICE_WRITE_ALLOW = [
516
+ '/dev/null',
517
+ '/dev/zero',
518
+ '/dev/tty',
519
+ '/dev/stdin',
520
+ '/dev/stdout',
521
+ '/dev/stderr',
522
+ ];
523
+ /** Common privilege-gaining binaries denied inside Seatbelt (1-B). */
524
+ const DEFAULT_PRIVILEGE_DENY_EXEC = [
525
+ '/usr/bin/sudo',
526
+ '/bin/su',
527
+ '/usr/bin/su',
528
+ '/usr/sbin/chroot',
529
+ '/usr/bin/login',
530
+ '/usr/bin/newgrp',
531
+ '/usr/bin/dscl',
532
+ ];
533
+ function resolveShell() {
534
+ if (process.platform === 'win32') {
535
+ const comspec = process.env.COMSPEC || 'cmd.exe';
536
+ return { executable: comspec, args: ['/d', '/s', '/c'], kind: 'cmd' };
537
+ }
538
+ return { executable: '/bin/sh', args: ['-c'], kind: 'bash' };
539
+ }
540
+ /**
541
+ * Create the best process sandbox this host can offer.
542
+ *
543
+ * @param options - profile override / force env keys
544
+ * @returns sandbox provider with probed isolation
545
+ */
546
+ export async function createProcessSandbox(options) {
547
+ const sandbox = new ProcessSandbox(options);
548
+ await sandbox.probe();
549
+ return sandbox;
550
+ }
551
+ /**
552
+ * Does this profile meet the L4 process floor?
553
+ *
554
+ * @param profile - isolation profile
555
+ * @returns assessment
556
+ */
557
+ export { assessL4ProcessMinimum, supervisedSpawnProfile };