@bitkyc08/opencodex 2.41.0 → 2.43.0-preview.20260906

package/src/providers/model-rename-startup.ts

@@ -1,10 +1,47 @@
-import { saveConfig } from "../config";
+import { mutatePersistedConfig } from "../config";
 import { projectModelRenames } from "./model-rename-migration";
 import type { OcxConfig } from "../types";
 
 export interface ModelRenameStartupDeps {
   project: typeof projectModelRenames;
-  save: (config: OcxConfig) => void;
+  /** Injected writer for tests and callers that own their own persistence. */
+  save?: (config: OcxConfig) => void;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Recursive key-by-key adopt: descend into a changed container, replace only changed leaves. */
+function adoptRecord(live: Record<string, unknown>, next: Record<string, unknown>): void {
+  for (const key of Object.keys(live)) {
+    if (!(key in next)) delete live[key];
+  }
+  for (const [key, value] of Object.entries(next)) {
+    const current = live[key];
+    if (JSON.stringify(current) === JSON.stringify(value)) continue;
+    if (isPlainObject(current) && isPlainObject(value)) {
+      adoptRecord(current, value);
+      continue;
+    }
+    live[key] = value;
+  }
+}
+
+/**
+ * Copy `source` onto `target` in place, touching only the keys that actually differ.
+ *
+ * A clear-and-reassign preserves the top-level object identity while silently detaching every
+ * nested sub-object a caller still holds a live reference to. The renames rewrite one provider
+ * row at a time, so every sibling row — and the `providers` container itself — must survive
+ * with its identity intact.
+ */
+function adoptConfig(target: OcxConfig, source: OcxConfig): void {
+  if (target === source) return;
+  adoptRecord(
+    target as unknown as Record<string, unknown>,
+    structuredClone(source) as unknown as Record<string, unknown>,
+  );
 }
 
 /**
@@ -15,14 +52,41 @@ export interface ModelRenameStartupDeps {
  * recoverable from the config alone. This one only rewrites model ids that the
  * registry itself no longer seeds, and the pre-migration value is a string this
  * file still names, so the change is reversible by hand.
+ *
+ * Persistence failure is not fatal. This runs inside `startServer`, so a missing, malformed or
+ * contended config degrades to a warning plus the in-memory projection rather than taking the
+ * boot path down.
  */
 export function runModelRenameStartupMigration(
   config: OcxConfig,
-  deps: ModelRenameStartupDeps = { project: projectModelRenames, save: saveConfig },
+  deps: ModelRenameStartupDeps = { project: projectModelRenames },
 ): OcxConfig {
-  const projection = deps.project(config);
-  for (const warning of projection.warnings) console.warn(`[model-rename-migration] ${warning}`);
-  if (!projection.changed) return projection.config;
-  deps.save(projection.config);
-  return projection.config;
+  const projection = deps.project(structuredClone(config));
+  if (!projection.changed) {
+    for (const warning of projection.warnings) console.warn(`[model-rename-migration] ${warning}`);
+    return config;
+  }
+  if (deps.save) {
+    deps.save(projection.config);
+    adoptConfig(config, projection.config);
+    for (const warning of projection.warnings) console.warn(`[model-rename-migration] ${warning}`);
+    return config;
+  }
+  const outcome = mutatePersistedConfig(fresh => {
+    const next = deps.project(fresh);
+    if (next.changed) adoptConfig(fresh, next.config);
+    return { changed: next.changed, value: next };
+  });
+  if (outcome.status === "unavailable") {
+    console.warn(
+      `[model-rename-migration] persistence unavailable (${outcome.reason}); applying the renames `
+      + "in memory for this run only.",
+    );
+    adoptConfig(config, projection.config);
+    for (const warning of projection.warnings) console.warn(`[model-rename-migration] ${warning}`);
+    return config;
+  }
+  adoptConfig(config, outcome.value.config);
+  for (const warning of outcome.value.warnings) console.warn(`[model-rename-migration] ${warning}`);
+  return config;
 }

package/src/providers/muse-subscription-usage.ts

@@ -0,0 +1,95 @@
+/**
+ * Meta's subscription-usage SSE frame.
+ *
+ * Meta publishes no quota endpoint — 17 plausible REST paths were probed and every one
+ * 404s, and no `x-ratelimit-*` header appears on any of three measured request shapes
+ * (devlog/_plan/260903_muse_spark_plan_oauth/003 §E). The only machine-readable usage
+ * Meta emits arrives mid-stream, as one extra event alongside the ordinary
+ * `response.*` sequence on a streaming `POST /v1/responses`.
+ *
+ * That inverts the usual seam: this module is fed by the request path, not by a probe,
+ * and nothing can refresh its output on demand — obtaining a newer value would mean
+ * spending a real inference turn.
+ *
+ * Measured payload (2026-09-03):
+ *
+ * ```json
+ * { "type": "response.subscription_usage",
+ *   "subscription": {
+ *     "tier": "27681393394859588",
+ *     "window": { "used_percent": 0, "resets_at": 1788431188, "window_duration_mins": 300 },
+ *     "weekly": { "used_percent": 0, "resets_at": 1788739200 } } }
+ * ```
+ */
+import { asRecord, normalizePercent, normalizeResetAt, toFiniteNumber } from "./quota-wire";
+import type { ProviderQuota, ProviderQuotaWindow } from "./quota-types";
+
+/** The SSE frame type Meta emits on streaming turns. */
+export const MUSE_SUBSCRIPTION_USAGE_TYPE = "response.subscription_usage";
+
+/** Meta's five-hour window, identified by its declared duration rather than assumed. */
+const FIVE_HOUR_WINDOW_MINS = 300;
+
+/** True when a parsed SSE payload is the subscription-usage frame. */
+export function isMuseSubscriptionUsagePayload(payload: unknown): boolean {
+  return asRecord(payload)?.type === MUSE_SUBSCRIPTION_USAGE_TYPE;
+}
+
+/**
+ * Translate the frame into a `ProviderQuota`.
+ *
+ * Returns null — never throws — for anything unrecognizable. This runs inside SSE
+ * inspection on a live request, where the only acceptable failure is silence: a parse
+ * error must not cost the user their turn.
+ *
+ * `subscription.tier` is deliberately dropped. It is an opaque numeric id, not the plan
+ * label the Muse CLI prints, so surfacing it would show a meaningless number.
+ */
+export function parseMuseSubscriptionUsage(payload: unknown): ProviderQuota | null {
+  const subscription = asRecord(asRecord(payload)?.subscription);
+  if (!subscription) return null;
+
+  const quota: ProviderQuota = { updatedAt: Date.now() };
+  let sawWindow = false;
+
+  const window = asRecord(subscription.window);
+  if (window) {
+    const percent = normalizePercent(window.used_percent);
+    const resetAt = normalizeResetAt(window.resets_at);
+    const durationMins = toFiniteNumber(window.window_duration_mins);
+    if (percent !== undefined) {
+      if (durationMins === FIVE_HOUR_WINDOW_MINS) {
+        quota.fiveHourPercent = percent;
+        if (resetAt !== undefined) quota.fiveHourResetAt = resetAt;
+        sawWindow = true;
+      } else {
+        // A window of some other length is NOT forced into the five-hour slot: filing a
+        // ten-hour window there would understate usage by the ratio of the two windows,
+        // and would do so with full confidence. Carry it with its real duration instead.
+        const custom: ProviderQuotaWindow = {
+          label: durationMins === undefined ? "subscription" : `${durationMins}m`,
+          percent,
+          ...(resetAt !== undefined ? { resetAt } : {}),
+        };
+        quota.customWindows = [...(quota.customWindows ?? []), custom];
+        sawWindow = true;
+      }
+    }
+  }
+
+  const weekly = asRecord(subscription.weekly);
+  if (weekly) {
+    const percent = normalizePercent(weekly.used_percent);
+    if (percent !== undefined) {
+      quota.weeklyPercent = percent;
+      const resetAt = normalizeResetAt(weekly.resets_at);
+      if (resetAt !== undefined) quota.weeklyResetAt = resetAt;
+      sawWindow = true;
+    }
+  }
+
+  // Either window may be absent independently, but a payload carrying neither says
+  // nothing — returning a bare `updatedAt` would publish an empty row that the GUI
+  // would render as a quota with no bars.
+  return sawWindow ? quota : null;
+}

package/src/providers/openai-sidecar.ts

@@ -7,10 +7,11 @@ import {
   resolveCodexAuthContext,
   type CodexAccountSelectionAdmission,
   type CodexAuthContext,
+  type CodexAuthPolicyConfig,
 } from "../codex/auth-context";
 import { recordCodexUpstreamOutcome, type CodexUpstreamOutcome } from "../codex/routing";
 import { extractAccountId } from "../oauth/chatgpt";
-import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential } from "../server/auth-cors";
+import { ForwardAdmissionCredentialError, validateForwardAdmissionCredential, type DataPlaneAdmission } from "../server/auth-cors";
 import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
 import {
   CODEX_FORWARD_BASE_URL,
@@ -78,6 +79,8 @@ export function listOpenAiForwardSidecarCandidates(config: OcxConfig): OpenAiFor
 
 function directSidecarHeaders(
   incomingHeaders: Headers,
+  config: CodexAuthPolicyConfig,
+  admission?: Pick<DataPlaneAdmission, "source">,
 ): Headers | undefined {
   const bearer = incomingHeaders.get("authorization")?.replace(/^Bearer\s+/i, "").trim();
   if (!bearer) return undefined;
@@ -89,7 +92,7 @@ function directSidecarHeaders(
   // intentional ChatGPT-auth operation instead of silently reclassifying any JWT-shaped
   // provider credential as a Codex bearer.
   if (!requestedAccountId || requestedAccountId !== derivedAccountId) return undefined;
-  const selected = headersForCodexAuthContext(incomingHeaders, { kind: "main", accountId: null });
+  const selected = headersForCodexAuthContext(incomingHeaders, { kind: "main", accountId: null }, config, undefined, admission);
   return selected;
 }
 
@@ -99,10 +102,13 @@ export async function resolveFirstUsableOpenAiSidecar(
   config: OcxConfig,
   options: {
     exactAccount?: ExactOpenAiSidecarAccount;
+    admission?: Pick<DataPlaneAdmission, "source">;
+    codexAuthPolicy?: CodexAuthPolicyConfig;
     beginCodexAccountSelection?: () => CodexAccountSelectionAdmission | undefined;
   } = {},
 ): Promise<ResolvedOpenAiForwardSidecar | undefined> {
   const { exactAccount } = options;
+  const policy = options.codexAuthPolicy ?? config;
   let callerBearerMayBeForwarded = true;
   try {
     validateForwardAdmissionCredential(incomingHeaders, config);
@@ -116,10 +122,13 @@ export async function resolveFirstUsableOpenAiSidecar(
       // credential directly even when the provider is globally Direct, and never
       // consult Pool active state, affinity, probes, or alternates.
       const authContext = await resolveCodexAuthContext(incomingHeaders, config, "pool", {
+        codexAuthPolicy: policy,
         accountId: exactAccount.accountId,
         modelId: exactAccount.modelId,
+        admission: options.admission,
         beginCodexAccountSelection: options.beginCodexAccountSelection,
       });
+      const selectedHeaders = headersForCodexAuthContext(incomingHeaders, authContext, policy, exactAccount.modelId, options.admission);
       if ((authContext.kind !== "pool" && authContext.kind !== "main-pool")
         || !isCodexAuthContextUsable(authContext, config)) {
         // Exact selection is fail-closed. A generation/runtime-state race must not fall through
@@ -129,7 +138,7 @@ export async function resolveFirstUsableOpenAiSidecar(
       return {
         ...candidate,
         authContext,
-        headers: headersForCodexAuthContext(incomingHeaders, authContext),
+        headers: selectedHeaders,
         recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(
           config,
           authContext.accountId,
@@ -149,7 +158,7 @@ export async function resolveFirstUsableOpenAiSidecar(
     }
     if (candidate.accountMode === "direct") {
       if (!callerBearerMayBeForwarded || !hasCallerCodexBearer(incomingHeaders)) continue;
-      const headers = directSidecarHeaders(incomingHeaders);
+      const headers = directSidecarHeaders(incomingHeaders, policy, options.admission);
       if (!headers) continue;
       return {
         ...candidate,
@@ -158,13 +167,16 @@ export async function resolveFirstUsableOpenAiSidecar(
       };
     }
     const authContext = await resolveCodexAuthContext(incomingHeaders, config, candidate.accountMode, {
+      codexAuthPolicy: policy,
+      admission: options.admission,
       beginCodexAccountSelection: options.beginCodexAccountSelection,
     });
+    const selectedHeaders = headersForCodexAuthContext(incomingHeaders, authContext, policy, undefined, options.admission);
     if (!isCodexAuthContextUsable(authContext, config)) continue;
     return {
       ...candidate,
       authContext,
-      headers: headersForCodexAuthContext(incomingHeaders, authContext),
+      headers: selectedHeaders,
       ...(authContext.kind === "pool" || authContext.kind === "main-pool"
         ? {
           recordOutcome: (outcome: CodexUpstreamOutcome) => recordCodexUpstreamOutcome(

package/src/providers/openai-tiers-destination.ts

@@ -0,0 +1,102 @@
+import type { OcxProviderConfig } from "../types";
+import { openaiResponsesUrl } from "../adapters/openai-responses-url";
+
+export const OPENAI_CODEX_PROVIDER_ID = "openai";
+export const LEGACY_OPENAI_MULTI_PROVIDER_ID = "openai-multi";
+export const OPENAI_API_PROVIDER_ID = "openai-apikey";
+export const LEGACY_CHATGPT_PROVIDER_ID = "chatgpt";
+
+export const CODEX_FORWARD_BASE_URL = "https://chatgpt.com/backend-api/codex";
+
+function normalizedBaseUrl(value: string): string | undefined {
+  try {
+    const url = new URL(value.trim());
+    if (url.username || url.password || url.search || url.hash) return undefined;
+    const path = url.pathname.replace(/\/+$/, "");
+    return `${url.origin}${path}`;
+  } catch {
+    return undefined;
+  }
+}
+
+export function isCanonicalOpenAiForwardProvider(provider: OcxProviderConfig): boolean {
+  return provider.adapter === "openai-responses"
+    && provider.authMode === "forward"
+    && normalizedBaseUrl(provider.baseUrl) === CODEX_FORWARD_BASE_URL;
+}
+
+const OPENAI_API_ORIGIN = "https://api.openai.com";
+const OPENAI_API_BASE_URL = `${OPENAI_API_ORIGIN}/v1`;
+const OPENAI_API_RESPONSES_URL = `${OPENAI_API_BASE_URL}/responses`;
+
+/**
+ * The Responses endpoint the adapter would actually POST key-auth traffic to, normalized.
+ *
+ * Mirrors the adapter's own construction (`src/adapters/openai-responses.ts`): a configured
+ * `responsesPath` is appended to the base verbatim, and only the default branch runs the
+ * `/v1/responses` suffix normalization. Classifying on the base URL alone would call
+ * `baseUrl: "https://api.openai.com"` with `responsesPath: "/other"` official even though that
+ * request never reaches the official Responses endpoint.
+ */
+function resolvedResponsesEndpoint(provider: OcxProviderConfig): string | undefined {
+  try {
+    const raw = provider.responsesPath === undefined
+      ? openaiResponsesUrl(provider.baseUrl)
+      : `${provider.baseUrl.replace(/\/$/, "")}${provider.responsesPath}`;
+    return normalizedBaseUrl(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+function isOfficialOpenAiResponsesDestination(provider: OcxProviderConfig): boolean {
+  // Exact normalized URL keeps lookalike/suffix hosts out of this set: `api.openai.com.evil.test`
+  // resolves to its own origin, never to the official one.
+  return resolvedResponsesEndpoint(provider) === OPENAI_API_RESPONSES_URL;
+}
+
+/**
+ * Whether this provider can serve `POST /responses/compact`. The canonical ChatGPT
+ * backend can, and so can the official OpenAI API — but an arbitrary gateway that
+ * merely speaks the Responses wire cannot, and calling it there fails compaction
+ * with an unhelpful error instead of falling back to a routed summary (#422).
+ */
+export function supportsNativeResponsesCompactEndpoint(
+  providerName: string,
+  provider: OcxProviderConfig,
+): boolean {
+  if (isCanonicalOpenAiForwardProvider(provider)) return true;
+  return providerName === OPENAI_API_PROVIDER_ID
+    && provider.adapter === "openai-responses"
+    && normalizedBaseUrl(provider.baseUrl) === OPENAI_API_BASE_URL;
+}
+
+/**
+ * Whether this destination is an OpenAI-operated Responses backend — the canonical ChatGPT Codex
+ * surface or the official OpenAI API.
+ *
+ * Deliberately not keyed on `authMode === "forward"`: a noncanonical forward provider does not
+ * receive the caller's credentials (see the forward-header gate in the Responses adapter), so
+ * forward auth says nothing about which backend is on the other end.
+ */
+export function isOpenAiOperatedResponsesDestination(provider: OcxProviderConfig): boolean {
+  if (isCanonicalOpenAiForwardProvider(provider)) return true;
+  return provider.adapter === "openai-responses"
+    && isOfficialOpenAiResponsesDestination(provider);
+}
+
+/**
+ * Whether this destination can decode a native (non-`ocx1:`) compaction blob.
+ *
+ * Only the backend that minted a blob can decode it. `authMode: "forward"` alone is not a signal:
+ * the adapter forwards caller credentials only to the canonical ChatGPT Codex surface, while a
+ * noncanonical forward provider receives no caller credentials and may point at any backend.
+ *
+ * Relay only to an OpenAI-operated destination or a destination whose operator explicitly opts in.
+ * Keyed by destination rather than provider id: a blob's issuer is the URL that produced it, not the
+ * local config key a replay travels under.
+ */
+export function destinationDecodesNativeCompactionBlob(provider: OcxProviderConfig): boolean {
+  return isOpenAiOperatedResponsesDestination(provider)
+    || provider.decodesNativeCompactionBlobs === true;
+}

package/src/providers/openai-tiers.ts

@@ -2,13 +2,9 @@ import type { CodexAccountMode, OcxConfig, OcxProviderConfig, ProviderCostOverla
 import { OPENAI_PROVIDER_TIER_VERSION } from "../types";
 import { openaiResponsesUrl } from "../adapters/openai-responses-url";
 import { MAX_COST4_RATE } from "../usage/expected-prices";
+import { OPENAI_CODEX_PROVIDER_ID, LEGACY_OPENAI_MULTI_PROVIDER_ID, LEGACY_CHATGPT_PROVIDER_ID, CODEX_FORWARD_BASE_URL, isCanonicalOpenAiForwardProvider } from "./openai-tiers-destination";
+export { OPENAI_CODEX_PROVIDER_ID, LEGACY_OPENAI_MULTI_PROVIDER_ID, OPENAI_API_PROVIDER_ID, LEGACY_CHATGPT_PROVIDER_ID, CODEX_FORWARD_BASE_URL, isCanonicalOpenAiForwardProvider, supportsNativeResponsesCompactEndpoint, isOpenAiOperatedResponsesDestination, destinationDecodesNativeCompactionBlob } from "./openai-tiers-destination";
 
-export const OPENAI_CODEX_PROVIDER_ID = "openai";
-export const LEGACY_OPENAI_MULTI_PROVIDER_ID = "openai-multi";
-export const OPENAI_API_PROVIDER_ID = "openai-apikey";
-export const LEGACY_CHATGPT_PROVIDER_ID = "chatgpt";
-
-export const CODEX_FORWARD_BASE_URL = "https://chatgpt.com/backend-api/codex";
 const LEGACY_OPENAI_MULTI_PREFIX = `${LEGACY_OPENAI_MULTI_PROVIDER_ID}/`;
 
 function canonicalCodexForwardProvider(mode: CodexAccountMode): OcxProviderConfig {
@@ -20,99 +16,6 @@ function canonicalCodexForwardProvider(mode: CodexAccountMode): OcxProviderConfi
   };
 }
 
-function normalizedBaseUrl(value: string): string | undefined {
-  try {
-    const url = new URL(value.trim());
-    if (url.username || url.password || url.search || url.hash) return undefined;
-    const path = url.pathname.replace(/\/+$/, "");
-    return `${url.origin}${path}`;
-  } catch {
-    return undefined;
-  }
-}
-
-export function isCanonicalOpenAiForwardProvider(provider: OcxProviderConfig): boolean {
-  return provider.adapter === "openai-responses"
-    && provider.authMode === "forward"
-    && normalizedBaseUrl(provider.baseUrl) === CODEX_FORWARD_BASE_URL;
-}
-
-const OPENAI_API_ORIGIN = "https://api.openai.com";
-const OPENAI_API_BASE_URL = `${OPENAI_API_ORIGIN}/v1`;
-const OPENAI_API_RESPONSES_URL = `${OPENAI_API_BASE_URL}/responses`;
-
-/**
- * The Responses endpoint the adapter would actually POST key-auth traffic to, normalized.
- *
- * Mirrors the adapter's own construction (`src/adapters/openai-responses.ts`): a configured
- * `responsesPath` is appended to the base verbatim, and only the default branch runs the
- * `/v1/responses` suffix normalization. Classifying on the base URL alone would call
- * `baseUrl: "https://api.openai.com"` with `responsesPath: "/other"` official even though that
- * request never reaches the official Responses endpoint.
- */
-function resolvedResponsesEndpoint(provider: OcxProviderConfig): string | undefined {
-  try {
-    const raw = provider.responsesPath === undefined
-      ? openaiResponsesUrl(provider.baseUrl)
-      : `${provider.baseUrl.replace(/\/$/, "")}${provider.responsesPath}`;
-    return normalizedBaseUrl(raw);
-  } catch {
-    return undefined;
-  }
-}
-
-function isOfficialOpenAiResponsesDestination(provider: OcxProviderConfig): boolean {
-  // Exact normalized URL keeps lookalike/suffix hosts out of this set: `api.openai.com.evil.test`
-  // resolves to its own origin, never to the official one.
-  return resolvedResponsesEndpoint(provider) === OPENAI_API_RESPONSES_URL;
-}
-
-/**
- * Whether this provider can serve `POST /responses/compact`. The canonical ChatGPT
- * backend can, and so can the official OpenAI API — but an arbitrary gateway that
- * merely speaks the Responses wire cannot, and calling it there fails compaction
- * with an unhelpful error instead of falling back to a routed summary (#422).
- */
-export function supportsNativeResponsesCompactEndpoint(
-  providerName: string,
-  provider: OcxProviderConfig,
-): boolean {
-  if (isCanonicalOpenAiForwardProvider(provider)) return true;
-  return providerName === OPENAI_API_PROVIDER_ID
-    && provider.adapter === "openai-responses"
-    && normalizedBaseUrl(provider.baseUrl) === OPENAI_API_BASE_URL;
-}
-
-/**
- * Whether this destination is an OpenAI-operated Responses backend — the canonical ChatGPT Codex
- * surface or the official OpenAI API.
- *
- * Deliberately not keyed on `authMode === "forward"`: a noncanonical forward provider does not
- * receive the caller's credentials (see the forward-header gate in the Responses adapter), so
- * forward auth says nothing about which backend is on the other end.
- */
-export function isOpenAiOperatedResponsesDestination(provider: OcxProviderConfig): boolean {
-  if (isCanonicalOpenAiForwardProvider(provider)) return true;
-  return provider.adapter === "openai-responses"
-    && isOfficialOpenAiResponsesDestination(provider);
-}
-
-/**
- * Whether this destination can decode a native (non-`ocx1:`) compaction blob.
- *
- * Only the backend that minted a blob can decode it. `authMode: "forward"` alone is not a signal:
- * the adapter forwards caller credentials only to the canonical ChatGPT Codex surface, while a
- * noncanonical forward provider receives no caller credentials and may point at any backend.
- *
- * Relay only to an OpenAI-operated destination or a destination whose operator explicitly opts in.
- * Keyed by destination rather than provider id: a blob's issuer is the URL that produced it, not the
- * local config key a replay travels under.
- */
-export function destinationDecodesNativeCompactionBlob(provider: OcxProviderConfig): boolean {
-  return isOpenAiOperatedResponsesDestination(provider)
-    || provider.decodesNativeCompactionBlobs === true;
-}
-
 export interface OpenAiTierMigrationProjection {
   config: OcxConfig;
   changed: boolean;

package/src/providers/opencode-go-transport.ts

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import type { OcxProviderConfig } from "../types";
+import { registryEntryForProviderDestination } from "./registry";
+
+export const OPENCODE_GO_SESSION_HEADER = "x-opencode-session";
+
+function hasHeaderCaseInsensitive(
+  headers: Record<string, string> | undefined,
+  name: string,
+): boolean {
+  const target = name.toLowerCase();
+  return Object.keys(headers ?? {}).some(key => key.toLowerCase() === target);
+}
+
+/** Derive a provider-scoped opaque value without exposing Codex task or subagent ids. */
+export function deriveOpenCodeGoSessionId(sessionLane: string): string {
+  const digest = createHash("sha256")
+    .update("opencodex/opencode-go/session/v1\0")
+    .update(sessionLane)
+    .digest("hex")
+    .slice(0, 32);
+  return `ocx_${digest}`;
+}
+
+/** Add per-conversation Go affinity only to the canonical fixed-key destination. */
+export function resolveOpenCodeGoTransport<T extends OcxProviderConfig>(
+  provider: T,
+  sessionLane: string | undefined,
+): T {
+  if (registryEntryForProviderDestination(provider)?.id !== "opencode-go") return provider;
+  if (!sessionLane) return provider;
+  if (hasHeaderCaseInsensitive(provider.headers, OPENCODE_GO_SESSION_HEADER)) return provider;
+
+  return {
+    ...provider,
+    headers: {
+      ...(provider.headers ?? {}),
+      [OPENCODE_GO_SESSION_HEADER]: deriveOpenCodeGoSessionId(sessionLane),
+    },
+  };
+}