@agent-native/agentkit 0.2.4 → 0.2.5-nightly-20260917210345

package/dist/client/client.js

@@ -1,5 +1,5 @@
 import { AgentProtocolValidationError, AgentKitProtocolError, createRequestAbortedError, createAgentKitProtocolVersionOffer, parseAgentEvent, projectAgentCapabilities, resumeEntryFromApproval, } from "../protocol/index.js";
-import { classifyAgentEvent, createAgentThreadState, reduceAgentEvent, } from "./state.js";
+import { classifyAgentEvent, createAgentThreadState, reduceAgentEvent, settleRunProjection, } from "./state.js";
 /**
  * Creates the deterministic AgentKit controller used by every UI binding.
  * Prefer this factory at application boundaries; the class remains public for
@@ -8,6 +8,72 @@ import { classifyAgentEvent, createAgentThreadState, reduceAgentEvent, } from ".
 export function createAgentKitClient(options) {
     return new AgentKitClient(options);
 }
+function isTerminalRunEvent(event) {
+    return (event.type === "run.completed" ||
+        event.type === "run.failed" ||
+        event.type === "run.cancelled" ||
+        (event.type === "run.status" &&
+            (event.status === "completed" ||
+                event.status === "failed" ||
+                event.status === "cancelled")));
+}
+function sameQueuedMessageIds(first, second) {
+    return (first.length === second.length &&
+        first.every((message, index) => message.id === second[index]?.id));
+}
+function mergeQueuedMessageOverride(override, durable) {
+    const expectedIds = new Set(override.messages.map((message) => message.id));
+    const durableVisible = durable.filter((message) => !override.removedIds.has(message.id));
+    const merged = [...override.messages];
+    for (let index = 0; index < durableVisible.length; index += 1) {
+        const message = durableVisible[index];
+        if (expectedIds.has(message.id))
+            continue;
+        let nextExpectedIndex = -1;
+        for (let nextIndex = index + 1; nextIndex < durableVisible.length; nextIndex += 1) {
+            const candidateIndex = merged.findIndex((current) => current.id === durableVisible[nextIndex]?.id);
+            if (candidateIndex >= 0) {
+                nextExpectedIndex = candidateIndex;
+                break;
+            }
+        }
+        if (nextExpectedIndex >= 0) {
+            merged.splice(nextExpectedIndex, 0, message);
+            continue;
+        }
+        let previousExpectedIndex = -1;
+        for (let previousIndex = index - 1; previousIndex >= 0; previousIndex -= 1) {
+            const candidateIndex = merged.findIndex((current) => current.id === durableVisible[previousIndex]?.id);
+            if (candidateIndex >= 0) {
+                previousExpectedIndex = candidateIndex;
+                break;
+            }
+        }
+        if (previousExpectedIndex >= 0) {
+            merged.splice(previousExpectedIndex + 1, 0, message);
+        }
+        else {
+            merged.push(message);
+        }
+    }
+    return merged;
+}
+function mergeRuntimeRecordMap(loaded, baseline, current) {
+    if (current === baseline)
+        return loaded;
+    const merged = { ...loaded };
+    for (const id of Object.keys(baseline)) {
+        if (!Object.prototype.hasOwnProperty.call(current, id))
+            delete merged[id];
+    }
+    for (const [id, record] of Object.entries(current)) {
+        if (!Object.prototype.hasOwnProperty.call(baseline, id) ||
+            baseline[id] !== record) {
+            merged[id] = record;
+        }
+    }
+    return merged;
+}
 function defaultCreateId(prefix) {
     if (typeof crypto !== "undefined" && crypto.randomUUID) {
         return `${prefix}-${crypto.randomUUID()}`;
@@ -152,6 +218,8 @@ export class AgentKitClient {
     consumerAbortControllers = new Map();
     threadLoads = new Map();
     threadLeaseCounts = new Map();
+    queuedMessageOverrides = new Map();
+    queueMutationChains = new Map();
     queuePromotions = new Set();
     requestAbortController = new AbortController();
     capabilitiesLoad;
@@ -273,7 +341,10 @@ export class AgentKitClient {
         if (existing) {
             return this.invokeRequest(requestContext, () => existing);
         }
-        const load = this.loadThreadProjection(threadId, requestContext);
+        // Durable projections can lag an accepted stream. Preserve the local
+        // cursor and event boundaries so refresh cannot reorder the transcript or
+        // turn the next streamed event into an artificial sequence gap.
+        const load = this.loadThreadProjection(threadId, requestContext, true);
         this.threadLoads.set(threadId, load);
         try {
             return await load;
@@ -284,6 +355,17 @@ export class AgentKitClient {
             }
         }
     }
+    enqueueQueueMutation(threadId, mutation) {
+        const previous = this.queueMutationChains.get(threadId) ?? Promise.resolve();
+        const next = previous.then(mutation);
+        const settled = next.then(() => undefined, () => undefined);
+        this.queueMutationChains.set(threadId, settled);
+        return next.finally(() => {
+            if (this.queueMutationChains.get(threadId) === settled) {
+                this.queueMutationChains.delete(threadId);
+            }
+        });
+    }
     async loadThreadProjection(threadId, requestContext, preserveRuntimeProjection = false) {
         const baseline = this.snapshot.threads[threadId] ?? createAgentThreadState(threadId);
         if (!this.snapshot.threads[threadId])
@@ -301,6 +383,20 @@ export class AgentKitClient {
                 : undefined;
             this.assertActive();
             const runSnapshots = new Map((snapshot?.runs ?? []).map((run) => [run.id, run]));
+            const durableQueuedMessages = snapshot?.queuedMessages;
+            const queuedOverride = this.queuedMessageOverrides.get(threadId);
+            const queuedOverrideMessages = queuedOverride
+                ? durableQueuedMessages
+                    ? mergeQueuedMessageOverride(queuedOverride, durableQueuedMessages)
+                    : queuedOverride.messages
+                : undefined;
+            if (queuedOverride &&
+                durableQueuedMessages &&
+                queuedOverrideMessages &&
+                sameQueuedMessageIds(queuedOverrideMessages, durableQueuedMessages) &&
+                queuedOverride.removedIds.size === 0) {
+                this.queuedMessageOverrides.delete(threadId);
+            }
             const missingRunIds = (snapshot?.activeRunIds ?? []).filter((runId) => !runSnapshots.has(runId));
             const getRun = this.transport.getRun;
             const activeRuns = missingRunIds.length
@@ -351,26 +447,21 @@ export class AgentKitClient {
                     queuedMessages,
                 };
             }
-            if (preserveRuntimeProjection) {
-                const reconciliation = this.reconcileMessages(baseline.messages, thread.messages);
-                const runtimeProjection = this.remapThreadMessageReferences(baseline, reconciliation.idRemap);
-                const authoritative = {
-                    thread: thread.thread,
-                    messages: reconciliation.messages,
+            if (preserveRuntimeProjection && snapshot) {
+                const current = this.getThread(threadId);
+                thread = this.mergeLoadedThread(baseline, current, thread);
+                if (queuedOverrideMessages) {
                     // Queue mutations are already optimistic and independently durable.
                     // A completed-run snapshot can lag the accepted steer/remove write,
                     // so it must not resurrect work the client has already promoted.
-                    queuedMessages: baseline.queuedMessages,
-                };
-                thread = {
-                    ...this.mergeLoadedThread(createAgentThreadState(threadId), runtimeProjection, thread),
-                    ...authoritative,
-                };
+                    thread = { ...thread, queuedMessages: queuedOverrideMessages };
+                }
             }
             const current = this.getThread(threadId);
             if (current !== baseline) {
                 thread = this.mergeLoadedThread(baseline, current, thread);
             }
+            thread = this.settleTerminalThread(thread, snapshot);
             this.setThread(threadId, thread);
             this.setConnection("connected");
             for (const runId of thread.activeRunIds) {
@@ -488,9 +579,17 @@ export class AgentKitClient {
     }
     resubscribeRun(threadId, runId) {
         this.assertActive();
-        const status = this.getThread(threadId).runs[runId]?.status;
-        if (status && this.isTerminalStatus(status))
+        const thread = this.getThread(threadId);
+        const status = thread.runs[runId]?.status;
+        // A failed stream can be explicitly reattached to recover from a
+        // transient disconnect. Completed and cancelled runs have no live work to
+        // resume.
+        if (status === "completed" ||
+            status === "cancelled" ||
+            (status === "failed" &&
+                thread.events.some((event) => event.runId === runId && isTerminalRunEvent(event)))) {
             return Promise.resolve();
+        }
         const key = this.runKey(threadId, runId);
         const existing = this.consumers.get(key);
         if (existing)
@@ -680,19 +779,29 @@ export class AgentKitClient {
         if (!queueMessage) {
             throw new AgentKitCapabilityError("messageQueue");
         }
-        const result = await this.invokeRequest(requestContext, (context) => queueMessage({
-            threadId: input.threadId,
-            text: input.text,
-            attachments: input.attachments,
-            metadata: input.metadata,
-        }, context));
-        this.assertActive();
-        const thread = this.getThread(input.threadId);
-        this.setThread(input.threadId, {
-            ...thread,
-            queuedMessages: [...thread.queuedMessages, result.message],
+        return this.enqueueQueueMutation(input.threadId, async () => {
+            this.assertActive();
+            const result = await this.invokeRequest(requestContext, (context) => queueMessage({
+                threadId: input.threadId,
+                text: input.text,
+                attachments: input.attachments,
+                metadata: input.metadata,
+            }, context));
+            this.assertActive();
+            const thread = this.getThread(input.threadId);
+            this.setThread(input.threadId, {
+                ...thread,
+                queuedMessages: [...thread.queuedMessages, result.message],
+            });
+            const queueOverride = this.queuedMessageOverrides.get(input.threadId);
+            const removedIds = new Set(queueOverride?.removedIds);
+            removedIds.delete(result.message.id);
+            this.queuedMessageOverrides.set(input.threadId, {
+                messages: [...thread.queuedMessages, result.message],
+                removedIds,
+            });
+            return result.message;
         });
-        return result.message;
     }
     async removeQueuedMessage(threadId, messageId, context) {
         this.assertActive();
@@ -702,30 +811,52 @@ export class AgentKitClient {
         if (!removeQueuedMessage) {
             throw new AgentKitCapabilityError("messageQueue");
         }
-        const previous = this.getThread(threadId);
-        const removedIndex = previous.queuedMessages.findIndex((message) => message.id === messageId);
-        const removed = previous.queuedMessages[removedIndex];
-        this.setThread(threadId, {
-            ...previous,
-            queuedMessages: previous.queuedMessages.filter((message) => message.id !== messageId),
-        });
-        try {
-            await this.invokeRequest(requestContext, (context) => removeQueuedMessage({ threadId, messageId }, context));
+        return this.enqueueQueueMutation(threadId, async () => {
             this.assertActive();
-        }
-        catch (error) {
-            if (this.disposed)
-                throw error;
+            const previous = this.getThread(threadId);
+            const removedIndex = previous.queuedMessages.findIndex((message) => message.id === messageId);
+            const removed = previous.queuedMessages[removedIndex];
+            const previousOverride = this.queuedMessageOverrides.get(threadId);
             if (removed) {
-                const current = this.getThread(threadId);
-                if (!current.queuedMessages.some((message) => message.id === messageId)) {
-                    const queuedMessages = [...current.queuedMessages];
-                    queuedMessages.splice(Math.min(removedIndex, queuedMessages.length), 0, removed);
-                    this.setThread(threadId, { ...current, queuedMessages });
+                const queuedMessages = previous.queuedMessages.filter((message) => message.id !== messageId);
+                this.setThread(threadId, { ...previous, queuedMessages });
+                const removedIds = new Set(previousOverride?.removedIds);
+                removedIds.add(messageId);
+                this.queuedMessageOverrides.set(threadId, {
+                    messages: queuedMessages,
+                    removedIds,
+                });
+            }
+            try {
+                await this.invokeRequest(requestContext, (context) => removeQueuedMessage({ threadId, messageId }, context));
+                this.assertActive();
+            }
+            catch (error) {
+                if (this.disposed)
+                    throw error;
+                if (removed) {
+                    const current = this.getThread(threadId);
+                    if (!current.queuedMessages.some((message) => message.id === messageId)) {
+                        const queuedMessages = [...current.queuedMessages];
+                        queuedMessages.splice(Math.min(removedIndex, queuedMessages.length), 0, removed);
+                        this.setThread(threadId, { ...current, queuedMessages });
+                        const currentOverride = this.queuedMessageOverrides.get(threadId);
+                        const removedIds = new Set(currentOverride?.removedIds);
+                        removedIds.delete(messageId);
+                        if (currentOverride || removedIds.size > 0) {
+                            this.queuedMessageOverrides.set(threadId, {
+                                messages: queuedMessages,
+                                removedIds,
+                            });
+                        }
+                        else {
+                            this.queuedMessageOverrides.delete(threadId);
+                        }
+                    }
                 }
+                throw error;
             }
-            throw error;
-        }
+        });
     }
     async steerQueuedMessage(threadId, messageId, context) {
         this.assertActive();
@@ -735,68 +866,94 @@ export class AgentKitClient {
         if (!steerQueuedMessage) {
             throw new AgentKitCapabilityError("messageQueue");
         }
-        const previous = this.getThread(threadId);
-        const queued = previous.queuedMessages.find((message) => message.id === messageId);
-        if (!queued)
-            throw new Error(`Unknown queued message: ${messageId}`);
-        const message = {
-            id: queued.id,
-            role: "user",
-            createdAt: queued.createdAt,
-            status: "complete",
-            parts: [
-                { type: "text", text: queued.text },
-                ...(queued.attachments ?? []),
-            ],
-            metadata: queued.metadata,
-        };
-        const previousConnection = this.snapshot.connection;
-        const previousError = this.snapshot.error;
-        this.setThread(threadId, {
-            ...previous,
-            messages: [...previous.messages, message],
-            queuedMessages: previous.queuedMessages.filter((candidate) => candidate.id !== messageId),
-            suggestions: [],
-        });
-        this.setConnection("connecting");
-        try {
-            const result = await this.invokeRequest(requestContext, (context) => steerQueuedMessage({ threadId, messageId }, context));
+        return this.enqueueQueueMutation(threadId, async () => {
             this.assertActive();
-            if (!result) {
-                this.setConnection("connected");
-                return;
-            }
-            if (result.capabilities) {
-                this.patch({
-                    capabilities: result.capabilities,
-                    capabilitiesStatus: "ready",
-                });
-            }
-            this.markRunStarted(threadId, result.runId);
-            const completed = this.consume(threadId, result.runId);
-            this.trackConsumer(threadId, result.runId, completed);
-            return {
-                runId: result.runId,
-                completed,
-                cancel: () => this.cancelRun(threadId, result.runId),
+            const previous = this.getThread(threadId);
+            const queued = previous.queuedMessages.find((message) => message.id === messageId);
+            if (!queued)
+                throw new Error(`Unknown queued message: ${messageId}`);
+            const previousOverride = this.queuedMessageOverrides.get(threadId);
+            const message = {
+                id: queued.id,
+                role: "user",
+                createdAt: queued.createdAt,
+                status: "complete",
+                parts: [
+                    { type: "text", text: queued.text },
+                    ...(queued.attachments ?? []),
+                ],
+                metadata: queued.metadata,
             };
-        }
-        catch (error) {
-            if (this.disposed)
-                throw error;
-            const current = this.getThread(threadId);
-            const queuedMessages = current.queuedMessages.some((candidate) => candidate.id === queued.id)
-                ? current.queuedMessages
-                : [queued, ...current.queuedMessages];
+            const previousConnection = this.snapshot.connection;
+            const previousError = this.snapshot.error;
             this.setThread(threadId, {
-                ...current,
-                messages: current.messages.filter((candidate) => candidate.id !== message.id),
-                queuedMessages,
+                ...previous,
+                messages: [...previous.messages, message],
+                queuedMessages: previous.queuedMessages.filter((candidate) => candidate.id !== messageId),
+                suggestions: [],
             });
-            this.patch({ connection: previousConnection, error: previousError });
-            this.report(error, "queue_steer_failed");
-            throw error;
-        }
+            const removedIds = new Set(previousOverride?.removedIds);
+            removedIds.add(messageId);
+            this.queuedMessageOverrides.set(threadId, {
+                messages: previous.queuedMessages.filter((candidate) => candidate.id !== messageId),
+                removedIds,
+            });
+            this.setConnection("connecting");
+            try {
+                const result = await this.invokeRequest(requestContext, (context) => steerQueuedMessage({ threadId, messageId }, context));
+                this.assertActive();
+                if (!result) {
+                    this.setConnection("connected");
+                    return;
+                }
+                if (result.capabilities) {
+                    this.patch({
+                        capabilities: result.capabilities,
+                        capabilitiesStatus: "ready",
+                    });
+                }
+                this.markRunStarted(threadId, result.runId);
+                const completed = this.consume(threadId, result.runId);
+                this.trackConsumer(threadId, result.runId, completed);
+                return {
+                    runId: result.runId,
+                    completed,
+                    cancel: () => this.cancelRun(threadId, result.runId),
+                };
+            }
+            catch (error) {
+                if (this.disposed)
+                    throw error;
+                const current = this.getThread(threadId);
+                const queuedMessages = current.queuedMessages.some((candidate) => candidate.id === queued.id)
+                    ? current.queuedMessages
+                    : (() => {
+                        const restored = [...current.queuedMessages];
+                        restored.splice(Math.min(previous.queuedMessages.indexOf(queued), restored.length), 0, queued);
+                        return restored;
+                    })();
+                this.setThread(threadId, {
+                    ...current,
+                    messages: current.messages.filter((candidate) => candidate.id !== message.id),
+                    queuedMessages,
+                });
+                const currentOverride = this.queuedMessageOverrides.get(threadId);
+                const restoredRemovedIds = new Set(currentOverride?.removedIds);
+                restoredRemovedIds.delete(messageId);
+                if (currentOverride || restoredRemovedIds.size > 0) {
+                    this.queuedMessageOverrides.set(threadId, {
+                        messages: queuedMessages,
+                        removedIds: restoredRemovedIds,
+                    });
+                }
+                else {
+                    this.queuedMessageOverrides.delete(threadId);
+                }
+                this.patch({ connection: previousConnection, error: previousError });
+                this.report(error, "queue_steer_failed");
+                throw error;
+            }
+        });
     }
     async cancelRun(threadId, runId, context) {
         this.assertActive();
@@ -872,6 +1029,7 @@ export class AgentKitClient {
         await this.invokeRequest(requestContext, (context) => deleteThread({ threadId }, context));
         this.assertActive();
         this.stopThreadConsumers(threadId, "deleted");
+        this.queuedMessageOverrides.delete(threadId);
         const threads = { ...this.snapshot.threads };
         delete threads[threadId];
         this.patch({ threads });
@@ -886,6 +1044,8 @@ export class AgentKitClient {
         }
         this.consumerAbortControllers.clear();
         this.threadLeaseCounts.clear();
+        this.queueMutationChains.clear();
+        this.queuedMessageOverrides.clear();
         this.patch({ connection: "offline" });
         this.listeners.clear();
         this.consumers.clear();
@@ -953,9 +1113,7 @@ export class AgentKitClient {
                                 event.request.status === "failed")) {
                             interruptedForContinuation = false;
                         }
-                        if (event.type === "run.completed" ||
-                            event.type === "run.failed" ||
-                            event.type === "run.cancelled") {
+                        if (isTerminalRunEvent(event)) {
                             terminalEvent = event;
                         }
                     }
@@ -972,7 +1130,9 @@ export class AgentKitClient {
                         throw new Error(`AgentKit run ${runId} ended without a terminal event.`);
                     }
                     this.setConnection("connected");
-                    if (terminalEvent.type === "run.completed") {
+                    if (terminalEvent.type === "run.completed" ||
+                        (terminalEvent.type === "run.status" &&
+                            terminalEvent.status === "completed")) {
                         if (!this.threadLoads.has(threadId) &&
                             (this.transport.getThreadSnapshot || this.transport.getThread)) {
                             await this.loadThreadProjection(threadId, this.createRequestContext(), true);
@@ -1001,6 +1161,8 @@ export class AgentKitClient {
             if (abortController.signal.reason instanceof AgentKitConsumerStoppedError) {
                 return;
             }
+            const runError = toError(error, "run_stream_failed");
+            this.markRunFailed(threadId, runId, runError);
             this.fail(error, "run_stream_failed");
             throw error;
         }
@@ -1082,6 +1244,38 @@ export class AgentKitClient {
             Number.isFinite(current) &&
             expiration <= current);
     }
+    settleTerminalThread(thread, snapshot) {
+        const runs = Object.values(thread.runs);
+        const terminalRuns = runs.filter((run) => this.isTerminalStatus(run.status));
+        const settled = terminalRuns.reduce((currentThread, run) => settleRunProjection(currentThread, run.id, run.status, run.completedAt ?? this.now(), run.activeMessageId), thread);
+        if (thread.activeRunIds.length > 0 ||
+            runs.some((run) => !this.isTerminalStatus(run.status))) {
+            return settled;
+        }
+        const snapshotHasNoActiveRuns = snapshot?.activeRunIds?.length === 0 ||
+            (snapshot?.activeRunIds === undefined &&
+                snapshot?.runs !== undefined &&
+                snapshot.runs.length > 0 &&
+                snapshot.runs.every((run) => this.isTerminalStatus(run.status)));
+        if (!snapshotHasNoActiveRuns)
+            return settled;
+        // A snapshot can outlive the event association for its assistant message.
+        // If any known run failed or was cancelled, settle an unassociated message
+        // as an error rather than presenting a partial response as successful.
+        const settledMessageStatus = terminalRuns.length > 0 &&
+            terminalRuns.every((run) => run.status === "completed")
+            ? "complete"
+            : "error";
+        // Lifecycle events can age out independently of the message projection.
+        // Once the snapshot proves that no run remains active, any assistant
+        // message still marked streaming is stale rather than in-flight work.
+        return {
+            ...settled,
+            messages: settled.messages.map((message) => message.role === "assistant" && message.status === "streaming"
+                ? { ...message, status: settledMessageStatus }
+                : message),
+        };
+    }
     hydrateThread(snapshot, runs, activeRunIds) {
         let hydrated = createAgentThreadState(snapshot.id);
         for (const event of snapshot.events ?? []) {
@@ -1107,7 +1301,7 @@ export class AgentKitClient {
         ]));
         const mergedRuns = this.mergeRuns(hydrated.runs, runs);
         const currentActiveRunIds = activeRunIds.filter((runId) => !this.isTerminalStatus(mergedRuns[runId]?.status ?? "running"));
-        return {
+        const projected = {
             ...hydrated,
             thread: snapshot,
             // The snapshot projection is authoritative. The event log rebuilds all
@@ -1157,6 +1351,7 @@ export class AgentKitClient {
             artifacts: snapshot.artifacts ?? hydrated.artifacts,
             suggestions: snapshot.suggestions ?? hydrated.suggestions,
         };
+        return this.settleTerminalThread(projected, snapshot);
     }
     async requireCapability(capability, context) {
         const capabilities = await this.ensureCapabilities(context);
@@ -1180,81 +1375,86 @@ export class AgentKitClient {
         return new AgentKitCapabilityError(descriptor.id, unavailable ? "unavailable" : "unsupported", descriptor.error?.message ?? descriptor.description, descriptor.error?.retryable ?? unavailable, descriptor.error?.correlationId, descriptor.error?.details);
     }
     mergeLoadedThread(baseline, current, loaded) {
-        const runs = current.runs === baseline.runs
-            ? loaded.runs
-            : this.mergeRuns(loaded.runs, current.runs);
-        const activeRunIds = Array.from(new Set([...loaded.activeRunIds, ...current.activeRunIds])).filter((runId) => !this.isTerminalStatus(runs[runId]?.status ?? "running"));
+        const messagesChanged = current.messages !== baseline.messages;
+        const reconciliation = loaded.messages.length > 0
+            ? this.reconcileMessages(current.messages, loaded.messages)
+            : undefined;
+        const hasMessageIdRemap = (reconciliation?.idRemap.size ?? 0) > 0;
+        // Keep the live projection as the winner only for identities accepted by
+        // a concurrent stream. A content match still needs the durable identity
+        // when the stream finished before this refresh established its baseline.
+        const live = reconciliation
+            ? this.remapThreadMessageReferences(current, reconciliation.idRemap)
+            : current;
+        const loadedSnapshot = loaded.thread;
+        const snapshotIncludes = (key) => loadedSnapshot !== undefined &&
+            Object.prototype.hasOwnProperty.call(loadedSnapshot, key);
+        const snapshotIncludesRuntimeProjection = (key) => snapshotIncludes(key) || snapshotIncludes("events");
+        const mergeRecordProjection = (loadedProjection, baselineProjection, currentProjection, snapshotKey) => currentProjection === baselineProjection &&
+            !snapshotIncludesRuntimeProjection(snapshotKey)
+            ? currentProjection
+            : mergeRuntimeRecordMap(loadedProjection, baselineProjection, currentProjection);
+        const mergeListProjection = (loadedProjection, baselineProjection, currentProjection, snapshotKey) => {
+            if (currentProjection === baselineProjection &&
+                !snapshotIncludesRuntimeProjection(snapshotKey)) {
+                return currentProjection;
+            }
+            if (currentProjection === baselineProjection)
+                return loadedProjection;
+            const baselineById = new Map(baselineProjection.map((item) => [item.id, item]));
+            const currentById = new Map(currentProjection.map((item) => [item.id, item]));
+            const removedIds = new Set([...baselineById.keys()].filter((id) => !currentById.has(id)));
+            const changedItems = currentProjection.filter((item) => {
+                const baselineItem = baselineById.get(item.id);
+                return baselineItem === undefined || baselineItem !== item;
+            });
+            return this.mergeItemsById(loadedProjection.filter((item) => !removedIds.has(item.id)), changedItems);
+        };
+        const runs = this.mergeRuns(loaded.runs, live.runs);
+        const activeRunIds = Array.from(new Set([...loaded.activeRunIds, ...live.activeRunIds])).filter((runId) => !this.isTerminalStatus(runs[runId]?.status ?? "running"));
         return {
             ...loaded,
             thread: current.thread === baseline.thread ? loaded.thread : current.thread,
-            messages: current.messages === baseline.messages
-                ? loaded.messages
-                : this.mergeItemsById(loaded.messages, current.messages),
-            queuedMessages: current.queuedMessages === baseline.queuedMessages
-                ? loaded.queuedMessages
-                : this.mergeQueuedMessages(baseline.queuedMessages, loaded.queuedMessages, current.queuedMessages),
+            messages: messagesChanged || hasMessageIdRemap
+                ? reconciliation.messages
+                : loaded.messages.length > 0 || current.messages.length === 0
+                    ? loaded.messages
+                    : current.messages,
+            queuedMessages: current.queuedMessages === baseline.queuedMessages &&
+                !snapshotIncludes("queuedMessages")
+                ? current.queuedMessages
+                : this.mergeQueuedMessages(baseline.queuedMessages, loaded.queuedMessages, live.queuedMessages),
             runs,
             activeRunIds,
-            events: current.events === baseline.events
-                ? loaded.events
-                : this.mergeEvents(loaded.events, current.events),
-            agents: current.agents === baseline.agents
-                ? loaded.agents
-                : { ...loaded.agents, ...current.agents },
-            agentInteractions: current.agentInteractions === baseline.agentInteractions
-                ? loaded.agentInteractions
-                : this.mergeItemsById(loaded.agentInteractions, current.agentInteractions),
-            activities: current.activities === baseline.activities
-                ? loaded.activities
-                : { ...loaded.activities, ...current.activities },
-            tasks: current.tasks === baseline.tasks
-                ? loaded.tasks
-                : { ...loaded.tasks, ...current.tasks },
-            tools: current.tools === baseline.tools
-                ? loaded.tools
-                : { ...loaded.tools, ...current.tools },
-            approvals: current.approvals === baseline.approvals
-                ? loaded.approvals
-                : current.approvals,
-            approvalRunIds: current.approvalRunIds === baseline.approvalRunIds
-                ? loaded.approvalRunIds
-                : current.approvalRunIds,
-            connectionRequests: current.connectionRequests === baseline.connectionRequests
-                ? loaded.connectionRequests
-                : { ...loaded.connectionRequests, ...current.connectionRequests },
-            connectionRequestRunIds: current.connectionRequestRunIds === baseline.connectionRequestRunIds
-                ? loaded.connectionRequestRunIds
-                : {
-                    ...loaded.connectionRequestRunIds,
-                    ...current.connectionRequestRunIds,
-                },
-            artifacts: current.artifacts === baseline.artifacts
-                ? loaded.artifacts
-                : this.mergeItemsById(loaded.artifacts, current.artifacts),
-            widgets: current.widgets === baseline.widgets
-                ? loaded.widgets
-                : { ...loaded.widgets, ...current.widgets },
-            widgetMessageIds: current.widgetMessageIds === baseline.widgetMessageIds
-                ? loaded.widgetMessageIds
-                : { ...loaded.widgetMessageIds, ...current.widgetMessageIds },
-            annotations: current.annotations === baseline.annotations
-                ? loaded.annotations
-                : { ...loaded.annotations, ...current.annotations },
-            annotationMessageIds: current.annotationMessageIds === baseline.annotationMessageIds
-                ? loaded.annotationMessageIds
-                : {
-                    ...loaded.annotationMessageIds,
-                    ...current.annotationMessageIds,
-                },
-            suggestions: current.suggestions === baseline.suggestions
-                ? loaded.suggestions
+            events: reconciliation
+                ? this.mergeEvents(loaded.events, live.events)
+                : current.events === baseline.events && !snapshotIncludes("events")
+                    ? live.events
+                    : current.events === baseline.events
+                        ? loaded.events
+                        : this.mergeEvents(loaded.events, live.events),
+            agents: mergeRecordProjection(loaded.agents, baseline.agents, live.agents, "agents"),
+            agentInteractions: mergeListProjection(loaded.agentInteractions, baseline.agentInteractions, live.agentInteractions, "interactions"),
+            activities: mergeRecordProjection(loaded.activities, baseline.activities, live.activities, "activities"),
+            tasks: mergeRecordProjection(loaded.tasks, baseline.tasks, live.tasks, "tasks"),
+            taskGroups: mergeRecordProjection(loaded.taskGroups, baseline.taskGroups, live.taskGroups, "taskGroups"),
+            tools: mergeRecordProjection(loaded.tools, baseline.tools, live.tools, "toolCalls"),
+            approvals: mergeRecordProjection(loaded.approvals, baseline.approvals, live.approvals, "approvals"),
+            approvalRunIds: mergeRecordProjection(loaded.approvalRunIds, baseline.approvalRunIds, live.approvalRunIds, "approvals"),
+            connectionRequests: mergeRecordProjection(loaded.connectionRequests, baseline.connectionRequests, live.connectionRequests, "connectionRequests"),
+            connectionRequestRunIds: mergeRecordProjection(loaded.connectionRequestRunIds, baseline.connectionRequestRunIds, live.connectionRequestRunIds, "connectionRequests"),
+            artifacts: mergeListProjection(loaded.artifacts, baseline.artifacts, live.artifacts, "artifacts"),
+            widgets: mergeRecordProjection(loaded.widgets, baseline.widgets, live.widgets, "widgets"),
+            widgetMessageIds: mergeRecordProjection(loaded.widgetMessageIds, baseline.widgetMessageIds, live.widgetMessageIds, "widgets"),
+            annotations: mergeRecordProjection(loaded.annotations, baseline.annotations, live.annotations, "annotations"),
+            annotationMessageIds: mergeRecordProjection(loaded.annotationMessageIds, baseline.annotationMessageIds, live.annotationMessageIds, "annotations"),
+            suggestions: snapshotIncludesRuntimeProjection("suggestions")
+                ? current.suggestions === baseline.suggestions
+                    ? loaded.suggestions
+                    : live.suggestions
                 : current.suggestions,
-            actions: current.actions === baseline.actions
-                ? loaded.actions
-                : { ...loaded.actions, ...current.actions },
-            uploads: current.uploads === baseline.uploads
-                ? loaded.uploads
-                : { ...loaded.uploads, ...current.uploads },
+            actions: mergeRecordProjection(loaded.actions, baseline.actions, live.actions, "events"),
+            uploads: mergeRecordProjection(loaded.uploads, baseline.uploads, live.uploads, "events"),
         };
     }
     mergeRuns(first, second) {
@@ -1290,9 +1490,8 @@ export class AgentKitClient {
         return merged;
     }
     reconcileMessages(current, durable) {
-        if (durable.length === 0) {
+        if (durable.length === 0)
             return { messages: current, idRemap: new Map() };
-        }
         const durableIds = new Set(durable.map((message) => message.id));
         const currentIds = new Set(current.map((message) => message.id));
         const unmatchedContent = new Map();
@@ -1307,22 +1506,68 @@ export class AgentKitClient {
                 message,
             ]);
         }
-        const optimistic = [];
         const idRemap = new Map();
-        for (const message of current) {
-            if (durableIds.has(message.id))
-                continue;
+        let hasMatchedMessage = false;
+        const liveMessages = current.map((message) => {
+            if (durableIds.has(message.id)) {
+                hasMatchedMessage = true;
+                return message;
+            }
             const key = this.messageContentKey(message);
             const matches = unmatchedContent.get(key);
             const durableMatch = matches?.shift();
             if (durableMatch) {
+                hasMatchedMessage = true;
                 idRemap.set(message.id, durableMatch.id);
+                return durableMatch;
+            }
+            return message;
+        });
+        if (!hasMatchedMessage) {
+            return { messages: [...durable, ...current], idRemap };
+        }
+        const presentIds = new Set(liveMessages.map((message) => message.id));
+        const messages = [...liveMessages];
+        for (let durableIndex = 0; durableIndex < durable.length; durableIndex++) {
+            const message = durable[durableIndex];
+            if (presentIds.has(message.id))
+                continue;
+            let insertBefore = -1;
+            for (let nextIndex = durableIndex + 1; nextIndex < durable.length; nextIndex++) {
+                const nextId = durable[nextIndex]?.id;
+                if (!nextId)
+                    continue;
+                const candidateIndex = messages.findIndex((currentMessage) => currentMessage.id === nextId);
+                if (candidateIndex >= 0) {
+                    insertBefore = candidateIndex;
+                    break;
+                }
+            }
+            if (insertBefore >= 0) {
+                messages.splice(insertBefore, 0, message);
             }
             else {
-                optimistic.push(message);
+                let previousDurableIndex = -1;
+                for (let previousIndex = durableIndex - 1; previousIndex >= 0; previousIndex -= 1) {
+                    const previousId = durable[previousIndex]?.id;
+                    if (!previousId)
+                        continue;
+                    const candidateIndex = messages.findIndex((currentMessage) => currentMessage.id === previousId);
+                    if (candidateIndex >= 0) {
+                        previousDurableIndex = candidateIndex;
+                        break;
+                    }
+                }
+                if (previousDurableIndex >= 0) {
+                    messages.splice(previousDurableIndex + 1, 0, message);
+                }
+                else {
+                    messages.unshift(message);
+                }
             }
+            presentIds.add(message.id);
         }
-        return { messages: [...durable, ...optimistic], idRemap };
+        return { messages, idRemap };
     }
     remapThreadMessageReferences(thread, idRemap) {
         if (idRemap.size === 0)
@@ -1412,13 +1657,38 @@ export class AgentKitClient {
     }
     mergeEvents(first, second) {
         const merged = [...first];
-        const keys = new Set(first.map((event) => `${event.threadId}\u0000${event.runId}\u0000${event.sequence}`));
+        const indexByKey = new Map(first.map((event, index) => [
+            `${event.threadId}\u0000${event.runId}\u0000${event.sequence}`,
+            index,
+        ]));
         for (const event of second) {
             const key = `${event.threadId}\u0000${event.runId}\u0000${event.sequence}`;
-            if (!keys.has(key)) {
-                keys.add(key);
+            const existingIndex = indexByKey.get(key);
+            if (existingIndex === undefined) {
+                indexByKey.set(key, merged.length);
                 merged.push(event);
             }
+            else {
+                // The second projection is the live stream. It may contain richer
+                // payloads than a snapshot captured before that event was persisted.
+                merged[existingIndex] = event;
+            }
+        }
+        // Sequences are scoped to a run, so there is no valid global numeric sort.
+        // Keep cross-run interleaving stable while repairing each run's local
+        // order in the slots it already occupies.
+        const positionsByRun = new Map();
+        merged.forEach((event, index) => {
+            const positions = positionsByRun.get(event.runId) ?? [];
+            positions.push(index);
+            positionsByRun.set(event.runId, positions);
+        });
+        for (const positions of positionsByRun.values()) {
+            const events = positions.map((index) => merged[index]);
+            events.sort((left, right) => left.sequence - right.sequence);
+            positions.forEach((index, position) => {
+                merged[index] = events[position];
+            });
         }
         return merged;
     }
@@ -1449,18 +1719,37 @@ export class AgentKitClient {
         const thread = this.getThread(threadId);
         const run = thread.runs[runId] ?? this.runState(runId);
         const activeRunIds = thread.activeRunIds.filter((id) => id !== runId);
-        this.setThread(threadId, {
+        const completedAt = this.now();
+        this.setThread(threadId, settleRunProjection({
             ...thread,
             runs: {
                 ...thread.runs,
                 [runId]: {
                     ...run,
                     status: "cancelled",
-                    completedAt: this.now(),
+                    completedAt,
                 },
             },
             activeRunIds,
-        });
+        }, runId, "cancelled", completedAt, run.activeMessageId));
+    }
+    markRunFailed(threadId, runId, error) {
+        const thread = this.getThread(threadId);
+        const run = thread.runs[runId] ?? this.runState(runId);
+        const completedAt = this.now();
+        this.setThread(threadId, settleRunProjection({
+            ...thread,
+            runs: {
+                ...thread.runs,
+                [runId]: {
+                    ...run,
+                    status: "failed",
+                    completedAt,
+                    error,
+                },
+            },
+            activeRunIds: thread.activeRunIds.filter((id) => id !== runId),
+        }, runId, "failed", completedAt, run.activeMessageId));
     }
     markRunStarted(threadId, runId) {
         const thread = this.getThread(threadId);
@@ -1494,6 +1783,7 @@ export class AgentKitClient {
             completedAt: run?.completedAt,
             usage: run?.usage,
             error: run?.error,
+            activeMessageId: run?.activeMessageId,
         };
     }
     runSnapshot(threadId, runId) {
@@ -1565,7 +1855,13 @@ export class AgentKitClient {
                 receivedSequence: admission.receivedSequence,
             });
         }
-        this.setThread(event.threadId, reduceAgentEvent(thread, event));
+        const next = reduceAgentEvent(thread, event);
+        if (event.type === "queue.updated") {
+            // A replayed queue snapshot is the ordered server view. It supersedes
+            // the temporary protection used while a queue mutation catches up.
+            this.queuedMessageOverrides.delete(event.threadId);
+        }
+        this.setThread(event.threadId, next);
     }
     setThread(threadId, thread) {
         this.patch({