Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

agent.ts

294 lines13.2 KB

1/**
2 * The sandbox agent — one `createCloudflareSandboxAgent()` call.
3 *
4 * The factory returns the run-coordinator Durable Object, the `@cloudflare/sandbox`
5 * Sandbox DO, and a stateless Worker fetch handler. `src/server.ts` re-exports the
6 * two DOs (so wrangler can bind them) and composes `agent.worker` with the TanStack
7 * Start request handler so the whole thing — UI + agent + container — ships as one
8 * Worker.
9 *
10 * This is the DEFAULT `do-drives` model: the coordinator DO runs `chat()` itself and
11 * serves the MCP tool-bridge from its own `fetch` handler; the container only runs
12 * the coding-agent CLI. The package also supports a `colocated` mode (the harness
13 * loop runs inside the container) — see the README and `docs/sandbox/overview.md`
14 * for the tradeoff; this example intentionally shows the simpler `do-drives` path.
15 *
16 * SWITCHABLE HARNESS: one app, three coding agents. The `HARNESS` var
17 * (`claude-code` | `codex` | `grok`, default `claude-code`) picks which CLI
18 * `chat()` drives — the run-log / WebSocket / tool-bridge topology is
19 * adapter-agnostic, so only the adapter + the injected API key change. The
20 * container image ships all three CLIs (see Dockerfile); selection is host-side.
21 *
22 * NOTE: Workers-runtime code — it compiles against the real Cloudflare + TanStack AI
23 * types, but the end-to-end container run is only exercised on a real Cloudflare
24 * deploy (see the README "Limitations").
25 */
26import {
27 PREVIEW_GUIDANCE,
28 createCloudflareSandboxAgent,
29 exposePreviewTool,
30 resolvePreviewHost,
31} from '@tanstack/ai-sandbox-cloudflare/agent'
32import {
33 createSecrets,
34 defineSandbox,
35 defineWorkspace,
36} from '@tanstack/ai-sandbox'
37import { claudeCodeText } from '@tanstack/ai-claude-code'
38import { codexText } from '@tanstack/ai-codex'
39import { grokBuildText } from '@tanstack/ai-grok-build'
40import { toolDefinition } from '@tanstack/ai'
41import { z } from 'zod'
42import { namedCloudflareSandbox } from './sandbox-provider'
43import {
44 isGrokModel,
45 isGrokProtocol,
46 isGrokTransport,
47 isHarness,
48} from './sandbox-options'
49import type {
50 GrokBuildModel,
51 GrokBuildProtocol,
52 GrokTransport,
53 HarnessName,
54} from './sandbox-options'
55import type { AnyTextAdapter } from '@tanstack/ai'
56import type {
57 SandboxAgentEnv,
58 StartRunInput,
59} from '@tanstack/ai-sandbox-cloudflare/agent'
60​
61/**
62 * The Worker env this app binds. The base `SandboxAgentEnv` is harness-agnostic —
63 * it binds NO API key — so we extend it with the `HARNESS` selector and the API
64 * key each harness's in-sandbox CLI authenticates with. Keys are optional on the
65 * type (you only need the one for your chosen harness); {@link selectHarness} /
66 * {@link HARNESSES} fail with a clear error at run time if the selected harness's
67 * key is missing.
68 */
69export interface AppEnv extends SandboxAgentEnv {
70 /**
71 * Which in-sandbox coding agent to run: `claude-code` (default) | `codex` |
72 * `grok`. Set as a wrangler `var` (see wrangler.jsonc /
73 * `.dev.vars`). The container image ships all three CLIs; this only picks which
74 * `chat()` drives.
75 */
76 HARNESS?: string
77 /** Anthropic API key — the `claude-code` harness's in-sandbox CLI auth. */
78 ANTHROPIC_API_KEY?: string
79 /** OpenAI Codex key — the `codex` harness. Injected into the sandbox AS CODEX_API_KEY. */
80 CODEX_API_KEY?: string
81 /** Plain OpenAI key, used as the codex key when CODEX_API_KEY is unset. */
82 OPENAI_API_KEY?: string
83 /** xAI key — the `grok` harness. Injected as XAI_API_KEY. */
84 XAI_API_KEY?: string
85 /** Alternate name for the xAI key. */
86 GROK_API_KEY?: string
88​
89export type { HarnessName, GrokBuildModel, GrokBuildProtocol, GrokTransport }
90​
91export interface GrokHarnessOptions {
92 model?: GrokBuildModel
93 protocol?: GrokBuildProtocol
94 transport?: GrokTransport
96​
97interface HarnessSpec {
98 /** Build the harness/text adapter `chat()` runs in the coordinator DO. */
99 adapter: (grokOptions?: GrokHarnessOptions) => AnyTextAdapter
100 /**
101 * The secret env injected into the sandbox container for the in-CLI auth.
102 * Throws a clear error if the harness's required key isn't set, rather than
103 * starting a keyless run that fails deep inside the CLI.
104 */
105 secrets: (env: AppEnv) => Record<string, string>
107​
108const HARNESSES: Record<HarnessName, HarnessSpec> = {
109 'claude-code': {
110 adapter: () => claudeCodeText('sonnet'),
111 secrets: (env) => {
112 const key = env.ANTHROPIC_API_KEY
113 if (!key) throw new Error('claude-code harness needs ANTHROPIC_API_KEY.')
114 return { ANTHROPIC_API_KEY: key }
115 },
116 },
117 codex: {
118 // `danger-full-access` is REQUIRED on Cloudflare: codex's default
119 // `workspace-write` mode wraps every shell command in its own OS sandbox
120 // (bubblewrap), which needs to create a new user namespace — and the
121 // Cloudflare container forbids that ("bwrap: No permissions to create a new
122 // namespace"). The container is ALREADY the isolation boundary, so we disable
123 // codex's redundant inner sandbox.
124 adapter: () =>
125 codexText('gpt-5.3-codex', { sandboxMode: 'danger-full-access' }),
126 // `codex exec` authenticates headlessly via CODEX_API_KEY; a bare
127 // OPENAI_API_KEY makes it try the OAuth WebSocket transport (→ 401), so we
128 // accept either name and inject the value AS CODEX_API_KEY.
129 secrets: (env) => {
130 const key = env.CODEX_API_KEY ?? env.OPENAI_API_KEY
131 if (!key) {
132 throw new Error(
133 'codex harness needs CODEX_API_KEY (or OPENAI_API_KEY).',
134 )
135 }
136 return { CODEX_API_KEY: key }
137 },
138 },
139 grok: {
140 // No special sandboxMode needed for the xAI Grok Build CLI (unlike codex).
141 adapter: (grokOptions?: GrokHarnessOptions) =>
142 grokBuildText(grokOptions?.model ?? 'composer-2.5', {
143 protocol: grokOptions?.protocol ?? 'acp',
144 transport: grokOptions?.transport ?? 'auto',
145 }),
146 secrets: (env) => {
147 const key = env.XAI_API_KEY ?? env.GROK_API_KEY
148 if (!key) {
149 throw new Error('grok harness needs XAI_API_KEY (or GROK_API_KEY).')
150 }
151 return { XAI_API_KEY: key }
152 },
153 },
155​
156/** Per-run Grok options from UI metadata (`metadata.grokModel` / protocol / transport). */
157function resolveGrokOptions(input: StartRunInput): GrokHarnessOptions {
158 const metadata = input.metadata
159 return {
160 model:
161 metadata && isGrokModel(metadata.grokModel)
162 ? metadata.grokModel
163 : 'composer-2.5',
164 protocol:
165 metadata && isGrokProtocol(metadata.grokProtocol)
166 ? metadata.grokProtocol
167 : 'acp',
168 transport:
169 metadata && isGrokTransport(metadata.grokTransport)
170 ? metadata.grokTransport
171 : 'auto',
172 }
174​
175function buildAdapter(
176 harness: HarnessName,
177 input: StartRunInput,
178): AnyTextAdapter {
179 if (harness === 'grok') {
180 return HARNESSES.grok.adapter(resolveGrokOptions(input))
181 }
182 return HARNESSES[harness].adapter()
184​
185/**
186 * Resolve the active harness for a run. A per-run `metadata.harness` (chosen in
187 * the UI and forwarded through the trigger) wins; otherwise the deploy default
188 * `env.HARNESS`; otherwise `claude-code`. Throws on an unknown value.
189 */
190function resolveHarness(input: StartRunInput, env: AppEnv): HarnessName {
191 const override = input.metadata?.harness
192 if (override !== undefined) {
193 if (!isHarness(override)) {
194 throw new Error(
195 `Unknown harness "${String(override)}". Use claude-code | codex | grok.`,
196 )
197 }
198 return override
199 }
200 const fromEnv = env.HARNESS
201 if (fromEnv === undefined || fromEnv === '') return 'claude-code'
202 if (!isHarness(fromEnv)) {
203 throw new Error(
204 `Unknown HARNESS "${fromEnv}". Set it to claude-code | codex | grok.`,
205 )
206 }
207 return fromEnv
209​
210/**
211 * The demo host tool: the canonical recipe for scaffolding a **self-contained**
212 * TanStack Start app — one that runs with NO env vars, API keys, or external
213 * services, so its sandbox preview URL works for anyone with zero setup.
214 *
215 * It's a `chat()` server tool, so the factory bridges it to the in-sandbox agent
216 * over the DO-served MCP endpoint — the agent (Claude Code) sees it as
217 * `mcp__tanstack__tanstackStartRecipe`, calls it BEFORE scaffolding, the DO runs
218 * it on the host, and the result streams back. Returning it from `tools` is what
219 * exercises the `/_bridge` path.
220 *
221 * The recipe scaffolds via `npx --yes @tanstack/cli create … --intent` — no global
222 * install needed in the container image (npm/npx ship on the base image) — which
223 * both creates a real TanStack Start app and writes TanStack Intent skill mappings
224 * into it for coding agents. The bridge still matters for the sandbox-specific bits
225 * the generic skill can't know: build a NO-env app and bind/expose the dev server
226 * for a preview URL.
227 */
228const RECIPE = {
229 scaffold:
230 'Scaffold with the TanStack CLI via npx (no global install needed — run it EXACTLY like this): `npx --yes @tanstack/cli create my-app --framework react --no-examples --intent -y`. The package is `@tanstack/cli` (it ships the `tanstack` bin); do NOT guess other package names. `--intent` writes TanStack Intent agent-skill mappings for coding agents. This creates a TanStack Start app and installs deps. (Add `--no-install` to skip install, or `--add-ons <id,…>` for integrations — but keep it env-free; do NOT add auth/database add-ons that need keys.)',
231 app: 'Turn it into a SELF-CONTAINED interactive app — NO external APIs, NO env vars, NO keys. Pick something visual: a kanban board, a sortable dashboard over a bundled data.json, a markdown notepad, a drawing pad, or a small game (e.g. Game of Life). Keep all state client-side (persist to localStorage). Make it look polished.',
232 run: 'FIRST, so the preview\'s quick-tunnel hostname is accepted, add `server: { host: true, allowedHosts: true }` to the app\'s `vite.config.ts` (Vite rejects unknown hosts by default). THEN start the dev server bound to all interfaces on PORT 5173 — NOT 3000 (reserved by the sandbox control plane): `pnpm dev --host 0.0.0.0 --port 5173` (or `npm run dev -- --host 0.0.0.0 --port 5173`). Once it is listening, call the `exposePreview` tool with `{ "port": 5173 }` to get a public preview URL (a Cloudflare quick tunnel) and share it with the user. The app runs with ZERO configuration — no API keys or env needed.',
233} as const
234​
235const tanstackStartRecipe = toolDefinition({
236 name: 'tanstackStartRecipe',
237 description:
238 'The canonical recipe for building a self-contained TanStack Start app in this sandbox that runs with no env or API keys: scaffold via `npx --yes @tanstack/cli create … --intent`, what to build, and how to bind/expose the dev server for a preview URL. Call this BEFORE scaffolding.',
239 inputSchema: z.object({
240 section: z
241 .enum(['scaffold', 'app', 'run', 'all'])
242 .describe('Which part of the recipe you need (use "all" first).'),
243 }),
244}).server(({ section }) =>
245 section === 'all' ? RECIPE : { [section]: RECIPE[section] },
247​
248/**
249 * The configured agent. `src/server.ts` wires `agent.Coordinator` / `agent.Sandbox`
250 * to the `RUN_COORDINATOR` + `Sandbox` bindings in `wrangler.jsonc`, and routes the
251 * agent's HTTP surface (`/runs`, `/_bridge`, `/tool-exec`) to `agent.worker`.
252 */
253export const agent = createCloudflareSandboxAgent<AppEnv>({
254 // The adapter is resolved per run: the UI's `metadata.harness` picks the coding
255 // agent `chat()` drives, falling back to the `HARNESS` deploy default.
256 adapter: (input, env) => buildAdapter(resolveHarness(input, env), input),
257 // App-agnostic transport guidance, prepended to every run's system prompt: how to
258 // start a dev server whose quick-tunnel preview works (bind wide, allow all hosts
259 // so the tunnel hostname is accepted). Package-owned because it's the transport's
260 // concern. See `PREVIEW_GUIDANCE`.
261 systemPrompts: [PREVIEW_GUIDANCE],
262 // `tanstackStartRecipe` (demo-specific scaffold guidance) + the package's
263 // `exposePreview` (mint a preview URL for the running app) — both bridged to the
264 // in-sandbox agent over `/_bridge`. `exposePreviewTool` closes over the run's
265 // `threadId` + `env`, so it is built per run here.
266 tools: (input, env) => [tanstackStartRecipe, exposePreviewTool(input, env)],
267 // Custom sandbox so we control (a) the env injected into the container and (b) the
268 // container's NAME. We pin the container to the run's `threadId` via
269 // `namedCloudflareSandbox` so `exposePreview` can address the same container to
270 // expose a port. The injected secret is the selected harness's API key only (the
271 // demo app the agent builds needs none); the value comes from the Worker `env`:
272 // set it in `.dev.vars` (local) or `wrangler secret put` (prod). Secrets are
273 // injected at create/resume, never written to snapshots.
274 sandbox: (input, env) =>
275 defineSandbox({
276 id: 'cf-edge-agent',
277 // Named by `threadId` so `exposePreview`'s quick tunnel targets this exact
278 // container (and survives DO eviction for `reuse: 'thread'`).
279 provider: namedCloudflareSandbox(
280 env.Sandbox,
281 input.threadId,
282 resolvePreviewHost(env, input),
283 ),
284 workspace: defineWorkspace({
285 // No source to clone — the container image already ships the harness CLIs.
286 source: { type: 'none' },
287 secrets: createSecrets(
288 HARNESSES[resolveHarness(input, env)].secrets(env),
289 ),
290 }),
291 // One sandbox per thread, so a follow-up message resumes the same workspace.
292 lifecycle: { reuse: 'thread' },
293 }),
294})