@octopi-agent/engine 0.90.11 → 0.98.4

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 (246) hide show
  1. package/dist/config-admin/agent-presets.d.ts +70 -0
  2. package/dist/config-admin/agent-presets.js +243 -0
  3. package/dist/config-admin/discover.d.ts +30 -0
  4. package/dist/config-admin/discover.js +48 -0
  5. package/dist/config-admin/env.d.ts +22 -0
  6. package/dist/config-admin/env.js +41 -0
  7. package/dist/config-admin/index.d.ts +20 -0
  8. package/dist/config-admin/index.js +15 -0
  9. package/dist/config-admin/model-presets.d.ts +75 -0
  10. package/dist/config-admin/model-presets.js +249 -0
  11. package/dist/config-admin/name-guard.d.ts +14 -0
  12. package/dist/config-admin/name-guard.js +24 -0
  13. package/dist/config-admin/patch.d.ts +56 -0
  14. package/dist/config-admin/patch.js +201 -0
  15. package/dist/config-admin/port.d.ts +68 -0
  16. package/dist/config-admin/port.js +21 -0
  17. package/dist/config-admin/redact.d.ts +39 -0
  18. package/dist/config-admin/redact.js +42 -0
  19. package/dist/config-schema/agent.d.ts +45 -1
  20. package/dist/config-schema/context.d.ts +6 -1
  21. package/dist/config-schema/context.js +8 -0
  22. package/dist/config-schema/engine.d.ts +110 -4
  23. package/dist/config-schema/governance.d.ts +45 -1
  24. package/dist/config-schema/governance.js +187 -0
  25. package/dist/config-schema/models.d.ts +5 -2
  26. package/dist/config-schema/models.js +4 -1
  27. package/dist/config-schema/observability.d.ts +9 -0
  28. package/dist/config-schema/observability.js +29 -0
  29. package/dist/config-schema/run.d.ts +3 -0
  30. package/dist/config-schema/run.js +14 -0
  31. package/dist/config.d.ts +29 -4
  32. package/dist/config.js +15 -4
  33. package/dist/harness/activation/dispatcher.d.ts +8 -2
  34. package/dist/harness/activation/dispatcher.js +33 -5
  35. package/dist/harness/activation/inbox.d.ts +87 -0
  36. package/dist/harness/activation/inbox.js +169 -0
  37. package/dist/harness/activation/runtime.d.ts +9 -8
  38. package/dist/harness/activation/runtime.js +100 -8
  39. package/dist/harness/activation/types.d.ts +19 -0
  40. package/dist/harness/activation/types.js +2 -0
  41. package/dist/harness/agent/builder.d.ts +26 -1
  42. package/dist/harness/agent/builder.js +85 -37
  43. package/dist/harness/agent/config-bridge.d.ts +5 -0
  44. package/dist/harness/agent/config-bridge.js +3 -0
  45. package/dist/harness/agent/config-integrity.d.ts +138 -0
  46. package/dist/harness/agent/config-integrity.js +235 -0
  47. package/dist/harness/agent/wire-agent-builder.js +7 -1
  48. package/dist/harness/collaboration/autonomous-subsystem/index.d.ts +2 -2
  49. package/dist/harness/collaboration/autonomous-subsystem/index.js +1 -1
  50. package/dist/harness/collaboration/autonomous-subsystem/loader.js +3 -0
  51. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.js +19 -2
  52. package/dist/harness/collaboration/autonomous-subsystem/think/completion-guard.d.ts +40 -0
  53. package/dist/harness/collaboration/autonomous-subsystem/think/completion-guard.js +59 -0
  54. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +3 -1
  55. package/dist/harness/collaboration/autonomous-subsystem/think/index.d.ts +2 -0
  56. package/dist/harness/collaboration/autonomous-subsystem/think/index.js +1 -0
  57. package/dist/harness/collaboration/autonomous-subsystem/think/model-resolver.js +1 -1
  58. package/dist/harness/collaboration/autonomous-subsystem/types.d.ts +9 -0
  59. package/dist/harness/collaboration/delegation/child-run.js +21 -5
  60. package/dist/harness/collaboration/delegation/notifier.js +4 -3
  61. package/dist/harness/collaboration/delegation/service.js +2 -3
  62. package/dist/harness/collaboration/delegation/wiring.js +6 -5
  63. package/dist/harness/collaboration/orchestration/reflector/llm-reflector.d.ts +1 -1
  64. package/dist/harness/collaboration/orchestration/reflector/llm-reflector.js +1 -1
  65. package/dist/harness/context/capabilities/compact/engine.d.ts +30 -0
  66. package/dist/harness/context/capabilities/compact/engine.js +198 -46
  67. package/dist/harness/context/capabilities/compact/handover.d.ts +78 -0
  68. package/dist/harness/context/capabilities/compact/handover.js +107 -0
  69. package/dist/harness/context/capabilities/compact/index.d.ts +3 -1
  70. package/dist/harness/context/capabilities/compact/index.js +2 -1
  71. package/dist/harness/context/capabilities/compact/types.d.ts +30 -1
  72. package/dist/harness/context/capabilities/summary/executor.js +2 -1
  73. package/dist/harness/context/capabilities/summary/policies.js +8 -5
  74. package/dist/harness/context/capabilities/summary/resolver.d.ts +1 -1
  75. package/dist/harness/context/capabilities/summary/resolver.js +4 -4
  76. package/dist/harness/context/capabilities/summary/types.d.ts +2 -2
  77. package/dist/harness/context/constitution/default-agents.md +11 -10
  78. package/dist/harness/context/default-context-engine.d.ts +34 -4
  79. package/dist/harness/context/default-context-engine.js +194 -49
  80. package/dist/harness/context/hybrid-compressor.js +6 -0
  81. package/dist/harness/context/layers.d.ts +2 -4
  82. package/dist/harness/context/layers.js +9 -11
  83. package/dist/harness/context/llm-summarizer.d.ts +2 -8
  84. package/dist/harness/context/llm-summarizer.js +69 -91
  85. package/dist/harness/context/message-selector.js +4 -3
  86. package/dist/harness/context/summarize.d.ts +3 -1
  87. package/dist/harness/context/summarize.js +9 -4
  88. package/dist/harness/context/system-prompt-assembler.d.ts +2 -0
  89. package/dist/harness/context/system-prompt-assembler.js +1 -0
  90. package/dist/harness/context/truncate-compressor.js +7 -0
  91. package/dist/harness/context/turn-envelope.d.ts +3 -2
  92. package/dist/harness/context/turn-envelope.js +3 -2
  93. package/dist/harness/context/types.d.ts +33 -1
  94. package/dist/harness/extension/execution-environment/dangerous-commands.d.ts +28 -0
  95. package/dist/harness/extension/execution-environment/dangerous-commands.js +129 -0
  96. package/dist/harness/extension/execution-environment/effect-policy.d.ts +149 -8
  97. package/dist/harness/extension/execution-environment/effect-policy.js +274 -19
  98. package/dist/harness/extension/execution-environment/index.d.ts +4 -2
  99. package/dist/harness/extension/execution-environment/index.js +2 -1
  100. package/dist/harness/extension/execution-environment/kill-switch.d.ts +34 -0
  101. package/dist/harness/extension/execution-environment/kill-switch.js +46 -0
  102. package/dist/harness/extension/execution-environment/ops-audit.d.ts +204 -0
  103. package/dist/harness/extension/execution-environment/ops-audit.js +337 -0
  104. package/dist/harness/extension/execution-environment/privileged-exec.d.ts +158 -0
  105. package/dist/harness/extension/execution-environment/privileged-exec.js +418 -0
  106. package/dist/harness/extension/execution-environment/process-info.d.ts +180 -0
  107. package/dist/harness/extension/execution-environment/process-info.js +466 -0
  108. package/dist/harness/extension/execution-environment/process-isolation.d.ts +7 -0
  109. package/dist/harness/extension/execution-environment/process-isolation.js +9 -0
  110. package/dist/harness/extension/execution-environment/sandbox.d.ts +109 -0
  111. package/dist/harness/extension/execution-environment/sandbox.js +228 -21
  112. package/dist/harness/extension/execution-environment/tool-capabilities.d.ts +1 -1
  113. package/dist/harness/extension/execution-environment/tool-capabilities.js +6 -0
  114. package/dist/harness/extension/execution-environment/types.d.ts +19 -0
  115. package/dist/harness/extension/execution-environment/undo-log.d.ts +6 -2
  116. package/dist/harness/extension/execution-environment/undo-log.js +31 -10
  117. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +5 -0
  118. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.js +33 -0
  119. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +4 -5
  120. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +5 -15
  121. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +3 -0
  122. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +70 -26
  123. package/dist/harness/extension/plugin-ecosystem/tools/document-tools.js +3 -9
  124. package/dist/harness/extension/plugin-ecosystem/tools/file-edit.js +3 -6
  125. package/dist/harness/extension/plugin-ecosystem/tools/file-ops.js +9 -5
  126. package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +9 -130
  127. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +122 -14
  128. package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +2 -0
  129. package/dist/harness/extension/plugin-ecosystem/tools/index.js +2 -0
  130. package/dist/harness/extension/plugin-ecosystem/tools/package-tools.js +4 -13
  131. package/dist/harness/extension/plugin-ecosystem/tools/platform.d.ts +25 -11
  132. package/dist/harness/extension/plugin-ecosystem/tools/platform.js +168 -62
  133. package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.d.ts +43 -0
  134. package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.js +350 -0
  135. package/dist/harness/extension/plugin-ecosystem/tools/process-tools.d.ts +30 -0
  136. package/dist/harness/extension/plugin-ecosystem/tools/process-tools.js +137 -0
  137. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +54 -4
  138. package/dist/harness/governance/human-in-the-loop/decision-cache.js +42 -16
  139. package/dist/harness/governance/security/default-risk-policy.d.ts +1 -0
  140. package/dist/harness/governance/security/default-risk-policy.js +1 -0
  141. package/dist/harness/governance/security/default-security-guard.js +9 -0
  142. package/dist/harness/governance/security/index.d.ts +1 -0
  143. package/dist/harness/governance/security/index.js +2 -0
  144. package/dist/harness/governance/security/risk-evaluator.js +13 -0
  145. package/dist/harness/governance/security/risk-types.d.ts +12 -0
  146. package/dist/harness/governance/security/shell-parser-fallback.d.ts +29 -0
  147. package/dist/harness/governance/security/shell-parser-fallback.js +410 -0
  148. package/dist/harness/governance/security/shell-parser-shared.d.ts +83 -0
  149. package/dist/harness/governance/security/shell-parser-shared.js +188 -0
  150. package/dist/harness/governance/security/shell-parser-treesitter.d.ts +52 -0
  151. package/dist/harness/governance/security/shell-parser-treesitter.js +370 -0
  152. package/dist/harness/governance/security/shell-parser.d.ts +23 -10
  153. package/dist/harness/governance/security/shell-parser.js +37 -496
  154. package/dist/harness/governance/security/temp-path.d.ts +9 -0
  155. package/dist/harness/governance/security/temp-path.js +13 -2
  156. package/dist/harness/governance/security/vendor/README.md +24 -0
  157. package/dist/harness/governance/security/vendor/tree-sitter-bash.LICENSE.txt +21 -0
  158. package/dist/harness/governance/security/vendor/tree-sitter-bash.wasm +0 -0
  159. package/dist/harness/governance/session-acl/seed-roles.js +14 -0
  160. package/dist/harness/index.d.ts +2 -0
  161. package/dist/harness/index.js +2 -0
  162. package/dist/harness/knowledge/fts.js +1 -2
  163. package/dist/harness/knowledge/index-store.js +59 -9
  164. package/dist/harness/memory/index.d.ts +6 -2
  165. package/dist/harness/memory/index.js +4 -1
  166. package/dist/harness/memory/memory-events.d.ts +25 -0
  167. package/dist/harness/memory/memory-events.js +38 -0
  168. package/dist/harness/memory/sqlite/agent-db.js +15 -0
  169. package/dist/harness/memory/sqlite/keyword-search.d.ts +1 -0
  170. package/dist/harness/memory/sqlite/keyword-search.js +4 -3
  171. package/dist/harness/memory/sqlite/wisdom-store.d.ts +7 -2
  172. package/dist/harness/memory/sqlite/wisdom-store.js +51 -2
  173. package/dist/harness/memory/steward-policy.d.ts +3 -0
  174. package/dist/harness/memory/steward-policy.js +1 -1
  175. package/dist/harness/memory/types.d.ts +41 -3
  176. package/dist/harness/memory/wisdom-attribution.d.ts +136 -0
  177. package/dist/harness/memory/wisdom-attribution.js +287 -0
  178. package/dist/harness/memory/wisdom-events.d.ts +37 -0
  179. package/dist/harness/memory/wisdom-events.js +61 -0
  180. package/dist/harness/memory/wisdom-formation.d.ts +20 -1
  181. package/dist/harness/memory/wisdom-formation.js +55 -21
  182. package/dist/harness/memory/wisdom.d.ts +7 -2
  183. package/dist/harness/memory/wisdom.js +40 -2
  184. package/dist/harness/observability/observer/hub.js +8 -0
  185. package/dist/harness/observability/observer/run-snapshot.js +1 -0
  186. package/dist/harness/observability/observer/types.d.ts +4 -0
  187. package/dist/harness/run/agent/agent.d.ts +7 -0
  188. package/dist/harness/run/agent/agent.js +23 -1
  189. package/dist/harness/run/reliability/fallback-provider.d.ts +117 -5
  190. package/dist/harness/run/reliability/fallback-provider.js +262 -22
  191. package/dist/harness/run/reliability/harness-events.d.ts +24 -1
  192. package/dist/harness/run/reliability/model-error-policy.d.ts +32 -0
  193. package/dist/harness/run/reliability/model-error-policy.js +42 -0
  194. package/dist/harness/run/reliability/provider-wrapper.js +29 -2
  195. package/dist/harness/run/reliability/refusal-guard.d.ts +20 -0
  196. package/dist/harness/run/reliability/refusal-guard.js +102 -0
  197. package/dist/harness/run/reliability/run-agent.js +231 -33
  198. package/dist/harness/run/run-guard/default-run-guard.js +1 -1
  199. package/dist/harness/run/run-scope.d.ts +35 -0
  200. package/dist/harness/run/runner.d.ts +141 -2
  201. package/dist/harness/run/runner.js +592 -42
  202. package/dist/harness/session/attachments/llm-intent.js +2 -1
  203. package/dist/harness/session/tasks/render.d.ts +4 -1
  204. package/dist/harness/session/tasks/render.js +10 -7
  205. package/dist/harness/shared/events/agent-event-map.d.ts +66 -0
  206. package/dist/harness/shared/events/agent-event-map.js +5 -0
  207. package/dist/harness/shared/paths/glob.d.ts +52 -0
  208. package/dist/harness/shared/paths/glob.js +218 -0
  209. package/dist/harness/shared/paths/index.d.ts +84 -0
  210. package/dist/harness/shared/paths/index.js +179 -0
  211. package/dist/index.d.ts +3 -3
  212. package/dist/index.js +2 -2
  213. package/dist/integration/agent-runtime/channel-message-source.js +19 -1
  214. package/dist/integration/index.d.ts +2 -0
  215. package/dist/integration/index.js +1 -0
  216. package/dist/integration/observability/loop-watchdog.d.ts +56 -0
  217. package/dist/integration/observability/loop-watchdog.js +177 -0
  218. package/dist/integration/observability/metrics.d.ts +3 -0
  219. package/dist/integration/observability/metrics.js +18 -7
  220. package/dist/integration/providers/anthropic.d.ts +23 -0
  221. package/dist/integration/providers/anthropic.js +97 -12
  222. package/dist/integration/providers/fetch-timeout.d.ts +42 -0
  223. package/dist/integration/providers/fetch-timeout.js +51 -0
  224. package/dist/integration/providers/openai.d.ts +10 -0
  225. package/dist/integration/providers/openai.js +58 -11
  226. package/dist/integration/providers/provider-diagnostics.d.ts +80 -0
  227. package/dist/integration/providers/provider-diagnostics.js +89 -0
  228. package/dist/integration/providers/timeout-coherence.d.ts +52 -0
  229. package/dist/integration/providers/timeout-coherence.js +68 -0
  230. package/dist/integration/providers/wire-dump.d.ts +62 -0
  231. package/dist/integration/providers/wire-dump.js +111 -2
  232. package/dist/integration/storage/jsonl.js +4 -1
  233. package/dist/subsystems/cognition-steward/conceptualize/config.yaml +4 -2
  234. package/dist/subsystems/cognition-steward/conceptualize/handler.js +12 -20
  235. package/dist/subsystems/memory-steward/backfill/config.yaml +4 -2
  236. package/dist/subsystems/memory-steward/backfill/handler.js +44 -52
  237. package/dist/subsystems/wisdom-steward/attribute/SUBSYSTEM.md +24 -0
  238. package/dist/subsystems/wisdom-steward/attribute/config.yaml +60 -0
  239. package/dist/subsystems/wisdom-steward/attribute/handler.d.ts +23 -0
  240. package/dist/subsystems/wisdom-steward/attribute/handler.js +167 -0
  241. package/dist/subsystems/wisdom-steward/evaluate/handler.js +3 -1
  242. package/dist/subsystems/wisdom-steward/formation/config.yaml +12 -5
  243. package/dist/subsystems/wisdom-steward/formation/handler.js +12 -18
  244. package/dist/subsystems/wisdom-steward/govern/config.yaml +1 -1
  245. package/dist/subsystems/wisdom-steward/govern/handler.js +4 -0
  246. package/package.json +8 -2
@@ -0,0 +1,158 @@
1
+ /**
2
+ * 独立提权执行通道(ops P3,`arch/ops-privileged-mode.md` §5 P3 / §8)
3
+ *
4
+ * 设计要点(拍板 + 评审修复):
5
+ * - **提权走独立通道,不与牢笼抢轴**:引擎侧 `execFile` 执行完整 argv——不经 shell
6
+ * (无插值/无通配)、不包 jail、env 消毒、cwd 钉住(规则显式或 `/`,**不受 agent
7
+ * 控制**)、超时 + 真树杀(detached 进程组)。
8
+ * - **全等匹配**(effect-policy `matchEscalationRule`):`cmd` 绝对路径 + `args` 逐项
9
+ * 全等;执行即所配 argv,无任何隐式前缀。
10
+ * - **二进制不可换(TOCTOU 护栏)**:对规则的**每一个有效目标**(`via: sudo` 形态下是
11
+ * sudo 之后的真实二进制,不只是 `cmd`)检查:不在 agent 可写面(含符号链接解析后)、
12
+ * 文件与父目录链均不可被 agent uid / 组 / 世界写(可写目录 + rename 即可换二进制)。
13
+ * - **启动期探测,拿不到即拒绝启动**(拍板 #5):`via: sudo` 跑 `sudo -n true`(绝对
14
+ * 路径);`via: direct` 断言高权限(geteuid 0 / win32 `fsutil dirty query`)。
15
+ * 探测证明「通道可用」,不证明「每条规则被 sudoers 授权」(文档如实声明)。
16
+ */
17
+ /** 白名单提权规则(§4) */
18
+ export interface EscalationRule {
19
+ /** 稳定规则标识(审计关联);缺省 `allow[<下标>]`(重排会断裂——显式 id 更好) */
20
+ id?: string;
21
+ /** 绝对路径(拒绝相对路径:PATH 解析 = 可换二进制) */
22
+ cmd: string;
23
+ /** 逐项全等的 argv 尾部;`via: sudo` 形态必须以 `-n` 开头 + 真实目标绝对路径 */
24
+ args?: string[];
25
+ /** true → 执行前走 HitlDecision 确认闸(缓存 key 含完整 argv) */
26
+ confirm?: boolean;
27
+ /** 提权进程的工作目录(绝对路径);缺省 `/`——绝不取 agent 的 cwd */
28
+ cwd?: string;
29
+ }
30
+ /** 提权策略(resolved) */
31
+ export interface EscalationPolicy {
32
+ /**
33
+ * `none`(缺省)| `allowlist`(cmd+args 全等)| `full`(全量档,P4)。
34
+ * `full` 仅在 `jail: "none"` + `privilegedAck` + `mode: "host"` 下合法(§4.1)。
35
+ */
36
+ policy: 'none' | 'allowlist' | 'full';
37
+ via: 'sudo' | 'direct';
38
+ allow: EscalationRule[];
39
+ }
40
+ /** 提权执行输入 */
41
+ export interface PrivilegedExecOptions {
42
+ /** 已通过全等匹配的 cmd(绝对路径) */
43
+ cmd: string;
44
+ args: string[];
45
+ via: 'sudo' | 'direct';
46
+ /** 特权进程 cwd(缺省 `/`;规则可显式指定) */
47
+ cwd?: string;
48
+ timeoutMs?: number;
49
+ /** run 中止信号:触发即时树杀(与超时同一收回路径,不等 timeoutMs 兜底) */
50
+ abortSignal?: AbortSignal;
51
+ }
52
+ /** 提权执行结果 */
53
+ export interface PrivilegedExecResult {
54
+ /** false = 进程从未成功 spawn(区别于「执行了但非零退出」) */
55
+ executed: boolean;
56
+ exitCode: number | null;
57
+ stdout: string;
58
+ stderr: string;
59
+ durationMs: number;
60
+ timedOut: boolean;
61
+ /** run 中止即时树杀所致(区别于 timedOut:外部中止,不是命令超时) */
62
+ aborted?: boolean;
63
+ }
64
+ /** 启动探测结论 */
65
+ export type EscalationReadiness = {
66
+ ok: true;
67
+ } | {
68
+ ok: false;
69
+ reason: string;
70
+ };
71
+ /**
72
+ * 执行一条已匹配的提权命令(不经 shell、不包 jail、cwd 钉住)。
73
+ *
74
+ * @param options - cmd/args(完整 argv)、via、cwd、timeoutMs
75
+ * @returns 执行结果(spawn 从未成功时 executed=false)
76
+ */
77
+ export declare function runPrivilegedExec(options: PrivilegedExecOptions): Promise<PrivilegedExecResult>;
78
+ /**
79
+ * 列出规则的**有效提权目标**(TOCTOU 护栏逐个检查的对象)。
80
+ *
81
+ * `via: sudo` 形态的真正目标是 sudo 之后的二进制(`args[1]`)——只查 `cmd` 等于不查。
82
+ *
83
+ * @param rule - 白名单规则
84
+ * @param via - 通道形态
85
+ * @returns 目标路径列表;形态非法时 `invalid` 给出原因
86
+ */
87
+ export declare function escalationRuleTargets(rule: EscalationRule, via: 'sudo' | 'direct'): {
88
+ targets: string[];
89
+ } | {
90
+ invalid: string;
91
+ };
92
+ /**
93
+ * TOCTOU 护栏:目标二进制不可被换(agent 可写面 / 文件或父目录可写 → 拒绝)。
94
+ *
95
+ * 检查口径(评审修复):
96
+ * - 路径与其 `realpath` 都做可写面判定(符号链接穿透);
97
+ * - 文件本体 **与父目录链**都不可写(可写目录 + rename 即可替换 0555 文件);
98
+ * - 目标不存在(可后装)时仅当父目录链安全才放行。
99
+ *
100
+ * @param target - 目标二进制绝对路径
101
+ * @param writableRoots - agent 可写根(workspace/home/tmp/transactionRoots/…)
102
+ * @returns 违规原因;通过返回 null
103
+ */
104
+ export declare function checkEscalationBinary(target: string, writableRoots: readonly string[]): string | null;
105
+ /**
106
+ * 提权可写根的统一口径(daemon 启动探测与 resolve 校验共用,防两处漂移)。
107
+ *
108
+ * @param options.workspaces - agent workspace 集合
109
+ * @param options.transactionRoots - 配置 transactionRoots
110
+ * @returns 可写根列表(含 home/tmp/OCTOPI_HOME)
111
+ */
112
+ export declare function escalationWritableRoots(options?: {
113
+ workspaces?: readonly string[];
114
+ transactionRoots?: readonly string[];
115
+ }): string[];
116
+ /**
117
+ * 启动期探测:声明了提权就必须真的拿得到(拍板 #5:拒绝启动,禁止降级静默)。
118
+ *
119
+ * @param config - 提权策略(配置形或 resolved 均可)
120
+ * @param options.writableRoots - TOCTOU 护栏的可写根集合
121
+ * @returns ok 或拒绝原因
122
+ */
123
+ export declare function probeEscalationReadiness(config: EscalationPolicy | {
124
+ policy?: 'none' | 'allowlist' | 'full';
125
+ via?: 'sudo' | 'direct';
126
+ allow?: EscalationRule[];
127
+ } | undefined, options?: {
128
+ writableRoots?: readonly string[];
129
+ }): Promise<EscalationReadiness>;
130
+ /**
131
+ * 本进程是否已高权限(root / Windows elevated 管理员令牌)。
132
+ *
133
+ * POSIX 同步读 `geteuid()`;win32 走 `fsutil dirty query` 行为探测(与
134
+ * `probeEscalationReadiness` 的 direct 分支同口径,不读配置位、不猜 token)。
135
+ * 结果按进程生命期缓存(权限不可自行提升,探测一次即事实不变)。
136
+ *
137
+ * @returns true = 高权限进程
138
+ */
139
+ export declare function isProcessElevated(): Promise<boolean>;
140
+ /** 同步口径的高权限猜测(POSIX 可判;win32 同步不可判时如实返回 false 交由异步探测补) */
141
+ export declare function isProcessElevatedSync(): boolean;
142
+ /**
143
+ * root/elevated 部署的显式 privileged 声明断言(§5 P4 root 部署语义)。
144
+ *
145
+ * daemon 以 root 跑时没有 sudo,危险轴变成「笼不笼 × uid=0」——启动期高权限进程
146
+ * 必须在 effectPolicy 里显式 `privilegedAck` 表态,拿不到声明就拒绝启动,
147
+ * 不允许「root 就这么跑着」的静默特权态。
148
+ *
149
+ * @param params.elevated - 进程是否高权限(`isProcessElevated` 探测值)
150
+ * @param params.privilegedAck - effectPolicy.privilegedAck(可缺省)
151
+ * @param params.scope - 出错信息里的配置面标识(如 `<top>` / agent id)
152
+ * @throws `privileged_declaration_required`(elevated 且无声明)
153
+ */
154
+ export declare function assertPrivilegedDeclaration(params: {
155
+ elevated: boolean;
156
+ privilegedAck?: string;
157
+ scope: string;
158
+ }): void;
@@ -0,0 +1,418 @@
1
+ /**
2
+ * 独立提权执行通道(ops P3,`arch/ops-privileged-mode.md` §5 P3 / §8)
3
+ *
4
+ * 设计要点(拍板 + 评审修复):
5
+ * - **提权走独立通道,不与牢笼抢轴**:引擎侧 `execFile` 执行完整 argv——不经 shell
6
+ * (无插值/无通配)、不包 jail、env 消毒、cwd 钉住(规则显式或 `/`,**不受 agent
7
+ * 控制**)、超时 + 真树杀(detached 进程组)。
8
+ * - **全等匹配**(effect-policy `matchEscalationRule`):`cmd` 绝对路径 + `args` 逐项
9
+ * 全等;执行即所配 argv,无任何隐式前缀。
10
+ * - **二进制不可换(TOCTOU 护栏)**:对规则的**每一个有效目标**(`via: sudo` 形态下是
11
+ * sudo 之后的真实二进制,不只是 `cmd`)检查:不在 agent 可写面(含符号链接解析后)、
12
+ * 文件与父目录链均不可被 agent uid / 组 / 世界写(可写目录 + rename 即可换二进制)。
13
+ * - **启动期探测,拿不到即拒绝启动**(拍板 #5):`via: sudo` 跑 `sudo -n true`(绝对
14
+ * 路径);`via: direct` 断言高权限(geteuid 0 / win32 `fsutil dirty query`)。
15
+ * 探测证明「通道可用」,不证明「每条规则被 sudoers 授权」(文档如实声明)。
16
+ */
17
+ import { spawn } from 'node:child_process';
18
+ import { statSync, realpathSync } from 'node:fs';
19
+ import { homedir, tmpdir } from 'node:os';
20
+ import { dirname, isAbsolute, resolve, sep } from 'node:path';
21
+ import { killProcessTree, scrubEnv } from './process-isolation.js';
22
+ function envForExec() {
23
+ // root 态下 PATH/HOME 都是注入面(per-user 配置、可写 PATH 目录)——钉死系统值。
24
+ // 其余一律不透传(凭证/注入面收敛)。
25
+ if (process.platform === 'win32') {
26
+ return scrubEnv({
27
+ SystemRoot: process.env.SystemRoot ?? 'C:\\Windows',
28
+ WINDIR: process.env.WINDIR ?? 'C:\\Windows',
29
+ PATH: `${process.env.SystemRoot ?? 'C:\\Windows'}\\System32`,
30
+ });
31
+ }
32
+ return scrubEnv({ PATH: '/usr/sbin:/usr/bin:/sbin:/bin', HOME: '/', LANG: 'C' });
33
+ }
34
+ const OUTPUT_CAP = 128 * 1024;
35
+ function capOutput(text) {
36
+ return text.length > OUTPUT_CAP ? `${text.slice(0, OUTPUT_CAP)}\n…[truncated ${text.length - OUTPUT_CAP} chars]` : text;
37
+ }
38
+ /**
39
+ * 执行一条已匹配的提权命令(不经 shell、不包 jail、cwd 钉住)。
40
+ *
41
+ * @param options - cmd/args(完整 argv)、via、cwd、timeoutMs
42
+ * @returns 执行结果(spawn 从未成功时 executed=false)
43
+ */
44
+ export function runPrivilegedExec(options) {
45
+ const started = Date.now();
46
+ const timeoutMs = options.timeoutMs ?? 120_000;
47
+ return new Promise((resolveP) => {
48
+ let settled = false;
49
+ let stdout = '';
50
+ let stderr = '';
51
+ let timedOut = false;
52
+ let aborted = false;
53
+ let killer;
54
+ let onAbort;
55
+ const done = (result) => {
56
+ if (settled)
57
+ return;
58
+ settled = true;
59
+ if (killer)
60
+ clearTimeout(killer);
61
+ if (onAbort)
62
+ options.abortSignal?.removeEventListener('abort', onAbort);
63
+ resolveP(result);
64
+ };
65
+ try {
66
+ // spawn(不是 execFile):detached 只有 spawn 才转发——独立进程组是真树杀的前提
67
+ const child = spawn(options.cmd, options.args, {
68
+ cwd: options.cwd ?? '/',
69
+ env: envForExec(),
70
+ windowsHide: true,
71
+ detached: process.platform !== 'win32',
72
+ stdio: ['ignore', 'pipe', 'pipe'],
73
+ });
74
+ child.stdout?.setEncoding('utf8');
75
+ child.stderr?.setEncoding('utf8');
76
+ child.stdout?.on('data', (chunk) => {
77
+ if (stdout.length < OUTPUT_CAP * 2)
78
+ stdout += chunk;
79
+ });
80
+ child.stderr?.on('data', (chunk) => {
81
+ if (stderr.length < OUTPUT_CAP * 2)
82
+ stderr += chunk;
83
+ });
84
+ killer = setTimeout(() => {
85
+ timedOut = true;
86
+ try {
87
+ killProcessTree(child);
88
+ }
89
+ catch {
90
+ // 树杀失败退化单杀:至少收回直接子进程,结果侧如实 timedOut
91
+ try {
92
+ child.kill('SIGKILL');
93
+ }
94
+ catch {
95
+ // 进程已死:结果照常出
96
+ }
97
+ }
98
+ }, timeoutMs);
99
+ killer.unref?.();
100
+ // run 中止即时树杀(与超时同一收回路径):外部中止不等 timeoutMs 兜底
101
+ onAbort = () => {
102
+ aborted = true;
103
+ try {
104
+ killProcessTree(child);
105
+ }
106
+ catch {
107
+ try {
108
+ child.kill('SIGKILL');
109
+ }
110
+ catch {
111
+ // 进程已死:结果照常出
112
+ }
113
+ }
114
+ };
115
+ if (options.abortSignal) {
116
+ if (options.abortSignal.aborted)
117
+ onAbort();
118
+ else
119
+ options.abortSignal.addEventListener('abort', onAbort, { once: true });
120
+ }
121
+ child.on('error', (err) => {
122
+ // spawn 从未成功(ENOENT/EPERM…)= 未执行,区别于执行了但非零退出
123
+ done({
124
+ executed: false,
125
+ exitCode: null,
126
+ stdout: capOutput(stdout),
127
+ stderr: capOutput(stderr || errText(err)),
128
+ durationMs: Date.now() - started,
129
+ timedOut,
130
+ ...(aborted ? { aborted: true } : {}),
131
+ });
132
+ });
133
+ // 收 `exit` 而非 `close`:后台子孙继承 stdio 管道时 close 会被吊住不返回
134
+ child.on('exit', (code) => {
135
+ // 命令结束即树杀(D1 同语义):特权通道不留孤儿(后台 `&` 进程/孙进程);
136
+ // 守护型目标(systemctl 等)已 setsid 自立组,不受此杀
137
+ try {
138
+ killProcessTree(child);
139
+ }
140
+ catch {
141
+ // 组已空或无权限:无孤儿可杀,照常出结果
142
+ }
143
+ done({
144
+ executed: true,
145
+ exitCode: code,
146
+ stdout: capOutput(stdout),
147
+ stderr: capOutput(stderr),
148
+ durationMs: Date.now() - started,
149
+ timedOut,
150
+ ...(aborted ? { aborted: true } : {}),
151
+ });
152
+ });
153
+ }
154
+ catch (err) {
155
+ // spawn 同步抛出:同「未执行」语义,绝不冒充执行结果
156
+ done({
157
+ executed: false,
158
+ exitCode: null,
159
+ stdout: '',
160
+ stderr: errText(err),
161
+ durationMs: Date.now() - started,
162
+ timedOut,
163
+ });
164
+ }
165
+ });
166
+ }
167
+ function errText(err) {
168
+ return err instanceof Error ? err.message : String(err);
169
+ }
170
+ /**
171
+ * 列出规则的**有效提权目标**(TOCTOU 护栏逐个检查的对象)。
172
+ *
173
+ * `via: sudo` 形态的真正目标是 sudo 之后的二进制(`args[1]`)——只查 `cmd` 等于不查。
174
+ *
175
+ * @param rule - 白名单规则
176
+ * @param via - 通道形态
177
+ * @returns 目标路径列表;形态非法时 `invalid` 给出原因
178
+ */
179
+ export function escalationRuleTargets(rule, via) {
180
+ const args = rule.args ?? [];
181
+ if (via === 'sudo') {
182
+ if (args[0] !== '-n') {
183
+ return { invalid: `via=sudo rules must spell \`sudo -n\` explicitly (args[0] must be "-n"), got ${JSON.stringify(args[0])}` };
184
+ }
185
+ const target = args[1];
186
+ if (target === undefined || !isAbsolute(target)) {
187
+ return { invalid: `via=sudo rules need the real target as args[1] (absolute path), got ${JSON.stringify(target)}` };
188
+ }
189
+ return { targets: [rule.cmd, target] };
190
+ }
191
+ return { targets: [rule.cmd] };
192
+ }
193
+ /**
194
+ * TOCTOU 护栏:目标二进制不可被换(agent 可写面 / 文件或父目录可写 → 拒绝)。
195
+ *
196
+ * 检查口径(评审修复):
197
+ * - 路径与其 `realpath` 都做可写面判定(符号链接穿透);
198
+ * - 文件本体 **与父目录链**都不可写(可写目录 + rename 即可替换 0555 文件);
199
+ * - 目标不存在(可后装)时仅当父目录链安全才放行。
200
+ *
201
+ * @param target - 目标二进制绝对路径
202
+ * @param writableRoots - agent 可写根(workspace/home/tmp/transactionRoots/…)
203
+ * @returns 违规原因;通过返回 null
204
+ */
205
+ export function checkEscalationBinary(target, writableRoots) {
206
+ if (!isAbsolute(target))
207
+ return `path must be absolute, got ${JSON.stringify(target)}`;
208
+ const raw = resolve(target);
209
+ const roots = writableRoots.map((r) => resolve(r));
210
+ const underRoots = (p) => {
211
+ for (const root of roots) {
212
+ if (p === root || p.startsWith(root.endsWith(sep) ? root : root + sep)) {
213
+ return `is inside agent-writable root ${root}`;
214
+ }
215
+ }
216
+ return null;
217
+ };
218
+ const hit = underRoots(raw);
219
+ if (hit)
220
+ return `cmd ${raw} ${hit}`;
221
+ const uid = typeof process.getuid === 'function' ? process.getuid() : null;
222
+ const checkParentChain = (p) => {
223
+ let dir = dirname(p);
224
+ for (;;) {
225
+ const parentHit = underRoots(dir);
226
+ if (parentHit)
227
+ return `parent dir ${dir} ${parentHit}`;
228
+ if (dir === dirname(dir))
229
+ return null;
230
+ let st;
231
+ try {
232
+ st = statSync(dir);
233
+ }
234
+ catch {
235
+ dir = dirname(dir);
236
+ continue;
237
+ }
238
+ const writable = (st.mode & 0o222) !== 0;
239
+ if (writable) {
240
+ if (uid !== null && st.uid === uid)
241
+ return `parent dir ${dir} is writable by the agent uid`;
242
+ if ((st.mode & 0o022) !== 0)
243
+ return `parent dir ${dir} is group/world-writable`;
244
+ }
245
+ dir = dirname(dir);
246
+ }
247
+ };
248
+ // 目标不存在(可后装):仅当父目录链不可换时放行;存在时连同 realpath 一并检查
249
+ let real = raw;
250
+ try {
251
+ real = realpathSync(raw);
252
+ const realHit = underRoots(real);
253
+ if (realHit)
254
+ return `cmd ${real} ${realHit} (symlink target)`;
255
+ }
256
+ catch {
257
+ const parent = checkParentChain(raw);
258
+ if (parent)
259
+ return `cmd ${raw}: ${parent}`;
260
+ return null;
261
+ }
262
+ const parent = checkParentChain(real) ?? checkParentChain(raw);
263
+ if (parent)
264
+ return `cmd ${raw}: ${parent}`;
265
+ // Windows 无 POSIX mode 语义(读回恒 0666):roots + 父目录链即全部口径(win32 边界)
266
+ if (process.platform === 'win32')
267
+ return null;
268
+ let st;
269
+ try {
270
+ st = statSync(real);
271
+ }
272
+ catch {
273
+ return `cmd ${real} unreadable`;
274
+ }
275
+ if ((st.mode & 0o222) === 0)
276
+ return null;
277
+ if (uid !== null && st.uid === uid)
278
+ return `cmd ${real} is writable by the agent uid (${uid}) — replaceable binary`;
279
+ if ((st.mode & 0o022) !== 0)
280
+ return `cmd ${real} is group/world-writable — replaceable binary`;
281
+ return null;
282
+ }
283
+ /**
284
+ * 提权可写根的统一口径(daemon 启动探测与 resolve 校验共用,防两处漂移)。
285
+ *
286
+ * @param options.workspaces - agent workspace 集合
287
+ * @param options.transactionRoots - 配置 transactionRoots
288
+ * @returns 可写根列表(含 home/tmp/OCTOPI_HOME)
289
+ */
290
+ export function escalationWritableRoots(options) {
291
+ return [
292
+ ...(options?.workspaces ?? []),
293
+ ...(options?.transactionRoots ?? []),
294
+ homedir(),
295
+ tmpdir(),
296
+ resolve(homedir(), '.octopi'),
297
+ ];
298
+ }
299
+ /**
300
+ * 启动期探测:声明了提权就必须真的拿得到(拍板 #5:拒绝启动,禁止降级静默)。
301
+ *
302
+ * @param config - 提权策略(配置形或 resolved 均可)
303
+ * @param options.writableRoots - TOCTOU 护栏的可写根集合
304
+ * @returns ok 或拒绝原因
305
+ */
306
+ export async function probeEscalationReadiness(config, options) {
307
+ const escalation = {
308
+ policy: config?.policy ?? 'none',
309
+ via: config?.via ?? 'sudo',
310
+ allow: config?.allow ?? [],
311
+ };
312
+ if (escalation.policy === 'none')
313
+ return { ok: true };
314
+ if (escalation.policy === 'full') {
315
+ // 全量档(P4)没有 allowlist 面;带 allow 规则 = 配置死键(schema 已拒,库路径兜底)
316
+ if (escalation.allow.length > 0) {
317
+ return { ok: false, reason: 'escalation.policy=full takes no escalation.allow rules (exact-match list is an allowlist-only concept)' };
318
+ }
319
+ }
320
+ else if (escalation.allow.length === 0) {
321
+ return { ok: false, reason: 'escalation.policy=allowlist but effectPolicy.escalation.allow is empty' };
322
+ }
323
+ for (const rule of escalation.allow) {
324
+ const targets = escalationRuleTargets(rule, escalation.via);
325
+ if ('invalid' in targets)
326
+ return { ok: false, reason: `allowlist rule rejected: ${targets.invalid}` };
327
+ for (const target of targets.targets) {
328
+ const bad = checkEscalationBinary(target, options?.writableRoots ?? escalationWritableRoots());
329
+ if (bad)
330
+ return { ok: false, reason: `allowlist rule rejected: ${bad}` };
331
+ }
332
+ }
333
+ if (escalation.via === 'sudo') {
334
+ // 绝对路径执行(裸名 sudo 可被 PATH 劫持);探测≠规则被 sudoers 授权(文档如实声明)
335
+ const probe = await runPrivilegedExec({
336
+ cmd: '/usr/bin/sudo',
337
+ args: ['-n', 'true'],
338
+ via: 'sudo',
339
+ timeoutMs: 5000,
340
+ });
341
+ if (probe.exitCode !== 0) {
342
+ return {
343
+ ok: false,
344
+ reason: `escalation.via=sudo but ` + '`/usr/bin/sudo -n true`' + ` failed (exit=${probe.exitCode}): ${probe.stderr.trim()}`,
345
+ };
346
+ }
347
+ return { ok: true };
348
+ }
349
+ // via: direct —— 进程自身必须已高权限(POSIX euid 0 / win32 fsutil 探测)
350
+ if (process.platform === 'win32') {
351
+ const fsutil = `${process.env.SystemRoot ?? 'C:\\Windows'}\\System32\\fsutil.exe`;
352
+ const probe = await runPrivilegedExec({ cmd: fsutil, args: ['dirty', 'query', 'C:'], via: 'direct', timeoutMs: 5000 });
353
+ if (probe.exitCode !== 0) {
354
+ return { ok: false, reason: 'escalation.via=direct but process is not elevated (`fsutil dirty query` failed)' };
355
+ }
356
+ return { ok: true };
357
+ }
358
+ const euid = typeof process.geteuid === 'function' ? process.geteuid() : -1;
359
+ if (euid !== 0) {
360
+ return { ok: false, reason: `escalation.via=direct but geteuid()=${euid} (need 0)` };
361
+ }
362
+ return { ok: true };
363
+ }
364
+ /**
365
+ * 本进程是否已高权限(root / Windows elevated 管理员令牌)。
366
+ *
367
+ * POSIX 同步读 `geteuid()`;win32 走 `fsutil dirty query` 行为探测(与
368
+ * `probeEscalationReadiness` 的 direct 分支同口径,不读配置位、不猜 token)。
369
+ * 结果按进程生命期缓存(权限不可自行提升,探测一次即事实不变)。
370
+ *
371
+ * @returns true = 高权限进程
372
+ */
373
+ export async function isProcessElevated() {
374
+ if (cachedElevated !== undefined)
375
+ return cachedElevated;
376
+ if (process.platform === 'win32') {
377
+ const fsutil = `${process.env.SystemRoot ?? 'C:\\Windows'}\\System32\\fsutil.exe`;
378
+ const probe = await runPrivilegedExec({
379
+ cmd: fsutil,
380
+ args: ['dirty', 'query', 'C:'],
381
+ via: 'direct',
382
+ timeoutMs: 5000,
383
+ });
384
+ cachedElevated = probe.exitCode === 0;
385
+ }
386
+ else {
387
+ const euid = typeof process.geteuid === 'function' ? process.geteuid() : -1;
388
+ cachedElevated = euid === 0;
389
+ }
390
+ return cachedElevated;
391
+ }
392
+ let cachedElevated;
393
+ /** 同步口径的高权限猜测(POSIX 可判;win32 同步不可判时如实返回 false 交由异步探测补) */
394
+ export function isProcessElevatedSync() {
395
+ if (process.platform === 'win32')
396
+ return false;
397
+ return typeof process.geteuid === 'function' ? process.geteuid() === 0 : false;
398
+ }
399
+ /**
400
+ * root/elevated 部署的显式 privileged 声明断言(§5 P4 root 部署语义)。
401
+ *
402
+ * daemon 以 root 跑时没有 sudo,危险轴变成「笼不笼 × uid=0」——启动期高权限进程
403
+ * 必须在 effectPolicy 里显式 `privilegedAck` 表态,拿不到声明就拒绝启动,
404
+ * 不允许「root 就这么跑着」的静默特权态。
405
+ *
406
+ * @param params.elevated - 进程是否高权限(`isProcessElevated` 探测值)
407
+ * @param params.privilegedAck - effectPolicy.privilegedAck(可缺省)
408
+ * @param params.scope - 出错信息里的配置面标识(如 `<top>` / agent id)
409
+ * @throws `privileged_declaration_required`(elevated 且无声明)
410
+ */
411
+ export function assertPrivilegedDeclaration(params) {
412
+ if (!params.elevated)
413
+ return;
414
+ if (params.privilegedAck?.trim())
415
+ return;
416
+ throw new Error(`privileged_declaration_required (${params.scope}): process is elevated (root/admin) but ` +
417
+ `effectPolicy.privilegedAck is missing — declare the privileged deployment explicitly or run unprivileged`);
418
+ }