@ai-sdk/harness 1.0.75 → 1.0.77

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @ai-sdk/harness
 
+## 1.0.77
+
+### Patch Changes
+
+- Updated dependencies [e6087c9]
+- Updated dependencies [9566914]
+- Updated dependencies [b181020]
+- Updated dependencies [7054073]
+- Updated dependencies [a828527]
+- Updated dependencies [d3cc3fe]
+  - @ai-sdk/provider-utils@5.0.28
+  - ai@7.0.70
+
+## 1.0.76
+
+### Patch Changes
+
+- fc1970b: feat(harness): allow passing caller-owned `sandboxSession` to `HarnessAgent.createSession()` and in that case allow omitting the then unnecessary `sandbox` arg from `HarnessAgent` constructor
+  - ai@7.0.69
+
 ## 1.0.75
 
 ### Patch Changes

package/README.md

@@ -98,9 +98,9 @@ const agent = new HarnessAgent({
 });
 ```
 
-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.
+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 network sandbox session 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:
+`sandbox` is an optional `HarnessV1SandboxProvider`. When omitted, pass a `HarnessV1NetworkSandboxSession` to every `agent.createSession({ sandboxSession })` call. 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.
@@ -116,9 +116,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`. When you reuse a caller-provided sandbox with a bridge-backed
-harness, declare the available port pool, for example
-`createVercelSandbox({ sandbox, bridgePorts: [4000] })`.
+`HarnessAgent`. When several bridge-backed harnesses share a caller-provided
+sandbox, create that sandbox with one exposed port for each harness. Then pass
+each harness's assigned port to that harness's `create*` function.
 
 ### Available harnesses
 
@@ -126,7 +126,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 `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.
+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 selected network sandbox session. The harness layer stops or destroys sessions it acquires from the provider, while a session passed to `agent.createSession({ sandboxSession })` remains caller-owned. Call `sandboxSession.restricted()` for the tool-safe file-IO/exec/spawn surface.
 
 Each prompt and continuation receives an optional `responseFormat`. JSON
 formats carry a caller-provided JSON Schema plus optional name and description;

package/dist/agent/index.d.ts

@@ -4,75 +4,6 @@ import { OutputInterface, StopCondition, ToolApprovalStatus, TelemetryOptions, A
 import { z } from 'zod/v4';
 import { JSONValue, LanguageModelV4ToolCall, LanguageModelV4ToolApprovalRequest, LanguageModelV4ToolResult, LanguageModelV4FinishReason, LanguageModelV4Usage, JSONSchema7, AISDKError } from '@ai-sdk/provider';
 
-/** Severity of a diagnostic. */
-type HarnessDebugLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
-/**
- * Consumer-facing diagnostics configuration. Set on `HarnessAgentSettings` to
- * enable bridge log forwarding and the `HARNESS_DEBUG` stderr default in code.
- * `HARNESS_DEBUG` / `HARNESS_DEBUG_LEVEL` / `HARNESS_DEBUG_SUBSYSTEMS` env vars
- * fill any unset field — a convenience default, never the only path.
- */
-type HarnessDebugConfig = {
-    /** Master switch. Nothing is captured or forwarded when false/unset. */
-    readonly enabled?: boolean;
-    /** Threshold; events at or above this severity are emitted. Default `debug`. */
-    readonly level?: HarnessDebugLevel;
-    /** Dotted-prefix subsystem filter for structured events. */
-    readonly subsystems?: ReadonlyArray<string>;
-};
-/**
- * A forwarded bridge diagnostic, normalized for host consumers.
- *
- * The bridge emits two raw frame kinds — captured console lines (`sandbox-log`)
- * and structured events (`debug-event`). The framework normalizes both into
- * this single shape before handing them to a consumer's `onLog` callback, the
- * `HARNESS_DEBUG` stderr default, and observability reporters. Diagnostics are
- * kept first-class and per-line — they are never folded into telemetry spans.
- */
-type HarnessDiagnostic = {
-    /**
-     * Severity. Structured events carry their own level; captured console lines
-     * map `stderr` → `'warn'` and `stdout` → `'info'`.
-     */
-    readonly level: HarnessDebugLevel;
-    /** Human-readable line (console capture) or message (structured event). */
-    readonly message: string;
-    /**
-     * Dotted subsystem. For captured console output this is
-     * `sandbox.log.<source>`; for structured events it is the adapter-supplied
-     * subsystem (e.g. `bridge.turn`).
-     */
-    readonly subsystem: string;
-    /** `'log'` = captured console line; `'event'` = structured `bridgeLog`. */
-    readonly kind: 'log' | 'event';
-    /** Originating sandbox source label (console capture). */
-    readonly source?: string;
-    /** Which standard stream the line came from (console capture). */
-    readonly stream?: 'stdout' | 'stderr';
-    /** Structured attributes (structured events only). */
-    readonly attrs?: Record<string, unknown>;
-    /** Error payload (structured events only). */
-    readonly error?: {
-        name?: string;
-        message: string;
-        stack?: string;
-    };
-    /** The harness session this diagnostic originated from. */
-    readonly sessionId?: string;
-    /** Host receipt time (epoch ms). */
-    readonly timestamp: number;
-};
-/**
- * A telemetry integration that also wants the per-line diagnostics stream. The
- * framework calls `ingestDiagnostic` for every forwarded bridge diagnostic in
- * addition to driving the standard `Telemetry` span lifecycle, so a single
- * reporter object (e.g. `createFileReporter`) registered in
- * `telemetry.integrations` receives both spans and logs.
- */
-interface HarnessDiagnosticConsumer {
-    ingestDiagnostic?(diagnostic: HarnessDiagnostic): void;
-}
-
 /**
  * One file to write into the sandbox as part of an adapter's bootstrap recipe.
  * Absolute paths are used as-is. Relative paths are resolved against the
@@ -1111,17 +1042,6 @@ type HarnessV1BuiltinTool<INPUT = unknown, OUTPUT = unknown> = Tool<INPUT, OUTPU
 interface HarnessV1SandboxProvider {
     readonly specificationVersion: 'harness-sandbox-v1';
     readonly providerId: string;
-    /**
-     * Pool of ports the consumer reserved on a caller-provided sandbox for
-     * concurrent harness sessions. The session manager leases one port per
-     * session and releases on stop or destroy.
-     *
-     * Only meaningful when the provider wraps a caller-provided sandbox
-     * (the caller pre-declared the ports). In create-new modes the provider
-     * mints a fresh sandbox per session, so no leasing is needed; providers
-     * leave this undefined.
-     */
-    readonly bridgePorts?: ReadonlyArray<number>;
     /**
      * Providers should throw `HarnessSandboxAuthenticationError` when sandbox
      * acquisition fails because credentials are missing, invalid, or not
@@ -1178,6 +1098,75 @@ interface HarnessV1SandboxProvider {
     }) => PromiseLike<HarnessV1NetworkSandboxSession>;
 }
 
+/** Severity of a diagnostic. */
+type HarnessDebugLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+/**
+ * Consumer-facing diagnostics configuration. Set on `HarnessAgentSettings` to
+ * enable bridge log forwarding and the `HARNESS_DEBUG` stderr default in code.
+ * `HARNESS_DEBUG` / `HARNESS_DEBUG_LEVEL` / `HARNESS_DEBUG_SUBSYSTEMS` env vars
+ * fill any unset field — a convenience default, never the only path.
+ */
+type HarnessDebugConfig = {
+    /** Master switch. Nothing is captured or forwarded when false/unset. */
+    readonly enabled?: boolean;
+    /** Threshold; events at or above this severity are emitted. Default `debug`. */
+    readonly level?: HarnessDebugLevel;
+    /** Dotted-prefix subsystem filter for structured events. */
+    readonly subsystems?: ReadonlyArray<string>;
+};
+/**
+ * A forwarded bridge diagnostic, normalized for host consumers.
+ *
+ * The bridge emits two raw frame kinds — captured console lines (`sandbox-log`)
+ * and structured events (`debug-event`). The framework normalizes both into
+ * this single shape before handing them to a consumer's `onLog` callback, the
+ * `HARNESS_DEBUG` stderr default, and observability reporters. Diagnostics are
+ * kept first-class and per-line — they are never folded into telemetry spans.
+ */
+type HarnessDiagnostic = {
+    /**
+     * Severity. Structured events carry their own level; captured console lines
+     * map `stderr` → `'warn'` and `stdout` → `'info'`.
+     */
+    readonly level: HarnessDebugLevel;
+    /** Human-readable line (console capture) or message (structured event). */
+    readonly message: string;
+    /**
+     * Dotted subsystem. For captured console output this is
+     * `sandbox.log.<source>`; for structured events it is the adapter-supplied
+     * subsystem (e.g. `bridge.turn`).
+     */
+    readonly subsystem: string;
+    /** `'log'` = captured console line; `'event'` = structured `bridgeLog`. */
+    readonly kind: 'log' | 'event';
+    /** Originating sandbox source label (console capture). */
+    readonly source?: string;
+    /** Which standard stream the line came from (console capture). */
+    readonly stream?: 'stdout' | 'stderr';
+    /** Structured attributes (structured events only). */
+    readonly attrs?: Record<string, unknown>;
+    /** Error payload (structured events only). */
+    readonly error?: {
+        name?: string;
+        message: string;
+        stack?: string;
+    };
+    /** The harness session this diagnostic originated from. */
+    readonly sessionId?: string;
+    /** Host receipt time (epoch ms). */
+    readonly timestamp: number;
+};
+/**
+ * A telemetry integration that also wants the per-line diagnostics stream. The
+ * framework calls `ingestDiagnostic` for every forwarded bridge diagnostic in
+ * addition to driving the standard `Telemetry` span lifecycle, so a single
+ * reporter object (e.g. `createFileReporter`) registered in
+ * `telemetry.integrations` receives both spans and logs.
+ */
+interface HarnessDiagnosticConsumer {
+    ingestDiagnostic?(diagnostic: HarnessDiagnostic): void;
+}
+
 type HarnessAgentAdapter<TBuiltinTools extends ToolSet = ToolSet> = HarnessV1<TBuiltinTools>;
 type HarnessAgentBuiltinTool<INPUT = unknown, OUTPUT = unknown> = HarnessV1BuiltinTool<INPUT, OUTPUT>;
 type HarnessAgentBuiltinToolName = HarnessV1BuiltinToolName;
@@ -1333,12 +1322,11 @@ type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAge
      */
     readonly toolApproval?: HarnessAgentToolApprovalConfiguration;
     /**
-     * Sandbox provider whose `create()` produces the network sandbox session the
-     * harness runs against. Its `restricted()` view is also propagated to user
-     * tool `execute()` calls (as the `experimental_sandbox` field), typed as
-     * `Experimental_SandboxSession` so tools cannot reach the infra surface.
+     * Optional sandbox provider used to create or resume network sandbox
+     * sessions. When omitted, every `createSession()` call must provide an
+     * existing network sandbox session.
      */
-    readonly sandbox: HarnessV1SandboxProvider;
+    readonly sandbox?: HarnessV1SandboxProvider;
     /**
      * Sandbox working-directory and lifecycle hook configuration.
      */
@@ -1414,9 +1402,7 @@ type HarnessAgentTurnState = 'idle' | 'running' | 'awaiting-approval' | 'awaitin
  * Live harness session held by the caller.
  *
  * Created by {@link import('./harness-agent').HarnessAgent.createSession}.
- * Owns the underlying adapter session, the network sandbox session, and the
- * bridge-port lease (when the provider wraps a caller-provided sandbox with a
- * port pool).
+ * Owns the underlying adapter session and the network sandbox session.
  *
  * Pass the instance back to `agent.generate` / `agent.stream` on every
  * call; end the local handle with `detach()`, `stop()`, or `destroy()`.
@@ -1432,11 +1418,10 @@ declare class HarnessAgentSession {
      */
     readonly sessionId: string;
     private readonly harness;
-    private readonly sandboxProvider;
     private readonly sessionWorkDir;
+    private readonly ownsSandboxLifecycle;
     private underlyingSession;
     private sandboxSession;
-    private leasedBridgePort;
     private readonly toolApproval;
     private readonly pendingToolApprovals;
     private readonly pendingToolResults;
@@ -1455,8 +1440,7 @@ declare class HarnessAgentSession {
         harness: HarnessAgentAdapter;
         underlyingSession: HarnessAgentAdapterSession;
         sandboxSession: HarnessV1NetworkSandboxSession;
-        sandboxProvider: HarnessV1SandboxProvider;
-        leasedBridgePort?: number;
+        ownsSandboxLifecycle?: boolean;
         sessionWorkDir: string;
         toolApproval: HarnessAgentToolApprovalConfiguration | undefined;
         pendingToolApprovals?: readonly HarnessAgentPendingToolApproval[];
@@ -1512,14 +1496,15 @@ declare class HarnessAgentSession {
      */
     detach(): Promise<HarnessAgentResumeSessionState>;
     /**
-     * Persist enough state to resume later, then stop the runtime and sandbox.
+     * Persist enough state to resume later, then stop the runtime and any
+     * harness-owned sandbox.
      * Returns the resume state for a future
      * `agent.createSession({ sessionId, resumeFrom })` call.
      */
     stop(): Promise<HarnessAgentResumeSessionState>;
     /**
-     * Stop the runtime and discard resumability. The sandbox is destroyed when
-     * the provider supports destruction; otherwise it is stopped.
+     * Stop the runtime and discard resumability. A harness-owned sandbox is
+     * destroyed when supported; otherwise it is stopped.
      */
     destroy(): Promise<void>;
     /**
@@ -1531,9 +1516,8 @@ declare class HarnessAgentSession {
      *
      * After this call the session is detached. This in-process handle no
      * longer drives turns; a future slice creates a fresh session from the
-     * returned state. The sandbox is **not** stopped and no port lease is
-     * released, because bridge-backed adapters may still have a live bridge on
-     * that port.
+     * returned state. The sandbox is **not** stopped because bridge-backed
+     * adapters may still have a live bridge.
      */
     suspendTurn(): Promise<HarnessAgentContinueTurnState>;
     private getPendingToolApprovals;
@@ -1549,7 +1533,6 @@ declare class HarnessAgentSession {
     private startTrackedTurn;
     private finishTrackedTurn;
     private endLocalHandle;
-    private releasePortLease;
     private requireReusableSession;
 }
 
@@ -1592,12 +1575,13 @@ interface HarnessAgentCallExtensions {
  *    the result is fed back to the harness via `submitToolResult`.
  *    Adapter builtin tools (e.g. Claude Code's `Bash`) pass through
  *    untouched.
- *  - **Sandbox propagation.** `settings.sandbox` is a sandbox provider.
- *    On `createSession`, the agent calls `provider.createSession()` (or
- *    `resumeSession()`) and passes the resulting network sandbox session into
- *    `doStart`. Its `restricted()` view (a tool-safe
+ *  - **Sandbox propagation.** On `createSession`, the agent uses a
+ *    caller-provided network sandbox session when present; otherwise it calls
+ *    the configured provider's `createSession()` (or `resumeSession()`). It
+ *    passes the selected session into `doStart`. Its `restricted()` view (a tool-safe
  *    `Experimental_SandboxSession`) is handed to user-tool `execute()` calls
- *    via `experimental_sandbox`.
+ *    via `experimental_sandbox`. Caller-provided sandboxes remain owned by the
+ *    caller and are not stopped or destroyed by the harness layer.
  */
 declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAgentAdapter, TUserTools extends ToolSet = {}, RUNTIME_CONTEXT extends Context = Context, OUTPUT extends OutputInterface = never> implements Agent<never, HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, OUTPUT> {
     readonly version: "agent-v1";
@@ -1646,6 +1630,11 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
          * handing it to the adapter.
          */
         continueFrom?: HarnessAgentContinueTurnState;
+        /**
+         * Existing network sandbox session to run the harness in. When provided,
+         * the caller retains ownership of the sandbox lifecycle.
+         */
+        sandboxSession?: HarnessV1NetworkSandboxSession;
         abortSignal?: AbortSignal;
     }): Promise<HarnessAgentSession>;
     generate(options: AgentCallParameters<never, HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT> & HarnessAgentCallExtensions): Promise<GenerateTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, OUTPUT>>;
@@ -1676,7 +1665,6 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
         abortSignal?: AbortSignal;
     }): Promise<StreamTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, OUTPUT>>;
     private _startTurn;
-    private _acquireSandbox;
     private _resolveTurnInput;
     private _toToolSpecs;
     private _toGenerateResult;