@sealant/sdk 0.5.1 → 0.7.0

package/dist/facade/workspace.js

@@ -1,15 +1,75 @@
 import { execWorkspace } from "../effect/exec-workspace.js";
-import { getWorkspaceOp } from "../effect/operations.js";
+import { createSessionOp, expireWorkspaceOp, getSessionOp, getWorkspaceOp, listSessionsOp, restartWorkspaceOp, stopWorkspaceOp, } from "../effect/operations.js";
 import { SealantError, SealantNotImplementedError } from "../errors.js";
-const FAILED_STATUSES = new Set(["failed", "cancelled"]);
+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.
+const FAILED_STATUSES = new Set(["failed", "cancelled", "stopped"]);
 const READY_POLL_INTERVAL_MS = 2_000;
 const READY_TIMEOUT_MS = 10 * 60 * 1_000;
+const STOP_POLL_INTERVAL_MS = 1_000;
+const STOP_TIMEOUT_MS = 60 * 1_000;
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 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) {
@@ -23,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,
@@ -54,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).
@@ -83,9 +147,48 @@ export const makeWorkspace = (ctx, init) => {
             }
             return iterate();
         },
-        stop: () => Promise.reject(new SealantNotImplementedError("workspace.stop (lifecycle, Phase 3)")),
-        restart: () => Promise.reject(new SealantNotImplementedError("workspace.restart (lifecycle, Phase 3)")),
-        expire: () => Promise.reject(new SealantNotImplementedError("workspace.expire (lifecycle, Phase 3)")),
+        // BLOCKING stop: the control plane accepts the stop (202) and the worker tears the container
+        // down; resolve only once the workspace reports the terminal "stopped" status, so callers can
+        // trust the container is gone when this settles.
+        stop: async () => {
+            const ownerUserId = ctx.config.hostLocal.ownerUserId;
+            await ctx.runtime.run(stopWorkspaceOp(init.id, { ownerUserId }));
+            const deadline = Date.now() + STOP_TIMEOUT_MS;
+            for (;;) {
+                const details = await ctx.runtime.run(getWorkspaceOp(init.id));
+                if (details.status === "stopped") {
+                    return;
+                }
+                if (Date.now() > deadline) {
+                    throw new SealantError(`Timed out waiting for workspace ${init.id} to stop.`, {
+                        code: "workspace_stop_timeout",
+                    });
+                }
+                await delay(STOP_POLL_INTERVAL_MS);
+            }
+        },
+        // Restart drives a fresh launch (new attempt, new container, same resolved spec) and returns a
+        // handle that resolves readiness against the NEW runtime via the usual ready() gate.
+        restart: async () => {
+            const ownerUserId = ctx.config.hostLocal.ownerUserId;
+            await ctx.runtime.run(restartWorkspaceOp(init.id, { ownerUserId }));
+            return makeWorkspace(ctx, {
+                id: init.id,
+                name: init.name,
+                status: "queued",
+                ...(init.harness === undefined ? {} : { harness: init.harness }),
+            });
+        },
+        // expire({in: "2h"}) sets the TTL, expire() expires now (the platform reaper stops it on its
+        // next tick), expire({in: null}) clears the TTL. Resolves once the expiry is recorded.
+        expire: async (options) => {
+            const ownerUserId = ctx.config.hostLocal.ownerUserId;
+            const ttl = options?.in;
+            await ctx.runtime.run(expireWorkspaceOp(init.id, {
+                ownerUserId,
+                ...(ttl === undefined ? {} : { ttlSeconds: ttl === null ? null : parseTtlSeconds(ttl) }),
+            }));
+        },
     };
     return workspace;
 };

package/dist/internal/blueprint.d.ts

@@ -26,5 +26,6 @@ export declare const buildCreateWorkspaceRequest: (options: CreateOptions, confi
             readonly github?: string | undefined;
         } | undefined;
         readonly spec: unknown;
+        readonly ttlSeconds?: number | undefined;
     };
 };

package/dist/internal/blueprint.js

@@ -11,7 +11,9 @@
  * plane resolves those account references server-side (never secret material over this path).
  */
 import { randomUUID } from "node:crypto";
+import { SealantError } from "../errors.js";
 import { mapWorkspaceCredentials } from "./credentials.js";
+import { parseTtlSeconds } from "./duration.js";
 const sanitizeRepoSlug = (value) => {
     const slug = value
         .toLowerCase()
@@ -27,20 +29,32 @@ const toGitUrl = (repository) => {
     return `https://${repository}.git`;
 };
 export const buildCreateWorkspaceRequest = (options, config) => {
-    const tail = options.repository
+    if ((options.repository === undefined) === (options.source === undefined)) {
+        throw new SealantError("workspaces.create requires exactly one of `repository` (a git remote to clone) or `source` (a caller-owned mount).", { code: "invalid_create_options" });
+    }
+    if (options.source !== undefined && options.ref !== undefined) {
+        throw new SealantError("`ref` applies only to `repository` sources, not mounts.", {
+            code: "invalid_create_options",
+        });
+    }
+    const sourceName = options.repository ?? options.source?.path ?? "workspace";
+    const tail = sourceName
         .split("/")
         .filter((s) => s.length > 0)
-        .pop() ?? options.repository;
+        .pop() ?? sourceName;
     const credentials = mapWorkspaceCredentials(options.credentials);
     const spec = {
         version: "1",
         sources: {
-            workspace: {
-                kind: "git",
-                provider: "generic",
-                url: toGitUrl(options.repository),
-                ref: options.ref ?? "main",
-            },
+            workspace: options.repository !== undefined
+                ? {
+                    kind: "git",
+                    provider: "generic",
+                    url: toGitUrl(options.repository),
+                    // Omitted ref = the repository's default branch, resolved by the clone itself.
+                    ...(options.ref === undefined ? {} : { ref: options.ref }),
+                }
+                : { kind: "mount", hostPath: options.source?.path },
         },
         harness: { id: options.harness.id },
         customization: { enableSealantd: true },
@@ -63,6 +77,7 @@ export const buildCreateWorkspaceRequest = (options, config) => {
             repository: sanitizeRepoSlug(tail),
             tag: `sdk-${randomUUID().slice(0, 8)}`,
             ...(options.name === undefined ? {} : { name: options.name }),
+            ...(options.ttl === undefined ? {} : { ttlSeconds: parseTtlSeconds(options.ttl) }),
             spec,
         },
     };

package/dist/internal/duration.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parse a human TTL like `"90m"`, `"2h"`, `"45s"`, `"1d"` into whole seconds (milliseconds round
+ * up to at least 1s — the wire TTL is second-granular). Throws a typed `SealantError` on anything
+ * else so a typo'd TTL fails at the call site instead of silently never expiring.
+ */
+export declare const parseTtlSeconds: (ttl: string) => number;

package/dist/internal/duration.js

@@ -0,0 +1,34 @@
+import { SealantError } from "../errors.js";
+const DURATION_PATTERN = /^(\d+)(ms|s|m|h|d)$/;
+const UNIT_SECONDS = {
+    s: 1,
+    m: 60,
+    h: 3600,
+    d: 86400,
+};
+/**
+ * Parse a human TTL like `"90m"`, `"2h"`, `"45s"`, `"1d"` into whole seconds (milliseconds round
+ * up to at least 1s — the wire TTL is second-granular). Throws a typed `SealantError` on anything
+ * else so a typo'd TTL fails at the call site instead of silently never expiring.
+ */
+export const parseTtlSeconds = (ttl) => {
+    const match = DURATION_PATTERN.exec(ttl.trim());
+    if (match === null) {
+        throw new SealantError(`Invalid TTL duration "${ttl}". Use a positive integer with a unit: e.g. "45s", "90m", "2h", "1d".`, { code: "invalid_ttl" });
+    }
+    const value = Number.parseInt(match[1] ?? "", 10);
+    const unit = match[2] ?? "";
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new SealantError(`Invalid TTL duration "${ttl}". The value must be a positive integer.`, {
+            code: "invalid_ttl",
+        });
+    }
+    if (unit === "ms") {
+        return Math.max(1, Math.ceil(value / 1000));
+    }
+    const multiplier = UNIT_SECONDS[unit];
+    if (multiplier === undefined) {
+        throw new SealantError(`Invalid TTL duration "${ttl}".`, { code: "invalid_ttl" });
+    }
+    return value * multiplier;
+};

package/dist/types.d.ts

@@ -56,8 +56,8 @@ export interface Harness {
     /** Optional launch command for an interactive session (defaults to the executable). */
     readonly launchCommand?: string;
 }
-/** Lifecycle status of a workspace. `stopped`/`expired` arrive with lifecycle close-out (Phase 3). */
-export type WorkspaceStatus = "queued" | "running" | "ready" | "failed" | "cancelled";
+/** Lifecycle status of a workspace. */
+export type WorkspaceStatus = "queued" | "running" | "ready" | "failed" | "cancelled" | "stopped";
 /** A coarse lifecycle event observed while a workspace is being provisioned. */
 export interface WorkspaceEvent {
     readonly type: string;
@@ -90,12 +90,30 @@ export interface WorkspaceCredentialsOptions {
     /** `true` for the caller's default GitHub account, or a string naming a specific one. */
     readonly github?: boolean | string;
 }
+/**
+ * A workspace sourced from a CALLER-OWNED host directory instead of a fresh clone. The platform
+ * bind-mounts `path` as the workspace working directory and treats it as caller-owned: writes
+ * persist across workspace stop/restart/expiry, and the path is never reprovisioned or deleted.
+ * The install must allowlist the path's root (`SEALANT_WORKSPACE_MOUNT_ALLOWED_ROOTS`); paths
+ * outside the allowlist are rejected at create. Credentials and dotfiles options compose
+ * unchanged. Clone-based workspaces remain the right shape for independent verification.
+ */
+export interface WorkspaceMountSource {
+    readonly kind: "mount";
+    /** Absolute, normalized host path (no `..` segments). */
+    readonly path: string;
+}
 export interface CreateOptions {
-    /** Source git repository to build the workspace around (e.g. `"github.com/acme/billing-service"`). */
-    readonly repository: string;
+    /**
+     * Source git repository to build the workspace around (e.g. `"github.com/acme/billing-service"`).
+     * Exactly one of `repository` or `source` must be provided.
+     */
+    readonly repository?: string;
+    /** Alternative to `repository`: source the workspace from a caller-owned mount. */
+    readonly source?: WorkspaceMountSource;
     /** The harness to run inside the workspace. */
     readonly harness: Harness;
-    /** Git ref to check out (defaults to the repository's default branch). */
+    /** Git ref to check out (defaults to the repository's default branch; `repository` only). */
     readonly ref?: string;
     /** Human-friendly name for the workspace. */
     readonly name?: string;
@@ -109,6 +127,12 @@ export interface CreateOptions {
     readonly onEvent?: (event: WorkspaceEvent) => void;
     /** Connected-account credentials to attach to the workspace (see `WorkspaceCredentialsOptions`). */
     readonly credentials?: WorkspaceCredentialsOptions;
+    /**
+     * Time-to-live for the workspace, e.g. `"90m"`, `"2h"` (also `"45s"`, `"1d"`). Once it elapses
+     * the platform stops the workspace and removes its container. Omitted = the server default TTL
+     * (if the install configures one).
+     */
+    readonly ttl?: string;
 }
 export interface ListOptions {
     readonly status?: WorkspaceStatus;
@@ -150,15 +174,20 @@ export interface Workspace {
      * run record like any other process. `argv[0]` is the executable, the rest its arguments.
      */
     exec(argv: readonly string[], options?: WorkspaceExecOptions): Promise<WorkspaceExecResult>;
+    /** Interactive PTY sessions: open new ones, reattach to existing ones by id. */
+    readonly sessions: WorkspaceSessions;
     /** Lifecycle events as an async stream. */
     events(): AsyncIterable<WorkspaceEvent>;
-    /** Stop the workspace now (Phase 3). */
+    /** Stop the workspace: remove its container and settle it in the terminal "stopped" status. */
     stop(): Promise<void>;
-    /** Restart the workspace into a fresh runtime (Phase 3). */
+    /** Restart the workspace into a fresh runtime — a new container, no filesystem carry-over. */
     restart(): Promise<Workspace>;
-    /** Schedule the workspace to expire (Phase 3). */
+    /**
+     * Schedule the workspace to expire: `expire({ in: "2h" })` sets the TTL, `expire()` expires it
+     * now (the platform reaper stops it shortly), `expire({ in: null })` clears the TTL.
+     */
     expire(options?: {
-        readonly in?: string;
+        readonly in?: string | null;
     }): Promise<void>;
 }
 export interface RunOptions {
@@ -166,9 +195,23 @@ export interface RunOptions {
     readonly signal?: AbortSignal;
     /** Idempotency key so a retried call does not start a duplicate run. */
     readonly idempotencyKey?: string;
+    /**
+     * Opaque correlation bag ({ projectId, sessionId, ... }): stored verbatim by the platform and
+     * echoed on reads. No platform-side semantics.
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
+/** Options for opening an interactive PTY session. */
 export interface SessionOptions {
-    readonly signal?: AbortSignal;
+    /** Working directory inside the workspace (defaults to the repository root). */
+    readonly cwd?: string;
+    /** Extra environment for the PTY process (not for secrets — use `credentials`). */
+    readonly env?: Readonly<Record<string, string>>;
+    readonly cols?: number;
+    readonly rows?: number;
+    readonly term?: string;
+    /** Opaque correlation bag, stored verbatim and echoed on reads. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
 }
 /** Runs a harness in a workspace, one-shot or interactive. */
 export interface HarnessRunner {
@@ -176,7 +219,7 @@ export interface HarnessRunner {
     run(prompt: string, options?: RunOptions): Promise<Run>;
     /** NON-BLOCKING: returns a live handle immediately for streaming via `run.record.stream()`. */
     start(prompt: string, options?: RunOptions): Promise<Run>;
-    /** Interactive session reusing the live workspace (Phase 3). */
+    /** Opens an interactive PTY session running the harness's launch command. */
     session(options?: SessionOptions): Promise<InteractiveSession>;
 }
 export type RunOutcome = "completed" | "failed";
@@ -467,12 +510,91 @@ export interface Run {
     /** Resolves once the run has terminally completed (no-op if already settled). */
     wait(): Promise<Run>;
 }
-/** An interactive harness session over the live workspace (Phase 3). */
+/** Lifecycle status of an interactive session. */
+export type SessionStatus = "starting" | "running" | "exited" | "failed";
+/** One recorded output chunk. `sequence` is the durable resume cursor. */
+export interface SessionOutputChunk {
+    readonly sequence: bigint;
+    readonly data: Uint8Array;
+}
+/** A point-in-time report of an interactive session's lifecycle. */
+export interface InteractiveSessionStatus {
+    readonly status: SessionStatus;
+    readonly exitCode?: number;
+    readonly exitSignal?: number;
+    /**
+     * Highest recorded output sequence — resume a disconnected reader with
+     * `output({ from: outputHighWater + 1n })` (or re-read from `0n` for full history).
+     */
+    readonly outputHighWater: bigint;
+}
+/**
+ * An interactive PTY session over a live workspace. Sessions are DURABLE PLATFORM RESOURCES, not
+ * client connections: the PTY keeps running when this handle (or the whole process) goes away, and
+ * a session can be re-fetched by id from any workspace handle (`workspace.sessions.get(id)`) and
+ * driven from there. Output is byte-exact, redacted, and sequence-keyed — `output({ from: 0n })`
+ * after a reconnect replays the full recorded history and then live-tails.
+ */
 export interface InteractiveSession {
-    send(input: string): Promise<void>;
-    output(): AsyncIterable<Uint8Array>;
+    readonly id: string;
+    readonly workspaceId: string;
+    /** The run recording this session — its record is the durable, replayable evidence. */
+    readonly runId: string;
+    /** Send keystrokes. Strings are UTF-8-encoded; bytes pass through untouched. */
+    send(input: string | Uint8Array): Promise<void>;
+    /**
+     * Byte-exact output as a RESUMABLE stream: recorded history from `from` (inclusive; default the
+     * beginning), then the live tail until the session settles. Each chunk carries its durable
+     * sequence, so a disconnected consumer resumes with `from: lastChunk.sequence + 1n`.
+     */
+    output(options?: {
+        readonly from?: bigint;
+        readonly signal?: AbortSignal;
+    }): AsyncIterable<SessionOutputChunk>;
+    /** Resize the PTY. */
+    resize(cols: number, rows: number): Promise<void>;
+    /** Deliver a POSIX signal to the session's process (e.g. 2 = SIGINT). */
+    signal(signal: number): Promise<void>;
+    /** Current lifecycle + the output high-water mark (the resume cursor). */
+    status(): Promise<InteractiveSessionStatus>;
+    /** Close the PTY (hang up the terminal). Resolves once the session settles. */
     close(): Promise<void>;
 }
+/** Interactive sessions of one workspace: open new ones, reattach to existing ones. */
+export interface WorkspaceSessions {
+    /** Opens a PTY session running `argv` (argv[0] is the program). */
+    open(argv: readonly string[], options?: SessionOptions): Promise<InteractiveSession>;
+    /** Reattach to a session by id — works from ANY handle, not just the creating one. */
+    get(sessionId: string): Promise<InteractiveSession>;
+    /** Sessions of this workspace, newest first. */
+    list(): Promise<readonly InteractiveSession[]>;
+}
+/**
+ * Scopes for the session surface: `session:read` (stream/status/output), `session:input`
+ * (input/resize/signal), `workspace:exec` (open sessions/terminals, exec). A client holding only
+ * `session:read` can stream output but is rejected for input and exec.
+ */
+export type AccessTokenScope = "session:read" | "session:input" | "workspace:exec";
+export interface CreateAccessTokenOptions {
+    readonly scopes: readonly AccessTokenScope[];
+    readonly name?: string;
+    /** Narrow the token to one workspace. */
+    readonly workspaceId?: string;
+    /** Time-to-live, e.g. `"15m"`, `"2h"`. Omitted = no expiry. */
+    readonly ttl?: string;
+}
+export interface CreatedAccessToken {
+    readonly tokenId: string;
+    /** The bearer secret — shown exactly once, never retrievable again. Use it as `apiKey`. */
+    readonly token: string;
+    readonly scopes: readonly AccessTokenScope[];
+    readonly workspaceId?: string;
+    readonly expiresAt?: string;
+}
+/** Mint scoped bearer tokens (e.g. for a mobile pairing flow's per-scope grants). */
+export interface AccessTokensNamespace {
+    create(options: CreateAccessTokenOptions): Promise<CreatedAccessToken>;
+}
 /**
  * Connected-account selection for inference — the same reference shape as workspace creation,
  * minus GitHub (not a model provider). `true` means "my default account"; a string names one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/sdk",
-  "version": "0.5.1",
+  "version": "0.7.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.5.1"
+    "@sealant/api-contracts": "^0.7.0"
   },
   "devDependencies": {
     "@effect/vitest": "^4.0.0-beta.85",