@superblocksteam/gateway 2.0.161 → 2.0.162-next.1

package/dist/sabs/websocket-session-peer.d.ts

@@ -1,7 +1,9 @@
+import type { LLMProviderConfig } from "@superblocksteam/library-shared/types";
 import type { RecentToolRun } from "../capabilities/types.js";
 import { type OrchestratorClient } from "../orchestrator/client.js";
 import type { SuperblocksServerClient } from "../server/client.js";
-import type { HoldLiveEditInput, TurnState, ForwardPromptResult, PromptInput, RetryAction, SessionPeer, StartPromptResult, TurnDecision, TurnUpdate } from "./session-peer.js";
+import { AppState } from "./app-state.js";
+import { type ForwardPromptResult, type HoldLiveEditInput, type PromptInput, type RecoveryAction, type RetryAction, type SessionPeer, type StartPromptResult, type TurnDecision, type TurnState, type TurnUpdate } from "./session-peer.js";
 /**
  * Consecutive upgrade rejections from one host before asking where the live
  * edit went. More than one, so an ingress route that briefly answers for a pod
@@ -34,20 +36,37 @@ export declare const MAX_RERESOLVES_PER_OPEN = 3;
  */
 export declare const DEFAULT_RELEASE_AFTER_TURN_MS = 30000;
 export type WebSocketSessionPeerOptions = {
+    /** Shared with the capability layer; created here when omitted. */
+    appState?: AppState;
     /**
      * How long a lost liveness beat must stay lost before the turn on that socket
      * is given up on. See {@link DEFAULT_BEAT_LOST_GRACE_MS}.
      */
     beatLostGraceMs?: number;
+    captureCheckpointScreenshot?: (input: {
+        applicationId: string;
+        commitId: string;
+        sessionToken: string;
+    }) => Promise<string | undefined>;
+    /**
+     * Hard cap on the detached capture-and-upload task. Capture can spend 45s
+     * plus settle, then the upload RPC can spend the held-socket budget. Without
+     * this, a hung Playwright launch never drains pendingCheckpointScreenshots.
+     */
+    checkpointScreenshotTimeoutMs?: number;
     connectAttemptTimeoutMs?: number;
-    coreModel?: string;
+    coreModel?: LLMProviderConfig["coreModel"];
     /**
      * How long a turn that died before Superblocks saw it stays worth reporting.
-     * See {@link FailedStarts}; injectable so its bounds are testable without
-     * waiting them out.
+     * See {@link AppState}; injectable so its bounds are testable without waiting
+     * them out.
      */
     failedStartTtlMs?: number;
-    /** Distinct apps holding a dead start at once. See {@link FailedStarts}. */
+    /** Maximum age of acknowledged work before it is treated as abandoned. */
+    pendingStartTtlMs?: number;
+    /**
+     * Distinct apps holding a dead start at once. See {@link AppState}.
+     */
     maxFailedStarts?: number;
     /** Consecutive genuine misses before the beat is declared lost. */
     heartbeatMaxMisses?: number;
@@ -77,7 +96,7 @@ export type WebSocketSessionPeerOptions = {
      * executing APIs. Defaults to `default`.
      */
     profileKey?: string;
-    provider?: string;
+    provider?: LLMProviderConfig["provider"];
     pushWaitMs?: number;
     readyWaitMs?: number;
     /** Grace period between a turn settling and the gateway socket being dropped. */
@@ -99,7 +118,6 @@ export type WebSocketSessionPeerOptions = {
      */
     testingEnabled?: boolean;
     timeoutMs?: number;
-    turnTimeoutMs?: number;
     /** Origin the sandbox app shell should report as its parent window. */
     uiBaseUrl?: string;
 };
@@ -112,6 +130,7 @@ export declare function buildSessionUrl(input: {
 export declare class WebSocketSessionPeer implements SessionPeer {
     private readonly options;
     private readonly held;
+    private readonly promptStarts;
     /**
      * Every server -> editor method the dev server has called on this peer.
      * Diagnostic only: it answers "did that push ever arrive" without guessing
@@ -129,36 +148,36 @@ export declare class WebSocketSessionPeer implements SessionPeer {
      * prompt for the same app replaces it.
      */
     private readonly turns;
-    /**
-     * Last plan Clark proposed per application, so approve/refine can re-send
-     * planContext without the MCP client echoing the full markdown.
-     */
-    private readonly pendingPlans;
-    /**
-     * Last needs_decision payload (plan or multi_choice) per application, so
-     * approve/refine via edit_app can reuse the pending plan after
-     * check_app_progress drained the finished turn.
-     */
-    private readonly pendingDecisions;
-    /**
-     * Applications that have dispatched at least one BUILD turn. Survives
-     * clearing the pending plan, which happens as soon as an approved build
-     * starts — the point of the latch is the turns that come after it.
-     */
-    private readonly buildModeApplications;
-    /**
-     * Turns that died before Superblocks ever saw them, so no {@link ActiveTurn}
-     * was ever created to hold the outcome. Read by
-     * {@link WebSocketSessionPeer.turnState} and
-     * {@link WebSocketSessionPeer.awaitTurn} after the live map, and cleared when
-     * a prompt for the app is accepted.
-     */
-    private readonly failedStarts;
+    /** Browser-owned turns observed over an authenticated held session. */
+    private readonly observedTurns;
+    private readonly editorStructureByScope;
+    /** Facts about an application that outlive any one turn. */
+    private readonly appState;
     constructor(options?: WebSocketSessionPeerOptions);
+    /** The per-application facts this peer writes, for the capability layer. */
+    state(): AppState;
+    recordPendingStart(input: {
+        applicationId: string;
+        branch?: string;
+        idempotencyKey?: string;
+        organizationId: string;
+        retryAction?: RetryAction;
+        userId: string;
+    }): number;
+    clearPendingStart(input: {
+        applicationId: string;
+        branch?: string;
+        idempotencyKey?: string;
+        organizationId: string;
+        pendingStartToken?: number;
+        userId: string;
+    }): void;
+    private waitForPendingTurn;
     /**
      * Plan waiting on human approve/refine for this application, if any.
      */
-    pendingPlan(applicationId: string): {
+    pendingPlan(applicationId: string, requestedBranch?: string): {
+        branch?: string;
         messageId?: string;
         plan: string;
         title?: string;
@@ -166,7 +185,8 @@ export declare class WebSocketSessionPeer implements SessionPeer {
     /**
      * Full needs_decision payload waiting on a human for this application.
      */
-    pendingDecision(applicationId: string): {
+    pendingDecision(applicationId: string, requestedBranch?: string): {
+        branch?: string;
         decision: TurnDecision;
         recentRuns?: RecentToolRun[];
         reply: string;
@@ -177,42 +197,41 @@ export declare class WebSocketSessionPeer implements SessionPeer {
      */
     recordFailedStart(input: {
         applicationId: string;
+        branch?: string;
+        decision?: TurnDecision;
+        generationStatus?: "detached" | "live_edit_terminated" | "needs_decision";
+        idempotencyKey?: string;
         organizationId: string;
+        pendingStartRequired?: boolean;
+        pendingStartToken?: number;
         reason: string;
+        recoveryAction?: RecoveryAction;
+        revision?: number;
         retryAction?: RetryAction;
+        retryable?: false;
         userId: string;
     }): void;
     /**
      * Where this application's turn stands for this caller, read without draining
      * the activity an {@link WebSocketSessionPeer.awaitTurn} poll is owed.
      *
-     * Order matters, and it is recency. A turn still *running* is live work and
-     * outranks everything - a second prompt failing to open its own session does
-     * not end it. Failing that, this caller's own dead start outranks a turn that
-     * already finished: `turns` keeps finished turns, so without this a follow-up
-     * whose connect failed would be answered by the previous turn's outcome and
-     * its reply, reporting an edit as landed that never ran. And it is read rather
-     * than superseded by deleting from `turns`, because that map is keyed by
-     * application while a dead start belongs to one caller - deleting would erase
-     * a colleague's outcome to answer this caller's question.
-     *
-     * Reading recency out of the order rather than out of a clock holds because
-     * of the two rules either side of this one: accepting a prompt clears every
-     * caller's record for the app, and no record is made while a turn is running.
-     * Together they leave every stored record newer than any finished turn it can
-     * be read beside, so "the record wins" is not a guess about which came first.
+     * A running turn is current. Once it finishes, the newer of that turn and an
+     * unscoped failed start wins; explicit branch reads filter before comparing.
+     * Revisions preserve that ordering even when both events share a clock tick.
      */
     turnState(input: {
         applicationId: string;
+        branch?: string;
         organizationId: string;
         userId: string;
     }): TurnState | undefined;
     clearPendingPlan(applicationId: string): void;
     clearPendingDecision(applicationId: string): void;
-    markBuildMode(applicationId: string): void;
-    buildMode(applicationId: string): boolean;
     isHeld(applicationId: string): boolean;
-    libraryBrowserContext(applicationId: string): import("@superblocksteam/library-shared/types").BrowserContext | undefined;
+    heldContext(applicationId: string): {
+        branch?: string;
+    } | undefined;
+    libraryBrowserContext(applicationId: string, requestedBranch?: string): import("@superblocksteam/library-shared/types").BrowserContext | undefined;
     holdLiveEdit(input: HoldLiveEditInput): Promise<void>;
     release(applicationId: string): void;
     closeAll(): void;
@@ -224,17 +243,27 @@ export declare class WebSocketSessionPeer implements SessionPeer {
      * {@link startPrompt} so there is one turn lifecycle, not two.
      */
     forwardPrompt(input: PromptInput): Promise<ForwardPromptResult>;
+    private claimPromptLane;
     startPrompt(input: PromptInput): Promise<StartPromptResult>;
     /**
      * Sends the prompt on a session already holding a subscribed turn, and hands
      * the turn to {@link runTurn} once the session confirms it took it on.
      */
     private sendPrompt;
+    private latestTurn;
+    private observeEditorEvent;
+    private forgetObservedTurn;
+    private finishObservedTurn;
+    private settleObservedTurn;
+    private armObservedTurnRelease;
+    private armObservedPostTurnRelease;
     awaitTurn(input: {
         applicationId: string;
+        branch?: string;
         organizationId?: string;
         signal?: AbortSignal;
         userId?: string;
+        floorMs?: number;
         waitMs: number;
     }): Promise<TurnUpdate>;
     /**
@@ -245,15 +274,6 @@ export declare class WebSocketSessionPeer implements SessionPeer {
      */
     private runTurn;
     private pushWaitMs;
-    /**
-     * Attaches a turn to the events SABS relays for its live edit, returning the
-     * idempotent detach the turn calls when it ends.
-     *
-     * A turn with no live edit id, or a deployment with no push channel, gets a
-     * detach that does nothing: the socket remains its only source, which is the
-     * behavior from before the channel existed.
-     */
-    private subscribeToPushes;
     /**
      * Checks that the session took this prompt on as a turn belonging to this
      * peer, and gives up on it now if it did not.
@@ -261,8 +281,8 @@ export declare class WebSocketSessionPeer implements SessionPeer {
      * A dev server that predates the gateway role accepts the socket, echoes the
      * role it was offered, and then treats the connection as a library socket: the
      * prompt is acknowledged and Clark's pushes go to the browser binding
-     * instead. The turn would spend its whole budget looking detached, and a
-     * rollout with one stale sandbox in it would look like Clark hanging. Only a
+     * instead. The turn would stay detached, and a rollout with one stale
+     * sandbox in it would look like Clark hanging. Only a
      * server that bound the turn can name it back, so the missing handle is the
      * mismatch, reported where it is still cheap to act on.
      */
@@ -341,6 +361,10 @@ export declare class WebSocketSessionPeer implements SessionPeer {
      */
     private proveIdentity;
     private reconnect;
+    private setHeld;
+    private recordEditorStructure;
+    private publishEditorStructure;
+    private currentViewStatus;
     /** Lines this caller has not been handed yet. */
     private drain;
     private wake;
@@ -348,7 +372,7 @@ export declare class WebSocketSessionPeer implements SessionPeer {
     private note;
     /**
      * Records the outcome of a turn from outside runTurn, and ends the collector
-     * waits so runTurn cannot overwrite it with a later timeout of its own. The
+     * waits so runTurn cannot overwrite it with a later terminal status. The
      * first outcome written wins: it is the one callers have already been shown.
      */
     private settleTurn;
@@ -360,6 +384,7 @@ export declare class WebSocketSessionPeer implements SessionPeer {
     private checkpoint;
     private ensureHeld;
     private connect;
+    private assertReadOnlyHoldCurrent;
     /**
      * The liveness beat for one held socket.
      *
@@ -369,13 +394,16 @@ export declare class WebSocketSessionPeer implements SessionPeer {
      * who to tell.
      */
     private buildHeartbeat;
+    private livenessTurnSnapshot;
+    private sameLivenessTurnSnapshot;
+    private confirmBeatLostSession;
     private armIdle;
     /**
      * Ends a turn whose live edit is gone.
      *
      * The dev server exits on its own when its lock is lost, and it says nothing
-     * on the way out. A turn left waiting on that socket burns its entire budget
-     * — ten minutes — before the caller is told anything.
+     * on the way out. A turn left waiting on that socket would otherwise never
+     * report an outcome to the caller.
      *
      * Reached only once the live edit being gone is established, which a close on
      * its own never does: either it named its own end in the application range,
@@ -414,17 +442,20 @@ export declare class WebSocketSessionPeer implements SessionPeer {
     /**
      * Ends a turn whose socket has stopped answering.
      *
-     * Two gates, because they answer different questions. `SocketHeartbeat`
+     * Three gates answer different questions. `SocketHeartbeat`
      * declares the beat lost after consecutive genuine misses, having already
      * excused a run of unanswered beats and every silence that inbound traffic
      * explained - the right threshold for a diagnostic, and too eager for this: a
      * sandbox that misses two beats and answers the next was recovering, and its
      * turn has to survive that. So the loss also has to outlast
      * {@link DEFAULT_BEAT_LOST_GRACE_MS}, and any beat that succeeds clears it.
+     * Finally, the exact live edit must either be terminal in the control plane,
+     * or its direct HTTP health check must fail again after another grace
+     * window. One timeout, 5xx, or inconclusive control-plane result is still
+     * recoverable.
      *
      * What is left is a request channel that has been silent for minutes on a
-     * socket that never closed, with a turn waiting on it - which without this
-     * waits out the whole turn budget.
+     * socket that never closed, with a turn waiting on it indefinitely.
      *
      * This is the only trigger that reaches a half-open socket. An unsolicited
      * close is the ordinary one and never arrives for a connection that stays up
@@ -477,13 +508,17 @@ export declare class WebSocketSessionPeer implements SessionPeer {
      * session.
      */
     private supersedeTurn;
+    private cancelTurn;
+    private discardUnstartedTurn;
     private armPostTurnRelease;
+    private releasePostTurnIfReady;
     private armKeepalive;
     /**
      * Clears the turn timers only. The beat is stopped separately on purpose: it
      * belongs to the socket and outlives these, which the post-turn grace period
      * resets.
      */
+    private clearIdleTimer;
     private clearTimers;
     private drop;
     private editorContextFor;