@coder/ai-sdk-sandbox 0.3.0 → 0.4.1

package/README.md

@@ -11,20 +11,23 @@ you pass it as the `sandbox` to a `HarnessAgent` exactly like
 `@ai-sdk/sandbox-vercel`.
 
 > **Status:** experimental. This provider tracks the stable AI SDK v7 harness
-> packages (`@ai-sdk/harness@^1.0.23`).
+> packages (see the `@ai-sdk/harness` peer range in
+> [`package.json`](./package.json)).
 
 ## Install
 
 ```bash
-npm add @coder/ai-sdk-sandbox @ai-sdk/harness @ai-sdk/harness-claude-code @ai-sdk/provider-utils
+pnpm add @coder/ai-sdk-sandbox @ai-sdk/harness @ai-sdk/harness-claude-code @ai-sdk/provider-utils
 ```
 
-On the host you also need:
+Choose one host transport:
 
-- the [`coder` CLI](https://coder.com/docs/install) on PATH and authenticated
-  (`coder login`); for non-ambient auth, configure the transport explicitly with
-  `new CoderCliTransport({ url, token })` (see [Settings](#settings));
-- an **OpenSSH client** (`ssh`) on PATH — exec runs through it (see "How it works").
+- `CoderNativeTransport` connects directly to Coderd and requires no `coder` or
+  `ssh` binary on the host. Pass a deployment URL and token (see
+  [Native transport](#native-transport)).
+- The default `CoderCliTransport` requires the
+  [`coder` CLI](https://coder.com/docs/install), an authenticated `coder login`,
+  and an OpenSSH client (`ssh`) on PATH.
 
 ## Quick start
 
@@ -36,7 +39,7 @@ import { createClaudeCode } from "@ai-sdk/harness-claude-code";
 import { createCoderWorkspace } from "@coder/ai-sdk-sandbox";
 
 const agent = new HarnessAgent({
-  harness: createClaudeCode({ thinking: "adaptive" }),
+  harness: createClaudeCode({ thinking: { type: "adaptive" } }),
   sandbox: createCoderWorkspace({ workspace: "my-dev-workspace" }),
   instructions: "You are a careful coding assistant.",
 });
@@ -55,6 +58,33 @@ try {
 
 See [`examples/claude-code.ts`](./examples/claude-code.ts) for a runnable version.
 
+### Native transport
+
+Use `CoderNativeTransport` when the host should not depend on the Coder CLI or
+OpenSSH:
+
+```ts
+import { CoderNativeTransport, createCoderWorkspace } from "@coder/ai-sdk-sandbox";
+
+const transport = new CoderNativeTransport({
+  url: process.env.CODER_URL!,
+  token: process.env.CODER_SESSION_TOKEN!,
+});
+
+const sandbox = createCoderWorkspace({
+  workspace: "my-dev-workspace",
+  transport,
+});
+
+// When the application shuts down, close cached relay WebSockets:
+await transport.close();
+```
+
+The constructor falls back to `CODER_URL` and `CODER_SESSION_TOKEN`, so
+`new CoderNativeTransport()` is sufficient when both are set. The token is sent
+only to Coderd in the `Coder-Session-Token` header; it is never copied into the
+workspace.
+
 ## Creating workspaces on demand
 
 Instead of pointing at an existing workspace, you can have the provider **create
@@ -63,7 +93,7 @@ the session ends. Add a `create` block:
 
 ```ts
 const agent = new HarnessAgent({
-  harness: createClaudeCode({ thinking: "adaptive" }),
+  harness: createClaudeCode({ thinking: { type: "adaptive" } }),
   sandbox: createCoderWorkspace({
     create: {
       template: "docker", // required: the template to create from
@@ -96,12 +126,13 @@ createCoderWorkspace({
 
 **Parameters vs. presets.** A preset's parameter values take precedence over an
 overlapping `parameters` entry of the same name (this is Coder's behavior), so
-set a given value via the preset _or_ `parameters`, not both. Required
-parameters (those without a template default) must be supplied via `parameters`,
-`parameterFile`, a `preset`, or `useParameterDefaults` — otherwise creation
-fails (it can't prompt non-interactively). If you set a `preset`, the provider
-preflight-validates the name against the template's presets and fails fast with
-the available names (set `validate: false` to skip).
+set a given value via the preset _or_ `parameters`, not both. Every unset
+non-ephemeral parameter must be supplied via `parameters`, `parameterFile`, or a
+`preset`, unless `useParameterDefaults` accepts its template default. Parameters
+marked required have no usable default and must always be supplied; otherwise
+creation fails because it cannot prompt non-interactively. If you set a `preset`,
+the provider preflight-validates the name against the template's presets and
+fails fast with the available names (set `validate: false` to skip).
 
 ### Create settings
 
@@ -171,7 +202,7 @@ 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
+pnpm add @ai-sdk/tui
 ```
 
 The TUI drives a session-less agent, so adapt the `HarnessAgent` (whose
@@ -185,7 +216,7 @@ import { runAgentTUI, type AgentTUIAgent } from "@ai-sdk/tui";
 import { createCoderWorkspace } from "@coder/ai-sdk-sandbox";
 
 const agent = new HarnessAgent({
-  harness: createClaudeCode({ thinking: "adaptive" }),
+  harness: createClaudeCode({ thinking: { type: "adaptive" } }),
   sandbox: createCoderWorkspace({ workspace: "my-dev-ws" }),
   // or, to create a fresh workspace per session from a template:
   // sandbox: createCoderWorkspace({ create: { template: 'claude-code-test' } }),
@@ -233,7 +264,11 @@ Because the bridge runs inside the workspace, the workspace image must have:
 [Creating workspaces on demand](#creating-workspaces-on-demand)).
 
 ```ts
-import { createCoderWorkspace, CoderCliTransport } from "@coder/ai-sdk-sandbox";
+import {
+  createCoderWorkspace,
+  CoderCliTransport,
+  CoderNativeTransport,
+} from "@coder/ai-sdk-sandbox";
 
 createCoderWorkspace({
   // One of these is required (TypeScript enforces it):
@@ -254,6 +289,12 @@ createCoderWorkspace({
     // url: process.env.CODER_URL, token: process.env.CODER_SESSION_TOKEN,
     // env: {}, loginShell: true, waitMode: 'no',
   }),
+
+  // Or connect directly to Coderd with no host CLI/OpenSSH dependency:
+  // transport: new CoderNativeTransport({
+  //   url: process.env.CODER_URL,
+  //   token: process.env.CODER_SESSION_TOKEN,
+  // }),
 });
 ```
 
@@ -276,10 +317,11 @@ createCoderWorkspace({
 
 The adapter binds its bridge to a port and resolves it from
 `createClaudeCode({ port })` or, by default, `sandbox.ports[0]`. Expose that port
-via `ports` (default `[4000]`); `getPortUrl` opens an OpenSSH `-L` local forward
-(over the same `coder ssh --stdio` ProxyCommand) to it on demand and returns a
-loopback `ws://` URL. The forward is plaintext on loopback, so `https`/`wss`
-requests resolve to their `http`/`ws` loopback equivalent.
+via `ports` (default `[4000]`); `getPortUrl` asks the configured transport for a
+local TCP forward and returns a loopback `ws://` URL. The CLI transport uses
+OpenSSH `-L`; the native transport multiplexes TCP over its Coderd WebSocket.
+The forward is plaintext on loopback, so `https`/`wss` requests resolve to their
+`http`/`ws` loopback equivalent.
 
 ## How it works
 
@@ -290,14 +332,13 @@ bridge runs the vendor SDK in-workspace and streams events back to the host.
 
 This provider maps that contract onto Coder primitives:
 
-| Harness contract                            | Coder implementation                                                                        |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `run` / `spawn`                             | OpenSSH `bash -lc '…'` over a `coder ssh --stdio` ProxyCommand                              |
-| `readFile` / `writeFile` / `read*`/`write*` | base64 piped over the SSH connection (binary-safe)                                          |
-| `getPortUrl({ port, protocol })`            | OpenSSH `-L <local>:127.0.0.1:<port>` over the same ProxyCommand → `ws://127.0.0.1:<local>` |
-| `ports` / `setPorts`                        | the workspace's exposed port set                                                            |
-| `createSession` / `resumeSession` / `id`    | attach to a workspace by name                                                               |
-| `stop` / `destroy`                          | `coder stop` / `coder delete` (only when it owns the lifecycle)                             |
+| Harness contract                            | CLI transport                                      | Native transport                                          |
+| ------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------- |
+| `run` / `spawn`                             | OpenSSH over `coder ssh --stdio`                   | versioned process relay over Coderd's agent PTY WebSocket |
+| `readFile` / `writeFile` / `read*`/`write*` | base64 over SSH                                    | base64 over the native process relay                      |
+| `getPortUrl({ port, protocol })`            | OpenSSH `-L`                                       | multiplexed TCP channels over the relay                   |
+| `createSession` / `resumeSession` / `id`    | CLI workspace lookup                               | Coderd v2 REST API                                        |
+| `stop` / `destroy`                          | `coder stop` / `coder delete` when lifecycle-owned | Coderd workspace-build transitions                        |
 
 **Why OpenSSH and not `coder ssh <ws> -- cmd`?** `coder ssh` allocates a PTY for
 the command, which rewrites newlines to CRLF, merges stdout and stderr onto one
@@ -308,6 +349,15 @@ provider does the programmatic equivalent, running real OpenSSH over a
 `coder ssh --stdio` ProxyCommand. That yields clean, separated streams and
 correct exit codes (verified against a live workspace).
 
+**How the native relay stays byte-clean.** Coderd's browser-terminal endpoint
+is a PTY, which by itself merges stdout/stderr and has no process exit-code
+channel. The native transport uses it only as a carrier: it bootstraps a small,
+dependency-free Node relay, switches the PTY to raw/no-echo mode, and exchanges
+versioned newline-delimited frames with base64 byte payloads. The relay launches
+commands with separate pipes and also opens TCP sockets for `getPortUrl`. It
+does not bind a workspace port or persist credentials/files; one relay is cached
+per selected workspace agent and `transport.close()` tears it down.
+
 The WebSocket the harness opens against `getPortUrl(...)` is the critical path,
 and it needs no wildcard access URLs — the host running `HarnessAgent` is already
 a Coder client. We forward via OpenSSH `-L` rather than `coder port-forward`:
@@ -326,6 +376,11 @@ and a full Claude Code turn with tool use (`scripts/e2e-claude.ts`).
   workspace per session rather than leasing ports from a shared sandbox.
 - File reads buffer the whole file (binary content moves as base64). Fine for
   bootstrap-sized files; not intended for streaming very large files.
+- `CoderNativeTransport` currently targets POSIX workspaces with `bash`, `stty`,
+  `base64`, and Node.js. Its default relay executable is `node`; override
+  `relayNodeCommand` when Node lives at a fixed nonstandard path.
+- A workspace with multiple agents must be selected as `workspace.agent`; the
+  native transport refuses to guess.
 - `@ai-sdk/sandbox-just-bash` cannot expose ports and is rejected by bridge-backed
   adapters — this provider exists precisely to provide that port.
 - To run Claude Code / Codex, the **workspace** image needs Node.js (the adapter
@@ -335,21 +390,28 @@ and a full Claude Code turn with tool use (`scripts/e2e-claude.ts`).
 ## Development
 
 ```bash
-npm install
-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)
+# From this package's directory (packages/sandbox):
+pnpm install
+pnpm typecheck   # tsc against the real harness types
+pnpm test        # vitest: unit + local integration (fake `coder` + `ssh`)
+pnpm build       # tsup → dist/ (ESM + d.ts)
 
-# Formatting & linting (Biome):
-npm run format      # biome format --write .   (apply formatting)
-npm run lint        # biome lint .             (report lint issues)
-npm run check       # biome check .            (format + lint, read-only; for CI)
+# Formatting & linting are root-level scripts (`-w` runs them from anywhere in the repo):
+pnpm -w format   # oxfmt (apply formatting)
+pnpm -w lint     # oxlint (report lint issues)
+pnpm -w check    # format check + lint + typecheck (CI gate)
 
 # End-to-end against a real workspace (needs the coder CLI + a running workspace):
-npm run verify:real -- my-ws
+pnpm verify:real my-ws
+
+# The same contract through Coderd directly. The CLI is used only to mint a
+# token for this shell; CoderNativeTransport never invokes it:
+CODER_URL=https://coder.example.com \
+  CODER_SESSION_TOKEN="$(coder tokens create --name ai-sdk-sandbox)" \
+  pnpm verify:native my-ws
 
 # End-to-end of create mode (creates a throwaway workspace, then deletes it):
-npm run verify:create -- docker
+pnpm verify:create docker
 ```
 
 The local integration tests exercise the real transport (argument building,

package/dist/index.d.ts

@@ -1,12 +1,11 @@
-import { HarnessV1SandboxProvider, HarnessV1NetworkSandboxSession } from '@ai-sdk/harness';
+import { HarnessV1SandboxProvider, HarnessV1NetworkSandboxSession, HarnessV1PortEndpoint } from '@ai-sdk/harness';
 import { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
 
 /**
  * Transport abstraction over a Coder workspace. The sandbox session talks to a
  * workspace exclusively through this interface, which keeps the harness-facing
  * session decoupled from *how* we reach Coder (the default is the `coder` CLI;
- * tests inject a mock, and a future implementation could use the Coder REST API
- * or a persistent SSH/SFTP connection).
+ * {@link CoderNativeTransport} uses Coderd directly, and tests inject mocks).
  */
 interface CoderTransport {
     /** Run a command to completion, buffering stdout/stderr into strings. */
@@ -227,6 +226,62 @@ declare class CoderCliTransport implements CoderTransport {
     listPresets(options: ListPresetsOptions): Promise<PresetInfo[]>;
 }
 
+interface CoderNativeTransportOptions {
+    /** Coder deployment URL. Defaults to `CODER_URL`. */
+    url?: string;
+    /** Coder session/API token. Defaults to `CODER_SESSION_TOKEN`. */
+    token?: string;
+    /** Custom fetch implementation, primarily for tests or custom HTTP agents. */
+    fetch?: typeof globalThis.fetch;
+    /** Additional headers sent to Coderd over both HTTP and WebSocket. */
+    headers?: Record<string, string>;
+    /** Poll interval while waiting for provisioner builds. Default: 1000ms. */
+    buildPollIntervalMs?: number;
+    /** Maximum wait for one provisioner build. Default: 30 minutes. */
+    buildTimeoutMs?: number;
+    /** Maximum wait for the workspace relay handshake. Default: 30000ms. */
+    relayConnectTimeoutMs?: number;
+    /** Node executable used inside the workspace for the relay. Default: `node`. */
+    relayNodeCommand?: string;
+    /** Run commands through `bash -lc` instead of `bash -c`. Default: true. */
+    loginShell?: boolean;
+}
+/**
+ * Native Coder transport: Coderd's REST API supplies the control plane and an
+ * authenticated workspace-agent PTY carries a small multiplexed process/TCP
+ * relay. No local `coder` or `ssh` binary is launched.
+ */
+declare class CoderNativeTransport implements CoderTransport {
+    #private;
+    constructor(options?: CoderNativeTransportOptions);
+    exec(options: TransportExecOptions): Promise<ExecResult>;
+    spawn(options: TransportExecOptions): SpawnedProcess;
+    forwardPort(options: ForwardPortOptions): Promise<PortForward>;
+    start(workspace: string, options?: LifecycleOptions): Promise<void>;
+    stop(workspace: string, options?: LifecycleOptions): Promise<void>;
+    destroy(workspace: string, options?: LifecycleOptions): Promise<void>;
+    status(workspace: string, options?: LifecycleOptions): Promise<WorkspaceStatus | null>;
+    create(options: CreateWorkspaceOptions): Promise<void>;
+    listPresets(options: ListPresetsOptions): Promise<PresetInfo[]>;
+    /** Close every cached workspace relay. Existing local port-forwards close too. */
+    close(): Promise<void>;
+}
+
+/** Error returned for a non-success response from Coderd's v2 API. */
+declare class CoderNativeApiError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    readonly detail?: string;
+    constructor(options: {
+        status: number;
+        method: string;
+        path: string;
+        message: string;
+        detail?: string;
+    });
+}
+
 /** Stable provider id reported on the {@link HarnessV1SandboxProvider}. */
 declare const CODER_WORKSPACE_PROVIDER_ID = "coder-workspace";
 /**
@@ -474,11 +529,10 @@ interface CoderWorkspaceSessionConfig {
 /**
  * A {@link HarnessV1NetworkSandboxSession} backed by a Coder workspace.
  *
- * Exec maps to `coder ssh`, file I/O to base64-over-`coder ssh`, and
- * `getPortUrl` to an OpenSSH `-L` local forward over a `coder ssh --stdio`
- * ProxyCommand, exposed as a local `ws://127.0.0.1:<port>` URL — which is what
- * bridge-backed harness adapters (Claude Code, Codex) open their WebSocket
- * against.
+ * The configured {@link CoderTransport} supplies process execution, lifecycle,
+ * and TCP forwarding. `getPortEndpoint` exposes a forwarded port as a local
+ * `ws://127.0.0.1:<port>` URL, which is what bridge-backed harness adapters
+ * (Claude Code, Codex) open their WebSocket against.
  */
 declare class CoderWorkspaceSession implements HarnessV1NetworkSandboxSession {
     #private;
@@ -495,6 +549,11 @@ declare class CoderWorkspaceSession implements HarnessV1NetworkSandboxSession {
     readonly writeFile: (options: WriteFileOptions<ReadableStream<Uint8Array>>) => Promise<void>;
     readonly writeBinaryFile: (options: WriteFileOptions<Uint8Array>) => Promise<void>;
     readonly writeTextFile: (options: WriteTextFileOptions) => Promise<void>;
+    readonly getPortEndpoint: (options: {
+        port: number;
+        protocol?: "http" | "https" | "ws";
+    }) => Promise<HarnessV1PortEndpoint>;
+    /** @deprecated Kept for the `HarnessV1NetworkSandboxSession` contract; use `getPortEndpoint`. */
     readonly getPortUrl: (options: {
         port: number;
         protocol?: "http" | "https" | "ws";
@@ -508,4 +567,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 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 };
+export { CODER_WORKSPACE_PROVIDER_ID, CoderCliTransport, type CoderCliTransportOptions, type CoderCreateSettings, CoderNativeApiError, CoderNativeTransport, type CoderNativeTransportOptions, 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 };