@sealant/sdk 0.28.0 → 0.31.0

package/README.md

@@ -208,6 +208,39 @@ Not covered, and worth saying plainly: a process that _deliberately_ writes a se
 the repository or to a mount is producing ordinary workspace state, and the redactor masks captured
 I/O, not files.
 
+## Capture-sourced workspaces
+
+A `capture` source (sealantd ADR-0015) mounts nothing and clones nothing. The workspace daemon
+registers with a session channel, fetches the worktree's head plan, materialises it onto the
+executor's own disk, claims the lease, and ships captures back over the channel — so a session can
+run where no host path exists (a Cloudflare sandbox, a MicroVM) and outlive any one executor:
+
+```ts
+const workspace = await sealant.workspaces.create({
+  source: {
+    kind: "capture",
+    endpoint: "https://mend.example.com/session/s1",
+    worktreeId: "wt_1",
+    token: sessionToken, // the channel credential; secret
+  },
+  harness: claudeCode(),
+});
+```
+
+- `token` is lifted out of the blueprint and rides the request top level as `captureToken`. The
+  control plane seals it beside `secretEnv` and delivers it through the same boot file, as
+  `SEALANT_CAPTURE_TOKEN`; it is never in the spec, `WorkspaceDetails`, argv, or container env.
+- The channel address and worktree id reach the daemon as `SEALANT_CAPTURE_ENDPOINT` and
+  `SEALANT_CAPTURE_WORKTREE_ID`, with `SEALANT_WORKSPACE_SOURCE=capture`.
+- `worktreeId` is optional. A standby executor — launched ahead of any worktree so it can
+  materialise the project base and a dependency cache, then be bound to a worktree at claim — omits
+  it; `SEALANT_CAPTURE_WORKTREE_ID` stays unset and the daemon takes the worktree from the channel's
+  plan answer.
+- No mount allowlist applies. On Kubernetes the workspace root is an `emptyDir`; on Cloudflare the
+  sandbox is kept alive while the lease is live and a stop sends SIGTERM so the daemon can flush.
+- **No restart in place**: the credential is discarded once the launch settles, so `restart()` is
+  refused; create a replacement workspace with a fresh token.
+
 ## Dotfiles and shell
 
 Bring your own environment: a login shell and dotfiles applied before the workspace accepts work.
@@ -256,7 +289,7 @@ with readable failures:
   with `baseImage`.
 - **Node.js + npm** at or above the harness CLIs' floor (the CLIs are installed with
   `npm install -g` and run on the base's node).
-- **git**, for clone- and mount-sourced workspaces.
+- **git**, for clone-, mount- and capture-sourced workspaces.
 
 `packages` still works: names pass through **verbatim** (no portable-name resolution) to the base's
 own package manager — `apt`, `apk`, `dnf`, or `pacman`, autodetected — and the build fails with a

package/dist/effect/api-client.d.ts

@@ -1128,6 +1128,7 @@ declare const buildControlPlaneClient: (config: SealantInternalConfig) => Effect
                 readonly secretEnv?: {
                     readonly [x: string]: string;
                 } | undefined;
+                readonly captureToken?: string | undefined;
                 readonly ttlSeconds?: number | undefined;
             };
             readonly responseMode?: Mode;
@@ -1189,6 +1190,27 @@ declare const buildControlPlaneClient: (config: SealantInternalConfig) => Effect
             readonly workspaceId: string;
             readonly expiresAt: string | null;
         }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError), [Mode] extends ["response-only"] ? never : never>;
+        readonly flushWorkspaceCapture: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
+            readonly params: {
+                readonly workspaceId: string;
+            };
+            readonly payload: {
+                readonly ownerUserId: string;
+            };
+            readonly responseMode?: Mode;
+        }) => Effect.Effect<HttpApiClient.Client.Response<{
+            readonly epoch: number;
+            readonly worktreeId: string;
+            readonly headN?: number | undefined;
+            readonly pending: number;
+            readonly stagedBytes: number;
+            readonly uploadedObjects: number;
+            readonly uploadedBytes: number;
+            readonly registered: number;
+            readonly fenced: boolean;
+            readonly paused: boolean;
+            readonly lastSnapUnixMs?: number | undefined;
+        }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceConflictError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError), [Mode] extends ["response-only"] ? never : never>;
         readonly getWorkspace: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
             readonly params: {
                 readonly workspaceId: string;
@@ -1206,7 +1228,7 @@ declare const buildControlPlaneClient: (config: SealantInternalConfig) => Effect
             readonly repository?: string | undefined;
             readonly tag?: string | undefined;
             readonly runtime?: {
-                readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s";
+                readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s" | "microvm";
                 readonly resourceId: string;
                 readonly reference: string;
                 readonly status: "failed" | "pending" | "ready" | "running" | "stopped";
@@ -1241,7 +1263,7 @@ declare const buildControlPlaneClient: (config: SealantInternalConfig) => Effect
             readonly workspaceId: string;
             readonly attemptId: string;
             readonly runtime: {
-                readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s";
+                readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s" | "microvm";
                 readonly resourceId: string;
                 readonly reference: string;
                 readonly status: "failed" | "pending" | "ready" | "running" | "stopped";
@@ -1264,7 +1286,7 @@ declare const buildControlPlaneClient: (config: SealantInternalConfig) => Effect
                 readonly triggerType: "api" | "manual" | "retry" | "schedule";
                 readonly triggerRef?: string | undefined;
                 readonly runtime?: {
-                    readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s";
+                    readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s" | "microvm";
                     readonly resourceId: string;
                     readonly reference: string;
                     readonly status: "failed" | "pending" | "ready" | "running" | "stopped";
@@ -1325,7 +1347,7 @@ declare const buildControlPlaneClient: (config: SealantInternalConfig) => Effect
                 readonly repository?: string | undefined;
                 readonly tag?: string | undefined;
                 readonly runtime?: {
-                    readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s";
+                    readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s" | "microvm";
                     readonly resourceId: string;
                     readonly reference: string;
                     readonly status: "failed" | "pending" | "ready" | "running" | "stopped";
@@ -1360,6 +1382,26 @@ declare const buildControlPlaneClient: (config: SealantInternalConfig) => Effect
             readonly name: string;
             readonly updatedAt: string;
         }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError), [Mode] extends ["response-only"] ? never : never>;
+        readonly replanWorkspaceCapture: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
+            readonly params: {
+                readonly workspaceId: string;
+            };
+            readonly payload: {
+                readonly ownerUserId: string;
+            };
+            readonly responseMode?: Mode;
+        }) => Effect.Effect<HttpApiClient.Client.Response<{
+            readonly worktreeId: string;
+            readonly epoch: number;
+            readonly headN?: number | undefined;
+            readonly headCaptureId?: string | undefined;
+            readonly filesWritten: number;
+            readonly bytesWritten: number;
+            readonly filesSkipped: number;
+            readonly bytesSkipped: number;
+            readonly removed: number;
+            readonly unchanged: boolean;
+        }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceConflictError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError), [Mode] extends ["response-only"] ? never : never>;
         readonly restartWorkspace: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
             readonly params: {
                 readonly workspaceId: string;
@@ -2514,6 +2556,7 @@ declare const SealantApiClient_base: Context.ServiceClass<SealantApiClient, "@se
                 readonly secretEnv?: {
                     readonly [x: string]: string;
                 } | undefined;
+                readonly captureToken?: string | undefined;
                 readonly ttlSeconds?: number | undefined;
             };
             readonly responseMode?: Mode;
@@ -2575,6 +2618,27 @@ declare const SealantApiClient_base: Context.ServiceClass<SealantApiClient, "@se
             readonly workspaceId: string;
             readonly expiresAt: string | null;
         }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError), [Mode] extends ["response-only"] ? never : never>;
+        readonly flushWorkspaceCapture: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
+            readonly params: {
+                readonly workspaceId: string;
+            };
+            readonly payload: {
+                readonly ownerUserId: string;
+            };
+            readonly responseMode?: Mode;
+        }) => Effect.Effect<HttpApiClient.Client.Response<{
+            readonly epoch: number;
+            readonly worktreeId: string;
+            readonly headN?: number | undefined;
+            readonly pending: number;
+            readonly stagedBytes: number;
+            readonly uploadedObjects: number;
+            readonly uploadedBytes: number;
+            readonly registered: number;
+            readonly fenced: boolean;
+            readonly paused: boolean;
+            readonly lastSnapUnixMs?: number | undefined;
+        }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceConflictError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError), [Mode] extends ["response-only"] ? never : never>;
         readonly getWorkspace: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
             readonly params: {
                 readonly workspaceId: string;
@@ -2592,7 +2656,7 @@ declare const SealantApiClient_base: Context.ServiceClass<SealantApiClient, "@se
             readonly repository?: string | undefined;
             readonly tag?: string | undefined;
             readonly runtime?: {
-                readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s";
+                readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s" | "microvm";
                 readonly resourceId: string;
                 readonly reference: string;
                 readonly status: "failed" | "pending" | "ready" | "running" | "stopped";
@@ -2627,7 +2691,7 @@ declare const SealantApiClient_base: Context.ServiceClass<SealantApiClient, "@se
             readonly workspaceId: string;
             readonly attemptId: string;
             readonly runtime: {
-                readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s";
+                readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s" | "microvm";
                 readonly resourceId: string;
                 readonly reference: string;
                 readonly status: "failed" | "pending" | "ready" | "running" | "stopped";
@@ -2650,7 +2714,7 @@ declare const SealantApiClient_base: Context.ServiceClass<SealantApiClient, "@se
                 readonly triggerType: "api" | "manual" | "retry" | "schedule";
                 readonly triggerRef?: string | undefined;
                 readonly runtime?: {
-                    readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s";
+                    readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s" | "microvm";
                     readonly resourceId: string;
                     readonly reference: string;
                     readonly status: "failed" | "pending" | "ready" | "running" | "stopped";
@@ -2711,7 +2775,7 @@ declare const SealantApiClient_base: Context.ServiceClass<SealantApiClient, "@se
                 readonly repository?: string | undefined;
                 readonly tag?: string | undefined;
                 readonly runtime?: {
-                    readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s";
+                    readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s" | "microvm";
                     readonly resourceId: string;
                     readonly reference: string;
                     readonly status: "failed" | "pending" | "ready" | "running" | "stopped";
@@ -2746,6 +2810,26 @@ declare const SealantApiClient_base: Context.ServiceClass<SealantApiClient, "@se
             readonly name: string;
             readonly updatedAt: string;
         }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError), [Mode] extends ["response-only"] ? never : never>;
+        readonly replanWorkspaceCapture: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
+            readonly params: {
+                readonly workspaceId: string;
+            };
+            readonly payload: {
+                readonly ownerUserId: string;
+            };
+            readonly responseMode?: Mode;
+        }) => Effect.Effect<HttpApiClient.Client.Response<{
+            readonly worktreeId: string;
+            readonly epoch: number;
+            readonly headN?: number | undefined;
+            readonly headCaptureId?: string | undefined;
+            readonly filesWritten: number;
+            readonly bytesWritten: number;
+            readonly filesSkipped: number;
+            readonly bytesSkipped: number;
+            readonly removed: number;
+            readonly unchanged: boolean;
+        }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceConflictError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError), [Mode] extends ["response-only"] ? never : never>;
         readonly restartWorkspace: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
             readonly params: {
                 readonly workspaceId: string;

package/dist/effect/operations.d.ts

@@ -28,6 +28,7 @@ export declare const createWorkspaceOp: (payload: {
     readonly secretEnv?: {
         readonly [x: string]: string;
     } | undefined;
+    readonly captureToken?: string | undefined;
     readonly ttlSeconds?: number | undefined;
 }, idempotencyKey?: string | undefined) => Effect.Effect<{
     readonly workspaceId: string;
@@ -46,7 +47,7 @@ export declare const getWorkspaceOp: (workspaceId: string, ownerUserId?: string
     readonly repository?: string | undefined;
     readonly tag?: string | undefined;
     readonly runtime?: {
-        readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s";
+        readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s" | "microvm";
         readonly resourceId: string;
         readonly reference: string;
         readonly status: "failed" | "pending" | "ready" | "running" | "stopped";
@@ -82,7 +83,7 @@ export declare const listWorkspacesOp: (query: {
         readonly repository?: string | undefined;
         readonly tag?: string | undefined;
         readonly runtime?: {
-            readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s";
+            readonly adapter: "cloudflare" | "docker" | "k3s" | "k8s" | "microvm";
             readonly resourceId: string;
             readonly reference: string;
             readonly status: "failed" | "pending" | "ready" | "running" | "stopped";
@@ -145,6 +146,35 @@ export declare const bindWorkspaceOp: (workspaceId: string, payload: {
         readonly subpath: string;
     }[];
 }, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceConflictError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError, SealantApiClient>;
+export declare const flushWorkspaceCaptureOp: (workspaceId: string, payload: {
+    readonly ownerUserId: string;
+}) => Effect.Effect<{
+    readonly epoch: number;
+    readonly worktreeId: string;
+    readonly headN?: number | undefined;
+    readonly pending: number;
+    readonly stagedBytes: number;
+    readonly uploadedObjects: number;
+    readonly uploadedBytes: number;
+    readonly registered: number;
+    readonly fenced: boolean;
+    readonly paused: boolean;
+    readonly lastSnapUnixMs?: number | undefined;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceConflictError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError, SealantApiClient>;
+export declare const replanWorkspaceCaptureOp: (workspaceId: string, payload: {
+    readonly ownerUserId: string;
+}) => Effect.Effect<{
+    readonly worktreeId: string;
+    readonly epoch: number;
+    readonly headN?: number | undefined;
+    readonly headCaptureId?: string | undefined;
+    readonly filesWritten: number;
+    readonly bytesWritten: number;
+    readonly filesSkipped: number;
+    readonly bytesSkipped: number;
+    readonly removed: number;
+    readonly unchanged: boolean;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceConflictError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError, SealantApiClient>;
 export declare const stopWorkspaceOp: (workspaceId: string, payload: {
     readonly ownerUserId: string;
 }) => Effect.Effect<{

package/dist/effect/operations.js

@@ -12,6 +12,8 @@ export const getWorkspaceOp = (workspaceId, ownerUserId) => Effect.flatMap(Seala
 export const listWorkspacesOp = (query) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.listWorkspaces({ query }));
 export const execWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.execWorkspace({ params: { workspaceId }, payload }));
 export const bindWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.bindWorkspace({ params: { workspaceId }, payload }));
+export const flushWorkspaceCaptureOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.flushWorkspaceCapture({ params: { workspaceId }, payload }));
+export const replanWorkspaceCaptureOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.replanWorkspaceCapture({ params: { workspaceId }, payload }));
 export const stopWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.stopWorkspace({ params: { workspaceId }, payload }));
 export const restartWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.restartWorkspace({ params: { workspaceId }, payload }));
 export const expireWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.expireWorkspace({ params: { workspaceId }, payload }));

package/dist/facade/workspace.js

@@ -1,5 +1,5 @@
 import { execWorkspace } from "../effect/exec-workspace.js";
-import { bindWorkspaceOp, createSessionOp, expireWorkspaceOp, getSessionOp, getWorkspaceOp, listSessionsOp, restartWorkspaceOp, stopWorkspaceOp, } from "../effect/operations.js";
+import { bindWorkspaceOp, flushWorkspaceCaptureOp, createSessionOp, expireWorkspaceOp, getSessionOp, getWorkspaceOp, listSessionsOp, replanWorkspaceCaptureOp, restartWorkspaceOp, stopWorkspaceOp, } from "../effect/operations.js";
 import { SealantError, SealantNotImplementedError } from "../errors.js";
 import { parseTtlSeconds } from "../internal/duration.js";
 import { makeInteractiveSession } from "./session.js";
@@ -128,6 +128,39 @@ export const makeWorkspace = (ctx, init) => {
             }));
             return result.binds.map((bind) => ({ mountPath: bind.mountPath, subpath: bind.subpath }));
         },
+        capture: {
+            flush: async () => {
+                const status = await ctx.runtime.run(flushWorkspaceCaptureOp(init.id, { ownerUserId: ctx.config.hostLocal.ownerUserId }));
+                return {
+                    epoch: status.epoch,
+                    worktreeId: status.worktreeId,
+                    ...(status.headN === undefined ? {} : { headN: status.headN }),
+                    pending: status.pending,
+                    stagedBytes: status.stagedBytes,
+                    uploadedObjects: status.uploadedObjects,
+                    uploadedBytes: status.uploadedBytes,
+                    registered: status.registered,
+                    fenced: status.fenced,
+                    paused: status.paused,
+                    ...(status.lastSnapUnixMs === undefined ? {} : { lastSnapUnixMs: status.lastSnapUnixMs }),
+                };
+            },
+            replan: async () => {
+                const result = await ctx.runtime.run(replanWorkspaceCaptureOp(init.id, { ownerUserId: ctx.config.hostLocal.ownerUserId }));
+                return {
+                    worktreeId: result.worktreeId,
+                    epoch: result.epoch,
+                    ...(result.headN === undefined ? {} : { headN: result.headN }),
+                    ...(result.headCaptureId === undefined ? {} : { headCaptureId: result.headCaptureId }),
+                    filesWritten: result.filesWritten,
+                    bytesWritten: result.bytesWritten,
+                    filesSkipped: result.filesSkipped,
+                    bytesSkipped: result.bytesSkipped,
+                    removed: result.removed,
+                    unchanged: result.unchanged,
+                };
+            },
+        },
         // 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).
         events: () => {

package/dist/internal/blueprint.d.ts

@@ -29,6 +29,7 @@ export declare const buildCreateWorkspaceRequest: (options: CreateOptions, confi
         readonly secretEnv?: {
             readonly [x: string]: string;
         } | undefined;
+        readonly captureToken?: string | undefined;
         readonly ttlSeconds?: number | undefined;
     };
 };

package/dist/internal/blueprint.js

@@ -38,10 +38,13 @@ export const buildCreateWorkspaceRequest = (options, config) => {
         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.", {
+        throw new SealantError("`ref` applies only to `repository` sources, not mounts or captures.", {
             code: "invalid_create_options",
         });
     }
+    if (options.source?.kind === "capture" && options.source.token.trim().length === 0) {
+        throw new SealantError("A capture source needs a non-empty `token`: the session credential the daemon registers with.", { code: "invalid_create_options" });
+    }
     if (options.os !== undefined && options.baseImage !== undefined) {
         throw new SealantError("workspaces.create accepts either `os` (a managed OS family) or `baseImage` (a custom base image reference), not both.", { code: "invalid_create_options" });
     }
@@ -57,14 +60,18 @@ export const buildCreateWorkspaceRequest = (options, config) => {
         throw new SealantError("`dotfiles` requires a `repository`, at least one entry in `archives`, or both.", { code: "invalid_create_options" });
     }
     const sourceName = options.repository ??
-        (options.source?.kind === "standby" ? options.source.rootPath : options.source?.path) ??
+        (options.source?.kind === "standby"
+            ? options.source.rootPath
+            : options.source?.kind === "capture"
+                ? options.source.worktreeId
+                : options.source?.path) ??
         "workspace";
     const tail = sourceName
         .split("/")
         .filter((s) => s.length > 0)
         .pop() ?? sourceName;
     const credentials = mapWorkspaceCredentials(options.credentials);
-    const linkedWorktreeMount = options.source === undefined || options.source.kind === "standby"
+    const linkedWorktreeMount = options.source === undefined || options.source.kind !== "mount"
         ? null
         : discoverLinkedWorktreeMetadataMount(options.source.path);
     const explicitMounts = options.mounts ?? [];
@@ -150,7 +157,19 @@ export const buildCreateWorkspaceRequest = (options, config) => {
                 }
                 : options.source?.kind === "standby"
                     ? { kind: "standby", rootPath: options.source.rootPath }
-                    : { kind: "mount", hostPath: options.source?.path },
+                    : options.source?.kind === "capture"
+                        ? // The token is NOT here: it rides the request top level as `captureToken`.
+                            {
+                                kind: "capture",
+                                endpoint: options.source.endpoint,
+                                ...(options.source.worktreeId === undefined
+                                    ? {}
+                                    : { worktreeId: options.source.worktreeId }),
+                                ...(options.source.platform === undefined
+                                    ? {}
+                                    : { platform: options.source.platform }),
+                            }
+                        : { kind: "mount", hostPath: options.source?.path },
             ...(dotfilesRepository === undefined
                 ? {}
                 : {
@@ -218,6 +237,9 @@ export const buildCreateWorkspaceRequest = (options, config) => {
             ...(options.ttl === undefined ? {} : { ttlSeconds: parseTtlSeconds(options.ttl) }),
             spec,
             ...(secretEnv === undefined ? {} : { secretEnv }),
+            // The capture credential is the one secret outside `secretEnv`: sealed and delivered the
+            // same way by the control plane, under its platform-owned name.
+            ...(options.source?.kind === "capture" ? { captureToken: options.source.token } : {}),
         },
     };
 };

package/dist/types.d.ts

@@ -131,6 +131,30 @@ export interface WorkspaceStandbySource {
     /** Absolute, normalized deployment root (no `..` segments); container-visible in volume mode. */
     readonly rootPath: string;
 }
+/**
+ * A CAPTURE workspace (sealantd ADR-0015): the platform mounts nothing and clones nothing. The
+ * workspace daemon registers with the session channel at `endpoint` using `token`, fetches the
+ * worktree's head plan, materialises it onto the executor's own disk, claims the lease and ships
+ * captures back over the channel — so the same session can run on a host that has no path to
+ * offer (Cloudflare, a MicroVM) and outlive any one executor. `token` is delivered once, through
+ * the secret env channel (`SEALANT_CAPTURE_TOKEN`), never into the blueprint or any read; a
+ * capture workspace therefore cannot be restarted in place — create a replacement with a fresh
+ * token. `platform` is a hint recorded for placement bookkeeping. No allowlist applies.
+ */
+export interface WorkspaceCaptureSource {
+    readonly kind: "capture";
+    /** The session channel URL the daemon registers with. */
+    readonly endpoint: string;
+    /**
+     * The worktree whose captures this workspace materialises and extends. Omit for a standby
+     * executor launched before its worktree exists: the daemon then takes the worktree from the
+     * channel's plan answer, which names the one it is bound to at claim.
+     */
+    readonly worktreeId?: string;
+    /** The session-scoped channel credential. Secret: sealed for the launch, then discarded. */
+    readonly token: string;
+    readonly platform?: string;
+}
 /**
  * An ADDITIONAL caller-owned host directory bind-mounted beside the primary source — sibling
  * repositories, reference clones, scratch material the workspace should see without adopting.
@@ -164,6 +188,63 @@ export interface WorkspaceBindOptions {
     /** Relative path under the mount's root; an empty string unbinds. */
     readonly subpath: string;
 }
+/** The daemon's capture status after `workspace.capture.flush()` (sealantd ADR-0015). */
+export interface WorkspaceCaptureStatus {
+    /** The lease epoch the captures were shipped under. */
+    readonly epoch: number;
+    readonly worktreeId: string;
+    /** The head sequence registered on the session channel, once anything has been. */
+    readonly headN?: number;
+    /** Captures still staged and not yet shipped; zero after a complete flush. */
+    readonly pending: number;
+    readonly stagedBytes: number;
+    readonly uploadedObjects: number;
+    readonly uploadedBytes: number;
+    readonly registered: number;
+    /** The channel fenced this executor: nothing it captures from now on is accepted. */
+    readonly fenced: boolean;
+    /** The harness is paused (lease lost); see the daemon's lease semantics. */
+    readonly paused: boolean;
+    readonly lastSnapUnixMs?: number;
+}
+/** The daemon's answer to `workspace.capture.replan()` (sealantd 0.15 `capture.replan`). */
+export interface WorkspaceCaptureReplanned {
+    /** The worktree the session channel's plan answered; the executor captures under it from now on. */
+    readonly worktreeId: string;
+    /** The lease epoch the plan answered. */
+    readonly epoch: number;
+    /** The head sequence the plan carried, once the worktree has one. */
+    readonly headN?: number;
+    /** The head capture the plan carried, once the worktree has one. */
+    readonly headCaptureId?: string;
+    /** What the delta materialise wrote: files whose bytes, mode or links differed from disk. */
+    readonly filesWritten: number;
+    readonly bytesWritten: number;
+    /** What it left alone: files already matching the plan on disk. */
+    readonly filesSkipped: number;
+    readonly bytesSkipped: number;
+    /** Files, symlinks and emptied directories the plan dropped, swept from the tree. */
+    readonly removed: number;
+    /** The plan named the worktree and epoch already in force; nothing moved. */
+    readonly unchanged: boolean;
+}
+/** Capture operations of a capture-sourced workspace. */
+export interface WorkspaceCapture {
+    /**
+     * Final capture, then ship and register everything staged. Synchronous: resolves once the
+     * daemon has flushed (bounded by its grace window). Gate an executor's retirement on
+     * `pending === 0 && !fenced`. Refused on workspaces that are not capture-sourced.
+     */
+    flush(): Promise<WorkspaceCaptureStatus>;
+    /**
+     * Re-plan: the daemon asks the session channel for its plan again with no worktree named,
+     * delta-materialises the answer over what is on disk, and captures under the answered worktree
+     * and epoch from then on (the fence lifts, foreign queue entries drop). The claim hook for a
+     * standby executor. Synchronous and idempotent (`unchanged: true`). Refused on workspaces that
+     * are not capture-sourced.
+     */
+    replan(): Promise<WorkspaceCaptureReplanned>;
+}
 /** How a dotfiles tree is applied inside the workspace. */
 export type WorkspaceDotfilesManager = "auto" | "chezmoi" | "stow" | "copy";
 /**
@@ -231,8 +312,11 @@ export interface CreateOptions {
      * Exactly one of `repository` or `source` must be provided.
      */
     readonly repository?: string;
-    /** Alternative to `repository`: source the workspace from a caller-owned mount, or a standby root. */
-    readonly source?: WorkspaceMountSource | WorkspaceStandbySource;
+    /**
+     * Alternative to `repository`: source the workspace from a caller-owned mount, a standby root,
+     * or a capture channel (see each source type).
+     */
+    readonly source?: WorkspaceMountSource | WorkspaceStandbySource | WorkspaceCaptureSource;
     /** Additional read-only-by-default mounts beside the primary source (see `WorkspaceExtraMount`). */
     readonly mounts?: readonly WorkspaceExtraMount[];
     /** The harness to run inside the workspace. */
@@ -378,6 +462,8 @@ export interface Workspace {
      * binding, which each relaunch re-applies.
      */
     bind(options: WorkspaceBindOptions): Promise<readonly WorkspaceBind[]>;
+    /** Capture flush for capture-sourced workspaces (sealantd ADR-0015). */
+    readonly capture: WorkspaceCapture;
     /** Interactive PTY sessions: open new ones, reattach to existing ones by id. */
     readonly sessions: WorkspaceSessions;
     /** Lifecycle events as an async stream. */

package/package.json

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