@getpaseo/server 0.1.82 → 0.1.84

package/dist/server/server/session.js

@@ -6,10 +6,10 @@ import { realpathSync } from "node:fs";
 import { basename, resolve, sep } from "path";
 import { homedir } from "node:os";
 import { z } from "zod";
-import { CLIENT_CAPS } from "../shared/client-capabilities.js";
+import { CLIENT_CAPS } from "@getpaseo/protocol/client-capabilities";
 import { isLegacyEditorTargetId, serializeAgentStreamEvent, } from "./messages.js";
 import { TerminalSessionController } from "../terminal/terminal-session-controller.js";
-import { encodeFileTransferFrame, FileTransferOpcode, } from "../shared/binary-frames/index.js";
+import { encodeFileTransferFrame, FileTransferOpcode, } from "@getpaseo/protocol/binary-frames/index";
 import { CursorError } from "./pagination/cursor.js";
 import { SortablePager } from "./pagination/sortable-pager.js";
 import { TTSManager } from "./agent/tts-manager.js";
@@ -23,19 +23,19 @@ import { DictationStreamManager, } from "./dictation/dictation-stream-manager.js
 import { createVoiceTurnController, } from "./voice/voice-turn-controller.js";
 import { buildConfigOverrides, extractTimestamps, isStoredAgentProviderAvailable, toAgentPersistenceHandle, } from "./persistence-hooks.js";
 import { ensureAgentLoaded } from "./agent/agent-loading.js";
-import { formatSystemNotificationPrompt, sendPromptToAgent, unarchiveAgentState, } from "./agent/agent-prompt.js";
+import { formatSystemNotificationPrompt, sendPromptToAgent, waitForAgentRunStartWithTimeout, unarchiveAgentState, } from "./agent/agent-prompt.js";
+import { resolveCreateAgentTitles } from "./agent/create-agent-title.js";
+import { respondToAgentPermission } from "./agent/permission-response.js";
 import { experimental_createMCPClient } from "ai";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { buildWorkspaceScriptPayloads, readPaseoConfigForProjection, } from "./script-status-projection.js";
 import { deriveProjectSlug } from "./workspace-git-metadata.js";
 import { spawnWorkspaceScript } from "./worktree-bootstrap.js";
-import { applyMutableProviderConfigToOverrides } from "./daemon-config-store.js";
-import { getErrorMessage, getErrorMessageOr } from "../shared/error-utils.js";
-import { getAgentStatusPriority } from "../shared/agent-state-bucket.js";
-import { buildProviderRegistry } from "./agent/provider-registry.js";
+import { getErrorMessage, getErrorMessageOr } from "@getpaseo/protocol/error-utils";
+import { getAgentStatusPriority } from "@getpaseo/protocol/agent-state-bucket";
 import { resolveSnapshotCwd } from "./agent/provider-snapshot-manager.js";
-import { scheduleAgentMetadataGeneration } from "./agent/agent-metadata-generator.js";
-import { resolveCreateAgentTitles } from "./agent/create-agent-title.js";
+import { createAgentCommand } from "./agent/create-agent/create.js";
+import { archiveAgentCommand, cancelAgentRunCommand, closeAgentCommand, setAgentModeCommand, updateAgentCommand, } from "./agent/lifecycle-command.js";
 import { buildStoredAgentPayload, resolveEffectiveThinkingOptionId, resolveStoredAgentPayloadUpdatedAt, toAgentPayload, } from "./agent/agent-projections.js";
 import { appendTimelineItemIfAgentKnown, emitLiveTimelineItemIfAgentKnown, } from "./agent/timeline-append.js";
 import { projectTimelineRows, selectTimelineWindowByProjectedLimit, } from "./agent/timeline-projection.js";
@@ -59,7 +59,6 @@ import { searchHomeDirectories, searchWorkspaceEntries } from "../utils/director
 import { toCheckoutError } from "./checkout-git-utils.js";
 import { buildCheckoutPrStatusPayloadFromSnapshot, buildCheckoutStatusPayloadFromSnapshot, } from "./checkout/status-projection.js";
 import { toResolver } from "./speech/provider-resolver.js";
-import { resolveClientMessageId } from "./client-message-id.js";
 import { ChatServiceError, parseMentionAgentIds, } from "./chat/chat-service.js";
 import { notifyChatMentions, prepareChatMentionFanout } from "./chat/chat-mentions.js";
 import { execCommand } from "../utils/spawn.js";
@@ -105,6 +104,14 @@ function stripTrailingPathSeparators(path) {
 // Clients before 0.1.45 validate providers with z.enum(["claude", "codex", "opencode"]) and reject
 // the entire session message if they encounter an unknown provider.
 const LEGACY_PROVIDER_IDS = new Set(["claude", "codex", "opencode"]);
+// COMPAT(customModeIcons): the only mode icons known to clients before v0.1.84. Any
+// other icon name is downgraded to "ShieldCheck" for those clients.
+const LEGACY_MODE_ICONS = new Set([
+    "ShieldCheck",
+    "ShieldAlert",
+    "ShieldOff",
+    "ShieldQuestionMark",
+]);
 const MIN_VERSION_ALL_PROVIDERS = "0.1.45";
 const MIN_VERSION_FLEXIBLE_EDITOR_IDS = "0.1.50";
 function errorToFriendlyMessage(error) {
@@ -327,7 +334,7 @@ export class Session {
                 }
             },
         });
-        const { clientId, appVersion, clientCapabilities, onMessage, onBinaryMessage, onLifecycleIntent, logger, downloadTokenStore, pushTokenStore, paseoHome, agentManager, agentStorage, projectRegistry, workspaceRegistry, chatService, scheduleService, loopService, checkoutDiffManager, github, workspaceGitService, daemonConfigStore, mcpBaseUrl, stt, sttLanguage, tts, terminalManager, providerSnapshotManager, scriptRouteStore, scriptRuntimeStore, workspaceSetupSnapshots, onBranchChanged, getDaemonTcpPort, getDaemonTcpHost, resolveScriptHealth, voice, voiceBridge, dictation, agentProviderRuntimeSettings, providerOverrides, isDev, serverId, daemonVersion, daemonRuntimeConfig, } = options;
+        const { clientId, appVersion, clientCapabilities, onMessage, onBinaryMessage, onLifecycleIntent, logger, downloadTokenStore, pushTokenStore, paseoHome, agentManager, agentStorage, projectRegistry, workspaceRegistry, chatService, scheduleService, loopService, checkoutDiffManager, github, workspaceGitService, daemonConfigStore, mcpBaseUrl, stt, sttLanguage, tts, terminalManager, providerSnapshotManager, scriptRouteStore, scriptRuntimeStore, workspaceSetupSnapshots, onBranchChanged, getDaemonTcpPort, getDaemonTcpHost, resolveScriptHealth, voice, voiceBridge, dictation, serverId, daemonVersion, daemonRuntimeConfig, } = options;
         this.clientId = clientId;
         this.appVersion = appVersion ?? null;
         this.clientCapabilities = parseClientCapabilities(clientCapabilities);
@@ -389,7 +396,7 @@ export class Session {
             killTerminalsUnderPath: (rootPath) => this.terminalController.killTerminalsUnderPath(rootPath),
             logger: this.sessionLogger,
         });
-        this.providerSnapshotManager = providerSnapshotManager ?? null;
+        this.providerSnapshotManager = providerSnapshotManager;
         this.scriptRouteStore = scriptRouteStore ?? null;
         this.scriptRuntimeStore = scriptRuntimeStore ?? null;
         this.workspaceSetupSnapshots = workspaceSetupSnapshots ?? new Map();
@@ -400,9 +407,6 @@ export class Session {
         this.sttLanguage = sttLanguage ?? "en";
         this.subscribeToOptionalManagers();
         this.bindVoiceBridges({ voice, voiceBridge, dictation });
-        this.agentProviderRuntimeSettings = agentProviderRuntimeSettings;
-        this.providerOverrides = providerOverrides;
-        this.isDev = isDev === true;
         this.serverId = serverId;
         this.daemonVersion = daemonVersion;
         this.daemonRuntimeConfig = daemonRuntimeConfig;
@@ -432,6 +436,19 @@ export class Session {
     supports(capability) {
         return this.clientCapabilities.has(capability);
     }
+    // COMPAT(customModeIcons): rewrite icons unknown to v0.1.83 clients (whose MODE_ICONS
+    // map is a closed enum and would render `undefined`, crashing in render). Drop
+    // this and the cap gate when floor >= v0.1.84.
+    downgradeModeIconsForClient(modes) {
+        if (this.supports(CLIENT_CAPS.customModeIcons))
+            return modes;
+        return modes.map((mode) => mode.icon && !LEGACY_MODE_ICONS.has(mode.icon) ? { ...mode, icon: "ShieldCheck" } : mode);
+    }
+    downgradeEntryModesForClient(entries) {
+        if (this.supports(CLIENT_CAPS.customModeIcons))
+            return entries;
+        return entries.map((entry) => entry.modes ? { ...entry, modes: this.downgradeModeIconsForClient(entry.modes) } : entry);
+    }
     async syncWorkspaceGitObserverForWorkspace(workspace) {
         const descriptor = await this.describeWorkspaceRecordWithGitData(workspace);
         this.syncWorkspaceGitObservers([descriptor]);
@@ -538,41 +555,6 @@ export class Session {
         }
         return this.agentManager.hasInFlightRun(agentId);
     }
-    /**
-     * Start streaming an agent run and forward results via the websocket broadcast
-     */
-    startAgentStream(agentId, prompt, runOptions) {
-        this.sessionLogger.trace({
-            agentId,
-            promptType: typeof prompt === "string" ? "string" : "structured",
-            hasRunOptions: Boolean(runOptions),
-        }, "agent.session.start_stream.request");
-        let iterator;
-        try {
-            const shouldReplace = this.agentManager.hasInFlightRun(agentId);
-            iterator = shouldReplace
-                ? this.agentManager.replaceAgentRun(agentId, prompt, runOptions)
-                : this.agentManager.streamAgent(agentId, prompt, runOptions);
-            this.sessionLogger.trace({ agentId, shouldReplace }, "agent.session.start_stream.iterator_returned");
-        }
-        catch (error) {
-            this.handleAgentRunError(agentId, error, "Failed to start agent run");
-            return { ok: false, error: errorToFriendlyMessage(error) };
-        }
-        void (async () => {
-            try {
-                for await (const _ of iterator) {
-                    // Events are forwarded via the session's AgentManager subscription.
-                }
-                this.sessionLogger.trace({ agentId }, "agent.session.iterator.drained");
-            }
-            catch (error) {
-                this.sessionLogger.trace({ agentId, err: error }, "agent.session.iterator.error");
-                this.handleAgentRunError(agentId, error, "Agent stream failed");
-            }
-        })();
-        return { ok: true };
-    }
     handleAgentRunError(agentId, error, context) {
         const message = errorToFriendlyMessage(error);
         this.sessionLogger.error({ err: error, agentId, context }, `${context} for agent ${agentId}`);
@@ -612,25 +594,23 @@ export class Session {
      */
     subscribeToOptionalManagers() {
         this.terminalController.start();
-        if (this.providerSnapshotManager) {
-            const handleProviderSnapshotChange = (entries, cwd) => {
-                // COMPAT(providersSnapshot): keep provider visibility gating for older clients.
-                const visibleEntries = entries.filter((entry) => this.isProviderVisibleToClient(entry.provider));
-                const snapshotCwd = cwd === resolveSnapshotCwd() ? undefined : cwd;
-                this.emit({
-                    type: "providers_snapshot_update",
-                    payload: {
-                        ...(snapshotCwd ? { cwd: snapshotCwd } : {}),
-                        entries: visibleEntries,
-                        generatedAt: new Date().toISOString(),
-                    },
-                });
-            };
-            this.providerSnapshotManager.on("change", handleProviderSnapshotChange);
-            this.unsubscribeProviderSnapshotEvents = () => {
-                this.providerSnapshotManager?.off("change", handleProviderSnapshotChange);
-            };
-        }
+        const handleProviderSnapshotChange = (entries, cwd) => {
+            // COMPAT(providersSnapshot): keep provider visibility gating for older clients.
+            const visibleEntries = entries.filter((entry) => this.isProviderVisibleToClient(entry.provider));
+            const snapshotCwd = cwd === resolveSnapshotCwd() ? undefined : cwd;
+            this.emit({
+                type: "providers_snapshot_update",
+                payload: {
+                    ...(snapshotCwd ? { cwd: snapshotCwd } : {}),
+                    entries: this.downgradeEntryModesForClient(visibleEntries),
+                    generatedAt: new Date().toISOString(),
+                },
+            });
+        };
+        this.providerSnapshotManager.on("change", handleProviderSnapshotChange);
+        this.unsubscribeProviderSnapshotEvents = () => {
+            this.providerSnapshotManager.off("change", handleProviderSnapshotChange);
+        };
     }
     bindVoiceBridges(params) {
         const { voice, voiceBridge, dictation } = params;
@@ -771,18 +751,7 @@ export class Session {
         payload.archivedAt = storedRecord?.archivedAt ?? null;
         return payload;
     }
-    getProviderRegistry() {
-        return buildProviderRegistry(this.sessionLogger, {
-            runtimeSettings: this.agentProviderRuntimeSettings,
-            providerOverrides: applyMutableProviderConfigToOverrides(this.providerOverrides, this.daemonConfigStore.get().providers),
-            workspaceGitService: this.workspaceGitService,
-            isDev: this.isDev,
-        });
-    }
-    getRegisteredProviderIds() {
-        return Object.keys(this.getProviderRegistry());
-    }
-    buildStoredAgentPayload(record, registeredProviderIds = this.getRegisteredProviderIds()) {
+    buildStoredAgentPayload(record, registeredProviderIds = this.providerSnapshotManager.listRegisteredProviderIds()) {
         return buildStoredAgentPayload(record, registeredProviderIds);
     }
     isProviderVisibleToClient(provider) {
@@ -1523,7 +1492,7 @@ export class Session {
         // File-backed storage still needs an early delete fence before closeAgent().
         beginAgentDeleteIfSupported(this.agentStorage, agentId);
         try {
-            await this.agentManager.closeAgent(agentId);
+            await closeAgentCommand({ agentManager: this.agentManager }, agentId);
         }
         catch (error) {
             this.sessionLogger.warn({ err: error, agentId }, `Failed to close agent ${agentId} during delete`);
@@ -1567,35 +1536,12 @@ export class Session {
             },
         });
     }
-    async archiveStoredAgentForClose(agentId) {
-        const existing = await this.agentStorage.get(agentId);
-        if (!existing) {
-            throw new Error(`Agent not found: ${agentId}`);
-        }
-        if (existing.archivedAt) {
-            return {
-                agentId,
-                archivedAt: existing.archivedAt,
-            };
-        }
-        const archivedAt = new Date().toISOString();
-        await this.agentManager.archiveSnapshot(agentId, archivedAt);
-        return { agentId, archivedAt };
-    }
     async archiveAgentForClose(agentId) {
-        const liveAgent = this.agentManager.getAgent(agentId);
-        if (liveAgent) {
-            await this.interruptAgentIfRunning(agentId);
-            await this.agentManager.clearAgentAttention(agentId).catch(() => undefined);
-            await this.agentManager.archiveAgent(agentId);
-        }
-        else {
-            await this.archiveStoredAgentForClose(agentId);
-        }
-        const archivedRecord = await this.agentStorage.get(agentId);
-        if (!archivedRecord) {
-            throw new Error(`Agent not found in storage after archive: ${agentId}`);
-        }
+        const { archivedAt, record: archivedRecord } = await archiveAgentCommand({
+            agentManager: this.agentManager,
+            agentStorage: this.agentStorage,
+            logger: this.sessionLogger,
+        }, agentId);
         if (this.agentUpdatesSubscription) {
             const payload = this.buildStoredAgentPayload(archivedRecord);
             const project = await this.buildProjectPlacementForCwd(payload.cwd);
@@ -1624,10 +1570,7 @@ export class Session {
             }
             await this.emitWorkspaceUpdateForCwd(payload.cwd);
         }
-        if (!archivedRecord.archivedAt) {
-            throw new Error(`Agent missing archivedAt after archive: ${agentId}`);
-        }
-        return { agentId, archivedAt: archivedRecord.archivedAt };
+        return { agentId, archivedAt };
     }
     async handleCloseItemsRequest(msg) {
         const archiveResults = await Promise.allSettled(msg.agentIds.map((agentId) => this.archiveAgentForClose(agentId)));
@@ -1679,25 +1622,20 @@ export class Session {
             hasName: typeof name === "string",
             labelCount: labels ? Object.keys(labels).length : 0,
         }, "session: update_agent_request");
-        const normalizedName = name?.trim();
-        const normalizedLabels = labels && Object.keys(labels).length > 0 ? labels : undefined;
-        if (!normalizedName && !normalizedLabels) {
-            this.emit({
-                type: "update_agent_response",
-                payload: {
-                    requestId,
-                    agentId,
-                    accepted: false,
-                    error: "Nothing to update (provide name and/or labels)",
-                },
-            });
-            return;
-        }
         try {
-            await this.agentManager.updateAgentMetadata(agentId, {
-                ...(normalizedName ? { title: normalizedName } : {}),
-                ...(normalizedLabels ? { labels: normalizedLabels } : {}),
-            });
+            const result = await updateAgentCommand({ agentManager: this.agentManager }, { agentId, name, labels });
+            if (!result.accepted) {
+                this.emit({
+                    type: "update_agent_response",
+                    payload: {
+                        requestId,
+                        agentId,
+                        accepted: false,
+                        error: result.error,
+                    },
+                });
+                return;
+            }
             this.emit({
                 type: "update_agent_response",
                 payload: { requestId, agentId, accepted: true, error: null },
@@ -2134,7 +2072,6 @@ export class Session {
                 configTitle: config.title,
                 initialPrompt: trimmedPrompt,
             });
-            const resolvedConfig = config;
             const firstAgentContext = {
                 ...(trimmedPrompt ? { prompt: trimmedPrompt } : {}),
                 ...(attachments && attachments.length > 0 ? { attachments } : {}),
@@ -2147,22 +2084,33 @@ export class Session {
             });
             createdWorktreeForCleanup = createdWorktree;
             const createAgentConfig = createdWorktree
-                ? { ...resolvedConfig, cwd: createdWorktree.worktree.worktreePath }
-                : resolvedConfig;
-            const { sessionConfig, setupContinuation } = await this.buildAgentSessionConfig(createAgentConfig, git, worktreeName, firstAgentContext);
-            let resolvedWorkspace = msg.workspaceId
-                ? await this.workspaceRegistry.get(msg.workspaceId)
-                : ((await this.findWorkspaceByDirectory(sessionConfig.cwd)) ??
-                    (await this.findOrCreateWorkspaceForDirectory(sessionConfig.cwd)));
-            if (!resolvedWorkspace) {
-                throw new Error(`Workspace not found: ${msg.workspaceId}`);
-            }
-            const snapshot = await this.agentManager.createAgent(sessionConfig, undefined, {
+                ? { ...config, cwd: createdWorktree.worktree.worktreePath }
+                : config;
+            const { snapshot, liveSnapshot } = await createAgentCommand({
+                agentManager: this.agentManager,
+                agentStorage: this.agentStorage,
+                logger: this.sessionLogger,
+                paseoHome: this.paseoHome,
+                workspaceGitService: this.workspaceGitService,
+                providerSnapshotManager: this.providerSnapshotManager,
+            }, {
+                kind: "session",
+                config: createAgentConfig,
+                workspaceId: msg.workspaceId,
+                worktreeName,
+                initialPrompt,
+                clientMessageId,
+                outputSchema,
+                images,
+                attachments,
+                git,
                 labels,
-                workspaceId: resolvedWorkspace.workspaceId,
-                initialPrompt: trimmedPrompt,
                 env,
-                initialTitle: provisionalTitle,
+                provisionalTitle,
+                explicitTitle,
+                firstAgentContext,
+                buildSessionConfig: (sessionConfig, gitOptions, legacyWorktreeName, ctx) => this.buildAgentSessionConfig(sessionConfig, gitOptions, legacyWorktreeName, ctx),
+                resolveWorkspace: ({ cwd, workspaceId }) => this.resolveCreateAgentWorkspace(cwd, workspaceId),
             });
             createdAgentId = snapshot.id;
             await this.forwardAgentUpdate(snapshot);
@@ -2171,30 +2119,18 @@ export class Session {
                 agentId: snapshot.id,
                 createdWorktree,
             });
-            await this.sendInitialCreateAgentPrompt({
-                snapshot,
-                trimmedPrompt,
-                images,
-                attachments,
-                clientMessageId,
-                outputSchema,
-                explicitTitle,
-            });
             if (requestId) {
-                const agentPayload = await this.buildAgentPayload(snapshot);
+                const agentPayload = await this.buildAgentPayload(liveSnapshot);
                 this.emit({
                     type: "status",
                     payload: {
                         status: "agent_created",
-                        agentId: snapshot.id,
+                        agentId: liveSnapshot.id,
                         requestId,
                         agent: agentPayload,
                     },
                 });
             }
-            setupContinuation?.startAfterAgentCreate({
-                agentId: snapshot.id,
-            });
             this.sessionLogger.info({ agentId: snapshot.id, provider: snapshot.provider }, `Created agent ${snapshot.id} (${snapshot.provider})`);
         }
         catch (error) {
@@ -2226,28 +2162,15 @@ export class Session {
             });
         }
     }
-    async sendInitialCreateAgentPrompt(params) {
-        const { snapshot, trimmedPrompt, images, attachments, clientMessageId, outputSchema } = params;
-        const hasPrompt = Boolean(trimmedPrompt);
-        const hasImages = (images?.length ?? 0) > 0;
-        const hasAttachments = (attachments?.length ?? 0) > 0;
-        if (!hasPrompt && !hasImages && !hasAttachments) {
-            return;
-        }
-        scheduleAgentMetadataGeneration({
-            agentManager: this.agentManager,
-            agentId: snapshot.id,
-            cwd: snapshot.cwd,
-            workspaceGitService: this.workspaceGitService,
-            initialPrompt: trimmedPrompt,
-            explicitTitle: params.explicitTitle,
-            paseoHome: this.paseoHome,
-            logger: this.sessionLogger,
-        });
-        const started = await this.handleSendAgentMessage(snapshot.id, trimmedPrompt || "", resolveClientMessageId(clientMessageId), images, attachments, outputSchema ? { outputSchema } : undefined);
-        if (!started.ok) {
-            throw new Error(started.error);
+    async resolveCreateAgentWorkspace(cwd, workspaceId) {
+        const resolvedWorkspace = workspaceId
+            ? await this.workspaceRegistry.get(workspaceId)
+            : ((await this.findWorkspaceByDirectory(cwd)) ??
+                (await this.findOrCreateWorkspaceForDirectory(cwd)));
+        if (!resolvedWorkspace) {
+            throw new Error(`Workspace not found: ${workspaceId}`);
         }
+        return { workspaceId: resolvedWorkspace.workspaceId };
     }
     async handleResumeAgentRequest(msg) {
         const { handle, overrides, requestId } = msg;
@@ -2400,11 +2323,11 @@ export class Session {
                 if (!record) {
                     throw new Error(`Agent not found: ${agentId}`);
                 }
-                const providerRegistry = this.getProviderRegistry();
-                if (!isStoredAgentProviderAvailable(record, Object.keys(providerRegistry))) {
+                const registeredProviderIds = this.providerSnapshotManager.listRegisteredProviderIds();
+                if (!isStoredAgentProviderAvailable(record, registeredProviderIds)) {
                     throw new Error(`Agent ${agentId} references unavailable provider '${record.provider}'`);
                 }
-                const handle = toAgentPersistenceHandle(providerRegistry, record.persistence);
+                const handle = toAgentPersistenceHandle(registeredProviderIds, record.persistence);
                 if (!handle) {
                     throw new Error(`Agent ${agentId} cannot be refreshed because it lacks persistence`);
                 }
@@ -2453,7 +2376,7 @@ export class Session {
     async handleCancelAgentRequest(agentId, requestId) {
         this.sessionLogger.info({ agentId }, `Cancel request received for agent ${agentId}`);
         try {
-            await this.interruptAgentIfRunning(agentId);
+            await cancelAgentRunCommand({ agentManager: this.agentManager, logger: this.sessionLogger }, agentId);
             if (requestId) {
                 const agent = this.agentManager.getAgent(agentId);
                 const payload = agent ? await this.buildAgentPayload(agent) : null;
@@ -2575,43 +2498,6 @@ export class Session {
     async handleListProviderModelsRequest(msg) {
         const cwd = resolveSnapshotCwd(msg.cwd ? expandTilde(msg.cwd) : undefined);
         const fetchedAt = new Date().toISOString();
-        const manager = this.providerSnapshotManager;
-        if (!manager) {
-            try {
-                const definition = this.getProviderRegistry()[msg.provider];
-                if (!definition.enabled) {
-                    this.emitProviderDisabledResponse("models", msg.provider, msg.requestId, fetchedAt);
-                    return;
-                }
-                const models = await definition.fetchModels({
-                    cwd,
-                    force: false,
-                });
-                this.emit({
-                    type: "list_provider_models_response",
-                    payload: {
-                        provider: msg.provider,
-                        models,
-                        error: null,
-                        fetchedAt,
-                        requestId: msg.requestId,
-                    },
-                });
-            }
-            catch (error) {
-                this.sessionLogger.error({ err: error, provider: msg.provider }, `Failed to list models for ${msg.provider}`);
-                this.emit({
-                    type: "list_provider_models_response",
-                    payload: {
-                        provider: msg.provider,
-                        error: getErrorMessage(error),
-                        fetchedAt,
-                        requestId: msg.requestId,
-                    },
-                });
-            }
-            return;
-        }
         const entry = await this.getProviderSnapshotEntryForRead(cwd, msg.provider);
         if (!entry) {
             this.emit({
@@ -2658,91 +2544,51 @@ export class Session {
     async handleListProviderModesRequest(msg) {
         const fetchedAt = new Date().toISOString();
         const cwd = resolveSnapshotCwd(msg.cwd ? expandTilde(msg.cwd) : undefined);
-        const manager = this.providerSnapshotManager;
-        if (manager) {
-            const entry = await this.getProviderSnapshotEntryForRead(cwd, msg.provider);
-            if (!entry) {
-                this.emit({
-                    type: "list_provider_modes_response",
-                    payload: {
-                        provider: msg.provider,
-                        error: `Unknown provider: ${msg.provider}`,
-                        fetchedAt,
-                        requestId: msg.requestId,
-                    },
-                });
-                return;
-            }
-            if (!entry.enabled) {
-                this.emitProviderDisabledResponse("modes", msg.provider, msg.requestId, fetchedAt);
-                return;
-            }
-            if (entry.status === "ready") {
-                this.emit({
-                    type: "list_provider_modes_response",
-                    payload: {
-                        provider: msg.provider,
-                        modes: entry.modes ?? [],
-                        error: null,
-                        fetchedAt: entry.fetchedAt ?? fetchedAt,
-                        requestId: msg.requestId,
-                    },
-                });
-                return;
-            }
-            const errorMessage = entry.status === "error"
-                ? (entry.error ?? `Failed to list modes for ${msg.provider}`)
-                : `Provider ${msg.provider} is not available`;
+        const entry = await this.getProviderSnapshotEntryForRead(cwd, msg.provider);
+        if (!entry) {
             this.emit({
                 type: "list_provider_modes_response",
                 payload: {
                     provider: msg.provider,
-                    error: errorMessage,
+                    error: `Unknown provider: ${msg.provider}`,
                     fetchedAt,
                     requestId: msg.requestId,
                 },
             });
             return;
         }
-        try {
-            const definition = this.getProviderRegistry()[msg.provider];
-            if (!definition.enabled) {
-                this.emitProviderDisabledResponse("modes", msg.provider, msg.requestId, fetchedAt);
-                return;
-            }
-            const modes = await definition.fetchModes({
-                cwd,
-                force: false,
-            });
-            this.emit({
-                type: "list_provider_modes_response",
-                payload: {
-                    provider: msg.provider,
-                    modes,
-                    error: null,
-                    fetchedAt,
-                    requestId: msg.requestId,
-                },
-            });
+        if (!entry.enabled) {
+            this.emitProviderDisabledResponse("modes", msg.provider, msg.requestId, fetchedAt);
+            return;
         }
-        catch (error) {
-            this.sessionLogger.error({ err: error, provider: msg.provider }, `Failed to list modes for ${msg.provider}`);
+        if (entry.status === "ready") {
             this.emit({
                 type: "list_provider_modes_response",
                 payload: {
                     provider: msg.provider,
-                    error: getErrorMessage(error),
-                    fetchedAt,
+                    modes: this.downgradeModeIconsForClient(entry.modes ?? []),
+                    error: null,
+                    fetchedAt: entry.fetchedAt ?? fetchedAt,
                     requestId: msg.requestId,
                 },
             });
+            return;
         }
+        const errorMessage = entry.status === "error"
+            ? (entry.error ?? `Failed to list modes for ${msg.provider}`)
+            : `Provider ${msg.provider} is not available`;
+        this.emit({
+            type: "list_provider_modes_response",
+            payload: {
+                provider: msg.provider,
+                error: errorMessage,
+                fetchedAt,
+                requestId: msg.requestId,
+            },
+        });
     }
     async getProviderSnapshotEntryForRead(cwd, provider) {
         const manager = this.providerSnapshotManager;
-        if (!manager) {
-            return undefined;
-        }
         const findEntry = () => manager.getSnapshot(cwd).find((candidate) => candidate.provider === provider);
         let entry = findEntry();
         if (entry && !entry.enabled) {
@@ -2901,14 +2747,12 @@ export class Session {
     async handleGetProvidersSnapshotRequest(msg) {
         // COMPAT(providersSnapshot): keep legacy provider-list RPCs alongside snapshot flow.
         const entries = this.providerSnapshotManager
-            ? this.providerSnapshotManager
-                .getSnapshot(msg.cwd ? expandTilde(msg.cwd) : undefined)
-                .filter((entry) => this.isProviderVisibleToClient(entry.provider))
-            : [];
+            .getSnapshot(msg.cwd ? expandTilde(msg.cwd) : undefined)
+            .filter((entry) => this.isProviderVisibleToClient(entry.provider));
         this.emit({
             type: "get_providers_snapshot_response",
             payload: {
-                entries,
+                entries: this.downgradeEntryModesForClient(entries),
                 generatedAt: new Date().toISOString(),
                 requestId: msg.requestId,
             },
@@ -2916,13 +2760,13 @@ export class Session {
     }
     async handleRefreshProvidersSnapshotRequest(msg) {
         if (msg.cwd) {
-            await this.providerSnapshotManager?.refreshSnapshotForCwd({
+            await this.providerSnapshotManager.refreshSnapshotForCwd({
                 cwd: expandTilde(msg.cwd),
                 providers: msg.providers,
             });
         }
         else {
-            await this.providerSnapshotManager?.refreshSettingsSnapshot({
+            await this.providerSnapshotManager.refreshSettingsSnapshot({
                 providers: msg.providers,
             });
         }
@@ -2936,10 +2780,7 @@ export class Session {
     }
     async handleProviderDiagnosticRequest(msg) {
         try {
-            const client = this.getProviderRegistry()[msg.provider].createClient(this.sessionLogger);
-            const diagnostic = client.getDiagnostic
-                ? (await client.getDiagnostic()).diagnostic
-                : "No diagnostic available for this provider.";
+            const { diagnostic } = await this.providerSnapshotManager.getProviderDiagnostic(msg.provider);
             this.emit({
                 type: "provider_diagnostic_response",
                 payload: {
@@ -3175,7 +3016,7 @@ export class Session {
     async handleSetAgentModeRequest(agentId, modeId, requestId) {
         this.sessionLogger.info({ agentId, modeId, requestId }, "session: set_agent_mode_request");
         try {
-            await this.agentManager.setAgentMode(agentId, modeId);
+            await setAgentModeCommand({ agentManager: this.agentManager }, { agentId, modeId });
             this.sessionLogger.info({ agentId, modeId, requestId }, "session: set_agent_mode_request success");
             this.emit({
                 type: "set_agent_mode_response",
@@ -3420,14 +3261,14 @@ export class Session {
      * Handle agent permission response from user
      */
     async handleAgentPermissionResponse(agentId, requestId, response) {
-        this.sessionLogger.debug({ agentId, requestId }, `Handling permission response for agent ${agentId}, request ${requestId}`);
         try {
-            const result = await this.agentManager.respondToPermission(agentId, requestId, response);
-            this.sessionLogger.debug({ agentId }, `Permission response forwarded to agent ${agentId}`);
-            if (result?.followUpPrompt) {
-                this.sessionLogger.debug({ agentId }, "Permission response requires follow-up turn, starting agent stream");
-                this.startAgentStream(agentId, result.followUpPrompt);
-            }
+            await respondToAgentPermission({
+                agentManager: this.agentManager,
+                agentId,
+                requestId,
+                response,
+                logger: this.sessionLogger,
+            });
         }
         catch (error) {
             this.sessionLogger.error({ err: error, agentId, requestId }, "Failed to respond to permission");
@@ -4621,7 +4462,7 @@ export class Session {
         // (excluding internal agents which are for ephemeral system tasks)
         const registryRecords = await this.agentStorage.list();
         const liveIds = new Set(agentSnapshots.map((a) => a.id));
-        const registeredProviderIds = this.getRegisteredProviderIds();
+        const registeredProviderIds = this.providerSnapshotManager.listRegisteredProviderIds();
         const persistedAgents = registryRecords
             .filter((record) => !liveIds.has(record.id) && !record.internal)
             .filter((record) => filter?.includeUnavailablePersisted === true ||
@@ -5358,7 +5199,7 @@ export class Session {
                 request,
                 agentManager: this.agentManager,
                 agentStorage: this.agentStorage,
-                providerRegistry: this.getProviderRegistry(),
+                providerSnapshotManager: this.providerSnapshotManager,
             });
             this.emit({
                 type: "fetch_recent_provider_sessions_response",
@@ -5980,11 +5821,8 @@ export class Session {
                 });
                 return;
             }
-            const startAbort = new AbortController();
-            const startTimeoutMs = 15000;
-            const startTimeout = setTimeout(() => startAbort.abort("timeout"), startTimeoutMs);
             try {
-                await this.agentManager.waitForAgentRunStart(agentId, { signal: startAbort.signal });
+                await waitForAgentRunStartWithTimeout(this.agentManager, agentId);
             }
             catch (error) {
                 this.emit({
@@ -5998,9 +5836,6 @@ export class Session {
                 });
                 return;
             }
-            finally {
-                clearTimeout(startTimeout);
-            }
             this.emit({
                 type: "send_agent_message_response",
                 payload: {