@selesai/code 0.13.26 → 0.13.27

package/dist/core/session-manager.js

@@ -1,8 +1,8 @@
-import { uuidv7 } from "@earendil-works/pi-ai";
+import { getCurrentSystemMessage, uuidv7, } from "@earendil-works/pi-ai";
 import { randomUUID } from "crypto";
 import { appendFileSync, closeSync, createReadStream, existsSync, mkdirSync, openSync, readdirSync, readSync, statSync, writeFileSync, } from "fs";
 import { readdir, stat } from "fs/promises";
-import { join, resolve } from "path";
+import { basename, join, resolve } from "path";
 import { createInterface } from "readline";
 import { StringDecoder } from "string_decoder";
 import { APP_NAME, getAgentDir as getDefaultAgentDir, getSessionsDir } from "../config.js";
@@ -168,6 +168,8 @@ export function sessionEntryToContextMessages(entry) {
         const message = entry.message;
         // Session files are parsed without validation; old versions, forks, or
         // hand-edited files can contain messages with null/missing content.
+        if (message.role === "system" && message.content == null)
+            return [{ ...message, content: "" }];
         if ((message.role === "user" || message.role === "assistant" || message.role === "toolResult") &&
             message.content == null) {
             return [{ ...message, content: [] }];
@@ -183,7 +185,8 @@ export function sessionEntryToContextMessages(entry) {
         return [createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp)];
     }
     if (entry.type === "compaction") {
-        return [createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp)];
+        const summary = createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp);
+        return entry.systemMessage ? [entry.systemMessage, summary] : [summary];
     }
     return [];
 }
@@ -217,7 +220,7 @@ export function buildContextEntries(entries, leafId, byId) {
         if (entry.id === compaction.firstKeptEntryId) {
             foundFirstKept = true;
         }
-        if (foundFirstKept) {
+        if (foundFirstKept && !(entry.type === "message" && entry.message.role === "system")) {
             contextEntries.push(entry);
         }
     }
@@ -399,14 +402,16 @@ export function findMostRecentSession(sessionDir, cwd) {
     const resolvedCwd = cwd ? resolvePath(cwd) : undefined;
     try {
         const files = readdirSync(resolvedSessionDir)
-            .filter((f) => f.endsWith(".jsonl"))
-            .map((f) => join(resolvedSessionDir, f))
-            .map((path) => ({ path, header: readSessionHeaderForDiscovery(path) }))
-            .filter((file) => file.header !== null &&
-            (!resolvedCwd || sessionCwdMatches(getSessionHeaderCwd(file.header), resolvedCwd)))
-            .map(({ path }) => ({ path, mtime: statSync(path).mtime }))
-            .sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
-        return files[0]?.path || null;
+            .filter((file) => file.endsWith(".jsonl"))
+            .map((file) => join(resolvedSessionDir, file))
+            .map((path) => ({ path, mtime: statSync(path).mtimeMs }))
+            .sort((a, b) => b.mtime - a.mtime);
+        for (const { path } of files) {
+            const header = readSessionHeaderForDiscovery(path);
+            if (header && (!resolvedCwd || sessionCwdMatches(getSessionHeaderCwd(header), resolvedCwd)))
+                return path;
+        }
+        return null;
     }
     catch {
         // Directory access and stat races make recent-session discovery unavailable.
@@ -439,9 +444,9 @@ function getMessageActivityTime(entry) {
     const t = new Date(entry.timestamp).getTime();
     return Number.isNaN(t) ? undefined : t;
 }
-async function buildSessionInfo(filePath) {
+async function buildSessionInfo(filePath, signal, fileStats) {
     try {
-        const stats = await stat(filePath);
+        const stats = fileStats ?? (await stat(filePath));
         let header = null;
         let messageCount = 0;
         let firstMessage = "";
@@ -449,7 +454,7 @@ async function buildSessionInfo(filePath) {
         let name;
         let lastActivityTime;
         const rl = createInterface({
-            input: createReadStream(filePath, { encoding: "utf8" }),
+            input: createReadStream(filePath, { encoding: "utf8", signal }),
             crlfDelay: Infinity,
         });
         for await (const line of rl) {
@@ -510,67 +515,63 @@ async function buildSessionInfo(filePath) {
         };
     }
     catch {
+        signal?.throwIfAborted();
         return null;
     }
 }
 const MAX_CONCURRENT_SESSION_INFO_LOADS = 10;
-async function buildSessionInfosWithConcurrency(files, onLoaded) {
-    const results = new Array(files.length).fill(null);
-    const inFlight = new Set();
+const MAX_CONCURRENT_SESSION_DISCOVERY_LOADS = 64;
+const CURRENT_SESSION_LIST_PUBLISH_INTERVAL = 10;
+const ALL_SESSION_LIST_PUBLISH_INTERVAL = 100;
+async function mapWithConcurrency(items, limit, map, signal) {
+    const results = new Array(items.length);
     let nextIndex = 0;
-    const startNext = () => {
-        const index = nextIndex++;
-        const file = files[index];
-        if (!file)
-            return;
-        let task;
-        task = buildSessionInfo(file)
-            .then((info) => {
-            results[index] = info;
-        })
-            .catch(() => {
-            results[index] = null;
-        })
-            .finally(() => {
-            inFlight.delete(task);
-            onLoaded();
-        });
-        inFlight.add(task);
-    };
-    while (nextIndex < files.length || inFlight.size > 0) {
-        while (nextIndex < files.length && inFlight.size < MAX_CONCURRENT_SESSION_INFO_LOADS) {
-            startNext();
-        }
-        if (inFlight.size > 0) {
-            await Promise.race(inFlight);
+    const worker = async () => {
+        while (nextIndex < items.length) {
+            signal?.throwIfAborted();
+            const index = nextIndex++;
+            results[index] = await map(items[index], index);
         }
-    }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => worker()));
     return results;
 }
-async function listSessionsFromDir(dir, onProgress, progressOffset = 0, progressTotal) {
-    const sessions = [];
-    if (!existsSync(dir)) {
-        return sessions;
-    }
+function sortSessionInfos(sessions) {
+    return sessions.sort((a, b) => b.modified.getTime() - a.modified.getTime());
+}
+function buildSessionInfosWithConcurrency(files, onLoaded, signal) {
+    return mapWithConcurrency(files, MAX_CONCURRENT_SESSION_INFO_LOADS, async (file, index) => {
+        const info = await buildSessionInfo(file.path, signal, file.stats);
+        onLoaded(info, index);
+        return info;
+    }, signal);
+}
+async function listSessionsFromDir(dir, onProgress, signal) {
+    signal?.throwIfAborted();
+    if (!existsSync(dir))
+        return [];
     try {
         const dirEntries = await readdir(dir);
-        const files = dirEntries.filter((f) => f.endsWith(".jsonl")).map((f) => join(dir, f));
-        const total = progressTotal ?? files.length;
+        const files = dirEntries
+            .filter((file) => file.endsWith(".jsonl"))
+            .sort((a, b) => b.localeCompare(a))
+            .map((file) => ({ path: join(dir, file) }));
+        const total = files.length;
+        const partialSessions = [];
         let loaded = 0;
-        const results = await buildSessionInfosWithConcurrency(files, () => {
+        const results = await buildSessionInfosWithConcurrency(files, (info) => {
             loaded++;
-            onProgress?.(progressOffset + loaded, total);
-        });
-        for (const info of results) {
-            if (info) {
-                sessions.push(info);
-            }
-        }
+            if (info)
+                partialSessions.push(info);
+            const publishPartial = loaded === 1 || loaded % CURRENT_SESSION_LIST_PUBLISH_INTERVAL === 0 || loaded === files.length;
+            onProgress?.(loaded, total, publishPartial ? sortSessionInfos([...partialSessions]) : undefined);
+        }, signal);
+        return results.filter((info) => info !== null);
     }
     catch {
-        // Return empty list on error
+        signal?.throwIfAborted();
+        return [];
     }
-    return sessions;
 }
 /**
  * Manages conversation sessions as append-only trees stored in JSONL files.
@@ -814,19 +815,38 @@ export class SessionManager {
         this._appendEntry(entry);
         return entry.id;
     }
+    /** Append model-attributed usage that does not participate in LLM context. Returns the appended entry. */
+    appendUsage(kind, provider, model, usage, note) {
+        const entry = {
+            type: "usage",
+            id: generateId(this.byId),
+            parentId: this.leafId,
+            timestamp: new Date().toISOString(),
+            kind,
+            provider,
+            model,
+            usage,
+            ...(note ? { note } : {}),
+        };
+        this._appendEntry(entry);
+        return entry;
+    }
     /** Append a compaction summary as child of current leaf, then advance leaf. Returns entry id. */
     appendCompaction(summary, firstKeptEntryId, tokensBefore, details, fromHook, usage) {
+        const timestamp = new Date().toISOString();
+        const systemMessage = getCurrentSystemMessage(this.buildSessionContext().messages);
         const entry = {
             type: "compaction",
             id: generateId(this.byId),
             parentId: this.leafId,
-            timestamp: new Date().toISOString(),
+            timestamp,
             summary,
             firstKeptEntryId,
             tokensBefore,
             details,
             usage,
             fromHook,
+            ...(systemMessage ? { systemMessage: { ...systemMessage, timestamp: new Date(timestamp).getTime() } } : {}),
         };
         this._appendEntry(entry);
         return entry.id;
@@ -1301,65 +1321,108 @@ export class SessionManager {
         }
         return new SessionManager(resolvedTargetCwd, dir, newSessionFile, true);
     }
+    /**
+     * 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, id, sessionDir) {
+        const dir = sessionDir ? normalizePath(sessionDir) : getDefaultSessionDir(cwd);
+        const filterCwd = sessionDir !== undefined && dir !== getDefaultSessionDirPath(cwd);
+        const resolvedCwd = resolvePath(cwd);
+        try {
+            for (const file of readdirSync(dir)) {
+                if (!file.endsWith(".jsonl"))
+                    continue;
+                const path = join(dir, file);
+                const header = readSessionHeaderForDiscovery(path);
+                if (header?.id !== id)
+                    continue;
+                if (filterCwd && !sessionCwdMatches(getSessionHeaderCwd(header), resolvedCwd))
+                    continue;
+                return path;
+            }
+        }
+        catch {
+            // Exact session discovery is best-effort, matching list().
+        }
+        return 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 async list(cwd, sessionDir, onProgress) {
+    static async list(cwd, sessionDir, onProgress, signal) {
         const dir = sessionDir ? normalizePath(sessionDir) : getDefaultSessionDir(cwd);
         const filterCwd = sessionDir !== undefined && dir !== getDefaultSessionDirPath(cwd);
         const resolvedCwd = resolvePath(cwd);
-        const sessions = (await listSessionsFromDir(dir, onProgress)).filter((session) => !filterCwd || sessionCwdMatches(session.cwd, resolvedCwd));
-        sessions.sort((a, b) => b.modified.getTime() - a.modified.getTime());
-        return sessions;
-    }
-    static async listAll(sessionDirOrOnProgress, onProgress) {
+        const includeSession = (session) => !filterCwd || sessionCwdMatches(session.cwd, resolvedCwd);
+        const progress = onProgress
+            ? (loaded, total, partialSessions) => onProgress(loaded, total, partialSessions?.filter(includeSession))
+            : undefined;
+        const sessions = (await listSessionsFromDir(dir, progress, signal)).filter(includeSession);
+        return sortSessionInfos(sessions);
+    }
+    static async listAll(sessionDirOrOnProgress, onProgressOrSignal, signal) {
         const customSessionDir = typeof sessionDirOrOnProgress === "string" ? normalizePath(sessionDirOrOnProgress) : undefined;
-        const progress = typeof sessionDirOrOnProgress === "function" ? sessionDirOrOnProgress : onProgress;
+        const progress = typeof sessionDirOrOnProgress === "function"
+            ? sessionDirOrOnProgress
+            : typeof onProgressOrSignal === "function"
+                ? onProgressOrSignal
+                : undefined;
+        const abortSignal = typeof sessionDirOrOnProgress === "string" || typeof onProgressOrSignal === "function"
+            ? signal
+            : (onProgressOrSignal ?? signal);
+        abortSignal?.throwIfAborted();
         if (customSessionDir) {
-            const sessions = await listSessionsFromDir(customSessionDir, progress);
-            sessions.sort((a, b) => b.modified.getTime() - a.modified.getTime());
-            return sessions;
+            return sortSessionInfos(await listSessionsFromDir(customSessionDir, progress, abortSignal));
         }
         const sessionsDir = getSessionsDir();
         try {
-            if (!existsSync(sessionsDir)) {
+            if (!existsSync(sessionsDir))
                 return [];
-            }
             const entries = await readdir(sessionsDir, { withFileTypes: true });
             const dirs = entries.filter((e) => e.isDirectory()).map((e) => join(sessionsDir, e.name));
-            // Count total files first for accurate progress
-            let totalFiles = 0;
-            const dirFiles = [];
-            for (const dir of dirs) {
+            const dirFiles = await mapWithConcurrency(dirs, MAX_CONCURRENT_SESSION_DISCOVERY_LOADS, async (dir) => {
                 try {
-                    const files = (await readdir(dir)).filter((f) => f.endsWith(".jsonl"));
-                    dirFiles.push(files.map((f) => join(dir, f)));
-                    totalFiles += files.length;
+                    return (await readdir(dir)).filter((file) => file.endsWith(".jsonl")).map((file) => join(dir, file));
                 }
                 catch {
-                    dirFiles.push([]);
+                    return [];
                 }
-            }
-            // Process all files with progress tracking
-            let loaded = 0;
-            const sessions = [];
+            }, abortSignal);
             const allFiles = dirFiles.flat();
-            const results = await buildSessionInfosWithConcurrency(allFiles, () => {
-                loaded++;
-                progress?.(loaded, totalFiles);
-            });
-            for (const info of results) {
-                if (info) {
-                    sessions.push(info);
+            const candidates = await mapWithConcurrency(allFiles, MAX_CONCURRENT_SESSION_DISCOVERY_LOADS, async (path) => {
+                try {
+                    return { path, stats: await stat(path) };
                 }
-            }
-            sessions.sort((a, b) => b.modified.getTime() - a.modified.getTime());
-            return sessions;
+                catch {
+                    return { path };
+                }
+            }, abortSignal);
+            candidates.sort((a, b) => (b.stats?.mtimeMs ?? Number.NEGATIVE_INFINITY) - (a.stats?.mtimeMs ?? Number.NEGATIVE_INFINITY) ||
+                basename(b.path).localeCompare(basename(a.path)));
+            const totalFiles = candidates.length;
+            let loaded = 0;
+            let firstCandidateLoaded = false;
+            const partialSessions = [];
+            const results = await buildSessionInfosWithConcurrency(candidates, (info, index) => {
+                loaded++;
+                if (index === 0)
+                    firstCandidateLoaded = true;
+                if (info)
+                    partialSessions.push(info);
+                const publishPartial = firstCandidateLoaded &&
+                    (index === 0 || loaded % ALL_SESSION_LIST_PUBLISH_INTERVAL === 0 || loaded === totalFiles);
+                progress?.(loaded, totalFiles, publishPartial ? sortSessionInfos([...partialSessions]) : undefined);
+            }, abortSignal);
+            return sortSessionInfos(results.filter((info) => info !== null));
         }
         catch {
+            abortSignal?.throwIfAborted();
             return [];
         }
     }

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

@@ -1,10 +1,15 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Transport } from "@earendil-works/pi-ai";
-import type { ScrollViewScrollbar, TerminalCapabilities, TuiMode as RendererTuiMode } from "@earendil-works/pi-tui";
+import { type Model, type Transport } from "@earendil-works/pi-ai";
+import type { TuiMode as RendererTuiMode, ScrollViewScrollbar, TerminalCapabilities } from "@earendil-works/pi-tui";
+export interface CompactionModelOverride {
+    reserveTokens?: number;
+    keepRecentTokens?: number;
+}
 export interface CompactionSettings {
     enabled?: boolean;
     reserveTokens?: number;
     keepRecentTokens?: number;
+    modelOverrides?: Record<string, CompactionModelOverride>;
 }
 export interface BranchSummarySettings {
     reserveTokens?: number;
@@ -19,6 +24,7 @@ export interface RetrySettings {
     enabled?: boolean;
     maxRetries?: number;
     baseDelayMs?: number;
+    maxAgentDelayMs?: number;
     provider?: ProviderRetrySettings;
 }
 export type TuiMode = RendererTuiMode;
@@ -44,6 +50,10 @@ export interface ThinkingBudgetsSettings {
     medium?: number;
     high?: number;
 }
+export type MermaidRenderingMode = "off" | "final" | "streaming";
+/** Cache-warming profile. "idle" also warms between agent runs. */
+export declare const CACHE_WARMING_MODES: readonly ["off", "streaming", "idle"];
+export type CacheWarmingMode = (typeof CACHE_WARMING_MODES)[number];
 export interface MarkdownSettings {
     codeBlockIndent?: string;
 }
@@ -124,6 +134,7 @@ export interface Settings {
     extensionHost?: Record<string, "selesai" | "pi">;
     httpProxy?: string;
     httpIdleTimeoutMs?: number;
+    cacheWarming?: CacheWarmingMode;
     websocketConnectTimeoutMs?: number;
 }
 export type SettingsScope = "global" | "project";
@@ -234,9 +245,11 @@ export declare class SettingsManager {
     setTransport(transport: TransportSetting): void;
     getCompactionEnabled(): boolean;
     setCompactionEnabled(enabled: boolean): void;
-    getCompactionReserveTokens(): number;
-    getCompactionKeepRecentTokens(): number;
-    getCompactionSettings(): {
+    private getCompactionTokenSetting;
+    getCompactionReserveTokens(model?: Pick<Model<string>, "provider" | "id">): number;
+    getCompactionKeepRecentTokens(model?: Pick<Model<string>, "provider" | "id">): number;
+    /** Resolve each token setting through model override, ordinary setting, then built-in default. */
+    getCompactionSettings(model?: Pick<Model<string>, "provider" | "id">): {
         enabled: boolean;
         reserveTokens: number;
         keepRecentTokens: number;
@@ -252,9 +265,13 @@ export declare class SettingsManager {
         enabled: boolean;
         maxRetries: number;
         baseDelayMs: number;
+        maxAgentDelayMs: number;
     };
     getHttpIdleTimeoutMs(): number;
     setHttpIdleTimeoutMs(timeoutMs: number): void;
+    /** Read from global settings only because warming costs money. */
+    getCacheWarmingMode(): CacheWarmingMode;
+    setCacheWarmingMode(mode: CacheWarmingMode): void;
     getProviderRetrySettings(): {
         timeoutMs?: number;
         maxRetries?: number;

package/dist/core/settings-manager.js

@@ -1,3 +1,4 @@
+import { DEFAULT_MAX_AGENT_RETRY_DELAY_MS } from "@earendil-works/pi-ai";
 import { randomUUID } from "crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
@@ -5,35 +6,38 @@ import lockfile from "proper-lockfile";
 import { CONFIG_DIR_NAME, getAgentDir } from "../config.js";
 import { normalizePath, resolvePath } from "../utils/paths.js";
 import { DEFAULT_HTTP_IDLE_TIMEOUT_MS, parseHttpIdleTimeoutMs } from "./http-dispatcher.js";
+const DEFAULT_COMPACTION_TOKEN_SETTINGS = {
+    reserveTokens: 16384,
+    keepRecentTokens: 20000,
+};
+/** Cache-warming profile. "idle" also warms between agent runs. */
+export const CACHE_WARMING_MODES = ["off", "streaming", "idle"];
 const DEFAULT_AUTO_HANDOFF_SETTINGS = {
     enabled: false,
     thresholdTokens: 128_000,
 };
-/** Deep merge settings: project/overrides take precedence, nested objects merge recursively */
-function deepMergeSettings(base, overrides) {
+function isMergeableObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepMergeObjects(base, overrides) {
     const result = { ...base };
     for (const key of Object.keys(overrides)) {
         const overrideValue = overrides[key];
-        const baseValue = base[key];
         if (overrideValue === undefined) {
             continue;
         }
-        // For nested objects, merge recursively
-        if (typeof overrideValue === "object" &&
-            overrideValue !== null &&
-            !Array.isArray(overrideValue) &&
-            typeof baseValue === "object" &&
-            baseValue !== null &&
-            !Array.isArray(baseValue)) {
-            result[key] = { ...baseValue, ...overrideValue };
-        }
-        else {
-            // For primitives and arrays, override value wins
-            result[key] = overrideValue;
-        }
+        const baseValue = base[key];
+        result[key] =
+            isMergeableObject(baseValue) && isMergeableObject(overrideValue)
+                ? deepMergeObjects(baseValue, overrideValue)
+                : overrideValue;
     }
     return result;
 }
+/** Deep merge settings: project/overrides take precedence, nested objects merge recursively */
+function deepMergeSettings(base, overrides) {
+    return deepMergeObjects(base, overrides);
+}
 function parseTimeoutSetting(value, settingName) {
     const timeoutMs = parseHttpIdleTimeoutMs(value);
     if (timeoutMs !== undefined) {
@@ -604,17 +608,35 @@ export class SettingsManager {
         this.markModified("compaction", "enabled");
         this.save();
     }
-    getCompactionReserveTokens() {
-        return this.settings.compaction?.reserveTokens ?? 16384;
+    getCompactionTokenSetting(field, model) {
+        const compaction = this.settings.compaction;
+        const ordinary = compaction?.[field];
+        if (ordinary !== undefined && (typeof ordinary !== "number" || !Number.isSafeInteger(ordinary) || ordinary < 0)) {
+            throw new Error(`Invalid compaction.${field} setting: ${String(ordinary)}. Expected a non-negative safe integer.`);
+        }
+        const modelKey = model ? `${model.provider}/${model.id}` : undefined;
+        const entry = modelKey !== undefined ? compaction?.modelOverrides?.[modelKey] : undefined;
+        if (entry !== undefined && !isMergeableObject(entry)) {
+            throw new Error(`Invalid compaction.modelOverrides["${modelKey}"] setting: ${String(entry)}. Expected an object.`);
+        }
+        const override = entry?.[field];
+        if (override !== undefined && (typeof override !== "number" || !Number.isSafeInteger(override) || override < 0)) {
+            throw new Error(`Invalid compaction.modelOverrides["${modelKey}"].${field} setting: ${String(override)}. Expected a non-negative safe integer.`);
+        }
+        return override ?? ordinary ?? DEFAULT_COMPACTION_TOKEN_SETTINGS[field];
     }
-    getCompactionKeepRecentTokens() {
-        return this.settings.compaction?.keepRecentTokens ?? 20000;
+    getCompactionReserveTokens(model) {
+        return this.getCompactionTokenSetting("reserveTokens", model);
     }
-    getCompactionSettings() {
+    getCompactionKeepRecentTokens(model) {
+        return this.getCompactionTokenSetting("keepRecentTokens", model);
+    }
+    /** Resolve each token setting through model override, ordinary setting, then built-in default. */
+    getCompactionSettings(model) {
         return {
             enabled: this.getCompactionEnabled(),
-            reserveTokens: this.getCompactionReserveTokens(),
-            keepRecentTokens: this.getCompactionKeepRecentTokens(),
+            reserveTokens: this.getCompactionReserveTokens(model),
+            keepRecentTokens: this.getCompactionKeepRecentTokens(model),
         };
     }
     getBranchSummarySettings() {
@@ -642,6 +664,7 @@ export class SettingsManager {
             enabled: this.getRetryEnabled(),
             maxRetries: this.settings.retry?.maxRetries ?? 3,
             baseDelayMs: this.settings.retry?.baseDelayMs ?? 2000,
+            maxAgentDelayMs: this.settings.retry?.maxAgentDelayMs ?? DEFAULT_MAX_AGENT_RETRY_DELAY_MS,
         };
     }
     getHttpIdleTimeoutMs() {
@@ -655,6 +678,16 @@ export class SettingsManager {
         this.markModified("httpIdleTimeoutMs");
         this.save();
     }
+    /** Read from global settings only because warming costs money. */
+    getCacheWarmingMode() {
+        const mode = this.globalSettings.cacheWarming;
+        return mode !== undefined && CACHE_WARMING_MODES.includes(mode) ? mode : "streaming";
+    }
+    setCacheWarmingMode(mode) {
+        this.globalSettings.cacheWarming = mode;
+        this.markModified("cacheWarming");
+        this.save();
+    }
     getProviderRetrySettings() {
         return {
             timeoutMs: this.settings.retry?.provider?.timeoutMs,

package/dist/core/slash-commands.js

@@ -7,6 +7,7 @@ export const BUILTIN_SLASH_COMMANDS = [
     { name: "export", description: "Export session (HTML default, or specify path: .html/.jsonl)" },
     { name: "import", description: "Import and resume a session from a JSONL file" },
     { name: "share", description: "Share session as a secret GitHub gist" },
+    { name: "bug", description: "Report a bug to the Pi developers", argumentHint: "<description>" },
     { name: "copy", description: "Copy last agent message to clipboard" },
     { name: "name", description: "Set session display name" },
     { name: "session", description: "Show session info and stats" },

package/dist/core/system-prompt.d.ts

@@ -4,16 +4,22 @@
 import { type AgentPersona } from "./agents.ts";
 import { type Skill } from "./skills.ts";
 export interface BuildSystemPromptOptions {
-    /** Custom system prompt (replaces default). */
+    /** Custom system prompt (replaces the default prefix). */
     customPrompt?: string;
-    /** Tools to include in prompt. Default: [read, bash, edit, write, grep, find, ls] */
+    /** Exact full prompt replacement set by a before_agent_start handler. */
+    forceSystemPrompt?: string;
+    /** Tools to include in prompt. Default: [read, bash, edit, write] */
     selectedTools?: string[];
     /** Optional one-line tool snippets keyed by tool name. */
     toolSnippets?: Record<string, string>;
+    /** Guideline bullets contributed by each tool, keyed by tool name. */
+    toolGuidelines?: Record<string, string[]>;
     /** Additional guideline bullets appended to the default system prompt guidelines. */
     promptGuidelines?: string[];
     /** Text to append to system prompt. */
     appendSystemPrompt?: string;
+    /** Additional XML-wrapped prompt sections keyed by tag name. */
+    sections?: Record<string, string>;
     /** Working directory. */
     cwd: string;
     /** Pre-loaded context files. */
@@ -26,5 +32,44 @@ export interface BuildSystemPromptOptions {
     /** Pre-loaded subagent personas. */
     agents?: AgentPersona[];
 }
-/** Build the system prompt with tools, guidelines, and context */
-export declare function buildSystemPrompt(options: BuildSystemPromptOptions): string;
+export type NormalizedBuildSystemPromptOptions = BuildSystemPromptOptions & {
+    selectedTools: string[];
+    toolSnippets: Record<string, string>;
+    toolGuidelines: Record<string, string[]>;
+    promptGuidelines: string[];
+    appendSystemPrompt: string;
+    sections: Record<string, string>;
+    contextFiles: Array<{
+        path: string;
+        content: string;
+    }>;
+    skills: Skill[];
+    agents: AgentPersona[];
+};
+/**
+ * Ordered system prompt sections, keyed by name. `preamble` is untagged text; every other
+ * section is wrapped in a tag of the same name so the model can match later updates to it.
+ * These become `SystemMessage.sections` in the transcript.
+ */
+export type SystemPromptSections = Record<string, string>;
+/** Normalize prompt input into the mutable, collection-complete shape exposed to extensions. */
+export declare function normalizeBuildSystemPromptOptions(input: BuildSystemPromptOptions): NormalizedBuildSystemPromptOptions;
+export declare function buildRules(selectedTools: string[], toolGuidelines: Record<string, string[]>, promptGuidelines: string[]): string;
+/** Build the ordered, independently replaceable sections of the structured system prompt. */
+export declare function buildSystemPromptSections(input: BuildSystemPromptOptions): SystemPromptSections;
+/**
+ * The complete prompt state for `input`. A forced prompt is opaque and lives in `content`
+ * with no sections; otherwise `content` is empty and the structured sections carry the prompt.
+ */
+export declare function buildSystemPromptState(input: BuildSystemPromptOptions): {
+    content: string;
+    sections?: SystemPromptSections;
+};
+/** Build the system prompt text, rendered exactly as the transcript's system message replays it. */
+export declare function buildSystemPrompt(input: BuildSystemPromptOptions): string;
+/**
+ * Diff the sections the model currently has (replayed from the transcript, so never null)
+ * against the desired ones. Returns a `SystemMessage.sections` patch, or undefined when
+ * nothing changed.
+ */
+export declare function diffSystemPromptSections(previous: Record<string, string | null>, current: SystemPromptSections): Record<string, string | null> | undefined;