/add-harness-package

name: add-harness-package
description: Guide for adding new AI SDK harness packages. Use when creating a new @ai-sdk/harness-<name> package that adapts a coding-agent runtime to HarnessV1.
metadata:
  internal: true

Adding a New Harness Package

This guide covers creating a new `@ai-sdk/harness-<name>` package for an agent harness.

Before evaluating a runtime, read [Harness Requirements](references/harness-requirements.md) for feasibility criteria and capability gaps to document. Follow the requirements while implementing the harness package.

A harness can be **host-driven**, where the runtime runs in the host process and uses the sandbox remotely, or **bridge-backed**, where a small bridge runs inside the sandbox because the runtime needs local access to the sandbox filesystem or process environment. Prefer host-driven when the runtime supports it.

First-Party vs Third-Party Harnesses

• **Third-party packages**: Any runtime can publish an external harness package.
• **First-party `@ai-sdk/harness-<name>` packages**: Create an issue first to discuss whether the runtime belongs in this repo.

Reference Example

See https://github.com/vercel/ai/pull/16255/changes for a complete example of adding a new harness.

Harness Architecture

The AI SDK uses a layered harness architecture following the adapter pattern:

1. **Harness specification** (`@ai-sdk/harness`): Defines interfaces like `HarnessV1` and `HarnessV1Session` 2. **Utilities** (`@ai-sdk/harness/utils`): Shared code for implementing harnesses 3. **Harness implementations** (`@ai-sdk/harness-<name>`): Concrete adapters for harnesses 4. **Harness agent** (`@ai-sdk/harness/agent`): The high-level user-facing `HarnessAgent` API

Step-by-Step Guide

1. Create Package Structure

Create `packages/harness-<name>` with this baseline structure:

packages/harness-<name>/
├── src/
│   ├── index.ts
│   ├── <name>-harness.ts
│   ├── <name>-harness.test.ts
│   └── <name>-auth.ts              # if the runtime needs auth resolution
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── tsdown.config.ts
├── turbo.json
├── vitest.node.config.js
└── README.md

If the runtime must execute inside the sandbox, add bridge files as well:

src/
├── <name>-bridge-protocol.ts
├── <name>-bridge-protocol.test.ts
└── bridge/
    ├── index.ts
    ├── package.json
    └── pnpm-lock.yaml

Add a `CHANGELOG.md` containing just the package heading (`# @ai-sdk/harness-<name>`). Every package is required to have one.

2. Configure package.json

Use existing harness packages as the source of truth for scripts, exports, repository metadata, and publish settings.

Required package basics:

• `"name": "@ai-sdk/harness-<name>"`
• `"type": "module"`
• `"version": "0.0.0"` (starting point for new packages)
• `"license": "Apache-2.0"`
• `"sideEffects": false`
• dependency on `@ai-sdk/harness` via `workspace:*`
• dependency on `@ai-sdk/provider-utils` via `workspace:*` when using sandbox/auth/schema utilities
• runtime SDK/CLI dependencies required by the harness
• dev dependencies matching existing harness packages
• `"engines": { "node": ">=22" }`

For bridge packages, ensure all bridge assets under `src/bridge/` are copied into `dist/bridge/` and can be read from there. Read `.agents/guidelines/harness-bridge-assets.md` for detailed requirements.

Bridge dependency rules (bridge-backed harnesses):

• The bridge's runtime deps live in `src/bridge/package.json` (installed in-sandbox at bootstrap), not the main package.json. After changing them, regenerate `src/bridge/pnpm-lock.yaml` with `pnpm --dir packages/harness-<name>/src/bridge install --lockfile-only --ignore-workspace` (runnable from the repo root).
• For every third-party import in `src/bridge/`, add the dependency to `src/bridge/package.json` so it is installed in the sandbox. tsdown automatically externalizes dependencies, peer dependencies, and optional dependencies declared by the main package; add bridge-only dependencies that are not declared there to `deps.neverBundle` in `tsdown.config.ts`. A missing dependency or required exclusion may show up only at sandbox runtime as a module-resolution error.
• Include packages the runtime _lazily_ imports — e.g. provider SDKs (`@anthropic-ai/sdk`, `openai`) resolved from the model id at runtime — in `src/bridge/package.json` even though nothing imports them directly. They do not need a `neverBundle` entry unless the bridge source imports them. These fail only when a model of that provider is actually used.
• Match shared dependency versions (transport, schema, tooling, runtime SDKs) to what the other harness packages currently use — copy from a sibling package rather than choosing your own pins. Stale pins drift from security patches and can desync from the shared bridge runtime; check the current versions at creation time.
• ACP adapters built on `@ai-sdk/harness-acp` with an `npm-locked` source install their `src/bridge/package.json` in place of the `harness-acp` bridge manifest. That manifest must declare every dependency of `packages/harness-acp/src/v1/bridge/package.json` at the same version, and the adapter's manifest path must be added to `acpNpmLockedBridgeManifestPaths` in `tools/verify-harness-adapter-deps.mjs`.
• Add the adapter to `adapterConfigs` in `tools/verify-harness-adapter-deps.mjs` with its primary SDK packages, and add matching update commands to `skills/update-harness-dependencies/SKILL.md`. The verification script fails when a configured SDK package has no update command there.

3. Create TypeScript, Build, and Test Configs

Copy the nearest existing harness package config files and adjust paths/package names:

• `tsconfig.json`
• `tsconfig.build.json`
• `tsdown.config.ts`
• `turbo.json`
• `vitest.node.config.js`

Harness packages currently use Node tests only unless the implementation has a specific reason to add another runtime.

4. Implement the Harness Adapter

Export a factory fr