@bitkyc08/opencodex 2.99.0 → 2.100.0

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 (258) hide show
  1. package/AGENTS_INSTALL.md +19 -1
  2. package/README.md +37 -33
  3. package/SPONSORS.md +5 -1
  4. package/bin/ocx.mjs +1 -1
  5. package/gui/dist/assets/{App-C1hGwaN1.css → App-COo8Yopd.css} +1 -1
  6. package/gui/dist/assets/App-CitvEefy.js +59 -0
  7. package/gui/dist/assets/Tray-CeKVWQyB.js +1 -0
  8. package/gui/dist/assets/{brand-mark-wzPe3R-J.js → brand-mark-M92UnxX2.js} +1 -1
  9. package/gui/dist/assets/index-BP47do6-.js +94 -0
  10. package/gui/dist/assets/index-DmDooSAG.css +2 -0
  11. package/gui/dist/assets/{segment-thumb-features-fYEMxBaW.js → segment-thumb-features-CcxZBnxv.js} +1 -1
  12. package/gui/dist/classic/assets/App-aYgIQMxI.js +58 -0
  13. package/gui/dist/classic/assets/{Tray-BqZueZOx.js → Tray-D8jfUXpQ.js} +1 -1
  14. package/gui/dist/classic/assets/index-CfGqHooN.js +94 -0
  15. package/gui/dist/classic/assets/quota-summary-R-ih7OlS.js +1 -0
  16. package/gui/dist/classic/index.html +1 -1
  17. package/gui/dist/index.html +2 -2
  18. package/native/ocx-child/Cargo.lock +215 -0
  19. package/native/ocx-child/Cargo.toml +31 -0
  20. package/native/ocx-child/src/cli.rs +1901 -0
  21. package/native/ocx-child/src/codex_home.rs +429 -0
  22. package/native/ocx-child/src/codex_settings.rs +231 -0
  23. package/native/ocx-child/src/daemon.rs +363 -0
  24. package/native/ocx-child/src/http_wire.rs +619 -0
  25. package/native/ocx-child/src/journal.rs +977 -0
  26. package/native/ocx-child/src/lib.rs +22 -0
  27. package/native/ocx-child/src/main.rs +9 -0
  28. package/native/ocx-child/src/parity.rs +102 -0
  29. package/native/ocx-child/src/platform.rs +1487 -0
  30. package/native/ocx-child/src/relay.rs +1288 -0
  31. package/native/ocx-child/src/relay_auth.rs +166 -0
  32. package/native/ocx-child/src/routes.rs +236 -0
  33. package/native/ocx-child/src/state.rs +190 -0
  34. package/native/ocx-child/src/test_hooks.rs +58 -0
  35. package/native/ocx-child/src/toml_surgeon.rs +1156 -0
  36. package/package.json +8 -2
  37. package/src/adapters/anthropic.ts +28 -2
  38. package/src/adapters/claude-cli/adapter.ts +5 -25
  39. package/src/adapters/claude-cli/instruction-images.ts +31 -0
  40. package/src/adapters/claude-cli/stable-replay.ts +42 -14
  41. package/src/adapters/claude-cli/usage-admission.ts +53 -64
  42. package/src/adapters/coding-agent/protocol.ts +1 -1
  43. package/src/adapters/devin/live-models.ts +3 -0
  44. package/src/adapters/google-http.ts +3 -0
  45. package/src/adapters/google-vertex-key-project.ts +10 -2
  46. package/src/adapters/google.ts +40 -8
  47. package/src/adapters/kiro/usage.ts +3 -13
  48. package/src/adapters/openai-responses/passthrough.ts +5 -2
  49. package/src/adapters/openai-responses/request-strips.ts +32 -0
  50. package/src/adapters/openai-responses/tool-schema.ts +9 -4
  51. package/src/chat/inbound.ts +1 -1
  52. package/src/claude/auth-detect.ts +26 -8
  53. package/src/claude/inbound-content-options.ts +18 -3
  54. package/src/claude/inbound.ts +5 -2
  55. package/src/cli/bundled-bun-diagnostic.ts +91 -0
  56. package/src/cli/capabilities-agents-routing.ts +2 -2
  57. package/src/cli/capabilities-observe-system.ts +60 -0
  58. package/src/cli/combo-input.ts +6 -0
  59. package/src/cli/combo-result.ts +1 -1
  60. package/src/cli/combo.ts +4 -0
  61. package/src/cli/config-command.ts +16 -2
  62. package/src/cli/connect.ts +12 -10
  63. package/src/cli/dispatch.ts +4 -0
  64. package/src/cli/doctor.ts +11 -0
  65. package/src/cli/help.ts +1 -0
  66. package/src/cli/init.ts +4 -0
  67. package/src/cli/link-enrollment.ts +152 -25
  68. package/src/cli/link-local-control.ts +49 -0
  69. package/src/cli/link.ts +37 -10
  70. package/src/cli/provider-lifecycle-runtime.ts +4 -2
  71. package/src/cli/registry.ts +13 -0
  72. package/src/cli/star-prompt.ts +2 -0
  73. package/src/cli/status.ts +1 -1
  74. package/src/cli/telemetry-profile.ts +206 -0
  75. package/src/cli/telemetry.ts +260 -0
  76. package/src/client/hub-relay.ts +26 -0
  77. package/src/client/machine-api.ts +3 -0
  78. package/src/clients/config-export/t3code.ts +44 -5
  79. package/src/clients/omo-role-models.ts +1 -1
  80. package/src/codex/catalog/bundled.ts +44 -2
  81. package/src/codex/runtime.ts +12 -0
  82. package/src/codex/shim-restore-lock.ts +67 -30
  83. package/src/combos/types.ts +21 -1
  84. package/src/config/atomic-write.ts +24 -1
  85. package/src/config/diagnostics.ts +15 -0
  86. package/src/config/live-reconcile.ts +17 -0
  87. package/src/config/load-degrade.ts +16 -0
  88. package/src/config/provider-validation.ts +29 -0
  89. package/src/config/schema/config-schema.ts +24 -0
  90. package/src/config/schema/leaf-validators.ts +17 -0
  91. package/src/config/telemetry-carry.ts +30 -0
  92. package/src/config.ts +13 -1
  93. package/src/generated/compatibility-version.json +405 -153
  94. package/src/generated/model-metadata.ts +3 -3
  95. package/src/integrations/aside-profiles.ts +7 -1
  96. package/src/integrations/owned-refresh.ts +9 -2
  97. package/src/lab/artifacts/secure-fs.ts +12 -11
  98. package/src/lab/fabric/scratch.ts +11 -9
  99. package/src/lab/public/community.ts +2 -3
  100. package/src/lab/public/file-safety.ts +18 -20
  101. package/src/lab/public/mutation-lock.ts +109 -337
  102. package/src/lab/public/private-file.ts +4 -3
  103. package/src/lib/bun-runtime-preflight.ts +1 -1
  104. package/src/lib/codex-catalog-read-only.ts +122 -0
  105. package/src/lib/config-ownership.ts +49 -18
  106. package/src/lib/errors.ts +11 -0
  107. package/src/lib/gcp-adc.ts +167 -48
  108. package/src/lib/jsonc.ts +4 -2
  109. package/src/lib/local-control-socket.ts +88 -0
  110. package/src/lib/privacy.ts +15 -0
  111. package/src/lib/provider-client-headers.ts +3 -0
  112. package/src/lib/token-estimate.ts +13 -2
  113. package/src/link/child-binary-source.ts +228 -0
  114. package/src/link/ephemeral-child.ts +45 -0
  115. package/src/link/remote-plant.ts +306 -0
  116. package/src/link/remote-windows.ts +59 -5
  117. package/src/link/ssh-argv.ts +71 -8
  118. package/src/link/status-projection.ts +2 -0
  119. package/src/link/store.ts +5 -1
  120. package/src/oauth/claude-keychain-read.ts +165 -0
  121. package/src/oauth/local-token-detect.ts +14 -17
  122. package/src/protocols/envelope.ts +20 -2
  123. package/src/providers/api-key-selection.ts +8 -2
  124. package/src/providers/claude-cli-usage-state.ts +93 -0
  125. package/src/providers/github-copilot-auto.ts +25 -5
  126. package/src/providers/meta-muse-plan-refusal.ts +94 -0
  127. package/src/providers/model-rename-fields.ts +3 -0
  128. package/src/providers/quota/vendor-probes-key.ts +23 -4
  129. package/src/providers/quota/vendor-probes-oauth.ts +59 -0
  130. package/src/providers/quota/workbuddy.ts +2 -2
  131. package/src/providers/quota.ts +25 -18
  132. package/src/providers/registry/entries-core.ts +7 -4
  133. package/src/providers/registry/entries-extended.ts +39 -7
  134. package/src/providers/registry/model-seeds.ts +10 -2
  135. package/src/providers/resolved-model-policy.ts +4 -0
  136. package/src/providers/routed-config.ts +30 -3
  137. package/src/providers/stale-no-vision-seed-migration.ts +7 -0
  138. package/src/providers/vertex-environment-authority.ts +50 -0
  139. package/src/providers/workbuddy-credit-balance.ts +38 -6
  140. package/src/quota-pool/assemble.ts +14 -6
  141. package/src/router.ts +1 -0
  142. package/src/server/adapter-resolve.ts +11 -6
  143. package/src/server/audio-dictation.ts +21 -7
  144. package/src/server/auth-cors.ts +19 -0
  145. package/src/server/background-lifecycle.ts +71 -0
  146. package/src/server/chat-completions.ts +2 -0
  147. package/src/server/claude-messages.ts +30 -3
  148. package/src/server/index/live-sideband.ts +15 -1
  149. package/src/server/index/local-control-listener.ts +515 -0
  150. package/src/server/index/optional-listeners.ts +21 -1
  151. package/src/server/index/serve-options.ts +4 -3
  152. package/src/server/index/websocket-handler.ts +2 -0
  153. package/src/server/index.ts +3 -0
  154. package/src/server/management/combo-routes.ts +6 -1
  155. package/src/server/management/context.ts +1 -0
  156. package/src/server/management/link-child-preflight.ts +74 -0
  157. package/src/server/management/link-enrollment.ts +190 -25
  158. package/src/server/management/link-route-state.ts +6 -1
  159. package/src/server/management/link-routes.ts +27 -9
  160. package/src/server/management/model-rows.ts +4 -0
  161. package/src/server/management/oauth-account-routes.ts +9 -4
  162. package/src/server/management/provider-overwrite-carry.ts +9 -2
  163. package/src/server/management/provider-routes.ts +14 -0
  164. package/src/server/management/provider-thinking-display-patch.ts +54 -0
  165. package/src/server/management/route-registry.ts +7 -0
  166. package/src/server/management/session-routes.ts +4 -1
  167. package/src/server/management/telemetry-routes.ts +37 -0
  168. package/src/server/management/usage-aggregate-cache.ts +290 -67
  169. package/src/server/management-api.ts +11 -2
  170. package/src/server/messages-native-preflight.ts +166 -0
  171. package/src/server/messages-native.ts +143 -43
  172. package/src/server/messages-shared.ts +14 -0
  173. package/src/server/proxy-liveness.ts +99 -6
  174. package/src/server/request-log-conversation.ts +18 -2
  175. package/src/server/request-log.ts +7 -2
  176. package/src/server/responses/adapter-continuation.ts +1 -0
  177. package/src/server/responses/adapter-dispatch.ts +11 -28
  178. package/src/server/responses/adapter-failure-message.ts +68 -0
  179. package/src/server/responses/combo-stream-preflight.ts +14 -2
  180. package/src/server/responses/core-auth.ts +26 -5
  181. package/src/server/responses/core-codex-account.ts +8 -1
  182. package/src/server/responses/core-combo-failure.ts +6 -1
  183. package/src/server/responses/core-combo-native.ts +150 -37
  184. package/src/server/responses/core-combo.ts +15 -9
  185. package/src/server/responses/core-normalize.ts +1 -0
  186. package/src/server/responses/core-options.ts +7 -1
  187. package/src/server/responses/core-pipeline.ts +21 -1
  188. package/src/server/responses/fetch-helpers.ts +5 -0
  189. package/src/server/responses/opengateway-completion-guard.ts +7 -3
  190. package/src/server/responses/passthrough-delivery.ts +8 -1
  191. package/src/server/responses/passthrough-error.ts +22 -0
  192. package/src/server/responses/request-prepare.ts +7 -1
  193. package/src/server/responses/request-transport.ts +28 -5
  194. package/src/server/responses/run-turn-execution.ts +13 -0
  195. package/src/server/sse-frame-buffer.ts +5 -0
  196. package/src/server/ws-bridge.ts +10 -0
  197. package/src/service/launchd.ts +78 -4
  198. package/src/telemetry/aggregate.ts +348 -0
  199. package/src/telemetry/consent.ts +128 -0
  200. package/src/telemetry/contract.ts +403 -0
  201. package/src/telemetry/disclosure.ts +19 -0
  202. package/src/telemetry/install-id.ts +226 -0
  203. package/src/telemetry/payload.ts +129 -0
  204. package/src/telemetry/profile/client.ts +150 -0
  205. package/src/telemetry/profile/contract.ts +288 -0
  206. package/src/telemetry/profile/disclosure.ts +14 -0
  207. package/src/telemetry/profile/paths.ts +13 -0
  208. package/src/telemetry/profile/routes.ts +99 -0
  209. package/src/telemetry/profile/service.ts +234 -0
  210. package/src/telemetry/profile/state.ts +189 -0
  211. package/src/telemetry/profile/sync.ts +276 -0
  212. package/src/telemetry/routes.ts +183 -0
  213. package/src/telemetry/scheduler.ts +386 -0
  214. package/src/telemetry/sender.ts +97 -0
  215. package/src/telemetry/state.ts +334 -0
  216. package/src/types/combo-jev-effort-mode.ts +11 -0
  217. package/src/types/config.ts +3 -0
  218. package/src/types/provider.ts +11 -1
  219. package/src/types/request.ts +2 -0
  220. package/src/types/telemetry.ts +15 -0
  221. package/src/types/wire.ts +10 -0
  222. package/src/types.ts +5 -0
  223. package/src/update/index.ts +7 -1
  224. package/src/update/minisign.d.mts +17 -0
  225. package/src/update/minisign.mjs +88 -0
  226. package/src/update/signed-supply.d.mts +59 -0
  227. package/src/update/signed-supply.mjs +289 -0
  228. package/src/update/trust-root.json +38 -0
  229. package/src/update/update-bounded-json.d.mts +4 -0
  230. package/src/update/update-bounded-json.mjs +113 -0
  231. package/src/update/update-bytes.d.mts +2 -0
  232. package/src/update/update-bytes.mjs +23 -0
  233. package/src/update/update-candidate-id.d.mts +2 -0
  234. package/src/update/update-candidate-id.mjs +23 -0
  235. package/src/update/update-checkpoint-codec.d.mts +33 -0
  236. package/src/update/update-checkpoint-codec.mjs +217 -0
  237. package/src/update/update-contracts.d.mts +24 -0
  238. package/src/update/update-contracts.mjs +207 -0
  239. package/src/update/update-signature-threshold.d.mts +12 -0
  240. package/src/update/update-signature-threshold.mjs +47 -0
  241. package/src/update/update-signed-version.d.mts +5 -0
  242. package/src/update/update-signed-version.mjs +25 -0
  243. package/src/update/update-trust-anchor.d.mts +2 -0
  244. package/src/update/update-trust-anchor.mjs +2 -0
  245. package/src/usage/cache-diagnostic.ts +195 -50
  246. package/src/usage/expected-prices.ts +20 -2
  247. package/src/usage/filter-index.ts +1469 -0
  248. package/src/usage/ledger-scanner.ts +245 -4
  249. package/src/usage/source-filter.ts +10 -2
  250. package/src/usage/summary.ts +16 -0
  251. package/src/web-search/parse.ts +244 -38
  252. package/gui/dist/assets/App-BepstgEN.js +0 -59
  253. package/gui/dist/assets/Tray-BinxbEZo.js +0 -1
  254. package/gui/dist/assets/index-C-9X2yaI.js +0 -94
  255. package/gui/dist/assets/index-bnUWypyz.css +0 -2
  256. package/gui/dist/classic/assets/App-DX88_GCW.js +0 -58
  257. package/gui/dist/classic/assets/index-fSP71pLB.js +0 -94
  258. package/gui/dist/classic/assets/quota-summary-y2fl0WBv.js +0 -1
package/src/cli/combo.ts CHANGED
@@ -30,6 +30,7 @@ const USAGE = `Usage:
30
30
  [--native-alias [on|off]] [--allow-metered-targets <on|off>] [--display-name <label|->]
31
31
  [--description <text|->]
32
32
  [--image-input <auto|disabled>] [--reasoning-effort-mode <strict|adaptive>]
33
+ [--jev-effort-mode <decide|client>]
33
34
  [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->]
34
35
  [--decision-quota-signals <on|off|->] [--decision-quota-tiers <JSON|->]
35
36
  [--session-pin <duration|->] (e.g. 20m; keeps a session on JEV's target while active)
@@ -175,6 +176,7 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
175
176
  if (quotaSignals !== undefined && quotaSignals !== "-" || quotaTiers !== undefined && quotaTiers !== "-") throw new CliUsageError("quota settings apply only to jev", USAGE);
176
177
  if (sessionPinMs !== undefined) throw new CliUsageError("--session-pin applies only to the jev strategy", USAGE);
177
178
  if (decisionTimeoutMs != null) throw new CliUsageError("--decision-timeout applies only to the jev strategy", USAGE);
179
+ if (additional.jevEffortMode === "client") throw new CliUsageError("--jev-effort-mode client applies only to the jev strategy", USAGE);
178
180
  };
179
181
  if (strategyRaw !== undefined) requireStrategyFlags(strategyRaw);
180
182
  deps = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
@@ -210,6 +212,7 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
210
212
  if (additional.allowMeteredTargets !== undefined) combo.allowMeteredTargets = additional.allowMeteredTargets;
211
213
  if (additional.imageInput !== undefined) combo.imageInput = additional.imageInput;
212
214
  if (additional.reasoningEffortMode !== undefined) combo.reasoningEffortMode = additional.reasoningEffortMode;
215
+ if (additional.jevEffortMode !== undefined) combo.jevEffortMode = additional.jevEffortMode;
213
216
  if (displayName !== undefined) combo.displayName = displayName === "-" ? "" : displayName;
214
217
  if (description !== undefined) combo.description = description === "-" ? "" : description;
215
218
  if (decisionProvider !== undefined) combo.decisionProvider = decisionProvider === "-" ? null : decisionProvider;
@@ -227,6 +230,7 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
227
230
  delete combo.decisionQuotaSignals;
228
231
  delete combo.decisionQuotaTiers;
229
232
  delete combo.sessionPin;
233
+ delete combo.jevEffortMode;
230
234
  }
231
235
  if (effortMode === undefined && existing?.defaultEffortMode === "force") {
232
236
  combo.defaultEffortMode = effort === "-" ? "fallback" : "force";
@@ -258,6 +258,9 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
258
258
  const raw = action === "set" ? args.shift() : undefined;
259
259
  if (!path || (action === "set" && raw === undefined)) throw new CliUsageError(action === "unset" ? "config path is required" : "config path and value are required", USAGE);
260
260
  rejectArgs(args, USAGE);
261
+ if (pathSegments(path)[0] === "telemetry") {
262
+ throw new CliUsageError("telemetry cannot be modified via ocx config; use `ocx telemetry enable` or `ocx telemetry disable`", USAGE);
263
+ }
261
264
  // #1835/#1838: the read used to happen OUTSIDE the mutation lock, so a concurrent
262
265
  // edit landing between it and the save was reverted by this whole-snapshot write.
263
266
  // `mutatePersistedConfig` reruns this callback against the latest validated disk
@@ -331,14 +334,25 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
331
334
  if (!yes) throw new CliUsageError("import requires --yes", USAGE);
332
335
  rejectArgs(args, USAGE);
333
336
  await withConfigDirHardeningSettled(getConfigDir(), () => {
334
- readCliConfigForMutation();
335
- const imported = validate(loadInput(path));
337
+ const current = readCliConfigForMutation();
338
+ const rawInput = loadInput(path);
339
+ if (rawInput && typeof rawInput === "object" && !Array.isArray(rawInput) && Object.hasOwn(rawInput, "telemetry")) {
340
+ delete (rawInput as Record<string, unknown>).telemetry;
341
+ console.warn("Note: ignored telemetry block during config import; use `ocx telemetry` to manage telemetry consent.");
342
+ }
343
+ const imported = validate(rawInput);
336
344
  withConfigMutationLockSync(() => {
337
345
  const client = readClientConnectionState();
338
346
  if (client.kind === "connected" && (imported.runtimeRole !== "client"
339
347
  || JSON.stringify(imported.client) !== JSON.stringify(client.value))) {
340
348
  throw new Error("config import refused: disconnect the active client before replacing its connection");
341
349
  }
350
+ const persistedTelemetry = readConfigDiagnostics({ passive: true }).config.telemetry ?? current.telemetry;
351
+ if (persistedTelemetry !== undefined) {
352
+ imported.telemetry = structuredClone(persistedTelemetry);
353
+ } else {
354
+ delete imported.telemetry;
355
+ }
342
356
  saveConfig(imported);
343
357
  });
344
358
  });
@@ -1,7 +1,7 @@
1
1
  import { existsSync, lstatSync, readFileSync } from "node:fs";
2
2
  import { DEFAULT_CATALOG_PATH } from "../codex/paths";
3
3
  import { codexSupportedReasoningEfforts } from "../codex/catalog/effort";
4
- import { resolveCodexRuntime } from "../codex/runtime";
4
+ import { resolveCodexRuntime, type ResolvedCodexRuntime } from "../codex/runtime";
5
5
  import {
6
6
  inspectClientCatalogReadiness,
7
7
  type CatalogCompatibilityDeps,
@@ -61,14 +61,14 @@ export interface ClientCatalogProbeDeps extends CatalogCompatibilityDeps {
61
61
  /** Injected in tests; defaults to reading the materialized client catalog off disk. */
62
62
  readCatalogBody?: () => string | null;
63
63
  /**
64
- * A Codex command the caller already resolved, handed over so readiness skips resolving it
64
+ * The Codex runtime the caller already resolved, handed over so readiness skips resolving it
65
65
  * again. General `ocx status` resolves the full runtime for its diagnostics block; the resolver
66
66
  * memo is keyed by discovery scope and holds one entry, so a priority-only readiness resolve
67
67
  * and the full one miss each other and re-probe the same command with `--version` — up to eight
68
- * seconds apiece. Passing the command across adds no cache state, and it cannot disagree with
68
+ * seconds apiece. Passing the selection across adds no cache state, and it cannot disagree with
69
69
  * what status prints because it is the selection status is printing.
70
70
  */
71
- selectedCodexCommand?: string;
71
+ selectedCodexRuntime?: ResolvedCodexRuntime;
72
72
  }
73
73
 
74
74
  export const CONNECT_USAGE = `Usage:
@@ -139,12 +139,14 @@ function readInstalledCatalogBody(): string | null {
139
139
  * to the catalog probe: readiness does not consume alternative-runtime diagnostics. The resolver
140
140
  * keeps this priority-only cache separate from the full discovery used by `ocx status`.
141
141
  *
142
- * A caller that has already resolved passes its selection in through `selectedCodexCommand` rather
142
+ * A caller that has already resolved passes its selection in through `selectedCodexRuntime` rather
143
143
  * than paying for a second `--version` probe of the command it just resolved.
144
144
  */
145
- function observeLocalCodexEffortLadder(selected?: string): ReadonlySet<string> | null {
146
- const command = selected ?? resolveCodexRuntime({ discoverAlternatives: false }).runtime.command;
147
- return codexSupportedReasoningEfforts({ commandCandidates: () => [command] });
145
+ function observeLocalCodexEffortLadder(selected?: ResolvedCodexRuntime): ReadonlySet<string> | null {
146
+ const runtime = selected ?? resolveCodexRuntime({ discoverAlternatives: false }).runtime;
147
+ // The selection travels with its command so the probe can tell an unresolved sentinel, which may
148
+ // fall back to the ChatGPT.app CLI on macOS (#8360), from a bare command that actually ran.
149
+ return codexSupportedReasoningEfforts({ commandCandidates: () => [runtime.command], selectedRuntime: runtime });
148
150
  }
149
151
 
150
152
  /**
@@ -154,8 +156,8 @@ function observeLocalCodexEffortLadder(selected?: string): ReadonlySet<string> |
154
156
  * would run its own probe, which is how the two checks could disagree about the ladder within
155
157
  * a single `ocx connect`.
156
158
  */
157
- function catalogObserver(deps: ClientCatalogProbeDeps | undefined): CatalogCompatibilityDeps {
158
- const selected = deps?.selectedCodexCommand;
159
+ export function catalogObserver(deps: ClientCatalogProbeDeps | undefined): CatalogCompatibilityDeps {
160
+ const selected = deps?.selectedCodexRuntime;
159
161
  return { supportedEfforts: deps?.supportedEfforts ?? (() => observeLocalCodexEffortLadder(selected)) };
160
162
  }
161
163
 
@@ -913,6 +913,10 @@ const commandRunners: Record<string, CommandRunner> = {
913
913
  const { handleCommandcodeCommand } = await import("./integrations");
914
914
  return await handleCommandcodeCommand(deps.args.slice(1));
915
915
  },
916
+ telemetry: async deps => {
917
+ const { handleTelemetryCommand } = await import("./telemetry");
918
+ return await handleTelemetryCommand(deps.args.slice(1));
919
+ },
916
920
  help: async () => {
917
921
  printUsage();
918
922
  return 0;
package/src/cli/doctor.ts CHANGED
@@ -8,6 +8,7 @@
8
8
  * networking. See devlog/_plan/260630_wsl-account-autoswitch/30_*.
9
9
  */
10
10
  import { cliCommandDoctorChecks, collectCliPathDiagnostics } from "./cli-path-diagnostics";
11
+ import { collectBundledBunDiagnostic, formatBundledBunDiagnosticLines } from "./bundled-bun-diagnostic";
11
12
  import { accessSync, constants, existsSync, readFileSync } from "node:fs";
12
13
  import { homedir } from "node:os";
13
14
  import { dirname, join } from "node:path";
@@ -1607,6 +1608,16 @@ export async function runDoctor(args: string[] = []): Promise<void> {
1607
1608
  }
1608
1609
  }
1609
1610
 
1611
+ // The bundled dependency is the install's own runtime, distinct from whatever Bun is running
1612
+ // doctor or serving the proxy. A skipped postinstall (#8361) is invisible here otherwise.
1613
+ // A source checkout or standalone binary has no bundled `bun` dependency, so the
1614
+ // section has nothing to say there and prints no heading.
1615
+ const bundledBunLines = formatBundledBunDiagnosticLines(collectBundledBunDiagnostic());
1616
+ if (bundledBunLines.length > 0) {
1617
+ console.log("\nBundled Bun runtime");
1618
+ for (const line of bundledBunLines) console.log(line);
1619
+ }
1620
+
1610
1621
  console.log("\nWHAM reachability");
1611
1622
  const probe = await probeWham();
1612
1623
  const detail = probe.status !== null ? `status=${probe.status}` : `error=${probe.classification}`;
package/src/cli/help.ts CHANGED
@@ -102,6 +102,7 @@ Usage:
102
102
  ocx config [sub] Validated configuration show/get/set/import/export
103
103
  ocx advisor <status|on|off|set|consent> Advisor sidecar settings and context-sharing consent
104
104
  ocx companion <show|set|reset> Menu-bar and widget companion usage settings
105
+ ocx telemetry <sub> Anonymous usage telemetry status, preview, enable, and disable
105
106
  ocx lab <sub> Inspect Lab evidence and control local automation
106
107
  ocx codex-provider <sub> Confirm custom Codex provider routing: status|allow|revoke
107
108
  ocx chatgpt <sub> Experimental app-server shim: launch|restore|status (macOS)
package/src/cli/init.ts CHANGED
@@ -9,6 +9,7 @@ import { redactUserPath } from "../lib/redact";
9
9
  import { enrichProviderFromCatalog } from "../oauth/key-providers";
10
10
  import { deriveInitProviders } from "../providers/derive";
11
11
  import { pinSponsorsWithinKind } from "../providers/sponsor-order";
12
+ import { maybeShowTelemetryPrompt } from "./telemetry";
12
13
  import type { OcxConfig, OcxProviderConfig } from "../types";
13
14
 
14
15
  /** Parse a setup TCP port; only an empty answer selects the default. */
@@ -293,4 +294,7 @@ export async function runInit(): Promise<void> {
293
294
  } finally {
294
295
  prompt.close();
295
296
  }
297
+ if (configCreated && !process.exitCode) {
298
+ await maybeShowTelemetryPrompt();
299
+ }
296
300
  }
@@ -1,13 +1,19 @@
1
1
  import { createInterface } from "node:readline/promises";
2
+ import { plantUnavailableGuidance } from "../link/child-binary-source";
2
3
  import { assertSshAlias } from "../link/ssh-argv";
3
- import { CliUsageError, RuntimeApiError, runtimeBaseUrl, rejectArgs, takeJsonFlag, takeOption, printData } from "./runtime-api";
4
+ import { CliUsageError, RuntimeApiError, runtimeBaseUrl, rejectArgs, takeFlag, takeJsonFlag, takeOption, printData } from "./runtime-api";
4
5
  import type { LinkCliDeps } from "./link";
5
6
 
6
7
  const FINGERPRINT = /^SHA256:[A-Za-z0-9+/]{16,88}={0,2}$/;
8
+ const SEMVER = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]{1,128})?$/;
7
9
  const ENROLLMENT_DEADLINE_MS = 360_000;
8
10
  const PHASES: Record<string, string> = {
9
11
  remote_port_failed: "remote port selection", remote_port_timeout: "remote port selection",
12
+ remote_plant_failed: "remote ocx-child planting", remote_plant_timeout: "remote ocx-child planting",
13
+ remote_plant_unavailable: "local ocx-child binary resolution",
10
14
  child_preflight_failed: "Child preflight", child_preflight_timeout: "Child preflight",
15
+ child_port_busy: "Child port availability preflight",
16
+ child_external_provider_conflict: "Child Codex config ownership check",
11
17
  child_restart_unsupported: "Child restart preflight", child_curl_missing: "Child curl preflight",
12
18
  home_setup_failed: "Home setup", home_setup_timeout: "Home setup",
13
19
  remote_connect_failed: "Child enrollment", remote_connect_timeout: "Child enrollment",
@@ -16,28 +22,110 @@ const PHASES: Record<string, string> = {
16
22
  child_runtime_not_client: "Child runtime role verification",
17
23
  remote_platform_unsupported: "remote platform verification", remote_ocx_missing: "remote OpenCodex discovery",
18
24
  };
19
- const RECOVERY = "Run ocx disconnect and ocx restart on the Child before retrying.";
25
+ const RECOVERY_FULL = "Run ocx disconnect and ocx restart on the Child before retrying.";
26
+ const RECOVERY_EPHEMERAL = "Run ~/.cache/opencodex/bin/ocx-child detach on the Child before retrying.";
20
27
  type LinkRequest = <T>(path: string, init: RequestInit, deps: LinkCliDeps) => Promise<T>;
21
28
 
22
- function record(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); }
23
- function offered(value: unknown): { alias: string; fingerprint: string; keyType: string; ocxVersion: string } {
24
- if (!record(value) || Object.keys(value).sort().join(",") !== "alias,fingerprint,keyType,ocxVersion"
25
- || typeof value.alias !== "string" || typeof value.fingerprint !== "string" || !FINGERPRINT.test(value.fingerprint)
26
- || typeof value.keyType !== "string" || !/^[A-Za-z0-9@._+-]{1,64}$/.test(value.keyType)) throw new Error("Invalid host probe response");
27
- if (typeof value.ocxVersion !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]{1,128})?$/.test(value.ocxVersion)) throw new Error("Invalid host version response");
28
- return { alias: value.alias, fingerprint: value.fingerprint, keyType: value.keyType, ocxVersion: value.ocxVersion };
29
+ interface ParsedProbeOffer {
30
+ alias: string;
31
+ fingerprint: string;
32
+ keyType: string;
33
+ ocxVersion: string | null;
34
+ runtimeKind?: "full" | "ephemeral" | "missing";
35
+ targetTriple?: string | null;
36
+ plantable?: boolean;
37
+ binarySizeBytes?: number;
38
+ plantUnavailableReason?: string;
39
+ legacyExact: boolean;
40
+ }
41
+
42
+ function record(value: unknown): value is Record<string, unknown> {
43
+ return value !== null && typeof value === "object" && !Array.isArray(value);
44
+ }
45
+
46
+ const PROBE_ALLOWED_KEYS = new Set([
47
+ "alias", "fingerprint", "keyType", "ocxVersion",
48
+ "runtimeKind", "targetTriple", "plantable", "binarySizeBytes", "plantUnavailableReason",
49
+ ]);
50
+ const CONFIRM_ALLOWED_KEYS = new Set([
51
+ "alias", "fingerprint", "ocxVersion",
52
+ "runtimeKind", "targetTriple", "plantable", "binarySizeBytes", "plantUnavailableReason",
53
+ ]);
54
+
55
+ function parseOffered(value: unknown, allowMissing: boolean): ParsedProbeOffer {
56
+ if (!record(value)) throw new Error("Invalid host probe response");
57
+ const keys = Object.keys(value);
58
+ if (keys.some(k => !PROBE_ALLOWED_KEYS.has(k))) throw new Error("Invalid host probe response");
59
+ if (typeof value.alias !== "string" || typeof value.fingerprint !== "string" || !FINGERPRINT.test(value.fingerprint)
60
+ || typeof value.keyType !== "string" || !/^[A-Za-z0-9@._+-]{1,64}$/.test(value.keyType)) {
61
+ throw new Error("Invalid host probe response");
62
+ }
63
+ const legacyExact = keys.slice().sort().join(",") === "alias,fingerprint,keyType,ocxVersion";
64
+ if (!allowMissing && !legacyExact) throw new Error("Invalid host probe response");
65
+ if (value.ocxVersion === null) {
66
+ if (!allowMissing || value.runtimeKind !== "missing") throw new Error("Invalid host version response");
67
+ } else if (typeof value.ocxVersion !== "string" || !SEMVER.test(value.ocxVersion)) {
68
+ throw new Error("Invalid host version response");
69
+ }
70
+ if (value.runtimeKind !== undefined && value.runtimeKind !== "full" && value.runtimeKind !== "ephemeral" && value.runtimeKind !== "missing") {
71
+ throw new Error("Invalid host probe response");
72
+ }
73
+ if (value.targetTriple !== undefined && value.targetTriple !== null && (typeof value.targetTriple !== "string" || value.targetTriple.length > 64)) {
74
+ throw new Error("Invalid host probe response");
75
+ }
76
+ if (value.plantable !== undefined && typeof value.plantable !== "boolean") throw new Error("Invalid host probe response");
77
+ if (value.binarySizeBytes !== undefined && (typeof value.binarySizeBytes !== "number" || !Number.isSafeInteger(value.binarySizeBytes) || value.binarySizeBytes <= 0)) {
78
+ throw new Error("Invalid host probe response");
79
+ }
80
+ if (value.plantUnavailableReason !== undefined && typeof value.plantUnavailableReason !== "string") {
81
+ throw new Error("Invalid host probe response");
82
+ }
83
+ return {
84
+ alias: value.alias,
85
+ fingerprint: value.fingerprint,
86
+ keyType: value.keyType,
87
+ ocxVersion: value.ocxVersion,
88
+ ...(value.runtimeKind !== undefined ? { runtimeKind: value.runtimeKind } : {}),
89
+ ...(value.targetTriple !== undefined ? { targetTriple: value.targetTriple } : {}),
90
+ ...(value.plantable !== undefined ? { plantable: value.plantable } : {}),
91
+ ...(value.binarySizeBytes !== undefined ? { binarySizeBytes: value.binarySizeBytes } : {}),
92
+ ...(value.plantUnavailableReason !== undefined ? { plantUnavailableReason: value.plantUnavailableReason } : {}),
93
+ legacyExact,
94
+ };
95
+ }
96
+
97
+ function validateConfirmed(value: unknown, alias: string, fingerprint: string, allowMissing: boolean): void {
98
+ if (!record(value)) throw new Error("Invalid host confirmation response");
99
+ const keys = Object.keys(value);
100
+ if (keys.some(k => !CONFIRM_ALLOWED_KEYS.has(k))) throw new Error("Invalid host confirmation response");
101
+ if (value.alias !== alias || value.fingerprint !== fingerprint) throw new Error("Invalid host confirmation response");
102
+ const legacyExact = keys.slice().sort().join(",") === "alias,fingerprint,ocxVersion";
103
+ if (!allowMissing && !legacyExact) throw new Error("Invalid host confirmation response");
104
+ if (value.ocxVersion === null) {
105
+ if (!allowMissing || value.runtimeKind !== "missing") throw new Error("Invalid host confirmation response");
106
+ } else if (typeof value.ocxVersion !== "string" || !SEMVER.test(value.ocxVersion)) {
107
+ throw new Error("Invalid host confirmation response");
108
+ }
109
+ }
110
+
111
+ function formatSizeMb(bytes?: number): string {
112
+ if (!bytes || !Number.isFinite(bytes) || bytes <= 0) return "~0.9 MB";
113
+ return `~${Math.max(0.1, bytes / (1024 * 1024)).toFixed(1)} MB`;
29
114
  }
30
115
 
31
116
  export async function runLinkEnrollment(command: "probe" | "add", args: string[], deps: LinkCliDeps, request: LinkRequest, usage: string): Promise<void> {
32
117
  const wantsJson = takeJsonFlag(args);
118
+ const plantFlag = takeFlag(args, "--plant");
33
119
  const expected = takeOption(args, "--expect-fingerprint");
34
120
  const alias = args.shift();
35
121
  if (!alias) throw new CliUsageError(command + " requires an SSH alias", usage);
36
122
  try { assertSshAlias(alias); } catch { throw new CliUsageError("Invalid SSH alias", usage); }
37
123
  rejectArgs(args, usage);
38
124
  if (command === "probe" && expected !== undefined) throw new CliUsageError("--expect-fingerprint is only for link add", usage);
125
+ if (command === "probe" && plantFlag) throw new CliUsageError("--plant is only for link add", usage);
39
126
  if (expected !== undefined && !FINGERPRINT.test(expected)) throw new CliUsageError("Expected a SHA256 SSH fingerprint", usage);
40
- if (command === "add" && !expected && !(deps.stdinImpl ?? process.stdin).isTTY) {
127
+ const isTTY = Boolean((deps.stdinImpl ?? process.stdin).isTTY);
128
+ if (command === "add" && !expected && !isTTY) {
41
129
  throw new CliUsageError("Non-interactive link add requires --expect-fingerprint", usage);
42
130
  }
43
131
  const timeout = deps.enrollmentTimeoutMs ?? ENROLLMENT_DEADLINE_MS;
@@ -48,6 +136,7 @@ export async function runLinkEnrollment(command: "probe" | "add", args: string[]
48
136
  timer = setTimeout(() => { controller.abort(); reject(new Error("Link enrollment timed out; its outcome is uncertain. Run ocx link status on the Home and ocx connect status on the Child before retrying.")); }, timeout);
49
137
  });
50
138
  let boundDeps = deps;
139
+ let ephemeralFlow = false;
51
140
  const post = async <T>(path: string, body: unknown): Promise<T> => {
52
141
  controller.signal.throwIfAborted();
53
142
  const result = await request<T>(path, { method: "POST", redirect: "error", signal: controller.signal, headers: { "content-type": "application/json" }, body: JSON.stringify(body) }, boundDeps);
@@ -55,38 +144,75 @@ export async function runLinkEnrollment(command: "probe" | "add", args: string[]
55
144
  return result;
56
145
  };
57
146
  let rl: ReturnType<typeof createInterface> | undefined;
147
+ const askYes = async (promptText: string): Promise<boolean> => {
148
+ rl ??= createInterface({ input: deps.stdinImpl ?? process.stdin, output: process.stderr });
149
+ return (await rl.question(promptText, { signal: controller.signal })).trim() === "yes";
150
+ };
58
151
  const work = async () => {
59
152
  boundDeps = { ...deps, baseUrl: await runtimeBaseUrl(deps) };
60
153
  controller.signal.throwIfAborted();
61
- const probe = offered(await post<unknown>("/api/link/probe", { alias, includeVersion: true }));
154
+ const probeReq = command === "add" ? { alias, includeVersion: true, allowMissing: true } : { alias, includeVersion: true };
155
+ const probe = parseOffered(await post<unknown>("/api/link/probe", probeReq), command === "add");
62
156
  if (probe.alias !== alias) throw new Error("Host probe alias did not match");
63
- if (command === "probe") { printData(probe, wantsJson, [probe.alias + " " + probe.keyType + " " + probe.fingerprint + " opencodex " + probe.ocxVersion]); return; }
157
+ if (command === "probe") {
158
+ const payload = { alias: probe.alias, fingerprint: probe.fingerprint, keyType: probe.keyType, ocxVersion: probe.ocxVersion! };
159
+ printData(payload, wantsJson, [probe.alias + " " + probe.keyType + " " + probe.fingerprint + " opencodex " + probe.ocxVersion]);
160
+ return;
161
+ }
64
162
  if (expected && expected !== probe.fingerprint) throw new CliUsageError("The offered host fingerprint does not match --expect-fingerprint");
65
- if (!expected) {
66
- let approved: boolean;
67
- if (deps.confirmFingerprint) approved = await deps.confirmFingerprint(probe);
68
- else {
69
- rl = createInterface({ input: deps.stdinImpl ?? process.stdin, output: process.stderr });
70
- approved = (await rl.question("Confirm " + alias + " " + probe.keyType + " " + probe.fingerprint + " opencodex " + probe.ocxVersion + " (type yes): ", { signal: controller.signal })).trim() === "yes";
163
+ let shouldPlant = false;
164
+ ephemeralFlow = probe.runtimeKind === "ephemeral" || probe.runtimeKind === "missing";
165
+ if (probe.runtimeKind === "missing") {
166
+ if (probe.plantable !== true) {
167
+ throw new Error("ocx was not found on " + alias + ". " + plantUnavailableGuidance(probe.plantUnavailableReason, probe.targetTriple ?? null));
168
+ }
169
+ if (!isTTY && !plantFlag) {
170
+ throw new CliUsageError("Remote host has no OpenCodex runtime; pass --plant alongside --expect-fingerprint to plant lightweight ocx-child.", usage);
71
171
  }
172
+ const sizeLabel = formatSizeMb(probe.binarySizeBytes);
173
+ if (!expected) {
174
+ const approved = deps.confirmFingerprint
175
+ ? await deps.confirmFingerprint({ alias: probe.alias, fingerprint: probe.fingerprint, keyType: probe.keyType, ocxVersion: null, runtimeKind: "missing", binarySizeBytes: probe.binarySizeBytes })
176
+ : await askYes(`Confirm ${alias} ${probe.keyType} ${probe.fingerprint} — plant lightweight ocx-child (${sizeLabel}) and connect? (type yes): `);
177
+ controller.signal.throwIfAborted();
178
+ if (!approved) throw new CliUsageError("Host fingerprint and ocx-child plant were not confirmed");
179
+ } else if (!plantFlag) {
180
+ const approved = deps.confirmFingerprint
181
+ ? await deps.confirmFingerprint({ alias: probe.alias, fingerprint: probe.fingerprint, keyType: probe.keyType, ocxVersion: null, runtimeKind: "missing", binarySizeBytes: probe.binarySizeBytes })
182
+ : await askYes(`Plant lightweight ocx-child (${sizeLabel}) on ${alias} and connect? (type yes): `);
183
+ controller.signal.throwIfAborted();
184
+ if (!approved) throw new CliUsageError("Planting ocx-child was not confirmed");
185
+ }
186
+ shouldPlant = true;
187
+ } else if (!expected) {
188
+ const approved = deps.confirmFingerprint
189
+ ? await deps.confirmFingerprint({ alias: probe.alias, fingerprint: probe.fingerprint, keyType: probe.keyType, ...(probe.ocxVersion !== null ? { ocxVersion: probe.ocxVersion } : {}) })
190
+ : await askYes("Confirm " + alias + " " + probe.keyType + " " + probe.fingerprint + " opencodex " + probe.ocxVersion + " (type yes): ");
72
191
  controller.signal.throwIfAborted();
73
192
  if (!approved) throw new CliUsageError("Host fingerprint was not confirmed");
74
193
  }
75
- const confirm = await post<unknown>("/api/link/confirm-host", { alias, fingerprint: probe.fingerprint });
76
- if (!record(confirm) || Object.keys(confirm).sort().join(",") !== "alias,fingerprint,ocxVersion" || confirm.alias !== alias || confirm.fingerprint !== probe.fingerprint
77
- || typeof confirm.ocxVersion !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]{1,128})?$/.test(confirm.ocxVersion)) throw new Error("Invalid host confirmation response");
78
- const result = await post<unknown>("/api/link/apply", { alias, fingerprint: probe.fingerprint });
194
+ const sendAllowMissing = shouldPlant || probe.runtimeKind === "missing";
195
+ const confirm = await post<unknown>("/api/link/confirm-host", { alias, fingerprint: probe.fingerprint, ...(sendAllowMissing ? { allowMissing: true } : {}) });
196
+ validateConfirmed(confirm, alias, probe.fingerprint, sendAllowMissing);
197
+ const result = await post<unknown>("/api/link/apply", { alias, fingerprint: probe.fingerprint, ...(shouldPlant ? { plant: true } : {}) });
79
198
  if (!record(result) || Object.keys(result).join(",") !== "linkId" || typeof result.linkId !== "string" || !/^lnk_[0-9a-f]{16}$/.test(result.linkId)) throw new Error("Invalid link apply response");
80
- printData({ linkId: result.linkId, alias, state: "connected", childRole: "client" }, wantsJson, ["Connected " + alias + " as a Child (" + result.linkId + ")."]);
199
+ printData({ linkId: result.linkId, alias, state: "connected", childRole: "client", ...(shouldPlant ? { planted: true } : {}) }, wantsJson, ["Connected " + alias + " as a Child (" + result.linkId + ")."]);
81
200
  };
82
201
  try { await Promise.race([work(), expiry]); }
83
202
  catch (error) {
84
203
  if (error instanceof RuntimeApiError && record(error.body)) {
85
204
  const code = record(error.body.error) ? error.body.error.code : undefined;
86
205
  if (code === "remote_platform_unsupported" && error.body.residual !== true) throw new Error("The remote shell cannot run this Remote Link workflow. Update OpenCodex on Home and check PowerShell on the Child.");
206
+ if (code === "child_port_busy") throw new Error("The target port on the Child is already in use by another process; no Child files were modified.");
207
+ if (code === "child_preflight_output_limit") throw new Error("The Child's ocx config show --json output exceeded the Remote Link preflight limit; trim the Child's saved configuration and retry.");
208
+ if (code === "child_external_provider_conflict") throw new Error("The Child's ~/.codex/config.toml is already managed by another model provider or custom base URL; no Child files were modified.");
87
209
  const phase = typeof code === "string" && Object.hasOwn(PHASES, code) ? PHASES[code] : undefined;
88
- const message = phase ? "Remote Link failed during " + phase : error.message;
89
- if (phase || error.body.residual === true) throw new Error(message + (error.body.residual === true ? ". " + RECOVERY : ""));
210
+ // The server's hint is the Child's own bounded, redacted reason (#8357); a phase name
211
+ // alone left every failure to SSH reproduction and source reading.
212
+ const hint = record(error.body.error) && typeof error.body.error.hint === "string" ? error.body.error.hint : "";
213
+ const message = phase ? "Remote Link failed during " + phase + (hint ? ": " + hint : "") : error.message;
214
+ const recovery = ephemeralFlow ? RECOVERY_EPHEMERAL : RECOVERY_FULL;
215
+ if (phase || error.body.residual === true) throw new Error(message + (error.body.residual === true ? ". " + recovery : ""));
90
216
  }
91
217
  throw error;
92
218
  } finally {
@@ -95,3 +221,4 @@ export async function runLinkEnrollment(command: "probe" | "add", args: string[]
95
221
  rl?.close();
96
222
  }
97
223
  }
224
+
@@ -0,0 +1,49 @@
1
+ import { usableLocalControlSocket } from "../lib/local-control-socket";
2
+ import type { RuntimeApiDeps } from "./runtime-api";
3
+
4
+ export interface LocalControlDeps {
5
+ /** Test seam: the socket a live runtime on this port exposes, or null. */
6
+ localControlSocket?: (port: number) => string | null;
7
+ }
8
+
9
+ /**
10
+ * Send one `ocx link status` read over the runtime's local control socket when it has one (#8184).
11
+ * A hub whose public listener is not loopback refuses the admin token on its TCP listeners, and the
12
+ * socket is the ingress that may accept it. A runtime without the socket (Windows, a loopback bind,
13
+ * an older version), or one whose socket cannot be reached, is asked over TCP exactly as before.
14
+ */
15
+ export async function viaLocalControlSocket<T, D extends RuntimeApiDeps & LocalControlDeps>(
16
+ baseUrl: string,
17
+ deps: D,
18
+ request: (deps: D) => Promise<T>,
19
+ ): Promise<T> {
20
+ const tcp = { ...deps, baseUrl };
21
+ if (deps.baseUrl) return request(tcp);
22
+ let port: number;
23
+ try { port = Number(new URL(baseUrl).port); } catch { return request(tcp); }
24
+ const socket = (deps.localControlSocket ?? usableLocalControlSocket)(port);
25
+ if (!socket) return request(tcp);
26
+ const fetchImpl = deps.fetchImpl ?? fetch;
27
+ // The marker is set by the transport itself, never inferred from the answer. A runtime that
28
+ // answers 503 with an empty or non-JSON body is still answering, and replacing that answer with
29
+ // the TCP listener's 403 would be a worse report than the one the socket gave.
30
+ let unreachable = false;
31
+ try {
32
+ return await request({
33
+ ...deps,
34
+ baseUrl: "http://localhost",
35
+ fetchImpl: (async (url: string | URL | Request, init?: RequestInit) => {
36
+ try {
37
+ return await fetchImpl(url, { ...init, unix: socket } as RequestInit);
38
+ } catch (error) {
39
+ unreachable = true;
40
+ throw error;
41
+ }
42
+ }) as typeof fetch,
43
+ });
44
+ } catch (error) {
45
+ // Only a transport failure falls back: an answer from the socket is the runtime's answer.
46
+ if (unreachable) return request(tcp);
47
+ throw error;
48
+ }
49
+ }