@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,83 @@
1
+ /**
2
+ * Onboarding 落盘/播种/探针 — engine 侧动作面(评审 M2 抽取)。
3
+ *
4
+ * CLI 与 Web 向导的动作完全同源:渲染器只采集 choices,落盘(.env + 配置)、
5
+ * 部署模式播种、连接探针都从本模块走。整文件 schema 校验由调用方注入
6
+ * (deps.validateConfig)——完整 octopi.json 的 compose schema 在套件层,
7
+ * engine 不反向依赖 gateway/webui 片段。
8
+ *
9
+ * @module
10
+ */
11
+ import type { OnboardingChoices, OnboardingOutput } from './onboarding.js';
12
+ import { type ProbeErrorKind } from './error-copy.js';
13
+ /**
14
+ * 探针错误归并(§5 映射)。
15
+ * 分类实现单源在 `error-copy.ts`(probe 语境无 'context',出现时归 'server')。
16
+ */
17
+ export declare function classifyProbeError(err: Error): ProbeErrorKind;
18
+ /** 写一行 .env(0600;同名替换、异名追加) */
19
+ export declare function writeEnvLine(octopiHome: string, line: string): void;
20
+ /**
21
+ * 合入 octopi.json(B3 全接线 + M15 落盘前 schema 校验 + m6 entry 级合并)。
22
+ *
23
+ * @param configPath - 目标配置文件
24
+ * @param output - 向导产出
25
+ * @param validateConfig - 整文件 schema 校验器(fail-loud;套件层注入 compose schema)
26
+ * @throws 合并结果未过校验(不写坏文件)
27
+ */
28
+ export declare function mergeConfigFragment(configPath: string, output: OnboardingOutput, validateConfig: (raw: Record<string, unknown>) => void): void;
29
+ /**
30
+ * 部署模式播种(§4):①default 自助面(tenant/user id = 'default',DEFAULT_TENANT_ID 语义,M11);
31
+ * ②③组织 + admin(带密码)。幂等;撞名(他域已有同名 admin)fail-loud 且给出可执行出路(M10)。
32
+ *
33
+ * @param octopiHome - OCTOPI_HOME(registry.db 所在)
34
+ * @param choices - 向导选择
35
+ * @param opts - 播种选项(adminName 覆盖,默认 admin / OCTOPI_ADMIN_NAME)
36
+ * @throws 模式②③无密码、或 admin 名被其他组织占用
37
+ */
38
+ export declare function seedDeploymentRegistry(octopiHome: string, choices: OnboardingChoices, opts?: {
39
+ adminName?: string;
40
+ }): Promise<void>;
41
+ /**
42
+ * 探针(§5 测通内核):expandEnvValues 展开后建 provider 做一次可用性检查(B1)。
43
+ *
44
+ * @param choices - 当前选择
45
+ * @returns 'ok' 或错误归并(ProbeErrorKind 七类码)
46
+ */
47
+ export declare function probeProvider(choices: OnboardingChoices): Promise<'ok' | ProbeErrorKind>;
48
+ /**
49
+ * 配置里是否绑定非本机地址(M12:personal 远程绑定强制设密码的判定)
50
+ *
51
+ * @param configPath - 配置文件路径
52
+ * @returns web/channels 任一 host 为 lan/0.0.0.0 时 true
53
+ */
54
+ export declare function isRemoteBind(configPath: string): boolean;
55
+ /**
56
+ * 该部署形态是否需要 admin 密码(UI 据此决定是否显示密码输入)。
57
+ *
58
+ * 判据与服务端强制点保持一致:②③模式必填;个人模式**仅当远程绑定**时必填
59
+ * (`applyOnboarding` 的 onboarding_password_required)。此前 UI 只按「模式」判断,
60
+ * 导致个人+远程绑定时界面没有密码框、提交才被拒——用户无从修正。
61
+ *
62
+ * @param deploymentMode - 所选部署模式
63
+ * @param configPath - 配置文件路径(判定远程绑定)
64
+ * @returns 是否需要密码
65
+ */
66
+ export declare function requiresAdminPassword(deploymentMode: string, configPath: string): boolean;
67
+ /** applyOnboarding 依赖(渲染器/宿主注入;测试可替换) */
68
+ export interface ApplyOnboardingDeps {
69
+ configPath: string;
70
+ octopiHome: string;
71
+ /** 管理员名(默认 admin;撞名时的可执行出路,M10) */
72
+ adminName?: string;
73
+ /** 整文件 schema 校验器(fail-loud;套件层注入 compose schema,engine 不反向依赖) */
74
+ validateConfig: (raw: Record<string, unknown>) => void;
75
+ }
76
+ /**
77
+ * 一次性落盘 + 播种(commit 点统一入口——B2 顺序:.env → 配置 → 播种)。
78
+ *
79
+ * @param choices - 完整选择(须先过 validateStep 全链)
80
+ * @param deps - 动作依赖
81
+ * @throws 组装失败 / 校验失败 / 播种撞名(fail-loud,不产半截配置)
82
+ */
83
+ export declare function applyOnboarding(choices: OnboardingChoices, deps: ApplyOnboardingDeps): Promise<void>;
@@ -0,0 +1,259 @@
1
+ /**
2
+ * Onboarding 落盘/播种/探针 — engine 侧动作面(评审 M2 抽取)。
3
+ *
4
+ * CLI 与 Web 向导的动作完全同源:渲染器只采集 choices,落盘(.env + 配置)、
5
+ * 部署模式播种、连接探针都从本模块走。整文件 schema 校验由调用方注入
6
+ * (deps.validateConfig)——完整 octopi.json 的 compose schema 在套件层,
7
+ * engine 不反向依赖 gateway/webui 片段。
8
+ *
9
+ * @module
10
+ */
11
+ import { readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
12
+ import { restrictToOwner } from '../file-mode.js';
13
+ import { join } from 'node:path';
14
+ import { apiKeyEnvVar, assembleOnboarding } from './onboarding.js';
15
+ import { MIN_ADMIN_PASSWORD_LENGTH, checkAdminPassword } from './password-policy.js';
16
+ import { expandEnvValues } from './env.js';
17
+ import { classifyErrorKind } from './error-copy.js';
18
+ import { createProviderFromConfig } from '../config.js';
19
+ /**
20
+ * 探针错误归并(§5 映射)。
21
+ * 分类实现单源在 `error-copy.ts`(probe 语境无 'context',出现时归 'server')。
22
+ */
23
+ export function classifyProbeError(err) {
24
+ const kind = classifyErrorKind(err.message);
25
+ return kind === 'context' ? 'server' : kind;
26
+ }
27
+ /** 写一行 .env(0600;同名替换、异名追加) */
28
+ export function writeEnvLine(octopiHome, line) {
29
+ const envPath = join(octopiHome, '.env');
30
+ // MINOR-3:容忍 `export KEY=…` 声明形;无 `=` fail-loud(此前静默截断成坏键)
31
+ const normalized = line.trim().replace(/^export\s+/, '');
32
+ const eq = normalized.indexOf('=');
33
+ if (eq <= 0)
34
+ throw new Error(`writeEnvLine_invalid: 需要 KEY=VALUE 形式(收到:${normalized.slice(0, 20)}…)`);
35
+ const key = normalized.slice(0, eq);
36
+ let content = '';
37
+ try {
38
+ content = readFileSync(envPath, 'utf8');
39
+ }
40
+ catch {
41
+ // 无 .env:新建(下方 mode 0600 生效)
42
+ }
43
+ const lines = content.split('\n').filter((l) => l.trim() !== '');
44
+ const idx = lines.findIndex((l) => l.trim().replace(/^export\s+/, '').startsWith(`${key}=`));
45
+ if (idx >= 0)
46
+ lines[idx] = normalized;
47
+ else
48
+ lines.push(normalized);
49
+ // 先写临时文件再 rename:避免半截 .env + 避免 umask 窗口暴露明文 key
50
+ const tmp = `${envPath}.tmp`;
51
+ writeFileSync(tmp, lines.join('\n') + '\n', { mode: 0o600 });
52
+ // `.env` 含 provider apiKey:`mode` 在 Windows 上不生效,必须真实收紧 ACL;
53
+ // 收紧失败则删掉临时文件并抛错(不把明文 key 留在已知不安全的权限下)。
54
+ try {
55
+ restrictToOwner(tmp, 'file');
56
+ }
57
+ catch (err) {
58
+ try {
59
+ rmSync(tmp, { force: true });
60
+ }
61
+ catch {
62
+ /* 删不掉时仍抛出收紧失败:调用方不能误以为 key 已安全落盘 */
63
+ }
64
+ throw err;
65
+ }
66
+ renameSync(tmp, envPath);
67
+ // 同步进程 env(评审 B3):热应用 applyFromDisk 经 expandEnvValues 读 process.env——
68
+ // 只写盘不进进程会用空/旧 key 重建 provider。向导显式写入的值即用户意图,立即生效。
69
+ process.env[key] = normalized.slice(eq + 1);
70
+ }
71
+ /**
72
+ * 合入 octopi.json(B3 全接线 + M15 落盘前 schema 校验 + m6 entry 级合并)。
73
+ *
74
+ * @param configPath - 目标配置文件
75
+ * @param output - 向导产出
76
+ * @param validateConfig - 整文件 schema 校验器(fail-loud;套件层注入 compose schema)
77
+ * @throws 合并结果未过校验(不写坏文件)
78
+ */
79
+ export function mergeConfigFragment(configPath, output, validateConfig) {
80
+ let raw = {};
81
+ try {
82
+ raw = JSON.parse(readFileSync(configPath, 'utf8'));
83
+ }
84
+ catch (e) {
85
+ // B-4:只吞「文件不存在」(首启由向导创建);语法错/权限错必须抛——否则损坏配置会被空对象覆盖丢失
86
+ if (e.code !== 'ENOENT')
87
+ throw e;
88
+ }
89
+ const models = { ...(raw.models ?? {}) };
90
+ const providers = { ...(models.providers ?? {}) };
91
+ for (const [name, cfg] of Object.entries(output.configFragment.providers)) {
92
+ // entry 级合并:向导拥有 baseUrl/apiKey/models,既有 timeoutSeconds/options 保留(m6)
93
+ providers[name] = { ...(providers[name] ?? {}), ...cfg };
94
+ }
95
+ models.providers = providers;
96
+ // B3:档位与 agent model 接线到所选 provider/model
97
+ // M-10:档位 entry 级合并(整档替换会丢 fallbacks 等既有字段)
98
+ const levels = (models.level ?? {});
99
+ for (const [k, v] of Object.entries(output.configFragment.levels)) {
100
+ levels[k] = { ...(levels[k] ?? {}), ...v };
101
+ }
102
+ models.level = levels;
103
+ raw.models = models;
104
+ // M-10:只给 default agent 指模型(此前打平全部 agent 的 model——多 agent 配置被静默改写)
105
+ if (Array.isArray(raw.agents)) {
106
+ raw.agents = raw.agents.map((a) => a && typeof a === 'object' && (a.id === 'default' || a.id === undefined)
107
+ ? { ...a, model: output.configFragment.agentModel }
108
+ : a);
109
+ }
110
+ raw.language = output.configFragment.language;
111
+ raw.deploymentMode = output.configFragment.deploymentMode;
112
+ // M15:落盘前 schema 校验 fail-loud(坏配置留在盘上比不落盘更难查)
113
+ validateConfig(raw);
114
+ writeFileSync(configPath, JSON.stringify(raw, null, 2) + '\n', 'utf8');
115
+ }
116
+ /**
117
+ * 部署模式播种(§4):①default 自助面(tenant/user id = 'default',DEFAULT_TENANT_ID 语义,M11);
118
+ * ②③组织 + admin(带密码)。幂等;撞名(他域已有同名 admin)fail-loud 且给出可执行出路(M10)。
119
+ *
120
+ * @param octopiHome - OCTOPI_HOME(registry.db 所在)
121
+ * @param choices - 向导选择
122
+ * @param opts - 播种选项(adminName 覆盖,默认 admin / OCTOPI_ADMIN_NAME)
123
+ * @throws 模式②③无密码、或 admin 名被其他组织占用
124
+ */
125
+ export async function seedDeploymentRegistry(octopiHome, choices, opts) {
126
+ const { RegistryService } = await import('../harness/governance/registry/service.js');
127
+ const registry = await RegistryService.create({ dbPath: join(octopiHome, 'registry.db') });
128
+ try {
129
+ const adminName = opts?.adminName ?? process.env.OCTOPI_ADMIN_NAME ?? 'admin';
130
+ if (choices.deploymentMode === 'personal') {
131
+ // M11:显式 'default' 租户/用户(与 core DEFAULT_TENANT_ID 同一 ID 空间)
132
+ const tenant = registry.ensureTenant('default', 'default');
133
+ const existing = registry.getUserInTenant(tenant.tenantId, 'default');
134
+ if (!existing)
135
+ await registry.createUserInTenant({ tenantId: tenant.tenantId, name: 'default', isPlatformAdmin: true });
136
+ // M12:personal 远程绑定强制设密码(收进来的 adminPassword 即 default 用户密码)
137
+ if (choices.adminPassword)
138
+ await registry.setUserPassword((registry.getUserInTenant(tenant.tenantId, 'default')).userId, choices.adminPassword);
139
+ return;
140
+ }
141
+ const tenantName = choices.deploymentMode === 'multi-organization' ? (choices.orgName ?? 'default') : 'default';
142
+ const tenant = registry.ensureTenant(tenantName, tenantName === 'default' ? 'default' : undefined);
143
+ const badPw = checkAdminPassword(choices.adminPassword);
144
+ if (badPw === 'required')
145
+ throw new Error('onboarding_admin_password_required: ②③模式 admin 必须设密码');
146
+ if (badPw === 'too_short') {
147
+ throw new Error(`onboarding_admin_password_too_short: admin 密码至少 ${MIN_ADMIN_PASSWORD_LENGTH} 位`);
148
+ }
149
+ // 过了上面两道 = 非空且够长;显式收窄,避免后续把 string|undefined 传给 setUserPassword
150
+ const adminPassword = (choices.adminPassword ?? '').trim();
151
+ const existing = registry.getUserInTenant(tenant.tenantId, adminName);
152
+ if (existing) {
153
+ await registry.setUserPassword(existing.userId, adminPassword);
154
+ return;
155
+ }
156
+ const elsewhere = registry.getUserByName(adminName);
157
+ if (elsewhere && elsewhere.tenantId !== tenant.tenantId) {
158
+ // M10:绝不跨租户覆写密码;给出可执行出路
159
+ throw new Error(`registry_admin_name_taken: 用户名 ${adminName} 已被其他组织占用——重跑并指定 OCTOPI_ADMIN_NAME=<其他名字>`);
160
+ }
161
+ await registry.createUserInTenant({
162
+ tenantId: tenant.tenantId,
163
+ name: adminName,
164
+ password: choices.adminPassword,
165
+ isPlatformAdmin: true,
166
+ });
167
+ }
168
+ finally {
169
+ registry.close();
170
+ }
171
+ }
172
+ /**
173
+ * 探针(§5 测通内核):expandEnvValues 展开后建 provider 做一次可用性检查(B1)。
174
+ *
175
+ * @param choices - 当前选择
176
+ * @returns 'ok' 或错误归并(ProbeErrorKind 七类码)
177
+ */
178
+ export async function probeProvider(choices) {
179
+ const envVar = apiKeyEnvVar(choices.providerId);
180
+ const prevEnv = envVar ? process.env[envVar] : undefined;
181
+ try {
182
+ if (envVar && choices.apiKey)
183
+ process.env[envVar] = choices.apiKey.trim();
184
+ const { configFragment } = assembleOnboarding(choices);
185
+ // B1:createProviderFromConfig 不做 env 展开——必须先展开,否则 ${VAR} 字面量进 Authorization 头恒 401
186
+ const providerCfg = expandEnvValues(Object.values(configFragment.providers)[0]);
187
+ try {
188
+ const provider = await createProviderFromConfig(choices.providerId, providerCfg, {});
189
+ const ok = await provider.isAvailable();
190
+ return ok ? 'ok' : 'server';
191
+ }
192
+ catch (err) {
193
+ return classifyProbeError(err instanceof Error ? err : new Error(String(err)));
194
+ }
195
+ }
196
+ finally {
197
+ // M-1:探针只借用 env——长驻 daemon 不得残留密钥(tool 子进程默认继承 process.env)
198
+ if (envVar) {
199
+ if (prevEnv === undefined)
200
+ delete process.env[envVar];
201
+ else
202
+ process.env[envVar] = prevEnv;
203
+ }
204
+ }
205
+ }
206
+ /**
207
+ * 配置里是否绑定非本机地址(M12:personal 远程绑定强制设密码的判定)
208
+ *
209
+ * @param configPath - 配置文件路径
210
+ * @returns web/channels 任一 host 为 lan/0.0.0.0 时 true
211
+ */
212
+ export function isRemoteBind(configPath) {
213
+ try {
214
+ const raw = JSON.parse(readFileSync(configPath, 'utf8'));
215
+ const hosts = [raw.web?.host, ...(raw.channels ?? []).map((c) => c.host)];
216
+ return hosts.some((h) => h === 'lan' || h === '0.0.0.0');
217
+ }
218
+ catch {
219
+ // 配置缺失/不可读 = 无从判定远程绑定;按「本机」处理(不是错误路径:首启时配置可能刚脚手架)
220
+ return false;
221
+ }
222
+ }
223
+ /**
224
+ * 该部署形态是否需要 admin 密码(UI 据此决定是否显示密码输入)。
225
+ *
226
+ * 判据与服务端强制点保持一致:②③模式必填;个人模式**仅当远程绑定**时必填
227
+ * (`applyOnboarding` 的 onboarding_password_required)。此前 UI 只按「模式」判断,
228
+ * 导致个人+远程绑定时界面没有密码框、提交才被拒——用户无从修正。
229
+ *
230
+ * @param deploymentMode - 所选部署模式
231
+ * @param configPath - 配置文件路径(判定远程绑定)
232
+ * @returns 是否需要密码
233
+ */
234
+ export function requiresAdminPassword(deploymentMode, configPath) {
235
+ if (deploymentMode !== 'personal')
236
+ return true;
237
+ return isRemoteBind(configPath);
238
+ }
239
+ /**
240
+ * 一次性落盘 + 播种(commit 点统一入口——B2 顺序:.env → 配置 → 播种)。
241
+ *
242
+ * @param choices - 完整选择(须先过 validateStep 全链)
243
+ * @param deps - 动作依赖
244
+ * @throws 组装失败 / 校验失败 / 播种撞名(fail-loud,不产半截配置)
245
+ */
246
+ export async function applyOnboarding(choices, deps) {
247
+ // M-4:个人模式 + 远程绑定 = 裸奔,强制设密码(M12 服务端 enforce——CLI/Web 同受,此前只在 CLI 渲染层)
248
+ if (choices.deploymentMode === 'personal' &&
249
+ isRemoteBind(deps.configPath) &&
250
+ !String(choices.adminPassword ?? '').trim()) {
251
+ throw new Error('onboarding_password_required: 远程可访问的个人部署必须设置密码(否则任何人可直接使用)');
252
+ }
253
+ const output = assembleOnboarding(choices);
254
+ for (const line of output.envLines)
255
+ writeEnvLine(deps.octopiHome, line);
256
+ mergeConfigFragment(deps.configPath, output, deps.validateConfig);
257
+ // registry 播种是主成果(fail-loud)
258
+ await seedDeploymentRegistry(deps.octopiHome, choices, deps);
259
+ }
@@ -0,0 +1,160 @@
1
+ /**
2
+ * Onboarding 向导核心 — 单源状态机 / 双语文案表 / 配置组装(纯逻辑无 IO)。
3
+ *
4
+ * CLI 与 Web 向导共享本模块(product-onboarding.md §1):渲染器只做呈现,
5
+ * 步骤序、校验、落盘内容都在这里。生成器语义:产出与手写 octopi.json 同构。
6
+ *
7
+ * @module
8
+ */
9
+ import type { ProductLang, LocalizedText } from './i18n.js';
10
+ /** 向导步骤 id(product-onboarding.md §3 九步) */
11
+ export type OnboardingStepId = 'welcome' | 'init-mode' | 'deployment-mode' | 'provider' | 'api-key' | 'model' | 'probe' | 'services' | 'first-chat';
12
+ /** 步骤序(`init-mode` 仅在 Web 向导可用时呈现——CLI 先行期只有命令行一条道) */
13
+ export declare const ONBOARDING_STEPS: readonly OnboardingStepId[];
14
+ /** 初始化方式 */
15
+ export type InitMode = 'cli' | 'web';
16
+ /** 部署模式(§4) */
17
+ export type DeploymentMode = 'personal' | 'organization' | 'multi-organization';
18
+ /** 部署模式三选的产品描述 */
19
+ export interface DeploymentModeChoice {
20
+ id: DeploymentMode;
21
+ labels: LocalizedText;
22
+ descriptions: LocalizedText;
23
+ }
24
+ /** 部署模式选项(顺序即展示序) */
25
+ export declare const DEPLOYMENT_MODES: readonly DeploymentModeChoice[];
26
+ /** 向导收集的选择(渲染器逐步填充) */
27
+ export interface OnboardingChoices {
28
+ lang: ProductLang;
29
+ initMode: InitMode;
30
+ deploymentMode: DeploymentMode;
31
+ /** 模式②③的 admin 密码(明文仅存于内存,落盘即 scrypt,不进配置) */
32
+ adminPassword?: string;
33
+ /** 模式③的首个组织名(tenant 名) */
34
+ orgName?: string;
35
+ providerId: string;
36
+ /** 表单覆盖(baseUrl 等;apiKey 单独走 apiKey 字段) */
37
+ providerOverrides?: Record<string, unknown>;
38
+ /** LLM key 明文(写 .env 用,不进 octopi.json) */
39
+ apiKey?: string;
40
+ modelId: string;
41
+ }
42
+ /** 向导产出:配置片段 + .env 行 + 服务动作提示(渲染器负责执行落盘) */
43
+ export interface OnboardingOutput {
44
+ /** 合入 octopi.json 的片段(与手写配置同构) */
45
+ configFragment: {
46
+ language: ProductLang;
47
+ deploymentMode: DeploymentMode;
48
+ providers: Record<string, unknown>;
49
+ /** 模型档位接线(B3):三档都指向所选 provider/model(merge 时与既有 level 合并) */
50
+ levels: Record<string, {
51
+ primary: string;
52
+ }>;
53
+ /** default agent 应指向的 model 引用(`<provider>/<model>`;merge 时改写 agents) */
54
+ agentModel: string;
55
+ };
56
+ /** 写入 OCTOPI_HOME/.env 的行(KEY=VALUE;空 = 无需 key) */
57
+ envLines: string[];
58
+ }
59
+ /**
60
+ * 取当前语言的双语文案(与 pickLocalized 同源,保留本名给向导渲染器)
61
+ *
62
+ * @param map - 双语映射
63
+ * @param fallback - 回落文案
64
+ * @param lang - 当前语言
65
+ * @returns 本地化文案
66
+ */
67
+ export declare function pickLang(map: LocalizedText, fallback: string, lang: ProductLang): string;
68
+ /**
69
+ * 预设的 apiKey 环境变量名(.env 键 + `${VAR}` 占位同名)
70
+ *
71
+ * @param providerId - 预设 id
72
+ * @returns 环境变量名;无需 key 的预设(ollama 等)返回 ''
73
+ * @throws 未知 providerId(fail-loud)
74
+ */
75
+ export declare function apiKeyEnvVar(providerId: string): string;
76
+ /**
77
+ * 校验一步的选择是否完整(渲染器在「下一步」前调用)
78
+ *
79
+ * @param step - 步骤 id
80
+ * @param choices - 当前选择
81
+ * @returns 错误文案(当前语言);'' 表示通过
82
+ */
83
+ export declare function validateStep(step: OnboardingStepId, choices: OnboardingChoices): string;
84
+ /**
85
+ * 组装落盘内容(生成器语义:与手写 octopi.json 完全同构)
86
+ *
87
+ * @param choices - 完整选择(须先过 validateStep 全链)
88
+ * @returns 配置片段 + .env 行
89
+ * @throws provider 未知或 apiKey 缺失时抛错(fail-loud,不产半截配置)
90
+ */
91
+ export declare function assembleOnboarding(choices: OnboardingChoices): OnboardingOutput;
92
+ /**
93
+ * 列出可选 provider 预设(渲染器用)
94
+ *
95
+ * @returns 预设清单(只读)
96
+ */
97
+ export declare function providerChoices(): readonly import('./model-presets.js').ProviderPreset[];
98
+ export declare function mergeOnboardingChoices(base: OnboardingChoices, patch: Partial<OnboardingChoices>, opts?: {
99
+ /**
100
+ * 该部署形态是否要求 admin 密码(由调用方按模式 + 是否远程绑定判定)。
101
+ * 缺省 false = 按「不需要密码」清理残留值。
102
+ */
103
+ adminPasswordRequired?: boolean;
104
+ }): OnboardingChoices;
105
+ /** 向导状态机状态(渲染器逐步推进;纯数据可序列化——Web 侧可跨请求存放) */
106
+ export interface OnboardingMachineState {
107
+ /** 当前步骤;null = 结束(completed / aborted / exit) */
108
+ current: OnboardingStepId | null;
109
+ /** 回退栈(已走过的步骤) */
110
+ stack: OnboardingStepId[];
111
+ /** 正常走完全部步骤 */
112
+ completed: boolean;
113
+ /** EOF/输入断流而中止(半截状态不组装——批 1 EOF 尾巴) */
114
+ aborted: boolean;
115
+ /** 用户选择「保存并退出」(m5:文案=行为) */
116
+ exitSave: boolean;
117
+ }
118
+ /** 状态机事件(渲染器把用户动作翻译成事件) */
119
+ export type OnboardingEvent = {
120
+ kind: 'next';
121
+ } | {
122
+ kind: 'back';
123
+ } | {
124
+ kind: 'goto';
125
+ step: OnboardingStepId;
126
+ } | {
127
+ kind: 'exit';
128
+ save: boolean;
129
+ } | {
130
+ kind: 'eof';
131
+ };
132
+ /**
133
+ * commit 时机标记(渲染器据此调 applyOnboarding):
134
+ * - `after-probe`:测通通过、services 动作之前(B2——spawn 出的进程读盘才拿得到新配置)
135
+ * - `on-exit-save`:用户选「保存并退出」(m5)
136
+ * - `on-done`:正常走完(防御落盘,仅限完整状态)
137
+ */
138
+ export type OnboardingCommit = 'none' | 'after-probe' | 'on-exit-save' | 'on-done';
139
+ /** 转移结果 */
140
+ export interface OnboardingTransition {
141
+ state: OnboardingMachineState;
142
+ commit: OnboardingCommit;
143
+ /** 提示类反馈(渲染器本地化呈现) */
144
+ notice?: 'back-at-first';
145
+ }
146
+ /**
147
+ * 初始状态
148
+ *
149
+ * @param start - 起始步骤(默认 welcome)
150
+ * @returns 全新状态机状态
151
+ */
152
+ export declare function initialOnboardingState(start?: OnboardingStepId): OnboardingMachineState;
153
+ /**
154
+ * 纯转移函数(M2 核心):无 IO、无渲染,Web/CLI 唯一步骤图真相。
155
+ *
156
+ * @param state - 当前状态
157
+ * @param event - 事件
158
+ * @returns 转移后状态 + commit 时机
159
+ */
160
+ export declare function nextStep(state: OnboardingMachineState, event: OnboardingEvent): OnboardingTransition;