@sealant/sdk-next 0.40.0-next.760 → 0.40.0-next.763

package/dist/errors.d.ts

@@ -1,4 +1,5 @@
 import type { ForwardRefusalReason } from "@sealant/api-contracts";
+import type { ForwardResetCause } from "./types.js";
 /**
  * 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
@@ -82,3 +83,11 @@ export declare class SealantNotImplementedError extends SealantError {
     readonly name = "SealantNotImplementedError";
     constructor(operation: string);
 }
+/** A bounded forward was reset after it opened. Its streams error with this. */
+export declare class ForwardResetError extends SealantError {
+    readonly name: string;
+    readonly reason: ForwardResetCause;
+    /** The reason Core sent, when this SDK does not know it (`unrecognized-reset`). */
+    readonly wireReason?: string;
+    constructor(reason: ForwardResetCause, wireReason?: string);
+}

package/dist/errors.js

@@ -85,3 +85,16 @@ export class SealantNotImplementedError extends SealantError {
         super(`${operation} is part of the Sealant SDK surface but is not implemented in this build yet.`, { code: "not_implemented" });
     }
 }
+/** A bounded forward was reset after it opened. Its streams error with this. */
+export class ForwardResetError extends SealantError {
+    name = "ForwardResetError";
+    reason;
+    /** The reason Core sent, when this SDK does not know it (`unrecognized-reset`). */
+    wireReason;
+    constructor(reason, wireReason) {
+        super(`The forward was reset: ${wireReason ?? reason}.`, { code: "ForwardResetError" });
+        this.reason = reason;
+        if (wireReason !== undefined)
+            this.wireReason = wireReason;
+    }
+}

package/dist/facade/bounded-forward.d.ts

@@ -0,0 +1,7 @@
+import type { BoundedWorkspaceForward } from "../types.js";
+export declare const boundedForward: (ws: WebSocket, binding: {
+    readonly kind: "port";
+} | {
+    readonly kind: "session";
+    readonly session: string;
+}, onWindowOpen: () => void) => BoundedWorkspaceForward;

package/dist/facade/bounded-forward.js

@@ -0,0 +1,191 @@
+import { CountQueuingStrategy, ReadableStream, WritableStream, } from "node:stream/web";
+import { FORWARD_V2_MAX_FRAME_BYTES, ForwardFlow, forwardFrames, forwardResetReasonSchema, } from "@sealant/api-contracts";
+import { Schema } from "effect";
+import { ForwardResetError } from "../errors.js";
+const isKnownReset = Schema.is(forwardResetReasonSchema);
+const SOCKET_HIGH_WATER_BYTES = FORWARD_V2_MAX_FRAME_BYTES;
+/** A WHATWG socket has no drain event, so a held `progress` checks again this often. */
+const HELD_PROGRESS_RETRY_MS = 10;
+export const boundedForward = (ws, binding, onWindowOpen) => {
+    const flow = new ForwardFlow();
+    const unread = [];
+    const closed = Promise.withResolvers();
+    let state = { kind: "open" };
+    let windowOpen = false;
+    let finReceived = false;
+    let reader;
+    let writer;
+    let pendingRead;
+    let creditWaiter;
+    let progressRetry;
+    const sendText = (frame) => ws.send(JSON.stringify(frame));
+    const wakeReader = () => {
+        const waiter = pendingRead;
+        pendingRead = undefined;
+        waiter?.();
+    };
+    const wakeWriter = () => {
+        const waiter = creditWaiter;
+        creditWaiter = undefined;
+        waiter?.();
+    };
+    const settle = (next, close) => {
+        if (state.kind !== "open")
+            return;
+        state = next;
+        clearTimeout(progressRetry);
+        closed.resolve(close);
+        if (next.kind === "failed") {
+            writer?.error(next.error);
+            if (next.readable === "errored")
+                reader?.error(next.error);
+        }
+        wakeReader();
+        wakeWriter();
+    };
+    const resetBy = (reason, wireReason) => settle({ kind: "failed", error: new ForwardResetError(reason, wireReason), readable: "errored" }, { kind: "reset", reason, ...(wireReason === undefined ? {} : { wireReason }) });
+    const reset = (reason) => {
+        if (state.kind !== "open")
+            return;
+        if (ws.readyState === WebSocket.OPEN)
+            sendText({ t: "reset", reason });
+        resetBy(reason);
+        ws.close();
+    };
+    const endedByWorkspace = () => {
+        if (flow.delivered && creditWaiter === undefined) {
+            return settle({ kind: "ended" }, { kind: "end" });
+        }
+        settle({
+            kind: "failed",
+            error: new ForwardResetError("workspace-ended"),
+            readable: "drains-what-arrived",
+        }, { kind: "reset", reason: "workspace-ended" });
+    };
+    const sendProgress = () => {
+        if (state.kind !== "open" || ws.readyState !== WebSocket.OPEN || !flow.progressDue)
+            return;
+        if (ws.bufferedAmount > SOCKET_HIGH_WATER_BYTES) {
+            progressRetry ??= setTimeout(() => {
+                progressRetry = undefined;
+                sendProgress();
+            }, HELD_PROGRESS_RETRY_MS);
+            return;
+        }
+        const progress = flow.takeProgress();
+        if (progress !== undefined)
+            sendText(progress);
+    };
+    const deliver = (controller, chunk) => {
+        controller.enqueue(chunk);
+        flow.consumed(chunk.byteLength);
+        sendProgress();
+    };
+    const onInbound = (frame) => {
+        const inbound = flow.receive(frame);
+        switch (inbound.kind) {
+            case "data":
+                if (pendingRead === undefined || reader === undefined) {
+                    unread.push(inbound.data);
+                    return;
+                }
+                deliver(reader, inbound.data);
+                return wakeReader();
+            case "progress":
+                if (!windowOpen) {
+                    windowOpen = true;
+                    onWindowOpen();
+                }
+                return wakeWriter();
+            case "fin":
+                finReceived = true;
+                if (unread.length === 0)
+                    reader?.close();
+                wakeReader();
+                return endedByWorkspace();
+            case "reset": {
+                const known = isKnownReset(inbound.reason);
+                resetBy(known ? inbound.reason : "unrecognized-reset", known ? undefined : inbound.reason);
+                return ws.close();
+            }
+            case "violation":
+                return reset(inbound.reason);
+        }
+    };
+    ws.addEventListener("message", (event) => {
+        if (state.kind !== "open")
+            return;
+        if (event.data instanceof ArrayBuffer)
+            onInbound(new Uint8Array(event.data));
+        else if (typeof event.data === "string")
+            onInbound(event.data);
+    });
+    ws.addEventListener("close", () => resetBy("connection-lost"));
+    const readable = new ReadableStream({
+        start: (controller) => {
+            reader = controller;
+        },
+        pull: (controller) => {
+            const chunk = unread.shift();
+            if (chunk === undefined) {
+                return new Promise((resolve) => {
+                    pendingRead = resolve;
+                });
+            }
+            deliver(controller, chunk);
+            if (finReceived && unread.length === 0)
+                controller.close();
+        },
+        cancel: () => reset("aborted"),
+    }, { highWaterMark: 0 });
+    const waitForCredit = (fits) => new Promise((resolve, reject) => {
+        const check = () => {
+            if (state.kind === "failed")
+                return reject(state.error);
+            if (state.kind === "ended")
+                return reject(new ForwardResetError("workspace-ended"));
+            if (fits())
+                return resolve();
+            creditWaiter = check;
+        };
+        check();
+    });
+    const holdReadyUntilCredit = () => waitForCredit(() => flow.canSend(1));
+    const writable = new WritableStream({
+        start: (controller) => {
+            writer = controller;
+            // The sink's own `abort` runs only after a write waiting for credit settles. Node has had
+            // `signal` since 18; its types still lack it.
+            const signal = "signal" in controller ? controller.signal : undefined;
+            if (!(signal instanceof AbortSignal))
+                return;
+            signal.addEventListener("abort", () => {
+                // The stream is already erroring: erroring it again from here breaks Node's abort.
+                writer = undefined;
+                reset("aborted");
+            });
+        },
+        write: async (chunk) => {
+            for (const frame of forwardFrames(chunk)) {
+                await waitForCredit(() => flow.canSend(frame.byteLength));
+                flow.sent(frame.byteLength);
+                // A copy: a WHATWG socket refuses a view of a SharedArrayBuffer.
+                ws.send(new Uint8Array(frame));
+            }
+            await holdReadyUntilCredit();
+        },
+        close: () => {
+            if (state.kind === "open")
+                sendText(flow.fin());
+        },
+        abort: () => reset("aborted"),
+    }, new CountQueuingStrategy({ highWaterMark: 1 }));
+    sendText(flow.open());
+    return {
+        readable,
+        writable,
+        binding,
+        closed: closed.promise,
+        close: () => reset("aborted"),
+    };
+};

package/dist/facade/forward.d.ts

@@ -1,18 +1,9 @@
-import { type ForwardBinding } from "@sealant/api-contracts";
-import type { WorkspaceForward, WorkspaceForwardOptions } from "../types.js";
+import type { BoundedForwardTarget, BoundedWorkspaceForward, BoundedWorkspaceForwardOptions, 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>;
+export type ForwardV2Options = BoundedForwardTarget & Pick<BoundedWorkspaceForwardOptions, "signal" | "deadlineMs">;
+export declare const openForwardV2: (endpoint: ForwardEndpoint, workspaceId: string, port: number, options?: ForwardV2Options | undefined) => Promise<BoundedWorkspaceForward>;

package/dist/facade/forward.js

@@ -1,6 +1,7 @@
-import { FORWARD_V2_MAX_FRAME_BYTES, FORWARD_V2_SUBPROTOCOL, forwardOpenFrameSchema, forwardRefusalReasonSchema, } from "@sealant/api-contracts";
+import { FORWARD_REFUSAL_STATUS, FORWARD_V2_SUBPROTOCOL, forwardOpenFrameSchema, forwardRefusalReasonSchema, } from "@sealant/api-contracts";
 import { Option, Schema } from "effect";
 import { ForwardDialError } from "../errors.js";
+import { boundedForward } from "./bounded-forward.js";
 const forwardUrl = (endpoint, path, query) => {
     const url = new URL(path, endpoint.baseUrl);
     url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
@@ -16,7 +17,7 @@ const forwardUrl = (endpoint, path, query) => {
     }
     return url;
 };
-const bridgeForward = (ws, maxFrameBytes = Number.POSITIVE_INFINITY) => {
+const bridgeForward = (ws) => {
     const pending = [];
     let wake;
     let finished = false;
@@ -30,7 +31,7 @@ const bridgeForward = (ws, maxFrameBytes = Number.POSITIVE_INFINITY) => {
         wake?.();
     };
     ws.addEventListener("close", () => finish("closed"));
-    const receive = (event) => {
+    ws.addEventListener("message", (event) => {
         if (typeof event.data === "string") {
             try {
                 const frame = JSON.parse(event.data);
@@ -43,7 +44,7 @@ const bridgeForward = (ws, maxFrameBytes = Number.POSITIVE_INFINITY) => {
         }
         pending.push(new Uint8Array(event.data));
         wake?.();
-    };
+    });
     const output = {
         [Symbol.asyncIterator]: () => ({
             next: async () => {
@@ -63,14 +64,10 @@ const bridgeForward = (ws, maxFrameBytes = Number.POSITIVE_INFINITY) => {
             },
         }),
     };
-    const forward = {
+    return {
         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);
+            // 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" }));
@@ -82,7 +79,6 @@ const bridgeForward = (ws, maxFrameBytes = Number.POSITIVE_INFINITY) => {
             ws.close();
         },
     };
-    return { forward, receive };
 };
 export const openForward = (endpoint, workspaceId, port, options) => {
     const url = forwardUrl(endpoint, `/v1/workspaces/${workspaceId}/forward`, {
@@ -93,8 +89,7 @@ export const openForward = (endpoint, workspaceId, port, options) => {
     return new Promise((resolve, reject) => {
         const ws = new WebSocket(url);
         ws.binaryType = "arraybuffer";
-        const { forward, receive } = bridgeForward(ws);
-        ws.addEventListener("message", receive);
+        const forward = bridgeForward(ws);
         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 });
     });
@@ -136,11 +131,13 @@ const failedHandshakeError = async (url, origin, signal) => {
 };
 export const openForwardV2 = (endpoint, workspaceId, port, options) => {
     const host = options?.host ?? "127.0.0.1";
+    const session = options?.session;
     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,
+        session,
     });
     const origin = new URL(endpoint.baseUrl).origin;
     return new Promise((resolve, reject) => {
@@ -148,7 +145,6 @@ export const openForwardV2 = (endpoint, workspaceId, port, options) => {
             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) => {
@@ -178,8 +174,6 @@ export const openForwardV2 = (endpoint, workspaceId, port, options) => {
             }
         });
         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();
@@ -188,11 +182,22 @@ export const openForwardV2 = (endpoint, workspaceId, port, options) => {
             }
             if (frame.value.t === "refused")
                 return fail(refusalError(frame.value));
-            settle("open");
-            resolve({ binding: frame.value.binding, forward });
+            const { binding } = frame.value;
+            if (session !== undefined && (binding.kind !== "session" || binding.session !== session)) {
+                return fail(new ForwardDialError({
+                    reason: "binding-unsupported",
+                    status: FORWARD_REFUSAL_STATUS["binding-unsupported"],
+                    message: `${origin} opened the forward without binding it to session ${session}.`,
+                }));
+            }
+            phase = "awaiting-window";
+            const forward = boundedForward(ws, binding, () => {
+                settle("open");
+                resolve(forward);
+            });
         });
         ws.addEventListener("close", () => {
-            if (phase === "awaiting-answer") {
+            if (phase === "awaiting-answer" || phase === "awaiting-window") {
                 return fail(new ForwardDialError({
                     reason: "transport-unavailable",
                     message: `The forward's connection to ${origin} closed before the control plane answered.`,

package/dist/facade/workspace.js

@@ -7,7 +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 { openForward, openForwardV2 } from "./forward.js";
 import { makeInteractiveSession } from "./session.js";
 /** The wire runtime as the SDK reports it. */
 export const toRuntimeInfo = (runtime) => ({
@@ -295,6 +295,22 @@ const olderControlPlaneRefusal = (argv, error) => {
     });
 };
 export const makeWorkspace = (ctx, init) => {
+    const endpoint = {
+        baseUrl: ctx.config.baseUrl,
+        apiKey: ctx.config.apiKey,
+        ownerUserId: ctx.config.hostLocal.ownerUserId,
+    };
+    function forward(port, options) {
+        if (options?.flow === "bounded") {
+            return openForwardV2(endpoint, init.id, port, options);
+        }
+        if (options !== undefined && "session" in options) {
+            return Promise.reject(new SealantError('A forward bound to a session needs flow: "bounded".', {
+                code: "invalid_options",
+            }));
+        }
+        return openForward(endpoint, init.id, port, options);
+    }
     const openSession = async (argv, options) => {
         // The contract's own rule, checked before anything is asked, with the same value-free reason.
         const refused = sessionArgvIssue(argv);
@@ -801,11 +817,7 @@ export const makeWorkspace = (ctx, init) => {
         sshAsRoot: async () => {
             await ctx.runtime.run(clearWorkspaceSshUserOp(init.id, { ownerUserId: ctx.config.hostLocal.ownerUserId }));
         },
-        forward: (port, options) => openForward({
-            baseUrl: ctx.config.baseUrl,
-            apiKey: ctx.config.apiKey,
-            ownerUserId: ctx.config.hostLocal.ownerUserId,
-        }, init.id, port, options),
+        forward,
     };
     return workspace;
 };

package/dist/index.d.ts

@@ -16,7 +16,7 @@
  */
 export { Sealant } from "./client.js";
 export { claudeCode, codex, customHarness, opencode, pi } from "./harness.js";
-export { ForwardDialError, type ForwardDialFailure, type ForwardDialReason, SealantApiError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
+export { ForwardDialError, type ForwardDialFailure, type ForwardDialReason, ForwardResetError, 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 { ForwardDialError, SealantApiError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
+export { ForwardDialError, ForwardResetError, 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

@@ -14,6 +14,8 @@
  * compile against a stable contract from day one (unimplemented paths reject with
  * `SealantNotImplementedError` at runtime, see `./errors.js`).
  */
+import type { ReadableStream as NodeReadableStream, WritableStream as NodeWritableStream } from "node:stream/web";
+import type { ForwardBinding, ForwardResetReason } from "@sealant/api-contracts";
 /**
  * Public client configuration. Intentionally minimal: a base URL and an API key. Host-local
  * concerns required by the current slice (owner identity, registry, direct database access) live in
@@ -1160,7 +1162,13 @@ export interface Workspace {
      * workspace-private set: the container's loopback (default), or `docker` —
      * the workspace-scoped Docker sidecar's alias, where `docker compose`
      * publishes its ports.
+     *
+     * With `flow: "bounded"`, a TCP forward whose two directions are bounded: the workspace's
+     * producer is held back while `readable` is not read, and `writable` holds back its writer while
+     * the workspace does not take the bytes. It resolves once Core and the workspace runtime have
+     * opened it, and rejects with a {@link ForwardDialError} that says why when they did not.
      */
+    forward(port: number, options: BoundedWorkspaceForwardOptions): Promise<BoundedWorkspaceForward>;
     forward(port: number, options?: WorkspaceForwardOptions): Promise<WorkspaceForward>;
 }
 /**
@@ -1442,6 +1450,10 @@ export interface WorkspaceCredentialsHomeOptions {
 }
 /** Options for {@link Workspace.forward}. */
 export interface WorkspaceForwardOptions {
+    /** Only a bounded forward has a `flow`. */
+    readonly flow?: never;
+    /** Only a bounded forward can be bound to a session. */
+    readonly session?: never;
     /** Target inside the workspace: its loopback (default) or the Docker sidecar. */
     readonly host?: "127.0.0.1" | "localhost" | "docker";
     /**
@@ -1469,6 +1481,64 @@ export interface WorkspaceForward {
     /** Tear the forward down. */
     close(): void;
 }
+/**
+ * Where a bounded forward goes: the port on the workspace's loopback (default) or on the Docker
+ * sidecar, whatever holds it; or, with `session`, the port on the loopback only when a process of
+ * that session holds it. A bound forward resets with `owner-exited` once the session's leader exits.
+ */
+export type BoundedForwardTarget = {
+    readonly host?: "127.0.0.1" | "localhost" | "docker";
+    readonly session?: never;
+} | {
+    readonly host?: "127.0.0.1" | "localhost";
+    readonly session: string;
+};
+/** Options for a bounded {@link Workspace.forward}. TCP only. */
+export type BoundedWorkspaceForwardOptions = BoundedForwardTarget & {
+    readonly flow: "bounded";
+    /** Gives up opening the forward; an open forward ignores it. */
+    readonly signal?: AbortSignal;
+    /** How long opening may take before it rejects, in milliseconds. 30 000 by default. */
+    readonly deadlineMs?: number;
+};
+/**
+ * Why a bounded forward was reset: a reason either side sent, `connection-lost` when the socket
+ * closed with neither a `fin` nor a reset, `unrecognized-reset` when Core sent a reason newer than
+ * this SDK (kept in `wireReason`), or `workspace-ended` when the workspace ended the forward before
+ * it took everything written to it. A write after the workspace ended fails with `workspace-ended`
+ * too.
+ */
+export type ForwardResetCause = ForwardResetReason | "connection-lost" | "unrecognized-reset" | "workspace-ended";
+/**
+ * How a bounded forward ended: the workspace closed its side after it took everything written to
+ * it (`end`), or the forward was reset.
+ */
+export type BoundedWorkspaceForwardClose = {
+    readonly kind: "end";
+} | {
+    readonly kind: "reset";
+    readonly reason: ForwardResetCause;
+    readonly wireReason?: string;
+};
+/**
+ * A bounded forward. Reading `readable` is what lets the workspace send more; `writer.ready` waits
+ * while the workspace can take no more; `writable.close()` half-closes toward the workspace. Wrap
+ * it as a Node stream with `Duplex.fromWeb(forward)`. The streams are typed as `node:stream/web`'s,
+ * which `Duplex.fromWeb` accepts also where the DOM's stream types are loaded.
+ *
+ * A reset fails both streams with a `ForwardResetError`, at once: data the workspace sent that was
+ * not read yet is dropped. When the workspace ends first, `readable` still yields all it sent, and
+ * the writer fails with `workspace-ended` only if something written did not reach the workspace.
+ */
+export interface BoundedWorkspaceForward {
+    readonly readable: NodeReadableStream<Uint8Array>;
+    readonly writable: NodeWritableStream<Uint8Array>;
+    /** What the forward is bound to. */
+    readonly binding: ForwardBinding;
+    readonly closed: Promise<BoundedWorkspaceForwardClose>;
+    /** Resets both directions. */
+    close(): void;
+}
 export interface RunOptions {
     /** Cancel the run by aborting this signal. */
     readonly signal?: AbortSignal;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/sdk-next",
-  "version": "0.40.0-next.760",
+  "version": "0.40.0-next.763",
   "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.760"
+    "@sealant/api-contracts": "npm:@sealant/api-contracts-next@0.40.0-next.763"
   },
   "peerDependencies": {
     "effect": "^4.0.5"
   },
-  "gitHead": "eb43ab8076dbdd584f026d068c478078a294d570",
+  "gitHead": "c741e10743b2c553b526f93565c256fe8fa4bd8b",
   "publishConfig": {
     "access": "public"
   }