@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,289 +1,123 @@
1
- /**
2
- * Plugin API
3
- *
4
- * 这是 plugin register() 回调中接收的 api 对象。
5
- * Plugin 通过它注册各种能力(provider、channel、tool、hook 等)。
6
- */
7
- import type { ModelProvider } from '@octopi-agent/core/interfaces/model-provider.js';
8
- import type { WebSearchProvider } from '../tools/web-search-types.js';
9
- import type { ToolDefinition, ToolHandler } from '@octopi-agent/core/types.js';
10
- import type { ContextEngine } from '../../../context/types.js';
11
- import type { ChannelAdapter } from '../channel-types.js';
12
- /**
13
- * Hook 注册选项
14
- */
15
- export interface HookRegistrationOptions {
16
- /** 优先级(数字越大越先执行,默认 0) */
17
- priority?: number;
18
- /** 单个 handler 超时毫秒数 */
1
+ /** Public author API. Runtime ownership lives in PluginContributionRegistry. */
2
+ import { type ToolDefinition, type ToolHandler } from '@octopi-agent/core/types.js';
3
+ import type { PluginHookName, PluginSessionOpName } from './manifest.js';
4
+ import type { ExtensionHookHandler, HookEvent, HookResult, HookServiceRegistration, HookIterationTransform, HookVote } from '../hooks/types.js';
5
+ import type { ArgSpec, CommandInvoker, CommandKind, CommandResult, CommandRisk } from '../commands/types.js';
6
+ export interface PluginCommandContext {
7
+ sessionId: string;
8
+ agentId: string;
9
+ args: string[];
10
+ raw: string;
11
+ principal: {
12
+ actorId?: string;
13
+ actorType?: string;
14
+ tenantId?: string;
15
+ };
16
+ }
17
+ export interface PluginCommandRegistration {
18
+ name: string;
19
+ description?: string;
20
+ /** Client-side commands require a client contract and are not Plugin v1 contributions. */
21
+ kind?: Exclude<CommandKind, 'client'>;
22
+ risk?: CommandRisk;
23
+ invocableBy?: CommandInvoker[];
24
+ args?: ArgSpec[];
25
+ preempt?: boolean;
26
+ sessionOps?: PluginSessionOpName[];
27
+ handler: (context: PluginCommandContext) => Promise<CommandResult | string | void | unknown>;
28
+ }
29
+ export type PluginHookMap = {
30
+ [K in PluginHookName]: [HookEvent<K>, HookResult<K>];
31
+ };
32
+ export type HookHandler<K extends PluginHookName = PluginHookName> = ExtensionHookHandler<K>;
33
+ export type HookResultFor<K extends PluginHookName, P extends 'transform' | 'vote'> = K extends 'before_tool_call' ? P extends 'transform' ? Record<string, unknown> | void : HookVote | void : K extends 'before_iteration' ? P extends 'transform' ? HookIterationTransform | void : HookVote | void : never;
34
+ export interface OrderedHookEntry {
35
+ pluginId: string;
36
+ hookName: PluginHookName;
37
+ handler: (event: never) => unknown;
38
+ phase: 'single' | 'transform' | 'vote';
39
+ priority: number;
19
40
  timeoutMs?: number;
20
41
  }
21
- /**
22
- * Tool 注册选项
23
- */
42
+ export interface PluginToolContribution {
43
+ definition: ToolDefinition;
44
+ handler: ToolHandler;
45
+ optional: boolean;
46
+ executionMode?: 'parallel' | 'sequential';
47
+ }
24
48
  export interface ToolRegistrationOptions {
25
- /** 是否为可选工具(需要用户显式启用) */
49
+ /** Visibility is separately controlled by the Agent's tools allow/deny policy. */
26
50
  optional?: boolean;
51
+ executionMode?: 'parallel' | 'sequential';
27
52
  }
28
- /**
29
- * Provider 注册定义
30
- */
31
- export interface ProviderRegistration {
32
- /** Provider ID */
33
- id: string;
34
- /** Provider 实例 */
35
- provider: ModelProvider;
36
- }
37
- /**
38
- * Channel 注册定义
39
- */
40
- export interface ChannelRegistration {
41
- /** Channel ID */
42
- id: string;
43
- /** Channel Adapter 实例 */
44
- adapter: ChannelAdapter;
53
+ export interface HookRegistrationOptions {
54
+ /** Required for the two dual-phase events; ordinary events must not set it. */
55
+ phase?: 'transform' | 'vote';
56
+ priority?: number;
57
+ timeoutMs?: number;
45
58
  }
46
- /**
47
- * Hook handler 类型
48
- */
49
- export type HookHandler<TEvent = unknown, TResult = void> = (event: TEvent) => Promise<TResult | undefined | void>;
50
- /**
51
- * 有序 hook entry
52
- */
53
- export interface OrderedHookEntry {
54
- /** Plugin ID */
55
- pluginId: string;
56
- /** Hook 名称 */
57
- hookName: string;
58
- /** Handler 函数 */
59
- handler: HookHandler;
60
- /** 优先级 */
61
- priority: number;
62
- /** 超时 */
59
+ export interface DualPhaseHookOptions {
60
+ phase: 'transform' | 'vote';
61
+ priority?: number;
63
62
  timeoutMs?: number;
64
63
  }
65
- /**
66
- * Plugin Logger
67
- */
68
64
  export interface PluginLogger {
69
65
  debug(message: string, ...args: unknown[]): void;
70
66
  info(message: string, ...args: unknown[]): void;
71
67
  warn(message: string, ...args: unknown[]): void;
72
68
  error(message: string, ...args: unknown[]): void;
73
69
  }
74
- /**
75
- * Plugin API
76
- *
77
- * Plugin 在 register() 回调中使用此对象注册能力。
78
- */
79
70
  export declare class PluginApi {
80
- /** Plugin ID */
81
71
  readonly id: string;
82
- /** Plugin 显示名称 */
83
72
  readonly name: string;
84
- /** Plugin 版本 */
85
- readonly version?: string;
86
- /** Plugin 描述 */
73
+ readonly version: string;
87
74
  readonly description?: string;
88
- /** Plugin 源路径 */
89
75
  readonly source: string;
90
- /** Plugin root 目录 */
91
- readonly rootDir?: string;
92
- /** Plugin 配置 */
76
+ readonly rootDir: string;
93
77
  readonly pluginConfig: Record<string, unknown>;
94
- /** Plugin Logger */
95
78
  readonly logger: PluginLogger;
96
- /** 已注册的 providers */
97
- readonly _providers: ProviderRegistration[];
98
- /** 已注册的 channels */
99
- readonly _channels: ChannelRegistration[];
100
- /** 已注册的 tools */
101
- readonly _tools: Array<{
102
- definition: ToolDefinition;
103
- handler: HookHandler;
104
- optional: boolean;
105
- }>;
106
- /** 已注册的 context engines */
107
- readonly _contextEngines: Array<{
108
- id: string;
109
- engine: ContextEngine;
110
- }>;
111
- /** 已注册的 hooks */
112
- readonly _hooks: Map<string, OrderedHookEntry[]>;
113
- /** 已注册的 commands */
114
- readonly _commands: Array<{
115
- name: string;
116
- handler: HookHandler;
117
- description?: string;
118
- }>;
119
- /** 已注册的服务 */
120
- readonly _services: Array<{
121
- id: string;
122
- start: () => Promise<void>;
123
- stop: () => Promise<void>;
124
- }>;
125
79
  constructor(opts: {
126
80
  id: string;
127
81
  name: string;
128
- version?: string;
82
+ version: string;
129
83
  description?: string;
130
84
  source: string;
131
- rootDir?: string;
132
- pluginConfig?: Record<string, unknown>;
85
+ rootDir: string;
86
+ pluginConfig: Record<string, unknown>;
133
87
  });
134
88
  /**
135
- * 注册 LLM Provider
89
+ * Stage a Tool contribution. It is not mounted or exposed by this call.
136
90
  *
137
- * @param registration - Provider 注册定义
138
- */
139
- registerProvider(registration: ProviderRegistration): void;
140
- /**
141
- * 注册 Channel Adapter
142
- *
143
- * @param registration - Channel 注册定义
144
- */
145
- registerChannel(registration: ChannelRegistration): void;
146
- /**
147
- * 注册 Agent Tool
148
- *
149
- * Tool 名称不能与核心 tool 冲突。
150
- *
151
- * @param tool - Tool 定义(包含 name、description、parameters)
152
- * @param handler - Tool 处理函数
153
- * @param opts - 注册选项
91
+ * @param tool - Core ToolDefinition
92
+ * @param handler - Core ToolHandler
93
+ * @param opts - Execution and optional contribution metadata
154
94
  */
155
95
  registerTool(tool: ToolDefinition, handler: ToolHandler, opts?: ToolRegistrationOptions): void;
156
96
  /**
157
- * 注册 Context Engine
158
- *
159
- * Context Engine 是 exclusive slot —— 同一时刻只有一个 active。
160
- *
161
- * @param id - Engine ID
162
- * @param engine - Context Engine 实例
163
- */
164
- registerContextEngine(id: string, engine: ContextEngine): void;
165
- /**
166
- * 注册 Hook
167
- *
168
- * Hook handler 按 priority 降序执行,同 priority 按注册顺序。
169
- *
170
- * @param hookName - Hook 名称
171
- * @param handler - Hook handler
172
- * @param opts - 选项(priority、timeoutMs)
173
- */
174
- on<TEvent = unknown, TResult = void>(hookName: string, handler: (event: TEvent) => Promise<TResult | undefined | void>, opts?: HookRegistrationOptions): void;
175
- /**
176
- * 注册 Command
177
- *
178
- * Command 绕过 LLM,直接执行。
97
+ * Stage a typed hook contribution using one of the 22 existing event names.
179
98
  *
180
- * @param def - Command 定义
181
- */
182
- registerCommand(def: {
183
- name: string;
184
- handler: HookHandler;
185
- description?: string;
186
- }): void;
187
- /**
188
- * 注册后台服务
189
- *
190
- * 服务在 Gateway 启动时 start,关闭时 stop。
191
- *
192
- * @param service - 服务定义
193
- */
194
- registerService(service: {
195
- id: string;
196
- start: () => Promise<void>;
197
- stop: () => Promise<void>;
198
- }): void;
199
- /** 已注册的 web search providers */
200
- readonly _webSearchProviders: Array<{
201
- id: string;
202
- provider: WebSearchProvider;
203
- }>;
204
- /** 已注册的 media understanding providers */
205
- readonly _mediaUnderstandingProviders: Array<{
206
- id: string;
207
- provider: unknown;
208
- }>;
209
- /** 已注册的 image generation providers */
210
- readonly _imageGenerationProviders: Array<{
211
- id: string;
212
- provider: unknown;
213
- }>;
214
- /** 已注册的 music generation providers */
215
- readonly _musicGenerationProviders: Array<{
216
- id: string;
217
- provider: unknown;
218
- }>;
219
- /** 已注册的 video generation providers */
220
- readonly _videoGenerationProviders: Array<{
221
- id: string;
222
- provider: unknown;
223
- }>;
224
- /** 已注册的 speech providers */
225
- readonly _speechProviders: Array<{
226
- id: string;
227
- provider: unknown;
228
- }>;
229
- /** 已注册的 model catalog providers */
230
- readonly _modelCatalogProviders: Array<{
231
- provider: string;
232
- kinds: string[];
233
- liveCatalog: unknown;
234
- }>;
235
- /** 已注册的 memory embedding providers */
236
- readonly _memoryEmbeddingProviders: Array<{
237
- id: string;
238
- provider: unknown;
239
- }>;
240
- /**
241
- * 注册 Web Search Provider
99
+ * @param hookName - Existing hook name
100
+ * @param handler - Event-specific handler
101
+ * @param opts - Ordering and cooperative timeout options
102
+ */
103
+ on<K extends PluginHookName>(hookName: K, handler: HookHandler<K>, opts?: HookRegistrationOptions): void;
104
+ /** Register a parameter Transform or admission Vote for before_tool_call. */
105
+ onBeforeToolCall<P extends 'transform' | 'vote'>(phase: P, handler: (event: HookEvent<'before_tool_call'>) => HookResultFor<'before_tool_call', P> | Promise<HookResultFor<'before_tool_call', P>>, opts?: Omit<DualPhaseHookOptions, 'phase'>): void;
106
+ /** Register a controlled Iteration Transform or admission Vote. */
107
+ onBeforeIteration<P extends 'transform' | 'vote'>(phase: P, handler: (event: HookEvent<'before_iteration'>) => HookResultFor<'before_iteration', P> | Promise<HookResultFor<'before_iteration', P>>, opts?: Omit<DualPhaseHookOptions, 'phase'>): void;
108
+ /** Stage a Host-owned background service; start/stop is driven by Gateway. */
109
+ registerService(registration: HookServiceRegistration): void;
110
+ /**
111
+ * Stage a Command contribution. Host authorization is enforced when mounted.
242
112
  *
243
- * @param provider - 实现 WebSearchProvider 契约的实例
244
- */
245
- registerWebSearchProvider(provider: WebSearchProvider): void;
246
- /**
247
- * 注册 Media Understanding Provider
248
- */
249
- registerMediaUnderstandingProvider(provider: unknown): void;
250
- /**
251
- * 注册 Image Generation Provider
252
- */
253
- registerImageGenerationProvider(provider: unknown): void;
254
- /**
255
- * 注册 Music Generation Provider
256
- */
257
- registerMusicGenerationProvider(provider: unknown): void;
258
- /**
259
- * 注册 Video Generation Provider
260
- */
261
- registerVideoGenerationProvider(provider: unknown): void;
262
- /**
263
- * 注册 Speech Provider
264
- */
265
- registerSpeechProvider(provider: unknown): void;
266
- /**
267
- * 注册 Model Catalog Provider
268
- */
269
- registerModelCatalogProvider(catalog: {
270
- provider: string;
271
- kinds: string[];
272
- liveCatalog: unknown;
273
- }): void;
274
- /**
275
- * 注册 Memory Embedding Provider
276
- */
277
- registerMemoryEmbeddingProvider(provider: unknown): void;
278
- /**
279
- * 从 provider 对象提取 id(兼容多种命名)
113
+ * @param definition - Command metadata and handler
280
114
  */
281
- private getProviderId;
115
+ registerCommand(definition: PluginCommandRegistration): void;
282
116
  /**
283
- * 解析相对于 plugin root 的路径
117
+ * Resolve a path relative to the plugin root in ESM.
284
118
  *
285
- * @param input - 相对路径
286
- * @returns 绝对路径
119
+ * @param input - Relative or absolute path
120
+ * @returns Absolute path; not a filesystem security boundary
287
121
  */
288
122
  resolvePath(input: string): string;
289
123
  }