@selesai/code 0.13.39 → 0.14.0

package/dist/core/runtime-credentials.d.ts

@@ -1,4 +1,4 @@
-import type { Credential, CredentialInfo, CredentialStore } from "@earendil-works/pi-ai";
+import type { AuthOperationOptions, Credential, CredentialInfo, CredentialStore } from "@earendil-works/pi-ai";
 /** Async credential store overlay for non-persistent runtime API keys. */
 export declare class RuntimeCredentials implements CredentialStore {
     private readonly store;
@@ -9,8 +9,8 @@ export declare class RuntimeCredentials implements CredentialStore {
     hasRuntimeApiKey(providerId: string): boolean;
     getStore(): CredentialStore;
     reload(): void;
-    read(providerId: string): Promise<Credential | undefined>;
-    list(): Promise<readonly CredentialInfo[]>;
-    modify(providerId: string, fn: (current: Credential | undefined) => Promise<Credential | undefined>): Promise<Credential | undefined>;
-    delete(providerId: string): Promise<void>;
+    read(providerId: string, options?: AuthOperationOptions): Promise<Credential | undefined>;
+    list(options?: AuthOperationOptions): Promise<readonly CredentialInfo[]>;
+    modify(providerId: string, fn: (current: Credential | undefined) => Promise<Credential | undefined>, options?: AuthOperationOptions): Promise<Credential | undefined>;
+    delete(providerId: string, options?: AuthOperationOptions): Promise<void>;
 }

package/dist/core/runtime-credentials.js

@@ -20,22 +20,25 @@ export class RuntimeCredentials {
     reload() {
         this.store.reload?.();
     }
-    async read(providerId) {
+    async read(providerId, options) {
+        options?.signal?.throwIfAborted();
         const override = this.overrides.get(providerId);
-        return override ? { type: "api_key", key: override } : this.store.read(providerId);
+        return override ? { type: "api_key", key: override } : this.store.read(providerId, options);
     }
-    async list() {
-        const entries = new Map((await this.store.list()).map((entry) => [entry.providerId, entry]));
+    async list(options) {
+        const entries = new Map((await this.store.list(options)).map((entry) => [entry.providerId, entry]));
+        options?.signal?.throwIfAborted();
         for (const providerId of this.overrides.keys()) {
             entries.set(providerId, { providerId, type: "api_key" });
         }
         return [...entries.values()];
     }
-    modify(providerId, fn) {
-        return this.store.modify(providerId, fn);
+    modify(providerId, fn, options) {
+        return this.store.modify(providerId, fn, options);
     }
-    async delete(providerId) {
+    async delete(providerId, options) {
+        options?.signal?.throwIfAborted();
+        await this.store.delete(providerId, options);
         this.overrides.delete(providerId);
-        await this.store.delete(providerId);
     }
 }

package/dist/core/sdk.d.ts

@@ -32,16 +32,25 @@ export interface CreateAgentSessionOptions {
      */
     noTools?: "all" | "builtin";
     /**
-     * Optional allowlist of tool names.
+     * Optional allowlist of tool names or patterns, where `*` matches any characters.
      *
-     * When omitted, pi uses the `defaultTools` setting for the initial built-in
+     * When omitted, pi uses the resolved `defaultTools` setting for the initial
      * selection when configured. Otherwise it enables the default built-in tools
-     * (read, bash, edit, write, grep, find, ls). Extension/custom tools are inactive by default;
-     * `noTools: "builtin"` enables them instead. When provided, only the listed
-     * tool names are enabled.
+     * (read, bash, edit, write, grep, find, ls). Extension/custom tools use their
+     * declared exposure/defaultActive; `noTools: "builtin"` enables extension/custom tools. When provided, only matching tools are
+     * enabled. MCP tools stay registered for codemode and tool search unless an
+     * entry starts with `mcp__`; then only matching MCP tools are kept. An empty
+     * list, like `noTools: "all"`, disables MCP tools too.
+     *
+     * A list of only `+name` and `-name` entries is not an allowlist: it adds tools
+     * to or removes them from the default selection, like the `defaultTools` setting.
+     * These entries take exact names. Mixing them with plain entries throws.
      */
     tools?: string[];
-    /** Optional denylist of tool names to disable. Applies after `tools` when both are provided. */
+    /**
+     * Optional denylist of tool names or patterns to disable. Applies after `tools` when both are
+     * provided, MCP tools included.
+     */
     excludeTools?: string[];
     /** Custom tools to register (in addition to built-in tools). */
     customTools?: ToolDefinition[];
@@ -68,7 +77,7 @@ export type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Extension
 export type { PromptTemplate } from "./prompt-templates.ts";
 export type { Skill } from "./skills.ts";
 export type { Tool } from "./tools/index.ts";
-export { withFileMutationQueue, createCodingTools, createReadOnlyTools, createReadTool, createBashTool, createPowerShellTool, createEditTool, createWriteTool, createGrepTool, createFindTool, createLsTool, };
+export { withFileMutationQueue, createCodingTools, createReadOnlyTools, createReadTool, createBashTool, createEditTool, createWriteTool, createGrepTool, createFindTool, createLsTool, createPowerShellTool, };
 /**
  * Create an AgentSession with the specified options.
  *

package/dist/core/sdk.js

@@ -7,15 +7,17 @@ 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 { createToolNameMatcher } from "./mcp-servers.js";
 import { convertToLlm } from "./messages.js";
 import { findInitialModel } from "./model-resolver.js";
 import { ModelRuntime } from "./model-runtime.js";
 import { mergeProviderAttributionHeaders } from "./provider-attribution.js";
 import { DefaultResourceLoader } from "./resource-loader.js";
 import { getDefaultSessionDir, SessionManager } from "./session-manager.js";
-import { SettingsManager } from "./settings-manager.js";
+import { applyToolModifiers, DEFAULT_TOOL_NAMES, getToolListError, isToolModifier, SettingsManager, } from "./settings-manager.js";
 import { time } from "./timings.js";
 import { createBashTool, createCodingTools, createEditTool, createFindTool, createGrepTool, createLsTool, createPowerShellTool, createReadOnlyTools, createReadTool, createWriteTool, withFileMutationQueue, } from "./tools/index.js";
+import { getBranchSelection } from "./virtual-models.js";
 // Preserve the pre-0.81 fallback for extensions that construct Agent instances
 // or invoke low-level agent loops without supplying streamFn. Agent core remains
 // provider-agnostic and does not import pi-ai/compat itself.
@@ -24,7 +26,7 @@ setDefaultStreamFn(streamSimple);
 export * from "./agent-session-runtime.js";
 export { withFileMutationQueue, 
 // Tool factories (for custom cwd)
-createCodingTools, createReadOnlyTools, createReadTool, createBashTool, createPowerShellTool, createEditTool, createWriteTool, createGrepTool, createFindTool, createLsTool, };
+createCodingTools, createReadOnlyTools, createReadTool, createBashTool, createEditTool, createWriteTool, createGrepTool, createFindTool, createLsTool, createPowerShellTool, };
 // Helper Functions
 function getDefaultAgentDir() {
     return getAgentDir();
@@ -84,14 +86,17 @@ export async function createAgentSession(options = {}) {
     const hasThinkingEntry = sessionManager.getBranch().some((entry) => entry.type === "thinking_level_change");
     let model = options.model;
     let modelFallbackMessage;
+    // Assistant messages name the physical model that answered, so a virtual selection is only in
+    // model_change entries.
+    const sessionModel = getBranchSelection(sessionManager.getBranch(), (provider, modelId) => modelRuntime.getModel(provider, modelId));
     // If session has data, try to restore model from it
-    if (!model && hasExistingSession && existingSession.model) {
-        const restoredModel = modelRuntime.getModel(existingSession.model.provider, existingSession.model.modelId);
+    if (!model && hasExistingSession && sessionModel) {
+        const restoredModel = modelRuntime.getModel(sessionModel.provider, sessionModel.modelId);
         if (restoredModel && modelRuntime.hasConfiguredAuth(restoredModel.provider)) {
             model = restoredModel;
         }
         if (!model) {
-            modelFallbackMessage = `Could not restore model ${existingSession.model.provider}/${existingSession.model.modelId}`;
+            modelFallbackMessage = `Could not restore model ${sessionModel.provider}/${sessionModel.modelId}`;
         }
     }
     // If still no model, use findInitialModel (checks settings default, then provider defaults)
@@ -120,9 +125,12 @@ export async function createAgentSession(options = {}) {
             ? existingSession.thinkingLevel
             : (settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL);
     }
-    // Fall back to the selected model's override, then settings default
+    // Fall back to per-model override, then global default
     if (thinkingLevel === undefined && model) {
-        thinkingLevel = settingsManager.getModelThinkingLevel(model.provider, model.id);
+        const perModel = settingsManager.getModelThinkingLevel(model.provider, model.id);
+        if (perModel) {
+            thinkingLevel = perModel;
+        }
     }
     if (thinkingLevel === undefined) {
         thinkingLevel = settingsManager.getDefaultThinkingLevel() ?? DEFAULT_THINKING_LEVEL;
@@ -134,21 +142,29 @@ export async function createAgentSession(options = {}) {
     else {
         thinkingLevel = clampThinkingLevel(model, thinkingLevel);
     }
-    const defaultActiveToolNames = ["read", "bash", "edit", "write", "grep", "find", "ls"];
-    const configuredDefaultToolNames = settingsManager.getDefaultTools();
-    const allowedToolNames = options.tools ?? (options.noTools === "all" ? [] : undefined);
+    const toolListError = options.tools ? getToolListError(options.tools) : undefined;
+    if (toolListError)
+        throw new Error(`Invalid tools option: ${toolListError}`);
+    const defaultToolNames = options.noTools === "builtin"
+        ? [
+            ...resourceLoader.getExtensions().extensions.flatMap((extension) => Array.from(extension.tools.keys())),
+            ...(options.customTools?.map((tool) => tool.name) ?? []),
+        ]
+        : options.noTools
+            ? []
+            : (settingsManager.getDefaultTools() ?? DEFAULT_TOOL_NAMES);
+    // A `tools` list of only `+name`/`-name` entries changes the default selection instead of
+    // replacing it, like the `defaultTools` setting.
+    const toolModifiers = options.tools?.some(isToolModifier) ? options.tools : undefined;
+    const selectedToolNames = toolModifiers ? applyToolModifiers(defaultToolNames, toolModifiers) : options.tools;
+    const allowedToolNames = toolModifiers
+        ? options.noTools === "all"
+            ? selectedToolNames
+            : undefined
+        : (options.tools ?? (options.noTools === "all" ? [] : undefined));
     const excludedToolNames = options.excludeTools;
-    const excludedToolNameSet = excludedToolNames ? new Set(excludedToolNames) : undefined;
-    const initialActiveToolNames = (options.tools ??
-        (options.noTools === "builtin"
-            ? [
-                ...resourceLoader.getExtensions().extensions.flatMap((extension) => Array.from(extension.tools.keys())),
-                ...(options.customTools?.map((tool) => tool.name) ?? []),
-            ]
-            : options.noTools
-                ? []
-                : (configuredDefaultToolNames ?? defaultActiveToolNames))).filter((name) => !excludedToolNameSet?.has(name));
-    let agent;
+    const isExcludedTool = excludedToolNames ? createToolNameMatcher(excludedToolNames) : undefined;
+    const initialActiveToolNames = (selectedToolNames ?? defaultToolNames).filter((name) => !isExcludedTool?.(name));
     // Create convertToLlm wrapper that filters images if blockImages is enabled (defense-in-depth)
     const convertToLlmWithBlockImages = (messages) => {
         const converted = convertToLlm(messages);
@@ -200,6 +216,8 @@ export async function createAgentSession(options = {}) {
             },
         };
     };
+    // Warm only requests for the selected model. Requests a virtual selection routed, or that an
+    // extension redirected, may not be repeated by the next request, so warming them could be wasted.
     const cacheContextIsCurrent = (requestModel) => {
         const messages = agent.state.messages;
         return () => {
@@ -227,12 +245,25 @@ export async function createAgentSession(options = {}) {
             headers: response.headers,
         });
     };
-    agent = new Agent({
+    const handleProviderStreamEvent = async (data, model) => {
+        const runner = extensionRunnerRef.current;
+        if (!runner?.hasHandlers("provider_stream_event"))
+            return;
+        await runner.emit({
+            data,
+            type: "provider_stream_event",
+            provider: model.provider,
+            api: model.api,
+            model: model.id,
+        });
+    };
+    const agent = new Agent({
         initialState: {
             systemPrompt: "",
             model,
             thinkingLevel,
             tools: [],
+            messages: existingSession.messages,
         },
         convertToLlm: convertToLlmWithBlockImages,
         streamFn: async (model, context, options) => {
@@ -249,6 +280,7 @@ export async function createAgentSession(options = {}) {
         },
         onPayload: transformProviderPayload,
         onResponse: handleProviderResponse,
+        onProviderStreamEvent: handleProviderStreamEvent,
         sessionId: sessionManager.getSessionId(),
         transformContext: async (messages) => {
             const runner = extensionRunnerRef.current;
@@ -262,9 +294,8 @@ export async function createAgentSession(options = {}) {
         thinkingBudgets: settingsManager.getThinkingBudgets(),
         maxRetryDelayMs: settingsManager.getProviderRetrySettings().maxRetryDelayMs,
     });
-    // Restore messages if session has existing data
+    // Restore missing settings metadata for older sessions.
     if (hasExistingSession) {
-        agent.state.messages = existingSession.messages;
         if (!hasThinkingEntry) {
             sessionManager.appendThinkingLevelChange(thinkingLevel);
         }
@@ -287,6 +318,8 @@ export async function createAgentSession(options = {}) {
         modelRuntime,
         cacheWarmer,
         initialActiveToolNames,
+        usesDefaultTools: (options.tools === undefined || toolModifiers !== undefined) && !options.noTools,
+        defaultToolModifiers: toolModifiers,
         allowedToolNames,
         excludedToolNames,
         extensionRunnerRef,

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 SystemMessage, type TextContent, type Usage } from "@earendil-works/pi-ai";
+import { type AssistantMessage, type ImageContent, type Message, type SystemMessage, type TextContent, type ToolResultMessage, type Usage, type UserMessage } from "@earendil-works/pi-ai";
 import { type BashExecutionMessage, type CustomMessage } from "./messages.ts";
 export declare const CURRENT_SESSION_VERSION = 3;
 export interface SessionHeader {
@@ -113,8 +113,19 @@ export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
     details?: T;
     display: boolean;
 }
+/** Content that an append-only context edit may replace without changing message metadata. */
+export type ContextEditableContent = UserMessage["content"] | AssistantMessage["content"] | ToolResultMessage["content"] | CustomMessage["content"];
+/** Append-only change to one earlier entry's contribution to model context. */
+export interface ContextEditEntry extends SessionEntryBase {
+    type: "context_edit";
+    targetId: string;
+    /** Null omits the target from model context. A value replaces only its content. */
+    replacement: {
+        content: ContextEditableContent;
+    } | null;
+}
 /** Session entry - has id/parentId for tree structure (returned by "read" methods in SessionManager) */
-export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | UsageEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | SessionInfoEntry;
+export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | UsageEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | ContextEditEntry | LabelEntry | SessionInfoEntry;
 /** Raw file entry (includes header) */
 export type FileEntry = SessionHeader | SessionEntry;
 /** Tree node for getTree() - defensive copy of session structure */
@@ -126,6 +137,21 @@ export interface SessionTreeNode {
     /** Timestamp of the latest label change for this entry, if any */
     labelTimestamp?: string;
 }
+export interface ProjectedSessionEntry {
+    /** Raw append-only entry that owns this projected contribution. */
+    sourceEntry: SessionEntry;
+    /** Model-visible messages after context edits. Empty for state-only entries and omissions. */
+    messages: AgentMessage[];
+}
+export interface SessionProjection {
+    entries: ProjectedSessionEntry[];
+    messages: AgentMessage[];
+    thinkingLevel: string;
+    model: {
+        provider: string;
+        modelId: string;
+    } | null;
+}
 export interface SessionContext {
     messages: AgentMessage[];
     thinkingLevel: string;
@@ -149,7 +175,7 @@ export interface SessionInfo {
     firstMessage: string;
     allMessagesText: string;
 }
-export type ReadonlySessionManager = Pick<SessionManager, "getCwd" | "getSessionDir" | "getSessionId" | "getSessionFile" | "getLeafId" | "getLeafEntry" | "getEntry" | "getLabel" | "getBranch" | "buildContextEntries" | "getHeader" | "getEntries" | "getTree" | "getSessionName">;
+export type ReadonlySessionManager = Pick<SessionManager, "getCwd" | "getSessionDir" | "getSessionId" | "getSessionFile" | "getLeafId" | "getLeafEntry" | "getEntry" | "getLabel" | "getBranch" | "buildContextEntries" | "buildSessionProjection" | "getHeader" | "getEntries" | "getTree" | "getSessionName">;
 export declare function assertValidSessionId(id: string): void;
 /** Exported for testing */
 export declare function migrateSessionEntries(entries: FileEntry[]): void;
@@ -170,11 +196,9 @@ export declare function sessionEntryToContextMessages(entry: SessionEntry): Agen
  * compaction entry. Older summarized entries are omitted.
  */
 export declare function buildContextEntries(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>): SessionEntry[];
-/**
- * Build the session context from entries using tree traversal.
- * If leafId is provided, walks from that entry to root.
- * Handles compaction and branch summaries along the path.
- */
+/** Build provenance-preserving, compaction-aware model context. */
+export declare function buildSessionProjection(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>): SessionProjection;
+/** Build the finalized model context from the canonical session projection. */
 export declare function buildSessionContext(entries: SessionEntry[], leafId?: string | null, byId?: Map<string, SessionEntry>): SessionContext;
 export declare function getDefaultSessionDir(cwd: string, agentDir?: string): string;
 /** Exported for testing */
@@ -221,6 +245,13 @@ export declare class SessionManager {
     usesDefaultSessionDir(): boolean;
     getSessionId(): string;
     getSessionFile(): string | undefined;
+    /**
+     * A new session file is created only once the session contains a user or assistant message.
+     * Setup entries alone (model, thinking level, system prompt) stay in memory so opening and
+     * closing pi without chatting leaves no file behind. Starting at the user message (not the
+     * first assistant reply) keeps the prompt on disk if the first turn never completes (#10000).
+     */
+    private _hasConversation;
     _persist(entry: SessionEntry): void;
     private _appendEntry;
     /** Append a message as child of current leaf, then advance leaf. Returns entry id.
@@ -237,7 +268,7 @@ export declare class SessionManager {
     /** 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;
+    appendCompaction<T = unknown>(summary: string, firstKeptEntryId: string | null, 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. */
     appendCustomEntry(customType: string, data?: unknown): string;
     /** Append a session info entry (e.g., display name). Returns entry id. */
@@ -253,6 +284,8 @@ export declare class SessionManager {
      * @returns Entry id
      */
     appendCustomMessageEntry<T = unknown>(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details?: T): string;
+    /** Append a branch-local edit to an earlier model-visible entry. */
+    appendContextEdit(targetId: string, replacement: ContextEditEntry["replacement"]): string;
     getLeafId(): string | null;
     getLeafEntry(): SessionEntry | undefined;
     getEntry(id: string): SessionEntry | undefined;
@@ -285,11 +318,14 @@ export declare class SessionManager {
      * Build the session context (what gets sent to the LLM).
      * Uses tree traversal from current leaf.
      */
+    buildSessionProjection(): SessionProjection;
     buildSessionContext(): SessionContext;
     /**
      * Get session header.
      */
     getHeader(): SessionHeader | null;
+    /** Number of session entries (excludes header), without copying them like `getEntries()`. */
+    getEntryCount(): number;
     /**
      * Get all session entries (excludes header). Returns a shallow copy.
      * The session is append-only: use appendXXX() to add entries, branch() to

package/dist/core/session-manager.js

@@ -232,10 +232,55 @@ export function buildContextEntries(entries, leafId, byId) {
  * If leafId is provided, walks from that entry to root.
  * Handles compaction and branch summaries along the path.
  */
-export function buildSessionContext(entries, leafId, byId) {
+function projectContextEntry(entry, edit) {
+    const messages = sessionEntryToContextMessages(entry);
+    if (!edit)
+        return messages;
+    const replacement = edit.replacement;
+    if (replacement === null)
+        return [];
+    return messages.map((message) => {
+        if (message.role !== "user" &&
+            message.role !== "assistant" &&
+            message.role !== "toolResult" &&
+            message.role !== "custom") {
+            return message;
+        }
+        const content = (message.role === "assistant" || message.role === "toolResult") && typeof replacement.content === "string"
+            ? [{ type: "text", text: replacement.content }]
+            : replacement.content;
+        return { ...message, content };
+    });
+}
+/** Build provenance-preserving, compaction-aware model context. */
+export function buildSessionProjection(entries, leafId, byId) {
     const path = buildSessionPath(entries, leafId, byId);
     const { thinkingLevel, model } = getSessionContextSettings(path);
-    const messages = buildContextEntries(entries, leafId, byId).flatMap(sessionEntryToContextMessages);
+    const contextEntries = buildContextEntries(entries, leafId, byId);
+    const edits = new Map();
+    for (const entry of contextEntries) {
+        if (entry.type === "context_edit")
+            edits.set(entry.targetId, entry);
+    }
+    const projectedEntries = contextEntries.map((sourceEntry, index) => ({
+        sourceEntry,
+        // buildContextEntries() may retain an older compaction entry because its
+        // raw ID lies inside the newest retained range. Only the newest compaction
+        // at index zero contributes a checkpoint and summary.
+        messages: sourceEntry.type === "compaction" && index > 0
+            ? []
+            : projectContextEntry(sourceEntry, edits.get(sourceEntry.id)),
+    }));
+    return {
+        entries: projectedEntries,
+        messages: projectedEntries.flatMap((entry) => entry.messages),
+        thinkingLevel,
+        model,
+    };
+}
+/** Build the finalized model context from the canonical session projection. */
+export function buildSessionContext(entries, leafId, byId) {
+    const { messages, thinkingLevel, model } = buildSessionProjection(entries, leafId, byId);
     return { messages, thinkingLevel, model };
 }
 /**
@@ -737,21 +782,21 @@ export class SessionManager {
     getSessionFile() {
         return this.sessionFile;
     }
+    /**
+     * A new session file is created only once the session contains a user or assistant message.
+     * Setup entries alone (model, thinking level, system prompt) stay in memory so opening and
+     * closing pi without chatting leaves no file behind. Starting at the user message (not the
+     * first assistant reply) keeps the prompt on disk if the first turn never completes (#10000).
+     */
+    _hasConversation() {
+        return this.fileEntries.some((e) => e.type === "message" && (e.message.role === "user" || e.message.role === "assistant"));
+    }
     _persist(entry) {
         if (!this.persist || !this.sessionFile)
             return;
-        const hasAssistant = this.fileEntries.some((e) => e.type === "message" && e.message.role === "assistant");
-        if (!hasAssistant) {
-            if (this.flushed) {
-                appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
-            }
-            else {
-                // Mark as not flushed so when assistant arrives, all entries get written
-                this.flushed = false;
-            }
-            return;
-        }
         if (!this.flushed) {
+            if (!this._hasConversation())
+                return;
             const fd = openSync(this.sessionFile, "wx");
             try {
                 for (const e of this.fileEntries) {
@@ -834,14 +879,15 @@ export class SessionManager {
     /** 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 systemMessage = getCurrentSystemMessage(this.buildSessionProjection().messages);
+        const id = generateId(this.byId);
         const entry = {
             type: "compaction",
-            id: generateId(this.byId),
+            id,
             parentId: this.leafId,
             timestamp,
             summary,
-            firstKeptEntryId,
+            firstKeptEntryId: firstKeptEntryId ?? id,
             tokensBefore,
             details,
             usage,
@@ -880,10 +926,10 @@ export class SessionManager {
     /** Get the current session name from the latest session_info entry, if any. */
     getSessionName() {
         // Walk entries in reverse to find the latest session_info entry.
-        // Empty names explicitly clear the session title.
-        const entries = this.getEntries();
-        for (let i = entries.length - 1; i >= 0; i--) {
-            const entry = entries[i];
+        // Empty names explicitly clear the session title. Reads fileEntries directly: the footer
+        // calls this on every frame, and getEntries() copies the whole session.
+        for (let i = this.fileEntries.length - 1; i >= 0; i--) {
+            const entry = this.fileEntries[i];
             if (entry.type === "session_info") {
                 return entry.name?.trim() || undefined;
             }
@@ -912,6 +958,44 @@ export class SessionManager {
         this._appendEntry(entry);
         return entry.id;
     }
+    /** Append a branch-local edit to an earlier model-visible entry. */
+    appendContextEdit(targetId, replacement) {
+        if (replacement !== null &&
+            (typeof replacement !== "object" ||
+                !("content" in replacement) ||
+                (typeof replacement.content !== "string" && !Array.isArray(replacement.content)))) {
+            throw new Error("Context edit replacement must be null or contain string/array content");
+        }
+        const target = this.byId.get(targetId);
+        if (!target)
+            throw new Error(`Entry ${targetId} not found`);
+        if (!this.getBranch().some((entry) => entry.id === targetId)) {
+            throw new Error(`Entry ${targetId} is not on the active branch`);
+        }
+        const editable = target.type === "custom_message" ||
+            (target.type === "message" &&
+                (target.message.role === "user" ||
+                    target.message.role === "assistant" ||
+                    target.message.role === "toolResult"));
+        if (!editable)
+            throw new Error(`Entry ${targetId} does not contribute editable model content`);
+        const targetRole = target.type === "message" ? target.message.role : "custom";
+        const normalizedReplacement = replacement !== null &&
+            (targetRole === "assistant" || targetRole === "toolResult") &&
+            typeof replacement.content === "string"
+            ? { content: [{ type: "text", text: replacement.content }] }
+            : replacement;
+        const entry = {
+            type: "context_edit",
+            id: generateId(this.byId),
+            parentId: this.leafId,
+            timestamp: new Date().toISOString(),
+            targetId,
+            replacement: normalizedReplacement,
+        };
+        this._appendEntry(entry);
+        return entry.id;
+    }
     // =========================================================================
     // Tree Traversal
     // =========================================================================
@@ -997,8 +1081,12 @@ export class SessionManager {
      * Build the session context (what gets sent to the LLM).
      * Uses tree traversal from current leaf.
      */
+    buildSessionProjection() {
+        return buildSessionProjection(this.getEntries(), this.leafId, this.byId);
+    }
     buildSessionContext() {
-        return buildSessionContext(this.getEntries(), this.leafId, this.byId);
+        const { messages, thinkingLevel, model } = this.buildSessionProjection();
+        return { messages, thinkingLevel, model };
     }
     /**
      * Get session header.
@@ -1007,6 +1095,10 @@ export class SessionManager {
         const h = this.fileEntries.find((e) => e.type === "session");
         return h ? h : null;
     }
+    /** Number of session entries (excludes header), without copying them like `getEntries()`. */
+    getEntryCount() {
+        return this.byId.size;
+    }
     /**
      * Get all session entries (excludes header). Returns a shallow copy.
      * The session is append-only: use appendXXX() to add entries, branch() to
@@ -1089,13 +1181,14 @@ export class SessionManager {
         if (branchFromId !== null && !this.byId.has(branchFromId)) {
             throw new Error(`Entry ${branchFromId} not found`);
         }
+        const fromId = this.leafId ?? "root";
         this.leafId = branchFromId;
         const entry = {
             type: "branch_summary",
             id: generateId(this.byId),
             parentId: branchFromId,
             timestamp: new Date().toISOString(),
-            fromId: branchFromId ?? "root",
+            fromId,
             summary,
             details,
             usage,
@@ -1135,7 +1228,9 @@ export class SessionManager {
                 ? {
                     ...entry,
                     parentId: pathParentId,
-                    firstKeptEntryId: replacementByLabelId.get(entry.firstKeptEntryId) ?? entry.firstKeptEntryId,
+                    firstKeptEntryId: entry.firstKeptEntryId === entry.id
+                        ? entry.id
+                        : (replacementByLabelId.get(entry.firstKeptEntryId) ?? entry.firstKeptEntryId),
                 }
                 : { ...entry, parentId: pathParentId });
             pathParentId = entry.id;
@@ -1182,13 +1277,9 @@ export class SessionManager {
             this.sessionId = newSessionId;
             this.sessionFile = newSessionFile;
             this._buildIndex();
-            // Only write the file now if it contains an assistant message.
-            // Otherwise defer to _persist(), which creates the file on the
-            // first assistant response, matching the newSession() contract
-            // and avoiding the duplicate-header bug when _persist()'s
-            // no-assistant guard later resets flushed to false.
-            const hasAssistant = this.fileEntries.some((e) => e.type === "message" && e.message.role === "assistant");
-            if (hasAssistant) {
+            // Use the same rule as _persist(): write now if the branched path already
+            // has a conversation, otherwise let _persist() create the file later.
+            if (this._hasConversation()) {
                 this._rewriteFile();
                 this.flushed = true;
             }
@@ -1385,7 +1476,9 @@ export class SessionManager {
             if (!existsSync(sessionsDir))
                 return [];
             const entries = await readdir(sessionsDir, { withFileTypes: true });
-            const dirs = entries.filter((e) => e.isDirectory()).map((e) => join(sessionsDir, e.name));
+            const dirs = entries
+                .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+                .map((entry) => join(sessionsDir, entry.name));
             const dirFiles = await mapWithConcurrency(dirs, MAX_CONCURRENT_SESSION_DISCOVERY_LOADS, async (dir) => {
                 try {
                     return (await readdir(dir)).filter((file) => file.endsWith(".jsonl")).map((file) => join(dir, file));

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

@@ -0,0 +1,8 @@
+import type { AgentSessionRuntimeDiagnostic } from "./agent-session-services.ts";
+import type { SettingsManager } from "./settings-manager.ts";
+export declare function collectSettingsDiagnostics(settingsManager: SettingsManager): AgentSessionRuntimeDiagnostic[];
+/**
+ * Remove duplicate type/message diagnostics while preserving their first occurrence.
+ * Startup and runtime settings managers can report the same file error.
+ */
+export declare function deduplicateDiagnostics(diagnostics: readonly AgentSessionRuntimeDiagnostic[]): AgentSessionRuntimeDiagnostic[];