@selesai/code 0.13.26 → 0.13.27

package/dist/core/bug-report-upload.d.ts

@@ -0,0 +1,11 @@
+import type { BugReportBundle } from "./bug-report.ts";
+interface UploadBugReportOptions {
+    token?: string;
+    signal?: AbortSignal;
+    gatewayUrl?: string;
+}
+/** Upload a report as multipart form data, anonymously or attributed to a Radius account. */
+export declare function uploadBugReport(bundle: BugReportBundle, options?: UploadBugReportOptions): Promise<{
+    id: string;
+}>;
+export {};

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

@@ -0,0 +1,21 @@
+import { bugReportFiles } from "./bug-report.js";
+import { getRadiusGatewayUrl } from "./radius.js";
+/** Upload a report as multipart form data, anonymously or attributed to a Radius account. */
+export async function uploadBugReport(bundle, options = {}) {
+    const body = new FormData();
+    for (const file of bugReportFiles(bundle)) {
+        body.append(file.name, new Blob([file.data], { type: file.contentType }), file.name);
+    }
+    const response = await fetch(new URL("/v1/bug-reports", options.gatewayUrl ?? getRadiusGatewayUrl()), {
+        method: "POST",
+        headers: options.token ? { Authorization: `Bearer ${options.token}` } : undefined,
+        body,
+        signal: options.signal,
+    });
+    const json = (await response.json().catch(() => null));
+    if (response.ok && json?.ok === true && typeof json.bug_report?.id === "string") {
+        return { id: json.bug_report.id };
+    }
+    const detail = json && !json.ok ? json.description || json.error : undefined;
+    throw new Error(`Bug report upload failed: ${detail || response.statusText || response.status}`);
+}

package/dist/core/bug-report.d.ts

@@ -0,0 +1,175 @@
+import type { AgentMessage, StreamFn, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { type RetryPolicy } from "@earendil-works/pi-ai";
+import type { Api, Model } from "@earendil-works/pi-ai/compat";
+import type { CrashRecord } from "./crash-log.ts";
+import type { Extension } from "./extensions/types.ts";
+import type { ModelRuntime } from "./model-runtime.ts";
+import type { ReadonlySessionManager } from "./session-manager.ts";
+import type { Settings } from "./settings-manager.ts";
+export declare const BUG_REPORT_CUSTOM_ENTRY_TYPE = "pi.bug-report";
+/** Strip credentials and secret-looking query parameters from a URL. */
+export declare function redactUrl(value: string): string;
+/** Copy a JSON value while removing values that may contain credentials. */
+export declare function redactJsonValue(value: unknown): unknown;
+interface CollectBugReportMetadataOptions {
+    id?: string;
+    hint?: string;
+    sessionId: string;
+    cwd: string;
+    includeSession: boolean;
+    includeSummary: boolean;
+    messageCount: number;
+    model?: Model<Api>;
+    modelRuntime: ModelRuntime;
+    thinkingLevel: ThinkingLevel;
+    extensions: readonly Extension[];
+    extensionErrors: ReadonlyArray<{
+        path: string;
+        error: string;
+    }>;
+    globalSettings: Settings;
+    projectSettings: Settings;
+}
+export declare function collectBugReportMetadata(options: CollectBugReportMetadataOptions): {
+    schemaVersion: number;
+    id: string;
+    createdAt: string;
+    hint: string | null;
+    environment: {
+        version: string;
+        userAgent: string;
+        runtime: string;
+        platform: NodeJS.Platform;
+        arch: NodeJS.Architecture;
+        osRelease: string;
+        osVersion: string;
+        shell: string | null;
+        terminal: {
+            term: string | null;
+            program: string | null;
+            programVersion: string | null;
+            colorterm: string | null;
+            tmux: boolean;
+            ssh: boolean;
+            ci: boolean;
+        };
+        piEnvironmentVariables: string[];
+    };
+    session: {
+        id: string;
+        included: boolean;
+        summaryIncluded: boolean;
+        messageCount: number;
+        cwd?: string | undefined;
+    };
+    model: {
+        provider: string;
+        id: string;
+        name: string;
+        api: Api;
+        baseUrl: string;
+        reasoning: boolean;
+        input: ("image" | "text")[];
+        contextWindow: number;
+        maxTokens: number;
+        samplingParams: unknown;
+        compat: unknown;
+        thinkingLevelMap: Partial<Record<import("@earendil-works/pi-ai").ModelThinkingLevel, string | null>> | null;
+        headerNames: string[];
+    } | null;
+    provider: {
+        id: string;
+        name: string;
+        baseUrl: string | null;
+        headerNames: string[];
+        authTypes: ("api_key" | "oauth")[];
+        authStatus: import("./provider-composer.ts").AuthStatus;
+        usingOAuth: boolean;
+        registeredByExtension: boolean;
+    } | null;
+    thinkingLevel: ThinkingLevel;
+    extensions: {
+        path: string;
+        source: string;
+        scope: import("./source-info.ts").SourceScope;
+        origin: import("./source-info.ts").SourceOrigin;
+        hidden: boolean;
+    }[];
+    extensionErrors: {
+        path: string;
+        error: string;
+    }[];
+    settings: {
+        global: Settings;
+        project: Settings;
+    };
+};
+/** Collect failed assistant turns without collecting conversation content. */
+export declare function collectBugReportDiagnostics(sessionManager: ReadonlySessionManager, crashes?: readonly CrashRecord[]): {
+    schemaVersion: number;
+    sessionId: string;
+    entryCount: number;
+    assistantMessageCount: number;
+    assistant: {
+        entryId: string;
+        timestamp: string;
+        provider: string;
+        model: string;
+        api: Api;
+        stopReason: import("@earendil-works/pi-ai").StopReason;
+        rawStopReason?: string | undefined;
+        errorMessage?: string | undefined;
+        diagnostics: import("@earendil-works/pi-ai").AssistantMessageDiagnostic[];
+    }[];
+    crashes: {
+        timestamp: string;
+        version: string;
+        kind: "fatal_error" | "uncaught_exception";
+        message: string;
+        stack: string | null;
+        sessionFile: string | null;
+        cwd: string;
+    }[];
+};
+export type BugReportMetadata = ReturnType<typeof collectBugReportMetadata>;
+export type BugReportDiagnostics = ReturnType<typeof collectBugReportDiagnostics>;
+export interface BugReportBundle {
+    metadata: BugReportMetadata;
+    diagnostics: BugReportDiagnostics;
+    sessionJsonl?: string;
+    summary?: string;
+}
+export interface BugReportSessionEntryData {
+    id: string;
+    createdAt: string;
+    hint: string | null;
+    sessionIncluded: boolean;
+    summaryIncluded: boolean;
+    delivery: "zip" | "upload";
+    path?: string;
+}
+interface BugReportFile {
+    name: string;
+    contentType: string;
+    data: string;
+}
+/** Files shared by upload and zip export. */
+export declare function bugReportFiles(bundle: BugReportBundle): BugReportFile[];
+export declare function writeBugReportArchive(bundle: BugReportBundle, filePath: string): Promise<void>;
+export declare function bugReportArchiveFileName(id: string): string;
+interface GenerateBugReportSummaryOptions {
+    messages: readonly AgentMessage[];
+    hint?: string;
+    model: Model<Api>;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    env?: Record<string, string>;
+    signal: AbortSignal;
+    thinkingLevel?: ThinkingLevel;
+    streamFn?: StreamFn;
+    retry?: RetryPolicy;
+    sessionId?: string;
+}
+/** Ask the session model for a report when the user does not share the transcript. */
+export declare function generateBugReportSummary(options: GenerateBugReportSummaryOptions): Promise<string>;
+export {};

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 { getPiUserAgent } from "../utils/pi-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 = "pi.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) {
+    const { trackingId: _trackingId, ...rest } = settings;
+    return redactJsonValue(rest);
+}
+function collectEnvironment() {
+    const env = (name) => process.env[name] || null;
+    return {
+        version: VERSION,
+        userAgent: getPiUserAgent(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.
+        piEnvironmentVariables: Object.keys(process.env)
+            .filter((name) => name.startsWith("PI_"))
+            .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 shared by upload and zip export. */
+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 `pi-bug-report-${id}.zip`;
+}
+const BUG_SUMMARY_SYSTEM_PROMPT = `You are helping a user file a bug report about pi, the coding agent they are talking to. You will be shown the conversation transcript. Write a report for the pi 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;
+}

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-warmer.d.ts

@@ -0,0 +1,101 @@
+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 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;