@superblocksteam/vite-plugin-file-sync 2.0.161-next.0 → 2.0.162-next.0

package/dist/socket-manager.d.ts

@@ -1,6 +1,6 @@
 import type http from "node:http";
 import type { Tracer } from "@opentelemetry/api";
-import type { EditorClientMethods, LibraryClientMethods } from "@superblocksteam/library-shared/types";
+import type { EditorClientMethods, EditorHasDefaultStructure, GatewayClientMethods, LibraryClientMethods } from "@superblocksteam/library-shared/types";
 import { TracedEventEmitter } from "@superblocksteam/shared";
 import type { ISocketClient } from "@superblocksteam/shared";
 import type { AiService } from "./ai-service/index.js";
@@ -42,7 +42,7 @@ type SocketManagerEvents = {
         PeerConnectionLiveness
     ];
     "connect:gateway": [
-        ISocketClient<EditorClientMethods>,
+        ISocketClient<GatewayClientMethods>,
         string,
         PeerConnectionLiveness
     ];
@@ -65,6 +65,10 @@ declare class SocketManager extends TracedEventEmitter<SocketManagerEvents> {
      * {@link getSurvivingEditorClient} which peerId to prefer among leftovers.
      */
     private readonly editorPeerIdsBySocket;
+    private readonly authenticatedEditorSockets;
+    private readonly authenticatedGatewaySockets;
+    private editorStructureReport;
+    private readonly editorStructureReportByGateway;
     private peerIds;
     /**
      * Editor peers whose presence is registered with the lock service, and the
@@ -111,6 +115,8 @@ declare class SocketManager extends TracedEventEmitter<SocketManagerEvents> {
         superblocksBaseUrl?: string;
         maxPayloadBytes?: number;
     }): void;
+    reportEditorHasDefaultStructure(hasDefaultStructure: EditorHasDefaultStructure): void;
+    private sendEditorStructureReport;
     callEditorClients(fn: (socket: ISocketClient<EditorClientMethods>) => Promise<void>): void;
     /**
      * Both registries, for the signals a headless turn needs as much as a browser
@@ -144,14 +150,16 @@ declare class SocketManager extends TracedEventEmitter<SocketManagerEvents> {
     callLibraryClients(fn: (socket: ISocketClient<LibraryClientMethods>) => Promise<void>): void;
     getAnyLibraryClient(): ISocketClient<LibraryClientMethods> | undefined;
     getEditorClients(): Iterable<ISocketClient<EditorClientMethods>>;
+    private getAuthenticatedEditorPeers;
+    private getAuthenticatedGatewayPeers;
     /**
      * Attached headless gateway peers. Separate from {@link getEditorClients} so
      * a broadcast meant for browser tabs never reaches a gateway, and the
      * gateway's own lifecycle can be observed without editor semantics.
      */
-    getGatewayClients(): Iterable<ISocketClient<EditorClientMethods>>;
+    getGatewayClients(): Iterable<ISocketClient<GatewayClientMethods>>;
     /** The attached gateway peer with this peer id, if it is still connected. */
-    getGatewayClient(peerId: string): ISocketClient<EditorClientMethods> | undefined;
+    getGatewayClient(peerId: string): ISocketClient<GatewayClientMethods> | undefined;
     closeAllClients(): void;
     dispose(): void;
 }

package/dist/socket-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket-manager.d.ts","sourceRoot":"","sources":["../src/socket-manager.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"socket-manager.d.ts","sourceRoot":"","sources":["../src/socket-manager.ts"],"names":[],"mappings":"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"}

package/dist/socket-manager.js

@@ -1,8 +1,10 @@
+import { randomUUID } from "node:crypto";
 import { cp, mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { WebSocketServer } from "ws";
 import { createISocketClient, DEFAULT_NON_GIT_BRANCH, MAX_SOCKET_PAYLOAD_BYTES, SocketErrorException, SUPERBLOCKS_LIVE_GIT_BRANCH, TracedEventEmitter, TracedSocket, } from "@superblocksteam/shared";
+import { uploadCheckpointScreenshot } from "./ai-service/checkpoint-screenshot.js";
 import { uploadContextToBucketeer } from "./ai-service/context-upload.js";
 import { createSocketRecordingMiddleware } from "./ai-service/recording/recorders/socket-recorder.js";
 import { parseJwt } from "./ai-service/util/parse-jwt.js";
@@ -136,6 +138,10 @@ class SocketManager extends TracedEventEmitter {
      * {@link getSurvivingEditorClient} which peerId to prefer among leftovers.
      */
     editorPeerIdsBySocket = new WeakMap();
+    authenticatedEditorSockets = new WeakSet();
+    authenticatedGatewaySockets = new WeakSet();
+    editorStructureReport;
+    editorStructureReportByGateway = new WeakMap();
     peerIds = new Map();
     /**
      * Editor peers whose presence is registered with the lock service, and the
@@ -182,6 +188,7 @@ class SocketManager extends TracedEventEmitter {
         this.socketServer = wss;
         let activeGitService = gitService;
         const headlessLockOwners = [];
+        const headlessLockHandbackQueue = new OperationQueue();
         const headlessLockOperationQueue = new OperationQueue();
         /**
          * Drop every turn this peer owned, and hand the lock back if that was the
@@ -194,28 +201,50 @@ class SocketManager extends TracedEventEmitter {
          * nothing. The AppBranchLock would then stay held for the rest of that
          * socket's life, with no turn behind it.
          *
-         * Queued with the release path so the two cannot both decide they are
-         * last.
+         * Owner decisions and handbacks use separate queues so generation waits
+         * serialize releases without keeping later headless prompts from starting.
          */
-        const dropHeadlessLockOwners = async (peerId) => {
-            await headlessLockOperationQueue.enqueue(async () => {
-                const ownedAny = headlessLockOwners.some((owner) => owner.peerId === peerId);
-                if (!ownedAny) {
-                    return;
+        const dropHeadlessLockOwnersNow = async (peerId) => {
+            const ownedTurns = await headlessLockOperationQueue.enqueue(async () => {
+                const owned = headlessLockOwners.filter((owner) => owner.peerId === peerId);
+                if (headlessLockOwners.some((owner) => !owner.handbackFailed && !owned.includes(owner))) {
+                    for (let index = headlessLockOwners.length - 1; index >= 0; index--) {
+                        const owner = headlessLockOwners[index];
+                        if (owner && owned.includes(owner)) {
+                            headlessLockOwners.splice(index, 1);
+                        }
+                    }
+                    return [];
                 }
+                return owned;
+            });
+            if (ownedTurns.length === 0) {
+                return;
+            }
+            try {
+                await lockService?.relinquishLockForTurn(() => headlessLockOwners.some((owner) => !owner.handbackFailed &&
+                    (!ownedTurns.includes(owner) || owner.peerId !== peerId)));
+            }
+            catch (error) {
+                await headlessLockOperationQueue.enqueue(async () => {
+                    for (const owner of ownedTurns) {
+                        if (headlessLockOwners.includes(owner) && owner.peerId === peerId) {
+                            owner.handbackFailed = true;
+                        }
+                    }
+                });
+                throw error;
+            }
+            await headlessLockOperationQueue.enqueue(async () => {
                 for (let index = headlessLockOwners.length - 1; index >= 0; index--) {
-                    if (headlessLockOwners[index]?.peerId === peerId) {
+                    const owner = headlessLockOwners[index];
+                    if (owner && owner.peerId === peerId && ownedTurns.includes(owner)) {
                         headlessLockOwners.splice(index, 1);
                     }
                 }
-                if (headlessLockOwners.length > 0) {
-                    return;
-                }
-                // Re-read after the handback's generation wait: a replacement gateway
-                // can claim a turn while the old one's write is still finishing.
-                await lockService?.relinquishLockForTurn(() => headlessLockOwners.length > 0);
             });
         };
+        const dropHeadlessLockOwners = (peerId) => headlessLockHandbackQueue.enqueue(() => dropHeadlessLockOwnersNow(peerId));
         const dropHeadlessLockOwnersInBackground = (peerId, occasion) => {
             void dropHeadlessLockOwners(peerId).catch((err) => {
                 getLogger().warn(`[socket-manager] failed to hand the turn lock back after ${occasion}: ${err instanceof Error ? err.message : String(err)}`);
@@ -225,29 +254,52 @@ class SocketManager extends TracedEventEmitter {
             dropHeadlessLockOwnersInBackground(peerId, "a gateway's liveness lapsed");
             aiService?.endHeadlessTurn(peerId);
         });
-        const releaseHeadlessLock = async (peerId, turnId) => {
-            return await headlessLockOperationQueue.enqueue(async () => {
+        const releaseHeadlessLockNow = async (peerId, turnId) => {
+            const ownedTurn = await headlessLockOperationQueue.enqueue(async () => {
                 const ownerIndex = headlessLockOwners.findIndex((owner) => owner.peerId === peerId &&
                     (turnId ? owner.turnId === turnId : owner.turnId === undefined));
                 if (ownerIndex === -1) {
-                    return false;
+                    return undefined;
                 }
-                const [owner] = headlessLockOwners.splice(ownerIndex, 1);
-                if (headlessLockOwners.length > 0) {
-                    return true;
+                const owner = headlessLockOwners[ownerIndex];
+                if (!owner) {
+                    return undefined;
                 }
-                try {
-                    await lockService?.relinquishLockForTurn(() => headlessLockOwners.length > 0);
+                if (headlessLockOwners.some((candidate) => candidate !== owner && !candidate.handbackFailed)) {
+                    headlessLockOwners.splice(ownerIndex, 1);
                     return true;
                 }
-                catch (error) {
-                    if (owner) {
-                        headlessLockOwners.splice(ownerIndex, 0, owner);
+                owner.handbackFailed = false;
+                return owner;
+            });
+            if (!ownedTurn) {
+                return false;
+            }
+            if (ownedTurn === true) {
+                return true;
+            }
+            try {
+                await lockService?.relinquishLockForTurn(() => headlessLockOwners.some((owner) => !owner.handbackFailed &&
+                    (owner !== ownedTurn || owner.peerId !== peerId)));
+            }
+            catch (error) {
+                await headlessLockOperationQueue.enqueue(async () => {
+                    if (headlessLockOwners.includes(ownedTurn)) {
+                        ownedTurn.handbackFailed = true;
                     }
-                    throw error;
+                });
+                throw error;
+            }
+            return await headlessLockOperationQueue.enqueue(async () => {
+                const ownerIndex = headlessLockOwners.findIndex((owner) => owner === ownedTurn && owner.peerId === peerId);
+                if (ownerIndex === -1) {
+                    return false;
                 }
+                headlessLockOwners.splice(ownerIndex, 1);
+                return true;
             });
         };
+        const releaseHeadlessLock = (peerId, turnId) => headlessLockHandbackQueue.enqueue(() => releaseHeadlessLockNow(peerId, turnId));
         // Provide sync context (branchName, lastCommitId) to the AI service
         // for remote context restore fallback from Bucketeer on fresh pods.
         if (aiService && syncService) {
@@ -256,6 +308,8 @@ class SocketManager extends TracedEventEmitter {
                 getLastCommitId: () => syncService.lastCommitId,
             });
         }
+        aiService?.setAuthenticatedEditorPeersProvider?.(() => this.getAuthenticatedEditorPeers());
+        aiService?.setAuthenticatedGatewayPeersProvider?.(() => this.getAuthenticatedGatewayPeers());
         // Sticky guard. Set to true by `gitDisconnect` and deliberately NOT
         // cleared when it finishes: any callers of `getActiveGitService()` that
         // started before disconnect but resolve after it completes must still
@@ -438,6 +492,13 @@ class SocketManager extends TracedEventEmitter {
                 if (!result.success) {
                     throw new SocketErrorException(result.status, result.error);
                 }
+                if (isEditor && this.editorSockets.has(socket)) {
+                    this.authenticatedEditorSockets.add(socket);
+                }
+                if (kind === "gateway" && this.gatewaySockets.has(socket)) {
+                    this.authenticatedGatewaySockets.add(socket);
+                    this.sendEditorStructureReport(socket);
+                }
                 if (isEditor &&
                     userId &&
                     !this.editorPresenceUserIdByPeerId.has(peerId) &&
@@ -535,7 +596,8 @@ class SocketManager extends TracedEventEmitter {
                     // AI + draft handling
                     aiGenerate: [
                         async (request) => {
-                            await aiService?.handleAiGenerate(request);
+                            const inputSource = { kind, peerId };
+                            await aiService?.handleAiGenerate(request, inputSource);
                         },
                     ],
                     aiGenerateWithQueue: [
@@ -547,10 +609,12 @@ class SocketManager extends TracedEventEmitter {
                             // gateway peer that asked for the work, not to whichever
                             // socket connected most recently. The prompt's own
                             // `requestId` is the correlator that same caller presents to
-                            // reacquire this turn after losing its socket.
+                            // reacquire this turn after losing its socket. Legacy
+                            // callers that omit it receive a server-minted identity.
                             const { queueMode, ...aiRequest } = request;
+                            const inputSource = { kind, peerId };
                             if (kind !== "gateway") {
-                                return await aiService.handleAiGenerateWithQueue(aiRequest, queueMode);
+                                return await aiService.handleAiGenerateWithQueue(aiRequest, queueMode, inputSource);
                             }
                             // Write access is taken per turn, not held for the whole
                             // session, so the app is unlocked between prompts and a
@@ -558,10 +622,16 @@ class SocketManager extends TracedEventEmitter {
                             // awaited: a turn that cannot write must fail here carrying
                             // the server's own reason — somebody is editing in the
                             // browser — rather than bind routing and then unwind it.
-                            const requestedTurnId = typeof request.requestId === "string"
+                            const requestedTurnId = typeof request.requestId === "string" &&
+                                request.requestId.length > 0
                                 ? request.requestId
-                                : undefined;
+                                : randomUUID();
+                            const headlessRequest = {
+                                ...aiRequest,
+                                requestId: requestedTurnId,
+                            };
                             const lockOwner = {
+                                handbackFailed: false,
                                 peerId,
                                 turnId: requestedTurnId,
                             };
@@ -572,7 +642,7 @@ class SocketManager extends TracedEventEmitter {
                             });
                             let result;
                             try {
-                                result = await aiService.handleAiGenerateWithQueue(aiRequest, queueMode);
+                                result = await aiService.handleAiGenerateWithQueue(headlessRequest, queueMode, inputSource);
                                 const ownerIndex = headlessLockOwners.indexOf(lockOwner);
                                 for (let index = ownerIndex - 1; index >= 0; index--) {
                                     if (headlessLockOwners[index]?.peerId === peerId) {
@@ -650,9 +720,27 @@ class SocketManager extends TracedEventEmitter {
                                 commitId: result?.commitId,
                                 silently: request.silently,
                             });
-                            const draftStateCleared = await draftStateReport;
+                            const handleCleanupError = (error) => {
+                                if (!result?.commitId) {
+                                    throw error;
+                                }
+                                return false;
+                            };
+                            let draftStateCleared = await draftStateReport.catch(handleCleanupError);
                             if (draftStateCleared !== true) {
-                                throw new Error("Failed to clear server draft state");
+                                draftStateCleared = await syncService
+                                    .reportDraftStateToServer(false)
+                                    .catch(handleCleanupError);
+                            }
+                            if (draftStateCleared !== true) {
+                                if (!result?.commitId) {
+                                    throw new Error("Failed to clear server draft state");
+                                }
+                                getLogger().warn("[aiAcceptDraft] checkpoint saved but draft-state cleanup failed", {
+                                    applicationId: syncService.applicationId,
+                                    branchName: syncService.branchName,
+                                    commitId: result.commitId,
+                                });
                             }
                             if (result?.commitId) {
                                 // Upload context file to bucketeer asynchronously (fire-and-forget)
@@ -697,14 +785,41 @@ class SocketManager extends TracedEventEmitter {
                                         }
                                     })();
                                 }
-                                return {
-                                    commitId: result.commitId,
-                                };
+                                return draftStateCleared === true
+                                    ? { commitId: result.commitId }
+                                    : {
+                                        commitId: result.commitId,
+                                        warning: {
+                                            code: "draft_state_cleanup_failed",
+                                            message: "Checkpoint saved, but the server draft state could not be cleared",
+                                        },
+                                    };
                             }
                             getLogger().info("[aiAcceptDraft] No new checkpoint created for ai:accept (no hash changes from last checkpoint)");
                             return { commitId: "" };
                         },
                     ],
+                    aiUploadCheckpointScreenshot: [
+                        async (request, context) => {
+                            if (!syncService) {
+                                throw new Error("Sync service not available");
+                            }
+                            const jwt = aiService?.getClarkJwt() ||
+                                context.peerAuthorization?.replace("Bearer ", "");
+                            const resolvedBaseUrl = superblocksBaseUrl || aiService?.superblocksBaseUrl;
+                            if (!jwt || !resolvedBaseUrl) {
+                                throw new Error("Screenshot upload credentials are not available");
+                            }
+                            await uploadCheckpointScreenshot({
+                                applicationId: syncService.applicationId,
+                                branchName: syncService.branchName,
+                                commitId: request.commitId,
+                                jwt,
+                                screenshotDataUrl: request.screenshotDataUrl,
+                                superblocksBaseUrl: resolvedBaseUrl,
+                            });
+                        },
+                    ],
                     aiClearDraftState: [
                         async () => {
                             await syncService?.clearDraftsDirectory();
@@ -717,8 +832,8 @@ class SocketManager extends TracedEventEmitter {
                         },
                     ],
                     aiNotifyIntegrationSetupClosed: [
-                        async () => {
-                            await aiService?.handleIntegrationSetupClosed();
+                        async (request) => {
+                            await aiService?.handleIntegrationSetupClosed(request);
                         },
                     ],
                     aiInterpretPrompt: [
@@ -1568,6 +1683,33 @@ class SocketManager extends TracedEventEmitter {
             });
         });
     }
+    reportEditorHasDefaultStructure(hasDefaultStructure) {
+        if (hasDefaultStructure !== "yes" &&
+            hasDefaultStructure !== "no" &&
+            hasDefaultStructure !== "unknown") {
+            throw new Error("Invalid editor structure report");
+        }
+        this.editorStructureReport = { hasDefaultStructure };
+        for (const { peer } of this.getAuthenticatedGatewayPeers()) {
+            this.sendEditorStructureReport(peer);
+        }
+    }
+    sendEditorStructureReport(gateway) {
+        const report = this.editorStructureReport;
+        if (!report ||
+            this.editorStructureReportByGateway.get(gateway) ===
+                report.hasDefaultStructure) {
+            return;
+        }
+        this.editorStructureReportByGateway.set(gateway, report.hasDefaultStructure);
+        gateway.call.aiSetEditorHasDefaultStructure(report).catch((error) => {
+            if (this.editorStructureReportByGateway.get(gateway) ===
+                report.hasDefaultStructure) {
+                this.editorStructureReportByGateway.delete(gateway);
+            }
+            errorHandler(error);
+        });
+    }
     callEditorClients(fn) {
         for (const socket of this.editorSockets.keys()) {
             fn(socket).catch(errorHandler);
@@ -1646,6 +1788,20 @@ class SocketManager extends TracedEventEmitter {
     getEditorClients() {
         return this.editorSockets.keys();
     }
+    *getAuthenticatedEditorPeers() {
+        for (const [peer, peerId] of this.editorSockets) {
+            if (this.authenticatedEditorSockets.has(peer)) {
+                yield { peer, peerId };
+            }
+        }
+    }
+    *getAuthenticatedGatewayPeers() {
+        for (const [peer, peerId] of this.gatewaySockets) {
+            if (this.authenticatedGatewaySockets.has(peer)) {
+                yield { peer, peerId };
+            }
+        }
+    }
     /**
      * Attached headless gateway peers. Separate from {@link getEditorClients} so
      * a broadcast meant for browser tabs never reaches a gateway, and the