@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,289 +1,290 @@
1
- /**
2
- * Plugin API
3
- *
4
- * 这是 plugin register() 回调中接收的 api 对象。
5
- * Plugin 通过它注册各种能力(provider、channel、tool、hook 等)。
6
- */
1
+ /** Public author API. Runtime ownership lives in PluginContributionRegistry. */
2
+ import { CredentialStore } from '../../../governance/credentials/store.js';
3
+ import { type ToolDefinition, type ToolHandler } from '@octopi-agent/core/types.js';
4
+ import { type PluginHookName, type PluginSessionOpName } from './manifest.js';
5
+ import { type ContributionInstanceKind } from './contribution-instances.js';
6
+ export type { ContributionInstanceKind } from './contribution-instances.js';
7
+ import type { ExtensionHookHandler, HookEvent, HookResult, HookServiceRegistration, HookIterationTransform, HookVote } from '../hooks/types.js';
8
+ import type { ArgSpec, CommandInvoker, CommandKind, CommandResult, CommandRisk } from '../commands/types.js';
7
9
  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';
10
+ export interface PluginCommandContext {
11
+ sessionId: string;
12
+ agentId: string;
13
+ args: string[];
14
+ raw: string;
15
+ principal: {
16
+ actorId?: string;
17
+ actorType?: string;
18
+ tenantId?: string;
19
+ };
20
+ }
12
21
  /**
13
- * Hook 注册选项
22
+ * Per-plugin secret storage backed by the Host credentials vault
23
+ * (`OCTOPI_HOME/credentials/credentials.db`, AES-GCM). Values live in the
24
+ * plugin's own namespace (`plugin:<id>:<key>`) and are bound to the plugin as
25
+ * consumer — no other consumer can resolve them. Plaintext returned by `get`
26
+ * is short-lived: never log or persist it.
14
27
  */
15
- export interface HookRegistrationOptions {
16
- /** 优先级(数字越大越先执行,默认 0) */
17
- priority?: number;
18
- /** 单个 handler 超时毫秒数 */
28
+ export interface PluginSecrets {
29
+ /**
30
+ * Read a secret value in this plugin's namespace.
31
+ *
32
+ * @param key - Secret key (`[A-Za-z0-9._-]+`)
33
+ * @returns Plaintext value, or null when absent
34
+ */
35
+ get(key: string): Promise<string | null>;
36
+ /**
37
+ * Write or rotate a secret in this plugin's namespace.
38
+ *
39
+ * @param key - Secret key (`[A-Za-z0-9._-]+`)
40
+ * @param value - Plaintext value (encrypted at rest, never echoed)
41
+ */
42
+ set(key: string, value: string): Promise<void>;
43
+ /**
44
+ * Delete a secret from this plugin's namespace.
45
+ *
46
+ * @param key - Secret key
47
+ * @returns Whether a stored secret was removed
48
+ */
49
+ delete(key: string): Promise<boolean>;
50
+ }
51
+ export interface PluginCommandRegistration {
52
+ name: string;
53
+ description?: string;
54
+ /** Client-side commands require a client contract and are not Plugin v1 contributions. */
55
+ kind?: Exclude<CommandKind, 'client'>;
56
+ risk?: CommandRisk;
57
+ invocableBy?: CommandInvoker[];
58
+ args?: ArgSpec[];
59
+ preempt?: boolean;
60
+ sessionOps?: PluginSessionOpName[];
61
+ handler: (context: PluginCommandContext) => Promise<CommandResult | string | void | unknown>;
62
+ }
63
+ export type PluginHookMap = {
64
+ [K in PluginHookName]: [HookEvent<K>, HookResult<K>];
65
+ };
66
+ export type HookHandler<K extends PluginHookName = PluginHookName> = ExtensionHookHandler<K>;
67
+ 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;
68
+ export interface OrderedHookEntry {
69
+ pluginId: string;
70
+ hookName: PluginHookName;
71
+ handler: (event: never) => unknown;
72
+ phase: 'single' | 'transform' | 'vote';
73
+ priority: number;
19
74
  timeoutMs?: number;
20
75
  }
21
- /**
22
- * Tool 注册选项
23
- */
76
+ export interface PluginToolContribution {
77
+ definition: ToolDefinition;
78
+ handler: ToolHandler;
79
+ optional: boolean;
80
+ executionMode?: 'parallel' | 'sequential';
81
+ }
24
82
  export interface ToolRegistrationOptions {
25
- /** 是否为可选工具(需要用户显式启用) */
83
+ /** Visibility is separately controlled by the Agent's tools allow/deny policy. */
26
84
  optional?: boolean;
85
+ executionMode?: 'parallel' | 'sequential';
86
+ }
87
+ /** Normalized model entry handed to plugin provider factories (mirrors built-in adapters). */
88
+ export interface PluginProviderModelEntry {
89
+ name: string;
90
+ contextWindow?: number;
91
+ maxOutputTokens?: number;
92
+ temperature?: number;
93
+ reasoning?: boolean;
94
+ input?: Array<'text' | 'image' | 'audio' | 'video'>;
27
95
  }
28
96
  /**
29
- * Provider 注册定义
97
+ * Factory context: everything a plugin needs to build a Core ModelProvider for
98
+ * one `models.providers` config instance.
30
99
  */
31
- export interface ProviderRegistration {
32
- /** Provider ID */
33
- id: string;
34
- /** Provider 实例 */
35
- provider: ModelProvider;
100
+ export interface PluginProviderFactoryContext {
101
+ /** The `models.providers` key being instantiated. */
102
+ providerName: string;
103
+ baseUrl: string;
104
+ /** `${ENV_VAR}` placeholders already expanded; empty string means keyless. */
105
+ apiKey: string;
106
+ models: PluginProviderModelEntry[];
107
+ defaultModel?: string;
108
+ timeoutMs?: number;
109
+ /**
110
+ * `models.providers[key].options` passed through verbatim. Non-secret tuning
111
+ * knobs only — secrets belong in `apiKey` (credential channel), never here.
112
+ */
113
+ options: Record<string, unknown>;
36
114
  }
37
115
  /**
38
- * Channel 注册定义
116
+ * Provider factory staged by registerProvider. The Host calls it when a
117
+ * `models.providers` entry references this contribution via its `plugin` field
118
+ * (startup or config hot-reload), never at registration time.
39
119
  */
40
- export interface ChannelRegistration {
41
- /** Channel ID */
120
+ export type PluginProviderFactory = (context: PluginProviderFactoryContext) => ModelProvider | Promise<ModelProvider>;
121
+ export interface PluginProviderRegistration {
42
122
  id: string;
43
- /** Channel Adapter 实例 */
44
- adapter: ChannelAdapter;
123
+ factory: PluginProviderFactory;
45
124
  }
46
125
  /**
47
- * Hook handler 类型
126
+ * Factory context: everything a plugin needs to build a Gateway ChannelAdapter
127
+ * for one `channels` config instance.
48
128
  */
49
- export type HookHandler<TEvent = unknown, TResult = void> = (event: TEvent) => Promise<TResult | undefined | void>;
129
+ export interface PluginChannelFactoryContext {
130
+ /** The `channels` entry's `plugin` contribution id being instantiated. */
131
+ channelName: string;
132
+ /** `${ENV_VAR}` placeholders already expanded; empty string means keyless. */
133
+ apiKey: string;
134
+ /**
135
+ * `channels[].options` passed through verbatim. Non-secret tuning knobs only —
136
+ * secrets belong in `apiKey` (credential channel), never here.
137
+ */
138
+ options: Record<string, unknown>;
139
+ }
50
140
  /**
51
- * 有序 hook entry
141
+ * Channel factory staged by registerChannel. The Host calls it when a `channels`
142
+ * entry references this contribution via its `plugin` field (startup), never at
143
+ * registration time.
52
144
  */
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
- /** 超时 */
63
- timeoutMs?: number;
64
- }
145
+ export type PluginChannelFactory = (context: PluginChannelFactoryContext) => PluginChannelAdapterLike | Promise<PluginChannelAdapterLike>;
65
146
  /**
66
- * Plugin Logger
147
+ * Structural view of the ChannelAdapter SPI (`../channel-types.js`) kept local
148
+ * so the author API does not widen its import surface. The Host verifies the
149
+ * produced adapter and hard-binds its `name` to the config key.
67
150
  */
151
+ export interface PluginChannelAdapterLike {
152
+ name: string;
153
+ start(handler: (msg: import('../channel-types.js').ChannelMessage) => Promise<void>): Promise<void>;
154
+ send(reply: import('../channel-types.js').ChannelReply): Promise<void>;
155
+ stop(): Promise<void>;
156
+ }
157
+ export interface PluginChannelRegistration {
158
+ id: string;
159
+ factory: PluginChannelFactory;
160
+ }
161
+ export interface HookRegistrationOptions {
162
+ /** Required for the two dual-phase events; ordinary events must not set it. */
163
+ phase?: 'transform' | 'vote';
164
+ priority?: number;
165
+ timeoutMs?: number;
166
+ }
167
+ export interface DualPhaseHookOptions {
168
+ phase: 'transform' | 'vote';
169
+ priority?: number;
170
+ timeoutMs?: number;
171
+ }
68
172
  export interface PluginLogger {
69
173
  debug(message: string, ...args: unknown[]): void;
70
174
  info(message: string, ...args: unknown[]): void;
71
175
  warn(message: string, ...args: unknown[]): void;
72
176
  error(message: string, ...args: unknown[]): void;
73
177
  }
74
- /**
75
- * Plugin API
76
- *
77
- * Plugin 在 register() 回调中使用此对象注册能力。
78
- */
79
178
  export declare class PluginApi {
80
- /** Plugin ID */
81
179
  readonly id: string;
82
- /** Plugin 显示名称 */
83
180
  readonly name: string;
84
- /** Plugin 版本 */
85
- readonly version?: string;
86
- /** Plugin 描述 */
181
+ readonly version: string;
87
182
  readonly description?: string;
88
- /** Plugin 源路径 */
89
183
  readonly source: string;
90
- /** Plugin root 目录 */
91
- readonly rootDir?: string;
92
- /** Plugin 配置 */
184
+ readonly rootDir: string;
93
185
  readonly pluginConfig: Record<string, unknown>;
94
- /** Plugin Logger */
95
186
  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
- }>;
187
+ /** Per-plugin secret storage backed by the Host credentials vault. */
188
+ readonly secrets: PluginSecrets;
189
+ private readonly stateDirPath;
190
+ private credentialStore?;
191
+ private readonly injectedCredentialStore?;
125
192
  constructor(opts: {
126
193
  id: string;
127
194
  name: string;
128
- version?: string;
195
+ version: string;
129
196
  description?: string;
130
197
  source: string;
131
- rootDir?: string;
132
- pluginConfig?: Record<string, unknown>;
198
+ rootDir: string;
199
+ pluginConfig: Record<string, unknown>;
200
+ /** Override for the per-plugin state directory (tests / custom layouts). */
201
+ stateDir?: string;
202
+ /** Shared credentials vault; falls back to `CredentialStore.openDefault`. */
203
+ credentialStore?: CredentialStore;
133
204
  });
134
205
  /**
135
- * 注册 LLM Provider
136
- *
137
- * @param registration - Provider 注册定义
206
+ * Per-plugin private state directory (`OCTOPI_HOME/plugin-state/<id>`).
207
+ * Created on first access with mode 0700 (and tightened to 0700 when the
208
+ * directory already looser). Runtime state goes here — secrets go through
209
+ * {@link PluginApi.secrets}, never into files.
138
210
  */
139
- registerProvider(registration: ProviderRegistration): void;
211
+ get stateDir(): string;
212
+ /** Ensure the state directory exists with 0700. Called by stateDir consumers. */
213
+ ensureStateDir(): Promise<string>;
214
+ private getCredentialStore;
140
215
  /**
141
- * 注册 Channel Adapter
216
+ * Stage a Tool contribution. It is not mounted or exposed by this call.
142
217
  *
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 - 注册选项
218
+ * @param tool - Core ToolDefinition
219
+ * @param handler - Core ToolHandler
220
+ * @param opts - Execution and optional contribution metadata
154
221
  */
155
222
  registerTool(tool: ToolDefinition, handler: ToolHandler, opts?: ToolRegistrationOptions): void;
156
223
  /**
157
- * 注册 Context Engine
158
- *
159
- * Context Engine 是 exclusive slot —— 同一时刻只有一个 active。
224
+ * Stage a typed hook contribution using one of the 22 existing event names.
160
225
  *
161
- * @param id - Engine ID
162
- * @param engine - Context Engine 实例
226
+ * @param hookName - Existing hook name
227
+ * @param handler - Event-specific handler
228
+ * @param opts - Ordering and cooperative timeout options
163
229
  */
164
- registerContextEngine(id: string, engine: ContextEngine): void;
230
+ on<K extends PluginHookName>(hookName: K, handler: HookHandler<K>, opts?: HookRegistrationOptions): void;
231
+ /** Register a parameter Transform or admission Vote for before_tool_call. */
232
+ 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;
233
+ /** Register a controlled Iteration Transform or admission Vote. */
234
+ 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;
235
+ /** Stage a Host-owned background service; start/stop is driven by Gateway. */
236
+ registerService(registration: HookServiceRegistration): void;
165
237
  /**
166
- * 注册 Hook
238
+ * Stage a model Provider factory. The Host instantiates it when a
239
+ * `models.providers` entry references this id via its `plugin` field.
167
240
  *
168
- * Hook handler 按 priority 降序执行,同 priority 按注册顺序。
169
- *
170
- * @param hookName - Hook 名称
171
- * @param handler - Hook handler
172
- * @param opts - 选项(priority、timeoutMs)
241
+ * @param id - Stable provider id (globally unique across plugins, like services)
242
+ * @param factory - Builds a Core ModelProvider for one config instance
173
243
  */
174
- on<TEvent = unknown, TResult = void>(hookName: string, handler: (event: TEvent) => Promise<TResult | undefined | void>, opts?: HookRegistrationOptions): void;
244
+ registerProvider(id: string, factory: PluginProviderFactory): void;
175
245
  /**
176
- * 注册 Command
177
- *
178
- * Command 绕过 LLM,直接执行。
246
+ * Stage a Gateway channel factory. The Host instantiates it when a `channels`
247
+ * entry references this id via its `plugin` field.
179
248
  *
180
- * @param def - Command 定义
249
+ * @param id - Stable channel id (globally unique across plugins, like providers)
250
+ * @param factory - Builds a ChannelAdapter for one channels config instance
181
251
  */
182
- registerCommand(def: {
183
- name: string;
184
- handler: HookHandler;
185
- description?: string;
186
- }): void;
252
+ registerChannel(id: string, factory: PluginChannelFactory): void;
187
253
  /**
188
- * 注册后台服务
254
+ * Look up the live runtime instance the Host serves for one of this
255
+ * plugin's own factory-backed contributions (providers, channels). The
256
+ * instance is registered when the Host accepts the factory product (after
257
+ * contract validation) and retires when its lifecycle method runs (`stop()`
258
+ * for channels, `dispose()` for providers — recorded when the call is
259
+ * requested, regardless of the outcome) or when a newer instance for the
260
+ * same config identity supersedes it (hot-reload replace; the superseded
261
+ * instance may still serve draining in-flight work).
189
262
  *
190
- * 服务在 Gateway 启动时 start,关闭时 stop。
263
+ * Exactly-one semantics: the lookup succeeds only while exactly one live
264
+ * instance exists. It throws a real error when the contribution was never
265
+ * instantiated, when its instance was retired, when several instances are
266
+ * live at once (multi-instance providers must capture per-instance handles
267
+ * in their factory closure instead), or when the key is not a contribution
268
+ * of this plugin (cross-plugin lookup is not part of the v1 contract).
191
269
  *
192
- * @param service - 服务定义
270
+ * @param kind - 'provider' or 'channel'
271
+ * @param id - Contribution key (the id passed to registerProvider/registerChannel)
272
+ * @returns The live instance the Host serves for this contribution
193
273
  */
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
- }>;
274
+ getContributionInstance(kind: 'provider', id: string): ModelProvider;
275
+ getContributionInstance(kind: 'channel', id: string): PluginChannelAdapterLike;
276
+ getContributionInstance(kind: ContributionInstanceKind, id: string): object;
240
277
  /**
241
- * 注册 Web Search Provider
278
+ * Stage a Command contribution. Host authorization is enforced when mounted.
242
279
  *
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(兼容多种命名)
280
+ * @param definition - Command metadata and handler
280
281
  */
281
- private getProviderId;
282
+ registerCommand(definition: PluginCommandRegistration): void;
282
283
  /**
283
- * 解析相对于 plugin root 的路径
284
+ * Resolve a path relative to the plugin root in ESM.
284
285
  *
285
- * @param input - 相对路径
286
- * @returns 绝对路径
286
+ * @param input - Relative or absolute path
287
+ * @returns Absolute path; not a filesystem security boundary
287
288
  */
288
289
  resolvePath(input: string): string;
289
290
  }