@bitkyc08/opencodex 2.100.2 → 2.100.4

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 (644) hide show
  1. package/AGENTS_INSTALL.md +23 -1
  2. package/README.md +1 -1
  3. package/bin/ocx.mjs +40 -19
  4. package/gui/dist/assets/{App-COo8Yopd.css → App-BGP8I0V4.css} +1 -1
  5. package/gui/dist/assets/App-DcpyI78f.js +60 -0
  6. package/gui/dist/assets/{Tray-BcaI-VCr.js → Tray-CzjPJprT.js} +1 -1
  7. package/gui/dist/assets/brand-mark-BTIi7e69.js +1 -0
  8. package/gui/dist/assets/index-DJxM-imn.css +2 -0
  9. package/gui/dist/assets/index-DVgU6S3y.js +138 -0
  10. package/gui/dist/assets/{segment-thumb-features-e9A_FogJ.js → segment-thumb-features-Bn6Y-g3R.js} +1 -1
  11. package/gui/dist/classic/assets/App-eYJAyNHM.js +59 -0
  12. package/gui/dist/classic/assets/{Tray-DT146AhS.js → Tray-xHMYxLkV.js} +1 -1
  13. package/gui/dist/classic/assets/index-DSaVRW4F.js +138 -0
  14. package/gui/dist/classic/assets/quota-summary-DyzHlkFl.js +1 -0
  15. package/gui/dist/classic/index.html +1 -1
  16. package/gui/dist/index.html +2 -2
  17. package/native/ocx-child/Cargo.toml +9 -0
  18. package/native/ocx-child/src/cli.rs +404 -20
  19. package/native/ocx-child/src/codex_home.rs +99 -14
  20. package/native/ocx-child/src/daemon.rs +2 -1
  21. package/native/ocx-child/src/lib.rs +3 -0
  22. package/native/ocx-child/src/link_ws.rs +2598 -0
  23. package/native/ocx-child/src/link_ws_advert.rs +346 -0
  24. package/native/ocx-child/src/link_ws_frame.rs +749 -0
  25. package/native/ocx-child/src/parity.rs +5 -1
  26. package/native/ocx-child/src/platform.rs +152 -6
  27. package/native/ocx-child/src/relay.rs +150 -19
  28. package/package.json +3 -3
  29. package/src/adapters/anthropic/advisor-tool.ts +176 -0
  30. package/src/adapters/anthropic/beta-body-pairs.ts +6 -0
  31. package/src/adapters/anthropic/client-identity.ts +3 -1
  32. package/src/adapters/anthropic/passthrough.ts +9 -3
  33. package/src/adapters/anthropic/per-message-effort.ts +296 -0
  34. package/src/adapters/anthropic.ts +34 -14
  35. package/src/adapters/claude-cli/adapter.ts +1 -0
  36. package/src/adapters/client-fingerprint.ts +3 -3
  37. package/src/adapters/cursor/discovery.ts +17 -0
  38. package/src/adapters/cursor/native-exec-desktop.ts +2 -1
  39. package/src/adapters/cursor/native-exec-shell.ts +2 -1
  40. package/src/adapters/cursor/protobuf-request.ts +8 -8
  41. package/src/adapters/cursor.ts +7 -6
  42. package/src/adapters/devin/cloud-direct/chat.ts +71 -14
  43. package/src/adapters/google-antigravity-wire.ts +7 -5
  44. package/src/adapters/google-errors.ts +14 -2
  45. package/src/adapters/google-wire-compiler.ts +2 -2
  46. package/src/adapters/google.ts +9 -2
  47. package/src/adapters/kiro/payload.ts +7 -4
  48. package/src/adapters/kiro/reasoning.ts +44 -1
  49. package/src/adapters/kiro/structured-output.ts +10 -8
  50. package/src/adapters/kiro-tools.ts +61 -15
  51. package/src/adapters/openai-chat/destination-policy.ts +16 -0
  52. package/src/adapters/openai-chat/reasoning-replay.ts +4 -1
  53. package/src/adapters/qoder/adapter.ts +9 -1
  54. package/src/adapters/zed.ts +7 -2
  55. package/src/advisor/consult.ts +15 -4
  56. package/src/advisor/context.ts +12 -3
  57. package/src/advisor/runtime.ts +35 -5
  58. package/src/advisor/settings.ts +8 -0
  59. package/src/advisor/synthetic-tool.ts +21 -8
  60. package/src/bridge/response-json.ts +11 -2
  61. package/src/bridge/sse.ts +43 -8
  62. package/src/claude/auth-detect.ts +21 -33
  63. package/src/claude/desktop-3p.ts +11 -5
  64. package/src/claude/desktop-gateway-state.ts +2 -0
  65. package/src/claude/desktop-remote-store-artifact.ts +14 -3
  66. package/src/claude/desktop-remote-store.ts +82 -12
  67. package/src/claude/inbound-content-options.ts +31 -16
  68. package/src/claude/outbound.ts +13 -3
  69. package/src/cli/account-api.ts +21 -1
  70. package/src/cli/account-auth.ts +83 -22
  71. package/src/cli/account-extended.ts +33 -2
  72. package/src/cli/account-key-quota.ts +34 -5
  73. package/src/cli/account.ts +4 -2
  74. package/src/cli/advisor.ts +7 -4
  75. package/src/cli/alias.ts +38 -1
  76. package/src/cli/capabilities-access-remote.ts +128 -3
  77. package/src/cli/capabilities-accounts.ts +6 -6
  78. package/src/cli/capabilities-agents-routing.ts +17 -10
  79. package/src/cli/capabilities-base.ts +49 -19
  80. package/src/cli/capabilities-integrations.ts +2 -2
  81. package/src/cli/capabilities-observe-system.ts +2 -2
  82. package/src/cli/capabilities-provider-models.ts +18 -2
  83. package/src/cli/capabilities-route-to.ts +43 -0
  84. package/src/cli/capabilities.ts +2 -0
  85. package/src/cli/capability-contracts.ts +1 -1
  86. package/src/cli/claude-desktop.ts +30 -11
  87. package/src/cli/claude.ts +17 -3
  88. package/src/cli/codex-launcher.ts +3 -1
  89. package/src/cli/codex-shim-autorestore.ts +5 -42
  90. package/src/cli/config-command.ts +14 -1
  91. package/src/cli/config-root-startup.ts +34 -0
  92. package/src/cli/connect.ts +88 -16
  93. package/src/cli/desktop-runtime-guidance.ts +1 -1
  94. package/src/cli/disconnect-runtime.ts +178 -0
  95. package/src/cli/dispatch.ts +61 -13
  96. package/src/cli/export-command.ts +1 -1
  97. package/src/cli/gui-pair-client.ts +6 -3
  98. package/src/cli/gui.ts +10 -5
  99. package/src/cli/help-catalog.ts +11 -0
  100. package/src/cli/help.ts +4 -3
  101. package/src/cli/index.ts +85 -94
  102. package/src/cli/inspect.ts +11 -2
  103. package/src/cli/integrations.ts +26 -1
  104. package/src/cli/link-apply-restart.ts +4 -2
  105. package/src/cli/link-capture.ts +64 -0
  106. package/src/cli/link-child-ops.ts +218 -40
  107. package/src/cli/link-cleanup.ts +8 -5
  108. package/src/cli/link-diagnostics.ts +67 -0
  109. package/src/cli/link-enrollment.ts +158 -12
  110. package/src/cli/link-operations.ts +52 -0
  111. package/src/cli/link-recover.ts +152 -0
  112. package/src/cli/link-routes.ts +90 -0
  113. package/src/cli/link-status-child.ts +44 -1
  114. package/src/cli/link-status-traffic.ts +34 -0
  115. package/src/cli/link.ts +315 -37
  116. package/src/cli/message-command.ts +1 -1
  117. package/src/cli/message-mcp-command.ts +23 -10
  118. package/src/cli/models-runtime.ts +3 -3
  119. package/src/cli/opencode.ts +3 -1
  120. package/src/cli/pi-sync.ts +35 -0
  121. package/src/cli/preflight-exemptions.ts +49 -0
  122. package/src/cli/registry.ts +33 -14
  123. package/src/cli/resolve.ts +23 -8
  124. package/src/cli/restart-failure.ts +15 -2
  125. package/src/cli/root.ts +5 -1
  126. package/src/cli/route-to.ts +172 -0
  127. package/src/cli/runtime-api.ts +9 -8
  128. package/src/cli/status.ts +7 -2
  129. package/src/cli/stop-approval.ts +66 -19
  130. package/src/cli/stop-report.ts +23 -0
  131. package/src/cli/stop-windows-checked.ts +304 -0
  132. package/src/cli/sync-command.ts +70 -15
  133. package/src/cli/sync-fanout.ts +74 -19
  134. package/src/cli/sync-flags.ts +40 -3
  135. package/src/cli/sync-link-status.ts +18 -2
  136. package/src/cli/sync-update-guard.ts +7 -2
  137. package/src/cli/system-command.ts +1 -1
  138. package/src/cli/system-restart-client.ts +10 -3
  139. package/src/cli/system-settings-parity.ts +2 -1
  140. package/src/cli/uninstall-plan.ts +77 -5
  141. package/src/cli/uninstall-stop.ts +152 -0
  142. package/src/cli/v2-input.ts +10 -6
  143. package/src/cli/v2-local-output.ts +3 -2
  144. package/src/cli/v2-runtime.ts +10 -3
  145. package/src/cli/v2.ts +22 -7
  146. package/src/client/connect.ts +376 -35
  147. package/src/client/desktop-refusal.ts +38 -0
  148. package/src/client/lifecycle-lock.ts +29 -4
  149. package/src/client/link-home-features.ts +27 -0
  150. package/src/client/link-home.ts +92 -4
  151. package/src/client/link-ingress.ts +21 -3
  152. package/src/client/link-join.ts +12 -2
  153. package/src/client/link-parity-reporter.ts +60 -6
  154. package/src/client/link-relay-transport.ts +161 -36
  155. package/src/client/link-relay.ts +150 -6
  156. package/src/client/link-request-compression.ts +84 -0
  157. package/src/client/link-state.ts +11 -5
  158. package/src/client/link-status.ts +39 -1
  159. package/src/client/link-teardown.ts +1 -0
  160. package/src/client/link-tunnel.ts +56 -5
  161. package/src/client/link-websocket-limits.ts +89 -0
  162. package/src/client/link-websocket.ts +586 -0
  163. package/src/client/link-ws-advertisement.ts +100 -0
  164. package/src/client/link-ws-framer.ts +241 -0
  165. package/src/client/link-ws-transport.ts +177 -0
  166. package/src/client/machine-api.ts +13 -2
  167. package/src/client/machine-listener.ts +48 -7
  168. package/src/client/route-intent-apply.ts +293 -0
  169. package/src/client/route-intent-file-originals.ts +97 -0
  170. package/src/client/route-intent-native-originals.ts +201 -0
  171. package/src/client/route-intent-watch.ts +141 -0
  172. package/src/client/runtime-restart.ts +141 -7
  173. package/src/client/runtime.ts +63 -15
  174. package/src/client/state.ts +44 -0
  175. package/src/client/sync-expectation.ts +36 -2
  176. package/src/client/sync-runtime.ts +7 -0
  177. package/src/clients/config-export/alias-selectors.ts +63 -40
  178. package/src/clients/config-export/contracts.ts +2 -0
  179. package/src/clients/config-export/nested-selectors.ts +42 -0
  180. package/src/clients/config-export.ts +22 -3
  181. package/src/codex/account-pause.ts +4 -0
  182. package/src/codex/account-runtime-state.ts +4 -0
  183. package/src/codex/account-store.ts +12 -3
  184. package/src/codex/account-usability.ts +13 -0
  185. package/src/codex/auth-api/account-list.ts +29 -3
  186. package/src/codex/auth-api/main-account-probe.ts +3 -1
  187. package/src/codex/auth-api/main-hard-lock-refusal-read.ts +172 -0
  188. package/src/codex/auth-collision.ts +23 -22
  189. package/src/codex/auth-context.ts +61 -8
  190. package/src/codex/catalog/build-entries.ts +10 -0
  191. package/src/codex/catalog/derive-entry.ts +7 -0
  192. package/src/codex/catalog/gather-capture.ts +8 -2
  193. package/src/codex/catalog/parsing.ts +7 -3
  194. package/src/codex/catalog/provider-models.ts +54 -15
  195. package/src/codex/catalog/reserve-warn.ts +7 -5
  196. package/src/codex/catalog/reserve.ts +4 -3
  197. package/src/codex/catalog/retained-sync.ts +4 -1
  198. package/src/codex/catalog/routed-defaults.ts +35 -0
  199. package/src/codex/catalog/routed-gather.ts +1 -1
  200. package/src/codex/catalog-auto-refresh.ts +11 -0
  201. package/src/codex/cli-update-job.ts +35 -13
  202. package/src/codex/convergence.ts +4 -2
  203. package/src/codex/desktop-compatibility/native-identity.ts +4 -8
  204. package/src/codex/features.ts +2 -2
  205. package/src/codex/history-provider.ts +31 -0
  206. package/src/codex/inject/multi-agent-v2.ts +9 -3
  207. package/src/codex/inject/paginated-openai-compat.ts +54 -1
  208. package/src/codex/inject/plan.ts +20 -2
  209. package/src/codex/inject.ts +2 -0
  210. package/src/codex/journal-config-restore.ts +217 -0
  211. package/src/codex/journal.ts +75 -6
  212. package/src/codex/loopback-target.ts +22 -8
  213. package/src/codex/main-account.ts +109 -57
  214. package/src/codex/native-main-auth-file.ts +118 -0
  215. package/src/codex/native-main-credentials.ts +270 -0
  216. package/src/codex/native-main-owner.ts +3 -0
  217. package/src/codex/native-main-refresh-mode.ts +14 -1
  218. package/src/codex/native-profile-manager.ts +4 -3
  219. package/src/codex/native-profile-store.ts +3 -61
  220. package/src/codex/orca-import.ts +10 -1
  221. package/src/codex/quota-history.ts +13 -0
  222. package/src/codex/quota-window-conflict.ts +103 -0
  223. package/src/codex/quota.ts +86 -15
  224. package/src/codex/subagent-model-fallback.ts +3 -1
  225. package/src/codex/websocket-activity.ts +171 -16
  226. package/src/codex/websocket-registry.ts +11 -4
  227. package/src/combos/cooldown-store.ts +25 -5
  228. package/src/combos/failover.ts +342 -3
  229. package/src/combos/index.ts +5 -0
  230. package/src/combos/resolve.ts +115 -19
  231. package/src/config/dashboard-trusted-proxy.ts +83 -0
  232. package/src/config/diagnostics.ts +31 -0
  233. package/src/config/feature-flags.ts +9 -0
  234. package/src/config/live-reconcile.ts +16 -4
  235. package/src/config/load-degrade.ts +14 -1
  236. package/src/config/multi-agent-surface.ts +28 -5
  237. package/src/config/pending-teardown.ts +60 -3
  238. package/src/config/persisted-mutation.ts +2 -2
  239. package/src/config/persisted-projections.ts +18 -0
  240. package/src/config/process-state.ts +176 -4
  241. package/src/config/provider-validation.ts +4 -4
  242. package/src/config/reserve-capability.ts +96 -0
  243. package/src/config/schema/config-schema.ts +12 -0
  244. package/src/config/schema/leaf-validators.ts +11 -2
  245. package/src/config/schema/routed-catalog-defaults.ts +49 -0
  246. package/src/config/windows-process-command-line.ts +107 -0
  247. package/src/config.ts +7 -7
  248. package/src/desktop-update/acquire.ts +202 -0
  249. package/src/desktop-update/cli.ts +168 -0
  250. package/src/desktop-update/drain.ts +40 -0
  251. package/src/desktop-update/headless.ts +285 -0
  252. package/src/desktop-update/image.ts +85 -0
  253. package/src/desktop-update/install.ts +53 -0
  254. package/src/desktop-update/msi.ts +72 -0
  255. package/src/desktop-update/release.ts +128 -0
  256. package/src/desktop-update/runtime.ts +155 -0
  257. package/src/desktop-update/staging.ts +118 -0
  258. package/src/desktop-update/trust.ts +45 -0
  259. package/src/generated/compatibility-version.json +1114 -442
  260. package/src/generated/model-metadata.ts +1 -1
  261. package/src/images/fulfill-video.ts +3 -3
  262. package/src/images/loop.ts +9 -2
  263. package/src/images/plan.ts +147 -11
  264. package/src/images/types.ts +13 -4
  265. package/src/images/xai-video-client.ts +72 -10
  266. package/src/integrations/model-name-guard.ts +25 -0
  267. package/src/integrations/route-intent-catalog.ts +26 -0
  268. package/src/integrations/route-intent-connected.ts +262 -0
  269. package/src/integrations/route-intent-contract.ts +55 -0
  270. package/src/integrations/route-intent-disconnect.ts +109 -0
  271. package/src/integrations/route-intent-initial.ts +64 -0
  272. package/src/integrations/route-intent-state.ts +117 -0
  273. package/src/integrations/route-intent-tick.ts +65 -0
  274. package/src/integrations/route-intent.ts +212 -0
  275. package/src/integrations/writer.ts +44 -11
  276. package/src/lib/client-retry-after.ts +29 -0
  277. package/src/lib/config-ownership.ts +13 -0
  278. package/src/lib/desktop-gui-origin.ts +28 -0
  279. package/src/lib/errors.ts +1 -1
  280. package/src/lib/gcp-adc.ts +48 -4
  281. package/src/lib/gui-pair-capability.ts +2 -1
  282. package/src/lib/messages-error-body.ts +4 -1
  283. package/src/lib/offline-resend.ts +150 -0
  284. package/src/lib/outbound-credential-registry.ts +362 -4
  285. package/src/lib/paced-stream.ts +34 -0
  286. package/src/lib/passive-key-fetch-proof.ts +30 -0
  287. package/src/lib/passive-read.ts +5 -0
  288. package/src/lib/process-control.ts +76 -12
  289. package/src/lib/provider-outbound.ts +17 -6
  290. package/src/lib/redact.ts +84 -8
  291. package/src/lib/request-failure-model.ts +2 -0
  292. package/src/lib/response-body-inactivity.ts +23 -1
  293. package/src/lib/state-store-registrations.ts +11 -0
  294. package/src/lib/state-store-sweeper.ts +4 -0
  295. package/src/lib/supervisor-markers.ts +18 -0
  296. package/src/lib/terminal-safe-text.ts +58 -0
  297. package/src/lib/translator-budget.ts +3 -2
  298. package/src/lib/upstream-retry.ts +52 -9
  299. package/src/link/alias-lock.ts +119 -0
  300. package/src/link/child-activity.ts +28 -2
  301. package/src/link/child-binary-cache-fill.d.mts +50 -0
  302. package/src/link/child-binary-cache-fill.mjs +494 -0
  303. package/src/link/child-binary-cache-start.ts +73 -0
  304. package/src/link/child-binary-source.ts +12 -5
  305. package/src/link/child-gated-ocx.ts +29 -11
  306. package/src/link/child-observations.ts +2 -1
  307. package/src/link/child-observe.ts +2 -2
  308. package/src/link/child-ops-engine.ts +159 -91
  309. package/src/link/child-ops-host.ts +138 -0
  310. package/src/link/child-ops-runners.ts +319 -0
  311. package/src/link/child-ops-scheduler.ts +207 -0
  312. package/src/link/child-ops-types.ts +89 -0
  313. package/src/link/child-parity.ts +23 -4
  314. package/src/link/child-policy.ts +93 -0
  315. package/src/link/child-update-contract.ts +12 -3
  316. package/src/link/codex-settings.ts +1 -1
  317. package/src/link/compatibility.ts +18 -1
  318. package/src/link/diagnostics-read.ts +163 -0
  319. package/src/link/diagnostics.ts +20 -7
  320. package/src/link/explicit-route.ts +209 -0
  321. package/src/link/link-recover.ts +113 -0
  322. package/src/link/management-routes.ts +3 -1
  323. package/src/link/operation-recovery-slot.ts +44 -0
  324. package/src/link/operations-journal.ts +408 -0
  325. package/src/link/peer-report.ts +1 -1
  326. package/src/link/relay-auth.ts +14 -0
  327. package/src/link/remote-plant.ts +152 -14
  328. package/src/link/remote-platform.ts +21 -10
  329. package/src/link/remote-probe.ts +11 -3
  330. package/src/link/remote-windows.ts +124 -36
  331. package/src/link/request-compression.ts +30 -0
  332. package/src/link/residual-recovery.ts +66 -0
  333. package/src/link/retirement.ts +128 -0
  334. package/src/link/route-intent-watch.ts +41 -0
  335. package/src/link/route-intent.ts +209 -0
  336. package/src/link/route-proof.ts +82 -0
  337. package/src/link/route-rounds.ts +579 -0
  338. package/src/link/route-select.ts +95 -0
  339. package/src/link/route-trust.ts +96 -0
  340. package/src/link/ssh-argv.ts +172 -24
  341. package/src/link/ssh-capture-redact.ts +253 -0
  342. package/src/link/ssh-capture.ts +497 -0
  343. package/src/link/ssh-runner.ts +141 -14
  344. package/src/link/status-projection.ts +87 -0
  345. package/src/link/store.ts +54 -1
  346. package/src/link/supervisor.ts +543 -55
  347. package/src/link/sync-fanout-classify.ts +16 -0
  348. package/src/link/sync-then-restart.ts +65 -0
  349. package/src/link/tombstones.ts +209 -0
  350. package/src/link/traffic.ts +178 -0
  351. package/src/link/ws-activity-holds.ts +474 -0
  352. package/src/local-credentials/publication-fence.ts +20 -1
  353. package/src/messaging/budget.ts +23 -5
  354. package/src/messaging/mcp-queue-rpc.ts +1 -1
  355. package/src/messaging/mcp-queue-server.ts +16 -1
  356. package/src/messaging/mcp-resume-tools.ts +25 -0
  357. package/src/messaging/remote-enrollment.ts +3 -3
  358. package/src/messaging/remote-tunnels.ts +2 -2
  359. package/src/messaging/resume-permissions.ts +27 -0
  360. package/src/messaging/rpc.ts +50 -6
  361. package/src/oauth/anthropic-continuity.ts +23 -7
  362. package/src/oauth/anthropic-routing.ts +5 -2
  363. package/src/oauth/anthropic.ts +22 -2
  364. package/src/oauth/antigravity-risk.ts +126 -0
  365. package/src/oauth/claude-keychain-read.ts +78 -68
  366. package/src/oauth/generic-account-failover.ts +89 -18
  367. package/src/oauth/generic-session-affinity.ts +10 -3
  368. package/src/oauth/index.ts +24 -6
  369. package/src/oauth/local-token-detect.ts +8 -29
  370. package/src/oauth/login-cli-errors.ts +5 -1
  371. package/src/oauth/login-cli.ts +68 -19
  372. package/src/oauth/login-flow-state.ts +26 -3
  373. package/src/oauth/meta-muse.ts +1 -1
  374. package/src/oauth/pool-kernel.ts +3 -3
  375. package/src/oauth/store.ts +7 -0
  376. package/src/oauth/xai.ts +248 -14
  377. package/src/protocols/contract.ts +4 -0
  378. package/src/protocols/encoders/messages.ts +1 -0
  379. package/src/providers/alias-template.ts +48 -0
  380. package/src/providers/anthropic-billing-ownership.ts +2 -0
  381. package/src/providers/anthropic-billing-refusal.ts +27 -3
  382. package/src/providers/anthropic-output-caps.ts +46 -0
  383. package/src/providers/anthropic-reset-grant-ledger.ts +9 -3
  384. package/src/providers/antigravity-effort-families.ts +11 -3
  385. package/src/providers/antigravity-models.ts +32 -9
  386. package/src/providers/antigravity-wire-snapshot.ts +3 -2
  387. package/src/providers/api-key-pause.ts +3 -0
  388. package/src/providers/api-key-resolve.ts +49 -7
  389. package/src/providers/api-key-response-ownership.ts +2 -0
  390. package/src/providers/api-key-selection.ts +51 -9
  391. package/src/providers/api-keys.ts +6 -2
  392. package/src/providers/cache-affinity-identity.ts +73 -0
  393. package/src/providers/cache-affinity.ts +256 -0
  394. package/src/providers/default-aliases.ts +98 -20
  395. package/src/providers/google-vertex-model-discovery.ts +515 -0
  396. package/src/providers/key-failover.ts +123 -8
  397. package/src/providers/key-store.ts +3 -3
  398. package/src/providers/kiro-models.ts +3 -5
  399. package/src/providers/label.ts +31 -5
  400. package/src/providers/mistral-transport.ts +17 -4
  401. package/src/providers/model-rename-fields.ts +5 -0
  402. package/src/providers/muse-key-quota.ts +14 -6
  403. package/src/providers/new-model-policy-runtime.ts +17 -4
  404. package/src/providers/new-model-policy.ts +30 -4
  405. package/src/providers/passive-key-observation.ts +252 -0
  406. package/src/providers/quota/account-cache.ts +2 -1
  407. package/src/providers/quota/anthropic-cooldown-recovery-worker.ts +121 -0
  408. package/src/providers/quota/passive-key-limits.ts +272 -0
  409. package/src/providers/quota/passive-wire-model.ts +126 -0
  410. package/src/providers/quota/report-cache.ts +61 -2
  411. package/src/providers/quota/workbuddy.ts +6 -2
  412. package/src/providers/quota-key-accounts.ts +11 -6
  413. package/src/providers/quota-types.ts +18 -0
  414. package/src/providers/quota.ts +11 -12
  415. package/src/providers/registry/entries-core.ts +34 -16
  416. package/src/providers/registry/entries-extended.ts +32 -0
  417. package/src/providers/registry/model-seeds.ts +35 -0
  418. package/src/providers/resolved-model-policy.ts +7 -0
  419. package/src/providers/routed-config.ts +8 -3
  420. package/src/providers/workbuddy-credit-balance.ts +125 -16
  421. package/src/providers/xai-transport.ts +3 -0
  422. package/src/remote/features.ts +17 -0
  423. package/src/responses/anthropic-progress.ts +10 -4
  424. package/src/responses/citation-markers.ts +231 -0
  425. package/src/responses/effort-history.ts +732 -0
  426. package/src/responses/spill-store.ts +5 -1
  427. package/src/responses/state/replay-input.ts +50 -0
  428. package/src/responses/state/replay-owner.ts +24 -0
  429. package/src/responses/state/snapshot-codec.ts +9 -0
  430. package/src/responses/state/spill-queue.ts +1 -0
  431. package/src/responses/state.ts +42 -60
  432. package/src/router.ts +2 -2
  433. package/src/routing/history/integrity.ts +41 -4
  434. package/src/routing/home-route-capture.ts +123 -0
  435. package/src/routing/home-route-intent.ts +200 -0
  436. package/src/routing/route-intent-state.ts +178 -0
  437. package/src/routing/route-to-live-settings.ts +35 -0
  438. package/src/routing/route-to-local.ts +145 -0
  439. package/src/routing/route-to-status.ts +94 -0
  440. package/src/routing/route-to-sync-child.ts +32 -0
  441. package/src/server/adapter-resolve.ts +21 -1
  442. package/src/server/admitted-http-turn.ts +3 -0
  443. package/src/server/auth-cors.ts +111 -3
  444. package/src/server/bare-upstream-error.ts +220 -0
  445. package/src/server/chat-native.ts +14 -5
  446. package/src/server/claude-messages.ts +6 -4
  447. package/src/server/codex-model-list.ts +4 -2
  448. package/src/server/configured-credentials.ts +37 -5
  449. package/src/server/direct-local-http.ts +26 -3
  450. package/src/server/gui-desktop-authorization.ts +36 -0
  451. package/src/server/gui-pair-delivery.ts +6 -3
  452. package/src/server/gui-session.ts +10 -1
  453. package/src/server/inbound-body-admission.ts +17 -4
  454. package/src/server/index/link-listener.ts +196 -12
  455. package/src/server/index/link-management.ts +15 -1
  456. package/src/server/index/link-relay-sessions.ts +87 -8
  457. package/src/server/index/link-websocket-limits.ts +136 -0
  458. package/src/server/index/link-websocket.ts +692 -0
  459. package/src/server/index/optional-listeners.ts +97 -7
  460. package/src/server/index/route-intent-watch.ts +47 -0
  461. package/src/server/index/serve-contract.ts +86 -0
  462. package/src/server/index/serve-options.ts +36 -86
  463. package/src/server/index/startup-warnings.ts +8 -2
  464. package/src/server/index/websocket-handler.ts +26 -4
  465. package/src/server/index.ts +15 -4
  466. package/src/server/inference/client-encoder-delivery.ts +2 -0
  467. package/src/server/inspection-tee.ts +39 -2
  468. package/src/server/lifecycle.ts +2 -0
  469. package/src/server/link-turn.ts +149 -0
  470. package/src/server/management/advisor-routes.ts +10 -2
  471. package/src/server/management/agent-settings-routes.ts +50 -16
  472. package/src/server/management/anthropic-reset-grant-routes.ts +1 -1
  473. package/src/server/management/config-routes.ts +39 -3
  474. package/src/server/management/context.ts +9 -2
  475. package/src/server/management/desktop-authorization.ts +41 -0
  476. package/src/server/management/desktop-compatibility-routes.ts +9 -8
  477. package/src/server/management/desktop-compatibility-runtime-routes.ts +3 -2
  478. package/src/server/management/desktop-compatibility-settings-routes.ts +5 -3
  479. package/src/server/management/home-integration-decision.ts +89 -0
  480. package/src/server/management/integration-routes.ts +208 -81
  481. package/src/server/management/link-child-ops-routes.ts +145 -43
  482. package/src/server/management/link-child-preflight.ts +31 -0
  483. package/src/server/management/link-diagnostics-route.ts +29 -0
  484. package/src/server/management/link-enrollment.ts +199 -47
  485. package/src/server/management/link-operation.ts +609 -0
  486. package/src/server/management/link-recover-route.ts +103 -0
  487. package/src/server/management/link-route-edit.ts +192 -0
  488. package/src/server/management/link-route-request.ts +62 -0
  489. package/src/server/management/link-route-state.ts +83 -7
  490. package/src/server/management/link-routes.ts +553 -51
  491. package/src/server/management/link-traffic-status.ts +13 -0
  492. package/src/server/management/model-routes.ts +122 -36
  493. package/src/server/management/model-rows.ts +2 -1
  494. package/src/server/management/native-integration-routes.ts +176 -70
  495. package/src/server/management/oauth-account-routes.ts +58 -18
  496. package/src/server/management/protocol-routes.ts +7 -0
  497. package/src/server/management/provider-completion-test.ts +4 -4
  498. package/src/server/management/provider-overwrite-carry.ts +14 -0
  499. package/src/server/management/provider-routes.ts +68 -65
  500. package/src/server/management/provider-routing-quota.ts +45 -0
  501. package/src/server/management/route-registry.ts +22 -3
  502. package/src/server/management/route-to-routes.ts +257 -0
  503. package/src/server/management/static-catalog-probe.ts +33 -0
  504. package/src/server/management/system-restart.ts +4 -2
  505. package/src/server/management/usage-aggregate-cache.ts +101 -66
  506. package/src/server/management-api.ts +17 -3
  507. package/src/server/management-auth.ts +13 -1
  508. package/src/server/messages-native-preflight.ts +27 -4
  509. package/src/server/messages-native.ts +17 -5
  510. package/src/server/persistent-gui-session.ts +6 -3
  511. package/src/server/proxy-liveness.ts +87 -15
  512. package/src/server/relay-eager.ts +36 -12
  513. package/src/server/relay.ts +189 -117
  514. package/src/server/request-body-facts.ts +48 -0
  515. package/src/server/request-decompress.ts +65 -2
  516. package/src/server/request-log-account-rotation.ts +6 -0
  517. package/src/server/request-log-attempt-usage.ts +69 -0
  518. package/src/server/request-log-cache-affinity.ts +60 -0
  519. package/src/server/request-log-conversation.ts +45 -2
  520. package/src/server/request-log-terminal-status.ts +210 -24
  521. package/src/server/request-log.ts +76 -80
  522. package/src/server/reserve-capability-startup.ts +32 -0
  523. package/src/server/responses/adapter-continuation.ts +2 -1
  524. package/src/server/responses/adapter-delivery.ts +4 -0
  525. package/src/server/responses/adapter-dispatch.ts +36 -17
  526. package/src/server/responses/advisor-plan-slot.ts +33 -1
  527. package/src/server/responses/advisor-question.ts +21 -0
  528. package/src/server/responses/advisor-slot.ts +10 -3
  529. package/src/server/responses/antigravity-fault-rotation.ts +24 -0
  530. package/src/server/responses/antigravity-validation-refusal.ts +43 -6
  531. package/src/server/responses/bare-namespace-aliases.ts +18 -0
  532. package/src/server/responses/buffered-sse-json.ts +9 -3
  533. package/src/server/responses/code-mode-collab-surface.ts +11 -0
  534. package/src/server/responses/codex-tool-catalog.ts +156 -0
  535. package/src/server/responses/combo-required-tool-fulfillments.ts +4 -2
  536. package/src/server/responses/combo-selection-keepalive.ts +254 -0
  537. package/src/server/responses/combo-stream-preflight.ts +557 -54
  538. package/src/server/responses/compact.ts +32 -8
  539. package/src/server/responses/core-codex-account.ts +17 -3
  540. package/src/server/responses/core-combo-failure.ts +8 -0
  541. package/src/server/responses/core-combo.ts +55 -12
  542. package/src/server/responses/core-errors.ts +13 -7
  543. package/src/server/responses/core-lifetime.ts +3 -2
  544. package/src/server/responses/core-normalize.ts +3 -1
  545. package/src/server/responses/core-options.ts +14 -0
  546. package/src/server/responses/core.ts +23 -0
  547. package/src/server/responses/estimated-usage.ts +115 -0
  548. package/src/server/responses/fetch-helpers.ts +15 -10
  549. package/src/server/responses/jev-model-invoke.ts +7 -2
  550. package/src/server/responses/native-replay-guard.ts +57 -0
  551. package/src/server/responses/opengateway-completion-guard.ts +10 -4
  552. package/src/server/responses/outbound-request-body.ts +29 -0
  553. package/src/server/responses/passthrough-completion.ts +109 -9
  554. package/src/server/responses/passthrough-delivery.ts +77 -18
  555. package/src/server/responses/passthrough-dispatch.ts +77 -73
  556. package/src/server/responses/policy-fallback.ts +13 -1
  557. package/src/server/responses/request-prepare.ts +59 -11
  558. package/src/server/responses/request-transport.ts +10 -3
  559. package/src/server/responses/reset-replay.ts +46 -2
  560. package/src/server/responses/run-turn-execution.ts +2 -0
  561. package/src/server/responses/sidecar-execution.ts +19 -0
  562. package/src/server/responses/terminal-error-redaction.ts +222 -25
  563. package/src/server/responses/ws-upstream.ts +2 -2
  564. package/src/server/sse-payload-rewrite.ts +3 -2
  565. package/src/server/stop-service-route.ts +85 -0
  566. package/src/server/system-env-shell.ts +12 -1
  567. package/src/server/system-env.ts +5 -3
  568. package/src/server/windows-tcp-drop.ts +21 -4
  569. package/src/server/workflow-refusal.ts +8 -0
  570. package/src/server/ws-bridge.ts +191 -12
  571. package/src/service/cli-windows-stop.ts +189 -0
  572. package/src/service/cli.ts +41 -12
  573. package/src/service/desktop-supervision.d.mts +2 -0
  574. package/src/service/desktop-supervision.mjs +5 -0
  575. package/src/service/disconnected-client-restart.ts +60 -0
  576. package/src/service/guarded-manager-target.ts +18 -1
  577. package/src/service/health.ts +99 -6
  578. package/src/service/launchd.ts +84 -31
  579. package/src/service/orchestration.ts +418 -91
  580. package/src/service/repair.ts +223 -6
  581. package/src/service/restart-proxy-stop.ts +79 -0
  582. package/src/service/service-child-ownership.ts +6 -2
  583. package/src/service/windows-checked-stop-live.ts +467 -0
  584. package/src/service/windows-checked-stop.ts +435 -0
  585. package/src/service/windows-command-line-token.ts +23 -0
  586. package/src/service/windows-guarded-manager.ts +77 -34
  587. package/src/service/windows-ops.ts +38 -56
  588. package/src/service/windows-process-evidence.ts +292 -0
  589. package/src/service/windows-process-native.ts +262 -0
  590. package/src/service/windows-service-stop.ts +321 -0
  591. package/src/service/windows-stop-binding.ts +187 -0
  592. package/src/service/windows-stop-budget.ts +123 -0
  593. package/src/service/windows-stop-confirm.ts +158 -0
  594. package/src/service/windows-stop-deadline.ts +56 -0
  595. package/src/service.ts +2 -2
  596. package/src/stall-timeout.ts +11 -0
  597. package/src/types/config.ts +57 -110
  598. package/src/types/link.ts +20 -0
  599. package/src/types/multi-agent.ts +13 -0
  600. package/src/types/provider.ts +60 -2
  601. package/src/types/request.ts +23 -0
  602. package/src/types/routed-catalog-defaults.ts +17 -0
  603. package/src/types/routing-profile.ts +90 -0
  604. package/src/types.ts +4 -0
  605. package/src/update/guarded-runtime-ops.ts +5 -7
  606. package/src/update/index.ts +26 -11
  607. package/src/update/install-detection.mjs +3 -1
  608. package/src/update/job-pinned-start.ts +2 -0
  609. package/src/update/job-windows-restart.ts +19 -32
  610. package/src/update/job.ts +12 -5
  611. package/src/update/npm-install.d.mts +11 -0
  612. package/src/update/npm-install.mjs +44 -7
  613. package/src/update/orchestrated-entry.ts +1 -1
  614. package/src/update/orchestrated-node-driver.mjs +3 -2
  615. package/src/update/orchestrated-pnpm.d.mts +4 -0
  616. package/src/update/orchestrated-pnpm.mjs +50 -6
  617. package/src/update/orchestrated-session.d.mts +3 -1
  618. package/src/update/orchestrated-session.mjs +21 -6
  619. package/src/update/pnpm-global-install.d.mts +21 -3
  620. package/src/update/pnpm-global-install.mjs +322 -19
  621. package/src/update/pnpm-store-layout.mjs +46 -0
  622. package/src/update/sync-update-mutex.d.mts +3 -2
  623. package/src/update/sync-update-mutex.mjs +57 -8
  624. package/src/update/transactional-install.d.mts +3 -1
  625. package/src/update/transactional-install.mjs +545 -12
  626. package/src/update/windows-installer-marker.d.mts +1 -0
  627. package/src/update/windows-installer-marker.mjs +44 -0
  628. package/src/usage/expected-prices.ts +8 -0
  629. package/src/usage/filter-index.ts +326 -77
  630. package/src/usage/ledger-scanner.ts +15 -0
  631. package/src/usage/link-log-fields.ts +48 -0
  632. package/src/usage/log.ts +57 -6
  633. package/src/usage/request-body.ts +37 -0
  634. package/src/usage/telemetry-contract.ts +1 -0
  635. package/src/web-search/loop.ts +3 -0
  636. package/src/web-search/passthrough-bridge.ts +7 -0
  637. package/gui/dist/assets/App-BpJOzw4F.js +0 -59
  638. package/gui/dist/assets/brand-mark-DU-0Vdkr.js +0 -1
  639. package/gui/dist/assets/index-Bbor_y80.js +0 -94
  640. package/gui/dist/assets/index-DJEkIDAi.css +0 -2
  641. package/gui/dist/classic/assets/App-BrIlUiLc.js +0 -58
  642. package/gui/dist/classic/assets/index-DyJHagvT.js +0 -94
  643. package/gui/dist/classic/assets/quota-summary-CakPe9Ni.js +0 -1
  644. package/src/server/management/desktop-compatibility-authorization.ts +0 -12
@@ -0,0 +1,200 @@
1
+ /** Upgrade bridge: existing journaled integrations are Home intent, never unowned file guesses. */
2
+ import { homedir } from "node:os";
3
+ import { join, resolve } from "node:path";
4
+ import { readBoundedRegularFileSync } from "../lib/bounded-file-read";
5
+ import { createIntegrationStateStore, type IntegrationStateStore } from "../integrations/store";
6
+ import { listAsideProfileStores } from "../integrations/aside-profile-context";
7
+ import { asideHomeDir } from "../clients/config-export";
8
+ import { parseRouteClientIntent, projectHomeRouteIntent, ROUTE_CLIENT_IDS, type HomeRouteIntentDocument, type RouteClientId, type RouteClientIntent, type RouteIntentState } from "../link/route-intent";
9
+ import { dropHomeNativeOverrides, homeRouteIntentInUse, readRouteIntentState, setRouteClientIntent, updateRouteIntentState } from "./route-intent-state";
10
+ import { captureHomeRouteDefaults, durableHomeNativeRouteDefaults, fillHomeNativeRouteDefaults, homeHasLinks, type CaptureHomeRouteDefaultsOptions } from "./home-route-capture";
11
+ import { withConfigMutationLockSync } from "../config/mutation-lock";
12
+ import { readConfigDiagnostics } from "../config";
13
+ import { packageVersion } from "../lib/package-version";
14
+ import type { OcxConfig } from "../types";
15
+
16
+ /** Existing Aside ownership must be resolved explicitly, never projected as off. */
17
+ export class HomeAsideIntentDerivationError extends Error {
18
+ constructor(cause: unknown) {
19
+ super("Existing Aside ownership needs an explicit Home route intent", { cause });
20
+ this.name = "HomeAsideIntentDerivationError";
21
+ }
22
+ }
23
+
24
+ export function readHomeRouteIntentState(config: OcxConfig, options: { store?: IntegrationStateStore; home?: string; state?: RouteIntentState } = {}): RouteIntentState {
25
+ const state = structuredClone(options.state ?? readRouteIntentState());
26
+ const store = options.store ?? createIntegrationStateStore();
27
+ const records = store.readRecordsStrict();
28
+ for (const [client, owner] of Object.entries(records)) {
29
+ if (state.defaults[client as keyof typeof state.defaults] !== undefined || !owner || client === "aside") continue;
30
+ const intent = parseRouteClientIntent({ enabled: true, ...(owner.modelNames ? { modelNames: owner.modelNames } : {}) });
31
+ if (intent) state.defaults[client as keyof typeof state.defaults] = intent;
32
+ }
33
+ // A Home override does not resolve the default inherited by Children.
34
+ if (state.defaults.aside !== undefined) return state;
35
+ // The Home decision may already have changed or removed its ownership records. They no longer
36
+ // prove what Children inherited before that decision, even when there are no records left.
37
+ if (state.devices.home?.aside !== undefined) throw new HomeAsideIntentDerivationError(undefined);
38
+ const aside = deriveHomeAsideIntent(config, { store, home: options.home });
39
+ if (aside) state.defaults.aside = aside;
40
+ return state;
41
+ }
42
+
43
+ /**
44
+ * For status reads and the Home's own sync: existing Aside ownership that cannot be named by stable
45
+ * userIds leaves the Children's Aside default unresolved. The returned state then carries a
46
+ * placeholder off default only so a document can be projected; a device without its own Aside entry
47
+ * must be reported as unresolved (`routeToAsideUnresolved`), never as off.
48
+ */
49
+ export function readHomeRouteIntentStateAsideTolerant(config: OcxConfig, options: { state?: RouteIntentState } = {}): { state: RouteIntentState; asideUnresolved: boolean } {
50
+ try { return { state: readHomeRouteIntentState(config, options), asideUnresolved: false }; }
51
+ catch (error) {
52
+ if (!(error instanceof HomeAsideIntentDerivationError)) throw error;
53
+ const pinned = structuredClone(options.state ?? readRouteIntentState());
54
+ pinned.defaults.aside = { enabled: false };
55
+ return { state: readHomeRouteIntentState(config, { state: pinned }), asideUnresolved: true };
56
+ }
57
+ }
58
+
59
+ /**
60
+ * The Aside intent the Home's current Aside ownership amounts to: the stable userIds of every owned
61
+ * profile, all profiles under the all-profiles policy, or undefined when nothing is owned.
62
+ * `extraProfileIds` adds profiles about to be enabled, so a caller can refuse before writing
63
+ * anything when one of them has no stable userId. Throws HomeAsideIntentDerivationError.
64
+ */
65
+ export function deriveHomeAsideIntent(config: OcxConfig, options: { store?: IntegrationStateStore; home?: string; extraProfileIds?: readonly number[] | "all" } = {}): RouteClientIntent | undefined {
66
+ const store = options.store ?? createIntegrationStateStore();
67
+ const records = store.readRecordsStrict();
68
+ const scopes = listAsideProfileStores(store).filter(scope => scope.store.readRecordsStrict().aside);
69
+ const extra = options.extraProfileIds ?? [];
70
+ if (!records.aside && scopes.length === 0 && extra.length === 0 && config.asideProfileSync?.allProfiles !== true) return undefined;
71
+ if (config.asideProfileSync?.allProfiles === true) return { enabled: true, accounts: "all" };
72
+ try {
73
+ const raw: unknown = JSON.parse(readBoundedRegularFileSync(join(asideHomeDir(process.env, options.home ?? homedir()), "accounts.json"), 4 * 1024 * 1024).toString("utf8"));
74
+ if (!raw || typeof raw !== "object" || !("accounts" in raw) || !Array.isArray(raw.accounts)) throw new Error("existing Aside selection needs explicit route intent");
75
+ const every = extra === "all" ? raw.accounts.flatMap((row: unknown) => row && typeof row === "object" && "id" in row && typeof row.id === "number" ? [row.id] : []) : extra;
76
+ const slots = new Set([...scopes.map(scope => scope.profileId), ...every]);
77
+ if (records.aside) {
78
+ const root = asideHomeDir(process.env, options.home ?? homedir());
79
+ const owned = resolve(records.aside.configPath);
80
+ const matches = raw.accounts.filter((row: unknown) => row && typeof row === "object" && "id" in row
81
+ && typeof row.id === "number" && Number.isSafeInteger(row.id) && row.id >= 0
82
+ && resolve(join(root, "u", String(row.id), "models.json")) === owned);
83
+ if (matches.length !== 1) throw new Error("existing Aside owner needs explicit route intent");
84
+ slots.add(matches[0].id);
85
+ }
86
+ const userIds: string[] = [];
87
+ for (const slot of slots) {
88
+ const row = raw.accounts.find((value: unknown) => value && typeof value === "object" && "id" in value && value.id === slot);
89
+ if (!row || typeof row !== "object" || !("userId" in row) || typeof row.userId !== "string") throw new Error("existing Aside selection needs explicit stable userIds");
90
+ userIds.push(row.userId);
91
+ }
92
+ const intent = parseRouteClientIntent({ enabled: true, accounts: [...new Set(userIds)] }, "aside");
93
+ if (!intent) throw new Error("existing Aside selection needs explicit stable userIds");
94
+ return intent;
95
+ } catch (cause) {
96
+ throw new HomeAsideIntentDerivationError(cause);
97
+ }
98
+ }
99
+
100
+ /**
101
+ * Records a Home Aside profile change (the dashboard, `ocx integration client enable --client aside
102
+ * --profile N`, an Aside restore) as the Home's `devices.home.aside` decision, naming the stable
103
+ * userIds of every profile it owns afterwards, so ocx sync keeps it. Only once the Home uses route
104
+ * intent; returns whether a decision was recorded. Throws HomeAsideIntentDerivationError.
105
+ */
106
+ export function recordHomeAsideDecision(config: OcxConfig): boolean {
107
+ return withConfigMutationLockSync(() => {
108
+ if (!homeRouteIntentInUse(readRouteIntentState())) return false;
109
+ setRouteClientIntent("aside", deriveHomeAsideIntent(config) ?? { enabled: false }, "home");
110
+ return true;
111
+ });
112
+ }
113
+
114
+ /**
115
+ * Capture defaults before a local materializer changes native switches or owners. The native
116
+ * defaults come from the shared one-time capture; every other client from ownership or builtin.
117
+ * A Home-only decision passes `whenLinked`, the rule every Home-only switch writer follows: a Home
118
+ * without links has no Child to protect, so nothing reads or writes route-intent.json for it. Saving
119
+ * ownership defaults there would pin clients the dashboard later turns on (ocx sync applies saved
120
+ * defaults), and a damaged file would block a toggle that never needed it.
121
+ */
122
+ export function initializeHomeRouteIntentDefaults(config: OcxConfig, version: string, decidingDefault?: RouteClientId,
123
+ options: CaptureHomeRouteDefaultsOptions = {}): void {
124
+ if (options.whenLinked && !homeHasLinks()) return;
125
+ withConfigMutationLockSync(() => {
126
+ // Every default is derived before anything is written: an Aside refusal leaves the file as it was.
127
+ const native = durableHomeNativeRouteDefaults(config);
128
+ const prior = readRouteIntentState();
129
+ if (native) fillHomeNativeRouteDefaults(prior, native);
130
+ if (decidingDefault) prior.defaults[decidingDefault] = { enabled: false };
131
+ const inherited = projectHomeRouteIntent(config, version, undefined, readHomeRouteIntentState(config, { state: prior }));
132
+ updateRouteIntentState(state => {
133
+ if (native) fillHomeNativeRouteDefaults(state, native);
134
+ for (const [client, intent] of Object.entries(inherited.clients)) state.defaults[client as keyof typeof state.defaults] ??= intent;
135
+ // A `devices.home` native entry from an earlier version no longer decides anything.
136
+ dropHomeNativeOverrides(state);
137
+ return state;
138
+ });
139
+ });
140
+ }
141
+
142
+ /**
143
+ * The link listener's capture of every default a Child inherits, from the Home's durable config:
144
+ * the native switches and the file clients' ownership, frozen in one write. An upgraded Home that
145
+ * saved only the native defaults gets the rest here, so a later dashboard toggle cannot move a
146
+ * Child's default. When existing Aside ownership cannot be resolved nothing else is saved; the
147
+ * native defaults are then captured on their own and the error is raised so the listener retries.
148
+ */
149
+ export function captureChildRouteDefaults(): void {
150
+ const latest = readConfigDiagnostics();
151
+ if (latest.error) throw new Error("the configuration could not be read");
152
+ if (latest.config.runtimeRole === "client") return;
153
+ try {
154
+ initializeHomeRouteIntentDefaults(latest.config, packageVersion("0.0.0"), undefined, { whenLinked: true });
155
+ } catch (error) {
156
+ if (error instanceof HomeAsideIntentDerivationError) captureHomeRouteDefaults(undefined, { whenLinked: true });
157
+ throw error;
158
+ }
159
+ }
160
+
161
+ /**
162
+ * What a Child inherits. Never reads the Home's live native switches; see home-route-capture.
163
+ * A pure read: enrollment and the link listener's start have already captured the native defaults.
164
+ */
165
+ export function projectChildRouteIntent(config: OcxConfig, version: string, deviceId: string): HomeRouteIntentDocument {
166
+ const { state, asideUnresolved } = readHomeRouteIntentStateAsideTolerant(config);
167
+ if (asideUnresolved && state.devices[deviceId]?.aside === undefined) throw new HomeAsideIntentDerivationError(undefined);
168
+ return projectHomeRouteIntent(config, version, deviceId, state);
169
+ }
170
+
171
+ /** Provisioning runs under Home authority, before the read-only Child starts. */
172
+ export function seedRouteDeviceClients(config: OcxConfig, version: string, deviceId: string, selected?: readonly RouteClientId[], activeDeviceIds?: readonly string[]): void {
173
+ withConfigMutationLockSync(() => {
174
+ if (activeDeviceIds) reconcileHomeRouteDevices(activeDeviceIds);
175
+ initializeHomeRouteIntentDefaults(config, version);
176
+ // Absence means inherit, not an implicit device selection that masks Home changes.
177
+ if (selected === undefined) return;
178
+ updateRouteIntentState(state => {
179
+ const overrides = (state.devices[deviceId] ??= {});
180
+ const revisions = ((state.revisions ??= {})[deviceId] ??= {});
181
+ for (const client of ROUTE_CLIENT_IDS) {
182
+ if (client !== "codex" && client !== "claude" && !selected.includes(client)) continue;
183
+ overrides[client] = { ...(overrides[client] ?? {}), enabled: selected.includes(client) };
184
+ revisions[client] = (revisions[client] ?? 0) + 1;
185
+ }
186
+ return state;
187
+ });
188
+ });
189
+ }
190
+
191
+ /** Trust retirement also retires policy/revisions; Home and live peers retain their state. */
192
+ export function reconcileHomeRouteDevices(activeDeviceIds: readonly string[]): void {
193
+ const live = new Set(["home", ...activeDeviceIds]);
194
+ updateRouteIntentState(state => {
195
+ for (const map of [state.devices, state.revisions]) {
196
+ for (const id of Object.keys(map ?? {})) if (!live.has(id)) delete map![id];
197
+ }
198
+ return state;
199
+ });
200
+ }
@@ -0,0 +1,178 @@
1
+ /** Home-owned desired policy. Reads never create or repair a file. */
2
+ import { chmodSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
3
+ import { dirname, join } from "node:path";
4
+ import { atomicWriteFile, isMissingPathError } from "../config/atomic-write";
5
+ import { withConfigMutationLockSync } from "../config/mutation-lock";
6
+ import { getConfigDir } from "../config/paths";
7
+ import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
8
+ import { hardenSecretDir } from "../lib/windows-secret-acl";
9
+ import { emptyRouteIntentState, HOME_NATIVE_ROUTE_CLIENTS, isHomeNativeRouteClient, isRouteClientId, parseRouteClientIntent,
10
+ type HomeNativeRouteClientId, type RouteClientId, type RouteClientIntent, type RouteIntentState } from "../link/route-intent";
11
+ export type { RouteIntentState } from "../link/route-intent";
12
+
13
+ const MAX_STATE_BYTES = 1024 * 1024;
14
+ export function routeIntentStatePath(): string { return join(getConfigDir(), "route-intent.json"); }
15
+
16
+ /**
17
+ * `route-intent.json` exists but cannot be read or parsed. Writers answer it with a typed refusal
18
+ * that names the file, because only the operator can fix or remove it.
19
+ */
20
+ export class RouteIntentStateUnreadableError extends Error {
21
+ readonly path: string;
22
+ constructor(path: string, cause: unknown) {
23
+ super(`Route intent in ${path} could not be read; nothing was changed. Inspect it, fix or remove it, then retry.`, { cause });
24
+ this.name = "RouteIntentStateUnreadableError";
25
+ this.path = path;
26
+ }
27
+ }
28
+ function deviceIdAllowed(value: string): boolean {
29
+ return /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,255}$/.test(value) && !["__proto__", "constructor", "prototype"].includes(value);
30
+ }
31
+ function parseIntentMap(value: unknown): Partial<Record<RouteClientId, RouteClientIntent>> {
32
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid route intent map");
33
+ const result: Partial<Record<RouteClientId, RouteClientIntent>> = {};
34
+ for (const [client, raw] of Object.entries(value)) {
35
+ if (!isRouteClientId(client)) throw new Error("unknown route client");
36
+ const intent = parseRouteClientIntent(raw, client);
37
+ if (!intent) throw new Error("invalid route client intent");
38
+ result[client] = intent;
39
+ }
40
+ return result;
41
+ }
42
+ export function parseRouteIntentState(value: unknown): RouteIntentState {
43
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid route intent state");
44
+ const raw = value as Record<string, unknown>;
45
+ if (raw.version !== 1 || Object.keys(raw).some(key => !["version", "defaults", "devices", "revisions"].includes(key)) || !Object.hasOwn(raw, "defaults") || !Object.hasOwn(raw, "devices")
46
+ || !raw.devices || typeof raw.devices !== "object" || Array.isArray(raw.devices)) throw new Error("invalid route intent state");
47
+ const state = emptyRouteIntentState();
48
+ state.defaults = parseIntentMap(raw.defaults);
49
+ for (const [id, map] of Object.entries(raw.devices)) {
50
+ if (!deviceIdAllowed(id)) throw new Error("invalid route device id");
51
+ state.devices[id] = parseIntentMap(map);
52
+ }
53
+ if (raw.revisions !== undefined) {
54
+ if (!raw.revisions || typeof raw.revisions !== "object" || Array.isArray(raw.revisions)) throw new Error("invalid route device revisions");
55
+ state.revisions = {};
56
+ for (const [id, map] of Object.entries(raw.revisions)) {
57
+ if (!deviceIdAllowed(id) || !map || typeof map !== "object" || Array.isArray(map)) throw new Error("invalid route device revisions");
58
+ const revisions: Partial<Record<RouteClientId, number>> = {};
59
+ for (const [client, revision] of Object.entries(map)) {
60
+ if (!isRouteClientId(client) || typeof revision !== "number" || !Number.isSafeInteger(revision) || revision < 0) throw new Error("invalid route client revision");
61
+ revisions[client] = revision;
62
+ }
63
+ state.revisions[id] = revisions;
64
+ }
65
+ }
66
+ return state;
67
+ }
68
+ export function readRouteIntentState(path = routeIntentStatePath()): RouteIntentState {
69
+ try {
70
+ const stat = lstatSync(path);
71
+ if (!stat.isFile() || stat.size > MAX_STATE_BYTES) throw new Error("invalid route intent state file");
72
+ return parseRouteIntentState(JSON.parse(readFileSync(path, "utf8")));
73
+ } catch (error) {
74
+ if (isMissingPathError(error)) return emptyRouteIntentState();
75
+ throw new RouteIntentStateUnreadableError(path, error);
76
+ }
77
+ }
78
+ function writeState(state: RouteIntentState, path: string): void {
79
+ const dir = dirname(path);
80
+ assertNotRealHomeUnderTest(dir);
81
+ const body = `${JSON.stringify(state, null, 2)}\n`;
82
+ if (Buffer.byteLength(body) > MAX_STATE_BYTES) throw new Error("route intent state too large");
83
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
84
+ if (process.platform === "win32") hardenSecretDir(dir, { required: true });
85
+ else chmodSync(dir, 0o700);
86
+ atomicWriteFile(path, body);
87
+ }
88
+ export function writeRouteIntentState(state: RouteIntentState, path = routeIntentStatePath()): void {
89
+ const parsed = parseRouteIntentState(state);
90
+ withConfigMutationLockSync(() => writeState(parsed, path), dirname(path));
91
+ }
92
+ export function updateRouteIntentState(update: (state: RouteIntentState) => RouteIntentState, path = routeIntentStatePath()): RouteIntentState {
93
+ return withConfigMutationLockSync(() => {
94
+ const next = parseRouteIntentState(update(readRouteIntentState(path)));
95
+ writeState(next, path);
96
+ return next;
97
+ }, dirname(path));
98
+ }
99
+ export function setRouteClientIntent(client: RouteClientId, intent: RouteClientIntent, deviceId?: string): RouteIntentState {
100
+ const parsed = parseRouteClientIntent(intent, client);
101
+ if (!isRouteClientId(client) || !parsed || (deviceId !== undefined && !deviceIdAllowed(deviceId))) throw new Error("invalid route intent selection");
102
+ if (deviceId === "home" && isHomeNativeRouteClient(client)) throw new Error("A Home native decision is its native switch; use recordHomeNativeDecision");
103
+ return updateRouteIntentState(state => {
104
+ const map = deviceId === undefined ? state.defaults : (state.devices[deviceId] ??= {});
105
+ map[client] = { ...map[client], ...parsed };
106
+ if (deviceId !== undefined) advanceRevision(state, deviceId, client);
107
+ return state;
108
+ });
109
+ }
110
+ export function clearRouteClientIntent(client: RouteClientId, deviceId: string): RouteIntentState {
111
+ if (!isRouteClientId(client) || !deviceIdAllowed(deviceId)) throw new Error("invalid route intent selection");
112
+ if (deviceId === "home" && isHomeNativeRouteClient(client)) throw new Error("A Home native decision is its native switch; use recordHomeNativeDecision");
113
+ return updateRouteIntentState(state => {
114
+ const map = state.devices[deviceId];
115
+ if (map) { delete map[client]; if (Object.keys(map).length === 0) delete state.devices[deviceId]; }
116
+ advanceRevision(state, deviceId, client);
117
+ return state;
118
+ });
119
+ }
120
+
121
+ /**
122
+ * Earlier versions recorded Home native decisions as `devices.home` entries. The Home's native
123
+ * switches govern those clients now, so such an entry is dropped instead of pinning anything.
124
+ */
125
+ export function dropHomeNativeOverrides(state: RouteIntentState, clients: readonly HomeNativeRouteClientId[] = HOME_NATIVE_ROUTE_CLIENTS): void {
126
+ const map = state.devices.home;
127
+ if (!map) return;
128
+ for (const client of clients) delete map[client];
129
+ if (Object.keys(map).length === 0) delete state.devices.home;
130
+ }
131
+
132
+ /** Drops those legacy entries from the file, writing only when one is there. */
133
+ export function dropLegacyHomeNativeOverrides(): void {
134
+ withConfigMutationLockSync(() => {
135
+ const map = readRouteIntentState().devices.home;
136
+ if (!map || !HOME_NATIVE_ROUTE_CLIENTS.some(client => map[client] !== undefined)) return;
137
+ updateRouteIntentState(state => { dropHomeNativeOverrides(state); return state; });
138
+ });
139
+ }
140
+
141
+ /**
142
+ * Bookkeeping for a Home decision about a native client, which itself is written to the Home's
143
+ * native switch. No `devices.home` entry is kept. The caller has already captured the Children's
144
+ * native defaults (src/routing/home-route-capture.ts), so the switch never becomes one.
145
+ */
146
+ export function recordHomeNativeDecision(client: HomeNativeRouteClientId): RouteIntentState {
147
+ return updateRouteIntentState(state => {
148
+ dropHomeNativeOverrides(state, [client]);
149
+ return state;
150
+ });
151
+ }
152
+
153
+ /** ocx sync applies route intent to every Home client once the file holds a default or a Home entry. */
154
+ export function homeRouteIntentInUse(state: RouteIntentState): boolean {
155
+ return Object.keys(state.defaults).length > 0 || Object.keys(state.devices.home ?? {}).length > 0;
156
+ }
157
+
158
+ /**
159
+ * A file integration toggle on the Home (the dashboard, `PUT /api/client-integrations/<id>`) is the
160
+ * Home's own decision for that client. Once the Home uses route intent, ocx sync applies it to every
161
+ * client, so the toggle is recorded as a `devices.home` entry and Children keep their defaults.
162
+ * Without route intent nothing is written. Returns whether a decision was recorded.
163
+ */
164
+ export function recordHomeFileIntegrationDecision(client: RouteClientId, intent: RouteClientIntent): boolean {
165
+ if (isHomeNativeRouteClient(client) || client === "aside") return false;
166
+ return withConfigMutationLockSync(() => {
167
+ if (!homeRouteIntentInUse(readRouteIntentState())) return false;
168
+ setRouteClientIntent(client, intent, "home");
169
+ return true;
170
+ });
171
+ }
172
+
173
+ function advanceRevision(state: RouteIntentState, deviceId: string, client: RouteClientId): void {
174
+ const revisions = ((state.revisions ??= {})[deviceId] ??= {});
175
+ const next = (revisions[client] ?? 0) + 1;
176
+ if (!Number.isSafeInteger(next)) throw new Error("route device revision exhausted");
177
+ revisions[client] = next;
178
+ }
@@ -0,0 +1,35 @@
1
+ import { readConfigDiagnostics, withConfigMutationLockSync } from "../config";
2
+ import type { OcxConfig } from "../types";
3
+
4
+ /** Reflect controller-owned fields from current durable state, preserving concurrent settings. */
5
+ export function mirrorRouteNativeSettings(live: OcxConfig, current: OcxConfig): void {
6
+ for (const client of ["codex", "grok", "claude-desktop"] as const) {
7
+ const value = current.clientIntegrations?.[client];
8
+ if (value !== undefined) (live.clientIntegrations ??= {})[client] = value;
9
+ else if (live.clientIntegrations) delete live.clientIntegrations[client];
10
+ }
11
+ for (const key of ["enabled", "authModeMigratedAt"] as const) {
12
+ const value = current.claudeCode?.[key];
13
+ if (value !== undefined) live.claudeCode = { ...live.claudeCode, [key]: value };
14
+ else if (live.claudeCode) delete live.claudeCode[key];
15
+ }
16
+ const messages = current.apiSurfaces?.messages?.enabled;
17
+ if (messages !== undefined) live.apiSurfaces = { ...live.apiSurfaces, messages: { ...live.apiSurfaces?.messages, enabled: messages } };
18
+ else if (live.apiSurfaces?.messages) delete live.apiSurfaces.messages.enabled;
19
+ }
20
+
21
+ export function refreshRouteNativeSettings(live: OcxConfig): void {
22
+ withConfigMutationLockSync(() => {
23
+ const latest = readConfigDiagnostics();
24
+ if (latest.source !== "file" || latest.error) throw new Error("config_unavailable");
25
+ mirrorRouteNativeSettings(live, latest.config);
26
+ });
27
+ }
28
+
29
+ /** A copy carrying the durable native switches; another process may have changed them. */
30
+ export function withDurableRouteNativeSettings(config: OcxConfig): OcxConfig {
31
+ const copy = structuredClone(config);
32
+ const latest = readConfigDiagnostics();
33
+ if (latest.source === "file" && !latest.error) mirrorRouteNativeSettings(copy, latest.config);
34
+ return copy;
35
+ }
@@ -0,0 +1,145 @@
1
+ /** Local CLI reads/applies never relay management writes from a Child to its Home. */
2
+ import { readClientConnectionState } from "../client/state";
3
+ import { withLinkApply } from "../client/link-home";
4
+ import { projectHomeRouteIntent, ROUTE_CLIENT_IDS, type RouteClientId, type RouteClientIntent, type RouteClientOutcome } from "../link/route-intent";
5
+ import { HomeAsideIntentDerivationError, initializeHomeRouteIntentDefaults, readHomeRouteIntentState, readHomeRouteIntentStateAsideTolerant } from "./home-route-intent";
6
+ import { captureHomeRouteDefaults } from "./home-route-capture";
7
+ import { routeToAsideUnresolved, routeToDeviceStatus, type RouteToDeviceStatus, type RouteToStatus } from "./route-to-status";
8
+ import { withDurableRouteNativeSettings } from "./route-to-live-settings";
9
+ import { dropLegacyHomeNativeOverrides, readRouteIntentState, type RouteIntentState } from "./route-intent-state";
10
+ import { readLocalRouteIntentOff, readRouteIntentReceipt, setLocalRouteIntentOff } from "../integrations/route-intent";
11
+ import type { LinkChildContext } from "../cli/link-child";
12
+ import type { OcxConfig } from "../types";
13
+
14
+ /**
15
+ * The Home's status row. Existing Aside ownership without stable userIds and no saved Home Aside
16
+ * decision is reported as unresolved Aside (with `HOME_ASIDE_UNRESOLVED_MESSAGE` in the response)
17
+ * and every other client as usual, so a full sync that left Aside alone can still report the rest.
18
+ */
19
+ export function readHomeRouteToStatus(config: OcxConfig, version: string): RouteToDeviceStatus {
20
+ const local = withDurableRouteNativeSettings(config);
21
+ const { state, asideUnresolved } = readHomeRouteIntentStateAsideTolerant(local);
22
+ const document = projectHomeRouteIntent(local, version, "home", state);
23
+ const receipt = readRouteIntentReceipt();
24
+ const status = routeToDeviceStatus("home", "home", document, receipt?.outcomes ?? [], receipt?.appliedRouteIntentDigest ?? null);
25
+ return asideUnresolved && state.devices.home?.aside === undefined ? routeToAsideUnresolved(status) : status;
26
+ }
27
+
28
+ /** What a full Home sync tells the person when it leaves Aside alone. */
29
+ export const HOME_ASIDE_UNRESOLVED_MESSAGE = "Aside was left unchanged on this Home: its existing Aside profiles have no stable userIds in Aside's accounts.json, so route intent cannot name them. Repair the manifest, or decide Aside for the Home with ocx route to aside on|off --device home.";
30
+
31
+ /**
32
+ * `onlyClient` is the client a single Home write decides: only that client is materialized on the
33
+ * Home. For a native client the decision (`onlyIntent`, else the default Children inherit) is
34
+ * written through the Home's native switch. A sync passes none and never writes a Home native
35
+ * switch: each native client is refreshed to match the switch as it is.
36
+ *
37
+ * A full sync on a Home whose existing Aside ownership cannot be named by stable userIds, and that
38
+ * has no saved Aside decision, leaves Aside exactly as it is and applies every other client, calling
39
+ * `onAsideUnresolved`. A Home upgraded with such profiles therefore keeps a working `ocx sync`;
40
+ * only a write that decides Aside still refuses until the person resolves it.
41
+ *
42
+ * `homeAsideDecision` is the one exception: an explicit `--device home` Aside write is the Home's
43
+ * own decision, so it is applied without deriving the Children's Aside default, which stays absent.
44
+ * The saved `devices.home.aside` entry is what a later full sync reads, so it keeps the decision.
45
+ */
46
+ export async function syncHomeRouteTo(config: OcxConfig, version: string, overwriteConflict = false, overwriteClient?: RouteClientId, commit?: () => void,
47
+ deps: { loadModels?: typeof import("../server/management/model-rows").loadExportModels; materialize?: typeof import("../client/route-intent-apply").materializeLocalRouteIntent;
48
+ onlyClient?: RouteClientId; onlyIntent?: () => RouteClientIntent | undefined; onAsideUnresolved?: (message: string) => void;
49
+ homeAsideDecision?: boolean } = {}): Promise<RouteClientOutcome[]> {
50
+ return withLinkApply(async () => {
51
+ commit?.();
52
+ const local = withDurableRouteNativeSettings(config);
53
+ // A Home-only Aside decision never needs the Children's Aside default; only a write that sets
54
+ // that default (or a full sync reading it) does.
55
+ const leaveAside = deps.homeAsideDecision === true || deps.onlyClient === undefined || deps.onlyClient !== "aside";
56
+ let asideUnresolved = false;
57
+ // The Home's own apply is Home-only: it captures the Children's native defaults only once the
58
+ // Home has a link. A default write's commit above has already captured them. Without a link it
59
+ // saves no defaults, and only drops a legacy devices.home native entry if one is there.
60
+ // A saved Home Aside entry means this apply must not derive the Children's Aside default at all.
61
+ const homeAsideSaved = readRouteIntentState().devices.home?.aside !== undefined;
62
+ try {
63
+ if (homeAsideSaved) captureHomeRouteDefaults(undefined, { whenLinked: true });
64
+ else initializeHomeRouteIntentDefaults(local, version, undefined, { whenLinked: true });
65
+ }
66
+ catch (error) {
67
+ if (!(error instanceof HomeAsideIntentDerivationError) || !leaveAside) throw error;
68
+ // Save what can be saved: the native defaults, never a guessed Aside default.
69
+ captureHomeRouteDefaults(undefined, { whenLinked: true });
70
+ asideUnresolved = true;
71
+ }
72
+ dropLegacyHomeNativeOverrides();
73
+ const decidedIntent = deps.onlyIntent?.();
74
+ let state;
75
+ try { state = readHomeRouteIntentState(local); }
76
+ catch (error) {
77
+ if (!(error instanceof HomeAsideIntentDerivationError) || !leaveAside) throw error;
78
+ asideUnresolved = true;
79
+ // A placeholder so the document is complete; Aside is excluded from materialization below.
80
+ // This placeholder is never saved as a default.
81
+ const pinned: RouteIntentState = readRouteIntentState();
82
+ pinned.defaults.aside = { enabled: false };
83
+ state = readHomeRouteIntentState(local, { state: pinned });
84
+ }
85
+ if (asideUnresolved && (state.devices.home?.aside !== undefined || readRouteIntentState().defaults.aside !== undefined)) asideUnresolved = false;
86
+ const document = projectHomeRouteIntent(local, version, "home", state,
87
+ { decidedClient: deps.onlyClient, ...(decidedIntent ? { decidedIntent } : {}) });
88
+ const { loadExportModels } = await import("../server/management/model-rows");
89
+ const { materializeLocalRouteIntent } = await import("../client/route-intent-apply");
90
+ const materialize = deps.materialize ?? materializeLocalRouteIntent;
91
+ const only = deps.onlyClient !== undefined ? [deps.onlyClient]
92
+ : asideUnresolved ? ROUTE_CLIENT_IDS.filter(client => client !== "aside") : undefined;
93
+ // A single-client write keeps the other clients' last proven outcomes in the Home receipt.
94
+ const scope = only ? { retainSkippedOutcomes: true, ...(deps.onlyClient ? { decidedClient: deps.onlyClient } : {}) } : {};
95
+ const off = ROUTE_CLIENT_IDS.filter(client => !document.clients[client].enabled && (!only || only.includes(client)));
96
+ // Disabling needs no catalog. The off pass keeps the receipt's last served roster, so a decision
97
+ // that only turns clients off completes here without waiting for unrelated model discovery.
98
+ const previousModels = readRouteIntentReceipt()?.models ?? [];
99
+ const offReceipt = await materialize(local, document, previousModels, { overwriteConflict, overwriteClient, onlyClients: off, ...scope });
100
+ if (only && only.every(client => off.includes(client))) {
101
+ if (asideUnresolved) deps.onAsideUnresolved?.(HOME_ASIDE_UNRESOLVED_MESSAGE);
102
+ return asideUnresolved ? offReceipt.outcomes.filter(row => row.client !== "aside") : offReceipt.outcomes;
103
+ }
104
+ const receipt = await materialize(local, document, await (deps.loadModels ?? loadExportModels)(local), { overwriteConflict, overwriteClient,
105
+ ...(only ? { onlyClients: only } : {}), ...scope });
106
+ if (asideUnresolved) deps.onAsideUnresolved?.(HOME_ASIDE_UNRESOLVED_MESSAGE);
107
+ return asideUnresolved ? receipt.outcomes.filter(row => row.client !== "aside") : receipt.outcomes;
108
+ });
109
+ }
110
+
111
+ function assertChild(context: LinkChildContext): void {
112
+ const state = readClientConnectionState();
113
+ if (state.kind !== "connected" || state.value.transport !== "link" || state.value.link?.linkId !== context.linkId) {
114
+ throw new Error("The Remote Link connection changed; retry against the current device");
115
+ }
116
+ }
117
+
118
+ export function readLocalRouteToStatus(context: LinkChildContext): RouteToStatus {
119
+ assertChild(context);
120
+ const receipt = readRouteIntentReceipt();
121
+ if (!receipt) throw new Error("This Child has no recorded route intent. Run ocx route to sync to read and apply its Home intent");
122
+ const stale = receipt.outcomes.filter(row => row.outcome === "stale").map(row => row.client);
123
+ return { schema: "ocx.route-to/1", devices: [routeToDeviceStatus(context.linkId, "this", receipt.document,
124
+ receipt.outcomes, receipt.appliedRouteIntentDigest, readLocalRouteIntentOff())],
125
+ ...(receipt.catalogPending || stale.length ? { deferred: { reason: "intent_or_catalog_pending" as const, clients: stale } } : {}) };
126
+ }
127
+
128
+ export async function syncLocalRouteTo(context: LinkChildContext, overwriteConflict = false,
129
+ deps: { sync?: typeof import("../client/connect").syncConnectedClient } = {}): Promise<RouteToStatus> {
130
+ assertChild(context);
131
+ const { syncConnectedClient } = await import("../client/connect");
132
+ const result = await (deps.sync ?? syncConnectedClient)({ expect: { kind: "link", linkId: context.linkId }, overwriteConflict });
133
+ const status = readLocalRouteToStatus(context);
134
+ if (result.stale) status.deferred ??= { reason: "intent_or_catalog_pending", clients: status.devices[0]!.clients.filter(row => row.applied === "stale").map(row => row.client) };
135
+ return status;
136
+ }
137
+
138
+ export async function setLocalRouteToOff(context: LinkChildContext, client: RouteClientId, off: boolean): Promise<RouteToStatus> {
139
+ await withLinkApply(async () => {
140
+ assertChild(context);
141
+ setLocalRouteIntentOff(client, off);
142
+ });
143
+ // The existing sync takes the lifecycle/config locks and checks the pinned connection again.
144
+ return syncLocalRouteTo(context);
145
+ }
@@ -0,0 +1,94 @@
1
+ import { ROUTE_CLIENT_IDS, routeClientIntentDigest, routeIntentDigest, type HomeRouteIntentDocument, type RouteClientId, type RouteClientOutcome } from "../link/route-intent";
2
+
3
+ export interface RouteToClientStatus {
4
+ client: RouteClientId;
5
+ /**
6
+ * `unresolved`: only Aside, on a device that follows the Children's Aside default while the Home's
7
+ * existing Aside ownership cannot be named by stable userIds. Nothing decides it yet, so it is
8
+ * neither on nor off; the status carries a warning saying how to resolve it.
9
+ */
10
+ intent: "on" | "off" | "unresolved";
11
+ /** `native`: a Home row governed by the Home's own persisted native switch. */
12
+ source: "builtin" | "default" | "device" | "native" | "local";
13
+ applied: RouteClientOutcome["outcome"] | null;
14
+ target?: string;
15
+ }
16
+
17
+ export interface RouteToDeviceStatus {
18
+ id: string;
19
+ alias: string;
20
+ desiredDigest: string;
21
+ appliedRouteIntentDigest: string | null;
22
+ clients: RouteToClientStatus[];
23
+ /**
24
+ * Present only on a device that never reads route intent: an ephemeral `ocx-child` refreshes the
25
+ * Home catalog through ocx sync and nothing else, so it has no client rows.
26
+ */
27
+ routeIntent?: "unsupported";
28
+ reason?: typeof EPHEMERAL_NO_ROUTE_INTENT;
29
+ }
30
+
31
+ /** Why an ephemeral `ocx-child` link has no route intent. */
32
+ export const EPHEMERAL_NO_ROUTE_INTENT = "ephemeral-child-no-route-intent" as const;
33
+
34
+ export type RouteToSyncRow = { id: string; state: "synced" | "failed" | "pending" | "unsupported"; reason?: string };
35
+
36
+ export interface RouteToStatus {
37
+ schema: "ocx.route-to/1";
38
+ devices: RouteToDeviceStatus[];
39
+ syncs?: RouteToSyncRow[];
40
+ deferred?: { reason: "intent_or_catalog_pending"; clients: RouteClientId[] };
41
+ /** Actionable notices about clients the request left alone, such as unresolved Aside on the Home. */
42
+ warnings?: string[];
43
+ }
44
+
45
+ /** The status row of an ephemeral Child: route intent is unsupported, never stale or pending. */
46
+ export function unsupportedRouteToDevice(id: string, alias: string): RouteToDeviceStatus {
47
+ return { id, alias, desiredDigest: "", appliedRouteIntentDigest: null, clients: [], routeIntent: "unsupported", reason: EPHEMERAL_NO_ROUTE_INTENT };
48
+ }
49
+
50
+ /** Report a device's Aside row as unresolved: its projected placeholder is not a decision. */
51
+ export function routeToAsideUnresolved(device: RouteToDeviceStatus): RouteToDeviceStatus {
52
+ return { ...device, clients: device.clients.map(row => row.client === "aside"
53
+ ? { client: "aside", intent: "unresolved", source: row.source, applied: null } : row) };
54
+ }
55
+
56
+ /**
57
+ * Compare receipts with today's intent: an outcome recorded for an earlier intent is stale, never
58
+ * current. That includes an earlier conflict or failure, which says nothing about the new intent.
59
+ */
60
+ export function routeToDeviceStatus(
61
+ id: string,
62
+ alias: string,
63
+ document: HomeRouteIntentDocument,
64
+ outcomes: readonly RouteClientOutcome[],
65
+ appliedDigest: string | null,
66
+ localOff: readonly RouteClientId[] = [],
67
+ ): RouteToDeviceStatus {
68
+ const effective = structuredClone(document);
69
+ for (const row of outcomes) {
70
+ if (row.initialIntent && row.initialRevision === (document.clientRevisions?.[row.client] ?? 0)) {
71
+ effective.clients[row.client] = { ...effective.clients[row.client], ...row.initialIntent };
72
+ effective.sources[row.client] = "device";
73
+ }
74
+ }
75
+ const desiredDigest = routeIntentDigest(effective);
76
+ return {
77
+ id, alias, desiredDigest, appliedRouteIntentDigest: appliedDigest,
78
+ clients: ROUTE_CLIENT_IDS.map(client => {
79
+ const outcome = outcomes.find(row => row.client === client);
80
+ const disabledLocally = localOff.includes(client) || outcome?.source === "local";
81
+ // A receipt without per-client digests only proves its whole-document digest for current rows.
82
+ const outdated = outcome !== undefined && !disabledLocally && outcome.outcome !== "stale"
83
+ && (outcome.intentDigest ? outcome.intentDigest !== routeClientIntentDigest(effective, client)
84
+ : outcome.outcome === "current" && desiredDigest !== appliedDigest);
85
+ return {
86
+ client,
87
+ intent: disabledLocally ? "off" : effective.clients[client].enabled ? "on" : "off",
88
+ source: disabledLocally ? "local" : effective.sources[client],
89
+ applied: outdated ? "stale" : outcome?.outcome ?? null,
90
+ ...(outcome?.target ? { target: outcome.target } : {}),
91
+ };
92
+ }),
93
+ };
94
+ }