comisai 1.0.4

package/node_modules/@comis/agent/dist/executor/executor-session-state.js

@@ -0,0 +1,299 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Session-scoped state management for PiExecutor.
+ *
+ * Extracted from pi-executor.ts to isolate module-level Map state into
+ * a focused module with getter/setter/clear functions. All session-scoped
+ * Maps that previously lived in pi-executor.ts are centralized here.
+ *
+ * Consumers:
+ * - pi-executor.ts: reads/writes state during execution
+ * - session-snapshot-cleanup.ts: clears state on session expiry
+ * - session-latch.test.ts: accesses latches for test assertions
+ *
+ * @module
+ */
+import { createSessionLatch } from "./session-latch.js";
+import { createCacheBreakDetector } from "./cache-break-detection.js";
+// ---------------------------------------------------------------------------
+// Design 4.1: Bounded session Maps with LRU eviction + TTL
+// ---------------------------------------------------------------------------
+/** Maximum number of entries per session state map before LRU eviction. */
+export const SESSION_STATE_MAX = 100;
+/** TTL in ms -- entries inactive for longer are evicted on next access/set. */
+export const SESSION_STATE_TTL_MS = 3_600_000; // 1 hour
+/**
+ * Create a Map-like object with automatic LRU eviction and TTL-based expiry.
+ * Entries inactive for >ttlMs are evicted on the next set() call.
+ * When capacity is exceeded, the least-recently-accessed entry is evicted.
+ *
+ * @param maxEntries - Maximum entries (default: SESSION_STATE_MAX = 100)
+ * @param ttlMs - TTL in ms (default: SESSION_STATE_TTL_MS = 1 hour)
+ */
+export function createBoundedSessionMap(maxEntries = SESSION_STATE_MAX, ttlMs = SESSION_STATE_TTL_MS) {
+    const map = new Map();
+    function evictStale() {
+        const now = Date.now();
+        for (const [key, entry] of map) {
+            if (now - entry.lastAccess > ttlMs)
+                map.delete(key);
+        }
+        // If still over capacity, evict oldest (first key = LRU in insertion order)
+        while (map.size > maxEntries) {
+            const oldestKey = map.keys().next().value;
+            if (oldestKey !== undefined)
+                map.delete(oldestKey);
+            else
+                break;
+        }
+    }
+    return {
+        get(key) {
+            const entry = map.get(key);
+            if (!entry)
+                return undefined;
+            // Move to most-recently-used: delete then re-insert
+            map.delete(key);
+            entry.lastAccess = Date.now();
+            map.set(key, entry);
+            return entry.value;
+        },
+        set(key, value) {
+            // If key exists, delete first to update insertion order
+            if (map.has(key)) {
+                map.delete(key);
+            }
+            map.set(key, { value, lastAccess: Date.now() });
+            // Evict stale and over-capacity entries after insertion
+            evictStale();
+        },
+        delete(key) {
+            return map.delete(key);
+        },
+        has(key) {
+            return map.has(key);
+        },
+        get size() {
+            return map.size;
+        },
+        clear() {
+            map.clear();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Session-scoped JIT guide delivery tracking
+// ---------------------------------------------------------------------------
+/**
+ * Per-session Set of tool names that have already received their JIT guide.
+ * Keyed by formatted session key. Cleared when isFirstMessageInSession is true.
+ * Follows the same pattern as sessionPromptDigests in prompt-assembly.ts.
+ */
+const sessionDeliveredGuides = createBoundedSessionMap();
+/** Get delivered guides Set for a session. */
+export function getDeliveredGuides(sessionKey) {
+    return sessionDeliveredGuides.get(sessionKey);
+}
+/** Set delivered guides Set for a session. */
+export function setDeliveredGuides(sessionKey, value) {
+    sessionDeliveredGuides.set(sessionKey, value);
+}
+/**
+ * Clear delivered guides for a session. Exported for session cleanup
+ * (co-located with session cleanup pattern).
+ */
+export function clearSessionDeliveredGuides(sessionKey) {
+    sessionDeliveredGuides.delete(sessionKey);
+}
+/** Map<sessionKey, ToolShape[]> -- snapshotted on first turn, reused on subsequent turns. */
+const sessionToolSchemaSnapshots = createBoundedSessionMap();
+/** Map<sessionKey, toolCompositionHash> -- tracks tool names that were active when the tool schema snapshot was taken. */
+const sessionToolSchemaSnapshotHashes = createBoundedSessionMap();
+/** Get the tool schema snapshot for a session. */
+export function getToolSchemaSnapshots(sessionKey) {
+    return sessionToolSchemaSnapshots.get(sessionKey);
+}
+/** Set the tool schema snapshot for a session. */
+export function setToolSchemaSnapshots(sessionKey, value) {
+    sessionToolSchemaSnapshots.set(sessionKey, value);
+}
+/** Delete the tool schema snapshot for a session (used on composition change). */
+export function deleteToolSchemaSnapshots(sessionKey) {
+    sessionToolSchemaSnapshots.delete(sessionKey);
+}
+/** Clear the tool schema snapshot for a session (e.g., on session reset/compaction).
+ *  Exported for session cleanup following the same pattern as clearSessionDeliveredGuides
+ *  and clearSessionToolNameSnapshot (prompt-assembly.ts).
+ *
+ *  NOTE: As of this implementation, none of the clearSession* functions
+ *  (clearSessionDeliveredGuides, clearSessionToolNameSnapshot)
+ *  have production call sites in the daemon -- they are exported for test cleanup
+ *  (beforeEach) and future session eviction wiring. The sessionToolSchemaSnapshots Map
+ *  is bounded by active session count (one entry per unique agent:channel:chat key),
+ *  and each entry is small (~2-5KB for typical tool sets). This is acceptable for the
+ *  current deployment scale. When a session eviction path is added to the daemon,
+ *  clearSessionToolSchemaSnapshot should be called alongside the other clearSession* functions. */
+export function clearSessionToolSchemaSnapshot(sessionKey) {
+    sessionToolSchemaSnapshots.delete(sessionKey);
+}
+/** Get the tool schema snapshot hash for a session. */
+export function getToolSchemaSnapshotHash(sessionKey) {
+    return sessionToolSchemaSnapshotHashes.get(sessionKey);
+}
+/** Set the tool schema snapshot hash for a session. */
+export function setToolSchemaSnapshotHash(sessionKey, value) {
+    sessionToolSchemaSnapshotHashes.set(sessionKey, value);
+}
+/** Clear the tool schema snapshot hash for a session. */
+export function clearSessionToolSchemaSnapshotHash(sessionKey) {
+    sessionToolSchemaSnapshotHashes.delete(sessionKey);
+}
+/** Compute a deterministic hash of tool names for tool composition change detection. */
+export function computeToolCompositionHash(toolNames) {
+    return toolNames.slice().sort().join(",");
+}
+// ---------------------------------------------------------------------------
+// Session-scoped cache breakpoint persistence
+// ---------------------------------------------------------------------------
+/** Per-session lastBreakpointIndex persistence.
+ *  Stores the highest cache breakpoint index from the previous execution
+ *  so the next execute() call can seed the context engine's cacheFenceIndex.
+ *  Cleared on session expiry (clearSessionBreakpointIndex). */
+const sessionBreakpointIndex = createBoundedSessionMap();
+/** Get persisted breakpoint index for a session. */
+export function getBreakpointIndex(sessionKey) {
+    return sessionBreakpointIndex.get(sessionKey);
+}
+/** Set persisted breakpoint index for a session. */
+export function setBreakpointIndex(sessionKey, value) {
+    sessionBreakpointIndex.set(sessionKey, value);
+}
+/** Delete persisted breakpoint index for a session. */
+export function deleteBreakpointIndex(sessionKey) {
+    sessionBreakpointIndex.delete(sessionKey);
+}
+/** Get the size of the breakpoint index map (for logging). */
+export function getBreakpointIndexMapSize() {
+    return sessionBreakpointIndex.size;
+}
+/** Clear persisted breakpoint index for a session. Exported for session cleanup
+ *  (co-located with clearSessionDeliveredGuides, clearSessionToolSchemaSnapshot). */
+export function clearSessionBreakpointIndex(sessionKey) {
+    sessionBreakpointIndex.delete(sessionKey);
+}
+const sessionEvictionCooldown = createBoundedSessionMap();
+/** Get eviction cooldown state for a session. */
+export function getEvictionCooldown(sessionKey) {
+    return sessionEvictionCooldown.get(sessionKey);
+}
+/** Set eviction cooldown (called on server eviction detection). */
+export function setEvictionCooldown(sessionKey, turnsRemaining) {
+    sessionEvictionCooldown.set(sessionKey, { turnsRemaining, evictedAt: Date.now() });
+}
+/** Decrement eviction cooldown by 1 turn. Deletes entry when reaching 0. */
+export function decrementEvictionCooldown(sessionKey) {
+    const state = sessionEvictionCooldown.get(sessionKey);
+    if (!state)
+        return;
+    if (state.turnsRemaining <= 1) {
+        sessionEvictionCooldown.delete(sessionKey);
+    }
+    else {
+        sessionEvictionCooldown.set(sessionKey, { ...state, turnsRemaining: state.turnsRemaining - 1 });
+    }
+}
+/** Clear eviction cooldown for a session. */
+export function clearSessionEvictionCooldown(sessionKey) {
+    sessionEvictionCooldown.delete(sessionKey);
+}
+const sessionCacheSavings = createBoundedSessionMap();
+/** Get cumulative cache savings for a session. */
+export function getCacheSavings(sessionKey) {
+    return sessionCacheSavings.get(sessionKey);
+}
+/** Record a turn's cache savings (called each turn_end). */
+export function recordCacheSavings(sessionKey, savedUsd) {
+    const existing = sessionCacheSavings.get(sessionKey);
+    if (existing) {
+        sessionCacheSavings.set(sessionKey, {
+            cumulativeSavingsUsd: existing.cumulativeSavingsUsd + savedUsd,
+            turnCount: existing.turnCount + 1,
+        });
+    }
+    else {
+        sessionCacheSavings.set(sessionKey, {
+            cumulativeSavingsUsd: savedUsd,
+            turnCount: 1,
+        });
+    }
+}
+/** Clear cumulative cache savings for a session. */
+export function clearSessionCacheSavings(sessionKey) {
+    sessionCacheSavings.delete(sessionKey);
+}
+// ---------------------------------------------------------------------------
+// Session-scoped cache warm state
+// ---------------------------------------------------------------------------
+/** Session-scoped cache warm state. Tracks whether adaptive retention
+ *  has escalated during any prior execute() call for this session key.
+ *  When true, subsequent execute() calls start with config retention (long)
+ *  instead of cold-start (short), preventing TTL downgrade on the first API call. */
+const sessionCacheWarm = createBoundedSessionMap();
+/** Get session cache warm state. */
+export function getCacheWarm(sessionKey) {
+    return sessionCacheWarm.get(sessionKey);
+}
+/** Set session cache warm state. */
+export function setCacheWarm(sessionKey, value) {
+    sessionCacheWarm.set(sessionKey, value);
+}
+/** Clear session cache warm state. Exported for session cleanup
+ *  (co-located with clearSessionBreakpointIndex, clearSessionDeliveredGuides). */
+export function clearSessionCacheWarm(sessionKey) {
+    sessionCacheWarm.delete(sessionKey);
+}
+/** SESS-LATCH: Session-scoped latches keyed by formatted session key. */
+const sessionLatches = createBoundedSessionMap();
+/** SESS-LATCH: Get or create latches for a session. */
+export function getOrCreateSessionLatches(sessionKey) {
+    let latches = sessionLatches.get(sessionKey);
+    if (!latches) {
+        latches = {
+            betaHeader: createSessionLatch(),
+            retention: createSessionLatch(),
+            deferLoading: createSessionLatch(),
+            idleThinkingClear: createSessionLatch(),
+        };
+        sessionLatches.set(sessionKey, latches);
+    }
+    return latches;
+}
+/** SESS-LATCH: Get latches for a session without creating (used by thinking override). */
+export function getSessionLatches(sessionKey) {
+    return sessionLatches.get(sessionKey);
+}
+/** SESS-LATCH: Clear all latches for a session (called on session reset). */
+export function clearSessionLatches(sessionKey) {
+    const latches = sessionLatches.get(sessionKey);
+    if (latches) {
+        latches.betaHeader.reset();
+        latches.retention.reset();
+        latches.deferLoading.reset();
+        latches.idleThinkingClear.reset();
+        sessionLatches.delete(sessionKey);
+    }
+}
+/** SESS-LATCH: Exported for test access following _prefix convention. */
+export { clearSessionLatches as _clearSessionLatchesForTest };
+export { getOrCreateSessionLatches as _getOrCreateSessionLatchesForTest };
+// ---------------------------------------------------------------------------
+// Module-level singleton for cache break detection
+// ---------------------------------------------------------------------------
+let cacheBreakDetectorInstance;
+/** Lazily create or return the singleton cache break detector. */
+export function getCacheBreakDetector(logger) {
+    if (!cacheBreakDetectorInstance) {
+        cacheBreakDetectorInstance = createCacheBreakDetector(logger);
+    }
+    return cacheBreakDetectorInstance;
+}

package/node_modules/@comis/agent/dist/executor/executor-stream-setup.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Stream wrapper composition for PiExecutor.
+ *
+ * Extracted from pi-executor.ts execute() to isolate the ordered
+ * construction of the stream wrapper chain (TTL guard, validation
+ * formatter, bouncer, turn budget, config resolver, request body
+ * injector, Gemini cache injector, trace writers).
+ *
+ * Mutable refs (executionCacheRetention, adaptiveRetention,
+ * executionMinTokensOverride) remain in pi-executor.ts. This module
+ * receives getter callbacks for those values.
+ *
+ * Consumers:
+ * - pi-executor.ts: calls setupStreamWrappers() during execute()
+ *
+ * Wrapper ordering (outermost first):
+ * 1. TTL guard (cache TTL expiry detection)
+ * 2. Validation error formatter (AJV error simplification)
+ * 3. Tool result size bouncer (per-tool truncation)
+ * 4. Turn result budget (per-turn aggregate budget)
+ * 5. Config resolver (maxTokens, temperature, cacheRetention)
+ * 6. Request body injector (Anthropic cache breakpoints)
+ * 7. Gemini cache injector (Google CachedContent injection)
+ * 8. Trace writers (JSONL cache trace, API payload trace)
+ *
+ * @module
+ */
+import { type SessionKey, type PerAgentConfig } from "@comis/core";
+import type { ComisLogger } from "@comis/infra";
+import type { CacheRetention } from "@mariozechner/pi-ai";
+import type { StreamFnWrapper } from "./stream-wrappers/index.js";
+import type { TruncationSummary } from "./stream-wrappers/tool-result-size-bouncer.js";
+import type { TurnBudgetSummary } from "./stream-wrappers/turn-result-budget-wrapper.js";
+import type { TtlSplitEstimate } from "../bridge/pi-event-bridge.js";
+import type { GeminiCacheManager } from "./gemini-cache-manager.js";
+import { getCacheBreakDetector } from "./executor-session-state.js";
+import type { SessionManager } from "@mariozechner/pi-coding-agent";
+import type { ContextEngine } from "../context-engine/index.js";
+import type { AdaptiveCacheRetention } from "./adaptive-cache-retention.js";
+import type { ExcludeDeferralResult } from "./tool-deferral.js";
+import type { SystemPromptBlocks } from "../bootstrap/index.js";
+import type { ExecutionOverrides } from "./types.js";
+/** Subset of PiExecutorDeps used by stream wrapper setup. */
+export interface StreamSetupDeps {
+    logger: ComisLogger;
+    eventBus: import("@comis/core").TypedEventBus;
+    agentId?: string;
+    tenantId?: string;
+    tracingDefaults?: {
+        maxSize: string;
+        maxFiles: number;
+    };
+    geminiCacheManager?: GeminiCacheManager;
+}
+/** Parameters for the setupStreamWrappers function. */
+export interface StreamSetupParams {
+    config: PerAgentConfig;
+    deps: StreamSetupDeps;
+    sessionKey: SessionKey;
+    formattedKey: string;
+    /** Session manager instance for microcompaction guard installation. */
+    sm: SessionManager;
+    resolvedModel?: {
+        id: string;
+        provider: string;
+    };
+    modelCompat?: {
+        supportsTools?: boolean;
+    };
+    modelTier: "small" | "medium" | "large";
+    executionOverrides?: ExecutionOverrides;
+    deferralResult?: ExcludeDeferralResult;
+    systemPromptBlocks?: SystemPromptBlocks;
+    agentId?: string;
+    /** Get the current adaptive cache retention (may be undefined). */
+    getAdaptiveRetention: () => AdaptiveCacheRetention | undefined;
+    /** Get the per-execution cache retention override. */
+    getExecutionCacheRetention: () => CacheRetention | undefined;
+    /** Get the per-execution minTokens override. */
+    getExecutionMinTokensOverride: () => number | undefined;
+    /** Callback invoked when cache breakpoints are placed (feeds index back to context engine). */
+    onBreakpointsPlaced?: (highestIdx: number) => void;
+    /** Callback invoked when Gemini cache hit is detected. */
+    onGeminiCacheHit?: (entry: {
+        cachedTokens: number;
+    }) => void;
+}
+/** Result of stream wrapper setup. */
+export interface StreamSetupResult {
+    /** Ordered stream function wrappers (outermost first). */
+    wrappers: StreamFnWrapper[];
+    /** Mutable holder for context engine reference (wired after context engine creation). */
+    contextEngineRef: {
+        current?: ContextEngine;
+    };
+    /** Cache break detector singleton for this execution. */
+    cacheBreakDetector: ReturnType<typeof getCacheBreakDetector>;
+    /** Truncation metadata registry (toolCallId -> truncation stats). */
+    truncationMetaRegistry: Map<string, {
+        truncated: boolean;
+        fullChars: number;
+        returnedChars: number;
+    }>;
+    /** Get truncation summary for bookend log. */
+    getTruncationSummary: () => TruncationSummary;
+    /** Get turn budget summary for bookend log. */
+    getTurnBudgetSummary: () => TurnBudgetSummary;
+    /** Captured adaptive retention snapshot (for TTL guard timestamp recording). */
+    capturedRetention: AdaptiveCacheRetention | undefined;
+    /** Shared mutable TTL split estimate, populated by requestBodyInjector,
+     *  consumed by pi-event-bridge on turn_end for per-TTL cost calculation. */
+    ttlSplit: TtlSplitEstimate;
+}
+/**
+ * Build the ordered stream wrapper chain for a single execution.
+ *
+ * Pure function with params object ( extraction pattern). All mutable
+ * refs and closure state remain in pi-executor.ts orchestrator scope and are
+ * accessed via getter callbacks.
+ *
+ * @param params - Stream setup parameters including config, deps, and getter callbacks
+ * @returns Stream setup result with wrappers array and shared state refs
+ */
+export declare function setupStreamWrappers(params: StreamSetupParams): StreamSetupResult;

package/node_modules/@comis/agent/dist/executor/executor-stream-setup.js

@@ -0,0 +1,244 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Stream wrapper composition for PiExecutor.
+ *
+ * Extracted from pi-executor.ts execute() to isolate the ordered
+ * construction of the stream wrapper chain (TTL guard, validation
+ * formatter, bouncer, turn budget, config resolver, request body
+ * injector, Gemini cache injector, trace writers).
+ *
+ * Mutable refs (executionCacheRetention, adaptiveRetention,
+ * executionMinTokensOverride) remain in pi-executor.ts. This module
+ * receives getter callbacks for those values.
+ *
+ * Consumers:
+ * - pi-executor.ts: calls setupStreamWrappers() during execute()
+ *
+ * Wrapper ordering (outermost first):
+ * 1. TTL guard (cache TTL expiry detection)
+ * 2. Validation error formatter (AJV error simplification)
+ * 3. Tool result size bouncer (per-tool truncation)
+ * 4. Turn result budget (per-turn aggregate budget)
+ * 5. Config resolver (maxTokens, temperature, cacheRetention)
+ * 6. Request body injector (Anthropic cache breakpoints)
+ * 7. Gemini cache injector (Google CachedContent injection)
+ * 8. Trace writers (JSONL cache trace, API payload trace)
+ *
+ * @module
+ */
+import { safePath, } from "@comis/core";
+import { createToolResultSizeBouncer, createTurnResultBudgetWrapper, createConfigResolver, createCacheTraceWriter, createApiPayloadTraceWriter, createRequestBodyInjector, createValidationErrorFormatter, } from "./stream-wrappers/index.js";
+import { resolveToolCallingTemperature } from "./tool-deferral.js";
+import { computeFeatureFlagHash } from "./prompt-assembly.js";
+import { createTtlGuard, getElapsedSinceLastResponse } from "./ttl-guard.js";
+import { isAnthropicFamily, isGoogleFamily } from "../provider/capabilities.js";
+import { createGeminiCacheInjector } from "./gemini-cache-injector.js";
+import { extractAnthropicPromptState, extractGeminiPromptState } from "./cache-break-detection.js";
+import { createBlockStabilityTracker } from "./block-stability-tracker.js";
+import { clearSessionCacheWarm, getOrCreateSessionLatches, clearSessionLatches, getCacheBreakDetector, getBreakpointIndex, getEvictionCooldown, } from "./executor-session-state.js";
+import { installMicrocompactionGuard } from "../context-engine/index.js";
+import { homedir } from "node:os";
+import path from "node:path";
+// ---------------------------------------------------------------------------
+// Setup function
+// ---------------------------------------------------------------------------
+/**
+ * Build the ordered stream wrapper chain for a single execution.
+ *
+ * Pure function with params object ( extraction pattern). All mutable
+ * refs and closure state remain in pi-executor.ts orchestrator scope and are
+ * accessed via getter callbacks.
+ *
+ * @param params - Stream setup parameters including config, deps, and getter callbacks
+ * @returns Stream setup result with wrappers array and shared state refs
+ */
+export function setupStreamWrappers(params) {
+    const { config, deps, formattedKey, sm, modelTier, executionOverrides, deferralResult, systemPromptBlocks, agentId, getAdaptiveRetention, getExecutionCacheRetention, getExecutionMinTokensOverride, onBreakpointsPlaced, onGeminiCacheHit, } = params;
+    // Mutable holder for context engine -- allows the requestBodyInjector
+    // callback closure to reference contextEngine before it's created (assigned below).
+    const contextEngineRef = {};
+    // Obtain cache break detector singleton for this execution.
+    const cacheBreakDetector = getCacheBreakDetector(deps.logger);
+    // Block stability tracker for adaptive TTL promotion.
+    // Singleton per module (same pattern as cacheBreakDetector) -- state is per-session inside the tracker.
+    const blockStabilityTracker = createBlockStabilityTracker();
+    // Offload oversized tool results to disk before JSONL session write.
+    installMicrocompactionGuard(sm, sm.getSessionDir(), deps.logger, (_toolName) => {
+        cacheBreakDetector.notifyContentModification(formattedKey);
+    });
+    const wrappers = [];
+    // Reformat AJV validation errors before the LLM sees them.
+    const validationErrorFormatter = createValidationErrorFormatter(deps.logger);
+    // Shared truncation metadata registry for audit event flow.
+    const truncationMetaRegistry = new Map();
+    const registerTruncation = (toolCallId, meta) => {
+        truncationMetaRegistry.set(toolCallId, { truncated: true, fullChars: meta.fullChars, returnedChars: meta.returnedChars });
+    };
+    // Bouncer with tool-specific truncation hints and summary accumulator
+    const truncationHints = new Map([
+        ["bash", "Use head/tail/grep to limit output, or add --max-lines flag"],
+        ["file_ops", "Read specific line ranges instead of entire files"],
+        ["memory_search", "Reduce limit parameter or narrow search query"],
+    ]);
+    const { wrapper: bouncerWrapper, getTruncationSummary } = createToolResultSizeBouncer(config.maxToolResultChars, deps.logger, truncationHints, registerTruncation);
+    // Per-turn aggregate result budget
+    const { wrapper: turnBudgetWrapper, getTurnBudgetSummary } = createTurnResultBudgetWrapper(200_000, // MAX_TOOL_RESULTS_PER_TURN_CHARS
+    500, // MIN_CHARS_PER_TOOL
+    deps.logger, registerTruncation);
+    // Shared TTL split estimate, populated by requestBodyInjector, consumed by bridge
+    const ttlSplit = { cacheWrite5mTokens: 0, cacheWrite1hTokens: 0 };
+    // Capture adaptive retention into local const to prevent race condition.
+    const capturedRetention = getAdaptiveRetention();
+    const capturedCacheRetention = getExecutionCacheRetention();
+    // Wrapper chain order (outermost first):
+    // ttlGuard -> validationErrorFormatter -> toolResultSizeBouncer -> turnResultBudget ->
+    //   configResolver -> requestBodyInjector (Anthropic) -> geminiCacheInjector (Google) -> [traceWriters]
+    // TTL guard is outermost wrapper
+    const onTtlExpiry = () => {
+        // Four coordinated resets on TTL expiry
+        capturedRetention?.reset(); // 1. Reset adaptive retention to cold-start
+        clearSessionCacheWarm(formattedKey); // 2. Clear session warm state
+        cacheBreakDetector.notifyTtlExpiry(formattedKey); // 3. Notify detector
+        clearSessionLatches(formattedKey); // 4. SESS-LATCH: Reset latches for fresh cache cycle
+        // Latch idle thinking clear when elapsed > 1h
+        if (!executionOverrides?.spawnPacket) {
+            const elapsed = getElapsedSinceLastResponse(formattedKey);
+            if (elapsed !== undefined && elapsed > 60 * 60 * 1000) {
+                getOrCreateSessionLatches(formattedKey).idleThinkingClear.setOnce(true);
+            }
+        }
+    };
+    wrappers.push(createTtlGuard({
+        sessionKey: formattedKey,
+        getRetention: () => capturedRetention?.getRetention(),
+        onTtlExpiry,
+        logger: deps.logger,
+    }), validationErrorFormatter, bouncerWrapper, turnBudgetWrapper, createConfigResolver({
+        maxTokens: config.maxTokens,
+        temperature: config.temperature ?? resolveToolCallingTemperature(modelTier),
+        // SDK breakpoint on last message must always use "short" (5m).
+        // getMessageRetention() now returns "long" after escalation, but the SDK's
+        // own last-message breakpoint is the most volatile position.
+        // Only override when adaptive retention or explicit config exists; otherwise
+        // let the original resolution chain (undefined) flow through so the provider
+        // guard in config-resolver.ts skips non-configured agents.
+        cacheRetention: () => {
+            if (capturedRetention || capturedCacheRetention || config.cacheRetention) {
+                return "short";
+            }
+            return undefined;
+        },
+    }, deps.logger), createRequestBodyInjector({
+        getCacheRetention: () => capturedRetention?.getRetention()
+            ?? capturedCacheRetention ?? config.cacheRetention,
+        getMessageRetention: () => capturedRetention?.getMessageRetention(),
+        getSystemPromptBlocks: () => systemPromptBlocks,
+        fastMode: config.fastMode,
+        storeCompletions: config.storeCompletions,
+        getMinTokensOverride: getExecutionMinTokensOverride,
+        cacheBreakpointStrategy: config.cacheBreakpointStrategy,
+        skipCacheWrite: !!executionOverrides?.spawnPacket,
+        cacheWriteTimestamp: executionOverrides?.spawnPacket?.cacheSafeParams?.cacheWriteTimestamp,
+        parentCacheRetention: executionOverrides?.spawnPacket?.cacheSafeParams?.cacheRetention,
+        getCacheFenceIndex: () => getBreakpointIndex(formattedKey) ?? -1,
+        getElapsedSinceLastResponse: () => getElapsedSinceLastResponse(formattedKey),
+        observationKeepWindow: 25,
+        microcompactTokenCeiling: 180_000,
+        onContentModification: () => cacheBreakDetector.notifyContentModification(formattedKey),
+        onAdaptiveRetentionReset: () => capturedRetention?.reset(),
+        sessionKey: formattedKey,
+        onBreakpointsPlaced: onBreakpointsPlaced
+            ? (highestIdx) => onBreakpointsPlaced(highestIdx)
+            : undefined,
+        onPayloadForCacheDetection: (apiParams, model, headers) => {
+            if (isAnthropicFamily(model.provider)) {
+                const stateInput = extractAnthropicPromptState(apiParams, model.id, capturedRetention?.getRetention(), formattedKey, agentId ?? "unknown", headers);
+                cacheBreakDetector.recordPromptState(stateInput);
+            }
+        },
+        getDeferredToolNames: () => {
+            return new Set(deferralResult?.deferredNames ?? []);
+        },
+        getBetaHeaderLatch: () => formattedKey ? getOrCreateSessionLatches(formattedKey).betaHeader : null,
+        getRetentionLatch: () => formattedKey ? getOrCreateSessionLatches(formattedKey).retention : null,
+        getDeferLoadingLatch: () => formattedKey ? getOrCreateSessionLatches(formattedKey).deferLoading : null,
+        // Total MCP tool count for all-deferred detection.
+        // MCP tools use "mcp:" or "mcp__" name prefix (see tool-deferral.ts).
+        getTotalMcpToolCount: () => {
+            if (!deferralResult)
+                return 0;
+            const allTools = [...deferralResult.activeTools, ...deferralResult.deferredEntries.map(e => ({ name: e.name }))];
+            return allTools.filter(t => t.name.startsWith("mcp:") || t.name.startsWith("mcp__")).length;
+        },
+        // Feature flag hash for config-aware tool cache invalidation.
+        featureFlagHash: computeFeatureFlagHash({ toolPolicy: { mode: config.skills?.toolPolicy?.profile } }),
+        // Eviction cooldown getter for breakpoint budget override.
+        getEvictionCooldown: () => getEvictionCooldown(formattedKey),
+        // Block stability tracker for message breakpoint TTL promotion.
+        // Only active for non-subagent sessions (skipCacheWrite=false).
+        blockStabilityTracker,
+        stabilityThreshold: 3, // Promote after 3 consecutive identical calls
+        // TTL split estimate callback — updates shared mutable object for bridge consumption.
+        onTtlSplitEstimate: (estimate) => {
+            ttlSplit.cacheWrite5mTokens = estimate.cacheWrite5mTokens;
+            ttlSplit.cacheWrite1hTokens = estimate.cacheWrite1hTokens;
+        },
+    }, deps.logger));
+    // Gemini cache injector -- mutually exclusive with
+    // requestBodyInjector via isGoogleFamily/isAnthropicFamily provider guards.
+    if (deps.geminiCacheManager) {
+        const geminiCacheConfig = config.geminiCache ?? { enabled: false, maxActiveCaches: 20 };
+        wrappers.push(createGeminiCacheInjector({
+            enabled: geminiCacheConfig.enabled,
+            cacheManager: deps.geminiCacheManager,
+            sessionKey: formattedKey,
+            agentId: agentId ?? "unknown",
+            onCacheHit: onGeminiCacheHit
+                ? (entry) => onGeminiCacheHit(entry)
+                : undefined,
+            onPayloadForCacheDetection: (apiParams, model) => {
+                if (isGoogleFamily(model.provider)) {
+                    const stateInput = extractGeminiPromptState(apiParams, model.id, formattedKey, agentId ?? "unknown");
+                    cacheBreakDetector.recordPromptState(stateInput);
+                }
+            },
+        }, deps.logger));
+    }
+    // Conditional JSONL trace wrappers
+    if (config.tracing?.enabled) {
+        const rawOutputDir = config.tracing.outputDir.replace(/^~/, homedir());
+        // Validate trace output directory with safePath
+        let outputDir;
+        try {
+            const baseDir = config.tracing.outputDir.startsWith("~") ? homedir() : path.dirname(rawOutputDir);
+            const relativePart = config.tracing.outputDir.startsWith("~")
+                ? config.tracing.outputDir.slice(2) // strip "~/"
+                : path.basename(rawOutputDir);
+            outputDir = safePath(baseDir, relativePart);
+        }
+        catch {
+            deps.logger.warn({ outputDir: rawOutputDir, hint: "Trace output directory failed path validation", errorKind: "validation" }, "Trace output directory rejected by safePath -- tracing disabled for this session");
+            outputDir = ""; // sentinel to skip
+        }
+        if (outputDir) {
+            const sessionSlug = formattedKey.replace(/[^a-zA-Z0-9-_]/g, "_");
+            const cacheTracePath = `${outputDir}/${sessionSlug}.cache-trace.jsonl`;
+            const apiPayloadPath = `${outputDir}/${sessionSlug}.api-payload.jsonl`;
+            // Rotation defaults from daemon.logging.tracing
+            const traceMaxSize = deps.tracingDefaults?.maxSize ?? "5m";
+            const traceMaxFiles = deps.tracingDefaults?.maxFiles ?? 3;
+            wrappers.push(createCacheTraceWriter({ filePath: cacheTracePath, agentId, sessionId: formattedKey, maxSize: traceMaxSize, maxFiles: traceMaxFiles }, deps.logger), createApiPayloadTraceWriter({ filePath: apiPayloadPath, agentId, sessionId: formattedKey, maxSize: traceMaxSize, maxFiles: traceMaxFiles }, deps.logger));
+            deps.logger.info({ outputDir, cacheTracePath, apiPayloadPath }, "JSONL tracing enabled");
+        }
+    }
+    return {
+        wrappers,
+        contextEngineRef,
+        cacheBreakDetector,
+        truncationMetaRegistry,
+        getTruncationSummary,
+        getTurnBudgetSummary,
+        capturedRetention,
+        ttlSplit,
+    };
+}