@sealant/sdk 0.3.1 → 0.5.0

package/dist/effect/exec-workspace.d.ts

@@ -0,0 +1,5 @@
+import type { SdkContext } from "../facade/context.js";
+import type { WorkspaceInit } from "../facade/workspace.js";
+import type { WorkspaceExecOptions, WorkspaceExecResult } from "../types.js";
+/** The `workspace.exec()` implementation (Promise boundary over the Effect above). */
+export declare const execWorkspace: (ctx: SdkContext, init: WorkspaceInit, argv: readonly string[], options?: WorkspaceExecOptions | undefined) => Promise<WorkspaceExecResult>;

package/dist/effect/exec-workspace.js

@@ -0,0 +1,60 @@
+import { Effect } from "effect";
+import { SealantError } from "../errors.js";
+import { makeRun, toRunChangesData } from "../facade/run.js";
+import { execWorkspaceOp, getRunChangesOp, getRunOp, getRunScrollbackOp, getRunTimelineOp, } from "./operations.js";
+const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled"]);
+const POLL_INTERVAL = "500 millis";
+const EXEC_TIMEOUT_MS = 30 * 60 * 1_000;
+const isRecord = (value) => typeof value === "object" && value !== null;
+/**
+ * The exec'd command's process: the `processStarted` entry whose recorded executable matches, or the
+ * first one when attribution is imprecise (the record contains only processes this run exec'd).
+ */
+const findCommandProcessId = (entries, executable) => {
+    const match = entries.find((entry) => isRecord(entry.ref) && entry.ref["executable"] === executable);
+    return (match ?? entries[0])?.processId;
+};
+const readScrollback = (runId, processId, stream) => Effect.map(getRunScrollbackOp(runId, { processId, stream }), (response) => Buffer.from(response.contentBase64, "base64").toString("utf8"));
+const execWorkspaceEffect = (ctx, init, argv, options) => Effect.gen(function* () {
+    const [executable, ...args] = argv;
+    if (executable === undefined || executable.length === 0) {
+        return yield* Effect.fail(new SealantError("exec requires argv with at least the executable.", {
+            code: "invalid_argv",
+        }));
+    }
+    const created = yield* execWorkspaceOp(init.id, {
+        ownerUserId: ctx.config.hostLocal.ownerUserId,
+        commands: [{ executable, args, ...(options?.cwd === undefined ? {} : { cwd: options.cwd }) }],
+    });
+    const runId = created.runId;
+    // Block until the check run is terminal, polling the control plane (same shape as harness.run()).
+    const deadline = Date.now() + EXEC_TIMEOUT_MS;
+    let wire = created;
+    while (!TERMINAL_STATUSES.has(wire.status)) {
+        if (Date.now() > deadline) {
+            return yield* Effect.fail(new SealantError(`Timed out waiting for exec run ${runId} to complete.`, {
+                code: "exec_timeout",
+            }));
+        }
+        yield* Effect.sleep(POLL_INTERVAL);
+        wire = yield* getRunOp(runId);
+    }
+    // Exec framing: "completed" means every command executed and was recorded — anything else means
+    // the machinery broke and the exit code cannot be trusted, which IS the error case.
+    if (wire.status !== "completed") {
+        return yield* Effect.fail(new SealantError(`Workspace exec did not complete: ${wire.errorMessage ?? `run ${runId} is ${wire.status}`}`, { code: "exec_failed" }));
+    }
+    const started = yield* getRunTimelineOp(runId, { kinds: "processStarted" });
+    const processId = findCommandProcessId(started, executable);
+    const stdout = processId === undefined ? "" : yield* readScrollback(runId, processId, "stdout");
+    const stderr = processId === undefined ? "" : yield* readScrollback(runId, processId, "stderr");
+    const changes = toRunChangesData(yield* getRunChangesOp(runId));
+    return {
+        exitCode: wire.exitCode ?? -1,
+        stdout,
+        stderr,
+        run: makeRun(ctx, { wire, changes }),
+    };
+});
+/** The `workspace.exec()` implementation (Promise boundary over the Effect above). */
+export const execWorkspace = (ctx, init, argv, options) => ctx.runtime.run(execWorkspaceEffect(ctx, init, argv, options));

package/dist/effect/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @sealant/sdk/effect — the Effect-native core of the SDK, for consumers that are Effect end-to-end.
+ *
+ * The Promise facade (`@sealant/sdk`) is a thin wrapper over what this subpath exports directly:
+ *
+ *   - `SealantApiClient` + `sealantApiClientLayer` — the contract-derived control-plane client as an
+ *     Effect service. The client is generated from the `@sealant/api-contracts` `HttpApi`, so its
+ *     request/response types and tagged error channel are the contract's, by construction.
+ *   - The operation effects (`createWorkspaceOp`, `createRunOp`, `getRunTimelineOp`, …) — one per
+ *     contract endpoint, returning WIRE types on a typed error channel.
+ *   - `makeSdkRuntime` — the managed runtime the facade itself runs on, for consumers who want the
+ *     memoized layer build + `SealantError` mapping without hand-rolling a scope.
+ *   - The tagged contract errors (`WorkspaceNotFoundError`, `RunNotFoundError`, …) so failures can be
+ *     matched with `Effect.catchTag` instead of string-matching a squashed `SealantError`.
+ *
+ * Errors: effects composed from this subpath fail with the TYPED contract errors (plus Effect HTTP
+ * client/schema errors) — nothing is squashed. The plain `SealantError` classes only enter play via
+ * `makeSdkRuntime`, which maps the typed channel at the Promise boundary exactly like the facade.
+ */
+export { SealantApiClient, sealantApiClientLayer } from "./api-client.js";
+export type { ControlPlaneClient } from "./api-client.js";
+export * from "./operations.js";
+export { makeSdkRuntime } from "./runtime.js";
+export type { SdkRuntime, SdkServices } from "./runtime.js";
+export { resolveInternalConfig } from "../internal/config.js";
+export type { SealantHostLocalConfig, SealantInternalConfig } from "../internal/config.js";
+export { InferenceBadRequestError, InferenceConflictError, InferenceInternalServerError, InferenceNotFoundError, InferenceUnavailableError, RunBadRequestError, RunInternalServerError, RunNotFoundError, WorkspaceBadGatewayError, WorkspaceBadRequestError, WorkspaceConflictError, WorkspaceForbiddenError, WorkspaceInternalServerError, WorkspaceNotFoundError, WorkspaceServiceUnavailableError, WorkspaceUnauthorizedError, } from "@sealant/api-contracts";

package/dist/effect/index.js

@@ -0,0 +1,31 @@
+/**
+ * @sealant/sdk/effect — the Effect-native core of the SDK, for consumers that are Effect end-to-end.
+ *
+ * The Promise facade (`@sealant/sdk`) is a thin wrapper over what this subpath exports directly:
+ *
+ *   - `SealantApiClient` + `sealantApiClientLayer` — the contract-derived control-plane client as an
+ *     Effect service. The client is generated from the `@sealant/api-contracts` `HttpApi`, so its
+ *     request/response types and tagged error channel are the contract's, by construction.
+ *   - The operation effects (`createWorkspaceOp`, `createRunOp`, `getRunTimelineOp`, …) — one per
+ *     contract endpoint, returning WIRE types on a typed error channel.
+ *   - `makeSdkRuntime` — the managed runtime the facade itself runs on, for consumers who want the
+ *     memoized layer build + `SealantError` mapping without hand-rolling a scope.
+ *   - The tagged contract errors (`WorkspaceNotFoundError`, `RunNotFoundError`, …) so failures can be
+ *     matched with `Effect.catchTag` instead of string-matching a squashed `SealantError`.
+ *
+ * Errors: effects composed from this subpath fail with the TYPED contract errors (plus Effect HTTP
+ * client/schema errors) — nothing is squashed. The plain `SealantError` classes only enter play via
+ * `makeSdkRuntime`, which maps the typed channel at the Promise boundary exactly like the facade.
+ */
+// The contract-derived client service + layer.
+export { SealantApiClient, sealantApiClientLayer } from "./api-client.js";
+// One operation effect per contract endpoint (wire types in, wire types out).
+export * from "./operations.js";
+// The managed runtime the Promise facade runs on.
+export { makeSdkRuntime } from "./runtime.js";
+// The config the layer/runtime constructors take, and the resolver from the public `SealantConfig`.
+export { resolveInternalConfig } from "../internal/config.js";
+// The typed contract errors carried on the client's failure channel (workspaces + runs +
+// inference — the groups the operations above call). Re-exported so Effect consumers don't need to
+// depend on the contracts package directly to `Effect.catchTag` a failure.
+export { InferenceBadRequestError, InferenceConflictError, InferenceInternalServerError, InferenceNotFoundError, InferenceUnavailableError, RunBadRequestError, RunInternalServerError, RunNotFoundError, WorkspaceBadGatewayError, WorkspaceBadRequestError, WorkspaceConflictError, WorkspaceForbiddenError, WorkspaceInternalServerError, WorkspaceNotFoundError, WorkspaceServiceUnavailableError, WorkspaceUnauthorizedError, } from "@sealant/api-contracts";

package/dist/effect/operations.d.ts

@@ -1,6 +1,6 @@
 import { Effect } from "effect";
 import { SealantApiClient } from "./api-client.js";
-export declare const createSandboxOp: (payload: {
+export declare const createWorkspaceOp: (payload: {
     readonly ownerUserId: string;
     readonly registryId: string;
     readonly repository: string;
@@ -26,15 +26,15 @@ export declare const createSandboxOp: (payload: {
     } | undefined;
     readonly spec: unknown;
 }, idempotencyKey?: string | undefined) => Effect.Effect<{
-    readonly sandboxId: string;
+    readonly workspaceId: string;
     readonly name: string;
     readonly status: "cancelled" | "failed" | "queued" | "ready" | "running";
     readonly registryId: string;
     readonly repository: string;
     readonly tag: string;
-}, import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").SandboxBadGatewayError | import("@sealant/api-contracts").SandboxBadRequestError | import("@sealant/api-contracts").SandboxConflictError | import("@sealant/api-contracts").SandboxForbiddenError | import("@sealant/api-contracts").SandboxInternalServerError | import("@sealant/api-contracts").SandboxNotFoundError | import("@sealant/api-contracts").SandboxServiceUnavailableError | import("effect/Schema").SchemaError, SealantApiClient>;
-export declare const getSandboxOp: (sandboxId: string) => Effect.Effect<{
-    readonly sandboxId: string;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadGatewayError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceConflictError | import("@sealant/api-contracts").WorkspaceForbiddenError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError | import("@sealant/api-contracts").WorkspaceServiceUnavailableError, SealantApiClient>;
+export declare const getWorkspaceOp: (workspaceId: string) => Effect.Effect<{
+    readonly workspaceId: string;
     readonly name: string;
     readonly ownerUserId: string;
     readonly status: "cancelled" | "failed" | "queued" | "ready" | "running";
@@ -62,14 +62,14 @@ export declare const getSandboxOp: (sandboxId: string) => Effect.Effect<{
     readonly startedAt?: string | undefined;
     readonly finishedAt?: string | undefined;
     readonly spec?: unknown;
-}, unknown, SealantApiClient>;
-export declare const listSandboxesOp: (query: {
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError, SealantApiClient>;
+export declare const listWorkspacesOp: (query: {
     readonly ownerUserId: string;
     readonly status?: "cancelled" | "failed" | "queued" | "ready" | "running" | undefined;
     readonly limit?: string | undefined;
 }) => Effect.Effect<{
     readonly items: readonly {
-        readonly sandboxId: string;
+        readonly workspaceId: string;
         readonly name: string;
         readonly ownerUserId: string;
         readonly status: "cancelled" | "failed" | "queued" | "ready" | "running";
@@ -97,9 +97,32 @@ export declare const listSandboxesOp: (query: {
         readonly startedAt?: string | undefined;
         readonly finishedAt?: string | undefined;
     }[];
-}, import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").SandboxBadRequestError | import("@sealant/api-contracts").SandboxInternalServerError | import("effect/Schema").SchemaError, SealantApiClient>;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceInternalServerError, SealantApiClient>;
+export declare const execWorkspaceOp: (workspaceId: string, payload: {
+    readonly ownerUserId: string;
+    readonly commands: readonly {
+        readonly executable: string;
+        readonly args: readonly string[];
+        readonly cwd?: string | undefined;
+    }[];
+}) => Effect.Effect<{
+    readonly runId: string;
+    readonly workspaceId: string;
+    readonly attemptId?: string | undefined;
+    readonly ownerUserId: string;
+    readonly harnessId: string;
+    readonly mode: "interactive" | "one-shot";
+    readonly status: "cancelled" | "completed" | "failed" | "queued" | "running";
+    readonly prompt?: string | undefined;
+    readonly exitCode?: number | undefined;
+    readonly errorMessage?: string | undefined;
+    readonly startedAt?: string | undefined;
+    readonly finishedAt?: string | undefined;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceConflictError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError, SealantApiClient>;
 export declare const createRunOp: (payload: {
-    readonly sandboxId: string;
+    readonly workspaceId: string;
     readonly harnessId: string;
     readonly ownerUserId: string;
     readonly mode?: "interactive" | "one-shot" | undefined;
@@ -112,7 +135,7 @@ export declare const createRunOp: (payload: {
     } | undefined;
 }) => Effect.Effect<{
     readonly runId: string;
-    readonly sandboxId: string;
+    readonly workspaceId: string;
     readonly attemptId?: string | undefined;
     readonly ownerUserId: string;
     readonly harnessId: string;
@@ -125,10 +148,10 @@ export declare const createRunOp: (payload: {
     readonly finishedAt?: string | undefined;
     readonly createdAt: string;
     readonly updatedAt: string;
-}, unknown, SealantApiClient>;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").RunBadRequestError | import("@sealant/api-contracts").RunInternalServerError | import("@sealant/api-contracts").RunNotFoundError | import("effect/Schema").SchemaError, SealantApiClient>;
 export declare const getRunOp: (runId: string) => Effect.Effect<{
     readonly runId: string;
-    readonly sandboxId: string;
+    readonly workspaceId: string;
     readonly attemptId?: string | undefined;
     readonly ownerUserId: string;
     readonly harnessId: string;
@@ -141,16 +164,16 @@ export declare const getRunOp: (runId: string) => Effect.Effect<{
     readonly finishedAt?: string | undefined;
     readonly createdAt: string;
     readonly updatedAt: string;
-}, unknown, SealantApiClient>;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").RunInternalServerError | import("@sealant/api-contracts").RunNotFoundError | import("effect/Schema").SchemaError, SealantApiClient>;
 export declare const listRunsOp: (query: {
-    readonly sandboxId?: string | undefined;
+    readonly workspaceId?: string | undefined;
     readonly ownerUserId?: string | undefined;
     readonly status?: "cancelled" | "completed" | "failed" | "queued" | "running" | undefined;
     readonly limit?: string | undefined;
 }) => Effect.Effect<{
     readonly items: readonly {
         readonly runId: string;
-        readonly sandboxId: string;
+        readonly workspaceId: string;
         readonly attemptId?: string | undefined;
         readonly ownerUserId: string;
         readonly harnessId: string;
@@ -177,7 +200,7 @@ export declare const updateRunOp: (runId: string, payload: {
     }[] | undefined;
 }) => Effect.Effect<{
     readonly runId: string;
-    readonly sandboxId: string;
+    readonly workspaceId: string;
     readonly attemptId?: string | undefined;
     readonly ownerUserId: string;
     readonly harnessId: string;
@@ -190,7 +213,7 @@ export declare const updateRunOp: (runId: string, payload: {
     readonly finishedAt?: string | undefined;
     readonly createdAt: string;
     readonly updatedAt: string;
-}, unknown, SealantApiClient>;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").RunBadRequestError | import("@sealant/api-contracts").RunInternalServerError | import("@sealant/api-contracts").RunNotFoundError | import("effect/Schema").SchemaError, SealantApiClient>;
 export declare const getRunTimelineOp: (runId: string, query: {
     readonly fromSequence?: string | undefined;
     readonly toSequence?: string | undefined;
@@ -206,7 +229,7 @@ export declare const getRunTimelineOp: (runId: string, query: {
     readonly processId?: string | undefined;
     readonly captureMethod: number;
     readonly confidence: number;
-}[], unknown, SealantApiClient>;
+}[], import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").RunBadRequestError | import("@sealant/api-contracts").RunInternalServerError | import("@sealant/api-contracts").RunNotFoundError | import("effect/Schema").SchemaError, SealantApiClient>;
 export declare const getRunScrollbackOp: (runId: string, query: {
     readonly processId: string;
     readonly stream: "stderr" | "stdout";
@@ -216,7 +239,7 @@ export declare const getRunScrollbackOp: (runId: string, query: {
     readonly stream: "stderr" | "stdout";
     readonly byteCount: number;
     readonly contentBase64: string;
-}, unknown, SealantApiClient>;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").RunBadRequestError | import("@sealant/api-contracts").RunInternalServerError | import("@sealant/api-contracts").RunNotFoundError | import("effect/Schema").SchemaError, SealantApiClient>;
 export declare const getRunLossOp: (runId: string) => Effect.Effect<{
     readonly runId: string;
     readonly droppedEventCount: string;
@@ -231,7 +254,7 @@ export declare const getRunLossOp: (runId: string) => Effect.Effect<{
         readonly detectedVia: "gap" | "marker";
         readonly reason?: string | undefined;
     }[];
-}, unknown, SealantApiClient>;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").RunInternalServerError | import("@sealant/api-contracts").RunNotFoundError | import("effect/Schema").SchemaError, SealantApiClient>;
 export declare const getRunChangesOp: (runId: string) => Effect.Effect<{
     readonly files: readonly {
         readonly path: string;
@@ -239,4 +262,49 @@ export declare const getRunChangesOp: (runId: string) => Effect.Effect<{
         readonly oldPath?: string | undefined;
     }[];
     readonly diff: string;
-}, unknown, SealantApiClient>;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").RunInternalServerError | import("@sealant/api-contracts").RunNotFoundError | import("effect/Schema").SchemaError, SealantApiClient>;
+export declare const inferenceRespondOp: (payload: {
+    readonly ownerUserId: string;
+    readonly credentials?: {
+        readonly profileId?: string | undefined;
+        readonly claude?: string | undefined;
+        readonly codex?: string | undefined;
+    } | undefined;
+    readonly prompt?: string | undefined;
+    readonly system?: string | undefined;
+    readonly model?: string | undefined;
+    readonly maxTurns?: number | undefined;
+    readonly tools?: readonly {
+        readonly name: string;
+        readonly description?: string | undefined;
+        readonly inputSchema: unknown;
+    }[] | undefined;
+    readonly responseFormat?: {
+        readonly type: "json";
+        readonly schema?: unknown;
+    } | undefined;
+    readonly sessionId?: string | undefined;
+    readonly toolResults?: readonly {
+        readonly toolCallId: string;
+        readonly content: string;
+        readonly isError?: boolean | undefined;
+    }[] | undefined;
+}) => Effect.Effect<{
+    readonly sessionId: string;
+    readonly turn: {
+        readonly type: "text";
+        readonly text: string;
+        readonly json?: unknown;
+    } | {
+        readonly type: "toolCalls";
+        readonly calls: readonly {
+            readonly toolCallId: string;
+            readonly name: string;
+            readonly input: unknown;
+        }[];
+    };
+    readonly usage?: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    } | undefined;
+}, import("effect/unstable/http/HttpClientError").HttpClientError | import("@sealant/api-contracts").InferenceBadRequestError | import("@sealant/api-contracts").InferenceConflictError | import("@sealant/api-contracts").InferenceInternalServerError | import("@sealant/api-contracts").InferenceNotFoundError | import("@sealant/api-contracts").InferenceUnavailableError | import("effect/Schema").SchemaError, SealantApiClient>;

package/dist/effect/operations.js

@@ -1,12 +1,13 @@
 import { Effect } from "effect";
 import { SealantApiClient } from "./api-client.js";
-// ---- sandboxes ----
-export const createSandboxOp = (payload, idempotencyKey) => Effect.flatMap(SealantApiClient, (client) => client.sandboxes.createSandbox({
+// ---- workspaces ----
+export const createWorkspaceOp = (payload, idempotencyKey) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.createWorkspace({
     payload,
     headers: idempotencyKey === undefined ? {} : { "idempotency-key": idempotencyKey },
 }));
-export const getSandboxOp = (sandboxId) => Effect.flatMap(SealantApiClient, (client) => client.sandboxes.getSandbox({ params: { sandboxId } }));
-export const listSandboxesOp = (query) => Effect.flatMap(SealantApiClient, (client) => client.sandboxes.listSandboxes({ query }));
+export const getWorkspaceOp = (workspaceId) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.getWorkspace({ params: { workspaceId } }));
+export const listWorkspacesOp = (query) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.listWorkspaces({ query }));
+export const execWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.execWorkspace({ params: { workspaceId }, payload }));
 // ---- runs ----
 export const createRunOp = (payload) => Effect.flatMap(SealantApiClient, (client) => client.runs.createRun({ payload }));
 export const getRunOp = (runId) => Effect.flatMap(SealantApiClient, (client) => client.runs.getRun({ params: { runId } }));
@@ -16,3 +17,5 @@ export const getRunTimelineOp = (runId, query) => Effect.flatMap(SealantApiClien
 export const getRunScrollbackOp = (runId, query) => Effect.flatMap(SealantApiClient, (client) => client.runs.getRunScrollback({ params: { runId }, query }));
 export const getRunLossOp = (runId) => Effect.flatMap(SealantApiClient, (client) => client.runs.getRunLoss({ params: { runId } }));
 export const getRunChangesOp = (runId) => Effect.flatMap(SealantApiClient, (client) => client.runs.getRunChanges({ params: { runId } }));
+// ---- inference ----
+export const inferenceRespondOp = (payload) => Effect.flatMap(SealantApiClient, (client) => client.inference.respond({ payload }));

package/dist/effect/run-harness.d.ts

@@ -1,5 +1,5 @@
-import type { RunHarnessFn } from "../facade/sandbox.js";
-/** The BLOCKING `harness.run()` implementation, registered into the Sandbox facade by the client. */
+import type { RunHarnessFn } from "../facade/workspace.js";
+/** The BLOCKING `harness.run()` implementation, registered into the Workspace facade by the client. */
 export declare const runHarness: RunHarnessFn;
 /**
  * The NON-BLOCKING `harness.start()` implementation: register the run and return the live handle

package/dist/effect/run-harness.js

@@ -17,16 +17,16 @@ const POLL_INTERVAL = "500 millis";
 const RUN_TIMEOUT_MS = 30 * 60 * 1_000;
 /**
  * Registers the run WITH the harness command — the control plane executes it server-side (the worker
- * docker-execs it and ingests telemetry). The cwd is the sandbox repo, which the worker defaults to.
+ * docker-execs it and ingests telemetry). The cwd is the workspace repo, which the worker defaults to.
  */
 const createHarnessRunEffect = (ctx, init, prompt) => Effect.gen(function* () {
     const harness = init.harness;
     if (harness === undefined) {
-        return yield* Effect.fail(new SealantError("This sandbox handle has no harness; use the handle returned by sandboxes.create().", { code: "harness_required" }));
+        return yield* Effect.fail(new SealantError("This workspace handle has no harness; use the handle returned by workspaces.create().", { code: "harness_required" }));
     }
     const command = harness.buildRunCommand(prompt);
     return yield* createRunOp({
-        sandboxId: init.id,
+        workspaceId: init.id,
         ownerUserId: ctx.config.hostLocal.ownerUserId,
         harnessId: harness.id,
         mode: "one-shot",
@@ -53,7 +53,7 @@ const runHarnessEffect = (ctx, init, prompt) => Effect.gen(function* () {
     const changes = toRunChangesData(yield* getRunChangesOp(runId));
     return makeRun(ctx, { wire, changes });
 });
-/** The BLOCKING `harness.run()` implementation, registered into the Sandbox facade by the client. */
+/** The BLOCKING `harness.run()` implementation, registered into the Workspace facade by the client. */
 export const runHarness = (ctx, init, prompt) => ctx.runtime.run(runHarnessEffect(ctx, init, prompt));
 /**
  * The NON-BLOCKING `harness.start()` implementation: register the run and return the live handle

package/dist/errors.d.ts

@@ -13,7 +13,7 @@ export declare class SealantError extends Error {
         readonly cause?: unknown;
     });
 }
-/** A typed control/transport failure from the sandbox runtime daemon. */
+/** A typed control/transport failure from the workspace runtime daemon. */
 export declare class SealantRuntimeError extends SealantError {
     readonly name = "SealantRuntimeError";
     constructor(message: string, options?: {

package/dist/errors.js

@@ -13,7 +13,7 @@ export class SealantError extends Error {
         this.code = options?.code ?? "sealant_error";
     }
 }
-/** A typed control/transport failure from the sandbox runtime daemon. */
+/** A typed control/transport failure from the workspace runtime daemon. */
 export class SealantRuntimeError extends SealantError {
     name = "SealantRuntimeError";
     constructor(message, options) {

package/dist/facade/record.d.ts

@@ -1,5 +1,21 @@
-import type { RunCommand, RunRecord } from "../types.js";
+import type { RunCommand, RunRecord, TimelineEntry } from "../types.js";
 import type { SdkContext } from "./context.js";
+/**
+ * Maps a wire entry to the public DISCRIMINATED entry: the contract's payload schemas fold
+ * `(kind, ref)` into typed `data`, degrading to the `unknown` case (raw kind + payload preserved)
+ * for kinds newer than this SDK or payloads that fail their schema. Exported for tests.
+ */
+export declare const toTimelineEntry: (wire: {
+    readonly eventId: string;
+    readonly sequence: string;
+    readonly kind: string;
+    readonly occurredAt: string;
+    readonly summary: string;
+    readonly ref?: unknown;
+    readonly processId?: string | undefined;
+    readonly captureMethod: number;
+    readonly confidence: number;
+}) => TimelineEntry;
 /**
  * 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

package/dist/facade/record.js

@@ -1,3 +1,11 @@
+/**
+ * The `RunRecord` facade — the execution record as the SDK exposes it. Backed by the run/record
+ * contract endpoints (`client.runs.*`), it maps the wire shapes to the public types: decimal-string
+ * sequences become `bigint`, base64 scrollback becomes `Uint8Array`. `replay()`/`timeline()`/
+ * `scrollback()`/`loss()`/`summary()`/`stream()` are live; the time-travel folds are typed but
+ * reject until their read models land (Phase 1).
+ */
+import { decodeRecordEventPayload, } from "@sealant/api-contracts";
 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.
@@ -6,11 +14,17 @@ 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) => ({
+/**
+ * Maps a wire entry to the public DISCRIMINATED entry: the contract's payload schemas fold
+ * `(kind, ref)` into typed `data`, degrading to the `unknown` case (raw kind + payload preserved)
+ * for kinds newer than this SDK or payloads that fail their schema. Exported for tests.
+ */
+export const toTimelineEntry = (wire) => ({
     sequence: BigInt(wire.sequence),
-    kind: wire.kind,
     occurredAt: wire.occurredAt,
-    data: { summary: wire.summary, ...(wire.ref === undefined ? {} : { ref: wire.ref }) },
+    summary: wire.summary,
+    ...(wire.processId === undefined ? {} : { processId: wire.processId }),
+    ...decodeRecordEventPayload(wire.kind, wire.ref),
 });
 const toLossReport = (wire) => ({
     complete: !wire.earlyClose && wire.droppedEventCount === "0" && wire.sequenceGapCount === 0,

package/dist/facade/run.d.ts

@@ -1,6 +1,6 @@
 /**
  * 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
+ * (read a past run, record outlives the workspace), 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);

package/dist/facade/{sandbox.d.ts → workspace.d.ts}

@@ -1,18 +1,18 @@
-import type { Harness, Sandbox, SandboxStatus } from "../types.js";
+import type { Harness, Workspace, WorkspaceStatus } from "../types.js";
 import type { SdkContext } from "./context.js";
-export interface SandboxInit {
+export interface WorkspaceInit {
     readonly id: string;
     readonly name: string;
-    readonly status: SandboxStatus;
+    readonly status: WorkspaceStatus;
     /** 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
+ * avoid a static dependency cycle (workspace <-> 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 type RunHarnessFn = (ctx: SdkContext, init: WorkspaceInit, 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;
@@ -20,4 +20,4 @@ export interface HarnessExecutors {
     readonly start: RunHarnessFn;
 }
 export declare const registerHarnessExecutors: (executors: HarnessExecutors) => void;
-export declare const makeSandbox: (ctx: SdkContext, init: SandboxInit) => Sandbox;
+export declare const makeWorkspace: (ctx: SdkContext, init: WorkspaceInit) => Workspace;

package/dist/facade/{sandbox.js → workspace.js}

@@ -1,4 +1,5 @@
-import { getSandboxOp } from "../effect/operations.js";
+import { execWorkspace } from "../effect/exec-workspace.js";
+import { getWorkspaceOp } from "../effect/operations.js";
 import { SealantError, SealantNotImplementedError } from "../errors.js";
 const FAILED_STATUSES = new Set(["failed", "cancelled"]);
 const READY_POLL_INTERVAL_MS = 2_000;
@@ -8,7 +9,7 @@ let harnessExecutors;
 export const registerHarnessExecutors = (executors) => {
     harnessExecutors = executors;
 };
-export const makeSandbox = (ctx, init) => {
+export const makeWorkspace = (ctx, init) => {
     const harness = {
         run: (prompt, options) => {
             if (harnessExecutors === undefined) {
@@ -24,36 +25,37 @@ export const makeSandbox = (ctx, init) => {
         },
         session: () => Promise.reject(new SealantNotImplementedError("harness.session (interactive, Phase 3)")),
     };
-    const sandbox = {
+    const workspace = {
         id: init.id,
         name: init.name,
         status: async () => {
-            const details = await ctx.runtime.run(getSandboxOp(init.id));
+            const details = await ctx.runtime.run(getWorkspaceOp(init.id));
             return details.status;
         },
         ready: async () => {
             const deadline = Date.now() + READY_TIMEOUT_MS;
             for (;;) {
-                const details = await ctx.runtime.run(getSandboxOp(init.id));
+                const details = await ctx.runtime.run(getWorkspaceOp(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).
+                // in-workspace 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;
+                    return workspace;
                 }
                 if (FAILED_STATUSES.has(details.status)) {
-                    throw new SealantError(`Sandbox ${init.id} reached terminal status "${details.status}" before becoming ready.`, { code: "sandbox_not_ready" });
+                    throw new SealantError(`Workspace ${init.id} reached terminal status "${details.status}" before becoming ready.`, { code: "workspace_not_ready" });
                 }
                 if (Date.now() > deadline) {
-                    throw new SealantError(`Timed out waiting for sandbox ${init.id} to become ready.`, {
-                        code: "sandbox_ready_timeout",
+                    throw new SealantError(`Timed out waiting for workspace ${init.id} to become ready.`, {
+                        code: "workspace_ready_timeout",
                     });
                 }
                 await delay(READY_POLL_INTERVAL_MS);
             }
         },
         harness,
-        // Poll-backed lifecycle stream: emit a coarse event on each status transition until the sandbox
+        exec: (argv, options) => execWorkspace(ctx, init, argv, options),
+        // Poll-backed lifecycle stream: emit a coarse event on each status transition until the workspace
         // reaches a terminal/ready state. Swaps to SSE over Postgres LISTEN/NOTIFY in Stage 5 (same shape).
         events: () => {
             const ctxRun = ctx.runtime;
@@ -61,13 +63,13 @@ export const makeSandbox = (ctx, init) => {
                 let lastStatus;
                 const deadline = Date.now() + READY_TIMEOUT_MS;
                 for (;;) {
-                    const details = await ctxRun.run(getSandboxOp(init.id));
+                    const details = await ctxRun.run(getWorkspaceOp(init.id));
                     if (details.status !== lastStatus) {
                         lastStatus = details.status;
                         yield {
                             type: `status.${details.status}`,
                             occurredAt: new Date().toISOString(),
-                            message: `Sandbox status: ${details.status}`,
+                            message: `Workspace status: ${details.status}`,
                         };
                     }
                     if (details.status === "ready" || FAILED_STATUSES.has(details.status)) {
@@ -81,9 +83,9 @@ export const makeSandbox = (ctx, init) => {
             }
             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)")),
+        stop: () => Promise.reject(new SealantNotImplementedError("workspace.stop (lifecycle, Phase 3)")),
+        restart: () => Promise.reject(new SealantNotImplementedError("workspace.restart (lifecycle, Phase 3)")),
+        expire: () => Promise.reject(new SealantNotImplementedError("workspace.expire (lifecycle, Phase 3)")),
     };
-    return sandbox;
+    return workspace;
 };

package/dist/harness.d.ts

@@ -4,7 +4,7 @@
  *
  * 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").
+ * the baked workspace 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.
  */