sandbox0 0.10.3 → 0.10.5

package/dist/sandbox_managed_files.js

@@ -0,0 +1,96 @@
+import { wrapApiCall } from "./errors.js";
+import { ensureData } from "./response.js";
+import { Sandbox } from "./sandbox.js";
+function validateName(name) {
+    if (!/^[A-Za-z0-9._-]{1,128}$/.test(name) || name === "." || name === ".." || name.startsWith(".s0-write-")) {
+        throw new Error("invalid managed file name or namespace");
+    }
+}
+function validateSequence(value) {
+    if (typeof value !== "string" || !/^(0|[1-9][0-9]{0,19})$/.test(value) || BigInt(value) > 18446744073709551615n) {
+        throw new Error("invalid managed file mutation sequence");
+    }
+}
+function encode(content) {
+    if (!(content instanceof Uint8Array) || content.byteLength > 4 * 1024 * 1024)
+        throw new Error("invalid managed file content size or type");
+    let binary = "";
+    for (let i = 0; i < content.length; i += 8192)
+        binary += String.fromCharCode(...content.subarray(i, i + 8192));
+    return btoa(binary);
+}
+function decode(content) {
+    try {
+        if (typeof content !== "string" || content.length > 4 * Math.ceil((4 * 1024 * 1024) / 3))
+            throw new Error();
+        const binary = atob(content);
+        if (binary.length > 4 * 1024 * 1024 || btoa(binary) !== content)
+            throw new Error();
+        return Uint8Array.from(binary, c => c.charCodeAt(0));
+    }
+    catch {
+        throw new Error("invalid managed file response content");
+    }
+}
+/** Fixed-generation access to node-owned files, independent of guest execution.
+ * No automatic resume, generation discovery, fallback or write retry is performed.
+ * Sequences are shared across namespaces and do not track native guest refreshes.
+ */
+export class ManagedFiles {
+    client;
+    id;
+    generation;
+    namespace;
+    constructor(client, id, options) {
+        this.client = client;
+        this.id = id;
+        if (!Number.isSafeInteger(options.runtimeGeneration) || options.runtimeGeneration <= 0)
+            throw new Error("invalid managed file runtime generation");
+        if (options.namespace !== undefined)
+            validateName(options.namespace);
+        this.generation = options.runtimeGeneration;
+        this.namespace = options.namespace;
+    }
+    state(value) {
+        if (value.runtimeGeneration !== this.generation)
+            throw new Error("managed file response generation changed");
+        validateSequence(value.mutationSequence);
+        return value;
+    }
+    /** Describes projection state; does not attest historical RootFS credential safety. */
+    async inspect() {
+        const response = await wrapApiCall(() => this.client.apispec.sandboxes.inspectSandboxManagedFiles({ id: this.id, runtimeGeneration: this.generation }));
+        return this.state(ensureData(response, "managed file response missing"));
+    }
+    async read(name) {
+        validateName(name);
+        const params = { id: this.id, runtimeGeneration: this.generation, name };
+        const response = await wrapApiCall(() => this.namespace === undefined
+            ? this.client.apispec.sandboxes.readSandboxManagedFile(params)
+            : this.client.apispec.sandboxes.readSandboxNamespacedManagedFile({ ...params, namespace: this.namespace }));
+        const value = this.state(ensureData(response, "managed file response missing"));
+        return { ...value, content: decode(value.content) };
+    }
+    /** On an ambiguous error, inspect/read to reconcile; never blindly fetch a new sequence and repeat. */
+    async write(name, content, expectedMutationSequence) {
+        validateName(name);
+        validateSequence(expectedMutationSequence);
+        const params = { id: this.id, runtimeGeneration: this.generation, name, managedFileWriteRequest: { content: encode(content), expectedMutationSequence } };
+        const response = await wrapApiCall(() => this.namespace === undefined
+            ? this.client.apispec.sandboxes.writeSandboxManagedFile(params)
+            : this.client.apispec.sandboxes.writeSandboxNamespacedManagedFile({ ...params, namespace: this.namespace }));
+        return this.state(ensureData(response, "managed file response missing"));
+    }
+    async delete(name, expectedMutationSequence) {
+        validateName(name);
+        validateSequence(expectedMutationSequence);
+        const params = { id: this.id, runtimeGeneration: this.generation, name, expectedMutationSequence };
+        const response = await wrapApiCall(() => this.namespace === undefined
+            ? this.client.apispec.sandboxes.deleteSandboxManagedFile(params)
+            : this.client.apispec.sandboxes.deleteSandboxNamespacedManagedFile({ ...params, namespace: this.namespace }));
+        return this.state(ensureData(response, "managed file response missing"));
+    }
+}
+Sandbox.prototype.managedFiles = function (options) {
+    return new ManagedFiles(this.client, this.id, options);
+};

package/dist/sandbox_sessions.d.ts

@@ -5,6 +5,10 @@ declare module "./sandbox.js" {
     interface Sandbox {
         listSessions(): Promise<ExecutionSession[]>;
         createSession(spec: ExecutionSessionSpec, options?: SessionCreateOptions): Promise<ExecutionSession>;
+        /** Read-only original creation receipt; never auto-resumes or creates. */
+        findConditionalSession(creationKey: string, runtimeGeneration: number): Promise<ExecutionSession>;
+        findRestoredConditionalSession(creationKey: string, runtimeGeneration: number, creationRuntimeGeneration: number): Promise<ExecutionSession>;
+        connectRestoredConditionalSession(sessionId: string, creationKey: string, runtimeGeneration: number, creationRuntimeGeneration: number, attemptId: string, options?: SessionWebSocketOptions): Promise<ExecutionSessionConnection>;
         getSession(sessionId: string): Promise<ExecutionSession>;
         updateSession(sessionId: string, spec: ExecutionSessionSpec): Promise<ExecutionSession>;
         deleteSession(sessionId: string): Promise<SuccessDeletedResponse>;
@@ -15,6 +19,7 @@ declare module "./sandbox.js" {
         resizeSessionTerminal(sessionId: string, request: ExecutionSessionTerminalResizeRequest): Promise<SuccessResizedResponse>;
         listSessionEvents(sessionId: string, options?: SessionEventOptions): Promise<ExecutionSessionEventPage>;
         watchSessionEvents(sessionId: string, options?: SessionEventStreamOptions): Promise<SessionEventStream>;
+        connectConditionalSession(sessionId: string, creationKey: string, runtimeGeneration: number, attemptId: string, options?: SessionWebSocketOptions): Promise<ExecutionSessionConnection>;
         connectSession(sessionId: string, options?: SessionWebSocketOptions): Promise<ExecutionSessionConnection>;
     }
 }

package/dist/sandbox_sessions.d.ts.map

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

package/dist/sandbox_sessions.js

@@ -2,7 +2,7 @@ import { models } from "./apispec_compat.js";
 import { APIError, wrapApiCall } from "./errors.js";
 import { ensureData, ensureModel } from "./response.js";
 import { Sandbox } from "./sandbox.js";
-import { WebSocketClient } from "./ws_client.js";
+import { WebSocketClient, WebSocketUpgradeError } from "./ws_client.js";
 function getClient(sandbox) {
     return sandbox.client;
 }
@@ -11,6 +11,20 @@ Sandbox.prototype.listSessions = async function () {
     return ensureData(response, "list sessions returned empty response").sessions ?? [];
 };
 Sandbox.prototype.createSession = async function (spec, options) {
+    if (options?.runtimeGeneration !== undefined) {
+        if (!Number.isSafeInteger(options.runtimeGeneration) || options.runtimeGeneration <= 0 ||
+            !options.idempotencyKey?.trim() || options.idempotencyKey.length > 255) {
+            throw new Error("Conditional session creation requires a positive safe runtime generation and idempotency key");
+        }
+        const response = await wrapApiCall(() => getClient(this).apispec.sessions.apiV1SandboxesIdSessionsConditionalPost({
+            id: this.id, idempotencyKey: options.idempotencyKey,
+            conditionalExecutionSessionRequest: { sandboxId: this.id, runtimeGeneration: options.runtimeGeneration, spec },
+        }));
+        const session = ensureData(response, "conditional create session returned empty response");
+        if (session.runtimeGeneration !== options.runtimeGeneration)
+            throw new Error("Conditional session response has a different runtime generation; reconcile before retrying");
+        return session;
+    }
     const response = await wrapApiCall(() => getClient(this).apispec.sessions.apiV1SandboxesIdSessionsPost({
         id: this.id,
         executionSessionSpec: spec,
@@ -18,6 +32,37 @@ Sandbox.prototype.createSession = async function (spec, options) {
     }));
     return ensureData(response, "create session returned empty response");
 };
+Sandbox.prototype.findConditionalSession = async function (creationKey, runtimeGeneration) {
+    if (!Number.isSafeInteger(runtimeGeneration) || runtimeGeneration <= 0 ||
+        !creationKey?.trim() || creationKey.length > 255) {
+        throw new Error("Conditional session lookup requires a positive safe runtime generation and original creation key");
+    }
+    const response = await wrapApiCall(() => getClient(this).apispec.sessions.apiV1SandboxesIdSessionsConditionalLookupGet({
+        id: this.id, runtimeGeneration, idempotencyKey: creationKey,
+    }));
+    const session = ensureData(response, "conditional session lookup returned empty response");
+    if (session.runtimeGeneration !== runtimeGeneration)
+        throw new Error("Conditional session response has a different runtime generation; reconcile before retrying");
+    return session;
+};
+/** Explicit restored original attempt; external lineage and credential admission are caller responsibilities. */
+Sandbox.prototype.findRestoredConditionalSession = async function (creationKey, runtimeGeneration, creationRuntimeGeneration) {
+    if (!Number.isSafeInteger(creationRuntimeGeneration) || creationRuntimeGeneration <= 0 || creationRuntimeGeneration >= runtimeGeneration)
+        throw new Error("Restored lookup requires an earlier positive safe creation generation");
+    if (!Number.isSafeInteger(runtimeGeneration) || runtimeGeneration <= 0 ||
+        !creationKey?.trim() || creationKey.length > 255) {
+        throw new Error("Conditional session lookup requires a positive safe runtime generation and original creation key");
+    }
+    const response = await wrapApiCall(() => getClient(this).apispec.sessions.apiV1SandboxesIdSessionsConditionalLookupGet({
+        id: this.id, runtimeGeneration, creationRuntimeGeneration, idempotencyKey: creationKey,
+    }));
+    const session = ensureData(response, "conditional session lookup returned empty response");
+    if (session.runtimeGeneration !== runtimeGeneration)
+        throw new Error("Conditional session response has a different runtime generation; reconcile before retrying");
+    if (session.phase !== "running" || !session.attempt || session.attempt.runtimeGeneration !== creationRuntimeGeneration || session.attempt.finishedAt !== undefined)
+        throw new Error("Restored lookup requires the running original attempt");
+    return session;
+};
 Sandbox.prototype.getSession = async function (sessionId) {
     const response = await wrapApiCall(() => getClient(this).apispec.sessions.apiV1SandboxesIdSessionsSessionIdGet({
         id: this.id,
@@ -113,6 +158,63 @@ Sandbox.prototype.connectSession = async function (sessionId, options) {
     await socket.waitForOpen();
     return new ExecutionSessionConnection(socket);
 };
+/** Exact conditional attachment; no retry, auto-resume or ordinary fallback. */
+Sandbox.prototype.connectConditionalSession = async function (sessionId, creationKey, runtimeGeneration, attemptId, options) {
+    if (!sessionId || !attemptId || !creationKey.trim() || creationKey.length > 255 ||
+        !Number.isSafeInteger(runtimeGeneration) || runtimeGeneration <= 0 ||
+        (options?.after !== undefined && (!Number.isSafeInteger(options.after) || options.after < 0))) {
+        throw new Error("Conditional attachment requires session, creation key, positive safe generation, attempt and nonnegative safe cursor");
+    }
+    const client = getClient(this);
+    const path = `/api/v1/sandboxes/${encodeURIComponent(this.id)}/sessions/${encodeURIComponent(sessionId)}/conditional/ws`;
+    const wsUrl = new URL(client.websocketUrl(path));
+    wsUrl.searchParams.set("runtime_generation", String(runtimeGeneration));
+    wsUrl.searchParams.set("attempt_id", attemptId);
+    if (options?.after !== undefined)
+        wsUrl.searchParams.set("after", String(options.after));
+    const headers = { ...await client.wsHeaders(), "Idempotency-Key": creationKey };
+    const socket = await WebSocketClient.connect(wsUrl.toString(), { headers, singleAttempt: true });
+    try {
+        await socket.waitForOpen();
+    }
+    catch (error) {
+        if (error instanceof WebSocketUpgradeError)
+            throw new APIError({ statusCode: error.statusCode,
+                code: error.statusCode === 410 ? "event_cursor_expired" : undefined, message: "Conditional session attachment rejected" });
+        throw error;
+    }
+    return new ExecutionSessionConnection(socket);
+};
+/** Explicit restored attachment; never retries or creates. */
+Sandbox.prototype.connectRestoredConditionalSession = async function (sessionId, creationKey, runtimeGeneration, creationRuntimeGeneration, attemptId, options) {
+    if (!Number.isSafeInteger(creationRuntimeGeneration) || creationRuntimeGeneration <= 0 || creationRuntimeGeneration >= runtimeGeneration)
+        throw new Error("Restored attachment requires an earlier positive safe creation generation");
+    if (!sessionId || !attemptId || !creationKey.trim() || creationKey.length > 255 ||
+        !Number.isSafeInteger(runtimeGeneration) || runtimeGeneration <= 0 ||
+        (options?.after !== undefined && (!Number.isSafeInteger(options.after) || options.after < 0))) {
+        throw new Error("Conditional attachment requires session, creation key, positive safe generation, attempt and nonnegative safe cursor");
+    }
+    const client = getClient(this);
+    const path = `/api/v1/sandboxes/${encodeURIComponent(this.id)}/sessions/${encodeURIComponent(sessionId)}/conditional/ws`;
+    const wsUrl = new URL(client.websocketUrl(path));
+    wsUrl.searchParams.set("runtime_generation", String(runtimeGeneration));
+    wsUrl.searchParams.set("creation_runtime_generation", String(creationRuntimeGeneration));
+    wsUrl.searchParams.set("attempt_id", attemptId);
+    if (options?.after !== undefined)
+        wsUrl.searchParams.set("after", String(options.after));
+    const headers = { ...await client.wsHeaders(), "Idempotency-Key": creationKey };
+    const socket = await WebSocketClient.connect(wsUrl.toString(), { headers, singleAttempt: true });
+    try {
+        await socket.waitForOpen();
+    }
+    catch (error) {
+        if (error instanceof WebSocketUpgradeError)
+            throw new APIError({ statusCode: error.statusCode,
+                code: error.statusCode === 410 ? "event_cursor_expired" : undefined, message: "Conditional session attachment rejected" });
+        throw error;
+    }
+    return new ExecutionSessionConnection(socket);
+};
 export class ExecutionSessionEventStream {
     response;
     body;

package/dist/ws_client.d.ts

@@ -11,6 +11,8 @@ type WebSocketLike = EventTargetSocket | EventEmitterSocket;
 type WebSocketClientOptions = {
     headers?: Record<string, string>;
     connectTimeoutMs?: number;
+    /** Use the explicit ws transport: native runtimes may retry authentication. */
+    singleAttempt?: boolean;
     resolveWebSocketConstructor?: (options: WebSocketClientOptions) => Promise<WebSocketConstructor>;
 };
 export declare class WebSocketClient {
@@ -18,6 +20,7 @@ export declare class WebSocketClient {
     private readonly pendingSends;
     private closePending;
     private readonly connectTimeoutMs;
+    private upgradeStatus?;
     static connect(url: string, options?: WebSocketClientOptions): Promise<WebSocketClient>;
     private constructor();
     get readyState(): number;
@@ -30,5 +33,10 @@ export declare class WebSocketClient {
     waitForMessage(timeoutMs?: number): Promise<WebSocketRawData | null>;
     private flushPendingSends;
 }
+/** Internal status-only failure for an explicit, single HTTP upgrade. */
+export declare class WebSocketUpgradeError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number);
+}
 export {};
 //# sourceMappingURL=ws_client.d.ts.map

package/dist/ws_client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws_client.d.ts","sourceRoot":"","sources":["../src/ws_client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,gBAAgB,MAAM,IAAI,CAAC;AAEvC,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,WAAW,GACX,UAAU,GACV,MAAM,GACN,MAAM,EAAE,CAAC;AAEb,KAAK,oBAAoB,GAAG,KAAK,GAAG,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,OAAO,KAAK,aAAa,CAAC;AAQ7F,KAAK,iBAAiB,GAAG,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,kBAAkB,GAAG,qBAAqB,CAAC,GAAG;IACvH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,CAAC;AAEF,KAAK,kBAAkB,GAAG,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,KAAK,CAAC,GAAG;IAC1G,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,CAAC;AAEF,KAAK,aAAa,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAS5D,KAAK,sBAAsB,GAAG;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2BAA2B,CAAC,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAClG,CAAC;AAEF,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAC7C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;WAE7B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,eAAe,CAAC;IAKjG,OAAO;IAaP,IAAI,UAAU,IAAI,MAAM,CAEvB;IAEK,WAAW,CAAC,SAAS,SAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCnE,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI;IAIhE,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAIxC,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI;IAIlD,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAY3B,KAAK,IAAI,IAAI;IAYP,cAAc,CAAC,SAAS,SAAQ,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAiCzE,OAAO,CAAC,iBAAiB;CAQ1B"}
+{"version":3,"file":"ws_client.d.ts","sourceRoot":"","sources":["../src/ws_client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,gBAAgB,MAAM,IAAI,CAAC;AAEvC,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,WAAW,GACX,UAAU,GACV,MAAM,GACN,MAAM,EAAE,CAAC;AAEb,KAAK,oBAAoB,GAAG,KAAK,GAAG,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,OAAO,KAAK,aAAa,CAAC;AAQ7F,KAAK,iBAAiB,GAAG,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,kBAAkB,GAAG,qBAAqB,CAAC,GAAG;IACvH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,CAAC;AAEF,KAAK,kBAAkB,GAAG,IAAI,CAAC,gBAAgB,EAAE,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,KAAK,CAAC,GAAG;IAC1G,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,CAAC;AAEF,KAAK,aAAa,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAS5D,KAAK,sBAAsB,GAAG;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2BAA2B,CAAC,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAClG,CAAC;AAEF,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgB;IAC7C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,aAAa,CAAC,CAAS;WAElB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,eAAe,CAAC;IAKjG,OAAO;IAoBP,IAAI,UAAU,IAAI,MAAM,CAEvB;IAEK,WAAW,CAAC,SAAS,SAAwB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuCnE,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI;IAIhE,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAIxC,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI;IAIlD,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAY3B,KAAK,IAAI,IAAI;IAYP,cAAc,CAAC,SAAS,SAAQ,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAiCzE,OAAO,CAAC,iBAAiB;CAQ1B;AAED,yEAAyE;AACzE,qBAAa,qBAAsB,SAAQ,KAAK;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CACxC"}

package/dist/ws_client.js

@@ -9,6 +9,7 @@ export class WebSocketClient {
     pendingSends = [];
     closePending = false;
     connectTimeoutMs;
+    upgradeStatus;
     static async connect(url, options = {}) {
         const socket = await createWebSocket(url, options);
         return new WebSocketClient(socket, options);
@@ -16,6 +17,13 @@ export class WebSocketClient {
     constructor(socket, options = {}) {
         this.connectTimeoutMs = options.connectTimeoutMs ?? 10000;
         this.socket = socket;
+        if (options.singleAttempt && "on" in socket) {
+            // Keep only the status. Do not retain response headers, bodies or URLs.
+            socket.once("unexpected-response", (_request, response) => {
+                this.upgradeStatus = response.statusCode;
+                socket.close();
+            });
+        }
         addOpenListener(this.socket, () => {
             this.flushPendingSends();
             if (this.closePending) {
@@ -44,7 +52,9 @@ export class WebSocketClient {
             };
             const onError = (err) => {
                 cleanup();
-                reject(err instanceof Error ? err : new Error("websocket error"));
+                reject(this.upgradeStatus === undefined
+                    ? (err instanceof Error ? err : new Error("websocket error"))
+                    : new WebSocketUpgradeError(this.upgradeStatus));
             };
             const onClose = () => {
                 cleanup();
@@ -131,6 +141,14 @@ export class WebSocketClient {
         }
     }
 }
+/** Internal status-only failure for an explicit, single HTTP upgrade. */
+export class WebSocketUpgradeError extends Error {
+    statusCode;
+    constructor(statusCode) {
+        super("WebSocket upgrade rejected");
+        this.statusCode = statusCode;
+    }
+}
 async function createWebSocket(url, options) {
     const resolveConstructor = options.resolveWebSocketConstructor ?? defaultResolveWebSocketConstructor;
     const WebSocketCtor = await resolveConstructor(options);
@@ -143,7 +161,7 @@ async function createWebSocket(url, options) {
     return socket;
 }
 async function defaultResolveWebSocketConstructor(options) {
-    if (typeof globalThis.WebSocket === "function" && (!options.headers || isNodeLikeRuntime())) {
+    if (!options.singleAttempt && typeof globalThis.WebSocket === "function" && (!options.headers || isNodeLikeRuntime())) {
         return globalThis.WebSocket;
     }
     const imported = await importWsModule();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sandbox0",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "description": "Sandbox0 JavaScript/TypeScript SDK",
   "license": "Apache-2.0",
   "author": "Sandbox0 Team",
@@ -29,7 +29,7 @@
     "lint:eve": "npm run build && npm --prefix packages/eve run lint",
     "lint:e2e": "tsc -p tsconfig.e2e.json --noEmit",
     "lint:unit": "tsc -p tsconfig.unit.json --noEmit",
-    "generate:apispec": "rm -rf src/apispec && openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o src/apispec -c openapi-generator-config.yaml",
+    "generate:apispec": "rm -rf src/apispec && openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o src/apispec -c openapi-generator-config.yaml && node scripts/normalize-apispec.mjs",
     "test": "npm run test:unit",
     "test:e2e": "npm run test:e2e:sdk && npm run test:e2e:frameworks",
     "test:e2e:frameworks": "npm run test:e2e:eve",