@getpaseo/server 0.1.62 → 0.1.63

package/dist/server/server/agent/agent-manager.js

@@ -8,7 +8,20 @@ import { AGENT_STREAM_COALESCE_DEFAULT_WINDOW_MS, AgentStreamCoalescer, } from "
 import { getAgentProviderDefinition } from "./provider-manifest.js";
 const RELOAD_SESSION_CLOSE_TIMEOUT_MS = 3000;
 const INTERRUPT_SESSION_TIMEOUT_MS = 2000;
+function formatProviderList(providers) {
+    return providers.length > 0 ? providers.join(", ") : "none";
+}
 export { AGENT_LIFECYCLE_STATUSES };
+function resolveInitialAttention(input) {
+    if (input == null || !input.requiresAttention) {
+        return { requiresAttention: false };
+    }
+    return {
+        requiresAttention: true,
+        attentionReason: input.attentionReason,
+        attentionTimestamp: new Date(input.attentionTimestamp),
+    };
+}
 const SYSTEM_ERROR_PREFIX = "[System Error]";
 function attachPersistenceCwd(handle, cwd) {
     if (!handle) {
@@ -17,28 +30,30 @@ function attachPersistenceCwd(handle, cwd) {
     return {
         ...handle,
         metadata: {
-            ...(handle.metadata ?? {}),
+            ...handle.metadata,
             cwd,
         },
     };
 }
-const BUSY_STATUSES = ["initializing", "running"];
+const BUSY_STATUSES = new Set(["initializing", "running"]);
 const AgentIdSchema = z.string().uuid();
 function isAgentBusy(status) {
-    return BUSY_STATUSES.includes(status);
+    return BUSY_STATUSES.has(status);
 }
 function isTurnTerminalEvent(event) {
     return (event.type === "turn_completed" ||
         event.type === "turn_failed" ||
         event.type === "turn_canceled");
 }
+function abortMessage(reason, fallbackMessage) {
+    if (typeof reason === "string")
+        return reason;
+    if (reason instanceof Error)
+        return reason.message;
+    return fallbackMessage;
+}
 function createAbortError(signal, fallbackMessage) {
-    const reason = signal?.reason;
-    const message = typeof reason === "string"
-        ? reason
-        : reason instanceof Error
-            ? reason.message
-            : fallbackMessage;
+    const message = abortMessage(signal?.reason, fallbackMessage);
     return Object.assign(new Error(message), { name: "AbortError" });
 }
 function validateAgentId(agentId, source) {
@@ -55,9 +70,34 @@ function normalizeMessageId(messageId) {
     const trimmed = messageId.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
+function isDuplicateLegacyUserMessage(item, canonicalUserMessagesById) {
+    if (item.type !== "user_message") {
+        return false;
+    }
+    const eventMessageId = normalizeMessageId(item.messageId);
+    if (!eventMessageId) {
+        return false;
+    }
+    return canonicalUserMessagesById.get(eventMessageId) === item.text;
+}
+function buildExplicitTimelineSeedForRegister(now, options) {
+    const hasTimeline = Boolean(options?.timeline?.length);
+    const hasTimelineRows = Boolean(options?.timelineRows?.length);
+    const hasTimelineNextSeq = options?.timelineNextSeq !== undefined;
+    if (!hasTimeline && !hasTimelineRows && !hasTimelineNextSeq) {
+        return null;
+    }
+    return {
+        items: options?.timeline,
+        rows: options?.timelineRows,
+        nextSeq: options?.timelineNextSeq,
+        timestamp: (options?.updatedAt ?? options?.createdAt ?? now).toISOString(),
+    };
+}
 export class AgentManager {
     constructor(options) {
         this.clients = new Map();
+        this.providerEnabled = new Map();
         this.agents = new Map();
         this.timelineStore = new InMemoryAgentTimelineStore();
         this.agentsAwaitingInitialSnapshotPersist = new Set();
@@ -84,17 +124,26 @@ export class AgentManager {
                 this.notifyForegroundTurnWaiters(agentId, event);
             },
         });
-        if (options?.clients) {
-            for (const [provider, client] of Object.entries(options.clients)) {
-                if (client) {
-                    this.registerClient(provider, client);
-                }
-            }
-        }
+        this.updateProviderRegistry({
+            providerDefinitions: options.providerDefinitions ?? {},
+            clients: options.clients ?? {},
+        });
     }
     registerClient(provider, client) {
         this.clients.set(provider, client);
     }
+    updateProviderRegistry(input) {
+        for (const [provider, definition] of Object.entries(input.providerDefinitions)) {
+            if (definition) {
+                this.providerEnabled.set(provider, definition.enabled);
+            }
+        }
+        for (const [provider, client] of Object.entries(input.clients)) {
+            if (client) {
+                this.clients.set(provider, client);
+            }
+        }
+    }
     getRegisteredProviderIds() {
         return Array.from(this.clients.keys());
     }
@@ -187,9 +236,7 @@ export class AgentManager {
     listAgents() {
         return Array.from(this.agents.values())
             .filter((agent) => !agent.internal)
-            .map((agent) => ({
-            ...agent,
-        }));
+            .map((agent) => Object.assign({}, agent));
     }
     async listPersistedAgents(options) {
         if (options?.provider) {
@@ -199,21 +246,17 @@ export class AgentManager {
             }
             return client.listPersistedAgents({ limit: options.limit });
         }
-        const descriptors = [];
-        for (const [provider, client] of this.clients.entries()) {
-            if (!client.listPersistedAgents) {
-                continue;
-            }
+        const providerEntries = Array.from(this.clients.entries()).filter(([, client]) => !!client.listPersistedAgents);
+        const descriptorLists = await Promise.all(providerEntries.map(async ([provider, client]) => {
             try {
-                const entries = await client.listPersistedAgents({
-                    limit: options?.limit,
-                });
-                descriptors.push(...entries);
+                return await client.listPersistedAgents({ limit: options?.limit });
             }
             catch (error) {
                 this.logger.warn({ err: error, provider }, "Failed to list persisted agents for provider");
+                return [];
             }
-        }
+        }));
+        const descriptors = descriptorLists.flat();
         const limit = options?.limit ?? 20;
         return descriptors
             .sort((a, b) => b.lastActivityAt.getTime() - a.lastActivityAt.getTime())
@@ -322,16 +365,15 @@ export class AgentManager {
                         type: "http",
                         url: `${this.mcpBaseUrl}?callerAgentId=${resolvedAgentId}`,
                     },
-                    ...(config.mcpServers ?? {}),
+                    ...config.mcpServers,
                 },
             };
+        this.requireEnabledProvider(injectedConfig.provider);
         const normalizedConfig = await this.normalizeConfig(injectedConfig);
         const launchContext = this.buildLaunchContext(resolvedAgentId);
-        const client = this.requireClient(normalizedConfig.provider);
-        const available = await client.isAvailable();
-        if (!available) {
-            throw new Error(`Provider '${normalizedConfig.provider}' is not available. Please ensure the CLI is installed.`);
-        }
+        const client = await this.requireAvailableClient({
+            provider: normalizedConfig.provider,
+        });
         const session = await client.createSession(normalizedConfig, launchContext);
         return this.registerSession(session, normalizedConfig, resolvedAgentId, {
             labels: options?.labels,
@@ -443,10 +485,10 @@ export class AgentManager {
         try {
             return await Promise.race([
                 operation,
-                new Promise((resolve) => {
+                new Promise((resolvePromise) => {
                     timer = setTimeout(() => {
                         didTimeOut = true;
-                        resolve("timed_out");
+                        resolvePromise("timed_out");
                     }, options.timeoutMs);
                 }),
             ]);
@@ -766,10 +808,9 @@ export class AgentManager {
         const agent = existingAgent;
         agent.pendingReplacement = false;
         agent.lastError = undefined;
-        const self = this;
-        const pendingRun = self.createPendingForegroundRun();
-        self.pendingForegroundRuns.set(agentId, pendingRun);
-        const streamForwarder = (async function* streamForwarder() {
+        const pendingRun = this.createPendingForegroundRun();
+        this.pendingForegroundRuns.set(agentId, pendingRun);
+        const streamForwarder = async function* streamForwarder() {
             let turnId;
             let waiter = null;
             try {
@@ -778,20 +819,20 @@ export class AgentManager {
             }
             catch (error) {
                 const errorMsg = error instanceof Error ? error.message : "Failed to start turn";
-                self.handleStreamEvent(agent, {
+                this.handleStreamEvent(agent, {
                     type: "turn_failed",
                     provider: agent.provider,
                     error: errorMsg,
                 });
-                self.finalizeForegroundTurn(agent);
+                this.finalizeForegroundTurn(agent);
                 throw error;
             }
             pendingRun.started = true;
             agent.activeForegroundTurnId = turnId;
             agent.lifecycle = "running";
-            self.touchUpdatedAt(agent);
-            self.emitState(agent);
-            self.logger.trace({
+            this.touchUpdatedAt(agent);
+            this.emitState(agent);
+            this.logger.trace({
                 agentId,
                 lifecycle: agent.lifecycle,
                 activeForegroundTurnId: agent.activeForegroundTurnId,
@@ -801,8 +842,8 @@ export class AgentManager {
             let queueResolve = null;
             let done = false;
             let resolveSettled;
-            const settledPromise = new Promise((resolve) => {
-                resolveSettled = resolve;
+            const settledPromise = new Promise((resolvePromise) => {
+                resolveSettled = resolvePromise;
             });
             waiter = {
                 turnId,
@@ -832,8 +873,8 @@ export class AgentManager {
                         if (waiter.settled) {
                             break;
                         }
-                        await new Promise((resolve) => {
-                            queueResolve = resolve;
+                        await new Promise((resolvePromise) => {
+                            queueResolve = resolvePromise;
                         });
                     }
                 }
@@ -841,14 +882,14 @@ export class AgentManager {
             finally {
                 if (waiter) {
                     agent.foregroundTurnWaiters.delete(waiter);
-                    self.settleForegroundTurnWaiter(waiter);
+                    this.settleForegroundTurnWaiter(waiter);
                 }
-                self.settlePendingForegroundRun(agentId, pendingRun.token);
+                this.settlePendingForegroundRun(agentId, pendingRun.token);
                 if (!agent.activeForegroundTurnId) {
-                    await self.refreshRuntimeInfo(agent);
+                    await this.refreshRuntimeInfo(agent);
                 }
             }
-        })();
+        }.call(this);
         return streamForwarder;
     }
     finalizeForegroundTurn(agent, turnId) {
@@ -859,11 +900,17 @@ export class AgentManager {
         mutableAgent.activeForegroundTurnId = null;
         const terminalError = mutableAgent.lastError;
         const shouldHoldBusyForReplacement = mutableAgent.pendingReplacement && !terminalError;
-        mutableAgent.lifecycle = shouldHoldBusyForReplacement
-            ? "running"
-            : terminalError
-                ? "error"
-                : "idle";
+        let nextLifecycle;
+        if (shouldHoldBusyForReplacement) {
+            nextLifecycle = "running";
+        }
+        else if (terminalError) {
+            nextLifecycle = "error";
+        }
+        else {
+            nextLifecycle = "idle";
+        }
+        mutableAgent.lifecycle = nextLifecycle;
         const persistenceHandle = mutableAgent.session.describePersistence() ??
             (mutableAgent.runtimeInfo?.sessionId
                 ? { provider: mutableAgent.provider, sessionId: mutableAgent.runtimeInfo.sessionId }
@@ -894,29 +941,28 @@ export class AgentManager {
         agent.lifecycle = "running";
         this.touchUpdatedAt(agent);
         this.emitState(agent);
-        const self = this;
-        return (async function* replaceRunForwarder() {
+        return async function* replaceRunForwarder() {
             try {
-                await self.cancelAgentRun(agentId);
-                const nextRun = self.streamAgent(agentId, prompt, options);
+                await this.cancelAgentRun(agentId);
+                const nextRun = this.streamAgent(agentId, prompt, options);
                 for await (const event of nextRun) {
                     yield event;
                 }
             }
             catch (error) {
-                const latest = self.agents.get(agentId);
+                const latest = this.agents.get(agentId);
                 if (latest) {
                     const latestActive = latest;
                     latestActive.pendingReplacement = false;
                     if (!latestActive.activeForegroundTurnId && latestActive.lifecycle === "running") {
                         latestActive.lifecycle = "idle";
-                        self.touchUpdatedAt(latestActive);
-                        self.emitState(latestActive);
+                        this.touchUpdatedAt(latestActive);
+                        this.emitState(latestActive);
                     }
                 }
                 throw error;
             }
-        })();
+        }.call(this);
     }
     async waitForAgentRunStart(agentId, options) {
         const snapshot = this.getAgent(agentId);
@@ -933,7 +979,7 @@ export class AgentManager {
         if (options?.signal?.aborted) {
             throw createAbortError(options.signal, "wait_for_agent_start aborted");
         }
-        await new Promise((resolve, reject) => {
+        await new Promise((resolvePromise, reject) => {
             if (options?.signal?.aborted) {
                 reject(createAbortError(options.signal, "wait_for_agent_start aborted"));
                 return;
@@ -962,7 +1008,7 @@ export class AgentManager {
             };
             const finishOk = () => {
                 cleanup();
-                resolve();
+                resolvePromise();
             };
             const finishErr = (error) => {
                 cleanup();
@@ -1045,19 +1091,19 @@ export class AgentManager {
         // Wait briefly for the event to propagate if there's an active foreground turn.
         if (foregroundTurnId) {
             const waiter = Array.from(agent.foregroundTurnWaiters).find((candidate) => candidate.turnId === foregroundTurnId);
-            const timeout = new Promise((resolve) => setTimeout(resolve, 2000));
+            const timeout = new Promise((resolvePromise) => setTimeout(resolvePromise, 2000));
             if (waiter) {
                 await Promise.race([waiter.settledPromise, timeout]);
             }
             else if (agent.activeForegroundTurnId === foregroundTurnId) {
                 await Promise.race([
-                    new Promise((resolve) => {
+                    new Promise((resolvePromise) => {
                         const unsubscribe = this.subscribe((event) => {
                             if (event.type === "agent_state" &&
                                 event.agent.id === agentId &&
                                 !event.agent.activeForegroundTurnId) {
                                 unsubscribe();
-                                resolve();
+                                resolvePromise();
                             }
                         }, { agentId, replayState: false });
                     }),
@@ -1073,7 +1119,7 @@ export class AgentManager {
             }
         }
         else if (pendingRun) {
-            const timeout = new Promise((resolve) => setTimeout(resolve, 2000));
+            const timeout = new Promise((resolvePromise) => setTimeout(resolvePromise, 2000));
             await Promise.race([pendingRun.settledPromise, timeout]);
         }
         // If the foreground turn is still stuck after the timeout, force-dispatch a
@@ -1179,7 +1225,7 @@ export class AgentManager {
             return null;
         }
         return {
-            text: chunks.reverse().join(""),
+            text: chunks.toReversed().join(""),
             startsAtBeginning,
         };
     }
@@ -1256,7 +1302,7 @@ export class AgentManager {
         if (options?.signal?.aborted) {
             throw createAbortError(options.signal, "wait_for_agent aborted");
         }
-        return await new Promise((resolve, reject) => {
+        return await new Promise((resolvePromise, reject) => {
             // Bug #1 Fix: Check abort signal AGAIN inside Promise constructor
             // to avoid race condition between pre-Promise check and abort listener registration
             if (options?.signal?.aborted) {
@@ -1302,11 +1348,12 @@ export class AgentManager {
                 cleanup();
                 void this.getLastAssistantMessage(agentId)
                     .then((lastMessage) => {
-                    resolve({
+                    resolvePromise({
                         status: currentStatus,
                         permission,
                         lastMessage,
                     });
+                    return;
                 })
                     .catch(reject);
             };
@@ -1368,31 +1415,57 @@ export class AgentManager {
         }
         const initialPersistedTitle = await this.resolveInitialPersistedTitle(resolvedAgentId, config);
         const now = new Date();
-        const explicitTimelineSeed = options?.timeline?.length ||
-            options?.timelineRows?.length ||
-            options?.timelineNextSeq !== undefined
-            ? {
-                items: options?.timeline,
-                rows: options?.timelineRows,
-                nextSeq: options?.timelineNextSeq,
-                timestamp: (options?.updatedAt ?? options?.createdAt ?? now).toISOString(),
-            }
-            : null;
+        const { durableTimelineHasRows } = await this.initializeAgentTimelineForRegister({
+            agentId: resolvedAgentId,
+            now,
+            options,
+        });
+        const managed = this.buildManagedAgentForRegister({
+            resolvedAgentId,
+            session,
+            config,
+            now,
+            durableTimelineHasRows,
+            options,
+        });
+        this.agents.set(resolvedAgentId, managed);
+        // Initialize previousStatus to track transitions
+        this.previousStatuses.set(resolvedAgentId, managed.lifecycle);
+        await this.refreshRuntimeInfo(managed);
+        await this.persistSnapshot(managed, {
+            workspaceId: options?.workspaceId,
+            title: initialPersistedTitle,
+        });
+        this.emitState(managed, { persist: false });
+        await this.refreshSessionState(managed);
+        managed.lifecycle = "idle";
+        await this.persistSnapshot(managed, { workspaceId: options?.workspaceId });
+        this.emitState(managed, { persist: false });
+        this.subscribeToSession(managed);
+        return { ...managed };
+    }
+    async initializeAgentTimelineForRegister(params) {
+        const { agentId, now, options } = params;
+        const explicitTimelineSeed = buildExplicitTimelineSeedForRegister(now, options);
         const shouldSeedFromDurable = !explicitTimelineSeed &&
-            !this.timelineStore.has(resolvedAgentId) &&
+            !this.timelineStore.has(agentId) &&
             this.durableTimelineStore !== undefined;
         const durableTimelineSeed = shouldSeedFromDurable
-            ? await this.loadCommittedTimelineSeed(resolvedAgentId, now)
+            ? await this.loadCommittedTimelineSeed(agentId, now)
             : null;
         const durableTimelineHasRows = durableTimelineSeed != null && (durableTimelineSeed.nextSeq ?? 1) > 1;
         const timelineSeed = explicitTimelineSeed ?? durableTimelineSeed;
-        if (timelineSeed || !this.timelineStore.has(resolvedAgentId)) {
-            this.timelineStore.initialize(resolvedAgentId, timelineSeed ?? { timestamp: now.toISOString() });
+        if (timelineSeed || !this.timelineStore.has(agentId)) {
+            this.timelineStore.initialize(agentId, timelineSeed ?? { timestamp: now.toISOString() });
         }
         if (options?.timelineRows?.length) {
-            this.enqueueDurableTimelineBulkInsert(resolvedAgentId, options.timelineRows);
+            this.enqueueDurableTimelineBulkInsert(agentId, options.timelineRows);
         }
-        const managed = {
+        return { durableTimelineHasRows };
+    }
+    buildManagedAgentForRegister(params) {
+        const { resolvedAgentId, session, config, now, durableTimelineHasRows, options } = params;
+        return {
             id: resolvedAgentId,
             provider: config.provider,
             cwd: config.cwd,
@@ -1418,33 +1491,10 @@ export class AgentManager {
             lastUserMessageAt: options?.lastUserMessageAt ?? null,
             lastUsage: options?.lastUsage,
             lastError: options?.lastError,
-            attention: options?.attention != null
-                ? options.attention.requiresAttention
-                    ? {
-                        requiresAttention: true,
-                        attentionReason: options.attention.attentionReason,
-                        attentionTimestamp: new Date(options.attention.attentionTimestamp),
-                    }
-                    : { requiresAttention: false }
-                : { requiresAttention: false },
+            attention: resolveInitialAttention(options?.attention),
             internal: config.internal ?? false,
             labels: options?.labels ?? {},
         };
-        this.agents.set(resolvedAgentId, managed);
-        // Initialize previousStatus to track transitions
-        this.previousStatuses.set(resolvedAgentId, managed.lifecycle);
-        await this.refreshRuntimeInfo(managed);
-        await this.persistSnapshot(managed, {
-            workspaceId: options?.workspaceId,
-            title: initialPersistedTitle,
-        });
-        this.emitState(managed, { persist: false });
-        await this.refreshSessionState(managed);
-        managed.lifecycle = "idle";
-        await this.persistSnapshot(managed, { workspaceId: options?.workspaceId });
-        this.emitState(managed, { persist: false });
-        this.subscribeToSession(managed);
-        return { ...managed };
     }
     async loadCommittedTimelineSeed(agentId, now) {
         if (!this.durableTimelineStore) {
@@ -1507,6 +1557,7 @@ export class AgentManager {
                 return;
             }
             await this.dispatchSessionEvent(current, event);
+            return;
         })
             .catch((err) => {
             this.logger.error({ err, agentId, eventType: event.type }, "Failed to process session event");
@@ -1554,8 +1605,8 @@ export class AgentManager {
     }
     createPendingForegroundRun() {
         let resolveSettled;
-        const settledPromise = new Promise((resolve) => {
-            resolveSettled = resolve;
+        const settledPromise = new Promise((resolvePromise) => {
+            resolveSettled = resolvePromise;
         });
         return {
             token: randomUUID(),
@@ -1671,14 +1722,8 @@ export class AgentManager {
                 if (event.type !== "timeline") {
                     continue;
                 }
-                if (event.item.type === "user_message") {
-                    const eventMessageId = normalizeMessageId(event.item.messageId);
-                    if (eventMessageId) {
-                        const canonicalText = canonicalUserMessagesById.get(eventMessageId);
-                        if (canonicalText === event.item.text) {
-                            continue;
-                        }
-                    }
+                if (isDuplicateLegacyUserMessage(event.item, canonicalUserMessagesById)) {
+                    continue;
                 }
                 this.recordTimeline(agent.id, event.item);
             }
@@ -1718,185 +1763,212 @@ export class AgentManager {
             }
             this.agentStreamCoalescer.flushFor(agent.id);
         }
-        let shouldDispatchEvent = true;
-        let shouldNotifyWaiters = true;
+        const flags = { shouldDispatchEvent: true, shouldNotifyWaiters: true };
+        const dispatchPromise = this.dispatchStreamEventByType({
+            agent,
+            event,
+            options,
+            isForegroundEvent,
+            eventTurnId,
+            flags,
+        });
+        if (dispatchPromise) {
+            await dispatchPromise;
+        }
+        if (!options?.fromHistory && isForegroundEvent && isTurnTerminalEvent(event)) {
+            this.finalizeForegroundTurn(agent, eventTurnId);
+        }
+        if (!options?.fromHistory && flags.shouldDispatchEvent) {
+            this.dispatchStream(agent.id, event);
+        }
+        return flags.shouldNotifyWaiters;
+    }
+    dispatchStreamEventByType(params) {
+        const { agent, event, options, isForegroundEvent, eventTurnId, flags } = params;
         switch (event.type) {
             case "thread_started":
-                {
-                    const previousSessionId = agent.persistence?.sessionId ?? null;
-                    const handle = agent.session.describePersistence();
-                    if (handle) {
-                        agent.persistence = attachPersistenceCwd(handle, agent.cwd);
-                        if (agent.persistence?.sessionId !== previousSessionId) {
-                            this.emitState(agent);
-                        }
-                    }
-                    void this.refreshRuntimeInfo(agent);
-                }
-                break;
+                this.onStreamThreadStarted(agent);
+                return undefined;
             case "usage_updated":
                 agent.lastUsage = event.usage;
                 this.emitState(agent);
-                break;
+                return undefined;
             case "timeline":
-                {
-                    // Skip provider-replayed user_message items during history hydration.
-                    if (options?.fromHistory && event.item.type === "user_message") {
-                        const eventMessageId = normalizeMessageId(event.item.messageId);
-                        if (eventMessageId) {
-                            const canonicalText = options?.canonicalUserMessagesById?.get(eventMessageId);
-                            if (canonicalText === event.item.text) {
-                                shouldDispatchEvent = false;
-                                shouldNotifyWaiters = false;
-                                break;
-                            }
-                        }
-                    }
-                    // Suppress user_message echoes for the active foreground turn.
-                    if (!options?.fromHistory && event.item.type === "user_message" && isForegroundEvent) {
-                        const eventMessageId = normalizeMessageId(event.item.messageId);
-                        if (eventMessageId &&
-                            (await this.hasCommittedUserMessageFromStores(agent.id, {
-                                messageId: eventMessageId,
-                                text: event.item.text,
-                            }))) {
-                            break;
-                        }
-                    }
-                    if (options?.fromHistory) {
-                        this.recordTimeline(agent.id, event.item);
-                        shouldDispatchEvent = false;
-                        shouldNotifyWaiters = false;
-                        break;
-                    }
-                    this.recordAndDispatchTimelineItem(agent.id, event.item, event.provider, event.turnId);
-                    if (event.item.type === "user_message") {
-                        agent.lastUserMessageAt = new Date();
-                        this.emitState(agent);
-                    }
-                    shouldDispatchEvent = false;
-                    shouldNotifyWaiters = true;
-                }
-                break;
+                return this.onStreamTimelineEvent({ agent, event, options, isForegroundEvent, flags });
             case "turn_completed":
-                this.logger.trace({
-                    agentId: agent.id,
-                    lifecycle: agent.lifecycle,
-                    activeForegroundTurnId: agent.activeForegroundTurnId,
-                    eventTurnId,
-                }, "handleStreamEvent: turn_completed");
-                agent.lastUsage = event.usage;
-                agent.lastError = undefined;
-                // For autonomous turns (not foreground), transition to idle
-                // unless a replacement is pending (avoid idle flash during replace)
-                if (!isForegroundEvent && agent.lifecycle !== "idle" && !agent.pendingReplacement) {
-                    agent.lifecycle = "idle";
-                    this.emitState(agent);
-                }
-                void this.refreshRuntimeInfo(agent);
-                break;
+                this.onStreamTurnCompleted({ agent, event, eventTurnId, isForegroundEvent });
+                return undefined;
             case "turn_failed":
-                this.logger.warn({
-                    agentId: agent.id,
-                    lifecycle: agent.lifecycle,
-                    activeForegroundTurnId: agent.activeForegroundTurnId,
+                return this.onStreamTurnFailed({
+                    agent,
+                    event,
                     eventTurnId,
-                    error: event.error,
-                    code: event.code,
-                    diagnostic: event.diagnostic,
-                }, "handleStreamEvent: turn_failed");
-                // For autonomous turns, set error state directly
-                if (!isForegroundEvent) {
-                    agent.lifecycle = "error";
-                }
-                agent.lastError = event.error;
-                await this.appendSystemErrorTimelineMessage(agent, event.provider, this.formatTurnFailedMessage(event), options);
-                for (const [requestId] of agent.pendingPermissions) {
-                    agent.pendingPermissions.delete(requestId);
-                    if (!options?.fromHistory) {
-                        this.dispatchStream(agent.id, {
-                            type: "permission_resolved",
-                            provider: event.provider,
-                            requestId,
-                            resolution: { behavior: "deny", message: "Turn failed" },
-                        });
-                    }
-                }
-                if (!isForegroundEvent) {
-                    this.emitState(agent);
-                }
-                break;
+                    isForegroundEvent,
+                    options,
+                });
             case "turn_canceled":
-                this.logger.trace({
-                    agentId: agent.id,
-                    lifecycle: agent.lifecycle,
-                    activeForegroundTurnId: agent.activeForegroundTurnId,
-                    eventTurnId,
-                }, "handleStreamEvent: turn_canceled");
-                // For autonomous turns, transition to idle
-                // unless a replacement is pending (avoid idle flash during replace)
-                if (!isForegroundEvent && !agent.pendingReplacement) {
-                    agent.lifecycle = "idle";
-                }
-                agent.lastError = undefined;
-                for (const [requestId] of agent.pendingPermissions) {
-                    agent.pendingPermissions.delete(requestId);
-                    if (!options?.fromHistory) {
-                        this.dispatchStream(agent.id, {
-                            type: "permission_resolved",
-                            provider: event.provider,
-                            requestId,
-                            resolution: { behavior: "deny", message: "Interrupted" },
-                        });
-                    }
-                }
-                if (!isForegroundEvent) {
-                    this.emitState(agent);
-                }
-                break;
+                this.onStreamTurnCanceled({ agent, event, eventTurnId, isForegroundEvent, options });
+                return undefined;
             case "turn_started":
-                this.logger.trace({
-                    agentId: agent.id,
-                    lifecycle: agent.lifecycle,
-                    activeForegroundTurnId: agent.activeForegroundTurnId,
-                    eventTurnId,
-                }, "handleStreamEvent: turn_started");
-                // For autonomous turn_started (no foreground match), set running
-                if (!isForegroundEvent) {
-                    agent.lifecycle = "running";
-                    this.emitState(agent);
-                }
-                break;
+                this.onStreamTurnStarted({ agent, eventTurnId, isForegroundEvent });
+                return undefined;
             case "permission_requested":
-                {
-                    const hadPendingPermissions = agent.pendingPermissions.size > 0;
-                    agent.pendingPermissions.set(event.request.id, event.request);
-                    if (!hadPendingPermissions && !agent.internal) {
-                        this.broadcastAgentAttention(agent, "permission");
-                    }
-                }
-                this.emitState(agent);
-                break;
+                this.onStreamPermissionRequested(agent, event);
+                return undefined;
             case "permission_resolved":
-                agent.pendingPermissions.delete(event.requestId);
-                if (!options?.fromHistory && agent.inFlightPermissionResponses.has(event.requestId)) {
-                    agent.bufferedPermissionResolutions.set(event.requestId, event);
-                    shouldDispatchEvent = false;
-                    break;
-                }
-                this.emitState(agent);
-                break;
+                this.onStreamPermissionResolved({ agent, event, options, flags });
+                return undefined;
             default:
-                break;
+                return undefined;
         }
-        if (!options?.fromHistory && isForegroundEvent && isTurnTerminalEvent(event)) {
-            this.finalizeForegroundTurn(agent, eventTurnId);
+    }
+    onStreamThreadStarted(agent) {
+        const previousSessionId = agent.persistence?.sessionId ?? null;
+        const handle = agent.session.describePersistence();
+        if (handle) {
+            agent.persistence = attachPersistenceCwd(handle, agent.cwd);
+            if (agent.persistence?.sessionId !== previousSessionId) {
+                this.emitState(agent);
+            }
         }
-        // Skip dispatching individual stream events during history replay.
-        if (!options?.fromHistory && shouldDispatchEvent) {
-            this.dispatchStream(agent.id, event);
+        void this.refreshRuntimeInfo(agent);
+    }
+    async onStreamTimelineEvent(params) {
+        const { agent, event, options, isForegroundEvent, flags } = params;
+        // Skip provider-replayed user_message items during history hydration.
+        if (options?.fromHistory && event.item.type === "user_message") {
+            const eventMessageId = normalizeMessageId(event.item.messageId);
+            if (eventMessageId) {
+                const canonicalText = options?.canonicalUserMessagesById?.get(eventMessageId);
+                if (canonicalText === event.item.text) {
+                    flags.shouldDispatchEvent = false;
+                    flags.shouldNotifyWaiters = false;
+                    return;
+                }
+            }
+        }
+        // Suppress user_message echoes for the active foreground turn.
+        if (!options?.fromHistory && event.item.type === "user_message" && isForegroundEvent) {
+            const eventMessageId = normalizeMessageId(event.item.messageId);
+            if (eventMessageId &&
+                (await this.hasCommittedUserMessageFromStores(agent.id, {
+                    messageId: eventMessageId,
+                    text: event.item.text,
+                }))) {
+                return;
+            }
+        }
+        if (options?.fromHistory) {
+            this.recordTimeline(agent.id, event.item);
+            flags.shouldDispatchEvent = false;
+            flags.shouldNotifyWaiters = false;
+            return;
+        }
+        this.recordAndDispatchTimelineItem(agent.id, event.item, event.provider, event.turnId);
+        if (event.item.type === "user_message") {
+            agent.lastUserMessageAt = new Date();
+            this.emitState(agent);
+        }
+        flags.shouldDispatchEvent = false;
+        flags.shouldNotifyWaiters = true;
+    }
+    onStreamTurnCompleted(params) {
+        const { agent, event, eventTurnId, isForegroundEvent } = params;
+        this.logger.trace({
+            agentId: agent.id,
+            lifecycle: agent.lifecycle,
+            activeForegroundTurnId: agent.activeForegroundTurnId,
+            eventTurnId,
+        }, "handleStreamEvent: turn_completed");
+        agent.lastUsage = event.usage;
+        agent.lastError = undefined;
+        if (!isForegroundEvent && agent.lifecycle !== "idle" && !agent.pendingReplacement) {
+            agent.lifecycle = "idle";
+            this.emitState(agent);
+        }
+        void this.refreshRuntimeInfo(agent);
+    }
+    async onStreamTurnFailed(params) {
+        const { agent, event, eventTurnId, isForegroundEvent, options } = params;
+        this.logger.warn({
+            agentId: agent.id,
+            lifecycle: agent.lifecycle,
+            activeForegroundTurnId: agent.activeForegroundTurnId,
+            eventTurnId,
+            error: event.error,
+            code: event.code,
+            diagnostic: event.diagnostic,
+        }, "handleStreamEvent: turn_failed");
+        if (!isForegroundEvent) {
+            agent.lifecycle = "error";
+        }
+        agent.lastError = event.error;
+        await this.appendSystemErrorTimelineMessage(agent, event.provider, this.formatTurnFailedMessage(event), options);
+        this.resolvePendingPermissionsForAgent(agent, event.provider, options, "Turn failed");
+        if (!isForegroundEvent) {
+            this.emitState(agent);
+        }
+    }
+    onStreamTurnCanceled(params) {
+        const { agent, event, eventTurnId, isForegroundEvent, options } = params;
+        this.logger.trace({
+            agentId: agent.id,
+            lifecycle: agent.lifecycle,
+            activeForegroundTurnId: agent.activeForegroundTurnId,
+            eventTurnId,
+        }, "handleStreamEvent: turn_canceled");
+        if (!isForegroundEvent && !agent.pendingReplacement) {
+            agent.lifecycle = "idle";
+        }
+        agent.lastError = undefined;
+        this.resolvePendingPermissionsForAgent(agent, event.provider, options, "Interrupted");
+        if (!isForegroundEvent) {
+            this.emitState(agent);
+        }
+    }
+    onStreamTurnStarted(params) {
+        const { agent, eventTurnId, isForegroundEvent } = params;
+        this.logger.trace({
+            agentId: agent.id,
+            lifecycle: agent.lifecycle,
+            activeForegroundTurnId: agent.activeForegroundTurnId,
+            eventTurnId,
+        }, "handleStreamEvent: turn_started");
+        if (!isForegroundEvent) {
+            agent.lifecycle = "running";
+            this.emitState(agent);
+        }
+    }
+    onStreamPermissionRequested(agent, event) {
+        const hadPendingPermissions = agent.pendingPermissions.size > 0;
+        agent.pendingPermissions.set(event.request.id, event.request);
+        if (!hadPendingPermissions && !agent.internal) {
+            this.broadcastAgentAttention(agent, "permission");
+        }
+        this.emitState(agent);
+    }
+    onStreamPermissionResolved(params) {
+        const { agent, event, options, flags } = params;
+        agent.pendingPermissions.delete(event.requestId);
+        if (!options?.fromHistory && agent.inFlightPermissionResponses.has(event.requestId)) {
+            agent.bufferedPermissionResolutions.set(event.requestId, event);
+            flags.shouldDispatchEvent = false;
+            return;
+        }
+        this.emitState(agent);
+    }
+    resolvePendingPermissionsForAgent(agent, provider, options, message) {
+        for (const [requestId] of agent.pendingPermissions) {
+            agent.pendingPermissions.delete(requestId);
+            if (!options?.fromHistory) {
+                this.dispatchStream(agent.id, {
+                    type: "permission_resolved",
+                    provider,
+                    requestId,
+                    resolution: { behavior: "deny", message },
+                });
+            }
         }
-        return shouldNotifyWaiters;
     }
     recordAndDispatchTimelineItem(agentId, item, provider, turnId) {
         const row = this.recordTimeline(agentId, item);
@@ -2102,12 +2174,12 @@ export class AgentManager {
                 if (error instanceof Error &&
                     "code" in error &&
                     error.code === "ENOENT") {
-                    throw new Error(`Working directory does not exist: ${normalized.cwd}`);
+                    throw new Error(`Working directory does not exist: ${normalized.cwd}`, { cause: error });
                 }
                 if (error instanceof Error) {
                     throw error;
                 }
-                throw new Error(`Failed to access working directory: ${normalized.cwd}`);
+                throw new Error(`Failed to access working directory: ${normalized.cwd}`, { cause: error });
             }
         }
         if (typeof normalized.model === "string") {
@@ -2147,6 +2219,37 @@ export class AgentManager {
             },
         };
     }
+    async requireAvailableClient(options) {
+        const client = this.clients.get(options.provider);
+        if (!client) {
+            const configuredProviders = this.getConfiguredProviderIds();
+            throw new Error(`Unknown provider '${options.provider}'. Configured providers: ${formatProviderList(configuredProviders)}.`);
+        }
+        let unavailableReason = null;
+        try {
+            const available = await client.isAvailable();
+            if (available) {
+                return client;
+            }
+        }
+        catch (error) {
+            unavailableReason = error instanceof Error ? error.message : String(error);
+        }
+        const availableProviders = (await this.listProviderAvailability())
+            .filter((entry) => entry.available)
+            .map((entry) => entry.provider);
+        const providerList = formatProviderList(availableProviders);
+        const reason = unavailableReason ? ` Reason: ${unavailableReason}.` : "";
+        throw new Error(`Provider '${options.provider}' is not available.${reason} Available providers: ${providerList}. Use one of those providers, or install/configure '${options.provider}'.`);
+    }
+    requireEnabledProvider(provider) {
+        if (this.providerEnabled.get(provider) === false) {
+            throw new Error(`Provider '${provider}' is disabled`);
+        }
+    }
+    getConfiguredProviderIds() {
+        return Array.from(new Set([...this.providerEnabled.keys(), ...this.clients.keys()]));
+    }
     requireClient(provider) {
         const client = this.clients.get(provider);
         if (!client) {