@sealant/sdk 0.16.0 → 0.18.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,61 @@ 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.
 
+## Dotfiles and shell
+
+Bring your own environment: a login shell and dotfiles applied before the workspace accepts work.
+
+```ts
+const workspace = await sealant.workspaces.create({
+  repository: "github.com/acme/billing-service",
+  harness: codex(),
+  shell: "zsh",
+  dotfiles: {
+    // A repo the platform clones and applies (chezmoi/stow layouts detected, else copied):
+    repository: { url: "github.com/acme/dotfiles" },
+    // And/or caller-resolved archives — a checkout cloned host-side with your own ssh identity,
+    // or a scanned selection of home files, sent as gzipped tars (max 4, ~4MB decoded each):
+    archives: [{ data: tarGzBase64, manager: "copy", bootstrap: false }],
+  },
+});
+```
+
+`shell` installs the shell package and switches the login shell, so `.zshrc`/`.fishrc` actually take
+effect. The `repository` applies first, then each archive in order, so local selections override
+repo files. A failing apply fails the launch loudly rather than handing the agent a half-prepared
+home. Managed OS families only — with `baseImage`, `dotfiles` and non-bash `shell` are rejected
+client-side with the platform's reasoning.
+
+## 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/internal/blueprint.js

@@ -38,6 +38,20 @@ 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" });
+    }
+    if (options.baseImage !== undefined && options.dotfiles !== undefined) {
+        throw new SealantError("`dotfiles` is not supported with `baseImage`: custom bases guarantee only a POSIX shell, so the dotfiles managers are not provisioned.", { code: "invalid_create_options" });
+    }
+    if (options.baseImage !== undefined && options.shell !== undefined && options.shell !== "bash") {
+        throw new SealantError("`shell` is not supported with `baseImage`: custom bases run /bin/sh and the login shell cannot be switched.", { code: "invalid_create_options" });
+    }
+    if (options.dotfiles !== undefined &&
+        options.dotfiles.repository === undefined &&
+        (options.dotfiles.archives === undefined || options.dotfiles.archives.length === 0)) {
+        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?.path ?? "workspace";
     const tail = sourceName
         .split("/")
@@ -69,6 +83,8 @@ export const buildCreateWorkspaceRequest = (options, config) => {
             ...(toolingPackages.length === 0 ? {} : { packages: toolingPackages }),
             ...(dockerService ? { services: { docker: { enabled: true } } } : {}),
         };
+    const dotfilesRepository = options.dotfiles?.repository;
+    const dotfilesArchives = options.dotfiles?.archives ?? [];
     const spec = {
         version: "1",
         sources: {
@@ -81,6 +97,21 @@ export const buildCreateWorkspaceRequest = (options, config) => {
                     ...(options.ref === undefined ? {} : { ref: options.ref }),
                 }
                 : { kind: "mount", hostPath: options.source?.path },
+            ...(dotfilesRepository === undefined
+                ? {}
+                : {
+                    inputs: [
+                        {
+                            id: "dotfiles",
+                            kind: "git",
+                            purpose: "dotfiles",
+                            provider: "generic",
+                            url: toGitUrl(dotfilesRepository.url),
+                            // Omitted ref = the remote's default branch — never assumed to be `main`.
+                            ...(dotfilesRepository.ref === undefined ? {} : { ref: dotfilesRepository.ref }),
+                        },
+                    ],
+                }),
             ...(mounts.length === 0
                 ? {}
                 : {
@@ -93,9 +124,39 @@ export const buildCreateWorkspaceRequest = (options, config) => {
                 }),
         },
         harness: { id: options.harness.id },
-        customization: { enableSealantd: true },
+        customization: {
+            enableSealantd: true,
+            ...(options.shell === undefined ? {} : { defaultShell: options.shell }),
+            // The repository path's knobs live at customization level; archives carry their own.
+            ...(dotfilesRepository?.manager === undefined
+                ? {}
+                : { dotfilesManager: dotfilesRepository.manager }),
+            ...(dotfilesRepository?.bootstrap === undefined
+                ? {}
+                : { dotfilesBootstrap: dotfilesRepository.bootstrap }),
+            ...(dotfilesRepository?.bootstrapCommand === undefined
+                ? {}
+                : { dotfilesBootstrapCommand: dotfilesRepository.bootstrapCommand }),
+        },
+        ...(dotfilesArchives.length === 0
+            ? {}
+            : {
+                runtime: {
+                    dotfilesArchives: dotfilesArchives.map((archive) => ({
+                        data: archive.data,
+                        ...(archive.manager === undefined ? {} : { manager: archive.manager }),
+                        ...(archive.target === undefined ? {} : { target: archive.target }),
+                        ...(archive.bootstrap === undefined ? {} : { bootstrap: archive.bootstrap }),
+                        ...(archive.bootstrapCommand === undefined
+                            ? {}
+                            : { bootstrapCommand: archive.bootstrapCommand }),
+                    })),
+                },
+            }),
         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
@@ -122,6 +123,53 @@ export interface WorkspaceExtraMount {
     /** Defaults to `true`. Pass `false` deliberately — writes to extra mounts are unrecorded. */
     readonly readOnly?: boolean;
 }
+/** How a dotfiles tree is applied inside the workspace. */
+export type WorkspaceDotfilesManager = "auto" | "chezmoi" | "stow" | "copy";
+/**
+ * A dotfiles repository the platform clones and applies before the workspace accepts work. Public
+ * or GitHub-App-reachable repos work as-is; for a repo only the caller's own ssh identity can
+ * reach, resolve it host-side and send the checkout as an archive instead (see
+ * `WorkspaceDotfilesArchive`).
+ */
+export interface WorkspaceDotfilesRepository {
+    /** Clone URL (or `"github.com/acme/dotfiles"` shorthand). */
+    readonly url: string;
+    /** Git ref. Omitted = the remote's default branch — never assumed to be `main`. */
+    readonly ref?: string;
+    /** Defaults to `"auto"`: chezmoi/stow layouts are detected, everything else is copied. */
+    readonly manager?: WorkspaceDotfilesManager;
+    /** Run the repo's bootstrap command after applying (skipped when absent). Defaults to true. */
+    readonly bootstrap?: boolean;
+    /** Bootstrap command, relative to the checkout. Defaults to `./install.sh`. */
+    readonly bootstrapCommand?: string;
+}
+/**
+ * A caller-resolved dotfiles tree: a gzipped tar the daemon extracts and applies at boot through
+ * the same manager dispatch as a cloned repo. This is the shape for dotfiles resolved host-side —
+ * a checkout cloned with the caller's own ssh identity, or a scanned selection of home files —
+ * so no URL or credential ever has to reach the workspace. Max 4 archives, ~4MB decoded each.
+ */
+export interface WorkspaceDotfilesArchive {
+    /** base64 of a `.tar.gz` whose contents apply relative to the target. */
+    readonly data: string;
+    /** Defaults to `"auto"`. Scanned home files usually want `"copy"`. */
+    readonly manager?: WorkspaceDotfilesManager;
+    /** Where the tree lands: `"home"` (default) or `"config"` (`$HOME/.config`, copy manager only). */
+    readonly target?: "home" | "config";
+    /** Run `./install.sh` (or `bootstrapCommand`) after applying when present. Defaults to true. */
+    readonly bootstrap?: boolean;
+    readonly bootstrapCommand?: string;
+}
+/**
+ * Dotfiles for the workspace: a repository the platform clones, caller-resolved archives, or both
+ * (the repository applies first, archives after — in order — so local selections override repo
+ * files). Applied before the workspace reports ready; a failing apply fails the launch loudly.
+ * Not supported with `baseImage` (custom bases guarantee only a POSIX shell).
+ */
+export interface WorkspaceDotfilesOptions {
+    readonly repository?: WorkspaceDotfilesRepository;
+    readonly archives?: readonly WorkspaceDotfilesArchive[];
+}
 /** Runtime-managed services attached only to this workspace. */
 export interface WorkspaceServicesOptions {
     /**
@@ -146,10 +194,27 @@ 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[];
+    /**
+     * Login shell for the workspace user (`"bash"` default). The shell package is installed and the
+     * login shell switched, so dotfiles like `.zshrc` actually take effect. Managed OS families
+     * only — custom bases guarantee just a POSIX shell.
+     */
+    readonly shell?: "bash" | "zsh" | "fish";
+    /** Dotfiles applied before the workspace accepts work (see `WorkspaceDotfilesOptions`). */
+    readonly dotfiles?: WorkspaceDotfilesOptions;
     /** Runtime-managed services that need more than installing an OS package. */
     readonly services?: WorkspaceServicesOptions;
     /** When true (default), resolve only once the workspace runtime is live. */

package/package.json

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