@octopi-agent/engine 0.102.10 → 0.121.10

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 (317) hide show
  1. package/dist/builtin-model-info.js +28 -7
  2. package/dist/config-admin/agent-presets.d.ts +32 -0
  3. package/dist/config-admin/agent-presets.js +133 -0
  4. package/dist/config-admin/discover.d.ts +33 -4
  5. package/dist/config-admin/discover.js +101 -6
  6. package/dist/config-admin/env.d.ts +11 -0
  7. package/dist/config-admin/env.js +41 -0
  8. package/dist/config-admin/error-copy.d.ts +106 -0
  9. package/dist/config-admin/error-copy.js +287 -0
  10. package/dist/config-admin/i18n.d.ts +21 -0
  11. package/dist/config-admin/i18n.js +19 -0
  12. package/dist/config-admin/index.d.ts +6 -2
  13. package/dist/config-admin/index.js +3 -1
  14. package/dist/config-admin/model-presets.d.ts +14 -0
  15. package/dist/config-admin/model-presets.js +595 -70
  16. package/dist/config-admin/onboarding-apply.d.ts +71 -0
  17. package/dist/config-admin/onboarding-apply.js +235 -0
  18. package/dist/config-admin/onboarding.d.ts +154 -0
  19. package/dist/config-admin/onboarding.js +270 -0
  20. package/dist/config-admin/redact.d.ts +42 -9
  21. package/dist/config-admin/redact.js +69 -5
  22. package/dist/config-schema/agent.d.ts +5 -1
  23. package/dist/config-schema/agent.js +20 -2
  24. package/dist/config-schema/browser.d.ts +62 -0
  25. package/dist/config-schema/browser.js +89 -0
  26. package/dist/config-schema/context.d.ts +7 -2
  27. package/dist/config-schema/context.js +6 -3
  28. package/dist/config-schema/engine.d.ts +86 -7
  29. package/dist/config-schema/engine.js +9 -2
  30. package/dist/config-schema/governance.d.ts +12 -1
  31. package/dist/config-schema/governance.js +10 -2
  32. package/dist/config-schema/models.d.ts +12 -8
  33. package/dist/config-schema/models.js +16 -1
  34. package/dist/config-schema/run.d.ts +4 -0
  35. package/dist/config-schema/run.js +10 -0
  36. package/dist/config-schema/shared.d.ts +1 -0
  37. package/dist/config-schema/shared.js +4 -2
  38. package/dist/config-schema/substrate.d.ts +5 -0
  39. package/dist/config-schema/substrate.js +8 -0
  40. package/dist/config.d.ts +116 -10
  41. package/dist/config.js +109 -13
  42. package/dist/file-mode.d.ts +67 -0
  43. package/dist/file-mode.js +182 -0
  44. package/dist/fork-child.d.ts +82 -0
  45. package/dist/fork-child.js +123 -0
  46. package/dist/harness/activation/delegated-run.d.ts +42 -0
  47. package/dist/harness/activation/delegated-run.js +71 -0
  48. package/dist/harness/activation/dispatcher.js +4 -0
  49. package/dist/harness/activation/index.d.ts +1 -0
  50. package/dist/harness/activation/run-backend.d.ts +92 -0
  51. package/dist/harness/activation/run-backend.js +16 -0
  52. package/dist/harness/activation/run-protocol.d.ts +392 -0
  53. package/dist/harness/activation/run-protocol.js +19 -0
  54. package/dist/harness/activation/runtime.d.ts +33 -0
  55. package/dist/harness/activation/runtime.js +119 -28
  56. package/dist/harness/activation/types.d.ts +19 -2
  57. package/dist/harness/agent/builder.d.ts +12 -0
  58. package/dist/harness/agent/builder.js +78 -22
  59. package/dist/harness/agent/config-bridge.d.ts +10 -1
  60. package/dist/harness/agent/config-bridge.js +15 -3
  61. package/dist/harness/agent/registered-tool-adapter.d.ts +27 -0
  62. package/dist/harness/agent/registered-tool-adapter.js +67 -0
  63. package/dist/harness/agent/wire-agent-builder.d.ts +2 -0
  64. package/dist/harness/agent/wire-agent-builder.js +9 -2
  65. package/dist/harness/capabilities/document/backends/plain.js +2 -1
  66. package/dist/harness/capabilities/document/legacy/factory.js +3 -2
  67. package/dist/harness/collaboration/autonomous-subsystem/audit/reader.d.ts +17 -0
  68. package/dist/harness/collaboration/autonomous-subsystem/audit/reader.js +66 -36
  69. package/dist/harness/collaboration/autonomous-subsystem/audit/writer.d.ts +6 -2
  70. package/dist/harness/collaboration/autonomous-subsystem/audit/writer.js +27 -7
  71. package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.js +13 -0
  72. package/dist/harness/collaboration/autonomous-subsystem/loader.js +1 -0
  73. package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +11 -0
  74. package/dist/harness/collaboration/autonomous-subsystem/runtime.js +17 -0
  75. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.d.ts +13 -3
  76. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.js +48 -39
  77. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +3 -0
  78. package/dist/harness/collaboration/autonomous-subsystem/types.d.ts +4 -0
  79. package/dist/harness/collaboration/delegation/child-run.d.ts +9 -0
  80. package/dist/harness/collaboration/delegation/child-run.js +34 -2
  81. package/dist/harness/collaboration/delegation/registry-types.d.ts +2 -0
  82. package/dist/harness/collaboration/delegation/service.d.ts +9 -4
  83. package/dist/harness/collaboration/delegation/service.js +33 -12
  84. package/dist/harness/collaboration/delegation/store.d.ts +2 -0
  85. package/dist/harness/collaboration/delegation/store.js +1 -0
  86. package/dist/harness/collaboration/delegation/types.d.ts +11 -0
  87. package/dist/harness/collaboration/delegation/wiring.d.ts +2 -0
  88. package/dist/harness/collaboration/delegation/wiring.js +1 -0
  89. package/dist/harness/context/capabilities/compact/engine.d.ts +44 -5
  90. package/dist/harness/context/capabilities/compact/engine.js +127 -39
  91. package/dist/harness/context/capabilities/compact/index.d.ts +2 -1
  92. package/dist/harness/context/capabilities/compact/index.js +1 -1
  93. package/dist/harness/context/capabilities/compact/types.d.ts +59 -9
  94. package/dist/harness/context/capabilities/summary/gate.d.ts +19 -2
  95. package/dist/harness/context/capabilities/summary/gate.js +53 -6
  96. package/dist/harness/context/capabilities/summary/registry.js +20 -0
  97. package/dist/harness/context/capabilities/summary/tool-binding.js +16 -12
  98. package/dist/harness/context/capabilities/summary/tool-bindings.d.ts +13 -0
  99. package/dist/harness/context/capabilities/summary/tool-bindings.js +22 -0
  100. package/dist/harness/context/capabilities/summary/types.d.ts +16 -0
  101. package/dist/harness/context/constitution/default-agents.md +85 -0
  102. package/dist/harness/context/context-size-ledger.js +8 -1
  103. package/dist/harness/context/default-context-engine.d.ts +100 -6
  104. package/dist/harness/context/default-context-engine.js +382 -89
  105. package/dist/harness/context/index.d.ts +2 -1
  106. package/dist/harness/context/index.js +1 -0
  107. package/dist/harness/context/layer-health.d.ts +4 -0
  108. package/dist/harness/context/layer-health.js +4 -0
  109. package/dist/harness/context/layer-types.d.ts +57 -0
  110. package/dist/harness/context/layer-types.js +73 -1
  111. package/dist/harness/context/layers.d.ts +3 -0
  112. package/dist/harness/context/layers.js +13 -6
  113. package/dist/harness/context/prefix-fingerprint.d.ts +46 -0
  114. package/dist/harness/context/prefix-fingerprint.js +52 -0
  115. package/dist/harness/context/summarize.js +18 -0
  116. package/dist/harness/context/system-prompt-assembler.d.ts +2 -0
  117. package/dist/harness/context/system-prompt-assembler.js +5 -2
  118. package/dist/harness/context/tool-result-aging.d.ts +104 -16
  119. package/dist/harness/context/tool-result-aging.js +211 -57
  120. package/dist/harness/context/types.d.ts +71 -4
  121. package/dist/harness/context/types.js +25 -1
  122. package/dist/harness/extension/execution-environment/effect-policy.d.ts +4 -3
  123. package/dist/harness/extension/execution-environment/effect-policy.js +2 -2
  124. package/dist/harness/extension/execution-environment/privileged-exec.js +4 -1
  125. package/dist/harness/extension/execution-environment/workspace.js +1 -1
  126. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +27 -1
  127. package/dist/harness/extension/plugin-ecosystem/channel-types.js +11 -2
  128. package/dist/harness/extension/plugin-ecosystem/client-tools/registry.d.ts +12 -0
  129. package/dist/harness/extension/plugin-ecosystem/client-tools/registry.js +25 -0
  130. package/dist/harness/extension/plugin-ecosystem/commands/builtin.js +28 -1
  131. package/dist/harness/extension/plugin-ecosystem/index.d.ts +1 -0
  132. package/dist/harness/extension/plugin-ecosystem/index.js +1 -0
  133. package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +168 -1
  134. package/dist/harness/extension/plugin-ecosystem/plugins/api.js +156 -15
  135. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-instances.d.ts +95 -0
  136. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-instances.js +170 -0
  137. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-kinds.d.ts +178 -0
  138. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-kinds.js +314 -0
  139. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.d.ts +40 -5
  140. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.js +45 -26
  141. package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +1 -1
  142. package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +11 -1
  143. package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +42 -76
  144. package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +30 -1
  145. package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +46 -0
  146. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +9 -0
  147. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +19 -14
  148. package/dist/harness/extension/plugin-ecosystem/plugins/staging.d.ts +3 -1
  149. package/dist/harness/extension/plugin-ecosystem/plugins/staging.js +1 -1
  150. package/dist/harness/extension/plugin-ecosystem/tools/browser-types.d.ts +333 -0
  151. package/dist/harness/extension/plugin-ecosystem/tools/browser-types.js +16 -0
  152. package/dist/harness/extension/plugin-ecosystem/tools/browser.d.ts +64 -0
  153. package/dist/harness/extension/plugin-ecosystem/tools/browser.js +692 -0
  154. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +0 -37
  155. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +108 -4
  156. package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +18 -0
  157. package/dist/harness/extension/plugin-ecosystem/tools/file-edit.js +34 -0
  158. package/dist/harness/extension/plugin-ecosystem/tools/file-search.d.ts +0 -6
  159. package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +57 -4
  160. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +81 -13
  161. package/dist/harness/extension/plugin-ecosystem/tools/http.js +5 -0
  162. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.js +13 -7
  163. package/dist/harness/extension/plugin-ecosystem/tools/package-tools.js +126 -14
  164. package/dist/harness/extension/plugin-ecosystem/tools/platform.d.ts +1 -1
  165. package/dist/harness/extension/plugin-ecosystem/tools/platform.js +44 -5
  166. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +10 -24
  167. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.d.ts +7 -0
  168. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.js +4 -0
  169. package/dist/harness/governance/credentials/db.d.ts +9 -0
  170. package/dist/harness/governance/credentials/db.js +122 -31
  171. package/dist/harness/governance/credentials/store.d.ts +68 -7
  172. package/dist/harness/governance/credentials/store.js +177 -64
  173. package/dist/harness/governance/credentials/types.d.ts +13 -2
  174. package/dist/harness/governance/index.d.ts +1 -0
  175. package/dist/harness/governance/index.js +1 -0
  176. package/dist/harness/governance/registry/db.d.ts +32 -0
  177. package/dist/harness/governance/registry/db.js +142 -0
  178. package/dist/harness/governance/registry/index.d.ts +9 -0
  179. package/dist/harness/governance/registry/index.js +9 -0
  180. package/dist/harness/governance/registry/service.d.ts +381 -0
  181. package/dist/harness/governance/registry/service.js +825 -0
  182. package/dist/harness/governance/registry/types.d.ts +77 -0
  183. package/dist/harness/governance/registry/types.js +7 -0
  184. package/dist/harness/governance/security/default-security-guard.d.ts +3 -0
  185. package/dist/harness/governance/security/default-security-guard.js +12 -1
  186. package/dist/harness/governance/security/risk-evaluator.d.ts +13 -3
  187. package/dist/harness/governance/security/risk-evaluator.js +307 -21
  188. package/dist/harness/governance/security/shell-parser-treesitter.js +12 -4
  189. package/dist/harness/governance/session-acl/tool-rights.d.ts +1 -0
  190. package/dist/harness/index.d.ts +5 -3
  191. package/dist/harness/index.js +2 -2
  192. package/dist/harness/knowledge/boot-config.d.ts +2 -0
  193. package/dist/harness/knowledge/boot-config.js +2 -0
  194. package/dist/harness/knowledge/client.d.ts +53 -7
  195. package/dist/harness/knowledge/client.js +77 -20
  196. package/dist/harness/knowledge/db.d.ts +16 -0
  197. package/dist/harness/knowledge/db.js +107 -41
  198. package/dist/harness/knowledge/engine-thread.js +5 -7
  199. package/dist/harness/knowledge/grounding.js +4 -1
  200. package/dist/harness/knowledge/http-app.d.ts +15 -0
  201. package/dist/harness/knowledge/http-app.js +82 -21
  202. package/dist/harness/knowledge/http-bridge.d.ts +15 -0
  203. package/dist/harness/knowledge/http-bridge.js +19 -0
  204. package/dist/harness/knowledge/knowledge-serve-child.js +2 -3
  205. package/dist/harness/knowledge/query-service.d.ts +12 -2
  206. package/dist/harness/knowledge/query-service.js +75 -41
  207. package/dist/harness/knowledge/query-worker-client.d.ts +5 -1
  208. package/dist/harness/knowledge/query-worker-client.js +4 -1
  209. package/dist/harness/knowledge/query-worker.js +5 -3
  210. package/dist/harness/knowledge/read-http.d.ts +2 -0
  211. package/dist/harness/knowledge/read-http.js +9 -2
  212. package/dist/harness/knowledge/retriever.d.ts +1 -1
  213. package/dist/harness/knowledge/retriever.js +1 -2
  214. package/dist/harness/knowledge/serve.d.ts +6 -1
  215. package/dist/harness/knowledge/serve.js +5 -6
  216. package/dist/harness/knowledge/source-store.d.ts +101 -5
  217. package/dist/harness/knowledge/source-store.js +297 -71
  218. package/dist/harness/knowledge/start-service-process.d.ts +27 -8
  219. package/dist/harness/knowledge/start-service-process.js +49 -90
  220. package/dist/harness/knowledge/tenant-gate.d.ts +81 -0
  221. package/dist/harness/knowledge/tenant-gate.js +167 -0
  222. package/dist/harness/knowledge/writer-service.d.ts +18 -2
  223. package/dist/harness/knowledge/writer-service.js +80 -16
  224. package/dist/harness/knowledge/writer-worker-client.d.ts +9 -2
  225. package/dist/harness/knowledge/writer-worker-client.js +20 -3
  226. package/dist/harness/knowledge/writer-worker.js +11 -4
  227. package/dist/harness/memory/backfill-trigger.d.ts +10 -3
  228. package/dist/harness/memory/backfill-trigger.js +19 -19
  229. package/dist/harness/memory/cognition-seeds.d.ts +45 -0
  230. package/dist/harness/memory/cognition-seeds.js +67 -0
  231. package/dist/harness/memory/cognition.d.ts +12 -3
  232. package/dist/harness/memory/cognition.js +55 -35
  233. package/dist/harness/memory/conceptualizer.d.ts +11 -1
  234. package/dist/harness/memory/conceptualizer.js +10 -1
  235. package/dist/harness/memory/context-slice.d.ts +42 -0
  236. package/dist/harness/memory/context-slice.js +197 -0
  237. package/dist/harness/memory/health-probe.d.ts +8 -2
  238. package/dist/harness/memory/health-probe.js +10 -13
  239. package/dist/harness/memory/index.d.ts +5 -1
  240. package/dist/harness/memory/index.js +3 -1
  241. package/dist/harness/memory/sqlite/agent-db.d.ts +1 -0
  242. package/dist/harness/memory/sqlite/agent-db.js +9 -8
  243. package/dist/harness/memory/sqlite/cognition-store.d.ts +26 -3
  244. package/dist/harness/memory/sqlite/cognition-store.js +103 -45
  245. package/dist/harness/memory/sqlite/memory-store.js +4 -0
  246. package/dist/harness/memory/sqlite/sqlite-vec.d.ts +24 -1
  247. package/dist/harness/memory/sqlite/sqlite-vec.js +37 -1
  248. package/dist/harness/memory/types.d.ts +18 -2
  249. package/dist/harness/observability/observer/hub.d.ts +10 -0
  250. package/dist/harness/observability/observer/hub.js +95 -2
  251. package/dist/harness/run/agent/agent.js +3 -2
  252. package/dist/harness/run/concurrency/tool-validator.js +4 -3
  253. package/dist/harness/run/reliability/run-agent.d.ts +22 -0
  254. package/dist/harness/run/reliability/run-agent.js +79 -10
  255. package/dist/harness/run/run-host.d.ts +302 -0
  256. package/dist/harness/run/run-host.js +978 -0
  257. package/dist/harness/run/run-scope.d.ts +11 -0
  258. package/dist/harness/run/run-scope.js +19 -1
  259. package/dist/harness/run/runner.d.ts +149 -22
  260. package/dist/harness/run/runner.js +352 -35
  261. package/dist/harness/session/in-memory-store.js +13 -1
  262. package/dist/harness/session/schedules/service.d.ts +10 -2
  263. package/dist/harness/session/schedules/service.js +13 -2
  264. package/dist/harness/session/tasks/tools.js +12 -0
  265. package/dist/harness/session/types.d.ts +10 -14
  266. package/dist/harness/shared/events/agent-event-map.d.ts +29 -0
  267. package/dist/harness/shared/types/agent-definition.d.ts +6 -0
  268. package/dist/index.d.ts +3 -2
  269. package/dist/index.js +2 -1
  270. package/dist/integration/agent-runtime/channel-message-source.d.ts +3 -1
  271. package/dist/integration/agent-runtime/channel-message-source.js +4 -3
  272. package/dist/integration/browser/camoufox.d.ts +40 -0
  273. package/dist/integration/browser/camoufox.js +80 -0
  274. package/dist/integration/browser/index.d.ts +91 -0
  275. package/dist/integration/browser/index.js +110 -0
  276. package/dist/integration/browser/install.d.ts +47 -0
  277. package/dist/integration/browser/install.js +214 -0
  278. package/dist/integration/browser/playwright.d.ts +224 -0
  279. package/dist/integration/browser/playwright.js +925 -0
  280. package/dist/integration/browser/service.d.ts +41 -0
  281. package/dist/integration/browser/service.js +181 -0
  282. package/dist/integration/browser/stealth.d.ts +42 -0
  283. package/dist/integration/browser/stealth.js +104 -0
  284. package/dist/integration/providers/anthropic-message-normalize.d.ts +20 -0
  285. package/dist/integration/providers/anthropic-message-normalize.js +48 -0
  286. package/dist/integration/providers/anthropic.js +27 -2
  287. package/dist/integration/providers/fetch-timeout.d.ts +17 -0
  288. package/dist/integration/providers/fetch-timeout.js +24 -0
  289. package/dist/integration/providers/openai.d.ts +8 -0
  290. package/dist/integration/providers/openai.js +41 -1
  291. package/dist/integration/providers/wire-dump-diff.js +2 -1
  292. package/dist/integration/providers/wire-dump.d.ts +56 -2
  293. package/dist/integration/providers/wire-dump.js +119 -6
  294. package/dist/integration/storage/archive-manager.d.ts +14 -2
  295. package/dist/integration/storage/archive-manager.js +24 -8
  296. package/dist/integration/storage/atomic-tmp.d.ts +12 -0
  297. package/dist/integration/storage/atomic-tmp.js +36 -0
  298. package/dist/integration/storage/jsonl.d.ts +9 -0
  299. package/dist/integration/storage/jsonl.js +137 -38
  300. package/dist/integration/storage/session-index.d.ts +5 -0
  301. package/dist/integration/storage/session-index.js +25 -4
  302. package/dist/integration/tools/assemble.d.ts +50 -0
  303. package/dist/integration/tools/assemble.js +137 -0
  304. package/dist/paths.d.ts +18 -0
  305. package/dist/paths.js +36 -0
  306. package/dist/subsystems/cognition-steward/conceptualize/config.yaml +3 -1
  307. package/dist/subsystems/cognition-steward/conceptualize/handler.js +74 -5
  308. package/dist/subsystems/cognition-steward/consolidate/SUBSYSTEM.md +3 -2
  309. package/dist/subsystems/cognition-steward/consolidate/config.yaml +11 -2
  310. package/dist/subsystems/cognition-steward/consolidate/handler.d.ts +6 -3
  311. package/dist/subsystems/cognition-steward/consolidate/handler.js +266 -28
  312. package/dist/subsystems/memory-steward/backfill/handler.js +3 -2
  313. package/dist/subsystems/memory-steward/govern/config.yaml +6 -1
  314. package/dist/subsystems/wisdom-steward/attribute/config.yaml +5 -1
  315. package/dist/subsystems/wisdom-steward/formation/config.yaml +3 -0
  316. package/dist/subsystems/wisdom-steward/govern/config.yaml +6 -1
  317. package/package.json +5 -3
@@ -0,0 +1,978 @@
1
+ /**
2
+ * RunHost — run 实例侧执行宿主(arch/service-topology.md §4「P0b 落地形态」)。
3
+ *
4
+ * 持有 run 侧全部运行时态:挂载槽、in-flight 计数、退役回收、会话锁、准入闸门执行、
5
+ * 审批/客户端工具跨通道配对、compact 解析(P0a 迁移注记清偿:控制面只传键,
6
+ * systemPrompt/tools/摘要绑定在此从 run 侧自身状态解析)。
7
+ *
8
+ * 内核自 gateway 的 InProcessRunBackend 搬入(行为冻结;原搬迁自 gateway.ts 的
9
+ * agentCache/retiredRunners/runnerInflight/wrapInflightTracking/retireRunner 语义不变)。
10
+ * gateway 脚手架以子类形态过渡到 P0b 步骤 5 删除;远程实现(run-serve-child)直接
11
+ * 以本类为执行核。
12
+ *
13
+ * 语义边界(触发面/执行面分离,§5.4):本类只做执行面;触发面(AgentRuntime /
14
+ * TriggerSource)永远在 gateway 进程。inbox 重投等需要触发面的动作经
15
+ * `notify('redispatch')` 回 gateway,本类不内嵌任何常驻触发器。
16
+ */
17
+ import { randomUUID } from 'node:crypto';
18
+ import { SessionRunnerDispatcher } from '../activation/index.js';
19
+ import { InRunCompactUnavailable } from './runner.js';
20
+ import { isTurnInput } from '../context/layer-types.js';
21
+ import { InProcessSessionLock } from './concurrency/session-lease.js';
22
+ import { registeredToolToAgentTool } from '../agent/registered-tool-adapter.js';
23
+ /** 会话 metadata 的模型绑定读取(与 gateway.readSessionModelId 同式,禁手抄) */
24
+ function readSessionModelId(metadata) {
25
+ const raw = metadata?.model;
26
+ if (typeof raw === 'string' && raw.trim())
27
+ return raw.trim();
28
+ if (raw && typeof raw === 'object') {
29
+ const obj = raw;
30
+ if (typeof obj.model === 'string' && obj.model) {
31
+ return typeof obj.provider === 'string' && obj.provider
32
+ ? `${obj.provider}/${obj.model}`
33
+ : obj.model;
34
+ }
35
+ }
36
+ return null;
37
+ }
38
+ export class RunHost {
39
+ sessionLock;
40
+ opts;
41
+ mounted = new Map();
42
+ /** 脉搏注册表(P0c A′):key → 进程内驱动入口 + 自述元数据(gateway 单发驱动) */
43
+ pulseFire = new Map();
44
+ pulseSpecs = new Map();
45
+ buildInFlight = new Map();
46
+ retiredRunners = [];
47
+ runnerInflight = new WeakMap();
48
+ activeRuns = new Map();
49
+ pendingApprovals = new Map();
50
+ pendingClientCalls = new Map();
51
+ visibilitySnapshot = {
52
+ installed: [],
53
+ live: [],
54
+ // 初始即过期:未收到首个快照前客户端工具一律不可见(fail-safe,宁缺勿滥)
55
+ expiresAt: 0,
56
+ };
57
+ /** 客户端工具现况注册表(B3:mount 晚于 setClientTools 时重放;add 同名覆盖) */
58
+ clientToolRegistry = new Map();
59
+ knowledgeState = 'starting';
60
+ constructor(options) {
61
+ this.opts = options;
62
+ this.sessionLock = options.sessionLock ?? new InProcessSessionLock();
63
+ }
64
+ mount(spec) {
65
+ if (this.mounted.has(spec.agentId)) {
66
+ // fail-loud:重复挂载说明调用方漏了 retire(旧 Runner 会泄漏 timer/订阅)
67
+ throw new Error(`run_backend: agent "${spec.agentId}" already mounted (retire first)`);
68
+ }
69
+ const inner = new SessionRunnerDispatcher({
70
+ runner: spec.runner,
71
+ redispatch: (trigger, options) => this.opts.redispatch(trigger, options),
72
+ // 不要把 agent 默认 model 写入 defaults:
73
+ // RunConfig.model 只表示**消息级**覆盖;会话覆盖在 session.metadata.model
74
+ runConfigDefaults: spec.runConfigDefaults,
75
+ });
76
+ const handle = {
77
+ agentId: spec.agentId,
78
+ agent: spec.agent,
79
+ ...(spec.contextEngine === undefined ? {} : { contextEngine: spec.contextEngine }),
80
+ ...(spec.contextHealth === undefined ? {} : { contextHealth: spec.contextHealth }),
81
+ registerTools: spec.registerTools,
82
+ dispatcher: this.wrapInflightTracking(spec.runner, inner),
83
+ };
84
+ this.mounted.set(spec.agentId, { handle, runner: spec.runner });
85
+ // 脉搏注册(P0c A′):重复 key = 装配 bug,fail-loud
86
+ for (const p of spec.pulses ?? []) {
87
+ if (this.pulseFire.has(p.spec.key)) {
88
+ throw new Error(`run_backend: duplicate pulse key "${p.spec.key}"`);
89
+ }
90
+ this.pulseFire.set(p.spec.key, p.fire);
91
+ this.pulseSpecs.set(p.spec.key, p.spec);
92
+ }
93
+ // B3:客户端工具重放——setClientTools 可能早于首个 mount(WS 注册工具后用户才发
94
+ // 首条消息)。注册表现况补挂进新 agent;谓词对非注册工具恒放行,不影响常规工具面。
95
+ if (this.clientToolRegistry.size > 0) {
96
+ this.applyClientTools([...this.clientToolRegistry.values()].map((tool) => ({ op: 'add', tool })), this.buildVisibilityPredicate());
97
+ }
98
+ else {
99
+ // 可选调用:测试桩/最小 agent 面可不实现可见性过滤(谓词缺省=全放行等价)
100
+ spec.agent.setToolVisibilityFilter?.(this.buildVisibilityPredicate());
101
+ }
102
+ return handle;
103
+ }
104
+ get(agentId) {
105
+ return this.mounted.get(agentId)?.handle;
106
+ }
107
+ /**
108
+ * 消息路径 get-or-mount(gateway.getOrMountHandle 同语义):未挂载则经
109
+ * buildMountSpec 钩子构建+挂载;同 agent 并发首建单飞合流。
110
+ *
111
+ * 语义基线(B1):并发请求全部成功;竞态败者回收自己的构建产物、复用胜者句柄;
112
+ * 其余 mount 错误如实上抛(fail-loud)。
113
+ *
114
+ * @param agentId - agent id
115
+ * @param definition - agent 定义(纯数据;透传构建钩子)
116
+ * @returns 句柄(保证已挂载)
117
+ */
118
+ ensureMounted(agentId, definition) {
119
+ const existing = this.mounted.get(agentId);
120
+ if (existing)
121
+ return Promise.resolve(existing.handle);
122
+ const inFlight = this.buildInFlight.get(agentId);
123
+ if (inFlight)
124
+ return inFlight;
125
+ const build = this.opts.buildMountSpec;
126
+ if (!build) {
127
+ return Promise.reject(new Error('not_implemented: run_host buildMountSpec not wired (ensureMounted)'));
128
+ }
129
+ const task = (async () => {
130
+ const spec = await build(agentId, definition);
131
+ try {
132
+ return this.mount(spec);
133
+ }
134
+ catch (err) {
135
+ // mount 失败回收构建产物(防后台 timer 泄漏);竞态败者复用胜者,其余错误照抛
136
+ try {
137
+ spec.runner.dispose();
138
+ }
139
+ catch {
140
+ // 回收失败不掩盖原始错误
141
+ }
142
+ const winner = this.mounted.get(agentId);
143
+ if (winner)
144
+ return winner.handle;
145
+ throw err;
146
+ }
147
+ })();
148
+ this.buildInFlight.set(agentId, task);
149
+ const clear = () => {
150
+ if (this.buildInFlight.get(agentId) === task)
151
+ this.buildInFlight.delete(agentId);
152
+ };
153
+ void task.then(clear, clear);
154
+ return task;
155
+ }
156
+ handles() {
157
+ return [...this.mounted.values()].map((m) => m.handle);
158
+ }
159
+ mountedAgentIds() {
160
+ return [...this.mounted.keys()];
161
+ }
162
+ retire(agentId) {
163
+ const m = this.mounted.get(agentId);
164
+ if (!m)
165
+ return;
166
+ this.mounted.delete(agentId);
167
+ // 该执行体的脉搏随退役拆除(key 带 agentId 前缀)
168
+ for (const key of [...this.pulseFire.keys()]) {
169
+ if (key.startsWith(`${agentId}:`)) {
170
+ this.pulseFire.delete(key);
171
+ this.pulseSpecs.delete(key);
172
+ }
173
+ }
174
+ this.retireRunner(m.runner);
175
+ }
176
+ execute(req, signal) {
177
+ const m = this.mounted.get(req.agentId);
178
+ if (!m) {
179
+ // fail-loud:未装载即调用方违例(须先 mount;不静默空转、不返回假成功)
180
+ throw new Error(`run_backend: agent "${req.agentId}" not mounted`);
181
+ }
182
+ return m.handle.dispatcher.execute(req, signal);
183
+ }
184
+ /**
185
+ * 契约执行入口(§4):execute + 按会话登记 AbortController(control 'abort' 的目标)。
186
+ * 并发同会话调用不在此拦(E1/E2 互斥由 sessionLock 排队语义承接;abort 作用于该
187
+ * 会话全部在途 controller)。
188
+ *
189
+ * @param req - run 请求(纯数据)
190
+ * @param signal - 外部中止信号(委派子 run 的 D4 本地投影;合流到本 run 的 controller)
191
+ * @returns 协议事件流
192
+ */
193
+ startRun(req, signal) {
194
+ const controller = new AbortController();
195
+ let set = this.activeRuns.get(req.sessionId);
196
+ if (!set) {
197
+ set = new Set();
198
+ this.activeRuns.set(req.sessionId, set);
199
+ }
200
+ set.add(controller);
201
+ const onExternalAbort = () => controller.abort(signal?.reason);
202
+ if (signal) {
203
+ if (signal.aborted)
204
+ controller.abort(signal.reason);
205
+ else
206
+ signal.addEventListener('abort', onExternalAbort, { once: true });
207
+ }
208
+ let iter;
209
+ try {
210
+ iter = this.execute(req, controller.signal);
211
+ }
212
+ catch (err) {
213
+ // 同步错(未挂载等):摘外部监听 + 摘在途登记再上抛(否则按失败请求累积泄漏);
214
+ // 保持同步抛 = 契约错误表面「未装载等同步错直接 4xx」不变
215
+ signal?.removeEventListener('abort', onExternalAbort);
216
+ set.delete(controller);
217
+ if (set.size === 0)
218
+ this.activeRuns.delete(req.sessionId);
219
+ throw err;
220
+ }
221
+ const self = this;
222
+ return (async function* () {
223
+ try {
224
+ yield* iter;
225
+ }
226
+ finally {
227
+ signal?.removeEventListener('abort', onExternalAbort);
228
+ const s = self.activeRuns.get(req.sessionId);
229
+ s?.delete(controller);
230
+ if (s && s.size === 0)
231
+ self.activeRuns.delete(req.sessionId);
232
+ }
233
+ })();
234
+ }
235
+ /**
236
+ * 控制 op 统一入口(契约 `control` 的 run 侧执行面)。
237
+ * 错误表面:失败一律进 `RunControlResponse` 的 `ok:false`(远程层映射 HTTP 4xx),
238
+ * 不静默吞。
239
+ *
240
+ * @param op - 纯数据控制 op
241
+ * @returns 执行结果
242
+ */
243
+ async handleControl(op) {
244
+ try {
245
+ switch (op.type) {
246
+ case 'abort': {
247
+ const set = this.activeRuns.get(op.sessionId);
248
+ if (set) {
249
+ for (const controller of set) {
250
+ controller.abort(op.reason ?? 'aborted');
251
+ }
252
+ }
253
+ // 幂等:无在途 run 也成功(stop 按钮连点语义)
254
+ return { ok: true };
255
+ }
256
+ case 'sessionAppendMessage': {
257
+ // 与 Runner.handle 共 sessionLock(E1/E2):无锁写入会被下一次增量同步判为
258
+ // 「漂移」而整包抹掉(2026-11-04 定位的语义,随写路径迁入)
259
+ const writer = this.requireSessionWriter();
260
+ const release = await this.sessionLock.acquire(op.sessionId);
261
+ try {
262
+ const session = await writer.load(op.sessionId);
263
+ if (!session)
264
+ return { ok: true };
265
+ session.messages.push(op.message);
266
+ session.meta.updatedAt = Date.now();
267
+ await writer.save(op.sessionId, session);
268
+ return { ok: true };
269
+ }
270
+ finally {
271
+ release();
272
+ }
273
+ }
274
+ case 'truncateMessagesFrom': {
275
+ return await this.truncateMessagesFrom(op.sessionId, op.fromIndex);
276
+ }
277
+ case 'askUserReply': {
278
+ const pending = this.pendingAsks.get(op.askId);
279
+ if (!pending) {
280
+ return { ok: false, error: { message: `run_host: unknown askId "${op.askId}"` } };
281
+ }
282
+ this.pendingAsks.delete(op.askId);
283
+ if (op.outcome.ok)
284
+ pending.resolve(op.outcome.answer);
285
+ else
286
+ pending.reject(new Error(op.outcome.error.message));
287
+ return { ok: true };
288
+ }
289
+ case 'approvalReply': {
290
+ const resolve = this.pendingApprovals.get(op.approvalId);
291
+ if (!resolve) {
292
+ return { ok: false, error: { message: `run_host: unknown approvalId "${op.approvalId}"` } };
293
+ }
294
+ this.pendingApprovals.delete(op.approvalId);
295
+ resolve(op.result);
296
+ return { ok: true };
297
+ }
298
+ case 'clientToolResult': {
299
+ const resolve = this.pendingClientCalls.get(op.callId);
300
+ if (!resolve) {
301
+ return { ok: false, error: { message: `run_host: unknown callId "${op.callId}"` } };
302
+ }
303
+ this.pendingClientCalls.delete(op.callId);
304
+ resolve(op.outcome);
305
+ return { ok: true };
306
+ }
307
+ case 'compact': {
308
+ // 手动压缩双通路(方案 A,2026-11-20 拍板):run 进行中 =「主动压缩立即
309
+ // 触发」——请求进活跃 run、下一个消息缝执行同一条 compact 路径(同保护/
310
+ // 同摘要/同 transform 记录),不排 session 锁(持锁排队 = run 结束才执行,
311
+ // 恰是要修的意图落空)。run 空闲 → 照旧锁路径(FIFO 立即执行)。
312
+ const m = this.mounted.get(op.agentId);
313
+ if (m && this.activeRuns.has(op.sessionId)) {
314
+ try {
315
+ const result = await this.resolveAndCompact(op.sessionId, op.agentId, m, (options) => m.runner.requestInRunCompact(op.sessionId, op.agentId, options));
316
+ return { ok: true, result };
317
+ }
318
+ catch (err) {
319
+ if (!(err instanceof InRunCompactUnavailable))
320
+ throw err;
321
+ // 竞态:判活跃后 run 恰已收尾 → 落回锁路径(此时锁空闲,立即执行)
322
+ }
323
+ }
324
+ const result = await this.compactSession(op.sessionId, op.agentId);
325
+ return { ok: true, result };
326
+ }
327
+ case 'reloadAgent': {
328
+ const build = this.requireBuildMountSpec();
329
+ this.retire(op.agentId);
330
+ const spec = await build(op.agentId, op.definition);
331
+ this.mount(spec);
332
+ return { ok: true };
333
+ }
334
+ case 'retireAgent': {
335
+ this.retire(op.agentId);
336
+ return { ok: true };
337
+ }
338
+ case 'setClientTools': {
339
+ this.visibilitySnapshot = op.visibility;
340
+ const ops = op.ops.map((o) => o.op === 'add'
341
+ ? ({ op: 'add', tool: this.materializeClientTool(o.tool) })
342
+ : ({ op: 'remove', name: o.name }));
343
+ // B3:注册表现况登记(mount 晚于本 op 时按表重放)
344
+ for (const change of ops) {
345
+ if (change.op === 'add') {
346
+ this.clientToolRegistry.set(change.tool.definition.name, change.tool);
347
+ }
348
+ else {
349
+ this.clientToolRegistry.delete(change.name);
350
+ }
351
+ }
352
+ this.applyClientTools(ops, this.buildVisibilityPredicate());
353
+ return { ok: true };
354
+ }
355
+ case 'syncKnowledgeState': {
356
+ this.knowledgeState = op.state;
357
+ return { ok: true };
358
+ }
359
+ case 'inboxOffer': {
360
+ // 协调面「插话」跨进程入口:目标 agent 未挂载 = 本实例无活跃 Run 可接
361
+ //(get-or-mount 语义下未挂载即无会话活跃面)→ 'dispatched',调用方照常
362
+ // dispatch 新 Run。挂载了则 offer 进其 SessionInbox(原 Trigger 随行,
363
+ // Run 关闭未消费时由 inbox 回调 redispatch 重投)。
364
+ const m = this.mounted.get(op.agentId);
365
+ const inbox = m?.handle.dispatcher.inbox;
366
+ if (!inbox) {
367
+ return { ok: true, result: { delivery: 'dispatched' } };
368
+ }
369
+ const delivery = inbox.offer({
370
+ agentId: op.agentId,
371
+ sessionId: op.sessionId,
372
+ entryId: op.entryId,
373
+ human: op.human,
374
+ triggerType: op.triggerType,
375
+ modelOverride: op.modelOverride,
376
+ modelProvider: op.modelProvider,
377
+ message: op.message,
378
+ trigger: op.trigger,
379
+ });
380
+ return { ok: true, result: { delivery: await delivery } };
381
+ }
382
+ case 'contextHealth': {
383
+ const m = op.agentId ? this.mounted.get(op.agentId) : undefined;
384
+ if (op.agentId && !m) {
385
+ return { ok: false, error: { message: `run_backend: agent "${op.agentId}" not mounted` } };
386
+ }
387
+ const probe = m?.handle.contextHealth;
388
+ if (!probe) {
389
+ return { ok: false, error: { message: 'run_host: context health probe not available' } };
390
+ }
391
+ return { ok: true, result: await probe(op.agentId) };
392
+ }
393
+ case 'reattestSecurity': {
394
+ if (!this.opts.reattestSecurity) {
395
+ return {
396
+ ok: false,
397
+ error: { message: 'run_host: reattestSecurity not wired (security guard missing)' },
398
+ };
399
+ }
400
+ const result = this.opts.reattestSecurity({
401
+ expectHash: op.expectHash,
402
+ allowedChanged: op.allowedChanged,
403
+ });
404
+ return { ok: true, result };
405
+ }
406
+ case 'pulse': {
407
+ // 脉搏单发(P0c A′):gateway 调度器驱动一次声明式 tick;未知 key fail-loud
408
+ const fire = this.pulseFire.get(op.key);
409
+ if (!fire) {
410
+ return { ok: false, error: { message: `run_host: unknown pulse key "${op.key}"` } };
411
+ }
412
+ await fire();
413
+ return { ok: true, result: { pulsed: op.key } };
414
+ }
415
+ }
416
+ // 未识别 op:fail-loud(静默吞会让调用方误以为已执行)
417
+ return {
418
+ ok: false,
419
+ error: { message: `run_host: unknown control op "${op.type}"` },
420
+ };
421
+ }
422
+ catch (err) {
423
+ return {
424
+ ok: false,
425
+ error: {
426
+ message: err instanceof Error ? err.message : String(err),
427
+ ...(err instanceof Error && err.name ? { name: err.name } : {}),
428
+ },
429
+ };
430
+ }
431
+ }
432
+ /**
433
+ * 审批请求(pluginManager approval sink 与装配 requestApproval 的远程形态入口):
434
+ * 注册配对并经 notify 出港;回执由 control 'approvalReply' 解配对。
435
+ *
436
+ * @param input - 审批请求载荷(RunApprovalRequestInput 形状)
437
+ * @returns 审批结果
438
+ */
439
+ askApproval(input) {
440
+ const approvalId = `ap-${randomUUID()}`;
441
+ return new Promise((resolve, reject) => {
442
+ this.pendingApprovals.set(approvalId, resolve);
443
+ try {
444
+ this.notify({ type: 'approval_request', approvalId, input });
445
+ }
446
+ catch (err) {
447
+ this.pendingApprovals.delete(approvalId);
448
+ reject(err);
449
+ }
450
+ });
451
+ }
452
+ /** ask_user 跨通道配对(问句经 notify 出港,作答经 control 'askUserReply' 解配对) */
453
+ pendingAsks = new Map();
454
+ /**
455
+ * ask_user 提问(AskUserCallback 的远程形态入口):注册配对并经 notify 出港。
456
+ * 回执 ok:false 时拒接 → 工具调用抛错(fail-loud,不吞失败)。
457
+ *
458
+ * @param input - 问句载荷
459
+ * @returns 用户作答
460
+ */
461
+ askQuestion(input) {
462
+ const askId = `ask-${randomUUID()}`;
463
+ return new Promise((resolve, reject) => {
464
+ this.pendingAsks.set(askId, { resolve, reject });
465
+ try {
466
+ this.notify({
467
+ type: 'ask_user_request',
468
+ askId,
469
+ sessionId: input.sessionId,
470
+ agentId: input.agentId,
471
+ question: input.question,
472
+ ...(input.options === undefined ? {} : { options: input.options }),
473
+ });
474
+ }
475
+ catch (err) {
476
+ this.pendingAsks.delete(askId);
477
+ reject(err instanceof Error ? err : new Error(String(err)));
478
+ }
479
+ });
480
+ }
481
+ /**
482
+ * 把动态 client tool 同步进已 build 的 Agent(E5 下同 session 串行,无需锁 tool 列表)。
483
+ * handleControl('setClientTools') 与 in-process 直连路径共用本核心。
484
+ *
485
+ * @param ops - 工具增删(RegisteredTool 已就位)
486
+ * @param visibility - 会话 tool 面可见性谓词
487
+ */
488
+ applyClientTools(ops, visibility) {
489
+ for (const { handle } of this.mounted.values()) {
490
+ handle.agent.setToolVisibilityFilter(visibility);
491
+ if (ops.length === 0)
492
+ continue;
493
+ const current = handle.agent.tools;
494
+ let next = [...current];
495
+ for (const op of ops) {
496
+ if (op.op === 'add') {
497
+ next = next.filter((t) => t.name !== op.tool.definition.name);
498
+ next.push(registeredToolToAgentTool(op.tool));
499
+ }
500
+ else {
501
+ next = next.filter((t) => t.name !== op.name);
502
+ }
503
+ }
504
+ handle.agent.setTools(next);
505
+ }
506
+ }
507
+ compactSession(sessionId, agentId) {
508
+ const m = this.mounted.get(agentId);
509
+ if (!m) {
510
+ // fail-loud **同步抛**(契约错误表面两形态之一):未装载即调用方违例。
511
+ // 前置检查必须留在非 async 方法里——async 化会把同步抛降级为异步拒斥。
512
+ throw new Error(`run_backend: agent "${agentId}" not mounted`);
513
+ }
514
+ return this.resolveAndCompact(sessionId, agentId, m);
515
+ }
516
+ /**
517
+ * 截断会话消息(编辑重发唯一写路径;自 gateway.truncateMessagesFrom 迁入,行为冻结)。
518
+ * 校验:仅最后一轮中止、锚点为该 turn 用户输入;随后截断 + 租约下标收缩 +
519
+ * abortedTurn 清理 + 本轮文件效应逆放(用户手改保留)。
520
+ *
521
+ * @param sessionId - 会话 id
522
+ * @param fromIndex - 截断锚点(须等于 abortedTurn.userMessageIndex)
523
+ * @returns 控制响应(result = 消息数 + 文件效应逆放结果)
524
+ */
525
+ async truncateMessagesFrom(sessionId, fromIndex) {
526
+ const writer = this.requireSessionWriter();
527
+ const release = await this.sessionLock.acquire(sessionId);
528
+ try {
529
+ const session = await writer.load(sessionId);
530
+ if (!session) {
531
+ throw new Error(`Session "${sessionId}" not found`);
532
+ }
533
+ // 仅服务「最后一轮进行中 → 回到本轮起点」;效应是整轮 discard,不是按 index 定点回滚
534
+ const aborted = session.metadata?.abortedTurn;
535
+ const allowed = aborted && typeof aborted.userMessageIndex === 'number'
536
+ ? aborted.userMessageIndex
537
+ : undefined;
538
+ if (allowed === undefined || fromIndex !== allowed) {
539
+ throw new Error(`edit_resend_only_last_aborted_turn: fromIndex must equal abortedTurn.userMessageIndex`);
540
+ }
541
+ if (!Number.isInteger(fromIndex) || fromIndex < 0 || fromIndex > session.messages.length) {
542
+ throw new Error(`fromIndex out of range: ${fromIndex}`);
543
+ }
544
+ // 与 view 同口径的写路径守卫:截断锚点必须是该 turn 的用户输入。
545
+ // legacy/损坏的 abortedTurn 元数据可能指向引擎载体/notify,切在错误位置会把
546
+ // 真正的中止残片留在历史里,重发叠出重复用户轮
547
+ const anchor = session.messages[fromIndex];
548
+ if (!isTurnInput(anchor)) {
549
+ throw new Error(`edit_resend_only_last_aborted_turn: abortedTurn anchor is not a turn user message`);
550
+ }
551
+ session.messages = session.messages.slice(0, fromIndex);
552
+ // 租约下标必须随 messages 重写收缩,否则下一轮 LLM 窗口被裁空
553
+ if (typeof session.contextDetachIndex === 'number') {
554
+ session.contextDetachIndex = Math.min(session.contextDetachIndex, fromIndex);
555
+ }
556
+ session.meta.updatedAt = Date.now();
557
+ // abortedTurn 是 metadata 键:save 浅合并删不掉,必须 updateMetadata
558
+ await writer.save(sessionId, session);
559
+ await writer.patchMetadata(sessionId, (meta) => {
560
+ delete meta.abortedTurn;
561
+ });
562
+ // L3: edit-resend reverses this turn's agent file effects (user hand-edits survive)
563
+ const fileEffects = await writer.discardFileUndo(sessionId, session.primaryAgentId ?? session.agentId);
564
+ return { ok: true, result: { messageCount: session.messages.length, fileEffects } };
565
+ }
566
+ catch (err) {
567
+ return {
568
+ ok: false,
569
+ error: {
570
+ message: err instanceof Error ? err.message : String(err),
571
+ ...(err instanceof Error && err.name ? { name: err.name } : {}),
572
+ },
573
+ };
574
+ }
575
+ finally {
576
+ release();
577
+ }
578
+ }
579
+ /**
580
+ * 冒烟(健康门 §4.3,`POST /smoke`):逐 agent 装配热路径自检——工具面枚举 +
581
+ * 一次 no-LLM 应答(contextHealth)。**不是 run,不占 run 语义**。
582
+ *
583
+ * @returns 冒烟报告(逐项如实入 checks;聚合 ok = 有 agent 且全部通过)
584
+ */
585
+ async smoke() {
586
+ const agents = [];
587
+ for (const [agentId, m] of this.mounted) {
588
+ const checks = [];
589
+ const toolNames = m.handle.agent.tools.map((t) => t.name);
590
+ const toolCount = toolNames.length;
591
+ checks.push(toolCount > 0
592
+ ? { name: 'tools', ok: true, detail: toolNames.join(',') }
593
+ : { name: 'tools', ok: false, detail: 'empty tool surface' });
594
+ if (m.handle.contextHealth) {
595
+ try {
596
+ await m.handle.contextHealth(agentId);
597
+ checks.push({ name: 'contextHealth', ok: true });
598
+ }
599
+ catch (err) {
600
+ checks.push({
601
+ name: 'contextHealth',
602
+ ok: false,
603
+ detail: err instanceof Error ? err.message : String(err),
604
+ });
605
+ }
606
+ }
607
+ else {
608
+ // NIT-3:无 context engine 的 agent 没走到装配热路径——如实记 skipped,不算验证过
609
+ checks.push({
610
+ name: 'contextHealth',
611
+ ok: true,
612
+ detail: 'skipped: no context engine (assembly path not exercised on this agent)',
613
+ });
614
+ }
615
+ agents.push({ agentId, toolCount, checks });
616
+ }
617
+ return { ok: agents.length > 0 && agents.every((a) => a.checks.every((c) => c.ok)), agents };
618
+ }
619
+ async health() {
620
+ let inFlightRuns = 0;
621
+ for (const { runner } of this.mounted.values()) {
622
+ inFlightRuns += this.runnerInflight.get(runner) ?? 0;
623
+ }
624
+ return {
625
+ pulses: [...this.pulseSpecs.values()],
626
+ mountedAgents: this.mounted.size,
627
+ inFlightRuns,
628
+ retiredRunners: this.retiredRunners.length,
629
+ };
630
+ }
631
+ disposeAll() {
632
+ // F2:先中止在途 run 再收摊——否则 /runs 流拖到兜底硬杀,消费端经 m1 把
633
+ // 正常停机误报成截断失败。abort 让执行流走正常终态收束(aborted)。
634
+ for (const controllers of this.activeRuns.values()) {
635
+ for (const controller of controllers) {
636
+ try {
637
+ controller.abort(new Error('run_backend: host disposing'));
638
+ }
639
+ catch {
640
+ // stop 路径 fail-open,不阻断关闭
641
+ }
642
+ }
643
+ }
644
+ this.activeRuns.clear();
645
+ // 释放 Runner 后台 timer(BackfillTrigger / HealthProbe / SubsystemRuntime)
646
+ for (const { runner } of this.mounted.values()) {
647
+ try {
648
+ runner.dispose();
649
+ }
650
+ catch {
651
+ // stop 路径 fail-open,不阻断关闭
652
+ }
653
+ }
654
+ this.mounted.clear();
655
+ // 热失效退役 runner 兜底回收
656
+ for (const runner of this.retiredRunners.splice(0)) {
657
+ try {
658
+ runner.dispose();
659
+ }
660
+ catch {
661
+ // stop 路径 fail-open,不阻断关闭
662
+ }
663
+ }
664
+ }
665
+ /**
666
+ * compact 解析(P0a 迁移注记清偿):systemPrompt/tools/摘要绑定/进度双缝全部从
667
+ * run 侧自身状态解析,控制面只传键。搬移自 gateway.ts 手动压缩调用点(行为冻结)。
668
+ *
669
+ * @param sessionId - 会话 id
670
+ * @param agentId - compact 视图归属 agent(E4 键,调用方已消歧)
671
+ * @returns 压缩结果
672
+ */
673
+ async resolveAndCompact(sessionId, agentId, m, exec = (options) => m.runner.compactSession(sessionId, agentId, options)) {
674
+ const structural = m.handle.contextEngine;
675
+ if (!structural?.compactStructural) {
676
+ return {
677
+ ok: false,
678
+ compacted: false,
679
+ reason: 'context engine does not support structural compact',
680
+ tokensBefore: 0,
681
+ summarizeAttempted: false,
682
+ };
683
+ }
684
+ const providers = this.opts.providers;
685
+ if (!providers) {
686
+ throw new Error('not_implemented: run_host providers not wired (compact)');
687
+ }
688
+ const metadata = await this.opts.loadSessionMetadata?.(sessionId);
689
+ const modelRef = readSessionModelId(metadata);
690
+ const defModel = this.opts.resolveDefaultModel?.(agentId);
691
+ const { createProviderSummarize } = await import('../context/summarize.js');
692
+ const { resolveModelRef } = await import('./model/index.js');
693
+ let summarize;
694
+ const bound = modelRef
695
+ ? resolveModelRef(modelRef, {
696
+ providers,
697
+ defaultProvider: defModel?.provider,
698
+ isOverride: true,
699
+ })
700
+ : defModel
701
+ ? resolveModelRef(`${defModel.provider}/${defModel.model}`, {
702
+ providers,
703
+ isOverride: false,
704
+ })
705
+ : null;
706
+ if (bound) {
707
+ // 会话模型绑定(评审 F6):摘要必须走当前会话模型——丢了 modelName 会走 provider 默认
708
+ // 模型,既违背「走当前会话模型」拍板,也让同形前缀缓存(per provider+model)彻底失效
709
+ summarize = createProviderSummarize(bound.provider, {
710
+ model: bound.modelName,
711
+ maxOutputTokens: bound.maxOutputTokens,
712
+ });
713
+ }
714
+ // 请求口径计量原料(评审 B1,2026-11-08)与摘要请求工具面(2026-11-12):manual 压缩的
715
+ // before/after 与摘要前缀都必须与会话下一请求同源。工具面解析收口到 Runner
716
+ // (`resolveSessionLlmTools`:toolsForSession ∩ agentToolPolicy ∩ session ACL),
717
+ // 与 run 内 `runContext.tools` 同一漏斗——禁在此手抄,手抄会漂移成两份工具面,
718
+ // 摘要请求 tools 与原请求不同字节 → 前缀缓存从第一字节断开(评审 MAJ-3)。
719
+ // 老化策略必须与工具面同批取(同一漏斗):摘要前缀的 messages 半区依赖 toolAgers,
720
+ // 单独取 tools 会让摘要视图退回默认指针 → 前缀从第一条工具结果起分叉。
721
+ const surface = await m.runner.resolveSessionToolSurface(sessionId, agentId);
722
+ const manualTools = surface.tools;
723
+ // D1:与 handle 共用 Runner session 锁(E4 键);持久化走 Runner。
724
+ // 执行器可替换:锁路径(默认)与 in-run 消息缝路径(handleControl('compact'))
725
+ // 共用本解析段——两路的 systemPrompt/tools/摘要绑定/老化策略零漂移。
726
+ return exec({
727
+ systemPrompt: m.handle.agent.context.systemPrompt,
728
+ tools: manualTools,
729
+ compactStructural: (input) => structural.compactStructural({
730
+ sessionId: input.sessionId,
731
+ agentId: input.agentId,
732
+ messages: input.messages,
733
+ summarize: input.summarize,
734
+ compactTargetTokens: input.compactTargetTokens,
735
+ taskSnapshot: input.taskSnapshot,
736
+ systemPrompt: input.systemPrompt,
737
+ tools: input.tools,
738
+ loadCompactState: input.loadCompactState,
739
+ toolAgers: surface.toolAgers,
740
+ toolArgAgers: surface.toolArgAgers,
741
+ // 摘要请求窗口护栏(评审 F5):窗口/输出上限随会话模型绑定注入,防最满时压缩被 400
742
+ contextWindow: bound?.contextWindow,
743
+ maxOutputTokens: bound?.maxOutputTokens,
744
+ // F22:manual 路 cache-miss 旁路事件直采(Builder 合同是**双缝**:Hub timeline +
745
+ // gatewayBus→WS/store);onCompactEvent 由宿主接线该双缝(remote 形态转 notify)。
746
+ emit: (e) => {
747
+ this.opts.onCompactEvent?.({ ...e, sessionId: e.sessionId ?? sessionId });
748
+ },
749
+ // run 中止信号(F1):in-run 路随 run abort 取消摘要;锁路径无 run 时 undefined
750
+ signal: input.signal,
751
+ }),
752
+ summarize,
753
+ compactTargetTokens: this.opts.compactTargetTokens,
754
+ });
755
+ }
756
+ /**
757
+ * 退役 runner:in-flight 计数归零即 dispose;30min 长尾强制兜底(warn 后仍回收)。
758
+ *
759
+ * @param runner - 要退役的 runner
760
+ */
761
+ retireRunner(runner) {
762
+ this.retiredRunners.push(runner);
763
+ const tryDispose = () => {
764
+ const inflight = this.runnerInflight.get(runner) ?? 0;
765
+ if (inflight > 0) {
766
+ // 仍有 run 在旧构建上跑完(拍板语义:不抢锁、不断流)——稍后重查
767
+ const t = setTimeout(tryDispose, 5_000);
768
+ t.unref?.();
769
+ return;
770
+ }
771
+ this.disposeRetiredRunner(runner);
772
+ };
773
+ tryDispose();
774
+ const force = setTimeout(() => {
775
+ if (this.retiredRunners.includes(runner)) {
776
+ // 文案保留 [Gateway] 前缀:与旧版告警/运维 grep 兼容(模块已迁 backend,勿改前缀)
777
+ console.warn('[Gateway] retired runner force-disposed with runs possibly in-flight (>30min)');
778
+ this.disposeRetiredRunner(runner);
779
+ }
780
+ }, 30 * 60_000);
781
+ force.unref?.();
782
+ }
783
+ /**
784
+ * 退役 runner 回收(幂等;stop 兜底也走这里)。
785
+ *
786
+ * @param runner - 要回收的 runner
787
+ */
788
+ disposeRetiredRunner(runner) {
789
+ const idx = this.retiredRunners.indexOf(runner);
790
+ if (idx < 0)
791
+ return;
792
+ this.retiredRunners.splice(idx, 1);
793
+ this.runnerInflight.delete(runner);
794
+ try {
795
+ runner.dispose();
796
+ }
797
+ catch {
798
+ // 退役回收 fail-open:dispose 只清后台 timer,失败不阻断
799
+ }
800
+ }
801
+ /**
802
+ * 包装 dispatcher:execute 前过 run 起点准入闸门(ops P2 三件套),
803
+ * execute 期间维护 runner 的 in-flight run 计数(退役 dispose 判据)。
804
+ *
805
+ * @param runner - 计数/账本归属的 runner
806
+ * @param inner - 原 dispatcher
807
+ * @returns 包装后的 dispatcher(结构兼容 RunDispatcher)
808
+ */
809
+ wrapInflightTracking(runner, inner) {
810
+ const backend = this;
811
+ return {
812
+ inbox: inner.inbox,
813
+ execute(req, signal) {
814
+ // run 起点准入闸门(与安全配置漂移守卫同位):
815
+ // 被拒 run 不计入 in-flight(retireRunner 判据不受影响)。
816
+ const gate = backend.opts.admissionGate?.({
817
+ agentId: req.agentId,
818
+ sessionId: req.sessionId,
819
+ });
820
+ if (gate) {
821
+ // 三件套对齐(ops P2):与 security_config_drift / kill_switch_active 同待遇——
822
+ // 账本 + 观测 + run 通道报错。required 拒 run 是知识面故障下最响的事件,
823
+ // 不得只留用户侧报错(监控盲区/审计缺口)。
824
+ const origin = { agentId: req.agentId, sessionId: req.sessionId };
825
+ runner.recordAdmissionRefusal(gate.event, {
826
+ state: gate.state,
827
+ action: 'refuse_new_run',
828
+ reason: gate.error,
829
+ origin,
830
+ }, origin);
831
+ return (async function* () {
832
+ throw new Error(gate.error);
833
+ })();
834
+ }
835
+ backend.runnerInflight.set(runner, (backend.runnerInflight.get(runner) ?? 0) + 1);
836
+ const iter = inner.execute(req, signal);
837
+ return (async function* () {
838
+ try {
839
+ yield* iter;
840
+ }
841
+ finally {
842
+ // 完成 / 抛错 / 消费端提前 return 均收敛计数
843
+ backend.runnerInflight.set(runner, (backend.runnerInflight.get(runner) ?? 1) - 1);
844
+ }
845
+ })();
846
+ },
847
+ };
848
+ }
849
+ /**
850
+ * 客户端工具桥:wire spec → RegisteredTool(handler 跨通道配对执行)。
851
+ * 请求经 notify('client_tool_call') 出港,结果由 control 'clientToolResult' 解配对。
852
+ *
853
+ * @param spec - 线上工具形状(definition + source)
854
+ * @returns run 侧可执行工具
855
+ */
856
+ materializeClientTool(spec) {
857
+ return {
858
+ definition: spec.definition,
859
+ ...(spec.source === undefined ? {} : { source: spec.source }),
860
+ handler: (args, context) => {
861
+ // 方案 A 配套:工具面粘滞保留 schema,因此这里必须响亮拒绝「确认离线」的调用,
862
+ // 而不是挂到 TTL 超时(模型拿到可读错误即可换路,代价远小于重建前缀缓存)。
863
+ if (this.isClientToolConfirmedOffline(context.sessionId, spec.definition.name)) {
864
+ return Promise.resolve({
865
+ error: 'client_unavailable',
866
+ hint: `客户端工具 "${spec.definition.name}" 当前没有在线连接;该端重新连接后可重试`,
867
+ });
868
+ }
869
+ const callId = `ct-${randomUUID()}`;
870
+ return new Promise((resolve, reject) => {
871
+ const abortSignal = context.abortSignal;
872
+ let settled = false;
873
+ const onAbort = () => {
874
+ if (settled)
875
+ return;
876
+ settled = true;
877
+ this.pendingClientCalls.delete(callId);
878
+ // run 侧中止即通知 gateway 收掉执行腿(否则其 pending 挂到 TTL 过期);
879
+ // 通知失败不改写本地结局——中止已发生,gateway 侧由 TTL 兜底
880
+ try {
881
+ this.notify({ type: 'client_tool_cancel', callId, reason: 'run aborted' });
882
+ }
883
+ catch {
884
+ // swallow:中止路径没有更上层消费者可回告,结局由下方 resolve 表达
885
+ }
886
+ // 与 createClientTool 中止语义一致:LLM 可见 error 形结局,不静默悬挂
887
+ resolve({ error: 'cancelled', hint: 'run aborted while waiting for client tool' });
888
+ };
889
+ if (abortSignal?.aborted) {
890
+ onAbort();
891
+ return;
892
+ }
893
+ abortSignal?.addEventListener('abort', onAbort, { once: true });
894
+ this.pendingClientCalls.set(callId, (outcome) => {
895
+ if (settled)
896
+ return;
897
+ settled = true;
898
+ abortSignal?.removeEventListener('abort', onAbort);
899
+ if (outcome.ok)
900
+ resolve(outcome.result);
901
+ else
902
+ reject(new Error(outcome.error.message));
903
+ });
904
+ try {
905
+ this.notify({
906
+ type: 'client_tool_call',
907
+ callId,
908
+ sessionId: context.sessionId,
909
+ agentId: context.agentId,
910
+ toolName: spec.definition.name,
911
+ args,
912
+ messages: context.messages,
913
+ });
914
+ }
915
+ catch (err) {
916
+ if (settled)
917
+ return;
918
+ settled = true;
919
+ this.pendingClientCalls.delete(callId);
920
+ abortSignal?.removeEventListener('abort', onAbort);
921
+ reject(err instanceof Error ? err : new Error(String(err)));
922
+ }
923
+ });
924
+ },
925
+ };
926
+ }
927
+ /** 可见性谓词(快照求值;宿主 onBuilt 在构建期装到 agent 上) */
928
+ buildVisibilityPredicate() {
929
+ const snapshot = this.visibilitySnapshot;
930
+ // 方案 A(工具面粘滞):已安装的客户端工具对某会话**见过即永久可见**。
931
+ // liveness 抖动绝不改变 LLM 可见的 tools schema——`tools` 位于缓存前缀最前,
932
+ // 一次增删会让整段历史前缀失效(生产实测 70k–124k token 全价重算/次)。
933
+ // 客户端真的不在线时,由调用期返回 `client_unavailable`(响亮、可重试)。
934
+ // 快照过期同样不收缩工具面;过期只让调用期校验退化为「照常派发」。
935
+ const sticky = snapshot.everLive ?? snapshot.live;
936
+ return (sessionId, toolName) => {
937
+ if (!snapshot.installed.includes(toolName))
938
+ return true;
939
+ return sticky.some((e) => e.sessionId === sessionId && e.toolName === toolName);
940
+ };
941
+ }
942
+ /**
943
+ * 调用期 liveness 校验(方案 A 的配套):工具留在 schema 里,但真的没有 live
944
+ * provider 时立刻响亮失败,而不是挂到 TTL 超时。
945
+ *
946
+ * 快照过期 = liveness 未知 → 不阻断(交调用自身 TTL 兜底),避免误拒。
947
+ *
948
+ * @param sessionId - 会话 id
949
+ * @param toolName - 客户端工具名
950
+ * @returns true = 可信地不在线(拒绝调用)
951
+ */
952
+ isClientToolConfirmedOffline(sessionId, toolName) {
953
+ const snapshot = this.visibilitySnapshot;
954
+ if (Date.now() > snapshot.expiresAt)
955
+ return false;
956
+ if (!snapshot.installed.includes(toolName))
957
+ return false;
958
+ return !snapshot.live.some((e) => e.sessionId === sessionId && e.toolName === toolName);
959
+ }
960
+ requireSessionWriter() {
961
+ if (!this.opts.sessionWriter) {
962
+ throw new Error('not_implemented: run_host sessionWriter not wired (session write ops)');
963
+ }
964
+ return this.opts.sessionWriter;
965
+ }
966
+ requireBuildMountSpec() {
967
+ if (!this.opts.buildMountSpec) {
968
+ throw new Error('not_implemented: run_host buildMountSpec not wired (reloadAgent)');
969
+ }
970
+ return this.opts.buildMountSpec;
971
+ }
972
+ notify(n) {
973
+ if (!this.opts.notify) {
974
+ throw new Error(`not_implemented: run_host notify not wired (${n.type})`);
975
+ }
976
+ this.opts.notify(n);
977
+ }
978
+ }