@getpaseo/server 0.1.15 → 0.1.17

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

@@ -0,0 +1,1712 @@
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { stat } from "node:fs/promises";
+import { AGENT_LIFECYCLE_STATUSES, } from "../../shared/agent-lifecycle.js";
+import { z } from "zod";
+import { AGENT_PROVIDER_IDS } from "./provider-manifest.js";
+export { AGENT_LIFECYCLE_STATUSES };
+const SYSTEM_ERROR_PREFIX = "[System Error]";
+function attachPersistenceCwd(handle, cwd) {
+    if (!handle) {
+        return null;
+    }
+    return {
+        ...handle,
+        metadata: {
+            ...(handle.metadata ?? {}),
+            cwd,
+        },
+    };
+}
+const DEFAULT_TIMELINE_FETCH_LIMIT = 200;
+const LIVE_BACKLOG_TERMINAL_REPLAY_DELAY_MS = 300;
+const BUSY_STATUSES = [
+    "initializing",
+    "running",
+];
+const AgentIdSchema = z.string().uuid();
+function isAgentBusy(status) {
+    return BUSY_STATUSES.includes(status);
+}
+function isTurnTerminalEvent(event) {
+    return (event.type === "turn_completed" ||
+        event.type === "turn_failed" ||
+        event.type === "turn_canceled");
+}
+function createAbortError(signal, fallbackMessage) {
+    const reason = signal?.reason;
+    const message = typeof reason === "string"
+        ? reason
+        : reason instanceof Error
+            ? reason.message
+            : fallbackMessage;
+    return Object.assign(new Error(message), { name: "AbortError" });
+}
+function validateAgentId(agentId, source) {
+    const result = AgentIdSchema.safeParse(agentId);
+    if (!result.success) {
+        throw new Error(`${source}: agentId must be a UUID`);
+    }
+    return result.data;
+}
+function supportsLiveEventStream(session) {
+    return ("streamLiveEvents" in session &&
+        typeof session.streamLiveEvents ===
+            "function");
+}
+function normalizeMessageId(messageId) {
+    if (typeof messageId !== "string") {
+        return undefined;
+    }
+    const trimmed = messageId.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+export class AgentManager {
+    constructor(options) {
+        this.clients = new Map();
+        this.agents = new Map();
+        this.subscribers = new Set();
+        this.previousStatuses = new Map();
+        this.backgroundTasks = new Set();
+        this.liveEventPumps = new Map();
+        this.liveEventBacklog = new Map();
+        this.liveEventBacklogFlushTimers = new Map();
+        const maxTimelineItems = options?.maxTimelineItems;
+        this.maxTimelineItems =
+            typeof maxTimelineItems === "number" &&
+                Number.isFinite(maxTimelineItems) &&
+                maxTimelineItems >= 0
+                ? Math.floor(maxTimelineItems)
+                : null;
+        this.idFactory = options?.idFactory ?? (() => randomUUID());
+        this.registry = options?.registry;
+        this.onAgentAttention = options?.onAgentAttention;
+        this.logger = options.logger.child({ module: "agent", component: "agent-manager" });
+        if (options?.clients) {
+            for (const [provider, client] of Object.entries(options.clients)) {
+                if (client) {
+                    this.registerClient(provider, client);
+                }
+            }
+        }
+    }
+    registerClient(provider, client) {
+        this.clients.set(provider, client);
+    }
+    setAgentAttentionCallback(callback) {
+        this.onAgentAttention = callback;
+    }
+    touchUpdatedAt(agent) {
+        const nowMs = Date.now();
+        const previousMs = agent.updatedAt.getTime();
+        const nextMs = nowMs > previousMs ? nowMs : previousMs + 1;
+        const next = new Date(nextMs);
+        agent.updatedAt = next;
+        return next;
+    }
+    subscribe(callback, options) {
+        const targetAgentId = options?.agentId == null
+            ? null
+            : validateAgentId(options.agentId, "subscribe");
+        const record = {
+            callback,
+            agentId: targetAgentId,
+        };
+        this.subscribers.add(record);
+        if (options?.replayState !== false) {
+            if (record.agentId) {
+                const agent = this.agents.get(record.agentId);
+                if (agent) {
+                    callback({
+                        type: "agent_state",
+                        agent: { ...agent },
+                    });
+                }
+            }
+            else {
+                // For global subscribers, skip internal agents during replay
+                for (const agent of this.agents.values()) {
+                    if (agent.internal) {
+                        continue;
+                    }
+                    callback({
+                        type: "agent_state",
+                        agent: { ...agent },
+                    });
+                }
+            }
+        }
+        return () => {
+            this.subscribers.delete(record);
+        };
+    }
+    listAgents() {
+        return Array.from(this.agents.values())
+            .filter((agent) => !agent.internal)
+            .map((agent) => ({
+            ...agent,
+        }));
+    }
+    async listPersistedAgents(options) {
+        if (options?.provider) {
+            const client = this.requireClient(options.provider);
+            if (!client.listPersistedAgents) {
+                return [];
+            }
+            return client.listPersistedAgents({ limit: options.limit });
+        }
+        const descriptors = [];
+        for (const [provider, client] of this.clients.entries()) {
+            if (!client.listPersistedAgents) {
+                continue;
+            }
+            try {
+                const entries = await client.listPersistedAgents({
+                    limit: options?.limit,
+                });
+                descriptors.push(...entries);
+            }
+            catch (error) {
+                this.logger.warn({ err: error, provider }, "Failed to list persisted agents for provider");
+            }
+        }
+        const limit = options?.limit ?? 20;
+        return descriptors
+            .sort((a, b) => b.lastActivityAt.getTime() - a.lastActivityAt.getTime())
+            .slice(0, limit);
+    }
+    async listProviderAvailability() {
+        const checks = AGENT_PROVIDER_IDS.map(async (providerId) => {
+            const provider = providerId;
+            const client = this.clients.get(provider);
+            if (!client) {
+                return {
+                    provider,
+                    available: false,
+                    error: `No client registered for provider '${provider}'`,
+                };
+            }
+            try {
+                const available = await client.isAvailable();
+                return {
+                    provider,
+                    available,
+                    error: null,
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.logger.warn({ err: error, provider }, "Failed to check provider availability");
+                return {
+                    provider,
+                    available: false,
+                    error: message,
+                };
+            }
+        });
+        return Promise.all(checks);
+    }
+    async listDraftCommands(config) {
+        const normalizedConfig = await this.normalizeConfig(config);
+        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 session = await client.createSession(normalizedConfig);
+        try {
+            if (!session.listCommands) {
+                throw new Error(`Provider '${normalizedConfig.provider}' does not support listing commands`);
+            }
+            return await session.listCommands();
+        }
+        finally {
+            try {
+                await session.close();
+            }
+            catch (error) {
+                this.logger.warn({ err: error, provider: normalizedConfig.provider }, "Failed to close draft command listing session");
+            }
+        }
+    }
+    getAgent(id) {
+        const agent = this.agents.get(id);
+        return agent ? { ...agent } : null;
+    }
+    getTimeline(id) {
+        const agent = this.requireAgent(id);
+        return [...agent.timeline];
+    }
+    getTimelineRows(id) {
+        const agent = this.requireAgent(id);
+        const { rows } = this.ensureTimelineState(agent);
+        return rows.map((row) => ({ ...row }));
+    }
+    fetchTimeline(id, options) {
+        const agent = this.requireAgent(id);
+        const { rows, epoch, nextSeq, minSeq, maxSeq, } = this.ensureTimelineState(agent);
+        const direction = options?.direction ?? "tail";
+        const requestedLimit = options?.limit;
+        const limit = requestedLimit === undefined
+            ? DEFAULT_TIMELINE_FETCH_LIMIT
+            : Math.max(0, Math.floor(requestedLimit));
+        const cursor = options?.cursor;
+        const window = { minSeq, maxSeq, nextSeq };
+        if (cursor && cursor.epoch !== epoch) {
+            return {
+                epoch,
+                direction,
+                reset: true,
+                staleCursor: true,
+                gap: false,
+                window,
+                hasOlder: false,
+                hasNewer: false,
+                rows: rows.map((row) => ({ ...row })),
+            };
+        }
+        const selectAll = limit === 0;
+        const cloneRows = (items) => items.map((row) => ({ ...row }));
+        if (direction === "after" && cursor && rows.length > 0 && cursor.seq < minSeq - 1) {
+            return {
+                epoch,
+                direction,
+                reset: true,
+                staleCursor: false,
+                gap: true,
+                window,
+                hasOlder: false,
+                hasNewer: false,
+                rows: cloneRows(rows),
+            };
+        }
+        if (rows.length === 0) {
+            return {
+                epoch,
+                direction,
+                reset: false,
+                staleCursor: false,
+                gap: false,
+                window,
+                hasOlder: false,
+                hasNewer: false,
+                rows: [],
+            };
+        }
+        if (direction === "tail") {
+            const selected = selectAll || limit >= rows.length ? rows : rows.slice(rows.length - limit);
+            const hasOlder = selected.length > 0 && selected[0].seq > minSeq;
+            return {
+                epoch,
+                direction,
+                reset: false,
+                staleCursor: false,
+                gap: false,
+                window,
+                hasOlder,
+                hasNewer: false,
+                rows: cloneRows(selected),
+            };
+        }
+        if (direction === "after") {
+            const baseSeq = cursor?.seq ?? 0;
+            const startIdx = rows.findIndex((row) => row.seq > baseSeq);
+            if (startIdx < 0) {
+                return {
+                    epoch,
+                    direction,
+                    reset: false,
+                    staleCursor: false,
+                    gap: false,
+                    window,
+                    hasOlder: baseSeq >= minSeq,
+                    hasNewer: false,
+                    rows: [],
+                };
+            }
+            const selected = selectAll ? rows.slice(startIdx) : rows.slice(startIdx, startIdx + limit);
+            const lastSelected = selected[selected.length - 1];
+            return {
+                epoch,
+                direction,
+                reset: false,
+                staleCursor: false,
+                gap: false,
+                window,
+                hasOlder: selected[0].seq > minSeq,
+                hasNewer: Boolean(lastSelected && lastSelected.seq < maxSeq),
+                rows: cloneRows(selected),
+            };
+        }
+        // direction === "before"
+        const beforeSeq = cursor?.seq ?? nextSeq;
+        const endExclusive = rows.findIndex((row) => row.seq >= beforeSeq);
+        const boundedRows = endExclusive < 0 ? rows : rows.slice(0, endExclusive);
+        const selected = selectAll || limit >= boundedRows.length
+            ? boundedRows
+            : boundedRows.slice(boundedRows.length - limit);
+        const hasOlder = selected.length > 0 && selected[0].seq > minSeq;
+        const hasNewer = endExclusive >= 0;
+        return {
+            epoch,
+            direction,
+            reset: false,
+            staleCursor: false,
+            gap: false,
+            window,
+            hasOlder,
+            hasNewer,
+            rows: cloneRows(selected),
+        };
+    }
+    async createAgent(config, agentId, options) {
+        // Generate agent ID early so we can use it in MCP config
+        const resolvedAgentId = validateAgentId(agentId ?? this.idFactory(), "createAgent");
+        const normalizedConfig = await this.normalizeConfig(config, {
+            labels: options?.labels,
+            agentId: 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 session = await client.createSession(normalizedConfig);
+        return this.registerSession(session, normalizedConfig, resolvedAgentId, { labels: options?.labels });
+    }
+    // Reconstruct an agent from provider persistence. Callers should explicitly
+    // hydrate timeline history after resume.
+    async resumeAgentFromPersistence(handle, overrides, agentId, options) {
+        const resolvedAgentId = validateAgentId(agentId ?? this.idFactory(), "resumeAgentFromPersistence");
+        const metadata = (handle.metadata ?? {});
+        const mergedConfig = {
+            ...metadata,
+            ...overrides,
+            provider: handle.provider,
+        };
+        const normalizedConfig = await this.normalizeConfig(mergedConfig);
+        const resumeOverrides = normalizedConfig.model !== mergedConfig.model
+            ? { ...overrides, model: normalizedConfig.model }
+            : overrides;
+        const client = this.requireClient(handle.provider);
+        const session = await client.resumeSession(handle, resumeOverrides);
+        return this.registerSession(session, normalizedConfig, resolvedAgentId, options);
+    }
+    // Hot-reload an active agent session with config overrides while preserving
+    // in-memory timeline state.
+    async reloadAgentSession(agentId, overrides) {
+        let existing = this.requireAgent(agentId);
+        if (existing.lifecycle === "running" || existing.pendingRun) {
+            await this.cancelAgentRun(agentId);
+            existing = this.requireAgent(agentId);
+        }
+        const timelineState = this.ensureTimelineState(existing);
+        const preservedTimeline = [...existing.timeline];
+        const preservedTimelineRows = timelineState.rows.map((row) => ({ ...row }));
+        const preservedTimelineEpoch = timelineState.epoch;
+        const preservedTimelineNextSeq = timelineState.nextSeq;
+        const preservedHistoryPrimed = existing.historyPrimed;
+        const preservedLastUsage = existing.lastUsage;
+        const preservedLastError = existing.lastError;
+        const preservedAttention = existing.attention;
+        const handle = existing.persistence;
+        const provider = handle?.provider ?? existing.provider;
+        const client = this.requireClient(provider);
+        const refreshConfig = {
+            ...existing.config,
+            ...overrides,
+            provider,
+        };
+        const normalizedConfig = await this.normalizeConfig(refreshConfig);
+        const session = handle
+            ? await client.resumeSession(handle, normalizedConfig)
+            : await client.createSession(normalizedConfig);
+        // Remove the existing agent entry before swapping sessions
+        this.agents.delete(agentId);
+        this.liveEventPumps.delete(agentId);
+        this.liveEventBacklog.delete(agentId);
+        this.clearLiveEventBacklogFlushTimer(agentId);
+        try {
+            await existing.session.close();
+        }
+        catch (error) {
+            this.logger.warn({ err: error, agentId }, "Failed to close previous session during refresh");
+        }
+        // Preserve existing labels and timeline during reload.
+        return this.registerSession(session, normalizedConfig, agentId, {
+            labels: existing.labels,
+            createdAt: existing.createdAt,
+            updatedAt: existing.updatedAt,
+            lastUserMessageAt: existing.lastUserMessageAt,
+            timeline: preservedTimeline,
+            timelineRows: preservedTimelineRows,
+            timelineEpoch: preservedTimelineEpoch,
+            timelineNextSeq: preservedTimelineNextSeq,
+            historyPrimed: preservedHistoryPrimed,
+            lastUsage: preservedLastUsage,
+            lastError: preservedLastError,
+            attention: preservedAttention,
+        });
+    }
+    async closeAgent(agentId) {
+        const agent = this.requireAgent(agentId);
+        this.logger.trace({
+            agentId,
+            lifecycle: agent.lifecycle,
+            hasPendingRun: Boolean(agent.pendingRun),
+            pendingPermissions: agent.pendingPermissions.size,
+        }, "closeAgent: start");
+        this.agents.delete(agentId);
+        this.liveEventPumps.delete(agentId);
+        this.liveEventBacklog.delete(agentId);
+        this.clearLiveEventBacklogFlushTimer(agentId);
+        // Clean up previousStatus to prevent memory leak
+        this.previousStatuses.delete(agentId);
+        const session = agent.session;
+        const closedAgent = {
+            ...agent,
+            lifecycle: "closed",
+            session: null,
+            pendingRun: null,
+        };
+        await session.close();
+        this.emitState(closedAgent);
+        this.logger.trace({ agentId }, "closeAgent: completed");
+    }
+    async setAgentMode(agentId, modeId) {
+        const agent = this.requireAgent(agentId);
+        await agent.session.setMode(modeId);
+        agent.currentModeId = modeId;
+        // Update runtimeInfo to reflect the new mode
+        if (agent.runtimeInfo) {
+            agent.runtimeInfo = { ...agent.runtimeInfo, modeId };
+        }
+        this.emitState(agent);
+    }
+    async setAgentModel(agentId, modelId) {
+        const agent = this.requireAgent(agentId);
+        const normalizedModelId = typeof modelId === "string" && modelId.trim().length > 0 ? modelId : null;
+        if (agent.session.setModel) {
+            await agent.session.setModel(normalizedModelId);
+        }
+        agent.config.model = normalizedModelId ?? undefined;
+        if (agent.runtimeInfo) {
+            agent.runtimeInfo = { ...agent.runtimeInfo, model: normalizedModelId };
+        }
+        this.emitState(agent);
+    }
+    async setAgentThinkingOption(agentId, thinkingOptionId) {
+        const agent = this.requireAgent(agentId);
+        const normalizedThinkingOptionId = typeof thinkingOptionId === "string" && thinkingOptionId.trim().length > 0
+            ? thinkingOptionId
+            : null;
+        if (agent.session.setThinkingOption) {
+            await agent.session.setThinkingOption(normalizedThinkingOptionId);
+        }
+        agent.config.thinkingOptionId = normalizedThinkingOptionId ?? undefined;
+        this.emitState(agent);
+    }
+    async setTitle(agentId, title) {
+        const agent = this.requireAgent(agentId);
+        const normalizedTitle = title.trim();
+        if (!normalizedTitle) {
+            return;
+        }
+        this.touchUpdatedAt(agent);
+        await this.persistSnapshot(agent, { title: normalizedTitle });
+        this.emitState(agent);
+    }
+    async setLabels(agentId, labels) {
+        const agent = this.requireAgent(agentId);
+        agent.labels = { ...agent.labels, ...labels };
+        await this.persistSnapshot(agent);
+        this.emitState(agent);
+    }
+    notifyAgentState(agentId) {
+        const agent = this.agents.get(agentId);
+        if (!agent || agent.internal) {
+            return;
+        }
+        this.touchUpdatedAt(agent);
+        this.emitState(agent);
+    }
+    async clearAgentAttention(agentId) {
+        const agent = this.requireAgent(agentId);
+        if (agent.attention.requiresAttention) {
+            agent.attention = { requiresAttention: false };
+            await this.persistSnapshot(agent);
+            this.emitState(agent);
+        }
+    }
+    async runAgent(agentId, prompt, options) {
+        const events = this.streamAgent(agentId, prompt, options);
+        const timeline = [];
+        let finalText = "";
+        let usage;
+        let canceled = false;
+        for await (const event of events) {
+            if (event.type === "timeline") {
+                timeline.push(event.item);
+            }
+            else if (event.type === "turn_completed") {
+                usage = event.usage;
+            }
+            else if (event.type === "turn_failed") {
+                throw new Error(this.formatTurnFailedMessage(event));
+            }
+            else if (event.type === "turn_canceled") {
+                canceled = true;
+            }
+        }
+        finalText = this.getLastAssistantMessageFromTimeline(timeline) ?? "";
+        const agent = this.requireAgent(agentId);
+        const sessionId = agent.persistence?.sessionId;
+        if (!sessionId) {
+            throw new Error(`Agent ${agentId} has no persistence.sessionId after run completed`);
+        }
+        return {
+            sessionId,
+            finalText,
+            usage,
+            timeline,
+            canceled,
+        };
+    }
+    recordUserMessage(agentId, text, options) {
+        const agent = this.requireAgent(agentId);
+        const normalizedMessageId = normalizeMessageId(options?.messageId);
+        const item = {
+            type: "user_message",
+            text,
+            messageId: normalizedMessageId,
+        };
+        const updatedAt = this.touchUpdatedAt(agent);
+        agent.lastUserMessageAt = updatedAt;
+        const row = this.recordTimeline(agent, item);
+        this.dispatchStream(agentId, {
+            type: "timeline",
+            item,
+            provider: agent.provider,
+        }, {
+            seq: row.seq,
+            epoch: this.ensureTimelineState(agent).epoch,
+        });
+        if (options?.emitState !== false) {
+            this.emitState(agent);
+        }
+    }
+    async appendTimelineItem(agentId, item) {
+        const agent = this.requireAgent(agentId);
+        this.touchUpdatedAt(agent);
+        const row = this.recordTimeline(agent, item);
+        this.dispatchStream(agentId, {
+            type: "timeline",
+            item,
+            provider: agent.provider,
+        }, {
+            seq: row.seq,
+            epoch: this.ensureTimelineState(agent).epoch,
+        });
+        await this.persistSnapshot(agent);
+    }
+    async emitLiveTimelineItem(agentId, item) {
+        const agent = this.requireAgent(agentId);
+        this.touchUpdatedAt(agent);
+        this.dispatchStream(agentId, {
+            type: "timeline",
+            item,
+            provider: agent.provider,
+        });
+    }
+    streamAgent(agentId, prompt, options) {
+        const existingAgent = this.requireAgent(agentId);
+        this.logger.trace({
+            agentId,
+            lifecycle: existingAgent.lifecycle,
+            hasPendingRun: Boolean(existingAgent.pendingRun),
+            promptType: typeof prompt === "string" ? "string" : "structured",
+            hasRunOptions: Boolean(options),
+        }, "streamAgent: requested");
+        if (existingAgent.pendingRun) {
+            this.logger.trace({
+                agentId,
+                lifecycle: existingAgent.lifecycle,
+            }, "streamAgent: rejected because pendingRun already exists");
+            throw new Error(`Agent ${agentId} already has an active run`);
+        }
+        const agent = existingAgent;
+        const iterator = agent.session.stream(prompt, options);
+        agent.lastError = undefined;
+        let finalized = false;
+        const finalize = (error) => {
+            this.logger.trace({
+                agentId,
+                error,
+                alreadyFinalized: finalized,
+                lifecycle: agent.lifecycle,
+                hasPendingRun: Boolean(agent.pendingRun),
+            }, "streamAgent.finalize: invoked");
+            if (finalized) {
+                return;
+            }
+            finalized = true;
+            if (agent.pendingRun !== streamForwarder) {
+                this.logger.trace({
+                    agentId,
+                    error,
+                    lifecycle: agent.lifecycle,
+                    hasPendingRun: Boolean(agent.pendingRun),
+                }, "streamAgent.finalize: skipped because pendingRun no longer points to streamForwarder");
+                if (error) {
+                    agent.lastError = error;
+                }
+                return;
+            }
+            const mutableAgent = agent;
+            mutableAgent.pendingRun = null;
+            const terminalError = error ?? mutableAgent.lastError;
+            mutableAgent.lifecycle = terminalError ? "error" : "idle";
+            mutableAgent.lastError = terminalError;
+            const persistenceHandle = mutableAgent.session.describePersistence() ??
+                (mutableAgent.runtimeInfo?.sessionId
+                    ? { provider: mutableAgent.provider, sessionId: mutableAgent.runtimeInfo.sessionId }
+                    : null);
+            if (persistenceHandle) {
+                mutableAgent.persistence = attachPersistenceCwd(persistenceHandle, mutableAgent.cwd);
+            }
+            this.logger.trace({
+                agentId,
+                lifecycle: mutableAgent.lifecycle,
+                hasPendingRun: Boolean(mutableAgent.pendingRun),
+                terminalError,
+            }, "streamAgent.finalize: applying terminal state");
+            this.emitState(mutableAgent);
+            this.flushLiveEventBacklog(mutableAgent);
+        };
+        const self = this;
+        const streamForwarder = (async function* streamForwarder() {
+            let finalizeError;
+            try {
+                for await (const event of iterator) {
+                    self.handleStreamEvent(agent, event);
+                    if (event.type === "turn_started" ||
+                        event.type === "turn_completed" ||
+                        event.type === "turn_failed" ||
+                        event.type === "turn_canceled") {
+                        self.logger.trace({
+                            agentId,
+                            eventType: event.type,
+                            lifecycle: agent.lifecycle,
+                            hasPendingRun: Boolean(agent.pendingRun),
+                        }, "streamAgent: forwarded terminal/turn event");
+                    }
+                    yield event;
+                }
+            }
+            catch (error) {
+                finalizeError =
+                    error instanceof Error ? error.message : "Agent stream failed";
+                self.handleStreamEvent(agent, {
+                    type: "turn_failed",
+                    provider: agent.provider,
+                    error: finalizeError,
+                });
+                throw error;
+            }
+            finally {
+                await self.refreshRuntimeInfo(agent);
+                // Ensure we always clear the pending run and emit state when the stream is
+                // cancelled early (e.g., via .return()) so the UI can exit the cancelling state.
+                finalize(finalizeError);
+            }
+        })();
+        agent.pendingRun = streamForwarder;
+        agent.lifecycle = "running";
+        // Bump updatedAt when lifecycle changes so downstream consumers can
+        // deterministically order idle->running transitions.
+        this.touchUpdatedAt(agent);
+        self.emitState(agent);
+        this.logger.trace({
+            agentId,
+            lifecycle: agent.lifecycle,
+            hasPendingRun: Boolean(agent.pendingRun),
+        }, "streamAgent: started");
+        return streamForwarder;
+    }
+    async waitForAgentRunStart(agentId, options) {
+        const snapshot = this.getAgent(agentId);
+        if (!snapshot) {
+            throw new Error(`Agent ${agentId} not found`);
+        }
+        if (snapshot.lifecycle === "running") {
+            return;
+        }
+        if (!("pendingRun" in snapshot) || !snapshot.pendingRun) {
+            throw new Error(`Agent ${agentId} has no pending run`);
+        }
+        if (options?.signal?.aborted) {
+            throw createAbortError(options.signal, "wait_for_agent_start aborted");
+        }
+        await new Promise((resolve, reject) => {
+            if (options?.signal?.aborted) {
+                reject(createAbortError(options.signal, "wait_for_agent_start aborted"));
+                return;
+            }
+            let unsubscribe = null;
+            let abortHandler = null;
+            const cleanup = () => {
+                if (unsubscribe) {
+                    try {
+                        unsubscribe();
+                    }
+                    catch {
+                        // ignore cleanup errors
+                    }
+                    unsubscribe = null;
+                }
+                if (abortHandler && options?.signal) {
+                    try {
+                        options.signal.removeEventListener("abort", abortHandler);
+                    }
+                    catch {
+                        // ignore cleanup errors
+                    }
+                    abortHandler = null;
+                }
+            };
+            const finishOk = () => {
+                cleanup();
+                resolve();
+            };
+            const finishErr = (error) => {
+                cleanup();
+                reject(error);
+            };
+            if (options?.signal) {
+                abortHandler = () => finishErr(createAbortError(options.signal, "wait_for_agent_start aborted"));
+                options.signal.addEventListener("abort", abortHandler, { once: true });
+            }
+            unsubscribe = this.subscribe((event) => {
+                if (event.type === "agent_state") {
+                    if (event.agent.id !== agentId) {
+                        return;
+                    }
+                    if (event.agent.lifecycle === "running") {
+                        finishOk();
+                        return;
+                    }
+                    if (event.agent.lifecycle === "error") {
+                        finishErr(new Error(event.agent.lastError ?? `Agent ${agentId} failed to start`));
+                        return;
+                    }
+                    if ("pendingRun" in event.agent && !event.agent.pendingRun) {
+                        finishErr(new Error(`Agent ${agentId} run finished before starting`));
+                        return;
+                    }
+                    return;
+                }
+            }, { agentId, replayState: true });
+        });
+    }
+    async respondToPermission(agentId, requestId, response) {
+        const agent = this.requireAgent(agentId);
+        await agent.session.respondToPermission(requestId, response);
+        agent.pendingPermissions.delete(requestId);
+        // Update currentModeId - the session may have changed mode internally
+        // (e.g., plan approval changes mode from "plan" to "acceptEdits")
+        try {
+            agent.currentModeId = await agent.session.getCurrentMode();
+        }
+        catch {
+            // Ignore errors from getCurrentMode - mode tracking is best effort
+        }
+        this.emitState(agent);
+    }
+    async cancelAgentRun(agentId) {
+        const agent = this.requireAgent(agentId);
+        const pendingRun = agent.pendingRun;
+        const hasForegroundPendingRun = Boolean(pendingRun) && typeof pendingRun?.return === "function";
+        const isAutonomousRunning = agent.lifecycle === "running" && !hasForegroundPendingRun;
+        if (!hasForegroundPendingRun && !isAutonomousRunning) {
+            return false;
+        }
+        try {
+            await agent.session.interrupt();
+        }
+        catch (error) {
+            this.logger.error({ err: error, agentId }, "Failed to interrupt session");
+        }
+        if (hasForegroundPendingRun && pendingRun) {
+            try {
+                // Await the generator's .return() to ensure the finally block runs
+                // and pendingRun is properly cleared before we return.
+                await pendingRun.return(undefined);
+            }
+            catch (error) {
+                this.logger.error({ err: error, agentId }, "Failed to cancel run");
+                throw error;
+            }
+        }
+        // Clear any pending permissions that weren't cleaned up by handleStreamEvent.
+        // Due to microtask ordering, .return() may force the generator to its finally
+        // block before it consumes the turn_canceled event, skipping our cleanup code.
+        if (agent.pendingPermissions.size > 0) {
+            for (const [requestId] of agent.pendingPermissions) {
+                this.dispatchStream(agent.id, {
+                    type: "permission_resolved",
+                    provider: agent.provider,
+                    requestId,
+                    resolution: { behavior: "deny", message: "Interrupted" },
+                });
+            }
+            agent.pendingPermissions.clear();
+            this.emitState(agent);
+        }
+        return true;
+    }
+    getPendingPermissions(agentId) {
+        const agent = this.requireAgent(agentId);
+        return Array.from(agent.pendingPermissions.values());
+    }
+    peekPendingPermission(agent) {
+        const iterator = agent.pendingPermissions.values().next();
+        return iterator.done ? null : iterator.value;
+    }
+    async hydrateTimelineFromProvider(agentId) {
+        const agent = this.requireAgent(agentId);
+        await this.hydrateTimeline(agent);
+    }
+    getLastAssistantMessage(agentId) {
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            return null;
+        }
+        return this.getLastAssistantMessageFromTimeline(agent.timeline);
+    }
+    getLastAssistantMessageFromTimeline(timeline) {
+        // Collect the last contiguous assistant messages (Claude streams chunks)
+        const chunks = [];
+        for (let i = timeline.length - 1; i >= 0; i--) {
+            const item = timeline[i];
+            if (item.type !== "assistant_message") {
+                if (chunks.length) {
+                    break;
+                }
+                continue;
+            }
+            chunks.push(item.text);
+        }
+        if (!chunks.length) {
+            return null;
+        }
+        return chunks.reverse().join("");
+    }
+    async waitForAgentEvent(agentId, options) {
+        const snapshot = this.getAgent(agentId);
+        if (!snapshot) {
+            throw new Error(`Agent ${agentId} not found`);
+        }
+        const hasPendingRun = "pendingRun" in snapshot && Boolean(snapshot.pendingRun);
+        const immediatePermission = this.peekPendingPermission(snapshot);
+        if (immediatePermission) {
+            return {
+                status: snapshot.lifecycle,
+                permission: immediatePermission,
+                lastMessage: this.getLastAssistantMessage(agentId)
+            };
+        }
+        const initialStatus = snapshot.lifecycle;
+        const initialBusy = isAgentBusy(initialStatus) || hasPendingRun;
+        const waitForActive = options?.waitForActive ?? false;
+        if (!waitForActive && !initialBusy) {
+            return {
+                status: initialStatus,
+                permission: null,
+                lastMessage: this.getLastAssistantMessage(agentId)
+            };
+        }
+        if (waitForActive && !initialBusy && !hasPendingRun) {
+            return {
+                status: initialStatus,
+                permission: null,
+                lastMessage: this.getLastAssistantMessage(agentId)
+            };
+        }
+        if (options?.signal?.aborted) {
+            throw createAbortError(options.signal, "wait_for_agent aborted");
+        }
+        return await new Promise((resolve, 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) {
+                reject(createAbortError(options.signal, "wait_for_agent aborted"));
+                return;
+            }
+            let currentStatus = initialStatus;
+            let hasStarted = initialBusy || hasPendingRun;
+            let terminalStatusOverride = null;
+            // Bug #3 Fix: Declare unsubscribe and abortHandler upfront so cleanup can reference them
+            let unsubscribe = null;
+            let abortHandler = null;
+            const cleanup = () => {
+                // Clean up subscription
+                if (unsubscribe) {
+                    try {
+                        unsubscribe();
+                    }
+                    catch {
+                        // ignore cleanup errors
+                    }
+                    unsubscribe = null;
+                }
+                // Clean up abort listener
+                if (abortHandler && options?.signal) {
+                    try {
+                        options.signal.removeEventListener("abort", abortHandler);
+                    }
+                    catch {
+                        // ignore cleanup errors
+                    }
+                    abortHandler = null;
+                }
+            };
+            const finish = (permission) => {
+                cleanup();
+                resolve({
+                    status: currentStatus,
+                    permission,
+                    lastMessage: this.getLastAssistantMessage(agentId)
+                });
+            };
+            // Bug #3 Fix: Set up abort handler BEFORE subscription
+            // to ensure cleanup handlers exist before callback can fire
+            if (options?.signal) {
+                abortHandler = () => {
+                    cleanup();
+                    reject(createAbortError(options.signal, "wait_for_agent aborted"));
+                };
+                options.signal.addEventListener("abort", abortHandler, { once: true });
+            }
+            // Bug #3 Fix: Now subscribe with cleanup handlers already in place
+            // This prevents race condition if callback fires synchronously with replayState: true
+            unsubscribe = this.subscribe((event) => {
+                if (event.type === "agent_state") {
+                    currentStatus = event.agent.lifecycle;
+                    const pending = this.peekPendingPermission(event.agent);
+                    if (pending) {
+                        finish(pending);
+                        return;
+                    }
+                    if (isAgentBusy(event.agent.lifecycle)) {
+                        hasStarted = true;
+                        return;
+                    }
+                    if (!waitForActive || hasStarted) {
+                        if (terminalStatusOverride) {
+                            currentStatus = terminalStatusOverride;
+                        }
+                        finish(null);
+                    }
+                    return;
+                }
+                if (event.type === "agent_stream") {
+                    if (event.event.type === "permission_requested") {
+                        finish(event.event.request);
+                        return;
+                    }
+                    if (event.event.type === "turn_failed") {
+                        hasStarted = true;
+                        terminalStatusOverride = "error";
+                        return;
+                    }
+                    if (event.event.type === "turn_completed") {
+                        hasStarted = true;
+                    }
+                    if (event.event.type === "turn_canceled") {
+                        hasStarted = true;
+                    }
+                }
+            }, { agentId, replayState: true });
+        });
+    }
+    async registerSession(session, config, agentId, options) {
+        const resolvedAgentId = validateAgentId(agentId, "registerSession");
+        if (this.agents.has(resolvedAgentId)) {
+            throw new Error(`Agent with id ${resolvedAgentId} already exists`);
+        }
+        const initialPersistedTitle = await this.resolveInitialPersistedTitle(resolvedAgentId, config);
+        const now = new Date();
+        const initialTimeline = options?.timeline ? [...options.timeline] : [];
+        const initialTimelineRows = options?.timelineRows?.length
+            ? options.timelineRows.map((row) => ({ ...row }))
+            : this.buildTimelineRowsFromItems(initialTimeline, options?.timelineNextSeq ?? 1, (options?.updatedAt ?? options?.createdAt ?? now).toISOString());
+        const derivedNextSeq = options?.timelineNextSeq ??
+            (initialTimelineRows.length
+                ? initialTimelineRows[initialTimelineRows.length - 1].seq + 1
+                : 1);
+        const managed = {
+            id: resolvedAgentId,
+            provider: config.provider,
+            cwd: config.cwd,
+            session,
+            capabilities: session.capabilities,
+            config,
+            runtimeInfo: undefined,
+            lifecycle: "initializing",
+            createdAt: options?.createdAt ?? now,
+            updatedAt: options?.updatedAt ?? now,
+            availableModes: [],
+            currentModeId: null,
+            pendingPermissions: new Map(),
+            pendingRun: null,
+            timeline: initialTimeline,
+            timelineRows: initialTimelineRows,
+            timelineEpoch: options?.timelineEpoch ?? randomUUID(),
+            timelineNextSeq: derivedNextSeq,
+            persistence: attachPersistenceCwd(session.describePersistence(), config.cwd),
+            historyPrimed: options?.historyPrimed ?? false,
+            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 },
+            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, {
+            title: initialPersistedTitle,
+        });
+        this.emitState(managed);
+        await this.refreshSessionState(managed);
+        managed.lifecycle = "idle";
+        await this.persistSnapshot(managed);
+        this.emitState(managed);
+        this.startLiveEventPump(managed);
+        return { ...managed };
+    }
+    async resolveInitialPersistedTitle(agentId, config) {
+        const existing = await this.registry?.get(agentId);
+        if (existing) {
+            return existing.title ?? null;
+        }
+        if (Object.prototype.hasOwnProperty.call(config, "title")) {
+            return config.title ?? null;
+        }
+        return null;
+    }
+    buildTimelineRowsFromItems(items, startSeq, timestamp) {
+        let nextSeq = startSeq;
+        return items.map((item) => {
+            const row = {
+                seq: nextSeq,
+                timestamp,
+                item,
+            };
+            nextSeq += 1;
+            return row;
+        });
+    }
+    ensureTimelineState(agent) {
+        const minSeq = agent.timelineRows.length ? agent.timelineRows[0].seq : 0;
+        const maxSeq = agent.timelineRows.length
+            ? agent.timelineRows[agent.timelineRows.length - 1].seq
+            : 0;
+        return {
+            rows: agent.timelineRows,
+            epoch: agent.timelineEpoch,
+            nextSeq: agent.timelineNextSeq,
+            minSeq,
+            maxSeq,
+        };
+    }
+    async persistSnapshot(agent, options) {
+        if (!this.registry) {
+            return;
+        }
+        // Don't persist internal agents - they're ephemeral system tasks
+        if (agent.internal) {
+            return;
+        }
+        await this.registry.applySnapshot(agent, options);
+    }
+    async refreshSessionState(agent) {
+        try {
+            const modes = await agent.session.getAvailableModes();
+            agent.availableModes = modes;
+        }
+        catch {
+            agent.availableModes = [];
+        }
+        try {
+            agent.currentModeId = await agent.session.getCurrentMode();
+        }
+        catch {
+            agent.currentModeId = null;
+        }
+        try {
+            const pending = agent.session.getPendingPermissions();
+            agent.pendingPermissions = new Map(pending.map((request) => [request.id, request]));
+        }
+        catch {
+            agent.pendingPermissions.clear();
+        }
+        await this.refreshRuntimeInfo(agent);
+    }
+    async refreshRuntimeInfo(agent) {
+        try {
+            const newInfo = await agent.session.getRuntimeInfo();
+            const changed = newInfo.model !== agent.runtimeInfo?.model ||
+                newInfo.thinkingOptionId !== agent.runtimeInfo?.thinkingOptionId ||
+                newInfo.sessionId !== agent.runtimeInfo?.sessionId ||
+                newInfo.modeId !== agent.runtimeInfo?.modeId;
+            agent.runtimeInfo = newInfo;
+            if (!agent.persistence && newInfo.sessionId) {
+                agent.persistence = attachPersistenceCwd({ provider: agent.provider, sessionId: newInfo.sessionId }, agent.cwd);
+            }
+            // Emit state if runtimeInfo changed so clients get the updated model
+            if (changed) {
+                this.emitState(agent);
+            }
+        }
+        catch {
+            // Keep existing runtimeInfo if refresh fails.
+        }
+    }
+    async hydrateTimeline(agent) {
+        if (agent.historyPrimed) {
+            return;
+        }
+        agent.historyPrimed = true;
+        const canonicalUserMessagesById = new Map(agent.timelineRows.flatMap((row) => {
+            if (row.item.type !== "user_message") {
+                return [];
+            }
+            const messageId = normalizeMessageId(row.item.messageId);
+            if (!messageId) {
+                return [];
+            }
+            return [[messageId, row.item.text]];
+        }));
+        try {
+            for await (const event of agent.session.streamHistory()) {
+                this.handleStreamEvent(agent, event, {
+                    fromHistory: true,
+                    canonicalUserMessagesById: canonicalUserMessagesById.size > 0 ? canonicalUserMessagesById : undefined,
+                });
+            }
+        }
+        catch {
+            // ignore history failures
+        }
+    }
+    handleStreamEvent(agent, event, options) {
+        // Only update timestamp for live events, not history replay
+        if (!options?.fromHistory) {
+            this.touchUpdatedAt(agent);
+        }
+        let timelineRow = null;
+        switch (event.type) {
+            case "thread_started":
+                // Update persistence with the new session ID from the provider.
+                // persistence.sessionId is the single source of truth for session identity.
+                {
+                    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);
+                        }
+                    }
+                }
+                break;
+            case "timeline":
+                // Skip provider-replayed user_message items during history hydration.
+                // These are already canonically recorded by recordUserMessage() and replaying them would
+                // create duplicates. Match by messageId (not text) to avoid dropping legitimate
+                // provider-origin messages that happen to reuse the same text.
+                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) {
+                            break;
+                        }
+                    }
+                }
+                if (this.shouldSuppressLiveUserMessageEcho(agent, event, options)) {
+                    break;
+                }
+                timelineRow = this.recordTimeline(agent, event.item);
+                if (!options?.fromHistory &&
+                    event.item.type === "user_message") {
+                    agent.lastUserMessageAt = new Date();
+                    this.emitState(agent);
+                }
+                break;
+            case "turn_completed":
+                this.logger.trace({
+                    agentId: agent.id,
+                    lifecycle: agent.lifecycle,
+                    hasPendingRun: Boolean(agent.pendingRun),
+                }, "handleStreamEvent: turn_completed");
+                agent.lastUsage = event.usage;
+                agent.lastError = undefined;
+                if (!agent.pendingRun && agent.lifecycle !== "idle") {
+                    agent.lifecycle = "idle";
+                    this.emitState(agent);
+                }
+                void this.refreshRuntimeInfo(agent);
+                break;
+            case "turn_failed":
+                agent.lifecycle = "error";
+                agent.lastError = event.error;
+                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" },
+                        });
+                    }
+                }
+                this.emitState(agent);
+                break;
+            case "turn_canceled":
+                this.logger.trace({
+                    agentId: agent.id,
+                    lifecycle: agent.lifecycle,
+                    hasPendingRun: Boolean(agent.pendingRun),
+                }, "handleStreamEvent: turn_canceled");
+                if (!agent.pendingRun) {
+                    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" },
+                        });
+                    }
+                }
+                this.emitState(agent);
+                break;
+            case "turn_started":
+                this.logger.trace({
+                    agentId: agent.id,
+                    lifecycle: agent.lifecycle,
+                    hasPendingRun: Boolean(agent.pendingRun),
+                }, "handleStreamEvent: turn_started");
+                if (!agent.pendingRun) {
+                    agent.lifecycle = "running";
+                    this.emitState(agent);
+                }
+                break;
+            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;
+            case "permission_resolved":
+                agent.pendingPermissions.delete(event.requestId);
+                this.emitState(agent);
+                break;
+            default:
+                break;
+        }
+        // Skip dispatching individual stream events during history replay.
+        if (!options?.fromHistory) {
+            this.dispatchStream(agent.id, event, timelineRow
+                ? {
+                    seq: timelineRow.seq,
+                    epoch: this.ensureTimelineState(agent).epoch,
+                }
+                : undefined);
+        }
+    }
+    appendSystemErrorTimelineMessage(agent, provider, message, options) {
+        if (options?.fromHistory) {
+            return;
+        }
+        const normalized = message.trim();
+        if (!normalized) {
+            return;
+        }
+        const text = `${SYSTEM_ERROR_PREFIX} ${normalized}`;
+        const lastItem = agent.timelineRows[agent.timelineRows.length - 1]?.item;
+        if (lastItem?.type === "assistant_message" && lastItem.text === text) {
+            return;
+        }
+        const item = { type: "assistant_message", text };
+        const row = this.recordTimeline(agent, item);
+        this.dispatchStream(agent.id, {
+            type: "timeline",
+            item,
+            provider,
+        }, {
+            seq: row.seq,
+            epoch: this.ensureTimelineState(agent).epoch,
+        });
+    }
+    formatTurnFailedMessage(event) {
+        const base = event.error.trim();
+        const parts = [base.length > 0 ? base : "Provider run failed"];
+        const code = event.code?.trim();
+        if (code) {
+            parts.push(`code: ${code}`);
+        }
+        const diagnostic = event.diagnostic?.trim();
+        if (diagnostic && diagnostic !== base) {
+            parts.push(diagnostic);
+        }
+        return parts.join("\n\n");
+    }
+    shouldSuppressLiveUserMessageEcho(agent, event, options) {
+        if (options?.fromHistory || event.type !== "timeline") {
+            return false;
+        }
+        if (event.item.type !== "user_message" || !agent.pendingRun) {
+            return false;
+        }
+        const eventMessageId = normalizeMessageId(event.item.messageId);
+        const eventText = event.item.text;
+        if (!eventMessageId) {
+            return false;
+        }
+        return agent.timelineRows.some((row) => {
+            const rowItem = row.item;
+            if (rowItem.type !== "user_message") {
+                return false;
+            }
+            const rowMessageId = normalizeMessageId(rowItem.messageId);
+            return rowMessageId === eventMessageId && rowItem.text === eventText;
+        });
+    }
+    recordTimeline(agent, item) {
+        const timelineState = this.ensureTimelineState(agent);
+        const row = {
+            seq: timelineState.nextSeq,
+            timestamp: new Date().toISOString(),
+            item,
+        };
+        agent.timelineNextSeq = timelineState.nextSeq + 1;
+        agent.timeline.push(item);
+        timelineState.rows.push(row);
+        if (typeof this.maxTimelineItems === "number" &&
+            agent.timeline.length > this.maxTimelineItems) {
+            const removeCount = agent.timeline.length - this.maxTimelineItems;
+            agent.timeline.splice(0, removeCount);
+            timelineState.rows.splice(0, removeCount);
+        }
+        return row;
+    }
+    emitState(agent) {
+        // Keep attention as an edge-triggered unread signal, not a level signal.
+        this.checkAndSetAttention(agent);
+        this.dispatch({
+            type: "agent_state",
+            agent: { ...agent },
+        });
+    }
+    checkAndSetAttention(agent) {
+        const previousStatus = this.previousStatuses.get(agent.id);
+        const currentStatus = agent.lifecycle;
+        // Track the new status
+        this.previousStatuses.set(agent.id, currentStatus);
+        // Skip attention tracking for internal agents
+        if (agent.internal) {
+            return;
+        }
+        // Skip if already requires attention
+        if (agent.attention.requiresAttention) {
+            return;
+        }
+        // Check if agent transitioned from running to idle (finished)
+        if (previousStatus === "running" && currentStatus === "idle") {
+            agent.attention = {
+                requiresAttention: true,
+                attentionReason: "finished",
+                attentionTimestamp: new Date(),
+            };
+            this.broadcastAgentAttention(agent, "finished");
+            this.enqueueBackgroundPersist(agent);
+            return;
+        }
+        // Check if agent entered error state
+        if (previousStatus !== "error" && currentStatus === "error") {
+            agent.attention = {
+                requiresAttention: true,
+                attentionReason: "error",
+                attentionTimestamp: new Date(),
+            };
+            this.broadcastAgentAttention(agent, "error");
+            this.enqueueBackgroundPersist(agent);
+            return;
+        }
+    }
+    enqueueBackgroundPersist(agent) {
+        const task = this.persistSnapshot(agent).catch((err) => {
+            this.logger.error({ err, agentId: agent.id }, "Failed to persist agent snapshot");
+        });
+        this.trackBackgroundTask(task);
+    }
+    trackBackgroundTask(task) {
+        this.backgroundTasks.add(task);
+        void task.finally(() => {
+            this.backgroundTasks.delete(task);
+        });
+    }
+    /**
+     * Flush any background persistence work (best-effort).
+     * Used by daemon shutdown paths to avoid unhandled rejections after cleanup.
+     */
+    async flush() {
+        // Drain tasks, including tasks spawned while awaiting.
+        while (this.backgroundTasks.size > 0) {
+            const pending = Array.from(this.backgroundTasks);
+            await Promise.allSettled(pending);
+        }
+    }
+    broadcastAgentAttention(agent, reason) {
+        this.onAgentAttention?.({
+            agentId: agent.id,
+            provider: agent.provider,
+            reason,
+        });
+    }
+    dispatchStream(agentId, event, metadata) {
+        this.dispatch({ type: "agent_stream", agentId, event, ...metadata });
+    }
+    dispatch(event) {
+        for (const subscriber of this.subscribers) {
+            if (subscriber.agentId &&
+                event.type === "agent_stream" &&
+                subscriber.agentId !== event.agentId) {
+                continue;
+            }
+            if (subscriber.agentId &&
+                event.type === "agent_state" &&
+                subscriber.agentId !== event.agent.id) {
+                continue;
+            }
+            // Skip internal agents for global subscribers (those without a specific agentId)
+            if (!subscriber.agentId) {
+                if (event.type === "agent_state" && event.agent.internal) {
+                    continue;
+                }
+                if (event.type === "agent_stream") {
+                    const agent = this.agents.get(event.agentId);
+                    if (agent?.internal) {
+                        continue;
+                    }
+                }
+            }
+            subscriber.callback(event);
+        }
+    }
+    async normalizeConfig(config, _options) {
+        const normalized = { ...config };
+        // Always resolve cwd to absolute path for consistent history file lookup
+        if (normalized.cwd) {
+            normalized.cwd = resolve(normalized.cwd);
+            try {
+                const cwdStats = await stat(normalized.cwd);
+                if (!cwdStats.isDirectory()) {
+                    throw new Error(`Working directory is not a directory: ${normalized.cwd}`);
+                }
+            }
+            catch (error) {
+                if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                    throw new Error(`Working directory does not exist: ${normalized.cwd}`);
+                }
+                if (error instanceof Error) {
+                    throw error;
+                }
+                throw new Error(`Failed to access working directory: ${normalized.cwd}`);
+            }
+        }
+        if (typeof normalized.model === "string") {
+            const trimmed = normalized.model.trim();
+            const normalizedId = trimmed.toLowerCase();
+            normalized.model =
+                trimmed.length > 0 && normalizedId !== "default" ? trimmed : undefined;
+        }
+        return normalized;
+    }
+    requireClient(provider) {
+        const client = this.clients.get(provider);
+        if (!client) {
+            throw new Error(`No client registered for provider '${provider}'`);
+        }
+        return client;
+    }
+    requireAgent(id) {
+        const normalizedId = validateAgentId(id, "requireAgent");
+        const agent = this.agents.get(normalizedId);
+        if (!agent) {
+            throw new Error(`Unknown agent '${normalizedId}'`);
+        }
+        return agent;
+    }
+    startLiveEventPump(agent) {
+        if (!supportsLiveEventStream(agent.session)) {
+            return;
+        }
+        if (this.liveEventPumps.has(agent.id)) {
+            return;
+        }
+        const pump = (async () => {
+            while (true) {
+                const current = this.agents.get(agent.id);
+                if (!current) {
+                    return;
+                }
+                if (!supportsLiveEventStream(current.session)) {
+                    return;
+                }
+                try {
+                    for await (const event of current.session.streamLiveEvents()) {
+                        const latest = this.agents.get(agent.id);
+                        if (!latest) {
+                            return;
+                        }
+                        // Keep consuming provider events even during an active foreground run,
+                        // then replay them immediately once that run settles.
+                        if (latest.pendingRun) {
+                            this.logger.trace({
+                                agentId: latest.id,
+                                eventType: event.type,
+                                backlogSize: (this.liveEventBacklog.get(latest.id)?.length ?? 0) + 1,
+                            }, "Live event pump: queued event because pendingRun is active");
+                            this.enqueueLiveEvent(latest.id, event);
+                            continue;
+                        }
+                        this.flushLiveEventBacklog(latest);
+                        this.handleStreamEvent(latest, event);
+                    }
+                    this.logger.warn({ agentId: agent.id }, "Live event pump stream ended; restarting");
+                }
+                catch (error) {
+                    this.logger.warn({ err: error, agentId: agent.id }, "Live event pump failed");
+                }
+                // Keep pump alive unless the agent is gone.
+                await new Promise((resolve) => setTimeout(resolve, 250));
+                const latest = this.agents.get(agent.id);
+                if (!latest) {
+                    return;
+                }
+                if (!latest.pendingRun) {
+                    this.flushLiveEventBacklog(latest);
+                }
+            }
+        })();
+        this.liveEventPumps.set(agent.id, pump);
+        pump.finally(() => {
+            const current = this.liveEventPumps.get(agent.id);
+            if (current === pump) {
+                this.liveEventPumps.delete(agent.id);
+            }
+        });
+    }
+    enqueueLiveEvent(agentId, event) {
+        const existing = this.liveEventBacklog.get(agentId);
+        if (existing) {
+            existing.push(event);
+            return;
+        }
+        this.liveEventBacklog.set(agentId, [event]);
+    }
+    clearLiveEventBacklogFlushTimer(agentId) {
+        const timer = this.liveEventBacklogFlushTimers.get(agentId);
+        if (!timer) {
+            return;
+        }
+        clearTimeout(timer);
+        this.liveEventBacklogFlushTimers.delete(agentId);
+    }
+    scheduleLiveEventBacklogFlush(agentId, delayMs) {
+        if (this.liveEventBacklogFlushTimers.has(agentId)) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            this.liveEventBacklogFlushTimers.delete(agentId);
+            const latest = this.agents.get(agentId);
+            if (!latest) {
+                return;
+            }
+            if (latest.pendingRun) {
+                this.scheduleLiveEventBacklogFlush(agentId, LIVE_BACKLOG_TERMINAL_REPLAY_DELAY_MS);
+                return;
+            }
+            this.flushLiveEventBacklog(latest);
+        }, delayMs);
+        this.liveEventBacklogFlushTimers.set(agentId, timer);
+    }
+    flushLiveEventBacklog(agent) {
+        if (agent.pendingRun) {
+            return;
+        }
+        const pending = this.liveEventBacklog.get(agent.id);
+        if (!pending || pending.length === 0) {
+            return;
+        }
+        this.clearLiveEventBacklogFlushTimer(agent.id);
+        this.liveEventBacklog.delete(agent.id);
+        const immediate = [];
+        const deferred = [];
+        let sawTurnStarted = false;
+        let deferRemainder = false;
+        for (const event of pending) {
+            if (!deferRemainder && sawTurnStarted && isTurnTerminalEvent(event)) {
+                deferRemainder = true;
+            }
+            if (deferRemainder) {
+                deferred.push(event);
+                continue;
+            }
+            immediate.push(event);
+            if (event.type === "turn_started") {
+                sawTurnStarted = true;
+            }
+        }
+        for (const event of immediate) {
+            this.handleStreamEvent(agent, event);
+        }
+        if (deferred.length === 0) {
+            return;
+        }
+        const existing = this.liveEventBacklog.get(agent.id);
+        if (existing && existing.length > 0) {
+            this.liveEventBacklog.set(agent.id, [...deferred, ...existing]);
+        }
+        else {
+            this.liveEventBacklog.set(agent.id, deferred);
+        }
+        this.scheduleLiveEventBacklogFlush(agent.id, LIVE_BACKLOG_TERMINAL_REPLAY_DELAY_MS);
+    }
+}
+//# sourceMappingURL=agent-manager.js.map