comisai 1.0.4

package/node_modules/@comis/agent/dist/executor/executor-tool-pipeline.js

@@ -0,0 +1,192 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Tool pipeline processing for PiExecutor.
+ *
+ * Extracted from pi-executor.ts execute() to isolate tool deferral wiring,
+ * schema snapshot comparison, JIT guide wrapping, schema pruning,
+ * provider-specific normalization, mutation serializer setup, and xAI HTML
+ * entity decoding into a focused module.
+ *
+ * Consumers:
+ * - pi-executor.ts: calls pipeline functions during tool assembly in execute()
+ *
+ * @module
+ */
+import { getToolSchemaSnapshots, setToolSchemaSnapshots, getToolSchemaSnapshotHash, setToolSchemaSnapshotHash, deleteToolSchemaSnapshots, computeToolCompositionHash, } from "./executor-session-state.js";
+import { createJitGuideWrapper } from "./jit-guide-injector.js";
+import { pruneToolSchemas } from "../safety/tool-schema-safety.js";
+import { normalizeToolSchemasForProvider } from "../provider/tool-schema/normalize.js";
+import { createMutationSerializer, isConcurrencySafe } from "./tool-parallelism.js";
+// ---------------------------------------------------------------------------
+// HTML entity decoding for xAI/Grok tool call arguments
+// ---------------------------------------------------------------------------
+/**
+ * Recursively decode HTML entities in all string values of a params object.
+ * Used for xAI/Grok which HTML-encodes tool call argument strings.
+ * Only decodes the 4 standard XML entities: & < > "
+ */
+export function decodeHtmlEntitiesInParams(params) {
+    const result = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (typeof value === "string") {
+            result[key] = value
+                .replace(/&/g, "&")
+                .replace(/&lt;/g, "<")
+                .replace(/&gt;/g, ">")
+                .replace(/&quot;/g, '"');
+        }
+        else if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+            result[key] = decodeHtmlEntitiesInParams(value);
+        }
+        else if (Array.isArray(value)) {
+            result[key] = value.map((v) => typeof v === "string"
+                ? v.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"')
+                : (v !== null && typeof v === "object" && !Array.isArray(v))
+                    ? decodeHtmlEntitiesInParams(v)
+                    : v);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/** Apply JIT guide wrapping to tools. */
+export function applyJitGuideWrapping(params) {
+    return createJitGuideWrapper(params.tools, params.deliveredGuides, params.logger);
+}
+/** Apply schema pruning for small models. Returns processed tools. */
+export function applySchemasPruning(params) {
+    if (params.modelTier !== "small")
+        return params.tools;
+    const pruneResult = pruneToolSchemas(params.tools);
+    // INFO log for schema pruning (promoted, per-execution boundary event)
+    params.logger.info({
+        removedCount: pruneResult.totalRemoved,
+        tokensSaved: pruneResult.estimatedTokensSaved,
+        toolCount: pruneResult.tools.length,
+    }, "Schema descriptions pruned for small model");
+    return pruneResult.tools;
+}
+/**
+ * Apply tool schema snapshot: on first turn, snapshot tool shapes; on
+ * subsequent turns, rebuild tools from snapshot shapes + live execute().
+ *
+ * Returns the stable tool set with snapshotted schemas.
+ */
+export function applySchemaSnapshot(params) {
+    const { tools, sessionKey, deferredNames } = params;
+    // Hash-based invalidation -- when tool composition changes (discovery
+    // or re-deferral), invalidate the snapshot so it is recreated with the new set.
+    const currentHash = computeToolCompositionHash(tools.map(t => t.name));
+    const snapshotHash = getToolSchemaSnapshotHash(sessionKey);
+    if (snapshotHash && snapshotHash !== currentHash) {
+        // Tool composition changed (discovery or re-deferral) -- invalidate snapshot
+        deleteToolSchemaSnapshots(sessionKey);
+    }
+    let snapshotShapes = getToolSchemaSnapshots(sessionKey);
+    if (!snapshotShapes) {
+        // First turn (or invalidated): capture tool shapes after deferral + pruning
+        snapshotShapes = tools.map(t => ({
+            name: t.name,
+            label: t.label ?? t.name,
+            description: t.description ?? "",
+            parameters: t.parameters ? JSON.parse(JSON.stringify(t.parameters)) : undefined,
+        }));
+        setToolSchemaSnapshots(sessionKey, snapshotShapes);
+        setToolSchemaSnapshotHash(sessionKey, currentHash);
+        return tools;
+    }
+    // Subsequent turns: rebuild tools from snapshotted shapes + live execute()
+    const liveToolMap = new Map(tools.map(t => [t.name, t]));
+    const stableTools = [];
+    for (const shape of snapshotShapes) {
+        const liveTool = liveToolMap.get(shape.name);
+        if (liveTool) {
+            // Use snapshotted shape with live execute()
+            stableTools.push({
+                ...liveTool,
+                description: shape.description,
+                parameters: shape.parameters,
+            });
+        }
+        else {
+            // Tool disappeared (MCP disconnect) or deferred. Keep shape with stub execute().
+            // If tool is in the deferred set, return discover_tools hint instead
+            // of generic "temporarily unavailable" message.
+            stableTools.push({
+                name: shape.name,
+                label: shape.label,
+                description: shape.description,
+                parameters: shape.parameters,
+                execute: async () => {
+                    if (deferredNames.includes(shape.name)) {
+                        return {
+                            content: [{ type: "text", text: `Tool "${shape.name}" is deferred. Call discover_tools with query "select:${shape.name}" to fetch the schema first.` }],
+                            isError: true,
+                            details: undefined,
+                        };
+                    }
+                    return {
+                        content: [{ type: "text", text: `Tool "${shape.name}" is temporarily unavailable (MCP server disconnected). Try again later or use an alternative approach.` }],
+                        isError: true,
+                        details: undefined,
+                    };
+                },
+            });
+        }
+    }
+    // Append any NEW tools that appeared after snapshot (e.g., MCP reconnect with new tools)
+    for (const tool of tools) {
+        if (!snapshotShapes.some(s => s.name === tool.name)) {
+            stableTools.push(tool);
+            snapshotShapes.push({
+                name: tool.name,
+                label: tool.label ?? tool.name,
+                description: tool.description ?? "",
+                parameters: tool.parameters ? JSON.parse(JSON.stringify(tool.parameters)) : undefined,
+            });
+        }
+    }
+    return stableTools;
+}
+/**
+ * Apply provider-specific tool normalization: web search filtering,
+ * schema normalization, xAI HTML entity decoding, and mutation serializer.
+ *
+ * Returns the fully processed tool set ready for session creation.
+ */
+export function applyProviderNormalization(params) {
+    let tools = params.tools;
+    // Filter out Comis web_search when provider has native web search (e.g., xAI webSearch)
+    if (params.compat?.nativeWebSearchTool) {
+        tools = tools.filter((t) => t.name !== "web_search");
+    }
+    // Per-provider tool schema normalization (after snapshot, before session creation)
+    tools = normalizeToolSchemasForProvider(tools, {
+        provider: params.provider,
+        modelId: params.modelId,
+        compat: params.compat,
+    });
+    // Decode HTML entities in xAI tool call arguments via prepareArguments hook.
+    // Runs BEFORE TypeBox schema validation in the SDK agent loop (agent-loop.js:300-301),
+    // which is the correct interception point for argument normalization.
+    if (params.compat?.toolCallArgumentsEncoding === "html-entities") {
+        tools = tools.map((tool) => ({
+            ...tool,
+            prepareArguments: (args) => decodeHtmlEntitiesInParams(args),
+        }));
+    }
+    return tools;
+}
+/**
+ * Apply mutation serializer to tool execute() methods.
+ * SDK runs in default "parallel" mode -- read-only tools execute concurrently,
+ * mutating tools serialize via the mutex to prevent ordering bugs.
+ */
+export function applyMutationSerializer(tools, logger) {
+    const serializeTools = createMutationSerializer();
+    const result = serializeTools(tools);
+    logger.debug({ mutatingToolCount: result.filter(t => !isConcurrencySafe(t.name)).length }, "Mutation serializer applied to tool pipeline");
+    return result;
+}

package/node_modules/@comis/agent/dist/executor/fault-injector.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Test-only fault injector for the agent executor.
+ *
+ * Gated by the `COMIS_TEST_SILENT_FAIL_FLAG` environment variable (which
+ * names a file path). When the env var is set AND that file exists, the
+ * next call to tryInjectSilentFailure() consumes the file atomically and
+ * returns a synthetic silent-LLM-failure result. This lets operators
+ * validate the FINDING-2 retry/reuseSessionKey code path end-to-end
+ * without waiting for Anthropic's real API to fail silently.
+ *
+ * Safety:
+ * - Env var is ABSENT in every shipped config (installer, examples, docs).
+ *   No code activation in production without an explicit operator action.
+ * - Even with env var set, the file-flag must be explicitly created.
+ * - `unlinkSync` is atomic on POSIX, so parallel execute() calls cannot
+ *   both inject — at most one wins the race per armed flag.
+ * - Flag auto-consumes on first hit; no stuck-state risk.
+ *
+ * Operational note — `PrivateTmp=yes`:
+ *   The shipped systemd unit sets `PrivateTmp=yes`, so the daemon has an
+ *   isolated `/tmp` namespace. An operator who `touch`es a path under
+ *   `/tmp/` on the host will NOT make that file visible to the daemon —
+ *   `unlinkSync` will report ENOENT. Always pick a flag path under the
+ *   daemon's data dir (e.g. `/home/comis/.comis/.test-fault-flag`) so the
+ *   operator shell and the daemon see the same file.
+ *
+ * @module
+ */
+/** Shape returned when fault injection fires (otherwise `undefined`). */
+export interface SilentFailureInjection {
+    finishReason: "error";
+    response: "";
+    llmCalls: 0;
+    stepsExecuted: 0;
+}
+/** Minimal logger interface for fault-injection diagnostics. */
+interface Logger {
+    warn(obj: Record<string, unknown>, msg: string): void;
+    debug(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * If the fault flag is armed, atomically consume it and return a synthetic
+ * failure shape. Returns `undefined` in all other paths so the caller falls
+ * through to real execution.
+ *
+ * @param logger - For WARN on successful injection, DEBUG on unexpected FS errors.
+ * @param context - Extra fields attached to the WARN log (agentId, sessionKey, etc.).
+ * @returns SilentFailureInjection when fault fired; undefined otherwise.
+ */
+export declare function tryInjectSilentFailure(logger: Logger, context?: Record<string, unknown>): SilentFailureInjection | undefined;
+export {};

package/node_modules/@comis/agent/dist/executor/fault-injector.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Test-only fault injector for the agent executor.
+ *
+ * Gated by the `COMIS_TEST_SILENT_FAIL_FLAG` environment variable (which
+ * names a file path). When the env var is set AND that file exists, the
+ * next call to tryInjectSilentFailure() consumes the file atomically and
+ * returns a synthetic silent-LLM-failure result. This lets operators
+ * validate the FINDING-2 retry/reuseSessionKey code path end-to-end
+ * without waiting for Anthropic's real API to fail silently.
+ *
+ * Safety:
+ * - Env var is ABSENT in every shipped config (installer, examples, docs).
+ *   No code activation in production without an explicit operator action.
+ * - Even with env var set, the file-flag must be explicitly created.
+ * - `unlinkSync` is atomic on POSIX, so parallel execute() calls cannot
+ *   both inject — at most one wins the race per armed flag.
+ * - Flag auto-consumes on first hit; no stuck-state risk.
+ *
+ * Operational note — `PrivateTmp=yes`:
+ *   The shipped systemd unit sets `PrivateTmp=yes`, so the daemon has an
+ *   isolated `/tmp` namespace. An operator who `touch`es a path under
+ *   `/tmp/` on the host will NOT make that file visible to the daemon —
+ *   `unlinkSync` will report ENOENT. Always pick a flag path under the
+ *   daemon's data dir (e.g. `/home/comis/.comis/.test-fault-flag`) so the
+ *   operator shell and the daemon see the same file.
+ *
+ * @module
+ */
+import { unlinkSync } from "node:fs";
+/**
+ * If the fault flag is armed, atomically consume it and return a synthetic
+ * failure shape. Returns `undefined` in all other paths so the caller falls
+ * through to real execution.
+ *
+ * @param logger - For WARN on successful injection, DEBUG on unexpected FS errors.
+ * @param context - Extra fields attached to the WARN log (agentId, sessionKey, etc.).
+ * @returns SilentFailureInjection when fault fired; undefined otherwise.
+ */
+export function tryInjectSilentFailure(logger, context = {}) {
+    // eslint-disable-next-line no-restricted-syntax -- ops toggle read before SecretManager is initialized
+    const faultFlag = process.env.COMIS_TEST_SILENT_FAIL_FLAG;
+    if (!faultFlag)
+        return undefined;
+    // Optional scope gate: COMIS_TEST_SILENT_FAIL_SCOPE controls which
+    // execute() calls are eligible to consume the flag.
+    //   unset / "all"       — any execute() (parent or sub-agent) may fire
+    //   "subagent"          — only sub-agent sessions may fire
+    //   "parent"            — only non-sub-agent sessions may fire
+    // Sub-agent session keys contain "sub-agent:" (see sub-agent-runner).
+    // eslint-disable-next-line no-restricted-syntax -- ops toggle read before SecretManager is initialized
+    const scope = process.env.COMIS_TEST_SILENT_FAIL_SCOPE;
+    if (scope === "subagent" || scope === "parent") {
+        const sessionKey = typeof context.sessionKey === "string" ? context.sessionKey : "";
+        const isSubAgent = sessionKey.includes("sub-agent:") || sessionKey.includes("sub-agent-");
+        const scopeMatches = (scope === "subagent" && isSubAgent) ||
+            (scope === "parent" && !isSubAgent);
+        if (!scopeMatches)
+            return undefined;
+    }
+    try {
+        // Atomic consume — if another execute() already unlinked, ENOENT is thrown
+        // and we fall through to the catch.
+        unlinkSync(faultFlag);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            // Flag not present (common case when env var set but flag not armed,
+            // or another parallel execute() won the race) — normal execution.
+            return undefined;
+        }
+        // Unexpected FS error (EACCES, EISDIR, ...) — log but don't block real
+        // execution. Better to fail open than to break the daemon on a bad flag.
+        logger.debug({
+            err,
+            faultFlag,
+            hint: "Unexpected error consuming COMIS_TEST_SILENT_FAIL_FLAG; falling through to real execution",
+        }, "Fault flag consume failed");
+        return undefined;
+    }
+    logger.warn({
+        ...context,
+        hint: "COMIS_TEST_SILENT_FAIL_FLAG consumed -- this turn returns synthetic error for FINDING-2 retry-path testing",
+        errorKind: "dependency",
+    }, "Synthetic silent LLM failure injected for retry-path testing");
+    return {
+        finishReason: "error",
+        response: "",
+        llmCalls: 0,
+        stepsExecuted: 0,
+    };
+}

package/node_modules/@comis/agent/dist/executor/gemini-cache-injector.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Gemini cache injector stream wrapper.
+ *
+ * Injects CachedContent name into Gemini API payloads and atomically strips
+ * the three inherited fields (systemInstruction, tools, toolConfig) to avoid
+ * double-billing. Operates inside the onPayload hook (post-buildParams) per D-04.
+ *
+ * Handles cache injection, inherited field stripping, and staleness recovery.
+ *
+ * @module
+ */
+import type { ComisLogger } from "@comis/infra";
+import type { StreamFnWrapper } from "./stream-wrappers/types.js";
+import type { GeminiCacheManager, CacheEntry } from "./gemini-cache-manager.js";
+export interface GeminiCacheInjectorConfig {
+    /** Whether Gemini explicit caching is enabled (from geminiCache.enabled config). */
+    enabled: boolean;
+    /** The GeminiCacheManager instance for cache lifecycle. */
+    cacheManager: GeminiCacheManager;
+    /** Current session key for cache scoping. */
+    sessionKey: string;
+    /** Current agent ID for cache scoping. */
+    agentId: string;
+    /** Callback when a Gemini CachedContent entry is successfully injected.
+     *  Called with the CacheEntry so the caller can capture cache hit stats for logging. */
+    onCacheHit?: (entry: CacheEntry) => void;
+    /** Callback for cache break detection Phase 1.
+     *  Called with the API-ready payload AFTER any cache injection. */
+    onPayloadForCacheDetection?: (params: Record<string, unknown>, model: {
+        id: string;
+        provider: string;
+        [key: string]: unknown;
+    }) => void;
+}
+/**
+ * Create a Gemini cache injector stream wrapper.
+ *
+ * The wrapper intercepts Gemini API calls to:
+ * 1. Look up or create a CachedContent entry via the GeminiCacheManager
+ * 2. Inject the cache name into the payload's config.cachedContent field
+ * 3. Strip systemInstruction, tools, and toolConfig from config (already in cache)
+ *
+ * Provider guard ensures this is a no-op for non-Google providers.
+ * Mutual exclusion with requestBodyInjector is guaranteed by provider family guards.
+ *
+ * @param config - Injector configuration
+ * @param logger - Logger instance for debug/warn output
+ * @returns StreamFnWrapper for the wrapper chain
+ */
+export declare function createGeminiCacheInjector(config: GeminiCacheInjectorConfig, logger: ComisLogger): StreamFnWrapper;

package/node_modules/@comis/agent/dist/executor/gemini-cache-injector.js

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Gemini cache injector stream wrapper.
+ *
+ * Injects CachedContent name into Gemini API payloads and atomically strips
+ * the three inherited fields (systemInstruction, tools, toolConfig) to avoid
+ * double-billing. Operates inside the onPayload hook (post-buildParams) per D-04.
+ *
+ * Handles cache injection, inherited field stripping, and staleness recovery.
+ *
+ * @module
+ */
+import { suppressError } from "@comis/shared";
+import { computeCacheContentHash } from "./gemini-cache-manager.js";
+import { isGoogleFamily, isGoogleAIStudio } from "../provider/capabilities.js";
+import { CHARS_PER_TOKEN_RATIO_STRUCTURED } from "../context-engine/constants.js";
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a Gemini cache injector stream wrapper.
+ *
+ * The wrapper intercepts Gemini API calls to:
+ * 1. Look up or create a CachedContent entry via the GeminiCacheManager
+ * 2. Inject the cache name into the payload's config.cachedContent field
+ * 3. Strip systemInstruction, tools, and toolConfig from config (already in cache)
+ *
+ * Provider guard ensures this is a no-op for non-Google providers.
+ * Mutual exclusion with requestBodyInjector is guaranteed by provider family guards.
+ *
+ * @param config - Injector configuration
+ * @param logger - Logger instance for debug/warn output
+ * @returns StreamFnWrapper for the wrapper chain
+ */
+export function createGeminiCacheInjector(config, logger) {
+    return function geminiCacheInjector(next) {
+        // Use implicit parameter types from StreamFn (same pattern as createRequestBodyInjector)
+        return (model, context, options) => {
+            // Provider guard -- no-op for non-Google providers
+            if (!isGoogleFamily(model.provider)) {
+                return next(model, context, options);
+            }
+            // Enabled guard
+            if (!config.enabled) {
+                return next(model, context, options);
+            }
+            // AI Studio guard -- only AI Studio supports the Caches API
+            if (!isGoogleAIStudio(model.provider)) {
+                return next(model, context, options);
+            }
+            // Chain onPayload callback (preserve any existing onPayload from upstream wrappers)
+            const existingOnPayload = options?.onPayload;
+            const injectedOptions = {
+                ...options,
+                onPayload: async (payload, payloadModel) => {
+                    // Run existing onPayload first (if any)
+                    const resolvedParams = (existingOnPayload
+                        ? await Promise.resolve(existingOnPayload(payload, payloadModel))
+                        : payload);
+                    // Cast payloadModel for field access
+                    const modelInfo = payloadModel;
+                    // Extract config sub-object from Gemini payload
+                    const configObj = resolvedParams.config;
+                    if (!configObj) {
+                        // No config object -- pass through
+                        config.onPayloadForCacheDetection?.(resolvedParams, modelInfo);
+                        return resolvedParams;
+                    }
+                    const systemInstruction = configObj.systemInstruction;
+                    const tools = configObj.tools;
+                    const toolConfig = configObj.toolConfig;
+                    // Estimate tokens from cacheable content
+                    const estimatedTokens = Math.ceil(JSON.stringify({ systemInstruction, tools, toolConfig }).length / CHARS_PER_TOKEN_RATIO_STRUCTURED);
+                    // Compute content hash for cache invalidation
+                    const contentHash = computeCacheContentHash(systemInstruction, tools ?? [], toolConfig);
+                    // Request cache entry from manager
+                    const cacheResult = await config.cacheManager.getOrCreate({
+                        sessionKey: config.sessionKey,
+                        agentId: config.agentId,
+                        model: modelInfo.id,
+                        provider: modelInfo.provider,
+                        systemInstruction,
+                        tools: tools ?? [],
+                        toolConfig,
+                        contentHash,
+                        estimatedTokens,
+                    });
+                    // Handle getOrCreate error -- log WARN, evict stale, pass through uncached
+                    if (!cacheResult.ok) {
+                        logger.warn({
+                            err: cacheResult.error,
+                            sessionKey: config.sessionKey,
+                            hint: "Cache injection failed, passing through uncached",
+                            errorKind: "provider",
+                        }, "Gemini cache injector: getOrCreate failed");
+                        suppressError(config.cacheManager.dispose(config.sessionKey), "stale-cache-eviction");
+                        config.onPayloadForCacheDetection?.(resolvedParams, modelInfo);
+                        return resolvedParams;
+                    }
+                    // Below min tokens or no API key -- pass through uncached
+                    const entry = cacheResult.value;
+                    if (!entry) {
+                        config.onPayloadForCacheDetection?.(resolvedParams, modelInfo);
+                        return resolvedParams;
+                    }
+                    // D-03: Assertion -- all three fields must be present for stripping
+                    if (configObj.systemInstruction === undefined ||
+                        configObj.tools === undefined ||
+                        configObj.toolConfig === undefined) {
+                        logger.warn({
+                            sessionKey: config.sessionKey,
+                            cacheName: entry.name,
+                            hint: "Expected fields missing from config -- cache entry stale, evicting",
+                            errorKind: "validation",
+                        }, "Gemini cache injector: stale cache detected (D-03)");
+                        suppressError(config.cacheManager.dispose(config.sessionKey), "stale-cache-eviction-d03");
+                        config.onPayloadForCacheDetection?.(resolvedParams, modelInfo);
+                        return resolvedParams;
+                    }
+                    // Inject cachedContent and strip inherited fields atomically
+                    configObj.cachedContent = entry.name;
+                    delete configObj.systemInstruction;
+                    delete configObj.tools;
+                    delete configObj.toolConfig;
+                    logger.debug({
+                        cachedContent: entry.name,
+                        cachedTokens: entry.cachedTokens,
+                        sessionKey: config.sessionKey,
+                    }, "Gemini cache injector: injected cached content");
+                    // Notify caller of successful cache injection for observability
+                    config.onCacheHit?.(entry);
+                    // D-07: Phase 1 cache break detection callback
+                    config.onPayloadForCacheDetection?.(resolvedParams, modelInfo);
+                    return resolvedParams;
+                },
+            };
+            return next(model, context, injectedOptions);
+        };
+    };
+}

package/node_modules/@comis/agent/dist/executor/gemini-cache-lifecycle.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Gemini cache lifecycle wiring for daemon events.
+ *
+ * Subscribes to `session:expired` on the event bus and disposes the
+ * corresponding Gemini CachedContent entry (fire-and-forget via
+ * suppressError). This prevents orphaned CachedContent resources from
+ * lingering until API-side TTL expiry when sessions are cleaned up.
+ *
+ * Session expiry triggers Gemini cache disposal.
+ *
+ * @module
+ */
+import { type SessionKey } from "@comis/core";
+import type { GeminiCacheManager } from "./gemini-cache-manager.js";
+/**
+ * Wire session expiry events to Gemini cache disposal.
+ *
+ * When a session expires, the corresponding Gemini CachedContent is
+ * disposed fire-and-forget. Rejection is suppressed to avoid unhandled
+ * promise rejections -- the cache will naturally expire via API-side TTL.
+ *
+ * @param eventBus - Narrow structural type requiring only `on("session:expired", ...)`
+ * @param cacheManager - GeminiCacheManager instance to call dispose on
+ */
+export declare function wireGeminiCacheCleanup(eventBus: {
+    on(event: "session:expired", handler: (payload: {
+        sessionKey: SessionKey;
+        reason: string;
+    }) => void): void;
+}, cacheManager: GeminiCacheManager): void;

package/node_modules/@comis/agent/dist/executor/gemini-cache-lifecycle.js

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Gemini cache lifecycle wiring for daemon events.
+ *
+ * Subscribes to `session:expired` on the event bus and disposes the
+ * corresponding Gemini CachedContent entry (fire-and-forget via
+ * suppressError). This prevents orphaned CachedContent resources from
+ * lingering until API-side TTL expiry when sessions are cleaned up.
+ *
+ * Session expiry triggers Gemini cache disposal.
+ *
+ * @module
+ */
+import { formatSessionKey } from "@comis/core";
+import { suppressError } from "@comis/shared";
+/**
+ * Wire session expiry events to Gemini cache disposal.
+ *
+ * When a session expires, the corresponding Gemini CachedContent is
+ * disposed fire-and-forget. Rejection is suppressed to avoid unhandled
+ * promise rejections -- the cache will naturally expire via API-side TTL.
+ *
+ * @param eventBus - Narrow structural type requiring only `on("session:expired", ...)`
+ * @param cacheManager - GeminiCacheManager instance to call dispose on
+ */
+export function wireGeminiCacheCleanup(eventBus, cacheManager) {
+    eventBus.on("session:expired", (payload) => {
+        const key = formatSessionKey(payload.sessionKey);
+        suppressError(cacheManager.dispose(key), "gemini-cache-session-dispose");
+    });
+}

package/node_modules/@comis/agent/dist/executor/gemini-cache-manager.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Gemini CachedContent lifecycle manager.
+ *
+ * Creates, reuses, refreshes, and disposes CachedContent resources via the
+ * @google/genai SDK. Uses SHA-256 content hashing for invalidation and
+ * concurrent dedup via pending Promise tracking.
+ *
+ * .
+ *
+ * @module
+ */
+import type { Result } from "@comis/shared";
+/** Minimum cacheable tokens per Gemini model family. */
+export declare const GEMINI_MIN_CACHEABLE_TOKENS: Record<string, number>;
+export declare const GEMINI_DEFAULT_MIN_CACHEABLE_TOKENS = 2048;
+export interface CacheEntry {
+    name: string;
+    contentHash: string;
+    model: string;
+    agentId: string;
+    sessionKey: string;
+    expiresAt: number;
+    createdAt: number;
+    cachedTokens: number;
+}
+export interface CacheRequest {
+    sessionKey: string;
+    agentId: string;
+    model: string;
+    provider: string;
+    systemInstruction: unknown;
+    tools: unknown[];
+    toolConfig: unknown;
+    contentHash: string;
+    estimatedTokens: number;
+}
+export interface GeminiCacheManagerConfig {
+    getApiKey: () => string | undefined;
+    ttlSeconds: number;
+    maxActiveCachesPerAgent: number;
+    refreshThreshold: number;
+    logger: {
+        debug: (...args: unknown[]) => void;
+        warn: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+    };
+}
+export interface GeminiCacheManager {
+    getOrCreate(params: CacheRequest): Promise<Result<CacheEntry | undefined, Error>>;
+    dispose(sessionKey: string): Promise<void>;
+    disposeAll(): Promise<void>;
+    refresh(sessionKey: string): Promise<Result<void, Error>>;
+    getActiveCount(agentId: string): number;
+    /** Delete all orphaned comis:* caches from previous daemon runs. */
+    cleanupOrphaned(): Promise<Result<{
+        deleted: number;
+        skipped: number;
+    }, Error>>;
+}
+/**
+ * Compute a deterministic SHA-256 hex digest from system instruction, tools,
+ * and tool config. Used as the cache invalidation key.
+ */
+export declare function computeCacheContentHash(systemInstruction: unknown, tools: unknown[], toolConfig: unknown): string;
+/**
+ * Create a Gemini CachedContent lifecycle manager.
+ *
+ * Uses closure-scoped state (not module-level Maps) following the
+ * createCircuitBreaker / createBudgetGuard pattern.
+ *
+ * @param config - Manager configuration (API key getter, TTL, limits, logger)
+ * @returns GeminiCacheManager interface
+ */
+export declare function createGeminiCacheManager(config: GeminiCacheManagerConfig): GeminiCacheManager;