@sealant/sdk 0.15.0 → 0.17.0

package/README.md

@@ -105,8 +105,9 @@ and injects them at launch.
 
 ## Workspace tools and services
 
-Choose a supported operating-system family, request portable package names, and opt into services
-that need runtime support rather than a package install:
+Choose a supported operating-system family — `fedora` (the default), `arch`, `nix`, or `ubuntu` —
+request portable package names, and opt into services that need runtime support rather than a
+package install:
 
 ```ts
 const workspace = await sealant.workspaces.create({
@@ -123,6 +124,36 @@ const workspace = await sealant.workspaces.create({
 rootless daemon at launch. The workspace receives `DOCKER_HOST`; Sealant never mounts the host
 Docker socket. GitHub credentials provide both `GH_TOKEN` and `GITHUB_TOKEN` to the workspace.
 
+## Custom base images
+
+Instead of a managed OS family, a workspace image can be built from any image reference you already
+trust:
+
+```ts
+const workspace = await sealant.workspaces.create({
+  repository: "github.com/acme/billing-service",
+  harness: codex(),
+  baseImage: "node:22-bookworm",
+});
+```
+
+Distro package installs are skipped entirely — the build overlays only the `sealantd` supervisor
+(PID 1), the harness CLIs (installed with `npm`), and a fully static `socat` (the control-socket
+relay), all copied in as static binaries. This is the **base-image contract**, checked at build time
+with readable failures:
+
+- **Any Linux base, `amd64`/`arm64`**, with a **POSIX shell** at `/bin/sh`. Shells beyond that are
+  not assumed: the workspace login shell is `/bin/sh`, and `defaultShell` selection is not supported
+  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.
+
+`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
+readable error when the base has none. Dotfiles are not supported with `baseImage`. `baseImage` and
+`os` are mutually exclusive.
+
 ## Inference on connected accounts
 
 Run short, tool-calling inference loops on the caller's own subscription — server-side, through the

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

@@ -294,7 +294,7 @@ declare const buildControlPlaneClient: (config: SealantInternalConfig) => Effect
         readonly resolvePackage: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
             readonly query: {
                 readonly query: string;
-                readonly targetOs?: "arch" | "fedora" | "nix" | undefined;
+                readonly targetOs?: "arch" | "fedora" | "nix" | "ubuntu" | undefined;
             };
             readonly responseMode?: Mode;
         }) => Effect.Effect<HttpApiClient.Client.Response<{
@@ -329,6 +329,14 @@ declare const buildControlPlaneClient: (config: SealantInternalConfig) => Effect
                     readonly version?: string | undefined;
                     readonly status?: string | undefined;
                 };
+                readonly ubuntu: {
+                    readonly supported: boolean;
+                    readonly repo?: string | undefined;
+                    readonly packageName?: string | undefined;
+                    readonly projectName?: string | undefined;
+                    readonly version?: string | undefined;
+                    readonly status?: string | undefined;
+                };
             };
             readonly alternatives: readonly {
                 readonly projectName: string;
@@ -1604,7 +1612,7 @@ declare const SealantApiClient_base: Context.ServiceClass<SealantApiClient, "@se
         readonly resolvePackage: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
             readonly query: {
                 readonly query: string;
-                readonly targetOs?: "arch" | "fedora" | "nix" | undefined;
+                readonly targetOs?: "arch" | "fedora" | "nix" | "ubuntu" | undefined;
             };
             readonly responseMode?: Mode;
         }) => Effect.Effect<HttpApiClient.Client.Response<{
@@ -1639,6 +1647,14 @@ declare const SealantApiClient_base: Context.ServiceClass<SealantApiClient, "@se
                     readonly version?: string | undefined;
                     readonly status?: string | undefined;
                 };
+                readonly ubuntu: {
+                    readonly supported: boolean;
+                    readonly repo?: string | undefined;
+                    readonly packageName?: string | undefined;
+                    readonly projectName?: string | undefined;
+                    readonly version?: string | undefined;
+                    readonly status?: string | undefined;
+                };
             };
             readonly alternatives: readonly {
                 readonly projectName: string;

package/dist/facade/workspace.js

@@ -210,6 +210,9 @@ const openForward = (ctx, workspaceId, port, options) => {
     if (options?.host !== undefined) {
         url.searchParams.set("host", options.host);
     }
+    if (options?.protocol === "udp") {
+        url.searchParams.set("protocol", "udp");
+    }
     if (config.apiKey === undefined) {
         url.searchParams.set("ownerUserId", config.hostLocal.ownerUserId);
     }

package/dist/internal/blueprint.js

@@ -38,6 +38,9 @@ export const buildCreateWorkspaceRequest = (options, config) => {
             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" });
+    }
     const sourceName = options.repository ?? options.source?.path ?? "workspace";
     const tail = sourceName
         .split("/")
@@ -95,7 +98,9 @@ export const buildCreateWorkspaceRequest = (options, config) => {
         harness: { id: options.harness.id },
         customization: { enableSealantd: true },
         target: {
-            os: { family: options.os ?? "fedora", mode: "prefer" },
+            os: options.baseImage !== undefined
+                ? { family: "custom", mode: "require", baseImage: options.baseImage }
+                : { family: options.os ?? "fedora", mode: "prefer" },
             runtime: { family: "docker", mode: "require" },
         },
         lifecycle: {

package/dist/types.d.ts

@@ -65,7 +65,8 @@ export interface WorkspaceEvent {
     readonly message?: string;
 }
 /** The supported workspace OS families (maps to the blueprint target). */
-export type WorkspaceOs = "fedora" | "arch" | "nix";
+/** Supported workspace image OS families. `fedora` is the default when `os` is omitted. */
+export type WorkspaceOs = "fedora" | "arch" | "nix" | "ubuntu";
 /**
  * Connected-account credentials to attach to a workspace at creation time, per provider — so the
  * harness inside the workspace authenticates as the caller's own Claude / Codex / GitHub identity
@@ -146,8 +147,17 @@ export interface CreateOptions {
     readonly ref?: string;
     /** Human-friendly name for the workspace. */
     readonly name?: string;
-    /** OS family for the workspace image. */
+    /** OS family for the workspace image. Mutually exclusive with `baseImage`. */
     readonly os?: WorkspaceOs;
+    /**
+     * Build the workspace image FROM this arbitrary OCI image reference instead of a managed OS
+     * family (e.g. `"node:22-bookworm"`). Distro package installs are skipped; the build overlays
+     * only the sealantd supervisor, the harness CLIs (npm), and a static socat relay. See "Custom
+     * base images" in the SDK README for the base-image contract. Mutually exclusive with `os`;
+     * `packages` install through the base's own package manager (apt/apk/dnf/pacman) and fail the
+     * build readable when it has none.
+     */
+    readonly baseImage?: string;
     /** Extra OS packages to install in the workspace. */
     readonly packages?: readonly string[];
     /** Runtime-managed services that need more than installing an OS package. */
@@ -221,7 +231,7 @@ export interface Workspace {
         readonly in?: string | null;
     }): Promise<void>;
     /**
-     * Open a raw TCP byte pipe INSIDE the workspace — the primitive for
+     * Open a raw TCP byte pipe (or a UDP datagram pipe) INSIDE the workspace — the primitive for
      * reaching a dev server or database the workspace runs. Protocol-agnostic:
      * nothing inspects or records the payload. One held WebSocket per forward;
      * rejects when nothing accepts the connection. The target host is a CLOSED
@@ -235,6 +245,13 @@ export interface Workspace {
 export interface WorkspaceForwardOptions {
     /** Target inside the workspace: its loopback (default) or the Docker sidecar. */
     readonly host?: "127.0.0.1" | "localhost" | "docker";
+    /**
+     * Forward transport. TCP (default) is a byte stream; `"udp"` opens a
+     * connected UDP socket where one frame on this pipe is exactly one
+     * datagram, both directions. UDP has no connection handshake: opening
+     * succeeds even when nothing listens yet — datagrams simply drop.
+     */
+    readonly protocol?: "tcp" | "udp";
 }
 /**
  * A live port forward — one WebSocket, held until `close()` or the remote

package/package.json

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