@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
@@ -1,17 +1,26 @@
1
1
  /**
2
2
  * Plugin registerCommand → CommandRouter 桥接
3
3
  */
4
+ /**
5
+ * Mount effective plugin contributions without replacing author-declared metadata.
6
+ * The ref is Host-assigned plugin identity; it is not supplied by the handler.
7
+ *
8
+ * @param pm - Manager whose effective contribution registry has been published
9
+ * @returns Command definitions and stable plugin registration references
10
+ */
4
11
  export function pluginCommandsFromManager(pm) {
5
12
  return pm.getCommands().map((cmd) => {
6
13
  const rawName = cmd.name.replace(/^\/+/, '');
7
- return {
14
+ const definition = {
8
15
  name: rawName,
9
16
  description: cmd.description ?? rawName,
10
17
  usage: `/${rawName}`,
11
- kind: 'control',
18
+ kind: cmd.kind ?? 'control',
12
19
  source: 'plugin',
13
- risk: 'low',
14
- invocableBy: ['principal', 'plugin'],
20
+ ...(cmd.risk === undefined ? {} : { risk: cmd.risk }),
21
+ ...(cmd.invocableBy === undefined ? {} : { invocableBy: cmd.invocableBy }),
22
+ ...(cmd.args === undefined ? {} : { args: cmd.args }),
23
+ ...(cmd.preempt === undefined ? {} : { preempt: cmd.preempt }),
15
24
  async execute(ctx) {
16
25
  try {
17
26
  const out = (await cmd.handler({
@@ -45,5 +54,6 @@ export function pluginCommandsFromManager(pm) {
45
54
  }
46
55
  },
47
56
  };
57
+ return { definition, ref: cmd.pluginId };
48
58
  });
49
59
  }
@@ -3,13 +3,13 @@
3
3
  *
4
4
  * 冲突策略(§6.0):
5
5
  * - 保留名:非 builtin 不得占用(可选 allowReservedOverride + prefer-source 显式胜出)
6
- * - 同 (source, ref) 重复注册 = upsert(skill 热重载安全)
6
+ * - 同 (source, ref, name) 重复注册 = upsert;ref 可同时承载一个插件的多个 Command
7
7
  * - 同名多候选(≥2)= reject-all:无一 active,候选保留至收敛到 1
8
8
  * - 永不因 reject-all 删除已注册 builtin
9
9
  * - Run 在途:仅 preempt 命令立即执行(默认仅 /stop)
10
10
  */
11
11
  import type { IssueRegistry } from '../../../observability/diagnostics/registry.js';
12
- import type { CommandCatalogItem, CommandConflict, CommandDefinition, CommandRegisterResult, CommandResult, CommandSource, ConflictPolicy, PrincipalRef, SessionOp, SessionReadView } from './types.js';
12
+ import type { CommandCatalogItem, CommandConflict, CommandDefinition, CommandExecutionSource, CommandRegisterResult, CommandResult, CommandSource, ConflictPolicy, PrincipalRef, SessionOp, SessionReadView } from './types.js';
13
13
  export interface CommandRouterOptions {
14
14
  issueRegistry?: IssueRegistry;
15
15
  conflictPolicy?: ConflictPolicy;
@@ -31,6 +31,7 @@ export type ExecuteCommandOutcome = {
31
31
  kind: 'command';
32
32
  result: CommandResult;
33
33
  definition?: CommandDefinition;
34
+ executionSource?: CommandExecutionSource;
34
35
  conflict?: CommandConflict;
35
36
  };
36
37
  export declare class CommandRouter {
@@ -46,10 +47,10 @@ export declare class CommandRouter {
46
47
  private sourcePriority;
47
48
  constructor(options?: CommandRouterOptions);
48
49
  /**
49
- * 注册命令。同 (source, ref) 为 upsert;按 name 候选数重算 active。
50
+ * 注册命令。同 (source, ref, name) 为 upsert;按 name 候选数重算 active。
50
51
  */
51
52
  register(definition: CommandDefinition, ref?: string): CommandRegisterResult;
52
- /** 按 (source, ref) 注销候选并重算 */
53
+ /** 按 (source, ref, name) 注销候选并重算 */
53
54
  unregister(source: CommandSource, ref: string, name: string): void;
54
55
  get(name: string): CommandDefinition | null;
55
56
  listDefinitions(): CommandDefinition[];
@@ -3,15 +3,15 @@
3
3
  *
4
4
  * 冲突策略(§6.0):
5
5
  * - 保留名:非 builtin 不得占用(可选 allowReservedOverride + prefer-source 显式胜出)
6
- * - 同 (source, ref) 重复注册 = upsert(skill 热重载安全)
6
+ * - 同 (source, ref, name) 重复注册 = upsert;ref 可同时承载一个插件的多个 Command
7
7
  * - 同名多候选(≥2)= reject-all:无一 active,候选保留至收敛到 1
8
8
  * - 永不因 reject-all 删除已注册 builtin
9
9
  * - Run 在途:仅 preempt 命令立即执行(默认仅 /stop)
10
10
  */
11
11
  import { parseCommand, normalizeCommandName, unescapeLiteralSlash } from './parse.js';
12
12
  const DEFAULT_PRIORITY = ['builtin', 'plugin', 'user', 'skill'];
13
- function candidateKey(source, ref) {
14
- return source + '\0' + ref;
13
+ function candidateKey(source, ref, name) {
14
+ return `${source}\0${ref}\0${name}`;
15
15
  }
16
16
  export class CommandRouter {
17
17
  /** 全部候选(含冲突中未激活的) */
@@ -31,7 +31,7 @@ export class CommandRouter {
31
31
  this.sourcePriority = options.sourcePriority ?? DEFAULT_PRIORITY;
32
32
  }
33
33
  /**
34
- * 注册命令。同 (source, ref) 为 upsert;按 name 候选数重算 active。
34
+ * 注册命令。同 (source, ref, name) 为 upsert;按 name 候选数重算 active。
35
35
  */
36
36
  register(definition, ref) {
37
37
  const name = normalizeCommandName(definition.name);
@@ -50,16 +50,16 @@ export class CommandRouter {
50
50
  this.rejectName(name, conflict, `命令 /${name} 未加载`, `保留名 /${name} 不可被 ${definition.source}(${sourceRef})占用。`, `commands:command.reserved_denied:${name}`);
51
51
  return { ok: false, reason: 'conflict', conflict };
52
52
  }
53
- this.candidates.set(candidateKey(definition.source, sourceRef), {
53
+ this.candidates.set(candidateKey(definition.source, sourceRef, name), {
54
54
  definition: normalized,
55
55
  ref: sourceRef,
56
56
  name,
57
57
  });
58
58
  return this.recompute(name);
59
59
  }
60
- /** 按 (source, ref) 注销候选并重算 */
60
+ /** 按 (source, ref, name) 注销候选并重算 */
61
61
  unregister(source, ref, name) {
62
- this.candidates.delete(candidateKey(source, ref));
62
+ this.candidates.delete(candidateKey(source, ref, normalizeCommandName(name) ?? name));
63
63
  this.recompute(normalizeCommandName(name) ?? name);
64
64
  }
65
65
  get(name) {
@@ -129,10 +129,12 @@ export class CommandRouter {
129
129
  };
130
130
  }
131
131
  const def = entry.definition;
132
+ const executionSource = { source: def.source, ref: entry.ref };
132
133
  if (!this.isInvokedBy(def, principal)) {
133
134
  return {
134
135
  kind: 'command',
135
136
  definition: def,
137
+ executionSource,
136
138
  result: {
137
139
  status: 'denied',
138
140
  display: textDisplay(`命令 /${def.name} 不允许当前调用方使用。`),
@@ -144,6 +146,7 @@ export class CommandRouter {
144
146
  return {
145
147
  kind: 'command',
146
148
  definition: def,
149
+ executionSource,
147
150
  result: {
148
151
  status: 'error',
149
152
  display: textDisplay('Agent 正在运行——可发送 /stop 中止后再试。'),
@@ -157,6 +160,7 @@ export class CommandRouter {
157
160
  return {
158
161
  kind: 'command',
159
162
  definition: def,
163
+ executionSource,
160
164
  result: {
161
165
  status: 'ok',
162
166
  display: textDisplay(`已展开 /${def.name}`),
@@ -167,12 +171,13 @@ export class CommandRouter {
167
171
  };
168
172
  }
169
173
  const result = await def.execute(ctx);
170
- return { kind: 'command', definition: def, result };
174
+ return { kind: 'command', definition: def, executionSource, result };
171
175
  }
172
176
  catch (err) {
173
177
  return {
174
178
  kind: 'command',
175
179
  definition: def,
180
+ executionSource,
176
181
  result: {
177
182
  status: 'error',
178
183
  display: textDisplay(`命令 /${def.name} 执行失败:${err instanceof Error ? err.message : String(err)}`),
@@ -262,13 +267,17 @@ export class CommandRouter {
262
267
  }
263
268
  isInvokedBy(def, principal) {
264
269
  const allowed = def.invocableBy ?? ['principal'];
265
- const actorType = principal.actorType ?? 'user';
266
- if (actorType === 'agent')
267
- return allowed.includes('agent');
268
- if (actorType === 'service' || actorType === 'subsystem') {
269
- return allowed.includes('plugin') || allowed.includes('principal');
270
+ switch (principal.actorType ?? 'user') {
271
+ case 'host':
272
+ case 'user':
273
+ case 'timer':
274
+ return allowed.includes('principal');
275
+ case 'agent':
276
+ return allowed.includes('agent');
277
+ case 'service':
278
+ case 'subsystem':
279
+ return allowed.includes('service');
270
280
  }
271
- return allowed.includes('principal');
272
281
  }
273
282
  higherSource(a, b) {
274
283
  return this.sourcePriority.indexOf(a) <= this.sourcePriority.indexOf(b);
@@ -7,7 +7,9 @@
7
7
  export type CommandKind = 'client' | 'control' | 'prompt';
8
8
  export type CommandSource = 'builtin' | 'plugin' | 'user' | 'skill';
9
9
  export type CommandRisk = 'low' | 'medium' | 'high';
10
- export type CommandInvoker = 'principal' | 'agent' | 'plugin';
10
+ /** Invoker categories expressible by PrincipalRef; source="plugin" is not caller identity. */
11
+ export declare const COMMAND_INVOKERS: readonly ["principal", "agent", "service"];
12
+ export type CommandInvoker = (typeof COMMAND_INVOKERS)[number];
11
13
  export type SessionOp = {
12
14
  op: 'abort_run';
13
15
  reason?: string;
@@ -111,6 +113,11 @@ export interface CommandConflictCandidate {
111
113
  ref: string;
112
114
  action: 'registered' | 'rejected' | 'shadowed';
113
115
  }
116
+ /** Host-assigned identity of the mounted definition; never accepted from a handler. */
117
+ export interface CommandExecutionSource {
118
+ source: CommandSource;
119
+ ref: string;
120
+ }
114
121
  export interface CommandConflict {
115
122
  name: string;
116
123
  candidates: CommandConflictCandidate[];
@@ -4,4 +4,5 @@
4
4
  * 归属:plugin-ecosystem/commands(调用面,与 tools/ 对偶)。
5
5
  * 效应经 sessionOps 由 Host 落地;handler 不直接改 session/model(I1/I6)。
6
6
  */
7
- export {};
7
+ /** Invoker categories expressible by PrincipalRef; source="plugin" is not caller identity. */
8
+ export const COMMAND_INVOKERS = ['principal', 'agent', 'service'];
@@ -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
+ }