@getpaseo/server 0.1.62 → 0.1.65

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

@@ -5,10 +5,24 @@ import { AGENT_LIFECYCLE_STATUSES, } from "../../shared/agent-lifecycle.js";
 import { z } from "zod";
 import { InMemoryAgentTimelineStore, } from "./agent-timeline-store.js";
 import { AGENT_STREAM_COALESCE_DEFAULT_WINDOW_MS, AgentStreamCoalescer, } from "./agent-stream-coalescer.js";
+import { ForegroundRunState } from "./foreground-run-state.js";
 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 +31,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,14 +71,39 @@ 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();
         this.sessionEventTails = new Map();
-        this.pendingForegroundRuns = new Map();
+        this.foregroundRuns = new ForegroundRunState();
         this.subscribers = new Set();
         this.previousStatuses = new Map();
         this.backgroundTasks = new Set();
@@ -84,17 +125,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());
     }
@@ -148,7 +198,7 @@ export class AgentManager {
         }
         return (agent.lifecycle === "running" ||
             Boolean(agent.activeForegroundTurnId) ||
-            this.hasPendingForegroundRun(agentId));
+            this.foregroundRuns.hasPendingRun(agentId));
     }
     subscribe(callback, options) {
         const targetAgentId = options?.agentId == null ? null : validateAgentId(options.agentId, "subscribe");
@@ -187,9 +237,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,26 +247,32 @@ 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())
             .slice(0, limit);
     }
+    async findPersistedAgent(provider, sessionId) {
+        const client = this.requireClient(provider);
+        if (!client.listPersistedAgents) {
+            return null;
+        }
+        const descriptors = await client.listPersistedAgents({ limit: 200 });
+        return (descriptors.find((descriptor) => {
+            return (descriptor.sessionId === sessionId || descriptor.persistence.nativeHandle === sessionId);
+        }) ?? null);
+    }
     async listProviderAvailability() {
         const checks = Array.from(this.clients.keys()).map(async (provider) => {
             const client = this.clients.get(provider);
@@ -322,16 +376,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,
@@ -393,11 +446,7 @@ export class AgentManager {
             existing.unsubscribeSession();
             existing.unsubscribeSession = null;
         }
-        for (const waiter of existing.foregroundTurnWaiters) {
-            this.settleForegroundTurnWaiter(waiter);
-        }
-        existing.foregroundTurnWaiters.clear();
-        this.settlePendingForegroundRun(agentId);
+        this.foregroundRuns.clearAgent(agentId, existing);
         await this.closeReloadedSession(existing.session, agentId);
         // Preserve existing labels and timeline during reload.
         return this.registerSession(session, normalizedConfig, agentId, {
@@ -443,10 +492,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);
                 }),
             ]);
@@ -751,119 +800,88 @@ export class AgentManager {
             agentId,
             lifecycle: existingAgent.lifecycle,
             activeForegroundTurnId: existingAgent.activeForegroundTurnId,
-            hasPendingForegroundRun: this.hasPendingForegroundRun(agentId),
+            hasPendingForegroundRun: this.foregroundRuns.hasPendingRun(agentId),
             promptType: typeof prompt === "string" ? "string" : "structured",
             hasRunOptions: Boolean(options),
         }, "streamAgent: requested");
-        if (existingAgent.activeForegroundTurnId || this.hasPendingForegroundRun(agentId)) {
+        if (existingAgent.activeForegroundTurnId || this.foregroundRuns.hasPendingRun(agentId)) {
             this.logger.trace({
                 agentId,
                 lifecycle: existingAgent.lifecycle,
-                hasPendingForegroundRun: this.hasPendingForegroundRun(agentId),
+                hasPendingForegroundRun: this.foregroundRuns.hasPendingRun(agentId),
             }, "streamAgent: rejected because a foreground run is already in flight");
             throw new Error(`Agent ${agentId} already has an active run`);
         }
         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.foregroundRuns.createPendingRun(agentId);
+        const streamForwarder = async function* streamForwarder() {
             let turnId;
-            let waiter = null;
+            let turnStream = null;
             try {
                 const result = await agent.session.startTurn(prompt, options);
                 turnId = result.turnId;
             }
             catch (error) {
                 const errorMsg = error instanceof Error ? error.message : "Failed to start turn";
-                self.handleStreamEvent(agent, {
+                await this.handleStreamEvent(agent, {
                     type: "turn_failed",
                     provider: agent.provider,
                     error: errorMsg,
                 });
-                self.finalizeForegroundTurn(agent);
+                this.finalizeForegroundTurn(agent);
+                this.foregroundRuns.settlePendingRun(agentId, pendingRun.token);
                 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,
             }, "streamAgent: started");
-            // Create a pushable queue for this foreground turn
-            const queue = [];
-            let queueResolve = null;
-            let done = false;
-            let resolveSettled;
-            const settledPromise = new Promise((resolve) => {
-                resolveSettled = resolve;
-            });
-            waiter = {
-                turnId,
-                settled: false,
-                settledPromise,
-                resolveSettled,
-                callback: (event) => {
-                    queue.push(event);
-                    if (queueResolve) {
-                        queueResolve();
-                        queueResolve = null;
-                    }
-                },
-            };
-            agent.foregroundTurnWaiters.add(waiter);
+            turnStream = this.foregroundRuns.createTurnStream(turnId);
+            this.foregroundRuns.addWaiter(agent, turnStream.waiter);
             try {
-                while (!done) {
-                    while (queue.length > 0) {
-                        const event = queue.shift();
-                        yield event;
-                        if (isTurnTerminalEvent(event)) {
-                            done = true;
-                            break;
-                        }
-                    }
-                    if (!done && queue.length === 0) {
-                        if (waiter.settled) {
-                            break;
-                        }
-                        await new Promise((resolve) => {
-                            queueResolve = resolve;
-                        });
-                    }
+                for await (const event of turnStream.events(isTurnTerminalEvent)) {
+                    yield event;
                 }
             }
             finally {
-                if (waiter) {
-                    agent.foregroundTurnWaiters.delete(waiter);
-                    self.settleForegroundTurnWaiter(waiter);
+                if (turnStream) {
+                    this.foregroundRuns.deleteWaiter(agent, turnStream.waiter);
                 }
-                self.settlePendingForegroundRun(agentId, pendingRun.token);
+                this.foregroundRuns.settlePendingRun(agentId, pendingRun.token);
                 if (!agent.activeForegroundTurnId) {
-                    await self.refreshRuntimeInfo(agent);
+                    await this.refreshRuntimeInfo(agent);
                 }
             }
-        })();
+        }.call(this);
         return streamForwarder;
     }
     finalizeForegroundTurn(agent, turnId) {
         const mutableAgent = agent;
         if (turnId) {
-            this.rememberFinalizedForegroundTurn(mutableAgent, turnId);
+            this.foregroundRuns.rememberFinalizedTurn(mutableAgent, turnId);
         }
         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 }
@@ -886,7 +904,7 @@ export class AgentManager {
         const snapshot = this.requireAgent(agentId);
         if (snapshot.lifecycle !== "running" &&
             !snapshot.activeForegroundTurnId &&
-            !this.hasPendingForegroundRun(agentId)) {
+            !this.foregroundRuns.hasPendingRun(agentId)) {
             return this.streamAgent(agentId, prompt, options);
         }
         const agent = this.requireSessionAgent(agentId);
@@ -894,36 +912,35 @@ 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);
         if (!snapshot) {
             throw new Error(`Agent ${agentId} not found`);
         }
-        const pendingRun = this.getPendingForegroundRun(agentId);
+        const pendingRun = this.foregroundRuns.getPendingRun(agentId);
         if ((snapshot.lifecycle === "running" || pendingRun?.started) && !snapshot.pendingReplacement) {
             return;
         }
@@ -933,7 +950,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 +979,7 @@ export class AgentManager {
             };
             const finishOk = () => {
                 cleanup();
-                resolve();
+                resolvePromise();
             };
             const finishErr = (error) => {
                 cleanup();
@@ -978,7 +995,7 @@ export class AgentManager {
                     finishErr(new Error(`Agent ${agentId} not found`));
                     return true;
                 }
-                const currentPendingRun = this.getPendingForegroundRun(agentId);
+                const currentPendingRun = this.foregroundRuns.getPendingRun(agentId);
                 if ((current.lifecycle === "running" || currentPendingRun?.started) &&
                     !current.pendingReplacement) {
                     finishOk();
@@ -1032,7 +1049,7 @@ export class AgentManager {
     }
     async cancelAgentRun(agentId) {
         const agent = this.requireSessionAgent(agentId);
-        const pendingRun = this.getPendingForegroundRun(agentId);
+        const pendingRun = this.foregroundRuns.getPendingRun(agentId);
         const foregroundTurnId = agent.activeForegroundTurnId;
         const hasForegroundTurn = Boolean(foregroundTurnId);
         const isAutonomousRunning = agent.lifecycle === "running" && !hasForegroundTurn && !pendingRun;
@@ -1045,19 +1062,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 +1090,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
@@ -1089,7 +1106,7 @@ export class AgentManager {
             });
             // The synthetic event unblocks the streamForwarder generator, whose finally
             // block settles the pending foreground run asynchronously. Wait for it.
-            const staleRun = this.getPendingForegroundRun(agentId);
+            const staleRun = this.foregroundRuns.getPendingRun(agentId);
             if (staleRun && !staleRun.settled) {
                 await staleRun.settledPromise;
             }
@@ -1179,7 +1196,7 @@ export class AgentManager {
             return null;
         }
         return {
-            text: chunks.reverse().join(""),
+            text: chunks.toReversed().join(""),
             startsAtBeginning,
         };
     }
@@ -1226,7 +1243,7 @@ export class AgentManager {
         if (!snapshot) {
             throw new Error(`Agent ${agentId} not found`);
         }
-        const pendingForegroundRun = this.getPendingForegroundRun(agentId);
+        const pendingForegroundRun = this.foregroundRuns.getPendingRun(agentId);
         const hasForegroundTurn = Boolean(snapshot.activeForegroundTurnId) || Boolean(pendingForegroundRun);
         const immediatePermission = this.peekPendingPermission(snapshot);
         if (immediatePermission) {
@@ -1256,7 +1273,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 +1319,12 @@ export class AgentManager {
                 cleanup();
                 void this.getLastAssistantMessage(agentId)
                     .then((lastMessage) => {
-                    resolve({
+                    resolvePromise({
                         status: currentStatus,
                         permission,
                         lastMessage,
                     });
+                    return;
                 })
                     .catch(reject);
             };
@@ -1368,31 +1386,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 +1462,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) {
@@ -1463,17 +1484,13 @@ export class AgentManager {
             agent.unsubscribeSession();
             agent.unsubscribeSession = null;
         }
-        for (const waiter of agent.foregroundTurnWaiters) {
-            waiter.callback({
-                type: "turn_canceled",
-                provider: agent.provider,
-                reason: cancelReason,
-                turnId: waiter.turnId,
-            });
-            this.settleForegroundTurnWaiter(waiter);
-        }
-        agent.foregroundTurnWaiters.clear();
-        this.settlePendingForegroundRun(agent.id);
+        this.foregroundRuns.cancelWaiters(agent, (turnId) => ({
+            type: "turn_canceled",
+            provider: agent.provider,
+            reason: cancelReason,
+            turnId,
+        }));
+        this.foregroundRuns.settlePendingRun(agent.id);
         return {
             ...agent,
             lifecycle: "closed",
@@ -1507,6 +1524,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");
@@ -1521,70 +1539,14 @@ export class AgentManager {
     }
     async dispatchSessionEvent(agent, event) {
         const turnId = event.turnId;
-        const matchingWaiters = turnId == null
-            ? []
-            : Array.from(agent.foregroundTurnWaiters).filter((waiter) => waiter.turnId === turnId && !waiter.settled);
+        const matchingWaiters = this.foregroundRuns.getMatchingWaiters(agent, turnId);
         const shouldNotifyWaiters = await this.handleStreamEvent(agent, event);
         if (!shouldNotifyWaiters) {
             return;
         }
-        for (const waiter of matchingWaiters) {
-            waiter.callback(event);
-            if (isTurnTerminalEvent(event)) {
-                this.settleForegroundTurnWaiter(waiter);
-            }
-        }
-    }
-    settleForegroundTurnWaiter(waiter) {
-        if (waiter.settled) {
-            return;
-        }
-        waiter.settled = true;
-        waiter.resolveSettled();
-    }
-    rememberFinalizedForegroundTurn(agent, turnId) {
-        agent.finalizedForegroundTurnIds.add(turnId);
-        if (agent.finalizedForegroundTurnIds.size <= 50) {
-            return;
-        }
-        const oldest = agent.finalizedForegroundTurnIds.values().next().value;
-        if (oldest) {
-            agent.finalizedForegroundTurnIds.delete(oldest);
-        }
-    }
-    createPendingForegroundRun() {
-        let resolveSettled;
-        const settledPromise = new Promise((resolve) => {
-            resolveSettled = resolve;
+        this.foregroundRuns.notifyWaiters(matchingWaiters, event, {
+            terminal: isTurnTerminalEvent(event),
         });
-        return {
-            token: randomUUID(),
-            started: false,
-            settled: false,
-            settledPromise,
-            resolveSettled,
-        };
-    }
-    getPendingForegroundRun(agentId) {
-        return this.pendingForegroundRuns.get(agentId) ?? null;
-    }
-    hasPendingForegroundRun(agentId) {
-        return this.pendingForegroundRuns.has(agentId);
-    }
-    settlePendingForegroundRun(agentId, token) {
-        const pendingRun = this.pendingForegroundRuns.get(agentId);
-        if (!pendingRun) {
-            return;
-        }
-        if (token && pendingRun.token !== token) {
-            return;
-        }
-        this.pendingForegroundRuns.delete(agentId);
-        if (pendingRun.settled) {
-            return;
-        }
-        pendingRun.settled = true;
-        pendingRun.resolveSettled();
     }
     async resolveInitialPersistedTitle(agentId, config) {
         const existing = await this.registry?.get(agentId);
@@ -1671,14 +1633,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);
             }
@@ -1696,18 +1652,14 @@ export class AgentManager {
         if (!agent) {
             return;
         }
-        for (const waiter of agent.foregroundTurnWaiters) {
-            if (waiter.turnId === turnId && !waiter.settled) {
-                waiter.callback(event);
-            }
-        }
+        this.foregroundRuns.notifyAgentWaiters(agent, event);
     }
     async handleStreamEvent(agent, event, options) {
         const eventTurnId = event.turnId;
         const isForegroundEvent = Boolean(eventTurnId && agent.activeForegroundTurnId === eventTurnId);
         if (eventTurnId &&
             isTurnTerminalEvent(event) &&
-            agent.finalizedForegroundTurnIds.has(eventTurnId)) {
+            this.foregroundRuns.hasFinalizedTurn(agent, eventTurnId)) {
             return false;
         }
         // Only update timestamp for live events, not history replay
@@ -1718,185 +1670,240 @@ 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;
-            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;
+                return undefined;
+            case "mode_changed":
+                agent.currentModeId = event.currentModeId;
+                agent.availableModes = event.availableModes;
+                if (agent.runtimeInfo) {
+                    agent.runtimeInfo = { ...agent.runtimeInfo, modeId: event.currentModeId };
                 }
-                break;
-            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);
+                flags.shouldDispatchEvent = false;
+                this.emitState(agent);
+                return undefined;
+            case "model_changed":
+                agent.runtimeInfo = event.runtimeInfo;
+                if (!agent.persistence && event.runtimeInfo.sessionId) {
+                    agent.persistence = attachPersistenceCwd({ provider: agent.provider, sessionId: event.runtimeInfo.sessionId }, agent.cwd);
                 }
-                void this.refreshRuntimeInfo(agent);
-                break;
+                agent.currentModeId = event.runtimeInfo.modeId ?? agent.currentModeId;
+                flags.shouldDispatchEvent = false;
+                this.emitState(agent);
+                return undefined;
+            case "thinking_option_changed":
+                if (agent.runtimeInfo) {
+                    agent.runtimeInfo = {
+                        ...agent.runtimeInfo,
+                        thinkingOptionId: event.thinkingOptionId,
+                    };
+                }
+                flags.shouldDispatchEvent = false;
+                this.emitState(agent);
+                return undefined;
+            case "timeline":
+                return this.onStreamTimelineEvent({ agent, event, options, isForegroundEvent, flags });
+            case "turn_completed":
+                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 +2109,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 +2154,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) {