@coder/ai-sdk-sandbox 0.1.0 → 0.3.0

package/README.md

@@ -10,14 +10,13 @@ It implements the `HarnessV1SandboxProvider` contract from `@ai-sdk/harness`, so
 you pass it as the `sandbox` to a `HarnessAgent` exactly like
 `@ai-sdk/sandbox-vercel`.
 
-> **Status:** experimental. The AI SDK harness packages are published under the
-> `@canary` tag and their APIs can change between releases. This provider tracks
-> `@ai-sdk/harness@1.0.0-canary.11`.
+> **Status:** experimental. This provider tracks the stable AI SDK v7 harness
+> packages (`@ai-sdk/harness@^1.0.23`).
 
 ## Install
 
 ```bash
-npm add @coder/ai-sdk-sandbox @ai-sdk/harness@canary @ai-sdk/harness-claude-code@canary @ai-sdk/provider-utils@canary
+npm add @coder/ai-sdk-sandbox @ai-sdk/harness @ai-sdk/harness-claude-code @ai-sdk/provider-utils
 ```
 
 On the host you also need:
@@ -128,13 +127,51 @@ createCoderWorkspace({
 });
 ```
 
+## Provisioning a workspace without a session
+
+`ensureCoderWorkspace(settings)` runs the same get-or-create → start-if-stopped
+→ wait-until-ready pipeline as create mode, but without creating a harness
+sandbox session — use it to provision a workspace for **other tools** to bind
+to. It takes an explicit `workspace` name (`[owner/]workspace`; there is no
+`sessionId` to derive one from), an optional `create` block (same shape as
+above; `namePrefix`/`owner` are unused), plus `readyTimeoutMs`, `transport`, and
+`abortSignal`. A stopped workspace is always started. Without `create`, the
+workspace must already exist.
+
+It returns an `EnsuredCoderWorkspace`: the workspace's final (ready) status
+snapshot plus `created` (whether this call created it) and — when the transport
+reports one — `id`, the workspace UUID. That id is the handle other Coder
+packages bind to. `@coder/ai-sdk-agent` is intentionally **not** a dependency of
+this package; the two compose by a plain string handoff:
+
+```ts
+import { ensureCoderWorkspace } from "@coder/ai-sdk-sandbox";
+import { CoderAgent } from "@coder/ai-sdk-agent";
+
+const ws = await ensureCoderWorkspace({
+  workspace: "agent-ws",
+  create: { template: "docker" },
+});
+
+const agent = new CoderAgent({
+  baseUrl: process.env.CODER_URL!,
+  token: process.env.CODER_SESSION_TOKEN!,
+  organizationId: "<org-uuid>",
+  workspaceId: ws.id!, // binds the chat's workspace-scoped tools
+});
+```
+
+The non-null assertion is safe on `coder` CLIs that emit `id` in
+`coder list -o json`; old CLIs omit it, so guard
+(`if (ws.id === undefined) throw …`) when you can't pin the CLI version.
+
 ## Terminal UI
 
 For an interactive chat in your terminal instead of one-shot `generate()` calls,
 wrap the same agent with the AI SDK terminal UI ([`@ai-sdk/tui`](https://ai-sdk.dev/v7/docs/ai-sdk-harnesses/terminal-ui)):
 
 ```bash
-npm add @ai-sdk/tui@canary
+npm add @ai-sdk/tui
 ```
 
 The TUI drives a session-less agent, so adapt the `HarnessAgent` (whose
@@ -299,7 +336,7 @@ and a full Claude Code turn with tool use (`scripts/e2e-claude.ts`).
 
 ```bash
 npm install
-npm run typecheck   # tsc against the real canary harness types
+npm run typecheck   # tsc against the real harness types
 npm test            # vitest: unit + local integration (fake `coder` + `ssh`)
 npm run build       # tsup → dist/ (ESM + d.ts)
 

package/dist/index.d.ts

@@ -64,6 +64,11 @@ interface WorkspaceAgentInfo {
     lifecycleState: WorkspaceAgentLifecycle;
 }
 interface WorkspaceStatus {
+    /**
+     * Workspace UUID (top-level `id` in the Coder API). Optional: old `coder`
+     * CLIs or non-CLI transports may not report it, so never require it.
+     */
+    id?: string;
     /** Workspace name (without owner/agent qualifiers). */
     name: string;
     /** Workspace-level build status (`latest_build.status`). */
@@ -370,6 +375,65 @@ type CoderWorkspaceSettings = CoderWorkspaceBaseSettings & ({
  * ```
  */
 declare function createCoderWorkspace(settings: CoderWorkspaceSettings): HarnessV1SandboxProvider;
+/**
+ * Settings for {@link ensureCoderWorkspace} — the provisioning subset of
+ * {@link createCoderWorkspace}'s settings. There is no harness session here, so
+ * the workspace name must be explicit (no `sessionId` to derive one from) and a
+ * stopped workspace is always started.
+ */
+interface EnsureCoderWorkspaceSettings extends Pick<CoderWorkspaceBaseSettings, "readyTimeoutMs" | "transport"> {
+    /** The workspace to ensure, as `[owner/]workspace`. Required. */
+    workspace: string;
+    /**
+     * Create the workspace from a template when it doesn't exist; without it an
+     * existing workspace is required. `create.namePrefix` and `create.owner` are
+     * unused here (they only shape provider-derived names).
+     */
+    create?: CoderCreateSettings;
+    /** Aborts pending create/start/status calls and the readiness polling. */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Result of {@link ensureCoderWorkspace}: the workspace's final (ready) status
+ * snapshot plus whether this call created it.
+ */
+interface EnsuredCoderWorkspace extends WorkspaceStatus {
+    /** `true` when this call created the workspace (vs. reusing an existing one). */
+    created: boolean;
+}
+/**
+ * Ensure a Coder workspace exists, is started, and has a ready agent — without
+ * creating a harness sandbox session. Get-or-creates (when `create` is set),
+ * runs `coder start` if stopped, then polls until an agent is connected and its
+ * startup script has finished. Shares its internals with
+ * {@link createCoderWorkspace}'s create mode.
+ *
+ * The result includes the workspace UUID (`id`) when the transport reports one
+ * (a new-enough `coder` CLI; older CLIs may omit it) — the handle that other
+ * Coder packages bind to. `@coder/ai-sdk-agent` is intentionally *not* a
+ * dependency of this package; compose the two by passing the id:
+ *
+ * @example Provision a workspace, then bind a `CoderAgent` chat to it
+ * ```ts
+ * import { ensureCoderWorkspace } from '@coder/ai-sdk-sandbox';
+ * import { CoderAgent } from '@coder/ai-sdk-agent';
+ *
+ * const ws = await ensureCoderWorkspace({
+ *   workspace: 'agent-ws',
+ *   create: { template: 'docker' },
+ * });
+ * if (ws.id === undefined) {
+ *   throw new Error('this coder CLI does not report workspace ids; upgrade it');
+ * }
+ * const agent = new CoderAgent({
+ *   baseUrl: 'https://coder.example.com',
+ *   token: process.env.CODER_SESSION_TOKEN!,
+ *   organizationId: '<org-uuid>',
+ *   workspaceId: ws.id, // binds the chat's workspace-scoped tools
+ * });
+ * ```
+ */
+declare function ensureCoderWorkspace(settings: EnsureCoderWorkspaceSettings): Promise<EnsuredCoderWorkspace>;
 
 interface ReadFileOptions {
     path: string;
@@ -444,4 +508,4 @@ declare class CoderWorkspaceSession implements HarnessV1NetworkSandboxSession {
     readonly restricted: () => Experimental_SandboxSession;
 }
 
-export { CODER_WORKSPACE_PROVIDER_ID, CoderCliTransport, type CoderCliTransportOptions, type CoderCreateSettings, type CoderTransport, type CoderWorkspaceBaseSettings, type CoderWorkspaceRef, CoderWorkspaceSession, type CoderWorkspaceSessionConfig, type CoderWorkspaceSettings, type CreateWorkspaceOptions, type ExecResult, type ForwardPortOptions, type LifecycleOptions, type ListPresetsOptions, type PortForward, type PresetInfo, type SpawnedProcess, type TransportExecOptions, type WorkspaceAgentInfo, type WorkspaceAgentLifecycle, type WorkspaceAgentStatus, type WorkspaceBuildStatus, type WorkspaceStatus, createCoderWorkspace };
+export { CODER_WORKSPACE_PROVIDER_ID, CoderCliTransport, type CoderCliTransportOptions, type CoderCreateSettings, type CoderTransport, type CoderWorkspaceBaseSettings, type CoderWorkspaceRef, CoderWorkspaceSession, type CoderWorkspaceSessionConfig, type CoderWorkspaceSettings, type CreateWorkspaceOptions, type EnsureCoderWorkspaceSettings, type EnsuredCoderWorkspace, type ExecResult, type ForwardPortOptions, type LifecycleOptions, type ListPresetsOptions, type PortForward, type PresetInfo, type SpawnedProcess, type TransportExecOptions, type WorkspaceAgentInfo, type WorkspaceAgentLifecycle, type WorkspaceAgentStatus, type WorkspaceBuildStatus, type WorkspaceStatus, createCoderWorkspace, ensureCoderWorkspace };

package/dist/index.js

@@ -125,6 +125,8 @@ function parseWorkspaceStatus(workspace) {
     }
   }
   return {
+    // The workspace UUID; omitted (not required) so old CLI output stays accepted.
+    ...typeof ws.id === "string" && ws.id !== "" ? { id: ws.id } : {},
     name: typeof ws.name === "string" ? ws.name : "",
     buildStatus: typeof build.status === "string" ? build.status : "pending",
     transition: typeof build.transition === "string" ? build.transition : "start",
@@ -833,34 +835,61 @@ function createCoderWorkspace(settings) {
     }
   };
 }
+async function ensureCoderWorkspace(settings) {
+  const transport = settings.transport ?? new CoderCliTransport();
+  const { created, status } = await ensureWorkspaceReady(
+    transport,
+    settings.workspace,
+    settings.create,
+    settings.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+    "ensureCoderWorkspace",
+    settings.abortSignal
+  );
+  return { ...status, created };
+}
 async function ensureWorkspace(transport, workspace, settings, readyTimeoutMs, abortSignal) {
-  const create = settings.create;
-  if (create === void 0) {
+  if (settings.create === void 0) {
     if (settings.ensureStarted) {
       await transport.start(workspace, { abortSignal });
     }
     return { createdByProvider: false };
   }
+  const { created } = await ensureWorkspaceReady(
+    transport,
+    workspace,
+    settings.create,
+    readyTimeoutMs,
+    "createCoderWorkspace",
+    abortSignal
+  );
+  return { createdByProvider: created };
+}
+async function ensureWorkspaceReady(transport, workspace, create, readyTimeoutMs, caller, abortSignal) {
   const existing = await transport.status(workspace, { abortSignal });
-  let createdByProvider = false;
+  let created = false;
   if (existing === null) {
+    if (create === void 0) {
+      throw new Error(
+        `${caller}: workspace "${workspace}" does not exist; set \`create\` to create it from a template.`
+      );
+    }
     if (create.validate ?? true) {
-      await validatePreset(transport, create, abortSignal);
+      await validatePreset(transport, create, caller, abortSignal);
     }
     await transport.create(toCreateOptions(workspace, create, abortSignal));
-    createdByProvider = true;
+    created = true;
   } else {
-    if (create.ifExists === "error") {
+    if (create?.ifExists === "error") {
       throw new Error(
-        `createCoderWorkspace: workspace "${workspace}" already exists (create.ifExists: 'error').`
+        `${caller}: workspace "${workspace}" already exists (create.ifExists: 'error').`
       );
     }
     if (isStopped(existing)) {
       await transport.start(workspace, { abortSignal });
     }
   }
-  await waitForReady(transport, workspace, readyTimeoutMs, abortSignal);
-  return { createdByProvider };
+  const status = await waitForReady(transport, workspace, readyTimeoutMs, caller, abortSignal);
+  return { created, status };
 }
 function isStopped(status) {
   return status.buildStatus === "stopped" || status.buildStatus === "stopping" || status.transition === "stop";
@@ -889,7 +918,7 @@ function stringifyParams(params) {
   }
   return out;
 }
-async function validatePreset(transport, create, abortSignal) {
+async function validatePreset(transport, create, caller, abortSignal) {
   if (create.preset === void 0 || create.preset.toLowerCase() === "none") return;
   let presets;
   try {
@@ -906,11 +935,11 @@ async function validatePreset(transport, create, abortSignal) {
   if (!presets.some((preset) => preset.name === create.preset)) {
     const available = presets.map((preset) => `"${preset.name}"`).join(", ");
     throw new Error(
-      `createCoderWorkspace: preset "${create.preset}" not found for template "${create.template}". Available presets: ${available || "(none)"}.`
+      `${caller}: preset "${create.preset}" not found for template "${create.template}". Available presets: ${available || "(none)"}.`
     );
   }
 }
-async function waitForReady(transport, workspace, timeoutMs, abortSignal) {
+async function waitForReady(transport, workspace, timeoutMs, caller, abortSignal) {
   const deadline = Date.now() + timeoutMs;
   let last = "unknown";
   for (; ; ) {
@@ -919,28 +948,26 @@ async function waitForReady(transport, workspace, timeoutMs, abortSignal) {
     if (status !== null) {
       last = `build=${status.buildStatus} agents=[` + status.agents.map((a) => `${a.name || "?"}:${a.status}/${a.lifecycleState}`).join(", ") + "]";
       if (status.buildStatus === "failed") {
-        throw new Error(`createCoderWorkspace: workspace "${workspace}" build failed (${last}).`);
+        throw new Error(`${caller}: workspace "${workspace}" build failed (${last}).`);
       }
       if (status.buildStatus === "canceled" || status.buildStatus === "deleted") {
-        throw new Error(
-          `createCoderWorkspace: workspace "${workspace}" is ${status.buildStatus} (${last}).`
-        );
+        throw new Error(`${caller}: workspace "${workspace}" is ${status.buildStatus} (${last}).`);
       }
       const errored = status.agents.find(
         (a) => a.lifecycleState === "start_error" || a.lifecycleState === "start_timeout"
       );
       if (errored) {
         throw new Error(
-          `createCoderWorkspace: workspace "${workspace}" agent "${errored.name || "?"}" failed to start (lifecycle: ${errored.lifecycleState}).`
+          `${caller}: workspace "${workspace}" agent "${errored.name || "?"}" failed to start (lifecycle: ${errored.lifecycleState}).`
         );
       }
       if (status.buildStatus === "running" && status.agents.some((a) => a.status === "connected" && a.lifecycleState === "ready")) {
-        return;
+        return status;
       }
     }
     if (Date.now() >= deadline) {
       throw new Error(
-        `createCoderWorkspace: timed out after ${timeoutMs}ms waiting for workspace "${workspace}" to become ready (last status: ${last}).`
+        `${caller}: timed out after ${timeoutMs}ms waiting for workspace "${workspace}" to become ready (last status: ${last}).`
       );
     }
     await delay(READY_POLL_INTERVAL_MS, void 0, { signal: abortSignal });
@@ -978,5 +1005,6 @@ export {
   CODER_WORKSPACE_PROVIDER_ID,
   CoderCliTransport,
   CoderWorkspaceSession,
-  createCoderWorkspace
+  createCoderWorkspace,
+  ensureCoderWorkspace
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coder/ai-sdk-sandbox",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Coder workspace sandbox provider for the Vercel AI SDK v7 HarnessAgent",
   "keywords": [
     "ai-sdk",
@@ -41,10 +41,10 @@
     "provenance": true
   },
   "devDependencies": {
-    "@ai-sdk/harness": "1.0.0-canary.11",
-    "@ai-sdk/harness-claude-code": "1.0.0-canary.7",
-    "@ai-sdk/provider-utils": "5.0.0-canary.48",
-    "@ai-sdk/tui": "1.0.0-canary.11",
+    "@ai-sdk/harness": "^1.0.23",
+    "@ai-sdk/harness-claude-code": "^1.0.23",
+    "@ai-sdk/provider-utils": "^5.0.7",
+    "@ai-sdk/tui": "^1.0.19",
     "@arethetypeswrong/cli": "^0.18.0",
     "@types/node": "^22",
     "@vitest/coverage-v8": "^4.1.9",
@@ -56,8 +56,8 @@
     "zod": "4.4.3"
   },
   "peerDependencies": {
-    "@ai-sdk/harness": "^1.0.0-canary.11",
-    "@ai-sdk/provider-utils": "^5.0.0-canary.48"
+    "@ai-sdk/harness": "^1.0.0",
+    "@ai-sdk/provider-utils": "^5.0.0"
   },
   "engines": {
     "node": ">=22"