@bitkyc08/opencodex 2.59.0 → 2.60.0

package/src/server/management/aside-profile-routes.ts

@@ -3,14 +3,19 @@ import { ClientPathError } from "../../clients/config-export";
 import { IntegrationMutationBusyError } from "../../integrations/mutation-flight";
 import { IntegrationWriterLockBusyError } from "../../integrations/writer-lock";
 import {
-  getAsideProfileState, listAsideProfileStates, mutateAsideProfiles, refreshAsideProfiles,
-  type AsideProfilesInput,
+  getAsideProfileState, listAsideProfileStates, mutateAsideProfiles, previewAsideProfile, refreshAsideProfiles,
+  type AsideProfilesInput, type AsideProfileWriteOutcome,
 } from "../../integrations/aside-profiles";
 import {
   listAsideOperations, findAsideOperation, restoreAsideProfile, deleteAsideOperation,
   asideOperationMatchesCurrent,
 } from "../../integrations/aside-profile-journal";
+import type { AsideOperation } from "../../integrations/aside-profile-journal";
 import type { WriteRefused } from "../../integrations/writer";
+import type { IntegrationWriteInput } from "../../integrations/writer";
+import type { IntegrationMutationPlan, IntegrationPlanOperation } from "../../integrations/mutation-plan";
+import { previewIntegration } from "../../integrations/mutation-plan";
+import { exportSnapshotIdentity, previewExportSnapshot } from "./model-rows";
 import type { ManagementContext } from "./context";
 import { readManagementJsonBody, readOptionalManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
 import { jsonResponse } from "../auth-cors";
@@ -22,6 +27,142 @@ export interface AsideProfileRouteOptions {
 
 class ProfileQueryError extends Error { readonly status = 400; readonly code = "invalid_aside_profile"; }
 
+/**
+ * The confirmed plan carried with this request, or null when there is none.
+ *
+ * Both fields or neither, and the operation must be the one being requested. Dropping a supplied
+ * binding would be the worst available behaviour: the caller believes their confirmation is being
+ * checked while the mutation proceeds unchecked.
+ */
+function asideBinding(
+  body: { operation?: unknown; planFingerprint?: unknown },
+  expected: IntegrationPlanOperation,
+): { operation: IntegrationPlanOperation; fingerprint: string } | null {
+  const { operation, planFingerprint } = body;
+  if (operation === undefined && planFingerprint === undefined) return null;
+  if (operation === undefined || typeof planFingerprint !== "string" || planFingerprint.length === 0) {
+    throw new ProfileQueryError("operation and planFingerprint must be sent together");
+  }
+  if (operation !== expected) throw new ProfileQueryError("operation does not match the requested change");
+  return { operation: expected, fingerprint: planFingerprint };
+}
+
+/**
+ * The guard a bound profile change runs before it writes anything.
+ *
+ * It re-plans the same profile scope and compares. The hooks that call it sit ahead of the
+ * preference write and the journal import, which is the only placement that helps here: those two
+ * happen before any writer lock is taken, so a check under that lock would fire after the thing it
+ * was meant to prevent.
+ */
+/**
+ * The check a bound Aside change runs, against the input that change is about to write from.
+ *
+ * It plans the prepared input it is given rather than building one of its own. Rebuilding meant
+ * reading the live configuration a second time, so a configuration edited to something else and
+ * back again while this action was in flight produced a check that agreed with a plan the write
+ * never described.
+ *
+ * Exported so the check itself can be exercised with a real prepared input and a roster that
+ * actually moved. The window it closes needs an ordinary load to complete while a mutation is
+ * preparing, which no test seam reaches from outside; a copy of the guard would prove nothing
+ * about the one the route installs. It takes only the configuration from the request context.
+ */
+export function asideGuardFor(
+  ctx: Pick<ManagementContext, "config">,
+  capturedIdentity: string,
+  profileIdValue: number,
+  binding: { operation: IntegrationPlanOperation; fingerprint: string },
+  request: { opId?: string; confirmDrift?: boolean; resolved?: AsideOperation },
+  capture: { plan: IntegrationMutationPlan | null },
+): (prepared: IntegrationWriteInput) => Promise<AsideProfileWriteOutcome | null> {
+  return async prepared => {
+    const plan = planFor(prepared, profileIdValue, binding, request);
+    /*
+     * The roster this confirmation was planned against has to still be the retained one. Only its
+     * rows were carried into the mutation, so an ordinary load completing while this action
+     * prepared could have replaced or retired the snapshot, and fingerprinting the carried rows
+     * would then accept a confirmation for a roster the operator no longer has. The non-Aside
+     * guard verifies the same identity; this one verifies it before the preference write, which is
+     * the last moment that still precedes every effect this action has.
+     */
+    const rosterMoved = exportSnapshotIdentity(ctx.config) !== capturedIdentity;
+    if (!rosterMoved && plan.canApply && plan.fingerprint === binding.fingerprint) return null;
+    capture.plan = plan;
+    return {
+      ok: false,
+      reason: "conflict",
+      state: plan.state,
+      clientId: "aside",
+      message: rosterMoved
+        ? "the model roster changed while confirming"
+        : "that confirmation no longer describes this profile",
+      profileId: profileIdValue,
+    };
+  };
+}
+
+/**
+ * The same comparison, run again immediately before the document is written.
+ *
+ * Aside takes no writer lock, and its preference write and journal import sit between the first
+ * check and the write that check authorizes. A target edited in that window is read fresh by the
+ * writer, which then compares it against itself and finds nothing to object to, so a confirmation
+ * about the earlier file would still overwrite the later one.
+ *
+ * The roster is deliberately not re-examined here. This action has just written the operator's
+ * preference into the configuration, which retires the retained roster by design, so asking that
+ * question at this point would refuse every confirmation on principle. What is asked is the one
+ * thing this moment can answer: does the plan the operator confirmed still describe this file.
+ */
+export function asideLateGuardFor(
+  profileIdValue: number,
+  binding: { operation: IntegrationPlanOperation; fingerprint: string },
+  request: { opId?: string; confirmDrift?: boolean; resolved?: AsideOperation },
+  capture: { plan: IntegrationMutationPlan | null },
+): (prepared: IntegrationWriteInput) => Promise<AsideProfileWriteOutcome | null> {
+  return async prepared => {
+    const plan = planFor(prepared, profileIdValue, binding, request);
+    if (plan.canApply && plan.fingerprint === binding.fingerprint) return null;
+    capture.plan = plan;
+    return {
+      ok: false,
+      reason: "conflict",
+      state: plan.state,
+      clientId: "aside",
+      message: "that confirmation no longer describes this profile",
+      profileId: profileIdValue,
+    };
+  };
+}
+
+function planFor(
+  prepared: IntegrationWriteInput,
+  profileIdValue: number,
+  binding: { operation: IntegrationPlanOperation; fingerprint: string },
+  request: { opId?: string; confirmDrift?: boolean; resolved?: AsideOperation },
+): IntegrationMutationPlan {
+  return previewIntegration(prepared, {
+    profileId: profileIdValue,
+    operation: binding.operation,
+    ...(request.opId === undefined ? {} : { opId: request.opId }),
+    ...(request.confirmDrift === undefined ? {} : { confirmDrift: request.confirmDrift }),
+    // The row the route selected, so the guard and the mutation mean the same operation even
+    // when more than one valid copy exists.
+    ...(request.resolved === undefined
+      ? {}
+      : { resolved: { entry: request.resolved.entry, store: request.resolved.store } }),
+  });
+}
+
+function stalePlanResponse(ctx: ManagementContext, plan: IntegrationMutationPlan): Response {
+  return jsonResponse({
+    error: "integration preview is stale",
+    code: "integration_preview_stale",
+    plan,
+  }, 409, ctx.req, ctx.config);
+}
+
 const ASIDE_INTEGRATION_PATH = "/api/client-integrations/aside";
 const ASIDE_PROFILES_PATH = "/api/client-integrations/aside/profiles";
 
@@ -75,7 +216,7 @@ function nestedProfileContext(ctx: ManagementContext): { ctx: ManagementContext;
     url.searchParams.set("client", "aside");
     return { ctx: { ...ctx, url }, action: "journal" };
   }
-  if (parts.length > 2 || !parts[0] || (parts[1] !== undefined && !["journal", "restore"].includes(parts[1]))) {
+  if (parts.length > 2 || !parts[0] || (parts[1] !== undefined && !["journal", "restore", "preview"].includes(parts[1]))) {
     throw new ProfileQueryError("Invalid Aside profile path");
   }
   const prior = url.searchParams.get("profile");
@@ -107,12 +248,62 @@ export async function handleAsideProfileRoutes(
       }
       return null;
     }
+    if (normalized.action === "preview") {
+      if (req.method !== "POST") return null;
+      // A plan describes one profile, so an unscoped preview has nothing to describe.
+      if (id === undefined) throw new ProfileQueryError("a plan applies to one profile");
+      const body = await readProfileBody(req);
+      if (!isObject(body)) throw new ProfileQueryError("preview body must be an object");
+      const operation = body.operation;
+      if (operation !== "apply" && operation !== "overwrite" && operation !== "disable" && operation !== "restore") {
+        throw new ProfileQueryError("operation must be apply, overwrite, disable or restore");
+      }
+      if (operation === "restore" && (typeof body.opId !== "string" || !body.opId.trim())) {
+        throw new ProfileQueryError("opId must be a non-empty string");
+      }
+      // The preview resolves the row the same way the mutation will, once, here.
+      const selected = operation === "restore"
+        ? findAsideOperation(options.input(), String(body.opId).trim(), id)
+        : null;
+      if (operation === "restore" && selected === null) {
+        return jsonResponse({
+          error: "integration operation not found",
+          code: "integration_operation_not_found",
+        }, 404, req, ctx.config);
+      }
+      const roster = previewExportSnapshot(ctx.config);
+      if (roster === null) {
+        return jsonResponse({
+          error: "no model roster is cached yet, so this change cannot be planned",
+          code: "integration_preview_unavailable",
+        }, 409, req, ctx.config);
+      }
+      const plan = await previewAsideProfile({ ...options.input(), models: roster.models }, {
+        profileId: id,
+        operation,
+        ...(operation === "restore"
+          ? {
+            opId: String(body.opId).trim(),
+            confirmDrift: body.confirmDrift === true,
+            ...(selected === null ? {} : { resolved: { entry: selected.entry, store: selected.store } }),
+          }
+          : {}),
+      });
+      return jsonResponse(plan, 200, req, ctx.config);
+    }
     if (normalized.action === "restore") {
       if (req.method !== "POST") return null;
       const body = await readProfileBody(req);
       if (!isObject(body) || typeof body.opId !== "string" || !body.opId.trim()
         || (body.confirmDrift !== undefined && typeof body.confirmDrift !== "boolean")) throw new ProfileQueryError("Invalid Aside restore request");
-      return asideRestoreResponse(ctx, { opId: body.opId.trim(), confirmDrift: body.confirmDrift === true }, options);
+      // Rebuilding the body here previously dropped any binding, so a bound nested restore
+      // reached the writer with its confirmation unexamined. Forward the fields as sent.
+      return asideRestoreResponse(ctx, {
+        opId: body.opId.trim(),
+        confirmDrift: body.confirmDrift === true,
+        ...(body.operation === undefined ? {} : { operation: body.operation }),
+        ...(body.planFingerprint === undefined ? {} : { planFingerprint: body.planFingerprint }),
+      }, options);
     }
     if (url.pathname === "/api/client-integrations/aside/sync") {
       if (req.method !== "POST") return null;
@@ -134,7 +325,38 @@ export async function handleAsideProfileRoutes(
     if (!isObject(body) || typeof body.enabled !== "boolean") throw new ProfileQueryError("enabled must be a boolean");
     if (body.overwriteConflict !== undefined && typeof body.overwriteConflict !== "boolean") throw new ProfileQueryError("overwriteConflict must be a boolean");
     if (body.overwriteConflict === true && !body.enabled) throw new ProfileQueryError("overwriteConflict applies only to enabling an integration");
-    const batch = await mutateAsideProfiles(options.input(), { enabled: body.enabled, profileId: id, overwriteConflict: body.overwriteConflict === true });
+    // An exact profile is required before a binding could ever mean anything: one fingerprint
+    // cannot honestly describe several independently changing files.
+    const expected: IntegrationPlanOperation = body.enabled
+      ? (body.overwriteConflict === true ? "overwrite" : "apply")
+      : "disable";
+    if ((body.operation !== undefined || body.planFingerprint !== undefined) && id === undefined) {
+      throw new ProfileQueryError("a confirmed plan applies to one profile");
+    }
+    const binding = asideBinding(body, expected);
+    const capture: { plan: IntegrationMutationPlan | null } = { plan: null };
+    let mutationInput = options.input();
+    let revalidate: ((prepared: IntegrationWriteInput) => Promise<AsideProfileWriteOutcome | null>) | undefined;
+    let revalidateBeforeWrite: ((prepared: IntegrationWriteInput) => Promise<AsideProfileWriteOutcome | null>) | undefined;
+    if (binding !== null && id !== undefined) {
+      const roster = previewExportSnapshot(ctx.config);
+      if (roster === null) {
+        return jsonResponse({
+          error: "no model roster is cached yet, so this change cannot be planned",
+          code: "integration_preview_unavailable",
+        }, 409, req, ctx.config);
+      }
+      // One roster for the guard and the mutation, so they cannot disagree by construction.
+      mutationInput = { ...mutationInput, models: roster.models };
+      revalidate = asideGuardFor(ctx, roster.identity, id, binding, {}, capture);
+      revalidateBeforeWrite = asideLateGuardFor(id, binding, {}, capture);
+    }
+    const batch = await mutateAsideProfiles(
+      mutationInput,
+      { enabled: body.enabled, profileId: id, overwriteConflict: body.overwriteConflict === true },
+      revalidate ? { revalidate, ...(revalidateBeforeWrite ? { revalidateBeforeWrite } : {}) } : undefined,
+    );
+    if (capture.plan) return stalePlanResponse(ctx, capture.plan);
     if (id !== undefined) {
       const result = batch.results[0];
       if (!result) throw new Error("Aside profile mutation returned no result");
@@ -180,7 +402,9 @@ export async function asideJournalResponse(
 }
 
 export async function asideRestoreResponse(
-  ctx: ManagementContext, body: { opId: string; confirmDrift?: boolean }, options: AsideProfileRouteOptions,
+  ctx: ManagementContext,
+  body: { opId: string; confirmDrift?: boolean; operation?: unknown; planFingerprint?: unknown },
+  options: AsideProfileRouteOptions,
 ): Promise<Response | null> {
   try {
     validateClientSelector(ctx);
@@ -196,7 +420,42 @@ export async function asideRestoreResponse(
       if (id === undefined) return null;
       return jsonResponse({ error: "integration operation not found", code: "integration_operation_not_found", opId: body.opId }, 404, ctx.req, ctx.config);
     }
-    const result = await restoreAsideProfile(input, { ...body, profileId: operation.profileId });
+    if ((body.operation !== undefined || body.planFingerprint !== undefined) && id === undefined) {
+      throw new ProfileQueryError("a confirmed plan applies to one profile");
+    }
+    const restoreBinding = asideBinding(body, "restore");
+    const capture: { plan: IntegrationMutationPlan | null } = { plan: null };
+    let restoreInput = input;
+    let revalidate: ((prepared: IntegrationWriteInput) => Promise<AsideProfileWriteOutcome | null>) | undefined;
+    let revalidateBeforeWrite: ((prepared: IntegrationWriteInput) => Promise<AsideProfileWriteOutcome | null>) | undefined;
+    if (restoreBinding !== null) {
+      const roster = previewExportSnapshot(ctx.config);
+      if (roster === null) {
+        return jsonResponse({
+          error: "no model roster is cached yet, so this change cannot be planned",
+          code: "integration_preview_unavailable",
+        }, 409, ctx.req, ctx.config);
+      }
+      restoreInput = { ...restoreInput, models: roster.models };
+      revalidate = asideGuardFor(ctx, roster.identity, operation.profileId, restoreBinding, {
+        opId: body.opId,
+        confirmDrift: body.confirmDrift === true,
+        resolved: operation,
+      }, capture);
+      revalidateBeforeWrite = asideLateGuardFor(operation.profileId, restoreBinding, {
+        opId: body.opId,
+        confirmDrift: body.confirmDrift === true,
+        resolved: operation,
+      }, capture);
+    }
+    const result = await restoreAsideProfile(
+      restoreInput,
+      // The same row the preview and guard used. Letting the mutation resolve its own copy is how
+      // a confirmation ends up bound to an operation other than the one that runs.
+      { ...body, profileId: operation.profileId, selectedOperation: operation },
+      revalidate ? { revalidate, ...(revalidateBeforeWrite ? { revalidateBeforeWrite } : {}) } : undefined,
+    );
+    if (capture.plan) return stalePlanResponse(ctx, capture.plan);
     return result.ok ? jsonResponse(result, 200, ctx.req, ctx.config) : options.failure(result);
   } catch (error) {
     if (error instanceof ClientPathError && !ctx.url.searchParams.has("profile")

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

@@ -1,3 +1,5 @@
+import { compactionRoutingSchema } from "../../config/schema/leaf-validators";
+import { captureConfigTopLevelRollback } from "../../config/rebase-provenance";
 import type { IntegrationClientId } from "../../integrations/registry";
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
@@ -342,6 +344,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         reason: "not_requested",
         retryable: false,
       }),
+      compactionRouting: config.compactionRouting ?? null,
       startupHealth: await readStartupHealth(config),
       codexRuntime: {
         path: displayCodexRuntimePath(resolved.runtime.command),
@@ -433,6 +436,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       codexMainAccountHardLock?: unknown;
       codexDesktopAuthless?: unknown;
       codexClientCompaction?: unknown;
+      compactionRouting?: unknown;
     };
     if (body.codexAutoStart === undefined
       && body.streamMode === undefined
@@ -444,8 +448,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       && body.fastRows === undefined
       && body.codexMainAccountHardLock === undefined
       && body.codexDesktopAuthless === undefined
-      && body.codexClientCompaction === undefined) {
-      return jsonResponse({ error: "provide codexAutoStart, streamMode, appOwnedMemoryBudgetMb, codexAccountPickerEnabled, codexQuotaAutoRefresh, oauthOpenBrowser, ultraFastTier, fastRows, codexMainAccountHardLock, codexDesktopAuthless, or codexClientCompaction" }, 400);
+      && body.codexClientCompaction === undefined
+      && body.compactionRouting === undefined) {
+      return jsonResponse({ error: "provide codexAutoStart, streamMode, appOwnedMemoryBudgetMb, codexAccountPickerEnabled, codexQuotaAutoRefresh, oauthOpenBrowser, ultraFastTier, fastRows, codexMainAccountHardLock, codexDesktopAuthless, codexClientCompaction, or compactionRouting" }, 400);
     }
     if (body.codexAutoStart !== undefined && typeof body.codexAutoStart !== "boolean") {
       return jsonResponse({ error: "codexAutoStart boolean is required" }, 400);
@@ -475,6 +480,12 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     if (body.codexClientCompaction !== undefined && typeof body.codexClientCompaction !== "boolean") {
       return jsonResponse({ error: "codexClientCompaction boolean is required" }, 400);
     }
+    const compactionRouting = body.compactionRouting == null
+      ? body.compactionRouting
+      : compactionRoutingSchema.safeParse(body.compactionRouting);
+    if (compactionRouting != null && !compactionRouting.success) {
+      return jsonResponse({ error: "compactionRouting requires a model, an optional valid reasoningEffort, and optional non-repeating triggers drawn from \"manual\" and \"auto\"" }, 400);
+    }
     let quotaAutoRefreshChange: { id: string; window: "fiveHour" | "weekly"; enabled: boolean } | undefined;
     if (body.codexQuotaAutoRefresh !== undefined) {
       if (!isPlainRecord(body.codexQuotaAutoRefresh)) {
@@ -504,6 +515,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
     )) {
       return jsonResponse({ error: `appOwnedMemoryBudgetMb must be an integer from ${MIN_APP_OWNED_MEMORY_BUDGET_MB} to ${MAX_APP_OWNED_MEMORY_BUDGET_MB}` }, 400);
     }
+    const restoreCompactionRouting = captureConfigTopLevelRollback(config, ["compactionRouting"]);
     const previousSettings = {
       codexAutoStart: config.codexAutoStart,
       hasCodexAutoStart: Object.hasOwn(config, "codexAutoStart"),
@@ -570,6 +582,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       else if (body.codexDesktopAuthless === false) deleteConfigTopLevelKey(config, "codexDesktopAuthless");
       if (body.codexClientCompaction === true) config.codexClientCompaction = true;
       else if (body.codexClientCompaction === false) deleteConfigTopLevelKey(config, "codexClientCompaction");
+      if (compactionRouting === null) deleteConfigTopLevelKey(config, "compactionRouting");
+      else if (compactionRouting?.success) config.compactionRouting = compactionRouting.data;
       if (quotaAutoRefreshChange) {
         const { id, window, enabled } = quotaAutoRefreshChange;
         const setting = { ...(config.codexQuotaAutoRefresh?.[id] ?? {}) };
@@ -618,6 +632,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       if (previousSettings.hasCodexClientCompaction) {
         config.codexClientCompaction = previousSettings.codexClientCompaction;
       } else deleteConfigTopLevelKey(config, "codexClientCompaction");
+      restoreCompactionRouting();
       throw error;
     }
     if (typeof body.appOwnedMemoryBudgetMb === "number") {
@@ -669,6 +684,7 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       codexDesktopAuthless: authlessIsEnabled,
       codexClientCompaction: clientCompactionIsEnabled,
       codexDesktopSwitches,
+      compactionRouting: config.compactionRouting ?? null,
       codexMainAccountHardLock: config.codexMainAccountHardLock === true,
       mainAccountHardLock: getMainAccountHardLockStatus(config),
       startupHealth: await readStartupHealth(config),

package/src/server/management/context.ts

@@ -19,6 +19,7 @@ import type {
   performCodexRestart,
   readCodexAppServerState,
 } from "../../codex/app-server-restart-service";
+import type { RequestMetricsSnapshotter } from "../request-metrics";
 
 import type { RemoteWorkspaceHub } from "../../remote-control/workspace-hub";
 import type { RemoteWorkspaceSessionService } from "../../remote-control/workspace-sessions";
@@ -31,6 +32,8 @@ export type RemoteWorkspaceSessionsApi = Pick<RemoteWorkspaceSessionService,
   "availability" | "list" | "create" | "prompt" | "submitPrompt" | "stop" | "shutdown">;
 
 export interface ManagementApiDeps {
+  /** Read-only process-local aggregate metrics; absent keeps the scrape route unavailable. */
+  requestMetrics?: RequestMetricsSnapshotter;
   remoteWorkspaceHub?: RemoteWorkspaceHubApi;
   remoteWorkspaceSessions?: RemoteWorkspaceSessionsApi;
   /** The listener retains and awaits teardown only after this optional subsystem activates. */