@octopi-agent/engine 0.98.4 → 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 (301) hide show
  1. package/dist/config-schema/agent.d.ts +35 -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 +57 -160
  6. package/dist/config-schema/engine.js +1 -5
  7. package/dist/config-schema/governance.d.ts +8 -1
  8. package/dist/config-schema/governance.js +8 -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 +24 -3
  25. package/dist/harness/agent/builder.js +131 -27
  26. package/dist/harness/agent/config-bridge.js +9 -2
  27. package/dist/harness/agent/config-integrity.js +19 -2
  28. package/dist/harness/agent/wire-agent-builder.d.ts +11 -3
  29. package/dist/harness/agent/wire-agent-builder.js +26 -7
  30. package/dist/harness/capabilities/document/factory.d.ts +5 -0
  31. package/dist/harness/capabilities/document/factory.js +1 -0
  32. package/dist/harness/capabilities/document/port.js +6 -3
  33. package/dist/harness/capabilities/document/types.d.ts +5 -0
  34. package/dist/harness/collaboration/autonomous-subsystem/loader.js +1 -1
  35. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.d.ts +1 -1
  36. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.js +2 -2
  37. package/dist/harness/collaboration/autonomous-subsystem/sense/input-builder.js +4 -4
  38. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.d.ts +2 -2
  39. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.js +2 -2
  40. package/dist/harness/collaboration/autonomous-subsystem/signal/bus.d.ts +6 -0
  41. package/dist/harness/collaboration/autonomous-subsystem/signal/bus.js +25 -4
  42. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +1 -1
  43. package/dist/harness/collaboration/autonomous-subsystem/types.d.ts +3 -3
  44. package/dist/harness/collaboration/delegation/child-run.d.ts +1 -1
  45. package/dist/harness/collaboration/delegation/child-run.js +4 -4
  46. package/dist/harness/collaboration/delegation/index.d.ts +1 -1
  47. package/dist/harness/collaboration/delegation/index.js +1 -1
  48. package/dist/harness/collaboration/delegation/notifier.d.ts +6 -1
  49. package/dist/harness/collaboration/delegation/notifier.js +8 -1
  50. package/dist/harness/collaboration/delegation/service.d.ts +2 -0
  51. package/dist/harness/collaboration/delegation/service.js +2 -1
  52. package/dist/harness/collaboration/delegation/store.d.ts +2 -0
  53. package/dist/harness/collaboration/delegation/store.js +2 -1
  54. package/dist/harness/collaboration/delegation/types.d.ts +23 -2
  55. package/dist/harness/collaboration/delegation/types.js +22 -0
  56. package/dist/harness/collaboration/delegation/wiring.js +11 -1
  57. package/dist/harness/context/budget-allocator.d.ts +26 -18
  58. package/dist/harness/context/budget-allocator.js +67 -32
  59. package/dist/harness/context/capabilities/compact/engine.d.ts +0 -6
  60. package/dist/harness/context/capabilities/compact/engine.js +169 -121
  61. package/dist/harness/context/capabilities/compact/handover.d.ts +5 -3
  62. package/dist/harness/context/capabilities/compact/handover.js +7 -5
  63. package/dist/harness/context/capabilities/compact/index.d.ts +5 -1
  64. package/dist/harness/context/capabilities/compact/index.js +4 -0
  65. package/dist/harness/context/capabilities/compact/mechanical.d.ts +130 -0
  66. package/dist/harness/context/capabilities/compact/mechanical.js +268 -0
  67. package/dist/harness/context/capabilities/compact/messages.d.ts +60 -0
  68. package/dist/harness/context/capabilities/compact/messages.js +91 -0
  69. package/dist/harness/context/capabilities/compact/types.d.ts +76 -11
  70. package/dist/harness/context/capabilities/compact/types.js +11 -1
  71. package/dist/harness/context/capabilities/compact/view-split.d.ts +36 -0
  72. package/dist/harness/context/capabilities/compact/view-split.js +72 -0
  73. package/dist/harness/context/capabilities/summary/port.js +0 -1
  74. package/dist/harness/context/capabilities/summary/resolver.d.ts +1 -1
  75. package/dist/harness/context/capabilities/summary/resolver.js +1 -6
  76. package/dist/harness/context/capabilities/summary/tool-binding.d.ts +1 -1
  77. package/dist/harness/context/capabilities/summary/types.d.ts +3 -6
  78. package/dist/harness/context/context-size-ledger.d.ts +143 -0
  79. package/dist/harness/context/context-size-ledger.js +236 -0
  80. package/dist/harness/context/default-context-engine.d.ts +195 -119
  81. package/dist/harness/context/default-context-engine.js +1241 -743
  82. package/dist/harness/context/index.d.ts +2 -2
  83. package/dist/harness/context/index.js +1 -1
  84. package/dist/harness/context/layer-types.d.ts +15 -0
  85. package/dist/harness/context/layer-types.js +14 -1
  86. package/dist/harness/context/layers.d.ts +14 -15
  87. package/dist/harness/context/layers.js +41 -11
  88. package/dist/harness/context/message-selector.d.ts +10 -8
  89. package/dist/harness/context/message-selector.js +49 -27
  90. package/dist/harness/context/summarize.d.ts +2 -2
  91. package/dist/harness/context/summarize.js +9 -2
  92. package/dist/harness/context/system-prompt-assembler.d.ts +2 -0
  93. package/dist/harness/context/system-prompt-assembler.js +2 -1
  94. package/dist/harness/context/token-constants.d.ts +8 -6
  95. package/dist/harness/context/token-constants.js +8 -7
  96. package/dist/harness/context/token-estimate-fns.d.ts +37 -27
  97. package/dist/harness/context/token-estimate-fns.js +85 -66
  98. package/dist/harness/context/token-estimator.d.ts +27 -12
  99. package/dist/harness/context/token-estimator.js +120 -66
  100. package/dist/harness/context/token-segments.d.ts +88 -0
  101. package/dist/harness/context/token-segments.js +103 -0
  102. package/dist/harness/context/tool-result-aging.d.ts +6 -1
  103. package/dist/harness/context/tool-result-aging.js +16 -5
  104. package/dist/harness/context/tool-result-body.js +2 -0
  105. package/dist/harness/context/transform/anchors.d.ts +66 -0
  106. package/dist/harness/context/transform/anchors.js +125 -0
  107. package/dist/harness/context/transform/fold.d.ts +56 -0
  108. package/dist/harness/context/transform/fold.js +135 -0
  109. package/dist/harness/context/transform/migrate.d.ts +41 -0
  110. package/dist/harness/context/transform/migrate.js +69 -0
  111. package/dist/harness/context/transform/types.d.ts +129 -0
  112. package/dist/harness/context/transform/types.js +19 -0
  113. package/dist/harness/context/turn-envelope.d.ts +6 -3
  114. package/dist/harness/context/types.d.ts +127 -117
  115. package/dist/harness/extension/execution-environment/ops-audit.d.ts +1 -1
  116. package/dist/harness/extension/execution-environment/resource-limits.d.ts +1 -1
  117. package/dist/harness/extension/execution-environment/resource-limits.js +1 -1
  118. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +1 -1
  119. package/dist/harness/extension/plugin-ecosystem/commands/index.d.ts +3 -1
  120. package/dist/harness/extension/plugin-ecosystem/commands/index.js +1 -0
  121. package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.d.ts +12 -1
  122. package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.js +14 -4
  123. package/dist/harness/extension/plugin-ecosystem/commands/router.d.ts +5 -4
  124. package/dist/harness/extension/plugin-ecosystem/commands/router.js +23 -14
  125. package/dist/harness/extension/plugin-ecosystem/commands/types.d.ts +8 -1
  126. package/dist/harness/extension/plugin-ecosystem/commands/types.js +2 -1
  127. package/dist/harness/extension/plugin-ecosystem/hooks/adapter.d.ts +54 -0
  128. package/dist/harness/extension/plugin-ecosystem/hooks/adapter.js +397 -0
  129. package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.d.ts +16 -0
  130. package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.js +66 -0
  131. package/dist/harness/extension/plugin-ecosystem/hooks/index.d.ts +4 -0
  132. package/dist/harness/extension/plugin-ecosystem/hooks/index.js +2 -0
  133. package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.d.ts +11 -0
  134. package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.js +54 -0
  135. package/dist/harness/extension/plugin-ecosystem/hooks/journal.d.ts +9 -0
  136. package/dist/harness/extension/plugin-ecosystem/hooks/journal.js +22 -0
  137. package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.d.ts +12 -0
  138. package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.js +19 -0
  139. package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.d.ts +36 -0
  140. package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.js +338 -0
  141. package/dist/harness/extension/plugin-ecosystem/hooks/services.d.ts +24 -0
  142. package/dist/harness/extension/plugin-ecosystem/hooks/services.js +139 -0
  143. package/dist/harness/extension/plugin-ecosystem/hooks/types.d.ts +229 -0
  144. package/dist/harness/extension/plugin-ecosystem/hooks/types.js +1 -0
  145. package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +83 -249
  146. package/dist/harness/extension/plugin-ecosystem/plugins/api.js +88 -214
  147. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.d.ts +43 -0
  148. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.js +61 -0
  149. package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.d.ts +4 -0
  150. package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.js +18 -0
  151. package/dist/harness/extension/plugin-ecosystem/plugins/entry.d.ts +7 -85
  152. package/dist/harness/extension/plugin-ecosystem/plugins/entry.js +8 -50
  153. package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +6 -23
  154. package/dist/harness/extension/plugin-ecosystem/plugins/index.js +3 -23
  155. package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +50 -117
  156. package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +316 -285
  157. package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +23 -490
  158. package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +85 -353
  159. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +41 -223
  160. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +138 -19
  161. package/dist/harness/extension/plugin-ecosystem/plugins/staging.d.ts +15 -0
  162. package/dist/harness/extension/plugin-ecosystem/plugins/staging.js +15 -0
  163. package/dist/harness/extension/plugin-ecosystem/skills/manager.d.ts +6 -1
  164. package/dist/harness/extension/plugin-ecosystem/skills/manager.js +17 -1
  165. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +3 -0
  166. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +46 -21
  167. package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +18 -8
  168. package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.d.ts +11 -0
  169. package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.js +39 -0
  170. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.d.ts +1 -1
  171. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +11 -2
  172. package/dist/harness/governance/accounting/usage-ledger.d.ts +13 -1
  173. package/dist/harness/governance/accounting/usage-ledger.js +23 -1
  174. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +3 -3
  175. package/dist/harness/governance/human-in-the-loop/decision-cache.js +2 -2
  176. package/dist/harness/governance/security/capability-enforcer.js +1 -2
  177. package/dist/harness/index.d.ts +12 -12
  178. package/dist/harness/index.js +7 -7
  179. package/dist/harness/knowledge/boot-config.d.ts +55 -0
  180. package/dist/harness/knowledge/boot-config.js +50 -0
  181. package/dist/harness/knowledge/catalog-types.d.ts +2 -0
  182. package/dist/harness/knowledge/client.d.ts +24 -2
  183. package/dist/harness/knowledge/client.js +19 -5
  184. package/dist/harness/knowledge/db.js +5 -0
  185. package/dist/harness/knowledge/describe-sample.d.ts +23 -0
  186. package/dist/harness/knowledge/describe-sample.js +58 -0
  187. package/dist/harness/knowledge/describe.d.ts +8 -0
  188. package/dist/harness/knowledge/describe.js +18 -2
  189. package/dist/harness/knowledge/engine-thread.js +6 -0
  190. package/dist/harness/knowledge/grounding.js +3 -1
  191. package/dist/harness/knowledge/http-app.js +35 -4
  192. package/dist/harness/knowledge/http-params.d.ts +18 -0
  193. package/dist/harness/knowledge/http-params.js +24 -0
  194. package/dist/harness/knowledge/index.d.ts +2 -0
  195. package/dist/harness/knowledge/index.js +1 -0
  196. package/dist/harness/knowledge/knowledge-serve-child.js +3 -0
  197. package/dist/harness/knowledge/purge.js +5 -2
  198. package/dist/harness/knowledge/query-service.d.ts +13 -2
  199. package/dist/harness/knowledge/query-service.js +4 -2
  200. package/dist/harness/knowledge/query-worker-client.d.ts +9 -1
  201. package/dist/harness/knowledge/query-worker-client.js +4 -2
  202. package/dist/harness/knowledge/query-worker.js +4 -2
  203. package/dist/harness/knowledge/read-http.js +5 -1
  204. package/dist/harness/knowledge/serve.d.ts +8 -7
  205. package/dist/harness/knowledge/serve.js +9 -0
  206. package/dist/harness/knowledge/source-store.js +26 -3
  207. package/dist/harness/knowledge/start-service-process.d.ts +15 -7
  208. package/dist/harness/knowledge/start-service-process.js +21 -9
  209. package/dist/harness/knowledge/types.d.ts +7 -0
  210. package/dist/harness/knowledge/writer-service.d.ts +37 -9
  211. package/dist/harness/knowledge/writer-service.js +120 -14
  212. package/dist/harness/knowledge/writer-worker-client.d.ts +10 -9
  213. package/dist/harness/knowledge/writer-worker-client.js +20 -2
  214. package/dist/harness/knowledge/writer-worker.js +9 -1
  215. package/dist/harness/memory/sqlite/wisdom-store.js +35 -10
  216. package/dist/harness/memory/types.d.ts +6 -4
  217. package/dist/harness/memory/wisdom-formation.d.ts +14 -3
  218. package/dist/harness/memory/wisdom-formation.js +85 -22
  219. package/dist/harness/memory/wisdom-gates.d.ts +14 -0
  220. package/dist/harness/memory/wisdom-gates.js +59 -19
  221. package/dist/harness/memory/wisdom.js +9 -0
  222. package/dist/harness/observability/observer/hub.js +25 -15
  223. package/dist/harness/observability/observer/types.d.ts +10 -6
  224. package/dist/harness/run/agent/agent.d.ts +40 -21
  225. package/dist/harness/run/agent/agent.js +66 -13
  226. package/dist/harness/run/agent/index.d.ts +1 -1
  227. package/dist/harness/run/budget/budget.d.ts +28 -10
  228. package/dist/harness/run/budget/budget.js +38 -15
  229. package/dist/harness/run/model/index.d.ts +3 -1
  230. package/dist/harness/run/model/index.js +2 -1
  231. package/dist/harness/run/model/resolver.d.ts +4 -1
  232. package/dist/harness/run/model/resolver.js +36 -2
  233. package/dist/harness/run/model/run-scope.d.ts +2 -0
  234. package/dist/harness/run/model/run-scope.js +7 -0
  235. package/dist/harness/run/model/types.d.ts +22 -5
  236. package/dist/harness/run/model/types.js +3 -2
  237. package/dist/harness/run/model/window-truth.d.ts +37 -0
  238. package/dist/harness/run/model/window-truth.js +39 -0
  239. package/dist/harness/run/reliability/context-length-feedback.d.ts +77 -0
  240. package/dist/harness/run/reliability/context-length-feedback.js +128 -0
  241. package/dist/harness/run/reliability/harness-events.d.ts +3 -3
  242. package/dist/harness/run/reliability/model-error-policy.js +4 -0
  243. package/dist/harness/run/reliability/run-agent.d.ts +10 -4
  244. package/dist/harness/run/reliability/run-agent.js +137 -53
  245. package/dist/harness/run/reliability/run-metrics-collector.d.ts +19 -8
  246. package/dist/harness/run/reliability/run-metrics-collector.js +38 -23
  247. package/dist/harness/run/run-guard/default-run-guard.js +8 -8
  248. package/dist/harness/run/run-scope.d.ts +37 -4
  249. package/dist/harness/run/runner.d.ts +44 -29
  250. package/dist/harness/run/runner.js +320 -102
  251. package/dist/harness/session/attachments/index.d.ts +1 -0
  252. package/dist/harness/session/attachments/index.js +1 -0
  253. package/dist/harness/session/attachments/inject.d.ts +21 -10
  254. package/dist/harness/session/attachments/inject.js +76 -24
  255. package/dist/harness/session/attachments/recall-index.d.ts +70 -0
  256. package/dist/harness/session/attachments/recall-index.js +219 -0
  257. package/dist/harness/session/attachments/service.d.ts +21 -0
  258. package/dist/harness/session/attachments/service.js +258 -139
  259. package/dist/harness/session/attachments/types.d.ts +6 -0
  260. package/dist/harness/session/transform-store.d.ts +136 -0
  261. package/dist/harness/session/transform-store.js +302 -0
  262. package/dist/harness/session/types.d.ts +2 -2
  263. package/dist/harness/shared/events/agent-event-map.d.ts +46 -13
  264. package/dist/harness/shared/events/agent-event-map.js +3 -2
  265. package/dist/harness/shared/events/scenario-events.d.ts +6 -6
  266. package/dist/harness/shared/types/agent-definition.d.ts +1 -2
  267. package/dist/index.d.ts +14 -17
  268. package/dist/index.js +7 -9
  269. package/dist/integration/observability/metrics.d.ts +6 -6
  270. package/dist/integration/observability/metrics.js +13 -13
  271. package/dist/integration/observability/observer-bridge.js +2 -2
  272. package/dist/integration/observability/trace-collector.d.ts +5 -5
  273. package/dist/integration/observability/trace-collector.js +34 -35
  274. package/dist/integration/observability/trace-events.d.ts +3 -3
  275. package/dist/integration/observability/trace-events.js +3 -3
  276. package/dist/integration/providers/anthropic.js +14 -1
  277. package/dist/integration/providers/openai.js +7 -1
  278. package/dist/integration/providers/usage.d.ts +1 -1
  279. package/dist/integration/providers/wire-dump.d.ts +1 -1
  280. package/dist/integration/storage/archive-manager.d.ts +6 -0
  281. package/dist/integration/storage/archive-manager.js +10 -0
  282. package/dist/integration/storage/jsonl.d.ts +1 -1
  283. package/dist/integration/storage/jsonl.js +18 -16
  284. package/dist/subsystems/wisdom-steward/formation/SUBSYSTEM.md +8 -1
  285. package/dist/subsystems/wisdom-steward/formation/config.yaml +1 -0
  286. package/dist/subsystems/wisdom-steward/formation/handler.js +27 -5
  287. package/package.json +11 -14
  288. package/dist/harness/context/hybrid-compressor.d.ts +0 -41
  289. package/dist/harness/context/hybrid-compressor.js +0 -159
  290. package/dist/harness/context/llm-summarizer.d.ts +0 -46
  291. package/dist/harness/context/llm-summarizer.js +0 -249
  292. package/dist/harness/context/smart-router.d.ts +0 -75
  293. package/dist/harness/context/smart-router.js +0 -118
  294. package/dist/harness/context/truncate-compressor.d.ts +0 -28
  295. package/dist/harness/context/truncate-compressor.js +0 -107
  296. package/dist/harness/extension/plugin-ecosystem/plugins/capability.d.ts +0 -97
  297. package/dist/harness/extension/plugin-ecosystem/plugins/capability.js +0 -155
  298. package/dist/harness/extension/plugin-ecosystem/plugins/hooks.d.ts +0 -7
  299. package/dist/harness/extension/plugin-ecosystem/plugins/hooks.js +0 -7
  300. package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.d.ts +0 -86
  301. package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.js +0 -139
@@ -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
+ }
@@ -0,0 +1,229 @@
1
+ import type { Message, ThinkingLevel, ToolCall, ToolResult } from '@octopi-agent/core/types.js';
2
+ import type { HitlOutcome } from '../../../governance/human-in-the-loop/decision-cache.js';
3
+ import type { ChannelMessage, ChannelReply } from '../channel-types.js';
4
+ import type { PluginHookName } from '../plugins/manifest.js';
5
+ /** Per-call execution facts; a missing Port performs no plugin work. */
6
+ export interface ExtensionHookContext {
7
+ sessionId: string;
8
+ agentId: string;
9
+ runId?: string;
10
+ principal?: {
11
+ actorId?: string;
12
+ actorType?: string;
13
+ tenantId?: string;
14
+ };
15
+ signal?: AbortSignal;
16
+ trace?: {
17
+ traceId?: string;
18
+ spanId?: string;
19
+ };
20
+ }
21
+ export interface HookContribution<T> {
22
+ pluginId: string;
23
+ value: T;
24
+ }
25
+ export interface HookVote {
26
+ decision: 'allow' | 'deny' | 'require_approval';
27
+ reason?: string;
28
+ pluginId?: string;
29
+ /** Only before_tool_call may request the Host's existing HITL channel. */
30
+ approval?: HookToolApproval;
31
+ }
32
+ export interface HookTransformResult<T> {
33
+ value: T;
34
+ changes: HookContribution<unknown>[];
35
+ }
36
+ export interface HookCollectResult<T> {
37
+ contributions: HookContribution<T>[];
38
+ }
39
+ export interface HookFailure {
40
+ pluginId: string;
41
+ hookName: PluginHookName;
42
+ reason: 'error' | 'timeout' | 'aborted';
43
+ message: string;
44
+ }
45
+ export interface HookServiceRegistration {
46
+ serviceId: string;
47
+ required?: boolean;
48
+ timeoutMs?: number;
49
+ start?: (signal: AbortSignal) => void | Promise<void>;
50
+ stop?: (signal: AbortSignal) => void | Promise<void>;
51
+ }
52
+ export interface HookModelSelection {
53
+ provider: string;
54
+ model: string;
55
+ }
56
+ export interface HookModelSelectionEvent extends ExtensionHookContext {
57
+ current: Readonly<HookModelSelection>;
58
+ prompt: string;
59
+ }
60
+ export interface HookTurnEvent extends ExtensionHookContext {
61
+ prompt: string;
62
+ messages: readonly Message[];
63
+ }
64
+ export interface HookPromptBuildEvent extends HookTurnEvent {
65
+ runId: string;
66
+ }
67
+ export interface HookPromptContribution {
68
+ text: string;
69
+ }
70
+ export interface HookRunEvent extends ExtensionHookContext {
71
+ runId: string;
72
+ prompt: string;
73
+ messages: readonly Message[];
74
+ }
75
+ export interface HookReplyEvent extends HookRunEvent {
76
+ }
77
+ export interface HookFinalizeEvent extends ExtensionHookContext {
78
+ runId: string;
79
+ reply: Readonly<Message>;
80
+ }
81
+ export interface HookRunEndEvent extends ExtensionHookContext {
82
+ runId: string;
83
+ messages: readonly Message[];
84
+ durationMs: number;
85
+ /** Exact terminal cause: completed | should_stop | aborted | error | denied (observation-layer label). */
86
+ reason: string;
87
+ /** True only for clean terminal ends (completed / should_stop); aborted / error / denied are false. */
88
+ success: boolean;
89
+ error?: string;
90
+ }
91
+ export interface HookToolEvent extends ExtensionHookContext {
92
+ runId: string;
93
+ toolName: string;
94
+ call: Readonly<ToolCall>;
95
+ params: Readonly<Record<string, unknown>>;
96
+ }
97
+ export interface HookToolApproval {
98
+ title: string;
99
+ description: string;
100
+ severity?: 'info' | 'warning' | 'critical';
101
+ timeoutMs?: number;
102
+ timeoutBehavior?: 'deny';
103
+ }
104
+ export interface HookToolResultEvent extends ExtensionHookContext {
105
+ runId: string;
106
+ call: Readonly<ToolCall>;
107
+ originalParams: Readonly<Record<string, unknown>>;
108
+ params: Readonly<Record<string, unknown>>;
109
+ result: Readonly<ToolResult>;
110
+ error?: string;
111
+ }
112
+ export interface HookMessageReceivedEvent extends ExtensionHookContext {
113
+ message: Readonly<ChannelMessage>;
114
+ }
115
+ export interface HookMessageSendingEvent extends ExtensionHookContext {
116
+ reply: Readonly<ChannelReply>;
117
+ }
118
+ export interface HookMessageSentEvent extends HookMessageSendingEvent {
119
+ success: boolean;
120
+ error?: string;
121
+ }
122
+ export interface HookSessionEvent extends ExtensionHookContext {
123
+ reason?: 'created' | 'deleted' | 'archived';
124
+ }
125
+ export interface HookCompactionEvent extends ExtensionHookContext {
126
+ runId?: string;
127
+ mode: string;
128
+ previousSummary?: string;
129
+ coveredMessageCount?: number;
130
+ compacted?: boolean;
131
+ fresh?: boolean;
132
+ reason?: string;
133
+ error?: string;
134
+ }
135
+ export interface HookGatewayEvent extends ExtensionHookContext {
136
+ phase: 'started' | 'stopping';
137
+ }
138
+ export interface HookInstallEvent extends ExtensionHookContext {
139
+ type: 'skill' | 'plugin';
140
+ source: string;
141
+ target: string;
142
+ }
143
+ export interface HookIterationEvent extends ExtensionHookContext {
144
+ runId: string;
145
+ iteration: number;
146
+ messages: readonly Message[];
147
+ model: HookModelSelection;
148
+ thinking?: ThinkingLevel;
149
+ }
150
+ export interface HookIterationTransform {
151
+ model?: HookModelSelection;
152
+ thinking?: ThinkingLevel;
153
+ /** Ordered Runtime snapshot additions; never a systemPrompt override. */
154
+ snapshot?: string;
155
+ }
156
+ export interface HookAfterIterationEvent extends HookIterationEvent {
157
+ assistantMessage: Readonly<Message>;
158
+ toolResults: readonly ToolResult[];
159
+ usage?: import('@octopi-agent/core/types/step.js').TokenUsage;
160
+ }
161
+ export interface HookLoopEndEvent extends HookRunEndEvent {
162
+ iterations: number;
163
+ response?: string;
164
+ }
165
+ export interface HookBeforeToolTransform {
166
+ params: Record<string, unknown>;
167
+ }
168
+ export type ExtensionHookMap = {
169
+ before_model_resolve: [HookModelSelectionEvent, HookModelSelection | void, 'transform'];
170
+ agent_turn_prepare: [HookTurnEvent, string | void, 'transform'];
171
+ before_prompt_build: [HookPromptBuildEvent, HookPromptContribution | string | void, 'collect'];
172
+ before_agent_run: [HookRunEvent, HookVote | void, 'vote'];
173
+ before_agent_reply: [HookReplyEvent, Message | void, 'override'];
174
+ before_agent_finalize: [HookFinalizeEvent, Message | string | void, 'transform'];
175
+ agent_end: [HookRunEndEvent, void, 'observe'];
176
+ before_tool_call: [HookToolEvent, HookBeforeToolTransform | HookVote | void, 'transform_vote'];
177
+ after_tool_call: [HookToolResultEvent, void, 'observe'];
178
+ message_received: [HookMessageReceivedEvent, void, 'observe'];
179
+ message_sending: [HookMessageSendingEvent, HookVote | void, 'vote'];
180
+ message_sent: [HookMessageSentEvent, void, 'observe'];
181
+ session_start: [HookSessionEvent, void, 'observe'];
182
+ session_end: [HookSessionEvent, void, 'observe'];
183
+ before_compaction: [HookCompactionEvent, HookVote | void, 'vote'];
184
+ after_compaction: [HookCompactionEvent, void, 'observe'];
185
+ gateway_start: [HookGatewayEvent, void, 'observe'];
186
+ gateway_stop: [HookGatewayEvent, void, 'observe'];
187
+ before_install: [HookInstallEvent, HookVote | void, 'vote'];
188
+ before_iteration: [HookIterationEvent, HookIterationTransform | HookVote | void, 'transform_vote'];
189
+ after_iteration: [HookAfterIterationEvent, void, 'observe'];
190
+ loop_end: [HookLoopEndEvent, void, 'observe'];
191
+ };
192
+ export type HookEvent<K extends PluginHookName> = ExtensionHookMap[K][0];
193
+ export type HookResult<K extends PluginHookName> = K extends 'before_tool_call' ? Record<string, unknown> | HookVote | void : K extends 'before_iteration' ? HookIterationTransform | HookVote | void : ExtensionHookMap[K][1];
194
+ export type HookSemantics = 'observe' | 'collect' | 'transform' | 'vote' | 'override' | 'transform_vote';
195
+ export type HookAuditRecord = {
196
+ pluginId: string;
197
+ hookName: PluginHookName | 'service_start' | 'service_stop';
198
+ phase: 'observe' | 'collect' | 'transform' | 'vote' | 'override';
199
+ outcome: 'ok' | 'error' | 'timeout' | 'aborted' | 'denied' | 'skipped';
200
+ sessionId: string;
201
+ agentId: string;
202
+ runId?: string;
203
+ principal?: ExtensionHookContext['principal'];
204
+ reason?: string;
205
+ details?: Record<string, unknown>;
206
+ };
207
+ /**
208
+ * Harness-owned interception boundary. Consumers do not see PluginManager or
209
+ * plugin registrations; the adapter owns cardinality, failures and audit.
210
+ */
211
+ export interface ExtensionHookPort {
212
+ /** True when at least one handler is registered for the event (optionally for one phase). */
213
+ hasHooks(name: PluginHookName, phase?: 'single' | 'transform' | 'vote'): boolean;
214
+ observe<K extends PluginHookName>(name: K, event: HookEvent<K>): Promise<void>;
215
+ collect(name: 'before_prompt_build', event: HookPromptBuildEvent): Promise<HookCollectResult<HookPromptContribution>>;
216
+ transform<K extends PluginHookName>(name: K, event: HookEvent<K>, initial: unknown): Promise<HookTransformResult<unknown>>;
217
+ vote<K extends PluginHookName>(name: K, event: HookEvent<K>): Promise<HookVote>;
218
+ override(name: 'before_agent_reply', event: HookReplyEvent): Promise<Message | undefined>;
219
+ transformBeforeToolCall(event: HookToolEvent): Promise<HookTransformResult<Record<string, unknown>>>;
220
+ voteBeforeToolCall(event: HookToolEvent, originalParams: Readonly<Record<string, unknown>>): Promise<HookVote>;
221
+ beforeIteration(event: HookIterationEvent): Promise<{
222
+ transform: HookIterationTransform;
223
+ snapshotContributions: HookContribution<string>[];
224
+ vote: HookVote;
225
+ }>;
226
+ /** Resolved Host HITL decision (engine cache included); `allowed` gates execution. */
227
+ approveToolCall(event: HookToolEvent, request: Readonly<HookToolApproval>, pluginId: string): Promise<HitlOutcome>;
228
+ }
229
+ export type ExtensionHookHandler<K extends PluginHookName = PluginHookName> = (event: HookEvent<K>) => HookResult<K> | Promise<HookResult<K>>;