@sealant/sdk 0.0.0

package/dist/internal/config.js

@@ -0,0 +1,17 @@
+const DEFAULT_OWNER_USER_ID = "usr_local";
+// Must match the control-plane's REGISTRY_NAME (defaults to "default"); the API 404s otherwise.
+const DEFAULT_REGISTRY_ID = "default";
+const env = (key) => {
+    const value = process.env[key];
+    return value === undefined || value.length === 0 ? undefined : value;
+};
+/** Resolves the public config plus host-local needs (from env, with docker-compose defaults). */
+export const resolveInternalConfig = (config) => ({
+    baseUrl: config.baseUrl,
+    apiKey: config.apiKey,
+    fetch: config.fetch,
+    hostLocal: {
+        ownerUserId: env("SEALANT_OWNER_USER_ID") ?? DEFAULT_OWNER_USER_ID,
+        registryId: env("SEALANT_REGISTRY_ID") ?? DEFAULT_REGISTRY_ID,
+    },
+});

package/dist/internal/credentials.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Lowers the public `SandboxCredentialsOptions` onto the control-plane's sandbox-create payload
+ * shape. Pure and side-effect free so it is unit-testable on its own; `buildCreateSandboxRequest`
+ * calls it and folds the result into the request it builds.
+ *
+ * SECURITY: this only ever moves account **references** (booleans/names/ids) — never token values or
+ * other secret material. `true` resolves to the literal account name `"default"`; a string passes
+ * through as the named account; `profile` becomes `profileId`.
+ */
+import type { SandboxCredentialsOptions } from "../types.js";
+/** The control-plane's sandbox-create payload shape for connected-account credentials. */
+export interface SandboxCredentialsPayload {
+    readonly profileId?: string;
+    readonly claude?: string;
+    readonly codex?: string;
+    readonly github?: string;
+}
+/**
+ * Maps `SandboxCredentialsOptions` to the API payload shape, or `undefined` when no credentials were
+ * requested (omitted entirely, rather than serialized as an empty object).
+ */
+export declare const mapSandboxCredentials: (options: SandboxCredentialsOptions | undefined) => SandboxCredentialsPayload | undefined;

package/dist/internal/credentials.js

@@ -0,0 +1,26 @@
+const DEFAULT_ACCOUNT_NAME = "default";
+const mapAccountRef = (value) => {
+    if (value === undefined || value === false) {
+        return undefined;
+    }
+    return value === true ? DEFAULT_ACCOUNT_NAME : value;
+};
+/**
+ * Maps `SandboxCredentialsOptions` to the API payload shape, or `undefined` when no credentials were
+ * requested (omitted entirely, rather than serialized as an empty object).
+ */
+export const mapSandboxCredentials = (options) => {
+    if (options === undefined) {
+        return undefined;
+    }
+    const claude = mapAccountRef(options.claude);
+    const codex = mapAccountRef(options.codex);
+    const github = mapAccountRef(options.github);
+    const payload = {
+        ...(options.profile === undefined ? {} : { profileId: options.profile }),
+        ...(claude === undefined ? {} : { claude }),
+        ...(codex === undefined ? {} : { codex }),
+        ...(github === undefined ? {} : { github }),
+    };
+    return Object.keys(payload).length > 0 ? payload : undefined;
+};

package/dist/internal/map-error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Maps any failure crossing the Effect boundary onto a plain public `SealantError`. The Effect core
+ * fails with `@sealant/api-contracts` tagged errors (e.g. `SandboxNotFoundError`), Effect HTTP-client
+ * errors, or schema decode errors; the runtime squashes the `Cause` to its failure value and hands it
+ * here. This is the single funnel that keeps Effect internals out of the public, Promise-based API.
+ */
+import { SealantError } from "../errors.js";
+export declare const toSealantError: (cause: unknown) => SealantError;

package/dist/internal/map-error.js

@@ -0,0 +1,44 @@
+/**
+ * Maps any failure crossing the Effect boundary onto a plain public `SealantError`. The Effect core
+ * fails with `@sealant/api-contracts` tagged errors (e.g. `SandboxNotFoundError`), Effect HTTP-client
+ * errors, or schema decode errors; the runtime squashes the `Cause` to its failure value and hands it
+ * here. This is the single funnel that keeps Effect internals out of the public, Promise-based API.
+ */
+import { SealantApiError, SealantError } from "../errors.js";
+const asRecord = (value) => typeof value === "object" && value !== null ? value : undefined;
+const extractStatus = (record) => {
+    if (record === undefined) {
+        return undefined;
+    }
+    if (typeof record["status"] === "number") {
+        return record["status"];
+    }
+    const response = asRecord(record["response"]);
+    if (response !== undefined && typeof response["status"] === "number") {
+        return response["status"];
+    }
+    return undefined;
+};
+export const toSealantError = (cause) => {
+    if (cause instanceof SealantError) {
+        return cause;
+    }
+    const record = asRecord(cause);
+    const tag = record === undefined ? undefined : record["_tag"];
+    const message = record !== undefined && typeof record["message"] === "string"
+        ? record["message"]
+        : cause instanceof Error
+            ? cause.message
+            : typeof cause === "string"
+                ? cause
+                : "Sealant operation failed.";
+    if (typeof tag === "string") {
+        const status = extractStatus(record);
+        return new SealantApiError(message, {
+            code: tag,
+            ...(status === undefined ? {} : { status }),
+            cause,
+        });
+    }
+    return new SealantError(message, { cause });
+};

package/dist/types.d.ts

@@ -0,0 +1,291 @@
+/**
+ * The Sealant SDK public type surface.
+ *
+ * This is the fluent object model the marketing site commits to verbatim:
+ *
+ *   const sandbox = await sealant.sandboxes.create({ repository, harness: opencode() })
+ *   const run = await sandbox.harness.run("Round invoice totals once, after applying the discount.")
+ *   await run.record.replay()
+ *
+ * Design rule (load-bearing): these public types are HAND-WRITTEN and DECOUPLED from the Effect-core
+ * and `@sealant/telemetry` internal shapes. The facade maps internal data onto these types so the
+ * public surface stays stable across Effect-v4-beta churn and internal read-model changes. The whole
+ * surface is typed NOW — including operations not yet implemented in the current slice — so callers
+ * compile against a stable contract from day one (unimplemented paths reject with
+ * `SealantNotImplementedError` at runtime, see `./errors.js`).
+ */
+/**
+ * Public client configuration. Intentionally minimal: a base URL and an API key. Host-local
+ * concerns required by the current slice (owner identity, registry, direct database access) live in
+ * a separate internal config and never leak into this published type — see `./internal-config.ts`
+ * when the Effect core lands.
+ */
+export interface SealantConfig {
+    /** Base URL of the Sealant control-plane API (e.g. `http://localhost:8080`). */
+    readonly baseUrl: string;
+    /** Bearer token for authenticated deployments. Optional for a localhost demo with no auth. */
+    readonly apiKey?: string;
+    /** Override the `fetch` implementation (tests, custom agents, proxies). */
+    readonly fetch?: typeof fetch;
+}
+/** The harnesses with first-class integrations baked into the platform today. */
+export type HarnessId = "opencode" | "codex" | "claude-code";
+/** A single one-shot command to invoke a harness against a prompt inside the sandbox. */
+export interface HarnessRunCommand {
+    /** The executable to run (e.g. `"opencode"`). */
+    readonly executable: string;
+    /** Arguments, including the prompt where the harness expects it. */
+    readonly args: readonly string[];
+}
+/**
+ * A harness is a thin client value: an identity plus the knowledge of how to invoke it one-shot
+ * against a prompt. `opencode()`, `codex()`, `claudeCode()` and `customHarness()` (see `./harness.js`)
+ * produce these. Invoke-knowledge starts SDK-side as `buildRunCommand`; it migrates server-side into
+ * the platform's harness integration in a later phase so every surface shares one source of truth.
+ */
+export interface Harness {
+    /** Stable id. Built-in harnesses use a `HarnessId`; custom harnesses carry their own string. */
+    readonly id: string;
+    /** Builds the one-shot invocation for a prompt. */
+    readonly buildRunCommand: (prompt: string) => HarnessRunCommand;
+    /** Optional install hints for custom harnesses (built-ins are resolved by the platform). */
+    readonly install?: {
+        readonly packages?: readonly string[];
+        readonly command?: string;
+    };
+    /** Optional launch command for an interactive session (defaults to the executable). */
+    readonly launchCommand?: string;
+}
+/** Lifecycle status of a sandbox. `stopped`/`expired` arrive with lifecycle close-out (Phase 3). */
+export type SandboxStatus = "queued" | "running" | "ready" | "failed" | "cancelled";
+/** A coarse lifecycle event observed while a sandbox is being provisioned. */
+export interface SandboxEvent {
+    readonly type: string;
+    readonly occurredAt: string;
+    readonly message?: string;
+}
+/** The supported sandbox OS families (maps to the blueprint target). */
+export type SandboxOs = "fedora" | "arch" | "nix";
+/**
+ * Connected-account credentials to attach to a sandbox at creation time, per provider — so the
+ * harness inside the sandbox authenticates as the caller's own Claude / Codex / GitHub identity
+ * instead of running unauthenticated.
+ *
+ * For each provider: `true` means "my default account" (the one named `"default"`), and a `string`
+ * names a specific connected account. `profile` names a profile slug/id whose bundled per-provider
+ * bindings apply first; any explicit `claude`/`codex`/`github` field wins over the profile's binding
+ * for that provider.
+ *
+ * SECURITY: only account **references** (booleans/names/ids) ever cross this surface — token values,
+ * `auth.json` contents, and any other secret material never do. The control plane resolves references
+ * to encrypted credentials server-side and injects them at launch.
+ */
+export interface SandboxCredentialsOptions {
+    /** Profile id whose per-provider account bindings apply first. */
+    readonly profile?: string;
+    /** `true` for the caller's default Claude account, or a string naming a specific one. */
+    readonly claude?: boolean | string;
+    /** `true` for the caller's default Codex account, or a string naming a specific one. */
+    readonly codex?: boolean | string;
+    /** `true` for the caller's default GitHub account, or a string naming a specific one. */
+    readonly github?: boolean | string;
+}
+export interface CreateOptions {
+    /** Source git repository to build the sandbox around (e.g. `"github.com/acme/billing-service"`). */
+    readonly repository: string;
+    /** The harness to run inside the sandbox. */
+    readonly harness: Harness;
+    /** Git ref to check out (defaults to the repository's default branch). */
+    readonly ref?: string;
+    /** Human-friendly name for the sandbox. */
+    readonly name?: string;
+    /** OS family for the sandbox image. */
+    readonly os?: SandboxOs;
+    /** Extra OS packages to install in the sandbox. */
+    readonly packages?: readonly string[];
+    /** When true (default), resolve only once the sandbox runtime is live. */
+    readonly wait?: boolean;
+    /** Observe provisioning events as they happen. */
+    readonly onEvent?: (event: SandboxEvent) => void;
+    /** Connected-account credentials to attach to the sandbox (see `SandboxCredentialsOptions`). */
+    readonly credentials?: SandboxCredentialsOptions;
+}
+export interface ListOptions {
+    readonly status?: SandboxStatus;
+    readonly limit?: number;
+}
+/** A live, disposable development environment around a real repository. */
+export interface Sandbox {
+    readonly id: string;
+    readonly name: string;
+    /** Current lifecycle status. */
+    status(): Promise<SandboxStatus>;
+    /** Resolves once the sandbox runtime is live and ready to accept a run. */
+    ready(): Promise<this>;
+    /** Run a harness in this sandbox. */
+    readonly harness: HarnessRunner;
+    /** Lifecycle events as an async stream. */
+    events(): AsyncIterable<SandboxEvent>;
+    /** Stop the sandbox now (Phase 3). */
+    stop(): Promise<void>;
+    /** Restart the sandbox into a fresh runtime (Phase 3). */
+    restart(): Promise<Sandbox>;
+    /** Schedule the sandbox to expire (Phase 3). */
+    expire(options?: {
+        readonly in?: string;
+    }): Promise<void>;
+}
+export interface RunOptions {
+    /** Cancel the run by aborting this signal. */
+    readonly signal?: AbortSignal;
+    /** Idempotency key so a retried call does not start a duplicate run. */
+    readonly idempotencyKey?: string;
+}
+export interface SessionOptions {
+    readonly signal?: AbortSignal;
+}
+/** Runs a harness in a sandbox, one-shot or interactive. */
+export interface HarnessRunner {
+    /** BLOCKING: resolves once the harness has terminally completed; `result`/`changes` are settled. */
+    run(prompt: string, options?: RunOptions): Promise<Run>;
+    /** NON-BLOCKING: returns a live handle immediately for streaming via `run.record.stream()`. */
+    start(prompt: string, options?: RunOptions): Promise<Run>;
+    /** Interactive session reusing the live sandbox (Phase 3). */
+    session(options?: SessionOptions): Promise<InteractiveSession>;
+}
+export type RunOutcome = "completed" | "failed";
+/** Lifecycle status of a run (harness execution). */
+export type RunStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+export interface RunResult {
+    /** Raw lifecycle status (honest for non-terminal runs read via `runs.get`). */
+    readonly status: RunStatus;
+    /** Coarse terminal outcome: `completed` only when the run completed; otherwise `failed`. */
+    readonly outcome: RunOutcome;
+    readonly exitCode: number;
+    readonly summary?: string;
+}
+export type FileChangeKind = "added" | "modified" | "deleted" | "renamed";
+export interface RunFileChange {
+    readonly path: string;
+    readonly change: FileChangeKind;
+    /** Previous path for a rename. */
+    readonly oldPath?: string;
+}
+export interface RunChanges {
+    readonly files: readonly RunFileChange[];
+    /** The unified diff of everything that changed. */
+    diff(): Promise<string>;
+}
+export interface ArtifactRef {
+    readonly name: string;
+    readonly bytes: number;
+    readonly contentType?: string;
+}
+export interface RunArtifacts {
+    list(): Promise<readonly ArtifactRef[]>;
+    get(name: string): Promise<Uint8Array>;
+}
+/** A single ordered entry in the execution record's timeline. */
+export interface TimelineEntry {
+    readonly sequence: bigint;
+    readonly kind: string;
+    readonly occurredAt: string;
+    readonly data: unknown;
+}
+/** A re-fold of the record up to some point — scrubable by sequence. */
+export interface RunReplay {
+    readonly entries: readonly TimelineEntry[];
+    /** The entry at (or the last entry at-or-before) `sequence`. */
+    at(sequence: bigint): TimelineEntry | undefined;
+}
+/** One terminal command the run executed, reconstructed from the record (not raw event noise). */
+export interface RunCommand {
+    /** The executable that ran (e.g. `"opencode"`). */
+    readonly executable: string;
+    /** Its arguments. */
+    readonly args: readonly string[];
+    /** A ready-to-read shell line, e.g. `opencode run "fix the test"`. */
+    readonly command: string;
+    /** Working directory the command ran in. */
+    readonly cwd?: string;
+    /** Exit code, when the command exited normally. */
+    readonly exitCode?: number;
+    /** Signal number, when the command was terminated by a signal instead. */
+    readonly signal?: number;
+    /** Wall-clock duration in milliseconds, when known. */
+    readonly durationMs?: number;
+    /** Bytes the command wrote to stdout / stderr (full text is available via `scrollback`). */
+    readonly stdoutBytes: number;
+    readonly stderrBytes: number;
+}
+/** Provenance-honest report of any gaps detected in the recorded stream. */
+export interface LossReport {
+    readonly complete: boolean;
+    readonly spans: readonly {
+        readonly fromSequence?: bigint;
+        readonly toSequence?: bigint;
+    }[];
+}
+export interface RunSummary {
+    readonly runId: string;
+    readonly outcome: RunOutcome;
+    readonly entries: number;
+    readonly durationMs?: number;
+}
+/** Output streams a process can write to. */
+export type IoStream = "stdout" | "stderr";
+/**
+ * The execution record for a run: the durable, replayable history. Backed by the telemetry read
+ * facade. `replay()`/`timeline()`/`scrollback()`/`stream()` are available in the current slice; the
+ * time-travel folds (`fileTreeAt`/`processTreeAt`) reject until their read models land.
+ */
+export interface RunRecord {
+    readonly runId: string;
+    /** Re-fold the full record into a scrubable replay (low-level: every timeline entry). */
+    replay(options?: {
+        readonly speed?: number;
+        readonly onEntry?: (entry: TimelineEntry) => void;
+    }): Promise<RunReplay>;
+    /** The terminal commands the run executed — what the harness actually did, reconstructed. */
+    commands(): Promise<readonly RunCommand[]>;
+    /** A human-readable transcript: the commands and their outcomes, nicely laid out (no event noise). */
+    transcript(): Promise<string>;
+    /** Subscribe to the live event stream while the run is in progress (poll-backed; SSE later). */
+    stream(options?: {
+        readonly from?: bigint;
+    }): AsyncIterable<TimelineEntry>;
+    /** Iterate the full timeline as structured data. */
+    timeline(options?: {
+        readonly from?: bigint;
+    }): AsyncIterable<TimelineEntry>;
+    /** Byte-exact scrollback for a process's output stream. */
+    scrollback(processId: string, stream: IoStream): AsyncIterable<Uint8Array>;
+    /** Provenance-honest loss report. */
+    loss(): Promise<LossReport>;
+    /** A compact summary of the run. */
+    summary(): Promise<RunSummary>;
+    /** File-tree snapshot at a point in time (Phase 1 — rejects until backed). */
+    fileTreeAt(sequence: bigint): Promise<unknown>;
+    /** Process-tree snapshot at a point in time (Phase 1 — rejects until backed). */
+    processTreeAt(sequence: bigint): Promise<unknown>;
+}
+/** One unit of developer work: what it produced and how it happened. */
+export interface Run {
+    readonly id: string;
+    /** Terminal result (settled once `run()` resolves). */
+    readonly result: RunResult;
+    /** The before/after of what changed. */
+    readonly changes: RunChanges;
+    /** Retained artifacts. */
+    readonly artifacts: RunArtifacts;
+    /** The execution record. */
+    readonly record: RunRecord;
+    /** Resolves once the run has terminally completed (no-op if already settled). */
+    wait(): Promise<Run>;
+}
+/** An interactive harness session over the live sandbox (Phase 3). */
+export interface InteractiveSession {
+    send(input: string): Promise<void>;
+    output(): AsyncIterable<Uint8Array>;
+    close(): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1,17 @@
+/**
+ * The Sealant SDK public type surface.
+ *
+ * This is the fluent object model the marketing site commits to verbatim:
+ *
+ *   const sandbox = await sealant.sandboxes.create({ repository, harness: opencode() })
+ *   const run = await sandbox.harness.run("Round invoice totals once, after applying the discount.")
+ *   await run.record.replay()
+ *
+ * Design rule (load-bearing): these public types are HAND-WRITTEN and DECOUPLED from the Effect-core
+ * and `@sealant/telemetry` internal shapes. The facade maps internal data onto these types so the
+ * public surface stays stable across Effect-v4-beta churn and internal read-model changes. The whole
+ * surface is typed NOW — including operations not yet implemented in the current slice — so callers
+ * compile against a stable contract from day one (unimplemented paths reject with
+ * `SealantNotImplementedError` at runtime, see `./errors.js`).
+ */
+export {};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@sealant/sdk",
+  "version": "0.0.0",
+  "description": "The fluent public SDK for Sealant — create a sandbox, run a harness, replay the record.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sealant-sh/sealant.git",
+    "directory": "packages/sdk"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "effect": "^4.0.0-beta.85",
+    "@sealant/api-contracts": "^0.0.0"
+  },
+  "devDependencies": {
+    "@effect/vitest": "^4.0.0-beta.85",
+    "@sealant/typescript": "0.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsgo -p tsconfig.build.json",
+    "lint": "oxlint .",
+    "test": "vitest run",
+    "typecheck": "tsgo -p tsconfig.json --noEmit"
+  }
+}