@sealant/sdk 0.3.1 → 0.5.0

package/dist/types.d.ts

@@ -3,8 +3,8 @@
  *
  * 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.")
+ *   const workspace = await sealant.workspaces.create({ repository, harness: opencode() })
+ *   const run = await workspace.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
@@ -30,7 +30,7 @@ export interface SealantConfig {
 }
 /** 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. */
+/** A single one-shot command to invoke a harness against a prompt inside the workspace. */
 export interface HarnessRunCommand {
     /** The executable to run (e.g. `"opencode"`). */
     readonly executable: string;
@@ -56,19 +56,19 @@ export interface Harness {
     /** 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 {
+/** Lifecycle status of a workspace. `stopped`/`expired` arrive with lifecycle close-out (Phase 3). */
+export type WorkspaceStatus = "queued" | "running" | "ready" | "failed" | "cancelled";
+/** A coarse lifecycle event observed while a workspace is being provisioned. */
+export interface WorkspaceEvent {
     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";
+/** The supported workspace OS families (maps to the blueprint target). */
+export type WorkspaceOs = "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
+ * 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
  * instead of running unauthenticated.
  *
  * For each provider: `true` means "my default account" (the one named `"default"`), and a `string`
@@ -80,7 +80,7 @@ export type SandboxOs = "fedora" | "arch" | "nix";
  * `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 {
+export interface WorkspaceCredentialsOptions {
     /** 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. */
@@ -91,46 +91,72 @@ export interface SandboxCredentialsOptions {
     readonly github?: boolean | string;
 }
 export interface CreateOptions {
-    /** Source git repository to build the sandbox around (e.g. `"github.com/acme/billing-service"`). */
+    /** Source git repository to build the workspace around (e.g. `"github.com/acme/billing-service"`). */
     readonly repository: string;
-    /** The harness to run inside the sandbox. */
+    /** The harness to run inside the workspace. */
     readonly harness: Harness;
     /** Git ref to check out (defaults to the repository's default branch). */
     readonly ref?: string;
-    /** Human-friendly name for the sandbox. */
+    /** Human-friendly name for the workspace. */
     readonly name?: string;
-    /** OS family for the sandbox image. */
-    readonly os?: SandboxOs;
-    /** Extra OS packages to install in the sandbox. */
+    /** OS family for the workspace image. */
+    readonly os?: WorkspaceOs;
+    /** Extra OS packages to install in the workspace. */
     readonly packages?: readonly string[];
-    /** When true (default), resolve only once the sandbox runtime is live. */
+    /** When true (default), resolve only once the workspace 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;
+    readonly onEvent?: (event: WorkspaceEvent) => void;
+    /** Connected-account credentials to attach to the workspace (see `WorkspaceCredentialsOptions`). */
+    readonly credentials?: WorkspaceCredentialsOptions;
 }
 export interface ListOptions {
-    readonly status?: SandboxStatus;
+    readonly status?: WorkspaceStatus;
     readonly limit?: number;
 }
+/** Options for a deterministic `workspace.exec()`. */
+export interface WorkspaceExecOptions {
+    /** Working directory inside the workspace (defaults to the repository root). */
+    readonly cwd?: string;
+}
+/**
+ * The settled result of a deterministic `workspace.exec()`. The exit code is a check DATUM — a
+ * nonzero exit resolves normally (that's the point: `base fails` is a recorded fact, not an error).
+ * `exec()` rejects only when the execution machinery itself broke, i.e. when the exit code cannot
+ * be trusted.
+ */
+export interface WorkspaceExecResult {
+    /** Exit code of the executed command. */
+    readonly exitCode: number;
+    /** Everything the command wrote to stdout, decoded as UTF-8. */
+    readonly stdout: string;
+    /** Everything the command wrote to stderr, decoded as UTF-8. */
+    readonly stderr: string;
+    /** The run this exec was recorded as — its `record` is the durable, replayable evidence. */
+    readonly run: Run;
+}
 /** A live, disposable development environment around a real repository. */
-export interface Sandbox {
+export interface Workspace {
     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. */
+    status(): Promise<WorkspaceStatus>;
+    /** Resolves once the workspace runtime is live and ready to accept a run. */
     ready(): Promise<this>;
-    /** Run a harness in this sandbox. */
+    /** Run a harness in this workspace. */
     readonly harness: HarnessRunner;
+    /**
+     * Execute one command deterministically in the workspace — no agent in the loop — recorded into a
+     * run record like any other process. `argv[0]` is the executable, the rest its arguments.
+     */
+    exec(argv: readonly string[], options?: WorkspaceExecOptions): Promise<WorkspaceExecResult>;
     /** Lifecycle events as an async stream. */
-    events(): AsyncIterable<SandboxEvent>;
-    /** Stop the sandbox now (Phase 3). */
+    events(): AsyncIterable<WorkspaceEvent>;
+    /** Stop the workspace 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). */
+    /** Restart the workspace into a fresh runtime (Phase 3). */
+    restart(): Promise<Workspace>;
+    /** Schedule the workspace to expire (Phase 3). */
     expire(options?: {
         readonly in?: string;
     }): Promise<void>;
@@ -144,13 +170,13 @@ export interface RunOptions {
 export interface SessionOptions {
     readonly signal?: AbortSignal;
 }
-/** Runs a harness in a sandbox, one-shot or interactive. */
+/** Runs a harness in a workspace, 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). */
+    /** Interactive session reusing the live workspace (Phase 3). */
     session(options?: SessionOptions): Promise<InteractiveSession>;
 }
 export type RunOutcome = "completed" | "failed";
@@ -185,13 +211,171 @@ 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 {
+/** The runtime daemon's lifecycle state changed. `state` is a numeric `RuntimeState`. */
+export interface RuntimeStateChangedEvent {
+    readonly state: number;
+    readonly reason?: string | undefined;
+}
+/** Periodic runtime liveness signal. `state` is a numeric `RuntimeState`. */
+export interface RuntimeHeartbeatEvent {
+    readonly state: number;
+}
+/** A supervised process began executing. */
+export interface ProcessStartedEvent {
+    readonly pid: number;
+    readonly pgid: number;
+    readonly pidfd: boolean;
+    readonly executable: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    /** Wall clock at start, microseconds (decimal string). */
+    readonly startedAt: string;
+}
+/** A supervised process ended. `reason` is a numeric `ExitReason`. */
+export interface ProcessExitedEvent {
+    readonly exitCode?: number | undefined;
+    readonly signal?: number | undefined;
+    readonly reason: number;
+    /** Wall-clock duration, microseconds (decimal string). */
+    readonly durationMicros: string;
+}
+/**
+ * A run of process output. Raw bytes live in the artifact store (fetch byte-exact text via
+ * `record.scrollback()`); the event carries counts and a content hash. `stream` is a numeric
+ * `StreamKind` (stdout = 2, stderr = 3).
+ */
+export interface IoChunkEvent {
+    readonly stream: number;
+    readonly byteCount: string;
+    readonly streamOffset: string;
+    readonly contentAlgo?: string | undefined;
+    readonly contentHash?: string | undefined;
+    readonly transform?: {
+        readonly redacted: boolean;
+        readonly truncated: boolean;
+        readonly coalesced: boolean;
+        readonly originalByteCount?: string | undefined;
+    } | undefined;
+}
+/** The runtime dropped events under pressure. `priority` is a numeric `EventPriority`. */
+export interface TelemetryDroppedEvent {
+    readonly reason: string;
+    readonly count: string;
+    readonly priority: number;
+}
+/** Filesystem entry metadata attached to a change. `fileType` is a numeric `FileType`. */
+export interface FileEntryData {
+    readonly path: string;
+    readonly fileType: number;
+    readonly size: string;
+    readonly mtimeMicros: string;
+    readonly mode: number;
+    readonly hash?: string | undefined;
+    readonly symlinkTarget?: string | undefined;
+}
+/** A watched file changed. `kind` is a numeric `FileChangeKind`. */
+export interface FileChangeEvent {
+    readonly kind: number;
+    readonly path: string;
+    readonly renameFrom?: string | undefined;
+    readonly entry?: FileEntryData | undefined;
+    readonly certain: boolean;
+}
+/** The file watcher overflowed — changes under `root` may have been missed. */
+export interface FileWatchOverflowEvent {
+    readonly root: string;
+}
+/** A filesystem snapshot pass finished. */
+export interface FileSnapshotCompletedEvent {
+    readonly root: string;
+    readonly fileCount: string;
+}
+/** Aggregate before/after diff counts became available. */
+export interface FileDiffAvailableEvent {
+    readonly added: string;
+    readonly modified: string;
+    readonly deleted: string;
+    readonly renamed: string;
+}
+/** An outbound network request the run made. `scheme` is a numeric `NetworkScheme`. */
+export interface NetworkRequestEvent {
+    readonly scheme: number;
+    readonly method?: string | undefined;
+    readonly host: string;
+    readonly port: number;
+    readonly path?: string | undefined;
+    readonly status?: number | undefined;
+    readonly bytesSent: string;
+    readonly bytesReceived: string;
+    readonly durationMicros: string;
+}
+/** A network source the run touched — the raw material of a "sources the agent opened" trail. */
+export interface NetworkSourceObservedEvent {
+    readonly host: string;
+    readonly resolvedIps: readonly string[];
+    readonly port: number;
+    readonly scheme?: number | undefined;
+    readonly method?: string | undefined;
+    readonly path?: string | undefined;
+    readonly status?: number | undefined;
+}
+/** Fields shared by every timeline entry, independent of its kind. */
+export interface TimelineEntryBase {
     readonly sequence: bigint;
-    readonly kind: string;
     readonly occurredAt: string;
-    readonly data: unknown;
+    /** One-line human summary of the event. */
+    readonly summary: string;
+    /** Correlation id of the producing process, when attributable. */
+    readonly processId?: string | undefined;
 }
+/**
+ * A single ordered entry in the execution record's timeline, DISCRIMINATED by `kind`: switch on it
+ * and `data` narrows to the event's typed payload. The `"unknown"` case is the forward-compatibility
+ * path — it carries kinds newer than this SDK (or payloads that failed their schema) with the wire
+ * kind preserved in `rawKind` and the payload verbatim in `data`.
+ */
+export type TimelineEntry = (TimelineEntryBase & {
+    readonly kind: "runtimeStateChanged";
+    readonly data: RuntimeStateChangedEvent;
+}) | (TimelineEntryBase & {
+    readonly kind: "runtimeHeartbeat";
+    readonly data: RuntimeHeartbeatEvent;
+}) | (TimelineEntryBase & {
+    readonly kind: "processStarted";
+    readonly data: ProcessStartedEvent;
+}) | (TimelineEntryBase & {
+    readonly kind: "processExited";
+    readonly data: ProcessExitedEvent;
+}) | (TimelineEntryBase & {
+    readonly kind: "ioChunk";
+    readonly data: IoChunkEvent;
+}) | (TimelineEntryBase & {
+    readonly kind: "telemetryDropped";
+    readonly data: TelemetryDroppedEvent;
+}) | (TimelineEntryBase & {
+    readonly kind: "fileChange";
+    readonly data: FileChangeEvent;
+}) | (TimelineEntryBase & {
+    readonly kind: "fileWatchOverflow";
+    readonly data: FileWatchOverflowEvent;
+}) | (TimelineEntryBase & {
+    readonly kind: "fileSnapshotCompleted";
+    readonly data: FileSnapshotCompletedEvent;
+}) | (TimelineEntryBase & {
+    readonly kind: "fileDiffAvailable";
+    readonly data: FileDiffAvailableEvent;
+}) | (TimelineEntryBase & {
+    readonly kind: "networkRequest";
+    readonly data: NetworkRequestEvent;
+}) | (TimelineEntryBase & {
+    readonly kind: "networkSourceObserved";
+    readonly data: NetworkSourceObservedEvent;
+}) | (TimelineEntryBase & {
+    readonly kind: "unknown";
+    /** The kind as received on the wire — set when this SDK version doesn't model it. */
+    readonly rawKind: string;
+    readonly data: unknown;
+});
 /** A re-fold of the record up to some point — scrubable by sequence. */
 export interface RunReplay {
     readonly entries: readonly TimelineEntry[];
@@ -283,9 +467,96 @@ export interface Run {
     /** 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). */
+/** An interactive harness session over the live workspace (Phase 3). */
 export interface InteractiveSession {
     send(input: string): Promise<void>;
     output(): AsyncIterable<Uint8Array>;
     close(): Promise<void>;
 }
+/**
+ * Connected-account selection for inference — the same reference shape as workspace creation,
+ * minus GitHub (not a model provider). `true` means "my default account"; a string names one.
+ * Only claude accounts are supported today; a codex selection is rejected until Codex inference
+ * ships. SECURITY: only account references cross this surface — never token material.
+ */
+export interface InferenceCredentialsOptions {
+    /** Profile id whose claude binding applies when `claude` is not set explicitly. */
+    readonly profile?: string;
+    /** `true` for the caller's default claude account, or a string naming a specific one. */
+    readonly claude?: boolean | string;
+    /** Reserved — rejected until Codex inference ships. */
+    readonly codex?: boolean | string;
+}
+/** A caller-defined tool the model may call. `inputSchema` is a JSON Schema object, verbatim. */
+export interface InferenceToolDefinition {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: unknown;
+}
+/** A tool call the model made. Execute it YOUR side, then respond with an `InferenceToolResult`. */
+export interface InferenceToolCall {
+    readonly toolCallId: string;
+    readonly name: string;
+    readonly input: unknown;
+}
+/** Your result for one tool call, keyed by its `toolCallId`. */
+export interface InferenceToolResult {
+    readonly toolCallId: string;
+    readonly content: string;
+    readonly isError?: boolean;
+}
+/** The assistant turn: the final text (with parsed `json` when requested) or pending tool calls. */
+export type InferenceTurn = {
+    readonly type: "text";
+    readonly text: string;
+    readonly json?: unknown;
+} | {
+    readonly type: "toolCalls";
+    readonly calls: readonly InferenceToolCall[];
+};
+export interface InferenceUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+export interface InferenceResponse {
+    /** Continuation handle for the tool loop (held in memory server-side; expires after idle). */
+    readonly sessionId: string;
+    readonly turn: InferenceTurn;
+    /** Usage for the exchange, present on the final text turn. */
+    readonly usage?: InferenceUsage;
+}
+/** Starts a new inference exchange on a connected account. */
+export interface InferenceRespondOptions {
+    readonly prompt: string;
+    readonly system?: string;
+    readonly model?: string;
+    /** Upper bound on agentic turns within the exchange (server default 16). */
+    readonly maxTurns?: number;
+    readonly tools?: readonly InferenceToolDefinition[];
+    /** Structured output: reply as JSON (schema-constrained when `schema` is given). */
+    readonly responseFormat?: {
+        readonly type: "json";
+        readonly schema?: unknown;
+    };
+    readonly credentials: InferenceCredentialsOptions;
+}
+/** Continues an exchange by posting the results of the previous turn's tool calls. */
+export interface InferenceContinueOptions {
+    readonly sessionId: string;
+    readonly toolResults: readonly InferenceToolResult[];
+}
+/**
+ * Inference on connected accounts. The model call runs SERVER-SIDE through the official agent SDKs
+ * on the resolved account's credential (never raw model-API calls); the tool loop is CALLER-
+ * EXECUTED — a `toolCalls` turn parks server-side until you `respond()` with the results:
+ *
+ *   let response = await sealant.inference.respond({ prompt, tools, credentials: { claude: true } })
+ *   while (response.turn.type === "toolCalls") {
+ *     const toolResults = await runTools(response.turn.calls)
+ *     response = await sealant.inference.respond({ sessionId: response.sessionId, toolResults })
+ *   }
+ *   response.turn.text
+ */
+export interface InferenceNamespace {
+    respond(options: InferenceRespondOptions | InferenceContinueOptions): Promise<InferenceResponse>;
+}

package/dist/types.js

@@ -3,8 +3,8 @@
  *
  * 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.")
+ *   const workspace = await sealant.workspaces.create({ repository, harness: opencode() })
+ *   const run = await workspace.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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sealant/sdk",
-  "version": "0.3.1",
-  "description": "The fluent public SDK for Sealant — create a sandbox, run a harness, replay the record.",
+  "version": "0.5.0",
+  "description": "The fluent public SDK for Sealant — create a workspace, run a harness, replay the record.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -16,6 +16,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./effect": {
+      "types": "./dist/effect/index.d.ts",
+      "import": "./dist/effect/index.js"
     }
   },
   "publishConfig": {
@@ -23,7 +27,7 @@
   },
   "dependencies": {
     "effect": "^4.0.0-beta.85",
-    "@sealant/api-contracts": "^0.3.1"
+    "@sealant/api-contracts": "^0.5.0"
   },
   "devDependencies": {
     "@effect/vitest": "^4.0.0-beta.85",