@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/server/management/native-integration-routes.ts

@@ -17,18 +17,20 @@
  * Design of record: devlog/_fin/260803_integrations_toggle_all/030 (routes),
  * 011 (Claude Code), 012 (Grok).
  */
-import { readRuntimePort, saveConfigPreservingClaudeCode } from "../../config";
+import { loadConfig, readRuntimePort, saveConfigPreservingClaudeCode } from "../../config";
 import { filterCatalogVisibleModels, nativeOpenAiContextWindow, visibleNativeSlugs } from "../../codex/catalog";
+import { inspectDesktop3pConfigLibrary, removeDesktop3pStandardPivot, writeDesktop3pConfig } from "../../claude/desktop-3p";
 import { injectGrokConfig, stripGrokConfig, type GrokInjectModel } from "../../grok/inject";
 import { inspectGrokConfig } from "../../grok/inspect";
 import { grokConfigPath } from "../../grok/status";
 import { assertNativeTeardownOwned } from "../../integrations/native/ownership-preflight";
+import type { CodexNativeRestoreResult } from "../../codex/inject";
 import type { OcxConfig } from "../../types";
 import { jsonResponse } from "../auth-cors";
 import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 import type { ManagementContext } from "./context";
 
-export type NativeIntegrationClientId = "claude" | "grok" | "codex";
+export type NativeIntegrationClientId = "claude" | "grok" | "codex" | "claude-desktop";
 
 /** Every reason this module can decline, in one place (audit r3 #6). */
 export type NativeRefusalReason =
@@ -36,13 +38,17 @@ export type NativeRefusalReason =
   | "orphaned_marker"
   | "home_mismatch"
   | "config_busy"
-  | "write_failed";
+  | "write_failed"
+  | "metadata_unreadable"
+  | "cleanup_incomplete"
+  | "desired_state_changed";
 
 export interface NativeStatus {
   clientId: NativeIntegrationClientId;
   state: "absent" | "current" | "unsafe";
   installed: boolean;
   configPath: string;
+  desiredEnabled: boolean;
   /**
    * Set when a disable would be refused right now. ADVISORY: the file can
    * change before the PUT, which re-checks and whose answer is authoritative.
@@ -61,8 +67,10 @@ export interface NativeToggleEnvelope {
   changed: boolean;
   state: NativeStatus["state"];
   message: string;
+  desiredEnabled: boolean;
   /** Present when the outcome needs more than success/failure to be honest. */
   reason?: string;
+  artifacts?: CodexNativeRestoreResult["artifacts"];
 }
 
 export interface NativeRefusalEnvelope {
@@ -71,21 +79,66 @@ export interface NativeRefusalEnvelope {
   clientId: NativeIntegrationClientId;
   reason: NativeRefusalReason;
   message: string;
+  /** Present on every post-commit refusal; absent only for pre-commit refusals. */
+  desiredEnabled?: boolean;
+  residualPaths?: string[];
 }
 
+export type NativePostCommitRefusalEnvelope = Omit<NativeRefusalEnvelope, "desiredEnabled"> & {
+  desiredEnabled: boolean;
+};
+
 function refusal(
   status: number,
   clientId: NativeIntegrationClientId,
   reason: NativeRefusalReason,
   message: string,
+  extra: Pick<NativeRefusalEnvelope, "desiredEnabled" | "residualPaths"> = {},
 ): Response {
   return jsonResponse({
     error: status >= 500 ? "native integration change failed" : "native integration change refused",
     code: status >= 500 ? "native_integration_failed" : "native_integration_refused",
-    clientId, reason, message,
+    clientId, reason, message, ...extra,
   } satisfies NativeRefusalEnvelope, status);
 }
 
+function postCommitRefusal(
+  status: number,
+  clientId: NativeIntegrationClientId,
+  reason: NativeRefusalReason,
+  message: string,
+  extra: Pick<NativePostCommitRefusalEnvelope, "desiredEnabled" | "residualPaths">,
+): Response {
+  return jsonResponse({
+    error: status >= 500 ? "native integration change failed" : "native integration change refused",
+    code: status >= 500 ? "native_integration_failed" : "native_integration_refused",
+    clientId, reason, message, ...extra,
+  } satisfies NativePostCommitRefusalEnvelope, status);
+}
+
+function desktopStatus(config: ManagementContext["config"]): NativeStatus {
+  const seen = inspectDesktop3pConfigLibrary({
+    appliedFingerprint: config.claudeCode?.desktopProfile?.appliedFingerprint ?? null,
+  });
+  const state: NativeStatus["state"] = seen.kind === "gateway_ours"
+    ? "current"
+    : seen.kind === "unsafe" || seen.kind === "broken" ? "unsafe" : "absent";
+  const disableBlocked = seen.kind === "unsafe" || seen.kind === "broken" || seen.kind === "foreign"
+    ? {
+        reason: seen.kind === "unsafe" && seen.reason === "metadata_unreadable" ? "metadata_unreadable" as const : "write_failed" as const,
+        message: "Claude Desktop configuration cannot be changed safely.",
+      }
+    : null;
+  return {
+    clientId: "claude-desktop",
+    state,
+    installed: seen.kind !== "not_installed",
+    configPath: seen.libraryPath,
+    desiredEnabled: config.clientIntegrations?.["claude-desktop"] !== false,
+    disableBlocked,
+  };
+}
+
 /** Absent means ON: the six read sites all treat only an explicit `false` as off. */
 export function claudeCodeEnabled(config: ManagementContext["config"]): boolean {
   return config.claudeCode?.enabled !== false;
@@ -98,17 +151,30 @@ function claudeStatus(config: ManagementContext["config"], configPath: string):
     // The surface exists wherever the proxy does; there is no separate install.
     installed: true,
     configPath,
+    desiredEnabled: claudeCodeEnabled(config),
     // Nothing can refuse this disable: no external file, no shared teardown.
     disableBlocked: null,
   };
 }
 
+function codexStatus(config: ManagementContext["config"], configPath: string): NativeStatus {
+  const desiredEnabled = config.clientIntegrations?.codex !== false;
+  return {
+    clientId: "codex",
+    state: desiredEnabled ? "current" : "absent",
+    installed: true,
+    configPath,
+    desiredEnabled,
+    disableBlocked: null,
+  };
+}
+
 /**
  * Grok's GET row (030 §field table). `disableBlocked` is ADVISORY — the file
  * can change before the PUT, which re-checks with the same inspector and whose
  * answer is authoritative.
  */
-function grokStatus(): NativeStatus {
+function grokStatus(config: ManagementContext["config"]): NativeStatus {
   const seen = inspectGrokConfig();
   let disableBlocked: NativeStatus["disableBlocked"] = null;
   if (seen.kind === "orphaned_marker") {
@@ -137,6 +203,7 @@ function grokStatus(): NativeStatus {
     state,
     installed: seen.kind !== "not_installed",
     configPath: grokConfigPath(),
+    desiredEnabled: config.clientIntegrations?.grok !== false,
     disableBlocked,
   };
 }
@@ -260,9 +327,19 @@ async function handleCodexToggle(ctx: ManagementContext): Promise<Response> {
       const port = runtime?.port ?? ctx.config.port;
       const { syncModelsToCodex } = await import("../../codex/sync");
       const applied = await syncModelsToCodex(port);
+      if (applied.status === "skipped") {
+        return jsonResponse({
+          ok: true, clientId: "codex", changed: durable && persisted.status === "committed",
+          state: "absent",
+          desiredEnabled: enabled,
+          message: "Codex integration is OFF; enable did not change Codex.",
+          reason: "apply_incomplete",
+        } satisfies NativeToggleEnvelope);
+      }
       return jsonResponse({
         ok: true, clientId: "codex", changed: durable && persisted.status === "committed",
         state: applied.ok ? "current" : "absent",
+        desiredEnabled: enabled,
         message: applied.ok
           ? "Codex now routes through opencodex"
           : `Codex intent saved, but applying it did not complete: ${applied.message}`,
@@ -273,17 +350,28 @@ async function handleCodexToggle(ctx: ManagementContext): Promise<Response> {
     }
 
     // OFF. Restore the native path; the proxy keeps serving every other client.
+    if (durable && persisted.status === "unchanged") {
+      const { classifyNativeRoutedResidue } = await import("../../codex/native-residue");
+      if (classifyNativeRoutedResidue().kind === "clean") {
+        return jsonResponse({
+          ok: true, clientId: "codex", changed: false, state: "absent", desiredEnabled: false,
+          message: "Codex integration is already OFF and native; no Codex files changed.",
+        } satisfies NativeToggleEnvelope);
+      }
+    }
     const { restoreNativeCodexAsync } = await import("../../codex/inject");
-    const restored = await restoreNativeCodexAsync();
+    const restored = await restoreNativeCodexAsync({ revalidateDesiredState: true });
     return jsonResponse({
       ok: true, clientId: "codex", changed: durable && persisted.status === "committed",
       state: restored.success ? "absent" : "unsafe",
+      desiredEnabled: enabled,
       message: restored.success
         ? "Codex restored to its native path; the proxy is still serving other clients"
         : `Codex intent saved, but restoring the native path did not complete: ${restored.message}`,
       ...(restored.success
         ? (durable ? {} : { reason: "not_durable" })
         : { reason: "restore_incomplete" }),
+      artifacts: restored.artifacts,
     } satisfies NativeToggleEnvelope);
   })();
   try {
@@ -361,6 +449,7 @@ async function handleGrokToggle(ctx: ManagementContext): Promise<Response> {
       );
     }
     const durable = persisted.ok;
+    const desiredEnabled = durable ? loadConfig().clientIntegrations?.grok !== false : enabled;
 
     if (!enabled) {
       /*
@@ -369,24 +458,25 @@ async function handleGrokToggle(ctx: ManagementContext): Promise<Response> {
        * gated: writing our own fence tears nothing down.
        */
       const owned = assertNativeTeardownOwned();
-      if (!owned.ok) return refusal(409, "grok", "home_mismatch", owned.message);
+      if (!owned.ok) return postCommitRefusal(409, "grok", "home_mismatch", owned.message, { desiredEnabled });
 
       const result = stripGrokConfig();
       if (result.skippedReason === "no-grok-home") {
-        return refusal(404, "grok", "not_installed", NOT_INSTALLED_MESSAGE);
+        return postCommitRefusal(404, "grok", "not_installed", NOT_INSTALLED_MESSAGE, { desiredEnabled });
       }
       if (result.skippedReason === "orphaned-marker" || !result.ok) {
         // Orphaned can still arrive between the preflight and the strip; the
         // writer refuses it correctly and we map the refusal, never a retry lie.
         return result.skippedReason === "orphaned-marker"
-          ? refusal(409, "grok", "orphaned_marker", ORPHANED_MARKER_MESSAGE)
-          : refusal(500, "grok", "write_failed", result.message);
+          ? postCommitRefusal(409, "grok", "orphaned_marker", ORPHANED_MARKER_MESSAGE, { desiredEnabled })
+          : postCommitRefusal(500, "grok", "write_failed", result.message, { desiredEnabled });
       }
       // The writer's own read IS the last read within this synchronous
       // operation (012 Rev 3 N4): strip removed the fence, so absent.
       return jsonResponse({
         ok: true, clientId: "grok", changed: result.changed,
         state: "absent",
+        desiredEnabled,
         message: result.changed
           ? "Grok integration disabled — the opencodex block was removed. Re-enabling regenerates it from the current model list."
           : "Grok integration is already off",
@@ -427,13 +517,13 @@ async function handleGrokToggle(ctx: ManagementContext): Promise<Response> {
     } catch (error) {
       // A catalog failure must never write an empty fence (syncGrokConfig
       // guards this; the route inherits the rule). Nothing was written.
-      return refusal(500, "grok", "write_failed",
-        `The model catalog is unavailable, so nothing was written (${error instanceof Error ? error.message : String(error)}). Try again once provider discovery recovers.`);
+      return postCommitRefusal(500, "grok", "write_failed",
+        `The model catalog is unavailable, so nothing was written (${error instanceof Error ? error.message : String(error)}). Try again once provider discovery recovers.`, { desiredEnabled });
     }
 
     const recheck = inspectGrokConfig();
-    if (recheck.kind === "not_installed") return refusal(404, "grok", "not_installed", NOT_INSTALLED_MESSAGE);
-    if (recheck.kind === "orphaned_marker") return refusal(409, "grok", "orphaned_marker", ORPHANED_MARKER_MESSAGE);
+    if (recheck.kind === "not_installed") return postCommitRefusal(404, "grok", "not_installed", NOT_INSTALLED_MESSAGE, { desiredEnabled });
+    if (recheck.kind === "orphaned_marker") return postCommitRefusal(409, "grok", "orphaned_marker", ORPHANED_MARKER_MESSAGE, { desiredEnabled });
 
     const inject = deps.injectGrokConfig ?? injectGrokConfig;
     const result = inject(port, models, {
@@ -455,7 +545,7 @@ async function handleGrokToggle(ctx: ManagementContext): Promise<Response> {
       const after = inspectGrokConfig();
       switch (after.kind) {
         case "orphaned_marker":
-          return refusal(409, "grok", "orphaned_marker", ORPHANED_MARKER_MESSAGE);
+          return postCommitRefusal(409, "grok", "orphaned_marker", ORPHANED_MARKER_MESSAGE, { desiredEnabled });
         case "present":
           // A well-formed fence arrived from elsewhere between the strip and
           // this read (`ocx ensure`, another proxy, a hand edit). It is not
@@ -464,14 +554,16 @@ async function handleGrokToggle(ctx: ManagementContext): Promise<Response> {
           return jsonResponse({
             ok: true, clientId: "grok", changed: result.changed,
             state: "current", reason: "non_loopback_superseded",
+            desiredEnabled,
             message: "opencodex is bound to a non-loopback address, so this request did not write a block — but a well-formed opencodex block is present in the Grok config, written by something else. The card shows what is on disk.",
           } satisfies NativeToggleEnvelope);
         case "not_installed":
-          return refusal(404, "grok", "not_installed", NOT_INSTALLED_MESSAGE);
+          return postCommitRefusal(404, "grok", "not_installed", NOT_INSTALLED_MESSAGE, { desiredEnabled });
         case "absent":
           return jsonResponse({
             ok: true, clientId: "grok", changed: result.changed,
             state: "absent", reason: "non_loopback_removed",
+            desiredEnabled,
             message: "opencodex is bound to a non-loopback address, so Grok cannot be auto-registered. The previously generated block was removed because it pointed at a loopback address that no longer serves.",
           } satisfies NativeToggleEnvelope);
         default: {
@@ -484,17 +576,18 @@ async function handleGrokToggle(ctx: ManagementContext): Promise<Response> {
     }
 
     if (result.skippedReason === "no-grok-home") {
-      return refusal(404, "grok", "not_installed", NOT_INSTALLED_MESSAGE);
+      return postCommitRefusal(404, "grok", "not_installed", NOT_INSTALLED_MESSAGE, { desiredEnabled });
     }
     if (result.skippedReason === "orphaned-marker") {
-      return refusal(409, "grok", "orphaned_marker", ORPHANED_MARKER_MESSAGE);
+      return postCommitRefusal(409, "grok", "orphaned_marker", ORPHANED_MARKER_MESSAGE, { desiredEnabled });
     }
     if (!result.ok) {
-      return refusal(500, "grok", "write_failed", result.message);
+      return postCommitRefusal(500, "grok", "write_failed", result.message, { desiredEnabled });
     }
     return jsonResponse({
       ok: true, clientId: "grok", changed: result.changed,
       state: "current",
+      desiredEnabled,
       message: result.changed ? "Grok integration enabled — the opencodex block was regenerated from the current model list." : "Grok integration is already on",
     } satisfies NativeToggleEnvelope);
   })();
@@ -505,13 +598,93 @@ async function handleGrokToggle(ctx: ManagementContext): Promise<Response> {
   }
 }
 
+let claudeDesktopToggleFlight: Promise<Response> | null = null;
+
+async function handleClaudeDesktopToggle(ctx: ManagementContext): Promise<Response> {
+  if (claudeDesktopToggleFlight) {
+    return refusal(409, "claude-desktop", "config_busy",
+      "Another Claude Desktop change is already in flight. Nothing was written — try again in a moment.");
+  }
+  claudeDesktopToggleFlight = (async (): Promise<Response> => {
+    let body: { enabled?: unknown };
+    try {
+      body = await readManagementJsonBody(ctx.req);
+    } catch (error) {
+      rethrowManagementBodyTooLarge(error);
+      return jsonResponse({ error: "invalid JSON body" }, 400);
+    }
+    if (typeof body.enabled !== "boolean") return jsonResponse({ error: "enabled must be a boolean" }, 400);
+
+    const { setIntegrationEnabled } = await import("../../codex/desired-state");
+    const persisted = setIntegrationEnabled("claude-desktop", body.enabled);
+    if (!persisted.ok) {
+      return refusal(persisted.retryable ? 409 : 500, "claude-desktop", persisted.retryable ? "config_busy" : "write_failed", persisted.message);
+    }
+    const desiredEnabled = loadConfig().clientIntegrations?.["claude-desktop"] !== false;
+    const current = loadConfig();
+    const fingerprint = current.claudeCode?.desktopProfile?.appliedFingerprint ?? null;
+
+    if (!body.enabled) {
+      const removed = (ctx.deps.removeDesktop3pStandardPivot ?? removeDesktop3pStandardPivot)({ appliedFingerprint: fingerprint });
+      if (removed.kind === "cleanup_incomplete") {
+        return postCommitRefusal(500, "claude-desktop", "cleanup_incomplete",
+          "Claude Desktop now points at standard mode, but credential cleanup is incomplete.",
+          { desiredEnabled, residualPaths: removed.residualPaths ?? [] });
+      }
+      if (!removed.ok) {
+        return postCommitRefusal(409, "claude-desktop", removed.reason === "metadata_unreadable" ? "metadata_unreadable" : "write_failed",
+          "Claude Desktop configuration could not be changed safely.", { desiredEnabled });
+      }
+      return jsonResponse({
+        ok: true, clientId: "claude-desktop", changed: removed.changed, state: "absent", desiredEnabled,
+        message: removed.changed ? "Claude Desktop integration disabled." : "Claude Desktop integration is already off.",
+      } satisfies NativeToggleEnvelope);
+    }
+
+    const fetchModels = ctx.deps.fetchAllModels ?? defaultFetchAllModels;
+    try {
+      const fetched = await fetchModels(current);
+      const latest = loadConfig();
+      const latestDesiredEnabled = latest.clientIntegrations?.["claude-desktop"] !== false;
+      if (!latestDesiredEnabled) {
+        return postCommitRefusal(409, "claude-desktop", "desired_state_changed",
+          "Claude Desktop enable was cancelled because the desired state changed to off.", { desiredEnabled: latestDesiredEnabled });
+      }
+      const routed = filterCatalogVisibleModels(fetched, latest).map(model => ({
+        provider: model.provider, id: model.id, contextWindow: model.contextWindow,
+      }));
+      const runtime = (ctx.deps.readRuntimePort ?? readRuntimePort)(process.pid);
+      const result = (ctx.deps.writeDesktop3pConfig ?? writeDesktop3pConfig)(
+        runtime?.port ?? latest.port,
+        [...visibleNativeSlugs(latest)],
+        routed,
+        latest.apiKeys?.[0]?.key,
+        "static",
+        latest.claudeCode?.desktopProfile,
+      );
+      if (!result.written) return postCommitRefusal(500, "claude-desktop", "write_failed", "Claude Desktop apply failed.", { desiredEnabled: latestDesiredEnabled });
+      return jsonResponse({
+        ok: true, clientId: "claude-desktop", changed: true, state: "current", desiredEnabled: latestDesiredEnabled,
+        message: "Claude Desktop integration enabled.",
+      } satisfies NativeToggleEnvelope);
+    } catch {
+      return postCommitRefusal(500, "claude-desktop", "write_failed", "Claude Desktop apply failed.", { desiredEnabled });
+    }
+  })();
+  try {
+    return await claudeDesktopToggleFlight;
+  } finally {
+    claudeDesktopToggleFlight = null;
+  }
+}
+
 export async function handleNativeIntegrationRoutes(ctx: ManagementContext): Promise<Response | null> {
   const { req, url, config, deps } = ctx;
 
   if (url.pathname === "/api/native-integrations" && req.method === "GET") {
     const { getConfigPath } = await import("../../config");
     return jsonResponse({
-      clients: [claudeStatus(config, getConfigPath()), grokStatus()],
+      clients: [claudeStatus(config, getConfigPath()), grokStatus(config), codexStatus(config, getConfigPath()), desktopStatus(config)],
     } satisfies NativeStatusListEnvelope);
   }
 
@@ -532,6 +705,7 @@ export async function handleNativeIntegrationRoutes(ctx: ManagementContext): Pro
       return jsonResponse({
         ok: true, clientId: "claude", changed: false,
         state: enabled ? "current" : "absent",
+        desiredEnabled: enabled,
         message: enabled ? "Claude inbound is already on" : "Claude inbound is already off",
       } satisfies NativeToggleEnvelope);
     }
@@ -571,6 +745,7 @@ export async function handleNativeIntegrationRoutes(ctx: ManagementContext): Pro
     return jsonResponse({
       ok: true, clientId: "claude", changed: true,
       state: enabled ? "current" : "absent",
+      desiredEnabled: enabled,
       message: enabled ? "Claude inbound enabled" : "Claude inbound disabled",
     } satisfies NativeToggleEnvelope);
   }
@@ -583,5 +758,9 @@ export async function handleNativeIntegrationRoutes(ctx: ManagementContext): Pro
     return handleCodexToggle(ctx);
   }
 
+  if (url.pathname === "/api/native-integrations/claude-desktop" && req.method === "PUT") {
+    return handleClaudeDesktopToggle(ctx);
+  }
+
   return null;
 }

package/src/server/management/provider-routes.ts

@@ -165,6 +165,45 @@ function applyProviderPatchFields(
     next.liveModels = rawBody.liveModels;
     touched = true;
   }
+  // The Models page edits the catalog hints in place; keep them on the existing
+  // provider mutation path so validation, cache invalidation, and convergence stay unified (#1073).
+  if (Object.hasOwn(rawBody, "contextWindow")) {
+    const value = rawBody.contextWindow;
+    if (value === null) {
+      delete next.contextWindow;
+    // `Number.isInteger(1e100)` is true, so an integer check alone admits a value that
+    // serializes into the catalog as an enormous number and can make Codex reject the whole
+    // file. Safe-integer is the real bound for something that ends up in a JSON int field.
+    } else if (typeof value === "number" && Number.isSafeInteger(value) && value > 0) {
+      next.contextWindow = value;
+    } else {
+      return { error: "contextWindow must be a positive safe integer or null" };
+    }
+    touched = true;
+  }
+  if (Object.hasOwn(rawBody, "modelContextWindows")) {
+    const value = rawBody.modelContextWindows;
+    if (value === null) {
+      delete next.modelContextWindows;
+    } else {
+      if (!isPlainRecord(value)) return { error: "modelContextWindows must be a plain object or null" };
+      const windows: Record<string, number> = { ...(next.modelContextWindows ?? {}) };
+      for (const [model, window] of Object.entries(value)) {
+        if (!model.trim()) return { error: "modelContextWindows keys must be nonblank model ids" };
+        if (window === null) {
+          delete windows[model];
+          continue;
+        }
+        if (typeof window !== "number" || !Number.isSafeInteger(window) || window <= 0) {
+          return { error: "modelContextWindows values must be positive safe integers or null" };
+        }
+        windows[model] = window;
+      }
+      if (Object.keys(windows).length > 0) next.modelContextWindows = windows;
+      else delete next.modelContextWindows;
+    }
+    touched = true;
+  }
 
   // headers is the one object-valued field in the mask. PATCH semantics merge it
   // shallowly into the existing block so a single fingerprint header can be added
@@ -249,6 +288,8 @@ export async function handleProviderRoutes(ctx: ManagementContext): Promise<Resp
       allowPrivateNetwork: p.allowPrivateNetwork === true,
       liveModels: p.liveModels !== false,
       models: p.models ?? [],
+      contextWindow: p.contextWindow,
+      modelContextWindows: p.modelContextWindows,
       authMode: p.authMode,
       apiKeyTransport: p.apiKeyTransport,
       disabled: p.disabled === true,