@superblocksteam/gateway 2.0.166 → 2.0.168-next.0

package/dist/sabs/websocket-session-peer.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { WebSocket } from "ws";
+import { AiMode as SharedAiMode, } from "@superblocksteam/library-shared/types";
 import { createISocketClient, ISocket, SocketHeartbeat, } from "@superblocksteam/shared";
 import { canonicalizeOrchestratorBaseUrl, orchestratorUrlDependsOnProfile, pickOrchestratorBaseUrl, } from "../agents/resolve-orchestrator-url.js";
 import { gatewayDebug } from "../debug.js";
@@ -10,7 +11,7 @@ import { recordCheckpointOutcome, recordIntegrationProfileResolution, } from "..
 import { sanitizeAgentFacingText } from "./agent-facing-text.js";
 import { AppState } from "./app-state.js";
 import { buildBrowserContext } from "./browser-context.js";
-import { createEditorClientMethods, loadIntegrationsForPrompt, } from "./editor-client-methods.js";
+import { createEditorClientMethods, loadIntegrationsForPrompt, ToolPermissionListenerUnavailableError, } from "./editor-client-methods.js";
 import { EditorSocket } from "./editor-socket.js";
 import { appendRecentToolRun, buildRecentToolRun } from "./recent-tool-runs.js";
 import { PromptNotSentError, } from "./session-peer.js";
@@ -185,6 +186,12 @@ const DEFAULT_RECONNECT_GRACE_MS = 20_000;
  * on, so reconnect attempts are capped independently.
  */
 const DEFAULT_RECONNECT_ATTEMPTS = 3;
+/**
+ * How many times a takeover rereads a claim snapshot that browser events keep
+ * overtaking. Every read it made was answered, so running out keeps the claim
+ * instead of failing a working socket as unreachable.
+ */
+const MAX_CLAIM_REFRESHES = 3;
 /**
  * After the job settles, how long to wait for the dev server to finish flushing
  * Clark's files before giving up on checkpointing them.
@@ -226,6 +233,106 @@ function isBrowserObserverEvent(event) {
         (event.kind === "generation_state" &&
             event.gatewayObserverSource === "browser"));
 }
+/**
+ * Names why a New Chat reset must be ignored, or returns undefined when it may
+ * clear chat state. A reset for another generation, or one that cannot be
+ * matched to a turn still running, would otherwise end a turn it was never
+ * about.
+ */
+function ignoredChatResetReason(held, reset, previous) {
+    if (held.pendingTurn) {
+        return "pending_turn";
+    }
+    if (previous &&
+        (!reset.generationId || !previous.generationId) &&
+        !previous.finished &&
+        !previous.collector.isSettling()) {
+        return "unkeyed_active_turn";
+    }
+    if (reset.generationId &&
+        previous?.generationId &&
+        reset.generationId !== previous.generationId) {
+        return "other_generation";
+    }
+    return undefined;
+}
+/**
+ * Outcomes that leave the turn with the editor: one waiting on the user, and
+ * one that may still be running where only the editor can see it. An idle
+ * editor refutes both.
+ */
+function leavesTurnWithEditor(outcome) {
+    return outcome === "detached" || outcome === "needs_decision";
+}
+/**
+ * Whether a snapshot shows nothing newer than the owned turn's outcome: an idle
+ * editor, the owned generation completing as the turn already reported, or
+ * that generation still waiting on the tool permission the turn asked for. A
+ * permission reaches the gateway over its own RPC and never appears as the
+ * snapshot's interactive message, so the editor waiting with none is that
+ * permission still pending.
+ */
+function agreesWithOwnedOutcome({ generationId, state }, { hasActiveInteractiveMessage, owned, }) {
+    const outcome = owned?.finished;
+    if (!outcome) {
+        return false;
+    }
+    if (state === "idle") {
+        return !leavesTurnWithEditor(outcome.generationStatus);
+    }
+    if (generationId !== owned.generationId) {
+        return false;
+    }
+    if (state === "completed") {
+        return (outcome.generationStatus === "completed" ||
+            outcome.generationStatus === "no_changes");
+    }
+    return (state === "awaiting_user_input" &&
+        !hasActiveInteractiveMessage &&
+        outcome.decision?.kind === "tool_permission");
+}
+/**
+ * Whether a snapshot read while taking a turn over is that turn's own state,
+ * to replay onto it. One naming the turn's generation is, unless it awaits a
+ * decision it does not carry. So is an idle one naming no generation: that is
+ * what the editor shows once nothing runs and no terminal state is left to
+ * show, and the turn's collector still ignores an idle before the turn was
+ * seen generating.
+ */
+function replaysOntoTurn(generationState, known) {
+    if (!generationState.generationId) {
+        return generationState.state === "idle";
+    }
+    return (generationState.generationId === known.turn.generationId &&
+        (generationState.state !== "awaiting_user_input" ||
+            known.hasActiveInteractiveMessage ||
+            known.turn.collector.decision() !== undefined));
+}
+/**
+ * What a chat snapshot read on attach says about the turn this peer knew of.
+ *
+ * `unchanged` when it shows nothing newer than a finished owned turn (see
+ * {@link agreesWithOwnedOutcome}). Clearing then would erase the turn's
+ * outcome, checkpoint, retry advice or pending permission while the editor
+ * agrees with them. `settled` when nothing is running or waiting on the user.
+ * `observable` when there is a generation to follow: one running, one waiting
+ * on an answer, or the watched generation completing.
+ */
+function readChatSnapshot(generationState, known) {
+    if (agreesWithOwnedOutcome(generationState, known)) {
+        return "unchanged";
+    }
+    const { generationId, state } = generationState;
+    const { owned } = known;
+    const watchedGenerationId = known.observedGenerationId ?? owned?.generationId;
+    if (state === "idle" ||
+        (state === "completed" &&
+            (!watchedGenerationId || watchedGenerationId !== generationId)) ||
+        (state === "awaiting_user_input" && !known.hasActiveInteractiveMessage)) {
+        return "settled";
+    }
+    return "observable";
+}
 export function buildSessionUrl(input) {
     // liveEditUrl is server-sourced (connectLiveEdit), not caller-supplied, so a
     // host allowlist would mostly duplicate the Superblocks API's own trust
@@ -505,6 +612,11 @@ async function attempt(url, timeoutMs, onSocketError) {
             // emitter 'error' rather than reporting it to the caller. Recording it
             // rather than discarding it is what makes a later 1006 explainable.
             socket.on("error", onSocketError);
+            // The dev server flushes queued pushes the moment a peer binds, and
+            // those frames can share a read with the upgrade response. Without the
+            // pause they are emitted before ISocket is listening and lost. The
+            // caller resumes once its handlers are attached.
+            socket.pause();
             resolve(socket);
         });
         const onError = (error) => settle(() => reject(error));
@@ -811,9 +923,12 @@ export class WebSocketSessionPeer {
                 ...(failed.recoveryAction
                     ? { recoveryAction: failed.recoveryAction }
                     : {}),
-                ...(failed.retryable === false ? { reply: failed.reply } : {}),
+                ...(failed.retryable === false || !failed.retryAction
+                    ? { reply: failed.reply }
+                    : {}),
                 ...(failed.retryAction ? { retryAction: failed.retryAction } : {}),
                 ...(failed.retryable === false ? { retryable: false } : {}),
+                startFailed: true,
             };
         }
         if (turn && !turn.finished) {
@@ -837,7 +952,11 @@ export class WebSocketSessionPeer {
                 ? { checkpointWarning: turn.finished.checkpointWarning }
                 : {}),
             generationStatus: turn.finished.generationStatus,
+            ...(turn.mode ? { mode: turn.mode } : {}),
             phase: "finished",
+            ...(turn.finished.answered
+                ? { answered: true, reply: turn.finished.reply }
+                : {}),
             ...(turn.retryAction ? { retryAction: turn.retryAction } : {}),
             ...(turn.finished.retryable === false
                 ? { retryable: false }
@@ -860,7 +979,7 @@ export class WebSocketSessionPeer {
             ? { ...(entry.branchName ? { branch: entry.branchName } : {}) }
             : undefined;
     }
-    libraryBrowserContext(applicationId, requestedBranch) {
+    async libraryBrowserContext(applicationId, requestedBranch) {
         const held = this.held.get(applicationId);
         if (!held || requestedBranch !== held.branchName) {
             return undefined;
@@ -894,8 +1013,100 @@ export class WebSocketSessionPeer {
             held.organizationId = input.organizationId;
         }
         held.sessionToken = input.sessionToken;
-        await this.resolveHeldProfileKey(held);
-        await this.resolveHeldOrchestrator(held);
+        try {
+            await this.synchronizeChatState(held, input.sessionToken);
+            await this.resolveHeldProfileKey(held);
+            // TODO(AR-592): a discovery failure here fails the read even though the
+            // chat state above was just synced.
+            await this.resolveHeldOrchestrator(held);
+        }
+        finally {
+            this.armReadRelease(held);
+        }
+    }
+    /**
+     * Bounds a socket held only to read the editor state. Nothing runs on it,
+     * so it gets a finished turn's grace instead of keeping the sandbox awake
+     * and contesting the editor's binding for the life of the process. A turn
+     * seen on it clears this timer and arms its own.
+     */
+    armReadRelease(held) {
+        const observed = this.observedTurns.get(held.applicationId);
+        if (this.held.get(held.applicationId) !== held ||
+            held.idleTimer ||
+            (observed?.held === held && !observed.finished)) {
+            return;
+        }
+        held.idleTimer = setTimeout(() => {
+            if (this.held.get(held.applicationId) === held) {
+                this.drop(held, { preserveFinishedObserved: true });
+            }
+        }, this.options.releaseAfterReadMs ?? DEFAULT_RELEASE_AFTER_TURN_MS);
+        held.idleTimer.unref?.();
+    }
+    async synchronizeChatState(held, sessionToken, retryDecision = true) {
+        const revision = held.chatStateRevision;
+        const owned = this.turns.get(held.applicationId);
+        // Read before the snapshot call: ordinary browser text on the new socket
+        // does not bump the revision, yet it replaces the watched turn with one
+        // that has no generation, which would hide a matching completion.
+        const observedGenerationId = this.observedTurns.get(held.applicationId)?.generationId;
+        const isCurrent = () => this.held.get(held.applicationId) === held &&
+            isSocketOpen(held.ws) &&
+            !held.pendingTurn &&
+            this.turns.get(held.applicationId) === owned;
+        const snapshot = await editorSocket(held, sessionToken)
+            .aiChatGetMessages({ force: false })
+            .catch((error) => {
+            const dropped = isCurrent() && held.chatStateRevision === revision;
+            console.warn("gateway chat state sync failed", {
+                applicationId: held.applicationId,
+                dropped,
+                message: describeSocketError(error),
+            });
+            if (dropped) {
+                this.drop(held);
+            }
+            throw error;
+        });
+        if (!snapshot?.generationState || !isCurrent()) {
+            return;
+        }
+        if (held.chatStateRevision !== revision) {
+            const observed = this.observedTurns.get(held.applicationId);
+            if (retryDecision &&
+                observed?.finished?.generationStatus === "needs_decision") {
+                await this.synchronizeChatState(held, sessionToken, false);
+            }
+            return;
+        }
+        const reading = readChatSnapshot(snapshot.generationState, {
+            hasActiveInteractiveMessage: Boolean(snapshot.activeInteractiveMessage),
+            observedGenerationId,
+            owned,
+        });
+        if (reading === "unchanged") {
+            return;
+        }
+        this.clearChatSessionState(held.applicationId);
+        if (reading === "settled") {
+            return;
+        }
+        if (snapshot.generationState.state === "awaiting_user_input" &&
+            snapshot.activeInteractiveMessage) {
+            this.observeEditorEvent(held, {
+                kind: "message",
+                message: {
+                    ...snapshot.activeInteractiveMessage,
+                    gatewayObserverSource: "browser",
+                },
+            });
+        }
+        this.observeEditorEvent(held, {
+            ...snapshot.generationState,
+            gatewayObserverSource: "browser",
+            kind: "generation_state",
+        });
     }
     release(applicationId) {
         const entry = this.held.get(applicationId);
@@ -904,14 +1115,18 @@ export class WebSocketSessionPeer {
         }
         const turn = this.turns.get(applicationId);
         if (turn?.held === entry && !turn.finished) {
-            this.cancelTurn(turn, "This turn was cancelled because its live-edit session was released.");
+            this.cancelTurn(turn, {
+                reply: "This turn was cancelled because its live-edit session was released.",
+            });
         }
         this.drop(entry);
     }
     closeAll() {
         for (const turn of this.turns.values()) {
             if (!turn.finished) {
-                this.cancelTurn(turn, "This turn was cancelled because the gateway shut down.");
+                this.cancelTurn(turn, {
+                    reply: "This turn was cancelled because the gateway shut down.",
+                });
             }
         }
         for (const applicationId of [...this.observedTurns.keys()]) {
@@ -921,6 +1136,14 @@ export class WebSocketSessionPeer {
             this.release(applicationId);
         }
     }
+    resetForLogin() {
+        this.closeAll();
+        this.promptStarts.clear();
+        this.connecting.clear();
+        this.turns.clear();
+        this.editorStructureByScope.clear();
+        this.inboundMethods.clear();
+    }
     /**
      * Sends the prompt and waits for Clark's whole turn.
      *
@@ -947,7 +1170,7 @@ export class WebSocketSessionPeer {
                 throw new Error("Superblocks turn wait aborted");
             }
             if (update.status === "finished") {
-                const { activity: _activity, elapsedMs: _elapsedMs, status: _status, ...finished } = update;
+                const { activity: _activity, elapsedMs: _elapsedMs, mode: _mode, status: _status, ...finished } = update;
                 return {
                     ...finished,
                     // See startPrompt, which resolved this: the turn may have run on a
@@ -1081,6 +1304,7 @@ export class WebSocketSessionPeer {
                     }, input.idempotencyKey, input.pendingStartToken))) {
                 throw new PromptNotSentError("A newer start attempt replaced this one before its prompt was sent");
             }
+            const mode = this.turnMode(input);
             const turn = {
                 abort: new AbortController(),
                 activity: [],
@@ -1093,6 +1317,7 @@ export class WebSocketSessionPeer {
                     ? {}
                     : { idempotencyKey: input.idempotencyKey }),
                 listener: () => undefined,
+                ...(mode ? { mode } : {}),
                 ...(input.pendingStartToken === undefined
                     ? {}
                     : { pendingStartToken: input.pendingStartToken }),
@@ -1193,7 +1418,7 @@ export class WebSocketSessionPeer {
     async sendPrompt(args) {
         const { held, input, integrations, provisional, turn } = args;
         const timeoutMs = this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-        const browserContext = this.browserContextFor(held);
+        const browserContext = await this.browserContextFor(held);
         let acknowledgment;
         try {
             // The editor and the smoke client both send the credential twice: once
@@ -1223,7 +1448,11 @@ export class WebSocketSessionPeer {
                     thinkingEnabled: false,
                     unifiedProviderEnabled: true,
                 },
-                mode: (input.mode ?? "PLAN"),
+                ...(input.responseMetadata?.type === "tool_permission_response"
+                    ? {}
+                    : {
+                        mode: input.mode === "BUILD" ? SharedAiMode.BUILD : SharedAiMode.PLAN,
+                    }),
                 prompt: input.prompt,
                 promptContext: {
                     attachments: input.attachments ?? [],
@@ -1303,6 +1532,7 @@ export class WebSocketSessionPeer {
                 : new Error(`Prompt forward failed: ${rejection.message ?? "unknown socket error"}`);
         }
         turn.revision = this.appState.markTurnStarted();
+        turn.generationId = acknowledgment?.generationId;
         args.acceptBufferedEvents(acknowledgment?.generationId);
         input.onProgress?.("Superblocks accepted the prompt");
         // Only now, with the prompt accepted and a live turn about to go in the
@@ -1350,9 +1580,32 @@ export class WebSocketSessionPeer {
             status: "accepted",
         };
     }
+    /**
+     * The mode a new turn runs in. A reply to a tool permission carries no mode
+     * to Superblocks, which carries on in the mode of the turn that asked, so the
+     * reply takes that turn's mode here. When this peer did not run the turn that
+     * asked, the mode is unknown rather than guessed.
+     */
+    turnMode(input) {
+        const response = input.responseMetadata;
+        if (response?.type !== "tool_permission_response") {
+            return input.mode ?? "PLAN";
+        }
+        const asking = this.turns.get(input.applicationId);
+        const decision = asking?.finished?.decision;
+        return decision?.kind === "tool_permission" &&
+            decision.messageId === response.responseToMessageId
+            ? asking?.mode
+            : undefined;
+    }
     latestTurn(applicationId) {
         return (this.observedTurns.get(applicationId) ?? this.turns.get(applicationId));
     }
+    clearChatSessionState(applicationId) {
+        this.clearPendingDecision(applicationId);
+        this.forgetObservedTurn(applicationId);
+        this.supersedeTurn(applicationId);
+    }
     observeEditorEvent(held, event) {
         if (held.dropping || this.held.get(held.applicationId) !== held) {
             return;
@@ -1376,6 +1629,63 @@ export class WebSocketSessionPeer {
             this.clearPendingDecision(held.applicationId);
         }
         const owned = this.turns.get(held.applicationId);
+        const previous = observed ?? owned;
+        if (event.kind === "generation_state" &&
+            event.state === "idle" &&
+            event.chatSessionReset) {
+            const ignored = ignoredChatResetReason(held, event, previous);
+            if (ignored) {
+                console.warn("gateway chat session reset ignored", {
+                    applicationId: held.applicationId,
+                    reason: ignored,
+                    resetHasGenerationId: Boolean(event.generationId),
+                    turnHasGenerationId: Boolean(previous?.generationId),
+                });
+                return;
+            }
+            this.clearChatSessionState(held.applicationId);
+            this.armReadRelease(held);
+            return;
+        }
+        if (previous?.finished &&
+            event.kind === "generation_state" &&
+            event.generationId &&
+            event.generationId === previous.generationId &&
+            previous.finished.generationStatus !== "needs_decision") {
+            return;
+        }
+        if (previous?.finished &&
+            previous.held === held &&
+            !userContent &&
+            !activeGeneration) {
+            if (previous.finished.generationStatus === "needs_decision" &&
+                event.kind === "generation_state" &&
+                (event.state === "cancelled" ||
+                    event.state === "completed" ||
+                    event.state === "idle") &&
+                (!event.generationId ||
+                    !previous.generationId ||
+                    event.generationId === previous.generationId)) {
+                previous.finished.generationStatus =
+                    event.state === "cancelled"
+                        ? "cancelled"
+                        : event.hasSuggestions ||
+                            previous.collector.workSignals().length > 0
+                            ? "completed"
+                            : "no_changes";
+                delete previous.finished.decision;
+                this.clearPendingDecision(held.applicationId);
+                this.wake(previous);
+                if (observed) {
+                    this.armObservedTurnRelease(held.applicationId, observed);
+                }
+                else if (owned) {
+                    this.armPostTurnRelease(held, owned);
+                    this.armKeepalive(held);
+                }
+            }
+            return;
+        }
         if (owned) {
             if (!owned.finished && !userContent && !activeGeneration) {
                 return;
@@ -1399,12 +1709,6 @@ export class WebSocketSessionPeer {
             if (!activeGeneration) {
                 return;
             }
-            if (event.kind === "generation_state" &&
-                event.generationId &&
-                event.generationId === observed.generationId &&
-                observed.finished.generationStatus !== "needs_decision") {
-                return;
-            }
             observed = undefined;
             this.clearPendingDecision(held.applicationId);
         }
@@ -1495,7 +1799,7 @@ export class WebSocketSessionPeer {
             }
         }
         turn.finished = {
-            reply: turn.collector.reply(),
+            ...turn.collector.replyFields(),
             generationStatus,
             viewStatus: turn.collector.viewableStatus(),
             ...decisionFields(decision),
@@ -1504,13 +1808,15 @@ export class WebSocketSessionPeer {
         this.wake(turn);
         this.armObservedTurnRelease(applicationId, turn);
     }
-    settleObservedTurn(turn, generationStatus, reply = turn.collector.reply()) {
+    settleObservedTurn(turn, generationStatus, gatewayReply) {
         if (turn.finished) {
             return;
         }
         tagRetryableLiveEditDeath(turn, { generationStatus });
         turn.finished = {
-            reply,
+            ...(gatewayReply === undefined
+                ? turn.collector.replyFields()
+                : { reply: gatewayReply }),
             generationStatus,
             viewStatus: turn.collector.viewableStatus(),
             ...decisionFields(turn.collector.decision()),
@@ -1538,7 +1844,7 @@ export class WebSocketSessionPeer {
         this.clearTimers(held);
         const delayMs = this.options.releaseAfterTurnMs ?? DEFAULT_RELEASE_AFTER_TURN_MS;
         held.idleTimer = setTimeout(() => {
-            if (this.observedTurns.get(held.applicationId) === turn &&
+            if ((this.observedTurns.get(held.applicationId) ?? turn) === turn &&
                 this.held.get(held.applicationId) === held) {
                 this.drop(held, { preserveFinishedObserved: true });
             }
@@ -1671,6 +1977,7 @@ export class WebSocketSessionPeer {
                 activity,
                 ...(turn.branch === undefined ? {} : { branch: turn.branch }),
                 elapsedMs,
+                ...(turn.mode ? { mode: turn.mode } : {}),
                 status: "finished",
                 ...turn.finished,
                 viewStatus: this.currentViewStatus(input.applicationId, turn.branch, turn.finished.viewStatus),
@@ -1732,7 +2039,7 @@ export class WebSocketSessionPeer {
                         inboundMethods: [...this.inboundMethods].sort(),
                     });
                     turn.finished ??= {
-                        reply: collector.reply(),
+                        ...collector.replyFields(),
                         generationStatus: "detached",
                         viewStatus: collector.viewableStatus(),
                         ...decisionFields(collector.decision()),
@@ -1830,7 +2137,7 @@ export class WebSocketSessionPeer {
                 ...(checkpointOutcome?.status === "saved" && checkpointOutcome.warning
                     ? { checkpointWarning: checkpointOutcome.warning }
                     : {}),
-                reply: collector.reply(),
+                ...collector.replyFields(),
                 generationStatus,
                 ...(turn.recentRuns.length > 0
                     ? { recentRuns: [...turn.recentRuns] }
@@ -1849,7 +2156,7 @@ export class WebSocketSessionPeer {
             // A disconnect / supersede already settled the turn with the reason; the
             // abort it caused says less than what is already recorded.
             turn.finished ??= {
-                reply: collector.reply(),
+                ...collector.replyFields(),
                 generationStatus: "timeout",
                 viewStatus: collector.viewableStatus(),
                 ...decisionFields(collector.decision()),
@@ -2031,13 +2338,38 @@ export class WebSocketSessionPeer {
         fresh.listeners.add(turn.listener);
         previous.listeners.delete(turn.listener);
         fresh.heartbeat.start();
-        const claim = fresh.sessionToken === undefined
-            ? "refused"
+        let claim = fresh.sessionToken === undefined
+            ? { kind: "refused" }
             : await this.proveIdentity({
                 held: fresh,
+                deadline: input.deadline,
                 sessionToken: fresh.sessionToken,
                 turnId: turn.turnId,
             });
+        let refreshes = 0;
+        while (claim.kind === "claimed" &&
+            fresh.browserChatStateRevision !== claim.browserRevision &&
+            !turn.finished &&
+            turn.held === previous &&
+            this.turns.get(fresh.applicationId) === turn &&
+            fresh.sessionToken !== undefined) {
+            if (refreshes === MAX_CLAIM_REFRESHES || Date.now() >= input.deadline) {
+                console.warn("gateway clark reattach snapshot kept changing", {
+                    applicationId: fresh.applicationId,
+                    reason: refreshes === MAX_CLAIM_REFRESHES ? "refresh_cap" : "deadline",
+                    refreshes,
+                    turnId: turn.turnId,
+                });
+                break;
+            }
+            refreshes++;
+            claim = await this.proveIdentity({
+                held: fresh,
+                deadline: input.deadline,
+                sessionToken: fresh.sessionToken,
+                turnId: turn.turnId,
+            });
+        }
         // Opening and claiming take seconds, and the turn can settle inside them:
         // a relayed terminal event, the turn being cancelled, or a newer prompt
         // taking the app. runTurn arms the post-turn timers once, against the
@@ -2046,6 +2378,11 @@ export class WebSocketSessionPeer {
         // this point but the listener, so there is nothing to undo beyond letting
         // the replacement go.
         if (turn.finished || turn.held !== previous) {
+            if (fresh.pendingChatSessionReset &&
+                turn.held === previous &&
+                this.turns.get(fresh.applicationId) === turn) {
+                this.clearChatSessionState(fresh.applicationId);
+            }
             delete fresh.pendingTurn;
             fresh.listeners.delete(turn.listener);
             if (fresh.listeners.size === 0 &&
@@ -2054,7 +2391,7 @@ export class WebSocketSessionPeer {
             }
             return { kind: "stale" };
         }
-        if (claim === "unreachable") {
+        if (claim.kind === "unreachable") {
             delete fresh.pendingTurn;
             fresh.listeners.delete(turn.listener);
             this.drop(fresh);
@@ -2063,7 +2400,7 @@ export class WebSocketSessionPeer {
                 message: "the live-edit session stopped answering on a fresh socket",
             };
         }
-        if (claim === "refused") {
+        if (claim.kind === "refused") {
             delete fresh.pendingTurn;
             fresh.listeners.delete(turn.listener);
             // Go back to the socket the turn was on, but only while it is still
@@ -2084,6 +2421,28 @@ export class WebSocketSessionPeer {
         this.setHeld(fresh);
         fresh.heartbeat.start();
         this.drop(previous);
+        if (fresh.pendingChatSessionReset) {
+            this.observeEditorEvent(fresh, fresh.pendingChatSessionReset);
+            delete fresh.pendingChatSessionReset;
+        }
+        const snapshot = claim.snapshot;
+        if (!turn.finished &&
+            this.turns.get(fresh.applicationId) === turn &&
+            fresh.chatStateRevision === claim.revision &&
+            snapshot?.generationState &&
+            replaysOntoTurn(snapshot.generationState, {
+                hasActiveInteractiveMessage: Boolean(snapshot.activeInteractiveMessage),
+                turn,
+            })) {
+            if (snapshot.generationState.state === "awaiting_user_input" &&
+                snapshot.activeInteractiveMessage) {
+                turn.listener({
+                    kind: "message",
+                    message: snapshot.activeInteractiveMessage,
+                });
+            }
+            turn.listener({ ...snapshot.generationState, kind: "generation_state" });
+        }
         return { kind: "took_over" };
     }
     /**
@@ -2124,12 +2483,17 @@ export class WebSocketSessionPeer {
      * between two sockets on it.
      */
     async proveIdentity(input) {
+        if (Date.now() >= input.deadline) {
+            return { kind: "unreachable" };
+        }
+        const revision = input.held.chatStateRevision;
+        const browserRevision = input.held.browserChatStateRevision;
         try {
-            await editorSocket(input.held, input.sessionToken).aiChatGetMessages({
+            const snapshot = await beforePromptDeadline(editorSocket(input.held, input.sessionToken).aiChatGetMessages({
                 force: false,
                 ...this.turnCorrelator(input.turnId),
-            });
-            return "claimed";
+            }), input.deadline);
+            return { kind: "claimed", snapshot, revision, browserRevision };
         }
         catch (error) {
             const message = describeSocketError(error);
@@ -2140,7 +2504,7 @@ export class WebSocketSessionPeer {
             // A call that went unanswered says the socket opened onto something that
             // is not servicing requests, which is the same fact a lost liveness beat
             // reports and nothing like a session declining to hand a turn over.
-            return isTimeout({ message }) ? "unreachable" : "refused";
+            return { kind: isTimeout({ message }) ? "unreachable" : "refused" };
         }
     }
     async reconnect(previous, deadline) {
@@ -2166,6 +2530,15 @@ export class WebSocketSessionPeer {
         this.held.set(held.applicationId, held);
         this.publishEditorStructure(held);
     }
+    hasStoredToolPermission(held, messageId) {
+        if (held.dropping || this.held.get(held.applicationId) !== held) {
+            return false;
+        }
+        const pending = this.appState.pendingDecision(held.applicationId);
+        return (pending?.branch === held.branchName &&
+            pending?.decision.kind === "tool_permission" &&
+            pending.decision.messageId === messageId);
+    }
     recordEditorStructure(held, hasDefaultStructure) {
         held.editorHasDefaultStructure = hasDefaultStructure;
         this.publishEditorStructure(held);
@@ -2483,6 +2856,44 @@ export class WebSocketSessionPeer {
                 return undefined;
             }
             return (event) => {
+                if (isBrowserObserverEvent(event) &&
+                    event.kind === "generation_state" &&
+                    event.state === "idle" &&
+                    event.chatSessionReset &&
+                    held.pendingTurn &&
+                    this.turns.get(held.applicationId) === held.pendingTurn) {
+                    // Whether or not the reset names the pending turn, a claim
+                    // snapshot read before it is stale and must be read again.
+                    held.browserChatStateRevision++;
+                    held.chatStateRevision++;
+                    if (event.generationId &&
+                        event.generationId === held.pendingTurn.generationId) {
+                        held.pendingChatSessionReset = event;
+                    }
+                    else {
+                        console.warn("gateway chat session reset ignored", {
+                            applicationId: held.applicationId,
+                            reason: "uncorrelated_during_takeover",
+                            resetHasGenerationId: Boolean(event.generationId),
+                            turnHasGenerationId: Boolean(held.pendingTurn.generationId),
+                        });
+                    }
+                    return;
+                }
+                const browserText = isBrowserObserverEvent(event) &&
+                    event.kind === "message" &&
+                    event.message.role !== "user" &&
+                    (event.message.type === undefined ||
+                        event.message.type === "text" ||
+                        event.message.type === "text-delta" ||
+                        event.message.type === "reasoning");
+                if (isBrowserObserverEvent(event) && !browserText) {
+                    held.browserChatStateRevision++;
+                }
+                if (!browserText &&
+                    (event.kind === "message" || event.kind === "generation_state")) {
+                    held.chatStateRevision++;
+                }
                 if (event.kind === "sync_status" && event.status) {
                     held.syncStatus = event.status;
                 }
@@ -2499,6 +2910,10 @@ export class WebSocketSessionPeer {
                     }
                     return;
                 }
+                if (event.kind === "tool_permission_request" &&
+                    !this.hasStoredToolPermission(held, event.messageId)) {
+                    throw new ToolPermissionListenerUnavailableError();
+                }
             };
         }, (method) => {
             this.inboundMethods.add(method);
@@ -2545,32 +2960,6 @@ export class WebSocketSessionPeer {
                 turn.activity.push(line);
                 this.wake(turn);
             },
-            respondToToolPermission: async (payload) => {
-                const current = heldRef.current;
-                if (!current) {
-                    return;
-                }
-                const turn = current.pendingTurn ?? this.turns.get(current.applicationId);
-                if (!turn ||
-                    turn.finished ||
-                    (turn.held !== current && current.pendingTurn !== turn)) {
-                    return;
-                }
-                try {
-                    await editorSocket(current, current.sessionToken).aiRespondToToolPermission({
-                        approved: payload.approved,
-                        ...this.turnCorrelator(turn.turnId),
-                        messageId: payload.messageId,
-                        requestId: payload.requestId ?? payload.messageId,
-                    });
-                }
-                catch (error) {
-                    console.warn("gateway auto-approve tool permission failed", {
-                        applicationId: current.applicationId,
-                        message: error instanceof Error ? error.message : String(error),
-                    });
-                }
-            },
         }), [], {
             onClose: () => {
                 const current = this.held.get(input.applicationId);
@@ -2599,7 +2988,7 @@ export class WebSocketSessionPeer {
                     const applicationEnded = isApplicationClose(close);
                     this.settleObservedTurn(observed, applicationEnded ? "live_edit_terminated" : "detached", applicationEnded
                         ? LIVE_EDIT_TERMINATED_REPLY + describeClose(close)
-                        : observed.collector.reply());
+                        : undefined);
                     return;
                 }
                 // An application code is the live edit stating its own end, so there
@@ -2624,6 +3013,8 @@ export class WebSocketSessionPeer {
         const held = {
             applicationId: input.applicationId,
             branchName: input.branchName,
+            chatStateRevision: 0,
+            browserChatStateRevision: 0,
             client,
             heartbeat,
             idleTimer: undefined,
@@ -2647,6 +3038,9 @@ export class WebSocketSessionPeer {
             ws,
         };
         heldRef.current = held;
+        // Paused by `attempt` so no frame arrives before ISocket is listening and
+        // `heldRef` can route it. Frames resume on a later tick, after this block.
+        ws.resume();
         if (publish) {
             try {
                 this.assertReadOnlyHoldCurrent(input.applicationId, expectedTurn);
@@ -3122,7 +3516,7 @@ export class WebSocketSessionPeer {
             closeCode: input.close.code,
         });
         this.settleTurn(turn, {
-            reply: turn.collector.reply(),
+            ...turn.collector.replyFields(),
             generationStatus: "detached",
             viewStatus: turn.collector.viewableStatus(),
             ...decisionFields(turn.collector.decision()),
@@ -3140,11 +3534,14 @@ export class WebSocketSessionPeer {
         if (!prior) {
             return;
         }
-        this.cancelTurn(prior);
+        this.cancelTurn(prior, {
+            replaced: true,
+            reply: "This turn was replaced by a newer prompt on the same app, so its work was cancelled.",
+        });
     }
-    cancelTurn(turn, reply = "This turn was replaced by a newer prompt on the same app, so its work was cancelled.") {
+    cancelTurn(turn, outcome) {
         turn.finished ??= {
-            reply,
+            ...outcome,
             generationStatus: "cancelled",
             viewStatus: turn.collector.viewableStatus(),
         };
@@ -3294,7 +3691,7 @@ export class WebSocketSessionPeer {
      * the app shell cannot boot without — Clark then runs the turn with its
      * ordinary tools rather than failing it.
      */
-    browserContextFor(held) {
+    async browserContextFor(held) {
         if (!this.options.testingEnabled) {
             return undefined;
         }
@@ -3304,7 +3701,7 @@ export class WebSocketSessionPeer {
      * Library iframe bootstrap from a held session. Used for Gateway's own
      * live-canvas screenshot even when Clark's in-sandbox Playwright is off.
      */
-    buildHeldBrowserContext(held) {
+    async buildHeldBrowserContext(held) {
         if (!held.orchestratorUrl) {
             console.error("gateway live canvas skipped: missing_orchestrator_url", {
                 applicationId: held.applicationId,
@@ -3323,8 +3720,11 @@ export class WebSocketSessionPeer {
             });
             return undefined;
         }
+        const apiKey = this.options.getAccessToken
+            ? await this.options.getAccessToken()
+            : held.apiKey;
         return buildBrowserContext({
-            ...(held.apiKey ? { apiKey: held.apiKey } : {}),
+            ...(apiKey ? { apiKey } : {}),
             applicationId: held.applicationId,
             liveEditUrl: held.liveEdit.url,
             orchestratorUrl: held.orchestratorUrl,
@@ -3503,7 +3903,7 @@ export class WebSocketSessionPeer {
                 profileKey,
             });
             held.orchestratorUrl = orchestratorUrl;
-            held.orchestrator = new HttpOrchestratorClient(orchestratorUrl);
+            held.orchestrator = new HttpOrchestratorClient(orchestratorUrl, undefined, this.options.getAccessToken);
             held.orchestratorAgentType = inventory.agentType;
             delete held.orchestratorStale;
             console.error("gateway resolved orchestrator url", {