@octopi-agent/engine 0.86.38 → 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 (218) 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/agent.js +12 -5
  21. package/dist/config-schema/context.d.ts +7 -2
  22. package/dist/config-schema/context.js +8 -0
  23. package/dist/config-schema/engine.d.ts +110 -8
  24. package/dist/config-schema/governance.d.ts +43 -1
  25. package/dist/config-schema/governance.js +160 -2
  26. package/dist/config-schema/models.d.ts +7 -4
  27. package/dist/config-schema/models.js +4 -1
  28. package/dist/config-schema/observability.d.ts +9 -0
  29. package/dist/config-schema/observability.js +29 -0
  30. package/dist/config-schema/run.d.ts +3 -0
  31. package/dist/config-schema/run.js +14 -0
  32. package/dist/config-schema/shared.d.ts +3 -0
  33. package/dist/config-schema/shared.js +12 -0
  34. package/dist/config-schema/substrate.d.ts +1 -1
  35. package/dist/config.d.ts +60 -13
  36. package/dist/config.js +81 -78
  37. package/dist/harness/activation/dispatcher.d.ts +8 -2
  38. package/dist/harness/activation/dispatcher.js +33 -5
  39. package/dist/harness/activation/inbox.d.ts +87 -0
  40. package/dist/harness/activation/inbox.js +169 -0
  41. package/dist/harness/activation/runtime.d.ts +9 -8
  42. package/dist/harness/activation/runtime.js +100 -8
  43. package/dist/harness/activation/types.d.ts +19 -0
  44. package/dist/harness/activation/types.js +2 -0
  45. package/dist/harness/agent/builder.d.ts +18 -3
  46. package/dist/harness/agent/builder.js +42 -17
  47. package/dist/harness/agent/config-bridge.d.ts +5 -0
  48. package/dist/harness/agent/config-bridge.js +7 -1
  49. package/dist/harness/agent/config-integrity.d.ts +72 -0
  50. package/dist/harness/agent/config-integrity.js +146 -0
  51. package/dist/harness/agent/tool-purpose.d.ts +9 -1
  52. package/dist/harness/agent/tool-purpose.js +11 -2
  53. package/dist/harness/agent/wire-agent-builder.js +11 -3
  54. package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.d.ts +11 -1
  55. package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.js +11 -1
  56. package/dist/harness/collaboration/autonomous-subsystem/loader.d.ts +13 -0
  57. package/dist/harness/collaboration/autonomous-subsystem/loader.js +16 -1
  58. package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +4 -0
  59. package/dist/harness/collaboration/autonomous-subsystem/runtime.js +3 -1
  60. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +3 -1
  61. package/dist/harness/collaboration/delegation/child-run.js +21 -5
  62. package/dist/harness/collaboration/delegation/notifier.js +4 -3
  63. package/dist/harness/collaboration/delegation/service.js +2 -3
  64. package/dist/harness/collaboration/delegation/wiring.js +6 -5
  65. package/dist/harness/collaboration/orchestration/reflector/llm-reflector.d.ts +1 -1
  66. package/dist/harness/collaboration/orchestration/reflector/llm-reflector.js +1 -1
  67. package/dist/harness/context/capabilities/compact/engine.d.ts +30 -0
  68. package/dist/harness/context/capabilities/compact/engine.js +198 -46
  69. package/dist/harness/context/capabilities/compact/handover.d.ts +78 -0
  70. package/dist/harness/context/capabilities/compact/handover.js +107 -0
  71. package/dist/harness/context/capabilities/compact/index.d.ts +3 -1
  72. package/dist/harness/context/capabilities/compact/index.js +2 -1
  73. package/dist/harness/context/capabilities/compact/types.d.ts +30 -1
  74. package/dist/harness/context/capabilities/summary/executor.js +2 -1
  75. package/dist/harness/context/capabilities/summary/policies.js +8 -5
  76. package/dist/harness/context/constitution/default-agents.md +11 -10
  77. package/dist/harness/context/default-context-engine.d.ts +34 -4
  78. package/dist/harness/context/default-context-engine.js +198 -53
  79. package/dist/harness/context/hybrid-compressor.js +6 -0
  80. package/dist/harness/context/layer-types.d.ts +36 -0
  81. package/dist/harness/context/layer-types.js +38 -0
  82. package/dist/harness/context/llm-summarizer.d.ts +2 -8
  83. package/dist/harness/context/llm-summarizer.js +69 -91
  84. package/dist/harness/context/message-selector.js +4 -3
  85. package/dist/harness/context/root-instructions.js +1 -1
  86. package/dist/harness/context/summarize.d.ts +2 -0
  87. package/dist/harness/context/summarize.js +7 -2
  88. package/dist/harness/context/system-prompt-assembler.js +10 -4
  89. package/dist/harness/context/tool-result-aging.js +2 -2
  90. package/dist/harness/context/truncate-compressor.js +7 -0
  91. package/dist/harness/context/turn-envelope.d.ts +4 -3
  92. package/dist/harness/context/turn-envelope.js +4 -3
  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 +133 -4
  97. package/dist/harness/extension/execution-environment/effect-policy.js +263 -14
  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/isolation.js +5 -1
  101. package/dist/harness/extension/execution-environment/kill-switch.d.ts +34 -0
  102. package/dist/harness/extension/execution-environment/kill-switch.js +46 -0
  103. package/dist/harness/extension/execution-environment/ops-audit.d.ts +200 -0
  104. package/dist/harness/extension/execution-environment/ops-audit.js +338 -0
  105. package/dist/harness/extension/execution-environment/privileged-exec.d.ts +158 -0
  106. package/dist/harness/extension/execution-environment/privileged-exec.js +418 -0
  107. package/dist/harness/extension/execution-environment/process-info.d.ts +180 -0
  108. package/dist/harness/extension/execution-environment/process-info.js +466 -0
  109. package/dist/harness/extension/execution-environment/process-isolation.d.ts +7 -0
  110. package/dist/harness/extension/execution-environment/process-isolation.js +9 -0
  111. package/dist/harness/extension/execution-environment/sandbox.d.ts +109 -0
  112. package/dist/harness/extension/execution-environment/sandbox.js +264 -29
  113. package/dist/harness/extension/execution-environment/tool-capabilities.d.ts +1 -1
  114. package/dist/harness/extension/execution-environment/tool-capabilities.js +6 -0
  115. package/dist/harness/extension/execution-environment/types.d.ts +19 -0
  116. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +5 -0
  117. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.d.ts +6 -0
  118. package/dist/harness/extension/plugin-ecosystem/tools/allowlisted-run.js +50 -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 +53 -2
  123. package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +10 -17
  124. package/dist/harness/extension/plugin-ecosystem/tools/git-runner.d.ts +31 -0
  125. package/dist/harness/extension/plugin-ecosystem/tools/git-runner.js +104 -0
  126. package/dist/harness/extension/plugin-ecosystem/tools/git-status-snapshot.d.ts +111 -0
  127. package/dist/harness/extension/plugin-ecosystem/tools/git-status-snapshot.js +197 -0
  128. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.d.ts +8 -8
  129. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +9 -100
  130. package/dist/harness/extension/plugin-ecosystem/tools/index.d.ts +6 -0
  131. package/dist/harness/extension/plugin-ecosystem/tools/index.js +4 -0
  132. package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.d.ts +43 -0
  133. package/dist/harness/extension/plugin-ecosystem/tools/privileged-tool.js +350 -0
  134. package/dist/harness/extension/plugin-ecosystem/tools/process-tools.d.ts +30 -0
  135. package/dist/harness/extension/plugin-ecosystem/tools/process-tools.js +137 -0
  136. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +54 -4
  137. package/dist/harness/governance/human-in-the-loop/decision-cache.js +42 -16
  138. package/dist/harness/governance/security/temp-path.d.ts +9 -0
  139. package/dist/harness/governance/security/temp-path.js +13 -2
  140. package/dist/harness/governance/session-acl/seed-roles.js +14 -0
  141. package/dist/harness/index.d.ts +4 -0
  142. package/dist/harness/index.js +3 -0
  143. package/dist/harness/knowledge/file-identity.d.ts +8 -0
  144. package/dist/harness/knowledge/file-identity.js +26 -1
  145. package/dist/harness/knowledge/fts.js +1 -2
  146. package/dist/harness/knowledge/grounding.js +5 -5
  147. package/dist/harness/knowledge/index-store.d.ts +31 -4
  148. package/dist/harness/knowledge/index-store.js +180 -48
  149. package/dist/harness/knowledge/ingest.d.ts +115 -115
  150. package/dist/harness/knowledge/ingest.js +150 -150
  151. package/dist/harness/knowledge/knowledge-serve-child.js +1 -1
  152. package/dist/harness/knowledge/purge.js +4 -1
  153. package/dist/harness/memory/backfill-coverage.js +3 -1
  154. package/dist/harness/memory/sqlite/keyword-search.d.ts +1 -0
  155. package/dist/harness/memory/sqlite/keyword-search.js +4 -3
  156. package/dist/harness/observability/observer/hub.js +38 -1
  157. package/dist/harness/observability/observer/run-snapshot.js +1 -0
  158. package/dist/harness/observability/observer/types.d.ts +27 -0
  159. package/dist/harness/run/agent/agent.d.ts +7 -0
  160. package/dist/harness/run/agent/agent.js +23 -1
  161. package/dist/harness/run/reliability/fallback-provider.d.ts +117 -5
  162. package/dist/harness/run/reliability/fallback-provider.js +262 -22
  163. package/dist/harness/run/reliability/harness-events.d.ts +24 -1
  164. package/dist/harness/run/reliability/model-error-policy.d.ts +32 -0
  165. package/dist/harness/run/reliability/model-error-policy.js +42 -0
  166. package/dist/harness/run/reliability/provider-wrapper.js +29 -2
  167. package/dist/harness/run/reliability/refusal-guard.d.ts +20 -0
  168. package/dist/harness/run/reliability/refusal-guard.js +102 -0
  169. package/dist/harness/run/reliability/run-agent.js +231 -33
  170. package/dist/harness/run/run-guard/default-run-guard.js +1 -1
  171. package/dist/harness/run/run-scope.d.ts +31 -0
  172. package/dist/harness/run/runner.d.ts +132 -2
  173. package/dist/harness/run/runner.js +679 -60
  174. package/dist/harness/session/attachments/llm-intent.js +2 -1
  175. package/dist/harness/session/history/port.js +15 -5
  176. package/dist/harness/session/in-memory-store.d.ts +5 -0
  177. package/dist/harness/session/in-memory-store.js +33 -2
  178. package/dist/harness/session/tasks/render.d.ts +4 -1
  179. package/dist/harness/session/tasks/render.js +10 -7
  180. package/dist/harness/session/title.js +25 -9
  181. package/dist/harness/shared/events/agent-event-map.d.ts +92 -0
  182. package/dist/harness/shared/events/agent-event-map.js +7 -0
  183. package/dist/index.d.ts +6 -4
  184. package/dist/index.js +4 -3
  185. package/dist/integration/agent-runtime/channel-message-source.js +19 -1
  186. package/dist/integration/index.d.ts +2 -0
  187. package/dist/integration/index.js +1 -0
  188. package/dist/integration/observability/loop-watchdog.d.ts +56 -0
  189. package/dist/integration/observability/loop-watchdog.js +177 -0
  190. package/dist/integration/observability/metrics.d.ts +3 -0
  191. package/dist/integration/observability/metrics.js +18 -7
  192. package/dist/integration/observability/run-telemetry.d.ts +8 -0
  193. package/dist/integration/observability/run-telemetry.js +31 -8
  194. package/dist/integration/observability/trace-collector.js +26 -4
  195. package/dist/integration/observability/trace-events.d.ts +1 -0
  196. package/dist/integration/observability/trace-events.js +2 -0
  197. package/dist/integration/observability/trace-logger.js +27 -17
  198. package/dist/integration/providers/anthropic.d.ts +23 -0
  199. package/dist/integration/providers/anthropic.js +97 -12
  200. package/dist/integration/providers/fetch-timeout.d.ts +42 -0
  201. package/dist/integration/providers/fetch-timeout.js +51 -0
  202. package/dist/integration/providers/openai.d.ts +10 -0
  203. package/dist/integration/providers/openai.js +58 -11
  204. package/dist/integration/providers/provider-diagnostics.d.ts +80 -0
  205. package/dist/integration/providers/provider-diagnostics.js +89 -0
  206. package/dist/integration/providers/timeout-coherence.d.ts +52 -0
  207. package/dist/integration/providers/timeout-coherence.js +68 -0
  208. package/dist/integration/providers/wire-dump.d.ts +62 -0
  209. package/dist/integration/providers/wire-dump.js +111 -2
  210. package/dist/integration/storage/jsonl.d.ts +19 -1
  211. package/dist/integration/storage/jsonl.js +100 -4
  212. package/dist/paths.d.ts +19 -0
  213. package/dist/paths.js +38 -1
  214. package/dist/subsystems/cognition-steward/conceptualize/handler.js +1 -1
  215. package/dist/subsystems/memory-steward/backfill/handler.js +1 -1
  216. package/dist/subsystems/safety-guard/config.yaml +3 -1
  217. package/dist/subsystems/wisdom-steward/formation/handler.js +1 -1
  218. package/package.json +3 -2
@@ -0,0 +1,129 @@
1
+ /**
2
+ * 危险命令分类(§6:减速带,不是安全边界)— ops P4 pre-exec 闸 / P5 确认通道共用
3
+ *
4
+ * 诚实定位(必须与文档一致):**只拦事故,不拦攻击**。shell/argv 分类必然可绕过
5
+ * (`sh -c`、`python -c`、base64、变量拼接、别名、重定向)。任何「靠模式识别危险
6
+ * 命令」的机制都拦不住刻意构造的注入——真正的边界是权限范围(escalation.policy /
7
+ * L2 白名单 / OS uid)+ 审计。
8
+ *
9
+ * 分类表保守(§6 命中表):命中常见破坏性模式 → 要求确认;未命中 → 放行。
10
+ * **不做「未知即危险」**(否则误报淹没真信号)。
11
+ *
12
+ * 已知绕过(tests 钉死为用例,防后人误当边界):
13
+ * - `sh -c 'rm -rf /'` —— 嵌套 shell 的命令串本分类器不解析;
14
+ * - `> /etc/*` 重定向 —— argv 形态根本表达不了重定向。
15
+ */
16
+ /**
17
+ * 剥掉提权前缀(`sudo` / `doas` 及其选项)——分类对象是真实目标命令。
18
+ * 保守剥离:只处理选项 token 与 `-u <user>` 形态;剥不干净时宁可少报(§6 未命中放行)。
19
+ *
20
+ * @param argv - 完整 argv
21
+ * @returns 剥离后的 argv(至少含一个 token)
22
+ */
23
+ function stripPrivilegePrefix(argv) {
24
+ if (argv.length === 0)
25
+ return argv;
26
+ const base = basenameOf(argv[0]);
27
+ if (base !== 'sudo' && base !== 'doas')
28
+ return argv;
29
+ const rest = [];
30
+ for (let i = 1; i < argv.length; i += 1) {
31
+ const token = argv[i];
32
+ if (token === '--') {
33
+ rest.push(...argv.slice(i + 1));
34
+ break;
35
+ }
36
+ if (token.startsWith('-')) {
37
+ // `-u user` / `--user=user` 类选项会吞掉下一个 token
38
+ if (token === '-u' || token === '--user' || token === '-g' || token === '--group') {
39
+ i += 1;
40
+ }
41
+ continue;
42
+ }
43
+ rest.push(...argv.slice(i));
44
+ break;
45
+ }
46
+ return rest.length > 0 ? rest : argv.slice(1);
47
+ }
48
+ /** 可执行名(跨平台取末段;不解析 Windows 扩展名以外的语义) */
49
+ function basenameOf(path) {
50
+ const normalized = path.replace(/\\/g, '/');
51
+ const idx = normalized.lastIndexOf('/');
52
+ return (idx >= 0 ? normalized.slice(idx + 1) : normalized).toLowerCase();
53
+ }
54
+ /** 短选项聚合字母(`-rf` → ['r','f']);长选项/非选项不参与 */
55
+ function shortFlagLetters(tokens) {
56
+ const letters = new Set();
57
+ for (const token of tokens) {
58
+ if (token === '--')
59
+ break;
60
+ if (!token.startsWith('-') || token.startsWith('--') || token === '-')
61
+ continue;
62
+ for (const ch of token.slice(1))
63
+ letters.add(ch.toLowerCase());
64
+ }
65
+ return letters;
66
+ }
67
+ /** 是否出现递归/强制类长选项 */
68
+ function hasLongFlag(tokens, names) {
69
+ return tokens.some((t) => names.includes(t));
70
+ }
71
+ /**
72
+ * 按 §6 命中表对 argv 分类。
73
+ *
74
+ * @param argv - 完整 argv(argv[0] = 可执行文件;提权前缀 sudo/doas 会被剥掉后分类)
75
+ * @returns 是否危险 + 命中条目名
76
+ */
77
+ export function classifyDangerousArgv(argv) {
78
+ const effective = stripPrivilegePrefix(argv);
79
+ if (effective.length === 0)
80
+ return { dangerous: false };
81
+ const cmd = basenameOf(effective[0]);
82
+ const rest = effective.slice(1);
83
+ // `rm -rf`:递归 + 强制同现(-rf / -fr / -r -f / --recursive --force)
84
+ if (cmd === 'rm' || cmd === 'rm.exe') {
85
+ const flags = shortFlagLetters(rest);
86
+ const recursive = flags.has('r') || hasLongFlag(rest, ['--recursive']);
87
+ const force = flags.has('f') || hasLongFlag(rest, ['--force']);
88
+ if (recursive && force)
89
+ return { dangerous: true, pattern: 'rm -rf' };
90
+ return { dangerous: false };
91
+ }
92
+ // `dd of=/dev/*`:直接写块设备
93
+ if (cmd === 'dd' || cmd === 'dd.exe') {
94
+ if (rest.some((a) => a.startsWith('of=/dev/') || a.startsWith('of=\\\\.\\'))) {
95
+ return { dangerous: true, pattern: 'dd of=/dev/*' };
96
+ }
97
+ return { dangerous: false };
98
+ }
99
+ // `mkfs.*`:格式化
100
+ if (cmd.startsWith('mkfs'))
101
+ return { dangerous: true, pattern: 'mkfs.*' };
102
+ // `iptables -F`:清空防火墙规则
103
+ if (cmd === 'iptables' || cmd === 'iptables.exe' || cmd === 'nft') {
104
+ if (rest.includes('-F') || rest.includes('--flush')) {
105
+ return { dangerous: true, pattern: 'iptables -F' };
106
+ }
107
+ return { dangerous: false };
108
+ }
109
+ // `systemctl disable`:关服务自启
110
+ if (cmd === 'systemctl' || cmd === 'systemctl.exe') {
111
+ if (rest.includes('disable') || rest.includes('mask')) {
112
+ return { dangerous: true, pattern: 'systemctl disable' };
113
+ }
114
+ return { dangerous: false };
115
+ }
116
+ // `chmod -R` / `chown -R`:递归改权限/属主
117
+ if (cmd === 'chmod' || cmd === 'chown' || cmd === 'chmod.exe' || cmd === 'chown.exe') {
118
+ const flags = shortFlagLetters(rest);
119
+ if (flags.has('r') || hasLongFlag(rest, ['--recursive'])) {
120
+ return { dangerous: true, pattern: `${cmd} -R` };
121
+ }
122
+ return { dangerous: false };
123
+ }
124
+ // `truncate`:截断文件(静默毁数据的典型手滑)
125
+ if (cmd === 'truncate' || cmd === 'truncate.exe') {
126
+ return { dangerous: true, pattern: 'truncate' };
127
+ }
128
+ return { dangerous: false };
129
+ }
@@ -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) */
@@ -82,7 +109,7 @@ export interface EffectPolicyConfig {
82
109
  * `degrade` 降 effectiveMode + toolSurface=reduced + securityDegraded。
83
110
  */
84
111
  untrustedAdmission?: UntrustedAdmission;
85
- /** 额外事务 root(绝对路径);并入 allowRoots */
112
+ /** 额外事务 root(绝对路径或 ~ 形态,入口 trim → expand);并入 allowRoots */
86
113
  transactionRoots?: string[];
87
114
  pathContainment?: PathContainment;
88
115
  shellEscape?: ShellEscapePolicy;
@@ -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,7 +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
  }
236
+ /**
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.
242
+ *
243
+ * @param eff - resolved effective policy
244
+ * @returns true when a missing/broken jail must refuse execution
245
+ */
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;
153
270
  /**
154
271
  * 展开 effectPolicy 为有效策略
155
272
  *
@@ -190,12 +307,24 @@ export declare function isToolAllowedOnSurface(toolName: string, surface: ToolSu
190
307
  * @returns 是否允许
191
308
  */
192
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
+ }
193
321
  /**
194
322
  * 效应闸(P4):事务内自动放行;host-gate 交给宿主;engine 通道按内置策略。
195
323
  *
196
324
  * @param intent - 效应意图
197
325
  * @param options - 通道与回调
198
- * @throws Error 当拒绝执行时
326
+ * @returns 放行结论(confirmed/confirmSource + 确认人归因,审计用)
327
+ * @throws Error 当拒绝执行时(`effect_confirm_timeout` 超时 / `effect_denied` 拒绝,语义分家)
199
328
  */
200
329
  export declare function gateEffect(intent: EffectIntent, options: {
201
330
  effects: EffectConfirmChannel;
@@ -206,7 +335,7 @@ export declare function gateEffect(intent: EffectIntent, options: {
206
335
  /** SEC-7:always-scope 缓存键(agent 分桶);缺省尝试 RunScope */
207
336
  agentId?: string;
208
337
  hitlCache?: import('../../governance/human-in-the-loop/decision-cache.js').HitlDecisionCache;
209
- }): Promise<void>;
338
+ }): Promise<GateEffectResult>;
210
339
  /**
211
340
  * Session-only effect overrides. Append-only: may add allow roots for this
212
341
  * session; must never loosen pathContainment / shellEscape.