@ai-sdk/harness 0.0.0-07500555-20260730161446

package/CHANGELOG.md

@@ -0,0 +1,531 @@
+# @ai-sdk/harness
+
+## 0.0.0-07500555-20260730161446
+
+### Patch Changes
+
+- 5f65e61: feat(harness): add support for `stopWhen` control to `HarnessAgent` (e.g. `isStepCount(1)`)
+- Updated dependencies [589d87c]
+- Updated dependencies [7f6650b]
+- Updated dependencies [106ea59]
+  - @ai-sdk/provider@0.0.0-07500555-20260730161446
+  - ai@0.0.0-07500555-20260730161446
+  - @ai-sdk/provider-utils@0.0.0-07500555-20260730161446
+
+## 1.0.39
+
+### Patch Changes
+
+- 86a84c9: fix(harness): settle a turn aborted by the caller's abortSignal with an `abort` stream part instead of an AbortError `error` part, matching `streamText`'s abort contract
+  - ai@7.0.34
+
+## 1.0.38
+
+### Patch Changes
+
+- Updated dependencies [02ffdcb]
+- Updated dependencies [76cb673]
+- Updated dependencies [e808fa5]
+- Updated dependencies [33647d7]
+  - @ai-sdk/provider-utils@5.0.12
+  - ai@7.0.33
+
+## 1.0.37
+
+### Patch Changes
+
+- b460541: fix(harness): properly support client-side / host-side tools and handle unfinished turn semantics
+- 079591e: fix (harness): emit the message-level `start` part on HarnessAgent streams so `toUIMessageStream` persistence mode can inject the response message id
+- Updated dependencies [6cd7c74]
+- Updated dependencies [e35bcae]
+- Updated dependencies [a4eb3f3]
+  - ai@7.0.32
+
+## 1.0.36
+
+### Patch Changes
+
+- Updated dependencies [70f18c3]
+- Updated dependencies [cd06458]
+  - ai@7.0.31
+  - @ai-sdk/provider-utils@5.0.11
+
+## 1.0.35
+
+### Patch Changes
+
+- ai@7.0.30
+
+## 1.0.34
+
+### Patch Changes
+
+- ai@7.0.29
+
+## 1.0.33
+
+### Patch Changes
+
+- Updated dependencies [0bc8d4f]
+  - ai@7.0.28
+
+## 1.0.32
+
+### Patch Changes
+
+- Updated dependencies [ac01b79]
+- Updated dependencies [31c7be8]
+- Updated dependencies [2696562]
+  - ai@7.0.27
+  - @ai-sdk/provider-utils@5.0.10
+
+## 1.0.31
+
+### Patch Changes
+
+- Updated dependencies [27d294d]
+  - ai@7.0.26
+
+## 1.0.30
+
+### Patch Changes
+
+- Updated dependencies [4be62c1]
+- Updated dependencies [7805e4a]
+- Updated dependencies [7805e4a]
+- Updated dependencies [f8e82fd]
+- Updated dependencies [cd12954]
+  - @ai-sdk/provider-utils@5.0.9
+  - ai@7.0.25
+
+## 1.0.29
+
+### Patch Changes
+
+- Updated dependencies [e193290]
+- Updated dependencies [e193290]
+  - @ai-sdk/provider-utils@5.0.8
+  - ai@7.0.24
+
+## 1.0.28
+
+### Patch Changes
+
+- Updated dependencies [930f949]
+  - ai@7.0.23
+
+## 1.0.27
+
+### Patch Changes
+
+- Updated dependencies [8f89c25]
+  - ai@7.0.22
+
+## 1.0.26
+
+### Patch Changes
+
+- Updated dependencies [308a519]
+  - ai@7.0.21
+
+## 1.0.25
+
+### Patch Changes
+
+- 44e988a: fix(harness): fix harness tool approval regression
+
+## 1.0.24
+
+### Patch Changes
+
+- Updated dependencies [b9ac19f]
+- Updated dependencies [a4186d6]
+  - ai@7.0.20
+
+## 1.0.23
+
+### Patch Changes
+
+- 39c8276: fix(harness): improve opaque sandbox bridge error handling
+- 91fe6d8: fix(harness): emit `finish-step` stream parts correctly per the underlying model steps
+- 0be5014: fix(harness): fix obsolete portions of harness package readme
+
+## 1.0.22
+
+### Patch Changes
+
+- Updated dependencies [be7f05a]
+- Updated dependencies [ee55a07]
+- Updated dependencies [aad737d]
+- Updated dependencies [0f93c57]
+  - ai@7.0.19
+  - @ai-sdk/provider@4.0.3
+  - @ai-sdk/provider-utils@5.0.7
+
+## 1.0.21
+
+### Patch Changes
+
+- Updated dependencies [ac306ed]
+  - @ai-sdk/provider-utils@5.0.6
+  - ai@7.0.18
+
+## 1.0.20
+
+### Patch Changes
+
+- b7aa06a: fix(harness): include step numbers on harness step-end telemetry events.
+  - ai@7.0.17
+
+## 1.0.19
+
+### Patch Changes
+
+- Updated dependencies [a8f9b6d]
+  - ai@7.0.16
+
+## 1.0.18
+
+### Patch Changes
+
+- ai@7.0.15
+
+## 1.0.17
+
+### Patch Changes
+
+- 5c5c0f5: Add experimental streaming transcription support for transcription models, including OpenAI `gpt-realtime-whisper` and xAI WebSocket STT.
+- Updated dependencies [5c5c0f5]
+  - ai@7.0.14
+  - @ai-sdk/provider@4.0.2
+  - @ai-sdk/provider-utils@5.0.5
+
+## 1.0.16
+
+### Patch Changes
+
+- ai@7.0.13
+
+## 1.0.15
+
+### Patch Changes
+
+- Updated dependencies [ecfeb6f]
+- Updated dependencies [a193137]
+- Updated dependencies [c6f5e62]
+  - ai@7.0.12
+  - @ai-sdk/provider-utils@5.0.4
+
+## 1.0.14
+
+### Patch Changes
+
+- Updated dependencies [0a87626]
+  - ai@7.0.11
+
+## 1.0.13
+
+### Patch Changes
+
+- Updated dependencies [8c616f0]
+  - ai@7.0.10
+  - @ai-sdk/provider-utils@5.0.3
+
+## 1.0.12
+
+### Patch Changes
+
+- 7859cea: feat(harness): add tool filtering via `activeTools` and `inactiveTools`
+- c857346: feat(harness): add utility functions for certain duplicated layers in harnesses
+
+## 1.0.11
+
+### Patch Changes
+
+- ai@7.0.9
+
+## 1.0.10
+
+### Patch Changes
+
+- Updated dependencies [0274f34]
+  - @ai-sdk/provider@4.0.1
+  - ai@7.0.8
+  - @ai-sdk/provider-utils@5.0.2
+
+## 1.0.9
+
+### Patch Changes
+
+- Updated dependencies [d598481]
+  - ai@7.0.7
+
+## 1.0.8
+
+### Patch Changes
+
+- Updated dependencies [989402d]
+  - ai@7.0.6
+
+## 1.0.7
+
+### Patch Changes
+
+- Updated dependencies [a2750db]
+  - ai@7.0.5
+
+## 1.0.6
+
+### Patch Changes
+
+- Updated dependencies [6a436e3]
+  - @ai-sdk/provider-utils@5.0.1
+  - ai@7.0.4
+
+## 1.0.5
+
+### Patch Changes
+
+- ai@7.0.3
+
+## 1.0.4
+
+### Patch Changes
+
+- c493634: fix(harness): fix harness Zod usage to be v3/v4 compatible
+
+## 1.0.3
+
+### Patch Changes
+
+- 51d10a0: feat(harness): add `prepareSandboxForHarness` utility to prepare a caller-owned sandbox for one or more harnesses
+
+## 1.0.2
+
+### Patch Changes
+
+- ai@7.0.2
+
+## 1.0.1
+
+### Patch Changes
+
+- ai@7.0.1
+
+## 1.0.0
+
+### Major Changes
+
+- 9d6dbe0: feat(harness): add sandbox specific expansion for harness abstraction, add `sandbox-just-bash` and `sandbox-vercel`
+
+### Patch Changes
+
+- e5d4a24: chore(harness): update ws package
+- aae0138: fix(harness): make listening for sandbox bridge readiness compatible with Bun
+- be83911: fix(harness): reject bridge startup when the WebSocket port cannot be bound
+- 3d87086: fix(harness): guard against invalid resuming a session vs continuing a turn
+- d77bed4: chore(harness): separate harness spec types (v1) from consumer-facing types
+- 21d3d60: feat(harness): implement harness specification
+- 3d9a50c: feat(harness): implement harness adapters for Claude Code, Codex, Pi
+- 57e0a59: fix(harness): ensure finish chunk's total usage is actually coming from total usage
+- 6c7a3e5: Start the `1.0.0` canary release line for the experimental harness and sandbox packages. They were unintentionally published as `0.0.0-canary.*` because they were scaffolded with a `0.0.0-canary.0` premajor version, which semver could not advance past on a major bump.
+- 1ea15a3: fix(harness): fix various bugs with harness skills not being correctly processed by the harness adapters
+- a83a367: feat(harness): allow pre-snapshot `sandboxConfig.onBootstrap` callback in `HarnessAgent`
+- b8396f0: trigger initial beta release
+- 534dac6: fix(harness): fix incomplete OIDC token support for AI Gateway auth in harness adapters
+
+## 1.0.0-beta.27
+
+### Patch Changes
+
+- ai@7.0.0-beta.187
+
+## 1.0.0-beta.26
+
+### Patch Changes
+
+- a83a367: feat(harness): allow pre-snapshot `sandboxConfig.onBootstrap` callback in `HarnessAgent`
+
+## 1.0.0-beta.25
+
+### Patch Changes
+
+- ai@7.0.0-beta.186
+
+## 1.0.0-beta.24
+
+### Patch Changes
+
+- Updated dependencies [75763b0]
+  - ai@7.0.0-beta.185
+
+## 1.0.0-beta.23
+
+### Patch Changes
+
+- 57e0a59: fix(harness): ensure finish chunk's total usage is actually coming from total usage
+
+## 1.0.0-beta.22
+
+### Patch Changes
+
+- Updated dependencies [0416e3e]
+  - @ai-sdk/provider@4.0.0-beta.20
+  - ai@7.0.0-beta.184
+  - @ai-sdk/provider-utils@5.0.0-beta.50
+
+## 1.0.0-beta.21
+
+### Patch Changes
+
+- ai@7.0.0-beta.183
+
+## 1.0.0-beta.20
+
+### Patch Changes
+
+- e5d4a24: chore(harness): update ws package
+- Updated dependencies [cc6ab90]
+  - ai@7.0.0-beta.182
+
+## 1.0.0-beta.19
+
+### Patch Changes
+
+- Updated dependencies [6a2caf9]
+  - ai@7.0.0-beta.181
+
+## 1.0.0-beta.18
+
+### Patch Changes
+
+- Updated dependencies [81a284b]
+  - ai@7.0.0-beta.180
+
+## 1.0.0-beta.17
+
+### Patch Changes
+
+- 534dac6: fix(harness): fix incomplete OIDC token support for AI Gateway auth in harness adapters
+
+## 1.0.0-beta.16
+
+### Patch Changes
+
+- ai@7.0.0-beta.179
+
+## 1.0.0-beta.15
+
+### Patch Changes
+
+- Updated dependencies [b097c52]
+  - ai@7.0.0-beta.178
+
+## 1.0.0-beta.14
+
+### Patch Changes
+
+- b8396f0: trigger initial beta release
+- Updated dependencies [b8396f0]
+  - @ai-sdk/provider-utils@5.0.0-beta.49
+  - @ai-sdk/provider@4.0.0-beta.19
+  - ai@7.0.0-beta.177
+
+## 1.0.0-canary.13
+
+### Patch Changes
+
+- ai@7.0.0-canary.176
+
+## 1.0.0-canary.12
+
+### Patch Changes
+
+- Updated dependencies [6ec57f5]
+  - ai@7.0.0-canary.175
+
+## 1.0.0-canary.11
+
+### Patch Changes
+
+- be83911: fix(harness): reject bridge startup when the WebSocket port cannot be bound
+
+## 1.0.0-canary.10
+
+### Patch Changes
+
+- ai@7.0.0-canary.174
+
+## 1.0.0-canary.9
+
+### Patch Changes
+
+- ai@7.0.0-canary.173
+
+## 1.0.0-canary.8
+
+### Patch Changes
+
+- aae0138: fix(harness): make listening for sandbox bridge readiness compatible with Bun
+
+## 1.0.0-canary.7
+
+### Patch Changes
+
+- 3d87086: fix(harness): guard against invalid resuming a session vs continuing a turn
+- 1ea15a3: fix(harness): fix various bugs with harness skills not being correctly processed by the harness adapters
+- Updated dependencies [aeda373]
+- Updated dependencies [25a64f8]
+- Updated dependencies [375fdd7]
+- Updated dependencies [f18b08f]
+- Updated dependencies [b4507d5]
+  - @ai-sdk/provider-utils@5.0.0-canary.48
+  - ai@7.0.0-canary.172
+
+## 1.0.0-canary.6
+
+### Patch Changes
+
+- Updated dependencies [89ad56f]
+- Updated dependencies [f9a496f]
+- Updated dependencies [3295831]
+  - ai@7.0.0-canary.171
+
+## 1.0.0-canary.5
+
+### Patch Changes
+
+- d77bed4: chore(harness): separate harness spec types (v1) from consumer-facing types
+- Updated dependencies [bae5e2b]
+- Updated dependencies [69d7128]
+  - ai@7.0.0-canary.170
+  - @ai-sdk/provider-utils@5.0.0-canary.47
+
+## 1.0.0-canary.4
+
+### Patch Changes
+
+- 3d9a50c: feat(harness): implement harness adapters for Claude Code, Codex, Pi
+
+## 1.0.0-canary.3
+
+### Patch Changes
+
+- 21d3d60: feat(harness): implement harness specification
+- Updated dependencies [a5018ab]
+- Updated dependencies [21d3d60]
+- Updated dependencies [426dbbb]
+- Updated dependencies [7fd3360]
+  - ai@7.0.0-canary.169
+
+## 1.0.0-canary.2
+
+### Patch Changes
+
+- 6c7a3e5: Start the `1.0.0` canary release line for the experimental harness and sandbox packages. They were unintentionally published as `0.0.0-canary.*` because they were scaffolded with a `0.0.0-canary.0` premajor version, which semver could not advance past on a major bump.
+
+## 0.0.0-canary.1
+
+### Major Changes
+
+- 9d6dbe0: feat(harness): add sandbox specific expansion for harness abstraction, add `sandbox-just-bash` and `sandbox-vercel`

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2023 Vercel, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,176 @@
+# AI SDK - Harness Specification and Agent
+
+_This package is **experimental**._
+
+`HarnessAgent` implementation plus the underlying harness specification, including an expanded network session sandbox interface to support harness sandbox needs.
+
+## Setup
+
+```bash
+npm i ai zod @ai-sdk/harness @ai-sdk/harness-claude-code @ai-sdk/sandbox-vercel
+```
+
+## Usage
+
+```ts
+import { HarnessAgent } from '@ai-sdk/harness/agent';
+import { claudeCode } from '@ai-sdk/harness-claude-code';
+import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
+import { tool } from 'ai';
+import { z } from 'zod/v4';
+
+const agent = new HarnessAgent({
+  harness: claudeCode,
+  id: 'auth-agent',
+  instructions:
+    'You are a careful refactoring assistant. Prefer minimal diffs.',
+  sandbox: createVercelSandbox({
+    runtime: 'node24',
+    ports: [4000],
+  }),
+  sandboxConfig: {
+    bootstrapHash: 'ripgrep-v1',
+    onBootstrap: async ({ session, abortSignal }) => {
+      const streamResult = await session.run({
+        command:
+          'command -v rg >/dev/null || (apt-get update && apt-get install -y ripgrep)',
+        abortSignal,
+      });
+      if (result.exitCode !== 0) {
+        throw new Error(`Failed to install ripgrep: ${result.stderr}`);
+      }
+    },
+    onSession: async ({ session, sessionWorkDir, abortSignal }) => {
+      await session.writeTextFile({
+        path: `${sessionWorkDir}/README.md`,
+        content: 'Workspace notes for this session.',
+        abortSignal,
+      });
+    },
+  },
+  tools: {
+    deploy: tool({
+      description: 'Deploy to a target environment',
+      inputSchema: z.object({ env: z.enum(['staging', 'production']) }),
+      execute: async ({ env }) => ({ url: `https://${env}.example.com` }),
+    }),
+  },
+});
+
+const session = await agent.createSession();
+
+try {
+  const generateResult = await agent.generate({
+    session,
+    prompt: 'Fix the failing test in src/auth.ts',
+  });
+  console.log(generateResult.text);
+
+  // Streaming
+  const streamResult = await agent.stream({
+    session,
+    prompt: 'Now write a regression test',
+  });
+  for await (const part of streamResult.stream) {
+    if (part.type === 'text-delta') {
+      process.stdout.write(part.text);
+    }
+  }
+} finally {
+  await session.destroy();
+}
+```
+
+Use `session.detach()` to park a bridge-backed session for later attach, `session.stop()` to save state and stop the sandbox, or `session.destroy()` to clean up without keeping resume state. Bridge-backed adapters such as Claude Code, Codex, OpenCode, and DeepAgents require a sandbox provider that exposes ports — `@ai-sdk/sandbox-vercel` is the supported choice today. `@ai-sdk/sandbox-just-bash` is suitable only for host-runtime or otherwise non-bridge flows, such as Pi.
+
+`sandbox` is a required `HarnessV1SandboxProvider` — the agent calls `provider.createSession()` when a session starts. Use `sandboxConfig` for agent specific sandbox configuration that works independently from the sandbox provider that is used:
+
+- Use `sandboxConfig.onSession` to prepare the acquired sandbox before the harness adapter starts. The hook runs for fresh and resumed sessions, so keep it idempotent.
+- Use `sandboxConfig.onBootstrap` for expensive sandbox setup that should be baked into a reusable snapshot, such as installing tools or cloning a large repository. Provide `sandboxConfig.bootstrapHash` with it and change that value whenever the bootstrap output should invalidate the cached snapshot.
+- Use `sandboxConfig.workDir` to set a stable working directory for the agent, relative to the sandbox's default working directory; otherwise regular sessions use the existing `<harnessId>-<sessionId>` directory. In that case, the `onBootstrap` callback receives the sandbox's default working directory.
+
+Use `prepareHarnessSandboxTemplate()` to create or refresh the sandbox provider's
+own reusable template for one harness before serving traffic. This is the
+replacement for `prewarmHarness()`, which remains as a deprecated alias.
+
+Use `prepareSandboxForHarness()` when you own an existing sandbox and want to
+prepare it before creating your own snapshot. It applies the selected harness
+bootstrap recipes and `sandboxConfig.onBootstrap`, returns the computed
+preparation identity and per-harness recipe identities, and leaves snapshotting
+or stopping the sandbox to your code. Later, create a sandbox from that snapshot
+and pass the native sandbox object to `createVercelSandbox({ sandbox })` for the
+`HarnessAgent`. When you reuse a caller-provided sandbox with a bridge-backed
+harness, declare the available port pool, for example
+`createVercelSandbox({ sandbox, bridgePorts: [4000] })`.
+
+### Available harnesses
+
+See the [harness adapters documentation](https://ai-sdk.dev/v7/docs/ai-sdk-harnesses/harness-adapters).
+
+## Implementing a harness
+
+Implement the `HarnessV1` factory and a `HarnessV1Session` whose `doPromptTurn` emits events; the agent surface, streaming, tool execution, and multi-turn state are handled for you. Read `startOpts.sandboxSession` for the network sandbox session the agent created and will stop on cleanup. Call `sandboxSession.restricted()` for the tool-safe file-IO/exec/spawn surface.
+
+```ts
+import type { HarnessV1, HarnessV1Session } from '@ai-sdk/harness';
+
+export function myHarness(): HarnessV1 {
+  return {
+    specificationVersion: 'harness-v1',
+    harnessId: 'my-harness',
+    builtinTools: {},
+    doStart: async startOpts => {
+      const usage = {
+        inputTokens: { total: 0, noCache: 0 },
+        outputTokens: { total: 0, text: 0 },
+      };
+      const resumeState = {
+        type: 'resume-session' as const,
+        harnessId: 'my-harness',
+        specificationVersion: 'harness-v1' as const,
+        data: {},
+      };
+      const continueState = {
+        type: 'continue-turn' as const,
+        harnessId: 'my-harness',
+        specificationVersion: 'harness-v1' as const,
+        data: {},
+      };
+      const session: HarnessV1Session = {
+        sessionId: startOpts.sessionId,
+        isResume:
+          startOpts.resumeFrom != null || startOpts.continueFrom != null,
+        doPromptTurn: async promptOpts => {
+          const done = Promise.resolve().then(() => {
+            promptOpts.emit({ type: 'text-start', id: 't' });
+            promptOpts.emit({ type: 'text-delta', id: 't', delta: 'Hello.' });
+            promptOpts.emit({ type: 'text-end', id: 't' });
+            promptOpts.emit({
+              type: 'finish',
+              finishReason: { unified: 'stop', raw: 'stop' },
+              totalUsage: usage,
+            });
+          });
+          return { submitToolResult: async () => {}, done };
+        },
+        doContinueTurn: async continueOpts => {
+          const done = Promise.resolve().then(() => {
+            continueOpts.emit({
+              type: 'finish',
+              finishReason: { unified: 'stop', raw: 'stop' },
+              totalUsage: usage,
+            });
+          });
+          return { submitToolResult: async () => {}, done };
+        },
+        doCompact: async () => {},
+        doDetach: async () => resumeState,
+        doStop: async () => resumeState,
+        doDestroy: async () => {},
+        doSuspendTurn: async () => continueState,
+      };
+      return session;
+    },
+  };
+}
+```