@sealant/sdk 0.5.2 → 0.7.1

package/dist/effect/operations.d.ts

@@ -117,6 +117,14 @@ export declare const execWorkspaceOp: (workspaceId: string, payload: {
     readonly mode: "interactive" | "one-shot";
     readonly status: "cancelled" | "completed" | "failed" | "queued" | "running";
     readonly prompt?: string | undefined;
+    readonly command?: {
+        readonly executable: string;
+        readonly args: readonly string[];
+        readonly cwd?: string | undefined;
+    } | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
     readonly exitCode?: number | undefined;
     readonly errorMessage?: string | undefined;
     readonly startedAt?: string | undefined;
@@ -156,6 +164,9 @@ export declare const createRunOp: (payload: {
         readonly args: readonly string[];
         readonly cwd?: string | undefined;
     } | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
 }) => Effect.Effect<{
     readonly runId: string;
     readonly workspaceId: string;
@@ -165,6 +176,14 @@ export declare const createRunOp: (payload: {
     readonly mode: "interactive" | "one-shot";
     readonly status: "cancelled" | "completed" | "failed" | "queued" | "running";
     readonly prompt?: string | undefined;
+    readonly command?: {
+        readonly executable: string;
+        readonly args: readonly string[];
+        readonly cwd?: string | undefined;
+    } | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
     readonly exitCode?: number | undefined;
     readonly errorMessage?: string | undefined;
     readonly startedAt?: string | undefined;
@@ -181,6 +200,14 @@ export declare const getRunOp: (runId: string) => Effect.Effect<{
     readonly mode: "interactive" | "one-shot";
     readonly status: "cancelled" | "completed" | "failed" | "queued" | "running";
     readonly prompt?: string | undefined;
+    readonly command?: {
+        readonly executable: string;
+        readonly args: readonly string[];
+        readonly cwd?: string | undefined;
+    } | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
     readonly exitCode?: number | undefined;
     readonly errorMessage?: string | undefined;
     readonly startedAt?: string | undefined;
@@ -203,6 +230,14 @@ export declare const listRunsOp: (query: {
         readonly mode: "interactive" | "one-shot";
         readonly status: "cancelled" | "completed" | "failed" | "queued" | "running";
         readonly prompt?: string | undefined;
+        readonly command?: {
+            readonly executable: string;
+            readonly args: readonly string[];
+            readonly cwd?: string | undefined;
+        } | undefined;
+        readonly metadata?: {
+            readonly [x: string]: unknown;
+        } | undefined;
         readonly exitCode?: number | undefined;
         readonly errorMessage?: string | undefined;
         readonly startedAt?: string | undefined;
@@ -230,6 +265,14 @@ export declare const updateRunOp: (runId: string, payload: {
     readonly mode: "interactive" | "one-shot";
     readonly status: "cancelled" | "completed" | "failed" | "queued" | "running";
     readonly prompt?: string | undefined;
+    readonly command?: {
+        readonly executable: string;
+        readonly args: readonly string[];
+        readonly cwd?: string | undefined;
+    } | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
     readonly exitCode?: number | undefined;
     readonly errorMessage?: string | undefined;
     readonly startedAt?: string | undefined;
@@ -255,11 +298,13 @@ export declare const getRunTimelineOp: (runId: string, query: {
 }[], import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").RunBadRequestError | import("@sealant/api-contracts").RunInternalServerError | import("@sealant/api-contracts").RunNotFoundError | import("effect/Schema").SchemaError, SealantApiClient>;
 export declare const getRunScrollbackOp: (runId: string, query: {
     readonly processId: string;
-    readonly stream: "stderr" | "stdout";
+    readonly stream: "pty" | "stderr" | "stdout";
     readonly atSequence?: string | undefined;
+    readonly fromSequence?: string | undefined;
+    readonly limit?: string | undefined;
 }) => Effect.Effect<{
     readonly processId: string;
-    readonly stream: "stderr" | "stdout";
+    readonly stream: "pty" | "stderr" | "stdout";
     readonly byteCount: number;
     readonly contentBase64: string;
 }, import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").RunBadRequestError | import("@sealant/api-contracts").RunInternalServerError | import("@sealant/api-contracts").RunNotFoundError | import("effect/Schema").SchemaError, SealantApiClient>;
@@ -286,6 +331,158 @@ export declare const getRunChangesOp: (runId: string) => Effect.Effect<{
     }[];
     readonly diff: string;
 }, import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").RunInternalServerError | import("@sealant/api-contracts").RunNotFoundError | import("effect/Schema").SchemaError, SealantApiClient>;
+export declare const createSessionOp: (payload: {
+    readonly workspaceId: string;
+    readonly ownerUserId: string;
+    readonly argv: readonly string[];
+    readonly cwd?: string | undefined;
+    readonly env?: {
+        readonly [x: string]: string;
+    } | undefined;
+    readonly cols?: number | undefined;
+    readonly rows?: number | undefined;
+    readonly term?: string | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
+}) => Effect.Effect<{
+    readonly sessionId: string;
+    readonly workspaceId: string;
+    readonly runId: string;
+    readonly ownerUserId: string;
+    readonly status: "exited" | "failed" | "running" | "starting";
+    readonly argv: readonly string[];
+    readonly cwd?: string | undefined;
+    readonly cols: number;
+    readonly rows: number;
+    readonly exitCode?: number | undefined;
+    readonly exitSignal?: number | undefined;
+    readonly errorMessage?: string | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
+    readonly outputHighWater: string;
+    readonly createdAt: string;
+    readonly endedAt?: string | undefined;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").SessionBadGatewayError | import("@sealant/api-contracts").SessionBadRequestError | import("@sealant/api-contracts").SessionConflictError | import("@sealant/api-contracts").SessionForbiddenError | import("@sealant/api-contracts").SessionInternalServerError | import("@sealant/api-contracts").SessionNotFoundError | import("@sealant/api-contracts").SessionUnauthorizedError, SealantApiClient>;
+export declare const getSessionOp: (sessionId: string, ownerUserId?: string | undefined) => Effect.Effect<{
+    readonly sessionId: string;
+    readonly workspaceId: string;
+    readonly runId: string;
+    readonly ownerUserId: string;
+    readonly status: "exited" | "failed" | "running" | "starting";
+    readonly argv: readonly string[];
+    readonly cwd?: string | undefined;
+    readonly cols: number;
+    readonly rows: number;
+    readonly exitCode?: number | undefined;
+    readonly exitSignal?: number | undefined;
+    readonly errorMessage?: string | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
+    readonly outputHighWater: string;
+    readonly createdAt: string;
+    readonly endedAt?: string | undefined;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").SessionBadRequestError | import("@sealant/api-contracts").SessionForbiddenError | import("@sealant/api-contracts").SessionInternalServerError | import("@sealant/api-contracts").SessionNotFoundError | import("@sealant/api-contracts").SessionUnauthorizedError, SealantApiClient>;
+export declare const listSessionsOp: (query: {
+    readonly ownerUserId: string;
+    readonly workspaceId?: string | undefined;
+    readonly status?: "exited" | "failed" | "running" | "starting" | undefined;
+    readonly limit?: string | undefined;
+}) => Effect.Effect<{
+    readonly items: readonly {
+        readonly sessionId: string;
+        readonly workspaceId: string;
+        readonly runId: string;
+        readonly ownerUserId: string;
+        readonly status: "exited" | "failed" | "running" | "starting";
+        readonly argv: readonly string[];
+        readonly cwd?: string | undefined;
+        readonly cols: number;
+        readonly rows: number;
+        readonly exitCode?: number | undefined;
+        readonly exitSignal?: number | undefined;
+        readonly errorMessage?: string | undefined;
+        readonly metadata?: {
+            readonly [x: string]: unknown;
+        } | undefined;
+        readonly outputHighWater: string;
+        readonly createdAt: string;
+        readonly endedAt?: string | undefined;
+    }[];
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").SessionBadRequestError | import("@sealant/api-contracts").SessionForbiddenError | import("@sealant/api-contracts").SessionInternalServerError | import("@sealant/api-contracts").SessionUnauthorizedError, SealantApiClient>;
+export declare const getSessionOutputOp: (sessionId: string, query: {
+    readonly ownerUserId?: string | undefined;
+    readonly from?: string | undefined;
+    readonly limit?: string | undefined;
+}) => Effect.Effect<{
+    readonly sessionId: string;
+    readonly chunks: readonly {
+        readonly sequence: string;
+        readonly dataBase64: string;
+    }[];
+    readonly nextFrom: string;
+    readonly status: "exited" | "failed" | "running" | "starting";
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").SessionBadRequestError | import("@sealant/api-contracts").SessionForbiddenError | import("@sealant/api-contracts").SessionInternalServerError | import("@sealant/api-contracts").SessionNotFoundError | import("@sealant/api-contracts").SessionUnauthorizedError, SealantApiClient>;
+export declare const sendSessionInputOp: (sessionId: string, payload: {
+    readonly ownerUserId?: string | undefined;
+    readonly dataBase64: string;
+}) => Effect.Effect<{
+    readonly ok: boolean;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").SessionBadGatewayError | import("@sealant/api-contracts").SessionBadRequestError | import("@sealant/api-contracts").SessionConflictError | import("@sealant/api-contracts").SessionForbiddenError | import("@sealant/api-contracts").SessionInternalServerError | import("@sealant/api-contracts").SessionNotFoundError | import("@sealant/api-contracts").SessionUnauthorizedError, SealantApiClient>;
+export declare const resizeSessionOp: (sessionId: string, payload: {
+    readonly ownerUserId?: string | undefined;
+    readonly cols: number;
+    readonly rows: number;
+}) => Effect.Effect<{
+    readonly ok: boolean;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").SessionBadGatewayError | import("@sealant/api-contracts").SessionBadRequestError | import("@sealant/api-contracts").SessionConflictError | import("@sealant/api-contracts").SessionForbiddenError | import("@sealant/api-contracts").SessionInternalServerError | import("@sealant/api-contracts").SessionNotFoundError | import("@sealant/api-contracts").SessionUnauthorizedError, SealantApiClient>;
+export declare const signalSessionOp: (sessionId: string, payload: {
+    readonly ownerUserId?: string | undefined;
+    readonly signal: number;
+}) => Effect.Effect<{
+    readonly ok: boolean;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").SessionBadGatewayError | import("@sealant/api-contracts").SessionBadRequestError | import("@sealant/api-contracts").SessionConflictError | import("@sealant/api-contracts").SessionForbiddenError | import("@sealant/api-contracts").SessionInternalServerError | import("@sealant/api-contracts").SessionNotFoundError | import("@sealant/api-contracts").SessionUnauthorizedError, SealantApiClient>;
+export declare const closeSessionOp: (sessionId: string, payload: {
+    readonly ownerUserId?: string | undefined;
+}) => Effect.Effect<{
+    readonly sessionId: string;
+    readonly workspaceId: string;
+    readonly runId: string;
+    readonly ownerUserId: string;
+    readonly status: "exited" | "failed" | "running" | "starting";
+    readonly argv: readonly string[];
+    readonly cwd?: string | undefined;
+    readonly cols: number;
+    readonly rows: number;
+    readonly exitCode?: number | undefined;
+    readonly exitSignal?: number | undefined;
+    readonly errorMessage?: string | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
+    readonly outputHighWater: string;
+    readonly createdAt: string;
+    readonly endedAt?: string | undefined;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").SessionBadGatewayError | import("@sealant/api-contracts").SessionBadRequestError | import("@sealant/api-contracts").SessionForbiddenError | import("@sealant/api-contracts").SessionInternalServerError | import("@sealant/api-contracts").SessionNotFoundError | import("@sealant/api-contracts").SessionUnauthorizedError, SealantApiClient>;
+export declare const createAccessTokenOp: (payload: {
+    readonly ownerUserId: string;
+    readonly scopes: readonly ("session:input" | "session:read" | "workspace:exec")[];
+    readonly name?: string | undefined;
+    readonly workspaceId?: string | undefined;
+    readonly ttlSeconds?: number | undefined;
+}) => Effect.Effect<{
+    readonly tokenId: string;
+    readonly ownerUserId: string;
+    readonly name?: string | undefined;
+    readonly scopes: readonly ("session:input" | "session:read" | "workspace:exec")[];
+    readonly workspaceId?: string | undefined;
+    readonly expiresAt?: string | undefined;
+    readonly revokedAt?: string | undefined;
+    readonly createdAt: string;
+    readonly token: string;
+}, import("@sealant/api-contracts").AccessTokenBadRequestError | import("@sealant/api-contracts").AccessTokenInternalServerError | import("@sealant/api-contracts").AccessTokenNotFoundError | import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError, SealantApiClient>;
 export declare const inferenceRespondOp: (payload: {
     readonly ownerUserId: string;
     readonly credentials?: {

package/dist/effect/operations.js

@@ -20,5 +20,20 @@ export const getRunTimelineOp = (runId, query) => Effect.flatMap(SealantApiClien
 export const getRunScrollbackOp = (runId, query) => Effect.flatMap(SealantApiClient, (client) => client.runs.getRunScrollback({ params: { runId }, query }));
 export const getRunLossOp = (runId) => Effect.flatMap(SealantApiClient, (client) => client.runs.getRunLoss({ params: { runId } }));
 export const getRunChangesOp = (runId) => Effect.flatMap(SealantApiClient, (client) => client.runs.getRunChanges({ params: { runId } }));
+// ---- sessions ----
+export const createSessionOp = (payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.createSession({ payload, headers: {} }));
+export const getSessionOp = (sessionId, ownerUserId) => Effect.flatMap(SealantApiClient, (client) => client.sessions.getSession({
+    params: { sessionId },
+    headers: {},
+    query: ownerUserId === undefined ? {} : { ownerUserId },
+}));
+export const listSessionsOp = (query) => Effect.flatMap(SealantApiClient, (client) => client.sessions.listSessions({ query, headers: {} }));
+export const getSessionOutputOp = (sessionId, query) => Effect.flatMap(SealantApiClient, (client) => client.sessions.getSessionOutput({ params: { sessionId }, headers: {}, query }));
+export const sendSessionInputOp = (sessionId, payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.sendSessionInput({ params: { sessionId }, headers: {}, payload }));
+export const resizeSessionOp = (sessionId, payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.resizeSession({ params: { sessionId }, headers: {}, payload }));
+export const signalSessionOp = (sessionId, payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.signalSession({ params: { sessionId }, headers: {}, payload }));
+export const closeSessionOp = (sessionId, payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.closeSession({ params: { sessionId }, headers: {}, payload }));
+// ---- access tokens ----
+export const createAccessTokenOp = (payload) => Effect.flatMap(SealantApiClient, (client) => client.accessTokens.createAccessToken({ payload }));
 // ---- inference ----
 export const inferenceRespondOp = (payload) => Effect.flatMap(SealantApiClient, (client) => client.inference.respond({ payload }));

package/dist/effect/run-harness.js

@@ -11,31 +11,50 @@
 import { Effect } from "effect";
 import { SealantError } from "../errors.js";
 import { makeRun, toRunChangesData } from "../facade/run.js";
-import { createRunOp, getRunChangesOp, getRunOp } from "./operations.js";
+import { createRunOp, getRunChangesOp, getRunOp, getWorkspaceOp } from "./operations.js";
 const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled"]);
 const POLL_INTERVAL = "500 millis";
 const RUN_TIMEOUT_MS = 30 * 60 * 1_000;
 /**
- * Registers the run WITH the harness command — the control plane executes it server-side (the worker
- * docker-execs it and ingests telemetry). The cwd is the workspace repo, which the worker defaults to.
+ * Registers the run — the control plane executes it server-side (the worker docker-execs it and
+ * ingests telemetry). With a client harness value (the creating handle), the client-built command
+ * rides along — the escape hatch that keeps `customHarness()` working. WITHOUT one (a handle from
+ * `workspaces.get(id)`), the harness id is read from the workspace's own spec and NO command is
+ * sent: the control plane constructs the invocation server-side, so re-fetched handles are fully
+ * capable.
  */
-const createHarnessRunEffect = (ctx, init, prompt) => Effect.gen(function* () {
+const createHarnessRunEffect = (ctx, init, prompt, options) => Effect.gen(function* () {
+    const metadata = options?.metadata === undefined ? {} : { metadata: { ...options.metadata } };
     const harness = init.harness;
-    if (harness === undefined) {
-        return yield* Effect.fail(new SealantError("This workspace handle has no harness; use the handle returned by workspaces.create().", { code: "harness_required" }));
+    if (harness !== undefined) {
+        const command = harness.buildRunCommand(prompt);
+        return yield* createRunOp({
+            workspaceId: init.id,
+            ownerUserId: ctx.config.hostLocal.ownerUserId,
+            harnessId: harness.id,
+            mode: "one-shot",
+            prompt,
+            command: { executable: command.executable, args: [...command.args] },
+            ...metadata,
+        });
+    }
+    const details = yield* getWorkspaceOp(init.id);
+    const spec = details.spec;
+    const harnessId = spec?.harness?.id;
+    if (harnessId === undefined) {
+        return yield* Effect.fail(new SealantError(`Workspace ${init.id} has no harness in its spec; pass a harness at workspaces.create() or use workspace.exec().`, { code: "harness_required" }));
     }
-    const command = harness.buildRunCommand(prompt);
     return yield* createRunOp({
         workspaceId: init.id,
         ownerUserId: ctx.config.hostLocal.ownerUserId,
-        harnessId: harness.id,
+        harnessId,
         mode: "one-shot",
         prompt,
-        command: { executable: command.executable, args: [...command.args] },
+        ...metadata,
     });
 });
-const runHarnessEffect = (ctx, init, prompt) => Effect.gen(function* () {
-    const created = yield* createHarnessRunEffect(ctx, init, prompt);
+const runHarnessEffect = (ctx, init, prompt, options) => Effect.gen(function* () {
+    const created = yield* createHarnessRunEffect(ctx, init, prompt, options);
     const runId = created.runId;
     // Block until the run is terminal, polling the control plane.
     const deadline = Date.now() + RUN_TIMEOUT_MS;
@@ -54,10 +73,10 @@ const runHarnessEffect = (ctx, init, prompt) => Effect.gen(function* () {
     return makeRun(ctx, { wire, changes });
 });
 /** The BLOCKING `harness.run()` implementation, registered into the Workspace facade by the client. */
-export const runHarness = (ctx, init, prompt) => ctx.runtime.run(runHarnessEffect(ctx, init, prompt));
+export const runHarness = (ctx, init, prompt, options) => ctx.runtime.run(runHarnessEffect(ctx, init, prompt, options));
 /**
  * The NON-BLOCKING `harness.start()` implementation: register the run and return the live handle
  * immediately. Callers stream progress via `run.record.stream()` and settle via `run.wait()` (which
  * fetches the captured changes once terminal).
  */
-export const startHarness = (ctx, init, prompt) => ctx.runtime.run(Effect.map(createHarnessRunEffect(ctx, init, prompt), (created) => makeRun(ctx, { wire: created })));
+export const startHarness = (ctx, init, prompt, options) => ctx.runtime.run(Effect.map(createHarnessRunEffect(ctx, init, prompt, options), (created) => makeRun(ctx, { wire: created })));

package/dist/facade/session.d.ts

@@ -0,0 +1,22 @@
+import type { InteractiveSession } from "../types.js";
+import type { SdkContext } from "./context.js";
+export declare const makeInteractiveSession: (ctx: SdkContext, wire: {
+    readonly sessionId: string;
+    readonly workspaceId: string;
+    readonly runId: string;
+    readonly ownerUserId: string;
+    readonly status: "exited" | "failed" | "running" | "starting";
+    readonly argv: readonly string[];
+    readonly cwd?: string | undefined;
+    readonly cols: number;
+    readonly rows: number;
+    readonly exitCode?: number | undefined;
+    readonly exitSignal?: number | undefined;
+    readonly errorMessage?: string | undefined;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
+    readonly outputHighWater: string;
+    readonly createdAt: string;
+    readonly endedAt?: string | undefined;
+}) => InteractiveSession;

package/dist/facade/session.js

@@ -0,0 +1,171 @@
+import { closeSessionOp, getSessionOp, getSessionOutputOp, resizeSessionOp, sendSessionInputOp, signalSessionOp, } from "../effect/operations.js";
+const OUTPUT_POLL_INTERVAL_MS = 250;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const decodeBase64 = (value) => {
+    const buffer = Buffer.from(value, "base64");
+    return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+};
+/** Parse one SSE frame block ("event: ...\nid: ...\ndata: ...") into its fields. */
+const parseSseFrame = (block) => {
+    let event = "message";
+    let id;
+    const dataLines = [];
+    for (const line of block.split("\n")) {
+        if (line.startsWith(":")) {
+            continue; // comment / keep-alive
+        }
+        if (line.startsWith("event:")) {
+            event = line.slice(6).trim();
+        }
+        else if (line.startsWith("id:")) {
+            id = line.slice(3).trim();
+        }
+        else if (line.startsWith("data:")) {
+            dataLines.push(line.slice(5).trimStart());
+        }
+    }
+    if (dataLines.length === 0 && id === undefined) {
+        return undefined;
+    }
+    return { event, id, data: dataLines.join("\n") };
+};
+/** Stream the session's output over SSE. Throws on transport failure (caller falls back). */
+async function* streamOverSse(ctx, sessionId, from, signal) {
+    const config = ctx.config;
+    const fetchImpl = config.fetch ?? fetch;
+    const url = new URL(`/v1/sessions/${sessionId}/output/stream`, config.baseUrl);
+    url.searchParams.set("from", from.toString());
+    if (config.apiKey === undefined) {
+        url.searchParams.set("ownerUserId", config.hostLocal.ownerUserId);
+    }
+    const response = await fetchImpl(url, {
+        headers: {
+            accept: "text/event-stream",
+            ...(config.apiKey === undefined ? {} : { authorization: `Bearer ${config.apiKey}` }),
+        },
+        ...(signal === undefined ? {} : { signal }),
+    });
+    if (!response.ok || response.body === null) {
+        throw new Error(`session output stream failed: HTTP ${response.status}`);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffered = "";
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                return;
+            }
+            buffered += decoder.decode(value, { stream: true });
+            for (;;) {
+                const boundary = buffered.indexOf("\n\n");
+                if (boundary === -1) {
+                    break;
+                }
+                const block = buffered.slice(0, boundary);
+                buffered = buffered.slice(boundary + 2);
+                const frame = parseSseFrame(block);
+                if (frame === undefined) {
+                    continue;
+                }
+                if (frame.event === "end") {
+                    return;
+                }
+                if (frame.event === "output" && frame.id !== undefined) {
+                    yield { sequence: BigInt(frame.id), data: decodeBase64(frame.data) };
+                }
+            }
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+}
+/** Poll-backed fallback: page the range endpoint until the session settles. */
+async function* streamByPolling(ctx, sessionId, from, signal) {
+    let cursor = from;
+    for (;;) {
+        if (signal?.aborted === true) {
+            return;
+        }
+        const page = await ctx.runtime.run(getSessionOutputOp(sessionId, {
+            ownerUserId: ctx.config.hostLocal.ownerUserId,
+            from: cursor.toString(),
+        }));
+        for (const chunk of page.chunks) {
+            yield { sequence: BigInt(chunk.sequence), data: decodeBase64(chunk.dataBase64) };
+        }
+        cursor = BigInt(page.nextFrom);
+        if (page.chunks.length === 0) {
+            if (page.status === "exited" || page.status === "failed") {
+                return;
+            }
+            await delay(OUTPUT_POLL_INTERVAL_MS);
+        }
+    }
+}
+export const makeInteractiveSession = (ctx, wire) => {
+    const sessionId = wire.sessionId;
+    return {
+        id: sessionId,
+        workspaceId: wire.workspaceId,
+        runId: wire.runId,
+        send: async (input) => {
+            const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+            await ctx.runtime.run(sendSessionInputOp(sessionId, {
+                ownerUserId: ctx.config.hostLocal.ownerUserId,
+                dataBase64: Buffer.from(bytes).toString("base64"),
+            }));
+        },
+        output: (options) => {
+            const from = options?.from ?? 0n;
+            const signal = options?.signal;
+            async function* iterate() {
+                let cursor = from;
+                try {
+                    for await (const chunk of streamOverSse(ctx, sessionId, cursor, signal)) {
+                        yield chunk;
+                        cursor = chunk.sequence + 1n;
+                    }
+                    return;
+                }
+                catch (error) {
+                    if (signal?.aborted === true) {
+                        return;
+                    }
+                    // SSE transport unavailable (proxy, fetch impl, older server) — fall back to polling
+                    // from the cursor; the sequence keying makes the switch seamless.
+                    void error;
+                }
+                yield* streamByPolling(ctx, sessionId, cursor, signal);
+            }
+            return iterate();
+        },
+        resize: async (cols, rows) => {
+            await ctx.runtime.run(resizeSessionOp(sessionId, {
+                ownerUserId: ctx.config.hostLocal.ownerUserId,
+                cols,
+                rows,
+            }));
+        },
+        signal: async (signalNumber) => {
+            await ctx.runtime.run(signalSessionOp(sessionId, {
+                ownerUserId: ctx.config.hostLocal.ownerUserId,
+                signal: signalNumber,
+            }));
+        },
+        status: async () => {
+            const current = await ctx.runtime.run(getSessionOp(sessionId, ctx.config.hostLocal.ownerUserId));
+            return {
+                status: current.status,
+                ...(current.exitCode === undefined ? {} : { exitCode: current.exitCode }),
+                ...(current.exitSignal === undefined ? {} : { exitSignal: current.exitSignal }),
+                outputHighWater: BigInt(current.outputHighWater),
+            };
+        },
+        close: async () => {
+            await ctx.runtime.run(closeSessionOp(sessionId, { ownerUserId: ctx.config.hostLocal.ownerUserId }));
+        },
+    };
+};

package/dist/facade/workspace.js

@@ -1,7 +1,8 @@
 import { execWorkspace } from "../effect/exec-workspace.js";
-import { expireWorkspaceOp, getWorkspaceOp, restartWorkspaceOp, stopWorkspaceOp, } from "../effect/operations.js";
+import { createSessionOp, expireWorkspaceOp, getSessionOp, getWorkspaceOp, listSessionsOp, restartWorkspaceOp, stopWorkspaceOp, } from "../effect/operations.js";
 import { SealantError, SealantNotImplementedError } from "../errors.js";
 import { parseTtlSeconds } from "../internal/duration.js";
+import { makeInteractiveSession } from "./session.js";
 // Terminal statuses a workspace can never leave: ready()/events() fail fast (or end the stream)
 // on these instead of polling out their deadline. "stopped" is terminal too — a TTL expiry or a
 // concurrent stop while ready() polls must surface immediately, not as a 10-minute timeout.
@@ -15,7 +16,60 @@ let harnessExecutors;
 export const registerHarnessExecutors = (executors) => {
     harnessExecutors = executors;
 };
+// Launch commands for the built-in harnesses — used when a RE-FETCHED handle (no client harness
+// value) opens a harness session; the workspace's own spec names the harness id.
+const BUILTIN_LAUNCH_COMMANDS = {
+    opencode: "opencode",
+    codex: "codex",
+    "claude-code": "claude",
+};
 export const makeWorkspace = (ctx, init) => {
+    const openSession = async (argv, options) => {
+        const created = await ctx.runtime.run(createSessionOp({
+            workspaceId: init.id,
+            ownerUserId: ctx.config.hostLocal.ownerUserId,
+            argv: [...argv],
+            ...(options?.cwd === undefined ? {} : { cwd: options.cwd }),
+            ...(options?.env === undefined ? {} : { env: options.env }),
+            ...(options?.cols === undefined ? {} : { cols: options.cols }),
+            ...(options?.rows === undefined ? {} : { rows: options.rows }),
+            ...(options?.term === undefined ? {} : { term: options.term }),
+            ...(options?.metadata === undefined ? {} : { metadata: { ...options.metadata } }),
+        }));
+        return makeInteractiveSession(ctx, created);
+    };
+    const sessions = {
+        open: (argv, options) => openSession(argv, options),
+        get: async (sessionId) => {
+            const wire = await ctx.runtime.run(getSessionOp(sessionId, ctx.config.hostLocal.ownerUserId));
+            if (wire.workspaceId !== init.id) {
+                throw new SealantError(`Session ${sessionId} does not belong to workspace ${init.id}.`, {
+                    code: "session_not_found",
+                });
+            }
+            return makeInteractiveSession(ctx, wire);
+        },
+        list: async () => {
+            const response = await ctx.runtime.run(listSessionsOp({
+                ownerUserId: ctx.config.hostLocal.ownerUserId,
+                workspaceId: init.id,
+            }));
+            return response.items.map((item) => makeInteractiveSession(ctx, item));
+        },
+    };
+    /** The harness's interactive launch argv — client value when present, else from the spec. */
+    const resolveHarnessLaunchArgv = async () => {
+        if (init.harness !== undefined) {
+            return [init.harness.launchCommand ?? init.harness.id];
+        }
+        const details = await ctx.runtime.run(getWorkspaceOp(init.id));
+        const spec = details.spec;
+        const harnessId = spec?.harness?.id;
+        if (harnessId === undefined) {
+            throw new SealantError(`Workspace ${init.id} has no harness in its spec; open a session with workspace.sessions.open(argv) instead.`, { code: "harness_required" });
+        }
+        return [BUILTIN_LAUNCH_COMMANDS[harnessId] ?? harnessId];
+    };
     const harness = {
         run: (prompt, options) => {
             if (harnessExecutors === undefined) {
@@ -29,7 +83,10 @@ export const makeWorkspace = (ctx, init) => {
             }
             return harnessExecutors.start(ctx, init, prompt, options);
         },
-        session: () => Promise.reject(new SealantNotImplementedError("harness.session (interactive, Phase 3)")),
+        session: async (options) => {
+            const argv = await resolveHarnessLaunchArgv();
+            return openSession(argv, options);
+        },
     };
     const workspace = {
         id: init.id,
@@ -60,6 +117,7 @@ export const makeWorkspace = (ctx, init) => {
             }
         },
         harness,
+        sessions,
         exec: (argv, options) => execWorkspace(ctx, init, argv, options),
         // Poll-backed lifecycle stream: emit a coarse event on each status transition until the workspace
         // reaches a terminal/ready state. Swaps to SSE over Postgres LISTEN/NOTIFY in Stage 5 (same shape).