@coder/ai-sdk-sandbox 0.4.0 → 0.4.2

package/README.md

@@ -11,12 +11,13 @@ 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
 ```
 
 Choose one host transport:
@@ -38,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.",
 });
@@ -92,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
@@ -201,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
@@ -215,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' } }),
@@ -245,17 +246,181 @@ Esc or Ctrl+C).
 
 Because the bridge runs inside the workspace, the workspace image must have:
 
-- **Node.js** (the docs use `node24`). The bridge is `node bridge.mjs`.
-- **pnpm** available on PATH (e.g. via `corepack enable`) — the adapter uses it to
-  bootstrap the bridge.
-- **Outbound network access** to the npm registry (the adapter `pnpm install`s
-  the bridge's dependencies + the Claude Code CLI on first use) and to the model
-  API (`api.anthropic.com` for Claude Code, `api.openai.com` for Codex). Bake the
-  dependencies into the image to avoid per-session installs.
+- **Node.js ≥ 22** on the login-shell PATH. The bridge is `node bridge.mjs`, the
+  native transport's relay is `node -e`, and the pinned
+  `@anthropic-ai/claude-code` bridge dependency requires Node 22+.
+- **pnpm** on the login-shell PATH (e.g. `npm install -g pnpm`) — the adapter's
+  bootstrap runs `pnpm install --frozen-lockfile` to install the bridge's
+  dependencies.
+- **Outbound network access** to the npm registry (the bootstrap downloads the
+  bridge's dependencies — including the Claude Code CLI's ~250 MB platform
+  binary, which ships as an npm package — on first use) and to the model API
+  (`api.anthropic.com` for Claude Code, `api.openai.com` for Codex). Pre-bake
+  the bootstrap into the image to skip the registry entirely — see
+  [Template authoring](#template-authoring-zero-install-sessions).
 - **The model API key** available to the bridge — `ANTHROPIC_API_KEY` /
   `OPENAI_API_KEY`. Configure it through the adapter's `auth` option or ensure it
   is present in the workspace environment.
-- `bash` and `base64` (standard on any Linux dev image).
+- `bash` and `base64` (remote commands run through `bash -lc`; file I/O is
+  base64-encoded), plus `stty` for the native transport's relay bootstrap. All
+  standard on any Linux dev image.
+
+## Template authoring: zero-install sessions
+
+How to build a Coder template whose workspaces start harness sessions with
+**zero runtime install latency**. Generic template authoring is covered by the
+[Coder template docs](https://coder.com/docs/admin/templates) and
+[Coder's example Docker template](https://github.com/coder/coder/tree/main/examples/templates/docker);
+this section covers only the ai-sdk-specific delta. A validated
+Dockerfile + `main.tf` pair lives in [`examples/template/`](./examples/template/).
+
+### What the first session installs
+
+On the first session in a fresh workspace, the Claude Code adapter applies its
+bootstrap recipe relative to the session's default working directory (`$HOME`
+for this provider):
+
+1. It writes `package.json`, `pnpm-lock.yaml`, and `bridge.mjs` (assets shipped
+   inside `@ai-sdk/harness-claude-code`) to `~/.harness-bootstrap/claude-code/`.
+2. It runs `pnpm install --frozen-lockfile --store-dir .pnpm-store` there. This
+   is the expensive step: ~300 MB from the npm registry — the bridge
+   dependencies include the `@anthropic-ai/claude-code` platform binary — taking
+   tens of seconds to minutes depending on the network.
+3. It runs the CLI's `install.cjs` (links the platform binary npm delivered; no
+   extra download) and `./node_modules/.bin/claude --version`.
+4. It writes a `.bootstrap-<recipe-hash>.ok` marker next to them. Later sessions
+   see the marker and skip all of the above — a single file read.
+
+Zero-install means baking the results of steps 1–3 into the image **at that
+exact path**. The first session in each workspace then replays the recipe as a
+fast offline no-op (~4 s measured; pnpm prints `Already up to date` and
+downloads nothing) and writes the marker; every session after that is a single
+file read.
+
+### Step 1 — Dockerfile: pre-bake the bootstrap
+
+[`examples/template/Dockerfile`](./examples/template/Dockerfile) installs the
+[workspace requirements](#workspace-requirements) (Node 24 + pnpm on PATH,
+bash/coreutils) and replays the recipe at build time — same files, same
+commands, same absolute path:
+
+```dockerfile
+ARG HARNESS_CLAUDE_CODE_VERSION=1.0.76
+RUN mkdir -p /home/${USER}/.harness-bootstrap/claude-code \
+  && cd /tmp \
+  && npm pack @ai-sdk/harness-claude-code@${HARNESS_CLAUDE_CODE_VERSION} \
+  && tar -xzf ai-sdk-harness-claude-code-${HARNESS_CLAUDE_CODE_VERSION}.tgz \
+  && cp package/dist/bridge/package.json package/dist/bridge/pnpm-lock.yaml \
+    /home/${USER}/.harness-bootstrap/claude-code/ \
+  && cp package/dist/bridge/index.mjs \
+    /home/${USER}/.harness-bootstrap/claude-code/bridge.mjs \
+  && rm -rf package ai-sdk-harness-claude-code-${HARNESS_CLAUDE_CODE_VERSION}.tgz \
+  && cd /home/${USER}/.harness-bootstrap/claude-code \
+  && pnpm install --frozen-lockfile --store-dir .pnpm-store \
+  && node node_modules/@anthropic-ai/claude-code/install.cjs \
+  && ./node_modules/.bin/claude --version
+```
+
+Rules that make or break the pre-bake:
+
+- **Bake at the final absolute path.** pnpm records the store location as an
+  absolute path (in `node_modules/.modules.yaml`), so a cache baked at, say,
+  `/opt/...` and copied into `$HOME` later makes the session's `pnpm install`
+  abort (`ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY` — pnpm wants to purge and
+  reinstall, and a session has no TTY to confirm).
+- **Pin the adapter version your application resolves** (find it with
+  `pnpm why @ai-sdk/harness-claude-code`, or in your lockfile) and pass it as
+  `--build-arg HARNESS_CLAUDE_CODE_VERSION=...`. The recipe and its marker hash
+  derive from the adapter's shipped assets. A mismatch is not fatal — the
+  recipe re-runs in the same directory and downloads only the delta — but it
+  reintroduces registry traffic on first sessions.
+- **Build for the workspace CPU architecture** — the pre-bake fetches the
+  builder platform's `claude` binary.
+
+### Step 2 — main.tf: get the cache into the home volume
+
+[`examples/template/main.tf`](./examples/template/main.tf) is Coder's example
+Docker template minus the IDE modules, with three ai-sdk-specific choices:
+
+- **The workspace image is the pre-baked one** (`variable "image"`); push it to
+  a registry your Coder provisioners can pull from.
+- **`startup_script_behavior = "blocking"`** on `coder_agent`: this provider's
+  create mode waits for `lifecycle_state: ready` before the harness runs, and
+  blocking makes ready mean "startup script finished" (the attribute defaults to
+  `non-blocking`, in which case ready does not wait for the script).
+- **The home volume seeds itself from the image.** Docker populates a fresh
+  (empty) named volume with the image's content at the mount path, so
+  `/home/coder/.harness-bootstrap` lands in every new workspace's volume with no
+  startup-script copying. No port configuration is needed either: the provider
+  forwards the bridge port itself (OpenSSH `-L` or the native relay), not
+  through template port shares.
+
+For volume types that do _not_ copy image content (a Kubernetes PVC mounted at
+`/home/coder` shadows it with an empty filesystem), stash the bake outside the
+mount and restore it — at the same absolute path — on first start:
+
+```dockerfile
+# Dockerfile, after the pre-bake step:
+RUN sudo cp -a /home/${USER}/.harness-bootstrap /opt/harness-bootstrap-stash
+```
+
+```hcl
+  startup_script = <<-EOT
+    set -e
+    if [ ! -d ~/.harness-bootstrap ]; then
+      cp -a /opt/harness-bootstrap-stash ~/.harness-bootstrap
+    fi
+  EOT
+```
+
+(`cp -a` preserves the hardlinks between the pnpm store and `node_modules`, so
+the stash and the restore each stay ~300 MB rather than doubling.)
+
+Build, push, and point the provider at the template
+([creating templates](https://coder.com/docs/admin/templates/creating-templates)):
+
+```bash
+cd examples/template
+docker build -t <registry>/ai-sdk-sandbox-workspace:v1 .
+docker push <registry>/ai-sdk-sandbox-workspace:v1
+coder templates push ai-sdk-sandbox --variable image=<registry>/ai-sdk-sandbox-workspace:v1
+```
+
+```ts
+createCoderWorkspace({ create: { template: "ai-sdk-sandbox" } });
+```
+
+### Sizing
+
+Measured on the example image (linux/amd64): ~730 MB total — ~430 MB for
+Ubuntu 24.04 + Node 24 + pnpm, ~300 MB for the bootstrap cache (dominated by
+the pnpm store; `node_modules` hardlinks into it). Each workspace's home volume
+receives the ~300 MB seeded cache; leave headroom for per-session work
+directories (`claude-code-<sessionId>/`) and whatever your agents check out.
+
+### Verifying zero installs
+
+**Image-level (no Coder deployment needed).** Replay the bootstrap on a fresh
+volume with networking disabled — it must succeed offline:
+
+```bash
+docker volume rm -f probe-home && docker volume create probe-home
+docker run --rm --network none -v probe-home:/home/coder \
+  <image> bash -lc 'cd ~/.harness-bootstrap/claude-code \
+    && pnpm install --frozen-lockfile --store-dir .pnpm-store \
+    && node node_modules/@anthropic-ai/claude-code/install.cjs \
+    && ./node_modules/.bin/claude --version'
+```
+
+Expect `Already up to date` from pnpm and the CLI version banner in a few
+seconds — proof that a session's bootstrap needs no registry access.
+
+**Session-level.** After the first session against a workspace from the
+template, `~/.harness-bootstrap/claude-code/` must contain a `.bootstrap-*.ok`
+marker (later sessions skip the recipe entirely). If session creation instead
+stalls for minutes with pnpm download progress in the bootstrap, the image's
+pinned adapter version doesn't match the application's (see the pinning rule
+above).
 
 ## Settings
 
@@ -382,34 +547,37 @@ and a full Claude Code turn with tool use (`scripts/e2e-claude.ts`).
   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
-  installs the bridge + CLI on first use) and egress to the npm registry and the
-  model API. Provide the API key via the adapter's `auth` option.
+- To run Claude Code / Codex, the **workspace** image needs Node.js ≥ 22 (the
+  adapter installs the bridge + CLI on first use) and egress to the npm registry
+  and the model API — unless the image pre-bakes the bootstrap (see
+  [Template authoring](#template-authoring-zero-install-sessions)). Provide the
+  API key via the adapter's `auth` option.
 
 ## 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 retrieve
-# the already-authenticated token for this shell; CoderNativeTransport never invokes it:
+# 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 login token)" \
-  npm run verify:native -- my-ws
+  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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coder/ai-sdk-sandbox",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Coder workspace sandbox provider for the Vercel AI SDK v7 HarnessAgent",
   "keywords": [
     "ai-sdk",