@ai-sdk/harness 1.0.22 → 1.0.23

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @ai-sdk/harness
 
+## 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

package/README.md

@@ -7,22 +7,23 @@ _This package is **experimental**._
 ## Setup
 
 ```bash
-npm i @ai-sdk/harness
+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 { createClaudeCode } from '@ai-sdk/harness-claude-code';
+import { claudeCode } from '@ai-sdk/harness-claude-code';
 import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
 import { tool } from 'ai';
-import { z } from 'zod';
+import { z } from 'zod/v4';
 
 const agent = new HarnessAgent({
-  harness: createClaudeCode(),
+  harness: claudeCode,
   id: 'auth-agent',
-  system: 'You are a careful refactoring assistant. Prefer minimal diffs.',
+  instructions:
+    'You are a careful refactoring assistant. Prefer minimal diffs.',
   sandbox: createVercelSandbox({
     runtime: 'node24',
     ports: [4000],
@@ -30,7 +31,7 @@ const agent = new HarnessAgent({
   sandboxConfig: {
     bootstrapHash: 'ripgrep-v1',
     onBootstrap: async ({ session, abortSignal }) => {
-      const result = await session.run({
+      const streamResult = await session.run({
         command:
           'command -v rg >/dev/null || (apt-get update && apt-get install -y ripgrep)',
         abortSignal,
@@ -51,29 +52,26 @@ const agent = new HarnessAgent({
     deploy: tool({
       description: 'Deploy to a target environment',
       inputSchema: z.object({ env: z.enum(['staging', 'production']) }),
-      execute: async ({ env }) => ({ url: await deployTo(env) }),
+      execute: async ({ env }) => ({ url: `https://${env}.example.com` }),
     }),
   },
-  harnessOptions: {
-    'claude-code': { thinking: 'adaptive' },
-  },
 });
 
 const session = await agent.createSession();
 
 try {
-  const result = await agent.generate({
+  const generateResult = await agent.generate({
     session,
     prompt: 'Fix the failing test in src/auth.ts',
   });
-  console.log(result.text);
+  console.log(generateResult.text);
 
   // Streaming
-  const stream = await agent.stream({
+  const streamResult = await agent.stream({
     session,
     prompt: 'Now write a regression test',
   });
-  for await (const part of stream.fullStream) {
+  for await (const part of streamResult.stream) {
     if (part.type === 'text-delta') {
       process.stdout.write(part.text);
     }
@@ -83,7 +81,7 @@ try {
 }
 ```
 
-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 (claude-code, codex) 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 non-bridge flows.
+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:
 
@@ -101,7 +99,9 @@ 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`.
+`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
 
@@ -109,7 +109,7 @@ See the [harness adapters documentation](https://ai-sdk.dev/v7/docs/ai-sdk-harne
 
 ## Implementing a harness
 
-Implement the `HarnessV1` factory and a `HarnessV1Session` whose `doPrompt` 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.
+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';
@@ -118,46 +118,56 @@ export function myHarness(): HarnessV1 {
   return {
     specificationVersion: 'harness-v1',
     harnessId: 'my-harness',
-    builtinTools: [],
+    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: false,
+        isResume:
+          startOpts.resumeFrom != null || startOpts.continueFrom != null,
         doPromptTurn: async promptOpts => {
-          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: {
-              inputTokens: {
-                total: 0,
-                noCache: 0,
-                cacheRead: undefined,
-                cacheWrite: undefined,
-              },
-              outputTokens: { total: 0, text: 0, reasoning: undefined },
-            },
+          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: Promise.resolve() };
+          return { submitToolResult: async () => {}, done };
         },
-        doContinueTurn: async () => ({
-          submitToolResult: async () => {},
-          done: Promise.resolve(),
-        }),
         doCompact: async () => {},
-        doStop: async () => ({
-          harnessId: 'my-harness',
-          specificationVersion: 'harness-v1',
-          data: {},
-        }),
+        doDetach: async () => resumeState,
+        doStop: async () => resumeState,
         doDestroy: async () => {},
-        doSuspendTurn: async () => ({
-          harnessId: 'my-harness',
-          specificationVersion: 'harness-v1',
-          data: {},
-        }),
+        doSuspendTurn: async () => continueState,
       };
       return session;
     },

package/dist/agent/index.js

@@ -1171,6 +1171,51 @@ function normalizeToolApprovalStatus(input) {
   return input.status;
 }
 
+// src/utils/bridge-diagnostics.ts
+function isSerializedError(error) {
+  return typeof error === "object" && error != null && typeof error.message === "string";
+}
+function stringifyUnknown(value) {
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch (e) {
+    return String(value);
+  }
+}
+function formatBridgeError(error) {
+  var _a3, _b3;
+  if (error instanceof Error) {
+    return (_a3 = error.stack) != null ? _a3 : `${error.name}: ${error.message}`;
+  }
+  if (isSerializedError(error)) {
+    return (_b3 = error.stack) != null ? _b3 : `${error.name ? `${error.name}: ` : ""}${error.message}`;
+  }
+  return stringifyUnknown(error);
+}
+function writeToStderr(line) {
+  try {
+    process.stderr.write(line);
+  } catch (e) {
+  }
+}
+function logBridgeError({
+  harnessId,
+  sessionId,
+  context,
+  error,
+  write = writeToStderr
+}) {
+  const prefix = `[harness:${harnessId}:error${sessionId ? ` session=${sessionId}` : ""}]`;
+  const message = context ? `${context}: ${formatBridgeError(error)}` : formatBridgeError(error);
+  for (const line of message.split("\n")) {
+    if (line.trim().length > 0) {
+      write(`${prefix} ${line}
+`);
+    }
+  }
+}
+
 // src/agent/internal/run-prompt.ts
 function runPrompt(input) {
   var _a3, _b3, _c, _d;
@@ -1222,6 +1267,12 @@ function runPrompt(input) {
       });
     } catch (err) {
       telemetry.error(err);
+      logBridgeError({
+        harnessId: input.harness.harnessId,
+        sessionId: input.session.sessionId,
+        context: "failed to start harness turn",
+        error: err
+      });
       result.fail(err);
       return;
     }
@@ -1665,6 +1716,12 @@ function runPrompt(input) {
         }
         if (value.type === "error") {
           telemetry.error(value.error);
+          logBridgeError({
+            harnessId: input.harness.harnessId,
+            sessionId: input.session.sessionId,
+            context: "harness stream error",
+            error: value.error
+          });
           result.fail(value.error);
           return;
         }
@@ -1679,6 +1736,12 @@ function runPrompt(input) {
       );
     } catch (err) {
       telemetry.error(err);
+      logBridgeError({
+        harnessId: input.harness.harnessId,
+        sessionId: input.session.sessionId,
+        context: "harness turn failed",
+        error: err
+      });
       result.fail(err);
     } finally {
       reader.releaseLock();