@sealant/sdk-next 0.40.0-next.756 → 0.40.0-next.758

package/dist/errors.d.ts

@@ -1,3 +1,4 @@
+import type { ForwardRefusalReason } from "@sealant/api-contracts";
 /**
  * Public SDK errors. The Effect core fails on a typed `Schema.TaggedError` channel; the facade maps
  * every tagged failure onto one of these PLAIN `Error` subclasses (a single `_tag` switch) so the
@@ -23,7 +24,7 @@ export declare class SealantRuntimeError extends SealantError {
 }
 /** A control-plane API request failed (HTTP-level or typed API error). */
 export declare class SealantApiError extends SealantError {
-    readonly name = "SealantApiError";
+    readonly name: string;
     /** HTTP status, when the failure came from a response. */
     readonly status?: number;
     /**
@@ -48,6 +49,34 @@ export declare class SealantApiError extends SealantError {
         readonly cause?: unknown;
     });
 }
+/**
+ * Why a workspace forward did not open. Core names every refusal it sends. The SDK adds
+ * `unrecognized-refusal` (Core sent a reason newer than this SDK; it is kept in `wireReason`),
+ * `protocol-unsupported` (the control plane predates typed refusals, or answered with something
+ * unreadable) and `transport-unavailable` (no answer could be read at all).
+ */
+export type ForwardDialReason = ForwardRefusalReason | "unrecognized-refusal" | "protocol-unsupported" | "transport-unavailable";
+export type ForwardDialFailure = {
+    readonly reason: ForwardRefusalReason;
+    readonly status: number;
+    readonly message: string;
+} | {
+    readonly reason: "unrecognized-refusal";
+    readonly wireReason: string;
+    readonly status: number;
+    readonly message: string;
+} | {
+    readonly reason: "protocol-unsupported" | "transport-unavailable";
+    readonly message: string;
+};
+/** A workspace forward was refused before it opened. Branch on `reason`. */
+export declare class ForwardDialError extends SealantApiError {
+    readonly name: string;
+    readonly reason: ForwardDialReason;
+    /** The reason Core sent, when this SDK does not know it (`unrecognized-refusal`). */
+    readonly wireReason?: string;
+    constructor(failure: ForwardDialFailure);
+}
 /** The requested operation is part of the public surface but not yet implemented in this slice. */
 export declare class SealantNotImplementedError extends SealantError {
     readonly name = "SealantNotImplementedError";

package/dist/errors.js

@@ -60,6 +60,24 @@ export class SealantApiError extends SealantError {
         }
     }
 }
+/** A workspace forward was refused before it opened. Branch on `reason`. */
+export class ForwardDialError extends SealantApiError {
+    name = "ForwardDialError";
+    reason;
+    /** The reason Core sent, when this SDK does not know it (`unrecognized-refusal`). */
+    wireReason;
+    constructor(failure) {
+        super(failure.message, {
+            code: "ForwardDialError",
+            reason: failure.reason,
+            ...("status" in failure ? { status: failure.status } : {}),
+        });
+        this.reason = failure.reason;
+        if ("wireReason" in failure) {
+            this.wireReason = failure.wireReason;
+        }
+    }
+}
 /** The requested operation is part of the public surface but not yet implemented in this slice. */
 export class SealantNotImplementedError extends SealantError {
     name = "SealantNotImplementedError";

package/dist/facade/forward.d.ts

@@ -0,0 +1,18 @@
+import { type ForwardBinding } from "@sealant/api-contracts";
+import type { WorkspaceForward, WorkspaceForwardOptions } from "../types.js";
+export interface ForwardEndpoint {
+    readonly baseUrl: string;
+    readonly apiKey: string | undefined;
+    readonly ownerUserId: string;
+}
+export declare const openForward: (endpoint: ForwardEndpoint, workspaceId: string, port: number, options?: WorkspaceForwardOptions | undefined) => Promise<WorkspaceForward>;
+export interface ForwardV2Options {
+    readonly host?: "127.0.0.1" | "localhost" | "docker";
+    readonly signal?: AbortSignal;
+    readonly deadlineMs?: number;
+}
+export interface OpenedForwardV2 {
+    readonly binding: ForwardBinding;
+    readonly forward: WorkspaceForward;
+}
+export declare const openForwardV2: (endpoint: ForwardEndpoint, workspaceId: string, port: number, options?: ForwardV2Options | undefined) => Promise<OpenedForwardV2>;

package/dist/facade/forward.js

@@ -0,0 +1,207 @@
+import { FORWARD_V2_MAX_FRAME_BYTES, FORWARD_V2_SUBPROTOCOL, forwardOpenFrameSchema, forwardRefusalReasonSchema, } from "@sealant/api-contracts";
+import { Option, Schema } from "effect";
+import { ForwardDialError } from "../errors.js";
+const forwardUrl = (endpoint, path, query) => {
+    const url = new URL(path, endpoint.baseUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    for (const [name, value] of Object.entries(query)) {
+        if (value !== undefined)
+            url.searchParams.set(name, value);
+    }
+    // The owner assertion always rides the URL (a service principal needs it alongside its
+    // key, and WebSocket cannot carry headers — same contract as the session attach).
+    url.searchParams.set("ownerUserId", endpoint.ownerUserId);
+    if (endpoint.apiKey !== undefined) {
+        url.searchParams.set("token", endpoint.apiKey);
+    }
+    return url;
+};
+const bridgeForward = (ws, maxFrameBytes = Number.POSITIVE_INFINITY) => {
+    const pending = [];
+    let wake;
+    let finished = false;
+    const closedResolver = Promise.withResolvers();
+    const finish = (reason) => {
+        if (finished) {
+            return;
+        }
+        finished = true;
+        closedResolver.resolve(reason);
+        wake?.();
+    };
+    ws.addEventListener("close", () => finish("closed"));
+    const receive = (event) => {
+        if (typeof event.data === "string") {
+            try {
+                const frame = JSON.parse(event.data);
+                if (frame.t === "end") {
+                    finish("end");
+                }
+            }
+            catch { }
+            return;
+        }
+        pending.push(new Uint8Array(event.data));
+        wake?.();
+    };
+    const output = {
+        [Symbol.asyncIterator]: () => ({
+            next: async () => {
+                for (;;) {
+                    const chunk = pending.shift();
+                    if (chunk !== undefined) {
+                        return { done: false, value: chunk };
+                    }
+                    if (finished) {
+                        return { done: true, value: undefined };
+                    }
+                    await new Promise((r) => {
+                        wake = r;
+                    });
+                    wake = undefined;
+                }
+            },
+        }),
+    };
+    const forward = {
+        send: (input) => {
+            let offset = 0;
+            do {
+                // Copy into a plain ArrayBuffer-backed view (WebSocket.send rejects SharedArrayBuffer views).
+                ws.send(new Uint8Array(input.subarray(offset, offset + maxFrameBytes)).buffer);
+                offset += maxFrameBytes;
+            } while (offset < input.byteLength);
+        },
+        eof: () => {
+            ws.send(JSON.stringify({ t: "eof" }));
+        },
+        output,
+        closed: closedResolver.promise,
+        close: () => {
+            finish("closed");
+            ws.close();
+        },
+    };
+    return { forward, receive };
+};
+export const openForward = (endpoint, workspaceId, port, options) => {
+    const url = forwardUrl(endpoint, `/v1/workspaces/${workspaceId}/forward`, {
+        port: String(port),
+        host: options?.host,
+        protocol: options?.protocol === "udp" ? "udp" : undefined,
+    });
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(url);
+        ws.binaryType = "arraybuffer";
+        const { forward, receive } = bridgeForward(ws);
+        ws.addEventListener("message", receive);
+        ws.addEventListener("open", () => resolve(forward), { once: true });
+        ws.addEventListener("error", () => reject(new Error(`workspace forward failed: could not connect to ${url.host} (is anything listening on 127.0.0.1:${port} in the workspace?)`)), { once: true });
+    });
+};
+const FORWARD_V2_OPEN_DEADLINE_MS = 30_000;
+const decodeOpenFrame = Schema.decodeUnknownOption(Schema.fromJsonString(forwardOpenFrameSchema));
+const isKnownRefusal = Schema.is(forwardRefusalReasonSchema);
+const refusalError = (frame) => new ForwardDialError(isKnownRefusal(frame.reason)
+    ? { reason: frame.reason, status: frame.status, message: frame.message }
+    : {
+        reason: "unrecognized-refusal",
+        wireReason: frame.reason,
+        status: frame.status,
+        message: frame.message,
+    });
+/** A gated Core before v2 answers the route 401, an open one 404. Core with v2 answers 426. */
+const answeredLikeCoreBeforeV2 = (status) => status === 401 || status === 404;
+const failedHandshakeError = async (url, origin, signal) => {
+    const probe = new URL(url.pathname, url);
+    probe.protocol = url.protocol === "wss:" ? "https:" : "http:";
+    const unavailable = (detail) => new ForwardDialError({
+        reason: "transport-unavailable",
+        message: `The forward could not open a WebSocket to ${origin}; ${detail}.`,
+    });
+    try {
+        const response = await fetch(probe, { signal });
+        await response.body?.cancel();
+        if (answeredLikeCoreBeforeV2(response.status)) {
+            return new ForwardDialError({
+                reason: "protocol-unsupported",
+                message: `${origin} does not serve /forward/v2; it predates typed forward refusals.`,
+            });
+        }
+        return unavailable(`a plain request to the route got ${response.status}`);
+    }
+    catch {
+        return unavailable("a plain request to the route got no answer");
+    }
+};
+export const openForwardV2 = (endpoint, workspaceId, port, options) => {
+    const host = options?.host ?? "127.0.0.1";
+    const signal = options?.signal;
+    const deadlineMs = options?.deadlineMs ?? FORWARD_V2_OPEN_DEADLINE_MS;
+    const url = forwardUrl(endpoint, `/v1/workspaces/${workspaceId}/forward/v2`, {
+        port: String(port),
+        host,
+    });
+    const origin = new URL(endpoint.baseUrl).origin;
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true)
+            return reject(signal.reason);
+        const ws = new WebSocket(url, FORWARD_V2_SUBPROTOCOL);
+        ws.binaryType = "arraybuffer";
+        const { forward, receive } = bridgeForward(ws, FORWARD_V2_MAX_FRAME_BYTES);
+        const probing = new AbortController();
+        let phase = "handshake";
+        const settle = (next) => {
+            phase = next;
+            clearTimeout(deadline);
+            signal?.removeEventListener("abort", onAbort);
+            probing.abort();
+        };
+        const fail = (error) => {
+            if (phase === "open" || phase === "failed")
+                return;
+            settle("failed");
+            ws.close();
+            reject(error);
+        };
+        const unreadable = (message) => fail(new ForwardDialError({ reason: "protocol-unsupported", message }));
+        const onAbort = () => fail(signal?.reason);
+        const deadline = setTimeout(() => fail(new ForwardDialError({
+            reason: "transport-unavailable",
+            message: `${origin} did not open the forward within ${deadlineMs} ms.`,
+        })), deadlineMs);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        ws.addEventListener("open", () => {
+            phase = "awaiting-answer";
+            if (ws.protocol !== FORWARD_V2_SUBPROTOCOL) {
+                unreadable(`${origin} accepted the forward without the ${FORWARD_V2_SUBPROTOCOL} protocol.`);
+            }
+        });
+        ws.addEventListener("message", (event) => {
+            if (phase === "open")
+                return receive(event);
+            if (phase !== "awaiting-answer")
+                return;
+            const frame = typeof event.data === "string" ? decodeOpenFrame(event.data) : Option.none();
+            if (Option.isNone(frame)) {
+                return unreadable(`${origin} answered the forward with a frame this SDK cannot read.`);
+            }
+            if (frame.value.t === "refused")
+                return fail(refusalError(frame.value));
+            settle("open");
+            resolve({ binding: frame.value.binding, forward });
+        });
+        ws.addEventListener("close", () => {
+            if (phase === "awaiting-answer") {
+                return fail(new ForwardDialError({
+                    reason: "transport-unavailable",
+                    message: `The forward's connection to ${origin} closed before the control plane answered.`,
+                }));
+            }
+            if (phase !== "handshake")
+                return;
+            phase = "probing";
+            void failedHandshakeError(url, origin, probing.signal).then(fail);
+        });
+    });
+};

package/dist/facade/workspace.js

@@ -7,6 +7,7 @@ import { elapsed } from "../internal/clock.js";
 import { mapAccountRef } from "../internal/credentials.js";
 import { parseTtlSeconds } from "../internal/duration.js";
 import { requireProcessUser } from "../internal/process-user.js";
+import { openForward } from "./forward.js";
 import { makeInteractiveSession } from "./session.js";
 /** The wire runtime as the SDK reports it. */
 export const toRuntimeInfo = (runtime) => ({
@@ -23,6 +24,16 @@ export const toRuntimeInfo = (runtime) => ({
 // concurrent stop while ready() polls must surface immediately, not as a 10-minute timeout.
 // "retained" too: the executor ended and is kept for recovery; it never becomes ready.
 const FAILED_STATUSES = new Set(["failed", "cancelled", "stopped", "retained"]);
+const OWNER_MAP_REFUSAL_CODES = new Set(["owner-map-unsupported", "owner-map-unverified"]);
+const readyFailureCode = (code) => {
+    if (code === "image-build-stalled")
+        return "workspace_image_build_stalled";
+    if (code === "image-build-timeout")
+        return "workspace_image_build_timeout";
+    if (code !== undefined && OWNER_MAP_REFUSAL_CODES.has(code))
+        return code;
+    return "workspace_not_ready";
+};
 const READY_POLL_INTERVAL_MS = 2_000;
 /**
  * `ready()` looks again soon, then less often: a Docker launch is ready in about four seconds, and
@@ -479,13 +490,7 @@ export const makeWorkspace = (ctx, init) => {
                 }
                 if (FAILED_STATUSES.has(details.status)) {
                     const reason = details.error === undefined ? "" : `: ${details.error.message}`;
-                    throw new SealantError(`Workspace ${init.id} reached terminal status "${details.status}" before becoming ready${reason}`, {
-                        code: details.error?.code === "image-build-stalled"
-                            ? "workspace_image_build_stalled"
-                            : details.error?.code === "image-build-timeout"
-                                ? "workspace_image_build_timeout"
-                                : "workspace_not_ready",
-                    });
+                    throw new SealantError(`Workspace ${init.id} reached terminal status "${details.status}" before becoming ready${reason}`, { code: readyFailureCode(details.error?.code) });
                 }
                 const phase = details.phase === undefined ? undefined : toWorkspacePhase(details.phase);
                 const wasBuilding = building;
@@ -796,105 +801,11 @@ export const makeWorkspace = (ctx, init) => {
         sshAsRoot: async () => {
             await ctx.runtime.run(clearWorkspaceSshUserOp(init.id, { ownerUserId: ctx.config.hostLocal.ownerUserId }));
         },
-        forward: (port, options) => openForward(ctx, init.id, port, options),
+        forward: (port, options) => openForward({
+            baseUrl: ctx.config.baseUrl,
+            apiKey: ctx.config.apiKey,
+            ownerUserId: ctx.config.hostLocal.ownerUserId,
+        }, init.id, port, options),
     };
     return workspace;
 };
-/**
- * Open the held-WebSocket port forward (the byte-pipe data plane, mirroring
- * the session attachment): binary frames are payload bytes in both
- * directions; text frames are control JSON — `{"t":"eof"}` up for half-close,
- * `{"t":"end"}` down when the remote closes. Auth rides the connect
- * (`?token=` / `?ownerUserId=`), never per frame. The server refuses the
- * upgrade with a plain HTTP status when nothing listens on the port, which
- * surfaces here as the connect rejection.
- */
-const openForward = (ctx, workspaceId, port, options) => {
-    const config = ctx.config;
-    const url = new URL(`/v1/workspaces/${workspaceId}/forward`, config.baseUrl);
-    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-    url.searchParams.set("port", String(port));
-    if (options?.host !== undefined) {
-        url.searchParams.set("host", options.host);
-    }
-    if (options?.protocol === "udp") {
-        url.searchParams.set("protocol", "udp");
-    }
-    // The owner assertion always rides the URL (a service principal needs it alongside its
-    // key, and WebSocket cannot carry headers — same contract as the session attach).
-    url.searchParams.set("ownerUserId", config.hostLocal.ownerUserId);
-    if (config.apiKey !== undefined) {
-        url.searchParams.set("token", config.apiKey);
-    }
-    return new Promise((resolve, reject) => {
-        const ws = new WebSocket(url);
-        ws.binaryType = "arraybuffer";
-        // Push-queue bridging WS message events to the pull-based async iterable.
-        const pending = [];
-        let wake;
-        let finished = false;
-        const closedResolver = Promise.withResolvers();
-        const closed = closedResolver.promise;
-        const finish = (reason) => {
-            if (finished) {
-                return;
-            }
-            finished = true;
-            closedResolver.resolve(reason);
-            wake?.();
-        };
-        ws.addEventListener("message", (event) => {
-            if (typeof event.data === "string") {
-                try {
-                    const frame = JSON.parse(event.data);
-                    if (frame.t === "end") {
-                        finish("end");
-                    }
-                }
-                catch {
-                    // Unknown text frame — ignore.
-                }
-                return;
-            }
-            pending.push(new Uint8Array(event.data));
-            wake?.();
-        });
-        ws.addEventListener("close", () => finish("closed"));
-        const output = {
-            [Symbol.asyncIterator]: () => ({
-                next: async () => {
-                    for (;;) {
-                        const chunk = pending.shift();
-                        if (chunk !== undefined) {
-                            return { done: false, value: chunk };
-                        }
-                        if (finished) {
-                            return { done: true, value: undefined };
-                        }
-                        await new Promise((r) => {
-                            wake = r;
-                        });
-                        wake = undefined;
-                    }
-                },
-            }),
-        };
-        const forward = {
-            send: (input) => {
-                // Copy into a plain ArrayBuffer-backed view (WebSocket.send rejects SharedArrayBuffer views).
-                ws.send(new Uint8Array(input).buffer);
-            },
-            eof: () => {
-                ws.send(JSON.stringify({ t: "eof" }));
-            },
-            output,
-            closed,
-            close: () => {
-                finish("closed");
-                ws.close();
-            },
-        };
-        ws.addEventListener("open", () => resolve(forward), { once: true });
-        ws.addEventListener("error", () => reject(new Error(`workspace forward failed: could not connect to ${url.host} (is anything listening on 127.0.0.1:${port} in the workspace?)`)), { once: true });
-    });
-};

package/dist/index.d.ts

@@ -16,7 +16,7 @@
  */
 export { Sealant } from "./client.js";
 export { claudeCode, codex, customHarness, opencode, pi } from "./harness.js";
-export { SealantApiError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
+export { ForwardDialError, type ForwardDialFailure, type ForwardDialReason, SealantApiError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
 export type * from "./types.js";
 export { findWorkspaceEnvReservedRule, findWorkspaceSecretEnvReservedRule, formatWorkspaceEnvIssue, parseWorkspaceEnv, parseWorkspaceSecretEnv, WORKSPACE_ENV_MAX_ENTRIES, WORKSPACE_ENV_MAX_NAME_LENGTH, WORKSPACE_ENV_MAX_TOTAL_BYTES, WORKSPACE_ENV_MAX_VALUE_BYTES, WORKSPACE_ENV_NAME_PATTERN, WORKSPACE_ENV_SECRET_MARKERS, } from "@sealant/api-contracts/workspace-environment";
 export type { WorkspaceEnvIssue, WorkspaceEnvParseResult, WorkspaceEnvReservedRule, } from "@sealant/api-contracts/workspace-environment";

package/dist/index.js

@@ -16,7 +16,7 @@
  */
 export { Sealant } from "./client.js";
 export { claudeCode, codex, customHarness, opencode, pi } from "./harness.js";
-export { SealantApiError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
+export { ForwardDialError, SealantApiError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
 // The workspace environment policy (`CreateOptions.env` validation) is public API: downstream
 // products validate at their own boundaries with the exact rules the platform enforces.
 export { findWorkspaceEnvReservedRule, findWorkspaceSecretEnvReservedRule, formatWorkspaceEnvIssue, parseWorkspaceEnv, parseWorkspaceSecretEnv, WORKSPACE_ENV_MAX_ENTRIES, WORKSPACE_ENV_MAX_NAME_LENGTH, WORKSPACE_ENV_MAX_TOTAL_BYTES, WORKSPACE_ENV_MAX_VALUE_BYTES, WORKSPACE_ENV_NAME_PATTERN, WORKSPACE_ENV_SECRET_MARKERS, } from "@sealant/api-contracts/workspace-environment";

package/dist/types.d.ts

@@ -1064,11 +1064,14 @@ export interface Workspace {
      * Rejects with `workspace_ready_timeout` past the readiness bound, `workspace_image_build_timeout`
      * past the image-build bound (the caller's, or the control plane's own), `workspace_image_build_stalled` when the build stopped making
      * progress (with the step it stopped on), and `workspace_not_ready` when the launch ended
-     * otherwise (with the control plane's reason). When the handle came from
-     * `workspaces.create()` and `ready()` gives up on a bound, a stop is requested before the error
-     * is thrown, so an abandoned launch does not keep running to its cap; the error says whether the
-     * request was accepted (not that the workspace stopped). Options given here win over the ones
-     * given to `create()`.
+     * otherwise (with the control plane's reason; a runtime's `unsupported-runtime-requirement`
+     * refusal is one). A per-person launch the worker refused for its owner map rejects with the
+     * refusal's own code: `owner-map-unsupported` when the image cannot apply the owner map,
+     * `owner-map-unverified` when Core cannot tell whether it does.
+     * When the handle came from `workspaces.create()` and `ready()` gives up on a bound, a stop is
+     * requested before the error is thrown, so an abandoned launch does not keep running to its cap;
+     * the error says whether the request was accepted (not that the workspace stopped). Options given
+     * here win over the ones given to `create()`.
      */
     ready(options?: WorkspaceReadyOptions): Promise<this>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/sdk-next",
-  "version": "0.40.0-next.756",
+  "version": "0.40.0-next.758",
   "description": "The fluent public SDK for Sealant — create a workspace, run a harness, replay the record.",
   "license": "Apache-2.0",
   "repository": {
@@ -26,12 +26,12 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@sealant/api-contracts": "npm:@sealant/api-contracts-next@0.40.0-next.756"
+    "@sealant/api-contracts": "npm:@sealant/api-contracts-next@0.40.0-next.758"
   },
   "peerDependencies": {
     "effect": "^4.0.5"
   },
-  "gitHead": "93701b91347c5f4bc66573a0ee4e74073b68c83f",
+  "gitHead": "cad5836dece75c30a8aa91978d233cd1c1f7064d",
   "publishConfig": {
     "access": "public"
   }