apex-code 0.5.0 → 0.5.2

package/dist/core/bug-report.js

@@ -0,0 +1,291 @@
+import * as os from "node:os";
+import { contentText, normalizeContext, uuidv7 } from "@earendil-works/pi-ai";
+import { VERSION } from "../config.js";
+import { getApexCodeUserAgent } from "../utils/apex-code-user-agent.js";
+import { writeZipArchive } from "../utils/zip.js";
+import { completeSummarization, estimateTokens, getSummarizationFailure } from "./compaction/compaction.js";
+import { serializeConversation } from "./compaction/utils.js";
+import { convertToLlm } from "./messages.js";
+export const BUG_REPORT_CUSTOM_ENTRY_TYPE = "apex-code.bug-report";
+const BUG_REPORT_SCHEMA_VERSION = 1;
+const REDACTED = "<redacted>";
+const SENSITIVE_KEY = /(?:^|[-_])(api[-_]?key|secret|token|password|passwd|credential|authorization|cookie)(?:$|[-_])/i;
+function isSensitiveKey(key) {
+    return SENSITIVE_KEY.test(key.replace(/([a-z0-9])([A-Z])/g, "$1_$2"));
+}
+/** Strip credentials and secret-looking query parameters from a URL. */
+export function redactUrl(value) {
+    const nested = /^([a-z][a-z0-9+.-]*:)([a-z][a-z0-9+.-]*:\/\/.*)$/i.exec(value);
+    if (nested)
+        return `${nested[1]}${redactUrl(nested[2])}`;
+    try {
+        const url = new URL(value);
+        let changed = false;
+        if (url.username || url.password) {
+            url.username = "";
+            url.password = "";
+            changed = true;
+        }
+        for (const key of url.searchParams.keys()) {
+            if (isSensitiveKey(key)) {
+                url.searchParams.set(key, REDACTED);
+                changed = true;
+            }
+        }
+        return changed ? url.toString() : value;
+    }
+    catch {
+        return value;
+    }
+}
+/** Copy a JSON value while removing values that may contain credentials. */
+export function redactJsonValue(value) {
+    if (value === undefined)
+        return undefined;
+    return JSON.parse(JSON.stringify(value, (key, child) => {
+        if (child !== null && child !== undefined && isSensitiveKey(key))
+            return REDACTED;
+        return typeof child === "string" ? redactUrl(child) : child;
+    }));
+}
+function redactSettings(settings) {
+    return redactJsonValue(settings);
+}
+function collectEnvironment() {
+    const env = (name) => process.env[name] || null;
+    return {
+        version: VERSION,
+        userAgent: getApexCodeUserAgent(VERSION),
+        runtime: process.versions.bun ? `bun/${process.versions.bun}` : `node/${process.version}`,
+        platform: process.platform,
+        arch: process.arch,
+        osRelease: os.release(),
+        osVersion: os.version(),
+        shell: process.env.SHELL?.split(/[\\/]/).pop() || null,
+        terminal: {
+            term: env("TERM"),
+            program: env("TERM_PROGRAM"),
+            programVersion: env("TERM_PROGRAM_VERSION"),
+            colorterm: env("COLORTERM"),
+            tmux: Boolean(process.env.TMUX),
+            ssh: Boolean(process.env.SSH_CONNECTION || process.env.SSH_CLIENT || process.env.SSH_TTY),
+            ci: Boolean(process.env.CI),
+        },
+        // Names help diagnose configuration; values never leave the machine.
+        apexCodeEnvironmentVariables: Object.keys(process.env)
+            .filter((name) => name.startsWith("APEX_CODE_"))
+            .sort(),
+    };
+}
+function describeModel(model) {
+    return {
+        provider: model.provider,
+        id: model.id,
+        name: model.name,
+        api: model.api,
+        baseUrl: redactUrl(model.baseUrl),
+        reasoning: model.reasoning,
+        input: model.input,
+        contextWindow: model.contextWindow,
+        maxTokens: model.maxTokens,
+        samplingParams: model.samplingParams ? redactJsonValue(model.samplingParams) : null,
+        compat: model.compat ? redactJsonValue(model.compat) : null,
+        thinkingLevelMap: model.thinkingLevelMap ?? null,
+        headerNames: Object.keys(model.headers ?? {}).sort(),
+    };
+}
+function describeProvider(modelRuntime, provider) {
+    const authTypes = [];
+    if (provider.auth.apiKey)
+        authTypes.push("api_key");
+    if (provider.auth.oauth)
+        authTypes.push("oauth");
+    return {
+        id: provider.id,
+        name: provider.name,
+        baseUrl: provider.baseUrl ? redactUrl(provider.baseUrl) : null,
+        headerNames: Object.keys(provider.headers ?? {}).sort(),
+        authTypes,
+        authStatus: modelRuntime.getProviderAuthStatus(provider.id),
+        usingOAuth: modelRuntime.isUsingOAuth(provider.id),
+        registeredByExtension: modelRuntime.getRegisteredProviderIds().includes(provider.id),
+    };
+}
+function describeExtension(extension) {
+    return {
+        path: extension.path,
+        source: redactUrl(extension.sourceInfo.source),
+        scope: extension.sourceInfo.scope,
+        origin: extension.sourceInfo.origin,
+        hidden: extension.hidden === true,
+    };
+}
+export function collectBugReportMetadata(options) {
+    const hint = options.hint?.trim() || null;
+    const provider = options.model ? options.modelRuntime.getProvider(options.model.provider) : undefined;
+    return {
+        schemaVersion: BUG_REPORT_SCHEMA_VERSION,
+        id: options.id ?? uuidv7(),
+        createdAt: new Date().toISOString(),
+        hint,
+        environment: collectEnvironment(),
+        session: {
+            id: options.sessionId,
+            included: options.includeSession,
+            summaryIncluded: options.includeSummary,
+            messageCount: options.messageCount,
+            ...(options.includeSession ? { cwd: options.cwd } : {}),
+        },
+        model: options.model ? describeModel(options.model) : null,
+        provider: provider ? describeProvider(options.modelRuntime, provider) : null,
+        thinkingLevel: options.thinkingLevel,
+        extensions: options.extensions.map(describeExtension),
+        extensionErrors: options.extensionErrors.map(({ path, error }) => ({ path, error })),
+        settings: {
+            global: redactSettings(options.globalSettings),
+            project: redactSettings(options.projectSettings),
+        },
+    };
+}
+/** Collect failed assistant turns without collecting conversation content. */
+export function collectBugReportDiagnostics(sessionManager, crashes = []) {
+    const entries = sessionManager.getEntries();
+    const assistant = [];
+    let assistantMessageCount = 0;
+    for (const entry of entries) {
+        if (entry.type !== "message" || entry.message.role !== "assistant")
+            continue;
+        assistantMessageCount++;
+        const message = entry.message;
+        const diagnostics = message.diagnostics ?? [];
+        if (diagnostics.length === 0 &&
+            message.stopReason !== "error" &&
+            message.stopReason !== "aborted" &&
+            !message.errorMessage) {
+            continue;
+        }
+        assistant.push({
+            entryId: entry.id,
+            timestamp: entry.timestamp,
+            provider: message.provider,
+            model: message.model,
+            api: message.api,
+            stopReason: message.stopReason,
+            ...(message.rawStopReason === undefined ? {} : { rawStopReason: message.rawStopReason }),
+            ...(message.errorMessage === undefined ? {} : { errorMessage: message.errorMessage }),
+            diagnostics,
+        });
+    }
+    return {
+        schemaVersion: BUG_REPORT_SCHEMA_VERSION,
+        sessionId: sessionManager.getSessionId(),
+        entryCount: entries.length,
+        assistantMessageCount,
+        assistant,
+        crashes: crashes.map(({ notified: _notified, ...record }) => record),
+    };
+}
+/** Files included in the exported archive. */
+export function bugReportFiles(bundle) {
+    const files = [
+        { name: "report.json", contentType: "application/json", data: `${JSON.stringify(bundle.metadata, null, 2)}\n` },
+        {
+            name: "diagnostics.json",
+            contentType: "application/json",
+            data: `${JSON.stringify(bundle.diagnostics, null, 2)}\n`,
+        },
+    ];
+    if (bundle.sessionJsonl !== undefined) {
+        files.push({ name: "session.jsonl", contentType: "application/x-ndjson", data: bundle.sessionJsonl });
+    }
+    if (bundle.summary !== undefined) {
+        files.push({
+            name: "summary.md",
+            contentType: "text/markdown",
+            data: bundle.summary.endsWith("\n") ? bundle.summary : `${bundle.summary}\n`,
+        });
+    }
+    return files;
+}
+export function writeBugReportArchive(bundle, filePath) {
+    return writeZipArchive(filePath, bugReportFiles(bundle));
+}
+export function bugReportArchiveFileName(id) {
+    return `apex-code-bug-report-${id}.zip`;
+}
+const BUG_SUMMARY_SYSTEM_PROMPT = `You are helping a user file a bug report about Apex Code, the coding agent they are talking to. You will be shown the conversation transcript. Write a report for the Apex Code developers describing what the user was doing and what went wrong.
+
+Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the report.`;
+const BUG_SUMMARY_INSTRUCTIONS = `Write the bug report in Markdown with these sections:
+
+## What the user was doing
+One short paragraph.
+
+## What went wrong
+Concrete description of the failure: wrong output, errors, hangs, tool failures, unexpected behavior. Quote error messages and tool output verbatim where they exist.
+
+## Steps to reproduce
+Numbered list, as specific as the transcript allows.
+
+## Relevant details
+Tool calls involved, files touched, model behavior, anything else that helps a developer reproduce or locate the problem.
+
+Do not include file contents, secrets, or credentials from the transcript; refer to files by path only. Keep the report factual and concise.`;
+function selectMessages(messages, tokenBudget) {
+    const selected = [];
+    let tokens = 0;
+    for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        const next = estimateTokens(message);
+        if (selected.length > 0 && tokens + next > tokenBudget)
+            break;
+        selected.push(message);
+        tokens += next;
+    }
+    return selected.reverse();
+}
+/** Ask the session model for a report when the user does not share the transcript. */
+export async function generateBugReportSummary(options) {
+    const { model } = options;
+    const contextWindow = model.contextWindow > 0 ? model.contextWindow : 128_000;
+    const messages = selectMessages(options.messages, Math.floor(contextWindow * 0.6));
+    const hint = options.hint?.trim();
+    const prompt = [
+        messages.length < options.messages.length
+            ? `Note: only the last ${messages.length} of ${options.messages.length} messages are shown.`
+            : undefined,
+        `<conversation>\n${serializeConversation(convertToLlm(messages))}\n</conversation>`,
+        hint ? `<user-report>\n${hint}\n</user-report>` : undefined,
+        BUG_SUMMARY_INSTRUCTIONS,
+    ]
+        .filter((part) => part !== undefined)
+        .join("\n\n");
+    const requestOptions = {
+        maxTokens: Math.min(4096, model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY),
+        signal: options.signal,
+        apiKey: options.apiKey,
+        headers: options.headers,
+        env: options.env,
+        sessionId: options.sessionId,
+        ...(model.reasoning && options.thinkingLevel && options.thinkingLevel !== "off"
+            ? { reasoning: options.thinkingLevel }
+            : {}),
+    };
+    const response = await completeSummarization(model, normalizeContext({
+        systemPrompt: BUG_SUMMARY_SYSTEM_PROMPT,
+        messages: [{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() }],
+    }), requestOptions, options.streamFn, options.retry);
+    if (response.stopReason === "aborted")
+        throw new Error("Bug report summary was cancelled");
+    const failure = getSummarizationFailure(response, "Bug report summary");
+    if (failure)
+        throw new Error(failure);
+    if (response.content.some((block) => block.type === "toolCall")) {
+        throw new Error("Bug report summary attempted to call a tool");
+    }
+    const text = contentText(response.content).trim();
+    if (!text)
+        throw new Error("Bug report summary was empty");
+    return text;
+}
+//# sourceMappingURL=bug-report.js.map

package/dist/core/bug-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bug-report.js","sourceRoot":"","sources":["../../src/core/bug-report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAoB,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAGhG,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAC5G,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAK7C,MAAM,CAAC,MAAM,4BAA4B,GAAG,sBAAsB,CAAC;AACnE,MAAM,yBAAyB,GAAG,CAAC,CAAC;AACpC,MAAM,QAAQ,GAAG,YAAY,CAAC;AAC9B,MAAM,aAAa,GAAG,iGAAiG,CAAC;AAExH,SAAS,cAAc,CAAC,GAAW,EAAW;IAC7C,OAAO,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,CAAC;AAAA,CACtE;AAED,wEAAwE;AACxE,MAAM,UAAU,SAAS,CAAC,KAAa,EAAU;IAChD,MAAM,MAAM,GAAG,mDAAmD,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/E,IAAI,MAAM;QAAE,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACzD,IAAI,CAAC;QACJ,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;YAClC,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;YAClB,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;YAClB,OAAO,GAAG,IAAI,CAAC;QAChB,CAAC;QACD,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC;YAC3C,IAAI,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzB,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;gBACpC,OAAO,GAAG,IAAI,CAAC;YAChB,CAAC;QACF,CAAC;QACD,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AAAA,CACD;AAED,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAAC,KAAc,EAAW;IACxD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,IAAI,CAAC,KAAK,CAChB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,KAAc,EAAE,EAAE,CAAC;QAC9C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,IAAI,cAAc,CAAC,GAAG,CAAC;YAAE,OAAO,QAAQ,CAAC;QAClF,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAAA,CAC5D,CAAC,CACF,CAAC;AAAA,CACF;AAED,SAAS,cAAc,CAAC,QAAkB,EAAY;IACrD,OAAO,eAAe,CAAC,QAAQ,CAAa,CAAC;AAAA,CAC7C;AAED,SAAS,kBAAkB,GAAG;IAC7B,MAAM,GAAG,GAAG,CAAC,IAAY,EAAiB,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IACvE,OAAO;QACN,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,oBAAoB,CAAC,OAAO,CAAC;QACxC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,QAAQ,OAAO,CAAC,OAAO,EAAE;QACzF,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,SAAS,EAAE,EAAE,CAAC,OAAO,EAAE;QACvB,SAAS,EAAE,EAAE,CAAC,OAAO,EAAE;QACvB,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,IAAI,IAAI;QACtD,QAAQ,EAAE;YACT,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC;YACjB,OAAO,EAAE,GAAG,CAAC,cAAc,CAAC;YAC5B,cAAc,EAAE,GAAG,CAAC,sBAAsB,CAAC;YAC3C,SAAS,EAAE,GAAG,CAAC,WAAW,CAAC;YAC3B,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAC/B,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;YACzF,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;SAC3B;QACD,qEAAqE;QACrE,4BAA4B,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;aACpD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;aAC/C,IAAI,EAAE;KACR,CAAC;AAAA,CACF;AAED,SAAS,aAAa,CAAC,KAAiB,EAAE;IACzC,OAAO;QACN,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,OAAO,EAAE,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC;QACjC,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,cAAc,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI;QACnF,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI;QAC3D,gBAAgB,EAAE,KAAK,CAAC,gBAAgB,IAAI,IAAI;QAChD,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;KACpD,CAAC;AAAA,CACF;AAED,SAAS,gBAAgB,CAAC,YAA0B,EAAE,QAAkB,EAAE;IACzE,MAAM,SAAS,GAA+B,EAAE,CAAC;IACjD,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM;QAAE,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACpD,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK;QAAE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO;QACN,EAAE,EAAE,QAAQ,CAAC,EAAE;QACf,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI;QAC9D,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QACvD,SAAS;QACT,UAAU,EAAE,YAAY,CAAC,qBAAqB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,UAAU,EAAE,YAAY,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClD,qBAAqB,EAAE,YAAY,CAAC,wBAAwB,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;KACpF,CAAC;AAAA,CACF;AAED,SAAS,iBAAiB,CAAC,SAAoB,EAAE;IAChD,OAAO;QACN,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,MAAM,EAAE,SAAS,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC;QAC9C,KAAK,EAAE,SAAS,CAAC,UAAU,CAAC,KAAK;QACjC,MAAM,EAAE,SAAS,CAAC,UAAU,CAAC,MAAM;QACnC,MAAM,EAAE,SAAS,CAAC,MAAM,KAAK,IAAI;KACjC,CAAC;AAAA,CACF;AAmBD,MAAM,UAAU,wBAAwB,CAAC,OAAwC,EAAE;IAClF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC;IAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtG,OAAO;QACN,aAAa,EAAE,yBAAyB;QACxC,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,MAAM,EAAE;QAC1B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,IAAI;QACJ,WAAW,EAAE,kBAAkB,EAAE;QACjC,OAAO,EAAE;YACR,EAAE,EAAE,OAAO,CAAC,SAAS;YACrB,QAAQ,EAAE,OAAO,CAAC,cAAc;YAChC,eAAe,EAAE,OAAO,CAAC,cAAc;YACvC,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACvD;QACD,KAAK,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;QAC1D,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI;QAC5E,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,iBAAiB,CAAC;QACrD,eAAe,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACpF,QAAQ,EAAE;YACT,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,cAAc,CAAC;YAC9C,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,eAAe,CAAC;SAChD;KACD,CAAC;AAAA,CACF;AAED,8EAA8E;AAC9E,MAAM,UAAU,2BAA2B,CAC1C,cAAsC,EACtC,OAAO,GAA2B,EAAE,EACnC;IACD,MAAM,OAAO,GAAG,cAAc,CAAC,UAAU,EAAE,CAAC;IAC5C,MAAM,SAAS,GAAG,EAAE,CAAC;IACrB,IAAI,qBAAqB,GAAG,CAAC,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,WAAW;YAAE,SAAS;QAC7E,qBAAqB,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;QAC9B,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;QAC9C,IACC,WAAW,CAAC,MAAM,KAAK,CAAC;YACxB,OAAO,CAAC,UAAU,KAAK,OAAO;YAC9B,OAAO,CAAC,UAAU,KAAK,SAAS;YAChC,CAAC,OAAO,CAAC,YAAY,EACpB,CAAC;YACF,SAAS;QACV,CAAC;QACD,SAAS,CAAC,IAAI,CAAC;YACd,OAAO,EAAE,KAAK,CAAC,EAAE;YACjB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC;YACxF,GAAG,CAAC,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;YACrF,WAAW;SACX,CAAC,CAAC;IACJ,CAAC;IACD,OAAO;QACN,aAAa,EAAE,yBAAyB;QACxC,SAAS,EAAE,cAAc,CAAC,YAAY,EAAE;QACxC,UAAU,EAAE,OAAO,CAAC,MAAM;QAC1B,qBAAqB;QACrB,SAAS;QACT,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC;KACpE,CAAC;AAAA,CACF;AA4BD,8CAA8C;AAC9C,MAAM,UAAU,cAAc,CAAC,MAAuB,EAAmB;IACxE,MAAM,KAAK,GAAoB;QAC9B,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,kBAAkB,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;QAC/G;YACC,IAAI,EAAE,kBAAkB;YACxB,WAAW,EAAE,kBAAkB;YAC/B,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI;SACxD;KACD,CAAC;IACF,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,WAAW,EAAE,sBAAsB,EAAE,IAAI,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC;IACvG,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,eAAe;YAC5B,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,IAAI;SAC5E,CAAC,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AAAA,CACb;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAuB,EAAE,QAAgB,EAAiB;IAC/F,OAAO,eAAe,CAAC,QAAQ,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;AAAA,CACzD;AAED,MAAM,UAAU,wBAAwB,CAAC,EAAU,EAAU;IAC5D,OAAO,wBAAwB,EAAE,MAAM,CAAC;AAAA,CACxC;AAED,MAAM,yBAAyB,GAAG;;+GAE6E,CAAC;AAEhH,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;;6IAc4G,CAAC;AAE9I,SAAS,cAAc,CAAC,QAAiC,EAAE,WAAmB,EAAkB;IAC/F,MAAM,QAAQ,GAAmB,EAAE,CAAC;IACpC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,IAAI,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3D,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,IAAI,GAAG,WAAW;YAAE,MAAM;QAC9D,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,MAAM,IAAI,IAAI,CAAC;IAChB,CAAC;IACD,OAAO,QAAQ,CAAC,OAAO,EAAE,CAAC;AAAA,CAC1B;AAgBD,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,OAAwC,EAAmB;IACzG,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAC1B,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC;IAC9E,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,GAAG,CAAC,CAAC,CAAC;IACnF,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;IAClC,MAAM,MAAM,GAAG;QACd,QAAQ,CAAC,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM;YACxC,CAAC,CAAC,uBAAuB,QAAQ,CAAC,MAAM,OAAO,OAAO,CAAC,QAAQ,CAAC,MAAM,sBAAsB;YAC5F,CAAC,CAAC,SAAS;QACZ,mBAAmB,qBAAqB,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,mBAAmB;QACnF,IAAI,CAAC,CAAC,CAAC,kBAAkB,IAAI,kBAAkB,CAAC,CAAC,CAAC,SAAS;QAC3D,wBAAwB;KACxB;SACC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC;SACpC,IAAI,CAAC,MAAM,CAAC,CAAC;IACf,MAAM,cAAc,GAAwB;QAC3C,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC;QAC3F,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,OAAO,CAAC,aAAa,IAAI,OAAO,CAAC,aAAa,KAAK,KAAK;YAC9E,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,aAAa,EAAE;YACtC,CAAC,CAAC,EAAE,CAAC;KACN,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,qBAAqB,CAC3C,KAAK,EACL,gBAAgB,CAAC;QAChB,YAAY,EAAE,yBAAyB;QACvC,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;KAC9F,CAAC,EACF,cAAc,EACd,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,KAAK,CACb,CAAC;IACF,IAAI,QAAQ,CAAC,UAAU,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAC3F,MAAM,OAAO,GAAG,uBAAuB,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC;IACxE,IAAI,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAC3D,OAAO,IAAI,CAAC;AAAA,CACZ","sourcesContent":["import * as os from \"node:os\";\nimport { contentText, normalizeContext, type RetryPolicy, uuidv7 } from \"@earendil-works/pi-ai\";\nimport type { Api, Model, Provider, SimpleStreamOptions } from \"@earendil-works/pi-ai/compat\";\nimport type { AgentMessage, StreamFn, ThinkingLevel } from \"apex-code-agent-core\";\nimport { VERSION } from \"../config.ts\";\nimport { getApexCodeUserAgent } from \"../utils/apex-code-user-agent.ts\";\nimport { writeZipArchive } from \"../utils/zip.ts\";\nimport { completeSummarization, estimateTokens, getSummarizationFailure } from \"./compaction/compaction.ts\";\nimport { serializeConversation } from \"./compaction/utils.ts\";\nimport type { CrashRecord } from \"./crash-log.ts\";\nimport type { Extension } from \"./extensions/types.ts\";\nimport { convertToLlm } from \"./messages.ts\";\nimport type { ModelRuntime } from \"./model-runtime.ts\";\nimport type { ReadonlySessionManager } from \"./session-manager.ts\";\nimport type { Settings } from \"./settings-manager.ts\";\n\nexport const BUG_REPORT_CUSTOM_ENTRY_TYPE = \"apex-code.bug-report\";\nconst BUG_REPORT_SCHEMA_VERSION = 1;\nconst REDACTED = \"<redacted>\";\nconst SENSITIVE_KEY = /(?:^|[-_])(api[-_]?key|secret|token|password|passwd|credential|authorization|cookie)(?:$|[-_])/i;\n\nfunction isSensitiveKey(key: string): boolean {\n\treturn SENSITIVE_KEY.test(key.replace(/([a-z0-9])([A-Z])/g, \"$1_$2\"));\n}\n\n/** Strip credentials and secret-looking query parameters from a URL. */\nexport function redactUrl(value: string): string {\n\tconst nested = /^([a-z][a-z0-9+.-]*:)([a-z][a-z0-9+.-]*:\\/\\/.*)$/i.exec(value);\n\tif (nested) return `${nested[1]}${redactUrl(nested[2])}`;\n\ttry {\n\t\tconst url = new URL(value);\n\t\tlet changed = false;\n\t\tif (url.username || url.password) {\n\t\t\turl.username = \"\";\n\t\t\turl.password = \"\";\n\t\t\tchanged = true;\n\t\t}\n\t\tfor (const key of url.searchParams.keys()) {\n\t\t\tif (isSensitiveKey(key)) {\n\t\t\t\turl.searchParams.set(key, REDACTED);\n\t\t\t\tchanged = true;\n\t\t\t}\n\t\t}\n\t\treturn changed ? url.toString() : value;\n\t} catch {\n\t\treturn value;\n\t}\n}\n\n/** Copy a JSON value while removing values that may contain credentials. */\nexport function redactJsonValue(value: unknown): unknown {\n\tif (value === undefined) return undefined;\n\treturn JSON.parse(\n\t\tJSON.stringify(value, (key, child: unknown) => {\n\t\t\tif (child !== null && child !== undefined && isSensitiveKey(key)) return REDACTED;\n\t\t\treturn typeof child === \"string\" ? redactUrl(child) : child;\n\t\t}),\n\t);\n}\n\nfunction redactSettings(settings: Settings): Settings {\n\treturn redactJsonValue(settings) as Settings;\n}\n\nfunction collectEnvironment() {\n\tconst env = (name: string): string | null => process.env[name] || null;\n\treturn {\n\t\tversion: VERSION,\n\t\tuserAgent: getApexCodeUserAgent(VERSION),\n\t\truntime: process.versions.bun ? `bun/${process.versions.bun}` : `node/${process.version}`,\n\t\tplatform: process.platform,\n\t\tarch: process.arch,\n\t\tosRelease: os.release(),\n\t\tosVersion: os.version(),\n\t\tshell: process.env.SHELL?.split(/[\\\\/]/).pop() || null,\n\t\tterminal: {\n\t\t\tterm: env(\"TERM\"),\n\t\t\tprogram: env(\"TERM_PROGRAM\"),\n\t\t\tprogramVersion: env(\"TERM_PROGRAM_VERSION\"),\n\t\t\tcolorterm: env(\"COLORTERM\"),\n\t\t\ttmux: Boolean(process.env.TMUX),\n\t\t\tssh: Boolean(process.env.SSH_CONNECTION || process.env.SSH_CLIENT || process.env.SSH_TTY),\n\t\t\tci: Boolean(process.env.CI),\n\t\t},\n\t\t// Names help diagnose configuration; values never leave the machine.\n\t\tapexCodeEnvironmentVariables: Object.keys(process.env)\n\t\t\t.filter((name) => name.startsWith(\"APEX_CODE_\"))\n\t\t\t.sort(),\n\t};\n}\n\nfunction describeModel(model: Model<Api>) {\n\treturn {\n\t\tprovider: model.provider,\n\t\tid: model.id,\n\t\tname: model.name,\n\t\tapi: model.api,\n\t\tbaseUrl: redactUrl(model.baseUrl),\n\t\treasoning: model.reasoning,\n\t\tinput: model.input,\n\t\tcontextWindow: model.contextWindow,\n\t\tmaxTokens: model.maxTokens,\n\t\tsamplingParams: model.samplingParams ? redactJsonValue(model.samplingParams) : null,\n\t\tcompat: model.compat ? redactJsonValue(model.compat) : null,\n\t\tthinkingLevelMap: model.thinkingLevelMap ?? null,\n\t\theaderNames: Object.keys(model.headers ?? {}).sort(),\n\t};\n}\n\nfunction describeProvider(modelRuntime: ModelRuntime, provider: Provider) {\n\tconst authTypes: Array<\"api_key\" | \"oauth\"> = [];\n\tif (provider.auth.apiKey) authTypes.push(\"api_key\");\n\tif (provider.auth.oauth) authTypes.push(\"oauth\");\n\treturn {\n\t\tid: provider.id,\n\t\tname: provider.name,\n\t\tbaseUrl: provider.baseUrl ? redactUrl(provider.baseUrl) : null,\n\t\theaderNames: Object.keys(provider.headers ?? {}).sort(),\n\t\tauthTypes,\n\t\tauthStatus: modelRuntime.getProviderAuthStatus(provider.id),\n\t\tusingOAuth: modelRuntime.isUsingOAuth(provider.id),\n\t\tregisteredByExtension: modelRuntime.getRegisteredProviderIds().includes(provider.id),\n\t};\n}\n\nfunction describeExtension(extension: Extension) {\n\treturn {\n\t\tpath: extension.path,\n\t\tsource: redactUrl(extension.sourceInfo.source),\n\t\tscope: extension.sourceInfo.scope,\n\t\torigin: extension.sourceInfo.origin,\n\t\thidden: extension.hidden === true,\n\t};\n}\n\ninterface CollectBugReportMetadataOptions {\n\tid?: string;\n\thint?: string;\n\tsessionId: string;\n\tcwd: string;\n\tincludeSession: boolean;\n\tincludeSummary: boolean;\n\tmessageCount: number;\n\tmodel?: Model<Api>;\n\tmodelRuntime: ModelRuntime;\n\tthinkingLevel: ThinkingLevel;\n\textensions: readonly Extension[];\n\textensionErrors: ReadonlyArray<{ path: string; error: string }>;\n\tglobalSettings: Settings;\n\tprojectSettings: Settings;\n}\n\nexport function collectBugReportMetadata(options: CollectBugReportMetadataOptions) {\n\tconst hint = options.hint?.trim() || null;\n\tconst provider = options.model ? options.modelRuntime.getProvider(options.model.provider) : undefined;\n\treturn {\n\t\tschemaVersion: BUG_REPORT_SCHEMA_VERSION,\n\t\tid: options.id ?? uuidv7(),\n\t\tcreatedAt: new Date().toISOString(),\n\t\thint,\n\t\tenvironment: collectEnvironment(),\n\t\tsession: {\n\t\t\tid: options.sessionId,\n\t\t\tincluded: options.includeSession,\n\t\t\tsummaryIncluded: options.includeSummary,\n\t\t\tmessageCount: options.messageCount,\n\t\t\t...(options.includeSession ? { cwd: options.cwd } : {}),\n\t\t},\n\t\tmodel: options.model ? describeModel(options.model) : null,\n\t\tprovider: provider ? describeProvider(options.modelRuntime, provider) : null,\n\t\tthinkingLevel: options.thinkingLevel,\n\t\textensions: options.extensions.map(describeExtension),\n\t\textensionErrors: options.extensionErrors.map(({ path, error }) => ({ path, error })),\n\t\tsettings: {\n\t\t\tglobal: redactSettings(options.globalSettings),\n\t\t\tproject: redactSettings(options.projectSettings),\n\t\t},\n\t};\n}\n\n/** Collect failed assistant turns without collecting conversation content. */\nexport function collectBugReportDiagnostics(\n\tsessionManager: ReadonlySessionManager,\n\tcrashes: readonly CrashRecord[] = [],\n) {\n\tconst entries = sessionManager.getEntries();\n\tconst assistant = [];\n\tlet assistantMessageCount = 0;\n\tfor (const entry of entries) {\n\t\tif (entry.type !== \"message\" || entry.message.role !== \"assistant\") continue;\n\t\tassistantMessageCount++;\n\t\tconst message = entry.message;\n\t\tconst diagnostics = message.diagnostics ?? [];\n\t\tif (\n\t\t\tdiagnostics.length === 0 &&\n\t\t\tmessage.stopReason !== \"error\" &&\n\t\t\tmessage.stopReason !== \"aborted\" &&\n\t\t\t!message.errorMessage\n\t\t) {\n\t\t\tcontinue;\n\t\t}\n\t\tassistant.push({\n\t\t\tentryId: entry.id,\n\t\t\ttimestamp: entry.timestamp,\n\t\t\tprovider: message.provider,\n\t\t\tmodel: message.model,\n\t\t\tapi: message.api,\n\t\t\tstopReason: message.stopReason,\n\t\t\t...(message.rawStopReason === undefined ? {} : { rawStopReason: message.rawStopReason }),\n\t\t\t...(message.errorMessage === undefined ? {} : { errorMessage: message.errorMessage }),\n\t\t\tdiagnostics,\n\t\t});\n\t}\n\treturn {\n\t\tschemaVersion: BUG_REPORT_SCHEMA_VERSION,\n\t\tsessionId: sessionManager.getSessionId(),\n\t\tentryCount: entries.length,\n\t\tassistantMessageCount,\n\t\tassistant,\n\t\tcrashes: crashes.map(({ notified: _notified, ...record }) => record),\n\t};\n}\n\nexport type BugReportMetadata = ReturnType<typeof collectBugReportMetadata>;\nexport type BugReportDiagnostics = ReturnType<typeof collectBugReportDiagnostics>;\n\nexport interface BugReportBundle {\n\tmetadata: BugReportMetadata;\n\tdiagnostics: BugReportDiagnostics;\n\tsessionJsonl?: string;\n\tsummary?: string;\n}\n\nexport interface BugReportSessionEntryData {\n\tid: string;\n\tcreatedAt: string;\n\thint: string | null;\n\tsessionIncluded: boolean;\n\tsummaryIncluded: boolean;\n\tdelivery: \"zip\" | \"upload\";\n\tpath?: string;\n}\n\ninterface BugReportFile {\n\tname: string;\n\tcontentType: string;\n\tdata: string;\n}\n\n/** Files included in the exported archive. */\nexport function bugReportFiles(bundle: BugReportBundle): BugReportFile[] {\n\tconst files: BugReportFile[] = [\n\t\t{ name: \"report.json\", contentType: \"application/json\", data: `${JSON.stringify(bundle.metadata, null, 2)}\\n` },\n\t\t{\n\t\t\tname: \"diagnostics.json\",\n\t\t\tcontentType: \"application/json\",\n\t\t\tdata: `${JSON.stringify(bundle.diagnostics, null, 2)}\\n`,\n\t\t},\n\t];\n\tif (bundle.sessionJsonl !== undefined) {\n\t\tfiles.push({ name: \"session.jsonl\", contentType: \"application/x-ndjson\", data: bundle.sessionJsonl });\n\t}\n\tif (bundle.summary !== undefined) {\n\t\tfiles.push({\n\t\t\tname: \"summary.md\",\n\t\t\tcontentType: \"text/markdown\",\n\t\t\tdata: bundle.summary.endsWith(\"\\n\") ? bundle.summary : `${bundle.summary}\\n`,\n\t\t});\n\t}\n\treturn files;\n}\n\nexport function writeBugReportArchive(bundle: BugReportBundle, filePath: string): Promise<void> {\n\treturn writeZipArchive(filePath, bugReportFiles(bundle));\n}\n\nexport function bugReportArchiveFileName(id: string): string {\n\treturn `apex-code-bug-report-${id}.zip`;\n}\n\nconst BUG_SUMMARY_SYSTEM_PROMPT = `You are helping a user file a bug report about Apex Code, the coding agent they are talking to. You will be shown the conversation transcript. Write a report for the Apex Code developers describing what the user was doing and what went wrong.\n\nDo NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the report.`;\n\nconst BUG_SUMMARY_INSTRUCTIONS = `Write the bug report in Markdown with these sections:\n\n## What the user was doing\nOne short paragraph.\n\n## What went wrong\nConcrete description of the failure: wrong output, errors, hangs, tool failures, unexpected behavior. Quote error messages and tool output verbatim where they exist.\n\n## Steps to reproduce\nNumbered list, as specific as the transcript allows.\n\n## Relevant details\nTool calls involved, files touched, model behavior, anything else that helps a developer reproduce or locate the problem.\n\nDo not include file contents, secrets, or credentials from the transcript; refer to files by path only. Keep the report factual and concise.`;\n\nfunction selectMessages(messages: readonly AgentMessage[], tokenBudget: number): AgentMessage[] {\n\tconst selected: AgentMessage[] = [];\n\tlet tokens = 0;\n\tfor (let index = messages.length - 1; index >= 0; index--) {\n\t\tconst message = messages[index];\n\t\tconst next = estimateTokens(message);\n\t\tif (selected.length > 0 && tokens + next > tokenBudget) break;\n\t\tselected.push(message);\n\t\ttokens += next;\n\t}\n\treturn selected.reverse();\n}\n\ninterface GenerateBugReportSummaryOptions {\n\tmessages: readonly AgentMessage[];\n\thint?: string;\n\tmodel: Model<Api>;\n\tapiKey?: string;\n\theaders?: Record<string, string>;\n\tenv?: Record<string, string>;\n\tsignal: AbortSignal;\n\tthinkingLevel?: ThinkingLevel;\n\tstreamFn?: StreamFn;\n\tretry?: RetryPolicy;\n\tsessionId?: string;\n}\n\n/** Ask the session model for a report when the user does not share the transcript. */\nexport async function generateBugReportSummary(options: GenerateBugReportSummaryOptions): Promise<string> {\n\tconst { model } = options;\n\tconst contextWindow = model.contextWindow > 0 ? model.contextWindow : 128_000;\n\tconst messages = selectMessages(options.messages, Math.floor(contextWindow * 0.6));\n\tconst hint = options.hint?.trim();\n\tconst prompt = [\n\t\tmessages.length < options.messages.length\n\t\t\t? `Note: only the last ${messages.length} of ${options.messages.length} messages are shown.`\n\t\t\t: undefined,\n\t\t`<conversation>\\n${serializeConversation(convertToLlm(messages))}\\n</conversation>`,\n\t\thint ? `<user-report>\\n${hint}\\n</user-report>` : undefined,\n\t\tBUG_SUMMARY_INSTRUCTIONS,\n\t]\n\t\t.filter((part) => part !== undefined)\n\t\t.join(\"\\n\\n\");\n\tconst requestOptions: SimpleStreamOptions = {\n\t\tmaxTokens: Math.min(4096, model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY),\n\t\tsignal: options.signal,\n\t\tapiKey: options.apiKey,\n\t\theaders: options.headers,\n\t\tenv: options.env,\n\t\tsessionId: options.sessionId,\n\t\t...(model.reasoning && options.thinkingLevel && options.thinkingLevel !== \"off\"\n\t\t\t? { reasoning: options.thinkingLevel }\n\t\t\t: {}),\n\t};\n\tconst response = await completeSummarization(\n\t\tmodel,\n\t\tnormalizeContext({\n\t\t\tsystemPrompt: BUG_SUMMARY_SYSTEM_PROMPT,\n\t\t\tmessages: [{ role: \"user\", content: [{ type: \"text\", text: prompt }], timestamp: Date.now() }],\n\t\t}),\n\t\trequestOptions,\n\t\toptions.streamFn,\n\t\toptions.retry,\n\t);\n\tif (response.stopReason === \"aborted\") throw new Error(\"Bug report summary was cancelled\");\n\tconst failure = getSummarizationFailure(response, \"Bug report summary\");\n\tif (failure) throw new Error(failure);\n\tif (response.content.some((block) => block.type === \"toolCall\")) {\n\t\tthrow new Error(\"Bug report summary attempted to call a tool\");\n\t}\n\tconst text = contentText(response.content).trim();\n\tif (!text) throw new Error(\"Bug report summary was empty\");\n\treturn text;\n}\n"]}

package/dist/core/cache-stats.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-stats.d.ts","sourceRoot":"","sources":["../../src/core/cache-stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAgB,CAAC;AAK1C,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACzB,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,YAAY,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE;YAAE,SAAS,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,SAAS,CAAC;CACzF;AAmGD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAErG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,YAAY,EAAE,EACvB,MAAM,EAAE,gBAAgB,GACtB,GAAG,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAElC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,gBAAgB,GACtB,SAAS,GAAG,SAAS,CAEvB","sourcesContent":["import type { AssistantMessage } from \"@earendil-works/pi-ai\";\nimport type { SessionEntry } from \"./session-manager.ts\";\n\n/**\n * Prompt-cache TTL: idle gaps longer than this are worth mentioning as the\n * likely cause of a miss. Anthropic's default cache TTL is 5 minutes.\n */\nexport const CACHE_TTL_MS = 5 * 60 * 1000;\n\n/** Per-turn misses at or below this are cache breakpoint granularity noise. */\nconst NOISE_FLOOR_TOKENS = 1024;\n\n/** A counted cache miss on a single assistant message. */\nexport interface CacheMiss {\n\t/** Prompt tokens that were in the previous turn's prompt but not read from cache. */\n\tmissedTokens: number;\n\t/** Extra dollars paid vs. a full cache hit; 0 when pricing is unknown. */\n\tmissedCost: number;\n\t/** Milliseconds since the previous request (which last refreshed the cache). */\n\tidleMs: number;\n\t/** True when the model changed relative to the previous request. */\n\tmodelChanged: boolean;\n}\n\nexport interface CacheWasteTotals {\n\tmissedTokens: number;\n\tmissedCost: number;\n\t/** Number of counted misses (turns above the noise floor). */\n\tmissCount: number;\n}\n\n/** Minimal pricing lookup, satisfied by ModelRuntime. Cost is $/million tokens. */\nexport interface ModelPriceSource {\n\tgetModel(provider: string, modelId: string): { cost: { cacheRead: number } } | undefined;\n}\n\n/** The last request seen by the scan; everything in its prompt should be cached. */\ninterface PreviousRequest {\n\tpromptTokens: number;\n\tmodelKey: string;\n\ttimestamp: number;\n\t/**\n\t * Sticky: some earlier request in this scan segment reported cache activity.\n\t * Distinguishes a total miss on a cache-read-only provider (OpenAI-style,\n\t * writes unreported) from a provider that never reports caching at all.\n\t */\n\treportedCache: boolean;\n}\n\n/**\n * Compute the cache miss for one assistant message relative to the previous\n * request. Returns undefined when nothing is counted: first turn, after a\n * reset, no cache activity ever reported (provider without cache support), or\n * miss below the noise floor.\n */\nfunction detectMiss(\n\tprev: PreviousRequest | undefined,\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\t// A zero-cache turn only counts when cache activity was reported before:\n\t// on cache-read-only providers that is a total miss, while on providers\n\t// that never report caching it means nothing.\n\tif (!prev || promptTokens <= 0 || (usage.cacheRead + usage.cacheWrite === 0 && !prev.reportedCache)) {\n\t\treturn undefined;\n\t}\n\n\tconst missedTokens = Math.min(prev.promptTokens, promptTokens) - usage.cacheRead;\n\tif (missedTokens <= NOISE_FLOOR_TOKENS) return undefined;\n\n\t// Extra cost = missed tokens billed at the actual paid rate (input/cacheWrite,\n\t// incl. write premium) instead of the cache-read rate. Missed tokens can only\n\t// land in the input or cacheWrite buckets, so the paid rate comes straight\n\t// from this message's own cost breakdown.\n\tconst paidTokens = usage.input + usage.cacheWrite;\n\tconst paidPerToken = paidTokens > 0 ? (usage.cost.input + usage.cost.cacheWrite) / paidTokens : 0;\n\tconst readPerToken =\n\t\tusage.cacheRead > 0\n\t\t\t? usage.cost.cacheRead / usage.cacheRead\n\t\t\t: (models.getModel(message.provider, message.model)?.cost.cacheRead ?? 0) / 1_000_000;\n\n\treturn {\n\t\tmissedTokens,\n\t\tmissedCost: missedTokens * Math.max(0, paidPerToken - readPerToken),\n\t\tidleMs: Math.max(0, message.timestamp - prev.timestamp),\n\t\tmodelChanged: `${message.provider}/${message.model}` !== prev.modelKey,\n\t};\n}\n\nfunction asPreviousRequest(message: AssistantMessage, reportedCache: boolean): PreviousRequest | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\tif (promptTokens <= 0) return undefined;\n\treturn {\n\t\tpromptTokens,\n\t\tmodelKey: `${message.provider}/${message.model}`,\n\t\ttimestamp: message.timestamp,\n\t\treportedCache: reportedCache || usage.cacheRead + usage.cacheWrite > 0,\n\t};\n}\n\nfunction scan(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): { prev: PreviousRequest | undefined; totals: CacheWasteTotals; misses: Map<AssistantMessage, CacheMiss> } {\n\tlet prev: PreviousRequest | undefined;\n\tconst totals: CacheWasteTotals = { missedTokens: 0, missedCost: 0, missCount: 0 };\n\tconst misses = new Map<AssistantMessage, CacheMiss>();\n\n\tfor (const entry of entries) {\n\t\tif (entry.type === \"compaction\" || entry.type === \"branch_summary\") {\n\t\t\t// The context legitimately changed; the next turn's prompt is new content,\n\t\t\t// not re-billed content. Model switches are NOT exempt: they re-bill the\n\t\t\t// full prompt and should be counted.\n\t\t\tprev = undefined;\n\t\t\tcontinue;\n\t\t}\n\t\tif (entry.type === \"message\" && entry.message.role === \"assistant\") {\n\t\t\tconst miss = detectMiss(prev, entry.message, models);\n\t\t\tif (miss) {\n\t\t\t\ttotals.missedTokens += miss.missedTokens;\n\t\t\t\ttotals.missedCost += miss.missedCost;\n\t\t\t\ttotals.missCount += 1;\n\t\t\t\tmisses.set(entry.message, miss);\n\t\t\t}\n\t\t\tprev = asPreviousRequest(entry.message, prev?.reportedCache ?? false) ?? prev;\n\t\t}\n\t}\n\treturn { prev, totals, misses };\n}\n\n/**\n * Cumulative cache waste across a session: prompt tokens that should have been\n * cache reads (they were in the previous turn's prompt) but were re-billed.\n */\nexport function computeCacheWaste(entries: SessionEntry[], models: ModelPriceSource): CacheWasteTotals {\n\treturn scan(entries, models).totals;\n}\n\n/**\n * All counted cache misses across a session, keyed by the assistant message\n * (by reference) that paid for them. Used to re-derive transcript notices when\n * rebuilding the chat from entries (resume, post-compaction rebuild).\n */\nexport function collectCacheMisses(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): Map<AssistantMessage, CacheMiss> {\n\treturn scan(entries, models).misses;\n}\n\n/**\n * Detect a cache miss on a just-completed assistant message.\n * `entries` must not yet contain `message` (message_end fires before persistence).\n */\nexport function detectCacheMiss(\n\tentries: SessionEntry[],\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\treturn detectMiss(scan(entries, models).prev, message, models);\n}\n"]}
+{"version":3,"file":"cache-stats.d.ts","sourceRoot":"","sources":["../../src/core/cache-stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAgB,CAAC;AAK1C,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACzB,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,YAAY,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE;YAAE,SAAS,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,SAAS,CAAC;CACzF;AA6GD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAErG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,YAAY,EAAE,EACvB,MAAM,EAAE,gBAAgB,GACtB,GAAG,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAElC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,gBAAgB,GACtB,SAAS,GAAG,SAAS,CAEvB","sourcesContent":["import type { AssistantMessage } from \"@earendil-works/pi-ai\";\nimport type { SessionEntry } from \"./session-manager.ts\";\n\n/**\n * Prompt-cache TTL: idle gaps longer than this are worth mentioning as the\n * likely cause of a miss. Anthropic's default cache TTL is 5 minutes.\n */\nexport const CACHE_TTL_MS = 5 * 60 * 1000;\n\n/** Per-turn misses at or below this are cache breakpoint granularity noise. */\nconst NOISE_FLOOR_TOKENS = 1024;\n\n/** A counted cache miss on a single assistant message. */\nexport interface CacheMiss {\n\t/** Prompt tokens that were in the previous turn's prompt but not read from cache. */\n\tmissedTokens: number;\n\t/** Extra dollars paid vs. a full cache hit; 0 when pricing is unknown. */\n\tmissedCost: number;\n\t/** Milliseconds since the previous request (which last refreshed the cache). */\n\tidleMs: number;\n\t/** True when the model changed relative to the previous request. */\n\tmodelChanged: boolean;\n}\n\nexport interface CacheWasteTotals {\n\tmissedTokens: number;\n\tmissedCost: number;\n\t/** Number of counted misses (turns above the noise floor). */\n\tmissCount: number;\n}\n\n/** Minimal pricing lookup, satisfied by ModelRuntime. Cost is $/million tokens. */\nexport interface ModelPriceSource {\n\tgetModel(provider: string, modelId: string): { cost: { cacheRead: number } } | undefined;\n}\n\n/** The last request seen by the scan; everything in its prompt should be cached. */\ninterface PreviousRequest {\n\tpromptTokens: number;\n\tmodelKey: string;\n\ttimestamp: number;\n\t/**\n\t * Sticky: some earlier request in this scan segment reported cache activity.\n\t * Distinguishes a total miss on a cache-read-only provider (OpenAI-style,\n\t * writes unreported) from a provider that never reports caching at all.\n\t */\n\treportedCache: boolean;\n}\n\n/**\n * Compute the cache miss for one assistant message relative to the previous\n * request. Returns undefined when nothing is counted: first turn, after a\n * reset, no cache activity ever reported (provider without cache support), or\n * miss below the noise floor.\n */\nfunction detectMiss(\n\tprev: PreviousRequest | undefined,\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\t// A zero-cache turn only counts when cache activity was reported before:\n\t// on cache-read-only providers that is a total miss, while on providers\n\t// that never report caching it means nothing.\n\tif (!prev || promptTokens <= 0 || (usage.cacheRead + usage.cacheWrite === 0 && !prev.reportedCache)) {\n\t\treturn undefined;\n\t}\n\n\tconst missedTokens = Math.min(prev.promptTokens, promptTokens) - usage.cacheRead;\n\tif (missedTokens <= NOISE_FLOOR_TOKENS) return undefined;\n\n\t// Extra cost = missed tokens billed at the actual paid rate (input/cacheWrite,\n\t// incl. write premium) instead of the cache-read rate. Missed tokens can only\n\t// land in the input or cacheWrite buckets, so the paid rate comes straight\n\t// from this message's own cost breakdown.\n\tconst paidTokens = usage.input + usage.cacheWrite;\n\tconst paidPerToken = paidTokens > 0 ? (usage.cost.input + usage.cost.cacheWrite) / paidTokens : 0;\n\tconst readPerToken =\n\t\tusage.cacheRead > 0\n\t\t\t? usage.cost.cacheRead / usage.cacheRead\n\t\t\t: (models.getModel(message.provider, message.model)?.cost.cacheRead ?? 0) / 1_000_000;\n\n\treturn {\n\t\tmissedTokens,\n\t\tmissedCost: missedTokens * Math.max(0, paidPerToken - readPerToken),\n\t\tidleMs: Math.max(0, message.timestamp - prev.timestamp),\n\t\tmodelChanged: `${message.provider}/${message.model}` !== prev.modelKey,\n\t};\n}\n\nfunction asPreviousRequest(message: AssistantMessage, reportedCache: boolean): PreviousRequest | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\tif (promptTokens <= 0) return undefined;\n\treturn {\n\t\tpromptTokens,\n\t\tmodelKey: `${message.provider}/${message.model}`,\n\t\ttimestamp: message.timestamp,\n\t\treportedCache: reportedCache || usage.cacheRead + usage.cacheWrite > 0,\n\t};\n}\n\nfunction scan(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): { prev: PreviousRequest | undefined; totals: CacheWasteTotals; misses: Map<AssistantMessage, CacheMiss> } {\n\tlet prev: PreviousRequest | undefined;\n\tconst totals: CacheWasteTotals = { missedTokens: 0, missedCost: 0, missCount: 0 };\n\tconst misses = new Map<AssistantMessage, CacheMiss>();\n\n\tfor (const entry of entries) {\n\t\tif (entry.type === \"compaction\" || entry.type === \"branch_summary\") {\n\t\t\t// The context legitimately changed; the next turn's prompt is new content,\n\t\t\t// not re-billed content. Model switches are NOT exempt: they re-bill the\n\t\t\t// full prompt and should be counted.\n\t\t\tprev = undefined;\n\t\t\tcontinue;\n\t\t}\n\t\tif (entry.type === \"usage\" && entry.kind === \"cache_warm\") {\n\t\t\tconst promptTokens = entry.usage.input + entry.usage.cacheRead + entry.usage.cacheWrite;\n\t\t\tif (promptTokens > 0) {\n\t\t\t\tprev = {\n\t\t\t\t\tpromptTokens,\n\t\t\t\t\tmodelKey: `${entry.provider}/${entry.model}`,\n\t\t\t\t\ttimestamp: Date.parse(entry.timestamp),\n\t\t\t\t\treportedCache: true,\n\t\t\t\t};\n\t\t\t}\n\t\t} else if (entry.type === \"message\" && entry.message.role === \"assistant\") {\n\t\t\tconst miss = detectMiss(prev, entry.message, models);\n\t\t\tif (miss) {\n\t\t\t\ttotals.missedTokens += miss.missedTokens;\n\t\t\t\ttotals.missedCost += miss.missedCost;\n\t\t\t\ttotals.missCount += 1;\n\t\t\t\tmisses.set(entry.message, miss);\n\t\t\t}\n\t\t\tprev = asPreviousRequest(entry.message, prev?.reportedCache ?? false) ?? prev;\n\t\t}\n\t}\n\treturn { prev, totals, misses };\n}\n\n/**\n * Cumulative cache waste across a session: prompt tokens that should have been\n * cache reads (they were in the previous turn's prompt) but were re-billed.\n */\nexport function computeCacheWaste(entries: SessionEntry[], models: ModelPriceSource): CacheWasteTotals {\n\treturn scan(entries, models).totals;\n}\n\n/**\n * All counted cache misses across a session, keyed by the assistant message\n * (by reference) that paid for them. Used to re-derive transcript notices when\n * rebuilding the chat from entries (resume, post-compaction rebuild).\n */\nexport function collectCacheMisses(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): Map<AssistantMessage, CacheMiss> {\n\treturn scan(entries, models).misses;\n}\n\n/**\n * Detect a cache miss on a just-completed assistant message.\n * `entries` must not yet contain `message` (message_end fires before persistence).\n */\nexport function detectCacheMiss(\n\tentries: SessionEntry[],\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\treturn detectMiss(scan(entries, models).prev, message, models);\n}\n"]}

package/dist/core/cache-stats.js

@@ -63,7 +63,18 @@ function scan(entries, models) {
             prev = undefined;
             continue;
         }
-        if (entry.type === "message" && entry.message.role === "assistant") {
+        if (entry.type === "usage" && entry.kind === "cache_warm") {
+            const promptTokens = entry.usage.input + entry.usage.cacheRead + entry.usage.cacheWrite;
+            if (promptTokens > 0) {
+                prev = {
+                    promptTokens,
+                    modelKey: `${entry.provider}/${entry.model}`,
+                    timestamp: Date.parse(entry.timestamp),
+                    reportedCache: true,
+                };
+            }
+        }
+        else if (entry.type === "message" && entry.message.role === "assistant") {
             const miss = detectMiss(prev, entry.message, models);
             if (miss) {
                 totals.missedTokens += miss.missedTokens;

package/dist/core/cache-stats.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache-stats.js","sourceRoot":"","sources":["../../src/core/cache-stats.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AssistantMessage } from \"@earendil-works/pi-ai\";\nimport type { SessionEntry } from \"./session-manager.ts\";\n\n/**\n * Prompt-cache TTL: idle gaps longer than this are worth mentioning as the\n * likely cause of a miss. Anthropic's default cache TTL is 5 minutes.\n */\nexport const CACHE_TTL_MS = 5 * 60 * 1000;\n\n/** Per-turn misses at or below this are cache breakpoint granularity noise. */\nconst NOISE_FLOOR_TOKENS = 1024;\n\n/** A counted cache miss on a single assistant message. */\nexport interface CacheMiss {\n\t/** Prompt tokens that were in the previous turn's prompt but not read from cache. */\n\tmissedTokens: number;\n\t/** Extra dollars paid vs. a full cache hit; 0 when pricing is unknown. */\n\tmissedCost: number;\n\t/** Milliseconds since the previous request (which last refreshed the cache). */\n\tidleMs: number;\n\t/** True when the model changed relative to the previous request. */\n\tmodelChanged: boolean;\n}\n\nexport interface CacheWasteTotals {\n\tmissedTokens: number;\n\tmissedCost: number;\n\t/** Number of counted misses (turns above the noise floor). */\n\tmissCount: number;\n}\n\n/** Minimal pricing lookup, satisfied by ModelRuntime. Cost is $/million tokens. */\nexport interface ModelPriceSource {\n\tgetModel(provider: string, modelId: string): { cost: { cacheRead: number } } | undefined;\n}\n\n/** The last request seen by the scan; everything in its prompt should be cached. */\ninterface PreviousRequest {\n\tpromptTokens: number;\n\tmodelKey: string;\n\ttimestamp: number;\n\t/**\n\t * Sticky: some earlier request in this scan segment reported cache activity.\n\t * Distinguishes a total miss on a cache-read-only provider (OpenAI-style,\n\t * writes unreported) from a provider that never reports caching at all.\n\t */\n\treportedCache: boolean;\n}\n\n/**\n * Compute the cache miss for one assistant message relative to the previous\n * request. Returns undefined when nothing is counted: first turn, after a\n * reset, no cache activity ever reported (provider without cache support), or\n * miss below the noise floor.\n */\nfunction detectMiss(\n\tprev: PreviousRequest | undefined,\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\t// A zero-cache turn only counts when cache activity was reported before:\n\t// on cache-read-only providers that is a total miss, while on providers\n\t// that never report caching it means nothing.\n\tif (!prev || promptTokens <= 0 || (usage.cacheRead + usage.cacheWrite === 0 && !prev.reportedCache)) {\n\t\treturn undefined;\n\t}\n\n\tconst missedTokens = Math.min(prev.promptTokens, promptTokens) - usage.cacheRead;\n\tif (missedTokens <= NOISE_FLOOR_TOKENS) return undefined;\n\n\t// Extra cost = missed tokens billed at the actual paid rate (input/cacheWrite,\n\t// incl. write premium) instead of the cache-read rate. Missed tokens can only\n\t// land in the input or cacheWrite buckets, so the paid rate comes straight\n\t// from this message's own cost breakdown.\n\tconst paidTokens = usage.input + usage.cacheWrite;\n\tconst paidPerToken = paidTokens > 0 ? (usage.cost.input + usage.cost.cacheWrite) / paidTokens : 0;\n\tconst readPerToken =\n\t\tusage.cacheRead > 0\n\t\t\t? usage.cost.cacheRead / usage.cacheRead\n\t\t\t: (models.getModel(message.provider, message.model)?.cost.cacheRead ?? 0) / 1_000_000;\n\n\treturn {\n\t\tmissedTokens,\n\t\tmissedCost: missedTokens * Math.max(0, paidPerToken - readPerToken),\n\t\tidleMs: Math.max(0, message.timestamp - prev.timestamp),\n\t\tmodelChanged: `${message.provider}/${message.model}` !== prev.modelKey,\n\t};\n}\n\nfunction asPreviousRequest(message: AssistantMessage, reportedCache: boolean): PreviousRequest | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\tif (promptTokens <= 0) return undefined;\n\treturn {\n\t\tpromptTokens,\n\t\tmodelKey: `${message.provider}/${message.model}`,\n\t\ttimestamp: message.timestamp,\n\t\treportedCache: reportedCache || usage.cacheRead + usage.cacheWrite > 0,\n\t};\n}\n\nfunction scan(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): { prev: PreviousRequest | undefined; totals: CacheWasteTotals; misses: Map<AssistantMessage, CacheMiss> } {\n\tlet prev: PreviousRequest | undefined;\n\tconst totals: CacheWasteTotals = { missedTokens: 0, missedCost: 0, missCount: 0 };\n\tconst misses = new Map<AssistantMessage, CacheMiss>();\n\n\tfor (const entry of entries) {\n\t\tif (entry.type === \"compaction\" || entry.type === \"branch_summary\") {\n\t\t\t// The context legitimately changed; the next turn's prompt is new content,\n\t\t\t// not re-billed content. Model switches are NOT exempt: they re-bill the\n\t\t\t// full prompt and should be counted.\n\t\t\tprev = undefined;\n\t\t\tcontinue;\n\t\t}\n\t\tif (entry.type === \"message\" && entry.message.role === \"assistant\") {\n\t\t\tconst miss = detectMiss(prev, entry.message, models);\n\t\t\tif (miss) {\n\t\t\t\ttotals.missedTokens += miss.missedTokens;\n\t\t\t\ttotals.missedCost += miss.missedCost;\n\t\t\t\ttotals.missCount += 1;\n\t\t\t\tmisses.set(entry.message, miss);\n\t\t\t}\n\t\t\tprev = asPreviousRequest(entry.message, prev?.reportedCache ?? false) ?? prev;\n\t\t}\n\t}\n\treturn { prev, totals, misses };\n}\n\n/**\n * Cumulative cache waste across a session: prompt tokens that should have been\n * cache reads (they were in the previous turn's prompt) but were re-billed.\n */\nexport function computeCacheWaste(entries: SessionEntry[], models: ModelPriceSource): CacheWasteTotals {\n\treturn scan(entries, models).totals;\n}\n\n/**\n * All counted cache misses across a session, keyed by the assistant message\n * (by reference) that paid for them. Used to re-derive transcript notices when\n * rebuilding the chat from entries (resume, post-compaction rebuild).\n */\nexport function collectCacheMisses(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): Map<AssistantMessage, CacheMiss> {\n\treturn scan(entries, models).misses;\n}\n\n/**\n * Detect a cache miss on a just-completed assistant message.\n * `entries` must not yet contain `message` (message_end fires before persistence).\n */\nexport function detectCacheMiss(\n\tentries: SessionEntry[],\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\treturn detectMiss(scan(entries, models).prev, message, models);\n}\n"]}
+{"version":3,"file":"cache-stats.js","sourceRoot":"","sources":["../../src/core/cache-stats.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AssistantMessage } from \"@earendil-works/pi-ai\";\nimport type { SessionEntry } from \"./session-manager.ts\";\n\n/**\n * Prompt-cache TTL: idle gaps longer than this are worth mentioning as the\n * likely cause of a miss. Anthropic's default cache TTL is 5 minutes.\n */\nexport const CACHE_TTL_MS = 5 * 60 * 1000;\n\n/** Per-turn misses at or below this are cache breakpoint granularity noise. */\nconst NOISE_FLOOR_TOKENS = 1024;\n\n/** A counted cache miss on a single assistant message. */\nexport interface CacheMiss {\n\t/** Prompt tokens that were in the previous turn's prompt but not read from cache. */\n\tmissedTokens: number;\n\t/** Extra dollars paid vs. a full cache hit; 0 when pricing is unknown. */\n\tmissedCost: number;\n\t/** Milliseconds since the previous request (which last refreshed the cache). */\n\tidleMs: number;\n\t/** True when the model changed relative to the previous request. */\n\tmodelChanged: boolean;\n}\n\nexport interface CacheWasteTotals {\n\tmissedTokens: number;\n\tmissedCost: number;\n\t/** Number of counted misses (turns above the noise floor). */\n\tmissCount: number;\n}\n\n/** Minimal pricing lookup, satisfied by ModelRuntime. Cost is $/million tokens. */\nexport interface ModelPriceSource {\n\tgetModel(provider: string, modelId: string): { cost: { cacheRead: number } } | undefined;\n}\n\n/** The last request seen by the scan; everything in its prompt should be cached. */\ninterface PreviousRequest {\n\tpromptTokens: number;\n\tmodelKey: string;\n\ttimestamp: number;\n\t/**\n\t * Sticky: some earlier request in this scan segment reported cache activity.\n\t * Distinguishes a total miss on a cache-read-only provider (OpenAI-style,\n\t * writes unreported) from a provider that never reports caching at all.\n\t */\n\treportedCache: boolean;\n}\n\n/**\n * Compute the cache miss for one assistant message relative to the previous\n * request. Returns undefined when nothing is counted: first turn, after a\n * reset, no cache activity ever reported (provider without cache support), or\n * miss below the noise floor.\n */\nfunction detectMiss(\n\tprev: PreviousRequest | undefined,\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\t// A zero-cache turn only counts when cache activity was reported before:\n\t// on cache-read-only providers that is a total miss, while on providers\n\t// that never report caching it means nothing.\n\tif (!prev || promptTokens <= 0 || (usage.cacheRead + usage.cacheWrite === 0 && !prev.reportedCache)) {\n\t\treturn undefined;\n\t}\n\n\tconst missedTokens = Math.min(prev.promptTokens, promptTokens) - usage.cacheRead;\n\tif (missedTokens <= NOISE_FLOOR_TOKENS) return undefined;\n\n\t// Extra cost = missed tokens billed at the actual paid rate (input/cacheWrite,\n\t// incl. write premium) instead of the cache-read rate. Missed tokens can only\n\t// land in the input or cacheWrite buckets, so the paid rate comes straight\n\t// from this message's own cost breakdown.\n\tconst paidTokens = usage.input + usage.cacheWrite;\n\tconst paidPerToken = paidTokens > 0 ? (usage.cost.input + usage.cost.cacheWrite) / paidTokens : 0;\n\tconst readPerToken =\n\t\tusage.cacheRead > 0\n\t\t\t? usage.cost.cacheRead / usage.cacheRead\n\t\t\t: (models.getModel(message.provider, message.model)?.cost.cacheRead ?? 0) / 1_000_000;\n\n\treturn {\n\t\tmissedTokens,\n\t\tmissedCost: missedTokens * Math.max(0, paidPerToken - readPerToken),\n\t\tidleMs: Math.max(0, message.timestamp - prev.timestamp),\n\t\tmodelChanged: `${message.provider}/${message.model}` !== prev.modelKey,\n\t};\n}\n\nfunction asPreviousRequest(message: AssistantMessage, reportedCache: boolean): PreviousRequest | undefined {\n\tconst usage = message.usage;\n\tconst promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;\n\tif (promptTokens <= 0) return undefined;\n\treturn {\n\t\tpromptTokens,\n\t\tmodelKey: `${message.provider}/${message.model}`,\n\t\ttimestamp: message.timestamp,\n\t\treportedCache: reportedCache || usage.cacheRead + usage.cacheWrite > 0,\n\t};\n}\n\nfunction scan(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): { prev: PreviousRequest | undefined; totals: CacheWasteTotals; misses: Map<AssistantMessage, CacheMiss> } {\n\tlet prev: PreviousRequest | undefined;\n\tconst totals: CacheWasteTotals = { missedTokens: 0, missedCost: 0, missCount: 0 };\n\tconst misses = new Map<AssistantMessage, CacheMiss>();\n\n\tfor (const entry of entries) {\n\t\tif (entry.type === \"compaction\" || entry.type === \"branch_summary\") {\n\t\t\t// The context legitimately changed; the next turn's prompt is new content,\n\t\t\t// not re-billed content. Model switches are NOT exempt: they re-bill the\n\t\t\t// full prompt and should be counted.\n\t\t\tprev = undefined;\n\t\t\tcontinue;\n\t\t}\n\t\tif (entry.type === \"usage\" && entry.kind === \"cache_warm\") {\n\t\t\tconst promptTokens = entry.usage.input + entry.usage.cacheRead + entry.usage.cacheWrite;\n\t\t\tif (promptTokens > 0) {\n\t\t\t\tprev = {\n\t\t\t\t\tpromptTokens,\n\t\t\t\t\tmodelKey: `${entry.provider}/${entry.model}`,\n\t\t\t\t\ttimestamp: Date.parse(entry.timestamp),\n\t\t\t\t\treportedCache: true,\n\t\t\t\t};\n\t\t\t}\n\t\t} else if (entry.type === \"message\" && entry.message.role === \"assistant\") {\n\t\t\tconst miss = detectMiss(prev, entry.message, models);\n\t\t\tif (miss) {\n\t\t\t\ttotals.missedTokens += miss.missedTokens;\n\t\t\t\ttotals.missedCost += miss.missedCost;\n\t\t\t\ttotals.missCount += 1;\n\t\t\t\tmisses.set(entry.message, miss);\n\t\t\t}\n\t\t\tprev = asPreviousRequest(entry.message, prev?.reportedCache ?? false) ?? prev;\n\t\t}\n\t}\n\treturn { prev, totals, misses };\n}\n\n/**\n * Cumulative cache waste across a session: prompt tokens that should have been\n * cache reads (they were in the previous turn's prompt) but were re-billed.\n */\nexport function computeCacheWaste(entries: SessionEntry[], models: ModelPriceSource): CacheWasteTotals {\n\treturn scan(entries, models).totals;\n}\n\n/**\n * All counted cache misses across a session, keyed by the assistant message\n * (by reference) that paid for them. Used to re-derive transcript notices when\n * rebuilding the chat from entries (resume, post-compaction rebuild).\n */\nexport function collectCacheMisses(\n\tentries: SessionEntry[],\n\tmodels: ModelPriceSource,\n): Map<AssistantMessage, CacheMiss> {\n\treturn scan(entries, models).misses;\n}\n\n/**\n * Detect a cache miss on a just-completed assistant message.\n * `entries` must not yet contain `message` (message_end fires before persistence).\n */\nexport function detectCacheMiss(\n\tentries: SessionEntry[],\n\tmessage: AssistantMessage,\n\tmodels: ModelPriceSource,\n): CacheMiss | undefined {\n\treturn detectMiss(scan(entries, models).prev, message, models);\n}\n"]}

package/dist/core/cache-warmer.d.ts

@@ -0,0 +1,103 @@
+import { type Api, type Context, type Model, type ModelsSimpleStreamOptions, type SimpleStreamOptions } from "@earendil-works/pi-ai";
+import type { ModelRuntime } from "./model-runtime.ts";
+import type { SessionManager, UsageEntry } from "./session-manager.ts";
+import type { CacheWarmingMode } from "./settings-manager.ts";
+/** Refresh at 90% of the TTL while preserving at least ten seconds of margin. */
+export declare function getCacheWarmingDelayMs(ttlMs: number): number | undefined;
+/**
+ * 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 declare function getPromptCacheTtlMs(model: Model<Api>, options: SimpleStreamOptions | undefined): number | undefined;
+/**
+ * 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 declare function isReplayable(model: Model<Api>, options: SimpleStreamOptions | undefined): boolean;
+export type CacheWarmingAction = "warm" | "stop";
+/** Inputs and outcome of one warm-or-stop decision, as shown by `/session`. */
+export interface CacheWarmingDecision {
+    /** "streaming" while the agent run that sent the request is still active. */
+    phase: "streaming" | "idle";
+    /** Price of this refresh: a cache read of the prompt plus one output token. */
+    warmCost: number;
+    /** Extra price of the next real request if the cache entry is lost. */
+    missCost: number;
+    /** Estimated chance that a real request arrives before the entry expires. */
+    continuationProbability: number;
+    /** `continuationProbability * missCost - warmCost`. */
+    expectedSavings: number;
+    /** False when the prompt size or the model's prices are unknown. */
+    economicsAvailable: boolean;
+    /** Pi's decision: "warm" when `expectedSavings` is at least $0.05. */
+    action: CacheWarmingAction;
+}
+/**
+ * Fired before each refresh with pi's decision filled in. Everything else an
+ * extension might want (model, idle state, context size) is on the context.
+ */
+export interface CacheWarmingDecisionEvent extends Pick<CacheWarmingDecision, "warmCost" | "missCost" | "continuationProbability" | "action"> {
+    type: "cache_warming_decision";
+}
+export interface CacheWarmingDecisionEventResult {
+    /** Override whether this refresh is sent. "stop" ends warming until the next real request. */
+    action?: CacheWarmingAction;
+}
+export interface CacheWarmingStatus {
+    /** "scheduled": a refresh timer is armed; "refreshing": a warm request is in flight. */
+    state: "inactive" | "scheduled" | "refreshing";
+    /** Why nothing is scheduled. */
+    reason?: string;
+    nextWarmAt?: number;
+    /** The pending decision, or the decision that stopped warming. */
+    decision?: CacheWarmingDecision;
+    /** True when an extension changed `decision.action`. */
+    extensionOverride?: boolean;
+}
+/** The request whose prompt cache entry should be kept warm, exactly as it was sent. */
+export interface CacheWarmRequest {
+    model: Model<Api>;
+    context: Context;
+    options: ModelsSimpleStreamOptions;
+}
+/**
+ * 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 declare class CacheWarmer {
+    private run?;
+    private inactive;
+    private readonly models;
+    private readonly sessionManager;
+    private readonly getMode;
+    /** Lets extensions override `event.action`; failures fall back to pi's decision. */
+    private readonly decide;
+    /** Called with the persisted usage entry after each successful refresh. */
+    onWarmed?: (entry: UsageEntry) => void;
+    constructor(models: Pick<ModelRuntime, "streamSimple">, sessionManager: Pick<SessionManager, "appendUsage" | "getBranch">, getMode: () => CacheWarmingMode, decide?: (event: CacheWarmingDecisionEvent) => Promise<CacheWarmingAction>);
+    get status(): CacheWarmingStatus;
+    /** Keep the prompt cache entry written by `request` warm while `isCurrent` holds. */
+    start(request: CacheWarmRequest, isCurrent: () => boolean): void;
+    onAgentSettled(): void;
+    /** Reconcile an active run after the persisted warming mode changes. */
+    onModeChanged(): void;
+    cancel(): void;
+    private clearRun;
+    private stop;
+    private schedule;
+    private refresh;
+    private refreshDeadlineMissed;
+    private validateRun;
+    private getModeStopReason;
+    private evaluate;
+}
+/** One-line status for `/session`. */
+export declare function formatCacheWarmingStatus(status: CacheWarmingStatus, now?: number): string;
+/** One-line transcript text for persisted cache-warming usage. */
+export declare function formatCacheWarmingUsage(entry: UsageEntry): string;
+//# sourceMappingURL=cache-warmer.d.ts.map

package/dist/core/cache-warmer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-warmer.d.ts","sourceRoot":"","sources":["../../src/core/cache-warmer.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype Api,\n\ttype Context,\n\tcalculateCost,\n\ttype Model,\n\ttype ModelsSimpleStreamOptions,\n\ttype SimpleStreamOptions,\n\ttype Usage,\n} from \"@earendil-works/pi-ai\";\nimport { getProviderEnvValue } from \"@earendil-works/pi-ai/utils/provider-env\";\nimport type { ModelRuntime } from \"./model-runtime.ts\";\nimport type { SessionEntry, SessionManager, UsageEntry } from \"./session-manager.ts\";\nimport type { CacheWarmingMode } from \"./settings-manager.ts\";\n\n/** Streaming warming never continues past this long after the real request that started it. */\nconst MAX_WARMING_AGE_MS = 60 * 60_000;\n/** Idle warming uses a shorter horizon because continuation estimates become less reliable with age. */\nconst MAX_IDLE_WARMING_AGE_MS = 30 * 60_000;\n/** A refresh is sent only when it is expected to save at least this many dollars. */\nconst CACHE_WARMING_MINIMUM_EXPECTED_SAVINGS = 0.05;\n/**\n * Chance that a real request arrives before the cache entry expires while the\n * agent sits idle. Measured from our own usage; per-session estimates were not\n * better than this constant.\n */\nconst IDLE_CONTINUATION_PROBABILITY = 0.15;\n\n/** Refresh at 90% of the TTL while preserving at least ten seconds of margin. */\nexport function getCacheWarmingDelayMs(ttlMs: number): number | undefined {\n\tif (ttlMs <= 10_000) return undefined;\n\treturn Math.max(1, Math.floor(Math.min(ttlMs * 0.9, ttlMs - 10_000)));\n}\n\n/**\n * Lifetime of the prompt cache entry a request writes, from the model's\n * `promptCache` tier for the retention the request used. Undefined when the\n * model has no lifetime for that tier or caching is off.\n */\nexport function getPromptCacheTtlMs(model: Model<Api>, options: SimpleStreamOptions | undefined): number | undefined {\n\tconst retention =\n\t\toptions?.cacheRetention ??\n\t\t(getProviderEnvValue(\"PI_CACHE_RETENTION\", options?.env) === \"long\" ? \"long\" : \"short\");\n\tif (retention === \"none\") return undefined;\n\tconst seconds = model.promptCache?.[retention];\n\treturn seconds === undefined ? undefined : seconds * 1000;\n}\n\n/**\n * Whether replaying the request with a one-token output cap leaves its cache\n * entry untouched. Anthropic's budget-based thinking (Claude models without\n * adaptive thinking) derives `budget_tokens` from `max_tokens`; the replay\n * would get a different budget, which Anthropic keys the message cache on,\n * and the model could still think for thousands of tokens.\n */\nexport function isReplayable(model: Model<Api>, options: SimpleStreamOptions | undefined): boolean {\n\tif (!options?.reasoning || model.api !== \"anthropic-messages\") return true;\n\treturn (model as Model<\"anthropic-messages\">).compat?.forceAdaptiveThinking === true;\n}\n\n/** Prompt size of the most recent real request on the branch, as reported by the provider. */\nfunction lastPromptTokens(entries: SessionEntry[]): number {\n\tfor (let index = entries.length - 1; index >= 0; index--) {\n\t\tconst entry = entries[index];\n\t\tif (entry.type === \"message\" && entry.message.role === \"assistant\") {\n\t\t\tconst usage = entry.message.usage;\n\t\t\treturn usage.input + usage.cacheRead + usage.cacheWrite;\n\t\t}\n\t}\n\treturn 0;\n}\n\nfunction price(\n\tmodel: Model<Api>,\n\ttokens: Partial<Pick<Usage, \"input\" | \"output\" | \"cacheRead\" | \"cacheWrite\">>,\n): number {\n\tconst usage: Usage = {\n\t\tinput: 0,\n\t\toutput: 0,\n\t\tcacheRead: 0,\n\t\tcacheWrite: 0,\n\t\ttotalTokens: 0,\n\t\tcost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },\n\t\t...tokens,\n\t};\n\treturn calculateCost(model, usage).total;\n}\n\nexport type CacheWarmingAction = \"warm\" | \"stop\";\n\n/** Inputs and outcome of one warm-or-stop decision, as shown by `/session`. */\nexport interface CacheWarmingDecision {\n\t/** \"streaming\" while the agent run that sent the request is still active. */\n\tphase: \"streaming\" | \"idle\";\n\t/** Price of this refresh: a cache read of the prompt plus one output token. */\n\twarmCost: number;\n\t/** Extra price of the next real request if the cache entry is lost. */\n\tmissCost: number;\n\t/** Estimated chance that a real request arrives before the entry expires. */\n\tcontinuationProbability: number;\n\t/** `continuationProbability * missCost - warmCost`. */\n\texpectedSavings: number;\n\t/** False when the prompt size or the model's prices are unknown. */\n\teconomicsAvailable: boolean;\n\t/** Pi's decision: \"warm\" when `expectedSavings` is at least $0.05. */\n\taction: CacheWarmingAction;\n}\n\n/**\n * Fired before each refresh with pi's decision filled in. Everything else an\n * extension might want (model, idle state, context size) is on the context.\n */\nexport interface CacheWarmingDecisionEvent\n\textends Pick<CacheWarmingDecision, \"warmCost\" | \"missCost\" | \"continuationProbability\" | \"action\"> {\n\ttype: \"cache_warming_decision\";\n}\n\nexport interface CacheWarmingDecisionEventResult {\n\t/** Override whether this refresh is sent. \"stop\" ends warming until the next real request. */\n\taction?: CacheWarmingAction;\n}\n\nexport interface CacheWarmingStatus {\n\t/** \"scheduled\": a refresh timer is armed; \"refreshing\": a warm request is in flight. */\n\tstate: \"inactive\" | \"scheduled\" | \"refreshing\";\n\t/** Why nothing is scheduled. */\n\treason?: string;\n\tnextWarmAt?: number;\n\t/** The pending decision, or the decision that stopped warming. */\n\tdecision?: CacheWarmingDecision;\n\t/** True when an extension changed `decision.action`. */\n\textensionOverride?: boolean;\n}\n\n/** The request whose prompt cache entry should be kept warm, exactly as it was sent. */\nexport interface CacheWarmRequest {\n\tmodel: Model<Api>;\n\tcontext: Context;\n\toptions: ModelsSimpleStreamOptions;\n}\n\ninterface ActiveRun extends CacheWarmRequest {\n\t/** False once the session's model or messages no longer match the request. */\n\tisCurrent: () => boolean;\n\tttlMs: number;\n\tdelayMs: number;\n\t/** Latest safe time to send this refresh, leaving half the original expiry margin. */\n\trefreshDeadlineAt: number;\n\tstartedAt: number;\n\tcontroller: AbortController;\n\tphase: \"streaming\" | \"idle\";\n\tnextWarmAt: number;\n\t/** Set while a refresh that an extension forced is in flight. */\n\textensionOverride: boolean;\n\ttimer?: ReturnType<typeof setTimeout>;\n}\n\n/**\n * Keeps one prompt cache entry alive by re-sending its request with a\n * one-token output cap before the entry expires. `start` replaces any\n * previous run; warm requests never extend the fixed safety windows.\n */\nexport class CacheWarmer {\n\tprivate run?: ActiveRun;\n\tprivate inactive: CacheWarmingStatus;\n\tprivate readonly models: Pick<ModelRuntime, \"streamSimple\">;\n\tprivate readonly sessionManager: Pick<SessionManager, \"appendUsage\" | \"getBranch\">;\n\tprivate readonly getMode: () => CacheWarmingMode;\n\t/** Lets extensions override `event.action`; failures fall back to pi's decision. */\n\tprivate readonly decide: (event: CacheWarmingDecisionEvent) => Promise<CacheWarmingAction>;\n\t/** Called with the persisted usage entry after each successful refresh. */\n\tonWarmed?: (entry: UsageEntry) => void;\n\n\tconstructor(\n\t\tmodels: Pick<ModelRuntime, \"streamSimple\">,\n\t\tsessionManager: Pick<SessionManager, \"appendUsage\" | \"getBranch\">,\n\t\tgetMode: () => CacheWarmingMode,\n\t\tdecide: (event: CacheWarmingDecisionEvent) => Promise<CacheWarmingAction> = async (event) => event.action,\n\t) {\n\t\tthis.models = models;\n\t\tthis.sessionManager = sessionManager;\n\t\tthis.getMode = getMode;\n\t\tthis.decide = decide;\n\t\tthis.inactive = { state: \"inactive\", reason: \"waiting for first request\" };\n\t}\n\n\tget status(): CacheWarmingStatus {\n\t\tif (this.getMode() === \"off\") return { state: \"inactive\", reason: \"cache warming disabled\" };\n\t\tconst run = this.run;\n\t\tif (!run) return this.inactive;\n\t\tif (!run.isCurrent()) return { state: \"inactive\", reason: \"conversation context changed\" };\n\t\tconst decision = this.evaluate(run);\n\t\tconst refreshing = run.timer === undefined;\n\t\tif (!decision.economicsAvailable && !refreshing) {\n\t\t\treturn { state: \"inactive\", reason: \"cache economics unavailable\" };\n\t\t}\n\t\treturn {\n\t\t\tstate: refreshing ? \"refreshing\" : \"scheduled\",\n\t\t\tnextWarmAt: run.nextWarmAt,\n\t\t\tdecision,\n\t\t\textensionOverride: run.extensionOverride,\n\t\t};\n\t}\n\n\t/** Keep the prompt cache entry written by `request` warm while `isCurrent` holds. */\n\tstart(request: CacheWarmRequest, isCurrent: () => boolean): void {\n\t\tthis.clearRun();\n\t\tconst mode = this.getMode();\n\t\tif (mode === \"off\") {\n\t\t\tthis.stop(\"cache warming disabled\");\n\t\t\treturn;\n\t\t}\n\t\tif (!isReplayable(request.model, request.options)) {\n\t\t\tthis.stop(\"request cannot be replayed safely\");\n\t\t\treturn;\n\t\t}\n\t\tconst ttlMs = getPromptCacheTtlMs(request.model, request.options);\n\t\tif (ttlMs === undefined) {\n\t\t\tthis.stop(\n\t\t\t\trequest.options.cacheRetention === \"none\"\n\t\t\t\t\t? \"request disabled prompt caching\"\n\t\t\t\t\t: \"cache lifetime unavailable\",\n\t\t\t);\n\t\t\treturn;\n\t\t}\n\t\tconst delayMs = getCacheWarmingDelayMs(ttlMs);\n\t\tif (delayMs === undefined) {\n\t\t\tthis.stop(\"cache lifetime unavailable\");\n\t\t\treturn;\n\t\t}\n\t\tthis.run = {\n\t\t\t...request,\n\t\t\tisCurrent,\n\t\t\tttlMs,\n\t\t\tdelayMs,\n\t\t\trefreshDeadlineAt: 0,\n\t\t\tstartedAt: Date.now(),\n\t\t\tcontroller: new AbortController(),\n\t\t\tphase: \"streaming\",\n\t\t\tnextWarmAt: 0,\n\t\t\textensionOverride: false,\n\t\t};\n\t\tthis.schedule(this.run);\n\t}\n\n\tonAgentSettled(): void {\n\t\tconst run = this.run;\n\t\tif (!run) return;\n\t\tif (this.getMode() === \"streaming\") {\n\t\t\tthis.stop(\"agent run settled\");\n\t\t\treturn;\n\t\t}\n\t\trun.phase = \"idle\";\n\t\tconst deadline = run.startedAt + MAX_IDLE_WARMING_AGE_MS;\n\t\tif (run.nextWarmAt > deadline || Date.now() >= deadline) {\n\t\t\tthis.stop(\"30-minute idle safety limit reached\");\n\t\t}\n\t}\n\n\t/** Reconcile an active run after the persisted warming mode changes. */\n\tonModeChanged(): void {\n\t\tconst run = this.run;\n\t\tif (!run) return;\n\t\tconst reason = this.getModeStopReason(run);\n\t\tif (reason) this.stop(reason);\n\t}\n\n\tcancel(): void {\n\t\tthis.stop(\"inactive\");\n\t}\n\n\tprivate clearRun(): void {\n\t\tconst run = this.run;\n\t\tif (!run) return;\n\t\tthis.run = undefined;\n\t\tif (run.timer) clearTimeout(run.timer);\n\t\trun.controller.abort();\n\t}\n\n\tprivate stop(reason: string, stopped?: Pick<CacheWarmingStatus, \"decision\" | \"extensionOverride\">): void {\n\t\tthis.clearRun();\n\t\tthis.inactive = { state: \"inactive\", reason, ...stopped };\n\t}\n\n\tprivate schedule(run: ActiveRun): void {\n\t\trun.extensionOverride = false;\n\t\trun.nextWarmAt = Date.now() + run.delayMs;\n\t\t// A timer can run late after sleep or event-loop blockage. Keep half of\n\t\t// the planned pre-expiry margin for that delay and request dispatch; a\n\t\t// late refresh is likely a full-price cache write, not a cache warm.\n\t\trun.refreshDeadlineAt = run.nextWarmAt + Math.floor((run.ttlMs - run.delayMs) / 2);\n\t\tconst deadline = run.startedAt + (run.phase === \"idle\" ? MAX_IDLE_WARMING_AGE_MS : MAX_WARMING_AGE_MS);\n\t\tif (run.nextWarmAt > deadline || Date.now() >= deadline) {\n\t\t\tthis.stop(run.phase === \"idle\" ? \"30-minute idle safety limit reached\" : \"one-hour safety limit reached\");\n\t\t\treturn;\n\t\t}\n\t\trun.timer = setTimeout(() => void this.refresh(run), Math.max(0, run.nextWarmAt - Date.now()));\n\t\trun.timer.unref?.();\n\t}\n\n\tprivate async refresh(run: ActiveRun): Promise<void> {\n\t\trun.timer = undefined;\n\t\tif (!this.validateRun(run)) return;\n\t\tif (this.refreshDeadlineMissed(run)) return;\n\t\tconst decision = this.evaluate(run);\n\t\tconst { warmCost, missCost, continuationProbability } = decision;\n\t\tlet action = decision.action;\n\t\ttry {\n\t\t\taction = await this.decide({\n\t\t\t\ttype: \"cache_warming_decision\",\n\t\t\t\twarmCost,\n\t\t\t\tmissCost,\n\t\t\t\tcontinuationProbability,\n\t\t\t\taction,\n\t\t\t});\n\t\t} catch {\n\t\t\t// Extension failures fall back to pi's own decision.\n\t\t}\n\t\tif (!this.validateRun(run) || this.refreshDeadlineMissed(run)) return;\n\t\tconst extensionOverride = action !== decision.action;\n\t\tif (action === \"stop\") {\n\t\t\tconst reason = extensionOverride\n\t\t\t\t? \"stopped by extension\"\n\t\t\t\t: decision.economicsAvailable\n\t\t\t\t\t? \"expected savings below threshold\"\n\t\t\t\t\t: \"cache economics unavailable\";\n\t\t\tthis.stop(reason, { decision, extensionOverride });\n\t\t\treturn;\n\t\t}\n\n\t\trun.extensionOverride = extensionOverride;\n\t\ttry {\n\t\t\tconst message = await this.models\n\t\t\t\t.streamSimple(run.model, run.context, {\n\t\t\t\t\t...run.options,\n\t\t\t\t\tmaxTokens: 1,\n\t\t\t\t\tmaxRetries: 0,\n\t\t\t\t\tsignal: run.controller.signal,\n\t\t\t\t})\n\t\t\t\t.result();\n\t\t\tif (!this.validateRun(run)) return;\n\t\t\tif (message.stopReason !== \"error\" && message.stopReason !== \"aborted\") {\n\t\t\t\tconst entry = this.sessionManager.appendUsage(\n\t\t\t\t\t\"cache_warm\",\n\t\t\t\t\tmessage.provider,\n\t\t\t\t\tmessage.responseModel ?? message.model,\n\t\t\t\t\tmessage.usage,\n\t\t\t\t\textensionOverride ? \"extension override\" : undefined,\n\t\t\t\t);\n\t\t\t\tthis.onWarmed?.(entry);\n\t\t\t}\n\t\t} catch {\n\t\t\t// Cache warming is best-effort and must not affect the active agent run.\n\t\t}\n\t\tif (this.run === run) this.schedule(run);\n\t}\n\n\tprivate refreshDeadlineMissed(run: ActiveRun): boolean {\n\t\tif (Date.now() <= run.refreshDeadlineAt) return false;\n\t\tthis.stop(\"cache refresh deadline missed\");\n\t\treturn true;\n\t}\n\n\tprivate validateRun(run: ActiveRun): boolean {\n\t\tif (this.run !== run) return false;\n\t\tconst reason = this.getModeStopReason(run) ?? (!run.isCurrent() ? \"conversation context changed\" : undefined);\n\t\tif (!reason) return true;\n\t\tthis.stop(reason);\n\t\treturn false;\n\t}\n\n\tprivate getModeStopReason(run: ActiveRun): string | undefined {\n\t\tconst mode = this.getMode();\n\t\tif (mode === \"off\") return \"cache warming disabled\";\n\t\tif (mode === \"streaming\" && run.phase === \"idle\") return \"agent run settled\";\n\t\treturn undefined;\n\t}\n\n\tprivate evaluate(run: ActiveRun): CacheWarmingDecision {\n\t\tconst model = run.model;\n\t\tconst promptTokens = lastPromptTokens(this.sessionManager.getBranch());\n\t\tconst cacheHitCost = price(model, { cacheRead: promptTokens });\n\t\tconst cacheMissCost = price(\n\t\t\tmodel,\n\t\t\tmodel.cost.cacheWrite > 0 ? { cacheWrite: promptTokens } : { input: promptTokens },\n\t\t);\n\t\tconst warmCost = price(model, { cacheRead: promptTokens, output: 1 });\n\t\tconst missCost = Math.max(0, cacheMissCost - cacheHitCost);\n\t\tconst continuationProbability = run.phase === \"idle\" ? IDLE_CONTINUATION_PROBABILITY : 1;\n\t\tconst economicsAvailable = promptTokens > 0 && (cacheHitCost > 0 || cacheMissCost > 0);\n\t\tconst expectedSavings = continuationProbability * missCost - warmCost;\n\t\treturn {\n\t\t\tphase: run.phase,\n\t\t\twarmCost,\n\t\t\tmissCost,\n\t\t\tcontinuationProbability,\n\t\t\texpectedSavings,\n\t\t\teconomicsAvailable,\n\t\t\taction: expectedSavings >= CACHE_WARMING_MINIMUM_EXPECTED_SAVINGS ? \"warm\" : \"stop\",\n\t\t};\n\t}\n}\n\nfunction formatDollars(value: number): string {\n\treturn value < 0 ? `-$${Math.abs(value).toFixed(3)}` : `$${value.toFixed(3)}`;\n}\n\nfunction formatCacheWarmingEconomics(decision: CacheWarmingDecision): string {\n\tif (!decision.economicsAvailable) return \"cache economics unavailable\";\n\tconst probability = Math.round(decision.continuationProbability * 100);\n\tconst probabilityText =\n\t\tdecision.phase === \"streaming\"\n\t\t\t? `${probability}% continuation probability while agent is running`\n\t\t\t: `${probability}% continuation probability`;\n\tconst comparison = decision.action === \"warm\" ? \">=\" : \"<\";\n\treturn `${probabilityText}, expected savings ${formatDollars(decision.expectedSavings)} ${comparison} $${CACHE_WARMING_MINIMUM_EXPECTED_SAVINGS.toFixed(3)}`;\n}\n\nfunction formatCacheWarmingDecisionTime(nextWarmAt: number | undefined, now: number): string {\n\tif (nextWarmAt === undefined || nextWarmAt <= now) return \"Decision now\";\n\tlet remainingSeconds = Math.ceil((nextWarmAt - now) / 1000);\n\tconst hours = Math.floor(remainingSeconds / 3600);\n\tremainingSeconds %= 3600;\n\tconst minutes = Math.floor(remainingSeconds / 60);\n\tconst seconds = remainingSeconds % 60;\n\tconst parts: string[] = [];\n\tif (hours > 0) parts.push(`${hours}h`);\n\tif (minutes > 0) parts.push(`${minutes}m`);\n\tif (seconds > 0 || parts.length === 0) parts.push(`${seconds}s`);\n\treturn `Decision in ${parts.join(\" \")}`;\n}\n\n/** One-line status for `/session`. */\nexport function formatCacheWarmingStatus(status: CacheWarmingStatus, now = Date.now()): string {\n\tconst decision = status.decision;\n\t// A decision is attached once pi (or an extension) acted on it; \"inactive\"\n\t// without one never got that far.\n\tif (!decision || (status.state === \"inactive\" && !decision.economicsAvailable && !status.extensionOverride)) {\n\t\treturn `Inactive (${status.reason ?? \"unknown reason\"})`;\n\t}\n\tconst details = status.extensionOverride\n\t\t? `extension override, ${formatCacheWarmingEconomics(decision)}`\n\t\t: `${formatCacheWarmingEconomics(decision)} -> ${decision.action}`;\n\tif (status.state === \"inactive\") return `Stopped (${details})`;\n\tif (status.state === \"refreshing\") return `Warming cache (${details})`;\n\treturn `${formatCacheWarmingDecisionTime(status.nextWarmAt, now)} (${details})`;\n}\n\n/** One-line transcript text for persisted cache-warming usage. */\nexport function formatCacheWarmingUsage(entry: UsageEntry): string {\n\tconst note = entry.note ? ` (${entry.note})` : \"\";\n\tconst cost = entry.usage.cost.total.toFixed(6).replace(/(\\.\\d{3}\\d*?)0+$/, \"$1\");\n\treturn `Cache warmed${note}: $${cost}`;\n}\n"]}