@bitkyc08/opencodex 2.68.0 → 2.69.0

package/src/server/responses/request-prepare.ts

@@ -13,7 +13,14 @@ import {
 } from "./core-errors";
 import { parseSyntheticRowId } from "../fast-row";
 import { resolveComboId, comboIdFromRawBody, NoAvailableComboTargetsError } from "../../combos";
-import { INTERCEPT_TARGET_UNAVAILABLE_CODE, interceptTargetUnavailableResponse, resolveShadowCallTarget } from "./shadow-target-availability";
+import { INTERCEPT_TARGET_UNAVAILABLE_CODE, interceptTargetUnavailableResponse, resolveChosenTarget, resolveShadowCallTarget } from "./shadow-target-availability";
+import {
+  MEMORY_MODEL_TARGET_UNAVAILABLE_CODE,
+  configuredMemoryModel,
+  detectMemoryModelPhase,
+  memoryModelRouteReason,
+  memoryModelTargetUnavailableResponse,
+} from "./memory-models";
 import { recallComboForLane } from "./combo-session-recall";
 import {
   sessionLaneIdFromRequest,
@@ -22,6 +29,7 @@ import {
   reasoningReplayConversationIdFromResponsesRequest,
 } from "../request-log-conversation";
 import { resolveContextPrincipal } from "../auth-cors";
+import { resolveSkillsSnapshotScopeKey, snapshotSkillsCatalogInBody } from "./skills-snapshot";
 import {
   isShadowSourceModel,
   shadowSourceModelPrefix,
@@ -174,6 +182,20 @@ export async function prepareResponsesRequest(
       transport: options.inboundTransport,
     });
   }
+  // Codex's memory pipeline names a destination per phase. The phase is read from Codex's own turn
+  // metadata, never from the model id: Phase 1 shares `gpt-5.6-luna` with the app's title/commit
+  // helper calls. Read here, ahead of the shadow intercept below, because the phase decision is the
+  // more specific of the two settings and must be the one that survives when both match one request.
+  const memoryModelPhase = options.memoryModelPhase
+    ?? ((config.memoryModels?.extract || config.memoryModels?.consolidation)
+      && !options.comboAttempt && !options.compactionRoutingOverride && inboundWire === "responses"
+      ? detectMemoryModelPhase(body, req.headers, { transport: options.inboundTransport }) ?? undefined
+      : undefined);
+  const memoryModelTarget = memoryModelPhase ? configuredMemoryModel(config, memoryModelPhase) : undefined;
+  // A combo child is a synthetic replay of the parent's decision: its model is already the target's
+  // concrete provider/model, so neither site below may rewrite or re-resolve it. It keeps the phase
+  // through `options.memoryModelPhase` instead, which is what applies the phase effort.
+  const memoryModelApplies = memoryModelTarget !== undefined && options.comboAttempt !== true;
   options.onRequestBodyParsed?.(body);
   // An effort row naming a table-less combo (`combo/x--high`) must reach the combo dispatcher
   // as its base id, so the selector is normalized here, before comboIdFromRawBody reads model.
@@ -228,11 +250,22 @@ export async function prepareResponsesRequest(
   // hops — which only exist inside that loop — are unreachable (#4129). Rewrite the selector
   // here instead, before comboIdFromRawBody reads `model`, and identify the combo by CONFIG
   // LOOKUP so the check can never observe a one-candidate collapse.
+  // A memory target that names a combo has to reach the combo dispatcher as `model`, or its own
+  // failover loop is unreachable (#4129) — the same reason the shadow intercept rewrites its combo
+  // target here. Every other target is resolved at the late site, where the admission scope exists.
+  let memoryModelComboRouted = false;
+  if (memoryModelApplies && memoryModelTarget && body && typeof body === "object" && !Array.isArray(body)) {
+    const memoryComboId = resolveComboId(config, memoryModelTarget.model);
+    if (memoryComboId && Object.hasOwn(config.combos ?? {}, memoryComboId)) {
+      memoryModelComboRouted = true;
+      (body as Record<string, unknown>).model = memoryModelTarget.model;
+    }
+  }
   let shadowCallIntercepted = false;
   // A spawned sub-agent turn names its model on purpose; gpt-6-luna is both the helper
   // slug and a default sub-agent model, so neither intercept site may rewrite that turn.
   const threadSpawn = isThreadSpawnRequest(req.headers);
-  if (!options.comboAttempt && !options.compactionRoutingOverride && !threadSpawn && body && typeof body === "object" && !Array.isArray(body)) {
+  if (!options.comboAttempt && !options.compactionRoutingOverride && !threadSpawn && !memoryModelApplies && body && typeof body === "object" && !Array.isArray(body)) {
     const shadowIntercept = config.shadowCallIntercept;
     const rawShadowModel = (body as { model?: unknown }).model;
     if (shadowIntercept?.enabled && shadowIntercept.model && typeof rawShadowModel === "string"
@@ -258,6 +291,9 @@ export async function prepareResponsesRequest(
       // Concrete combo child selectors no longer match the shadow source model. Carry the
       // interception decision explicitly so provider-specific helper isolation still applies.
       shadowCallIntercepted,
+      // Same handoff for a memory phase whose target is a combo: the child keeps the phase's effort
+      // override and stays out of the parent conversation.
+      memoryModelPhase: memoryModelComboRouted ? memoryModelPhase : undefined,
       // The original request body was accepted above. Combo children are synthetic
       // replays and must not repeat the caller-owned timeout transition.
       onRequestBodyRead: undefined,
@@ -314,6 +350,15 @@ export async function prepareResponsesRequest(
       );
   }
 
+  const skillsSnapshotScopeKey = resolveSkillsSnapshotScopeKey({
+    req,
+    config,
+    admission: options.admission,
+        promptCacheKeyIsSharedCohort: options.promptCacheKeyIsSharedCohort,
+  });
+  // Substitutes a known snapshot now; a new catalog is only stored once the request is prepared.
+  const commitSkillsSnapshot = snapshotSkillsCatalogInBody(body, skillsSnapshotScopeKey, config);
+
   let parsed: OcxParsedRequest;
   let toolBridgeMaps: ReturnType<typeof buildToolBridgeMaps>;
   try {
@@ -381,6 +426,10 @@ export async function prepareResponsesRequest(
     }
     if (cursorClientThreadId) parsed._cursorClientThreadId = cursorClientThreadId;
     if (options.shadowCallIntercepted === true) parsed._cursorIsolateConversation = true;
+    if (options.memoryModelPhase !== undefined) {
+      parsed._memoryModelPhase = options.memoryModelPhase;
+      parsed._cursorIsolateConversation = true;
+    }
   } catch (err) {
     if (isTranslatorBudgetExceededError(err)) {
       return formatErrorResponse(413, "request_too_large", "request translation buffer exceeded the safe limit", {
@@ -484,9 +533,28 @@ export async function prepareResponsesRequest(
       : parsed._compactionRequest === true
         ? routeCompactionModel(config, modelId, evidenceFromBody(parsed._rawBody))
         : routeModel(config, modelId, evidenceFromBody(parsed._rawBody)));
+    // The phase's destination. Resolved through the admission-scoped resolver every other route
+    // uses, and it fails closed exactly like the shadow target: falling back to the native model
+    // would spend the quota the operator routed away from, without their choosing it.
+    let memoryRoute: RouteResult | undefined;
+    if (memoryModelApplies && memoryModelPhase && memoryModelTarget) {
+      const memoryTarget = resolveChosenTarget(memoryModelTarget.model, resolveRoute);
+      if ("unavailable" in memoryTarget) {
+        logCtx.errorCode = MEMORY_MODEL_TARGET_UNAVAILABLE_CODE;
+        return memoryModelTargetUnavailableResponse(memoryModelPhase);
+      }
+      credentialDomainWasRewritten = true;
+      parsed.modelId = memoryModelTarget.model;
+      if (parsed._rawBody && typeof parsed._rawBody === "object") {
+        (parsed._rawBody as { model?: string }).model = memoryModelTarget.model;
+      }
+      parsed._memoryModelPhase = memoryModelPhase;
+      parsed._cursorIsolateConversation = true;
+      memoryRoute = memoryTarget.route;
+    }
     const _sci = config.shadowCallIntercept;
     let shadowRoute: RouteResult | undefined;
-    if (!options.compactionRoutingOverride && !threadSpawn && _sci?.enabled && _sci.model && isShadowSourceModel(parsed.modelId, _sci.sourceModels)) {
+    if (!memoryRoute && !options.memoryModelPhase && !options.compactionRoutingOverride && !threadSpawn && _sci?.enabled && _sci.model && isShadowSourceModel(parsed.modelId, _sci.sourceModels)) {
       const sourcePrefix = shadowSourceModelPrefix(parsed.modelId, _sci.sourceModels)!;
       let sourceIdentity = { providerName: OPENAI_CODEX_PROVIDER_ID, modelId: sourcePrefix };
       try {
@@ -523,7 +591,20 @@ export async function prepareResponsesRequest(
       }
     }
     if (parsed._compactionRequest === true || options.compactionRoutingOverride) parsed._cursorIsolateConversation = true;
-    route = shadowRoute ?? resolveRoute(parsed.modelId);
+    route = memoryRoute ?? shadowRoute ?? resolveRoute(parsed.modelId);
+    // Name the phase in the persisted route decision, so the request log says why this turn went to
+    // the memory destination instead of leaving it looking like a plain user selection. Set here, on
+    // the resolved route, so a combo child's own route carries it too.
+    if (parsed._memoryModelPhase) {
+      const reason = memoryModelRouteReason(parsed._memoryModelPhase);
+      route.routeReason = reason;
+      if (route.routeDecision) {
+        route.routeDecision = {
+          ...route.routeDecision,
+          selected: { ...route.routeDecision.selected, reason },
+        };
+      }
+    }
     if (options.compactionRoutingOverride && !compactionRoutingKeepsProviderIdentity(config, options.compactionRoutingOverride, route)) {
       credentialDomainWasRewritten = true;
       // The destination does not share the conversation's credential domain, so it can neither
@@ -1263,6 +1344,7 @@ export async function prepareResponsesRequest(
     ? admissionState.authCtx.accountId
     : config.activeCodexAccountId ?? null;
 
+  commitSkillsSnapshot?.();
   return {
     inboundWire,
     translatorBudget,

package/src/server/responses/request-transport.ts

@@ -24,6 +24,7 @@ import {
   hasAnthropicFailoverQuorum,
 } from "../../oauth/anthropic-routing";
 import {
+  OAuthAccountPausedError,
   getValidAccessSnapshotForAccount,
   forceRefreshOAuthAccessSnapshot,
   getValidAccessTokenSnapshot,
@@ -697,6 +698,9 @@ export async function prepareResponsesTransport(
           `${redactSecretString(err.message)}. Remove or reconfigure provider '${safeProviderName}' in the OpenCodex configuration.`,
         );
       }
+      if (err instanceof OAuthAccountPausedError) {
+        return formatErrorResponse(403, "permission_error", publicOAuthAuthenticationErrorMessage(err));
+      }
       return formatErrorResponse(401, "authentication_error", publicOAuthAuthenticationErrorMessage(err));
     }
   }

package/src/server/responses/run-turn-execution.ts

@@ -551,7 +551,7 @@ export async function executeResponsesRunTurn(
       return retryQueue.stream();
     };
 
-    const { toolNsMap, declaredToolNames, toolParameterSchemas, freeformToolNames, toolSearchToolNames } = toolBridgeMaps;
+    const { toolNsMap, declaredToolNames, toolParameterSchemas, freeformToolNames, bareCustomToolNames, toolSearchToolNames } = toolBridgeMaps;
     const enforceDeclaredToolNames = inboundWire !== "chat" && inboundWire !== "anthropic";
     const classifyUndeclaredFirstTool = (
       event: AdapterEvent,
@@ -559,7 +559,7 @@ export async function executeResponsesRunTurn(
       if (!enforceDeclaredToolNames || event.type !== "tool_call_start") return undefined;
       // This tool is declared to the adapter by the private search loop.
       if (wsPlan && event.name === WEB_SEARCH_TOOL_NAME) return undefined;
-      const effectiveName = normalizeDeclaredToolName(event.name, declaredToolNames);
+      const effectiveName = normalizeDeclaredToolName(event.name, declaredToolNames, undefined, bareCustomToolNames);
       if (declaredToolNames.has(effectiveName)) return undefined;
       return {
         type: "error",
@@ -574,6 +574,7 @@ export async function executeResponsesRunTurn(
       if (preflight.replayUnsafe || preflight.error?.status !== 429
         || preflight.error.code === SEND_BUDGET_EXHAUSTED_CODE) return;
       const { httpStatus, error } = adapterFailureFromEvent(preflight.error);
+      transportState.bindKeyUsageFromBridge(preflight.error.usage);
       cancelResponseCompletion();
       runTurnAbort.abort();
       queue.close();
@@ -672,6 +673,7 @@ export async function executeResponsesRunTurn(
           stallTimeoutSec,
           hideThinkingSummary: parsed.options.hideThinkingSummary,
           declaredToolNames,
+          bareCustomToolNames,
           enforceDeclaredToolNames,
           toolParameterSchemas,
           ...(options.onFirstOutput ? { onFirstOutput: options.onFirstOutput } : {}),
@@ -814,6 +816,7 @@ export async function executeResponsesRunTurn(
         enforceDeclaredToolNames,
         toolParameterSchemas,
         freeformToolNames,
+        bareCustomToolNames,
         toolSearchToolNames,
         ...(routedCompaction ? { compaction: true } : {}),
         onProviderState: state => { providerState = state; },

package/src/server/responses/shadow-target-availability.ts

@@ -16,16 +16,21 @@ export const INTERCEPT_TARGET_UNAVAILABLE_CODE = "intercept_target_unavailable";
 /** Non-retryable: the target stays unavailable until the operator changes the configuration. */
 export const INTERCEPT_TARGET_UNAVAILABLE_STATUS = 409;
 
-export type ShadowTargetResolution = { route: RouteResult } | { unavailable: string };
+export type ChosenTargetResolution = { route: RouteResult } | { unavailable: string };
+export type ShadowTargetResolution = ChosenTargetResolution;
 
 /**
- * Resolve the configured target. Admission-scope refusals, exhausted combos and policy
+ * Resolve one operator-chosen target. Admission-scope refusals, exhausted combos and policy
  * evaluations keep their existing responses, so they are rethrown to the caller's handler.
+ *
+ * Shared by the shadow-call intercept and the memory-model routing: both name a single destination
+ * whose unavailability must not be papered over by the router's terminal default-provider
+ * fallback. `shadowCallTargetsIntersect` and the memory setting are the two callers.
  */
-export function resolveShadowCallTarget(
+export function resolveChosenTarget(
   model: string,
   resolve: (model: string) => RouteResult,
-): ShadowTargetResolution {
+): ChosenTargetResolution {
   let route: RouteResult;
   try {
     route = resolve(model);
@@ -44,6 +49,14 @@ export function resolveShadowCallTarget(
   return { route };
 }
 
+/** The shadow-call name for the shared resolver, kept because that is the surface's own vocabulary. */
+export function resolveShadowCallTarget(
+  model: string,
+  resolve: (model: string) => RouteResult,
+): ShadowTargetResolution {
+  return resolveChosenTarget(model, resolve);
+}
+
 const warnedTargets = new Set<string>();
 
 export function interceptTargetUnavailableResponse(model: string, detail: string): Response {

package/src/server/responses/sidecar-execution.ts

@@ -111,6 +111,17 @@ export async function executeResponsesSidecars(
     cancelResponseCompletion,
   } = responseEffects;
 
+  // Resolving the OpenAI search credential may hold the account's sole
+  // cooldown-recovery probe lease. A streamed sidecar result keeps it until the
+  // stream settles — completion or client cancel — so a later in-stream search
+  // outcome can still clear the cooldown; a response with no live body is
+  // terminal, so the lease is handed back before returning it. A recorded
+  // search outcome already settled the lease, making each release a
+  // generation-bound no-op.
+  const releaseSearchProbeLease = (): void => {
+    openAiSidecar?.releaseProbeLease?.();
+  };
+
 
   // Tool results are PAIRED by call_id. parseRequest writes it into OcxToolResultMessage.toolCallId
   // (parser.ts:738/752) without validating it, because inputItemSchema's permissive catch-all
@@ -133,6 +144,8 @@ export async function executeResponsesSidecars(
           || (message as { toolCallId: string }).toolCallId.length === 0),
     );
     if (unpaired) {
+      // Local validation has no running sidecar body to own this lease.
+      releaseSearchProbeLease();
       // Never interpolate the tool output: this message reaches the client and the logs.
       return formatErrorResponse(
         400,
@@ -330,6 +343,7 @@ export async function executeResponsesSidecars(
     // the bridge entirely so enabling the feature doesn't break ordinary non-streaming traffic.
     if (!parsed.stream) {
       if (imgPlan) {
+        releaseSearchProbeLease();
         return formatErrorResponse(400, "invalid_request_error", "image bridge requires stream=true");
       }
       // Video-only: skip bridge for non-streaming requests
@@ -431,11 +445,12 @@ export async function executeResponsesSidecars(
     if (imgResponse.body) {
       const imgTurnAc = new AbortController();
       imgTurnAc.signal.addEventListener("abort", cancelResponseCompletion, { once: true });
-      return new Response(trackStreamLifetime(imgResponse.body, imgTurnAc, undefined, options.turnAdmissionLease), {
+      return new Response(trackStreamLifetime(imgResponse.body, imgTurnAc, releaseSearchProbeLease, options.turnAdmissionLease), {
         status: imgResponse.status,
         headers: imgResponse.headers,
       });
     }
+    releaseSearchProbeLease();
     return imgResponse;
     } // end else (streaming bridge)
   }
@@ -511,11 +526,12 @@ export async function executeResponsesSidecars(
     if (wsResponse.body) {
       const wsTurnAc = new AbortController();
       wsTurnAc.signal.addEventListener("abort", cancelResponseCompletion, { once: true });
-      return new Response(trackStreamLifetime(wsResponse.body, wsTurnAc, undefined, options.turnAdmissionLease), {
+      return new Response(trackStreamLifetime(wsResponse.body, wsTurnAc, releaseSearchProbeLease, options.turnAdmissionLease), {
         status: wsResponse.status,
         headers: wsResponse.headers,
       });
     }
+    releaseSearchProbeLease();
     return wsResponse;
   }
 

package/src/server/responses/skills-snapshot.ts

@@ -0,0 +1,239 @@
+/**
+ * runtime skills catalog session snapshotting (#5569).
+ *
+ * Preserves the Anthropic/LLM prompt cache prefix across turns by freezing
+ * incoming <skills_instructions> for the duration of a trustworthy session.
+ * Gated by config `skills.catalog_refresh`: "per_session" (default) or "per_turn".
+ *
+ * Lifecycle & Bounds:
+ * - 4 hours idle TTL (sliding on access)
+ * - 1,000 maximum tracked sessions (LRU eviction)
+ * - 512 KiB maximum per snapshotted skills block
+ * - 8 MiB global retained byte bound across all sessions
+ */
+import type { OcxConfig, SkillsCatalogRefresh } from "../../types/config";
+import { isApiAuthRequired, resolveContextPrincipal, type DataPlaneAdmission } from "../auth-cors";
+import {
+  reasoningReplayConversationIdFromResponsesRequest,
+  sessionIdHeaderFromRequest,
+} from "../request-log-conversation";
+
+const SKILLS_BLOCK_GLOBAL_REGEX = /<skills_instructions>([\s\S]*?)<\/skills_instructions>/g;
+
+/** Maximum distinct sessions tracked in the memory LRU. */
+export const MAX_SNAPSHOT_SESSIONS = 1000;
+/** Slide expiry after 4 hours of inactivity. */
+export const SNAPSHOT_TTL_MS = 4 * 60 * 60 * 1000;
+/** Bounded byte ceiling per snapshotted skills block (512 KiB). */
+export const MAX_SKILLS_BLOCK_BYTES = 512 * 1024;
+/** Global retained byte bound across all tracked sessions (8 MiB). */
+export const MAX_TOTAL_RETAINED_BYTES = 8 * 1024 * 1024;
+
+interface SnapshotEntry {
+  skillsBlock: string; // The full <skills_instructions>...</skills_instructions> block
+  byteLength: number;
+  lastAccessed: number;
+}
+
+const snapshotCache = new Map<string, SnapshotEntry>();
+let totalRetainedBytes = 0;
+
+function evictOldestEntry(): boolean {
+  const oldest = snapshotCache.entries().next().value;
+  if (!oldest) return false;
+  const [key, entry] = oldest;
+  totalRetainedBytes -= entry.byteLength;
+  snapshotCache.delete(key);
+  return true;
+}
+
+export function resolveSkillsCatalogRefresh(config: OcxConfig | undefined): SkillsCatalogRefresh {
+  const configured = config?.skills?.catalog_refresh;
+  if (configured === "per_turn") return "per_turn";
+  return "per_session";
+}
+
+export interface ResolveSkillsSessionScopeInput {
+  req: Request;
+  config: OcxConfig;
+  admission?: DataPlaneAdmission;
+  cursorConversationId?: string;
+  promptCacheKeyIsSharedCohort?: boolean;
+}
+
+/**
+ * The principal a snapshot is scoped to. Without a named principal, only a server that requires
+ * no data-plane auth may share by conversation id (loopback admission, or an internal caller that
+ * passed none on such a server): its callers already share one trust domain, which on a no-auth
+ * server bound beyond loopback includes remote callers. Any other anonymous request gets no
+ * snapshot.
+ */
+function snapshotPrincipal(input: ResolveSkillsSessionScopeInput): string | null | undefined {
+  const principal = resolveContextPrincipal(input.req, input.config, input.admission);
+  if (principal) return principal;
+  if (input.admission) return input.admission.kind === "loopback" ? null : undefined;
+  return isApiAuthRequired(input.config) ? undefined : null;
+}
+
+/**
+ * Resolves a trustworthy cache key for skills catalog snapshotting.
+ * Returns null if no specific, reliable thread/session identity is available,
+ * or if the identity comes from a shared cohort fallback.
+ */
+export function resolveSkillsSnapshotScopeKey(input: ResolveSkillsSessionScopeInput): string | null {
+  if (input.promptCacheKeyIsSharedCohort === true) {
+    return null;
+  }
+
+  const parentThread = input.req.headers.get("x-codex-parent-thread-id")?.trim() || undefined;
+  const ownThreadId = input.req.headers.get("thread-id")?.trim() || undefined;
+  const cursorId = input.cursorConversationId?.trim() || undefined;
+
+  // When a parent thread is present, subagents/children may share a root session-id header.
+  // To prevent cross-thread/sibling collapse or parent-level caching, require an explicit
+  // own thread-id (or cursor id). If parentThread is present without an own child thread,
+  // bypass snapshotting completely.
+  if (parentThread) {
+    const childId = ownThreadId ?? cursorId;
+    if (!childId || childId === parentThread) {
+      return null;
+    }
+    const qualifiedId = `${parentThread}\u0000${childId}`;
+    const principal = snapshotPrincipal(input);
+    if (principal === undefined) return null;
+    return JSON.stringify(["skills_catalog_snapshot_v1", principal, qualifiedId]);
+  }
+
+  // Standalone conversation (no parent thread)
+  const standaloneId = reasoningReplayConversationIdFromResponsesRequest({
+    threadIdHeader: ownThreadId,
+    cursorConversationId: cursorId,
+    sessionIdHeader: sessionIdHeaderFromRequest(input.req.headers),
+  });
+  if (!standaloneId) {
+    return null;
+  }
+  const principal = snapshotPrincipal(input);
+  if (principal === undefined) return null;
+  return JSON.stringify(["skills_catalog_snapshot_v1", principal, standaloneId]);
+}
+
+/** One text slot that may carry a catalog: `instructions` or a developer/system text part. */
+interface CatalogSlot {
+  text: string;
+  write(next: string): void;
+}
+
+/** Every developer/system text slot, walked the same way the replacement writes. */
+function catalogSlots(body: Record<string, unknown>): CatalogSlot[] {
+  const slots: CatalogSlot[] = [];
+  if (typeof body.instructions === "string") {
+    slots.push({ text: body.instructions, write: next => { body.instructions = next; } });
+  }
+  if (!Array.isArray(body.input)) return slots;
+  for (const item of body.input) {
+    if (!item || typeof item !== "object") continue;
+    const it = item as Record<string, unknown>;
+    // Restrict message item type: must be undefined or "message", so role-like tool objects are untouched
+    if (it.type !== undefined && it.type !== "message") continue;
+    // Only developer and system content is inspected/transformed
+    if (it.role !== "developer" && it.role !== "system") continue;
+    const content = it.content;
+    if (typeof content === "string") {
+      slots.push({ text: content, write: next => { it.content = next; } });
+    } else if (Array.isArray(content)) {
+      for (const part of content) {
+        if (!part || typeof part !== "object") continue;
+        const p = part as Record<string, unknown>;
+        // Restrict text parts to known text / input_text
+        if (p.type !== "text" && p.type !== "input_text") continue;
+        if (typeof p.text === "string") slots.push({ text: p.text, write: next => { p.text = next; } });
+      }
+    }
+  }
+  return slots;
+}
+
+function liveSnapshot(scopeKey: string, now: number): SnapshotEntry | undefined {
+  const existing = snapshotCache.get(scopeKey);
+  if (!existing) return undefined;
+  if (now - existing.lastAccessed > SNAPSHOT_TTL_MS) {
+    totalRetainedBytes -= existing.byteLength;
+    snapshotCache.delete(scopeKey);
+    return undefined;
+  }
+  existing.lastAccessed = now;
+  // Refresh Map order for true LRU behavior
+  snapshotCache.delete(scopeKey);
+  snapshotCache.set(scopeKey, existing);
+  return existing;
+}
+
+function storeSnapshot(scopeKey: string, skillsBlock: string, now: number): void {
+  const blockBytes = Buffer.byteLength(skillsBlock, "utf8");
+  if (blockBytes > MAX_SKILLS_BLOCK_BYTES || blockBytes > MAX_TOTAL_RETAINED_BYTES) return;
+  // A concurrent request of the same conversation may have stored first; the first catalog wins.
+  if (snapshotCache.has(scopeKey)) return;
+  // Evict oldest entries until under count ceiling AND under global byte ceiling
+  while (
+    (snapshotCache.size >= MAX_SNAPSHOT_SESSIONS || totalRetainedBytes + blockBytes > MAX_TOTAL_RETAINED_BYTES)
+    && snapshotCache.size > 0
+  ) {
+    if (!evictOldestEntry()) break;
+  }
+  if (totalRetainedBytes + blockBytes > MAX_TOTAL_RETAINED_BYTES) return;
+  snapshotCache.set(scopeKey, { skillsBlock, byteLength: blockBytes, lastAccessed: now });
+  totalRetainedBytes += blockBytes;
+}
+
+/**
+ * Reuses the session's snapshotted <skills_instructions> in developer/system content, preserving
+ * the prompt cache prefix across turns. User and assistant messages and tool calls are never
+ * modified.
+ *
+ * Only a body with exactly one catalog block across all of those slots takes part: with two or
+ * more there is no way to tell which one the snapshot stands for, so the body passes through
+ * untouched rather than rewriting every block to one catalog.
+ *
+ * A known snapshot is substituted at once, so parsing and the verbatim passthrough body both see
+ * it. A new catalog is only stored through the returned commit, which the caller runs once the
+ * request has passed parsing and admission, so a rejected first request pins nothing.
+ */
+export function snapshotSkillsCatalogInBody(
+  body: unknown,
+  scopeKey: string | null,
+  config: OcxConfig,
+  now: number = Date.now(),
+): (() => void) | undefined {
+  if (!scopeKey) return undefined;
+  if (resolveSkillsCatalogRefresh(config) === "per_turn") return undefined;
+  if (!body || typeof body !== "object" || Array.isArray(body)) return undefined;
+
+  let found: { slot: CatalogSlot; block: string } | undefined;
+  let blocks = 0;
+  for (const slot of catalogSlots(body as Record<string, unknown>)) {
+    if (!slot.text.includes("<skills_instructions>")) continue;
+    for (const match of slot.text.matchAll(SKILLS_BLOCK_GLOBAL_REGEX)) {
+      blocks++;
+      found ??= { slot, block: match[0] };
+    }
+  }
+  if (blocks !== 1 || !found) return undefined;
+
+  const existing = liveSnapshot(scopeKey, now);
+  if (existing) {
+    const { slot, block } = found;
+    const at = slot.text.indexOf(block);
+    slot.write(slot.text.slice(0, at) + existing.skillsBlock + slot.text.slice(at + block.length));
+    return undefined;
+  }
+  const incoming = found.block;
+  return () => storeSnapshot(scopeKey, incoming, now);
+}
+
+/** Test helpers */
+export function resetSkillsSnapshotCacheForTests(): void {
+  snapshotCache.clear();
+  totalRetainedBytes = 0;
+}
+