cloudflare / cloudflare/agents

Add an @ai-sdk/sandbox-cloudflare HarnessAgent provider (during ai v7 migration)

Open
#1,829 0 comments 1 reaction 1 assignee Claimed by @aron-cf View on GitHub
enhancement
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.