comisai 1.0.4

package/node_modules/@comis/agent/dist/executor/stream-wrappers/api-payload-trace-writer.js

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * API payload trace writer stream wrapper.
+ *
+ * Writes pre-call and post-call JSONL trace lines per LLM call with
+ * request payload details and token usage.
+ *
+ * @module
+ */
+import { suppressError } from "@comis/shared";
+import { appendJsonlLine } from "./cache-trace-writer.js";
+/**
+ * Create a wrapper that writes pre-call and post-call JSONL trace lines
+ * per LLM call with request payload details and token usage.
+ *
+ * Pre-call line: model, provider, message count, stream options.
+ * Post-call line: token usage (input/output/cacheRead/cacheWrite) captured
+ * asynchronously via fire-and-forget on the stream result promise.
+ *
+ * Purpose: Per-call observability for cost analysis.
+ *
+ * @param config - API payload trace configuration (file path, optional agent ID)
+ * @param logger - Logger for debug output
+ * @returns A named StreamFnWrapper ("apiPayloadTraceWriter")
+ */
+export function createApiPayloadTraceWriter(config, logger) {
+    return function apiPayloadTraceWriter(next) {
+        return (model, context, options) => {
+            // Extract relevant option keys for the pre-call trace
+            const traceOptions = {};
+            if (options) {
+                const opts = options;
+                for (const key of ["maxTokens", "temperature", "cacheRetention"]) {
+                    if (opts[key] !== undefined) {
+                        traceOptions[key] = opts[key];
+                    }
+                }
+            }
+            // Pre-call trace line
+            appendJsonlLine(config.filePath, {
+                ts: new Date().toISOString(),
+                type: "api_payload",
+                agentId: config.agentId,
+                sessionId: config.sessionId,
+                modelId: model.id,
+                provider: model.provider,
+                messageCount: context.messages.length,
+                options: traceOptions,
+            }, logger, config.maxSize, config.maxFiles);
+            // TTFT measurement -- record start time before stream call
+            const streamStartMs = Date.now();
+            const stream = next(model, context, options);
+            // Post-call usage capture + TTFT (fire-and-forget)
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK stream result() is untyped
+            const resultPromise = stream?.result?.();
+            if (resultPromise && typeof resultPromise.then === "function") {
+                const usageCapture = resultPromise.then((msg) => {
+                    // Capture TTFT when stream result resolves (first available timing point)
+                    const ttftMs = Date.now() - streamStartMs;
+                    logger.debug({
+                        ttftMs,
+                        modelId: model.id,
+                        provider: model.provider,
+                        agentId: config.agentId,
+                        sessionId: config.sessionId,
+                    }, "TTFT (time-to-first-token proxy)");
+                    const usage = msg?.usage;
+                    if (usage) {
+                        appendJsonlLine(config.filePath, {
+                            ts: new Date().toISOString(),
+                            type: "api_usage",
+                            agentId: config.agentId,
+                            sessionId: config.sessionId,
+                            modelId: model.id,
+                            provider: model.provider,
+                            usage: {
+                                input: usage.input,
+                                output: usage.output,
+                                cacheRead: usage.cacheRead,
+                                cacheWrite: usage.cacheWrite,
+                                totalTokens: usage.totalTokens,
+                            },
+                        }, logger, config.maxSize, config.maxFiles);
+                    }
+                });
+                suppressError(usageCapture, "trace usage capture");
+            }
+            return stream;
+        };
+    };
+}

package/node_modules/@comis/agent/dist/executor/stream-wrappers/cache-trace-writer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Cache trace writer stream wrapper.
+ *
+ * Writes a JSONL trace line per LLM call with model ID, message count,
+ * and a truncated SHA-256 digest of the system prompt.
+ *
+ * @module
+ */
+import type { ComisLogger } from "@comis/infra";
+import type { StreamFnWrapper } from "./types.js";
+/**
+ * Configuration for the cache trace JSONL writer wrapper.
+ */
+export interface CacheTraceConfig {
+    /** Absolute path to the JSONL trace output file */
+    filePath: string;
+    /** Agent ID for trace attribution */
+    agentId?: string;
+    /** Session ID for trace correlation */
+    sessionId?: string;
+    /** Max file size before rotation (k/m/g suffix). Undefined = no rotation. */
+    maxSize?: string;
+    /** Number of rotated files to keep. Undefined = no rotation. */
+    maxFiles?: number;
+}
+/**
+ * Parse a human-readable size string (e.g. "5m", "1g", "500k") into bytes.
+ *
+ * Supports k (1024), m (1024^2), g (1024^3) suffixes (case-insensitive).
+ * Returns 0 if the string cannot be parsed (disables rotation).
+ *
+ * @internal Exported for testing only.
+ */
+export declare function parseSize(sizeStr: string): number;
+/**
+ * Rotate a trace file if it exceeds the configured maximum size.
+ *
+ * Rotation scheme: foo.jsonl -> foo.jsonl.1 -> foo.jsonl.2 -> ...
+ * Files beyond maxFiles are deleted.
+ *
+ * Rotation failure is logged at WARN but never throws -- rotation must not
+ * block tracing.
+ */
+export declare function rotateIfNeeded(filePath: string, maxSize: string | undefined, maxFiles: number | undefined, logger: ComisLogger): void;
+/**
+ * Append a single JSONL line to the given file path.
+ *
+ * Sync I/O is acceptable -- one line per LLM call, not a hot path.
+ * Errors are silently logged to prevent trace I/O from breaking execution.
+ *
+ * If maxSize and maxFiles are provided, rotates the file before writing
+ * when it exceeds the configured size threshold.
+ */
+export declare function appendJsonlLine(filePath: string, entry: Record<string, unknown>, logger: ComisLogger, maxSize?: string, maxFiles?: number): void;
+/**
+ * Create a wrapper that writes a JSONL trace line per LLM call with
+ * model ID, message count, and a truncated SHA-256 digest of the system prompt.
+ *
+ * Purpose: Per-call observability for cache-hit analysis.
+ *
+ * @param config - Cache trace configuration (file path, optional agent ID)
+ * @param logger - Logger for debug output
+ * @returns A named StreamFnWrapper ("cacheTraceWriter")
+ */
+export declare function createCacheTraceWriter(config: CacheTraceConfig, logger: ComisLogger): StreamFnWrapper;

package/node_modules/@comis/agent/dist/executor/stream-wrappers/cache-trace-writer.js

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Cache trace writer stream wrapper.
+ *
+ * Writes a JSONL trace line per LLM call with model ID, message count,
+ * and a truncated SHA-256 digest of the system prompt.
+ *
+ * @module
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, statSync, renameSync, unlinkSync } from "node:fs";
+// ---------------------------------------------------------------------------
+// JSONL trace utilities
+// ---------------------------------------------------------------------------
+/**
+ * Parse a human-readable size string (e.g. "5m", "1g", "500k") into bytes.
+ *
+ * Supports k (1024), m (1024^2), g (1024^3) suffixes (case-insensitive).
+ * Returns 0 if the string cannot be parsed (disables rotation).
+ *
+ * @internal Exported for testing only.
+ */
+export function parseSize(sizeStr) {
+    const match = /^(\d+)([kmg])?$/i.exec(sizeStr);
+    if (!match)
+        return 0;
+    const num = parseInt(match[1], 10);
+    const suffix = (match[2] ?? "").toLowerCase();
+    switch (suffix) {
+        case "k": return num * 1024;
+        case "m": return num * 1024 * 1024;
+        case "g": return num * 1024 * 1024 * 1024;
+        default: return num;
+    }
+}
+/**
+ * Rotate a trace file if it exceeds the configured maximum size.
+ *
+ * Rotation scheme: foo.jsonl -> foo.jsonl.1 -> foo.jsonl.2 -> ...
+ * Files beyond maxFiles are deleted.
+ *
+ * Rotation failure is logged at WARN but never throws -- rotation must not
+ * block tracing.
+ */
+export function rotateIfNeeded(filePath, maxSize, maxFiles, logger) {
+    if (maxSize === undefined || maxFiles === undefined)
+        return;
+    const maxSizeBytes = parseSize(maxSize);
+    if (maxSizeBytes === 0)
+        return;
+    let fileSize;
+    try {
+        fileSize = statSync(filePath).size;
+    }
+    catch {
+        // File doesn't exist or stat failed -- nothing to rotate
+        return;
+    }
+    if (fileSize < maxSizeBytes)
+        return;
+    try {
+        // Delete oldest file if it would exceed maxFiles after rotation
+        const oldestPath = `${filePath}.${maxFiles}`;
+        try {
+            unlinkSync(oldestPath);
+        }
+        catch { /* may not exist */ }
+        // Shift existing rotated files: .N-1 -> .N
+        for (let i = maxFiles - 1; i >= 1; i--) {
+            const from = `${filePath}.${i}`;
+            const to = `${filePath}.${i + 1}`;
+            try {
+                renameSync(from, to);
+            }
+            catch { /* may not exist */ }
+        }
+        // Rename current file to .1
+        renameSync(filePath, `${filePath}.1`);
+    }
+    catch (rotateErr) {
+        logger.warn({
+            err: rotateErr,
+            filePath,
+            hint: "Trace file rotation failed; tracing continues to current file",
+            errorKind: "resource",
+        }, "Trace file rotation failed");
+    }
+}
+/**
+ * Append a single JSONL line to the given file path.
+ *
+ * Sync I/O is acceptable -- one line per LLM call, not a hot path.
+ * Errors are silently logged to prevent trace I/O from breaking execution.
+ *
+ * If maxSize and maxFiles are provided, rotates the file before writing
+ * when it exceeds the configured size threshold.
+ */
+export function appendJsonlLine(filePath, entry, logger, maxSize, maxFiles) {
+    try {
+        rotateIfNeeded(filePath, maxSize, maxFiles, logger);
+        appendFileSync(filePath, JSON.stringify(entry) + "\n");
+    }
+    catch (writeErr) {
+        logger.warn({
+            err: writeErr,
+            filePath,
+            hint: "Check trace output directory permissions and disk space",
+            errorKind: "resource",
+        }, "JSONL trace write failed");
+    }
+}
+/**
+ * Create a wrapper that writes a JSONL trace line per LLM call with
+ * model ID, message count, and a truncated SHA-256 digest of the system prompt.
+ *
+ * Purpose: Per-call observability for cache-hit analysis.
+ *
+ * @param config - Cache trace configuration (file path, optional agent ID)
+ * @param logger - Logger for debug output
+ * @returns A named StreamFnWrapper ("cacheTraceWriter")
+ */
+export function createCacheTraceWriter(config, logger) {
+    return function cacheTraceWriter(next) {
+        return (model, context, options) => {
+            const systemPromptDigest = context.systemPrompt
+                ? createHash("sha256")
+                    .update(context.systemPrompt)
+                    .digest("hex")
+                    .slice(0, 16)
+                : undefined;
+            appendJsonlLine(config.filePath, {
+                ts: new Date().toISOString(),
+                type: "cache_trace",
+                agentId: config.agentId,
+                sessionId: config.sessionId,
+                modelId: model.id,
+                provider: model.provider,
+                messageCount: context.messages.length,
+                systemPromptDigest,
+                toolCount: context.tools?.length ?? 0,
+            }, logger, config.maxSize, config.maxFiles);
+            return next(model, context, options);
+        };
+    };
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Compose utility for stream wrapper chains.
+ *
+ * @module
+ */
+import type { StreamFn } from "@mariozechner/pi-agent-core";
+import type { ComisLogger } from "@comis/infra";
+import type { StreamFnWrapper } from "./types.js";
+/**
+ * Compose an ordered list of wrappers around a base StreamFn.
+ *
+ * Wrappers are applied in order: first wrapper is outermost (executes first),
+ * last wrapper is innermost (closest to base). Implemented as a right-fold.
+ *
+ * @param wrappers - Ordered list of wrappers to apply
+ * @param base - The original SDK StreamFn to wrap
+ * @param logger - Logger for debug output
+ * @returns Composed StreamFn with all wrappers applied
+ */
+export declare function composeStreamWrappers(wrappers: StreamFnWrapper[], base: StreamFn, logger: ComisLogger): StreamFn;

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

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Compose utility for stream wrapper chains.
+ *
+ * @module
+ */
+/**
+ * Compose an ordered list of wrappers around a base StreamFn.
+ *
+ * Wrappers are applied in order: first wrapper is outermost (executes first),
+ * last wrapper is innermost (closest to base). Implemented as a right-fold.
+ *
+ * @param wrappers - Ordered list of wrappers to apply
+ * @param base - The original SDK StreamFn to wrap
+ * @param logger - Logger for debug output
+ * @returns Composed StreamFn with all wrappers applied
+ */
+export function composeStreamWrappers(wrappers, base, logger) {
+    if (wrappers.length === 0) {
+        return base;
+    }
+    const composed = wrappers.reduceRight((fn, wrapper) => {
+        return wrapper(fn);
+    }, base);
+    logger.debug({ wrapperCount: wrappers.length, wrapperNames: wrappers.map(w => w.name || "anonymous") }, "Stream wrappers composed");
+    return composed;
+}

package/node_modules/@comis/agent/dist/executor/stream-wrappers/config-resolver.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Config resolver stream wrapper.
+ *
+ * Injects provider-specific parameters (maxTokens, temperature, cacheRetention)
+ * into stream options from Comis YAML per-agent config.
+ *
+ * @module
+ */
+import type { CacheRetention } from "@mariozechner/pi-ai";
+import type { ComisLogger } from "@comis/infra";
+import type { StreamFnWrapper } from "./types.js";
+/**
+ * Configuration for the config resolver wrapper.
+ * Values come from Comis YAML per-agent config (maxTokens, temperature).
+ */
+export interface ConfigResolverConfig {
+    /** Comis YAML maxTokens override. Undefined = do not inject. */
+    maxTokens?: number;
+    /** Comis YAML temperature override. Undefined = do not inject. */
+    temperature?: number;
+    /** Cache retention for Anthropic provider. Default: "long".
+     *  Accepts a getter function for per-execution dynamic resolution. */
+    cacheRetention?: CacheRetention | (() => CacheRetention | undefined);
+}
+/** SYS-BOUNDARY: Deterministic marker between static and dynamic system prompt blocks.
+ *  Enables cache break diagnostics to identify whether changes are in the
+ *  stable or dynamic portion. Appended to staticPrefix block. */
+export declare const SYSTEM_PROMPT_DYNAMIC_BOUNDARY = "\n\n---SYSTEM-PROMPT-DYNAMIC-BOUNDARY---\n\n";
+/**
+ * Resolve "auto" breakpoint strategy to concrete value
+ * based on active provider.
+ *
+ * Direct Anthropic -> "single" (minimizes KV page waste)
+ * Bedrock/Vertex -> "multi-zone" (proxy-based, broader cache coverage)
+ * Explicit "single" or "multi-zone" -> pass through unchanged
+ */
+export declare function resolveBreakpointStrategy(strategy: "auto" | "multi-zone" | "single" | undefined, _provider: string): "multi-zone" | "single";
+/**
+ * Create a wrapper that injects provider-specific parameters into stream options.
+ *
+ * For ALL providers: injects maxTokens and temperature from Comis config
+ * when they are defined.
+ *
+ * For Anthropic-family providers: injects cacheRetention when the resolved
+ * value is truthy (the config schema provides the default).
+ *
+ * Comis config values are operator overrides and WILL replace any existing
+ * options values -- this is intentional. The operator's YAML config is the
+ * authoritative source for these parameters.
+ *
+ * @param config - Config resolver configuration from Comis YAML
+ * @param logger - Logger for debug output
+ * @returns A named StreamFnWrapper ("configResolver")
+ */
+export declare function createConfigResolver(config: ConfigResolverConfig, logger: ComisLogger): StreamFnWrapper;

package/node_modules/@comis/agent/dist/executor/stream-wrappers/config-resolver.js

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Config resolver stream wrapper.
+ *
+ * Injects provider-specific parameters (maxTokens, temperature, cacheRetention)
+ * into stream options from Comis YAML per-agent config.
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Anthropic-family providers that support cache_control breakpoints. */
+const ANTHROPIC_FAMILY = new Set(["anthropic", "anthropic-vertex", "amazon-bedrock"]);
+/** SYS-BOUNDARY: Deterministic marker between static and dynamic system prompt blocks.
+ *  Enables cache break diagnostics to identify whether changes are in the
+ *  stable or dynamic portion. Appended to staticPrefix block. */
+export const SYSTEM_PROMPT_DYNAMIC_BOUNDARY = "\n\n---SYSTEM-PROMPT-DYNAMIC-BOUNDARY---\n\n";
+/**
+ * Resolve "auto" breakpoint strategy to concrete value
+ * based on active provider.
+ *
+ * Direct Anthropic -> "single" (minimizes KV page waste)
+ * Bedrock/Vertex -> "multi-zone" (proxy-based, broader cache coverage)
+ * Explicit "single" or "multi-zone" -> pass through unchanged
+ */
+export function resolveBreakpointStrategy(strategy, _provider) {
+    if (strategy === "single" || strategy === "multi-zone") {
+        return strategy;
+    }
+    // W11: All providers use multi-zone strategy. Previous "single" for
+    // direct anthropic caused breakpoint budget exhaustion.
+    return "multi-zone";
+}
+/**
+ * Create a wrapper that injects provider-specific parameters into stream options.
+ *
+ * For ALL providers: injects maxTokens and temperature from Comis config
+ * when they are defined.
+ *
+ * For Anthropic-family providers: injects cacheRetention when the resolved
+ * value is truthy (the config schema provides the default).
+ *
+ * Comis config values are operator overrides and WILL replace any existing
+ * options values -- this is intentional. The operator's YAML config is the
+ * authoritative source for these parameters.
+ *
+ * @param config - Config resolver configuration from Comis YAML
+ * @param logger - Logger for debug output
+ * @returns A named StreamFnWrapper ("configResolver")
+ */
+export function createConfigResolver(config, logger) {
+    return function configResolver(next) {
+        return (model, context, options) => {
+            const injected = {};
+            // Inject maxTokens and temperature for all providers when configured.
+            // Skip temperature for reasoning models (e.g. OpenAI o-series, gpt-5.4-mini)
+            // -- they don't support the parameter and the API returns 400.
+            if (config.maxTokens !== undefined) {
+                injected.maxTokens = config.maxTokens;
+            }
+            if (config.temperature !== undefined && !model.reasoning) {
+                injected.temperature = config.temperature;
+            }
+            // Inject cacheRetention for Anthropic-family providers when truthy
+            // Resolve dynamic getter for per-execution cache retention override
+            if (ANTHROPIC_FAMILY.has(model.provider)) {
+                const retention = typeof config.cacheRetention === "function"
+                    ? config.cacheRetention()
+                    : config.cacheRetention;
+                if (retention) {
+                    injected.cacheRetention = retention;
+                }
+            }
+            const injectedKeys = Object.keys(injected);
+            if (injectedKeys.length === 0) {
+                logger.debug({ wrapperName: "configResolver", provider: model.provider, skipped: true }, "Config resolution skipped");
+                return next(model, context, options);
+            }
+            logger.debug({ wrapperName: "configResolver", provider: model.provider, injected: injectedKeys }, "Config params injected");
+            const mergedOptions = { ...options, ...injected };
+            return next(model, context, mergedOptions);
+        };
+    };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Stream wrapper chain infrastructure for intercepting LLM calls.
+ *
+ * Barrel re-export of all stream wrappers, types, compose utility,
+ * and cache helpers. Preserves the complete public API surface from
+ * the original monolith stream-wrappers.ts.
+ *
+ * @module
+ */
+export type { StreamFnWrapper } from "./types.js";
+export { composeStreamWrappers } from "./compose.js";
+export { createToolResultSizeBouncer } from "./tool-result-size-bouncer.js";
+export type { TruncationSummary, ToolResultSizeBouncerResult } from "./tool-result-size-bouncer.js";
+export { createTurnResultBudgetWrapper } from "./turn-result-budget-wrapper.js";
+export type { TurnBudgetSummary, TurnResultBudgetWrapperResult } from "./turn-result-budget-wrapper.js";
+export { createValidationErrorFormatter } from "./validation-error-formatter.js";
+export { createConfigResolver, resolveBreakpointStrategy, SYSTEM_PROMPT_DYNAMIC_BOUNDARY } from "./config-resolver.js";
+export type { ConfigResolverConfig } from "./config-resolver.js";
+export { createCacheTraceWriter, parseSize, rotateIfNeeded } from "./cache-trace-writer.js";
+export type { CacheTraceConfig } from "./cache-trace-writer.js";
+export { createApiPayloadTraceWriter } from "./api-payload-trace-writer.js";
+export type { ApiPayloadTraceConfig } from "./api-payload-trace-writer.js";
+export { createRequestBodyInjector, addCacheControlToLastBlock, CACHEABLE_BLOCK_TYPES, getMinCacheableTokens, resolveCacheRetention, clearSessionBetaHeaderLatches, } from "./request-body-injector.js";
+export type { RequestBodyInjectorConfig } from "./request-body-injector.js";
+export { sessionRenderedToolCache, getOrCacheRenderedTool, clearSessionRenderedToolCache, clearSessionPerToolCache, } from "./tool-schema-cache.js";
+export type { RenderedToolCacheEntry, PerToolCacheEntry } from "./tool-schema-cache.js";

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

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Stream wrapper chain infrastructure for intercepting LLM calls.
+ *
+ * Barrel re-export of all stream wrappers, types, compose utility,
+ * and cache helpers. Preserves the complete public API surface from
+ * the original monolith stream-wrappers.ts.
+ *
+ * @module
+ */
+// Compose utility
+export { composeStreamWrappers } from "./compose.js";
+// Individual wrappers
+export { createToolResultSizeBouncer } from "./tool-result-size-bouncer.js";
+export { createTurnResultBudgetWrapper } from "./turn-result-budget-wrapper.js";
+export { createValidationErrorFormatter } from "./validation-error-formatter.js";
+export { createConfigResolver, resolveBreakpointStrategy, SYSTEM_PROMPT_DYNAMIC_BOUNDARY } from "./config-resolver.js";
+export { createCacheTraceWriter, parseSize, rotateIfNeeded } from "./cache-trace-writer.js";
+export { createApiPayloadTraceWriter } from "./api-payload-trace-writer.js";
+export { createRequestBodyInjector, addCacheControlToLastBlock, CACHEABLE_BLOCK_TYPES, getMinCacheableTokens, resolveCacheRetention, clearSessionBetaHeaderLatches, } from "./request-body-injector.js";
+// Tool schema cache extracted to leaf module
+export { sessionRenderedToolCache, getOrCacheRenderedTool, clearSessionRenderedToolCache, clearSessionPerToolCache, } from "./tool-schema-cache.js";