@octopi-agent/engine 0.102.10 → 0.121.15

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 (321) 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/console-access-key.d.ts +46 -0
  5. package/dist/config-admin/console-access-key.js +47 -0
  6. package/dist/config-admin/discover.d.ts +33 -4
  7. package/dist/config-admin/discover.js +101 -6
  8. package/dist/config-admin/env.d.ts +11 -0
  9. package/dist/config-admin/env.js +41 -0
  10. package/dist/config-admin/error-copy.d.ts +106 -0
  11. package/dist/config-admin/error-copy.js +287 -0
  12. package/dist/config-admin/i18n.d.ts +21 -0
  13. package/dist/config-admin/i18n.js +19 -0
  14. package/dist/config-admin/index.d.ts +8 -2
  15. package/dist/config-admin/index.js +4 -1
  16. package/dist/config-admin/model-presets.d.ts +14 -0
  17. package/dist/config-admin/model-presets.js +595 -70
  18. package/dist/config-admin/onboarding-apply.d.ts +83 -0
  19. package/dist/config-admin/onboarding-apply.js +259 -0
  20. package/dist/config-admin/onboarding.d.ts +160 -0
  21. package/dist/config-admin/onboarding.js +298 -0
  22. package/dist/config-admin/password-policy.d.ts +24 -0
  23. package/dist/config-admin/password-policy.js +31 -0
  24. package/dist/config-admin/redact.d.ts +42 -9
  25. package/dist/config-admin/redact.js +69 -5
  26. package/dist/config-schema/agent.d.ts +5 -1
  27. package/dist/config-schema/agent.js +20 -2
  28. package/dist/config-schema/browser.d.ts +62 -0
  29. package/dist/config-schema/browser.js +89 -0
  30. package/dist/config-schema/context.d.ts +7 -2
  31. package/dist/config-schema/context.js +6 -3
  32. package/dist/config-schema/engine.d.ts +86 -7
  33. package/dist/config-schema/engine.js +9 -2
  34. package/dist/config-schema/governance.d.ts +12 -1
  35. package/dist/config-schema/governance.js +10 -2
  36. package/dist/config-schema/models.d.ts +12 -8
  37. package/dist/config-schema/models.js +16 -1
  38. package/dist/config-schema/run.d.ts +4 -0
  39. package/dist/config-schema/run.js +10 -0
  40. package/dist/config-schema/shared.d.ts +1 -0
  41. package/dist/config-schema/shared.js +4 -2
  42. package/dist/config-schema/substrate.d.ts +5 -0
  43. package/dist/config-schema/substrate.js +8 -0
  44. package/dist/config.d.ts +116 -10
  45. package/dist/config.js +109 -13
  46. package/dist/file-mode.d.ts +67 -0
  47. package/dist/file-mode.js +182 -0
  48. package/dist/fork-child.d.ts +82 -0
  49. package/dist/fork-child.js +123 -0
  50. package/dist/harness/activation/delegated-run.d.ts +42 -0
  51. package/dist/harness/activation/delegated-run.js +71 -0
  52. package/dist/harness/activation/dispatcher.js +4 -0
  53. package/dist/harness/activation/index.d.ts +1 -0
  54. package/dist/harness/activation/run-backend.d.ts +92 -0
  55. package/dist/harness/activation/run-backend.js +16 -0
  56. package/dist/harness/activation/run-protocol.d.ts +392 -0
  57. package/dist/harness/activation/run-protocol.js +19 -0
  58. package/dist/harness/activation/runtime.d.ts +33 -0
  59. package/dist/harness/activation/runtime.js +119 -28
  60. package/dist/harness/activation/types.d.ts +19 -2
  61. package/dist/harness/agent/builder.d.ts +12 -0
  62. package/dist/harness/agent/builder.js +78 -22
  63. package/dist/harness/agent/config-bridge.d.ts +10 -1
  64. package/dist/harness/agent/config-bridge.js +15 -3
  65. package/dist/harness/agent/registered-tool-adapter.d.ts +27 -0
  66. package/dist/harness/agent/registered-tool-adapter.js +67 -0
  67. package/dist/harness/agent/wire-agent-builder.d.ts +2 -0
  68. package/dist/harness/agent/wire-agent-builder.js +9 -2
  69. package/dist/harness/capabilities/document/backends/plain.js +2 -1
  70. package/dist/harness/capabilities/document/legacy/factory.js +3 -2
  71. package/dist/harness/collaboration/autonomous-subsystem/audit/reader.d.ts +17 -0
  72. package/dist/harness/collaboration/autonomous-subsystem/audit/reader.js +66 -36
  73. package/dist/harness/collaboration/autonomous-subsystem/audit/writer.d.ts +6 -2
  74. package/dist/harness/collaboration/autonomous-subsystem/audit/writer.js +27 -7
  75. package/dist/harness/collaboration/autonomous-subsystem/boundary/validator.js +13 -0
  76. package/dist/harness/collaboration/autonomous-subsystem/loader.js +1 -0
  77. package/dist/harness/collaboration/autonomous-subsystem/runtime.d.ts +11 -0
  78. package/dist/harness/collaboration/autonomous-subsystem/runtime.js +17 -0
  79. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.d.ts +13 -3
  80. package/dist/harness/collaboration/autonomous-subsystem/sense/engine.js +48 -39
  81. package/dist/harness/collaboration/autonomous-subsystem/think/executor.js +3 -0
  82. package/dist/harness/collaboration/autonomous-subsystem/types.d.ts +4 -0
  83. package/dist/harness/collaboration/delegation/child-run.d.ts +9 -0
  84. package/dist/harness/collaboration/delegation/child-run.js +34 -2
  85. package/dist/harness/collaboration/delegation/registry-types.d.ts +2 -0
  86. package/dist/harness/collaboration/delegation/service.d.ts +9 -4
  87. package/dist/harness/collaboration/delegation/service.js +33 -12
  88. package/dist/harness/collaboration/delegation/store.d.ts +2 -0
  89. package/dist/harness/collaboration/delegation/store.js +1 -0
  90. package/dist/harness/collaboration/delegation/types.d.ts +11 -0
  91. package/dist/harness/collaboration/delegation/wiring.d.ts +2 -0
  92. package/dist/harness/collaboration/delegation/wiring.js +1 -0
  93. package/dist/harness/context/capabilities/compact/engine.d.ts +44 -5
  94. package/dist/harness/context/capabilities/compact/engine.js +127 -39
  95. package/dist/harness/context/capabilities/compact/index.d.ts +2 -1
  96. package/dist/harness/context/capabilities/compact/index.js +1 -1
  97. package/dist/harness/context/capabilities/compact/types.d.ts +59 -9
  98. package/dist/harness/context/capabilities/summary/gate.d.ts +19 -2
  99. package/dist/harness/context/capabilities/summary/gate.js +53 -6
  100. package/dist/harness/context/capabilities/summary/registry.js +20 -0
  101. package/dist/harness/context/capabilities/summary/tool-binding.js +16 -12
  102. package/dist/harness/context/capabilities/summary/tool-bindings.d.ts +13 -0
  103. package/dist/harness/context/capabilities/summary/tool-bindings.js +22 -0
  104. package/dist/harness/context/capabilities/summary/types.d.ts +16 -0
  105. package/dist/harness/context/constitution/default-agents.md +85 -0
  106. package/dist/harness/context/context-size-ledger.js +8 -1
  107. package/dist/harness/context/default-context-engine.d.ts +100 -6
  108. package/dist/harness/context/default-context-engine.js +382 -89
  109. package/dist/harness/context/index.d.ts +2 -1
  110. package/dist/harness/context/index.js +1 -0
  111. package/dist/harness/context/layer-health.d.ts +4 -0
  112. package/dist/harness/context/layer-health.js +4 -0
  113. package/dist/harness/context/layer-types.d.ts +57 -0
  114. package/dist/harness/context/layer-types.js +73 -1
  115. package/dist/harness/context/layers.d.ts +3 -0
  116. package/dist/harness/context/layers.js +13 -6
  117. package/dist/harness/context/prefix-fingerprint.d.ts +46 -0
  118. package/dist/harness/context/prefix-fingerprint.js +52 -0
  119. package/dist/harness/context/summarize.js +18 -0
  120. package/dist/harness/context/system-prompt-assembler.d.ts +2 -0
  121. package/dist/harness/context/system-prompt-assembler.js +5 -2
  122. package/dist/harness/context/tool-result-aging.d.ts +104 -16
  123. package/dist/harness/context/tool-result-aging.js +211 -57
  124. package/dist/harness/context/types.d.ts +71 -4
  125. package/dist/harness/context/types.js +25 -1
  126. package/dist/harness/extension/execution-environment/effect-policy.d.ts +4 -3
  127. package/dist/harness/extension/execution-environment/effect-policy.js +2 -2
  128. package/dist/harness/extension/execution-environment/privileged-exec.js +4 -1
  129. package/dist/harness/extension/execution-environment/workspace.js +1 -1
  130. package/dist/harness/extension/plugin-ecosystem/channel-types.d.ts +27 -1
  131. package/dist/harness/extension/plugin-ecosystem/channel-types.js +11 -2
  132. package/dist/harness/extension/plugin-ecosystem/client-tools/registry.d.ts +12 -0
  133. package/dist/harness/extension/plugin-ecosystem/client-tools/registry.js +25 -0
  134. package/dist/harness/extension/plugin-ecosystem/commands/builtin.js +28 -1
  135. package/dist/harness/extension/plugin-ecosystem/index.d.ts +1 -0
  136. package/dist/harness/extension/plugin-ecosystem/index.js +1 -0
  137. package/dist/harness/extension/plugin-ecosystem/plugins/api.d.ts +168 -1
  138. package/dist/harness/extension/plugin-ecosystem/plugins/api.js +156 -15
  139. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-instances.d.ts +95 -0
  140. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-instances.js +170 -0
  141. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-kinds.d.ts +178 -0
  142. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-kinds.js +314 -0
  143. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.d.ts +40 -5
  144. package/dist/harness/extension/plugin-ecosystem/plugins/contribution-registry.js +45 -26
  145. package/dist/harness/extension/plugin-ecosystem/plugins/index.d.ts +1 -1
  146. package/dist/harness/extension/plugin-ecosystem/plugins/loader.d.ts +11 -1
  147. package/dist/harness/extension/plugin-ecosystem/plugins/loader.js +42 -76
  148. package/dist/harness/extension/plugin-ecosystem/plugins/manager.d.ts +30 -1
  149. package/dist/harness/extension/plugin-ecosystem/plugins/manager.js +46 -0
  150. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.d.ts +9 -0
  151. package/dist/harness/extension/plugin-ecosystem/plugins/manifest.js +19 -14
  152. package/dist/harness/extension/plugin-ecosystem/plugins/staging.d.ts +3 -1
  153. package/dist/harness/extension/plugin-ecosystem/plugins/staging.js +1 -1
  154. package/dist/harness/extension/plugin-ecosystem/tools/browser-types.d.ts +333 -0
  155. package/dist/harness/extension/plugin-ecosystem/tools/browser-types.js +16 -0
  156. package/dist/harness/extension/plugin-ecosystem/tools/browser.d.ts +64 -0
  157. package/dist/harness/extension/plugin-ecosystem/tools/browser.js +692 -0
  158. package/dist/harness/extension/plugin-ecosystem/tools/builtin.d.ts +0 -37
  159. package/dist/harness/extension/plugin-ecosystem/tools/builtin.js +108 -4
  160. package/dist/harness/extension/plugin-ecosystem/tools/delegation.js +18 -0
  161. package/dist/harness/extension/plugin-ecosystem/tools/file-edit.js +34 -0
  162. package/dist/harness/extension/plugin-ecosystem/tools/file-search.d.ts +0 -6
  163. package/dist/harness/extension/plugin-ecosystem/tools/file-search.js +57 -4
  164. package/dist/harness/extension/plugin-ecosystem/tools/git-tools.js +81 -13
  165. package/dist/harness/extension/plugin-ecosystem/tools/http.js +5 -0
  166. package/dist/harness/extension/plugin-ecosystem/tools/knowledge.js +13 -7
  167. package/dist/harness/extension/plugin-ecosystem/tools/package-tools.js +126 -14
  168. package/dist/harness/extension/plugin-ecosystem/tools/platform.d.ts +1 -1
  169. package/dist/harness/extension/plugin-ecosystem/tools/platform.js +44 -5
  170. package/dist/harness/extension/plugin-ecosystem/tools/tool-bus.js +10 -24
  171. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.d.ts +7 -0
  172. package/dist/harness/extension/plugin-ecosystem/tools/tool-set.js +4 -0
  173. package/dist/harness/governance/credentials/db.d.ts +9 -0
  174. package/dist/harness/governance/credentials/db.js +122 -31
  175. package/dist/harness/governance/credentials/store.d.ts +68 -7
  176. package/dist/harness/governance/credentials/store.js +177 -64
  177. package/dist/harness/governance/credentials/types.d.ts +13 -2
  178. package/dist/harness/governance/index.d.ts +1 -0
  179. package/dist/harness/governance/index.js +1 -0
  180. package/dist/harness/governance/registry/db.d.ts +32 -0
  181. package/dist/harness/governance/registry/db.js +142 -0
  182. package/dist/harness/governance/registry/index.d.ts +9 -0
  183. package/dist/harness/governance/registry/index.js +9 -0
  184. package/dist/harness/governance/registry/service.d.ts +381 -0
  185. package/dist/harness/governance/registry/service.js +825 -0
  186. package/dist/harness/governance/registry/types.d.ts +77 -0
  187. package/dist/harness/governance/registry/types.js +7 -0
  188. package/dist/harness/governance/security/default-security-guard.d.ts +3 -0
  189. package/dist/harness/governance/security/default-security-guard.js +12 -1
  190. package/dist/harness/governance/security/risk-evaluator.d.ts +13 -3
  191. package/dist/harness/governance/security/risk-evaluator.js +307 -21
  192. package/dist/harness/governance/security/shell-parser-treesitter.js +12 -4
  193. package/dist/harness/governance/session-acl/tool-rights.d.ts +1 -0
  194. package/dist/harness/index.d.ts +5 -3
  195. package/dist/harness/index.js +2 -2
  196. package/dist/harness/knowledge/boot-config.d.ts +2 -0
  197. package/dist/harness/knowledge/boot-config.js +2 -0
  198. package/dist/harness/knowledge/client.d.ts +53 -7
  199. package/dist/harness/knowledge/client.js +77 -20
  200. package/dist/harness/knowledge/db.d.ts +16 -0
  201. package/dist/harness/knowledge/db.js +107 -41
  202. package/dist/harness/knowledge/engine-thread.js +5 -7
  203. package/dist/harness/knowledge/grounding.js +4 -1
  204. package/dist/harness/knowledge/http-app.d.ts +15 -0
  205. package/dist/harness/knowledge/http-app.js +82 -21
  206. package/dist/harness/knowledge/http-bridge.d.ts +15 -0
  207. package/dist/harness/knowledge/http-bridge.js +19 -0
  208. package/dist/harness/knowledge/knowledge-serve-child.js +2 -3
  209. package/dist/harness/knowledge/query-service.d.ts +12 -2
  210. package/dist/harness/knowledge/query-service.js +75 -41
  211. package/dist/harness/knowledge/query-worker-client.d.ts +5 -1
  212. package/dist/harness/knowledge/query-worker-client.js +4 -1
  213. package/dist/harness/knowledge/query-worker.js +5 -3
  214. package/dist/harness/knowledge/read-http.d.ts +2 -0
  215. package/dist/harness/knowledge/read-http.js +9 -2
  216. package/dist/harness/knowledge/retriever.d.ts +1 -1
  217. package/dist/harness/knowledge/retriever.js +1 -2
  218. package/dist/harness/knowledge/serve.d.ts +6 -1
  219. package/dist/harness/knowledge/serve.js +5 -6
  220. package/dist/harness/knowledge/source-store.d.ts +101 -5
  221. package/dist/harness/knowledge/source-store.js +297 -71
  222. package/dist/harness/knowledge/start-service-process.d.ts +27 -8
  223. package/dist/harness/knowledge/start-service-process.js +49 -90
  224. package/dist/harness/knowledge/tenant-gate.d.ts +81 -0
  225. package/dist/harness/knowledge/tenant-gate.js +167 -0
  226. package/dist/harness/knowledge/writer-service.d.ts +18 -2
  227. package/dist/harness/knowledge/writer-service.js +80 -16
  228. package/dist/harness/knowledge/writer-worker-client.d.ts +9 -2
  229. package/dist/harness/knowledge/writer-worker-client.js +20 -3
  230. package/dist/harness/knowledge/writer-worker.js +11 -4
  231. package/dist/harness/memory/backfill-trigger.d.ts +10 -3
  232. package/dist/harness/memory/backfill-trigger.js +19 -19
  233. package/dist/harness/memory/cognition-seeds.d.ts +45 -0
  234. package/dist/harness/memory/cognition-seeds.js +67 -0
  235. package/dist/harness/memory/cognition.d.ts +12 -3
  236. package/dist/harness/memory/cognition.js +55 -35
  237. package/dist/harness/memory/conceptualizer.d.ts +11 -1
  238. package/dist/harness/memory/conceptualizer.js +10 -1
  239. package/dist/harness/memory/context-slice.d.ts +42 -0
  240. package/dist/harness/memory/context-slice.js +197 -0
  241. package/dist/harness/memory/health-probe.d.ts +8 -2
  242. package/dist/harness/memory/health-probe.js +10 -13
  243. package/dist/harness/memory/index.d.ts +5 -1
  244. package/dist/harness/memory/index.js +3 -1
  245. package/dist/harness/memory/sqlite/agent-db.d.ts +1 -0
  246. package/dist/harness/memory/sqlite/agent-db.js +9 -8
  247. package/dist/harness/memory/sqlite/cognition-store.d.ts +26 -3
  248. package/dist/harness/memory/sqlite/cognition-store.js +103 -45
  249. package/dist/harness/memory/sqlite/memory-store.js +4 -0
  250. package/dist/harness/memory/sqlite/sqlite-vec.d.ts +24 -1
  251. package/dist/harness/memory/sqlite/sqlite-vec.js +37 -1
  252. package/dist/harness/memory/types.d.ts +18 -2
  253. package/dist/harness/observability/observer/hub.d.ts +10 -0
  254. package/dist/harness/observability/observer/hub.js +95 -2
  255. package/dist/harness/run/agent/agent.js +3 -2
  256. package/dist/harness/run/concurrency/tool-validator.js +4 -3
  257. package/dist/harness/run/reliability/run-agent.d.ts +22 -0
  258. package/dist/harness/run/reliability/run-agent.js +79 -10
  259. package/dist/harness/run/run-host.d.ts +302 -0
  260. package/dist/harness/run/run-host.js +978 -0
  261. package/dist/harness/run/run-scope.d.ts +11 -0
  262. package/dist/harness/run/run-scope.js +19 -1
  263. package/dist/harness/run/runner.d.ts +149 -22
  264. package/dist/harness/run/runner.js +352 -35
  265. package/dist/harness/session/in-memory-store.js +13 -1
  266. package/dist/harness/session/schedules/service.d.ts +10 -2
  267. package/dist/harness/session/schedules/service.js +13 -2
  268. package/dist/harness/session/tasks/tools.js +12 -0
  269. package/dist/harness/session/types.d.ts +10 -14
  270. package/dist/harness/shared/events/agent-event-map.d.ts +29 -0
  271. package/dist/harness/shared/types/agent-definition.d.ts +6 -0
  272. package/dist/index.d.ts +3 -2
  273. package/dist/index.js +2 -1
  274. package/dist/integration/agent-runtime/channel-message-source.d.ts +3 -1
  275. package/dist/integration/agent-runtime/channel-message-source.js +4 -3
  276. package/dist/integration/browser/camoufox.d.ts +40 -0
  277. package/dist/integration/browser/camoufox.js +80 -0
  278. package/dist/integration/browser/index.d.ts +91 -0
  279. package/dist/integration/browser/index.js +110 -0
  280. package/dist/integration/browser/install.d.ts +47 -0
  281. package/dist/integration/browser/install.js +214 -0
  282. package/dist/integration/browser/playwright.d.ts +224 -0
  283. package/dist/integration/browser/playwright.js +925 -0
  284. package/dist/integration/browser/service.d.ts +41 -0
  285. package/dist/integration/browser/service.js +181 -0
  286. package/dist/integration/browser/stealth.d.ts +42 -0
  287. package/dist/integration/browser/stealth.js +104 -0
  288. package/dist/integration/providers/anthropic-message-normalize.d.ts +20 -0
  289. package/dist/integration/providers/anthropic-message-normalize.js +48 -0
  290. package/dist/integration/providers/anthropic.js +27 -2
  291. package/dist/integration/providers/fetch-timeout.d.ts +17 -0
  292. package/dist/integration/providers/fetch-timeout.js +24 -0
  293. package/dist/integration/providers/openai.d.ts +8 -0
  294. package/dist/integration/providers/openai.js +41 -1
  295. package/dist/integration/providers/wire-dump-diff.js +2 -1
  296. package/dist/integration/providers/wire-dump.d.ts +56 -2
  297. package/dist/integration/providers/wire-dump.js +119 -6
  298. package/dist/integration/storage/archive-manager.d.ts +14 -2
  299. package/dist/integration/storage/archive-manager.js +24 -8
  300. package/dist/integration/storage/atomic-tmp.d.ts +12 -0
  301. package/dist/integration/storage/atomic-tmp.js +36 -0
  302. package/dist/integration/storage/jsonl.d.ts +9 -0
  303. package/dist/integration/storage/jsonl.js +137 -38
  304. package/dist/integration/storage/session-index.d.ts +5 -0
  305. package/dist/integration/storage/session-index.js +25 -4
  306. package/dist/integration/tools/assemble.d.ts +50 -0
  307. package/dist/integration/tools/assemble.js +137 -0
  308. package/dist/paths.d.ts +18 -0
  309. package/dist/paths.js +36 -0
  310. package/dist/subsystems/cognition-steward/conceptualize/config.yaml +3 -1
  311. package/dist/subsystems/cognition-steward/conceptualize/handler.js +74 -5
  312. package/dist/subsystems/cognition-steward/consolidate/SUBSYSTEM.md +3 -2
  313. package/dist/subsystems/cognition-steward/consolidate/config.yaml +11 -2
  314. package/dist/subsystems/cognition-steward/consolidate/handler.d.ts +6 -3
  315. package/dist/subsystems/cognition-steward/consolidate/handler.js +266 -28
  316. package/dist/subsystems/memory-steward/backfill/handler.js +3 -2
  317. package/dist/subsystems/memory-steward/govern/config.yaml +6 -1
  318. package/dist/subsystems/wisdom-steward/attribute/config.yaml +5 -1
  319. package/dist/subsystems/wisdom-steward/formation/config.yaml +3 -0
  320. package/dist/subsystems/wisdom-steward/govern/config.yaml +6 -1
  321. package/package.json +5 -3
@@ -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
+ }
@@ -0,0 +1,170 @@
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
+ const tables = new WeakMap();
21
+ /** Called only by the host when constructing an author API. */
22
+ export function createInstanceTable(api) {
23
+ const table = new ContributionInstanceTable();
24
+ tables.set(api, table);
25
+ return table;
26
+ }
27
+ /** Read the host-owned instance table of one author API. */
28
+ export function readInstanceTable(api) {
29
+ const table = tables.get(api);
30
+ if (!table)
31
+ throw new Error('PluginApi was not created by the host loader');
32
+ return table;
33
+ }
34
+ export class ContributionInstanceTable {
35
+ entries = [];
36
+ /**
37
+ * Record one Host-accepted instance and wrap its retirement method so the
38
+ * entry retires together with the instance. Wrapping happens here — the
39
+ * single registration path — so every Host teardown call site is covered
40
+ * without explicit retire calls.
41
+ *
42
+ * Acceptance semantics:
43
+ * - a newer instance for the same (kind, key, label) supersedes the previous
44
+ * one (config hot-reload replace); the superseded entry is marked retired;
45
+ * - re-accepting the *same* object (singleton factories) refreshes its label
46
+ * instead of double-registering it;
47
+ * - an instance that cannot be tracked is **not registered**: a non-object
48
+ * product, a frozen/sealed object whose retirement method cannot be
49
+ * wrapped, or (channels) a product without `stop` — in every case the
50
+ * Host's own contract validation is the authority that reports the broken
51
+ * adapter, and this method never invents methods it does not own.
52
+ *
53
+ * @param opts - Instance identity and retirement wiring
54
+ * @returns Whether the instance was registered (tracked)
55
+ */
56
+ attach(opts) {
57
+ const target = opts.instance;
58
+ // Callables are valid contract objects; only primitives/null are not.
59
+ if (typeof target !== 'object' && typeof target !== 'function')
60
+ return false;
61
+ if (target === null || target === undefined)
62
+ return false;
63
+ const same = this.entries.find((entry) => entry.kind === opts.kind && entry.key === opts.key && entry.instance === target);
64
+ if (same) {
65
+ // Re-acceptance (e.g. a singleton factory product that was retired and
66
+ // is being served again): the instance is live again as of now.
67
+ same.label = opts.label;
68
+ same.state = 'live';
69
+ return true;
70
+ }
71
+ const original = target[opts.retireMethod];
72
+ const entry = {
73
+ kind: opts.kind,
74
+ key: opts.key,
75
+ label: opts.label,
76
+ instance: target,
77
+ state: 'live',
78
+ superseded: [],
79
+ };
80
+ const retire = () => {
81
+ entry.state = 'retired';
82
+ };
83
+ if (typeof original === 'function') {
84
+ try {
85
+ target[opts.retireMethod] = function (...args) {
86
+ retire();
87
+ return original.apply(target, args);
88
+ };
89
+ }
90
+ catch {
91
+ // Frozen/sealed instance: retirement cannot be tracked. Leaving it
92
+ // unregistered keeps lookup honest ("never instantiated") instead of
93
+ // handing out an instance the Host has already stopped.
94
+ return false;
95
+ }
96
+ }
97
+ else if (opts.defineRetire) {
98
+ try {
99
+ target[opts.retireMethod] = retire;
100
+ }
101
+ catch {
102
+ return false;
103
+ }
104
+ }
105
+ else {
106
+ // Missing mandatory lifecycle method: a broken adapter. The Host's
107
+ // contract validation reports it; never patch `stop` here or that check
108
+ // would stop being honest. Untracked for the same reason as frozen.
109
+ return false;
110
+ }
111
+ // Logical retirement of the superseded instance (recorded for rollback),
112
+ // then prune retired tombstones to one per (kind, key) — lookup only
113
+ // distinguishes "was retired" from "never instantiated", so one tombstone
114
+ // is enough. Pruned tombstones stay reachable through `superseded`.
115
+ for (const prior of this.entries) {
116
+ if (prior.kind === opts.kind && prior.key === opts.key && prior.label === opts.label && prior.state === 'live') {
117
+ prior.state = 'retired';
118
+ entry.superseded.push(prior);
119
+ }
120
+ }
121
+ const retired = this.entries.filter((e) => e.kind === opts.kind && e.key === opts.key && e.state === 'retired');
122
+ for (const tomb of retired.slice(0, -1)) {
123
+ this.entries.splice(this.entries.indexOf(tomb), 1);
124
+ }
125
+ this.entries.push(entry);
126
+ return true;
127
+ }
128
+ /**
129
+ * Every recorded entry for one contribution key (live and retired).
130
+ *
131
+ * @param kind - Contribution kind
132
+ * @param key - Contribution key
133
+ * @returns Matching entries in instantiation order
134
+ */
135
+ find(kind, key) {
136
+ return this.entries.filter((entry) => entry.kind === kind && entry.key === key);
137
+ }
138
+ /**
139
+ * Logical retirement by instance identity — called by the Host when it
140
+ * stops routing to an instance (removal, hot-reload replace, config reset).
141
+ * Idempotent; the wrapped lifecycle method remains the physical backstop.
142
+ *
143
+ * @param instance - The instance object the Host stopped routing to
144
+ */
145
+ retireByInstance(instance) {
146
+ for (const entry of this.entries) {
147
+ if (entry.instance === instance)
148
+ entry.state = 'retired';
149
+ }
150
+ }
151
+ /**
152
+ * Roll back an acceptance of an instance that was validated but never
153
+ * installed (the Host aborted before routing to it). Removes its entry and
154
+ * resurrects the entries it superseded, so "live" again matches what the
155
+ * Host serves. No-op once the entry is not the current live one.
156
+ *
157
+ * @param instance - The accepted-but-never-installed instance
158
+ */
159
+ discardByInstance(instance) {
160
+ const entry = this.entries.find((e) => e.instance === instance);
161
+ if (!entry || entry.state !== 'live')
162
+ return;
163
+ this.entries.splice(this.entries.indexOf(entry), 1);
164
+ for (const prior of entry.superseded) {
165
+ prior.state = 'live';
166
+ if (!this.entries.includes(prior))
167
+ this.entries.push(prior);
168
+ }
169
+ }
170
+ }
@@ -0,0 +1,178 @@
1
+ /**
2
+ * Declarative contribution-kind table — the single source of truth for the
3
+ * plugin contribution pipeline semantics: staging uniqueness, reserved ids,
4
+ * publish ownership, manifest claims, manifest uniqueness and manifest↔
5
+ * registration reconciliation.
6
+ *
7
+ * Adding a contribution kind = one descriptor here + the typed surfaces
8
+ * (PluginApi.registerXxx signature, staging slot, record type/getter, manifest
9
+ * schema field). The staging write path (`push`, via `stageContribution`) and
10
+ * the staged-entry read path (`forEachStaged`, which pairs entries with their
11
+ * keys) both live on the descriptor, so the key↔entry pairing and the
12
+ * uniqueness checks cannot be bypassed or forgotten per kind.
13
+ *
14
+ * Hooks are the deliberate semantic exception (multi-handler per name, no
15
+ * cross-plugin ownership), but their staging write path — priority-sorted Map
16
+ * insert — is also owned here (`hooks.push`), not by `PluginApi.on`.
17
+ */
18
+ import type { ContributionInstanceTable } from './contribution-instances.js';
19
+ import type { OrderedHookEntry, PluginChannelRegistration, PluginCommandRegistration, PluginProviderRegistration, PluginToolContribution } from './api.js';
20
+ import type { HookServiceRegistration } from '../hooks/types.js';
21
+ import type { PluginManifest } from './manifest.js';
22
+ import type { StagedContributions } from './staging.js';
23
+ /** Field name shared by the manifest `contributes` block and the staging slot. */
24
+ export type ContributionField = 'tools' | 'commands' | 'hooks' | 'services' | 'providers' | 'channels';
25
+ /**
26
+ * Published-record slots. Records are uniformly `{ pluginId, ...entry }`
27
+ * (hooks entries already carry `pluginId`, so they are stored verbatim). The
28
+ * registry's typed getters return these slots; their declared record types are
29
+ * structurally identical, so drift is caught at compile time.
30
+ */
31
+ export interface ContributionSink {
32
+ tools: ({
33
+ pluginId: string;
34
+ } & PluginToolContribution)[];
35
+ commands: ({
36
+ pluginId: string;
37
+ } & PluginCommandRegistration)[];
38
+ hooks: OrderedHookEntry[];
39
+ services: ({
40
+ pluginId: string;
41
+ } & HookServiceRegistration)[];
42
+ providers: ({
43
+ pluginId: string;
44
+ } & PluginProviderRegistration)[];
45
+ channels: ({
46
+ pluginId: string;
47
+ } & PluginChannelRegistration)[];
48
+ }
49
+ /** Host-private hook that factory-backed records carry (see record.acceptInstance). */
50
+ export interface ContributionInstanceHostHook {
51
+ /**
52
+ * Register the Host-accepted instance (birth) with its config identity.
53
+ *
54
+ * @param instance - The accepted factory product
55
+ * @param label - Config identity of this instantiation
56
+ * @returns Whether the instance is retirement-trackable; false means it was
57
+ * not registered (frozen/sealed) and the Host should surface the
58
+ * degradation — lookup will report it as never instantiated
59
+ */
60
+ acceptInstance(instance: object, label: string): boolean;
61
+ }
62
+ export interface ContributionKind<TEntry extends object> {
63
+ /** Manifest `contributes.<field>` / staging slot name. */
64
+ readonly field: ContributionField;
65
+ /**
66
+ * Singular label used in diagnostics and ownership keys ("provider"). The
67
+ * ownership key prefix (`tool:`, `provider:`, …) IS this label — changing it
68
+ * changes conflict identity, so treat labels as stable identifiers.
69
+ */
70
+ readonly label: string;
71
+ /** Whether one key may be owned by only one plugin (hooks chain across plugins). */
72
+ readonly globallyUnique: boolean;
73
+ /** Whether one plugin may stage the same key only once (hooks allow many handlers). */
74
+ readonly perPluginUnique: boolean;
75
+ /** Ids plugins may never claim (built-in adapters). */
76
+ readonly reservedIds: readonly string[];
77
+ /** Unique key of one staged entry. */
78
+ keyOf(entry: TEntry): string;
79
+ /** Keys declared in the manifest `contributes` block (raw, unnormalized). */
80
+ declaredKeys(manifest: PluginManifest): string[];
81
+ /**
82
+ * Iterate staged entries paired with their keys — the read side's single
83
+ * path. The pairing is computed inside the descriptor, so consumers cannot
84
+ * observe a key without its entry or vice versa.
85
+ */
86
+ forEachStaged(slot: StagedContributions, visit: (key: string, entry: TEntry) => void): void;
87
+ /** Stage one entry — the write side's single path (hooks: priority-sorted Map insert). */
88
+ push(slot: StagedContributions, entry: TEntry): void;
89
+ /** Append one published record to the registry sink. */
90
+ collect(sink: ContributionSink, pluginId: string, entry: TEntry): void;
91
+ /**
92
+ * Factory-backed kinds only: extend the staged entry with the host-private
93
+ * `acceptInstance` hook so the Host can register the instance it accepted
94
+ * (birth) and the table can track its retirement. The wiring lives here,
95
+ * like `push`, so a new factory kind cannot silently produce untracked
96
+ * instances — the return type makes the hook mandatory at compile time.
97
+ */
98
+ bindInstances?(entry: TEntry, instances: ContributionInstanceTable): TEntry & ContributionInstanceHostHook;
99
+ /** Kind-specific manifest checks beyond per-kind key uniqueness. */
100
+ assertManifestExtras?(manifest: PluginManifest): void;
101
+ /** Kind-specific manifest↔registration reconciliation beyond key matching. */
102
+ reconcileExtra?(manifest: PluginManifest, slot: StagedContributions): void;
103
+ }
104
+ /**
105
+ * Every contribution kind in manifest-schema order. Iteration order is
106
+ * observable in first-failure diagnostics and record ordering — keep it aligned
107
+ * with the `contributes` schema field order.
108
+ */
109
+ export declare const CONTRIBUTION_KINDS: readonly ContributionKind<object>[];
110
+ /** Typed staging slots for the author-facing register methods. */
111
+ export declare const TOOL_KIND: ContributionKind<PluginToolContribution>;
112
+ export declare const COMMAND_KIND: ContributionKind<PluginCommandRegistration>;
113
+ export declare const HOOK_KIND: ContributionKind<OrderedHookEntry>;
114
+ export declare const SERVICE_KIND: ContributionKind<HookServiceRegistration>;
115
+ export declare const PROVIDER_KIND: ContributionKind<PluginProviderRegistration>;
116
+ export declare const CHANNEL_KIND: ContributionKind<PluginChannelRegistration>;
117
+ /**
118
+ * Reject a manifest key list containing duplicates.
119
+ *
120
+ * @param values - Declared contribution keys
121
+ * @param field - Manifest field path for the error message
122
+ */
123
+ export declare function assertUnique(values: readonly string[], field: string): void;
124
+ /**
125
+ * Enforce per-kind key uniqueness of the manifest `contributes` block, plus
126
+ * kind-specific manifest checks.
127
+ *
128
+ * @param manifest - Plugin manifest
129
+ * @throws Error naming the first duplicated key
130
+ */
131
+ export declare function assertManifestKeysUnique(manifest: PluginManifest): void;
132
+ /**
133
+ * Reject a contribution key a plugin may never claim (built-in adapters).
134
+ *
135
+ * @param pluginId - Staging plugin
136
+ * @param kind - Contribution kind being staged
137
+ * @param key - Normalized contribution key
138
+ */
139
+ export declare function assertClaimable(pluginId: string, kind: ContributionKind<object>, key: string): void;
140
+ /**
141
+ * Reject a duplicate key staged twice by one plugin.
142
+ *
143
+ * @param pluginId - Staging plugin
144
+ * @param kind - Contribution kind being staged
145
+ * @param slot - The plugin's staging area
146
+ * @param key - Normalized contribution key
147
+ */
148
+ export declare function assertStagingKeyFree(pluginId: string, kind: ContributionKind<object>, slot: StagedContributions, key: string): void;
149
+ /**
150
+ * The staging write path shared by every register method: reserved-id and
151
+ * per-plugin uniqueness checks, then the kind's own staging insert.
152
+ *
153
+ * @param pluginId - Staging plugin
154
+ * @param kind - Contribution kind being staged
155
+ * @param slot - The plugin's staging area
156
+ * @param entry - Contribution entry to stage
157
+ */
158
+ export declare function stageContribution<TEntry extends object>(pluginId: string, kind: ContributionKind<TEntry>, slot: StagedContributions, entry: TEntry): void;
159
+ /**
160
+ * Manifest-side ownership claim strings ("provider:openai-compat") used by the
161
+ * loader's cross-plugin conflict detection. Kinds without cross-plugin
162
+ * ownership (hooks) declare no claims.
163
+ *
164
+ * @param kind - Contribution kind
165
+ * @param manifest - Candidate manifest
166
+ * @returns Claim strings for every declared key of the kind
167
+ */
168
+ export declare function declaredClaims(kind: ContributionKind<object>, manifest: PluginManifest): string[];
169
+ /**
170
+ * Reconcile the manifest `contributes` block against what the plugin actually
171
+ * staged: both directions must match exactly, then kind-specific checks run.
172
+ *
173
+ * @param kind - Contribution kind
174
+ * @param manifest - Plugin manifest
175
+ * @param slot - The plugin's staging area
176
+ * @throws Error naming the first mismatched key
177
+ */
178
+ export declare function assertManifestCoverage(kind: ContributionKind<object>, manifest: PluginManifest, slot: StagedContributions): void;