@octopi-agent/engine 0.98.4 → 0.121.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 (493) hide show
  1. package/dist/builtin-model-info.js +28 -7
  2. package/dist/config-admin/agent-presets.d.ts +32 -0
  3. package/dist/config-admin/agent-presets.js +133 -0
  4. package/dist/config-admin/discover.d.ts +33 -4
  5. package/dist/config-admin/discover.js +101 -6
  6. package/dist/config-admin/env.d.ts +11 -0
  7. package/dist/config-admin/env.js +41 -0
  8. package/dist/config-admin/error-copy.d.ts +106 -0
  9. package/dist/config-admin/error-copy.js +287 -0
  10. package/dist/config-admin/i18n.d.ts +21 -0
  11. package/dist/config-admin/i18n.js +19 -0
  12. package/dist/config-admin/index.d.ts +6 -2
  13. package/dist/config-admin/index.js +3 -1
  14. package/dist/config-admin/model-presets.d.ts +14 -0
  15. package/dist/config-admin/model-presets.js +595 -70
  16. package/dist/config-admin/onboarding-apply.d.ts +71 -0
  17. package/dist/config-admin/onboarding-apply.js +235 -0
  18. package/dist/config-admin/onboarding.d.ts +154 -0
  19. package/dist/config-admin/onboarding.js +270 -0
  20. package/dist/config-admin/redact.d.ts +42 -9
  21. package/dist/config-admin/redact.js +69 -5
  22. package/dist/config-schema/agent.d.ts +40 -6
  23. package/dist/config-schema/agent.js +44 -6
  24. package/dist/config-schema/browser.d.ts +62 -0
  25. package/dist/config-schema/browser.js +89 -0
  26. package/dist/config-schema/context.d.ts +12 -37
  27. package/dist/config-schema/context.js +10 -31
  28. package/dist/config-schema/engine.d.ts +140 -164
  29. package/dist/config-schema/engine.js +10 -7
  30. package/dist/config-schema/governance.d.ts +20 -2
  31. package/dist/config-schema/governance.js +18 -3
  32. package/dist/config-schema/models.d.ts +10 -12
  33. package/dist/config-schema/models.js +16 -3
  34. package/dist/config-schema/run.d.ts +6 -2
  35. package/dist/config-schema/run.js +12 -2
  36. package/dist/config-schema/shared.d.ts +1 -3
  37. package/dist/config-schema/shared.js +4 -4
  38. package/dist/config-schema/substrate.d.ts +19 -88
  39. package/dist/config-schema/substrate.js +30 -107
  40. package/dist/config.d.ts +161 -123
  41. package/dist/config.js +109 -7
  42. package/dist/file-mode.d.ts +67 -0
  43. package/dist/file-mode.js +182 -0
  44. package/dist/fork-child.d.ts +82 -0
  45. package/dist/fork-child.js +123 -0
  46. package/dist/harness/activation/delegated-run.d.ts +42 -0
  47. package/dist/harness/activation/delegated-run.js +71 -0
  48. package/dist/harness/activation/dispatcher.js +11 -0
  49. package/dist/harness/activation/inbox.d.ts +3 -3
  50. package/dist/harness/activation/inbox.js +3 -3
  51. package/dist/harness/activation/index.d.ts +1 -0
  52. package/dist/harness/activation/run-backend.d.ts +92 -0
  53. package/dist/harness/activation/run-backend.js +16 -0
  54. package/dist/harness/activation/run-protocol.d.ts +392 -0
  55. package/dist/harness/activation/run-protocol.js +19 -0
  56. package/dist/harness/activation/runtime.d.ts +33 -0
  57. package/dist/harness/activation/runtime.js +130 -31
  58. package/dist/harness/activation/types.d.ts +20 -3
  59. package/dist/harness/agent/builder.d.ts +36 -3
  60. package/dist/harness/agent/builder.js +206 -46
  61. package/dist/harness/agent/config-bridge.d.ts +10 -1
  62. package/dist/harness/agent/config-bridge.js +24 -5
  63. package/dist/harness/agent/config-integrity.js +19 -2
  64. package/dist/harness/agent/registered-tool-adapter.d.ts +27 -0
  65. package/dist/harness/agent/registered-tool-adapter.js +67 -0
  66. package/dist/harness/agent/wire-agent-builder.d.ts +13 -3
  67. package/dist/harness/agent/wire-agent-builder.js +35 -9
  68. package/dist/harness/capabilities/document/backends/plain.js +2 -1
  69. package/dist/harness/capabilities/document/factory.d.ts +5 -0
  70. package/dist/harness/capabilities/document/factory.js +1 -0
  71. package/dist/harness/capabilities/document/legacy/factory.js +3 -2
  72. package/dist/harness/capabilities/document/port.js +6 -3
  73. package/dist/harness/capabilities/document/types.d.ts +5 -0
  74. package/dist/harness/collaboration/autonomous-subsystem/audit/reader.d.ts +17 -0
  75. package/dist/harness/collaboration/autonomous-subsystem/audit/reader.js +66 -36
  76. package/dist/harness/collaboration/autonomous-subsystem/audit/writer.d.ts +6 -2
  77. package/dist/harness/collaboration/autonomous-subsystem/audit/writer.js +27 -7
  78. package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.js +13 -0
  79. package/dist/harness/collaboration/autonomous-subsystem/loader.js +2 -1
  80. package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +11 -0
  81. package/dist/harness/collaboration/autonomous-subsystem/runtime.js +17 -0
  82. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.d.ts +14 -4
  83. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.js +50 -41
  84. package/dist/harness/collaboration/autonomous-subsystem/sense/input-builder.js +4 -4
  85. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.d.ts +2 -2
  86. package/dist/harness/collaboration/autonomous-subsystem/sense/metrics.js +2 -2
  87. package/dist/harness/collaboration/autonomous-subsystem/signal/bus.d.ts +6 -0
  88. package/dist/harness/collaboration/autonomous-subsystem/signal/bus.js +25 -4
  89. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +4 -1
  90. package/dist/harness/collaboration/autonomous-subsystem/types.d.ts +7 -3
  91. package/dist/harness/collaboration/delegation/child-run.d.ts +10 -1
  92. package/dist/harness/collaboration/delegation/child-run.js +38 -6
  93. package/dist/harness/collaboration/delegation/index.d.ts +1 -1
  94. package/dist/harness/collaboration/delegation/index.js +1 -1
  95. package/dist/harness/collaboration/delegation/notifier.d.ts +6 -1
  96. package/dist/harness/collaboration/delegation/notifier.js +8 -1
  97. package/dist/harness/collaboration/delegation/registry-types.d.ts +2 -0
  98. package/dist/harness/collaboration/delegation/service.d.ts +11 -4
  99. package/dist/harness/collaboration/delegation/service.js +35 -13
  100. package/dist/harness/collaboration/delegation/store.d.ts +4 -0
  101. package/dist/harness/collaboration/delegation/store.js +3 -1
  102. package/dist/harness/collaboration/delegation/types.d.ts +34 -2
  103. package/dist/harness/collaboration/delegation/types.js +22 -0
  104. package/dist/harness/collaboration/delegation/wiring.d.ts +2 -0
  105. package/dist/harness/collaboration/delegation/wiring.js +12 -1
  106. package/dist/harness/context/budget-allocator.d.ts +26 -18
  107. package/dist/harness/context/budget-allocator.js +67 -32
  108. package/dist/harness/context/capabilities/compact/engine.d.ts +44 -11
  109. package/dist/harness/context/capabilities/compact/engine.js +296 -160
  110. package/dist/harness/context/capabilities/compact/handover.d.ts +5 -3
  111. package/dist/harness/context/capabilities/compact/handover.js +7 -5
  112. package/dist/harness/context/capabilities/compact/index.d.ts +7 -2
  113. package/dist/harness/context/capabilities/compact/index.js +5 -1
  114. package/dist/harness/context/capabilities/compact/mechanical.d.ts +130 -0
  115. package/dist/harness/context/capabilities/compact/mechanical.js +268 -0
  116. package/dist/harness/context/capabilities/compact/messages.d.ts +60 -0
  117. package/dist/harness/context/capabilities/compact/messages.js +91 -0
  118. package/dist/harness/context/capabilities/compact/types.d.ts +134 -19
  119. package/dist/harness/context/capabilities/compact/types.js +11 -1
  120. package/dist/harness/context/capabilities/compact/view-split.d.ts +36 -0
  121. package/dist/harness/context/capabilities/compact/view-split.js +72 -0
  122. package/dist/harness/context/capabilities/summary/gate.d.ts +19 -2
  123. package/dist/harness/context/capabilities/summary/gate.js +53 -6
  124. package/dist/harness/context/capabilities/summary/port.js +0 -1
  125. package/dist/harness/context/capabilities/summary/registry.js +20 -0
  126. package/dist/harness/context/capabilities/summary/resolver.d.ts +1 -1
  127. package/dist/harness/context/capabilities/summary/resolver.js +1 -6
  128. package/dist/harness/context/capabilities/summary/tool-binding.d.ts +1 -1
  129. package/dist/harness/context/capabilities/summary/tool-binding.js +16 -12
  130. package/dist/harness/context/capabilities/summary/tool-bindings.d.ts +13 -0
  131. package/dist/harness/context/capabilities/summary/tool-bindings.js +22 -0
  132. package/dist/harness/context/capabilities/summary/types.d.ts +19 -6
  133. package/dist/harness/context/constitution/default-agents.md +85 -0
  134. package/dist/harness/context/context-size-ledger.d.ts +143 -0
  135. package/dist/harness/context/context-size-ledger.js +243 -0
  136. package/dist/harness/context/default-context-engine.d.ts +290 -120
  137. package/dist/harness/context/default-context-engine.js +1555 -764
  138. package/dist/harness/context/index.d.ts +3 -2
  139. package/dist/harness/context/index.js +2 -1
  140. package/dist/harness/context/layer-health.d.ts +4 -0
  141. package/dist/harness/context/layer-health.js +4 -0
  142. package/dist/harness/context/layer-types.d.ts +72 -0
  143. package/dist/harness/context/layer-types.js +87 -2
  144. package/dist/harness/context/layers.d.ts +17 -15
  145. package/dist/harness/context/layers.js +54 -17
  146. package/dist/harness/context/message-selector.d.ts +10 -8
  147. package/dist/harness/context/message-selector.js +49 -27
  148. package/dist/harness/context/prefix-fingerprint.d.ts +46 -0
  149. package/dist/harness/context/prefix-fingerprint.js +52 -0
  150. package/dist/harness/context/summarize.d.ts +2 -2
  151. package/dist/harness/context/summarize.js +27 -2
  152. package/dist/harness/context/system-prompt-assembler.d.ts +4 -0
  153. package/dist/harness/context/system-prompt-assembler.js +7 -3
  154. package/dist/harness/context/token-constants.d.ts +8 -6
  155. package/dist/harness/context/token-constants.js +8 -7
  156. package/dist/harness/context/token-estimate-fns.d.ts +37 -27
  157. package/dist/harness/context/token-estimate-fns.js +85 -66
  158. package/dist/harness/context/token-estimator.d.ts +27 -12
  159. package/dist/harness/context/token-estimator.js +120 -66
  160. package/dist/harness/context/token-segments.d.ts +88 -0
  161. package/dist/harness/context/token-segments.js +103 -0
  162. package/dist/harness/context/tool-result-aging.d.ts +109 -16
  163. package/dist/harness/context/tool-result-aging.js +220 -55
  164. package/dist/harness/context/tool-result-body.js +2 -0
  165. package/dist/harness/context/transform/anchors.d.ts +66 -0
  166. package/dist/harness/context/transform/anchors.js +125 -0
  167. package/dist/harness/context/transform/fold.d.ts +56 -0
  168. package/dist/harness/context/transform/fold.js +135 -0
  169. package/dist/harness/context/transform/migrate.d.ts +41 -0
  170. package/dist/harness/context/transform/migrate.js +69 -0
  171. package/dist/harness/context/transform/types.d.ts +129 -0
  172. package/dist/harness/context/transform/types.js +19 -0
  173. package/dist/harness/context/turn-envelope.d.ts +6 -3
  174. package/dist/harness/context/types.d.ts +196 -119
  175. package/dist/harness/context/types.js +25 -1
  176. package/dist/harness/extension/execution-environment/effect-policy.d.ts +4 -3
  177. package/dist/harness/extension/execution-environment/effect-policy.js +2 -2
  178. package/dist/harness/extension/execution-environment/ops-audit.d.ts +1 -1
  179. package/dist/harness/extension/execution-environment/privileged-exec.js +4 -1
  180. package/dist/harness/extension/execution-environment/resource-limits.d.ts +1 -1
  181. package/dist/harness/extension/execution-environment/resource-limits.js +1 -1
  182. package/dist/harness/extension/execution-environment/workspace.js +1 -1
  183. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +28 -2
  184. package/dist/harness/extension/plugin-ecosystem/channel-types.js +11 -2
  185. package/dist/harness/extension/plugin-ecosystem/client-tools/registry.d.ts +12 -0
  186. package/dist/harness/extension/plugin-ecosystem/client-tools/registry.js +25 -0
  187. package/dist/harness/extension/plugin-ecosystem/commands/builtin.js +28 -1
  188. package/dist/harness/extension/plugin-ecosystem/commands/index.d.ts +3 -1
  189. package/dist/harness/extension/plugin-ecosystem/commands/index.js +1 -0
  190. package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.d.ts +12 -1
  191. package/dist/harness/extension/plugin-ecosystem/commands/plugin-bridge.js +14 -4
  192. package/dist/harness/extension/plugin-ecosystem/commands/router.d.ts +5 -4
  193. package/dist/harness/extension/plugin-ecosystem/commands/router.js +23 -14
  194. package/dist/harness/extension/plugin-ecosystem/commands/types.d.ts +8 -1
  195. package/dist/harness/extension/plugin-ecosystem/commands/types.js +2 -1
  196. package/dist/harness/extension/plugin-ecosystem/hooks/adapter.d.ts +54 -0
  197. package/dist/harness/extension/plugin-ecosystem/hooks/adapter.js +397 -0
  198. package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.d.ts +16 -0
  199. package/dist/harness/extension/plugin-ecosystem/hooks/compaction-integration.js +66 -0
  200. package/dist/harness/extension/plugin-ecosystem/hooks/index.d.ts +4 -0
  201. package/dist/harness/extension/plugin-ecosystem/hooks/index.js +2 -0
  202. package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.d.ts +11 -0
  203. package/dist/harness/extension/plugin-ecosystem/hooks/iteration-snapshot.js +54 -0
  204. package/dist/harness/extension/plugin-ecosystem/hooks/journal.d.ts +9 -0
  205. package/dist/harness/extension/plugin-ecosystem/hooks/journal.js +22 -0
  206. package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.d.ts +12 -0
  207. package/dist/harness/extension/plugin-ecosystem/hooks/policy-error.js +19 -0
  208. package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.d.ts +36 -0
  209. package/dist/harness/extension/plugin-ecosystem/hooks/run-integration.js +338 -0
  210. package/dist/harness/extension/plugin-ecosystem/hooks/services.d.ts +24 -0
  211. package/dist/harness/extension/plugin-ecosystem/hooks/services.js +139 -0
  212. package/dist/harness/extension/plugin-ecosystem/hooks/types.d.ts +229 -0
  213. package/dist/harness/extension/plugin-ecosystem/hooks/types.js +1 -0
  214. package/dist/harness/extension/plugin-ecosystem/index.d.ts +1 -0
  215. package/dist/harness/extension/plugin-ecosystem/index.js +1 -0
  216. package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +223 -222
  217. package/dist/harness/extension/plugin-ecosystem/plugins/api.js +218 -203
  218. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-instances.d.ts +95 -0
  219. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-instances.js +170 -0
  220. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-kinds.d.ts +178 -0
  221. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-kinds.js +314 -0
  222. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.d.ts +78 -0
  223. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.js +80 -0
  224. package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.d.ts +4 -0
  225. package/dist/harness/extension/plugin-ecosystem/plugins/engine-compatibility.js +18 -0
  226. package/dist/harness/extension/plugin-ecosystem/plugins/entry.d.ts +7 -85
  227. package/dist/harness/extension/plugin-ecosystem/plugins/entry.js +8 -50
  228. package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +6 -23
  229. package/dist/harness/extension/plugin-ecosystem/plugins/index.js +3 -23
  230. package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +57 -114
  231. package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +279 -282
  232. package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +46 -484
  233. package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +123 -345
  234. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +50 -223
  235. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +144 -20
  236. package/dist/harness/extension/plugin-ecosystem/plugins/staging.d.ts +17 -0
  237. package/dist/harness/extension/plugin-ecosystem/plugins/staging.js +15 -0
  238. package/dist/harness/extension/plugin-ecosystem/skills/manager.d.ts +6 -1
  239. package/dist/harness/extension/plugin-ecosystem/skills/manager.js +17 -1
  240. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.d.ts +3 -0
  241. package/dist/harness/extension/plugin-ecosystem/tools/ask-user.js +46 -21
  242. package/dist/harness/extension/plugin-ecosystem/tools/browser-types.d.ts +333 -0
  243. package/dist/harness/extension/plugin-ecosystem/tools/browser-types.js +16 -0
  244. package/dist/harness/extension/plugin-ecosystem/tools/browser.d.ts +64 -0
  245. package/dist/harness/extension/plugin-ecosystem/tools/browser.js +692 -0
  246. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +0 -37
  247. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +108 -4
  248. package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +36 -8
  249. package/dist/harness/extension/plugin-ecosystem/tools/file-edit.js +34 -0
  250. package/dist/harness/extension/plugin-ecosystem/tools/file-search.d.ts +0 -6
  251. package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +57 -4
  252. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +81 -13
  253. package/dist/harness/extension/plugin-ecosystem/tools/http.js +5 -0
  254. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.js +13 -7
  255. package/dist/harness/extension/plugin-ecosystem/tools/package-tools.js +126 -14
  256. package/dist/harness/extension/plugin-ecosystem/tools/platform.d.ts +1 -1
  257. package/dist/harness/extension/plugin-ecosystem/tools/platform.js +44 -5
  258. package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.d.ts +11 -0
  259. package/dist/harness/extension/plugin-ecosystem/tools/plugin-tool.js +39 -0
  260. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.d.ts +1 -1
  261. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +19 -24
  262. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.d.ts +7 -0
  263. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.js +4 -0
  264. package/dist/harness/governance/accounting/usage-ledger.d.ts +13 -1
  265. package/dist/harness/governance/accounting/usage-ledger.js +23 -1
  266. package/dist/harness/governance/credentials/db.d.ts +9 -0
  267. package/dist/harness/governance/credentials/db.js +122 -31
  268. package/dist/harness/governance/credentials/store.d.ts +68 -7
  269. package/dist/harness/governance/credentials/store.js +177 -64
  270. package/dist/harness/governance/credentials/types.d.ts +13 -2
  271. package/dist/harness/governance/human-in-the-loop/decision-cache.d.ts +3 -3
  272. package/dist/harness/governance/human-in-the-loop/decision-cache.js +2 -2
  273. package/dist/harness/governance/index.d.ts +1 -0
  274. package/dist/harness/governance/index.js +1 -0
  275. package/dist/harness/governance/registry/db.d.ts +32 -0
  276. package/dist/harness/governance/registry/db.js +142 -0
  277. package/dist/harness/governance/registry/index.d.ts +9 -0
  278. package/dist/harness/governance/registry/index.js +9 -0
  279. package/dist/harness/governance/registry/service.d.ts +381 -0
  280. package/dist/harness/governance/registry/service.js +825 -0
  281. package/dist/harness/governance/registry/types.d.ts +77 -0
  282. package/dist/harness/governance/registry/types.js +7 -0
  283. package/dist/harness/governance/security/capability-enforcer.js +1 -2
  284. package/dist/harness/governance/security/default-security-guard.d.ts +3 -0
  285. package/dist/harness/governance/security/default-security-guard.js +12 -1
  286. package/dist/harness/governance/security/risk-evaluator.d.ts +13 -3
  287. package/dist/harness/governance/security/risk-evaluator.js +307 -21
  288. package/dist/harness/governance/security/shell-parser-treesitter.js +12 -4
  289. package/dist/harness/governance/session-acl/tool-rights.d.ts +1 -0
  290. package/dist/harness/index.d.ts +17 -15
  291. package/dist/harness/index.js +9 -9
  292. package/dist/harness/knowledge/boot-config.d.ts +57 -0
  293. package/dist/harness/knowledge/boot-config.js +52 -0
  294. package/dist/harness/knowledge/catalog-types.d.ts +2 -0
  295. package/dist/harness/knowledge/client.d.ts +77 -9
  296. package/dist/harness/knowledge/client.js +95 -24
  297. package/dist/harness/knowledge/db.d.ts +16 -0
  298. package/dist/harness/knowledge/db.js +112 -41
  299. package/dist/harness/knowledge/describe-sample.d.ts +23 -0
  300. package/dist/harness/knowledge/describe-sample.js +58 -0
  301. package/dist/harness/knowledge/describe.d.ts +8 -0
  302. package/dist/harness/knowledge/describe.js +18 -2
  303. package/dist/harness/knowledge/engine-thread.js +11 -7
  304. package/dist/harness/knowledge/grounding.js +7 -2
  305. package/dist/harness/knowledge/http-app.d.ts +15 -0
  306. package/dist/harness/knowledge/http-app.js +117 -25
  307. package/dist/harness/knowledge/http-bridge.d.ts +15 -0
  308. package/dist/harness/knowledge/http-bridge.js +19 -0
  309. package/dist/harness/knowledge/http-params.d.ts +18 -0
  310. package/dist/harness/knowledge/http-params.js +24 -0
  311. package/dist/harness/knowledge/index.d.ts +2 -0
  312. package/dist/harness/knowledge/index.js +1 -0
  313. package/dist/harness/knowledge/knowledge-serve-child.js +5 -3
  314. package/dist/harness/knowledge/purge.js +5 -2
  315. package/dist/harness/knowledge/query-service.d.ts +25 -4
  316. package/dist/harness/knowledge/query-service.js +79 -43
  317. package/dist/harness/knowledge/query-worker-client.d.ts +14 -2
  318. package/dist/harness/knowledge/query-worker-client.js +8 -3
  319. package/dist/harness/knowledge/query-worker.js +9 -5
  320. package/dist/harness/knowledge/read-http.d.ts +2 -0
  321. package/dist/harness/knowledge/read-http.js +14 -3
  322. package/dist/harness/knowledge/retriever.d.ts +1 -1
  323. package/dist/harness/knowledge/retriever.js +1 -2
  324. package/dist/harness/knowledge/serve.d.ts +14 -8
  325. package/dist/harness/knowledge/serve.js +14 -6
  326. package/dist/harness/knowledge/source-store.d.ts +101 -5
  327. package/dist/harness/knowledge/source-store.js +323 -74
  328. package/dist/harness/knowledge/start-service-process.d.ts +41 -14
  329. package/dist/harness/knowledge/start-service-process.js +67 -96
  330. package/dist/harness/knowledge/tenant-gate.d.ts +81 -0
  331. package/dist/harness/knowledge/tenant-gate.js +167 -0
  332. package/dist/harness/knowledge/types.d.ts +7 -0
  333. package/dist/harness/knowledge/writer-service.d.ts +55 -11
  334. package/dist/harness/knowledge/writer-service.js +200 -30
  335. package/dist/harness/knowledge/writer-worker-client.d.ts +19 -11
  336. package/dist/harness/knowledge/writer-worker-client.js +40 -5
  337. package/dist/harness/knowledge/writer-worker.js +20 -5
  338. package/dist/harness/memory/backfill-trigger.d.ts +10 -3
  339. package/dist/harness/memory/backfill-trigger.js +19 -19
  340. package/dist/harness/memory/cognition-seeds.d.ts +45 -0
  341. package/dist/harness/memory/cognition-seeds.js +67 -0
  342. package/dist/harness/memory/cognition.d.ts +12 -3
  343. package/dist/harness/memory/cognition.js +55 -35
  344. package/dist/harness/memory/conceptualizer.d.ts +11 -1
  345. package/dist/harness/memory/conceptualizer.js +10 -1
  346. package/dist/harness/memory/context-slice.d.ts +42 -0
  347. package/dist/harness/memory/context-slice.js +197 -0
  348. package/dist/harness/memory/health-probe.d.ts +8 -2
  349. package/dist/harness/memory/health-probe.js +10 -13
  350. package/dist/harness/memory/index.d.ts +5 -1
  351. package/dist/harness/memory/index.js +3 -1
  352. package/dist/harness/memory/sqlite/agent-db.d.ts +1 -0
  353. package/dist/harness/memory/sqlite/agent-db.js +9 -8
  354. package/dist/harness/memory/sqlite/cognition-store.d.ts +26 -3
  355. package/dist/harness/memory/sqlite/cognition-store.js +103 -45
  356. package/dist/harness/memory/sqlite/memory-store.js +4 -0
  357. package/dist/harness/memory/sqlite/sqlite-vec.d.ts +24 -1
  358. package/dist/harness/memory/sqlite/sqlite-vec.js +37 -1
  359. package/dist/harness/memory/sqlite/wisdom-store.js +35 -10
  360. package/dist/harness/memory/types.d.ts +24 -6
  361. package/dist/harness/memory/wisdom-formation.d.ts +14 -3
  362. package/dist/harness/memory/wisdom-formation.js +85 -22
  363. package/dist/harness/memory/wisdom-gates.d.ts +14 -0
  364. package/dist/harness/memory/wisdom-gates.js +59 -19
  365. package/dist/harness/memory/wisdom.js +9 -0
  366. package/dist/harness/observability/observer/hub.d.ts +10 -0
  367. package/dist/harness/observability/observer/hub.js +120 -17
  368. package/dist/harness/observability/observer/types.d.ts +10 -6
  369. package/dist/harness/run/agent/agent.d.ts +40 -21
  370. package/dist/harness/run/agent/agent.js +67 -13
  371. package/dist/harness/run/agent/index.d.ts +1 -1
  372. package/dist/harness/run/budget/budget.d.ts +28 -10
  373. package/dist/harness/run/budget/budget.js +38 -15
  374. package/dist/harness/run/concurrency/tool-validator.js +4 -3
  375. package/dist/harness/run/model/index.d.ts +3 -1
  376. package/dist/harness/run/model/index.js +2 -1
  377. package/dist/harness/run/model/resolver.d.ts +4 -1
  378. package/dist/harness/run/model/resolver.js +36 -2
  379. package/dist/harness/run/model/run-scope.d.ts +2 -0
  380. package/dist/harness/run/model/run-scope.js +7 -0
  381. package/dist/harness/run/model/types.d.ts +22 -5
  382. package/dist/harness/run/model/types.js +3 -2
  383. package/dist/harness/run/model/window-truth.d.ts +37 -0
  384. package/dist/harness/run/model/window-truth.js +39 -0
  385. package/dist/harness/run/reliability/context-length-feedback.d.ts +77 -0
  386. package/dist/harness/run/reliability/context-length-feedback.js +128 -0
  387. package/dist/harness/run/reliability/harness-events.d.ts +3 -3
  388. package/dist/harness/run/reliability/model-error-policy.js +4 -0
  389. package/dist/harness/run/reliability/run-agent.d.ts +32 -4
  390. package/dist/harness/run/reliability/run-agent.js +216 -63
  391. package/dist/harness/run/reliability/run-metrics-collector.d.ts +19 -8
  392. package/dist/harness/run/reliability/run-metrics-collector.js +38 -23
  393. package/dist/harness/run/run-guard/default-run-guard.js +8 -8
  394. package/dist/harness/run/run-host.d.ts +302 -0
  395. package/dist/harness/run/run-host.js +978 -0
  396. package/dist/harness/run/run-scope.d.ts +48 -4
  397. package/dist/harness/run/run-scope.js +19 -1
  398. package/dist/harness/run/runner.d.ts +181 -39
  399. package/dist/harness/run/runner.js +654 -119
  400. package/dist/harness/session/attachments/index.d.ts +1 -0
  401. package/dist/harness/session/attachments/index.js +1 -0
  402. package/dist/harness/session/attachments/inject.d.ts +21 -10
  403. package/dist/harness/session/attachments/inject.js +76 -24
  404. package/dist/harness/session/attachments/recall-index.d.ts +70 -0
  405. package/dist/harness/session/attachments/recall-index.js +219 -0
  406. package/dist/harness/session/attachments/service.d.ts +21 -0
  407. package/dist/harness/session/attachments/service.js +258 -139
  408. package/dist/harness/session/attachments/types.d.ts +6 -0
  409. package/dist/harness/session/in-memory-store.js +13 -1
  410. package/dist/harness/session/schedules/service.d.ts +10 -2
  411. package/dist/harness/session/schedules/service.js +13 -2
  412. package/dist/harness/session/tasks/tools.js +12 -0
  413. package/dist/harness/session/transform-store.d.ts +136 -0
  414. package/dist/harness/session/transform-store.js +302 -0
  415. package/dist/harness/session/types.d.ts +11 -15
  416. package/dist/harness/shared/events/agent-event-map.d.ts +75 -13
  417. package/dist/harness/shared/events/agent-event-map.js +3 -2
  418. package/dist/harness/shared/events/scenario-events.d.ts +6 -6
  419. package/dist/harness/shared/types/agent-definition.d.ts +7 -2
  420. package/dist/index.d.ts +16 -18
  421. package/dist/index.js +9 -10
  422. package/dist/integration/agent-runtime/channel-message-source.d.ts +3 -1
  423. package/dist/integration/agent-runtime/channel-message-source.js +4 -3
  424. package/dist/integration/browser/camoufox.d.ts +40 -0
  425. package/dist/integration/browser/camoufox.js +80 -0
  426. package/dist/integration/browser/index.d.ts +91 -0
  427. package/dist/integration/browser/index.js +110 -0
  428. package/dist/integration/browser/install.d.ts +47 -0
  429. package/dist/integration/browser/install.js +214 -0
  430. package/dist/integration/browser/playwright.d.ts +224 -0
  431. package/dist/integration/browser/playwright.js +925 -0
  432. package/dist/integration/browser/service.d.ts +41 -0
  433. package/dist/integration/browser/service.js +181 -0
  434. package/dist/integration/browser/stealth.d.ts +42 -0
  435. package/dist/integration/browser/stealth.js +104 -0
  436. package/dist/integration/observability/metrics.d.ts +6 -6
  437. package/dist/integration/observability/metrics.js +13 -13
  438. package/dist/integration/observability/observer-bridge.js +2 -2
  439. package/dist/integration/observability/trace-collector.d.ts +5 -5
  440. package/dist/integration/observability/trace-collector.js +34 -35
  441. package/dist/integration/observability/trace-events.d.ts +3 -3
  442. package/dist/integration/observability/trace-events.js +3 -3
  443. package/dist/integration/providers/anthropic-message-normalize.d.ts +20 -0
  444. package/dist/integration/providers/anthropic-message-normalize.js +48 -0
  445. package/dist/integration/providers/anthropic.js +41 -3
  446. package/dist/integration/providers/fetch-timeout.d.ts +17 -0
  447. package/dist/integration/providers/fetch-timeout.js +24 -0
  448. package/dist/integration/providers/openai.d.ts +8 -0
  449. package/dist/integration/providers/openai.js +48 -2
  450. package/dist/integration/providers/usage.d.ts +1 -1
  451. package/dist/integration/providers/wire-dump-diff.js +2 -1
  452. package/dist/integration/providers/wire-dump.d.ts +57 -3
  453. package/dist/integration/providers/wire-dump.js +119 -6
  454. package/dist/integration/storage/archive-manager.d.ts +20 -2
  455. package/dist/integration/storage/archive-manager.js +34 -8
  456. package/dist/integration/storage/atomic-tmp.d.ts +12 -0
  457. package/dist/integration/storage/atomic-tmp.js +36 -0
  458. package/dist/integration/storage/jsonl.d.ts +10 -1
  459. package/dist/integration/storage/jsonl.js +155 -54
  460. package/dist/integration/storage/session-index.d.ts +5 -0
  461. package/dist/integration/storage/session-index.js +25 -4
  462. package/dist/integration/tools/assemble.d.ts +50 -0
  463. package/dist/integration/tools/assemble.js +137 -0
  464. package/dist/paths.d.ts +18 -0
  465. package/dist/paths.js +36 -0
  466. package/dist/subsystems/cognition-steward/conceptualize/config.yaml +3 -1
  467. package/dist/subsystems/cognition-steward/conceptualize/handler.js +74 -5
  468. package/dist/subsystems/cognition-steward/consolidate/SUBSYSTEM.md +3 -2
  469. package/dist/subsystems/cognition-steward/consolidate/config.yaml +11 -2
  470. package/dist/subsystems/cognition-steward/consolidate/handler.d.ts +6 -3
  471. package/dist/subsystems/cognition-steward/consolidate/handler.js +266 -28
  472. package/dist/subsystems/memory-steward/backfill/handler.js +3 -2
  473. package/dist/subsystems/memory-steward/govern/config.yaml +6 -1
  474. package/dist/subsystems/wisdom-steward/attribute/config.yaml +5 -1
  475. package/dist/subsystems/wisdom-steward/formation/SUBSYSTEM.md +8 -1
  476. package/dist/subsystems/wisdom-steward/formation/config.yaml +4 -0
  477. package/dist/subsystems/wisdom-steward/formation/handler.js +27 -5
  478. package/dist/subsystems/wisdom-steward/govern/config.yaml +6 -1
  479. package/package.json +14 -15
  480. package/dist/harness/context/hybrid-compressor.d.ts +0 -41
  481. package/dist/harness/context/hybrid-compressor.js +0 -159
  482. package/dist/harness/context/llm-summarizer.d.ts +0 -46
  483. package/dist/harness/context/llm-summarizer.js +0 -249
  484. package/dist/harness/context/smart-router.d.ts +0 -75
  485. package/dist/harness/context/smart-router.js +0 -118
  486. package/dist/harness/context/truncate-compressor.d.ts +0 -28
  487. package/dist/harness/context/truncate-compressor.js +0 -107
  488. package/dist/harness/extension/plugin-ecosystem/plugins/capability.d.ts +0 -97
  489. package/dist/harness/extension/plugin-ecosystem/plugins/capability.js +0 -155
  490. package/dist/harness/extension/plugin-ecosystem/plugins/hooks.d.ts +0 -7
  491. package/dist/harness/extension/plugin-ecosystem/plugins/hooks.js +0 -7
  492. package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.d.ts +0 -86
  493. package/dist/harness/extension/plugin-ecosystem/plugins/lifecycle.js +0 -139
@@ -1,46 +1,75 @@
1
- /**
2
- * Plugin API
3
- *
4
- * 这是 plugin register() 回调中接收的 api 对象。
5
- * Plugin 通过它注册各种能力(provider、channel、tool、hook 等)。
6
- */
7
- /**
8
- * Plugin API
9
- *
10
- * Plugin 在 register() 回调中使用此对象注册能力。
11
- */
1
+ /** Public author API. Runtime ownership lives in PluginContributionRegistry. */
2
+ import { resolve, join } from 'node:path';
3
+ import { mkdir } from 'node:fs/promises';
4
+ import { restrictToOwner } from '../../../../file-mode.js';
5
+ import { getOctopiHome } from '../../../../paths.js';
6
+ import { CredentialStore } from '../../../governance/credentials/store.js';
7
+ import { TOOL_CAPABILITIES } from '@octopi-agent/core/types.js';
8
+ import { CONTRIBUTION_NAME_RE } from './manifest.js';
9
+ import { COMMAND_KIND, CHANNEL_KIND, HOOK_KIND, PROVIDER_KIND, SERVICE_KIND, TOOL_KIND, stageContribution } from './contribution-kinds.js';
10
+ import { createInstanceTable, readInstanceTable } from './contribution-instances.js';
11
+ import { createStaging, readStaging } from './staging.js';
12
+ import { normalizeCommandName } from '../commands/parse.js';
13
+ import { COMMAND_INVOKERS } from '../commands/types.js';
14
+ const SECRET_KEY_RE = /^[A-Za-z0-9._-]+$/;
15
+ /** Vault-backed secrets scoped to one plugin (`plugin:<id>:<key>` namespace). */
16
+ function createPluginSecrets(pluginId, storeOf) {
17
+ const consumer = { kind: 'plugin', id: pluginId };
18
+ const nameOf = (key) => {
19
+ if (typeof key !== 'string' || !SECRET_KEY_RE.test(key)) {
20
+ throw new Error(`Plugin "${pluginId}" invalid secret key "${String(key)}": expected [A-Za-z0-9._-]+`);
21
+ }
22
+ return `plugin:${pluginId}:${key}`;
23
+ };
24
+ return {
25
+ async get(key) {
26
+ const store = await storeOf();
27
+ return store.reveal(nameOf(key), consumer);
28
+ },
29
+ async set(key, value) {
30
+ if (typeof value !== 'string' || value === '') {
31
+ throw new Error(`Plugin "${pluginId}" secret "${key}" value must be a non-empty string`);
32
+ }
33
+ const store = await storeOf();
34
+ const name = nameOf(key);
35
+ store.set({
36
+ name,
37
+ kind: 'api_key',
38
+ description: `plugin:${pluginId} secret`,
39
+ secretMode: 'encrypted',
40
+ secretValue: value,
41
+ scope: { level: 'plugin', key: pluginId },
42
+ });
43
+ // Own-or-revoke: a secret written here belongs to this plugin only —
44
+ // bindings left over from a hand-provisioned row are revoked so the
45
+ // "only resolvable consumer" claim cannot be silently falsified.
46
+ for (const bound of store.listBindings(name)) {
47
+ if (bound.kind !== 'plugin' || bound.id !== pluginId) {
48
+ store.unbind({ kind: bound.kind, id: bound.id }, name);
49
+ }
50
+ }
51
+ store.bind(consumer, name);
52
+ },
53
+ async delete(key) {
54
+ const store = await storeOf();
55
+ return store.delete(nameOf(key));
56
+ },
57
+ };
58
+ }
12
59
  export class PluginApi {
13
- /** Plugin ID */
14
60
  id;
15
- /** Plugin 显示名称 */
16
61
  name;
17
- /** Plugin 版本 */
18
62
  version;
19
- /** Plugin 描述 */
20
63
  description;
21
- /** Plugin 源路径 */
22
64
  source;
23
- /** Plugin root 目录 */
24
65
  rootDir;
25
- /** Plugin 配置 */
26
66
  pluginConfig;
27
- /** Plugin Logger */
28
67
  logger;
29
- // ── 内部存储(PluginManager 读取) ──
30
- /** 已注册的 providers */
31
- _providers = [];
32
- /** 已注册的 channels */
33
- _channels = [];
34
- /** 已注册的 tools */
35
- _tools = [];
36
- /** 已注册的 context engines */
37
- _contextEngines = [];
38
- /** 已注册的 hooks */
39
- _hooks = new Map();
40
- /** 已注册的 commands */
41
- _commands = [];
42
- /** 已注册的服务 */
43
- _services = [];
68
+ /** Per-plugin secret storage backed by the Host credentials vault. */
69
+ secrets;
70
+ stateDirPath;
71
+ credentialStore;
72
+ injectedCredentialStore;
44
73
  constructor(opts) {
45
74
  this.id = opts.id;
46
75
  this.name = opts.name;
@@ -48,218 +77,204 @@ export class PluginApi {
48
77
  this.description = opts.description;
49
78
  this.source = opts.source;
50
79
  this.rootDir = opts.rootDir;
51
- this.pluginConfig = opts.pluginConfig ?? {};
80
+ this.pluginConfig = opts.pluginConfig;
81
+ this.stateDirPath = opts.stateDir ?? join(getOctopiHome(), 'plugin-state', opts.id);
82
+ this.injectedCredentialStore = opts.credentialStore;
83
+ this.secrets = createPluginSecrets(opts.id, () => this.getCredentialStore());
84
+ createStaging(this);
85
+ createInstanceTable(this);
52
86
  const prefix = `[plugin:${opts.id}]`;
53
87
  this.logger = {
54
- debug: (msg, ...args) => console.debug(`${prefix} ${msg}`, ...args),
55
- info: (msg, ...args) => console.info(`${prefix} ${msg}`, ...args),
56
- warn: (msg, ...args) => console.warn(`${prefix} ${msg}`, ...args),
57
- error: (msg, ...args) => console.error(`${prefix} ${msg}`, ...args),
88
+ debug: (message, ...args) => console.debug(`${prefix} ${message}`, ...args),
89
+ info: (message, ...args) => console.info(`${prefix} ${message}`, ...args),
90
+ warn: (message, ...args) => console.warn(`${prefix} ${message}`, ...args),
91
+ error: (message, ...args) => console.error(`${prefix} ${message}`, ...args),
58
92
  };
59
93
  }
60
- // ================================================================
61
- // Capability Registration
62
- // ================================================================
63
94
  /**
64
- * 注册 LLM Provider
65
- *
66
- * @param registration - Provider 注册定义
95
+ * Per-plugin private state directory (`OCTOPI_HOME/plugin-state/<id>`).
96
+ * Created on first access with mode 0700 (and tightened to 0700 when the
97
+ * directory already looser). Runtime state goes here — secrets go through
98
+ * {@link PluginApi.secrets}, never into files.
67
99
  */
68
- registerProvider(registration) {
69
- this._providers.push(registration);
70
- this.logger.info(`Registered provider: ${registration.id}`);
100
+ get stateDir() {
101
+ return this.stateDirPath;
71
102
  }
72
- /**
73
- * 注册 Channel Adapter
74
- *
75
- * @param registration - Channel 注册定义
76
- */
77
- registerChannel(registration) {
78
- this._channels.push(registration);
79
- this.logger.info(`Registered channel: ${registration.id}`);
103
+ /** Ensure the state directory exists with 0700. Called by stateDir consumers. */
104
+ async ensureStateDir() {
105
+ await mkdir(this.stateDirPath, { recursive: true, mode: 0o700 });
106
+ // mkdir's mode is masked by umask and does not tighten existing dirs.
107
+ // On Windows `chmod` neither takes effect nor throws (it only toggles the
108
+ // read-only flag), so the old `chmod` + catch below could never report a
109
+ // downgrade — the warning was dead code. Use the real restriction: POSIX
110
+ // chmod, Windows ACL (`icacls /inheritance:r /grant:r <user>`).
111
+ try {
112
+ restrictToOwner(this.stateDirPath, 'dir');
113
+ }
114
+ catch (error) {
115
+ // Degraded, explicit: a state dir that cannot be tightened is a real
116
+ // security downgrade, never a silent one.
117
+ this.logger.warn(`Plugin "${this.id}" stateDir ${this.stateDirPath}: cannot enforce mode 0700 (${String(error)}); state files rely on their own mode`);
118
+ }
119
+ return this.stateDirPath;
120
+ }
121
+ async getCredentialStore() {
122
+ this.credentialStore ??= this.injectedCredentialStore ?? (await CredentialStore.openDefault(getOctopiHome()));
123
+ return this.credentialStore;
80
124
  }
81
125
  /**
82
- * 注册 Agent Tool
83
- *
84
- * Tool 名称不能与核心 tool 冲突。
126
+ * Stage a Tool contribution. It is not mounted or exposed by this call.
85
127
  *
86
- * @param tool - Tool 定义(包含 name、description、parameters)
87
- * @param handler - Tool 处理函数
88
- * @param opts - 注册选项
128
+ * @param tool - Core ToolDefinition
129
+ * @param handler - Core ToolHandler
130
+ * @param opts - Execution and optional contribution metadata
89
131
  */
90
132
  registerTool(tool, handler, opts) {
91
- this._tools.push({
133
+ if (!tool.capabilities || tool.capabilities.length === 0) {
134
+ throw new Error(`Plugin tool "${tool.name}" must declare non-empty capabilities`);
135
+ }
136
+ if (new Set(tool.capabilities).size !== tool.capabilities.length ||
137
+ tool.capabilities.some((capability) => !TOOL_CAPABILITIES.includes(capability))) {
138
+ throw new Error(`Plugin tool "${tool.name}" has unknown or duplicate capabilities`);
139
+ }
140
+ const executionMode = opts?.executionMode ??
141
+ (tool.capabilities.includes('fs-write') ? 'sequential' : undefined);
142
+ stageContribution(this.id, TOOL_KIND, readStaging(this), {
92
143
  definition: tool,
93
- handler: handler,
144
+ handler,
94
145
  optional: opts?.optional ?? false,
146
+ ...(executionMode === undefined ? {} : { executionMode }),
95
147
  });
96
- this.logger.info(`Registered tool: ${tool.name}${opts?.optional ? ' (optional)' : ''}`);
97
148
  }
98
149
  /**
99
- * 注册 Context Engine
100
- *
101
- * Context Engine 是 exclusive slot —— 同一时刻只有一个 active。
150
+ * Stage a typed hook contribution using one of the 22 existing event names.
102
151
  *
103
- * @param id - Engine ID
104
- * @param engine - Context Engine 实例
105
- */
106
- registerContextEngine(id, engine) {
107
- this._contextEngines.push({ id, engine });
108
- this.logger.info(`Registered context engine: ${id}`);
109
- }
110
- /**
111
- * 注册 Hook
112
- *
113
- * Hook handler 按 priority 降序执行,同 priority 按注册顺序。
114
- *
115
- * @param hookName - Hook 名称
116
- * @param handler - Hook handler
117
- * @param opts - 选项(priority、timeoutMs)
152
+ * @param hookName - Existing hook name
153
+ * @param handler - Event-specific handler
154
+ * @param opts - Ordering and cooperative timeout options
118
155
  */
119
156
  on(hookName, handler, opts) {
120
- if (!this._hooks.has(hookName)) {
121
- this._hooks.set(hookName, []);
157
+ const dualPhase = hookName === 'before_tool_call' || hookName === 'before_iteration';
158
+ if (dualPhase !== (opts?.phase !== undefined)) {
159
+ throw new Error(`Plugin "${this.id}" must ${dualPhase ? 'declare' : 'omit'} phase for hook "${hookName}"`);
160
+ }
161
+ if (opts?.priority !== undefined && !Number.isFinite(opts.priority)) {
162
+ throw new Error(`Plugin "${this.id}" registered invalid hook priority`);
122
163
  }
123
- const entries = this._hooks.get(hookName);
124
- entries.push({
164
+ if (opts?.timeoutMs !== undefined && (!Number.isFinite(opts.timeoutMs) || opts.timeoutMs <= 0)) {
165
+ throw new Error(`Plugin "${this.id}" registered invalid hook timeout`);
166
+ }
167
+ const entry = {
125
168
  pluginId: this.id,
126
169
  hookName,
127
170
  handler: handler,
171
+ phase: opts?.phase ?? 'single',
128
172
  priority: opts?.priority ?? 0,
129
- timeoutMs: opts?.timeoutMs,
130
- });
131
- // 保持按 priority 降序排列
132
- entries.sort((a, b) => b.priority - a.priority);
133
- }
134
- /**
135
- * 注册 Command
136
- *
137
- * Command 绕过 LLM,直接执行。
138
- *
139
- * @param def - Command 定义
140
- */
141
- registerCommand(def) {
142
- this._commands.push(def);
143
- this.logger.info(`Registered command: ${def.name}`);
144
- }
145
- /**
146
- * 注册后台服务
147
- *
148
- * 服务在 Gateway 启动时 start,关闭时 stop。
149
- *
150
- * @param service - 服务定义
151
- */
152
- registerService(service) {
153
- this._services.push(service);
154
- this.logger.info(`Registered service: ${service.id}`);
155
- }
156
- // ================================================================
157
- // Extended Registration
158
- // ================================================================
159
- /** 已注册的 web search providers */
160
- _webSearchProviders = [];
161
- /** 已注册的 media understanding providers */
162
- _mediaUnderstandingProviders = [];
163
- /** 已注册的 image generation providers */
164
- _imageGenerationProviders = [];
165
- /** 已注册的 music generation providers */
166
- _musicGenerationProviders = [];
167
- /** 已注册的 video generation providers */
168
- _videoGenerationProviders = [];
169
- /** 已注册的 speech providers */
170
- _speechProviders = [];
171
- /** 已注册的 model catalog providers */
172
- _modelCatalogProviders = [];
173
- /** 已注册的 memory embedding providers */
174
- _memoryEmbeddingProviders = [];
175
- /**
176
- * 注册 Web Search Provider
177
- *
178
- * @param provider - 实现 WebSearchProvider 契约的实例
179
- */
180
- registerWebSearchProvider(provider) {
181
- const id = provider.id || this.getProviderId(provider);
182
- this._webSearchProviders.push({ id, provider });
183
- this.logger.info(`Registered web search provider: ${id}`);
184
- }
185
- /**
186
- * 注册 Media Understanding Provider
187
- */
188
- registerMediaUnderstandingProvider(provider) {
189
- const id = this.getProviderId(provider);
190
- this._mediaUnderstandingProviders.push({ id, provider });
191
- this.logger.info(`Registered media understanding provider: ${id}`);
173
+ ...(opts?.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
174
+ };
175
+ stageContribution(this.id, HOOK_KIND, readStaging(this), entry);
192
176
  }
193
- /**
194
- * 注册 Image Generation Provider
195
- */
196
- registerImageGenerationProvider(provider) {
197
- const id = this.getProviderId(provider);
198
- this._imageGenerationProviders.push({ id, provider });
199
- this.logger.info(`Registered image generation provider: ${id}`);
177
+ /** Register a parameter Transform or admission Vote for before_tool_call. */
178
+ onBeforeToolCall(phase, handler, opts) {
179
+ this.on('before_tool_call', handler, { ...opts, phase });
200
180
  }
201
- /**
202
- * 注册 Music Generation Provider
203
- */
204
- registerMusicGenerationProvider(provider) {
205
- const id = this.getProviderId(provider);
206
- this._musicGenerationProviders.push({ id, provider });
207
- this.logger.info(`Registered music generation provider: ${id}`);
181
+ /** Register a controlled Iteration Transform or admission Vote. */
182
+ onBeforeIteration(phase, handler, opts) {
183
+ this.on('before_iteration', handler, { ...opts, phase });
208
184
  }
209
- /**
210
- * 注册 Video Generation Provider
211
- */
212
- registerVideoGenerationProvider(provider) {
213
- const id = this.getProviderId(provider);
214
- this._videoGenerationProviders.push({ id, provider });
215
- this.logger.info(`Registered video generation provider: ${id}`);
185
+ /** Stage a Host-owned background service; start/stop is driven by Gateway. */
186
+ registerService(registration) {
187
+ if (!registration.serviceId.trim()) {
188
+ throw new Error(`Plugin "${this.id}" registered an empty service id`);
189
+ }
190
+ if (registration.timeoutMs !== undefined && (!Number.isFinite(registration.timeoutMs) || registration.timeoutMs <= 0)) {
191
+ throw new Error(`Plugin "${this.id}" registered an invalid service timeout`);
192
+ }
193
+ stageContribution(this.id, SERVICE_KIND, readStaging(this), { ...registration });
216
194
  }
217
195
  /**
218
- * 注册 Speech Provider
196
+ * Stage a model Provider factory. The Host instantiates it when a
197
+ * `models.providers` entry references this id via its `plugin` field.
198
+ *
199
+ * @param id - Stable provider id (globally unique across plugins, like services)
200
+ * @param factory - Builds a Core ModelProvider for one config instance
219
201
  */
220
- registerSpeechProvider(provider) {
221
- const id = this.getProviderId(provider);
222
- this._speechProviders.push({ id, provider });
223
- this.logger.info(`Registered speech provider: ${id}`);
202
+ registerProvider(id, factory) {
203
+ const normalized = id.trim();
204
+ if (!CONTRIBUTION_NAME_RE.test(normalized) || typeof factory !== 'function') {
205
+ throw new Error(`Plugin "${this.id}" registered an invalid provider contribution "${id}"`);
206
+ }
207
+ stageContribution(this.id, PROVIDER_KIND, readStaging(this), { id: normalized, factory });
224
208
  }
225
209
  /**
226
- * 注册 Model Catalog Provider
210
+ * Stage a Gateway channel factory. The Host instantiates it when a `channels`
211
+ * entry references this id via its `plugin` field.
212
+ *
213
+ * @param id - Stable channel id (globally unique across plugins, like providers)
214
+ * @param factory - Builds a ChannelAdapter for one channels config instance
227
215
  */
228
- registerModelCatalogProvider(catalog) {
229
- this._modelCatalogProviders.push(catalog);
230
- this.logger.info(`Registered model catalog: ${catalog.provider} (${catalog.kinds.join(', ')})`);
216
+ registerChannel(id, factory) {
217
+ const normalized = id.trim();
218
+ if (!CONTRIBUTION_NAME_RE.test(normalized) || typeof factory !== 'function') {
219
+ throw new Error(`Plugin "${this.id}" registered an invalid channel contribution "${id}"`);
220
+ }
221
+ stageContribution(this.id, CHANNEL_KIND, readStaging(this), { id: normalized, factory });
231
222
  }
232
- /**
233
- * 注册 Memory Embedding Provider
234
- */
235
- registerMemoryEmbeddingProvider(provider) {
236
- const id = this.getProviderId(provider);
237
- this._memoryEmbeddingProviders.push({ id, provider });
238
- this.logger.info(`Registered memory embedding provider: ${id}`);
223
+ getContributionInstance(kind, id) {
224
+ if (kind !== 'provider' && kind !== 'channel') {
225
+ throw new Error(`Plugin "${this.id}" cannot look up instances of kind "${String(kind)}": expected "provider" or "channel"`);
226
+ }
227
+ if (typeof id !== 'string') {
228
+ throw new Error(`Plugin "${this.id}" cannot look up ${kind} instance "${String(id)}": id must be a string`);
229
+ }
230
+ const key = id.trim();
231
+ const staging = readStaging(this);
232
+ const owns = kind === 'provider'
233
+ ? staging.providers.some((entry) => entry.id === key)
234
+ : staging.channels.some((entry) => entry.id === key);
235
+ if (!owns) {
236
+ throw new Error(`Plugin "${this.id}" cannot look up ${kind} "${key}": not a contribution of this plugin`);
237
+ }
238
+ const entries = readInstanceTable(this).find(kind, key);
239
+ const live = entries.filter((entry) => entry.state === 'live');
240
+ if (live.length === 1)
241
+ return live[0].instance;
242
+ if (live.length > 1) {
243
+ const labels = live.map((entry) => `"${entry.label}"`).join(', ');
244
+ throw new Error(`Plugin "${this.id}" ${kind} "${key}" has ${live.length} live instances (${labels}): getContributionInstance requires exactly one`);
245
+ }
246
+ if (entries.length > 0) {
247
+ throw new Error(`Plugin "${this.id}" ${kind} "${key}" has no live instance (its instance was retired)`);
248
+ }
249
+ throw new Error(`Plugin "${this.id}" ${kind} "${key}" has no live instance (the Host has not instantiated it)`);
239
250
  }
240
- // ================================================================
241
- // Utility
242
- // ================================================================
243
251
  /**
244
- * 从 provider 对象提取 id(兼容多种命名)
252
+ * Stage a Command contribution. Host authorization is enforced when mounted.
253
+ *
254
+ * @param definition - Command metadata and handler
245
255
  */
246
- getProviderId(provider) {
247
- if (provider && typeof provider === 'object') {
248
- const p = provider;
249
- return (p.id ?? p.name ?? 'unknown');
256
+ registerCommand(definition) {
257
+ const name = normalizeCommandName(definition.name);
258
+ if (!name)
259
+ throw new Error(`Plugin "${this.id}" registered invalid command name`);
260
+ if (definition.kind !== undefined && definition.kind !== 'control' && definition.kind !== 'prompt') {
261
+ throw new Error(`Plugin "${this.id}" registered unsupported kind for command "${name}"`);
262
+ }
263
+ if (definition.invocableBy && (definition.invocableBy.length === 0 ||
264
+ new Set(definition.invocableBy).size !== definition.invocableBy.length ||
265
+ definition.invocableBy.some((invoker) => !COMMAND_INVOKERS.includes(invoker)))) {
266
+ throw new Error(`Plugin "${this.id}" registered invalid invocableBy for command "${name}"`);
250
267
  }
251
- return 'unknown';
268
+ const staging = readStaging(this);
269
+ stageContribution(this.id, COMMAND_KIND, staging, { ...definition, name });
252
270
  }
253
271
  /**
254
- * 解析相对于 plugin root 的路径
272
+ * Resolve a path relative to the plugin root in ESM.
255
273
  *
256
- * @param input - 相对路径
257
- * @returns 绝对路径
274
+ * @param input - Relative or absolute path
275
+ * @returns Absolute path; not a filesystem security boundary
258
276
  */
259
277
  resolvePath(input) {
260
- if (!this.rootDir)
261
- return input;
262
- const path = require('node:path');
263
- return path.resolve(this.rootDir, input);
278
+ return resolve(this.rootDir, input);
264
279
  }
265
280
  }
@@ -0,0 +1,95 @@
1
+ /**
2
+ * Host-owned contribution instance tracking for factory-backed kinds
3
+ * (providers, channels). Not exported through the author SDK; authors reach it
4
+ * only through `PluginApi.getContributionInstance`.
5
+ *
6
+ * Lifecycle model: an instance is born when the Host **accepts** the factory
7
+ * product (post-validation, i.e. exactly what the Host routes to) and dies by
8
+ * one of two triggers:
9
+ * - physical: the Host calls its lifecycle method (`stop()` for channels,
10
+ * `dispose()` for providers) — recorded when the call is *requested*,
11
+ * regardless of outcome, because the Host will not revive it either way;
12
+ * - logical: a newer instance is accepted for the same contribution key and
13
+ * label (config hot-reload replace). The superseded instance may still serve
14
+ * draining in-flight work; it is simply no longer returned by lookup.
15
+ *
16
+ * Storage follows the staging pattern: one table per PluginApi, created by the
17
+ * host loader, so a plugin can only ever see instances of its own
18
+ * contributions.
19
+ */
20
+ import type { PluginApi } from './api.js';
21
+ /** Contribution kinds whose entries are factories producing runtime instances. */
22
+ export type ContributionInstanceKind = 'provider' | 'channel';
23
+ /** The instance method the Host calls to retire the instance. */
24
+ export type RetirementMethod = 'stop' | 'dispose';
25
+ export interface ContributionInstanceEntry {
26
+ readonly kind: ContributionInstanceKind;
27
+ /** The contribution key (provider/channel id). */
28
+ readonly key: string;
29
+ /** Config identity of this instantiation (provider config key; channel label). */
30
+ label: string;
31
+ readonly instance: object;
32
+ state: 'live' | 'retired';
33
+ /** Entries this acceptance superseded — restored when the acceptance is rolled back. */
34
+ superseded: ContributionInstanceEntry[];
35
+ }
36
+ /** Called only by the host when constructing an author API. */
37
+ export declare function createInstanceTable(api: PluginApi): ContributionInstanceTable;
38
+ /** Read the host-owned instance table of one author API. */
39
+ export declare function readInstanceTable(api: PluginApi): ContributionInstanceTable;
40
+ export declare class ContributionInstanceTable {
41
+ private entries;
42
+ /**
43
+ * Record one Host-accepted instance and wrap its retirement method so the
44
+ * entry retires together with the instance. Wrapping happens here — the
45
+ * single registration path — so every Host teardown call site is covered
46
+ * without explicit retire calls.
47
+ *
48
+ * Acceptance semantics:
49
+ * - a newer instance for the same (kind, key, label) supersedes the previous
50
+ * one (config hot-reload replace); the superseded entry is marked retired;
51
+ * - re-accepting the *same* object (singleton factories) refreshes its label
52
+ * instead of double-registering it;
53
+ * - an instance that cannot be tracked is **not registered**: a non-object
54
+ * product, a frozen/sealed object whose retirement method cannot be
55
+ * wrapped, or (channels) a product without `stop` — in every case the
56
+ * Host's own contract validation is the authority that reports the broken
57
+ * adapter, and this method never invents methods it does not own.
58
+ *
59
+ * @param opts - Instance identity and retirement wiring
60
+ * @returns Whether the instance was registered (tracked)
61
+ */
62
+ attach(opts: {
63
+ kind: ContributionInstanceKind;
64
+ key: string;
65
+ label: string;
66
+ instance: object;
67
+ retireMethod: RetirementMethod;
68
+ defineRetire: boolean;
69
+ }): boolean;
70
+ /**
71
+ * Every recorded entry for one contribution key (live and retired).
72
+ *
73
+ * @param kind - Contribution kind
74
+ * @param key - Contribution key
75
+ * @returns Matching entries in instantiation order
76
+ */
77
+ find(kind: ContributionInstanceKind, key: string): readonly ContributionInstanceEntry[];
78
+ /**
79
+ * Logical retirement by instance identity — called by the Host when it
80
+ * stops routing to an instance (removal, hot-reload replace, config reset).
81
+ * Idempotent; the wrapped lifecycle method remains the physical backstop.
82
+ *
83
+ * @param instance - The instance object the Host stopped routing to
84
+ */
85
+ retireByInstance(instance: object): void;
86
+ /**
87
+ * Roll back an acceptance of an instance that was validated but never
88
+ * installed (the Host aborted before routing to it). Removes its entry and
89
+ * resurrects the entries it superseded, so "live" again matches what the
90
+ * Host serves. No-op once the entry is not the current live one.
91
+ *
92
+ * @param instance - The accepted-but-never-installed instance
93
+ */
94
+ discardByInstance(instance: object): void;
95
+ }