@sealant/sdk 0.4.0 → 0.5.0

package/README.md

@@ -20,8 +20,23 @@ await run.record.replay();
 ## Design
 
 - **Plain-Promise facade over an Effect core.** The default export is ordinary `async`/`await`. The
-  Effect-native core (services, `Stream`s, typed errors) will be reachable via the
-  `@sealant/sdk/effect` subpath for power users.
+  Effect-native core is reachable via the `@sealant/sdk/effect` subpath for consumers that are
+  Effect end-to-end: the contract-derived client as a service, one operation effect per endpoint,
+  and the typed contract errors on the failure channel (no squashing) —
+
+  ```ts
+  import { Effect } from "effect";
+  import { getRunOp, resolveInternalConfig, sealantApiClientLayer } from "@sealant/sdk/effect";
+
+  const layer = sealantApiClientLayer(resolveInternalConfig({ baseUrl: "http://localhost:8080" }));
+
+  const status = getRunOp("run_123").pipe(
+    Effect.map((run) => run.status),
+    Effect.catchTag("RunNotFoundError", () => Effect.succeed("gone" as const)),
+    Effect.provide(layer),
+  );
+  ```
+
 - **Decoupled public types.** The types in [`src/types.ts`](src/types.ts) are hand-written and kept
   independent of the Effect-core and `@sealant/telemetry` internal shapes, so the public surface
   stays stable across internal change. The whole surface is typed now, including operations not yet
@@ -29,6 +44,46 @@ await run.record.replay();
 - **Harness-neutral.** `opencode()`, `codex()`, `claudeCode()`, and `customHarness()` are thin
   client values describing how to invoke a harness one-shot.
 
+## Deterministic exec
+
+Run a command in the workspace with no agent in the loop — recorded into a run record like any other
+process:
+
+```ts
+const check = await workspace.exec(["pnpm", "test"], { cwd: "/workspace/repo" });
+check.exitCode; // the check datum — a NONZERO exit RESOLVES (that's the point)
+check.stdout; // full stdout, decoded
+check.run.record; // the durable evidence
+
+// A causal proof is three execs with three recorded exit codes:
+const base = await workspace.exec(["pnpm", "test"]); // fails
+// ...apply the fix...
+const head = await workspace.exec(["pnpm", "test"]); // passes
+```
+
+`exec()` rejects only when the execution machinery itself broke (workspace gone, transport dropped)
+— i.e. when the exit code cannot be trusted. The underlying endpoint
+(`POST /v1/workspaces/:id/exec`) accepts an ordered **list** of commands recorded as one check run;
+the SDK surface starts with the single-command form.
+
+## Typed record events
+
+Timeline reads are discriminated by `kind` — switch on it and `data` narrows to the event's typed
+payload (all 12 recorded kinds: process, io, file, network, runtime, and loss events):
+
+```ts
+for await (const entry of run.record.timeline()) {
+  if (entry.kind === "networkSourceObserved") {
+    entry.data.host; // typed — the raw material of a "sources the agent opened" trail
+    entry.data.status;
+  }
+}
+```
+
+Forward compatibility is a case, not an error: kinds newer than your SDK version (and payloads that
+fail their schema) arrive as `{ kind: "unknown", rawKind, data }` with everything preserved. Wire
+conventions carry through: uint64 fields are decimal strings, protocol enums are numbers.
+
 ## Connected-account credentials
 
 Attach the caller's connected Claude / Codex / GitHub accounts to a workspace so the harness
@@ -48,13 +103,53 @@ field wins over the profile's binding for that provider. Only account references
 surface — secret material never does; the control plane resolves references to encrypted credentials
 and injects them at launch.
 
+## Inference on connected accounts
+
+Run short, tool-calling inference loops on the caller's own subscription — server-side, through the
+official agent SDKs (never raw model-API calls on stored credentials), with the tool loop executed
+on YOUR side:
+
+```ts
+let response = await sealant.inference.respond({
+  prompt: "Compile a review brief from this run record.",
+  tools: [
+    {
+      name: "get_timeline",
+      inputSchema: { type: "object", properties: { runId: { type: "string" } } },
+    },
+  ],
+  responseFormat: { type: "json", schema: briefSchema },
+  credentials: { claude: true },
+});
+
+while (response.turn.type === "toolCalls") {
+  const toolResults = await Promise.all(
+    response.turn.calls.map(async (call) => ({
+      toolCallId: call.toolCallId,
+      content: await runTool(call.name, call.input),
+    })),
+  );
+  response = await sealant.inference.respond({ sessionId: response.sessionId, toolResults });
+}
+
+response.turn.json; // schema-constrained result
+```
+
+Only account references cross the surface — the control plane resolves and decrypts server-side and
+invokes the official Claude Agent SDK with the account's own subscription token. Claude accounts
+only for now (Codex inference is a stated follow-up); sessions are held in memory by the control
+plane and expire after a few idle minutes, so handle a 404 on continuation by restarting the
+exchange.
+
 ## Status
 
 The core loop is real: `workspaces.create()`/`get()`/`list()`, `ready()`, blocking `harness.run()`
 and non-blocking `harness.start()` (run execution happens server-side; the SDK is a thin HTTP
-client), `runs.get()`, and the record read surface — `replay()`, `timeline()`, `scrollback()`,
-`commands()`, `transcript()`, `stream()` (poll-backed), `loss()`, `summary()`, plus captured
-`changes` (files + diff) settled by `run()`/`wait()`.
+client), deterministic `workspace.exec()`, `inference.respond()` (connected-account inference with a
+caller-executed tool loop), `runs.get()`, and the record read surface — `replay()`, `timeline()`
+(typed, kind-discriminated entries), `scrollback()`, `commands()`, `transcript()`, `stream()`
+(poll-backed), `loss()`, `summary()`, plus captured `changes` (files + diff) settled by
+`run()`/`wait()`. The Effect-native core ships at `@sealant/sdk/effect`.
 
 Still typed stubs pending their read models / endpoints: `artifacts.get()` and the time-travel folds
 `fileTreeAt()`/`processTreeAt()` (Phase 1), and `harness.session()` + workspace lifecycle

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { CreateOptions, ListOptions, Run, Workspace, SealantConfig } from "./types.js";
+import type { CreateOptions, InferenceNamespace, ListOptions, Run, Workspace, SealantConfig } from "./types.js";
 export declare class Sealant {
     #private;
     constructor(config: SealantConfig);
@@ -10,6 +10,11 @@ export declare class Sealant {
         get: (id: string) => Promise<Workspace>;
         list: (options?: ListOptions | undefined) => Promise<readonly Workspace[]>;
     };
+    /**
+     * Inference on connected accounts — server-side via the official agent SDKs, never raw model-API
+     * calls. Tool calls park server-side; execute them here and `respond()` with the results.
+     */
+    readonly inference: InferenceNamespace;
     /** Runs by id — so a record can be replayed long after its workspace is gone. */
     readonly runs: {
         get: (runId: string) => Promise<Run>;

package/dist/client.js

@@ -10,7 +10,7 @@
  * stable surface and reject with `SealantNotImplementedError` so callers can compile and wire
  * against the final shape today.
  */
-import { createWorkspaceOp, getRunOp, getWorkspaceOp, listWorkspacesOp, } from "./effect/operations.js";
+import { createWorkspaceOp, getRunOp, getWorkspaceOp, inferenceRespondOp, listWorkspacesOp, } from "./effect/operations.js";
 import { runHarness, startHarness } from "./effect/run-harness.js";
 import { makeSdkRuntime } from "./effect/runtime.js";
 import { SealantError } from "./errors.js";
@@ -18,6 +18,7 @@ import { makeRun } from "./facade/run.js";
 import { makeWorkspace, registerHarnessExecutors } from "./facade/workspace.js";
 import { buildCreateWorkspaceRequest } from "./internal/blueprint.js";
 import { resolveInternalConfig } from "./internal/config.js";
+import { buildInferenceRespondRequest, mapInferenceResponse } from "./internal/inference.js";
 // Wire the run-execution implementations into the Workspace facade (the injection point exists to
 // break the workspace <-> run-harness import cycle; the client is the composition root).
 registerHarnessExecutors({ run: runHarness, start: startHarness });
@@ -90,6 +91,17 @@ export class Sealant {
             }));
         },
     };
+    /**
+     * Inference on connected accounts — server-side via the official agent SDKs, never raw model-API
+     * calls. Tool calls park server-side; execute them here and `respond()` with the results.
+     */
+    inference = {
+        respond: async (options) => {
+            const payload = buildInferenceRespondRequest(options, this.#ctx.config.hostLocal.ownerUserId);
+            const wire = await this.#runtime.run(inferenceRespondOp(payload));
+            return mapInferenceResponse(wire);
+        },
+    };
     /** Runs by id — so a record can be replayed long after its workspace is gone. */
     runs = {
         get: async (runId) => {

package/dist/effect/api-client.d.ts

@@ -183,6 +183,56 @@ declare const buildControlPlaneClient: (config: SealantInternalConfig) => Effect
             readonly syncedAt: string;
         }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : import("@sealant/api-contracts").GitHubForbiddenError | import("@sealant/api-contracts").GitHubInternalServerError | import("@sealant/api-contracts").GitHubNotFoundError | import("@sealant/api-contracts").GitHubServiceUnavailableError | import("effect/Schema").SchemaError), [Mode] extends ["response-only"] ? never : never>;
     };
+    readonly inference: {
+        readonly respond: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
+            readonly 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;
+            };
+            readonly responseMode?: Mode;
+        }) => Effect.Effect<HttpApiClient.Client.Response<{
+            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;
+        }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : 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), [Mode] extends ["response-only"] ? never : never>;
+    };
     readonly packages: {
         readonly resolvePackage: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
             readonly query: {
@@ -716,6 +766,35 @@ declare const buildControlPlaneClient: (config: SealantInternalConfig) => Effect
             readonly repository: string;
             readonly tag: string;
         }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : 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), [Mode] extends ["response-only"] ? never : never>;
+        readonly execWorkspace: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
+            readonly params: {
+                readonly workspaceId: string;
+            };
+            readonly payload: {
+                readonly ownerUserId: string;
+                readonly commands: readonly {
+                    readonly executable: string;
+                    readonly args: readonly string[];
+                    readonly cwd?: string | undefined;
+                }[];
+            };
+            readonly responseMode?: Mode;
+        }) => Effect.Effect<HttpApiClient.Client.Response<{
+            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;
+        }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceConflictError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError), [Mode] extends ["response-only"] ? never : never>;
         readonly getWorkspace: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
             readonly params: {
                 readonly workspaceId: string;
@@ -1066,6 +1145,56 @@ declare const SealantApiClient_base: Context.ServiceClass<SealantApiClient, "@se
             readonly syncedAt: string;
         }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : import("@sealant/api-contracts").GitHubForbiddenError | import("@sealant/api-contracts").GitHubInternalServerError | import("@sealant/api-contracts").GitHubNotFoundError | import("@sealant/api-contracts").GitHubServiceUnavailableError | import("effect/Schema").SchemaError), [Mode] extends ["response-only"] ? never : never>;
     };
+    readonly inference: {
+        readonly respond: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
+            readonly 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;
+            };
+            readonly responseMode?: Mode;
+        }) => Effect.Effect<HttpApiClient.Client.Response<{
+            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;
+        }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : 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), [Mode] extends ["response-only"] ? never : never>;
+    };
     readonly packages: {
         readonly resolvePackage: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
             readonly query: {
@@ -1599,6 +1728,35 @@ declare const SealantApiClient_base: Context.ServiceClass<SealantApiClient, "@se
             readonly repository: string;
             readonly tag: string;
         }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : 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), [Mode] extends ["response-only"] ? never : never>;
+        readonly execWorkspace: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
+            readonly params: {
+                readonly workspaceId: string;
+            };
+            readonly payload: {
+                readonly ownerUserId: string;
+                readonly commands: readonly {
+                    readonly executable: string;
+                    readonly args: readonly string[];
+                    readonly cwd?: string | undefined;
+                }[];
+            };
+            readonly responseMode?: Mode;
+        }) => Effect.Effect<HttpApiClient.Client.Response<{
+            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;
+        }, Mode>, import("effect/unstable/http/HttpClientError").HttpClientError | ([Mode] extends ["response-only"] ? never : import("effect/Schema").SchemaError | import("@sealant/api-contracts").WorkspaceBadRequestError | import("@sealant/api-contracts").WorkspaceConflictError | import("@sealant/api-contracts").WorkspaceInternalServerError | import("@sealant/api-contracts").WorkspaceNotFoundError), [Mode] extends ["response-only"] ? never : never>;
         readonly getWorkspace: <Mode extends import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode = import("effect/unstable/httpapi/HttpApiEndpoint").ClientResponseMode>(request: {
             readonly params: {
                 readonly workspaceId: string;

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

@@ -62,7 +62,7 @@ export declare const getWorkspaceOp: (workspaceId: string) => Effect.Effect<{
     readonly startedAt?: string | undefined;
     readonly finishedAt?: string | undefined;
     readonly spec?: unknown;
-}, unknown, SealantApiClient>;
+}, 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;
@@ -98,6 +98,29 @@ export declare const listWorkspacesOp: (query: {
         readonly finishedAt?: string | undefined;
     }[];
 }, 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 workspaceId: string;
     readonly harnessId: string;
@@ -125,7 +148,7 @@ 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 workspaceId: string;
@@ -141,7 +164,7 @@ 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 workspaceId?: string | undefined;
     readonly ownerUserId?: string | undefined;
@@ -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

@@ -7,6 +7,7 @@ export const createWorkspaceOp = (payload, idempotencyKey) => Effect.flatMap(Sea
 }));
 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/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/workspace.js

@@ -1,3 +1,4 @@
+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"]);
@@ -53,6 +54,7 @@ export const makeWorkspace = (ctx, init) => {
             }
         },
         harness,
+        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: () => {

package/dist/internal/inference.d.ts

@@ -0,0 +1,47 @@
+import type { InferenceContinueOptions, InferenceRespondOptions, InferenceResponse } from "../types.js";
+export declare const buildInferenceRespondRequest: (options: InferenceContinueOptions | InferenceRespondOptions, ownerUserId: string) => {
+    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;
+};
+export declare const mapInferenceResponse: (wire: {
+    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;
+}) => InferenceResponse;

package/dist/internal/inference.js

@@ -0,0 +1,78 @@
+const DEFAULT_ACCOUNT_NAME = "default";
+const mapAccountRef = (value) => {
+    if (value === undefined || value === false) {
+        return undefined;
+    }
+    return value === true ? DEFAULT_ACCOUNT_NAME : value;
+};
+export const buildInferenceRespondRequest = (options, ownerUserId) => {
+    if ("sessionId" in options) {
+        return {
+            ownerUserId,
+            sessionId: options.sessionId,
+            toolResults: options.toolResults.map((result) => ({
+                toolCallId: result.toolCallId,
+                content: result.content,
+                ...(result.isError === undefined ? {} : { isError: result.isError }),
+            })),
+        };
+    }
+    const claude = mapAccountRef(options.credentials.claude);
+    const codex = mapAccountRef(options.credentials.codex);
+    return {
+        ownerUserId,
+        credentials: {
+            ...(options.credentials.profile === undefined
+                ? {}
+                : { profileId: options.credentials.profile }),
+            ...(claude === undefined ? {} : { claude }),
+            ...(codex === undefined ? {} : { codex }),
+        },
+        prompt: options.prompt,
+        ...(options.system === undefined ? {} : { system: options.system }),
+        ...(options.model === undefined ? {} : { model: options.model }),
+        ...(options.maxTurns === undefined ? {} : { maxTurns: options.maxTurns }),
+        ...(options.tools === undefined
+            ? {}
+            : {
+                tools: options.tools.map((tool) => ({
+                    name: tool.name,
+                    ...(tool.description === undefined ? {} : { description: tool.description }),
+                    inputSchema: tool.inputSchema,
+                })),
+            }),
+        ...(options.responseFormat === undefined
+            ? {}
+            : {
+                responseFormat: {
+                    type: options.responseFormat.type,
+                    ...(options.responseFormat.schema === undefined
+                        ? {}
+                        : { schema: options.responseFormat.schema }),
+                },
+            }),
+    };
+};
+export const mapInferenceResponse = (wire) => {
+    const turn = wire.turn.type === "text"
+        ? {
+            type: "text",
+            text: wire.turn.text,
+            ...(wire.turn.json === undefined ? {} : { json: wire.turn.json }),
+        }
+        : {
+            type: "toolCalls",
+            calls: wire.turn.calls.map((call) => ({
+                toolCallId: call.toolCallId,
+                name: call.name,
+                input: call.input,
+            })),
+        };
+    return {
+        sessionId: wire.sessionId,
+        turn,
+        ...(wire.usage === undefined
+            ? {}
+            : { usage: { inputTokens: wire.usage.inputTokens, outputTokens: wire.usage.outputTokens } }),
+    };
+};

package/dist/types.d.ts

@@ -114,6 +114,27 @@ export interface ListOptions {
     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 Workspace {
     readonly id: string;
@@ -124,6 +145,11 @@ export interface Workspace {
     ready(): Promise<this>;
     /** 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<WorkspaceEvent>;
     /** Stop the workspace now (Phase 3). */
@@ -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[];
@@ -289,3 +473,90 @@ export interface InteractiveSession {
     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/package.json

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