@sealant/sdk 0.3.1 → 0.5.0

package/README.md

@@ -1,18 +1,18 @@
 # @sealant/sdk
 
-The fluent public SDK for Sealant — **create a sandbox, run a harness, replay the record.**
+The fluent public SDK for Sealant — **create a workspace, run a harness, replay the record.**
 
 ```ts
 import { Sealant, opencode } from "@sealant/sdk";
 
 const sealant = new Sealant({ baseUrl: "http://localhost:8080" });
 
-const sandbox = await sealant.sandboxes.create({
+const workspace = await sealant.workspaces.create({
   repository: "github.com/acme/billing-service",
   harness: opencode(),
 });
 
-const run = await sandbox.harness.run("Round invoice totals once, after applying the discount.");
+const run = await workspace.harness.run("Round invoice totals once, after applying the discount.");
 
 await run.record.replay();
 ```
@@ -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,13 +44,53 @@ 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 sandbox so the harness
+Attach the caller's connected Claude / Codex / GitHub accounts to a workspace so the harness
 authenticates as that identity instead of running unauthenticated:
 
 ```ts
-const sandbox = await sealant.sandboxes.create({
+const workspace = await sealant.workspaces.create({
   repository: "github.com/acme/billing-service",
   harness: claudeCode(),
   credentials: { claude: true, github: "bot-account" },
@@ -48,14 +103,54 @@ 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: `sandboxes.create()`/`get()`/`list()`, `ready()`, blocking `harness.run()`
+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()` + sandbox lifecycle
+`fileTreeAt()`/`processTreeAt()` (Phase 1), and `harness.session()` + workspace lifecycle
 `stop()`/`restart()`/`expire()` (Phase 3).

package/dist/client.d.ts

@@ -1,16 +1,21 @@
-import type { CreateOptions, ListOptions, Run, Sandbox, SealantConfig } from "./types.js";
+import type { CreateOptions, InferenceNamespace, ListOptions, Run, Workspace, SealantConfig } from "./types.js";
 export declare class Sealant {
     #private;
     constructor(config: SealantConfig);
     /** The configured control-plane base URL. */
     get baseUrl(): string;
-    /** Sandbox lifecycle: create, fetch, and list live environments. */
-    readonly sandboxes: {
-        create: (options: CreateOptions) => Promise<Sandbox>;
-        get: (id: string) => Promise<Sandbox>;
-        list: (options?: ListOptions | undefined) => Promise<readonly Sandbox[]>;
+    /** Workspace lifecycle: create, fetch, and list live environments. */
+    readonly workspaces: {
+        create: (options: CreateOptions) => Promise<Workspace>;
+        get: (id: string) => Promise<Workspace>;
+        list: (options?: ListOptions | undefined) => Promise<readonly Workspace[]>;
     };
-    /** Runs by id — so a record can be replayed long after its sandbox is gone. */
+    /**
+     * 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,16 +10,17 @@
  * stable surface and reject with `SealantNotImplementedError` so callers can compile and wire
  * against the final shape today.
  */
-import { createSandboxOp, getRunOp, getSandboxOp, listSandboxesOp } 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";
 import { makeRun } from "./facade/run.js";
-import { makeSandbox, registerHarnessExecutors } from "./facade/sandbox.js";
-import { buildCreateSandboxRequest } from "./internal/blueprint.js";
+import { makeWorkspace, registerHarnessExecutors } from "./facade/workspace.js";
+import { buildCreateWorkspaceRequest } from "./internal/blueprint.js";
 import { resolveInternalConfig } from "./internal/config.js";
-// Wire the run-execution implementations into the Sandbox facade (the injection point exists to
-// break the sandbox <-> run-harness import cycle; the client is the composition root).
+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 });
 export class Sealant {
     #config;
@@ -38,19 +39,19 @@ export class Sealant {
     get baseUrl() {
         return this.#config.baseUrl;
     }
-    /** Sandbox lifecycle: create, fetch, and list live environments. */
-    sandboxes = {
+    /** Workspace lifecycle: create, fetch, and list live environments. */
+    workspaces = {
         create: async (options) => {
-            const { payload } = buildCreateSandboxRequest(options, this.#ctx.config);
-            const created = await this.#runtime.run(createSandboxOp(payload));
-            const sandbox = makeSandbox(this.#ctx, {
-                id: created.sandboxId,
+            const { payload } = buildCreateWorkspaceRequest(options, this.#ctx.config);
+            const created = await this.#runtime.run(createWorkspaceOp(payload));
+            const workspace = makeWorkspace(this.#ctx, {
+                id: created.workspaceId,
                 name: created.name,
                 status: created.status,
                 harness: options.harness,
             });
             if (options.wait === false) {
-                return sandbox;
+                return workspace;
             }
             // Pump provisioning events to onEvent (best-effort) while we wait for ready. Never let an
             // event-stream hiccup fail create().
@@ -58,7 +59,7 @@ export class Sealant {
                 const onEvent = options.onEvent;
                 void (async () => {
                     try {
-                        for await (const event of sandbox.events()) {
+                        for await (const event of workspace.events()) {
                             onEvent(event);
                         }
                     }
@@ -67,30 +68,41 @@ export class Sealant {
                     }
                 })();
             }
-            return sandbox.ready();
+            return workspace.ready();
         },
         get: async (id) => {
-            const details = await this.#runtime.run(getSandboxOp(id));
-            return makeSandbox(this.#ctx, {
-                id: details.sandboxId,
+            const details = await this.#runtime.run(getWorkspaceOp(id));
+            return makeWorkspace(this.#ctx, {
+                id: details.workspaceId,
                 name: details.name,
                 status: details.status,
             });
         },
         list: async (options) => {
-            const response = await this.#runtime.run(listSandboxesOp({
+            const response = await this.#runtime.run(listWorkspacesOp({
                 ownerUserId: this.#ctx.config.hostLocal.ownerUserId,
                 ...(options?.status === undefined ? {} : { status: options.status }),
                 ...(options?.limit === undefined ? {} : { limit: String(options.limit) }),
             }));
-            return response.items.map((item) => makeSandbox(this.#ctx, {
-                id: item.sandboxId,
+            return response.items.map((item) => makeWorkspace(this.#ctx, {
+                id: item.workspaceId,
                 name: item.name,
                 status: item.status,
             }));
         },
     };
-    /** Runs by id — so a record can be replayed long after its sandbox is gone. */
+    /**
+     * 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) => {
             const wire = await this.#runtime.run(getRunOp(runId));