@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,54 @@
1
+ import type { ExtensionHookPort, HookAuditRecord, HookCollectResult, HookContribution, HookEvent, HookIterationEvent, HookIterationTransform, HookPromptBuildEvent, HookPromptContribution, HookToolApproval, HookToolEvent, HookTransformResult, HookVote } from './types.js';
2
+ import type { PluginHookName } from '../plugins/manifest.js';
3
+ import type { PluginEntryConfig } from '../plugins/loader.js';
4
+ import type { HitlOutcome } from '../../../governance/human-in-the-loop/decision-cache.js';
5
+ import type { Message } from '@octopi-agent/core/types.js';
6
+ export interface RegisteredHook {
7
+ pluginId: string;
8
+ hookName: PluginHookName;
9
+ /** Explicit phase for dual-phase events; ordinary events use single. */
10
+ phase: 'single' | 'transform' | 'vote';
11
+ priority: number;
12
+ timeoutMs?: number;
13
+ handler: (event: never) => unknown;
14
+ }
15
+ export interface HookExecutionHost {
16
+ getHooks(): RegisteredHook[];
17
+ getPluginConfig(pluginId: string): PluginEntryConfig | undefined;
18
+ recordHook(record: HookAuditRecord): void | Promise<void>;
19
+ /** Resolved Host HITL decision (engine cache included); ask errors must not escape as allow. */
20
+ approveToolCall(event: HookToolEvent, request: Readonly<HookToolApproval>, pluginId: string): Promise<HitlOutcome>;
21
+ }
22
+ export declare class HookDeniedError extends Error {
23
+ readonly vote: HookVote;
24
+ readonly hookName: PluginHookName;
25
+ constructor(vote: HookVote, hookName: PluginHookName);
26
+ }
27
+ export declare function requireHookApproval(vote: HookVote, hookName: PluginHookName): void;
28
+ /** Adapts effective plugin registrations to explicit cardinality operations. */
29
+ export declare class PluginHookAdapter implements ExtensionHookPort {
30
+ private readonly host;
31
+ constructor(host: HookExecutionHost);
32
+ observe<K extends PluginHookName>(name: K, event: HookEvent<K>): Promise<void>;
33
+ collect(name: 'before_prompt_build', event: HookPromptBuildEvent): Promise<HookCollectResult<HookPromptContribution>>;
34
+ hasHooks(name: PluginHookName, phase?: 'single' | 'transform' | 'vote'): boolean;
35
+ transform<K extends PluginHookName>(name: K, event: HookEvent<K>, initial: unknown): Promise<HookTransformResult<unknown>>;
36
+ vote<K extends PluginHookName>(name: K, event: HookEvent<K>): Promise<HookVote>;
37
+ override(name: 'before_agent_reply', event: Parameters<ExtensionHookPort['override']>[1]): Promise<Message | undefined>;
38
+ transformBeforeToolCall(event: HookToolEvent): Promise<HookTransformResult<Record<string, unknown>>>;
39
+ voteBeforeToolCall(event: HookToolEvent, originalParams: Readonly<Record<string, unknown>>): Promise<HookVote>;
40
+ beforeIteration(event: HookIterationEvent): Promise<{
41
+ transform: HookIterationTransform;
42
+ snapshotContributions: HookContribution<string>[];
43
+ vote: HookVote;
44
+ }>;
45
+ approveToolCall(event: HookToolEvent, request: Readonly<HookToolApproval>, pluginId: string): Promise<HitlOutcome>;
46
+ private entries;
47
+ private invokeVote;
48
+ private transformEvent;
49
+ private transformedValue;
50
+ private invoke;
51
+ private outcome;
52
+ private execute;
53
+ private record;
54
+ }
@@ -0,0 +1,397 @@
1
+ export class HookDeniedError extends Error {
2
+ vote;
3
+ hookName;
4
+ constructor(vote, hookName) {
5
+ super(vote.reason ?? `Plugin hook ${hookName} denied the operation`);
6
+ this.vote = vote;
7
+ this.hookName = hookName;
8
+ this.name = 'HookDeniedError';
9
+ }
10
+ }
11
+ export function requireHookApproval(vote, hookName) {
12
+ if (vote.decision !== 'allow')
13
+ throw new HookDeniedError(vote, hookName);
14
+ }
15
+ function isVote(value) {
16
+ if (value === null || typeof value !== 'object' || !('decision' in value))
17
+ return false;
18
+ const decision = value.decision;
19
+ return decision === 'allow' || decision === 'deny' || decision === 'require_approval';
20
+ }
21
+ function failureMessage(error) {
22
+ return error instanceof Error ? error.message : String(error);
23
+ }
24
+ function isParams(value) {
25
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
26
+ }
27
+ /** Adapts effective plugin registrations to explicit cardinality operations. */
28
+ export class PluginHookAdapter {
29
+ host;
30
+ constructor(host) {
31
+ this.host = host;
32
+ }
33
+ async observe(name, event) {
34
+ for (const entry of this.entries(name, 'single')) {
35
+ await this.execute(entry, event, 'observe', async () => {
36
+ await entry.handler(event);
37
+ });
38
+ }
39
+ }
40
+ async collect(name, event) {
41
+ const contributions = [];
42
+ for (const entry of this.entries(name, 'single')) {
43
+ await this.execute(entry, event, 'collect', async () => {
44
+ const result = await entry.handler(event);
45
+ if (result === undefined)
46
+ return;
47
+ const value = typeof result === 'string' ? { text: result } : result;
48
+ if (!value || typeof value.text !== 'string') {
49
+ throw new Error('before_prompt_build must return text or {text}');
50
+ }
51
+ if (!value.text.trim())
52
+ return;
53
+ contributions.push({ pluginId: entry.pluginId, value: { text: value.text } });
54
+ });
55
+ }
56
+ return { contributions };
57
+ }
58
+ hasHooks(name, phase) {
59
+ return this.host.getHooks()
60
+ .some((entry) => entry.hookName === name && (phase === undefined || entry.phase === phase));
61
+ }
62
+ async transform(name, event, initial) {
63
+ let value = initial;
64
+ const changes = [];
65
+ for (const entry of this.entries(name, 'single')) {
66
+ const currentEvent = this.transformEvent(name, event, value);
67
+ try {
68
+ const next = await this.invoke(entry, currentEvent);
69
+ if (next !== undefined && next !== null) {
70
+ value = this.transformedValue(name, value, next);
71
+ changes.push({ pluginId: entry.pluginId, value });
72
+ }
73
+ await this.record(entry, name, currentEvent, 'transform', 'ok');
74
+ }
75
+ catch (error) {
76
+ await this.record(entry, name, currentEvent, 'transform', this.outcome(error), failureMessage(error));
77
+ throw error;
78
+ }
79
+ }
80
+ return { value, changes };
81
+ }
82
+ async vote(name, event) {
83
+ let final = { decision: 'allow' };
84
+ for (const entry of this.entries(name, 'single')) {
85
+ const vote = await this.invokeVote(entry, event);
86
+ if (vote.decision === 'require_approval') {
87
+ final = { decision: 'deny', pluginId: entry.pluginId, reason: `${name} does not support approval votes` };
88
+ await this.record(entry, name, event, 'vote', 'denied', final.reason);
89
+ }
90
+ else if (vote.decision === 'deny') {
91
+ final = vote;
92
+ }
93
+ }
94
+ return final;
95
+ }
96
+ async override(name, event) {
97
+ const entries = this.entries(name, 'single');
98
+ if (entries.length === 0)
99
+ return undefined;
100
+ if (entries.length > 1) {
101
+ const error = new Error(`Override hook ${name} has multiple owners: ${entries.map((entry) => entry.pluginId).join(', ')}`);
102
+ await Promise.all(entries.map((entry) => this.record(entry, name, event, 'override', 'error', error.message)));
103
+ throw error;
104
+ }
105
+ const entry = entries[0];
106
+ try {
107
+ const result = await this.invoke(entry, event);
108
+ if (result !== undefined && result !== null) {
109
+ const message = result;
110
+ if (!isParams(result) || message.role !== 'assistant') {
111
+ throw new Error('before_agent_reply must return an assistant Message');
112
+ }
113
+ if (message.toolCalls?.length) {
114
+ throw new Error('before_agent_reply must not return toolCalls (no tool results would follow)');
115
+ }
116
+ if (typeof message.content !== 'string' && !Array.isArray(message.content)) {
117
+ throw new Error('before_agent_reply must return text or block-array content');
118
+ }
119
+ }
120
+ await this.record(entry, name, event, 'override', 'ok');
121
+ return (result ?? undefined);
122
+ }
123
+ catch (error) {
124
+ await this.record(entry, name, event, 'override', this.outcome(error), failureMessage(error));
125
+ throw error;
126
+ }
127
+ }
128
+ async transformBeforeToolCall(event) {
129
+ let params = { ...event.params };
130
+ const changes = [];
131
+ for (const entry of this.entries('before_tool_call', 'transform')) {
132
+ const current = { ...event, params: { ...params } };
133
+ try {
134
+ const result = await this.invoke(entry, current);
135
+ if (result !== undefined && result !== null) {
136
+ if (!isParams(result))
137
+ throw new Error('before_tool_call Transform must return a parameter object');
138
+ params = { ...result };
139
+ changes.push({ pluginId: entry.pluginId, value: { ...params } });
140
+ }
141
+ await this.record(entry, 'before_tool_call', current, 'transform', 'ok', undefined, {
142
+ toolName: event.toolName,
143
+ callId: event.call.id,
144
+ originalParams: current.params,
145
+ finalParams: { ...params },
146
+ });
147
+ }
148
+ catch (error) {
149
+ await this.record(entry, 'before_tool_call', current, 'transform', this.outcome(error), failureMessage(error), {
150
+ toolName: event.toolName,
151
+ callId: event.call.id,
152
+ originalParams: event.params,
153
+ });
154
+ throw error;
155
+ }
156
+ }
157
+ return { value: params, changes };
158
+ }
159
+ async voteBeforeToolCall(event, originalParams) {
160
+ const pending = [];
161
+ let denied;
162
+ for (const entry of this.entries('before_tool_call', 'vote')) {
163
+ const vote = await this.invokeVote(entry, event, {
164
+ toolName: event.toolName,
165
+ callId: event.call.id,
166
+ originalParams,
167
+ params: event.params,
168
+ });
169
+ pending.push({ entry, vote });
170
+ if (vote.decision === 'deny')
171
+ denied = vote;
172
+ }
173
+ // A deny from any participant wins without prompting for an unnecessary approval.
174
+ if (denied)
175
+ return denied;
176
+ let final = { decision: 'allow' };
177
+ for (const { entry, vote } of pending) {
178
+ if (vote.decision !== 'require_approval')
179
+ continue;
180
+ if (!vote.approval) {
181
+ const reason = 'require_approval requires an approval request';
182
+ await this.record(entry, 'before_tool_call', event, 'vote', 'denied', reason);
183
+ return { decision: 'deny', pluginId: entry.pluginId, reason };
184
+ }
185
+ const approved = await this.host.approveToolCall(event, vote.approval, entry.pluginId);
186
+ const denyReason = approved.denyDetail
187
+ ?? (approved.timedOut ? 'Host approval timed out' : 'Host approval was not granted');
188
+ await this.record(entry, 'before_tool_call', event, 'vote', approved.allowed ? 'ok' : 'denied', approved.allowed ? undefined : denyReason, {
189
+ approval: vote.approval,
190
+ toolName: event.toolName,
191
+ callId: event.call.id,
192
+ hitlDecision: approved.decision,
193
+ ...(approved.timedOut ? { timedOut: true } : {}),
194
+ ...(approved.denyReason === undefined ? {} : { denyReason: approved.denyReason }),
195
+ });
196
+ if (!approved.allowed) {
197
+ return { decision: 'deny', pluginId: entry.pluginId, reason: denyReason };
198
+ }
199
+ // The Host decision resolved this Vote: approved means allow, not "still pending".
200
+ final = { decision: 'allow', pluginId: entry.pluginId };
201
+ }
202
+ return final;
203
+ }
204
+ async beforeIteration(event) {
205
+ const transform = {};
206
+ const snapshotContributions = [];
207
+ for (const entry of this.entries('before_iteration', 'transform')) {
208
+ const current = {
209
+ ...event,
210
+ model: transform.model ?? event.model,
211
+ thinking: transform.thinking ?? event.thinking,
212
+ };
213
+ try {
214
+ const result = await this.invoke(entry, current);
215
+ if (result) {
216
+ if (typeof result.snapshot === 'string') {
217
+ transform.snapshot = [transform.snapshot, result.snapshot].filter(Boolean).join('\n\n');
218
+ if (result.snapshot.trim())
219
+ snapshotContributions.push({ pluginId: entry.pluginId, value: result.snapshot });
220
+ }
221
+ if (result.model)
222
+ transform.model = { ...result.model };
223
+ if (result.thinking !== undefined)
224
+ transform.thinking = result.thinking;
225
+ }
226
+ await this.record(entry, 'before_iteration', current, 'transform', 'ok', undefined, {
227
+ model: transform.model,
228
+ thinking: transform.thinking,
229
+ snapshotPluginIds: snapshotContributions.map((contribution) => contribution.pluginId),
230
+ });
231
+ }
232
+ catch (error) {
233
+ await this.record(entry, 'before_iteration', current, 'transform', this.outcome(error), failureMessage(error));
234
+ throw error;
235
+ }
236
+ }
237
+ let final = { decision: 'allow' };
238
+ const finalEvent = {
239
+ ...event,
240
+ model: transform.model ?? event.model,
241
+ thinking: transform.thinking ?? event.thinking,
242
+ };
243
+ for (const entry of this.entries('before_iteration', 'vote')) {
244
+ const vote = await this.invokeVote(entry, finalEvent);
245
+ if (vote.decision === 'deny')
246
+ final = vote;
247
+ else if (vote.decision === 'require_approval') {
248
+ final = { decision: 'deny', pluginId: entry.pluginId, reason: 'before_iteration does not support approval votes' };
249
+ await this.record(entry, 'before_iteration', finalEvent, 'vote', 'denied', final.reason);
250
+ }
251
+ }
252
+ return { transform, snapshotContributions: [...snapshotContributions], vote: final };
253
+ }
254
+ async approveToolCall(event, request, pluginId) {
255
+ return this.host.approveToolCall(event, request, pluginId);
256
+ }
257
+ entries(name, phase) {
258
+ return this.host.getHooks()
259
+ .map((entry, index) => ({ entry, index }))
260
+ .filter(({ entry }) => entry.hookName === name && entry.phase === phase)
261
+ .sort((a, b) => b.entry.priority - a.entry.priority || a.index - b.index)
262
+ .map(({ entry }) => entry);
263
+ }
264
+ async invokeVote(entry, event, details) {
265
+ let vote;
266
+ let failure;
267
+ try {
268
+ const result = await this.invoke(entry, event);
269
+ if (result !== undefined && result !== null && !isVote(result)) {
270
+ throw new Error('Vote hook must return {decision}');
271
+ }
272
+ vote = result === undefined || result === null
273
+ ? { decision: 'allow', pluginId: entry.pluginId }
274
+ : { ...result, pluginId: entry.pluginId };
275
+ }
276
+ catch (error) {
277
+ // Fail-closed to deny, but the audit must not relabel a handler failure as a
278
+ // human/policy deny — record the real cause class and keep the message.
279
+ failure = this.outcome(error);
280
+ vote = { decision: 'deny', pluginId: entry.pluginId, reason: failureMessage(error) };
281
+ }
282
+ await this.record(entry, entry.hookName, event, 'vote', failure ?? (vote.decision === 'deny' ? 'denied' : 'ok'), vote.reason, details);
283
+ return vote;
284
+ }
285
+ transformEvent(name, event, value) {
286
+ if (name === 'agent_turn_prepare')
287
+ return { ...event, prompt: value };
288
+ if (name === 'before_model_resolve')
289
+ return { ...event, current: value };
290
+ if (name === 'before_agent_finalize')
291
+ return { ...event, reply: value };
292
+ throw new Error(`${name} is not a Transform hook`);
293
+ }
294
+ transformedValue(name, previous, next) {
295
+ if (name === 'agent_turn_prepare') {
296
+ if (typeof next !== 'string')
297
+ throw new Error('agent_turn_prepare must return a prompt string');
298
+ return next;
299
+ }
300
+ if (name === 'before_agent_finalize') {
301
+ const value = typeof next === 'string'
302
+ ? { ...previous, content: next }
303
+ : next;
304
+ if (!isParams(value) || value.role !== 'assistant') {
305
+ throw new Error('before_agent_finalize must return an assistant Message or string');
306
+ }
307
+ const message = value;
308
+ if (message.toolCalls?.length) {
309
+ throw new Error('before_agent_finalize must not add toolCalls to the final reply');
310
+ }
311
+ if (typeof message.content !== 'string' && !Array.isArray(message.content)) {
312
+ throw new Error('before_agent_finalize must keep text or block-array content');
313
+ }
314
+ return value;
315
+ }
316
+ if (name === 'before_model_resolve') {
317
+ if (!isParams(next) || typeof next.provider !== 'string' || !next.provider ||
318
+ typeof next.model !== 'string' || !next.model) {
319
+ throw new Error('before_model_resolve must return non-empty provider/model strings');
320
+ }
321
+ return { provider: next.provider, model: next.model };
322
+ }
323
+ throw new Error(`${name} is not a Transform hook`);
324
+ }
325
+ async invoke(entry, event) {
326
+ const parent = event.signal;
327
+ if (parent?.aborted)
328
+ throw new Error('Hook aborted before handler start');
329
+ const controller = new AbortController();
330
+ const timeoutMs = this.host.getPluginConfig(entry.pluginId)?.hooks?.timeouts?.[entry.hookName]
331
+ ?? this.host.getPluginConfig(entry.pluginId)?.hooks?.timeoutMs
332
+ ?? entry.timeoutMs ?? 30_000;
333
+ let timedOut = false;
334
+ let settled = false;
335
+ const abort = () => controller.abort(parent?.reason);
336
+ parent?.addEventListener('abort', abort, { once: true });
337
+ const timer = setTimeout(() => {
338
+ timedOut = true;
339
+ controller.abort(new Error(`Hook handler timed out after ${timeoutMs}ms`));
340
+ }, timeoutMs);
341
+ try {
342
+ return await new Promise((resolve, reject) => {
343
+ const finish = (fn) => {
344
+ if (settled)
345
+ return;
346
+ settled = true;
347
+ fn();
348
+ };
349
+ controller.signal.addEventListener('abort', () => {
350
+ finish(() => reject(timedOut
351
+ ? new Error(`Hook handler timed out after ${timeoutMs}ms`)
352
+ : new Error('Hook handler aborted')));
353
+ }, { once: true });
354
+ Promise.resolve().then(() => entry.handler({ ...event, signal: controller.signal })).then((result) => finish(() => resolve(result)), (error) => finish(() => reject(error)));
355
+ });
356
+ }
357
+ finally {
358
+ settled = true;
359
+ clearTimeout(timer);
360
+ parent?.removeEventListener('abort', abort);
361
+ }
362
+ }
363
+ outcome(error) {
364
+ const message = failureMessage(error);
365
+ return message.includes('timed out') ? 'timeout' : message.includes('aborted') ? 'aborted' : 'error';
366
+ }
367
+ async execute(entry, event, phase, fn) {
368
+ try {
369
+ await fn();
370
+ await this.record(entry, entry.hookName, event, phase, 'ok');
371
+ }
372
+ catch (error) {
373
+ // Observe and optional Collect explicitly fail open; their audit records the failure.
374
+ await this.record(entry, entry.hookName, event, phase, this.outcome(error), failureMessage(error));
375
+ }
376
+ }
377
+ async record(entry, name, event, phase, outcome, reason, details) {
378
+ try {
379
+ await this.host.recordHook({
380
+ pluginId: entry.pluginId,
381
+ hookName: name,
382
+ phase,
383
+ outcome,
384
+ sessionId: event.sessionId,
385
+ agentId: event.agentId,
386
+ ...(event.runId === undefined ? {} : { runId: event.runId }),
387
+ ...(event.principal === undefined ? {} : { principal: event.principal }),
388
+ ...(reason === undefined ? {} : { reason }),
389
+ ...(details === undefined ? {} : { details }),
390
+ });
391
+ }
392
+ catch (error) {
393
+ // Audit is an observability sink here, not an authorization grant; retain the original decision.
394
+ console.error(`[PluginHookAdapter] audit failed for ${entry.pluginId}/${name}:`, error);
395
+ }
396
+ }
397
+ }
@@ -0,0 +1,16 @@
1
+ import type { CompactEngine, CompactOptions, CompactOutcome } from '../../../context/capabilities/compact/index.js';
2
+ import type { ExtensionHookPort } from './types.js';
3
+ /** Keep Hook admission outside compaction algorithms and the E4 state transition. */
4
+ export declare class HookedCompactEngine implements CompactEngine {
5
+ private readonly inner;
6
+ private readonly port;
7
+ private readonly identity;
8
+ constructor(inner: CompactEngine, port: ExtensionHookPort, identity: {
9
+ sessionId: string;
10
+ agentId?: string;
11
+ });
12
+ /** Text compaction is not a Session compaction event. */
13
+ compactText(text: string, options?: CompactOptions): Promise<CompactOutcome>;
14
+ /** Vote before any summary work; observe the actual success/degraded/fresh result. */
15
+ compactMessages(messages: Parameters<CompactEngine['compactMessages']>[0], options: CompactOptions): Promise<CompactOutcome>;
16
+ }
@@ -0,0 +1,66 @@
1
+ import { getRunScope } from '../../../run/run-scope.js';
2
+ import { HeuristicTokenEstimator } from '../../../context/token-estimator.js';
3
+ /** Keep Hook admission outside compaction algorithms and the E4 state transition. */
4
+ export class HookedCompactEngine {
5
+ inner;
6
+ port;
7
+ identity;
8
+ constructor(inner, port, identity) {
9
+ this.inner = inner;
10
+ this.port = port;
11
+ this.identity = identity;
12
+ }
13
+ /** Text compaction is not a Session compaction event. */
14
+ compactText(text, options) {
15
+ return this.inner.compactText(text, options);
16
+ }
17
+ /** Vote before any summary work; observe the actual success/degraded/fresh result. */
18
+ async compactMessages(messages, options) {
19
+ const scope = getRunScope();
20
+ const event = {
21
+ // Explicit caller identity wins: a manual compaction must not be attributed
22
+ // to whatever Run happens to hold the async context.
23
+ sessionId: options.sessionId ?? scope?.sessionId ?? this.identity.sessionId,
24
+ agentId: options.agentId ?? scope?.agentId ?? this.identity.agentId ?? 'default',
25
+ ...(scope?.runId === undefined ? {} : { runId: scope.runId }),
26
+ ...(scope?.principal === undefined ? {} : { principal: scope.principal }),
27
+ ...(options.signal === undefined ? {} : { signal: options.signal }),
28
+ mode: options.mode ?? 'auto',
29
+ previousSummary: options.previousSummary,
30
+ };
31
+ const vote = await this.port.vote('before_compaction', event);
32
+ if (vote.decision !== 'allow') {
33
+ return {
34
+ ok: true,
35
+ summary: options.previousSummary,
36
+ compacted: false,
37
+ reason: `denied:${vote.reason ?? 'before_compaction'}`,
38
+ tokensBefore: options.estimator?.estimateMessages(messages)
39
+ ?? new HeuristicTokenEstimator().estimateMessages(messages),
40
+ summarizeAttempted: false,
41
+ fresh: false,
42
+ view: [...messages],
43
+ };
44
+ }
45
+ try {
46
+ const outcome = await this.inner.compactMessages(messages, options);
47
+ await this.port.observe('after_compaction', {
48
+ ...event,
49
+ coveredMessageCount: options.foldRange?.replacedCount,
50
+ compacted: outcome.compacted,
51
+ fresh: outcome.fresh,
52
+ reason: outcome.reason,
53
+ });
54
+ return outcome;
55
+ }
56
+ catch (error) {
57
+ await this.port.observe('after_compaction', {
58
+ ...event,
59
+ compacted: false,
60
+ fresh: false,
61
+ error: error instanceof Error ? error.message : String(error),
62
+ });
63
+ throw error;
64
+ }
65
+ }
66
+ }
@@ -0,0 +1,4 @@
1
+ export { PluginHookAdapter, HookDeniedError, requireHookApproval } from './adapter.js';
2
+ export type { HookExecutionHost, RegisteredHook } from './adapter.js';
3
+ export { HookAuditJournal } from './journal.js';
4
+ export type { ExtensionHookContext, ExtensionHookHandler, ExtensionHookMap, ExtensionHookPort, HookAuditRecord, HookCollectResult, HookContribution, HookEvent, HookIterationEvent, HookIterationTransform, HookModelSelection, HookResult, HookSemantics, HookServiceRegistration, HookToolApproval, HookToolEvent, HookTransformResult, HookVote, } from './types.js';
@@ -0,0 +1,2 @@
1
+ export { PluginHookAdapter, HookDeniedError, requireHookApproval } from './adapter.js';
2
+ export { HookAuditJournal } from './journal.js';
@@ -0,0 +1,11 @@
1
+ import type { LLMMessage } from '@octopi-agent/core/interfaces/model-provider.js';
2
+ /**
3
+ * Build a Run/Iteration-only view. The authoritative turn_start remains byte-frozen.
4
+ * No system role is added and plugin content cannot masquerade as a user stimulus.
5
+ */
6
+ export declare function projectPluginIterationSnapshot(messages: LLMMessage[], contributions: readonly {
7
+ pluginId: string;
8
+ text: string;
9
+ }[], tokenBudget: number): Promise<LLMMessage[]>;
10
+ /** Apply the configured token budget before the snapshot reaches a model request. */
11
+ export declare function iterationSnapshotTokenBudget(configured: number | undefined, contextWindow: number | undefined): number;
@@ -0,0 +1,54 @@
1
+ import { formatTurnContextXml, formatTurnStartContent, joinSlotXml, parseTurnEnvelope, } from '../../../context/turn-envelope.js';
2
+ import { PluginRuntimeSnapshotLayer } from '../../../context/layers.js';
3
+ /**
4
+ * Build a Run/Iteration-only view. The authoritative turn_start remains byte-frozen.
5
+ * No system role is added and plugin content cannot masquerade as a user stimulus.
6
+ */
7
+ export async function projectPluginIterationSnapshot(messages, contributions, tokenBudget) {
8
+ if (contributions.length === 0)
9
+ return messages;
10
+ const layer = new PluginRuntimeSnapshotLayer(contributions.map(({ pluginId, text }) => ({ pluginId, value: { text } })));
11
+ const projected = await layer.assemble({
12
+ sessionId: 'run',
13
+ messages: [],
14
+ tokenBudget: Math.max(1, tokenBudget),
15
+ systemBudget: 0,
16
+ });
17
+ if (!projected)
18
+ return messages;
19
+ const index = messages.findLastIndex((message) => parseTurnEnvelope(message.content) !== null);
20
+ if (index < 0)
21
+ throw new Error('before_iteration snapshot requires a current turn_start envelope');
22
+ const original = messages[index];
23
+ const parsed = parseTurnEnvelope(original.content);
24
+ if (!parsed.turnId || !parsed.at || !parsed.hasUserMessage) {
25
+ throw new Error('before_iteration snapshot cannot rewrite an incomplete turn envelope');
26
+ }
27
+ const slots = parsed.slots.map((slot) => ({ tag: slot.tag, body: slot.body }));
28
+ const runtime = slots.find((slot) => slot.tag === 'runtime_snapshot');
29
+ if (runtime)
30
+ runtime.body = [runtime.body, projected.text].filter(Boolean).join('\n\n');
31
+ else
32
+ slots.unshift({ tag: 'runtime_snapshot', body: projected.text });
33
+ const content = formatTurnStartContent({
34
+ turnId: parsed.turnId,
35
+ at: parsed.at,
36
+ turnContextXml: formatTurnContextXml({ turnId: parsed.turnId, slotsXml: joinSlotXml(slots) }),
37
+ userText: parsed.userText,
38
+ });
39
+ const copy = { ...original };
40
+ if (typeof original.content === 'string' || original.content == null)
41
+ copy.content = content;
42
+ else if (Array.isArray(original.content)) {
43
+ copy.content = [
44
+ { type: 'text', text: content },
45
+ ...original.content.filter((block) => block.type !== 'text'),
46
+ ];
47
+ }
48
+ return [...messages.slice(0, index), copy, ...messages.slice(index + 1)];
49
+ }
50
+ /** Apply the configured token budget before the snapshot reaches a model request. */
51
+ export function iterationSnapshotTokenBudget(configured, contextWindow) {
52
+ const cap = Math.max(1, Math.floor((contextWindow ?? 8192) * 0.1));
53
+ return Math.max(1, Math.min(configured ?? 4096, cap));
54
+ }
@@ -0,0 +1,9 @@
1
+ import type { HookAuditRecord } from './types.js';
2
+ /** Append-only hook audit; not a tamper-evident ledger or a sandbox. */
3
+ export declare class HookAuditJournal {
4
+ private readonly rootDir;
5
+ private tail;
6
+ constructor(rootDir: () => string);
7
+ /** Serialize appends per journal instance and surface write failures to the Host. */
8
+ append(record: HookAuditRecord): Promise<void>;
9
+ }
@@ -0,0 +1,22 @@
1
+ import { appendFile, mkdir } from 'node:fs/promises';
2
+ import { join } from 'node:path';
3
+ /** Append-only hook audit; not a tamper-evident ledger or a sandbox. */
4
+ export class HookAuditJournal {
5
+ rootDir;
6
+ tail = Promise.resolve();
7
+ constructor(rootDir) {
8
+ this.rootDir = rootDir;
9
+ }
10
+ /** Serialize appends per journal instance and surface write failures to the Host. */
11
+ append(record) {
12
+ const task = this.tail.then(async () => {
13
+ const directory = join(this.rootDir(), 'hooks');
14
+ await mkdir(directory, { recursive: true });
15
+ const day = new Date().toISOString().slice(0, 10);
16
+ const entry = { timestamp: Date.now(), ...record };
17
+ await appendFile(join(directory, `${day}.jsonl`), `${JSON.stringify(entry)}\n`, 'utf8');
18
+ });
19
+ this.tail = task.catch(() => undefined);
20
+ return task;
21
+ }
22
+ }
@@ -0,0 +1,12 @@
1
+ declare const terminalMarker: unique symbol;
2
+ /** A Host-controlled extension failure must not enter the model transport retry policy. */
3
+ export declare class ExtensionTerminalError extends Error {
4
+ readonly cause: unknown;
5
+ readonly [terminalMarker] = true;
6
+ constructor(cause: unknown);
7
+ }
8
+ /** This is a Host/reliability policy, not a Core or Plugin contract. */
9
+ export declare function shouldAbortWithoutRetry(error: unknown): boolean;
10
+ /** Restore the extension failure to the normal Agent error-event surface. */
11
+ export declare function unwrapExtensionTerminalError(error: unknown): unknown;
12
+ export {};