@octopi-agent/engine 0.90.11 → 0.97.15

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 (169) 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 +43 -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 +106 -4
  23. package/dist/config-schema/governance.d.ts +43 -1
  24. package/dist/config-schema/governance.js +157 -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 +15 -1
  42. package/dist/harness/agent/builder.js +31 -10
  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 +72 -0
  46. package/dist/harness/agent/config-integrity.js +146 -0
  47. package/dist/harness/agent/wire-agent-builder.js +2 -1
  48. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +3 -1
  49. package/dist/harness/collaboration/delegation/child-run.js +21 -5
  50. package/dist/harness/collaboration/delegation/notifier.js +4 -3
  51. package/dist/harness/collaboration/delegation/service.js +2 -3
  52. package/dist/harness/collaboration/delegation/wiring.js +6 -5
  53. package/dist/harness/collaboration/orchestration/reflector/llm-reflector.d.ts +1 -1
  54. package/dist/harness/collaboration/orchestration/reflector/llm-reflector.js +1 -1
  55. package/dist/harness/context/capabilities/compact/engine.d.ts +30 -0
  56. package/dist/harness/context/capabilities/compact/engine.js +198 -46
  57. package/dist/harness/context/capabilities/compact/handover.d.ts +78 -0
  58. package/dist/harness/context/capabilities/compact/handover.js +107 -0
  59. package/dist/harness/context/capabilities/compact/index.d.ts +3 -1
  60. package/dist/harness/context/capabilities/compact/index.js +2 -1
  61. package/dist/harness/context/capabilities/compact/types.d.ts +30 -1
  62. package/dist/harness/context/capabilities/summary/executor.js +2 -1
  63. package/dist/harness/context/capabilities/summary/policies.js +8 -5
  64. package/dist/harness/context/constitution/default-agents.md +11 -10
  65. package/dist/harness/context/default-context-engine.d.ts +34 -4
  66. package/dist/harness/context/default-context-engine.js +194 -49
  67. package/dist/harness/context/hybrid-compressor.js +6 -0
  68. package/dist/harness/context/llm-summarizer.d.ts +2 -8
  69. package/dist/harness/context/llm-summarizer.js +69 -91
  70. package/dist/harness/context/message-selector.js +4 -3
  71. package/dist/harness/context/summarize.d.ts +2 -0
  72. package/dist/harness/context/summarize.js +7 -2
  73. package/dist/harness/context/truncate-compressor.js +7 -0
  74. package/dist/harness/context/turn-envelope.d.ts +3 -2
  75. package/dist/harness/context/turn-envelope.js +3 -2
  76. package/dist/harness/context/types.d.ts +33 -1
  77. package/dist/harness/extension/execution-environment/dangerous-commands.d.ts +28 -0
  78. package/dist/harness/extension/execution-environment/dangerous-commands.js +129 -0
  79. package/dist/harness/extension/execution-environment/effect-policy.d.ts +127 -8
  80. package/dist/harness/extension/execution-environment/effect-policy.js +244 -19
  81. package/dist/harness/extension/execution-environment/index.d.ts +4 -2
  82. package/dist/harness/extension/execution-environment/index.js +2 -1
  83. package/dist/harness/extension/execution-environment/kill-switch.d.ts +34 -0
  84. package/dist/harness/extension/execution-environment/kill-switch.js +46 -0
  85. package/dist/harness/extension/execution-environment/ops-audit.d.ts +200 -0
  86. package/dist/harness/extension/execution-environment/ops-audit.js +338 -0
  87. package/dist/harness/extension/execution-environment/privileged-exec.d.ts +158 -0
  88. package/dist/harness/extension/execution-environment/privileged-exec.js +418 -0
  89. package/dist/harness/extension/execution-environment/process-info.d.ts +180 -0
  90. package/dist/harness/extension/execution-environment/process-info.js +466 -0
  91. package/dist/harness/extension/execution-environment/process-isolation.d.ts +7 -0
  92. package/dist/harness/extension/execution-environment/process-isolation.js +9 -0
  93. package/dist/harness/extension/execution-environment/sandbox.d.ts +109 -0
  94. package/dist/harness/extension/execution-environment/sandbox.js +228 -21
  95. package/dist/harness/extension/execution-environment/tool-capabilities.d.ts +1 -1
  96. package/dist/harness/extension/execution-environment/tool-capabilities.js +6 -0
  97. package/dist/harness/extension/execution-environment/types.d.ts +19 -0
  98. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +5 -0
  99. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.js +33 -0
  100. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +4 -5
  101. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +5 -15
  102. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +3 -0
  103. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +53 -2
  104. package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +2 -0
  105. package/dist/harness/extension/plugin-ecosystem/tools/index.js +2 -0
  106. package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.d.ts +43 -0
  107. package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.js +350 -0
  108. package/dist/harness/extension/plugin-ecosystem/tools/process-tools.d.ts +30 -0
  109. package/dist/harness/extension/plugin-ecosystem/tools/process-tools.js +137 -0
  110. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +54 -4
  111. package/dist/harness/governance/human-in-the-loop/decision-cache.js +42 -16
  112. package/dist/harness/governance/security/temp-path.d.ts +9 -0
  113. package/dist/harness/governance/security/temp-path.js +13 -2
  114. package/dist/harness/governance/session-acl/seed-roles.js +14 -0
  115. package/dist/harness/index.d.ts +2 -0
  116. package/dist/harness/index.js +2 -0
  117. package/dist/harness/knowledge/fts.js +1 -2
  118. package/dist/harness/knowledge/index-store.js +59 -9
  119. package/dist/harness/memory/sqlite/keyword-search.d.ts +1 -0
  120. package/dist/harness/memory/sqlite/keyword-search.js +4 -3
  121. package/dist/harness/observability/observer/hub.js +8 -0
  122. package/dist/harness/observability/observer/run-snapshot.js +1 -0
  123. package/dist/harness/observability/observer/types.d.ts +4 -0
  124. package/dist/harness/run/agent/agent.d.ts +7 -0
  125. package/dist/harness/run/agent/agent.js +23 -1
  126. package/dist/harness/run/reliability/fallback-provider.d.ts +117 -5
  127. package/dist/harness/run/reliability/fallback-provider.js +262 -22
  128. package/dist/harness/run/reliability/harness-events.d.ts +24 -1
  129. package/dist/harness/run/reliability/model-error-policy.d.ts +32 -0
  130. package/dist/harness/run/reliability/model-error-policy.js +42 -0
  131. package/dist/harness/run/reliability/provider-wrapper.js +29 -2
  132. package/dist/harness/run/reliability/refusal-guard.d.ts +20 -0
  133. package/dist/harness/run/reliability/refusal-guard.js +102 -0
  134. package/dist/harness/run/reliability/run-agent.js +231 -33
  135. package/dist/harness/run/run-guard/default-run-guard.js +1 -1
  136. package/dist/harness/run/run-scope.d.ts +31 -0
  137. package/dist/harness/run/runner.d.ts +116 -2
  138. package/dist/harness/run/runner.js +547 -41
  139. package/dist/harness/session/attachments/llm-intent.js +2 -1
  140. package/dist/harness/session/tasks/render.d.ts +4 -1
  141. package/dist/harness/session/tasks/render.js +10 -7
  142. package/dist/harness/shared/events/agent-event-map.d.ts +66 -0
  143. package/dist/harness/shared/events/agent-event-map.js +5 -0
  144. package/dist/index.d.ts +3 -3
  145. package/dist/index.js +2 -2
  146. package/dist/integration/agent-runtime/channel-message-source.js +19 -1
  147. package/dist/integration/index.d.ts +2 -0
  148. package/dist/integration/index.js +1 -0
  149. package/dist/integration/observability/loop-watchdog.d.ts +56 -0
  150. package/dist/integration/observability/loop-watchdog.js +177 -0
  151. package/dist/integration/observability/metrics.d.ts +3 -0
  152. package/dist/integration/observability/metrics.js +18 -7
  153. package/dist/integration/providers/anthropic.d.ts +23 -0
  154. package/dist/integration/providers/anthropic.js +97 -12
  155. package/dist/integration/providers/fetch-timeout.d.ts +42 -0
  156. package/dist/integration/providers/fetch-timeout.js +51 -0
  157. package/dist/integration/providers/openai.d.ts +10 -0
  158. package/dist/integration/providers/openai.js +58 -11
  159. package/dist/integration/providers/provider-diagnostics.d.ts +80 -0
  160. package/dist/integration/providers/provider-diagnostics.js +89 -0
  161. package/dist/integration/providers/timeout-coherence.d.ts +52 -0
  162. package/dist/integration/providers/timeout-coherence.js +68 -0
  163. package/dist/integration/providers/wire-dump.d.ts +62 -0
  164. package/dist/integration/providers/wire-dump.js +111 -2
  165. package/dist/integration/storage/jsonl.js +4 -1
  166. package/dist/subsystems/cognition-steward/conceptualize/handler.js +1 -1
  167. package/dist/subsystems/memory-steward/backfill/handler.js +1 -1
  168. package/dist/subsystems/wisdom-steward/formation/handler.js +1 -1
  169. package/package.json +3 -2
@@ -6,6 +6,7 @@
6
6
  */
7
7
  import type { HitlDecision } from '@octopi-agent/core/types/tools.js';
8
8
  import type { ToolIsolationMode } from './isolation.js';
9
+ import type { EscalationPolicy, EscalationRule } from './privileged-exec.js';
9
10
  import { type ProcessIsolationProfile } from './process-isolation.js';
10
11
  /** 命名运行模式 */
11
12
  export type EffectRunMode = 'workspace' | 'project' | 'host' | 'untrusted';
@@ -24,7 +25,11 @@ export type ShellEscapePolicy = 'deny' | 'confirm' | 'allow';
24
25
  export type EffectCommitPolicy = 'auto' | 'manual';
25
26
  /** 效应确认通道 */
26
27
  /** 效应意图(host-gate confirmEffect 入参) */
27
- export type EffectIntent = {
28
+ export type EffectIntent = EffectIntentPayload & {
29
+ /** 引擎侧确认窗(毫秒):宿主卡片生命周期须严格晚于它结束(见 core confirmEffect 契约) */
30
+ timeoutMs?: number;
31
+ };
32
+ type EffectIntentPayload = {
28
33
  kind: 'file.write';
29
34
  path: string;
30
35
  mode: 'create' | 'overwrite' | 'append' | 'edit';
@@ -66,6 +71,28 @@ export type EffectConfirmChannel = 'engine' | 'host-gate';
66
71
  export type ShellJournalMode = 'snapshot' | 'off';
67
72
  /** How to admit `untrusted` when L4 process jail is missing */
68
73
  export type UntrustedAdmission = 'refuse' | 'degrade';
74
+ /**
75
+ * 进程牢笼意图(ops P0,`arch/ops-privileged-mode.md` §4):
76
+ * `auto` = 按模式派生(缺笼如实降级)| `require` = 拿不到即拒 | `none` = 显式无笼(需 privilegedAck)。
77
+ * 「主动选择无约束」与「被动失去约束」必须可区分——授权 ≠ 降级。
78
+ */
79
+ export type JailIntent = 'auto' | 'require' | 'none';
80
+ /** jail 意图落空时的行为:`refuse` 拒绝执行 | `degrade` 记 securityDegraded + 告警(禁止静默) */
81
+ export type OnJailUnavailable = 'refuse' | 'degrade';
82
+ export type { EscalationPolicy, EscalationRule };
83
+ /** run 开始即记录的 jail 状态(意图 × 实测后端)——「授权」与「故障」的事后判据 */
84
+ export interface OpsJailState {
85
+ /** 配置意图 */
86
+ intent: JailIntent;
87
+ /** 实测 ProcessIsolationProfile.backend */
88
+ backend: import('./process-isolation.js').IsolationBackend | 'unknown';
89
+ /** L4 最小判据是否成立(intent=none 时仅作事实上报) */
90
+ jailAvailable: boolean;
91
+ /** true = 授权态(显式 none / 笼按意图就位);false = 故障或缺失(降级路径) */
92
+ authorized: boolean;
93
+ /** 本 run 的 securityDegraded 代码 */
94
+ degraded: string[];
95
+ }
69
96
  /** Effective tool surface after isolation admission */
70
97
  export type ToolSurface = 'full' | 'reduced';
71
98
  /** Machine-readable degradations (never silent) */
@@ -111,6 +138,39 @@ export interface EffectPolicyConfig {
111
138
  maxBytes?: number;
112
139
  maxFileSize?: number;
113
140
  };
141
+ /** 进程牢笼意图;缺省 `auto`(按模式派生,缺笼如实降级 + 告警) */
142
+ jail?: JailIntent;
143
+ /** jail≠none 且笼不可用时:`refuse` 拒绝执行 | `degrade`(缺省)记 securityDegraded + 告警 */
144
+ onJailUnavailable?: OnJailUnavailable;
145
+ /** `jail: "none"` 时必填的显式表态(缺省拒绝启动;§8.1 二级确认)。root/elevated
146
+ * 部署同样要求此声明(§5 P4 root 部署语义,启动期断言)。 */
147
+ privilegedAck?: string;
148
+ /** 提权策略(§4/§5 P3/P4):`allowlist` 按 cmd+args 全等放行;`full` 全量档
149
+ * (需 `jail: "none"` + `privilegedAck` + `mode: "host"`);缺省 `none` */
150
+ escalation?: {
151
+ policy?: 'none' | 'allowlist' | 'full';
152
+ via?: 'sudo' | 'direct';
153
+ allow?: EscalationRule[];
154
+ };
155
+ /**
156
+ * 危险命令确认(§6:减速带而非安全边界):命中保守分类表的 argv 要求确认。
157
+ * `policy`:`confirm`(缺省,走 HitlDecision)| `deny`(直接拒绝)| `off`(关闭分类)。
158
+ * `timeoutMs`:确认超时(超时一律 deny,不可配 outcome);缺省 120000。
159
+ */
160
+ dangerousCommands?: {
161
+ policy?: 'confirm' | 'deny' | 'off';
162
+ timeoutMs?: number;
163
+ };
164
+ /** ops 审计账本开关(安全字段:重启生效 + 宿主署名,§4.3);缺省 `on` */
165
+ opsAudit?: 'on' | 'off';
166
+ /** ops 审计账本路径(缺省 `<OCTOPI_HOME>/audit/ops.<agentId>.jsonl`) */
167
+ opsAuditPath?: string;
168
+ /**
169
+ * 审计外送收口路径(P5 唯一不可抵赖档,原则 8);缺省不外送。
170
+ * **必须放在 agent 可写面之外**(`~/.octopi` 在 host 模式可写面内——放那里等于没外送)。
171
+ * 每条账目以信封(count=seq + tailHash 锚点 + entry 原样)append-only 外送,宿主可重验链。
172
+ */
173
+ opsAuditExportPath?: string;
114
174
  }
115
175
  /** 展开后的有效策略 */
116
176
  export interface EffectiveEffectPolicy {
@@ -149,17 +209,64 @@ export interface EffectiveEffectPolicy {
149
209
  maxBytes?: number;
150
210
  maxFileSize?: number;
151
211
  };
212
+ /** 进程牢笼意图(auto/require/none) */
213
+ jail: JailIntent;
214
+ /** jail 意图落空时的行为(refuse/degrade) */
215
+ onJailUnavailable: OnJailUnavailable;
216
+ /** 提权策略(ops P3/P4,resolved) */
217
+ escalation: EscalationPolicy;
218
+ /**
219
+ * 特权部署标记(§5 P4 / §8.1):`jail: "none"`(授权无笼)或 `escalation.policy: "full"`
220
+ * (全量提权)即为特权上下文。root/elevated 进程维度由启动期探测叠加(UI 常驻
221
+ * `PRIVILEGED` 标记的数据源)。**授权态 ≠ 降级**:此标记不进 securityDegraded。
222
+ */
223
+ privileged: boolean;
224
+ /** 危险命令减速带(§6)resolved:分类策略 + 确认超时(超时一律 deny) */
225
+ dangerousCommands: {
226
+ policy: 'confirm' | 'deny' | 'off';
227
+ timeoutMs: number;
228
+ };
229
+ /** ops 审计账本开关(ops P2) */
230
+ opsAudit: 'on' | 'off';
231
+ /** ops 审计账本路径覆盖 */
232
+ opsAuditPath?: string;
233
+ /** 审计外送收口路径(P5;缺省不外送) */
234
+ opsAuditExportPath?: string;
152
235
  }
153
236
  /**
154
- * Whether the resolved policy demands a process jail (untrusted that survived
155
- * untrusted admission). Single predicate shared by the run path (runner) and
156
- * host-side read surfaces (WebUI git status endpoint) so the isolation level
157
- * never drifts between them.
237
+ * Whether the resolved policy demands a process jail — fail-closed when the
238
+ * jail cannot be applied (ops P0: `jail: require`, `onJailUnavailable: refuse`,
239
+ * or untrusted that survived untrusted admission). Single predicate shared by
240
+ * the run path (runner) and host-side read surfaces (WebUI git status endpoint)
241
+ * so the isolation level never drifts between them.
158
242
  *
159
243
  * @param eff - resolved effective policy
160
- * @returns true when untrusted was requested and remains effective
244
+ * @returns true when a missing/broken jail must refuse execution
161
245
  */
162
246
  export declare function requiresJail(eff: EffectiveEffectPolicy): boolean;
247
+ /**
248
+ * 白名单提权全等匹配(§5 P3):`cmd` 绝对路径比对 + `args` 逐项全等。
249
+ * 不做前缀/正则/插值——任何「宽松匹配」都会把 allowlist 变成任意命令通道。
250
+ *
251
+ * @param escalation - resolved 提权策略
252
+ * @param cmd - 请求的可执行文件(必须与规则逐字相同)
253
+ * @param args - 请求的 argv 尾部
254
+ * @returns 命中的规则与稳定 ruleId;未命中 null
255
+ */
256
+ export declare function matchEscalationRule(escalation: EscalationPolicy, cmd: string, args: readonly string[]): {
257
+ rule: EscalationRule;
258
+ ruleId: string;
259
+ } | null;
260
+ /**
261
+ * 构造 run 开始即记录的 `ops.jail.state`(意图 × 实测后端)。
262
+ * 「主动选择无约束」(authorized, intent=none)与「被动失去约束」
263
+ * (authorized=false, 缺笼降级)事后可分辨即靠这条记录。
264
+ *
265
+ * @param eff - 解析后的有效策略
266
+ * @param isolation - probe 到的隔离画像(缺省按「无笼」)
267
+ * @returns jail 状态记录
268
+ */
269
+ export declare function buildOpsJailState(eff: EffectiveEffectPolicy, isolation?: ProcessIsolationProfile): OpsJailState;
163
270
  /**
164
271
  * 展开 effectPolicy 为有效策略
165
272
  *
@@ -200,12 +307,24 @@ export declare function isToolAllowedOnSurface(toolName: string, surface: ToolSu
200
307
  * @returns 是否允许
201
308
  */
202
309
  export declare function isPathAllowed(resolved: string, allowRoots: string[], containment: PathContainment): boolean;
310
+ /** 闸门放行结论(ops P2:审计要「是否经确认」的事实,不是通道配置) */
311
+ export interface GateEffectResult {
312
+ /** 是否经宿主确认(自动放行 = false;未过闸 = 不返回本值而是 throw) */
313
+ confirmed: boolean;
314
+ /** 放行来源:确认过 / 事务自动 / engine 内置策略 */
315
+ confirmSource: 'host-gate' | 'auto-transaction' | 'auto-engine';
316
+ /** ops P5 确认人署名(仅 host-gate 经人工批准时;缓存命中/自动放行如实缺省) */
317
+ confirmedBy?: string;
318
+ /** ops P5 确认通道(gateway | webhook | …) */
319
+ confirmChannel?: string;
320
+ }
203
321
  /**
204
322
  * 效应闸(P4):事务内自动放行;host-gate 交给宿主;engine 通道按内置策略。
205
323
  *
206
324
  * @param intent - 效应意图
207
325
  * @param options - 通道与回调
208
- * @throws Error 当拒绝执行时
326
+ * @returns 放行结论(confirmed/confirmSource + 确认人归因,审计用)
327
+ * @throws Error 当拒绝执行时(`effect_confirm_timeout` 超时 / `effect_denied` 拒绝,语义分家)
209
328
  */
210
329
  export declare function gateEffect(intent: EffectIntent, options: {
211
330
  effects: EffectConfirmChannel;
@@ -216,7 +335,7 @@ export declare function gateEffect(intent: EffectIntent, options: {
216
335
  /** SEC-7:always-scope 缓存键(agent 分桶);缺省尝试 RunScope */
217
336
  agentId?: string;
218
337
  hitlCache?: import('../../governance/human-in-the-loop/decision-cache.js').HitlDecisionCache;
219
- }): Promise<void>;
338
+ }): Promise<GateEffectResult>;
220
339
  /**
221
340
  * Session-only effect overrides. Append-only: may add allow roots for this
222
341
  * session; must never loosen pathContainment / shellEscape.
@@ -6,9 +6,10 @@
6
6
  */
7
7
  import { isAbsolute, resolve } from 'node:path';
8
8
  import { expandHomePath } from '../../../paths.js';
9
+ import { checkEscalationBinary, escalationRuleTargets, escalationWritableRoots, } from './privileged-exec.js';
9
10
  import { deniesReducedSurface, resolveToolCapabilities, } from './tool-capabilities.js';
10
11
  import { assessL4ProcessMinimum, } from './process-isolation.js';
11
- import { resolveHitlDecision } from '../../governance/human-in-the-loop/decision-cache.js';
12
+ import { resolveHitlOutcome } from '../../governance/human-in-the-loop/decision-cache.js';
12
13
  import { getRunSessionId, getRunScope } from '../../run/run-scope.js';
13
14
  /**
14
15
  * Engine default when `effectPolicy.mode` is omitted (secure-by-default).
@@ -70,17 +71,68 @@ const MODE_DEFAULTS = {
70
71
  },
71
72
  };
72
73
  /**
73
- * Whether the resolved policy demands a process jail (untrusted that survived
74
- * untrusted admission). Single predicate shared by the run path (runner) and
75
- * host-side read surfaces (WebUI git status endpoint) so the isolation level
76
- * never drifts between them.
74
+ * Whether the resolved policy demands a process jail — fail-closed when the
75
+ * jail cannot be applied (ops P0: `jail: require`, `onJailUnavailable: refuse`,
76
+ * or untrusted that survived untrusted admission). Single predicate shared by
77
+ * the run path (runner) and host-side read surfaces (WebUI git status endpoint)
78
+ * so the isolation level never drifts between them.
77
79
  *
78
80
  * @param eff - resolved effective policy
79
- * @returns true when untrusted was requested and remains effective
81
+ * @returns true when a missing/broken jail must refuse execution
80
82
  */
81
83
  export function requiresJail(eff) {
84
+ // jail=none 是授权无笼:onJailUnavailable 对它无意义,不得误报「要求笼」
85
+ if (eff.jail === 'none')
86
+ return false;
87
+ if (eff.jail === 'require' || eff.onJailUnavailable === 'refuse')
88
+ return true;
82
89
  return eff.requestedMode === 'untrusted' && eff.mode === 'untrusted';
83
90
  }
91
+ /**
92
+ * 白名单提权全等匹配(§5 P3):`cmd` 绝对路径比对 + `args` 逐项全等。
93
+ * 不做前缀/正则/插值——任何「宽松匹配」都会把 allowlist 变成任意命令通道。
94
+ *
95
+ * @param escalation - resolved 提权策略
96
+ * @param cmd - 请求的可执行文件(必须与规则逐字相同)
97
+ * @param args - 请求的 argv 尾部
98
+ * @returns 命中的规则与稳定 ruleId;未命中 null
99
+ */
100
+ export function matchEscalationRule(escalation, cmd, args) {
101
+ if (escalation.policy !== 'allowlist')
102
+ return null;
103
+ for (let i = 0; i < escalation.allow.length; i += 1) {
104
+ const rule = escalation.allow[i];
105
+ const ruleArgs = rule.args ?? [];
106
+ if (rule.cmd === cmd &&
107
+ ruleArgs.length === args.length &&
108
+ ruleArgs.every((a, idx) => a === args[idx])) {
109
+ // 显式 id 优先(下标 id 在规则重排后会断裂审计关联)
110
+ return { rule, ruleId: rule.id ?? `allow[${i}]` };
111
+ }
112
+ }
113
+ return null;
114
+ }
115
+ /**
116
+ * 构造 run 开始即记录的 `ops.jail.state`(意图 × 实测后端)。
117
+ * 「主动选择无约束」(authorized, intent=none)与「被动失去约束」
118
+ * (authorized=false, 缺笼降级)事后可分辨即靠这条记录。
119
+ *
120
+ * @param eff - 解析后的有效策略
121
+ * @param isolation - probe 到的隔离画像(缺省按「无笼」)
122
+ * @returns jail 状态记录
123
+ */
124
+ export function buildOpsJailState(eff, isolation) {
125
+ const l4 = isolation ? assessL4ProcessMinimum(isolation) : { ok: false };
126
+ const jailAvailable = l4.ok;
127
+ return {
128
+ intent: eff.jail,
129
+ backend: isolation?.backend ?? 'unknown',
130
+ jailAvailable,
131
+ // none = 授权无笼;其余意图下只有笼按意图就位才是授权态
132
+ authorized: eff.jail === 'none' || jailAvailable,
133
+ degraded: [...eff.securityDegraded],
134
+ };
135
+ }
84
136
  /**
85
137
  * 展开 effectPolicy 为有效策略
86
138
  *
@@ -116,6 +168,47 @@ export function resolveEffectiveEffectPolicy(config, baseWorkspace, isolation) {
116
168
  baseWorkspace !== undefined ? expandHomePath(baseWorkspace.trim()) : baseWorkspace;
117
169
  const requestedMode = config.mode ?? DEFAULT_EFFECT_RUN_MODE;
118
170
  const untrustedAdmission = config.untrustedAdmission ?? 'refuse';
171
+ // ops P0:jail 意图先解析;**纯配置矛盾 fail-closed 先于任何探测分支**——
172
+ // 矛盾是配置事实,不该被「先撞上缺笼」抢先抛成另一种错误
173
+ const jail = config.jail ?? 'auto';
174
+ const onJailUnavailable = config.onJailUnavailable ?? 'degrade';
175
+ // ops P4 §4.1:full 档纯配置矛盾——同上原则,先于任何探测分支(矛盾是配置事实,
176
+ // 不该被「先撞上缺笼/缺 ack」抢先抛成另一种错误)
177
+ if (config.escalation?.policy === 'full') {
178
+ if (requestedMode !== 'host') {
179
+ throw new Error('effect_policy_invalid: escalation.policy=full requires mode=host (explicitly designated machine)');
180
+ }
181
+ if (jail !== 'none') {
182
+ throw new Error('effect_policy_invalid: escalation.policy=full requires jail=none (whole-shell freedom contradicts a jailed shell)');
183
+ }
184
+ if (!config.privilegedAck?.trim()) {
185
+ throw new Error('effect_policy_invalid: escalation.policy=full requires effectPolicy.privilegedAck (explicit privileged declaration)');
186
+ }
187
+ if ((config.escalation.allow ?? []).length > 0) {
188
+ // 死键 fail-loud:full 档没有 allowlist 面,静默忽略会误导配置读者
189
+ throw new Error('effect_policy_invalid: escalation.policy=full takes no escalation.allow rules (remove them, or use policy=allowlist)');
190
+ }
191
+ }
192
+ if (jail === 'none') {
193
+ if (requestedMode === 'untrusted') {
194
+ throw new Error('effect_policy_invalid: jail=none cannot combine with mode=untrusted (untrusted promises a jail)');
195
+ }
196
+ if (!config.privilegedAck?.trim()) {
197
+ throw new Error('effect_policy_invalid: jail=none requires effectPolicy.privilegedAck (explicit unjailed choice)');
198
+ }
199
+ if (onJailUnavailable === 'refuse') {
200
+ // 死键 fail-loud:none 下该旋钮无指代,静默忽略会误导配置读者
201
+ throw new Error('effect_policy_invalid: onJailUnavailable=refuse has no meaning under jail=none (remove it, or use jail=auto/require)');
202
+ }
203
+ if (config.network === 'deny' || config.network === 'allowlist') {
204
+ // 网络限制只由 jail 实施:无笼时 deny/allowlist 是无法兑现的承诺,拒绝作假
205
+ throw new Error('effect_policy_invalid: network=deny/allowlist cannot be enforced under jail=none (network is jail-implemented only)');
206
+ }
207
+ // 授权无笼:不为 jail 记 securityDegraded(这是授权,不是降级)
208
+ }
209
+ else if ((jail === 'require' || onJailUnavailable === 'refuse') && untrustedAdmission === 'degrade') {
210
+ throw new Error('effect_policy_invalid: jail=require/onJailUnavailable=refuse contradicts untrustedAdmission=degrade (same condition, opposite outcomes)');
211
+ }
119
212
  let mode = requestedMode;
120
213
  let toolSurface = 'full';
121
214
  const securityDegraded = [];
@@ -123,6 +216,13 @@ export function resolveEffectiveEffectPolicy(config, baseWorkspace, isolation) {
123
216
  const profile = isolation;
124
217
  const l4 = profile ? assessL4ProcessMinimum(profile) : { ok: false, missing: ['processTree'] };
125
218
  if (!l4.ok) {
219
+ if (config.jail === 'require' || config.onJailUnavailable === 'refuse') {
220
+ // jail 意图 fail-closed 优先且错误码/建议指向 jail 旋钮(untrustedAdmission=degrade
221
+ // 与该组合矛盾,配置校验已拒,不能在这里推荐它)
222
+ throw new Error(`jail_required_unavailable: effectPolicy.jail=${config.jail ?? 'auto'} ` +
223
+ `(onJailUnavailable=${config.onJailUnavailable ?? 'degrade'}) but no process jail ` +
224
+ `(missing: ${l4.missing.join(', ')}). Install bwrap/sandbox-exec, or set jail=none with privilegedAck.`);
225
+ }
126
226
  if (untrustedAdmission === 'refuse') {
127
227
  throw new Error(`untrusted_refused: L4 process jail unavailable (missing: ${l4.missing.join(', ')}). ` +
128
228
  `Install bwrap/sandbox-exec or set effectPolicy.untrustedAdmission=degrade.`);
@@ -145,6 +245,62 @@ export function resolveEffectiveEffectPolicy(config, baseWorkspace, isolation) {
145
245
  securityDegraded.push('network_open');
146
246
  }
147
247
  }
248
+ // ops P0:jail 可用性申报(纯配置矛盾已在上方先拒)。授权(none)≠ 降级(缺笼)。
249
+ if (jail !== 'none') {
250
+ const l4 = isolation
251
+ ? assessL4ProcessMinimum(isolation)
252
+ : { ok: false, missing: ['processTree'] };
253
+ if (!l4.ok) {
254
+ if (jail === 'require' || onJailUnavailable === 'refuse') {
255
+ throw new Error(`jail_required_unavailable: effectPolicy.jail=${jail} (onJailUnavailable=${onJailUnavailable}) ` +
256
+ `but no process jail (missing: ${l4.missing.join(', ')}). ` +
257
+ `Install bwrap/sandbox-exec, or set jail=none with privilegedAck.`);
258
+ }
259
+ // degrade:run 级如实申报(untrusted 降级路径可能已记,去重)
260
+ if (!securityDegraded.includes('no_process_jail'))
261
+ securityDegraded.push('no_process_jail');
262
+ }
263
+ }
264
+ // ops P3:提权策略(§4.1)。纯配置矛盾 fail-closed;allowlist 二进制 TOCTOU 护栏
265
+ // 同步兜底(库路径无 daemon 启动探测时也不能放行可换二进制)。
266
+ const escalation = {
267
+ policy: config.escalation?.policy ?? 'none',
268
+ via: config.escalation?.via ?? 'sudo',
269
+ allow: config.escalation?.allow ?? [],
270
+ };
271
+ if (escalation.policy !== 'none') {
272
+ if (requestedMode === 'untrusted') {
273
+ // untrusted 的产品承诺就是笼;「越笼」提权通道与之矛盾(§4.1 同类拒绝)
274
+ throw new Error('effect_policy_invalid: escalation cannot combine with mode=untrusted (untrusted promises a jail)');
275
+ }
276
+ }
277
+ // (full 档纯配置矛盾已在最前 fail-closed,此处只剩 allowlist 的 TOCTOU 护栏)
278
+ if (escalation.policy === 'allowlist') {
279
+ if (escalation.allow.length === 0) {
280
+ throw new Error('effect_policy_invalid: escalation.policy=allowlist requires escalation.allow rules');
281
+ }
282
+ // 可写根统一口径(与 daemon 启动探测共用 escalationWritableRoots,防两处漂移)
283
+ const writableRoots = escalationWritableRoots({
284
+ workspaces: baseWorkspace !== undefined ? [baseWorkspace] : [],
285
+ transactionRoots: (config.transactionRoots ?? []).map((r) => expandHomePath(r)),
286
+ });
287
+ for (const rule of escalation.allow) {
288
+ if (!isAbsolute(rule.cmd)) {
289
+ throw new Error(`effect_policy_invalid: escalation rule cmd must be absolute, got ${JSON.stringify(rule.cmd)}`);
290
+ }
291
+ // 有效目标逐个过 TOCTOU 护栏(via: sudo 形态含 sudo 之后的真实二进制)
292
+ const targets = escalationRuleTargets(rule, escalation.via);
293
+ if ('invalid' in targets) {
294
+ throw new Error(`effect_policy_invalid: escalation rule rejected (${targets.invalid})`);
295
+ }
296
+ for (const target of targets.targets) {
297
+ const bad = checkEscalationBinary(target, writableRoots);
298
+ if (bad) {
299
+ throw new Error(`effect_policy_invalid: escalation rule rejected (${bad})`);
300
+ }
301
+ }
302
+ }
303
+ }
148
304
  // Path jail is part of the untrusted promise; never loosen it from config.
149
305
  const d = MODE_DEFAULTS[mode];
150
306
  const pathContainment = requestedMode === 'untrusted'
@@ -166,9 +322,13 @@ export function resolveEffectiveEffectPolicy(config, baseWorkspace, isolation) {
166
322
  // degraded untrusted must not leave shell allow as a hole
167
323
  shellEscape: toolSurface === 'reduced' ? 'deny' : (config.shellEscape ?? d.shellEscape),
168
324
  // untrusted product promise: egress deny is not a config knob (like pathContainment)
325
+ // jail=none:网络限制只由 jail 实施,无笼时 deny 是假承诺——显式配置已在上方拒绝,
326
+ // 未指定则如实取 open(§4.2 注记带 network=open)
169
327
  network: requestedMode === 'untrusted' || toolSurface === 'reduced'
170
328
  ? 'deny'
171
- : (config.network ?? d.network),
329
+ : jail === 'none'
330
+ ? 'open'
331
+ : (config.network ?? d.network),
172
332
  processLimits: config.processLimits ?? d.processLimits,
173
333
  commit: config.commit ?? d.commit,
174
334
  onClose,
@@ -182,6 +342,18 @@ export function resolveEffectiveEffectPolicy(config, baseWorkspace, isolation) {
182
342
  undoLimit: config.undoLimit,
183
343
  shellJournal: config.shellJournal ?? 'snapshot',
184
344
  shellJournalLimit: config.shellJournalLimit,
345
+ jail,
346
+ onJailUnavailable,
347
+ escalation,
348
+ // 特权上下文(§5 P4/§8.1):授权态标记,不是降级;root/elevated 维度由启动期探测叠加
349
+ privileged: jail === 'none' || escalation.policy === 'full',
350
+ dangerousCommands: {
351
+ policy: config.dangerousCommands?.policy ?? 'confirm',
352
+ timeoutMs: config.dangerousCommands?.timeoutMs ?? 120_000,
353
+ },
354
+ opsAudit: config.opsAudit ?? 'on',
355
+ opsAuditPath: config.opsAuditPath,
356
+ opsAuditExportPath: config.opsAuditExportPath,
185
357
  };
186
358
  }
187
359
  /**
@@ -222,19 +394,39 @@ export function isPathAllowed(resolved, allowRoots, containment) {
222
394
  return target === r || target.startsWith(r + '/');
223
395
  });
224
396
  }
397
+ /** 效应确认缓存 key(含目标):一次点头只覆盖同一目标,不按 kind 一类放行 */
398
+ function effectCacheKey(intent) {
399
+ switch (intent.kind) {
400
+ case 'file.write':
401
+ return `file.write:${intent.path}`;
402
+ case 'shell':
403
+ return `shell:${intent.command}`;
404
+ case 'runner':
405
+ return `runner:${intent.command}`;
406
+ case 'vcs':
407
+ return `vcs:${intent.operation}:${intent.cwd ?? ''}`;
408
+ case 'memory.write':
409
+ return `memory.write:${intent.domain}`;
410
+ case 'other':
411
+ return `other:${intent.description}`;
412
+ }
413
+ }
225
414
  /**
226
415
  * 效应闸(P4):事务内自动放行;host-gate 交给宿主;engine 通道按内置策略。
227
416
  *
228
417
  * @param intent - 效应意图
229
418
  * @param options - 通道与回调
230
- * @throws Error 当拒绝执行时
419
+ * @returns 放行结论(confirmed/confirmSource + 确认人归因,审计用)
420
+ * @throws Error 当拒绝执行时(`effect_confirm_timeout` 超时 / `effect_denied` 拒绝,语义分家)
231
421
  */
232
422
  export async function gateEffect(intent, options) {
233
423
  // 可事务化(可 undo)→ 自动
234
- if (intent.kind === 'memory.write' && intent.transactional)
235
- return;
236
- if (intent.kind === 'file.write' && intent.transactional)
237
- return;
424
+ if (intent.kind === 'memory.write' && intent.transactional) {
425
+ return { confirmed: false, confirmSource: 'auto-transaction' };
426
+ }
427
+ if (intent.kind === 'file.write' && intent.transactional) {
428
+ return { confirmed: false, confirmSource: 'auto-transaction' };
429
+ }
238
430
  if (intent.kind === 'shell') {
239
431
  const esc = options.shellEscape ?? 'allow';
240
432
  // deny:无 L4 无法只禁越界,必须拒绝 shell(fail-closed,保策略语义)
@@ -250,25 +442,58 @@ export async function gateEffect(intent, options) {
250
442
  // shellEscape gates the shell tool only — workspace stays capable of git/project scripts.
251
443
  if (options.effects !== 'host-gate') {
252
444
  // engine 通道:路径牢笼由 L2 承担;shell 已在上方按 shellEscape 处理
253
- return;
445
+ return { confirmed: false, confirmSource: 'auto-engine' };
254
446
  }
255
447
  // host-gate:非事务效应交给宿主(自动放行 / 宿主 UI / 策略引擎)
256
448
  const decide = options.confirmEffect;
257
449
  if (!decide) {
258
450
  throw new Error('confirm_effect_missing: effectPolicy.effects=host-gate requires confirmEffect callback');
259
451
  }
260
- // SEC-7:HitlDecision + 引擎缓存;失败路径 fail-closed
261
- const allowed = await resolveHitlDecision({
452
+ // SEC-7:HitlDecision + 引擎缓存;失败路径 fail-closed。
453
+ // 缓存 key 含目标(B(c) 拍板 2026-10-26):一次 approve_session 只覆盖同一目标,
454
+ // 不再按 kind 一类放行(旧「有意粗粒度」已翻案,见 KNOWN-ISSUES)
455
+ const outcome = await resolveHitlOutcome({
262
456
  cache: options.hitlCache,
263
457
  channel: 'effect',
264
- key: intent.kind,
458
+ key: effectCacheKey(intent),
265
459
  sessionId: options.sessionId ?? getRunSessionId(),
266
460
  agentId: options.agentId ?? getRunScope()?.agentId,
267
- ask: () => decide(intent),
461
+ // 宿主可返回裸 HitlDecision 或 ConfirmOutcome(带归因/来源);归因随结果回传审计
462
+ ask: async () => {
463
+ const raw = await decide(intent);
464
+ const normalized = typeof raw === 'string' ? { decision: raw } : raw;
465
+ return {
466
+ decision: normalized.decision,
467
+ ...(normalized.approver !== undefined ? { approver: normalized.approver } : {}),
468
+ ...(normalized.channel !== undefined ? { channel: normalized.channel } : {}),
469
+ // 宿主标注的拒绝来源:timeout 归超时语义;其余归通道故障——不得冒充人工拒绝
470
+ ...(normalized.decision === 'deny' && normalized.reason === 'timeout'
471
+ ? { timedOut: true }
472
+ : {}),
473
+ ...(normalized.decision === 'deny' &&
474
+ normalized.reason !== undefined &&
475
+ normalized.reason !== 'timeout'
476
+ ? { denyReason: 'channel_error', denyDetail: normalized.reason }
477
+ : {}),
478
+ };
479
+ },
268
480
  });
269
- if (!allowed) {
270
- throw new Error(`effect_denied: ${intent.kind}`);
481
+ if (!outcome.allowed) {
482
+ // 错误面分家(与审计 why 同一口径):超时 ≠ 人工拒绝 ≠ 通道故障,不得混为一谈
483
+ if (outcome.timedOut) {
484
+ throw new Error(`effect_confirm_timeout: no decision for ${effectCacheKey(intent)} — timeout is deny; do NOT retry this call until a human decides`);
485
+ }
486
+ const provenance = outcome.denyReason
487
+ ? ` (${outcome.denyReason}${outcome.denyDetail ? `: ${outcome.denyDetail}` : ''})`
488
+ : '';
489
+ throw new Error(`effect_denied: ${intent.kind}${provenance} — ${outcome.denyReason ? 'no human decision was reached' : 'a human rejected this effect'}`);
271
490
  }
491
+ return {
492
+ confirmed: true,
493
+ confirmSource: 'host-gate',
494
+ ...(outcome.approver !== undefined ? { confirmedBy: outcome.approver } : {}),
495
+ ...(outcome.channel !== undefined ? { confirmChannel: outcome.channel } : {}),
496
+ };
272
497
  }
273
498
  const EFFECT_OVERRIDES_META_KEY = 'effectOverrides';
274
499
  /**
@@ -7,6 +7,8 @@
7
7
  export { ProcessSandbox, createProcessSandbox, assessL4ProcessMinimum, supervisedSpawnProfile, } from './sandbox.js';
8
8
  export { probeProcessIsolation, scrubEnv, killProcessTree, L4_PROCESS_MINIMUM, } from './process-isolation.js';
9
9
  export type { ProcessIsolationProfile, IsolationBackend, ProcessTreeIsolation, FilesystemIsolation, ResourceIsolation, NetworkIsolation, PrivilegeIsolation, EnvHygiene, L4ProcessAssessment, } from './process-isolation.js';
10
+ export { listProcesses, getAncestorPidChain, resolveProcessImage, buildAncestorChain, selectProcesses, parsePsProcessTable, parseCpuTimeToMs, parseProcPidEntry, parsePowerShellProcessTable, firstExecutableFromLsof, } from './process-info.js';
11
+ export type { ProcessInfoEntry, ProcessListResult, ListProcessesOptions, SelectedProcesses, AncestorChain, TableParseResult, } from './process-info.js';
10
12
  export { FileWorkspace } from './workspace.js';
11
13
  export type { FileWorkspaceConfig } from './workspace.js';
12
14
  export { DEFAULT_TOOL_ISOLATION, resolveToolIsolationCwd, safeSessionDirSegment, looksLikeAbsoluteSessionPath, } from './isolation.js';
@@ -15,8 +17,8 @@ export { TurnFileUndoLog, commitSessionFileUndo, discardSessionFileUndo, resolve
15
17
  export type { SessionUndoPaths, FileUndoEntry, DiscardFileEffectsResult, DiscardConflictReason, } from './undo-log.js';
16
18
  export { isProbablyText, reverseAgentOverwrite, merge3Lines } from './undo-merge.js';
17
19
  export { snapshotShellRoots, captureShellInventory, diffShellInventory, journalShellDiff, writeNotReversed, } from './shell-journal.js';
18
- export { resolveEffectiveEffectPolicy, requiresJail, isPathAllowed, isToolAllowedOnSurface, gateEffect, DEFAULT_EFFECT_RUN_MODE, readSessionEffectOverrides, normalizeTransactionRoots, mergeTransactionRoots, SESSION_EFFECT_OVERRIDES_KEY, } from './effect-policy.js';
19
- export type { UntrustedAdmission, ToolSurface, SecurityDegradation, EffectiveEffectPolicy, SessionEffectOverrides, } from './effect-policy.js';
20
+ export { resolveEffectiveEffectPolicy, requiresJail, buildOpsJailState, isPathAllowed, isToolAllowedOnSurface, gateEffect, DEFAULT_EFFECT_RUN_MODE, readSessionEffectOverrides, normalizeTransactionRoots, mergeTransactionRoots, SESSION_EFFECT_OVERRIDES_KEY, } from './effect-policy.js';
21
+ export type { UntrustedAdmission, JailIntent, OnJailUnavailable, OpsJailState, ToolSurface, SecurityDegradation, EffectiveEffectPolicy, SessionEffectOverrides, } from './effect-policy.js';
20
22
  export { runWithToolLimits, resolveToolTimeoutMs, ToolTimeoutError, } from './resource-limits.js';
21
23
  export type { ToolRunLimits } from './resource-limits.js';
22
24
  export { TurnMemoryJournal, JournaledMemoryStore, createMemoryRestorer, discardMemoryUndo, } from './memory-undo.js';
@@ -6,12 +6,13 @@
6
6
  */
7
7
  export { ProcessSandbox, createProcessSandbox, assessL4ProcessMinimum, supervisedSpawnProfile, } from './sandbox.js';
8
8
  export { probeProcessIsolation, scrubEnv, killProcessTree, L4_PROCESS_MINIMUM, } from './process-isolation.js';
9
+ export { listProcesses, getAncestorPidChain, resolveProcessImage, buildAncestorChain, selectProcesses, parsePsProcessTable, parseCpuTimeToMs, parseProcPidEntry, parsePowerShellProcessTable, firstExecutableFromLsof, } from './process-info.js';
9
10
  export { FileWorkspace } from './workspace.js';
10
11
  export { DEFAULT_TOOL_ISOLATION, resolveToolIsolationCwd, safeSessionDirSegment, looksLikeAbsoluteSessionPath, } from './isolation.js';
11
12
  export { TurnFileUndoLog, commitSessionFileUndo, discardSessionFileUndo, resolveSessionUndoPaths, resolveSessionUndoOnClose, } from './undo-log.js';
12
13
  export { isProbablyText, reverseAgentOverwrite, merge3Lines } from './undo-merge.js';
13
14
  export { snapshotShellRoots, captureShellInventory, diffShellInventory, journalShellDiff, writeNotReversed, } from './shell-journal.js';
14
- export { resolveEffectiveEffectPolicy, requiresJail, isPathAllowed, isToolAllowedOnSurface, gateEffect, DEFAULT_EFFECT_RUN_MODE, readSessionEffectOverrides, normalizeTransactionRoots, mergeTransactionRoots, SESSION_EFFECT_OVERRIDES_KEY, } from './effect-policy.js';
15
+ export { resolveEffectiveEffectPolicy, requiresJail, buildOpsJailState, isPathAllowed, isToolAllowedOnSurface, gateEffect, DEFAULT_EFFECT_RUN_MODE, readSessionEffectOverrides, normalizeTransactionRoots, mergeTransactionRoots, SESSION_EFFECT_OVERRIDES_KEY, } from './effect-policy.js';
15
16
  export { runWithToolLimits, resolveToolTimeoutMs, ToolTimeoutError, } from './resource-limits.js';
16
17
  export { TurnMemoryJournal, JournaledMemoryStore, createMemoryRestorer, discardMemoryUndo, } from './memory-undo.js';
17
18
  export { resolveToolCapabilities, deniesReducedSurface, BUILTIN_TOOL_CAPABILITIES, REDUCED_DENIED_CAPABILITIES, } from './tool-capabilities.js';
@@ -0,0 +1,34 @@
1
+ /**
2
+ * kill switch(ops P5,`arch/ops-privileged-mode.md` §5 P5)——宿主侧急停
3
+ *
4
+ * 一条命令停掉 agent 的全部执行能力,**不依赖 LLM 判断与 agent 合作**:
5
+ * 宿主写一个哨兵文件(`octopi ops kill <agentId>`),引擎在 run 准入与每次工具
6
+ * 调用前检查——文件在 = 什么都不执行。删除文件(`octopi ops revive`)恢复。
7
+ *
8
+ * 设计约束:
9
+ * - **宿主侧信号**:不走 LLM、不走 agent 工具面(agent 无法自己解除;它甚至无法
10
+ * 阻止检查——检查点在 beforeToolCall,先于一切工具 handler)。
11
+ * - **每次实查,不缓存**:急停必须即时生效,也必须可即时恢复。
12
+ * - fail-closed:检查本身异常(stat 失败)按「未触发」处理不降级——哨兵缺失是
13
+ * 常态;但**路径未配置**时不得假装有急停(诚实:没有检查点 = 没有 kill switch)。
14
+ */
15
+ /** 急停状态 */
16
+ export interface KillSwitchState {
17
+ engaged: boolean;
18
+ /** 触发的哨兵文件路径(engaged=true 时给出) */
19
+ path?: string;
20
+ }
21
+ /**
22
+ * 默认哨兵路径(宿主布局):`<OCTOPI_HOME>/agents/<agentId>/KILL`。
23
+ *
24
+ * @param agentId - agent 标识
25
+ * @returns 哨兵文件绝对路径
26
+ */
27
+ export declare function defaultKillSwitchPath(agentId: string): string;
28
+ /**
29
+ * 检查急停哨兵(每次实查;文件存在 = engaged)。
30
+ *
31
+ * @param paths - 哨兵路径列表(任一存在即触发)
32
+ * @returns 急停状态
33
+ */
34
+ export declare function checkKillSwitch(paths: readonly string[] | undefined): KillSwitchState;