feat(prompt): snapshot skills catalog per session to preserve prompt cache

docs-site/src/content/docs/guides/codex-prompt.md

@@ -169,6 +169,35 @@ repair writes a backup before it touches anything.
 Changes apply to newly started sessions. A session already running keeps the
 prompt settings it started with.
 
+## Keeping the skills catalog stable
+
+The proxy defaults to `skills.catalog_refresh: "per_session"`: the first
+`<skills_instructions>` catalog received for a conversation is reused on later
+requests in that conversation. This keeps skill discovery and `SKILL.md` edits
+from changing that part of the upstream prompt cache prefix mid-session.
+
+To use the catalog supplied by the client on every turn, set this in opencodex's
+`$OPENCODEX_HOME/config.json` (normally `~/.opencodex/config.json`), then restart
+the proxy:
+
+```json
+{
+  "skills": {
+    "catalog_refresh": "per_turn"
+  }
+}
+```
+
+The supported values are `"per_session"` (default) and `"per_turn"`. This is a
+proxy setting, separate from Codex's `skills.include_instructions` toggle.
+Requests without a reliable conversation identity use the catalog supplied by
+the client. Snapshots are held in memory and do not survive a proxy restart.
+They expire after four hours of inactivity and may be evicted when the bounded
+cache fills. An initial catalog block larger than 512 KiB is forwarded without caching.
+After expiry or eviction, the next received catalog becomes the new snapshot.
+The dashboard's prompt preview still reads the current files; it does not show
+the snapshot retained for an ongoing conversation.
+
 ## What this page reads, and what it does not
 
 opencodex reads one configuration file — your `config.toml`. Codex resolves its

docs-site/src/content/docs/reference/configuration/agents.md

@@ -8,6 +8,15 @@ routes, and limits delegated work.
 
 ## Agent fields
 
+### Skills catalog refresh
+
+`skills.catalog_refresh` accepts `"per_session"` (the default) or `"per_turn"`
+in opencodex's `config.json`. Session mode reuses the first received skills
+instructions for a conversation, protecting the prompt cache prefix from catalog
+changes between turns. Turn mode forwards the client's current catalog.
+See [Keeping the skills catalog stable](/guides/codex-prompt/#keeping-the-skills-catalog-stable)
+for configuration and snapshot lifetime details.
+
 ### Astra roster upgrade
 
 On the first start after upgrading, existing `subagentModels` lists receive

scripts/test-layout/layout.json

@@ -168,6 +168,7 @@
     "responses-compaction-recovery-policy.test.ts": "responses",
     "deepseek-artifact-tool-schema.test.ts": "providers",
     "client-config-export-output-limit.test.ts": "config",
+    "responses-skills-snapshot.test.ts": "responses",
     "openai-chat-serialized-tool-call-scaling.test.ts": "adapters/openai",
     "openai-chat-tool-call-id-remint.test.ts": "adapters/openai",
     "coding-agent-json-lines-scaling.test.ts": "providers",

src/config/diagnostics.ts

@@ -63,6 +63,7 @@ import {
   runtimeRoleSchema,
   spendSchema,
   compactionRoutingSchema,
+  skillsConfigSchema,
 } from "./schema/leaf-validators";
 
 export type ConfigDiagnostics = {
@@ -594,6 +595,17 @@ export function metricsExportConfigError(value: unknown): string | null {
   return null;
 }
 
+
+function skillsConfigError(value: unknown): string | null {
+  const raw = rawConfigRecord(value);
+  if (!raw || !Object.hasOwn(raw, "skills") || raw.skills === undefined) return null;
+  const result = skillsConfigSchema.safeParse(raw.skills);
+  if (result.success) return null;
+  const issue = result.error.issues[0];
+  const field = issue?.path.join(".");
+  return "schema_invalid: skills" + (field ? "." + field : "") + ": " + (issue?.message ?? "invalid configuration");
+}
+
 export function validateConfigCandidate(value: unknown): { ok: true; config: OcxConfig } | { ok: false; error: string } {
   const compactionRouting = rawConfigRecord(value)?.compactionRouting;
   if (compactionRouting !== undefined && !compactionRoutingSchema.safeParse(compactionRouting).success) {
@@ -625,7 +637,8 @@ export function validateConfigCandidate(value: unknown): { ok: true; config: Ocx
     ?? clientRolePairError(value)
     ?? loopbackListenerPortError(value)
     ?? managementIngressConfigError(value)
-    ?? metricsExportConfigError(value);
+    ?? metricsExportConfigError(value)
+    ?? skillsConfigError(value);
   if (boundaryError) return { ok: false, error: boundaryError };
   const result = configSchema.safeParse(value);
   if (result.success) {

src/config/schema/config-schema.ts

@@ -16,6 +16,7 @@ import {
   remoteGuiConfigSchema,
   runtimeRoleSchema,
   spendSchema,
+  skillsConfigSchema,
   configuredCodexPoolAccountIds,
   apiKeyEntrySchema,
   asideProfileSyncSchema,
@@ -78,6 +79,7 @@ export const configSchema = z.object({
   // A malformed privacy block must never be read as "unmask": .catch(undefined) drops it and
   // emailMaskingEnabled then falls back to masked, which is also what an absent block means.
   privacy: z.object({ maskEmails: z.boolean().optional() }).strict().optional().catch(undefined),
+  skills: skillsConfigSchema.optional().catch(undefined),
   // Malformed hand edits disable this opt-in exporter. Live writes reject them in diagnostics.ts.
   metricsExport: z.object({ enabled: z.boolean().optional() }).strict().optional().catch(undefined),
   // Kept raw on purpose: `.catch(undefined)` would turn a mistyped `enabled` into "inherit",

src/config/schema/leaf-validators.ts

@@ -1055,3 +1055,10 @@ export const spendSchema = z.object({
   pool: spendScopeSchema.optional(),
   retentionDays: z.number().int().min(1).max(365).optional(),
 }).strict();
+
+/**
+ * Runtime skills catalog configuration (#5569).
+ */
+export const skillsConfigSchema = z.object({
+  catalog_refresh: z.enum(["per_session", "per_turn"]).optional(),
+}).strict();

src/server/responses/request-prepare.ts

@@ -22,6 +22,7 @@ import {
   reasoningReplayConversationIdFromResponsesRequest,
 } from "../request-log-conversation";
 import { resolveContextPrincipal } from "../auth-cors";
+import { resolveSkillsSnapshotScopeKey, snapshotSkillsCatalogInBody } from "./skills-snapshot";
 import {
   isShadowSourceModel,
   shadowSourceModelPrefix,
@@ -314,6 +315,14 @@ export async function prepareResponsesRequest(
       );
   }
 
+  const skillsSnapshotScopeKey = resolveSkillsSnapshotScopeKey({
+    req,
+    config,
+    admission: options.admission,
+        promptCacheKeyIsSharedCohort: options.promptCacheKeyIsSharedCohort,
+  });
+  snapshotSkillsCatalogInBody(body, skillsSnapshotScopeKey, config);
+
   let parsed: OcxParsedRequest;
   let toolBridgeMaps: ReturnType<typeof buildToolBridgeMaps>;
   try {

src/server/responses/skills-snapshot.ts

@@ -0,0 +1,211 @@
+/**
+ * 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 { 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;
+}
+
+/**
+ * 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 = resolveContextPrincipal(input.req, input.config, input.admission) ?? 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 = resolveContextPrincipal(input.req, input.config, input.admission) ?? null;
+  return JSON.stringify(["skills_catalog_snapshot_v1", principal, standaloneId]);
+}
+
+function snapshotOrReplaceInText(
+  text: string,
+  scopeKey: string,
+  now: number,
+): string {
+  if (!text.includes("<skills_instructions>")) return text;
+
+  return text.replace(SKILLS_BLOCK_GLOBAL_REGEX, (match) => {
+    const existing = snapshotCache.get(scopeKey);
+    if (existing) {
+      // Check TTL on cache hits
+      if (now - existing.lastAccessed > SNAPSHOT_TTL_MS) {
+        totalRetainedBytes -= existing.byteLength;
+        snapshotCache.delete(scopeKey);
+      } else {
+        existing.lastAccessed = now;
+        // Refresh Map order for true LRU behavior
+        snapshotCache.delete(scopeKey);
+        snapshotCache.set(scopeKey, existing);
+        return existing.skillsBlock;
+      }
+    }
+
+    // First turn or expired: snapshot incoming block if bounded
+    const incomingBlock = match;
+    const blockBytes = Buffer.byteLength(incomingBlock, "utf8");
+    if (blockBytes <= MAX_SKILLS_BLOCK_BYTES && blockBytes <= MAX_TOTAL_RETAINED_BYTES) {
+      // 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) {
+        snapshotCache.set(scopeKey, {
+          skillsBlock: incomingBlock,
+          byteLength: blockBytes,
+          lastAccessed: now,
+        });
+        totalRetainedBytes += blockBytes;
+      }
+    }
+    return match;
+  });
+}
+
+/**
+ * Transforms incoming developer/system prompt contents to reuse the session's
+ * snapshotted <skills_instructions>, preserving prefix cache across turns.
+ * User and assistant messages, as well as tool calls, are never modified.
+ */
+export function snapshotSkillsCatalogInBody(
+  body: unknown,
+  scopeKey: string | null,
+  config: OcxConfig,
+  now: number = Date.now(),
+): void {
+  if (!scopeKey) return;
+  if (resolveSkillsCatalogRefresh(config) === "per_turn") return;
+  if (!body || typeof body !== "object" || Array.isArray(body)) return;
+
+  const b = body as Record<string, unknown>;
+
+  // 1. Check top-level instructions field
+  if (typeof b.instructions === "string" && b.instructions.includes("<skills_instructions>")) {
+    b.instructions = snapshotOrReplaceInText(b.instructions, scopeKey, now);
+  }
+
+  // 2. Check input array for developer/system messages only
+  if (Array.isArray(b.input)) {
+    for (const item of b.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;
+      const role = it.role;
+      // Only developer and system content is inspected/transformed
+      if (role !== "developer" && role !== "system") continue;
+
+      const content = it.content;
+      if (typeof content === "string") {
+        if (content.includes("<skills_instructions>")) {
+          it.content = snapshotOrReplaceInText(content, scopeKey, now);
+        }
+      } 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" && p.text.includes("<skills_instructions>")) {
+            p.text = snapshotOrReplaceInText(p.text, scopeKey, now);
+          }
+        }
+      }
+    }
+  }
+}
+
+/** Test helpers */
+export function resetSkillsSnapshotCacheForTests(): void {
+  snapshotCache.clear();
+  totalRetainedBytes = 0;
+}
+

src/types.ts

@@ -77,6 +77,8 @@ export type {
   OcxConnectedClientId,
   OcxClientConnectionConfig,
   OcxConfig,
+  SkillsCatalogRefresh,
+  OcxSkillsConfig,
   OcxAccountPoolRotationStrategy,
   OcxAccountPoolQuotaWindow,
   OcxComboCooldownWaitPolicy,

src/types/config.ts

@@ -362,6 +362,18 @@ export interface OcxConfigRebaseProvenance {
   deletedTopLevelKeys: string[];
 }
 
+
+export type SkillsCatalogRefresh = "per_session" | "per_turn";
+
+export interface OcxSkillsConfig {
+  /**
+   * Refresh policy for the runtime skills catalog (#5569).
+   * `per_session` (default): snapshots incoming `<skills_instructions>` on the first turn of a trustworthy session and reuses it across turns to preserve the Anthropic prompt cache.
+   * `per_turn`: re-derives/passes through incoming skills instructions every turn (previous behavior).
+   */
+  catalog_refresh?: SkillsCatalogRefresh;
+}
+
 export type OcxRuntimeRole = "standalone" | "hub" | "client";
 
 export interface OcxHubConfig {
@@ -487,6 +499,8 @@ export interface OcxConfig {
   client?: OcxClientConnectionConfig;
   /** Operator-facing redaction policy for management and CLI projections. */
   privacy?: OcxPrivacyConfig;
+  /** Runtime skills catalog session snapshotting settings (#5569). */
+  skills?: OcxSkillsConfig;
   /** Opt-in process-local aggregate request metrics on the authenticated management plane. */
   metricsExport?: { enabled?: boolean };
   /** Opt in to one identical-turn retry when a Responses completion has no text or tool call. */