@aexol/spectral 0.9.181 → 0.9.183

package/dist/sdk/ai/cache-benchmark/benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"benchmark.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/benchmark.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAgB,aAAa,EAAE,MAAM,YAAY,CAAC;AAMhG,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,eAAe,GAAG,eAAe,CA0F9F;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,eAAe,GAAG,eAAe,EAAE,CASzG;AASD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAuBxE"}

package/dist/sdk/ai/cache-benchmark/benchmark.js

@@ -0,0 +1,123 @@
+import { PrefixCacheSimulator } from "./prefix-cache.js";
+import { createTurnEntry, resolvePerTurn } from "./synthetic.js";
+import { fillerText, serializePrompt } from "./tokens.js";
+import { DEFAULT_CACHE_PRICING } from "./types.js";
+function resolvePricing(config) {
+    return { ...DEFAULT_CACHE_PRICING, ...(config.pricing ?? {}) };
+}
+export function runBenchmark(strategy, config) {
+    const pricing = resolvePricing(config);
+    const minCacheTokens = config.minCacheTokens ?? 1024;
+    const reReadFraction = config.reReadFraction ?? 0;
+    const systemText = fillerText(Math.max(0, config.systemPromptTokens * 4), 0);
+    const toolsText = fillerText(Math.max(0, config.toolsTokens * 4), 1);
+    const simulator = new PrefixCacheSimulator({
+        sessionId: config.sessionId ?? "benchmark",
+        minCacheTokens,
+    });
+    let state = strategy.init();
+    let cutCount = 0;
+    let totalPromptTokens = 0;
+    let totalInputTokens = 0;
+    let totalOutputTokens = 0;
+    let totalCacheReadTokens = 0;
+    let totalCacheWriteTokens = 0;
+    let maxPromptTokens = 0;
+    let finalPromptTokens = 0;
+    let totalTurnPromptTokens = 0;
+    let totalDroppedTokens = 0;
+    let totalSummaryTokens = 0;
+    let totalReReadTokens = 0;
+    for (let turn = 0; turn < config.turns; turn++) {
+        const promptTokens = resolvePerTurn(config.turnPromptTokens, turn);
+        const outputTokens = resolvePerTurn(config.turnOutputTokens, turn);
+        const entry = createTurnEntry(turn + 1, promptTokens);
+        const step = strategy.step(state, turn, entry);
+        state = { entries: step.entries };
+        if (step.cut)
+            cutCount++;
+        if (step.lost) {
+            totalDroppedTokens += step.lost.droppedTokens;
+            totalSummaryTokens += step.lost.summaryTokens;
+            const hardLost = Math.max(0, step.lost.droppedTokens - step.lost.summaryTokens);
+            totalReReadTokens += hardLost * reReadFraction;
+        }
+        totalTurnPromptTokens += promptTokens;
+        const promptText = serializePrompt(systemText, toolsText, step.entries);
+        const result = simulator.account(promptText, outputTokens);
+        totalPromptTokens += result.promptTokens;
+        totalInputTokens += result.inputTokens;
+        totalOutputTokens += result.outputTokens;
+        totalCacheReadTokens += result.cacheReadTokens;
+        totalCacheWriteTokens += result.cacheWriteTokens;
+        maxPromptTokens = Math.max(maxPromptTokens, result.promptTokens);
+        finalPromptTokens = result.promptTokens;
+    }
+    const contextLossRate = totalDroppedTokens > 0
+        ? Math.min(1, Math.max(0, 1 - totalSummaryTokens / totalDroppedTokens))
+        : 0;
+    const avgTurnPromptTokens = totalTurnPromptTokens / config.turns;
+    const reReadTurns = avgTurnPromptTokens > 0 ? totalReReadTokens / avgTurnPromptTokens : 0;
+    const reReadCost = (totalReReadTokens * pricing.input) / 1_000_000;
+    const totalCost = ((totalInputTokens + totalReReadTokens) * pricing.input +
+        totalOutputTokens * pricing.output +
+        totalCacheReadTokens * pricing.cacheRead) /
+        1_000_000;
+    const cacheHitRate = totalPromptTokens > 0 ? totalCacheReadTokens / totalPromptTokens : 0;
+    return {
+        name: strategy.name,
+        turns: config.turns,
+        cutCount,
+        totalPromptTokens,
+        totalInputTokens,
+        totalOutputTokens,
+        totalCacheReadTokens,
+        totalCacheWriteTokens,
+        cacheHitRate,
+        avgPromptTokens: Math.round(totalPromptTokens / config.turns),
+        maxPromptTokens,
+        finalPromptTokens,
+        totalDroppedTokens,
+        totalSummaryTokens,
+        contextLossRate,
+        totalReReadTokens,
+        reReadTurns,
+        reReadCost,
+        totalCost,
+        costPerTurn: totalCost / config.turns,
+        costVsKeepAllPct: 0,
+    };
+}
+/** Run several strategies over one scenario and fill in the keep-all cost delta. */
+export function runBenchmarkSuite(strategies, config) {
+    const results = strategies.map((strategy) => runBenchmark(strategy, config));
+    const baseline = results.find((result) => result.name === "keep-all");
+    if (baseline) {
+        for (const result of results) {
+            result.costVsKeepAllPct = (result.totalCost / baseline.totalCost - 1) * 100;
+        }
+    }
+    return results;
+}
+function fmt(value, digits = 2) {
+    return value.toLocaleString("en-US", {
+        minimumFractionDigits: digits,
+        maximumFractionDigits: digits,
+    });
+}
+export function formatBenchmarkReport(results) {
+    const lines = [];
+    lines.push("## Cache benchmark (OpenAI-style prefix cache)");
+    lines.push("");
+    lines.push("cacheHitRate = cacheRead / prompt tokens.");
+    lines.push("ctx loss % = 1 - summaryTokens/droppedTokens (100% == hard truncation destroyed everything).");
+    lines.push("re-read tokens = hard-lost context re-injected as new uncached input; re-read turns = re-read tokens / avg turn prompt. cost $ includes the re-read penalty.");
+    lines.push("");
+    lines.push("| strategy | cuts | avg prompt | cache hit % | ctx loss % | dropped ctx | re-read tok | re-read turns | cost $ | vs keep-all % |");
+    lines.push("| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |");
+    for (const result of results) {
+        lines.push(`| ${result.name} | ${result.cutCount} | ${fmt(result.avgPromptTokens, 0)} | ${fmt(result.cacheHitRate * 100, 1)} | ${fmt(result.contextLossRate * 100, 1)} | ${fmt(result.totalDroppedTokens, 0)} | ${fmt(result.totalReReadTokens, 0)} | ${fmt(result.reReadTurns, 1)} | ${fmt(result.totalCost, 4)} | ${fmt(result.costVsKeepAllPct, 1)} |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/sdk/ai/cache-benchmark/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./benchmark.js";
+export * from "./prefix-cache.js";
+export * from "./strategies.js";
+export * from "./synthetic.js";
+export * from "./tokens.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sdk/ai/cache-benchmark/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/sdk/ai/cache-benchmark/index.js

@@ -0,0 +1,6 @@
+export * from "./benchmark.js";
+export * from "./prefix-cache.js";
+export * from "./strategies.js";
+export * from "./synthetic.js";
+export * from "./tokens.js";
+export * from "./types.js";

package/dist/sdk/ai/cache-benchmark/prefix-cache.d.ts

@@ -0,0 +1,18 @@
+import type { PrefixCacheConfig, PrefixCacheTurnResult } from "./types.js";
+/** Length of the longest common character prefix between two strings. */
+export declare function commonPrefixLength(a: string, b: string): number;
+/**
+ * Deterministic simulator of OpenAI-style automatic prompt caching.
+ *
+ * Caching is scoped to `sessionId` and matches the longest common prefix with
+ * the previous request in that session. A prefix must reach `minCacheTokens`
+ * to be served from cache at all (OpenAI's real threshold is ~1024 tokens).
+ */
+export declare class PrefixCacheSimulator {
+    private readonly config;
+    private lastPrompt;
+    constructor(config: PrefixCacheConfig);
+    /** Account one provider request. `outputTokens` does not affect cache, only reporting. */
+    account(promptText: string, outputTokens: number): PrefixCacheTurnResult;
+}
+//# sourceMappingURL=prefix-cache.d.ts.map

package/dist/sdk/ai/cache-benchmark/prefix-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefix-cache.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/prefix-cache.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE3E,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAO/D;AAED;;;;;;GAMG;AACH,qBAAa,oBAAoB;IAGpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,UAAU,CAAqB;gBAEV,MAAM,EAAE,iBAAiB;IAEtD,0FAA0F;IAC1F,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,qBAAqB;CAwCxE"}

package/dist/sdk/ai/cache-benchmark/prefix-cache.js

@@ -0,0 +1,60 @@
+import { estimateTextTokens } from "./tokens.js";
+/** Length of the longest common character prefix between two strings. */
+export function commonPrefixLength(a, b) {
+    const length = Math.min(a.length, b.length);
+    let index = 0;
+    while (index < length && a[index] === b[index]) {
+        index++;
+    }
+    return index;
+}
+/**
+ * Deterministic simulator of OpenAI-style automatic prompt caching.
+ *
+ * Caching is scoped to `sessionId` and matches the longest common prefix with
+ * the previous request in that session. A prefix must reach `minCacheTokens`
+ * to be served from cache at all (OpenAI's real threshold is ~1024 tokens).
+ */
+export class PrefixCacheSimulator {
+    config;
+    lastPrompt;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Account one provider request. `outputTokens` does not affect cache, only reporting. */
+    account(promptText, outputTokens) {
+        const promptTokens = estimateTextTokens(promptText);
+        if (this.config.cacheRetention === "none" || !this.config.sessionId) {
+            return {
+                promptTokens,
+                cacheReadTokens: 0,
+                inputTokens: promptTokens,
+                cacheWriteTokens: promptTokens,
+                outputTokens,
+                commonPrefixTokens: 0,
+                cacheHit: false,
+            };
+        }
+        let commonPrefixTokens = 0;
+        let cacheReadTokens = 0;
+        let inputTokens = promptTokens;
+        if (this.lastPrompt !== undefined) {
+            const prefixChars = commonPrefixLength(this.lastPrompt, promptText);
+            commonPrefixTokens = estimateTextTokens(this.lastPrompt.slice(0, prefixChars));
+            if (commonPrefixTokens >= this.config.minCacheTokens) {
+                cacheReadTokens = commonPrefixTokens;
+                inputTokens = Math.max(0, promptTokens - cacheReadTokens);
+            }
+        }
+        this.lastPrompt = promptText;
+        return {
+            promptTokens,
+            cacheReadTokens,
+            inputTokens,
+            cacheWriteTokens: inputTokens,
+            outputTokens,
+            commonPrefixTokens,
+            cacheHit: cacheReadTokens > 0,
+        };
+    }
+}

package/dist/sdk/ai/cache-benchmark/strategies.d.ts

@@ -0,0 +1,18 @@
+import type { CacheStrategy, PromptEntry } from "./types.js";
+/** Create a deterministic compaction summary that is byte-stable after creation. */
+export declare function createSummaryEntry(cutTurn: number, summaryTokens: number): PromptEntry;
+/** Baseline: never compact. Prompt grows monotonically (best cache, until overflow). */
+export declare function keepAll(): CacheStrategy;
+/** Continuous sliding window: always keep only the last `windowTurns` entries. */
+export declare function truncateSliding(windowTurns: number): CacheStrategy;
+/** Batched truncation: cut to the last `keepLastTurns` entries once per `cutEveryTurns`. */
+export declare function truncateBatched(cutEveryTurns: number, keepLastTurns: number): CacheStrategy;
+/** Batched summarization: replace the dropped span with a fixed-size summary. */
+export declare function summarizeBatched(cutEveryTurns: number, keepRecentTurns: number, summaryTokens: number): CacheStrategy;
+/**
+ * Mirror the fork's autoOlderHistory policy: when estimated context tokens exceed
+ * `contextWindow * ratio`, replace the older span with a summary and keep a raw
+ * recent tail of ~`keepRecentTokens` tokens.
+ */
+export declare function summarizeOnTokenRatio(contextWindow: number, ratio: number, keepRecentTokens: number, summaryTokens: number): CacheStrategy;
+//# sourceMappingURL=strategies.d.ts.map

package/dist/sdk/ai/cache-benchmark/strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/strategies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAiB,MAAM,YAAY,CAAC;AAU5E,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,WAAW,CAUtF;AAED,wFAAwF;AACxF,wBAAgB,OAAO,IAAI,aAAa,CAMvC;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CAgBlE;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,aAAa,CAoB3F;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC/B,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,MAAM,GACnB,aAAa,CAsBf;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACpC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,gBAAgB,EAAE,MAAM,EACxB,aAAa,EAAE,MAAM,GACnB,aAAa,CAmCf"}

package/dist/sdk/ai/cache-benchmark/strategies.js

@@ -0,0 +1,131 @@
+import { fillerText } from "./tokens.js";
+function append(state, entry) {
+    return [...state.entries, entry];
+}
+function droppedTokens(entries) {
+    return entries.reduce((sum, entry) => sum + entry.tokens, 0);
+}
+/** Create a deterministic compaction summary that is byte-stable after creation. */
+export function createSummaryEntry(cutTurn, summaryTokens) {
+    const header = `summary(cut=${cutTurn}):`;
+    const bodyLength = Math.max(0, summaryTokens * 4 - header.length);
+    const text = header + fillerText(bodyLength, cutTurn);
+    return {
+        id: -cutTurn,
+        kind: "summary",
+        text,
+        tokens: Math.ceil(text.length / 4),
+    };
+}
+/** Baseline: never compact. Prompt grows monotonically (best cache, until overflow). */
+export function keepAll() {
+    return {
+        name: "keep-all",
+        init: () => ({ entries: [] }),
+        step: (state, _turn, entry) => ({ entries: append(state, entry), cut: false }),
+    };
+}
+/** Continuous sliding window: always keep only the last `windowTurns` entries. */
+export function truncateSliding(windowTurns) {
+    return {
+        name: `truncate-sliding(window=${windowTurns})`,
+        init: () => ({ entries: [] }),
+        step: (state, _turn, entry) => {
+            const appended = append(state, entry);
+            const entries = appended.slice(-windowTurns);
+            const dropped = appended.slice(0, Math.max(0, appended.length - entries.length));
+            const cut = dropped.length > 0;
+            return {
+                entries,
+                cut,
+                lost: cut ? { droppedTokens: droppedTokens(dropped), summaryTokens: 0 } : undefined,
+            };
+        },
+    };
+}
+/** Batched truncation: cut to the last `keepLastTurns` entries once per `cutEveryTurns`. */
+export function truncateBatched(cutEveryTurns, keepLastTurns) {
+    return {
+        name: `truncate-batched(every=${cutEveryTurns},keep=${keepLastTurns})`,
+        init: () => ({ entries: [] }),
+        step: (state, turn, entry) => {
+            const appended = append(state, entry);
+            // turn is 0-based; cut once a full batch has accumulated.
+            if ((turn + 1) % cutEveryTurns === 0) {
+                const entries = appended.slice(-keepLastTurns);
+                const dropped = appended.slice(0, Math.max(0, appended.length - entries.length));
+                const cut = dropped.length > 0;
+                return {
+                    entries,
+                    cut,
+                    lost: cut ? { droppedTokens: droppedTokens(dropped), summaryTokens: 0 } : undefined,
+                };
+            }
+            return { entries: appended, cut: false };
+        },
+    };
+}
+/** Batched summarization: replace the dropped span with a fixed-size summary. */
+export function summarizeBatched(cutEveryTurns, keepRecentTurns, summaryTokens) {
+    return {
+        name: `summarize-batched(every=${cutEveryTurns},keep=${keepRecentTurns},summary=${summaryTokens})`,
+        init: () => ({ entries: [] }),
+        step: (state, turn, entry) => {
+            const appended = append(state, entry);
+            if ((turn + 1) % cutEveryTurns !== 0) {
+                return { entries: appended, cut: false };
+            }
+            const recent = appended.slice(-keepRecentTurns);
+            if (recent.length === appended.length) {
+                return { entries: appended, cut: false };
+            }
+            const summary = createSummaryEntry(turn + 1, summaryTokens);
+            const dropped = appended.slice(0, appended.length - recent.length);
+            return {
+                entries: [summary, ...recent],
+                cut: true,
+                lost: { droppedTokens: droppedTokens(dropped), summaryTokens: summary.tokens },
+            };
+        },
+    };
+}
+/**
+ * Mirror the fork's autoOlderHistory policy: when estimated context tokens exceed
+ * `contextWindow * ratio`, replace the older span with a summary and keep a raw
+ * recent tail of ~`keepRecentTokens` tokens.
+ */
+export function summarizeOnTokenRatio(contextWindow, ratio, keepRecentTokens, summaryTokens) {
+    return {
+        name: `summarize-on-token-ratio(window=${contextWindow},ratio=${ratio},keep=${keepRecentTokens},summary=${summaryTokens})`,
+        init: () => ({ entries: [] }),
+        step: (state, turn, entry) => {
+            const appended = append(state, entry);
+            const total = appended.reduce((sum, e) => sum + e.tokens, 0);
+            if (total <= Math.floor(contextWindow * ratio)) {
+                return { entries: appended, cut: false };
+            }
+            // Walk from the newest entry backward, keeping the newest suffix whose
+            // total is <= keepRecentTokens (always keeping at least the newest entry).
+            let keptTokens = 0;
+            let keepFrom = appended.length;
+            for (let i = appended.length - 1; i >= 0; i--) {
+                const candidate = appended[i];
+                if (i < appended.length - 1 && keptTokens + candidate.tokens > keepRecentTokens)
+                    break;
+                keptTokens += candidate.tokens;
+                keepFrom = i;
+            }
+            const recent = appended.slice(keepFrom);
+            if (keepFrom === 0) {
+                return { entries: appended, cut: false };
+            }
+            const summary = createSummaryEntry(turn + 1, summaryTokens);
+            const dropped = appended.slice(0, keepFrom);
+            return {
+                entries: [summary, ...recent],
+                cut: true,
+                lost: { droppedTokens: droppedTokens(dropped), summaryTokens: summary.tokens },
+            };
+        },
+    };
+}

package/dist/sdk/ai/cache-benchmark/synthetic.d.ts

@@ -0,0 +1,6 @@
+import type { PromptEntry } from "./types.js";
+/** Build a deterministic, byte-stable prompt entry for a given turn. */
+export declare function createTurnEntry(turn: number, tokens: number): PromptEntry;
+/** Resolve a number-or-factory config value for a given turn. */
+export declare function resolvePerTurn(value: number | ((turn: number) => number), turn: number): number;
+//# sourceMappingURL=synthetic.d.ts.map

package/dist/sdk/ai/cache-benchmark/synthetic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthetic.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/synthetic.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAUzE;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/F"}

package/dist/sdk/ai/cache-benchmark/synthetic.js

@@ -0,0 +1,17 @@
+import { fillerText } from "./tokens.js";
+/** Build a deterministic, byte-stable prompt entry for a given turn. */
+export function createTurnEntry(turn, tokens) {
+    const header = `turn:${turn}:`;
+    const bodyLength = Math.max(0, tokens * 4 - header.length);
+    const text = header + fillerText(bodyLength, turn);
+    return {
+        id: turn,
+        kind: "turn",
+        text,
+        tokens: Math.ceil(text.length / 4),
+    };
+}
+/** Resolve a number-or-factory config value for a given turn. */
+export function resolvePerTurn(value, turn) {
+    return typeof value === "function" ? value(turn) : value;
+}

package/dist/sdk/ai/cache-benchmark/tokens.d.ts

@@ -0,0 +1,8 @@
+import type { PromptEntry } from "./types.js";
+/** Conservative chars/4 token heuristic, matching cli-node's estimateTokens. */
+export declare function estimateTextTokens(text: string): number;
+/** Deterministic filler of exactly `length` chars (a-z cycling, offset by `seed`). */
+export declare function fillerText(length: number, seed?: number): string;
+/** Join a stable head and ordered entries into one deterministic prompt string. */
+export declare function serializePrompt(systemText: string, toolsText: string, entries: PromptEntry[]): string;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/sdk/ai/cache-benchmark/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,SAAI,GAAG,MAAM,CAQ3D;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CAMrG"}

package/dist/sdk/ai/cache-benchmark/tokens.js

@@ -0,0 +1,22 @@
+/** Conservative chars/4 token heuristic, matching cli-node's estimateTokens. */
+export function estimateTextTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/** Deterministic filler of exactly `length` chars (a-z cycling, offset by `seed`). */
+export function fillerText(length, seed = 0) {
+    const base = "abcdefghijklmnopqrstuvwxyz";
+    const offset = ((seed % base.length) + base.length) % base.length;
+    let out = "";
+    for (let i = 0; i < length; i++) {
+        out += base[(offset + i) % base.length];
+    }
+    return out;
+}
+/** Join a stable head and ordered entries into one deterministic prompt string. */
+export function serializePrompt(systemText, toolsText, entries) {
+    const parts = [`[system]${systemText}`, `[tools]${toolsText}`];
+    for (const entry of entries) {
+        parts.push(`[${entry.kind}:${entry.id}]${entry.text}`);
+    }
+    return parts.join("\n");
+}

package/dist/sdk/ai/cache-benchmark/types.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Cache-benchmark model types.
+ *
+ * This is an offline, deterministic simulator of OpenAI-style automatic prompt
+ * caching. It answers one question cheaply and reproducibly: what happens to
+ * cacheRead / cacheWrite / input tokens (and therefore cost) when a compaction
+ * or truncation strategy rewrites or drops part of the conversation?
+ */
+/** Per-1M-token pricing used to turn token counters into an estimated cost. */
+export interface CachePricing {
+    /** $/1M uncached prompt (input) tokens. */
+    input: number;
+    /** $/1M completion (output) tokens. */
+    output: number;
+    /** $/1M cached prompt tokens. */
+    cacheRead: number;
+}
+export declare const DEFAULT_CACHE_PRICING: CachePricing;
+/** A single synthetic entry appended to (or injected into) the prompt. */
+export interface PromptEntry {
+    /** Stable id for this entry; summaries use negative ids. */
+    id: number;
+    /** Deterministic text serialized into the request. */
+    text: string;
+    /** Estimated token count for this entry. */
+    tokens: number;
+    /** Distinguishes real turns from injected compaction summaries. */
+    kind: "turn" | "summary";
+}
+/** Mutable per-strategy state carried across turns. */
+export interface StrategyState {
+    /** Ordered prompt entries currently in the active prefix (oldest first). */
+    entries: PromptEntry[];
+}
+/** Accounting for the context a cut destroyed (feeds quality/duration metrics). */
+export interface LostContext {
+    /** Raw prompt tokens removed from the live prefix by this cut. */
+    droppedTokens: number;
+    /** Tokens of the replacement summary (0 for hard truncation). */
+    summaryTokens: number;
+}
+/** Result of one strategy step. */
+export interface StrategyStep {
+    /** Ordered entries to send this turn (oldest first). */
+    entries: PromptEntry[];
+    /** True when this turn dropped or summarized part of the history (a cache breakpoint). */
+    cut: boolean;
+    /** Present when this turn dropped part of the history. */
+    lost?: LostContext;
+}
+export interface CacheStrategy {
+    name: string;
+    init(): StrategyState;
+    step(state: StrategyState, turn: number, entry: PromptEntry): StrategyStep;
+}
+/** Configuration for the prefix-cache simulator. */
+export interface PrefixCacheConfig {
+    sessionId?: string;
+    /** OpenAI only caches prefixes of at least this many tokens. */
+    minCacheTokens: number;
+    /** "none" disables cache accounting entirely (no reads/writes). */
+    cacheRetention?: "none" | "short" | "long";
+}
+/** One turn of prefix-cache accounting. */
+export interface PrefixCacheTurnResult {
+    /** Total prompt tokens sent (cached + uncached). */
+    promptTokens: number;
+    /** Prompt tokens served from cache. */
+    cacheReadTokens: number;
+    /** Prompt tokens not served from cache (== cacheWriteTokens in spectral usage semantics). */
+    inputTokens: number;
+    /** Prompt tokens written to cache this turn (the uncached prompt). */
+    cacheWriteTokens: number;
+    /** Completion tokens billed this turn. */
+    outputTokens: number;
+    /** Raw longest-common-prefix token count before the minimum-cache threshold. */
+    commonPrefixTokens: number;
+    /** Whether any prompt tokens were served from cache this turn. */
+    cacheHit: boolean;
+}
+/** Aggregate result for one strategy over a full scenario. */
+export interface BenchmarkResult {
+    name: string;
+    turns: number;
+    cutCount: number;
+    totalPromptTokens: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheReadTokens: number;
+    totalCacheWriteTokens: number;
+    /** cacheRead / prompt tokens, in [0, 1]. */
+    cacheHitRate: number;
+    avgPromptTokens: number;
+    maxPromptTokens: number;
+    finalPromptTokens: number;
+    /** Raw context tokens dropped by cuts (oldest-first history removed). */
+    totalDroppedTokens: number;
+    /** Replacement summary tokens injected by cuts. */
+    totalSummaryTokens: number;
+    /**
+     * Fraction of dropped context NOT carried forward by a summary, in [0, 1].
+     * 0 == nothing lost, 1 == hard truncation destroyed everything.
+     */
+    contextLossRate: number;
+    /** Extra uncached input tokens from forced re-reads of hard-lost context. */
+    totalReReadTokens: number;
+    /** First-order duration proxy: how many extra turns those re-reads add. */
+    reReadTurns: number;
+    /** Dollar cost of the re-read recovery tokens. */
+    reReadCost: number;
+    totalCost: number;
+    costPerTurn: number;
+    /** Percent cost delta vs the keep-all baseline (0 == same cost). */
+    costVsKeepAllPct: number;
+}
+/** Scenario configuration for a benchmark run. */
+export interface BenchmarkConfig {
+    turns: number;
+    systemPromptTokens: number;
+    toolsTokens: number;
+    /** Prompt tokens appended per turn. Number or per-turn factory. */
+    turnPromptTokens: number | ((turn: number) => number);
+    /** Completion tokens billed per turn. Number or per-turn factory. */
+    turnOutputTokens: number | ((turn: number) => number);
+    pricing?: Partial<CachePricing>;
+    /** OpenAI only caches prefixes of at least this many tokens. */
+    minCacheTokens?: number;
+    sessionId?: string;
+    /**
+     * When a cut hard-loses context (dropped without a summary), the agent must
+     * re-read it. This is the fraction of hard-lost tokens re-injected as new
+     * uncached input. 0 disables recovery modeling (default); 1 means the agent
+     * fully re-reads everything it destroyed.
+     */
+    reReadFraction?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sdk/ai/cache-benchmark/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/cache-benchmark/types.ts"],"names":[],"mappings":"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"}

package/dist/sdk/ai/cache-benchmark/types.js

@@ -0,0 +1,14 @@
+/**
+ * Cache-benchmark model types.
+ *
+ * This is an offline, deterministic simulator of OpenAI-style automatic prompt
+ * caching. It answers one question cheaply and reproducibly: what happens to
+ * cacheRead / cacheWrite / input tokens (and therefore cost) when a compaction
+ * or truncation strategy rewrites or drops part of the conversation?
+ */
+export const DEFAULT_CACHE_PRICING = {
+    // Illustrative GPT-5-class pricing: cached input is 10% of uncached input.
+    input: 1.25,
+    output: 10,
+    cacheRead: 0.125,
+};

package/dist/sdk/ai/env-api-keys.js

@@ -101,22 +101,5 @@ export function getEnvApiKey(provider) {
             return "<authenticated>";
         }
     }
-    if (provider === "amazon-bedrock") {
-        // Amazon Bedrock supports multiple credential sources:
-        // 1. AWS_PROFILE - named profile from ~/.aws/credentials
-        // 2. AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY - standard IAM keys
-        // 3. AWS_BEARER_TOKEN_BEDROCK - Bedrock bearer token
-        // 4. AWS_CONTAINER_CREDENTIALS_RELATIVE_URI - ECS task roles
-        // 5. AWS_CONTAINER_CREDENTIALS_FULL_URI - ECS task roles (full URI)
-        // 6. AWS_WEB_IDENTITY_TOKEN_FILE - IRSA (IAM Roles for Service Accounts)
-        if (process.env.AWS_PROFILE ||
-            (process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY) ||
-            process.env.AWS_BEARER_TOKEN_BEDROCK ||
-            process.env.AWS_CONTAINER_CREDENTIALS_RELATIVE_URI ||
-            process.env.AWS_CONTAINER_CREDENTIALS_FULL_URI ||
-            process.env.AWS_WEB_IDENTITY_TOKEN_FILE) {
-            return "<authenticated>";
-        }
-    }
     return undefined;
 }

package/dist/sdk/ai/models.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../../src/sdk/ai/models.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAEN,KAAK,8BAA8B,EACnC,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAqBvF,KAAK,kBAAkB,GAAG,OAAO,MAAM,GAAG;IACzC,cAAc,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,cAAc,CAAC,GAC9C,MAAM,CAAC,8BAA8B,EAAE,KAAK,CAAC,wBAAwB,CAAC,CAAC,CAAC;CACzE,CAAC;AAEF,KAAK,QAAQ,CACZ,SAAS,SAAS,aAAa,EAC/B,QAAQ,SAAS,MAAM,kBAAkB,CAAC,SAAS,CAAC,IACjD,kBAAkB,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,SAAS;IAAE,GAAG,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,CAAC,IAAI,SAAS,GAAG,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;AAEpH,wBAAgB,QAAQ,CAAC,SAAS,SAAS,aAAa,EAAE,QAAQ,SAAS,MAAM,kBAAkB,CAAC,SAAS,CAAC,EAC7G,QAAQ,EAAE,SAAS,EACnB,OAAO,EAAE,QAAQ,GACf,KAAK,CAAC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAGtC;AAED,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAE9C;AAED,wBAAgB,SAAS,CAAC,SAAS,SAAS,aAAa,EACxD,QAAQ,EAAE,SAAS,GACjB,KAAK,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAGnE;AAED,wBAAgB,aAAa,CAAC,IAAI,SAAS,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAO/F;AAID,wBAAgB,0BAA0B,CAAC,IAAI,SAAS,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,kBAAkB,EAAE,CASrG;AAED,wBAAgB,kBAAkB,CAAC,IAAI,SAAS,GAAG,EAClD,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAClB,KAAK,EAAE,kBAAkB,GACvB,kBAAkB,CAgBpB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,SAAS,GAAG,EAC9C,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,EACjC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,GAC/B,OAAO,CAGT"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../../src/sdk/ai/models.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAEN,KAAK,8BAA8B,EACnC,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAiCvF,KAAK,kBAAkB,GAAG,OAAO,MAAM,GAAG;IACzC,cAAc,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,cAAc,CAAC,GAC9C,MAAM,CAAC,8BAA8B,EAAE,KAAK,CAAC,wBAAwB,CAAC,CAAC,CAAC;CACzE,CAAC;AAEF,KAAK,QAAQ,CACZ,SAAS,SAAS,aAAa,EAC/B,QAAQ,SAAS,MAAM,kBAAkB,CAAC,SAAS,CAAC,IACjD,kBAAkB,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,SAAS;IAAE,GAAG,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,CAAC,IAAI,SAAS,GAAG,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;AAEpH,wBAAgB,QAAQ,CAAC,SAAS,SAAS,aAAa,EAAE,QAAQ,SAAS,MAAM,kBAAkB,CAAC,SAAS,CAAC,EAC7G,QAAQ,EAAE,SAAS,EACnB,OAAO,EAAE,QAAQ,GACf,KAAK,CAAC,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAGtC;AAED,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAE9C;AAED,wBAAgB,SAAS,CAAC,SAAS,SAAS,aAAa,EACxD,QAAQ,EAAE,SAAS,GACjB,KAAK,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAGnE;AAED,wBAAgB,aAAa,CAAC,IAAI,SAAS,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAO/F;AAID,wBAAgB,0BAA0B,CAAC,IAAI,SAAS,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,kBAAkB,EAAE,CASrG;AAED,wBAAgB,kBAAkB,CAAC,IAAI,SAAS,GAAG,EAClD,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAClB,KAAK,EAAE,kBAAkB,GACvB,kBAAkB,CAgBpB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,SAAS,GAAG,EAC9C,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,EACjC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,GAC/B,OAAO,CAGT"}