@selesai/code 0.13.26 → 0.13.27

package/dist/core/cache-warmer.js

@@ -0,0 +1,341 @@
+import { calculateCost, } from "@earendil-works/pi-ai";
+import { getProviderEnvValue } from "@earendil-works/pi-ai/utils/provider-env";
+/** Streaming warming never continues past this long after the real request that started it. */
+const MAX_WARMING_AGE_MS = 60 * 60_000;
+/** Idle warming uses a shorter horizon because continuation estimates become less reliable with age. */
+const MAX_IDLE_WARMING_AGE_MS = 30 * 60_000;
+/** A refresh is sent only when it is expected to save at least this many dollars. */
+const CACHE_WARMING_MINIMUM_EXPECTED_SAVINGS = 0.05;
+/**
+ * Chance that a real request arrives before the cache entry expires while the
+ * agent sits idle. Measured from our own usage; per-session estimates were not
+ * better than this constant.
+ */
+const IDLE_CONTINUATION_PROBABILITY = 0.15;
+/** Refresh at 90% of the TTL while preserving at least ten seconds of margin. */
+export function getCacheWarmingDelayMs(ttlMs) {
+    if (ttlMs <= 10_000)
+        return undefined;
+    return Math.max(1, Math.floor(Math.min(ttlMs * 0.9, ttlMs - 10_000)));
+}
+/**
+ * Lifetime of the prompt cache entry a request writes, from the model's
+ * `promptCache` tier for the retention the request used. Undefined when the
+ * model has no lifetime for that tier or caching is off.
+ */
+export function getPromptCacheTtlMs(model, options) {
+    const retention = options?.cacheRetention ??
+        (getProviderEnvValue("PI_CACHE_RETENTION", options?.env) === "long" ? "long" : "short");
+    if (retention === "none")
+        return undefined;
+    const seconds = model.promptCache?.[retention];
+    return seconds === undefined ? undefined : seconds * 1000;
+}
+/**
+ * Whether replaying the request with a one-token output cap leaves its cache
+ * entry untouched. Anthropic's budget-based thinking (Claude models without
+ * adaptive thinking) derives `budget_tokens` from `max_tokens`; the replay
+ * would get a different budget, which Anthropic keys the message cache on,
+ * and the model could still think for thousands of tokens.
+ */
+export function isReplayable(model, options) {
+    if (!options?.reasoning || model.api !== "anthropic-messages")
+        return true;
+    return model.compat?.forceAdaptiveThinking === true;
+}
+/** Prompt size of the most recent real request on the branch, as reported by the provider. */
+function lastPromptTokens(entries) {
+    for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index];
+        if (entry.type === "message" && entry.message.role === "assistant") {
+            const usage = entry.message.usage;
+            return usage.input + usage.cacheRead + usage.cacheWrite;
+        }
+    }
+    return 0;
+}
+function price(model, tokens) {
+    const usage = {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        ...tokens,
+    };
+    return calculateCost(model, usage).total;
+}
+/**
+ * Keeps one prompt cache entry alive by re-sending its request with a
+ * one-token output cap before the entry expires. `start` replaces any
+ * previous run; warm requests never extend the fixed safety windows.
+ */
+export class CacheWarmer {
+    run;
+    inactive;
+    models;
+    sessionManager;
+    getMode;
+    /** Lets extensions override `event.action`; failures fall back to pi's decision. */
+    decide;
+    /** Called with the persisted usage entry after each successful refresh. */
+    onWarmed;
+    constructor(models, sessionManager, getMode, decide = async (event) => event.action) {
+        this.models = models;
+        this.sessionManager = sessionManager;
+        this.getMode = getMode;
+        this.decide = decide;
+        this.inactive = { state: "inactive", reason: "waiting for first request" };
+    }
+    get status() {
+        if (this.getMode() === "off")
+            return { state: "inactive", reason: "cache warming disabled" };
+        const run = this.run;
+        if (!run)
+            return this.inactive;
+        if (!run.isCurrent())
+            return { state: "inactive", reason: "conversation context changed" };
+        const decision = this.evaluate(run);
+        const refreshing = run.timer === undefined;
+        if (!decision.economicsAvailable && !refreshing) {
+            return { state: "inactive", reason: "cache economics unavailable" };
+        }
+        return {
+            state: refreshing ? "refreshing" : "scheduled",
+            nextWarmAt: run.nextWarmAt,
+            decision,
+            extensionOverride: run.extensionOverride,
+        };
+    }
+    /** Keep the prompt cache entry written by `request` warm while `isCurrent` holds. */
+    start(request, isCurrent) {
+        this.clearRun();
+        const mode = this.getMode();
+        if (mode === "off") {
+            this.stop("cache warming disabled");
+            return;
+        }
+        if (!isReplayable(request.model, request.options)) {
+            this.stop("request cannot be replayed safely");
+            return;
+        }
+        const ttlMs = getPromptCacheTtlMs(request.model, request.options);
+        if (ttlMs === undefined) {
+            this.stop(request.options.cacheRetention === "none"
+                ? "request disabled prompt caching"
+                : "cache lifetime unavailable");
+            return;
+        }
+        const delayMs = getCacheWarmingDelayMs(ttlMs);
+        if (delayMs === undefined) {
+            this.stop("cache lifetime unavailable");
+            return;
+        }
+        this.run = {
+            ...request,
+            isCurrent,
+            delayMs,
+            startedAt: Date.now(),
+            controller: new AbortController(),
+            phase: "streaming",
+            nextWarmAt: 0,
+            extensionOverride: false,
+        };
+        this.schedule(this.run);
+    }
+    onAgentSettled() {
+        const run = this.run;
+        if (!run)
+            return;
+        if (this.getMode() === "streaming") {
+            this.stop("agent run settled");
+            return;
+        }
+        run.phase = "idle";
+        const deadline = run.startedAt + MAX_IDLE_WARMING_AGE_MS;
+        if (run.nextWarmAt > deadline || Date.now() >= deadline) {
+            this.stop("30-minute idle safety limit reached");
+        }
+    }
+    /** Reconcile an active run after the persisted warming mode changes. */
+    onModeChanged() {
+        const run = this.run;
+        if (!run)
+            return;
+        const reason = this.getModeStopReason(run);
+        if (reason)
+            this.stop(reason);
+    }
+    cancel() {
+        this.stop("inactive");
+    }
+    clearRun() {
+        const run = this.run;
+        if (!run)
+            return;
+        this.run = undefined;
+        if (run.timer)
+            clearTimeout(run.timer);
+        run.controller.abort();
+    }
+    stop(reason, stopped) {
+        this.clearRun();
+        this.inactive = { state: "inactive", reason, ...stopped };
+    }
+    schedule(run) {
+        run.extensionOverride = false;
+        run.nextWarmAt = Date.now() + run.delayMs;
+        const deadline = run.startedAt + (run.phase === "idle" ? MAX_IDLE_WARMING_AGE_MS : MAX_WARMING_AGE_MS);
+        if (run.nextWarmAt > deadline || Date.now() >= deadline) {
+            this.stop(run.phase === "idle" ? "30-minute idle safety limit reached" : "one-hour safety limit reached");
+            return;
+        }
+        run.timer = setTimeout(() => void this.refresh(run), Math.max(0, run.nextWarmAt - Date.now()));
+        run.timer.unref?.();
+    }
+    async refresh(run) {
+        run.timer = undefined;
+        if (!this.validateRun(run))
+            return;
+        const decision = this.evaluate(run);
+        const { warmCost, missCost, continuationProbability } = decision;
+        let action = decision.action;
+        try {
+            action = await this.decide({
+                type: "cache_warming_decision",
+                warmCost,
+                missCost,
+                continuationProbability,
+                action,
+            });
+        }
+        catch {
+            // Extension failures fall back to pi's own decision.
+        }
+        if (!this.validateRun(run))
+            return;
+        const extensionOverride = action !== decision.action;
+        if (action === "stop") {
+            const reason = extensionOverride
+                ? "stopped by extension"
+                : decision.economicsAvailable
+                    ? "expected savings below threshold"
+                    : "cache economics unavailable";
+            this.stop(reason, { decision, extensionOverride });
+            return;
+        }
+        run.extensionOverride = extensionOverride;
+        try {
+            const message = await this.models
+                .streamSimple(run.model, run.context, {
+                ...run.options,
+                maxTokens: 1,
+                maxRetries: 0,
+                signal: run.controller.signal,
+            })
+                .result();
+            if (!this.validateRun(run))
+                return;
+            if (message.stopReason !== "error" && message.stopReason !== "aborted") {
+                const entry = this.sessionManager.appendUsage("cache_warm", message.provider, message.responseModel ?? message.model, message.usage, extensionOverride ? "extension override" : undefined);
+                this.onWarmed?.(entry);
+            }
+        }
+        catch {
+            // Cache warming is best-effort and must not affect the active agent run.
+        }
+        if (this.run === run)
+            this.schedule(run);
+    }
+    validateRun(run) {
+        if (this.run !== run)
+            return false;
+        const reason = this.getModeStopReason(run) ?? (!run.isCurrent() ? "conversation context changed" : undefined);
+        if (!reason)
+            return true;
+        this.stop(reason);
+        return false;
+    }
+    getModeStopReason(run) {
+        const mode = this.getMode();
+        if (mode === "off")
+            return "cache warming disabled";
+        if (mode === "streaming" && run.phase === "idle")
+            return "agent run settled";
+        return undefined;
+    }
+    evaluate(run) {
+        const model = run.model;
+        const promptTokens = lastPromptTokens(this.sessionManager.getBranch());
+        const cacheHitCost = price(model, { cacheRead: promptTokens });
+        const cacheMissCost = price(model, model.cost.cacheWrite > 0 ? { cacheWrite: promptTokens } : { input: promptTokens });
+        const warmCost = price(model, { cacheRead: promptTokens, output: 1 });
+        const missCost = Math.max(0, cacheMissCost - cacheHitCost);
+        const continuationProbability = run.phase === "idle" ? IDLE_CONTINUATION_PROBABILITY : 1;
+        const economicsAvailable = promptTokens > 0 && (cacheHitCost > 0 || cacheMissCost > 0);
+        const expectedSavings = continuationProbability * missCost - warmCost;
+        return {
+            phase: run.phase,
+            warmCost,
+            missCost,
+            continuationProbability,
+            expectedSavings,
+            economicsAvailable,
+            action: expectedSavings >= CACHE_WARMING_MINIMUM_EXPECTED_SAVINGS ? "warm" : "stop",
+        };
+    }
+}
+function formatDollars(value) {
+    return value < 0 ? `-$${Math.abs(value).toFixed(3)}` : `$${value.toFixed(3)}`;
+}
+function formatCacheWarmingEconomics(decision) {
+    if (!decision.economicsAvailable)
+        return "cache economics unavailable";
+    const probability = Math.round(decision.continuationProbability * 100);
+    const probabilityText = decision.phase === "streaming"
+        ? `${probability}% continuation probability while agent is running`
+        : `${probability}% continuation probability`;
+    const comparison = decision.action === "warm" ? ">=" : "<";
+    return `${probabilityText}, expected savings ${formatDollars(decision.expectedSavings)} ${comparison} $${CACHE_WARMING_MINIMUM_EXPECTED_SAVINGS.toFixed(3)}`;
+}
+function formatCacheWarmingDecisionTime(nextWarmAt, now) {
+    if (nextWarmAt === undefined || nextWarmAt <= now)
+        return "Decision now";
+    let remainingSeconds = Math.ceil((nextWarmAt - now) / 1000);
+    const hours = Math.floor(remainingSeconds / 3600);
+    remainingSeconds %= 3600;
+    const minutes = Math.floor(remainingSeconds / 60);
+    const seconds = remainingSeconds % 60;
+    const parts = [];
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0)
+        parts.push(`${minutes}m`);
+    if (seconds > 0 || parts.length === 0)
+        parts.push(`${seconds}s`);
+    return `Decision in ${parts.join(" ")}`;
+}
+/** One-line status for `/session`. */
+export function formatCacheWarmingStatus(status, now = Date.now()) {
+    const decision = status.decision;
+    // A decision is attached once pi (or an extension) acted on it; "inactive"
+    // without one never got that far.
+    if (!decision || (status.state === "inactive" && !decision.economicsAvailable && !status.extensionOverride)) {
+        return `Inactive (${status.reason ?? "unknown reason"})`;
+    }
+    const details = status.extensionOverride
+        ? `extension override, ${formatCacheWarmingEconomics(decision)}`
+        : `${formatCacheWarmingEconomics(decision)} -> ${decision.action}`;
+    if (status.state === "inactive")
+        return `Stopped (${details})`;
+    if (status.state === "refreshing")
+        return `Warming cache (${details})`;
+    return `${formatCacheWarmingDecisionTime(status.nextWarmAt, now)} (${details})`;
+}
+/** One-line transcript text for persisted cache-warming usage. */
+export function formatCacheWarmingUsage(entry) {
+    const note = entry.note ? ` (${entry.note})` : "";
+    const cost = entry.usage.cost.total.toFixed(6).replace(/(\.\d{3}\d*?)0+$/, "$1");
+    return `Cache warmed${note}: $${cost}`;
+}

package/dist/core/compaction/branch-summarization.js

@@ -4,7 +4,7 @@
  * When navigating to a different point in the session tree, this generates
  * a summary of the branch being left so context isn't lost.
  */
-import { contentText } from "@earendil-works/pi-ai";
+import { contentText, normalizeContext } from "@earendil-works/pi-ai";
 import { convertToLlm, createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "../messages.js";
 import { completeSummarization, estimateTokens, getSummarizationFailure } from "./compaction.js";
 import { computeFileLists, createFileOps, extractFileOpsFromMessage, formatFileOperations, SUMMARIZATION_SYSTEM_PROMPT, serializeConversation, } from "./utils.js";
@@ -221,7 +221,7 @@ export async function generateBranchSummary(entries, options) {
     // request behavior (timeouts, retries, attribution headers) stays consistent
     // without running through agent state/events. Retried via completeSummarization
     // so transient stream drops reuse the configured retry policy.
-    const context = { systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages };
+    const context = normalizeContext({ systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages });
     const requestOptions = { apiKey, headers, env, signal, maxTokens };
     const response = await completeSummarization(model, context, requestOptions, streamFn, retry, callbacks);
     // Check if aborted or errored

package/dist/core/compaction/compaction.d.ts

@@ -6,7 +6,7 @@
  */
 import type { AgentMessage, StreamFn, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { type RetryCallbacks, type RetryPolicy } from "@earendil-works/pi-ai";
-import type { AssistantMessage, Context, Model, SimpleStreamOptions, Usage } from "@earendil-works/pi-ai/compat";
+import type { AssistantMessage, Model, SimpleStreamOptions, TranscriptContext, Usage } from "@earendil-works/pi-ai/compat";
 import { type SessionEntry } from "../session-manager.ts";
 import { type FileOperations } from "./utils.ts";
 /** Details stored in CompactionEntry.details for file tracking */
@@ -102,14 +102,14 @@ export declare function getSummarizationFailure(response: AssistantMessage, labe
  * the whole compaction on the first attempt. Deterministic errors and aborts return
  * immediately (see {@link retryAssistantCall}).
  */
-export declare function completeSummarization(model: Model<any>, context: Context, options: SimpleStreamOptions, streamFn?: StreamFn, retry?: RetryPolicy, callbacks?: RetryCallbacks): Promise<AssistantMessage>;
+export declare function completeSummarization(model: Model<any>, context: TranscriptContext, options: SimpleStreamOptions, streamFn?: StreamFn, retry?: RetryPolicy, callbacks?: RetryCallbacks): Promise<AssistantMessage>;
 /**
  * Generate a summary of the conversation using the LLM.
  * If previousSummary is provided, uses the update prompt to merge.
  */
-export declare function generateSummary(currentMessages: AgentMessage[], model: Model<any>, reserveTokens: number, apiKey: string | undefined, headers?: Record<string, string>, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, env?: Record<string, string>, retry?: RetryPolicy, callbacks?: RetryCallbacks): Promise<string>;
+export declare function generateSummary(currentMessages: AgentMessage[], model: Model<any>, reserveTokens: number, apiKey: string | undefined, headers?: Record<string, string>, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, env?: Record<string, string>, retry?: RetryPolicy, callbacks?: RetryCallbacks, sessionId?: string): Promise<string>;
 /** Generate or update a conversation summary and return its provider usage. */
-export declare function generateSummaryWithUsage(currentMessages: AgentMessage[], model: Model<any>, reserveTokens: number, apiKey: string | undefined, headers?: Record<string, string>, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, env?: Record<string, string>, retry?: RetryPolicy, callbacks?: RetryCallbacks): Promise<{
+export declare function generateSummaryWithUsage(currentMessages: AgentMessage[], model: Model<any>, reserveTokens: number, apiKey: string | undefined, headers?: Record<string, string>, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, env?: Record<string, string>, retry?: RetryPolicy, callbacks?: RetryCallbacks, sessionId?: string): Promise<{
     text: string;
     usage: Usage;
 }>;
@@ -137,5 +137,6 @@ export declare function prepareCompaction(pathEntries: SessionEntry[], settings:
  *
  * @param preparation - Pre-calculated preparation from prepareCompaction()
  * @param customInstructions - Optional custom focus for the summary
+ * @param sessionId - Optional routing session ID forwarded without enabling prompt caching
  */
-export declare function compact(preparation: CompactionPreparation, model: Model<any>, apiKey: string | undefined, headers?: Record<string, string>, customInstructions?: string, signal?: AbortSignal, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, env?: Record<string, string>, retry?: RetryPolicy, callbacks?: RetryCallbacks): Promise<CompactionResult>;
+export declare function compact(preparation: CompactionPreparation, model: Model<any>, apiKey: string | undefined, headers?: Record<string, string>, customInstructions?: string, signal?: AbortSignal, thinkingLevel?: ThinkingLevel, streamFn?: StreamFn, env?: Record<string, string>, retry?: RetryPolicy, callbacks?: RetryCallbacks, sessionId?: string): Promise<CompactionResult>;

package/dist/core/compaction/compaction.js

@@ -4,7 +4,7 @@
  * Pure functions for compaction logic. The session manager handles I/O,
  * and after compaction the session is reloaded.
  */
-import { contentText, retryAssistantCall, uuidv7 } from "@earendil-works/pi-ai";
+import { contentText, normalizeContext, retryAssistantCall, uuidv7, } from "@earendil-works/pi-ai";
 import { completeSimple } from "@earendil-works/pi-ai/compat";
 import { convertToLlm } from "../messages.js";
 import { buildSessionContext, sessionEntryToContextMessages, } from "../session-manager.js";
@@ -47,7 +47,9 @@ function getMessageFromEntryForCompaction(entry) {
     if (entry.type === "compaction") {
         return undefined;
     }
-    return sessionEntryToContextMessages(entry)[0];
+    // System messages are prompt state, not conversation; the compaction entry carries their replay.
+    const message = sessionEntryToContextMessages(entry)[0];
+    return message?.role === "system" ? undefined : message;
 }
 function combineUsage(first, second) {
     return {
@@ -321,13 +323,10 @@ export function findCutPoint(entries, startIndex, endIndex, keepRecentTokens) {
         accumulatedTokens += messageTokens;
         // Check if we've exceeded the budget
         if (accumulatedTokens >= keepRecentTokens) {
-            // Find the closest valid cut point at or after this entry
-            for (let c = 0; c < cutPoints.length; c++) {
-                if (cutPoints[c] >= i) {
-                    cutIndex = cutPoints[c];
-                    break;
-                }
-            }
+            // Prefer the closest valid cut point at or after this entry. If trailing
+            // tool results exceed the budget by themselves, keep their preceding
+            // assistant tool call instead of falling back to the first message.
+            cutIndex = cutPoints.find((candidate) => candidate >= i) ?? cutPoints[cutPoints.length - 1];
             break;
         }
     }
@@ -385,9 +384,7 @@ Use this EXACT format:
 - [Or "(none)" if not applicable]
 
 Keep each section concise. Preserve exact file paths, function names, and error messages.`;
-const UPDATE_SUMMARIZATION_PROMPT = `The messages above are NEW conversation messages to incorporate into the existing summary provided in <previous-summary> tags.
-
-Update the existing structured summary with new information. RULES:
+const UPDATE_SUMMARIZATION_INSTRUCTIONS = `Update the existing structured summary with new information. RULES:
 - PRESERVE all existing information from the previous summary
 - ADD new progress, decisions, and context from the new messages
 - UPDATE the Progress section: move items from "In Progress" to "Done" when completed
@@ -423,6 +420,9 @@ Use this EXACT format:
 - [Preserve important context, add new if needed]
 
 Keep each section concise. Preserve exact file paths, function names, and error messages.`;
+const UPDATE_SUMMARIZATION_PROMPT = `The messages above are NEW conversation messages to incorporate into the existing summary provided in <previous-summary> tags.
+
+${UPDATE_SUMMARIZATION_INSTRUCTIONS}`;
 /**
  * Returns an error message when a summarization response cannot safely be persisted.
  * A length stop contains partial text and must not become a session checkpoint.
@@ -436,8 +436,8 @@ export function getSummarizationFailure(response, label) {
     }
     return undefined;
 }
-function createSummarizationOptions(model, maxTokens, apiKey, headers, env, signal, thinkingLevel) {
-    const options = { maxTokens, signal, apiKey, headers, env };
+function createSummarizationOptions(model, maxTokens, apiKey, headers, env, signal, thinkingLevel, sessionId) {
+    const options = { maxTokens, signal, apiKey, headers, env, sessionId };
     if (model.reasoning && thinkingLevel && thinkingLevel !== "off") {
         options.reasoning = thinkingLevel;
     }
@@ -451,11 +451,12 @@ function createSummarizationOptions(model, maxTokens, apiKey, headers, env, sign
  * immediately (see {@link retryAssistantCall}).
  */
 export async function completeSummarization(model, context, options, streamFn, retry, callbacks) {
-    // Summaries are standalone requests, so isolate routing and avoid cache writes that cannot be reused.
+    // Avoid cache writes for one-off summaries. Reuse caller-supplied routing when available;
+    // callers without a session ID, including branch summaries, receive a fresh routing ID.
     const requestOptions = {
         ...options,
         cacheRetention: "none",
-        sessionId: uuidv7(),
+        sessionId: options.sessionId ?? uuidv7(),
     };
     const produce = async () => streamFn
         ? (await streamFn(model, context, requestOptions)).result()
@@ -466,11 +467,24 @@ export async function completeSummarization(model, context, options, streamFn, r
  * Generate a summary of the conversation using the LLM.
  * If previousSummary is provided, uses the update prompt to merge.
  */
-export async function generateSummary(currentMessages, model, reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks) {
-    return (await generateSummaryWithUsage(currentMessages, model, reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks)).text;
+export async function generateSummary(currentMessages, model, reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks, sessionId) {
+    return (await generateSummaryWithUsage(currentMessages, model, reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks, sessionId)).text;
+}
+/** Build the provider context for a standalone summary request. */
+function buildSummarizationContext(promptText) {
+    return normalizeContext({
+        systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
+        messages: [
+            {
+                role: "user",
+                content: [{ type: "text", text: promptText }],
+                timestamp: Date.now(),
+            },
+        ],
+    });
 }
 /** Generate or update a conversation summary and return its provider usage. */
-export async function generateSummaryWithUsage(currentMessages, model, reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks) {
+export async function generateSummaryWithUsage(currentMessages, model, reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks, sessionId) {
     const maxTokens = Math.min(Math.floor(0.8 * reserveTokens), model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY);
     // Use update prompt if we have a previous summary, otherwise initial prompt
     let basePrompt = previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT;
@@ -487,19 +501,15 @@ export async function generateSummaryWithUsage(currentMessages, model, reserveTo
         promptText += `<previous-summary>\n${previousSummary}\n</previous-summary>\n\n`;
     }
     promptText += basePrompt;
-    const summarizationMessages = [
-        {
-            role: "user",
-            content: [{ type: "text", text: promptText }],
-            timestamp: Date.now(),
-        },
-    ];
-    const completionOptions = createSummarizationOptions(model, maxTokens, apiKey, headers, env, signal, thinkingLevel);
-    const response = await completeSummarization(model, { systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages }, completionOptions, streamFn, retry, callbacks);
+    const completionOptions = createSummarizationOptions(model, maxTokens, apiKey, headers, env, signal, thinkingLevel, sessionId);
+    const response = await completeSummarization(model, buildSummarizationContext(promptText), completionOptions, streamFn, retry, callbacks);
     const failure = getSummarizationFailure(response, "Summarization");
     if (failure) {
         throw new Error(failure);
     }
+    if (response.content.some((block) => block.type === "toolCall")) {
+        throw new Error("Summarization attempted to call a tool");
+    }
     const textContent = contentText(response.content);
     return { text: textContent, usage: response.usage };
 }
@@ -593,28 +603,29 @@ Be concise. Focus on what's needed to understand the kept suffix.`;
  *
  * @param preparation - Pre-calculated preparation from prepareCompaction()
  * @param customInstructions - Optional custom focus for the summary
+ * @param sessionId - Optional routing session ID forwarded without enabling prompt caching
  */
-export async function compact(preparation, model, apiKey, headers, customInstructions, signal, thinkingLevel, streamFn, env, retry, callbacks) {
+export async function compact(preparation, model, apiKey, headers, customInstructions, signal, thinkingLevel, streamFn, env, retry, callbacks, sessionId) {
     const { firstKeptEntryId, messagesToSummarize, turnPrefixMessages, isSplitTurn, tokensBefore, previousSummary, fileOps, settings, } = preparation;
     // Generate summaries and merge into one
     let summary;
     let summaryUsage;
     if (isSplitTurn && turnPrefixMessages.length > 0) {
-        let historyText = "No prior history.";
+        let historyText = previousSummary ?? "No prior history.";
         let historyUsage;
         if (messagesToSummarize.length > 0) {
-            const historyResult = await generateSummaryWithUsage(messagesToSummarize, model, settings.reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks);
+            const historyResult = await generateSummaryWithUsage(messagesToSummarize, model, settings.reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks, sessionId);
             historyText = historyResult.text;
             historyUsage = historyResult.usage;
         }
-        const turnPrefixResult = await generateTurnPrefixSummary(turnPrefixMessages, model, settings.reserveTokens, apiKey, headers, env, signal, thinkingLevel, streamFn, retry, callbacks);
+        const turnPrefixResult = await generateTurnPrefixSummary(turnPrefixMessages, model, settings.reserveTokens, apiKey, headers, env, signal, thinkingLevel, streamFn, retry, callbacks, sessionId);
         // Merge into single summary
         summary = `${historyText}\n\n---\n\n**Turn Context (split turn):**\n\n${turnPrefixResult.text}`;
         summaryUsage = historyUsage ? combineUsage(historyUsage, turnPrefixResult.usage) : turnPrefixResult.usage;
     }
     else {
         // Just generate history summary
-        const result = await generateSummaryWithUsage(messagesToSummarize, model, settings.reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks);
+        const result = await generateSummaryWithUsage(messagesToSummarize, model, settings.reserveTokens, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks, sessionId);
         summary = result.text;
         summaryUsage = result.usage;
     }
@@ -635,23 +646,19 @@ export async function compact(preparation, model, apiKey, headers, customInstruc
 /**
  * Generate a summary for a turn prefix (when splitting a turn).
  */
-async function generateTurnPrefixSummary(messages, model, reserveTokens, apiKey, headers, env, signal, thinkingLevel, streamFn, retry, callbacks) {
+async function generateTurnPrefixSummary(messages, model, reserveTokens, apiKey, headers, env, signal, thinkingLevel, streamFn, retry, callbacks, sessionId) {
     const maxTokens = Math.min(Math.floor(0.5 * reserveTokens), model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY); // Smaller budget for turn prefix
     const llmMessages = convertToLlm(messages);
     const conversationText = serializeConversation(llmMessages);
     const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;
-    const summarizationMessages = [
-        {
-            role: "user",
-            content: [{ type: "text", text: promptText }],
-            timestamp: Date.now(),
-        },
-    ];
-    const response = await completeSummarization(model, { systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages }, createSummarizationOptions(model, maxTokens, apiKey, headers, env, signal, thinkingLevel), streamFn, retry, callbacks);
+    const response = await completeSummarization(model, buildSummarizationContext(promptText), createSummarizationOptions(model, maxTokens, apiKey, headers, env, signal, thinkingLevel, sessionId), streamFn, retry, callbacks);
     const failure = getSummarizationFailure(response, "Turn prefix summarization");
     if (failure) {
         throw new Error(failure);
     }
+    if (response.content.some((block) => block.type === "toolCall")) {
+        throw new Error("Turn prefix summarization attempted to call a tool");
+    }
     return {
         text: contentText(response.content),
         usage: response.usage,

package/dist/core/crash-log.d.ts

@@ -0,0 +1,21 @@
+export interface CrashRecord {
+    timestamp: string;
+    version: string;
+    kind: "uncaught_exception" | "fatal_error";
+    message: string;
+    stack: string | null;
+    sessionFile: string | null;
+    cwd: string;
+    notified?: boolean;
+}
+export declare function readCrashLog(path?: string): CrashRecord[];
+/** Best-effort persistence for callers that are already crashing. */
+export declare function recordCrash(crash: {
+    kind: CrashRecord["kind"];
+    error: unknown;
+    sessionFile?: string;
+    cwd: string;
+}, path?: string): CrashRecord | undefined;
+/** Return the newest recent crash, marking pending records as announced. */
+export declare function takeUnnotifiedCrash(path?: string, now?: number): CrashRecord | undefined;
+export declare function clearCrashLog(path?: string): void;