@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
@@ -6,10 +6,21 @@
6
6
  * Public contract: `docs/process-isolation.md`.
7
7
  */
8
8
  import { spawn } from 'node:child_process';
9
- import { realpath, unlink, writeFile } from 'node:fs/promises';
9
+ import { realpath, stat, unlink, writeFile } from 'node:fs/promises';
10
10
  import { homedir, tmpdir } from 'node:os';
11
11
  import { join, resolve } from 'node:path';
12
+ import { StringDecoder } from 'node:string_decoder';
12
13
  import { assessL4ProcessMinimum, killProcessTree, probeProcessIsolation, scrubEnv, supervisedSpawnProfile, } from './process-isolation.js';
14
+ /**
15
+ * Run 级失笼降级的归一码前缀(ops P0):probe 缺笼与运行时失笼共用 `no_process_jail`
16
+ * 前缀,消费面按前缀匹配即可覆盖全部失笼路径。
17
+ *
18
+ * @param detail - 失笼细节(jail_setup_failed / jail_spawn_failed / …)
19
+ * @returns 归一后的 securityDegraded 代码
20
+ */
21
+ export function jailDegradationCode(detail) {
22
+ return `no_process_jail: ${detail}`;
23
+ }
13
24
  /**
14
25
  * Supervised process runner: tree-killable spawn with scrubbed env.
15
26
  * This is NOT a filesystem jail — `isolation.filesystem` stays `cwd-pin`.
@@ -62,6 +73,22 @@ export class ProcessSandbox {
62
73
  const env = scrubEnv(config?.env, { forceKeys: this.forceEnvKeys });
63
74
  const timeoutMs = config?.limits?.timeoutMs ?? 60_000;
64
75
  const maxOutputBytes = config?.limits?.maxOutputBytes ?? 10 * 1024 * 1024;
76
+ if (config?.disableJail && config?.requireJail) {
77
+ // 库契约守卫:两个都设 = 配置矛盾,绝不静默取舍
78
+ return Promise.reject(new Error('sandbox_config_conflict: disableJail and requireJail are mutually exclusive'));
79
+ }
80
+ // 授权无笼(ops P0:jail=none + privilegedAck 已过配置闸):显式注记,不是降级
81
+ if (config?.disableJail) {
82
+ return this.withExecDiagnostics(this.runSupervised(file, args, config, {
83
+ ...profile,
84
+ backend: 'supervised-spawn',
85
+ processTree: 'killable',
86
+ filesystem: 'cwd-pin',
87
+ privilege: 'same',
88
+ network: 'open',
89
+ notes: [...(profile.notes ?? []), 'jail=disabled_by_config (privileged)'],
90
+ }, { cwd, env, timeoutMs, maxOutputBytes }), cwd, []);
91
+ }
65
92
  // Jail backends wrap the spawn; fall back to supervised spawn.
66
93
  if (profile.backend === 'linux-bwrap' && process.platform === 'linux') {
67
94
  return this.runBwrap(file, args, config, profile, { cwd, env, timeoutMs, maxOutputBytes });
@@ -70,15 +97,71 @@ export class ProcessSandbox {
70
97
  return this.runSeatbelt(file, args, config, profile, { cwd, env, timeoutMs, maxOutputBytes });
71
98
  }
72
99
  if (config?.requireJail) {
73
- return Promise.reject(new Error(`untrusted_jail_failed: no process jail backend (probe=${profile.backend}); refuse unsandboxed execute`));
100
+ return Promise.reject(new Error(`jail_required_unavailable: no process jail backend (probe=${profile.backend}); refuse unsandboxed execute`));
74
101
  }
75
- return this.runSupervised(file, args, config, profile, { cwd, env, timeoutMs, maxOutputBytes });
102
+ // jail 意图落空(auto+degrade):逐条命令如实注记;run 级 securityDegraded
103
+ // 已由 resolveEffectiveEffectPolicy 记 `no_process_jail`(probe 期缺笼)
104
+ return this.withExecDiagnostics(this.runSupervised(file, args, config, {
105
+ ...profile,
106
+ notes: [...(profile.notes ?? []), 'jail=unavailable (supervised-spawn); running unsandboxed'],
107
+ }, { cwd, env, timeoutMs, maxOutputBytes }), cwd, []);
108
+ }
109
+ /**
110
+ * Attribute a setuid/privilege exec denial on the caller's channels.
111
+ *
112
+ * A jail that does not apply (nested sandbox, wrapper missing) still refuses
113
+ * setuid exec when an **enclosing** jail is in force, so attribution cannot
114
+ * live only in `runSeatbelt`. `denyExec` stays empty there: without proof we
115
+ * own the profile, claiming a specific deny-list entry would be a guess.
116
+ *
117
+ * @param pending - result promise from whichever backend ran
118
+ * @param cwd - run cwd, used to resolve bare command names
119
+ * @param denyExec - deny list we know is in force (empty when unknown)
120
+ * @returns result, with one explanation attached when stderr was attributable
121
+ */
122
+ withExecDiagnostics(pending, cwd, denyExec) {
123
+ if (process.platform !== 'darwin')
124
+ return Promise.resolve(pending);
125
+ return Promise.resolve(pending).then(async (result) => {
126
+ const denial = await explainSeatbeltExecDenial({ stderr: result.stderr, cwd, denyExec });
127
+ if (!denial)
128
+ return result;
129
+ return {
130
+ ...result,
131
+ isolation: {
132
+ ...result.isolation,
133
+ notes: [...(result.isolation.notes ?? []), denial.note],
134
+ },
135
+ diagnostics: { hints: [denial.hint] },
136
+ };
137
+ });
76
138
  }
77
139
  runSupervised(file, args, config, profile, opts) {
78
140
  return new Promise((resolve, reject) => {
79
141
  const start = Date.now();
80
142
  let stdout = '';
81
143
  let stderr = '';
144
+ // 输出上限按原始字节计(stdout/stderr 各自独立计):字符数远小于字节数,
145
+ // 旧口径会让上限推迟触发、放走 ~3x 字节。计数含被丢弃块,故已捕获文本恒 ≤
146
+ // 上限;usage().outputBytes 只计已捕获字节(`captured*`,见下方 usage 调用)。
147
+ let stdoutBytes = 0;
148
+ let stderrBytes = 0;
149
+ // 已捕获原始字节:usage 的唯一口径。不能用 byteLength(文本) 代替——被切断的
150
+ // 多字节字符解码后是 3 字节的 U+FFFD,按文本重算会虚高(也说明必须用
151
+ // StringDecoder 跨块解码,逐块 toString 会让 stdout/stderr 文本本身被污染)。
152
+ let stdoutCaptured = 0;
153
+ let stderrCaptured = 0;
154
+ const stdoutDecoder = new StringDecoder('utf8');
155
+ const stderrDecoder = new StringDecoder('utf8');
156
+ let decodersFlushed = false;
157
+ /** 冲刷解码器尾部:未收尾的多字节字符在此输出(截断流输出 U+FFFD 是正确结果)。 */
158
+ const flushDecoders = () => {
159
+ if (decodersFlushed)
160
+ return;
161
+ decodersFlushed = true;
162
+ stdout += stdoutDecoder.end();
163
+ stderr += stderrDecoder.end();
164
+ };
82
165
  let terminated = false;
83
166
  let terminateReason = '';
84
167
  let settled = false;
@@ -116,24 +199,29 @@ export class ProcessSandbox {
116
199
  const onAbort = () => kill('Aborted');
117
200
  config?.signal?.addEventListener('abort', onAbort, { once: true });
118
201
  proc.stdout?.on('data', (data) => {
119
- if (stdout.length + data.length > opts.maxOutputBytes) {
202
+ stdoutBytes += data.length;
203
+ if (stdoutBytes > opts.maxOutputBytes) {
120
204
  kill('Output size limit exceeded');
121
205
  return;
122
206
  }
123
- stdout += data.toString('utf8');
207
+ stdoutCaptured += data.length;
208
+ stdout += stdoutDecoder.write(data);
124
209
  });
125
210
  proc.stderr?.on('data', (data) => {
126
- if (stderr.length + data.length > opts.maxOutputBytes) {
211
+ stderrBytes += data.length;
212
+ if (stderrBytes > opts.maxOutputBytes) {
127
213
  kill('Output size limit exceeded');
128
214
  return;
129
215
  }
130
- stderr += data.toString('utf8');
216
+ stderrCaptured += data.length;
217
+ stderr += stderrDecoder.write(data);
131
218
  });
132
219
  const timer = setTimeout(() => {
133
220
  kill(`Execution timeout (${opts.timeoutMs}ms)`);
134
221
  }, opts.timeoutMs);
135
222
  proc.on('close', (exitCode, signal) => {
136
- const usage = this.usage(start, stdout, stderr);
223
+ flushDecoders();
224
+ const usage = this.usage(start, stdoutCaptured, stderrCaptured);
137
225
  // null exitCode = signal death; never report that as success (exit 0)
138
226
  const code = typeof exitCode === 'number' ? exitCode : -1;
139
227
  finish({
@@ -151,10 +239,11 @@ export class ProcessSandbox {
151
239
  });
152
240
  });
153
241
  proc.on('error', (err) => {
154
- const usage = this.usage(start, stdout, stderr);
242
+ flushDecoders();
243
+ const usage = this.usage(start, stdoutCaptured, stderrCaptured);
155
244
  const isJailWrapper = profile.backend === 'linux-bwrap' || profile.backend === 'mac-seatbelt';
156
245
  if (config?.requireJail && isJailWrapper) {
157
- fail(new Error(`untrusted_jail_failed: jail spawn failed: ${err.message} (requireJail=true; refuse unsandboxed execute)`));
246
+ fail(new Error(`jail_required_unavailable: jail spawn failed: ${err.message} (requireJail=true; refuse unsandboxed execute)`));
158
247
  return;
159
248
  }
160
249
  const honest = isJailWrapper
@@ -165,8 +254,10 @@ export class ProcessSandbox {
165
254
  notes: [...(profile.notes ?? []), `jail spawn failed: ${err.message}`],
166
255
  }
167
256
  : profile;
168
- if (isJailWrapper)
169
- config?.noteSecurityDegraded?.(`jail_spawn_failed: ${err.message}`);
257
+ // 归一码 no_process_jail(与 jailSetupFailed/jailWrapperRuntimeFailure 同前缀)
258
+ if (isJailWrapper) {
259
+ config?.noteSecurityDegraded?.(jailDegradationCode(`jail_spawn_failed: ${err.message}`));
260
+ }
170
261
  finish({
171
262
  exitCode: -1,
172
263
  stdout,
@@ -235,11 +326,14 @@ export class ProcessSandbox {
235
326
  // Host override wins; otherwise generate a profile covering allowRoots (D3-b+).
236
327
  let profilePath = process.env.OCTOPI_SB_PROFILE;
237
328
  let generatedPath;
329
+ /** Deny list in force, or null when an external profile owns it (unknown). */
330
+ let denyExec = null;
238
331
  if (!profilePath) {
239
332
  generatedPath = join(tmpdir(), `octopi-sb-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.sb`);
240
333
  try {
241
334
  await writeFile(generatedPath, buildSeatbeltProfile(roots, network), { encoding: 'utf8', mode: 0o600 });
242
335
  profilePath = generatedPath;
336
+ denyExec = DEFAULT_PRIVILEGE_DENY_EXEC;
243
337
  }
244
338
  catch (err) {
245
339
  return this.jailSetupFailed(file, args, config, profile, opts, `seatbelt profile generation failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -266,7 +360,11 @@ export class ProcessSandbox {
266
360
  if (isJailWrapperSetupFailure(result, 'sandbox-exec')) {
267
361
  return await this.jailWrapperRuntimeFailure(result, config, profile, `seatbelt apply failed (exit=${result.exitCode}): ${result.stderr.slice(0, 200)}`);
268
362
  }
269
- return result;
363
+ // A real command may have printed EPERM for reasons the caller cannot see
364
+ // from inside the jail (setuid exec is an OS invariant; privileged
365
+ // helpers are denied by the profile). Attribute it once, on the honest
366
+ // channels: isolation notes (what the jail did) + diagnostics (next step).
367
+ return this.withExecDiagnostics(result, opts.cwd, denyExec ?? []);
270
368
  }
271
369
  finally {
272
370
  if (generatedPath) {
@@ -280,7 +378,7 @@ export class ProcessSandbox {
280
378
  */
281
379
  jailSetupFailed(file, args, config, profile, opts, reason) {
282
380
  if (config?.requireJail) {
283
- return Promise.reject(new Error(`untrusted_jail_failed: ${reason} (requireJail=true; refuse unsandboxed execute)`));
381
+ return Promise.reject(new Error(`jail_required_unavailable: ${reason} (requireJail=true; refuse unsandboxed execute)`));
284
382
  }
285
383
  const degraded = {
286
384
  ...profile,
@@ -291,7 +389,8 @@ export class ProcessSandbox {
291
389
  network: 'open',
292
390
  notes: [...(profile.notes ?? []), `jail_setup_failed: ${reason}; supervised fallback`],
293
391
  };
294
- config?.noteSecurityDegraded?.(`jail_setup_failed: ${reason}`);
392
+ // 归一码 no_process_jail:消费面按前缀匹配即可覆盖 probe 缺笼与运行时建笼失败两类路径
393
+ config?.noteSecurityDegraded?.(jailDegradationCode(`jail_setup_failed: ${reason}`));
295
394
  return this.runSupervised(file, args, config, degraded, opts);
296
395
  }
297
396
  /**
@@ -309,9 +408,10 @@ export class ProcessSandbox {
309
408
  */
310
409
  jailWrapperRuntimeFailure(result, config, profile, reason) {
311
410
  if (config?.requireJail) {
312
- return Promise.reject(new Error(`untrusted_jail_failed: ${reason} (requireJail=true; refuse unsandboxed execute)`));
411
+ return Promise.reject(new Error(`jail_required_unavailable: ${reason} (requireJail=true; refuse unsandboxed execute)`));
313
412
  }
314
- config?.noteSecurityDegraded?.(`jail_setup_failed: ${reason}`);
413
+ // 归一码 no_process_jail(同 jailSetupFailed)
414
+ config?.noteSecurityDegraded?.(jailDegradationCode(`jail_setup_failed: ${reason}`));
315
415
  return Promise.resolve({
316
416
  ...result,
317
417
  isolation: {
@@ -328,12 +428,12 @@ export class ProcessSandbox {
328
428
  },
329
429
  });
330
430
  }
331
- usage(start, stdout, stderr) {
431
+ usage(start, stdoutCaptured, stderrCaptured) {
332
432
  return {
333
433
  elapsedMs: Date.now() - start,
334
434
  peakMemoryBytes: -1,
335
435
  cpuTimeMs: -1,
336
- outputBytes: Buffer.byteLength(stdout, 'utf8') + Buffer.byteLength(stderr, 'utf8'),
436
+ outputBytes: stdoutCaptured + stderrCaptured,
337
437
  };
338
438
  }
339
439
  }
@@ -492,16 +592,151 @@ export const SEATBELT_DEVICE_WRITE_ALLOW = [
492
592
  '/dev/stdout',
493
593
  '/dev/stderr',
494
594
  ];
495
- /** Common privilege-gaining binaries denied inside Seatbelt (1-B). */
496
- const DEFAULT_PRIVILEGE_DENY_EXEC = [
497
- '/usr/bin/sudo',
498
- '/bin/su',
499
- '/usr/bin/su',
500
- '/usr/sbin/chroot',
501
- '/usr/bin/login',
502
- '/usr/bin/newgrp',
503
- '/usr/bin/dscl',
504
- ];
595
+ /**
596
+ * Privilege-gaining binaries, grouped by the capability they grant.
597
+ *
598
+ * This is a **cross-platform superset on purpose**, not a survey of the host
599
+ * running it. Two reasons:
600
+ * - Seatbelt's `(literal ...)` matches a path string exactly; it does not
601
+ * normalise `/bin` vs `/usr/bin` or `sbin` vs `bin`. Distributions disagree
602
+ * on all of them (`su` is `/bin/su` on Debian, `/usr/bin/su` on macOS;
603
+ * `chroot` lives under `/usr/sbin` on macOS and additionally under
604
+ * `/usr/bin` / `/sbin` elsewhere). A missing spelling is an open door.
605
+ * - A deny line for a path that does not exist on this host never matches and
606
+ * costs nothing: no error, no runtime penalty. So the asymmetry is one-way —
607
+ * dead entries are free, missing entries are a hole.
608
+ *
609
+ * **Do not trim this list by inspecting one machine.** Every entry that looks
610
+ * dead on macOS is live on some Linux distribution. New privilege-gaining
611
+ * helpers (`pkexec`, `doas`, `run0`, `sudoedit`) are inherited by every jail
612
+ * backend that shares this table, so the risk of a stale entry is the cheaper
613
+ * side of the trade.
614
+ */
615
+ export const PRIVILEGE_DENY_EXEC_GROUPS = {
616
+ /** Full privilege switch to any user. */
617
+ su: ['/bin/su', '/usr/bin/su', '/sbin/su'],
618
+ /** Run a command as another user (sudo family). */
619
+ sudo: ['/usr/bin/sudo', '/bin/sudo', '/usr/local/bin/sudo'],
620
+ /** Edit a file as root through sudo. */
621
+ sudoedit: ['/usr/bin/sudoedit', '/bin/sudoedit'],
622
+ /** Polkit-mediated privilege escalation (desktop Linux). */
623
+ pkexec: ['/usr/bin/pkexec', '/usr/local/bin/pkexec'],
624
+ /** Minimal sudo replacement (OpenBSD, Alpine, some Linux). */
625
+ doas: ['/usr/bin/doas', '/usr/local/bin/doas', '/usr/local/sbin/doas'],
626
+ /** systemd-run privilege escalation (systemd >= 256). */
627
+ run0: ['/usr/bin/run0'],
628
+ /** Replace the session, bypassing the caller's credentials. */
629
+ login: ['/usr/bin/login', '/bin/login'],
630
+ /** Change the process group ID without a password. */
631
+ newgrp: ['/usr/bin/newgrp', '/bin/newgrp', '/usr/bin/sg', '/bin/sg'],
632
+ /** Start a process in a different root / namespace. */
633
+ chroot: ['/usr/sbin/chroot', '/usr/bin/chroot', '/sbin/chroot', '/bin/chroot'],
634
+ /** Read or modify the local directory service (macOS account DB). */
635
+ dscl: ['/usr/bin/dscl', '/usr/sbin/dscl'],
636
+ };
637
+ /**
638
+ * Flat deny list in force unless the host overrides it.
639
+ *
640
+ * Derived from {@link PRIVILEGE_DENY_EXEC_GROUPS} so the grouped table stays
641
+ * the single source of truth.
642
+ */
643
+ export const DEFAULT_PRIVILEGE_DENY_EXEC = Object.values(PRIVILEGE_DENY_EXEC_GROUPS).flat();
644
+ /** POSIX binary directories searched for a bare command name. */
645
+ const EXEC_LOOKUP_DIRS = ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin'];
646
+ /** Setuid file mode bit. */
647
+ const SETUID_BIT = 0o4000;
648
+ /** Cap on distinct paths probed from one stderr, to bound `stat` cost. */
649
+ const EXEC_DENIAL_PROBE_LIMIT = 8;
650
+ /**
651
+ * Locate a binary the shell named in an EPERM line.
652
+ *
653
+ * @param token - absolute path or bare command name from stderr
654
+ * @param cwd - base for relative paths
655
+ * @returns resolved absolute path with its mode, or null when nothing exists
656
+ */
657
+ async function resolveExecutable(token, cwd) {
658
+ const candidates = token.includes('/')
659
+ ? [resolve(cwd, token)]
660
+ : EXEC_LOOKUP_DIRS.map((dir) => join(dir, token));
661
+ for (const candidate of candidates) {
662
+ try {
663
+ const info = await stat(candidate);
664
+ if (info.isFile())
665
+ return { path: candidate, mode: info.mode };
666
+ }
667
+ catch {
668
+ // Not in this directory — try the next candidate.
669
+ }
670
+ }
671
+ return null;
672
+ }
673
+ /**
674
+ * Extract the subject of each EPERM line.
675
+ *
676
+ * Shells disagree on where the path sits:
677
+ * - bash/sh: `bash: line 1: /usr/bin/top: Operation not permitted`
678
+ * - zsh: `zsh:1: operation not permitted: /usr/bin/top`
679
+ *
680
+ * Deduped and capped: a pathological command can emit thousands of EPERM lines
681
+ * and each candidate costs up to one `stat` per lookup dir.
682
+ *
683
+ * @param stderr - captured stderr
684
+ * @returns distinct paths in emission order
685
+ */
686
+ function extractDeniedTargets(stderr) {
687
+ const targets = new Set();
688
+ for (const raw of stderr.split('\n')) {
689
+ if (targets.size >= EXEC_DENIAL_PROBE_LIMIT)
690
+ break;
691
+ const line = raw.trim();
692
+ if (!/operation not permitted/i.test(line))
693
+ continue;
694
+ const trailing = /(?:^|:)\s*([^\s:][^:\n]*?):\s*operation not permitted$/i.exec(line);
695
+ if (trailing?.[1]) {
696
+ targets.add(trailing[1].trim());
697
+ continue;
698
+ }
699
+ const leading = /operation not permitted:\s*(\S.*)$/i.exec(line);
700
+ if (leading?.[1])
701
+ targets.add(leading[1].trim());
702
+ }
703
+ return [...targets];
704
+ }
705
+ /**
706
+ * Attribute an exec denial inside the macOS jail so the caller can correct
707
+ * itself without re-discovering the sandbox's invariants by trial and error.
708
+ *
709
+ * @param args - captured stderr, run cwd, and the deny list written into the profile
710
+ * @returns the first attributable denial, or null when EPERM had another cause
711
+ */
712
+ export async function explainSeatbeltExecDenial(args) {
713
+ const deny = new Set(args.denyExec ?? DEFAULT_PRIVILEGE_DENY_EXEC);
714
+ for (const token of extractDeniedTargets(args.stderr)) {
715
+ const found = await resolveExecutable(token, args.cwd);
716
+ if (!found)
717
+ continue;
718
+ if (deny.has(found.path)) {
719
+ return {
720
+ target: found.path,
721
+ kind: 'privilege-deny',
722
+ note: `exec_denied: ${found.path} is on the jail privilege deny list`,
723
+ hint: `exec_denied: ${found.path} is on the sandbox privilege deny list (buildSeatbeltProfile) — ` +
724
+ `privileged helpers are blocked by design inside the jail; do not retry, find an unprivileged route.`,
725
+ };
726
+ }
727
+ if ((found.mode & SETUID_BIT) !== 0) {
728
+ return {
729
+ target: found.path,
730
+ kind: 'setuid-exec',
731
+ note: `exec_denied: ${found.path} is setuid; seatbelt refuses setuid exec (macOS invariant)`,
732
+ hint: `exec_denied: ${found.path} is setuid and seatbelt refuses setuid exec — a macOS invariant, ` +
733
+ `not configurable by the profile. Do not retry it; read the same state without exec'ing a ` +
734
+ `setuid binary (e.g. pgrep -fl, lsof, vm_stat, or libproc proc_pidinfo).`,
735
+ };
736
+ }
737
+ }
738
+ return null;
739
+ }
505
740
  function resolveShell() {
506
741
  if (process.platform === 'win32') {
507
742
  const comspec = process.env.COMSPEC || 'cmd.exe';
@@ -10,7 +10,7 @@
10
10
  import type { ToolCapability } from '@octopi-agent/core/types.js';
11
11
  export type { ToolCapability };
12
12
  /** Capabilities that are denied on the reduced tool surface. */
13
- export declare const REDUCED_DENIED_CAPABILITIES: readonly ["exec", "egress", "send", "dynamic-code", "runner"];
13
+ export declare const REDUCED_DENIED_CAPABILITIES: readonly ["exec", "egress", "send", "dynamic-code", "runner", "host-read"];
14
14
  /**
15
15
  * Builtin name → capability tags. Keep in sync with each tool definition's
16
16
  * `capabilities` field (backfilled for every builtin).
@@ -15,6 +15,8 @@ export const REDUCED_DENIED_CAPABILITIES = [
15
15
  'dynamic-code',
16
16
  /** project_run executes workspace-defined scripts (code execution) */
17
17
  'runner',
18
+ /** host introspection (process table/argv) — engine-side data bypasses the jail's "cannot see host processes" boundary */
19
+ 'host-read',
18
20
  ];
19
21
  /**
20
22
  * Builtin name → capability tags. Keep in sync with each tool definition's
@@ -48,6 +50,10 @@ export const BUILTIN_TOOL_CAPABILITIES = {
48
50
  document_read: ['fs-read'],
49
51
  document_probe: ['fs-read'],
50
52
  env_info: ['fs-read'],
53
+ // 只读进程诊断(ops P1):宿主内省(进程表/argv),reduced 面剥掉(host-read)
54
+ process_list: ['host-read'],
55
+ // exec 标签:reduced 面剥掉提权通道(降能力不降墙)
56
+ priv_exec: ['exec'],
51
57
  http_request: ['egress'],
52
58
  web_search: ['egress'],
53
59
  ask_user: [],
@@ -35,6 +35,13 @@ export interface SandboxConfig {
35
35
  * Setup failure throws instead of falling back to supervised spawn.
36
36
  */
37
37
  requireJail?: boolean;
38
+ /**
39
+ * ops P0: authorized no-jail (`effectPolicy.jail: "none"`, privilegedAck
40
+ * already enforced at config resolution). Skips jail wrapping even when a
41
+ * backend is present and notes `jail=disabled_by_config (privileged)` —
42
+ * this is an authorization, never a degradation.
43
+ */
44
+ disableJail?: boolean;
38
45
  /**
39
46
  * Allow `$HOME` writes inside the jail (project/host only per 2b).
40
47
  * tmpdir and, on POSIX, shared `/tmp` + `/var/tmp` are always writable (2a);
@@ -84,6 +91,18 @@ export interface SandboxResult {
84
91
  usage: ResourceUsage;
85
92
  /** Honest isolation actually applied for this run */
86
93
  isolation: ProcessIsolationProfile;
94
+ /** Structured diagnostics; absent when the run explained itself */
95
+ diagnostics?: SandboxDiagnostics;
96
+ }
97
+ /**
98
+ * Structured, machine-readable diagnostics for a sandboxed run.
99
+ *
100
+ * Hints exist so a caller can self-correct on the next attempt instead of
101
+ * re-discovering a sandbox invariant (mirrors `file_search` diagnostics).
102
+ */
103
+ export interface SandboxDiagnostics {
104
+ /** Actionable self-correction hints, one line each */
105
+ hints?: string[];
87
106
  }
88
107
  /**
89
108
  * SandboxProvider — execute commands under an isolation profile.
@@ -9,6 +9,7 @@
9
9
  * - Plugin 通过 registerChannel(adapter) 注册实现
10
10
  * - Gateway / Integration 按部署形态挂载具体 adapter
11
11
  */
12
+ export type ChannelMessageDelivery = 'steered' | 'followup' | 'run';
12
13
  export interface ChannelMessage {
13
14
  id: string;
14
15
  channel: string;
@@ -18,6 +19,10 @@ export interface ChannelMessage {
18
19
  conversationId: string;
19
20
  timestamp: number;
20
21
  metadata?: Record<string, unknown>;
22
+ /** Runtime 受理后的真实去向;宿主回执用,不进入模型。 */
23
+ delivery?: ChannelMessageDelivery;
24
+ /** 宿主传入;Runtime 实际受理后由 Gateway 调用。 */
25
+ onDelivery?: (delivery: ChannelMessageDelivery) => void;
21
26
  }
22
27
  export interface ChannelReply {
23
28
  channel: string;
@@ -18,6 +18,12 @@ export interface AllowlistedRunOptions {
18
18
  timeoutMs?: number;
19
19
  /** Journal write effects via shell-journal (default true for mutating tools) */
20
20
  journal?: boolean;
21
+ /**
22
+ * Apply the tool output gate (caps output toward model context). Default true.
23
+ * Structured consumers (UI snapshots) pass false and cap on their own terms —
24
+ * the gate cuts at a char budget and would slice parse records mid-stream.
25
+ */
26
+ applyOutputGate?: boolean;
21
27
  }
22
28
  export interface AllowlistedRunResult {
23
29
  stdout: string;
@@ -51,6 +51,7 @@ export async function runAllowlistedArgv(options) {
51
51
  allowRoots: [cwd, ...journalRoots],
52
52
  networkPolicy: context?.networkPolicy ?? 'deny',
53
53
  requireJail: context?.requireJail,
54
+ disableJail: context?.disableJail,
54
55
  homeWrite: context?.homeWrite,
55
56
  noteSecurityDegraded: context?.noteSecurityDegraded,
56
57
  signal: context?.abortSignal,
@@ -59,6 +60,38 @@ export async function runAllowlistedArgv(options) {
59
60
  maxOutputBytes: 16 * 1024 * 1024,
60
61
  },
61
62
  });
63
+ // ops P2 §7:统一动作记录(allowlisted exec 同契约;P3 提权通道复用此形态)
64
+ try {
65
+ const { isJailBackend } = await import('../../execution-environment/process-isolation.js');
66
+ context?.recordOpsEvent?.({
67
+ event: 'ops.command.executed',
68
+ data: {
69
+ tool: 'allowlisted_run',
70
+ argv: [executable, ...args],
71
+ cwd,
72
+ exitCode: sandboxResult.exitCode,
73
+ durationMs: sandboxResult.usage.elapsedMs,
74
+ escalated: false,
75
+ // 子步执行的确认态由所属工具的效应闸门承担,本层无从得知——记 null(未知),
76
+ // 不用 false/true 冒充
77
+ confirmed: null,
78
+ confirmSource: 'not-gated-here',
79
+ jail: {
80
+ backend: sandboxResult.isolation.backend,
81
+ unconfined: context?.disableJail === true || !isJailBackend(sandboxResult.isolation.backend),
82
+ },
83
+ originAttributed: Boolean(context?.sessionId),
84
+ origin: {
85
+ sessionId: context?.sessionId,
86
+ agentId: context?.agentId,
87
+ runId: context?.runId ?? null,
88
+ },
89
+ },
90
+ });
91
+ }
92
+ catch {
93
+ // 审计回传失败不阻断业务结果(与下方 journal 同策略)
94
+ }
62
95
  // Journal after-diff (same contract as shell tool §5.6)
63
96
  try {
64
97
  const sj = await import('../../execution-environment/shell-journal.js');
@@ -83,6 +116,23 @@ export async function runAllowlistedArgv(options) {
83
116
  catch {
84
117
  // Journal failure must not drop the business result (matches shell tool).
85
118
  }
119
+ if (options.applyOutputGate === false) {
120
+ // Structured consumers cap on their own terms (parse, then slice). The only
121
+ // stream cut left is the sandbox output cap, which kills the process *before*
122
+ // appending the offending chunk — so length heuristics cannot see it; the
123
+ // honest signal is the terminate reason (verified in sandbox.ts).
124
+ return {
125
+ stdout: sandboxResult.stdout,
126
+ stderr: sandboxResult.stderr,
127
+ exitCode: sandboxResult.exitCode,
128
+ durationMs: sandboxResult.usage.elapsedMs,
129
+ truncated: sandboxResult.terminated && sandboxResult.terminateReason === 'Output size limit exceeded',
130
+ rawStdoutLength: sandboxResult.stdout.length,
131
+ terminated: sandboxResult.terminated,
132
+ terminateReason: sandboxResult.terminateReason,
133
+ isolation: sandboxResult.isolation,
134
+ };
135
+ }
86
136
  try {
87
137
  const { applyToolOutputGate, resolveSupportBinding } = await import('../../../context/capabilities/summary/index.js');
88
138
  const binding = resolveSupportBinding('shell', undefined, 8000);
@@ -4,7 +4,9 @@
4
4
  * 通过工厂函数接收 AskUserCallback(闭包注入),与 UI 层解耦。
5
5
  * 回调持有「等回答」的 Promise;Gateway/UI 提供答案后工具才返回。
6
6
  *
7
- * 超时在此自强制(definition.timeoutMs 仅作声明,工具总线不代为执行)。
7
+ * 无超时(2026-10-26 拍板):需要用户确认的问题不能被时间自动跳过。
8
+ * 退出只有两路:会话中止(abortSignal)或 Gateway 取消(ASK_USER_CANCELLED 哨兵)。
9
+ * definition 不声明 timeoutMs,工具总线(runWithToolLimits)因此不设看门狗。
8
10
  */
9
11
  import type { RegisteredTool } from '@octopi-agent/core/types.js';
10
12
  /** askUser 回调上下文(绑定到具体会话) */
@@ -27,8 +29,5 @@ export declare const ASK_USER_CANCELLED = "__ask_user_cancelled__";
27
29
  * 创建 ask_user 工具
28
30
  *
29
31
  * @param callback - 等待用户回答的回调(通常由 Gateway 挂 pending question)
30
- * @param options.timeoutMs - 等待上限;超时返回错误而不是悬挂
31
32
  */
32
- export declare function createAskUserTool(callback: AskUserCallback, options?: {
33
- timeoutMs?: number;
34
- }): RegisteredTool;
33
+ export declare function createAskUserTool(callback: AskUserCallback): RegisteredTool;