@sealant/sdk 0.7.1 → 0.8.0

package/dist/facade/session.js

@@ -1,4 +1,95 @@
 import { closeSessionOp, getSessionOp, getSessionOutputOp, resizeSessionOp, sendSessionInputOp, signalSessionOp, } from "../effect/operations.js";
+/**
+ * Open the held-WebSocket terminal attachment (the data plane). One socket:
+ * binary frames are PTY bytes in both directions, text frames are control
+ * JSON (`{"t":"resize",...}` up, `{"t":"end"}` down). Auth rides the connect —
+ * `?token=` for apiKey clients (WebSocket cannot set headers), `?ownerUserId=`
+ * for host-local — and never repeats per event.
+ */
+const openAttachment = (ctx, sessionId, options) => {
+    const config = ctx.config;
+    const url = new URL(`/v1/sessions/${sessionId}/attach`, config.baseUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.searchParams.set("from", (options?.from ?? 0n).toString());
+    if (config.apiKey === undefined) {
+        url.searchParams.set("ownerUserId", config.hostLocal.ownerUserId);
+    }
+    else {
+        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 attachment = {
+            send: (input) => {
+                const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+                // Copy into a plain ArrayBuffer-backed view (WebSocket.send rejects SharedArrayBuffer views).
+                ws.send(new Uint8Array(bytes).buffer);
+            },
+            resize: (cols, rows) => {
+                ws.send(JSON.stringify({ t: "resize", cols, rows }));
+            },
+            output,
+            closed,
+            close: () => {
+                finish("closed");
+                ws.close();
+            },
+        };
+        ws.addEventListener("open", () => resolve(attachment), { once: true });
+        ws.addEventListener("error", () => reject(new Error(`session attach failed: could not connect to ${url.host}`)), { once: true });
+    });
+};
 const OUTPUT_POLL_INTERVAL_MS = 250;
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const decodeBase64 = (value) => {
@@ -167,5 +258,6 @@ export const makeInteractiveSession = (ctx, wire) => {
         close: async () => {
             await ctx.runtime.run(closeSessionOp(sessionId, { ownerUserId: ctx.config.hostLocal.ownerUserId }));
         },
+        attach: (options) => openAttachment(ctx, sessionId, options),
     };
 };

package/dist/types.d.ts

@@ -559,6 +559,35 @@ export interface InteractiveSession {
     status(): Promise<InteractiveSessionStatus>;
     /** Close the PTY (hang up the terminal). Resolves once the session settles. */
     close(): Promise<void>;
+    /**
+     * THE DATA PLANE for interactive terminals: one held WebSocket carrying
+     * input, output, and resize — auth once at connect, no per-keystroke
+     * requests. Output replays byte-exact from `from` and then live-tails.
+     * `send`/`resize`/`signal`/`output` above remain the request/response
+     * control-plane verbs; a terminal UI should attach instead.
+     */
+    attach(options?: SessionAttachOptions): Promise<SessionAttachment>;
+}
+/** Options for {@link InteractiveSession.attach}. */
+export interface SessionAttachOptions {
+    /** Replay output from this sequence (inclusive; default `0n` = full history). */
+    readonly from?: bigint;
+}
+/**
+ * A live terminal attachment — one WebSocket, held until `close()` or the
+ * session settles. Not durable: reattach by calling `attach` again.
+ */
+export interface SessionAttachment {
+    /** Write keystrokes onto the held socket (no request/response round-trip). */
+    send(input: string | Uint8Array): void;
+    /** Resize the PTY over the held socket. */
+    resize(cols: number, rows: number): void;
+    /** Output bytes: recorded replay from `from`, then live, until settle/close. */
+    readonly output: AsyncIterable<Uint8Array>;
+    /** Resolves when the attachment ends: session settled (`"end"`) or the socket closed. */
+    readonly closed: Promise<"end" | "closed">;
+    /** Drop the attachment (the session keeps running). */
+    close(): void;
 }
 /** Interactive sessions of one workspace: open new ones, reattach to existing ones. */
 export interface WorkspaceSessions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/sdk",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "The fluent public SDK for Sealant — create a workspace, run a harness, replay the record.",
   "license": "Apache-2.0",
   "repository": {
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "effect": "^4.0.0-beta.85",
-    "@sealant/api-contracts": "^0.7.1"
+    "@sealant/api-contracts": "^0.8.0"
   },
   "devDependencies": {
     "@effect/vitest": "^4.0.0-beta.85",