@selesai/code 0.13.26 → 0.13.27

package/dist/core/model-config.js

@@ -86,7 +86,6 @@ const OpenAICompletionsCompatSchema = Type.Object({
     supportsOpenAIGrammarTools: Type.Optional(Type.Boolean()),
     supportsStrictMode: Type.Optional(Type.Boolean()),
     sendSessionAffinityHeaders: Type.Optional(Type.Boolean()),
-    deferredToolsMode: Type.Optional(Type.Literal("kimi")),
     sessionAffinityFormat: Type.Optional(Type.Union([Type.Literal("openai"), Type.Literal("openai-nosession"), Type.Literal("openrouter")])),
     supportsLongCacheRetention: Type.Optional(Type.Boolean()),
     vllmPriority: Type.Optional(Type.Number()),
@@ -97,10 +96,26 @@ const OpenAIResponsesCompatSchema = Type.Object({
     supportsLongCacheRetention: Type.Optional(Type.Boolean()),
     supportsStrictMode: Type.Optional(Type.Boolean()),
     supportsOpenAIGrammarTools: Type.Optional(Type.Boolean()),
-    supportsAdditionalTools: Type.Optional(Type.Boolean()),
-    supportsToolSearch: Type.Optional(Type.Boolean()),
     supportsMaxOutputTokens: Type.Optional(Type.Boolean()),
 });
+const ModelCostRatesSchema = {
+    input: Type.Number(),
+    output: Type.Number(),
+    cacheRead: Type.Number(),
+    cacheWrite: Type.Number(),
+};
+const ModelCostTierSchema = Type.Object({
+    inputTokensAbove: Type.Number(),
+    ...ModelCostRatesSchema,
+});
+const ModelCostSchema = Type.Object({
+    ...ModelCostRatesSchema,
+    tiers: Type.Optional(Type.Array(ModelCostTierSchema)),
+});
+const ModelPromptCacheSchema = Type.Object({
+    short: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
+    long: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
+});
 const AnthropicMessagesCompatSchema = Type.Object({
     supportsEagerToolInputStreaming: Type.Optional(Type.Boolean()),
     supportsLongCacheRetention: Type.Optional(Type.Boolean()),
@@ -111,27 +126,17 @@ const AnthropicMessagesCompatSchema = Type.Object({
     allowEmptySignature: Type.Optional(Type.Boolean()),
     supportsStrictTools: Type.Optional(Type.Boolean()),
     supportsMidConvoEffort: Type.Optional(Type.Boolean()),
-    supportsToolReferences: Type.Optional(Type.Boolean()),
+    allowedFallbackModels: Type.Optional(Type.Array(Type.Object({
+        provider: Type.String({ minLength: 1 }),
+        model: Type.String({ minLength: 1 }),
+        cost: ModelCostSchema,
+    }), { maxItems: 3 })),
 });
 const ProviderCompatSchema = Type.Union([
     OpenAICompletionsCompatSchema,
     OpenAIResponsesCompatSchema,
     AnthropicMessagesCompatSchema,
 ]);
-const ModelCostRatesSchema = {
-    input: Type.Number(),
-    output: Type.Number(),
-    cacheRead: Type.Number(),
-    cacheWrite: Type.Number(),
-};
-const ModelCostTierSchema = Type.Object({
-    inputTokensAbove: Type.Number(),
-    ...ModelCostRatesSchema,
-});
-const ModelCostSchema = Type.Object({
-    ...ModelCostRatesSchema,
-    tiers: Type.Optional(Type.Array(ModelCostTierSchema)),
-});
 const ModelDefinitionSchema = Type.Object({
     id: Type.String({ minLength: 1 }),
     name: Type.Optional(Type.String({ minLength: 1 })),
@@ -141,6 +146,7 @@ const ModelDefinitionSchema = Type.Object({
     thinkingLevelMap: Type.Optional(ThinkingLevelMapSchema),
     input: Type.Optional(Type.Array(Type.Union([Type.Literal("text"), Type.Literal("image")]))),
     cost: Type.Optional(ModelCostSchema),
+    promptCache: Type.Optional(ModelPromptCacheSchema),
     contextWindow: Type.Optional(Type.Number()),
     maxTokens: Type.Optional(Type.Number()),
     headers: Type.Optional(Type.Record(Type.String(), Type.String())),
@@ -158,6 +164,7 @@ const ModelOverrideSchema = Type.Object({
         cacheWrite: Type.Optional(Type.Number()),
         tiers: Type.Optional(Type.Array(ModelCostTierSchema)),
     })),
+    promptCache: Type.Optional(ModelPromptCacheSchema),
     contextWindow: Type.Optional(Type.Number()),
     maxTokens: Type.Optional(Type.Number()),
     headers: Type.Optional(Type.Record(Type.String(), Type.String())),

package/dist/core/model-resolver.js

@@ -14,7 +14,7 @@ export const defaultModelPerProvider = {
     openai: "gpt-5.5",
     "azure-openai-responses": "gpt-5.4",
     "openai-codex": "gpt-5.5",
-    radius: "auto",
+    radius: "balanced",
     nvidia: "nvidia/nemotron-3-super-120b-a12b",
     deepseek: "deepseek-v4-pro",
     google: "gemini-3.1-pro-preview",
@@ -39,6 +39,7 @@ export const defaultModelPerProvider = {
     opencode: "kimi-k2.6",
     "opencode-go": "kimi-k2.6",
     "kimi-coding": "kimi-for-coding",
+    meta: "muse-spark-1.3",
     "cloudflare-workers-ai": "@cf/moonshotai/kimi-k2.6",
     "cloudflare-ai-gateway": "workers-ai/@cf/moonshotai/kimi-k2.6",
     "qwen-token-plan": "qwen3.7-max",

package/dist/core/model-runtime.js

@@ -1,5 +1,5 @@
 import { dirname, join } from "node:path";
-import { createModels, lazyStream, ModelsError, } from "@earendil-works/pi-ai";
+import { createModels, lazyStream, ModelsError, normalizeContext, } from "@earendil-works/pi-ai";
 import * as builtinProviderCatalog from "@earendil-works/pi-ai/providers/all";
 import { getAgentDir, getBundledDefaultsDir } from "../config.js";
 import { AuthStorage as DefaultAuthStorage } from "./auth-storage.js";
@@ -340,18 +340,20 @@ export class ModelRuntime {
         };
     }
     stream(model, context, options) {
+        const transcript = normalizeContext(context);
         return lazyStream(model, async () => {
             const prepared = await this.prepareRequest(model, options);
-            return prepared.provider.stream(prepared.model, context, prepared.options);
+            return prepared.provider.stream(prepared.model, transcript, prepared.options);
         });
     }
     complete(model, context, options) {
         return this.stream(model, context, options).result();
     }
     streamSimple(model, context, options) {
+        const transcript = normalizeContext(context);
         return lazyStream(model, async () => {
             const prepared = await this.prepareRequest(model, options);
-            return prepared.provider.streamSimple(prepared.model, context, prepared.options);
+            return prepared.provider.streamSimple(prepared.model, transcript, prepared.options);
         });
     }
     completeSimple(model, context, options) {

package/dist/core/provider-composer.d.ts

@@ -1,4 +1,4 @@
-import { type Api, type AssistantMessageEventStream, type Context, type Model, type OAuthCredentials, type OAuthLoginCallbacks, type Provider, type ProviderHeaders, type RefreshModelsContext, type SimpleStreamOptions } from "@earendil-works/pi-ai";
+import { type Api, type AssistantMessageEventStream, type Model, type OAuthCredentials, type OAuthLoginCallbacks, type Provider, type ProviderHeaders, type RefreshModelsContext, type SimpleStreamOptions, type TranscriptContext } from "@earendil-works/pi-ai";
 import type { ModelConfig, ModelsJsonProvider } from "./model-config.ts";
 import { clearConfigValueCache } from "./resolve-config-value.ts";
 export interface ExtensionOAuthConfig {
@@ -16,7 +16,12 @@ export interface ProviderConfigInput {
     baseUrl?: string;
     apiKey?: string;
     api?: Api;
-    streamSimple?: (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+    /**
+     * Declarative custom-provider streaming handler. The context is a normalized transcript:
+     * read the prompt and tools from its system messages. Invoke `options.onPayload` before
+     * sending and `options.onResponse` after receiving the response.
+     */
+    streamSimple?: (model: Model<Api>, context: TranscriptContext, options?: SimpleStreamOptions) => AssistantMessageEventStream;
     headers?: Record<string, string>;
     authHeader?: boolean;
     oauth?: ExtensionOAuthConfig;

package/dist/core/provider-composer.js

@@ -1,4 +1,5 @@
 import { lazyStream, } from "@earendil-works/pi-ai";
+import { normalizeContext } from "@earendil-works/pi-ai/utils/transcript";
 import { getApiProvider } from "@earendil-works/pi-ai/compat";
 import { clearConfigValueCache, getConfigValueEnvVarNames, isCommandConfigValue, isConfigValueConfigured, resolveConfigValueOrThrow, resolveHeadersOrThrow, } from "./resolve-config-value.js";
 export const clearApiKeyCache = clearConfigValueCache;
@@ -321,20 +322,24 @@ export function composeModelProvider(providerId, base, modelConfig, extension) {
         throw new Error(`Provider ${providerId}: no authentication method configured.`);
     const supportsBaseApi = (model) => base?.getModels().some((entry) => entry.api === model.api) ?? false;
     const streamWith = (model, context, options, simple) => lazyStream(model, async () => {
+        // Provider boundary: the platform's streaming entry points hand providers a
+        // branded TranscriptContext. Lift the ordinary request context here, where the
+        // fork forwards into a platform adapter.
+        const transcript = normalizeContext(context);
         if (extension?.streamSimple && model.api === extension.api) {
-            return extension.streamSimple(model, context, options);
+            return extension.streamSimple(model, transcript, options);
         }
         if (base && supportsBaseApi(model)) {
             return simple
-                ? base.streamSimple(model, context, options)
-                : base.stream(model, context, options);
+                ? base.streamSimple(model, transcript, options)
+                : base.stream(model, transcript, options);
         }
         const api = getApiProvider(model.api);
         if (!api)
             throw new Error(`No API provider registered for api: ${model.api}`);
         return simple
-            ? api.streamSimple(model, context, options)
-            : api.stream(model, context, options);
+            ? api.streamSimple(model, transcript, options)
+            : api.stream(model, transcript, options);
     });
     return {
         id: providerId,

package/dist/core/radius.d.ts

@@ -1 +1,4 @@
 export declare const RADIUS_PROVIDER_ID = "radius";
+export declare const ENV_RADIUS_GATEWAY = "PI_RADIUS_GATEWAY";
+/** Radius gateway origin, honoring the `PI_RADIUS_GATEWAY` override. */
+export declare function getRadiusGatewayUrl(): string;

package/dist/core/radius.js

@@ -1 +1,7 @@
+import { DEFAULT_RADIUS_GATEWAY, normalizeRadiusGatewayUrl } from "@earendil-works/pi-ai/providers/radius-config";
 export const RADIUS_PROVIDER_ID = "radius";
+export const ENV_RADIUS_GATEWAY = "PI_RADIUS_GATEWAY";
+/** Radius gateway origin, honoring the `PI_RADIUS_GATEWAY` override. */
+export function getRadiusGatewayUrl() {
+    return normalizeRadiusGatewayUrl(process.env[ENV_RADIUS_GATEWAY] ?? DEFAULT_RADIUS_GATEWAY);
+}

package/dist/core/sdk.js

@@ -5,6 +5,7 @@ import { getAgentDir } from "../config.js";
 import { resolvePath } from "../utils/paths.js";
 import { AgentSession } from "./agent-session.js";
 import { formatNoModelsAvailableMessage } from "./auth-guidance.js";
+import { CacheWarmer } from "./cache-warmer.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
 import { convertToLlm } from "./messages.js";
 import { findInitialModel } from "./model-resolver.js";
@@ -179,6 +180,53 @@ export async function createAgentSession(options = {}) {
         });
     };
     const extensionRunnerRef = {};
+    const cacheWarmer = new CacheWarmer(modelRuntime, sessionManager, () => settingsManager.getCacheWarmingMode(), async (event) => extensionRunnerRef.current?.emitCacheWarmingDecision(event) ?? event.action);
+    const buildRequestOptions = (requestModel, options = {}) => {
+        const providerRetrySettings = settingsManager.getProviderRetrySettings();
+        const httpIdleTimeoutMs = settingsManager.getHttpIdleTimeoutMs();
+        const effectiveTimeoutMs = httpIdleTimeoutMs === 0 ? 2147483647 : httpIdleTimeoutMs;
+        const headerRunner = extensionRunnerRef.current;
+        return {
+            ...options,
+            timeoutMs: options.timeoutMs ?? providerRetrySettings.timeoutMs ?? effectiveTimeoutMs,
+            websocketConnectTimeoutMs: options.websocketConnectTimeoutMs ?? settingsManager.getWebSocketConnectTimeoutMs(),
+            maxRetries: options.maxRetries ?? providerRetrySettings.maxRetries,
+            maxRetryDelayMs: options.maxRetryDelayMs ?? providerRetrySettings.maxRetryDelayMs,
+            transformHeaders: async (requestHeaders) => {
+                const headers = mergeProviderAttributionHeaders(requestModel, settingsManager, options.sessionId, requestHeaders);
+                return headerRunner?.hasHandlers("before_provider_headers")
+                    ? headerRunner.emitBeforeProviderHeaders(headers ?? {})
+                    : (headers ?? {});
+            },
+        };
+    };
+    const cacheContextIsCurrent = (requestModel) => {
+        const messages = agent.state.messages;
+        return () => {
+            const currentModel = agent.state.model;
+            const currentMessages = agent.state.messages;
+            return (currentModel.provider === requestModel.provider &&
+                currentModel.id === requestModel.id &&
+                messages.length <= currentMessages.length &&
+                messages.every((message, index) => currentMessages[index] === message));
+        };
+    };
+    const transformProviderPayload = async (payload) => {
+        const runner = extensionRunnerRef.current;
+        if (!runner?.hasHandlers("before_provider_request"))
+            return payload;
+        return runner.emitBeforeProviderRequest(payload);
+    };
+    const handleProviderResponse = async (response) => {
+        const runner = extensionRunnerRef.current;
+        if (!runner?.hasHandlers("after_provider_response"))
+            return;
+        await runner.emit({
+            type: "after_provider_response",
+            status: response.status,
+            headers: response.headers,
+        });
+    };
     agent = new Agent({
         initialState: {
             systemPrompt: "",
@@ -188,46 +236,19 @@ export async function createAgentSession(options = {}) {
         },
         convertToLlm: convertToLlmWithBlockImages,
         streamFn: async (model, context, options) => {
-            const providerRetrySettings = settingsManager.getProviderRetrySettings();
-            const httpIdleTimeoutMs = settingsManager.getHttpIdleTimeoutMs();
-            // SDKs treat timeout=0 as 0ms (immediate timeout), not "no timeout".
-            // Use max int32 to effectively disable the timeout.
-            const effectiveTimeoutMs = httpIdleTimeoutMs === 0 ? 2147483647 : httpIdleTimeoutMs;
-            const timeoutMs = options?.timeoutMs ?? providerRetrySettings.timeoutMs ?? effectiveTimeoutMs;
-            const websocketConnectTimeoutMs = options?.websocketConnectTimeoutMs ?? settingsManager.getWebSocketConnectTimeoutMs();
-            const headerRunner = extensionRunnerRef.current;
-            return modelRuntime.streamSimple(model, context, {
-                ...options,
-                timeoutMs,
-                websocketConnectTimeoutMs,
-                maxRetries: options?.maxRetries ?? providerRetrySettings.maxRetries,
-                maxRetryDelayMs: options?.maxRetryDelayMs ?? providerRetrySettings.maxRetryDelayMs,
-                transformHeaders: async (requestHeaders) => {
-                    const headers = mergeProviderAttributionHeaders(model, settingsManager, options?.sessionId, requestHeaders);
-                    return headerRunner?.hasHandlers("before_provider_headers")
-                        ? headerRunner.emitBeforeProviderHeaders(headers ?? {})
-                        : (headers ?? {});
-                },
-            });
-        },
-        onPayload: async (payload, _model) => {
-            const runner = extensionRunnerRef.current;
-            if (!runner?.hasHandlers("before_provider_request")) {
-                return payload;
-            }
-            return runner.emitBeforeProviderRequest(payload);
-        },
-        onResponse: async (response, _model) => {
-            const runner = extensionRunnerRef.current;
-            if (!runner?.hasHandlers("after_provider_response")) {
-                return;
+            const requestOptions = buildRequestOptions(model, options);
+            // Compaction and summaries use their own routing ids; only session requests
+            // replace the cache entry, so warming restarts from them. Keep warming while
+            // the current transcript still extends the request's prefix. Agent state may
+            // shallow-copy the messages array or refresh the model object without changing
+            // the provider request, so top-level object identity is not a valid cache key.
+            if (options?.sessionId === sessionManager.getSessionId()) {
+                cacheWarmer.start({ model, context, options: requestOptions }, cacheContextIsCurrent(model));
             }
-            await runner.emit({
-                type: "after_provider_response",
-                status: response.status,
-                headers: response.headers,
-            });
+            return modelRuntime.streamSimple(model, context, requestOptions);
         },
+        onPayload: transformProviderPayload,
+        onResponse: handleProviderResponse,
         sessionId: sessionManager.getSessionId(),
         transformContext: async (messages) => {
             const runner = extensionRunnerRef.current;
@@ -264,6 +285,7 @@ export async function createAgentSession(options = {}) {
         resourceLoader,
         customTools: options.customTools,
         modelRuntime,
+        cacheWarmer,
         initialActiveToolNames,
         allowedToolNames,
         excludedToolNames,

package/dist/core/session-export.d.ts

@@ -1,3 +1,7 @@
 import { type SessionManager } from "./session-manager.ts";
-/** Write the current session branch and optional trailing export-only entries as JSONL. */
-export declare function exportSessionToJsonl(sessionManager: SessionManager, outputPath?: string, createTrailingEntries?: (parentId: string | null, timestamp: string) => readonly object[]): string;
+type TrailingEntries = (parentId: string | null, timestamp: string) => readonly object[];
+/** Serialize the current branch and optional export-only entries as JSONL. */
+export declare function serializeSessionBranch(sessionManager: SessionManager, createTrailingEntries?: TrailingEntries): string;
+/** Write the current session branch and optional export-only entries as JSONL. */
+export declare function exportSessionToJsonl(sessionManager: SessionManager, outputPath?: string, createTrailingEntries?: TrailingEntries): string;
+export {};

package/dist/core/session-export.js

@@ -2,13 +2,8 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { resolvePath } from "../utils/paths.js";
 import { CURRENT_SESSION_VERSION } from "./session-manager.js";
-/** Write the current session branch and optional trailing export-only entries as JSONL. */
-export function exportSessionToJsonl(sessionManager, outputPath, createTrailingEntries) {
-    const filePath = resolvePath(outputPath ?? `session-${new Date().toISOString().replace(/[:.]/g, "-")}.jsonl`, process.cwd());
-    const dir = dirname(filePath);
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
-    }
+/** Serialize the current branch and optional export-only entries as JSONL. */
+export function serializeSessionBranch(sessionManager, createTrailingEntries) {
     const timestamp = new Date().toISOString();
     const header = {
         type: "session",
@@ -17,15 +12,21 @@ export function exportSessionToJsonl(sessionManager, outputPath, createTrailingE
         timestamp,
         cwd: sessionManager.getCwd(),
     };
-    const lines = [JSON.stringify(header)];
+    const entries = [header];
     let parentId = null;
     for (const entry of sessionManager.getBranch()) {
-        lines.push(JSON.stringify({ ...entry, parentId }));
+        entries.push({ ...entry, parentId });
         parentId = entry.id;
     }
-    for (const entry of createTrailingEntries?.(parentId, timestamp) ?? []) {
-        lines.push(JSON.stringify(entry));
-    }
-    writeFileSync(filePath, `${lines.join("\n")}\n`);
+    entries.push(...(createTrailingEntries?.(parentId, timestamp) ?? []));
+    return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
+}
+/** Write the current session branch and optional export-only entries as JSONL. */
+export function exportSessionToJsonl(sessionManager, outputPath, createTrailingEntries) {
+    const filePath = resolvePath(outputPath ?? `session-${new Date().toISOString().replace(/[:.]/g, "-")}.jsonl`, process.cwd());
+    const dir = dirname(filePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(filePath, serializeSessionBranch(sessionManager, createTrailingEntries));
     return filePath;
 }

package/dist/core/session-format.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/session-format.test.js

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import { buildContextEntries, buildSessionContext, sessionEntryToContextMessages, } from "./session-manager.js";
+const base = (id, parentId) => ({
+    id,
+    parentId,
+    timestamp: "2026-01-01T00:00:00.000Z",
+});
+const user = (id, parentId, text) => ({
+    ...base(id, parentId),
+    type: "message",
+    message: { role: "user", content: [{ type: "text", text }], timestamp: 1 },
+});
+const system = (id, parentId, content, sections) => ({
+    ...base(id, parentId),
+    type: "message",
+    // Session files are parsed without validation; a null content is the readable-old-entry case.
+    message: { role: "system", content: content, sections, timestamp: 1 },
+});
+const usage = (id, parentId) => ({
+    ...base(id, parentId),
+    type: "usage",
+    kind: "cache_warm",
+    provider: "provider",
+    model: "model",
+    usage: {
+        input: 1,
+        output: 1,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 2,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+});
+const compaction = (id, parentId, withSystem) => ({
+    ...base(id, parentId),
+    type: "compaction",
+    summary: "summary text",
+    firstKeptEntryId: "",
+    tokensBefore: 100,
+    ...(withSystem
+        ? { systemMessage: { role: "system", content: "prompt state", sections: { rules: "<rules>r</rules>" }, timestamp: 1 } }
+        : {}),
+});
+describe("session entries to rebuilt context", () => {
+    it("tolerates a system entry whose content is absent", () => {
+        expect(sessionEntryToContextMessages(system("s1", null, null))).toEqual([
+            { role: "system", content: "", sections: undefined, timestamp: 1 },
+        ]);
+    });
+    it("keeps a system entry's sections so a resumed session restores its prompt state", () => {
+        const [message] = sessionEntryToContextMessages(system("s1", null, "base", { rules: "<rules>x</rules>" }));
+        expect(message.role).toBe("system");
+        expect(message.sections).toEqual({ rules: "<rules>x</rules>" });
+    });
+    it("does not contribute a usage entry to the message sequence", () => {
+        expect(sessionEntryToContextMessages(usage("u1", null))).toEqual([]);
+    });
+    it("replays a compaction boundary's system message before its summary", () => {
+        const messages = sessionEntryToContextMessages(compaction("c1", null, true));
+        expect(messages.map((m) => m.role)).toEqual(["system", "compactionSummary"]);
+    });
+    it("replays only the summary for a compaction boundary without prompt state", () => {
+        const messages = sessionEntryToContextMessages(compaction("c2", null, false));
+        expect(messages.map((m) => m.role)).toEqual(["compactionSummary"]);
+    });
+    it("rebuilds resume, branch navigation and backward tolerance in one sequence", () => {
+        const entries = [
+            user("m1", null, "first"),
+            system("s1", "m1", "instructions"),
+            usage("u1", "s1"),
+            system("s2", "u1", null),
+            compaction("c1", "s2", true),
+            user("m2", "c1", "second"),
+        ];
+        const byId = new Map(entries.map((entry) => [entry.id, entry]));
+        const context = buildSessionContext(entries, "m2", byId);
+        const roles = context.messages.map((message) => message.role);
+        // The compaction boundary replaces everything before its first-kept entry.
+        expect(roles[roles.length - 2]).toBe("compactionSummary");
+        expect(roles[roles.length - 1]).toBe("user");
+        expect(roles).toContain("system");
+    });
+    it("restores a branch's own prompt and tool state when navigating to it", () => {
+        const entries = [
+            user("a1", null, "root"),
+            system("as", "a1", "branch-a instructions"),
+            user("a2", "as", "on branch a"),
+            user("b2", "a1", "on branch b"),
+        ];
+        const byId = new Map(entries.map((entry) => [entry.id, entry]));
+        const branchA = buildContextEntries(entries, "a2", byId);
+        const branchB = buildContextEntries(entries, "b2", byId);
+        expect(branchA.map((entry) => entry.id)).toContain("as");
+        expect(branchB.map((entry) => entry.id)).not.toContain("as");
+    });
+});

package/dist/core/session-manager.d.ts

@@ -1,5 +1,5 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import { type ImageContent, type Message, type TextContent, type Usage } from "@earendil-works/pi-ai";
+import { type ImageContent, type Message, type SystemMessage, type TextContent, type Usage } from "@earendil-works/pi-ai";
 import { type BashExecutionMessage, type CustomMessage } from "./messages.ts";
 export declare const CURRENT_SESSION_VERSION = 3;
 export interface SessionHeader {
@@ -33,6 +33,16 @@ export interface ModelChangeEntry extends SessionEntryBase {
     provider: string;
     modelId: string;
 }
+export interface UsageEntry extends SessionEntryBase {
+    type: "usage";
+    /** Arbitrary usage category, such as "cache_warm". */
+    kind: string;
+    provider: string;
+    model: string;
+    usage: Usage;
+    /** Optional human-readable qualifier for usage notices. */
+    note?: string;
+}
 export interface CompactionEntry<T = unknown> extends SessionEntryBase {
     type: "compaction";
     summary: string;
@@ -44,6 +54,8 @@ export interface CompactionEntry<T = unknown> extends SessionEntryBase {
     usage?: Usage;
     /** True if generated by an extension, undefined/false if pi-generated (backward compatible) */
     fromHook?: boolean;
+    /** Complete prompt and tool state at this compaction boundary. */
+    systemMessage?: SystemMessage;
 }
 export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {
     type: "branch_summary";
@@ -102,7 +114,7 @@ export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
     display: boolean;
 }
 /** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */
-export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry;
+export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | UsageEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry;
 /** Raw file entry (includes header) */
 export type FileEntry = SessionHeader | SessionEntry;
 /** Tree node for getTree() - defensive copy of session structure */
@@ -169,7 +181,9 @@ export declare function getDefaultSessionDir(cwd: string, agentDir?: string): st
 export declare function loadEntriesFromFile(filePath: string): FileEntry[];
 /** Exported for testing */
 export declare function findMostRecentSession(sessionDir: string, cwd?: string): string | null;
-export type SessionListProgress = (loaded: number, total: number) => void;
+export type SessionListProgress = (loaded: number, total: number, 
+/** Sessions loaded so far, sorted by activity. Present on periodic updates. */
+partialSessions?: readonly SessionInfo[]) => void;
 /**
  * Manages conversation sessions as append-only trees stored in JSONL files.
  *
@@ -220,6 +234,8 @@ export declare class SessionManager {
     appendThinkingLevelChange(thinkingLevel: string): string;
     /** Append a model change as child of current leaf, then advance leaf. Returns entry id. */
     appendModelChange(provider: string, modelId: string): string;
+    /** Append model-attributed usage that does not participate in LLM context. Returns the appended entry. */
+    appendUsage(kind: string, provider: string, model: string, usage: Usage, note?: string): UsageEntry;
     /** Append a compaction summary as child of current leaf, then advance leaf. Returns entry id. */
     appendCompaction<T = unknown>(summary: string, firstKeptEntryId: string, tokensBefore: number, details?: T, fromHook?: boolean, usage?: Usage): string;
     /** Append a custom entry (for extensions) as child of current leaf, then advance leaf. Returns entry id. */
@@ -340,17 +356,24 @@ export declare class SessionManager {
      * @param sessionDir Optional session directory. If omitted, uses default for targetCwd.
      */
     static forkFrom(sourcePath: string, targetCwd: string, sessionDir?: string, options?: NewSessionOptions): SessionManager;
+    /**
+     * Find an exact session ID without loading transcript bodies.
+     * @param cwd Working directory (used to compute default session directory)
+     * @param id Exact session ID
+     * @param sessionDir Optional session directory. If omitted, uses default (~/.selesai/agent/sessions/<encoded-cwd>/).
+     */
+    static findById(cwd: string, id: string, sessionDir?: string): string | undefined;
     /**
      * List all sessions for a directory.
      * @param cwd Working directory (used to compute default session directory)
      * @param sessionDir Optional session directory. If omitted, uses the configured agent sessions directory.
      * @param onProgress Optional callback for progress updates (loaded, total)
      */
-    static list(cwd: string, sessionDir?: string, onProgress?: SessionListProgress): Promise<SessionInfo[]>;
+    static list(cwd: string, sessionDir?: string, onProgress?: SessionListProgress, signal?: AbortSignal): Promise<SessionInfo[]>;
     /**
      * List all sessions across all project directories.
      * @param onProgress Optional callback for progress updates (loaded, total)
      */
-    static listAll(onProgress?: SessionListProgress): Promise<SessionInfo[]>;
-    static listAll(sessionDir?: string, onProgress?: SessionListProgress): Promise<SessionInfo[]>;
+    static listAll(onProgress?: SessionListProgress, signal?: AbortSignal): Promise<SessionInfo[]>;
+    static listAll(sessionDir?: string, onProgress?: SessionListProgress, signal?: AbortSignal): Promise<SessionInfo[]>;
 }