Felix Arntz

feat(harness-acp): introduce ACP harness adapter as a meta adapter to connect to any ACP compatible harness (#18483) ## Background AI SDK harness integrations currently require a dedicated adapter for each coding-agent runtime. ACP provides a common protocol that can support multiple runtimes through one adapter while keeping runtime-specific installation and authentication details in small profiles. Some harnesses only offer an ACP adapter as the sole way for programmatic control over their harness, so for those harnesses having an ACP adapter unblocks supporting them by our harness layer. ## Summary This adds `harness-acp`, a meta adapter for ACP v1 implementations. The adapter owns the generic sandbox bridge, protocol translation, host-tool relay, approvals, and lifecycle behavior, while callers configure the underlying ACP runtime declaratively. - Support simple and lockfile-pinned NPM acquisition for arbitrary ACP implementations. - Support direct and AI Gateway authentication with runtime-resolved environment variables and adapter-specific Gateway routes. - Translate ACP streams, native tools, host tools, approvals, skills, session modes, and resumable lifecycle state into Harness APIs. - Add complete Claude Code, Codex, and Grok Build profiles across documentation and interactive examples. ## End-to-End Verification - Exercised the added Claude Code ACP, Codex ACP, and Grok Build ACP through the interactive Harness example. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [x] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review) ## Related Issues See #16956.

feat(harness): add support for using adapter-native subscriptions where available (#20606) ## Background Harness adapters so far support direct auth via API keys and AI Gateway auth, but not using their native subscriptions. ## Summary This adds host-side native subscription resolution while retaining the existing `direct` and `ai-gateway` authentication modes. Direct authentication prefers explicit provider environment credentials, then falls back to a native subscription if no such credentials are present; AI Gateway authentication never reads native subscriptions. - Add shared OAuth access-token expiry and refresh helpers with a five-minute refresh window. - Resolve supported adapters' native credential files, keyrings, and CLI credentials at the host boundary. - Keep refresh tokens and real access tokens on the host while passing only fake credentials into the sandbox, which then get replaced at the host boundary via credential brokering. - Add native-subscription examples and adapter-specific coverage for every supported credential source and refresh flow. ## End-to-End Verification Ran the `native-subscription` harness examples added. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [x] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review)

feat(harness): allow changing harness settings between turns via `prepareCall()` support on `HarnessAgent` (#19828) ## Background `HarnessAgent` settings were fixed when an agent was created, preventing callers from adapting instructions, skills, and tools between completed turns. `ToolLoopAgent` already supported `prepareCall()` and `callOptionsSchema`, allowing to dynamically modify certain settings in between turns. ## Summary This aligns `HarnessAgent` with the `ToolLoopAgent` call-options pattern while keeping settings fixed throughout an active turn and its continuations. - Add `callOptionsSchema` and `prepareCall` support for deriving per-turn instructions, skills, and tools. - Capture active turn settings in continuation state so suspended and resumed turns cannot pick up later configuration. - Update harness adapters to apply settings changes between turns, including ACP skill refreshes and instruction guidance. - Make `writeSkills` safely replace only harness-owned skills and skip unchanged content using a manifest with SHA-256 hashes. - Add documentation, unit coverage, and changing-settings examples for every harness. ## End-to-End Verification Ran the new `changing-settings` examples against all harnesses. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [x] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review)

feat(harness): support `askUserQuestions` tool including support for normalization across harness adapters (#20267) ## Background Harness question tools expose incompatible inputs and previously had no reliable client-side answer channel. This made structured question flows unusable through `HarnessAgent`. ## Summary - Add the normalized `askUserQuestions` tool contract, including multi-question, partial-answer, free-form, cancellation, and provider metadata support. - Translate native question calls and answers for all supported harness adapters (see below). - Preserve pending question state across suspension and cross-process continuation. - Add an interactive question renderer to the Next.js harness example. - Omit question tools from ACP adapters where the runtime cannot provide an answerable client request. Harness support: - Claude Code: Supported. - Cline: Supported. - Codex: Unsupported — SDK has no question tool. - Cursor: Unsupported — question tool is not exposed in ACP mode. - Deep Agents: Unsupported — SDK has no question tool. - fx: Unsupported — question interaction is disabled in ACP mode. - Grok Build: Supported. - OpenCode: Supported. - Pi: Unsupported — SDK has no question tool. - Example ACP harness adapters: - Claude Code ACP: Supported. - Codex ACP: Supported. ## End-to-End Verification Verified the shared question example against Claude Code, Cline, OpenCode, Grok Build, Codex ACP, and Claude Code ACP. Also verified the interactive flow in `examples/harness-e2e-next`. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [x] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review) ## Future Work - Add support for additional ACP runtimes when they expose an answerable native question request. - Address plan mode from the original issue separately, tracked in #19944. ## Related Issues Fixes #19755

feat(harness): support request transformations in network sandbox abstraction and use it to apply credential brokering when available (#18859) ## Background Bridge-based harnesses currently forward provider credentials into sandboxed agent processes, which is far from ideal from a security perspective. Credential brokering allows us to keep those credentials only in the host environment and inject them into the relevant outgoing requests from the sandbox at the host boundary. ## Summary - Add optional `setRequestTransformations()` and `addRequestTransformations()` to the network sandbox abstraction. - Update the Vercel Sandbox implementation to support it, via its `networkPolicy` layer. - Preserve authoritative allow/deny policy and `forwardURL` rules while transformations are added, replaced, deferred, or restored across session resume. - Broker direct-provider and AI Gateway credentials for all bridge based harnesses: Claude Code, Codex, Deep Agents, Grok Build, OpenCode, and ACP-based harnesses. - Warn and retain legacy credential forwarding when a sandbox implementation does not expose additive request transformations. - Add shared credential-brokering utilities, structural conventions, tests, documentation, and an end-to-end Vercel Sandbox example. - For Codex specifically, disable websockets mode conditionally to be able to apply credential brokering. ## End-to-End Verification Ran many static and interactive examples across all bridge harnesses to verify continued correct execution with the new path of brokered credentials applied. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [x] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review)

feat(harness): refactor sandbox APIs for cleaner separation of concerns from harness layer, more intuitive DX regardless of how your sandbox is configured, and streamlined handling of sandbox templates/snapshots (#21497) ## Background Sandbox provisioning was coupled to `HarnessAgent`, while sharing a prepared sandbox across harnesses required manually preparing and snapshotting a native sandbox. Applications also need a way to create and resume sandbox sessions across processes without handing sandbox ownership to the agent. ## Summary - Move sandbox creation and ownership to explicit sessions passed to `HarnessAgent.createSession()`; agent session cleanup does not destroy a supplied sandbox. - Add reusable templates for one harness (`agent.getSandboxTemplate()`) or multiple harnesses (`createHarnessSandboxTemplate()`), with Vercel snapshot reuse. - Add create/resume network-session APIs with explicit `sandboxId`, native adaptations, and workflow session forwarding. Retain the provider-based APIs for compatibility. - Update documentation and examples for explicit preparation, resume, and cleanup. **Important:** While the new API surface is very different, there is currently no backward-compatibility breakage. All previous API surfaces have been deprecated, yet continue to work the same way. They will be removed in the future (planning for in roughly 2 months from now). ### API comparison Regular `HarnessAgent` session (using `claudeCode`): **Before** ```ts const agent = new HarnessAgent({ harness: claudeCode, sandbox: createVercelSandbox({ runtime: 'node24', ports: [4000] }), }); const session = await agent.createSession(); try { await agent.generate({ session, prompt }); } finally { await session.destroy(); } ``` **After** ```ts const agent = new HarnessAgent({ harness: claudeCode }); const sandboxSession = await createVercelNetworkSandboxSession({ runtime: 'node24', ports: [4000], template: await agent.getSandboxTemplate(), }); let session: HarnessAgentSession | undefined; try { session = await agent.createSession({ sandboxSession }); await agent.generate({ session, prompt }); } finally { await session?.destroy(); await sandboxSession.destroy(); } ``` The new API may look more complicated than the old one, but the reality is our API layer was optimized too much for this scenario before, coupling sandbox session lifecycle too much with the harness layer. Now, the two are cleanly decoupled. Consider the below comparison, which is for an externally controlled sandbox shared across `harnesses`, using the same `sandboxConfig` for preparation and each agent: **Before** ```ts const preparedSandbox = await Sandbox.create({ runtime: 'node24', ports: [4000], }); const preparedSession = await createVercelSandbox({ sandbox: preparedSandbox, }).createSession(); await prepareSandboxForHarness({ session: preparedSession.restricted(), harnesses, sandboxConfig, }); const snapshotId = (await preparedSandbox.stop()).snapshot?.id; if (snapshotId == null) throw new Error('Missing prepared snapshot'); for (const harness of harnesses) { const sandbox = await Sandbox.create({ source: { type: 'snapshot', snapshotId }, ports: [4000], }); const agent = new HarnessAgent({ harness, sandbox: createVercelSandbox({ sandbox }), sandboxConfig, }); const session = await agent.createSession(); try { await agent.generate({ session, prompt }); } finally { await session.destroy(); await sandbox.stop(); } } ``` **After** ```ts const template = await createHarnessSandboxTemplate({ harnesses, sandboxConfig, }); for (const harness of harnesses) { const sandboxSession = await createVercelNetworkSandboxSession({ runtime: 'node24', ports: [4000], template, }); const agent = new HarnessAgent({ harness, sandboxConfig }); let session: HarnessAgentSession | undefined; try { session = await agent.createSession({ sandboxSession }); await agent.generate({ session, prompt }); } finally { await session?.destroy(); await sandboxSession.destroy(); } } ``` This required a lot of unnecessarily complex code before, and still didn't work as well in terms of template reuse. Now both "After" snippets are very similar - sandbox lifecycle is decoupled from `HarnessAgent`, and the DX is very similar regardless of which use-case applies to you. ## End-to-End Verification Not recorded in this draft. To verify manually, run the `claude-code/sandbox-template` harness example and the multi-harness `prepare-sandbox-for-harness` example; rerun the latter to confirm the prepared Vercel snapshot is reused. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [x] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review)

feat(harness-codex): migrate adapter to use Codex app server, unlocking more granular tool call emissions, built-in tool filtering, and mid-turn steering (#21434) ## Background The Codex adapter's `codex exec` path obscured native tool calls and relied on a shell relay for host tools, limiting tool filtering and mid-turn steering. The Codex app-server protocol (`codex app-server`) provides far more granular insights and control. ## Summary Move the adapter to the Codex app-server protocol, retaining one server across compatible turns and restarting it when process configuration changes. `HarnessAgent` remains responsible for sandboxing; Codex's own sandbox and approvals stay disabled. - Replace the shell relay with app-server dynamic tools for host-executed calls. - Expose `apply_patch` and `view_image` as built-in tool calls and results, while preserving file-change events. - Support built-in tool filtering through native configuration where possible and a trusted `PreToolUse` hook when selectively disabling `apply_patch`; add mid-turn steering through `turn/steer`. - Update Codex documentation, tests, dependency checks, and the example UI for patch tool calls. ## End-to-End Verification All end-to-end examples in `examples/ai-functions/src/harness-agent/codex` are passing now, plus interactive testing via `examples/harness-e2e-next` was successfully completed. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [x] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review)

feat(harness): add support for structured output to `HarnessAgent` via `output` property (#18937) ## Background `HarnessAgent` previously pinned its output type to `never`, preventing callers from using the typed structured-output workflow supported by `ToolLoopAgent` and several underlying harness runtimes. ## Summary - Add constructor-level `output` support with typed final, partial, and element output streams. - Add an independent JSON Schema response-format contract to HarnessV1 without coupling `harness` to `provider`. - Map structured output to Claude Code, Cline, Codex, Deep Agents, Grok Build, and OpenCode; unsupported adapters and runtime configurations throw `HarnessCapabilityUnsupportedError`. - Let ACP profiles explicitly map output schemas into implementation-specific prompt metadata. - Add adapter documentation, tests, and runnable structured-output examples for every harness. ## Contributor Credit Thanks to @niranjan94 for reporting the missing structured-output path and documenting the underlying runtime capabilities. ## End-to-End Verification Ran `./tools/run-harness-agent-examples.sh --example with-structured-output` across all harnesses. Supported adapters generated and parsed the requested recipe schema; Pi and Codex ACP surfaced their expected unsupported-capability errors. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [x] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review) ## Related Issues Fixes #16120 Co-authored-by: Niranjan Rajendran <2404372+niranjan94@users.noreply.github.com>

feat(harness): add experimental support for steering agent conversations mid-turn (#19059) ## Background `HarnessAgent` did not expose steering the agent mid-turn, a common feature that many harnesses support. A few related primitives like lower-level API surfaces to submit another prompt mid-turn were already in place, but weren't properly wired up and didn't actually work end-to-end. ## Summary This adds an experimental steering API with acknowledged delivery to the active turn's next safe input boundary. - Add `experimental_steer` and `experimental_steerTurn` with active-turn and capability checks. - Add ID-based bridge acknowledgements and reconnect-safe resubmission. - Wire steering through supported harness adapters while preserving explicit unsupported-capability errors. - Add matching weather-tool steering examples and regression coverage across harnesses. ### Known limitations - Steering requires to operate on the same `HarnessAgentSession` instance that is actually controlling the current agent turn. Therefore, cross-process steering (e.g. in a separate REST request than where that turn was started) is currently not properly supported. The only workaround is relying on environments where the same session instance can be accessed in the other context too, e.g. a single-process dev server where you can store those session objects in memory and then retrieve them in the other request. - The mid-turn user prompts cannot properly be represented in the AI SDK messages list, because they're injected mid-turn into what AI SDK expects to be a stream of exclusively agent-owned stream parts. Fixing this will require a higher-level concept of steering support in AI SDK Core. ## End-to-End Verification Ran the new `steer.ts` examples in `examples/ai-functions/src/harness-agent`. ## Checklist - [x] All commits are signed with `git commit -s`. - [x] Tests have been added or updated and pass. - [ ] Documentation has been added or updated. - [x] A patch changeset has been added. - [x] The changes have been reviewed and tested. ## Related Issues Fixes #18274 See #19125 for making this a more proper implementation in the future

feat(harness): add support for per-harness MCP servers (#18647) ## Background Harness adapters could not consistently accept user-configured MCP servers, and external MCP tool calls could be rejected as unknown tools or lose their dynamic classification. At the same time, typed `HarnessAgent` tools must remain static even when a runtime transports them through MCP. ## Summary With this PR, all harness adapters can receive MCP servers and process tool calls to these MCP servers. - Add an optional `mcpServers: Record<string, unknown>` setting across harness adapters and forward it in each runtime's native format. - Merge external servers with any adapter-owned MCP server used for host tools, without deeply validating runtime-specific configuration. - Mark only external MCP tool calls as dynamic while preserving typed built-in and `HarnessAgent` tools. - Add ACP runtime-specific classification through `isMcpToolCall`, plus regression coverage, Context7 examples, documentation, and a konsistent invariant. ## End-to-End Verification - Ran the added Context7 MCP examples against all harnesses. ## Checklist - [x] All commits are signed (PRs with unsigned commits cannot be merged) - [x] Tests have been added / updated (for bug fixes / features) - [x] Documentation has been added / updated (for bug fixes / features) - [x] A _patch_ changeset for relevant packages has been added (for bug fixes / features - run `pnpm changeset` in the project root) - [x] I have reviewed this pull request (self-review)