cloudflare / cloudflare/agents
Add an @ai-sdk/sandbox-cloudflare HarnessAgent provider (during ai v7 migration)
- Dominant language
- TypeScript
- Stars
- 5.6k
- Forks
- 711
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 53
Description
## Summary
`examples/sandbox-coding-agent` hand-rolls a translation layer (`src/claude-code.ts` → `ClaudeStreamMapper`) that projects Claude Code's `stream-json` output into AI SDK `UIMessage` chunks, plus session `--resume` handling and a git-diff-as-output. This is, in effect, a miniature reimplementation of an AI SDK **Harness adapter**.
The AI SDK now ships a first-class harness abstraction that does exactly this (and more — usage, reasoning, permission flows, `detach()`/`stop()`/`suspendTurn()`/`continueStream()` resume):
- `@ai-sdk/harness` (`HarnessAgent`)
- `@ai-sdk/harness-claude-code` (adapter; talks to Claude Code over a `ws` bridge)
- sandbox providers: `@ai-sdk/sandbox-vercel`, `@ai-sdk/sandbox-just-bash`
We should be able to write `new HarnessAgent({ harness: claudeCode, sandbox: createCloudflareSandbox(...) })` and delete our bespoke mapper.
## The blocker
There is **no Cloudflare sandbox provider** — `@ai-sdk/sandbox-cloudflare` is a 404. `HarnessAgent` requires a `HarnessV1SandboxProvider`. Bridge-backed harnesses (Claude Code, Codex) need a network sandbox with an exposed port (`ports: [4000]`); the adapter connects to a WebSocket bridge inside the sandbox.
So the work is: implement a `HarnessV1SandboxProvider` over `@cloudflare/sandbox`, including exposing the bridge port (preview URLs / tunnels) the harness adapter connects to via `ws`.
## Why defer to the ai v7 migration
The harness packages (currently `1.0.6`) pin `ai@7.0.4` / `@ai-sdk/provider@4` / `@ai-sdk/provider-utils@5`. This repo is on `ai@^6`. Adopting `HarnessAgent` drags an AI SDK v7 bump, so it's cleanest to do alongside that migration. The packages are also explicitly experimental ("expect breaking changes").
## Acceptance / scope
- [ ] `@ai-sdk/sandbox-cloudflare` (or an in-repo equivalent) implementing `HarnessV1SandboxProvider` over `@cloudflare/sandbox`, with bridge-port exposure for bridge-backed harnesses.
- [ ] A variant of `examples/sandbox-coding-agent` that swaps `src/claude-code.ts` for `HarnessAgent` + `@ai-sdk/harness-claude-code`, deleting the hand-rolled `ClaudeStreamMapper`.
- [ ] Confirm the zero-token AI Gateway egress interception still composes (it operates at the container egress layer, independent of the translation, so it should).
- [ ] Decide whether the harness host runs in the Worker/DO or elsewhere, and validate the Workers-runtime compatibility of `@ai-sdk/harness` + `ws`.
## Context
- Docs: https://ai-sdk.dev/docs/ai-sdk-harnesses/overview , https://ai-sdk.dev/docs/ai-sdk-harnesses/harness-agent
- Current hand-rolled adapter: `examples/sandbox-coding-agent/src/claude-code.ts`
Contributor guide
Assessment
This issue has not been assessed yet.