@superblocksteam/gateway 2.0.0-SNAPSHOT.2161f9a02a4eb5d8

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

@@ -0,0 +1,533 @@
+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 { 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
+ * that is not up yet is waited out rather than read as a move.
+ *
+ * Exported so a test can say "kept trying past the point where it asked"
+ * without restating the number.
+ */
+export declare const HOST_REJECTIONS_BEFORE_RERESOLVE = 2;
+/**
+ * How many times one connect may ask where the session went.
+ *
+ * Bounded because each ask is a Superblocks API round trip, and spaced by a
+ * fresh rejection streak so the asks land across the connect window rather
+ * than all at the start of it - SABS needs time to notice the pod is gone
+ * before it can answer with anywhere different.
+ */
+export declare const MAX_RERESOLVES_PER_OPEN = 3;
+/**
+ * Grace period between a turn settling and the gateway socket being dropped.
+ *
+ * Long enough for the checkpoint and any trailing pushes to land, short enough
+ * that the sandbox is not held open by a peer with nothing left to do.
+ *
+ * Must outlast {@link DEFAULT_SETTLE_MS}. The teardown this release leads to is
+ * read as a dead live edit by any turn whose `completed` had not settled yet,
+ * so releasing inside the settle window would report healthy builds as
+ * failures. `releases the socket only after a completed has had its settle
+ * window` holds this.
+ */
+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;
+    connectAttemptTimeoutMs?: number;
+    coreModel?: LLMProviderConfig["coreModel"];
+    /**
+     * How long a turn that died before Superblocks saw it stays worth reporting.
+     * See {@link AppState}; injectable so its bounds are testable without waiting
+     * them out.
+     */
+    failedStartTtlMs?: number;
+    /** 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;
+    /**
+     * Consecutive unanswered beats to tolerate before neither proof of life nor
+     * grace may excuse another.
+     */
+    heartbeatMaxUnanswered?: number;
+    /** How often the held socket proves the gateway is still alive. */
+    heartbeatMs?: number;
+    /** How long a single liveness beat waits before it counts as missed. */
+    heartbeatTimeoutMs?: number;
+    idleMs?: number;
+    keepaliveMs?: number;
+    /**
+     * Optional test override for the orchestrator HTTP client. Production
+     * discovers the agent URL from Server `/users/me` agents per session.
+     */
+    orchestrator?: OrchestratorClient;
+    /**
+     * Optional test override for the agent base URL handed to the sandbox
+     * browser as `agentUrls`. Production discovers this from Server agents.
+     */
+    orchestratorUrl?: string;
+    /**
+     * Integration profile key used when asking the orchestrator for metadata or
+     * executing APIs. Defaults to `default`.
+     */
+    profileKey?: string;
+    provider?: LLMProviderConfig["provider"];
+    pushWaitMs?: number;
+    readyWaitMs?: number;
+    /** Grace period between a turn settling and the gateway socket being dropped. */
+    releaseAfterTurnMs?: number;
+    reattachWaitMs?: number;
+    /** How many times one turn goes back for a live edit that keeps dropping it. */
+    reconnectAttempts?: number;
+    /** How long a turn keeps trying to get back onto its live edit. */
+    reconnectGraceMs?: number;
+    /**
+     * Superblocks API client used to list integrations for Clark mid-build.
+     */
+    server?: SuperblocksServerClient;
+    settleMs?: number;
+    /**
+     * Opt-in: lets Clark run browser tests during a headless turn. Requires
+     * `orchestratorUrl` and `uiBaseUrl`. Off by default so Gateway turns do
+     * not launch Chromium inside the live-edit pod.
+     */
+    testingEnabled?: boolean;
+    timeoutMs?: number;
+    turnTimeoutMs?: number;
+    /** Origin the sandbox app shell should report as its parent window. */
+    uiBaseUrl?: string;
+};
+export declare function buildSessionUrl(input: {
+    applicationId: string;
+    liveEditUrl: string;
+    peerId: string;
+    userId?: string;
+}): URL;
+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
+     * from what the collector chose to keep.
+     */
+    private readonly inboundMethods;
+    /**
+     * In-flight opens, so overlapping prompts for one app share a socket instead
+     * of each opening their own and orphaning all but the last.
+     */
+    private readonly connecting;
+    /**
+     * Turns keyed by application. An entry outlives the call that started it and
+     * is kept after finishing so a late poll still learns the outcome; the next
+     * prompt for the same app replaces it.
+     */
+    private readonly turns;
+    /** 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, requestedBranch?: string): {
+        branch?: string;
+        messageId?: string;
+        plan: string;
+        title?: string;
+    } | undefined;
+    /**
+     * Full needs_decision payload waiting on a human for this application.
+     */
+    pendingDecision(applicationId: string, requestedBranch?: string): {
+        branch?: string;
+        decision: TurnDecision;
+        recentRuns?: RecentToolRun[];
+        reply: string;
+    } | undefined;
+    /**
+     * Remember a turn that never reached Superblocks. See
+     * {@link SessionPeer.recordFailedStart}.
+     */
+    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.
+     *
+     * 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;
+    isHeld(applicationId: string): boolean;
+    libraryBrowserContext(applicationId: string, requestedBranch?: string): import("@superblocksteam/library-shared/types").BrowserContext | undefined;
+    holdLiveEdit(input: HoldLiveEditInput): Promise<void>;
+    release(applicationId: string): void;
+    closeAll(): void;
+    /**
+     * Sends the prompt and waits for Clark's whole turn.
+     *
+     * Kept for callers with nowhere to poll from — the HTTP capability routes
+     * answer a single request — and implemented on the same engine as
+     * {@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>;
+    /**
+     * Follows the turn to its end on the held session: terminal state, then the
+     * checkpoint that commits Clark's draft. Never throws — a caller polling for
+     * news has to be told what happened, and the only place left to report a
+     * failure is the turn record itself.
+     */
+    private runTurn;
+    private pushWaitMs;
+    /**
+     * 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.
+     *
+     * 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
+     * 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.
+     */
+    private assertHeadlessTurnBound;
+    /**
+     * The field the session reads to decide which turn a call belongs to. Sent on
+     * the calls that make up a turn's lifetime, so a turn keeps reporting into
+     * this caller across a reattach and no other session can be handed it.
+     */
+    private turnCorrelator;
+    /**
+     * Moves a turn onto a fresh socket while the one it is on is still open,
+     * because Clark has stopped pushing to it. A turn that was running unseen
+     * becomes visible again from where it got to.
+     *
+     * The socket it came in on is still the better of the two whenever the
+     * replacement fails to take the turn over: the sandbox is demonstrably alive,
+     * and it is still pushing this turn somewhere. A caller mid-turn has nothing
+     * to gain from an exception here, so there is no failure to report but the
+     * log line.
+     */
+    private reattach;
+    /**
+     * Whether this turn gets another go at its live edit, booking it if so.
+     *
+     * The allowance is for a live edit that cannot hold a socket, and a turn that
+     * has heard from Clark since its last reconnect is not that: it is getting
+     * somewhere, so its allowance starts over. Without that, a long build behind
+     * a proxy that reaps every few minutes runs out of goes and is failed for the
+     * very reason this path exists to survive.
+     */
+    private takeReconnectAllowance;
+    /**
+     * Opens a replacement connection and asks the live edit to hand `turn` over
+     * to it.
+     *
+     * Everything that belongs to the session rather than to the socket is carried
+     * across first: the credential the claim itself is made with is one of those
+     * things, and so is the orchestrator a mid-turn tool call needs. The turn's
+     * listener goes on the replacement before the claim, so a push that arrives
+     * while it is in flight is not dropped.
+     *
+     * The turn is claimed before the old socket is let go. The session releases a
+     * turn when the connection holding it closes, so closing first leaves the
+     * claim nothing to take over; claiming first makes the old socket's close a
+     * no-op scoped to a peer that is no longer the owner.
+     *
+     * Nothing has moved when this fails: the listener is back where it was and
+     * the replacement is closed, which leaves the caller free to decide what a
+     * socket it could not replace means.
+     */
+    private takeOverTurn;
+    private attemptTakeOver;
+    /**
+     * Carries onto a replacement socket everything that belongs to the session
+     * rather than to the connection: who the turn runs as, what it is allowed to
+     * do, and which orchestrator its tool calls go to. A replacement missing any
+     * of it is connected but cannot act for the caller.
+     */
+    private carryOver;
+    /**
+     * Makes one authenticated read on a freshly opened socket.
+     *
+     * The dev server trusts a peer's identity per connection and does not carry
+     * it over from the peer this one replaced, so it withholds the pushes it
+     * scopes to a caller — Clark's step-by-step task status — until the new
+     * connection has proven who it is. Reading the chat is the cheapest way to
+     * prove it, and it costs a turn nothing when the read fails.
+     *
+     * Naming `turnId` is what makes this call a reattach rather than just an
+     * authenticated read: the session only moves a turn onto a connection that
+     * can say which turn it is taking over.
+     *
+     * Answers whether it worked, because a caller mid-reattach has to decide
+     * between two sockets on it.
+     */
+    private proveIdentity;
+    private reconnect;
+    private setHeld;
+    private recordEditorStructure;
+    private publishEditorStructure;
+    private currentViewStatus;
+    /** Lines this caller has not been handed yet. */
+    private drain;
+    private wake;
+    /** Adds a line to what the next poll on this turn is handed. */
+    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
+     * first outcome written wins: it is the one callers have already been shown.
+     */
+    private settleTurn;
+    /**
+     * Mirrors the browser editor's auto-accept: wait for the dev server to flush
+     * Clark's files, then commit the draft. Failing to checkpoint costs the caller
+     * a committed app, not the generation itself, so this never throws.
+     */
+    private checkpoint;
+    private ensureHeld;
+    private connect;
+    private assertReadOnlyHoldCurrent;
+    /**
+     * The liveness beat for one held socket.
+     *
+     * Everything about pacing, deadlines and when to believe a silence lives in
+     * {@link SocketHeartbeat}; what belongs here is only what is specific to this
+     * peer - which call to make, what counts as unanswered on this client, and
+     * who to tell.
+     */
+    private buildHeartbeat;
+    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.
+     *
+     * 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,
+     * or {@link recoverTurn} could not get back to it for the whole reconnect
+     * grace. `live_edit_terminated` is a claim about the sandbox, so it is worth
+     * only as much as the evidence behind it. The close code and heartbeat
+     * account go in the reply, since they are the only account of the cause that
+     * reaches the caller.
+     */
+    private abandonTurnOnDisconnect;
+    /**
+     * Ends a turn SABS has just said has no live edit left to run on.
+     *
+     * A socket close is the other trigger for this same outcome, and it is the
+     * slower one: the dev server exits silently when it loses its lock, so the
+     * close can be minutes late or never arrive at all. This event is the control
+     * plane stating the session is gone, which is the same fact without waiting
+     * for a connection to notice it.
+     *
+     * Only for a turn that has not settled itself, though. Every healthy build
+     * ends with its session torn down too, and reading that as a dead live edit
+     * would report each finished app as a failure. A collector that already
+     * settled on a terminal state keeps it; the teardown is the outcome only for
+     * a turn still waiting for one. The disconnect path needs no such guard - an
+     * unsolicited close mid-turn is abnormal in its own right, where a teardown
+     * is what the end of every turn looks like.
+     *
+     * Settled, not merely reached: a terminal state is provisional until the
+     * quiet window closes, because a build that resumes after a false
+     * completed/idle clears it. A teardown inside that window therefore still
+     * ends the turn - which is the honest answer, since the checkpoint that
+     * would follow runs over the socket to the dev server that just died and
+     * could not have landed either way.
+     */
+    private abandonTurnOnSessionTerminated;
+    /**
+     * Ends a turn whose socket has stopped answering.
+     *
+     * 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, an independent HTTP request must fail to confirm that this same
+     * application's dev server is healthy.
+     *
+     * 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.
+     *
+     * 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
+     * with nothing behind it, and the SABS `session: terminated` event cannot
+     * reach a gateway with no inbound route - which is every gateway run on a
+     * laptop, where a loopback public URL leaves SABS no way to post at all.
+     *
+     * The socket is deliberately left in place. Whether a connection proven
+     * wedged should also be torn down rather than handed to the next prompt is a
+     * separate question from whether this turn should keep waiting on it.
+     */
+    private abandonTurnOnBeatLost;
+    /**
+     * Records a dead live edit as the turn's outcome and ends every wait on it.
+     * `evidence` is appended to the reply because it is the only account of the
+     * cause that reaches the caller.
+     */
+    private settleAsLiveEditTerminated;
+    /**
+     * Decides what a close the gateway did not ask for actually means, by going
+     * back for the live edit rather than inferring from the close.
+     *
+     * The reattach machinery exists for exactly this: a turn whose socket went
+     * away is one the gateway can move onto a replacement. Abandoning here is
+     * what used to make that unreachable, and it charged a recoverable blip the
+     * whole turn - the caller is told to send the prompt again, and the work
+     * already done in it is discarded.
+     *
+     * Each of the three outcomes is a different thing to tell the caller:
+     *
+     * - taken over: nothing to tell. The turn carries on where it got to.
+     * - unreachable for the whole grace: the termination the close only hinted
+     *   at, now with the evidence to say so.
+     * - reached but refused the turn: the sandbox is alive and building where
+     *   this gateway cannot watch it, which is `detached`. Calling that a death
+     *   would send the caller to retry a build that is still running.
+     *
+     * A reconnect that fails while SABS is still relaying the turn settles
+     * nothing: the socket is one of two ways this turn reports, and the events
+     * still arriving are the better account of whether the build is alive.
+     *
+     * Never throws: nothing awaits this, and every outcome it can reach belongs
+     * on the turn rather than on the socket handler that started it.
+     */
+    private recoverTurn;
+    /**
+     * Ends a prior turn for `applicationId` before a newer prompt claims the map
+     * slot. Callers polling the old turn see `cancelled`; its runTurn exits via
+     * AbortSignal and must not keep listening or arming release on the held
+     * session.
+     */
+    private supersedeTurn;
+    private cancelTurn;
+    private discardUnstartedTurn;
+    private armPostTurnRelease;
+    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;
+    /**
+     * Context the sandbox needs before it will let Clark drive a browser.
+     *
+     * Absent when headless testing is off or the session is missing something
+     * the app shell cannot boot without — Clark then runs the turn with its
+     * ordinary tools rather than failing it.
+     */
+    private browserContextFor;
+    /**
+     * Library iframe bootstrap from a held session. Used for Gateway's own
+     * live-canvas screenshot even when Clark's in-sandbox Playwright is off.
+     */
+    private buildHeldBrowserContext;
+    /**
+     * Resolves a real org profile key once per held session. Sending the legacy
+     * placeholder `default` makes the orchestrator fail every integration query
+     * with "Invalid profile specified" / HTTP 500.
+     */
+    private resolveHeldProfileKey;
+    /**
+     * Discovers the orchestrator / agent base URL the way the browser does:
+     * Server `/users/me` agents filtered by org agentType, Active status, and
+     * profile tags. Operators never set this URL.
+     */
+    private resolveHeldOrchestrator;
+}