{part.name}
+ } + if (part.type === 'structured-output') { + const report = part.data ?? part.partial + return report?.name ?{final.oneLiner}
: null} + + ) +} +``` + +See [Harness Agents](../structured-outputs/harnesses) for the full part list and the repo-report example. + ## Typed models & options Like `openaiCompatible`, you can declare the harness's **models** and its @@ -130,7 +228,8 @@ const stream = chat({ ``` The base options are always available on `modelOptions` regardless of what you -declare: `sessionId` (resume), `cwd`, `authMethodId`, and `permissionMode`. +declare: `sessionId` (resume), `cwd`, `authMode`, `authMethodId`, and +`permissionMode`. ## Configuration @@ -144,7 +243,8 @@ declare: `sessionId` (resume), `cwd`, `authMethodId`, and `permissionMode`. | `openTransport` | Open any `AcpSessionTransport` yourself (e.g. boot a `serve` process and connect over WebSocket). Overrides `command`. | | `cwd` | Working directory inside the sandbox (default `/workspace`). | | `env` | Extra environment variables for the harness process. | -| `authMethodId` | ACP auth method to select before the session starts. | +| `authMode` | `'api-key'` (default) uses `authMethodId`. `'host'` skips ACP `authenticate`. See [Harness Auth](../sandbox/auth). | +| `authMethodId` | ACP auth method to select before the session starts. Ignored when `authMode` is `'host'`. | | `permissionMode` | `'default'` \| `'acceptEdits'` \| `'bypassPermissions'` (default). | | `permissions` | `'headless'` (auto-resolve, default) or `'interactive'` (emit approval-requested events for `ask` prompts). | | `onPermissionRequest` | Custom permission handler; overrides `permissions`/`permissionMode`. | diff --git a/docs/adapters/claude-code.md b/docs/adapters/claude-code.md index 01bfaeb300..f360bcd3ba 100644 --- a/docs/adapters/claude-code.md +++ b/docs/adapters/claude-code.md @@ -28,10 +28,19 @@ A runnable demo lives at [`examples/sandbox-cloudflare`](https://github.com/TanS ## Authentication -The harness resolves credentials the same way Claude Code does: +Your laptop can already have `claude login`. A CI runner only has +`ANTHROPIC_API_KEY`. The default `authMode` is `'api-key'`. Set `'host'` +when you want `claude login`. See [Harness Auth](../sandbox/auth). -- `ANTHROPIC_API_KEY` in the server's environment (or the `apiKey` config option), or -- an existing Claude subscription login on the machine (`claude login`). +```ts +import { claudeCodeText } from "@tanstack/ai-claude-code" + +claudeCodeText("claude-opus-4-8") +claudeCodeText("claude-opus-4-8", { authMode: "host" }) +``` + +- `'api-key'` (default): inject `ANTHROPIC_API_KEY` (or pass `apiKey`). +- `'host'`: use `claude login`. Do not inject `ANTHROPIC_API_KEY`. ## Basic Usage @@ -59,6 +68,7 @@ const stream = chat({ | `maxTurns` | Maximum harness-internal turns per run. | | `systemPromptMode` | `'append'` (default) keeps Claude Code's preset system prompt and appends your `systemPrompts`; `'replace'` sends yours as the entire prompt. | | `mcpServers` | Extra MCP servers passed through to the harness untouched. | +| `authMode` | `'api-key'` (default) injects `ANTHROPIC_API_KEY`. `'host'` uses `claude login`. Also valid on `modelOptions`. See [Harness Auth](../sandbox/auth). | | `apiKey` | Anthropic API key for the harness subprocess. | | `env` | Extra environment variables for the harness subprocess. | | `pathToClaudeCodeExecutable` | Use a specific Claude Code executable instead of the SDK's bundled one. | @@ -170,7 +180,65 @@ const stream = chat({ ## Structured Output -`structuredOutput()` uses the harness's native JSON-schema output format in a one-shot run (single turn, no tools). It works for finalization after a chat, but a plain provider adapter (e.g. `@tanstack/ai-anthropic`) is the better choice when structured extraction is the primary job — it's faster and doesn't spawn a subprocess. +Pass `outputSchema` on `chat()`. Claude Code runs one harness turn, uses its native tools, and returns a typed object. The schema JSON is passed to `--json-schema` as inline JSON (the CLI rejects a file path). Tool activity and prose stream as usual. The object arrives as `structured-output.complete`, including when Claude delivers it through its built-in `StructuredOutput` tool. + +The adapter loads only user settings (`--setting-sources user`). A cloned repo's `.claude/settings.json` does not block headless `-p`. The adapter does not pass `--bare`, because that flag ignores a host `claude login`. + +On local-process, Claude uses your host `claude login`. On Docker, pass `ANTHROPIC_API_KEY` in the process env. A container has no host login. + +```ts +import { chat } from "@tanstack/ai" +import { claudeCodeText } from "@tanstack/ai-claude-code" +import { defineSandbox, withSandbox } from "@tanstack/ai-sandbox" +import { dockerSandbox } from "@tanstack/ai-sandbox-docker" +import { z } from "zod" + +const Report = z.object({ + summary: z.string(), + filesChanged: z.array(z.string()), +}) + +const sandbox = defineSandbox({ + id: "repo-report", + provider: dockerSandbox({ image: "node:22" }), +}) + +const report = await chat({ + adapter: claudeCodeText("claude-opus-4-8"), + messages: [{ role: "user", content: "Review this repo." }], + outputSchema: Report, + middleware: [withSandbox(sandbox)], +}) + +report.summary +``` + +On the client, pass the same schema to `useChat` and read `final`. `partial` stays empty until the end. + +```tsx +import { fetchServerSentEvents, useChat } from "@tanstack/ai-react" +import { z } from "zod" + +const Report = z.object({ + summary: z.string(), + filesChanged: z.array(z.string()), +}) + +function ReportView() { + const { final, isLoading } = useChat({ + connection: fetchServerSentEvents("/api/repo-report"), + outputSchema: Report, + }) + + if (isLoading) returnThe agent is inspecting the repo.
+ if (!final) return null + return{final.summary}
+} +``` + +If you only need to extract JSON from a prompt and do not need a sandbox, use `@tanstack/ai-anthropic`. That path is faster. + +Full walkthrough, including the client: [Harness Agents](../structured-outputs/harnesses). ## Limitations diff --git a/docs/adapters/codex.md b/docs/adapters/codex.md index eb000dd053..4448b9603e 100644 --- a/docs/adapters/codex.md +++ b/docs/adapters/codex.md @@ -28,10 +28,19 @@ A runnable demo lives at [`examples/sandbox-cloudflare`](https://github.com/TanS ## Authentication -The harness resolves credentials the same way the Codex CLI does: +Your laptop can already have `codex login`. A CI runner only has +`CODEX_API_KEY`. The default `authMode` is `'api-key'`. Set `'host'` when +you want `codex login`. See [Harness Auth](../sandbox/auth). -- the `apiKey` config option (exported to the subprocess as `CODEX_API_KEY`; usage-based billing), or -- an existing ChatGPT login on the machine (`codex login`). +```ts +import { codexText } from "@tanstack/ai-codex" + +codexText("gpt-5.5") +codexText("gpt-5.5", { authMode: "host" }) +``` + +- `'api-key'` (default): expect `CODEX_API_KEY` (or pass `apiKey`). +- `'host'`: use `codex login`. Do not inject `CODEX_API_KEY`. ## Basic Usage @@ -60,13 +69,16 @@ const stream = chat({ | `networkAccessEnabled` | Allow network access inside the `workspace-write` sandbox. | | `webSearchMode` | `'disabled'` \| `'cached'` \| `'live'`. | | `additionalDirectories`| Extra writable directories beyond `cwd`. | +| `authMode` | `'api-key'` (default) expects `CODEX_API_KEY`. `'host'` uses `codex login`. See [Harness Auth](../sandbox/auth). | | `apiKey` | OpenAI API key for the harness subprocess. | | `baseUrl` | Override the Codex backend base URL. | | `codexPathOverride` | Use a specific codex executable instead of the SDK's bundled binary. | | `env` | Environment variables for the subprocess. When set, `process.env` is **not** inherited (Codex SDK semantics). | | `config` | Extra `--config key=value` overrides passed to the Codex CLI (e.g. additional `mcp_servers` entries). | -Per-call overrides — `sessionId`, `sandboxMode`, `approvalPolicy`, `modelReasoningEffort`, `workingDirectory`, `skipGitRepoCheck` — go through `modelOptions`. +Per-call overrides go through `modelOptions`: `sessionId`, `sandboxMode`, +`approvalPolicy`, `modelReasoningEffort`, `workingDirectory`, +`skipGitRepoCheck`, and `authMode`. ## Stateful Sessions @@ -170,7 +182,61 @@ const stream = chat({ ## Structured Output -`structuredOutput()` uses Codex's native `outputSchema` support in a fresh, read-only, one-shot thread whose final message is a JSON string conforming to your schema. It works for finalization after a chat, but a plain provider adapter (e.g. `@tanstack/ai-openai`) is the better choice when structured extraction is the primary job — it's faster and doesn't spawn a subprocess. +Pass `outputSchema` on `chat()`. Codex runs one harness turn and constrains the last message with `--output-schema`. Tool activity and assistant text stream as Codex writes them. The last message is also parsed as the schema object and arrives as `structured-output.complete`. + +```ts +import { chat } from "@tanstack/ai" +import { codexText } from "@tanstack/ai-codex" +import { defineSandbox, withSandbox } from "@tanstack/ai-sandbox" +import { dockerSandbox } from "@tanstack/ai-sandbox-docker" +import { z } from "zod" + +const Report = z.object({ + summary: z.string(), + filesChanged: z.array(z.string()), +}) + +const sandbox = defineSandbox({ + id: "repo-report", + provider: dockerSandbox({ image: "node:22" }), +}) + +const report = await chat({ + adapter: codexText("gpt-5.3-codex"), + messages: [{ role: "user", content: "Review this repo." }], + outputSchema: Report, + middleware: [withSandbox(sandbox)], +}) + +report.summary +``` + +On the client, pass the same schema to `useChat` and read `final`. `partial` stays empty until the end. + +```tsx +import { fetchServerSentEvents, useChat } from "@tanstack/ai-react" +import { z } from "zod" + +const Report = z.object({ + summary: z.string(), + filesChanged: z.array(z.string()), +}) + +function ReportView() { + const { final, isLoading } = useChat({ + connection: fetchServerSentEvents("/api/repo-report"), + outputSchema: Report, + }) + + if (isLoading) returnThe agent is inspecting the repo.
+ if (!final) return null + return{final.summary}
+} +``` + +If you only need to extract JSON from a prompt and do not need a sandbox, use `@tanstack/ai-openai`. That path is faster. + +Full walkthrough, including the client: [Harness Agents](../structured-outputs/harnesses). ## Limitations diff --git a/docs/adapters/grok-build.md b/docs/adapters/grok-build.md index 7d1e6600cc..899dffeb09 100644 --- a/docs/adapters/grok-build.md +++ b/docs/adapters/grok-build.md @@ -38,14 +38,23 @@ You also need a sandbox provider (e.g. `@tanstack/ai-sandbox-docker`) and the ## Authentication -Grok Build resolves credentials the same way the `grok` CLI does: +Your laptop can already have `grok login`. A CI runner only has `XAI_API_KEY`. +Both can use the same sandbox provider. The default `authMode` is `'api-key'`. +Set `'host'` when you want `grok login`. See [Harness Auth](../sandbox/auth). -- the `XAI_API_KEY` environment variable (headless / sandbox — inject it as a - workspace secret), or -- an existing grok.com browser login on the machine (local dev). +```ts +import { grokBuildText } from "@tanstack/ai-grok-build" + +grokBuildText("composer-2.5") +grokBuildText("composer-2.5", { authMode: "host" }) +``` + +- `'api-key'` (default): inject `XAI_API_KEY` and authenticate with it. +- `'host'`: skip ACP `authenticate`. Use `grok login`. Do not inject + `XAI_API_KEY` into that process. -The two auth modes expose the model under slightly different ids; the adapter -maps the short alias for you (see [Models](#models)). +The two modes list the model under slightly different ids. The adapter maps +the short alias for you (see [Models](#models)). ## Basic Usage @@ -74,7 +83,7 @@ const sandbox = defineSandbox({ const stream = chat({ threadId, - adapter: grokBuildText('grok-build'), + adapter: grokBuildText('composer-2.5'), messages, middleware: [withSandbox(sandbox)], }) @@ -106,6 +115,8 @@ Adapter config (second argument to `grokBuildText`): | `env` | Extra environment variables for the `grok` process inside the sandbox. | | `emitDiff` | Emit a `file.changed` CUSTOM event with the working-tree `git diff` after the run. Defaults to `true`. | | `protocol` | Harness wire protocol: `'acp'` or `'streaming-json'`. Defaults to `'acp'`. A durable sandbox run with no protocol set uses `'streaming-json'` so the run can journal. | +| `authMode` | `'api-key'` (default) uses `XAI_API_KEY`. `'host'` uses `grok login`. See [Harness Auth](../sandbox/auth). | +| `authMethodId` | Explicit ACP auth method. Wins over `authMode`. | | `extraArgs` | Extra raw CLI flags appended verbatim (advanced). | Per-call overrides go through `modelOptions`: @@ -116,6 +127,8 @@ Per-call overrides go through `modelOptions`: | `cwd` | Per-call override of the harness working directory. | | `maxTurns` | Per-call cap on the number of harness turns. | | `protocol` | Per-call override of the harness wire protocol. | +| `authMode` | Per-call `'host'` or `'api-key'`. Default `'api-key'`. | +| `authMethodId` | Per-call ACP auth method. Wins over `authMode`. | ## Stateful Sessions @@ -185,6 +198,64 @@ On the `'streaming-json'` path with auto-approve, the adapter adds `--always-approve --no-plan --no-auto-update`. Those flags keep Plan Mode and the CLI update check from blocking a headless run. +## Structured Output + +Pass `outputSchema` on `chat()`. Grok Build has no native schema flag. The adapter adds the JSON Schema to the prompt (ACP and `streaming-json`) and parses the last assistant text. Tool activity still streams. The object arrives as `structured-output.complete`. + +```ts +import { chat } from "@tanstack/ai" +import { grokBuildText } from "@tanstack/ai-grok-build" +import { defineSandbox, withSandbox } from "@tanstack/ai-sandbox" +import { dockerSandbox } from "@tanstack/ai-sandbox-docker" +import { z } from "zod" + +const Report = z.object({ + summary: z.string(), + filesChanged: z.array(z.string()), +}) + +const sandbox = defineSandbox({ + id: "repo-report", + provider: dockerSandbox({ image: "node:22" }), +}) + +const report = await chat({ + adapter: grokBuildText("grok-build"), + messages: [{ role: "user", content: "Review this repo." }], + outputSchema: Report, + middleware: [withSandbox(sandbox)], +}) + +report.summary +``` + +This path parses JSON from the last assistant message. If extract-only is the job, use `@tanstack/ai-grok`. + +On the client, pass the same schema to `useChat` and read `final`. `partial` stays empty until the end. + +```tsx +import { fetchServerSentEvents, useChat } from "@tanstack/ai-react" +import { z } from "zod" + +const Report = z.object({ + summary: z.string(), + filesChanged: z.array(z.string()), +}) + +function ReportView() { + const { final, isLoading } = useChat({ + connection: fetchServerSentEvents("/api/repo-report"), + outputSchema: Report, + }) + + if (isLoading) returnThe agent is inspecting the repo.
+ if (!final) return null + return{final.summary}
+} +``` + +Full walkthrough, including the client: [Harness Agents](../structured-outputs/harnesses). + ## Limitations - **Requires a sandbox.** Always run it under `withSandbox(...)`; see the diff --git a/docs/adapters/opencode.md b/docs/adapters/opencode.md index 23ccbb453c..a6915d752e 100644 --- a/docs/adapters/opencode.md +++ b/docs/adapters/opencode.md @@ -175,7 +175,61 @@ const stream = chat({ ## Structured Output -`structuredOutput()` is best-effort: OpenCode's prompt API has no native JSON-schema channel, so the schema is embedded as a prompt instruction in a fresh, one-shot session and the final text is parsed (markdown fences are stripped when present). It works for finalization after a chat, but a plain provider adapter (e.g. `@tanstack/ai-openai`) is the better choice when structured extraction is the primary job — it's faster, deterministic, and doesn't spawn a harness. +Pass `outputSchema` on `chat()`. OpenCode has no native schema flag. The adapter adds the JSON Schema to the prompt and parses the last assistant text (markdown fences are stripped). Tool activity still streams. The object arrives as `structured-output.complete`. + +```ts +import { chat } from "@tanstack/ai" +import { opencodeText } from "@tanstack/ai-opencode" +import { defineSandbox, withSandbox } from "@tanstack/ai-sandbox" +import { dockerSandbox } from "@tanstack/ai-sandbox-docker" +import { z } from "zod" + +const Report = z.object({ + summary: z.string(), + filesChanged: z.array(z.string()), +}) + +const sandbox = defineSandbox({ + id: "repo-report", + provider: dockerSandbox({ image: "node:22" }), +}) + +const report = await chat({ + adapter: opencodeText("anthropic/claude-opus-4-5"), + messages: [{ role: "user", content: "Review this repo." }], + outputSchema: Report, + middleware: [withSandbox(sandbox)], +}) + +report.summary +``` + +This path parses JSON from the last assistant message. If extract-only is the job, use a model adapter such as `@tanstack/ai-openai`. + +On the client, pass the same schema to `useChat` and read `final`. `partial` stays empty until the end. + +```tsx +import { fetchServerSentEvents, useChat } from "@tanstack/ai-react" +import { z } from "zod" + +const Report = z.object({ + summary: z.string(), + filesChanged: z.array(z.string()), +}) + +function ReportView() { + const { final, isLoading } = useChat({ + connection: fetchServerSentEvents("/api/repo-report"), + outputSchema: Report, + }) + + if (isLoading) returnThe agent is inspecting the repo.
+ if (!final) return null + return{final.summary}
+} +``` + +Full walkthrough, including the client: [Harness Agents](../structured-outputs/harnesses). ## Limitations diff --git a/docs/chat/structured-outputs.md b/docs/chat/structured-outputs.md index 425dc56abe..4793bed491 100644 --- a/docs/chat/structured-outputs.md +++ b/docs/chat/structured-outputs.md @@ -17,5 +17,6 @@ The structured-outputs guide has moved to its own top-level section, split by wh - **[Streaming UIs](../structured-outputs/streaming)** — `useChat({ outputSchema })` with `partial` and `final` populating a UI field by field. - **[Multi-Turn Chat](../structured-outputs/multi-turn)** — every assistant turn carries its own typed `StructuredOutputPart`, history stays renderable, and `messages[i].parts.find(p => p.type === "structured-output").data` is typed by your schema. - **[With Tools](../structured-outputs/with-tools)** — combining `outputSchema` with the agent loop, including pause/resume for server-tool approvals and client-tool invocations. +- **[Harness Agents](../structured-outputs/harnesses)** — a coding agent in a sandbox inspects files, then returns a typed object. > **Note:** This URL is kept for backward compatibility. New content lives under `/structured-outputs/*` — update existing bookmarks when you can. diff --git a/docs/config.json b/docs/config.json index 0dd0be3112..65677202e6 100644 --- a/docs/config.json +++ b/docs/config.json @@ -337,17 +337,19 @@ "label": "Overview", "to": "structured-outputs/overview", "addedAt": "2026-05-19", - "updatedAt": "2026-06-10" + "updatedAt": "2026-08-18" }, { "label": "One-Shot Extraction", "to": "structured-outputs/one-shot", - "addedAt": "2026-05-19" + "addedAt": "2026-05-19", + "updatedAt": "2026-08-14" }, { "label": "Streaming UIs", "to": "structured-outputs/streaming", - "addedAt": "2026-05-19" + "addedAt": "2026-05-19", + "updatedAt": "2026-08-18" }, { "label": "Multi-Turn Chat", @@ -358,7 +360,13 @@ "label": "With Tools", "to": "structured-outputs/with-tools", "addedAt": "2026-05-19", - "updatedAt": "2026-07-08" + "updatedAt": "2026-08-14" + }, + { + "label": "Harness Agents", + "to": "structured-outputs/harnesses", + "addedAt": "2026-08-14", + "updatedAt": "2026-08-18" } ] }, @@ -511,25 +519,30 @@ "label": "Overview", "to": "sandbox/overview", "addedAt": "2026-06-16", - "updatedAt": "2026-08-12" + "updatedAt": "2026-08-18" }, { "label": "Quick Start", "to": "sandbox/quick-start", "addedAt": "2026-06-29", - "updatedAt": "2026-08-12" + "updatedAt": "2026-08-18" }, { "label": "Providers", "to": "sandbox/providers", "addedAt": "2026-06-29", - "updatedAt": "2026-08-12" + "updatedAt": "2026-08-18" }, { "label": "Harnesses", "to": "sandbox/harnesses", "addedAt": "2026-06-30", - "updatedAt": "2026-08-04" + "updatedAt": "2026-08-18" + }, + { + "label": "Harness Auth", + "to": "sandbox/auth", + "addedAt": "2026-08-18" }, { "label": "Workspace", @@ -866,30 +879,31 @@ "label": "Claude Code", "to": "adapters/claude-code", "addedAt": "2026-06-12", - "updatedAt": "2026-06-30" + "updatedAt": "2026-08-18" }, { "label": "Codex", "to": "adapters/codex", "addedAt": "2026-06-12", - "updatedAt": "2026-08-12" + "updatedAt": "2026-08-18" }, { "label": "OpenCode", "to": "adapters/opencode", "addedAt": "2026-06-12", - "updatedAt": "2026-06-30" + "updatedAt": "2026-08-17" }, { "label": "Grok Build", "to": "adapters/grok-build", "addedAt": "2026-06-29", - "updatedAt": "2026-08-12" + "updatedAt": "2026-08-18" }, { "label": "ACP-Compatible", "to": "adapters/acp-compatible", - "addedAt": "2026-06-30" + "addedAt": "2026-06-30", + "updatedAt": "2026-08-18" }, { "label": "Amazon Bedrock", diff --git a/docs/sandbox/auth.md b/docs/sandbox/auth.md new file mode 100644 index 0000000000..5f0ef5b5ee --- /dev/null +++ b/docs/sandbox/auth.md @@ -0,0 +1,165 @@ +--- +title: Harness Auth +id: sandbox-auth +description: "Pick host login or an API key for a coding-agent harness. The same local-process sandbox can be your laptop or a CI runner." +--- + +Your laptop already has `grok login`, `claude login`, or `codex login`. A GitHub +runner has no browser login. It only has an API key. Both can use +`localProcessSandbox()`. + +Set `authMode` on the adapter. The sandbox type does not pick the credentials. +The default is `'api-key'`. Most harnesses run in Docker or a cloud sandbox. +Those have no host CLI login. + +- `'api-key'` (default): inject the key and use it. +- `'host'`: use the CLI login on the machine. Do not inject an API key into + that process. + +Pass `authMode` in one of two places: + +- Adapter factory: `grokBuildText('composer-2.5', { authMode: 'host' })` +- One call: `chat({ modelOptions: { authMode: 'host' } })` + +## Host login + +Use this when the machine already ran `grok login`, `claude login`, or +`codex login`. + +```ts +import { chat } from '@tanstack/ai' +import { grokBuildText } from '@tanstack/ai-grok-build' +import { defineSandbox, defineWorkspace, withSandbox } from '@tanstack/ai-sandbox' +import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process' +import { messages, threadId } from './chat-context' + +const sandbox = defineSandbox({ + id: 'repo-agent', + provider: localProcessSandbox({ + scrubEnv: ['XAI_API_KEY', 'GROK_API_KEY'], + }), + workspace: defineWorkspace({ + source: { type: 'local', path: '/abs/path/to/repo' }, + }), +}) + +const stream = chat({ + threadId, + adapter: grokBuildText('composer-2.5', { authMode: 'host' }), + messages, + middleware: [withSandbox(sandbox)], +}) +``` + +`scrubEnv` removes keys the host process inherited. If the CLI sees +`XAI_API_KEY`, it can prefer that key over your login. + +## API key + +This is the default. Use it on a runner, in Docker, or on any machine that +has no CLI login. You can omit `authMode`. + +```ts +import { chat } from '@tanstack/ai' +import { grokBuildText } from '@tanstack/ai-grok-build' +import { + createSecrets, + defineSandbox, + defineWorkspace, + githubRepo, + withSandbox, +} from '@tanstack/ai-sandbox' +import { dockerSandbox } from '@tanstack/ai-sandbox-docker' +import { messages, threadId } from './chat-context' + +const sandbox = defineSandbox({ + id: 'repo-agent', + provider: dockerSandbox({ image: 'node:22' }), + workspace: defineWorkspace({ + source: githubRepo({ repo: 'owner/app' }), + secrets: createSecrets({ + XAI_API_KEY: process.env.XAI_API_KEY ?? '', + }), + }), +}) + +const stream = chat({ + threadId, + adapter: grokBuildText('composer-2.5'), + messages, + middleware: [withSandbox(sandbox)], +}) +``` + +## Each harness + +| Adapter | `authMode: 'api-key'` (default) | `authMode: 'host'` | +| --- | --- | --- | +| [Grok Build](../adapters/grok-build) | `XAI_API_KEY` | `grok login` | +| [Claude Code](../adapters/claude-code) | `ANTHROPIC_API_KEY` | `claude login` | +| [Codex](../adapters/codex) | `CODEX_API_KEY` | `codex login` | +| [ACP-Compatible](../adapters/acp-compatible) | set `authMethodId` (for Grok, `xai.api_key`) | skip ACP `authenticate` | + +OpenCode still reads `OPENAI_API_KEY` from the process env. It has no `authMode` +flag. + +## Client and server + +The React chat example exposes the same choice on `/repo-report`. The client +sends `authMode`. The server builds the adapter with that value. + +Client: + +```tsx +import { fetchServerSentEvents, useChat } from '@tanstack/ai-react' + +function Report() { + const { sendMessage } = useChat({ + connection: fetchServerSentEvents('/api/sandbox-repo-report'), + forwardedProps: { authMode: 'api-key' }, + }) + + return ( + + ) +} +``` + +Server: + +```ts +import { chat, toServerSentEventsResponse } from '@tanstack/ai' +import { grokBuildText } from '@tanstack/ai-grok-build' +import { withSandbox } from '@tanstack/ai-sandbox' +import { sandbox } from './sandbox' + +export async function POST(request: Request) { + const body: unknown = await request.json() + const forwarded = + typeof body === 'object' && + body !== null && + 'forwardedProps' in body && + typeof body.forwardedProps === 'object' && + body.forwardedProps !== null + ? body.forwardedProps + : {} + const authMode = + 'authMode' in forwarded && forwarded.authMode === 'host' + ? 'host' + : 'api-key' + + const stream = chat({ + adapter: grokBuildText('composer-2.5', { authMode }), + messages: [{ role: 'user', content: 'Report on this repo' }], + stream: true, + middleware: [withSandbox(sandbox)], + }) + + return toServerSentEventsResponse(stream) +} +``` + +See [Harnesses](./harnesses) for which adapter to pick, and [Providers](./providers) +for `scrubEnv` on local-process. diff --git a/docs/sandbox/harnesses.md b/docs/sandbox/harnesses.md index 21da0c4b4a..a24081697a 100644 --- a/docs/sandbox/harnesses.md +++ b/docs/sandbox/harnesses.md @@ -18,12 +18,17 @@ fast at the call site unless a sandbox is provided via `withSandbox(...)`. Each agent has its own package with curated per-model metadata. Pass the adapter to `chat({ adapter })` and run it under any provider. -| Harness | Package | Adapter | Auth env | +| Harness | Package | Adapter | Auth | | --- | --- | --- | --- | -| [Grok Build](../adapters/grok-build) | `@tanstack/ai-grok-build` | `grokBuildText` | `XAI_API_KEY` (or grok.com login on local-process) | -| [Claude Code](../adapters/claude-code) | `@tanstack/ai-claude-code` | `claudeCodeText` | `ANTHROPIC_API_KEY` (or `claude login`) | -| [Codex](../adapters/codex) | `@tanstack/ai-codex` | `codexText` | `CODEX_API_KEY` (or `OPENAI_API_KEY`) | -| [OpenCode](../adapters/opencode) | `@tanstack/ai-opencode` | `opencodeText` | `OPENAI_API_KEY` (model-dependent) | +| [Grok Build](../adapters/grok-build) | `@tanstack/ai-grok-build` | `grokBuildText` | Default `'api-key'` (`XAI_API_KEY`). `'host'` uses `grok login`. | +| [Claude Code](../adapters/claude-code) | `@tanstack/ai-claude-code` | `claudeCodeText` | Default `'api-key'` (`ANTHROPIC_API_KEY`). `'host'` uses `claude login`. | +| [Codex](../adapters/codex) | `@tanstack/ai-codex` | `codexText` | Default `'api-key'` (`CODEX_API_KEY`). `'host'` uses `codex login`. | +| [OpenCode](../adapters/opencode) | `@tanstack/ai-opencode` | `opencodeText` | `OPENAI_API_KEY` from the process env. No `authMode` flag. | +| [ACP-Compatible](../adapters/acp-compatible) | `@tanstack/ai-acp` | `acpCompatible` / `acpCompatibleText` | Default `'api-key'` uses `authMethodId`. `'host'` skips ACP `authenticate`. | + +The provider is where the agent runs, not how it signs in. The default +`authMode` is `'api-key'`. Set `'host'` when the machine already has a CLI +login. See [Harness Auth](./auth). ```ts import { chat } from '@tanstack/ai' @@ -39,6 +44,10 @@ const stream = chat({ }) ``` +## Typed report from a harness + +If you want a typed object after the agent inspects the repo, pass `outputSchema` on the same `chat()` call. Dedicated adapters and `acpCompatible` honor it. See [Harness Agents](../structured-outputs/harnesses). + ## Harness output can go to a journal `grokBuildText`, `claudeCodeText`, and `codexText` can stop holding the agent's @@ -120,6 +129,7 @@ and protocol coverage). For which agents you can plug in, browse the official ## Where to go next +- **[Harness Auth](./auth)**: pick host login or an API key. The sandbox type does not pick this. - **[Providers](./providers)**: where the harness runs (local, Docker, Daytona, Vercel, Sprites). - **[The Run Journal](./journal)**: how a run's output survives the host that started it. - **[Takeover & Detached Runs](./takeover)**: detach on disconnect, and the three exports a harness adapter implements to support attach. diff --git a/docs/sandbox/overview.md b/docs/sandbox/overview.md index 79259a6b84..cf8f3064f4 100644 --- a/docs/sandbox/overview.md +++ b/docs/sandbox/overview.md @@ -66,6 +66,10 @@ any one without touching the others. hooks) into a reusable definition. `withSandbox(definition)` is the `chat()` middleware that turns it on for a run. +The provider is where the agent runs, not how it signs in. The default +`authMode` is `'api-key'`. Set `'host'` when the machine already has a CLI +login. See [Harness Auth](./auth). + ### How a run executes ```txt @@ -112,6 +116,8 @@ After that, pick the piece you need: (`sbxSandbox`), Daytona, Vercel, Sprites, and what each one can do. - [Harnesses](./harnesses): which agent runs. Grok Build, Claude Code, Codex, OpenCode, or any ACP agent. +- [Harness Auth](./auth): host CLI login or an API key. The sandbox type does + not pick this. - [Workspace](./workspace): the source repo, clone depth, and setup commands. - [Tools](./tools): bridge your app's own tools into the in-sandbox agent. - [Policy](./policy): allow, ask or deny guardrails on what the agent may run. @@ -127,7 +133,7 @@ build an adapter. ## Try it -Two runnable demos: +Three runnable demos: - [`examples/sandbox-web`](https://github.com/TanStack/ai/tree/main/examples/sandbox-web): a "build me an app" agent on Docker with durable runs wired. It scaffolds an app, @@ -135,3 +141,7 @@ Two runnable demos: and a closed tab, and Stop is a real cancel. - [`examples/sandbox-cloudflare`](https://github.com/TanStack/ai/tree/main/examples/sandbox-cloudflare): the same idea at the edge, with the harness picked per run from the UI. +- [`examples/ts-react-chat`](https://github.com/TanStack/ai/tree/main/examples/ts-react-chat) + at `/repo-report`: clone `TanStack/ai`, pick the harness, pick Auth + (`host` or `api-key`), and read a typed report from `useChat().final`. See + [Harness Agents](../structured-outputs/harnesses). diff --git a/docs/sandbox/providers.md b/docs/sandbox/providers.md index be63e7f340..5c59e605ca 100644 --- a/docs/sandbox/providers.md +++ b/docs/sandbox/providers.md @@ -61,30 +61,36 @@ const dev = localProcessSandbox() - **Isolation:** none. The harness runs directly on your host, inheriting your host environment. Use it for trusted or dev work only. There is no boundary between the agent and your machine. -- **Auth / env:** inherits the host environment. No API key injection is required - if your host CLI is already logged in. +- **Auth / env:** inherits the host environment. Set `authMode` on the harness + (`'host'` or `'api-key'`). The provider does not pick this. See + [Harness Auth](./auth). - **Snapshot / resume:** no snapshots and no durable resume-by-id; each run re-creates and re-bootstraps under the same identity. The snapshot step is skipped silently (see [Capabilities](#capabilities)). -### Use a host CLI's own auth (`scrubEnv`) +### Host login vs API key (`scrubEnv`) -Because `localProcessSandbox` runs the harness on your host, it inherits your host -environment, including any API keys exported there. Use `scrubEnv` to remove -variables before spawning, so the host CLI falls back to its own logged-in -session instead of billing the API. For example, drop `XAI_API_KEY` so Grok Build -uses your **grok.com login** (the same trick works for Claude Code with -`ANTHROPIC_API_KEY` → `claude login`): +The provider is where the agent runs, not how it signs in. The default +`authMode` is `'api-key'`. Set `'host'` when the machine already has a CLI +login. A local-process run can be your laptop or a GitHub runner. See +[Harness Auth](./auth). + +`localProcessSandbox` inherits the host environment, including any API keys +exported there. If you set `authMode: 'host'`, pass `scrubEnv` so those keys +do not override the CLI login: ```ts import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process' -const hostLogin = localProcessSandbox({ scrubEnv: ['XAI_API_KEY'] }) +const hostLogin = localProcessSandbox({ + scrubEnv: ['XAI_API_KEY', 'GROK_API_KEY'], +}) ``` -> Only local-process can do this. It is the only provider that runs your host -> CLI. Isolated and cloud providers have no host login, so they always use an -> injected API key (supplied as a workspace secret). +If the same local-process sandbox runs on a CI machine, set +`authMode: 'api-key'`. Then inject the key as a workspace secret. Isolated and +cloud providers have no host CLI login. Use `authMode: 'api-key'` and +workspace secrets there. ### Windows process teardown (`logger`) diff --git a/docs/sandbox/quick-start.md b/docs/sandbox/quick-start.md index fc9050e117..0da2a70bc2 100644 --- a/docs/sandbox/quick-start.md +++ b/docs/sandbox/quick-start.md @@ -135,23 +135,42 @@ npm i @tanstack/ai-sandbox-local-process ``` ```ts +import { chat } from '@tanstack/ai' +import { grokBuildText } from '@tanstack/ai-grok-build' +import { + defineSandbox, + defineWorkspace, + githubRepo, + withSandbox, +} from '@tanstack/ai-sandbox' import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process' -import { defineSandbox, defineWorkspace, githubRepo } from '@tanstack/ai-sandbox' +import { messages } from './chat-context' export const repoSandbox = defineSandbox({ id: 'bug-fixer', - provider: localProcessSandbox(), + provider: localProcessSandbox({ + scrubEnv: ['XAI_API_KEY', 'GROK_API_KEY'], + }), workspace: defineWorkspace({ source: githubRepo({ repo: 'owner/buggy-app' }), setup: ['corepack enable', 'pnpm install'], }), lifecycle: { reuse: 'thread' }, }) + +const stream = chat({ + adapter: grokBuildText('composer-2.5', { authMode: 'host' }), + messages, + middleware: [withSandbox(repoSandbox)], +}) ``` -Because local-process inherits your host environment, you can drop the -`XAI_API_KEY` secret and let Grok Build fall back to your grok.com login. For that -(and for Daytona, Vercel, Sprites, and Cloudflare runtimes), see [Providers](./providers). +Set `authMode: 'host'` so the adapter uses `grok login`. `scrubEnv` removes +keys the host process inherited. Those keys would override the login. + +A local-process run can also be a CI runner. That machine has no browser +login. Set `authMode: 'api-key'`. Then inject `XAI_API_KEY` as a workspace +secret. The sandbox type does not pick this. See [Harness Auth](./auth). ## Docker Sandboxes microVM (sbx) diff --git a/docs/structured-outputs/harnesses.md b/docs/structured-outputs/harnesses.md new file mode 100644 index 0000000000..543813bb8a --- /dev/null +++ b/docs/structured-outputs/harnesses.md @@ -0,0 +1,218 @@ +--- +title: Harness Structured Output +id: structured-outputs-harnesses +order: 6 +description: "Ask a coding agent in a sandbox to inspect a repo, then read a typed object from chat({ outputSchema }). Works with Claude Code, Codex, OpenCode, Grok Build, and acpCompatible." +keywords: + - tanstack ai + - structured outputs + - harness + - claude code + - codex + - opencode + - grok build + - outputSchema + - sandbox +--- + +You asked a coding agent to inspect a repository. The agent streams tool calls and prose. You need a typed object you can store or render, not a wall of text to parse. + +Pass `outputSchema` on the same `chat()` call. The harness runs its native tools. Then you get a validated object from `await chat()` or from `useChat().final`. + +This page is for sandbox harness adapters: + +- [Claude Code](../adapters/claude-code) +- [Codex](../adapters/codex) +- [OpenCode](../adapters/opencode) +- [Grok Build](../adapters/grok-build) +- [ACP-Compatible](../adapters/acp-compatible) (`acpCompatible`) + +If you only extract JSON from a prompt and you do not need a sandbox, use [One-Shot Extraction](./one-shot) with an HTTP adapter. + +## Define the schema + +```typescript group=harness-output +import { z } from "zod"; + +export const ReportSchema = z.object({ + name: z.string(), + oneLiner: z.string(), + audience: z.string(), + mainPackages: z.array( + z.object({ + name: z.string(), + role: z.string(), + }), + ), + howToRun: z.string(), +}); +``` + +The return type follows from the schema. You do not need a cast. + +## Server: sandbox plus outputSchema + +The harness needs a sandbox. Pass `withSandbox(...)`. If the client reads the stream, pass `stream: true`. Without `stream: true`, `chat()` returns a `Promise`, not SSE. + +```typescript group=harness-output +import { chat, toServerSentEventsResponse } from "@tanstack/ai"; +import { claudeCodeText } from "@tanstack/ai-claude-code"; +import { + defineSandbox, + defineWorkspace, + githubRepo, + withSandbox, +} from "@tanstack/ai-sandbox"; +import { dockerSandbox } from "@tanstack/ai-sandbox-docker"; + +const sandbox = defineSandbox({ + id: "repo-report", + provider: dockerSandbox({ image: "node:22" }), + workspace: defineWorkspace({ + source: githubRepo({ repo: "TanStack/ai" }), + }), +}); + +export async function POST(request: Request) { + const body: unknown = await request.json(); + const messages = + typeof body === "object" && + body !== null && + "messages" in body && + Array.isArray(body.messages) + ? body.messages + : []; + + const stream = chat({ + adapter: claudeCodeText("claude-opus-4-8"), + messages, + outputSchema: ReportSchema, + stream: true, + middleware: [withSandbox(sandbox)], + }); + + return toServerSentEventsResponse(stream); +} +``` + +Swap the adapter to change the agent: + +- `codexText("gpt-5.3-codex")` +- `opencodeText("anthropic/claude-opus-4-5")` +- `grokBuildText("composer-2.5")` +- `acpCompatibleText(...)` for any ACP CLI. See [ACP-Compatible](../adapters/acp-compatible). + +The typed object arrives as a `structured-output.complete` event. Tool activity streams first. + +## Client: read `parts` and `final` + +The assistant message holds the live run. Walk `messages[].parts` for tool calls, reasoning, and the typed object. `useChat().final` is a shortcut for the latest `structured-output` part. + +```tsx group=harness-output +import { useChat, fetchServerSentEvents } from "@tanstack/ai-react"; + +function RepoReport() { + const { messages, sendMessage, isLoading, final } = useChat({ + connection: fetchServerSentEvents("/api/repo-report"), + outputSchema: ReportSchema, + }); + + return ( + <> + + {messages.map((message) => ( +{part.content}
; + } + if (part.type === "tool-call") { + return ( ++ {part.name} ({part.state}) +
+ ); + } + if (part.type === "text") { + return{part.content}
; + } + if (part.type === "structured-output") { + const report = part.data ?? part.partial; + return report?.name ?{final.oneLiner}
: null} + + ); +} +``` + +Each part type: + +- `thinking`: harness reasoning, when the agent emits it +- `tool-call`: native harness tools such as `Read` or `Bash` +- `text`: prose the agent writes before the JSON +- `structured-output`: the schema object. `part.data` is the validated value. `part.partial` is a progressive parse when the adapter streams JSON text. `part.raw` is the source string. + +`final` is typed as the schema. It stays `null` until `structured-output.complete` arrives. It always matches the latest assistant turn. Older turns stay on their own `structured-output` parts. + +`partial` stays empty on harness adapters. The object is not streamed field by field. Render tool calls from `messages` while you wait. See [Streaming UIs](./streaming) for the `partial` / `final` shape. + +## How each harness applies the schema + +| Adapter | How the schema is applied | +|---|---| +| Claude Code | Native `--json-schema` flag on the same turn. The value is inline JSON, not a file path. | +| Codex | Native `--output-schema` flag on the same turn. Assistant text streams as Codex writes it. The last message is also the schema object. | +| OpenCode | Schema is added to the prompt. The adapter parses the last assistant text. | +| Grok Build | Schema is added to the prompt. The adapter parses the last assistant text. | +| ACP compatible | Schema is added to the prompt. The adapter parses the last assistant text. | + +OpenCode, Grok Build, and `acpCompatible` parse JSON from the last assistant message. That parse fails if the message is not JSON. If the job is extract-only and you do not need a sandbox, use `@tanstack/ai-openai` or `@tanstack/ai-grok`. + +## Approval gates and client tools + +Harness adapters run tools inside the sandbox. They do not pause for a browser round-trip. + +- A tool without a server `execute()` fails fast. +- A tool with `needsApproval` fails fast. + +If you need approval gates or client tools, use [With Tools](./with-tools) with an HTTP adapter. + +## Script without a UI + +If you do not stream to a browser, omit `stream: true`. The promise resolves with the typed object. + +```typescript group=harness-output +const report = await chat({ + adapter: claudeCodeText("claude-opus-4-8"), + messages: [{ role: "user", content: "What is this repository about?" }], + outputSchema: ReportSchema, + middleware: [withSandbox(sandbox)], +}); + +report.name; +report.oneLiner; +``` + +## Try it + +The React chat example includes a repo-report page. + +1. Open [`examples/ts-react-chat`](https://github.com/TanStack/ai/tree/main/examples/ts-react-chat). +2. Open `/repo-report`. +3. Pick Claude Code, Grok Build, ACP compatible, or Codex. +4. Pick Auth. The default is **API key**. Use **Host login** if the machine already ran `claude login`, `grok login`, or `codex login`. +5. Run the report. The page renders tool calls and reasoning from `messages[].parts`. It reads the typed object from the `structured-output` part and from `useChat().final`. + +The page clones `TanStack/ai` into a sandbox, asks the agent to inspect it, and shows the validated report. + +Claude Code does not need you to accept a trust dialog for that clone. The adapter loads only user settings, so the clone's `.claude/settings.json` does not block headless `-p`. Host login uses your host `claude login`. The sandbox type does not pick this. See [Harness Auth](../sandbox/auth). diff --git a/docs/structured-outputs/one-shot.md b/docs/structured-outputs/one-shot.md index 183181b88f..2e43cb4684 100644 --- a/docs/structured-outputs/one-shot.md +++ b/docs/structured-outputs/one-shot.md @@ -17,7 +17,7 @@ You have unstructured input — a paragraph of text, a freeform user prompt, the By the end of this guide you'll have a working `chat({ outputSchema })` call returning a fully-typed result, know how to describe fields so the model fills them correctly, and have a pattern for handling validation errors. -> **Note:** If you want to stream the result field-by-field into a UI, you want [Streaming UIs](./streaming) instead. If you want users to iterate on the object across multiple turns, you want [Multi-Turn Chat](./multi-turn). This page is for the single-extraction case. +> **Note:** If you want to stream the result field-by-field into a UI, you want [Streaming UIs](./streaming) instead. If you want users to iterate on the object across multiple turns, you want [Multi-Turn Chat](./multi-turn). If the model must inspect files in a sandbox first, you want [Harness Agents](./harnesses). This page is for the single-extraction case. ## Basic Usage diff --git a/docs/structured-outputs/overview.md b/docs/structured-outputs/overview.md index 18edaac6e5..79d1ad1c3f 100644 --- a/docs/structured-outputs/overview.md +++ b/docs/structured-outputs/overview.md @@ -57,8 +57,10 @@ Every adapter handles structured output through its provider's native API: | Google Gemini | `responseSchema` | | Ollama | JSON mode with schema | | OpenRouter / Grok / Groq | `response_format` with `json_schema` | +| Claude Code / Codex | Native schema flag on the same harness turn (`--json-schema` / `--output-schema`) | +| OpenCode / Grok Build / ACP compatible | Same-turn prompt-and-parse | -The provider-specific details are handled for you — the same `chat({ outputSchema })` call works across all of them. +The provider-specific details are handled for you. The same `chat({ outputSchema })` call works across all of them. For a coding agent in a sandbox, see [Harness Agents](./harnesses). ### Anthropic schema complexity limits @@ -75,7 +77,7 @@ Anthropic's exact limits change over time and aren't all published, so we delibe ## Which page do I read? -Pick the journey that matches what you're building. The four guides under "Structured Outputs" cover non-overlapping use cases — read the one that fits, not all of them. +Pick the journey that matches what you're building. The guides under Structured Outputs cover separate use cases. Read the one that fits. | You want to… | Read | |---|---| @@ -83,6 +85,7 @@ Pick the journey that matches what you're building. The four guides under "Struc | Build a UI that fills in field-by-field as the model streams (progressive form, live card, typewriter preview) | [Streaming UIs](./streaming) | | Let users iterate on a structured object across multiple turns — each turn produces a new typed object and history stays renderable | [Multi-Turn Chat](./multi-turn) | | Combine structured output with tool calls (agent loop that runs tools first, then returns a typed object) | [With Tools](./with-tools) | +| Ask a coding agent in a sandbox to inspect files, then return a typed object | [Harness Agents](./harnesses) | The streaming and multi-turn paths both build on `useChat({ outputSchema })`. The "with tools" path layers on top of either. Pick the one that describes your shipping shape — start there, follow the cross-links when you need a piece of another story. diff --git a/docs/structured-outputs/streaming.md b/docs/structured-outputs/streaming.md index cd37c21c7a..01c3f5bb77 100644 --- a/docs/structured-outputs/streaming.md +++ b/docs/structured-outputs/streaming.md @@ -93,7 +93,7 @@ What the hook does for you: - **`partial`** is `DeepPartial{part.content}
; + } + if (part.type === "structured-output") { + return ( +{report.oneLiner}
: null} + {report.audience ? ( ++ Audience: + {report.audience} +
+ ) : null} + {packages.length > 0 ? ( +{report.howToRun}
+ ) : null} +
+ Clone {REPORT_REPO}, pick a harness (including ACP compatible), and
+ grab a typed report from{' '}
+ messages[].parts and{' '}
+ outputSchema.
+
+ {chat.error.message} +
+ ) : null} + + {waiting ? ( ++ Starting the sandbox and the agent. Tool calls and text show up + here as they arrive. Codex can take a few minutes before the first + line. +
+ ) : null} + + {chat.messages.map((message) => ( ++ {part.content} +
+ ) + } + if (part.type === 'text' && part.content) { + if (report && isCompleteReportJson(part.content)) return null + return ( ++ {part.content} +
+ ) + } + if (part.type === 'tool-call') { + return ( ++ tool {part.name} + {part.state ? ` (${part.state})` : ''} +
+ ) + } + if (part.type === 'structured-output') { + const data = part.data ?? part.partial + if (!looksLikeReport(data)) return null + return+ Pick Claude Code, Grok Build, ACP compatible, or Codex, pick an + agent, then Run. The sandbox clones {REPORT_REPO} and the typed + report lands here. +
+ ) : null} +