@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
@@ -19,6 +19,7 @@ import { statSync, realpathSync } from 'node:fs';
19
19
  import { homedir, tmpdir } from 'node:os';
20
20
  import { dirname, isAbsolute, resolve, sep } from 'node:path';
21
21
  import { killProcessTree, scrubEnv } from './process-isolation.js';
22
+ import { elidedCharsMarker } from '@octopi-agent/core/elision.js';
22
23
  function envForExec() {
23
24
  // root 态下 PATH/HOME 都是注入面(per-user 配置、可写 PATH 目录)——钉死系统值。
24
25
  // 其余一律不透传(凭证/注入面收敛)。
@@ -33,7 +34,9 @@ function envForExec() {
33
34
  }
34
35
  const OUTPUT_CAP = 128 * 1024;
35
36
  function capOutput(text) {
36
- return text.length > OUTPUT_CAP ? `${text.slice(0, OUTPUT_CAP)}\n…[truncated ${text.length - OUTPUT_CAP} chars]` : text;
37
+ return text.length > OUTPUT_CAP
38
+ ? `${text.slice(0, OUTPUT_CAP)}\n${elidedCharsMarker(text.length - OUTPUT_CAP)}`
39
+ : text;
37
40
  }
38
41
  /**
39
42
  * 执行一条已匹配的提权命令(不经 shell、不包 jail、cwd 钉住)。
@@ -146,7 +146,7 @@ export class FileWorkspace {
146
146
  // ── 内部工具 ──
147
147
  async execGit(args) {
148
148
  return new Promise((resolve, reject) => {
149
- const proc = spawn('git', args, { cwd: this.root });
149
+ const proc = spawn('git', args, { cwd: this.root, windowsHide: true });
150
150
  let stdout = '';
151
151
  proc.stdout.on('data', (d) => { stdout += d.toString(); });
152
152
  proc.on('close', (code) => {
@@ -6,10 +6,20 @@
6
6
  *
7
7
  * 设计要点:
8
8
  * - 本文件只定义契约,不关心 HTTP / WebSocket 传输
9
- * - Plugin 通过 registerChannel(adapter) 注册实现
9
+ * - Plugin 通过 registerChannel(id, factory) 贡献命名工厂(contributes.channels),
10
+ * 宿主按 channels[].plugin 引用实例化为本契约 adapter
10
11
  * - Gateway / Integration 按部署形态挂载具体 adapter
11
12
  */
12
13
  export type ChannelMessageDelivery = 'continued' | 'followup' | 'run';
14
+ /**
15
+ * Channel labels owned by built-in adapters. Plugin contributions must not
16
+ * claim them. Reply routing looks up `channels.get(msg.channel)` — i.e. by the
17
+ * **message label**, not by adapter name: the built-in HttpChannelAdapter
18
+ * emits `channel: 'http'` (REST) and `channel: 'ws'` (WebSocket), so a plugin
19
+ * registering either label would intercept built-in replies and command
20
+ * short-replies.
21
+ */
22
+ export declare const BUILTIN_CHANNEL_IDS: readonly ["http", "ws"];
13
23
  export interface ChannelMessage {
14
24
  id: string;
15
25
  channel: string;
@@ -31,9 +41,25 @@ export interface ChannelReply {
31
41
  replyToId?: string;
32
42
  metadata?: Record<string, unknown>;
33
43
  }
44
+ /**
45
+ * Adapter runtime state for health aggregation. `retiring` marks the drain
46
+ * window before a hot-reload swap or shutdown; `degraded` means the adapter is
47
+ * alive but impaired (e.g. backing off after repeated failures).
48
+ */
49
+ export interface ChannelAdapterStatus {
50
+ state: 'running' | 'dormant' | 'degraded' | 'retiring';
51
+ /** Human-readable elaboration, e.g. why the adapter is degraded. */
52
+ detail?: string;
53
+ }
34
54
  export interface ChannelAdapter {
35
55
  name: string;
36
56
  start(handler: (msg: ChannelMessage) => Promise<void>): Promise<void>;
37
57
  send(reply: ChannelReply): Promise<void>;
38
58
  stop(): Promise<void>;
59
+ /**
60
+ * Optional health probe. Adapters that do not implement it are reported as
61
+ * `running` after a successful start() — the contract guarantees start/stop
62
+ * symmetry, so "started" is the truthful default, not a placeholder.
63
+ */
64
+ status?(): ChannelAdapterStatus;
39
65
  }
@@ -6,7 +6,16 @@
6
6
  *
7
7
  * 设计要点:
8
8
  * - 本文件只定义契约,不关心 HTTP / WebSocket 传输
9
- * - Plugin 通过 registerChannel(adapter) 注册实现
9
+ * - Plugin 通过 registerChannel(id, factory) 贡献命名工厂(contributes.channels),
10
+ * 宿主按 channels[].plugin 引用实例化为本契约 adapter
10
11
  * - Gateway / Integration 按部署形态挂载具体 adapter
11
12
  */
12
- export {};
13
+ /**
14
+ * Channel labels owned by built-in adapters. Plugin contributions must not
15
+ * claim them. Reply routing looks up `channels.get(msg.channel)` — i.e. by the
16
+ * **message label**, not by adapter name: the built-in HttpChannelAdapter
17
+ * emits `channel: 'http'` (REST) and `channel: 'ws'` (WebSocket), so a plugin
18
+ * registering either label would intercept built-in replies and command
19
+ * short-replies.
20
+ */
21
+ export const BUILTIN_CHANNEL_IDS = ['http', 'ws'];
@@ -81,6 +81,18 @@ export declare class ClientToolRegistry {
81
81
  listProviders(sessionId: string, now?: number): ClientToolProvider[];
82
82
  /** 会话内是否有 live provider(tool 面过滤用) */
83
83
  hasLiveProvider(sessionId: string, name: ClientToolName, now?: number): boolean;
84
+ /**
85
+ * 快照枚举:live provider 覆盖的 (session, tool) 对。
86
+ * 可见性谓词数据化(ClientToolVisibilitySnapshot)的数据源;run 侧本地求值。
87
+ *
88
+ * @param toolNames - 关心的工具名(通常是已安装客户端工具全集)
89
+ * @param now - 可选时间点(测试用)
90
+ * @returns live 对列表
91
+ */
92
+ livePairs(toolNames: ClientToolName[], now?: number): Array<{
93
+ sessionId: string;
94
+ toolName: ClientToolName;
95
+ }>;
84
96
  /** 全局是否仍有任一 live provider(决定能否 uninstall) */
85
97
  hasAnyProvider(name: ClientToolName, now?: number): boolean;
86
98
  getDescriptor(sessionId: string, name: ClientToolName, now?: number): ClientToolDescriptor | undefined;
@@ -154,6 +154,31 @@ export class ClientToolRegistry {
154
154
  }
155
155
  return false;
156
156
  }
157
+ /**
158
+ * 快照枚举:live provider 覆盖的 (session, tool) 对。
159
+ * 可见性谓词数据化(ClientToolVisibilitySnapshot)的数据源;run 侧本地求值。
160
+ *
161
+ * @param toolNames - 关心的工具名(通常是已安装客户端工具全集)
162
+ * @param now - 可选时间点(测试用)
163
+ * @returns live 对列表
164
+ */
165
+ livePairs(toolNames, now) {
166
+ const ts = this.at(now);
167
+ this.expireStaleProviders(ts);
168
+ const wanted = new Set(toolNames);
169
+ const pairs = [];
170
+ for (const [sessionId, providers] of this.bySession) {
171
+ for (const p of providers.values()) {
172
+ if (!this.isLive(p, ts))
173
+ continue;
174
+ for (const d of p.descriptors) {
175
+ if (wanted.has(d.name))
176
+ pairs.push({ sessionId, toolName: d.name });
177
+ }
178
+ }
179
+ }
180
+ return pairs;
181
+ }
157
182
  /** 全局是否仍有任一 live provider(决定能否 uninstall) */
158
183
  hasAnyProvider(name, now) {
159
184
  const ts = this.at(now);
@@ -153,7 +153,34 @@ export function createBuiltinCommands(host) {
153
153
  };
154
154
  },
155
155
  };
156
- return [help, stop, newSession, model, status, issues];
156
+ const compact = {
157
+ name: 'compact',
158
+ description: 'Compress conversation context (during an active run: executes at the next message seam)',
159
+ usage: '/compact',
160
+ kind: 'control',
161
+ source: 'builtin',
162
+ risk: 'low',
163
+ // preempt =「run 在途可立即执行」(router 语义,默认仅 /stop):/compact 的主场景
164
+ // 恰是 run 进行中(方案 A),但它不中断 run——只提交压缩请求,由活跃 run 在下一个
165
+ // 消息缝执行。与 /stop 同为 run 在途控制命令。
166
+ preempt: true,
167
+ async execute(_ctx) {
168
+ return {
169
+ status: 'ok',
170
+ display: {
171
+ type: 'text',
172
+ // 结果播报由 op 执行后回填(gateway applySessionOps case 'compact')——
173
+ // 本条只在执行面缺席时兜底;不承诺时序(评审 del-d0830117 F8)
174
+ text: '🗜️ Compact requested.',
175
+ },
176
+ // 与压缩按钮同通道(SessionOp case 'compact'):run 进行中走 in-run 缝执行,
177
+ // 空闲走锁路径(方案 A,2026-11-20)
178
+ sessionOps: [{ op: 'compact' }],
179
+ effects: [{ kind: 'compact', summary: 'requested' }],
180
+ };
181
+ },
182
+ };
183
+ return [help, stop, newSession, model, status, issues, compact];
157
184
  }
158
185
  /** UI 本地命令目录项(执行仍在 Client,文案与 catalog 同源) */
159
186
  export function createClientCatalogCommand() {
@@ -7,6 +7,7 @@ export * from './plugins/index.js';
7
7
  export * from './tools/index.js';
8
8
  export * from './client-tools/index.js';
9
9
  export type { ChannelAdapter, ChannelMessage, ChannelReply } from './channel-types.js';
10
+ export { BUILTIN_CHANNEL_IDS } from './channel-types.js';
10
11
  export { DefaultSkillManager, FileSystemSkillSource } from './skills/manager.js';
11
12
  export type { SkillSource, DiscoveredSkill } from './skills/manager.js';
12
13
  export type { SkillDefinition, SkillManager } from './skills/types.js';
@@ -6,6 +6,7 @@
6
6
  export * from './plugins/index.js';
7
7
  export * from './tools/index.js';
8
8
  export * from './client-tools/index.js';
9
+ export { BUILTIN_CHANNEL_IDS } from './channel-types.js';
9
10
  export { DefaultSkillManager, FileSystemSkillSource } from './skills/manager.js';
10
11
  export * from './mcp/index.js';
11
12
  export * from './commands/index.js';
@@ -1,8 +1,12 @@
1
1
  /** Public author API. Runtime ownership lives in PluginContributionRegistry. */
2
+ import { CredentialStore } from '../../../governance/credentials/store.js';
2
3
  import { type ToolDefinition, type ToolHandler } from '@octopi-agent/core/types.js';
3
- import type { PluginHookName, PluginSessionOpName } from './manifest.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';
4
7
  import type { ExtensionHookHandler, HookEvent, HookResult, HookServiceRegistration, HookIterationTransform, HookVote } from '../hooks/types.js';
5
8
  import type { ArgSpec, CommandInvoker, CommandKind, CommandResult, CommandRisk } from '../commands/types.js';
9
+ import type { ModelProvider } from '@octopi-agent/core/interfaces/model-provider.js';
6
10
  export interface PluginCommandContext {
7
11
  sessionId: string;
8
12
  agentId: string;
@@ -14,6 +18,36 @@ export interface PluginCommandContext {
14
18
  tenantId?: string;
15
19
  };
16
20
  }
21
+ /**
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.
27
+ */
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
+ }
17
51
  export interface PluginCommandRegistration {
18
52
  name: string;
19
53
  description?: string;
@@ -50,6 +84,80 @@ export interface ToolRegistrationOptions {
50
84
  optional?: boolean;
51
85
  executionMode?: 'parallel' | 'sequential';
52
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'>;
95
+ }
96
+ /**
97
+ * Factory context: everything a plugin needs to build a Core ModelProvider for
98
+ * one `models.providers` config instance.
99
+ */
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>;
114
+ }
115
+ /**
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.
119
+ */
120
+ export type PluginProviderFactory = (context: PluginProviderFactoryContext) => ModelProvider | Promise<ModelProvider>;
121
+ export interface PluginProviderRegistration {
122
+ id: string;
123
+ factory: PluginProviderFactory;
124
+ }
125
+ /**
126
+ * Factory context: everything a plugin needs to build a Gateway ChannelAdapter
127
+ * for one `channels` config instance.
128
+ */
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
+ }
140
+ /**
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.
144
+ */
145
+ export type PluginChannelFactory = (context: PluginChannelFactoryContext) => PluginChannelAdapterLike | Promise<PluginChannelAdapterLike>;
146
+ /**
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.
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
+ }
53
161
  export interface HookRegistrationOptions {
54
162
  /** Required for the two dual-phase events; ordinary events must not set it. */
55
163
  phase?: 'transform' | 'vote';
@@ -76,6 +184,11 @@ export declare class PluginApi {
76
184
  readonly rootDir: string;
77
185
  readonly pluginConfig: Record<string, unknown>;
78
186
  readonly logger: PluginLogger;
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?;
79
192
  constructor(opts: {
80
193
  id: string;
81
194
  name: string;
@@ -84,7 +197,21 @@ export declare class PluginApi {
84
197
  source: string;
85
198
  rootDir: string;
86
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;
87
204
  });
205
+ /**
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.
210
+ */
211
+ get stateDir(): string;
212
+ /** Ensure the state directory exists with 0700. Called by stateDir consumers. */
213
+ ensureStateDir(): Promise<string>;
214
+ private getCredentialStore;
88
215
  /**
89
216
  * Stage a Tool contribution. It is not mounted or exposed by this call.
90
217
  *
@@ -107,6 +234,46 @@ export declare class PluginApi {
107
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;
108
235
  /** Stage a Host-owned background service; start/stop is driven by Gateway. */
109
236
  registerService(registration: HookServiceRegistration): void;
237
+ /**
238
+ * Stage a model Provider factory. The Host instantiates it when a
239
+ * `models.providers` entry references this id via its `plugin` field.
240
+ *
241
+ * @param id - Stable provider id (globally unique across plugins, like services)
242
+ * @param factory - Builds a Core ModelProvider for one config instance
243
+ */
244
+ registerProvider(id: string, factory: PluginProviderFactory): void;
245
+ /**
246
+ * Stage a Gateway channel factory. The Host instantiates it when a `channels`
247
+ * entry references this id via its `plugin` field.
248
+ *
249
+ * @param id - Stable channel id (globally unique across plugins, like providers)
250
+ * @param factory - Builds a ChannelAdapter for one channels config instance
251
+ */
252
+ registerChannel(id: string, factory: PluginChannelFactory): void;
253
+ /**
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).
262
+ *
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).
269
+ *
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
273
+ */
274
+ getContributionInstance(kind: 'provider', id: string): ModelProvider;
275
+ getContributionInstance(kind: 'channel', id: string): PluginChannelAdapterLike;
276
+ getContributionInstance(kind: ContributionInstanceKind, id: string): object;
110
277
  /**
111
278
  * Stage a Command contribution. Host authorization is enforced when mounted.
112
279
  *
@@ -1,9 +1,61 @@
1
1
  /** Public author API. Runtime ownership lives in PluginContributionRegistry. */
2
- import { resolve } from 'node:path';
2
+ import { resolve, join } from 'node:path';
3
+ import { mkdir } from 'node:fs/promises';
4
+ import { restrictToOwner } from '../../../../file-mode.js';
5
+ import { getOctopiHome } from '../../../../paths.js';
6
+ import { CredentialStore } from '../../../governance/credentials/store.js';
3
7
  import { TOOL_CAPABILITIES } from '@octopi-agent/core/types.js';
8
+ import { CONTRIBUTION_NAME_RE } from './manifest.js';
9
+ import { COMMAND_KIND, CHANNEL_KIND, HOOK_KIND, PROVIDER_KIND, SERVICE_KIND, TOOL_KIND, stageContribution } from './contribution-kinds.js';
10
+ import { createInstanceTable, readInstanceTable } from './contribution-instances.js';
4
11
  import { createStaging, readStaging } from './staging.js';
5
12
  import { normalizeCommandName } from '../commands/parse.js';
6
13
  import { COMMAND_INVOKERS } from '../commands/types.js';
14
+ const SECRET_KEY_RE = /^[A-Za-z0-9._-]+$/;
15
+ /** Vault-backed secrets scoped to one plugin (`plugin:<id>:<key>` namespace). */
16
+ function createPluginSecrets(pluginId, storeOf) {
17
+ const consumer = { kind: 'plugin', id: pluginId };
18
+ const nameOf = (key) => {
19
+ if (typeof key !== 'string' || !SECRET_KEY_RE.test(key)) {
20
+ throw new Error(`Plugin "${pluginId}" invalid secret key "${String(key)}": expected [A-Za-z0-9._-]+`);
21
+ }
22
+ return `plugin:${pluginId}:${key}`;
23
+ };
24
+ return {
25
+ async get(key) {
26
+ const store = await storeOf();
27
+ return store.reveal(nameOf(key), consumer);
28
+ },
29
+ async set(key, value) {
30
+ if (typeof value !== 'string' || value === '') {
31
+ throw new Error(`Plugin "${pluginId}" secret "${key}" value must be a non-empty string`);
32
+ }
33
+ const store = await storeOf();
34
+ const name = nameOf(key);
35
+ store.set({
36
+ name,
37
+ kind: 'api_key',
38
+ description: `plugin:${pluginId} secret`,
39
+ secretMode: 'encrypted',
40
+ secretValue: value,
41
+ scope: { level: 'plugin', key: pluginId },
42
+ });
43
+ // Own-or-revoke: a secret written here belongs to this plugin only —
44
+ // bindings left over from a hand-provisioned row are revoked so the
45
+ // "only resolvable consumer" claim cannot be silently falsified.
46
+ for (const bound of store.listBindings(name)) {
47
+ if (bound.kind !== 'plugin' || bound.id !== pluginId) {
48
+ store.unbind({ kind: bound.kind, id: bound.id }, name);
49
+ }
50
+ }
51
+ store.bind(consumer, name);
52
+ },
53
+ async delete(key) {
54
+ const store = await storeOf();
55
+ return store.delete(nameOf(key));
56
+ },
57
+ };
58
+ }
7
59
  export class PluginApi {
8
60
  id;
9
61
  name;
@@ -13,6 +65,11 @@ export class PluginApi {
13
65
  rootDir;
14
66
  pluginConfig;
15
67
  logger;
68
+ /** Per-plugin secret storage backed by the Host credentials vault. */
69
+ secrets;
70
+ stateDirPath;
71
+ credentialStore;
72
+ injectedCredentialStore;
16
73
  constructor(opts) {
17
74
  this.id = opts.id;
18
75
  this.name = opts.name;
@@ -21,7 +78,11 @@ export class PluginApi {
21
78
  this.source = opts.source;
22
79
  this.rootDir = opts.rootDir;
23
80
  this.pluginConfig = opts.pluginConfig;
81
+ this.stateDirPath = opts.stateDir ?? join(getOctopiHome(), 'plugin-state', opts.id);
82
+ this.injectedCredentialStore = opts.credentialStore;
83
+ this.secrets = createPluginSecrets(opts.id, () => this.getCredentialStore());
24
84
  createStaging(this);
85
+ createInstanceTable(this);
25
86
  const prefix = `[plugin:${opts.id}]`;
26
87
  this.logger = {
27
88
  debug: (message, ...args) => console.debug(`${prefix} ${message}`, ...args),
@@ -30,6 +91,37 @@ export class PluginApi {
30
91
  error: (message, ...args) => console.error(`${prefix} ${message}`, ...args),
31
92
  };
32
93
  }
94
+ /**
95
+ * Per-plugin private state directory (`OCTOPI_HOME/plugin-state/<id>`).
96
+ * Created on first access with mode 0700 (and tightened to 0700 when the
97
+ * directory already looser). Runtime state goes here — secrets go through
98
+ * {@link PluginApi.secrets}, never into files.
99
+ */
100
+ get stateDir() {
101
+ return this.stateDirPath;
102
+ }
103
+ /** Ensure the state directory exists with 0700. Called by stateDir consumers. */
104
+ async ensureStateDir() {
105
+ await mkdir(this.stateDirPath, { recursive: true, mode: 0o700 });
106
+ // mkdir's mode is masked by umask and does not tighten existing dirs.
107
+ // On Windows `chmod` neither takes effect nor throws (it only toggles the
108
+ // read-only flag), so the old `chmod` + catch below could never report a
109
+ // downgrade — the warning was dead code. Use the real restriction: POSIX
110
+ // chmod, Windows ACL (`icacls /inheritance:r /grant:r <user>`).
111
+ try {
112
+ restrictToOwner(this.stateDirPath, 'dir');
113
+ }
114
+ catch (error) {
115
+ // Degraded, explicit: a state dir that cannot be tightened is a real
116
+ // security downgrade, never a silent one.
117
+ this.logger.warn(`Plugin "${this.id}" stateDir ${this.stateDirPath}: cannot enforce mode 0700 (${String(error)}); state files rely on their own mode`);
118
+ }
119
+ return this.stateDirPath;
120
+ }
121
+ async getCredentialStore() {
122
+ this.credentialStore ??= this.injectedCredentialStore ?? (await CredentialStore.openDefault(getOctopiHome()));
123
+ return this.credentialStore;
124
+ }
33
125
  /**
34
126
  * Stage a Tool contribution. It is not mounted or exposed by this call.
35
127
  *
@@ -45,12 +137,9 @@ export class PluginApi {
45
137
  tool.capabilities.some((capability) => !TOOL_CAPABILITIES.includes(capability))) {
46
138
  throw new Error(`Plugin tool "${tool.name}" has unknown or duplicate capabilities`);
47
139
  }
48
- if (readStaging(this).tools.some((entry) => entry.definition.name === tool.name)) {
49
- throw new Error(`Plugin "${this.id}" registered duplicate tool "${tool.name}"`);
50
- }
51
140
  const executionMode = opts?.executionMode ??
52
141
  (tool.capabilities.includes('fs-write') ? 'sequential' : undefined);
53
- readStaging(this).tools.push({
142
+ stageContribution(this.id, TOOL_KIND, readStaging(this), {
54
143
  definition: tool,
55
144
  handler,
56
145
  optional: opts?.optional ?? false,
@@ -83,9 +172,7 @@ export class PluginApi {
83
172
  priority: opts?.priority ?? 0,
84
173
  ...(opts?.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
85
174
  };
86
- const entries = [...(readStaging(this).hooks.get(hookName) ?? []), entry];
87
- entries.sort((a, b) => b.priority - a.priority);
88
- readStaging(this).hooks.set(hookName, entries);
175
+ stageContribution(this.id, HOOK_KIND, readStaging(this), entry);
89
176
  }
90
177
  /** Register a parameter Transform or admission Vote for before_tool_call. */
91
178
  onBeforeToolCall(phase, handler, opts) {
@@ -97,13 +184,69 @@ export class PluginApi {
97
184
  }
98
185
  /** Stage a Host-owned background service; start/stop is driven by Gateway. */
99
186
  registerService(registration) {
100
- if (!registration.serviceId.trim() || readStaging(this).services.some((item) => item.serviceId === registration.serviceId)) {
101
- throw new Error(`Plugin "${this.id}" registered an empty or duplicate service id`);
187
+ if (!registration.serviceId.trim()) {
188
+ throw new Error(`Plugin "${this.id}" registered an empty service id`);
102
189
  }
103
190
  if (registration.timeoutMs !== undefined && (!Number.isFinite(registration.timeoutMs) || registration.timeoutMs <= 0)) {
104
191
  throw new Error(`Plugin "${this.id}" registered an invalid service timeout`);
105
192
  }
106
- readStaging(this).services.push({ ...registration });
193
+ stageContribution(this.id, SERVICE_KIND, readStaging(this), { ...registration });
194
+ }
195
+ /**
196
+ * Stage a model Provider factory. The Host instantiates it when a
197
+ * `models.providers` entry references this id via its `plugin` field.
198
+ *
199
+ * @param id - Stable provider id (globally unique across plugins, like services)
200
+ * @param factory - Builds a Core ModelProvider for one config instance
201
+ */
202
+ registerProvider(id, factory) {
203
+ const normalized = id.trim();
204
+ if (!CONTRIBUTION_NAME_RE.test(normalized) || typeof factory !== 'function') {
205
+ throw new Error(`Plugin "${this.id}" registered an invalid provider contribution "${id}"`);
206
+ }
207
+ stageContribution(this.id, PROVIDER_KIND, readStaging(this), { id: normalized, factory });
208
+ }
209
+ /**
210
+ * Stage a Gateway channel factory. The Host instantiates it when a `channels`
211
+ * entry references this id via its `plugin` field.
212
+ *
213
+ * @param id - Stable channel id (globally unique across plugins, like providers)
214
+ * @param factory - Builds a ChannelAdapter for one channels config instance
215
+ */
216
+ registerChannel(id, factory) {
217
+ const normalized = id.trim();
218
+ if (!CONTRIBUTION_NAME_RE.test(normalized) || typeof factory !== 'function') {
219
+ throw new Error(`Plugin "${this.id}" registered an invalid channel contribution "${id}"`);
220
+ }
221
+ stageContribution(this.id, CHANNEL_KIND, readStaging(this), { id: normalized, factory });
222
+ }
223
+ getContributionInstance(kind, id) {
224
+ if (kind !== 'provider' && kind !== 'channel') {
225
+ throw new Error(`Plugin "${this.id}" cannot look up instances of kind "${String(kind)}": expected "provider" or "channel"`);
226
+ }
227
+ if (typeof id !== 'string') {
228
+ throw new Error(`Plugin "${this.id}" cannot look up ${kind} instance "${String(id)}": id must be a string`);
229
+ }
230
+ const key = id.trim();
231
+ const staging = readStaging(this);
232
+ const owns = kind === 'provider'
233
+ ? staging.providers.some((entry) => entry.id === key)
234
+ : staging.channels.some((entry) => entry.id === key);
235
+ if (!owns) {
236
+ throw new Error(`Plugin "${this.id}" cannot look up ${kind} "${key}": not a contribution of this plugin`);
237
+ }
238
+ const entries = readInstanceTable(this).find(kind, key);
239
+ const live = entries.filter((entry) => entry.state === 'live');
240
+ if (live.length === 1)
241
+ return live[0].instance;
242
+ if (live.length > 1) {
243
+ const labels = live.map((entry) => `"${entry.label}"`).join(', ');
244
+ throw new Error(`Plugin "${this.id}" ${kind} "${key}" has ${live.length} live instances (${labels}): getContributionInstance requires exactly one`);
245
+ }
246
+ if (entries.length > 0) {
247
+ throw new Error(`Plugin "${this.id}" ${kind} "${key}" has no live instance (its instance was retired)`);
248
+ }
249
+ throw new Error(`Plugin "${this.id}" ${kind} "${key}" has no live instance (the Host has not instantiated it)`);
107
250
  }
108
251
  /**
109
252
  * Stage a Command contribution. Host authorization is enforced when mounted.
@@ -122,10 +265,8 @@ export class PluginApi {
122
265
  definition.invocableBy.some((invoker) => !COMMAND_INVOKERS.includes(invoker)))) {
123
266
  throw new Error(`Plugin "${this.id}" registered invalid invocableBy for command "${name}"`);
124
267
  }
125
- if (readStaging(this).commands.some((entry) => entry.name === name)) {
126
- throw new Error(`Plugin "${this.id}" registered duplicate command "${definition.name}"`);
127
- }
128
- readStaging(this).commands.push({ ...definition, name });
268
+ const staging = readStaging(this);
269
+ stageContribution(this.id, COMMAND_KIND, staging, { ...definition, name });
129
270
  }
130
271
  /**
131
272
  * Resolve a path relative to the plugin root in ESM.