@sealant/sdk 0.0.0

package/dist/facade/record.js

@@ -0,0 +1,222 @@
+import { getRunLossOp, getRunOp, getRunScrollbackOp, getRunTimelineOp, } from "../effect/operations.js";
+import { SealantNotImplementedError } from "../errors.js";
+// Live `stream()` is poll-backed for now: it tails the timeline endpoint until the run is terminal.
+// The transport swaps to SSE over Postgres LISTEN/NOTIFY in Stage 5 behind this same signature.
+const TERMINAL_RUN_STATUSES = new Set(["completed", "failed", "cancelled"]);
+const STREAM_POLL_INTERVAL_MS = 500;
+const STREAM_TIMEOUT_MS = 30 * 60 * 1_000;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const toTimelineEntry = (wire) => ({
+    sequence: BigInt(wire.sequence),
+    kind: wire.kind,
+    occurredAt: wire.occurredAt,
+    data: { summary: wire.summary, ...(wire.ref === undefined ? {} : { ref: wire.ref }) },
+});
+const toLossReport = (wire) => ({
+    complete: !wire.earlyClose && wire.droppedEventCount === "0" && wire.sequenceGapCount === 0,
+    // Pass boundaries through only when present — do not fabricate a {0, 0} span.
+    spans: wire.spans.map((span) => ({
+        ...(span.fromSequence === undefined ? {} : { fromSequence: BigInt(span.fromSequence) }),
+        ...(span.toSequence === undefined ? {} : { toSequence: BigInt(span.toSequence) }),
+    })),
+});
+// ---------------------------------------------------------------------------------------------
+// Transcript reconstruction — turn the raw timeline into the terminal commands a human cares about.
+// ---------------------------------------------------------------------------------------------
+const STDERR_STREAM = 3; // StreamKind.STDERR (stdout is 2)
+const isRecord = (value) => typeof value === "object" && value !== null;
+const SHELL_SAFE = /^[A-Za-z0-9_/.:=@%+-]+$/;
+const quoteArg = (arg) => arg.length > 0 && SHELL_SAFE.test(arg) ? arg : `"${arg.replace(/(["\\$`])/g, "\\$1")}"`;
+const formatCommandLine = (executable, args) => [executable, ...args.map(quoteArg)].join(" ");
+const humanBytes = (n) => {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+};
+const humanDuration = (ms) => ms < 1000 ? `${ms} ms` : `${(ms / 1000).toFixed(ms < 10_000 ? 2 : 1)} s`;
+/**
+ * Folds the timeline into the ordered list of terminal commands. Process boundaries are
+ * `processStarted`/`processExited`; `ioChunk` byte counts accrue to the current command. Daemon noise
+ * (`runtimeStateChanged`, and the boot foreground we never `processStarted`) is skipped naturally.
+ */
+export const reconstructCommands = (entries) => {
+    const commands = [];
+    let current;
+    const flush = (exit) => {
+        if (current === undefined) {
+            return;
+        }
+        commands.push({
+            executable: current.executable,
+            args: current.args,
+            command: formatCommandLine(current.executable, current.args),
+            ...(current.cwd === undefined ? {} : { cwd: current.cwd }),
+            ...(exit?.exitCode === undefined ? {} : { exitCode: exit.exitCode }),
+            ...(exit?.signal === undefined ? {} : { signal: exit.signal }),
+            ...(exit?.durationMs === undefined ? {} : { durationMs: exit.durationMs }),
+            stdoutBytes: current.stdoutBytes,
+            stderrBytes: current.stderrBytes,
+        });
+        current = undefined;
+    };
+    for (const entry of entries) {
+        const ref = isRecord(entry.ref) ? entry.ref : {};
+        if (entry.kind === "processStarted") {
+            flush();
+            const args = ref["args"];
+            current = {
+                executable: typeof ref["executable"] === "string" ? ref["executable"] : "?",
+                args: Array.isArray(args) ? args.map((a) => String(a)) : [],
+                ...(typeof ref["cwd"] === "string" ? { cwd: ref["cwd"] } : {}),
+                stdoutBytes: 0,
+                stderrBytes: 0,
+            };
+        }
+        else if (entry.kind === "ioChunk" && current !== undefined) {
+            const bytes = typeof ref["byteCount"] === "string" ? Number(ref["byteCount"]) : 0;
+            if (ref["stream"] === STDERR_STREAM) {
+                current.stderrBytes += bytes;
+            }
+            else {
+                current.stdoutBytes += bytes;
+            }
+        }
+        else if (entry.kind === "processExited") {
+            flush({
+                ...(typeof ref["exitCode"] === "number" ? { exitCode: ref["exitCode"] } : {}),
+                ...(typeof ref["signal"] === "number" ? { signal: ref["signal"] } : {}),
+                ...(typeof ref["durationMicros"] === "string"
+                    ? { durationMs: Math.round(Number(ref["durationMicros"]) / 1000) }
+                    : {}),
+            });
+        }
+    }
+    flush();
+    return commands;
+};
+export const renderTranscript = (commands) => {
+    if (commands.length === 0) {
+        return "(no commands recorded)\n";
+    }
+    const blocks = commands.map((command) => {
+        const io = [];
+        if (command.stdoutBytes > 0) {
+            io.push(`stdout ${humanBytes(command.stdoutBytes)}`);
+        }
+        if (command.stderrBytes > 0) {
+            io.push(`stderr ${humanBytes(command.stderrBytes)}`);
+        }
+        const outcome = command.signal !== undefined
+            ? `terminated (signal ${command.signal})`
+            : command.exitCode === 0
+                ? "completed (exit 0)"
+                : command.exitCode !== undefined
+                    ? `failed (exit ${command.exitCode})`
+                    : "ended";
+        const duration = command.durationMs === undefined ? "" : ` · ${humanDuration(command.durationMs)}`;
+        return `  $ ${command.command}\n      ↳ ${[...io, outcome].join(" · ")}${duration}`;
+    });
+    return `${blocks.join("\n\n")}\n`;
+};
+export const makeRunRecord = (ctx, runId) => {
+    const fetchTimeline = (from) => ctx.runtime.run(getRunTimelineOp(runId, from === undefined ? {} : { fromSequence: from.toString() }));
+    return {
+        runId,
+        replay: async (options) => {
+            const wire = await fetchTimeline();
+            const entries = wire.map(toTimelineEntry);
+            if (options?.onEntry !== undefined) {
+                for (const entry of entries) {
+                    options.onEntry(entry);
+                }
+            }
+            const replay = {
+                entries,
+                at: (sequence) => {
+                    let found;
+                    for (const entry of entries) {
+                        if (entry.sequence <= sequence) {
+                            found = entry;
+                        }
+                        else {
+                            break;
+                        }
+                    }
+                    return found;
+                },
+            };
+            return replay;
+        },
+        commands: async () => reconstructCommands(await fetchTimeline()),
+        transcript: async () => renderTranscript(reconstructCommands(await fetchTimeline())),
+        stream: (options) => {
+            const ctxRun = ctx.runtime;
+            async function* iterate() {
+                let from = options?.from;
+                const deadline = Date.now() + STREAM_TIMEOUT_MS;
+                for (;;) {
+                    const wire = await ctxRun.run(getRunTimelineOp(runId, from === undefined ? {} : { fromSequence: from.toString() }));
+                    for (const entry of wire) {
+                        const mapped = toTimelineEntry(entry);
+                        yield mapped;
+                        from = mapped.sequence + 1n;
+                    }
+                    // Stop once the run is terminal — with one final drain to catch entries written between the
+                    // last timeline fetch and the status check.
+                    const run = await ctxRun.run(getRunOp(runId));
+                    if (TERMINAL_RUN_STATUSES.has(run.status)) {
+                        const tail = await ctxRun.run(getRunTimelineOp(runId, from === undefined ? {} : { fromSequence: from.toString() }));
+                        for (const entry of tail) {
+                            yield toTimelineEntry(entry);
+                        }
+                        return;
+                    }
+                    if (Date.now() > deadline) {
+                        return;
+                    }
+                    await delay(STREAM_POLL_INTERVAL_MS);
+                }
+            }
+            return iterate();
+        },
+        timeline: (options) => {
+            const run = ctx.runtime;
+            async function* iterate() {
+                const wire = await run.run(getRunTimelineOp(runId, options?.from === undefined ? {} : { fromSequence: options.from.toString() }));
+                for (const entry of wire) {
+                    yield toTimelineEntry(entry);
+                }
+            }
+            return iterate();
+        },
+        scrollback: (processId, stream) => {
+            const run = ctx.runtime;
+            async function* iterate() {
+                const response = await run.run(getRunScrollbackOp(runId, { processId, stream }));
+                const bytes = Buffer.from(response.contentBase64, "base64");
+                if (bytes.byteLength > 0) {
+                    yield new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+                }
+            }
+            return iterate();
+        },
+        loss: async () => toLossReport(await ctx.runtime.run(getRunLossOp(runId))),
+        summary: async () => {
+            const run = await ctx.runtime.run(getRunOp(runId));
+            const timeline = await fetchTimeline();
+            const durationMs = run.startedAt !== undefined && run.finishedAt !== undefined
+                ? new Date(run.finishedAt).getTime() - new Date(run.startedAt).getTime()
+                : undefined;
+            return {
+                runId,
+                outcome: run.status === "completed" ? "completed" : "failed",
+                entries: timeline.length,
+                ...(durationMs === undefined ? {} : { durationMs }),
+            };
+        },
+        fileTreeAt: () => Promise.reject(new SealantNotImplementedError("record.fileTreeAt (file-tree fold arrives in Phase 1)")),
+        processTreeAt: () => Promise.reject(new SealantNotImplementedError("record.processTreeAt (process-tree fold arrives in Phase 1)")),
+    };
+};

package/dist/facade/run.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The `Run` facade — one harness execution as the SDK exposes it. Built from a `runs.get` lookup
+ * (read a past run, record outlives the sandbox), from `harness.run()` (which also captures the file
+ * changes inline), or from `harness.start()` (a live handle; `wait()` settles it). `result` is
+ * derived from the wire status; `changes` is captured inline by `run()` and fetched by `wait()` once
+ * the run is terminal (the event-sourced fileChange projection that backs reads arrives in Phase 1);
+ * `artifacts` is empty until the artifact store is exposed; `record` reads via the run/record
+ * endpoints.
+ */
+import type { Run as WireRun } from "@sealant/api-contracts";
+import type { Run, RunFileChange } from "../types.js";
+import type { SdkContext } from "./context.js";
+export interface RunChangesData {
+    readonly files: readonly RunFileChange[];
+    readonly diff: string;
+}
+export interface RunInit {
+    readonly wire: WireRun;
+    readonly changes?: RunChangesData;
+}
+/** Maps the wire changes shape to the facade data (shared with the run-harness execution path). */
+export declare const toRunChangesData: (wire: {
+    readonly files: readonly {
+        readonly path: string;
+        readonly change: "added" | "deleted" | "modified" | "renamed";
+        readonly oldPath?: string | undefined;
+    }[];
+    readonly diff: string;
+}) => RunChangesData;
+export declare const makeRun: (ctx: SdkContext, init: RunInit) => Run;

package/dist/facade/run.js

@@ -0,0 +1,57 @@
+import { getRunChangesOp, getRunOp } from "../effect/operations.js";
+import { SealantError, SealantNotImplementedError } from "../errors.js";
+import { makeRunRecord } from "./record.js";
+/** Maps the wire changes shape to the facade data (shared with the run-harness execution path). */
+export const toRunChangesData = (wire) => ({
+    files: wire.files.map((file) => ({
+        path: file.path,
+        change: file.change,
+        ...(file.oldPath === undefined ? {} : { oldPath: file.oldPath }),
+    })),
+    diff: wire.diff,
+});
+const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled"]);
+const WAIT_POLL_INTERVAL_MS = 500;
+const WAIT_TIMEOUT_MS = 30 * 60 * 1_000;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const toResult = (wire) => ({
+    status: wire.status,
+    outcome: wire.status === "completed" ? "completed" : "failed",
+    exitCode: wire.exitCode ?? -1,
+});
+const emptyArtifacts = {
+    list: () => Promise.resolve([]),
+    get: () => Promise.reject(new SealantNotImplementedError("artifacts.get (artifact store wiring arrives in Phase 1)")),
+};
+export const makeRun = (ctx, init) => {
+    const runId = init.wire.runId;
+    const changesData = init.changes;
+    const changes = {
+        files: changesData?.files ?? [],
+        diff: () => Promise.resolve(changesData?.diff ?? ""),
+    };
+    return {
+        id: runId,
+        result: toResult(init.wire),
+        changes,
+        artifacts: emptyArtifacts,
+        record: makeRunRecord(ctx, runId),
+        wait: async () => {
+            let current = init.wire;
+            const deadline = Date.now() + WAIT_TIMEOUT_MS;
+            while (!TERMINAL_STATUSES.has(current.status)) {
+                if (Date.now() > deadline) {
+                    throw new SealantError(`Timed out waiting for run ${runId} to reach a terminal status.`, {
+                        code: "run_wait_timeout",
+                    });
+                }
+                await delay(WAIT_POLL_INTERVAL_MS);
+                current = await ctx.runtime.run(getRunOp(runId));
+            }
+            // Settle the changes: a handle from `harness.start()` or `runs.get()` has none captured yet,
+            // so read the server-side capture now that the run is terminal.
+            const settledChanges = changesData ?? toRunChangesData(await ctx.runtime.run(getRunChangesOp(runId)));
+            return makeRun(ctx, { wire: current, changes: settledChanges });
+        },
+    };
+};

package/dist/facade/sandbox.d.ts

@@ -0,0 +1,23 @@
+import type { Harness, Sandbox, SandboxStatus } from "../types.js";
+import type { SdkContext } from "./context.js";
+export interface SandboxInit {
+    readonly id: string;
+    readonly name: string;
+    readonly status: SandboxStatus;
+    /** Present when the handle came from `create()` (needed by `harness.run()`). */
+    readonly harness?: Harness;
+}
+/**
+ * The `harness.run()`/`harness.start()` implementations are injected by the run-execution module to
+ * avoid a static dependency cycle (sandbox <-> run execution). Until they are registered, both
+ * report that the feature is not wired in this build.
+ */
+export type RunHarnessFn = (ctx: SdkContext, init: SandboxInit, prompt: string, options?: import("../types.js").RunOptions) => Promise<import("../types.js").Run>;
+export interface HarnessExecutors {
+    /** BLOCKING `harness.run()`: resolves once the run is terminal. */
+    readonly run: RunHarnessFn;
+    /** NON-BLOCKING `harness.start()`: returns the live handle immediately. */
+    readonly start: RunHarnessFn;
+}
+export declare const registerHarnessExecutors: (executors: HarnessExecutors) => void;
+export declare const makeSandbox: (ctx: SdkContext, init: SandboxInit) => Sandbox;

package/dist/facade/sandbox.js

@@ -0,0 +1,89 @@
+import { getSandboxOp } from "../effect/operations.js";
+import { SealantError, SealantNotImplementedError } from "../errors.js";
+const FAILED_STATUSES = new Set(["failed", "cancelled"]);
+const READY_POLL_INTERVAL_MS = 2_000;
+const READY_TIMEOUT_MS = 10 * 60 * 1_000;
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+let harnessExecutors;
+export const registerHarnessExecutors = (executors) => {
+    harnessExecutors = executors;
+};
+export const makeSandbox = (ctx, init) => {
+    const harness = {
+        run: (prompt, options) => {
+            if (harnessExecutors === undefined) {
+                return Promise.reject(new SealantNotImplementedError("harness.run (run execution not wired in this build)"));
+            }
+            return harnessExecutors.run(ctx, init, prompt, options);
+        },
+        start: (prompt, options) => {
+            if (harnessExecutors === undefined) {
+                return Promise.reject(new SealantNotImplementedError("harness.start (run execution not wired in this build)"));
+            }
+            return harnessExecutors.start(ctx, init, prompt, options);
+        },
+        session: () => Promise.reject(new SealantNotImplementedError("harness.session (interactive, Phase 3)")),
+    };
+    const sandbox = {
+        id: init.id,
+        name: init.name,
+        status: async () => {
+            const details = await ctx.runtime.run(getSandboxOp(init.id));
+            return details.status;
+        },
+        ready: async () => {
+            const deadline = Date.now() + READY_TIMEOUT_MS;
+            for (;;) {
+                const details = await ctx.runtime.run(getSandboxOp(init.id));
+                // Gate on the coarse "ready" status, which the control plane now emits ONLY after the
+                // in-sandbox daemon's control socket is accepting (readiness probe in the launch path).
+                // This is honest: when ready() resolves, harness.run() can connect without racing the socket.
+                if (details.status === "ready") {
+                    return sandbox;
+                }
+                if (FAILED_STATUSES.has(details.status)) {
+                    throw new SealantError(`Sandbox ${init.id} reached terminal status "${details.status}" before becoming ready.`, { code: "sandbox_not_ready" });
+                }
+                if (Date.now() > deadline) {
+                    throw new SealantError(`Timed out waiting for sandbox ${init.id} to become ready.`, {
+                        code: "sandbox_ready_timeout",
+                    });
+                }
+                await delay(READY_POLL_INTERVAL_MS);
+            }
+        },
+        harness,
+        // Poll-backed lifecycle stream: emit a coarse event on each status transition until the sandbox
+        // reaches a terminal/ready state. Swaps to SSE over Postgres LISTEN/NOTIFY in Stage 5 (same shape).
+        events: () => {
+            const ctxRun = ctx.runtime;
+            async function* iterate() {
+                let lastStatus;
+                const deadline = Date.now() + READY_TIMEOUT_MS;
+                for (;;) {
+                    const details = await ctxRun.run(getSandboxOp(init.id));
+                    if (details.status !== lastStatus) {
+                        lastStatus = details.status;
+                        yield {
+                            type: `status.${details.status}`,
+                            occurredAt: new Date().toISOString(),
+                            message: `Sandbox status: ${details.status}`,
+                        };
+                    }
+                    if (details.status === "ready" || FAILED_STATUSES.has(details.status)) {
+                        return;
+                    }
+                    if (Date.now() > deadline) {
+                        return;
+                    }
+                    await delay(READY_POLL_INTERVAL_MS);
+                }
+            }
+            return iterate();
+        },
+        stop: () => Promise.reject(new SealantNotImplementedError("sandbox.stop (lifecycle, Phase 3)")),
+        restart: () => Promise.reject(new SealantNotImplementedError("sandbox.restart (lifecycle, Phase 3)")),
+        expire: () => Promise.reject(new SealantNotImplementedError("sandbox.expire (lifecycle, Phase 3)")),
+    };
+    return sandbox;
+};

package/dist/harness.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Harness factories. Each returns a thin `Harness` value: an id plus how to invoke it one-shot
+ * against a prompt.
+ *
+ * NOTE — the one-shot invocation forms below (`opencode run <prompt>`, `codex exec <prompt>`,
+ * `claude -p <prompt>`) are the expected headless shapes but are PENDING live verification against
+ * the baked sandbox image (see the SDK plan's task #2, "verify harness one-shot CLI semantics").
+ * Until that is confirmed, only `opencode()` is exercised end-to-end; the others are provided for the
+ * typed surface and adjusted once verified.
+ */
+import type { Harness } from "./types.js";
+/** OpenCode — the harness used in the canonical hero example. */
+export declare const opencode: () => Harness;
+/** OpenAI Codex CLI. */
+export declare const codex: () => Harness;
+/** Anthropic Claude Code. */
+export declare const claudeCode: (options?: {
+    readonly profile?: string;
+} | undefined) => Harness;
+/**
+ * A bring-your-own harness. The caller supplies how to invoke it one-shot (`invoke`) and, optionally,
+ * how to install and launch it. This is the harness-neutral escape hatch: any agent loop, CI worker,
+ * or custom binary.
+ */
+export declare const customHarness: (options: {
+    readonly id: string;
+    readonly invoke: (prompt: string) => readonly string[];
+    readonly executable?: string;
+    readonly install?: {
+        readonly packages?: readonly string[];
+        readonly command?: string;
+    };
+    readonly launchCommand?: string;
+}) => Harness;

package/dist/harness.js

@@ -0,0 +1,37 @@
+/** OpenCode — the harness used in the canonical hero example. */
+export const opencode = () => ({
+    id: "opencode",
+    buildRunCommand: (prompt) => ({ executable: "opencode", args: ["run", prompt] }),
+    launchCommand: "opencode",
+});
+/** OpenAI Codex CLI. */
+export const codex = () => ({
+    id: "codex",
+    buildRunCommand: (prompt) => ({ executable: "codex", args: ["exec", prompt] }),
+    launchCommand: "codex",
+});
+/** Anthropic Claude Code. */
+export const claudeCode = (options) => ({
+    id: "claude-code",
+    buildRunCommand: (prompt) => ({
+        executable: "claude",
+        args: options?.profile === undefined
+            ? ["-p", prompt]
+            : ["--profile", options.profile, "-p", prompt],
+    }),
+    launchCommand: "claude",
+});
+/**
+ * A bring-your-own harness. The caller supplies how to invoke it one-shot (`invoke`) and, optionally,
+ * how to install and launch it. This is the harness-neutral escape hatch: any agent loop, CI worker,
+ * or custom binary.
+ */
+export const customHarness = (options) => ({
+    id: options.id,
+    buildRunCommand: (prompt) => ({
+        executable: options.executable ?? options.id,
+        args: options.invoke(prompt),
+    }),
+    ...(options.install === undefined ? {} : { install: options.install }),
+    ...(options.launchCommand === undefined ? {} : { launchCommand: options.launchCommand }),
+});

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @sealant/sdk — the fluent public SDK for Sealant.
+ *
+ * Create a live sandbox around a real repository, run the harness you already use, stream progress
+ * while it works, and keep the replayable execution record after the sandbox is gone:
+ *
+ *   import { Sealant, opencode } from "@sealant/sdk"
+ *
+ *   const sealant = new Sealant({ baseUrl: "http://localhost:8080" })
+ *   const sandbox = await sealant.sandboxes.create({
+ *     repository: "github.com/acme/billing-service",
+ *     harness: opencode(),
+ *   })
+ *   const run = await sandbox.harness.run("Round invoice totals once, after applying the discount.")
+ *   await run.record.replay()
+ */
+export { Sealant } from "./client.js";
+export { claudeCode, codex, customHarness, opencode } from "./harness.js";
+export { SealantApiError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @sealant/sdk — the fluent public SDK for Sealant.
+ *
+ * Create a live sandbox around a real repository, run the harness you already use, stream progress
+ * while it works, and keep the replayable execution record after the sandbox is gone:
+ *
+ *   import { Sealant, opencode } from "@sealant/sdk"
+ *
+ *   const sealant = new Sealant({ baseUrl: "http://localhost:8080" })
+ *   const sandbox = await sealant.sandboxes.create({
+ *     repository: "github.com/acme/billing-service",
+ *     harness: opencode(),
+ *   })
+ *   const run = await sandbox.harness.run("Round invoice totals once, after applying the discount.")
+ *   await run.record.replay()
+ */
+export { Sealant } from "./client.js";
+export { claudeCode, codex, customHarness, opencode } from "./harness.js";
+export { SealantApiError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";

package/dist/internal/blueprint.d.ts

@@ -0,0 +1,30 @@
+import type { CreateOptions } from "../types.js";
+import type { SealantInternalConfig } from "./config.js";
+export declare const buildCreateSandboxRequest: (options: CreateOptions, config: SealantInternalConfig) => {
+    readonly payload: {
+        readonly ownerUserId: string;
+        readonly registryId: string;
+        readonly repository: string;
+        readonly tag: string;
+        readonly name?: string | undefined;
+        readonly sourceSelection?: {
+            readonly provider: "github";
+            readonly installationId: string;
+            readonly installationRepositoryId: string;
+            readonly ref?: string | undefined;
+        } | undefined;
+        readonly dotfilesSelection?: {
+            readonly provider: "github";
+            readonly installationId: string;
+            readonly installationRepositoryId: string;
+            readonly ref?: string | undefined;
+        } | undefined;
+        readonly credentials?: {
+            readonly profileId?: string | undefined;
+            readonly claude?: string | undefined;
+            readonly codex?: string | undefined;
+            readonly github?: string | undefined;
+        } | undefined;
+        readonly spec: unknown;
+    };
+};

package/dist/internal/blueprint.js

@@ -0,0 +1,69 @@
+/**
+ * Lowers the fluent `create({ repository, harness })` options into the existing
+ * `createSandboxRequestSchema` the control plane accepts — entirely client-side, so the slice needs
+ * no contract change. The public `repository` is the SOURCE git repo (it becomes
+ * `spec.sources.sandbox.url`); the contract's `repository`/`tag` are the OCI push coordinates, which
+ * we derive. `customization.enableSealantd` is forced on (it bakes + launches the daemon the run path
+ * connects to), the runtime target is pinned to docker (the only bridgeable adapter today), and the
+ * foreground is a keepalive so the sandbox idles with the daemon up and the harness is exec'd on
+ * demand by `run()` rather than launched at boot. `options.credentials`, if present, is lowered via
+ * `mapSandboxCredentials` (see `./credentials.js`) and folded into `spec.credentials`; the control
+ * plane resolves those account references server-side (never secret material over this path).
+ */
+import { randomUUID } from "node:crypto";
+import { mapSandboxCredentials } from "./credentials.js";
+const sanitizeRepoSlug = (value) => {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+    return slug.length > 0 ? slug : "repo";
+};
+const toGitUrl = (repository) => {
+    if (/^(https?:\/\/|git@|ssh:\/\/)/.test(repository)) {
+        return repository;
+    }
+    return `https://${repository}.git`;
+};
+export const buildCreateSandboxRequest = (options, config) => {
+    const tail = options.repository
+        .split("/")
+        .filter((s) => s.length > 0)
+        .pop() ?? options.repository;
+    const credentials = mapSandboxCredentials(options.credentials);
+    const spec = {
+        version: "1",
+        sources: {
+            sandbox: {
+                kind: "git",
+                provider: "generic",
+                url: toGitUrl(options.repository),
+                ref: options.ref ?? "main",
+            },
+        },
+        harness: { id: options.harness.id },
+        customization: { enableSealantd: true },
+        target: {
+            os: { family: options.os ?? "fedora", mode: "prefer" },
+            runtime: { family: "docker", mode: "require" },
+        },
+        lifecycle: {
+            startup: { foreground: { kind: "command", run: "sleep infinity", shell: "bash" } },
+        },
+        ...(options.packages === undefined || options.packages.length === 0
+            ? {}
+            : { tooling: { packages: options.packages.map((id) => ({ id })) } }),
+        ...(credentials === undefined ? {} : { credentials }),
+    };
+    return {
+        payload: {
+            ownerUserId: config.hostLocal.ownerUserId,
+            registryId: config.hostLocal.registryId,
+            repository: sanitizeRepoSlug(tail),
+            tag: `sdk-${randomUUID().slice(0, 8)}`,
+            ...(options.name === undefined ? {} : { name: options.name }),
+            spec,
+        },
+    };
+};

package/dist/internal/config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Internal SDK configuration.
+ *
+ * The PUBLIC surface (`SealantConfig` in `../types.ts`) is intentionally minimal: `{ baseUrl, apiKey }`.
+ * The SDK is now a thin HTTP client (run execution + telemetry moved server-side), so the only
+ * host-local concerns left are a pre-auth owner principal and the registry id used on create/run
+ * payloads. These live HERE — resolved from the environment with docker-compose defaults — so they
+ * never leak into the published `SealantConfig`, and they disappear entirely once auth lands.
+ */
+import type { SealantConfig } from "../types.js";
+export interface SealantHostLocalConfig {
+    /** Owner principal the control plane attributes sandboxes/runs to (pre-auth). */
+    readonly ownerUserId: string;
+    /** Registry the sandbox image is published to and launched from. */
+    readonly registryId: string;
+}
+export interface SealantInternalConfig {
+    readonly baseUrl: string;
+    readonly apiKey: string | undefined;
+    readonly fetch: typeof fetch | undefined;
+    readonly hostLocal: SealantHostLocalConfig;
+}
+/** Resolves the public config plus host-local needs (from env, with docker-compose defaults). */
+export declare const resolveInternalConfig: (config: SealantConfig) => SealantInternalConfig;