@octopi-agent/engine 0.97.15 → 0.102.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 (369) hide show
  1. package/dist/config-schema/agent.d.ts +37 -5
  2. package/dist/config-schema/agent.js +24 -4
  3. package/dist/config-schema/context.d.ts +6 -36
  4. package/dist/config-schema/context.js +4 -28
  5. package/dist/config-schema/engine.d.ts +61 -160
  6. package/dist/config-schema/engine.js +1 -5
  7. package/dist/config-schema/governance.d.ts +10 -1
  8. package/dist/config-schema/governance.js +38 -1
  9. package/dist/config-schema/models.d.ts +2 -8
  10. package/dist/config-schema/models.js +0 -2
  11. package/dist/config-schema/run.d.ts +2 -2
  12. package/dist/config-schema/run.js +2 -2
  13. package/dist/config-schema/shared.d.ts +0 -3
  14. package/dist/config-schema/shared.js +0 -2
  15. package/dist/config-schema/substrate.d.ts +14 -88
  16. package/dist/config-schema/substrate.js +22 -107
  17. package/dist/config.d.ts +45 -113
  18. package/dist/config.js +8 -2
  19. package/dist/harness/activation/dispatcher.js +7 -0
  20. package/dist/harness/activation/inbox.d.ts +3 -3
  21. package/dist/harness/activation/inbox.js +3 -3
  22. package/dist/harness/activation/runtime.js +13 -5
  23. package/dist/harness/activation/types.d.ts +2 -2
  24. package/dist/harness/agent/builder.d.ts +34 -2
  25. package/dist/harness/agent/builder.js +189 -58
  26. package/dist/harness/agent/config-bridge.js +9 -2
  27. package/dist/harness/agent/config-integrity.d.ts +66 -0
  28. package/dist/harness/agent/config-integrity.js +108 -2
  29. package/dist/harness/agent/wire-agent-builder.d.ts +11 -3
  30. package/dist/harness/agent/wire-agent-builder.js +31 -7
  31. package/dist/harness/capabilities/document/factory.d.ts +5 -0
  32. package/dist/harness/capabilities/document/factory.js +1 -0
  33. package/dist/harness/capabilities/document/port.js +6 -3
  34. package/dist/harness/capabilities/document/types.d.ts +5 -0
  35. package/dist/harness/collaboration/autonomous-subsystem/index.d.ts +2 -2
  36. package/dist/harness/collaboration/autonomous-subsystem/index.js +1 -1
  37. package/dist/harness/collaboration/autonomous-subsystem/loader.js +4 -1
  38. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.d.ts +1 -1
  39. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.js +21 -4
  40. package/dist/harness/collaboration/autonomous-subsystem/sense/input-builder.js +4 -4
  41. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.d.ts +2 -2
  42. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.js +2 -2
  43. package/dist/harness/collaboration/autonomous-subsystem/signal/bus.d.ts +6 -0
  44. package/dist/harness/collaboration/autonomous-subsystem/signal/bus.js +25 -4
  45. package/dist/harness/collaboration/autonomous-subsystem/think/completion-guard.d.ts +40 -0
  46. package/dist/harness/collaboration/autonomous-subsystem/think/completion-guard.js +59 -0
  47. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +1 -1
  48. package/dist/harness/collaboration/autonomous-subsystem/think/index.d.ts +2 -0
  49. package/dist/harness/collaboration/autonomous-subsystem/think/index.js +1 -0
  50. package/dist/harness/collaboration/autonomous-subsystem/think/model-resolver.js +1 -1
  51. package/dist/harness/collaboration/autonomous-subsystem/types.d.ts +12 -3
  52. package/dist/harness/collaboration/delegation/child-run.d.ts +1 -1
  53. package/dist/harness/collaboration/delegation/child-run.js +4 -4
  54. package/dist/harness/collaboration/delegation/index.d.ts +1 -1
  55. package/dist/harness/collaboration/delegation/index.js +1 -1
  56. package/dist/harness/collaboration/delegation/notifier.d.ts +6 -1
  57. package/dist/harness/collaboration/delegation/notifier.js +8 -1
  58. package/dist/harness/collaboration/delegation/service.d.ts +2 -0
  59. package/dist/harness/collaboration/delegation/service.js +2 -1
  60. package/dist/harness/collaboration/delegation/store.d.ts +2 -0
  61. package/dist/harness/collaboration/delegation/store.js +2 -1
  62. package/dist/harness/collaboration/delegation/types.d.ts +23 -2
  63. package/dist/harness/collaboration/delegation/types.js +22 -0
  64. package/dist/harness/collaboration/delegation/wiring.js +11 -1
  65. package/dist/harness/context/budget-allocator.d.ts +26 -18
  66. package/dist/harness/context/budget-allocator.js +67 -32
  67. package/dist/harness/context/capabilities/compact/engine.d.ts +0 -6
  68. package/dist/harness/context/capabilities/compact/engine.js +169 -121
  69. package/dist/harness/context/capabilities/compact/handover.d.ts +5 -3
  70. package/dist/harness/context/capabilities/compact/handover.js +7 -5
  71. package/dist/harness/context/capabilities/compact/index.d.ts +5 -1
  72. package/dist/harness/context/capabilities/compact/index.js +4 -0
  73. package/dist/harness/context/capabilities/compact/mechanical.d.ts +130 -0
  74. package/dist/harness/context/capabilities/compact/mechanical.js +268 -0
  75. package/dist/harness/context/capabilities/compact/messages.d.ts +60 -0
  76. package/dist/harness/context/capabilities/compact/messages.js +91 -0
  77. package/dist/harness/context/capabilities/compact/types.d.ts +76 -11
  78. package/dist/harness/context/capabilities/compact/types.js +11 -1
  79. package/dist/harness/context/capabilities/compact/view-split.d.ts +36 -0
  80. package/dist/harness/context/capabilities/compact/view-split.js +72 -0
  81. package/dist/harness/context/capabilities/summary/port.js +0 -1
  82. package/dist/harness/context/capabilities/summary/resolver.d.ts +1 -1
  83. package/dist/harness/context/capabilities/summary/resolver.js +4 -9
  84. package/dist/harness/context/capabilities/summary/tool-binding.d.ts +1 -1
  85. package/dist/harness/context/capabilities/summary/types.d.ts +4 -7
  86. package/dist/harness/context/context-size-ledger.d.ts +143 -0
  87. package/dist/harness/context/context-size-ledger.js +236 -0
  88. package/dist/harness/context/default-context-engine.d.ts +195 -119
  89. package/dist/harness/context/default-context-engine.js +1241 -743
  90. package/dist/harness/context/index.d.ts +2 -2
  91. package/dist/harness/context/index.js +1 -1
  92. package/dist/harness/context/layer-types.d.ts +15 -0
  93. package/dist/harness/context/layer-types.js +14 -1
  94. package/dist/harness/context/layers.d.ts +16 -19
  95. package/dist/harness/context/layers.js +42 -14
  96. package/dist/harness/context/message-selector.d.ts +10 -8
  97. package/dist/harness/context/message-selector.js +49 -27
  98. package/dist/harness/context/summarize.d.ts +3 -3
  99. package/dist/harness/context/summarize.js +11 -4
  100. package/dist/harness/context/system-prompt-assembler.d.ts +4 -0
  101. package/dist/harness/context/system-prompt-assembler.js +3 -1
  102. package/dist/harness/context/token-constants.d.ts +8 -6
  103. package/dist/harness/context/token-constants.js +8 -7
  104. package/dist/harness/context/token-estimate-fns.d.ts +37 -27
  105. package/dist/harness/context/token-estimate-fns.js +85 -66
  106. package/dist/harness/context/token-estimator.d.ts +27 -12
  107. package/dist/harness/context/token-estimator.js +120 -66
  108. package/dist/harness/context/token-segments.d.ts +88 -0
  109. package/dist/harness/context/token-segments.js +103 -0
  110. package/dist/harness/context/tool-result-aging.d.ts +6 -1
  111. package/dist/harness/context/tool-result-aging.js +16 -5
  112. package/dist/harness/context/tool-result-body.js +2 -0
  113. package/dist/harness/context/transform/anchors.d.ts +66 -0
  114. package/dist/harness/context/transform/anchors.js +125 -0
  115. package/dist/harness/context/transform/fold.d.ts +56 -0
  116. package/dist/harness/context/transform/fold.js +135 -0
  117. package/dist/harness/context/transform/migrate.d.ts +41 -0
  118. package/dist/harness/context/transform/migrate.js +69 -0
  119. package/dist/harness/context/transform/types.d.ts +129 -0
  120. package/dist/harness/context/transform/types.js +19 -0
  121. package/dist/harness/context/turn-envelope.d.ts +6 -3
  122. package/dist/harness/context/types.d.ts +127 -117
  123. package/dist/harness/extension/execution-environment/effect-policy.d.ts +24 -2
  124. package/dist/harness/extension/execution-environment/effect-policy.js +30 -0
  125. package/dist/harness/extension/execution-environment/ops-audit.d.ts +7 -3
  126. package/dist/harness/extension/execution-environment/ops-audit.js +11 -12
  127. package/dist/harness/extension/execution-environment/resource-limits.d.ts +1 -1
  128. package/dist/harness/extension/execution-environment/resource-limits.js +1 -1
  129. package/dist/harness/extension/execution-environment/undo-log.d.ts +6 -2
  130. package/dist/harness/extension/execution-environment/undo-log.js +31 -10
  131. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +1 -1
  132. package/dist/harness/extension/plugin-ecosystem/commands/index.d.ts +3 -1
  133. package/dist/harness/extension/plugin-ecosystem/commands/index.js +1 -0
  134. package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.d.ts +12 -1
  135. package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.js +14 -4
  136. package/dist/harness/extension/plugin-ecosystem/commands/router.d.ts +5 -4
  137. package/dist/harness/extension/plugin-ecosystem/commands/router.js +23 -14
  138. package/dist/harness/extension/plugin-ecosystem/commands/types.d.ts +8 -1
  139. package/dist/harness/extension/plugin-ecosystem/commands/types.js +2 -1
  140. package/dist/harness/extension/plugin-ecosystem/hooks/adapter.d.ts +54 -0
  141. package/dist/harness/extension/plugin-ecosystem/hooks/adapter.js +397 -0
  142. package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.d.ts +16 -0
  143. package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.js +66 -0
  144. package/dist/harness/extension/plugin-ecosystem/hooks/index.d.ts +4 -0
  145. package/dist/harness/extension/plugin-ecosystem/hooks/index.js +2 -0
  146. package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.d.ts +11 -0
  147. package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.js +54 -0
  148. package/dist/harness/extension/plugin-ecosystem/hooks/journal.d.ts +9 -0
  149. package/dist/harness/extension/plugin-ecosystem/hooks/journal.js +22 -0
  150. package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.d.ts +12 -0
  151. package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.js +19 -0
  152. package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.d.ts +36 -0
  153. package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.js +338 -0
  154. package/dist/harness/extension/plugin-ecosystem/hooks/services.d.ts +24 -0
  155. package/dist/harness/extension/plugin-ecosystem/hooks/services.js +139 -0
  156. package/dist/harness/extension/plugin-ecosystem/hooks/types.d.ts +229 -0
  157. package/dist/harness/extension/plugin-ecosystem/hooks/types.js +1 -0
  158. package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +83 -249
  159. package/dist/harness/extension/plugin-ecosystem/plugins/api.js +88 -214
  160. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.d.ts +43 -0
  161. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.js +61 -0
  162. package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.d.ts +4 -0
  163. package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.js +18 -0
  164. package/dist/harness/extension/plugin-ecosystem/plugins/entry.d.ts +7 -85
  165. package/dist/harness/extension/plugin-ecosystem/plugins/entry.js +8 -50
  166. package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +6 -23
  167. package/dist/harness/extension/plugin-ecosystem/plugins/index.js +3 -23
  168. package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +50 -117
  169. package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +316 -285
  170. package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +23 -490
  171. package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +85 -353
  172. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +41 -223
  173. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +138 -19
  174. package/dist/harness/extension/plugin-ecosystem/plugins/staging.d.ts +15 -0
  175. package/dist/harness/extension/plugin-ecosystem/plugins/staging.js +15 -0
  176. package/dist/harness/extension/plugin-ecosystem/skills/manager.d.ts +6 -1
  177. package/dist/harness/extension/plugin-ecosystem/skills/manager.js +17 -1
  178. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +3 -0
  179. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +46 -21
  180. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +17 -24
  181. package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +18 -8
  182. package/dist/harness/extension/plugin-ecosystem/tools/document-tools.js +3 -9
  183. package/dist/harness/extension/plugin-ecosystem/tools/file-edit.js +3 -6
  184. package/dist/harness/extension/plugin-ecosystem/tools/file-ops.js +9 -5
  185. package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +9 -130
  186. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +122 -14
  187. package/dist/harness/extension/plugin-ecosystem/tools/package-tools.js +4 -13
  188. package/dist/harness/extension/plugin-ecosystem/tools/platform.d.ts +25 -11
  189. package/dist/harness/extension/plugin-ecosystem/tools/platform.js +168 -62
  190. package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.d.ts +11 -0
  191. package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.js +39 -0
  192. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.d.ts +1 -1
  193. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +11 -2
  194. package/dist/harness/governance/accounting/usage-ledger.d.ts +13 -1
  195. package/dist/harness/governance/accounting/usage-ledger.js +23 -1
  196. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +3 -3
  197. package/dist/harness/governance/human-in-the-loop/decision-cache.js +2 -2
  198. package/dist/harness/governance/security/capability-enforcer.js +1 -2
  199. package/dist/harness/governance/security/default-risk-policy.d.ts +1 -0
  200. package/dist/harness/governance/security/default-risk-policy.js +1 -0
  201. package/dist/harness/governance/security/default-security-guard.js +9 -0
  202. package/dist/harness/governance/security/index.d.ts +1 -0
  203. package/dist/harness/governance/security/index.js +2 -0
  204. package/dist/harness/governance/security/risk-evaluator.js +13 -0
  205. package/dist/harness/governance/security/risk-types.d.ts +12 -0
  206. package/dist/harness/governance/security/shell-parser-fallback.d.ts +29 -0
  207. package/dist/harness/governance/security/shell-parser-fallback.js +410 -0
  208. package/dist/harness/governance/security/shell-parser-shared.d.ts +83 -0
  209. package/dist/harness/governance/security/shell-parser-shared.js +188 -0
  210. package/dist/harness/governance/security/shell-parser-treesitter.d.ts +52 -0
  211. package/dist/harness/governance/security/shell-parser-treesitter.js +370 -0
  212. package/dist/harness/governance/security/shell-parser.d.ts +23 -10
  213. package/dist/harness/governance/security/shell-parser.js +37 -496
  214. package/dist/harness/governance/security/vendor/README.md +24 -0
  215. package/dist/harness/governance/security/vendor/tree-sitter-bash.LICENSE.txt +21 -0
  216. package/dist/harness/governance/security/vendor/tree-sitter-bash.wasm +0 -0
  217. package/dist/harness/index.d.ts +12 -12
  218. package/dist/harness/index.js +7 -7
  219. package/dist/harness/knowledge/boot-config.d.ts +55 -0
  220. package/dist/harness/knowledge/boot-config.js +50 -0
  221. package/dist/harness/knowledge/catalog-types.d.ts +2 -0
  222. package/dist/harness/knowledge/client.d.ts +24 -2
  223. package/dist/harness/knowledge/client.js +19 -5
  224. package/dist/harness/knowledge/db.js +5 -0
  225. package/dist/harness/knowledge/describe-sample.d.ts +23 -0
  226. package/dist/harness/knowledge/describe-sample.js +58 -0
  227. package/dist/harness/knowledge/describe.d.ts +8 -0
  228. package/dist/harness/knowledge/describe.js +18 -2
  229. package/dist/harness/knowledge/engine-thread.js +6 -0
  230. package/dist/harness/knowledge/grounding.js +3 -1
  231. package/dist/harness/knowledge/http-app.js +35 -4
  232. package/dist/harness/knowledge/http-params.d.ts +18 -0
  233. package/dist/harness/knowledge/http-params.js +24 -0
  234. package/dist/harness/knowledge/index.d.ts +2 -0
  235. package/dist/harness/knowledge/index.js +1 -0
  236. package/dist/harness/knowledge/knowledge-serve-child.js +3 -0
  237. package/dist/harness/knowledge/purge.js +5 -2
  238. package/dist/harness/knowledge/query-service.d.ts +13 -2
  239. package/dist/harness/knowledge/query-service.js +4 -2
  240. package/dist/harness/knowledge/query-worker-client.d.ts +9 -1
  241. package/dist/harness/knowledge/query-worker-client.js +4 -2
  242. package/dist/harness/knowledge/query-worker.js +4 -2
  243. package/dist/harness/knowledge/read-http.js +5 -1
  244. package/dist/harness/knowledge/serve.d.ts +8 -7
  245. package/dist/harness/knowledge/serve.js +9 -0
  246. package/dist/harness/knowledge/source-store.js +26 -3
  247. package/dist/harness/knowledge/start-service-process.d.ts +15 -7
  248. package/dist/harness/knowledge/start-service-process.js +21 -9
  249. package/dist/harness/knowledge/types.d.ts +7 -0
  250. package/dist/harness/knowledge/writer-service.d.ts +37 -9
  251. package/dist/harness/knowledge/writer-service.js +120 -14
  252. package/dist/harness/knowledge/writer-worker-client.d.ts +10 -9
  253. package/dist/harness/knowledge/writer-worker-client.js +20 -2
  254. package/dist/harness/knowledge/writer-worker.js +9 -1
  255. package/dist/harness/memory/index.d.ts +6 -2
  256. package/dist/harness/memory/index.js +4 -1
  257. package/dist/harness/memory/memory-events.d.ts +25 -0
  258. package/dist/harness/memory/memory-events.js +38 -0
  259. package/dist/harness/memory/sqlite/agent-db.js +15 -0
  260. package/dist/harness/memory/sqlite/wisdom-store.d.ts +7 -2
  261. package/dist/harness/memory/sqlite/wisdom-store.js +86 -12
  262. package/dist/harness/memory/steward-policy.d.ts +3 -0
  263. package/dist/harness/memory/steward-policy.js +1 -1
  264. package/dist/harness/memory/types.d.ts +47 -7
  265. package/dist/harness/memory/wisdom-attribution.d.ts +136 -0
  266. package/dist/harness/memory/wisdom-attribution.js +287 -0
  267. package/dist/harness/memory/wisdom-events.d.ts +37 -0
  268. package/dist/harness/memory/wisdom-events.js +61 -0
  269. package/dist/harness/memory/wisdom-formation.d.ts +31 -1
  270. package/dist/harness/memory/wisdom-formation.js +130 -33
  271. package/dist/harness/memory/wisdom-gates.d.ts +14 -0
  272. package/dist/harness/memory/wisdom-gates.js +59 -19
  273. package/dist/harness/memory/wisdom.d.ts +7 -2
  274. package/dist/harness/memory/wisdom.js +49 -2
  275. package/dist/harness/observability/observer/hub.js +25 -15
  276. package/dist/harness/observability/observer/types.d.ts +10 -6
  277. package/dist/harness/run/agent/agent.d.ts +40 -21
  278. package/dist/harness/run/agent/agent.js +66 -13
  279. package/dist/harness/run/agent/index.d.ts +1 -1
  280. package/dist/harness/run/budget/budget.d.ts +28 -10
  281. package/dist/harness/run/budget/budget.js +38 -15
  282. package/dist/harness/run/model/index.d.ts +3 -1
  283. package/dist/harness/run/model/index.js +2 -1
  284. package/dist/harness/run/model/resolver.d.ts +4 -1
  285. package/dist/harness/run/model/resolver.js +36 -2
  286. package/dist/harness/run/model/run-scope.d.ts +2 -0
  287. package/dist/harness/run/model/run-scope.js +7 -0
  288. package/dist/harness/run/model/types.d.ts +22 -5
  289. package/dist/harness/run/model/types.js +3 -2
  290. package/dist/harness/run/model/window-truth.d.ts +37 -0
  291. package/dist/harness/run/model/window-truth.js +39 -0
  292. package/dist/harness/run/reliability/context-length-feedback.d.ts +77 -0
  293. package/dist/harness/run/reliability/context-length-feedback.js +128 -0
  294. package/dist/harness/run/reliability/harness-events.d.ts +3 -3
  295. package/dist/harness/run/reliability/model-error-policy.js +4 -0
  296. package/dist/harness/run/reliability/run-agent.d.ts +10 -4
  297. package/dist/harness/run/reliability/run-agent.js +137 -53
  298. package/dist/harness/run/reliability/run-metrics-collector.d.ts +19 -8
  299. package/dist/harness/run/reliability/run-metrics-collector.js +38 -23
  300. package/dist/harness/run/run-guard/default-run-guard.js +8 -8
  301. package/dist/harness/run/run-scope.d.ts +41 -4
  302. package/dist/harness/run/runner.d.ts +71 -31
  303. package/dist/harness/run/runner.js +368 -106
  304. package/dist/harness/session/attachments/index.d.ts +1 -0
  305. package/dist/harness/session/attachments/index.js +1 -0
  306. package/dist/harness/session/attachments/inject.d.ts +21 -10
  307. package/dist/harness/session/attachments/inject.js +76 -24
  308. package/dist/harness/session/attachments/recall-index.d.ts +70 -0
  309. package/dist/harness/session/attachments/recall-index.js +219 -0
  310. package/dist/harness/session/attachments/service.d.ts +21 -0
  311. package/dist/harness/session/attachments/service.js +258 -139
  312. package/dist/harness/session/attachments/types.d.ts +6 -0
  313. package/dist/harness/session/transform-store.d.ts +136 -0
  314. package/dist/harness/session/transform-store.js +302 -0
  315. package/dist/harness/session/types.d.ts +2 -2
  316. package/dist/harness/shared/events/agent-event-map.d.ts +46 -13
  317. package/dist/harness/shared/events/agent-event-map.js +3 -2
  318. package/dist/harness/shared/events/scenario-events.d.ts +6 -6
  319. package/dist/harness/shared/paths/glob.d.ts +52 -0
  320. package/dist/harness/shared/paths/glob.js +218 -0
  321. package/dist/harness/shared/paths/index.d.ts +84 -0
  322. package/dist/harness/shared/paths/index.js +179 -0
  323. package/dist/harness/shared/types/agent-definition.d.ts +1 -2
  324. package/dist/index.d.ts +14 -17
  325. package/dist/index.js +7 -9
  326. package/dist/integration/observability/metrics.d.ts +6 -6
  327. package/dist/integration/observability/metrics.js +13 -13
  328. package/dist/integration/observability/observer-bridge.js +2 -2
  329. package/dist/integration/observability/trace-collector.d.ts +5 -5
  330. package/dist/integration/observability/trace-collector.js +34 -35
  331. package/dist/integration/observability/trace-events.d.ts +3 -3
  332. package/dist/integration/observability/trace-events.js +3 -3
  333. package/dist/integration/providers/anthropic.js +14 -1
  334. package/dist/integration/providers/openai.js +7 -1
  335. package/dist/integration/providers/usage.d.ts +1 -1
  336. package/dist/integration/providers/wire-dump.d.ts +1 -1
  337. package/dist/integration/storage/archive-manager.d.ts +6 -0
  338. package/dist/integration/storage/archive-manager.js +10 -0
  339. package/dist/integration/storage/jsonl.d.ts +1 -1
  340. package/dist/integration/storage/jsonl.js +18 -16
  341. package/dist/subsystems/cognition-steward/conceptualize/config.yaml +4 -2
  342. package/dist/subsystems/cognition-steward/conceptualize/handler.js +12 -20
  343. package/dist/subsystems/memory-steward/backfill/config.yaml +4 -2
  344. package/dist/subsystems/memory-steward/backfill/handler.js +44 -52
  345. package/dist/subsystems/wisdom-steward/attribute/SUBSYSTEM.md +24 -0
  346. package/dist/subsystems/wisdom-steward/attribute/config.yaml +60 -0
  347. package/dist/subsystems/wisdom-steward/attribute/handler.d.ts +23 -0
  348. package/dist/subsystems/wisdom-steward/attribute/handler.js +167 -0
  349. package/dist/subsystems/wisdom-steward/evaluate/handler.js +3 -1
  350. package/dist/subsystems/wisdom-steward/formation/SUBSYSTEM.md +8 -1
  351. package/dist/subsystems/wisdom-steward/formation/config.yaml +13 -5
  352. package/dist/subsystems/wisdom-steward/formation/handler.js +39 -23
  353. package/dist/subsystems/wisdom-steward/govern/config.yaml +1 -1
  354. package/dist/subsystems/wisdom-steward/govern/handler.js +4 -0
  355. package/package.json +16 -14
  356. package/dist/harness/context/hybrid-compressor.d.ts +0 -41
  357. package/dist/harness/context/hybrid-compressor.js +0 -159
  358. package/dist/harness/context/llm-summarizer.d.ts +0 -46
  359. package/dist/harness/context/llm-summarizer.js +0 -249
  360. package/dist/harness/context/smart-router.d.ts +0 -75
  361. package/dist/harness/context/smart-router.js +0 -118
  362. package/dist/harness/context/truncate-compressor.d.ts +0 -28
  363. package/dist/harness/context/truncate-compressor.js +0 -107
  364. package/dist/harness/extension/plugin-ecosystem/plugins/capability.d.ts +0 -97
  365. package/dist/harness/extension/plugin-ecosystem/plugins/capability.js +0 -155
  366. package/dist/harness/extension/plugin-ecosystem/plugins/hooks.d.ts +0 -7
  367. package/dist/harness/extension/plugin-ecosystem/plugins/hooks.js +0 -7
  368. package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.d.ts +0 -86
  369. package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.js +0 -139
@@ -0,0 +1,19 @@
1
+ const terminalMarker = Symbol('octopi.extension-terminal');
2
+ /** A Host-controlled extension failure must not enter the model transport retry policy. */
3
+ export class ExtensionTerminalError extends Error {
4
+ cause;
5
+ [terminalMarker] = true;
6
+ constructor(cause) {
7
+ super(cause instanceof Error ? cause.message : String(cause));
8
+ this.cause = cause;
9
+ this.name = 'ExtensionTerminalError';
10
+ }
11
+ }
12
+ /** This is a Host/reliability policy, not a Core or Plugin contract. */
13
+ export function shouldAbortWithoutRetry(error) {
14
+ return typeof error === 'object' && error !== null && terminalMarker in error;
15
+ }
16
+ /** Restore the extension failure to the normal Agent error-event surface. */
17
+ export function unwrapExtensionTerminalError(error) {
18
+ return error instanceof ExtensionTerminalError ? error.cause : error;
19
+ }
@@ -0,0 +1,36 @@
1
+ import type { AgentContext, AgentLoopConfig, BeforeToolCallContext } from '@octopi-agent/core/loop/types.js';
2
+ import type { RunScope } from '../../../run/run-scope.js';
3
+ import type { HarnessLoopEvent } from '../../../run/reliability/harness-events.js';
4
+ import type { ExtensionHookPort } from './types.js';
5
+ export interface AgentExtensionHookIntegration {
6
+ prepareToolArguments: AgentLoopConfig['prepareToolArguments'];
7
+ onToolCallComplete: AgentLoopConfig['onToolCallComplete'];
8
+ beforeStep: AgentLoopConfig['beforeStep'];
9
+ onStepComplete: AgentLoopConfig['onStepComplete'];
10
+ }
11
+ /** Per-Run mutable projections shared with Core's existing config callbacks. */
12
+ export declare class AgentExtensionHookState {
13
+ private readonly port;
14
+ private readonly scope;
15
+ readonly originalToolParams: WeakMap<import("@octopi-agent/core").ToolCall, Readonly<Record<string, unknown>>>;
16
+ private iterationSnapshots;
17
+ private readonly originalOnStepComplete;
18
+ private readonly originalBeforeStep;
19
+ private readonly originalTransformLlmMessages;
20
+ constructor(port: ExtensionHookPort, scope: () => RunScope, config: AgentLoopConfig);
21
+ /** Project only the normalized Provider request, never the Run's message workspace. */
22
+ transformLlmMessages(messages: import('@octopi-agent/core/interfaces/model-provider.js').LLMMessage[]): Promise<import('@octopi-agent/core/interfaces/model-provider.js').LLMMessage[]>;
23
+ callbacks(): AgentExtensionHookIntegration;
24
+ private context;
25
+ private prepareToolArguments;
26
+ private onToolCallComplete;
27
+ private beforeStep;
28
+ private prepareStep;
29
+ private onStepComplete;
30
+ }
31
+ /** Enriches Loop config with per-Run hook callbacks; no plugin type enters Core. */
32
+ export declare function integrateAgentHooks(port: ExtensionHookPort | undefined, config: AgentLoopConfig, scope: () => RunScope): AgentExtensionHookState | undefined;
33
+ /** Host Run-level Vote/Override/Observe, outside the reliability loop. */
34
+ export declare function withAgentRunHooks(port: ExtensionHookPort | undefined, scope: RunScope, context: AgentContext, signal: AbortSignal | undefined, gen: AsyncGenerator<HarnessLoopEvent>): AsyncGenerator<HarnessLoopEvent>;
35
+ /** Build the Host Run tool Vote after SecurityGuard and before raw execution. */
36
+ export declare function voteAgentToolCall(port: ExtensionHookPort | undefined, ctx: BeforeToolCallContext, originalParams: WeakMap<BeforeToolCallContext['toolCall'], Readonly<Record<string, unknown>>>, signal?: AbortSignal): Promise<import('@octopi-agent/core/loop/types.js').BeforeToolCallResult | undefined>;
@@ -0,0 +1,338 @@
1
+ import { getTextContent } from '@octopi-agent/core/types.js';
2
+ import { getRunScope } from '../../../run/run-scope.js';
3
+ import { HookDeniedError } from './adapter.js';
4
+ import { ExtensionTerminalError, shouldAbortWithoutRetry, unwrapExtensionTerminalError } from './policy-error.js';
5
+ /** Per-Run mutable projections shared with Core's existing config callbacks. */
6
+ export class AgentExtensionHookState {
7
+ port;
8
+ scope;
9
+ originalToolParams = new WeakMap();
10
+ iterationSnapshots = new Map();
11
+ originalOnStepComplete;
12
+ originalBeforeStep;
13
+ originalTransformLlmMessages;
14
+ constructor(port, scope, config) {
15
+ this.port = port;
16
+ this.scope = scope;
17
+ this.originalOnStepComplete = config.onStepComplete;
18
+ this.originalBeforeStep = config.beforeStep;
19
+ this.originalTransformLlmMessages = config.transformLlmMessages;
20
+ }
21
+ /** Project only the normalized Provider request, never the Run's message workspace. */
22
+ async transformLlmMessages(messages) {
23
+ const index = Math.max(0, (this.scope().iteration ?? 1) - 1);
24
+ const snapshot = this.iterationSnapshots.get(index);
25
+ const current = this.originalTransformLlmMessages
26
+ ? await this.originalTransformLlmMessages(messages)
27
+ : messages;
28
+ if (!snapshot)
29
+ return current;
30
+ const { projectPluginIterationSnapshot } = await import('./iteration-snapshot.js');
31
+ return projectPluginIterationSnapshot(current, snapshot.contributions, snapshot.tokenBudget);
32
+ }
33
+ callbacks() {
34
+ return {
35
+ prepareToolArguments: async (ctx, signal) => this.prepareToolArguments(ctx, signal),
36
+ onToolCallComplete: async (ctx) => this.onToolCallComplete(ctx),
37
+ beforeStep: async (ctx) => this.beforeStep(ctx),
38
+ onStepComplete: async (ctx) => {
39
+ // Finalize first: empty-reply/planning detection, step summaries, events and
40
+ // persistence must all see the finalized reply — not the raw model output.
41
+ await this.onStepComplete(ctx);
42
+ await this.originalOnStepComplete?.(ctx);
43
+ },
44
+ };
45
+ }
46
+ context(signal) {
47
+ const scope = this.scope();
48
+ return {
49
+ sessionId: scope.sessionId,
50
+ agentId: scope.agentId,
51
+ ...(scope.runId === undefined ? {} : { runId: scope.runId }),
52
+ ...(scope.principal === undefined ? {} : { principal: scope.principal }),
53
+ ...(signal === undefined ? {} : { signal }),
54
+ };
55
+ }
56
+ async prepareToolArguments(ctx, signal) {
57
+ // No registered handler → nothing to attribute; skip event construction and
58
+ // the Run-identity requirement (direct Agent.run() must keep working idle).
59
+ if (!this.port.hasHooks('before_tool_call'))
60
+ return ctx.args;
61
+ const scope = this.scope();
62
+ if (!scope.runId)
63
+ throw new Error('before_tool_call requires a Host Run identity');
64
+ if (ctx.args === null || typeof ctx.args !== 'object' || Array.isArray(ctx.args))
65
+ return ctx.args;
66
+ const original = ctx.args;
67
+ const result = await this.port.transformBeforeToolCall({
68
+ ...this.context(signal),
69
+ runId: scope.runId,
70
+ toolName: ctx.toolCall.name,
71
+ call: ctx.toolCall,
72
+ params: original,
73
+ });
74
+ this.originalToolParams.set(ctx.toolCall, { ...original });
75
+ const value = result.value;
76
+ if (value === null || typeof value !== 'object' || Array.isArray(value)) {
77
+ // Fail-closed for this call: tool validation, SecurityGuard and audit all
78
+ // inspect a plain parameter record; a non-record transform hides the payload.
79
+ throw new Error('before_tool_call transform must return a plain object of parameters');
80
+ }
81
+ return value;
82
+ }
83
+ async onToolCallComplete(ctx) {
84
+ if (!this.port.hasHooks('after_tool_call'))
85
+ return;
86
+ const scope = this.scope();
87
+ if (!scope.runId)
88
+ return;
89
+ const params = (ctx.args ?? {});
90
+ await this.port.observe('after_tool_call', {
91
+ ...this.context(),
92
+ runId: scope.runId,
93
+ call: ctx.toolCall,
94
+ originalParams: this.originalToolParams.get(ctx.toolCall) ?? params,
95
+ params,
96
+ result: ctx.result,
97
+ ...(ctx.result.isError ? { error: getTextContent(String(ctx.result.content ?? '')) } : {}),
98
+ });
99
+ }
100
+ async beforeStep(ctx) {
101
+ try {
102
+ return await this.prepareStep(ctx);
103
+ }
104
+ catch (error) {
105
+ throw new ExtensionTerminalError(error);
106
+ }
107
+ }
108
+ async prepareStep(ctx) {
109
+ const originalUpdate = await this.originalBeforeStep?.(ctx);
110
+ const scope = this.scope();
111
+ // Iteration bookkeeping also serves after_iteration observations: keep it
112
+ // outside the before_iteration short-circuit or the counter stays at 0.
113
+ scope.iteration = ctx.iteration + 1;
114
+ if (!this.port.hasHooks('before_iteration'))
115
+ return originalUpdate;
116
+ const currentModel = scope.resolvedModel;
117
+ if (!scope.runId || !currentModel)
118
+ throw new Error('before_iteration requires a resolved Host model and Run identity');
119
+ const result = await this.port.beforeIteration({
120
+ ...this.context(),
121
+ runId: scope.runId,
122
+ iteration: ctx.iteration,
123
+ messages: ctx.context.messages,
124
+ model: { provider: currentModel.providerName, model: currentModel.modelName },
125
+ thinking: scope.thinkingLevel,
126
+ });
127
+ if (result.vote.decision !== 'allow') {
128
+ throw new HookDeniedError(result.vote, 'before_iteration');
129
+ }
130
+ let resolved = currentModel;
131
+ if (result.transform.model) {
132
+ if (!scope.resolveConfiguredModel) {
133
+ throw new Error('before_iteration model Transform has no Host model resolver');
134
+ }
135
+ const next = await scope.resolveConfiguredModel(result.transform.model);
136
+ if (!next)
137
+ throw new Error(`before_iteration selected an unconfigured model: ${result.transform.model.provider}/${result.transform.model.model}`);
138
+ resolved = next;
139
+ }
140
+ scope.resolvedModel = resolved;
141
+ // Consensus transform: undefined means "no opinion", never "clear".
142
+ if (result.transform.thinking !== undefined)
143
+ scope.thinkingLevel = result.transform.thinking;
144
+ if (resolved !== currentModel) {
145
+ const { updateResolvedModel } = await import('../../../run/model/run-scope.js');
146
+ updateResolvedModel(resolved);
147
+ }
148
+ if (result.transform.snapshot !== undefined) {
149
+ this.iterationSnapshots.set(ctx.iteration, {
150
+ contributions: result.snapshotContributions.map((contribution) => ({
151
+ pluginId: contribution.pluginId,
152
+ text: contribution.value,
153
+ })),
154
+ tokenBudget: Math.max(1, Math.min(scope.extensionSnapshotBudgetTokens ?? 4096, Math.floor((resolved.contextWindow ?? 8192) * 0.1))),
155
+ });
156
+ }
157
+ else {
158
+ this.iterationSnapshots.delete(ctx.iteration);
159
+ }
160
+ return {
161
+ ...originalUpdate,
162
+ ...(resolved === currentModel ? {} : { model: resolved.provider }),
163
+ ...(result.transform.thinking === undefined ? {} : { thinkingLevel: result.transform.thinking }),
164
+ };
165
+ }
166
+ async onStepComplete(ctx) {
167
+ const wantsFinalize = this.port.hasHooks('before_agent_finalize');
168
+ const wantsObserve = this.port.hasHooks('after_iteration');
169
+ if (!wantsFinalize && !wantsObserve)
170
+ return;
171
+ const scope = this.scope();
172
+ // Finalize needs only the Run identity; after_iteration additionally reports
173
+ // the resolved model — separate gates so a missing model never silently
174
+ // swallows a registered finalize.
175
+ if (!scope.runId)
176
+ return;
177
+ if (wantsFinalize && !ctx.message.toolCalls?.length) {
178
+ const transformed = await this.port.transform('before_agent_finalize', {
179
+ ...this.context(),
180
+ runId: scope.runId,
181
+ reply: ctx.message,
182
+ }, ctx.message);
183
+ const next = transformed.value;
184
+ if (ctx.context.messages.lastIndexOf(ctx.message) < 0) {
185
+ throw new Error('before_agent_finalize candidate is absent from RunScope messages');
186
+ }
187
+ // Mutate in place only: the message store slot, the event copy and the loop's
188
+ // message must stay one identity. Replacing the slot with the plugin's object
189
+ // forks persistence from events and drops timestamp/metadata on the stored side.
190
+ Object.assign(ctx.message, next);
191
+ }
192
+ if (!wantsObserve || !scope.resolvedModel)
193
+ return;
194
+ await this.port.observe('after_iteration', {
195
+ ...this.context(),
196
+ runId: scope.runId,
197
+ iteration: Math.max(0, (scope.iteration ?? 1) - 1),
198
+ messages: ctx.context.messages,
199
+ model: { provider: scope.resolvedModel.providerName, model: scope.resolvedModel.modelName },
200
+ ...(scope.thinkingLevel === undefined ? {} : { thinking: scope.thinkingLevel }),
201
+ assistantMessage: ctx.context.messages.find((message) => message === ctx.message) ?? ctx.message,
202
+ toolResults: ctx.toolResults,
203
+ });
204
+ }
205
+ }
206
+ /** Enriches Loop config with per-Run hook callbacks; no plugin type enters Core. */
207
+ export function integrateAgentHooks(port, config, scope) {
208
+ if (!port)
209
+ return undefined;
210
+ return new AgentExtensionHookState(port, scope, config);
211
+ }
212
+ /** Host Run-level Vote/Override/Observe, outside the reliability loop. */
213
+ export async function* withAgentRunHooks(port, scope, context, signal, gen) {
214
+ if (!port) {
215
+ yield* gen;
216
+ return;
217
+ }
218
+ const startedAt = Date.now();
219
+ const runId = scope.runId ?? `unidentified:${scope.sessionId}:${scope.agentId}`;
220
+ const base = {
221
+ sessionId: scope.sessionId,
222
+ agentId: scope.agentId,
223
+ runId,
224
+ ...(scope.principal === undefined ? {} : { principal: scope.principal }),
225
+ ...(signal === undefined ? {} : { signal }),
226
+ };
227
+ let reason = 'completed';
228
+ let success = true;
229
+ let failure;
230
+ let iterations = 0;
231
+ try {
232
+ const prompt = scope.prompt ?? getTextContent([...context.messages].reverse().find((message) => message.role === 'user')?.content ?? '');
233
+ const runEvent = { ...base, runId, prompt, messages: context.messages };
234
+ const vote = await port.vote('before_agent_run', runEvent);
235
+ if (vote.decision !== 'allow')
236
+ throw new HookDeniedError(vote, 'before_agent_run');
237
+ const override = await port.override('before_agent_reply', runEvent);
238
+ if (override) {
239
+ const finalized = await port.transform('before_agent_finalize', { ...base, runId, reply: override }, override);
240
+ const reply = {
241
+ ...finalized.value,
242
+ agentId: finalized.value.agentId ?? scope.agentId,
243
+ timestamp: finalized.value.timestamp ?? Date.now(),
244
+ };
245
+ context.messages.push(reply);
246
+ yield { type: 'agent_start', timestamp: Date.now() };
247
+ yield { type: 'step_start', timestamp: Date.now() };
248
+ yield { type: 'assistant_message', message: reply, timestamp: Date.now() };
249
+ yield { type: 'step_end', hasToolCalls: false, phase: 'final' };
250
+ iterations = 1;
251
+ yield { type: 'agent_end', reason: 'completed', timestamp: Date.now() };
252
+ }
253
+ else {
254
+ for await (const event of gen) {
255
+ if (event.type === 'agent_end') {
256
+ const terminal = shouldAbortWithoutRetry(event.error);
257
+ // failure first: the denied remap below must see the unwrapped cause.
258
+ failure = terminal ? unwrapExtensionTerminalError(event.error) : event.error;
259
+ reason = failure instanceof HookDeniedError && event.reason === 'error' ? 'denied' : event.reason;
260
+ success = isSuccessfulRunEnd(reason);
261
+ if (terminal) {
262
+ yield { ...event, error: failure };
263
+ break;
264
+ }
265
+ }
266
+ if (event.type === 'step_end')
267
+ iterations += 1;
268
+ yield event;
269
+ }
270
+ }
271
+ }
272
+ catch (error) {
273
+ failure = unwrapExtensionTerminalError(error);
274
+ reason = failure instanceof HookDeniedError ? 'denied' : 'error';
275
+ success = isSuccessfulRunEnd(reason);
276
+ yield { type: 'agent_end', reason: 'error', timestamp: Date.now(), error: failure };
277
+ }
278
+ finally {
279
+ const messages = context.messages;
280
+ await port.observe('loop_end', {
281
+ ...base,
282
+ runId,
283
+ messages,
284
+ durationMs: Date.now() - startedAt,
285
+ reason,
286
+ success,
287
+ ...(failure === undefined ? {} : { error: failure instanceof Error ? failure.message : String(failure) }),
288
+ iterations,
289
+ response: getTextContent([...messages].reverse().find((message) => message.role === 'assistant' && !message.toolCalls?.length)?.content ?? ''),
290
+ });
291
+ await observeRunEnd(port, base, messages, startedAt, reason, success, failure instanceof Error ? failure.message : typeof failure === 'string' ? failure : undefined);
292
+ }
293
+ }
294
+ /**
295
+ * Single success formula for loop_end and agent_end observations: clean terminal
296
+ * ends (completed / should_stop) succeed; aborted / error / denied do not. The
297
+ * Runner treats only `error` as a failed Run and `should_stop` as an intentional
298
+ * stop, so a clean stop is not a failure. `reason` always carries the exact cause.
299
+ */
300
+ function isSuccessfulRunEnd(reason) {
301
+ return reason === 'completed' || reason === 'should_stop';
302
+ }
303
+ async function observeRunEnd(port, base, messages, startedAt, reason, success, error) {
304
+ await port.observe('agent_end', {
305
+ ...base,
306
+ runId: base.runId ?? 'unknown',
307
+ messages,
308
+ durationMs: Date.now() - startedAt,
309
+ reason,
310
+ success,
311
+ ...(error === undefined ? {} : { error }),
312
+ });
313
+ }
314
+ /** Build the Host Run tool Vote after SecurityGuard and before raw execution. */
315
+ export async function voteAgentToolCall(port, ctx, originalParams, signal) {
316
+ if (!port || ctx.args === null || typeof ctx.args !== 'object' || Array.isArray(ctx.args))
317
+ return undefined;
318
+ const scope = getRunScope();
319
+ if (!scope?.runId)
320
+ throw new Error('before_tool_call Vote requires a Host Run identity');
321
+ const event = {
322
+ sessionId: scope.sessionId,
323
+ agentId: scope.agentId,
324
+ runId: scope.runId,
325
+ ...(scope.principal === undefined ? {} : { principal: scope.principal }),
326
+ ...(signal === undefined ? {} : { signal }),
327
+ toolName: ctx.toolCall.name,
328
+ call: ctx.toolCall,
329
+ params: ctx.args,
330
+ };
331
+ const vote = await port.voteBeforeToolCall(event, originalParams.get(ctx.toolCall) ?? event.params);
332
+ if (vote.decision === 'allow')
333
+ return undefined;
334
+ return {
335
+ block: true,
336
+ reason: vote.reason ?? `Plugin hook denied ${ctx.toolCall.name}`,
337
+ };
338
+ }
@@ -0,0 +1,24 @@
1
+ import type { PluginServiceRecord } from '../plugins/contribution-registry.js';
2
+ import type { HookAuditRecord } from './types.js';
3
+ export interface PluginServiceAudit {
4
+ append(record: HookAuditRecord): Promise<void>;
5
+ }
6
+ /** Host-owned service lifecycle. Registration alone has no background side effect. */
7
+ export declare class PluginServiceSupervisor {
8
+ private readonly onFailure;
9
+ private readonly audit?;
10
+ private started;
11
+ private starting;
12
+ private stopping;
13
+ constructor(onFailure: (service: PluginServiceRecord, error: unknown) => void, audit?: PluginServiceAudit | undefined);
14
+ /** Start in registration order; required failures roll back previously started services. */
15
+ start(services: readonly PluginServiceRecord[]): Promise<void>;
16
+ /** Stop only actually-started services, in reverse order; report all failures. */
17
+ stop(services: readonly PluginServiceRecord[]): Promise<void>;
18
+ /** Best-effort cleanup for a service that failed mid-start; never masks the start failure. */
19
+ private stopOne;
20
+ private key;
21
+ private message;
22
+ private record;
23
+ private invoke;
24
+ }
@@ -0,0 +1,139 @@
1
+ /** Host-owned service lifecycle. Registration alone has no background side effect. */
2
+ export class PluginServiceSupervisor {
3
+ onFailure;
4
+ audit;
5
+ started = new Set();
6
+ starting = false;
7
+ stopping = false;
8
+ constructor(onFailure, audit) {
9
+ this.onFailure = onFailure;
10
+ this.audit = audit;
11
+ }
12
+ /** Start in registration order; required failures roll back previously started services. */
13
+ async start(services) {
14
+ if (this.starting)
15
+ throw new Error('Plugin service startup is already in progress');
16
+ if (this.stopping)
17
+ throw new Error('Plugin service startup cannot overlap shutdown');
18
+ if (this.started.size > 0)
19
+ return;
20
+ this.starting = true;
21
+ try {
22
+ for (const service of services) {
23
+ if (!service.start)
24
+ continue;
25
+ try {
26
+ await this.invoke(service, 'start');
27
+ this.started.add(this.key(service));
28
+ await this.record(service, 'start', 'ok');
29
+ }
30
+ catch (error) {
31
+ await this.record(service, 'start', 'error', error);
32
+ // A failed or timed-out start may already hold ports/timers: release the
33
+ // failing service itself first, or its partial resources leak past rollback.
34
+ await this.stopOne(service);
35
+ if (service.required) {
36
+ await this.stop(services);
37
+ throw new Error(`Required plugin service ${service.pluginId}/${service.serviceId} failed to start: ${this.message(error)}`);
38
+ }
39
+ this.onFailure(service, error);
40
+ }
41
+ }
42
+ }
43
+ finally {
44
+ this.starting = false;
45
+ }
46
+ }
47
+ /** Stop only actually-started services, in reverse order; report all failures. */
48
+ async stop(services) {
49
+ if (this.stopping)
50
+ return;
51
+ this.stopping = true;
52
+ try {
53
+ const started = services.filter((service) => this.started.has(this.key(service))).reverse();
54
+ for (const service of started) {
55
+ this.started.delete(this.key(service));
56
+ try {
57
+ await this.invoke(service, 'stop');
58
+ await this.record(service, 'stop', 'ok');
59
+ }
60
+ catch (error) {
61
+ await this.record(service, 'stop', 'error', error);
62
+ this.onFailure(service, error);
63
+ }
64
+ }
65
+ }
66
+ finally {
67
+ this.stopping = false;
68
+ }
69
+ }
70
+ /** Best-effort cleanup for a service that failed mid-start; never masks the start failure. */
71
+ async stopOne(service) {
72
+ if (!service.stop)
73
+ return;
74
+ try {
75
+ await this.invoke(service, 'stop');
76
+ await this.record(service, 'stop', 'ok');
77
+ }
78
+ catch (error) {
79
+ // Swallowed on purpose: the start failure is the reported cause; cleanup
80
+ // errors only add audit context and must not replace it.
81
+ await this.record(service, 'stop', 'error', error);
82
+ }
83
+ }
84
+ key(service) {
85
+ return `${service.pluginId}:${service.serviceId}`;
86
+ }
87
+ message(error) {
88
+ return error instanceof Error ? error.message : String(error);
89
+ }
90
+ async record(service, phase, outcome, error) {
91
+ if (!this.audit)
92
+ return;
93
+ const hookName = phase === 'start' ? 'service_start' : 'service_stop';
94
+ try {
95
+ await this.audit.append({
96
+ pluginId: service.pluginId,
97
+ hookName,
98
+ phase: 'observe',
99
+ outcome,
100
+ sessionId: 'system',
101
+ agentId: 'host',
102
+ ...(error === undefined ? {} : { reason: this.message(error) }),
103
+ details: { serviceId: service.serviceId, phase },
104
+ });
105
+ }
106
+ catch (auditError) {
107
+ this.onFailure(service, new Error(`Service lifecycle audit failed (${phase}/${outcome}): ${this.message(auditError)}`));
108
+ }
109
+ }
110
+ async invoke(service, phase) {
111
+ const timeoutMs = service.timeoutMs ?? 30_000;
112
+ const controller = new AbortController();
113
+ let settled = false;
114
+ const timer = setTimeout(() => {
115
+ controller.abort(new Error(`Plugin service ${phase} timed out after ${timeoutMs}ms`));
116
+ }, timeoutMs);
117
+ try {
118
+ await new Promise((resolve, reject) => {
119
+ const finish = (error) => {
120
+ if (settled)
121
+ return;
122
+ settled = true;
123
+ if (error !== undefined)
124
+ reject(error);
125
+ else
126
+ resolve();
127
+ };
128
+ controller.signal.addEventListener('abort', () => finish(controller.signal.reason), { once: true });
129
+ Promise.resolve()
130
+ .then(() => phase === 'start' ? service.start?.(controller.signal) : service.stop?.(controller.signal))
131
+ .then(() => finish(), finish);
132
+ });
133
+ }
134
+ finally {
135
+ settled = true;
136
+ clearTimeout(timer);
137
+ }
138
+ }
139
+ }