@tanstack/ai-acp 0.1.0

package/README.md

@@ -0,0 +1,428 @@
+# @tanstack/ai-acp
+
+Shared [Agent Client Protocol](https://agentclientprotocol.com) (ACP) plumbing for TanStack AI **harness adapters** — the code that turns a coding-agent CLI (`grok`, `gemini --acp`, …) into a `chat()` backend inside a sandbox.
+
+Most apps should use a harness package directly (`@tanstack/ai-grok-build`, …). Reach for `@tanstack/ai-acp` when:
+
+- you want to plug an ACP agent that **has no dedicated adapter package** into a sandbox — use [`acpCompatible`](#plug-in-any-acp-agent-acpcompatible) (the `openaiCompatible` of harnesses), or
+- you are **building or extending** a harness adapter and need the transport, session, permission, and stream-translation layers in one place.
+
+## Installation
+
+```bash
+npm install @tanstack/ai-acp @tanstack/ai @tanstack/ai-sandbox
+```
+
+Peer dependencies: `@tanstack/ai`, `@tanstack/ai-sandbox`. The package also depends on [`@agentclientprotocol/sdk`](https://www.npmjs.com/package/@agentclientprotocol/sdk) for the JSON-RPC client.
+
+## What it does
+
+Harness CLIs that support ACP expose a long-lived JSON-RPC session. They stream **session updates** (text chunks, tool calls, planning, permissions) while the orchestrator drives the turn with `prompt`. TanStack AI speaks **AG-UI `StreamChunk`s** (`RUN_STARTED`, `TEXT_MESSAGE_CONTENT`, `TOOL_CALL_*`, `RUN_FINISHED`, …).
+
+`@tanstack/ai-acp` sits in the middle:
+
+```
+┌─────────────────┐     ACP JSON-RPC      ┌──────────────────┐
+│  Harness CLI    │ ◄──────────────────► │  startAcpSession │
+│  (in sandbox)   │   stdio or WebSocket │  (ClientSide)    │
+└─────────────────┘                      └────────┬─────────┘
+                                                  │ session updates
+                                                  ▼
+                                         ┌──────────────────┐
+                                         │  AsyncQueue      │
+                                         │  translateAcpStream │
+                                         └────────┬─────────┘
+                                                  │ StreamChunk
+                                                  ▼
+                                         ┌──────────────────┐
+                                         │  chat() stream   │
+                                         └──────────────────┘
+```
+
+Responsibilities split roughly as:
+
+| Layer              | Module                   | Role                                                                       |
+| ------------------ | ------------------------ | -------------------------------------------------------------------------- |
+| **Transport**      | `transport/*`            | Bytes ↔ JSON-RPC: stdio (NDJSON) or WebSocket                              |
+| **Session**        | `session/acp-client`     | `initialize` → `authenticate` → `newSession` / `loadSession` → `prompt`    |
+| **Sandbox server** | `session/sandbox-server` | Boot an in-sandbox `serve` process and connect over an exposed port        |
+| **Translation**    | `stream/translate`       | ACP `sessionUpdate` events → TanStack `StreamChunk`s                       |
+| **Permissions**    | `permissions`            | Map harness permission prompts to allow/reject (and optional approval ids) |
+
+## Plug in any ACP agent (`acpCompatible`)
+
+`acpCompatible` is the **easy path**: it builds a `chat()` text adapter for any
+ACP-compliant agent CLI without a dedicated package — the harness equivalent of
+`openaiCompatible`. Configure the harness once, select a model per call, pass it
+into a sandbox.
+
+```typescript
+import { acpCompatible } from '@tanstack/ai-acp'
+import { chat } from '@tanstack/ai'
+import { defineSandbox, withSandbox } from '@tanstack/ai-sandbox'
+import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
+
+// Configure the "pi" agent harness once (it speaks ACP over stdio):
+const pi = acpCompatible({
+  name: 'pi',
+  models: ['pi-fast', 'pi-pro'], // optional — makes pi('…') type-safe
+  command: ({ model, harnessCwd }) =>
+    `pi --acp -m ${model} --cwd ${harnessCwd}`,
+  authMethodId: 'pi-api-key', // when the harness advertises it
+  refusalMessage: 'Pi refused the request.',
+})
+
+// Then drive it like any other adapter, inside a sandbox:
+const stream = chat({
+  adapter: pi('pi-fast'),
+  messages: [
+    { role: 'user', content: 'Add a health check route and run the tests.' },
+  ],
+  middleware: [
+    withSandbox(
+      defineSandbox({
+        id: 'pi-demo',
+        provider: dockerSandbox({ image: 'node:22' }),
+        // …workspace: clone source, install the `pi` CLI, inject its API key
+      }),
+    ),
+  ],
+})
+```
+
+You get the full ACP flow for free: sandbox resolution, `chat()`-tool → MCP
+bridging, session resume (via `modelOptions.sessionId`), permission modes,
+abort, and AG-UI translation.
+
+### Configuration
+
+| Field                 | Purpose                                                                                                                                                                                  |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name` (required)     | Provider label, log prefix, and the `<name>.session-id` CUSTOM event name.                                                                                                               |
+| `models`              | Model ids the harness accepts — declaring them makes `harness('id')` type-safe. Omit to accept any string.                                                                               |
+| `modelOptions`        | Type-only brand (`{} as { … }`) for the per-call options of `chat({ modelOptions })`; merged with the base options and exposed on `ctx.modelOptions`.                                    |
+| `command`             | Build the **stdio** launch command (`({ model, cwd, harnessCwd, sandbox, env, modelOptions, signal }) => string`). Required unless `openTransport` is given.                             |
+| `openTransport`       | Full transport escape hatch — open any `AcpSessionTransport` yourself (e.g. boot a `serve` process and connect over WebSocket). Overrides `command`.                                     |
+| `cwd`                 | Working directory inside the sandbox (default `/workspace`).                                                                                                                             |
+| `skillsDir`           | The harness's skills dir relative to the workspace root (e.g. `'.pi/skills'`) — `withSandbox` workspace `gitSkill`s are linked here. MCP skills ride ACP natively, so they need no path. |
+| `env`                 | Extra environment variables for the harness process.                                                                                                                                     |
+| `authMethodId`        | ACP auth method to select before the session starts.                                                                                                                                     |
+| `permissionMode`      | `'default'` \| `'acceptEdits'` \| `'bypassPermissions'` (default).                                                                                                                       |
+| `permissions`         | `'headless'` (auto-resolve, default) or `'interactive'` (emit approval-requested events for `ask` prompts).                                                                              |
+| `onPermissionRequest` | Custom `PermissionHandler`; overrides `permissions`/`permissionMode`.                                                                                                                    |
+| `refusalMessage`      | `RUN_ERROR` message when the harness refuses.                                                                                                                                            |
+| `planEventName`       | Emit ACP `plan` updates as a CUSTOM event under this name.                                                                                                                               |
+| `emitDiff`            | Emit the post-run `git diff` of `cwd` as a `file.changed` CUSTOM event (off by default).                                                                                                 |
+| `onExtNotification`   | Handle vendor `_x/…` JSON-RPC notifications.                                                                                                                                             |
+| `buildPrompt`         | Override how chat history maps to the harness prompt (defaults to `buildAcpPrompt`).                                                                                                     |
+
+For WebSocket/`serve` harnesses, return your own transport from `openTransport`
+(see how `@tanstack/ai-grok-build` boots `grok agent serve` with
+`startAcpServerInSandbox` + `connectAcpWebSocket`). Use `acpCompatibleText(model,
+config)` for a one-shot single-model adapter.
+
+### Protocol coverage
+
+This is a compliant **minimal client** for the orchestration role — it drives a
+full prompt turn, not the entire spec surface. Everything it omits is either
+capability-gated (advertising non-support _is_ the spec-defined behavior) or a
+rendering choice, not a violation.
+
+- **Covered:** `initialize` (with `clientInfo` + version negotiation),
+  `authenticate`, `session/new`, `session/load`, `session/prompt`,
+  `session/cancel`, `session/request_permission` (all four option kinds), the
+  turn-output updates (`agent_message_chunk`, `agent_thought_chunk`, `tool_call`,
+  `tool_call_update`, `plan`), and all five stop reasons.
+- **Surfaced as `CUSTOM` events** (the AG-UI chat-event protocol has no
+  first-class event for non-text assistant _output_): `<name>.session-id`, the
+  plan event, and `<name>.message-content` for non-text agent content (image /
+  audio / resource blocks). Non-text **tool** content is preserved inside the
+  `TOOL_CALL_RESULT` payload.
+- **Workspace projection:** MCP skills → ACP `mcpServers` natively;
+  `gitSkill`s → linked into `skillsDir`; `fileSkill`/`instructions`/`secrets` →
+  handled by bootstrap. `agentSkill`/`plugins` are warned-and-skipped.
+- **Not implemented (by design):** `fs/read_text_file`, `fs/write_text_file`,
+  `terminal/*` (advertised unsupported — the agent has direct sandbox FS/shell
+  access); sending multimodal _prompts_ (text only); incremental `usage_update`
+  (final usage is reported); `available_commands_update` / `current_mode_update`;
+  and experimental features (elicitation, NES, providers, session modes).
+
+## Quick start (building a harness adapter)
+
+If `acpCompatible` doesn't fit (you need a typed provider-options surface, custom
+structured output, vendor projections, …), build the adapter by hand. The
+pattern every ACP harness adapter follows:
+
+1. Spawn the CLI inside a sandbox (`withSandbox` middleware).
+2. Open an ACP transport (stdio or WebSocket).
+3. Call `startAcpSession` and wire `onUpdate` / `onPermissionRequest`.
+4. Push events into an `AsyncQueue`, call `session.prompt`, then `translateAcpStream`.
+5. Emit a **CUSTOM** session-id chunk so follow-up runs can `loadSession`.
+
+```typescript
+import { chat } from '@tanstack/ai'
+import {
+  AsyncQueue,
+  resolveInteractivePermission,
+  spawnHandleToAcpTransport,
+  startAcpSession,
+  translateAcpStream,
+} from '@tanstack/ai-acp'
+import { withSandbox } from '@tanstack/ai-sandbox'
+
+// Inside your adapter's chatStream():
+const proc = await sandbox.process.spawn('my-cli --acp -m auto', {
+  cwd: '/workspace',
+})
+
+const queue = new AsyncQueue()
+const session = await startAcpSession({
+  transport: { kind: 'stdio', process: proc },
+  cwd: '/workspace',
+  authMethodId: 'gemini-api-key', // when the harness advertises it
+  resumeSessionId: options.modelOptions?.sessionId,
+  mcpServers: bridge
+    ? [
+        {
+          name: bridge.name,
+          url: bridge.url,
+          headers: [{ name: 'Authorization', value: `Bearer ${bridge.token}` }],
+        },
+      ]
+    : undefined,
+  onUpdate: (update) => queue.push({ kind: 'update', update }),
+  onPermissionRequest: (request) =>
+    resolveInteractivePermission(
+      request,
+      'acceptEdits',
+      bridgedToolNames,
+      options.approvals,
+      'my-harness',
+    ).outcome,
+})
+
+queue.push({ kind: 'session', sessionId: session.sessionId })
+
+session
+  .prompt(userText)
+  .then(({ stopReason, usage }) => {
+    queue.push({
+      kind: 'done',
+      stopReason,
+      ...(usage !== undefined && { usage }),
+    })
+    queue.end()
+  })
+  .catch((error) => queue.fail(error))
+
+yield *
+  translateAcpStream(queue, {
+    model: 'auto',
+    runId,
+    threadId,
+    genId: () => crypto.randomUUID(),
+    labels: {
+      sessionIdEvent: 'my-harness.session-id',
+      planEvent: 'my-harness.plan',
+      refusalMessage: 'Harness refused the request.',
+    },
+    bridgedToolNames,
+  })
+```
+
+Wire the adapter into `chat()` with `withSandbox(...)` like any other harness package.
+
+## Transports
+
+ACP can run over **stdio** (newline-delimited JSON-RPC on the child process pipes) or **WebSocket** (harness runs a `serve` subcommand inside the sandbox; the orchestrator connects through an exposed port).
+
+### Stdio
+
+Use when the sandbox can write to process stdin (`capabilities.writableStdin === true`):
+
+```typescript
+import { spawnHandleToAcpTransport } from '@tanstack/ai-acp'
+
+const proc = await sandbox.process.spawn('grok agent --acp -m auto', { cwd })
+// spawnHandleToAcpTransport adapts SpawnHandle stdout/stdin for ndJsonStream
+await startAcpSession({ transport: { kind: 'stdio', process: proc }, ... })
+```
+
+On providers without writable stdin (e.g. Cloudflare Containers), adapters feed the prompt via a shell redirect instead of a host stdin write — that workaround lives in each harness adapter, not in `@tanstack/ai-acp`.
+
+### WebSocket
+
+Use when stdin is not writable but the sandbox supports background processes and port exposure:
+
+```typescript
+import {
+  buildGrokServeWebSocketUrl,
+  resolveAcpTransportMode,
+  startAcpServerInSandbox,
+} from '@tanstack/ai-acp'
+
+const mode = resolveAcpTransportMode(sandbox, 'auto') // 'stdio' | 'websocket'
+
+const server = await startAcpServerInSandbox(sandbox, {
+  port: 2419,
+  cwd: '/workspace',
+  command: 'grok agent -m composer-2.5 --always-approve serve --bind 0.0.0.0:2419 --secret …',
+  buildWsUrl: ({ channel }) => buildGrokServeWebSocketUrl(channel.url, secret),
+  readyMarker: 'WebSocket URL:',
+  framing: 'frame',
+})
+
+const { stream, close } = await server.connect(signal)
+await startAcpSession({
+  transport: { kind: 'stream', stream, dispose: async () => { close(); await server.dispose() } },
+  ...
+})
+```
+
+`resolveAcpTransportMode(sandbox, preference)` implements the selection table:
+
+| Preference         | Behavior                                                                                                |
+| ------------------ | ------------------------------------------------------------------------------------------------------- |
+| `'stdio'`          | Requires `writableStdin`; throws if unavailable                                                         |
+| `'websocket'`      | Requires `ports` + `backgroundProcesses`                                                                |
+| `'auto'` (default) | Prefer stdio when writable; else WebSocket when ports are available; else throw with a actionable error |
+
+Helpers: `connectAcpWebSocket`, `httpChannelUrlToWsBase`, `webSocketFrameToAcpStream`, `parseWebSocketUrlFromServeOutput`.
+
+## Session lifecycle
+
+`startAcpSession` wraps `@agentclientprotocol/sdk`'s `ClientSideConnection`:
+
+1. **`initialize`** — negotiate protocol version and read agent capabilities.
+2. **`authenticate`** (optional) — when `authMethodId` is set and the harness advertises that method (e.g. `gemini-api-key`, `oauth-personal`).
+3. **`loadSession` or `newSession`** — resume when `resumeSessionId` is provided and the agent supports `loadSession`; otherwise start fresh. MCP server descriptors (bridged TanStack tools) are attached here.
+4. **`prompt`** — send the user turn; the harness streams updates via `sessionUpdate` callbacks until it returns `stopReason` + optional `usage`.
+5. **`cancel` / `dispose`** — abort an in-flight turn or tear down the transport.
+
+The returned `AcpSessionHandle` exposes `{ sessionId, resumed, prompt, cancel, dispose }`.
+
+### Stateful sessions
+
+On the first run, `translateAcpStream` emits a CUSTOM chunk:
+
+```typescript
+{ type: 'CUSTOM', name: 'my-harness.session-id', value: { sessionId: '…' } }
+```
+
+Thread that `sessionId` through `modelOptions.sessionId` on the next `chat()` call so `startAcpSession` can `loadSession` and only send the trailing user message.
+
+## Stream translation
+
+`translateAcpStream(events, ctx)` is a pure async generator. Feed it `AcpStreamEvent` values:
+
+| Event                                  | When                                      |
+| -------------------------------------- | ----------------------------------------- |
+| `{ kind: 'session', sessionId }`       | Right after `newSession` / `loadSession`  |
+| `{ kind: 'update', update }`           | Each `onUpdate` callback from the harness |
+| `{ kind: 'done', stopReason, usage? }` | After `prompt` resolves                   |
+
+ACP → AG-UI mapping (high level):
+
+| ACP `sessionUpdate`                | StreamChunk(s)                            |
+| ---------------------------------- | ----------------------------------------- |
+| `agent_message_chunk`              | `TEXT_MESSAGE_*`                          |
+| `agent_thought_chunk`              | `REASONING_*`                             |
+| `tool_call` / `tool_call_update`   | `TOOL_CALL_*` + `TOOL_CALL_RESULT`        |
+| `plan`                             | `CUSTOM` (when `labels.planEvent` is set) |
+| (terminal) `stopReason: 'refusal'` | `RUN_ERROR`                               |
+| (terminal) other stop reasons      | `RUN_FINISHED` + usage                    |
+
+`matchBridgedToolName` rewrites tool titles from the harness MCP namespace back to TanStack tool names when host tools are bridged in. `BRIDGED_MCP_SERVER_NAME` (`'tanstack'`) is the conventional MCP server name adapters use for the bridge.
+
+`AsyncQueue` bridges callback-style `onUpdate` notifications into the async-iterable world `translateAcpStream` consumes.
+
+## Permissions
+
+Harnesses can pause mid-turn and ask the client to approve a tool call. Wire `onPermissionRequest` on `startAcpSession`:
+
+```typescript
+import {
+  resolvePermission,
+  resolveInteractivePermission,
+} from '@tanstack/ai-acp'
+
+// Headless / sandboxed: auto-approve bridged tools + edits, reject everything else
+onPermissionRequest: (request) =>
+  resolvePermission(request, permissionMode, bridgedToolNames)
+
+// Interactive: same policy, but emit approval-requested events for 'ask' actions
+const { outcome, approvalId } = resolveInteractivePermission(
+  request,
+  permissionMode,
+  bridgedToolNames,
+  options.approvals,
+  'my-harness',
+)
+```
+
+`AcpPermissionMode`:
+
+| Mode                  | Behavior                                                        |
+| --------------------- | --------------------------------------------------------------- |
+| `'default'`           | Approve TanStack-bridged tools; reject other permission prompts |
+| `'acceptEdits'`       | Also auto-approve file mutations (`edit`, `move`, `delete`)     |
+| `'bypassPermissions'` | Approve everything                                              |
+
+Pass a custom `PermissionHandler` to override the policy entirely.
+
+## Public API
+
+### Harness adapter
+
+- `acpCompatible(config)` → `(model, overrides?) => AcpCompatibleTextAdapter`
+- `acpCompatibleText(model, config)` → `AcpCompatibleTextAdapter`
+- `buildAcpPrompt(messages, sessionId, harnessName?)` → `{ prompt, resume? }`
+- `AcpCompatibleConfig`, `AcpCompatibleProviderOptions`, `AcpHarnessContext`, `BuiltAcpPrompt`
+
+### Session
+
+- `startAcpSession(options)` → `AcpSessionHandle`
+- `StartAcpSessionOptions`, `AcpSessionHandle`
+
+### Translation
+
+- `translateAcpStream(events, ctx)` → `AsyncIterable<StreamChunk>`
+- `AsyncQueue<T>`
+- `matchBridgedToolName`, `BRIDGED_MCP_SERVER_NAME`
+- `AcpStreamEvent`, `TranslateContext`, `AcpTranslateLabels`
+
+### Transport
+
+- `spawnHandleToAcpTransport(handle)` — stdio byte streams from a `SpawnHandle`
+- `resolveAcpTransportMode(sandbox, preference?)`
+- `connectAcpWebSocket(url, options?)`, `httpChannelUrlToWsBase`
+- `webSocketFrameToAcpStream(ws)`
+
+### In-sandbox server
+
+- `startAcpServerInSandbox(sandbox, options)` → `AcpSandboxServer`
+- `buildGrokServeWebSocketUrl(channelUrl, secret)`
+- `parseWebSocketUrlFromServeOutput(stdout)`
+
+### Permissions
+
+- `resolvePermission`, `resolveInteractivePermission`
+- `AcpPermissionMode`, `PermissionHandler`, `AcpPermissionRequest`, `AcpPermissionOutcome`
+
+### Types
+
+Structural subsets of ACP shapes (`AcpSessionUpdate`, `AcpToolCallUpdate`, `AcpUsage`, …) live in `types/acp-types.ts` so the translator stays fixture-testable without pulling the full SDK surface into every consumer.
+
+## Consumers in this repo
+
+| Package                   | How it uses `@tanstack/ai-acp`                                            |
+| ------------------------- | ------------------------------------------------------------------------- |
+| `@tanstack/ai-grok-build` | Stdio + WebSocket (`grok agent serve`); vendor `extNotification` handling |
+
+Harness adapters re-export commonly needed symbols (`startAcpSession`, `translateAcpStream`, permission helpers) from their own entry points so app code rarely imports `@tanstack/ai-acp` directly.
+
+## Further reading
+
+- [Agent Client Protocol](https://agentclientprotocol.com)
+- TanStack harness adapters: `@tanstack/ai-grok-build`
+- Sandbox layer: `@tanstack/ai-sandbox` ([README](../ai-sandbox/README.md))

package/dist/esm/adapters/compatible.d.ts

@@ -0,0 +1,206 @@
+import { BaseTextAdapter, StructuredOutputOptions, StructuredOutputResult } from '@tanstack/ai/adapters';
+import { SandboxHandle } from '@tanstack/ai-sandbox';
+import { DefaultMessageMetadataByModality, Modality, ModelMessage, StreamChunk, TextOptions } from '@tanstack/ai';
+import { AcpSessionTransport } from '../transport/types.js';
+import { AcpPermissionMode, PermissionHandler } from '../types/acp-types.js';
+import { BuiltAcpPrompt } from '../messages/prompt.js';
+/**
+ * Everything a harness needs to know to launch its ACP server inside the
+ * sandbox. Passed to {@link AcpCompatibleConfig.command} /
+ * {@link AcpCompatibleConfig.openTransport}.
+ */
+export interface AcpHarnessContext<TModelOptions extends Record<string, any> = AcpCompatibleProviderOptions> {
+    /** The sandbox the harness runs in (from `withSandbox(...)` middleware). */
+    sandbox: SandboxHandle;
+    /** The selected model id. */
+    model: string;
+    /** Virtual cwd for `sandbox.process.spawn` (the provider maps `/workspace`). */
+    cwd: string;
+    /** Literal cwd for the harness's own `--cwd` flag / ACP `newSession`. */
+    harnessCwd: string;
+    /** Extra env vars configured for the harness process. */
+    env: Record<string, string> | undefined;
+    /**
+     * Per-call options from `chat({ modelOptions })` — the base ACP options plus
+     * whatever you declared via {@link AcpCompatibleConfig.modelOptions}. Read
+     * these to turn options into CLI flags / transport choices.
+     */
+    modelOptions: TModelOptions | undefined;
+    /** Abort signal for the run, when one was provided. */
+    signal: AbortSignal | undefined;
+}
+/** Union of selectable model names from a `models` tuple (any string if omitted). */
+export type AcpModelNameOf<TModels extends ReadonlyArray<string>> = TModels[number];
+export interface AcpCompatibleConfig<TModels extends ReadonlyArray<string> = ReadonlyArray<string>, TModelOptions extends Record<string, any> = AcpCompatibleProviderOptions> {
+    /**
+     * Harness name. Used as the provider label, the log prefix, and the CUSTOM
+     * session-id event name (`<name>.session-id`).
+     */
+    name: string;
+    /**
+     * The models this harness accepts. Declaring them makes the returned factory
+     * type-safe — `harness('known-model')` is checked, unknown ids are rejected.
+     * Omit to accept any string.
+     */
+    models?: TModels;
+    /**
+     * Type-only brand for the per-call options accepted via `chat({ modelOptions })`.
+     * Declare your harness's options here with `{} as { ... }` (the value is unused
+     * at runtime); they are merged with the base {@link AcpCompatibleProviderOptions}
+     * and exposed on {@link AcpHarnessContext.modelOptions} so `command` /
+     * `openTransport` can turn them into CLI flags.
+     *
+     * @example modelOptions: {} as { reasoningEffort?: 'low' | 'high' }
+     */
+    modelOptions?: TModelOptions;
+    /**
+     * Build the shell command that launches the harness's ACP server over
+     * **stdio** inside the sandbox (e.g. `` `pi --acp -m ${model}` ``). Required
+     * unless {@link openTransport} is provided.
+     */
+    command?: (ctx: AcpHarnessContext<AcpCompatibleProviderOptions & TModelOptions>) => string;
+    /**
+     * Full transport escape hatch — open any {@link AcpSessionTransport} yourself
+     * (e.g. boot a `serve` process and connect over WebSocket, as Grok Build
+     * does). Overrides {@link command}. Put ALL teardown in the returned
+     * transport's `dispose` (stream) / process (stdio); it is disposed when the
+     * session ends.
+     */
+    openTransport?: (ctx: AcpHarnessContext<AcpCompatibleProviderOptions & TModelOptions>) => Promise<AcpSessionTransport> | AcpSessionTransport;
+    /** Working directory inside the sandbox. Defaults to `/workspace`. */
+    cwd?: string;
+    /**
+     * The harness's skills directory, relative to the workspace root (e.g.
+     * `'.pi/skills'`) — its native convention for where it auto-discovers skills,
+     * the way Claude Code uses `.claude/skills`. When set, `withSandbox` workspace
+     * `gitSkill`s are linked here. MCP skills don't need this: they're passed to
+     * the agent over ACP natively. Omit and `gitSkill`s are left unlinked (warned).
+     */
+    skillsDir?: string;
+    /** Extra environment variables for the harness process. */
+    env?: Record<string, string>;
+    /**
+     * ACP auth method to select before the session starts, when the harness
+     * advertises one (e.g. `'pi-api-key'`). Overridable per call via
+     * `modelOptions.authMethodId`.
+     */
+    authMethodId?: string;
+    /** ACP permission policy. Defaults to `'bypassPermissions'`. */
+    permissionMode?: AcpPermissionMode;
+    /**
+     * Permission strategy:
+     * - `'headless'` (default) — auto-resolve via {@link permissionMode}; the
+     *   sandbox is the boundary, so the agent runs without prompting.
+     * - `'interactive'` — same policy, but `ask`-style prompts emit an
+     *   approval-requested event so a client can approve and re-run.
+     */
+    permissions?: 'headless' | 'interactive';
+    /** Custom permission handler; overrides {@link permissions}/{@link permissionMode}. */
+    onPermissionRequest?: PermissionHandler;
+    /** Message used for `RUN_ERROR` when the harness refuses a request. */
+    refusalMessage?: string;
+    /** Emit ACP `plan` updates as a CUSTOM event under this name (off by default). */
+    planEventName?: string;
+    /**
+     * After the run, emit the `git diff` of the working dir as a `file.changed`
+     * CUSTOM event. Requires a git repo at `cwd`. Off by default.
+     */
+    emitDiff?: boolean;
+    /**
+     * Harness-specific JSON-RPC notifications (vendor `_x/...` extensions). Must
+     * return without throwing — unknown extensions must not tear down the session.
+     */
+    onExtNotification?: (method: string, params: Record<string, unknown>) => void;
+    /**
+     * Convert chat history into the harness prompt + resume inputs. Defaults to
+     * {@link buildAcpPrompt} (trailing user message + flattened transcript).
+     */
+    buildPrompt?: (messages: Array<ModelMessage>, sessionId: string | undefined) => BuiltAcpPrompt;
+}
+/** Per-call provider options, passed via `modelOptions` on `chat()`. */
+export interface AcpCompatibleProviderOptions {
+    /**
+     * Resume an existing harness session. The adapter emits the session id of
+     * every run via a CUSTOM `<name>.session-id` event; thread it back here to
+     * continue (only the trailing user message is sent).
+     */
+    sessionId?: string;
+    /** Per-call override of the harness working directory. */
+    cwd?: string;
+    /** Per-call override of the ACP auth method. */
+    authMethodId?: string;
+    /** Per-call override of the ACP permission policy. */
+    permissionMode?: AcpPermissionMode;
+}
+/** Per-call options the adapter sees: the base ACP options + the harness's own. */
+type ResolvedOptions<TModelOptions extends Record<string, any>> = AcpCompatibleProviderOptions & TModelOptions;
+/**
+ * A generic ACP harness adapter built from {@link AcpCompatibleConfig}. Runs the
+ * configured coding-agent CLI inside the sandbox provided by `withSandbox(...)`
+ * and translates its ACP session into AG-UI `StreamChunk`s.
+ */
+export declare class AcpCompatibleTextAdapter<TModel extends string, TModelOptions extends Record<string, any> = AcpCompatibleProviderOptions> extends BaseTextAdapter<TModel, ResolvedOptions<TModelOptions>, ReadonlyArray<Modality> & readonly ['text'], DefaultMessageMetadataByModality, ReadonlyArray<string>, unknown, never> {
+    readonly name: string;
+    readonly requires: readonly [import('@tanstack/ai').Capability<SandboxHandle, "sandbox">];
+    private readonly harness;
+    constructor(config: AcpCompatibleConfig<ReadonlyArray<string>, TModelOptions>, model: TModel);
+    private sandboxFrom;
+    private buildPrompt;
+    private applySystemPrompts;
+    private makePermissionHandler;
+    chatStream(options: TextOptions<ResolvedOptions<TModelOptions>>): AsyncIterable<StreamChunk>;
+    private openStdioTransport;
+    private emitDiffChunks;
+    structuredOutput(_options: StructuredOutputOptions<ResolvedOptions<TModelOptions>>): Promise<StructuredOutputResult<unknown>>;
+}
+/**
+ * Configure an ACP-compatible harness once, then select a model per call.
+ *
+ * Mirrors `openaiCompatible`: it lets you plug ANY Agent Client Protocol agent
+ * into a TanStack AI sandbox without a dedicated adapter package.
+ *
+ * @example
+ * ```ts
+ * import { acpCompatible } from '@tanstack/ai-acp'
+ * import { chat } from '@tanstack/ai'
+ * import { defineSandbox, withSandbox } from '@tanstack/ai-sandbox'
+ *
+ * const pi = acpCompatible({
+ *   name: 'pi',
+ *   // declaring `models` makes pi('…') type-safe; omit to accept any string
+ *   models: ['pi-fast', 'pi-pro'],
+ *   // declare per-call options; merged with the base ACP options and exposed
+ *   // on ctx.modelOptions inside `command` / `openTransport`
+ *   modelOptions: {} as { reasoningEffort?: 'low' | 'high' },
+ *   command: ({ model, harnessCwd, modelOptions }) =>
+ *     `pi --acp -m ${model} --cwd ${harnessCwd}` +
+ *     (modelOptions?.reasoningEffort ? ` --effort ${modelOptions.reasoningEffort}` : ''),
+ *   authMethodId: 'pi-api-key',
+ * })
+ *
+ * chat({
+ *   adapter: pi('pi-pro'),
+ *   modelOptions: { reasoningEffort: 'high' }, // typed
+ *   messages,
+ *   middleware: [withSandbox(defineSandbox({ /* provider, install pi *\/ }))],
+ * })
+ * ```
+ */
+export declare function acpCompatible<const TModels extends ReadonlyArray<string> = ReadonlyArray<string>, TModelOptions extends Record<string, any> = AcpCompatibleProviderOptions>(config: AcpCompatibleConfig<TModels, TModelOptions>): <TModel extends AcpModelNameOf<TModels>>(model: TModel, overrides?: Partial<AcpCompatibleConfig<TModels, TModelOptions>>) => AcpCompatibleTextAdapter<TModel, TModelOptions>;
+/**
+ * One-shot helper: build a single-model ACP-compatible harness adapter inline.
+ *
+ * @example
+ * ```ts
+ * chat({
+ *   adapter: acpCompatibleText('pi-fast', {
+ *     name: 'pi',
+ *     command: ({ model }) => `pi --acp -m ${model}`,
+ *   }),
+ *   messages,
+ *   middleware: [withSandbox(defineSandbox({ ... }))],
+ * })
+ * ```
+ */
+export declare function acpCompatibleText<TModel extends string, TModelOptions extends Record<string, any> = AcpCompatibleProviderOptions>(model: TModel, config: AcpCompatibleConfig<ReadonlyArray<string>, TModelOptions>): AcpCompatibleTextAdapter<TModel, TModelOptions>;
+export {};