@bitkyc08/opencodex 2.55.0 → 2.56.0

package/src/server/management/route-registry.ts

@@ -86,34 +86,34 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   // server/management-api
   { method: "POST", path: "/api/stop", module: "server/management-api", mutates: true },
   // codex/auth-api
-  { method: "DELETE", path: "/api/codex-auth/accounts", module: "codex/auth-api", mutates: true },
-  { method: "GET", path: "/api/codex-auth/accounts", module: "codex/auth-api", mutates: false },
-  { method: "GET", path: "/api/codex-auth/active", module: "codex/auth-api", mutates: false },
-  { method: "GET", path: "/api/codex-auth/login-status", module: "codex/auth-api", mutates: false },
-  { method: "GET", path: "/api/codex-auth/quota", module: "codex/auth-api", mutates: false },
-  { method: "GET", path: "/api/codex-auth/quota/history", module: "codex/auth-api", mutates: false },
-  { method: "GET", path: "/api/codex-auth/reset-credits", module: "codex/auth-api", mutates: false },
-  { method: "PATCH", path: "/api/codex-auth/pool-strategy", module: "codex/auth-api", mutates: true },
-  { method: "POST", path: "/api/codex-auth/accounts", module: "codex/auth-api", mutates: true },
-  { method: "POST", path: "/api/codex-auth/accounts/clear-cooldown", module: "codex/auth-api", mutates: true },
-  { method: "POST", path: "/api/codex-auth/accounts/refresh", module: "codex/auth-api", mutates: true },
+  { method: "DELETE", path: "/api/codex-auth/accounts", module: "codex/auth-api/routes", mutates: true },
+  { method: "GET", path: "/api/codex-auth/accounts", module: "codex/auth-api/routes", mutates: false },
+  { method: "GET", path: "/api/codex-auth/active", module: "codex/auth-api/routes", mutates: false },
+  { method: "GET", path: "/api/codex-auth/login-status", module: "codex/auth-api/routes", mutates: false },
+  { method: "GET", path: "/api/codex-auth/quota", module: "codex/auth-api/routes", mutates: false },
+  { method: "GET", path: "/api/codex-auth/quota/history", module: "codex/auth-api/routes", mutates: false },
+  { method: "GET", path: "/api/codex-auth/reset-credits", module: "codex/auth-api/routes", mutates: false },
+  { method: "PATCH", path: "/api/codex-auth/pool-strategy", module: "codex/auth-api/routes", mutates: true },
+  { method: "POST", path: "/api/codex-auth/accounts", module: "codex/auth-api/routes", mutates: true },
+  { method: "POST", path: "/api/codex-auth/accounts/clear-cooldown", module: "codex/auth-api/routes", mutates: true },
+  { method: "POST", path: "/api/codex-auth/accounts/refresh", module: "codex/auth-api/routes", mutates: true },
   // codex/main-device-reauth-api (#3898): the native-main device reauth namespace;
   // /api/codex-auth/login stays pool-only and keeps rejecting __main__.
   { method: "POST", path: "/api/codex-auth/main/reauth-device", module: "codex/main-device-reauth-api", mutates: true },
   { method: "GET", path: "/api/codex-auth/main/reauth-device", module: "codex/main-device-reauth-api", mutates: false },
   { method: "DELETE", path: "/api/codex-auth/main/reauth-device", module: "codex/main-device-reauth-api", mutates: true },
-  { method: "POST", path: "/api/codex-auth/login", module: "codex/auth-api", mutates: true },
-  { method: "POST", path: "/api/codex-auth/login/cancel", module: "codex/auth-api", mutates: true },
-  { method: "POST", path: "/api/codex-auth/login/code", module: "codex/auth-api", mutates: true },
-  { method: "POST", path: "/api/codex-auth/reset-credits/consume", module: "codex/auth-api", mutates: true },
-  { method: "PUT", path: "/api/codex-auth/accounts/alias", module: "codex/auth-api", mutates: true },
-  { method: "PUT", path: "/api/codex-auth/accounts/pause", module: "codex/auth-api", mutates: true },
-  { method: "PUT", path: "/api/codex-auth/accounts/pause-exhausted", module: "codex/auth-api", mutates: true },
-  { method: "PUT", path: "/api/codex-auth/accounts/priority", module: "codex/auth-api", mutates: true },
-  { method: "PUT", path: "/api/codex-auth/active", module: "codex/auth-api", mutates: true },
-  { method: "PUT", path: "/api/codex-auth/auto-switch", module: "codex/auth-api", mutates: true },
-  { method: "PUT", path: "/api/codex-auth/failover", module: "codex/auth-api", mutates: true },
-  { method: "PUT", path: "/api/codex-auth/pool-strategy", module: "codex/auth-api", mutates: true, exempt: { reason: "compatibility-alias", why: "Superseded by PUT /api/pool/settings, which the CLI now drives. Kept working for existing clients and pinned by exact-body goldens in tests/server/account-pool-management-api.test.ts; no CLI verb targets it any more." } },
+  { method: "POST", path: "/api/codex-auth/login", module: "codex/auth-api/routes", mutates: true },
+  { method: "POST", path: "/api/codex-auth/login/cancel", module: "codex/auth-api/routes", mutates: true },
+  { method: "POST", path: "/api/codex-auth/login/code", module: "codex/auth-api/routes", mutates: true },
+  { method: "POST", path: "/api/codex-auth/reset-credits/consume", module: "codex/auth-api/routes", mutates: true },
+  { method: "PUT", path: "/api/codex-auth/accounts/alias", module: "codex/auth-api/routes", mutates: true },
+  { method: "PUT", path: "/api/codex-auth/accounts/pause", module: "codex/auth-api/routes", mutates: true },
+  { method: "PUT", path: "/api/codex-auth/accounts/pause-exhausted", module: "codex/auth-api/routes", mutates: true },
+  { method: "PUT", path: "/api/codex-auth/accounts/priority", module: "codex/auth-api/routes", mutates: true },
+  { method: "PUT", path: "/api/codex-auth/active", module: "codex/auth-api/routes", mutates: true },
+  { method: "PUT", path: "/api/codex-auth/auto-switch", module: "codex/auth-api/routes", mutates: true },
+  { method: "PUT", path: "/api/codex-auth/failover", module: "codex/auth-api/routes", mutates: true },
+  { method: "PUT", path: "/api/codex-auth/pool-strategy", module: "codex/auth-api/routes", mutates: true, exempt: { reason: "compatibility-alias", why: "Superseded by PUT /api/pool/settings, which the CLI now drives. Kept working for existing clients and pinned by exact-body goldens in tests/server/account-pool-management-api.test.ts; no CLI verb targets it any more." } },
   // codex/native-profile-api
   { method: "GET", path: "/api/native-main-profiles", module: "codex/native-profile-api", mutates: false },
   { method: "GET", path: "/api/native-main-profiles/doctor", module: "codex/native-profile-api", mutates: false },
@@ -308,6 +308,9 @@ export const MANAGEMENT_ROUTES: readonly ManagementRoute[] = [
   { method: "PUT", path: "/api/provider-context-caps", module: "server/management/provider-routes", mutates: true },
   // server/management/quota-reset-routes
   { method: "GET", path: "/api/quota-resets", module: "server/management/quota-reset-routes", mutates: false, mechanism: "negated-guard" },
+  // server/management/workflow-budget-routes
+  { method: "GET", path: "/api/workflow-budget", module: "server/management/workflow-budget-routes", mutates: false, exempt: { reason: "deferred-verb", why: "Reading a root's live budget is owed a CLI verb -- an operator staring at a 429 is usually already in a terminal -- but the ledger is process memory with no local transport to read it through, so the verb has to be an HTTP call the CLI does not yet make.", owner: "260915_workflow_budget_window wfc", ownerDoc: "devlog/_plan/260915_workflow_budget_window/030_wfc_diff_plan.md" } },
+  { method: "POST", path: "/api/workflow-budget/clear", module: "server/management/workflow-budget-routes", mutates: true, exempt: { reason: "deferred-verb", why: "Clearing one root is owed the same verb as the read above and for the same reason. It is deliberately not shipped as a verb in this work-phase: the read comes first, because an operator who cannot see which ceiling fired has no basis for deciding to forgive it.", owner: "260915_workflow_budget_window wfc", ownerDoc: "devlog/_plan/260915_workflow_budget_window/030_wfc_diff_plan.md" } },
   // server/management/request-history-routes
   { method: "GET", path: "/api/request-history", module: "server/management/request-history-routes", mutates: false },
   // server/management/routing-analytics-routes

package/src/server/management/shared.ts

@@ -37,7 +37,7 @@ import { DEFAULT_PROVIDER_CONTEXT_CAP, globalContextCapValue, providerContextCap
 import { resolveCodexHomeDir } from "../../codex/home";
 import { readUsageEntries } from "../../usage/log";
 import { getUsageDebugLogEntries } from "../../usage/debug";
-import { parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summary";
+import { cacheObservationFromUsage, parseRange, parseUsageSurface, summarizeUsage } from "../../usage/summary";
 import { stripCodexRuntimeProviderFields } from "../../codex/auth-context";
 import { getProviderRegistryEntry, providerMatchesRegistryTransport } from "../../providers/registry";
 import { getDebugLogEntries } from "../../lib/debug-log-buffer";
@@ -97,7 +97,7 @@ export type CostResult =
   | { kind: "value"; estimate: NonNullable<ReturnType<typeof estimateRequestCost>>; estimateReasons: CostEstimateReason[] }
   | { kind: "unavailable"; reason: MetricUnavailableReason };
 
-export type MetricSource = Pick<RequestLogEntry, "provider" | "model" | "durationMs" | "firstOutputMs" | "usageStatus" | "usage" | "requestedServiceTier" | "configuredServiceTier" | "responseServiceTier" | "tierOutcome" | "routeDecision"> & {
+export type MetricSource = Pick<RequestLogEntry, "provider" | "model" | "durationMs" | "firstOutputMs" | "usageStatus" | "usage" | "requestedServiceTier" | "configuredServiceTier" | "responseServiceTier" | "tierOutcome" | "routeDecision" | "cacheProvenance"> & {
   attempts?: readonly PersistedUsageAttempt[];
 };
 
@@ -186,9 +186,12 @@ export function costResult(entry: MetricSource): CostResult {
   if (!estimate) return { kind: "unavailable", reason: unavailableCostReason(entry) };
   const estimateReasons = [
     entry.usageStatus === "estimated" || entry.usage?.estimated ? "usage_estimated" as const : undefined,
-    entry.usage && entry.usage.cachedInputTokens === undefined
-      && entry.usage.cacheReadInputTokens === undefined
-      && entry.usage.cacheCreationInputTokens === undefined ? "cache_detail_missing" as const : undefined,
+    // A cost estimate is qualified by cache detail it can TRUST. A detail object that exists only
+    // because a strict client requires the field carries no cache reading, so it qualifies the
+    // estimate exactly as a missing one does — reading it as a measured zero prices the request
+    // as an uncached send that nothing observed.
+    entry.usage && cacheObservationFromUsage(entry.usage, entry.cacheProvenance).provenance !== "observed"
+      ? "cache_detail_missing" as const : undefined,
     estimate.price?.source === "expected" || estimate.attempts?.some(a => a.price.source === "expected")
       ? "expected_price_overlay" as const : undefined,
     estimate.price?.source === "user" || estimate.attempts?.some(a => a.price.source === "user")

package/src/server/management/workflow-budget-routes.ts

@@ -0,0 +1,133 @@
+/**
+ * Operator view of the in-memory workflow-budget ledger, plus a targeted clear.
+ *
+ * Loaded on demand from src/server/management-api.ts, which is the FOURTH entry in the protected
+ * set of tests/core-lab-boundary.test.ts — added precisely because eagerly importing handlers
+ * there put ~70 modules on every dashboard request. A static import here would make this
+ * subsystem the next instance of that bug.
+ *
+ * Authentication is inherited: every /api route passes through requireManagementAuth before the
+ * chain runs, so these handlers add no auth code of their own. The GET spends no user identity.
+ * The POST clears one root's windowed count ceilings; it does not spend identity, and the
+ * underlying ledger leaves in-flight concurrency and the token spend record untouched.
+ */
+
+import { jsonResponse } from "../auth-cors";
+import type { OcxConfig } from "../../types";
+import type { ManagementContext } from "./context";
+import { readManagementJsonBodyOr } from "./body";
+import {
+  clearWorkflowBudgetForRoot,
+  listTrackedWorkflowRoots,
+  listWorkflowBudgetEvents,
+  workflowBudgetSnapshot,
+  WORKFLOW_EVENT_CAPACITY,
+} from "../../lib/workflow-budget";
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = WORKFLOW_EVENT_CAPACITY;
+const MAX_ROOT_ID_LENGTH = 200;
+
+/**
+ * A root id is an opaque caller-thread token, not a path. Without a length cap a client
+ * could POST a multi-megabyte string that we would then store as a map key and echo back
+ * in events; 200 is well above any thread id we have seen and small enough to put in a URL.
+ */
+function parseRootId(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!trimmed || trimmed.length > MAX_ROOT_ID_LENGTH) return null;
+  return trimmed;
+}
+
+function invalidRootResponse(req: Request, config: OcxConfig): Response {
+  return jsonResponse(
+    { error: { code: "invalid_root", message: "root must be a non-empty string of at most 200 characters" } },
+    400,
+    req,
+    config,
+  );
+}
+
+function parseLimitParam(rawLimit: string | null): { ok: true; limit: number } | { ok: false } {
+  if (rawLimit !== null && !/^\d+$/.test(rawLimit)) return { ok: false };
+  return {
+    ok: true,
+    limit: rawLimit === null ? DEFAULT_LIMIT : Math.min(MAX_LIMIT, Number.parseInt(rawLimit, 10)),
+  };
+}
+
+export async function handleWorkflowBudgetRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { url, req, config } = ctx;
+
+  if (url.pathname === "/api/workflow-budget") {
+    if (req.method !== "GET") return null;
+
+    const parsedLimit = parseLimitParam(url.searchParams.get("limit"));
+    if (!parsedLimit.ok) {
+      return jsonResponse(
+        { error: { code: "invalid_limit", message: "limit must be a non-negative integer" } },
+        400,
+        req,
+        config,
+      );
+    }
+    const { limit } = parsedLimit;
+
+    const rawRoot = url.searchParams.get("root");
+    if (rawRoot !== null) {
+      const rootId = parseRootId(rawRoot);
+      if (rootId === null) return invalidRootResponse(req, config);
+      const snapshot = workflowBudgetSnapshot(rootId);
+      // An unknown id is a 200 with `root: null`, not a 404: the operator asked what this
+      // process currently holds for that token, and "nothing" is a legitimate answer. POST
+      // /clear is the opposite — claiming to forgive a ceiling that was never tracked would
+      // report a success that did not happen.
+      return jsonResponse(
+        {
+          root: snapshot ? { rootId, ...snapshot } : null,
+          events: listWorkflowBudgetEvents(WORKFLOW_EVENT_CAPACITY)
+            .filter((event) => event.rootId === rootId)
+            .slice(0, limit),
+        },
+        200,
+        req,
+        config,
+      );
+    }
+
+    return jsonResponse(
+      {
+        roots: listTrackedWorkflowRoots(limit),
+        events: listWorkflowBudgetEvents(limit),
+      },
+      200,
+      req,
+      config,
+    );
+  }
+
+  if (url.pathname === "/api/workflow-budget/clear") {
+    if (req.method !== "POST") return null;
+
+    const body = await readManagementJsonBodyOr(req, {});
+    const rawRoot = body && typeof body === "object" && !Array.isArray(body)
+      ? (body as { root?: unknown }).root
+      : undefined;
+    const rootId = parseRootId(rawRoot);
+    if (rootId === null) return invalidRootResponse(req, config);
+
+    const before = clearWorkflowBudgetForRoot(rootId);
+    if (!before) {
+      return jsonResponse(
+        { error: { code: "unknown_root", message: "root is not currently tracked" } },
+        404,
+        req,
+        config,
+      );
+    }
+    return jsonResponse({ cleared: true, root: rootId, before }, 200, req, config);
+  }
+
+  return null;
+}

package/src/server/management-api.ts

@@ -144,6 +144,17 @@ async function handleQuotaResetRoutesOnDemand(ctx: ManagementContext): Promise<R
   return handleQuotaResetRoutes(ctx);
 }
 
+/**
+ * Lazy like the Lab and routing-profile handlers, and for the same recorded reason: this file is
+ * mounted for every dashboard request, so a static import would put the workflow-budget ledger
+ * on all of them.
+ */
+async function handleWorkflowBudgetRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
+  if (!pathInManagementNamespace(ctx.url.pathname, "/api/workflow-budget", true)) return null;
+  const { handleWorkflowBudgetRoutes } = await import("./management/workflow-budget-routes");
+  return handleWorkflowBudgetRoutes(ctx);
+}
+
 async function handleGrokCouponRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
   if (!pathInManagementNamespace(ctx.url.pathname, "/api/grok/reset-coupons", true)) return null;
   const { handleGrokCouponRoutes } = await import("./management/grok-coupon-routes");
@@ -263,6 +274,7 @@ export async function handleManagementAPI(
     ??     (await handleLogsUsageRoutes(ctx))
     ??     (await handleRequestHistoryRoutes(ctx))
     ??     (await handleQuotaResetRoutesOnDemand(ctx))
+    ??     (await handleWorkflowBudgetRoutesOnDemand(ctx))
     ??     (await handleGrokCouponRoutesOnDemand(ctx))
     ??     (await handleRoutingAnalyticsRoutes(ctx))
     ??     (await handleRoutingProfileRoutesOnDemand(ctx))

package/src/server/request-log-conversation.ts

@@ -64,13 +64,16 @@ export function sessionIdHeaderFromRequest(headers: Headers): string | null {
 /**
  * Fixed-size logical turn lane (#820).
  *
- * A lane must be as SPECIFIC as the identity available, which is the opposite of what
- * `codexPoolAffinityKey` wants. Affinity deliberately prefers the parent thread so a whole
- * subagent fan-out pins to one account; a lane keyed that way would put every parallel
- * subagent of one parent into a single lane and reject all but the first with 503 — the
- * fan-out is the normal case, not an abuse.
+ * A lane must be as SPECIFIC as the identity available. `codexPoolAffinityKey` used to be the
+ * opposite: it preferred the parent thread, so a whole subagent fan-out shared one entry, and a
+ * lane keyed that way would have put every parallel subagent of one parent into a single lane
+ * and rejected all but the first with 503 — the fan-out is the normal case, not an abuse.
+ * Since #4546 affinity keys every thread as ITSELF and reads the parent only as a first-placement
+ * hint, so the two now agree on the unit. They still derive it differently: a lane is a digest an
+ * operator can match against what the client sent, while an affinity key is an opaque HMAC
+ * precisely so no caller-supplied identifier ends up in Pool state.
  *
- * So the parent is a QUALIFIER, never the lane on its own when a child thread exists: the
+ * The parent stays a QUALIFIER here, never the lane on its own when a child thread exists: the
  * pair separates siblings while still keeping one conversation's overlapping turns together.
  */
 export function sessionLaneIdFromRequest(headers: Headers): string | undefined {
@@ -256,4 +259,3 @@ export function getOrAllocateRequestSessionLane(req: Request): string {
 export function linkRequestSessionLane(sourceReq: Request, targetReq: Request): void {
   requestAllocatedSessionLanes.set(targetReq, getOrAllocateRequestSessionLane(sourceReq));
 }
-