sandbox0 0.10.4 → 0.10.5

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.4",
+  "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",