@ai-sdk/harness 1.0.123 → 1.0.126

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @ai-sdk/harness
 
+## 1.0.126
+
+### Patch Changes
+
+- af9597b: Compile packages for ES2022 runtime target
+- 31742b9: 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
+- Updated dependencies [af9597b]
+- Updated dependencies [bc49f78]
+  - ai@7.0.116
+  - @ai-sdk/provider-utils@5.0.49
+
+## 1.0.125
+
+### Patch Changes
+
+- Updated dependencies [be877ff]
+- Updated dependencies [be877ff]
+  - @ai-sdk/provider-utils@5.0.48
+  - ai@7.0.115
+
+## 1.0.124
+
+### Patch Changes
+
+- 40231b6: fix(harness): enforce tool input schemas at execution and consistently reject invalid inputs
+- Updated dependencies [b5679a7]
+- Updated dependencies [ca31b89]
+  - ai@7.0.114
+
 ## 1.0.123
 
 ### Patch Changes

package/README.md

@@ -15,7 +15,7 @@ npm i ai zod @ai-sdk/harness @ai-sdk/harness-claude-code @ai-sdk/sandbox-vercel
 ```ts
 import { HarnessAgent } from '@ai-sdk/harness/agent';
 import { claudeCode } from '@ai-sdk/harness-claude-code';
-import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
+import { createVercelNetworkSandboxSession } from '@ai-sdk/sandbox-vercel';
 import { tool } from 'ai';
 import { z } from 'zod/v4';
 
@@ -25,14 +25,10 @@ const agent = new HarnessAgent({
   model: 'claude-sonnet-4-5',
   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({
+      const result = await session.run({
         command:
           'command -v rg >/dev/null || (apt-get update && apt-get install -y ripgrep)',
         abortSignal,
@@ -58,7 +54,12 @@ const agent = new HarnessAgent({
   },
 });
 
-const session = await agent.createSession();
+const sandboxSession = await createVercelNetworkSandboxSession({
+  runtime: 'node24',
+  ports: [4000],
+  template: await agent.getSandboxTemplate(),
+});
+const session = await agent.createSession({ sandboxSession });
 
 try {
   const generateResult = await agent.generate({
@@ -79,6 +80,7 @@ try {
   }
 } finally {
   await session.destroy();
+  await sandboxSession.destroy();
 }
 ```
 
@@ -92,7 +94,6 @@ import { Output } from 'ai';
 
 const agent = new HarnessAgent({
   harness: claudeCode,
-  sandbox,
   output: Output.object({
     schema: z.object({ answer: z.string() }),
   }),

package/agent/index.ts

@@ -1,4 +1,5 @@
 export { HarnessAgent } from '../src/agent/harness-agent';
+export { createHarnessSandboxTemplate } from '../src/agent/create-harness-sandbox-template';
 export type { HarnessAllTools } from '../src/agent/harness-agent-tool-types';
 export type {
   HarnessAgentSandboxConfig,
@@ -26,6 +27,7 @@ export type {
   HarnessAgentStartOptions,
   HarnessAgentStreamPart,
   HarnessAgentToolSpec,
+  HarnessSandboxTemplate,
 } from '../src/agent/harness-agent-types';
 export { HarnessAgentSession } from '../src/agent/harness-agent-session';
 export { collectHarnessAgentToolApprovalContinuations } from '../src/agent/harness-agent-tool-approval-continuation';

package/dist/agent/index.d.ts

@@ -58,8 +58,8 @@ type HarnessV1PortEndpoint = {
     readonly headers?: Readonly<Record<string, string>>;
 };
 /**
- * Network sandbox session returned by `HarnessV1SandboxProvider.createSession()`. The
- * harness keeps this for the lifetime of a session. It is itself a
+ * Network sandbox session returned by sandbox adapter creation and resume
+ * functions. The harness keeps this for the lifetime of a session. It is itself a
  * {@link SandboxSession} (file I/O, exec, spawn) and adds the infra surface on
  * top: port resolution, lifecycle, and network-policy mutation.
  *
@@ -70,21 +70,14 @@ type HarnessV1PortEndpoint = {
  */
 interface HarnessV1NetworkSandboxSession extends Experimental_SandboxSession {
     /**
-     * Stable identifier for the underlying sandbox resource. Used by the
-     * harness session manager as the durable lookup key for cross-process
-     * resume — the framework persists this on lifecycle state so a future
-     * process can call `HarnessV1SandboxProvider.resume?({ sessionId })` and
-     * reach the same resource. Providers populate it from their native
-     * identifier (Vercel: the sandbox name; just-bash: a UUID minted at
-     * create time).
+     * Identifier for the sandbox session. Persist this separately from the
+     * harness session ID and resume state when reattaching across processes.
      */
     readonly id: string;
     /**
      * The sandbox's default working directory — the absolute path that
      * `run`/`spawn` resolve relative commands against when no `workingDirectory`
-     * is given. Read from the live sandbox (it is provider-specific and
-     * configurable at create time: Vercel defaults to `/vercel/sandbox`,
-     * just-bash to `/home/user`), never hardcoded.
+     * is given. Read from the live sandbox, never hardcoded.
      *
      * The framework composes each session's working directory underneath this
      * path (`<defaultWorkingDirectory>/<harnessId>-<sessionId>`) so adapters do
@@ -122,7 +115,7 @@ interface HarnessV1NetworkSandboxSession extends Experimental_SandboxSession {
     readonly destroy: () => PromiseLike<void>;
     /**
      * Update the sandbox's outbound network policy. Optional — implementations
-     * without a local enforcement primitive (e.g. just-bash) omit this. Callers
+     * without a local enforcement primitive omit this. Callers
      * use optional-call (`sandboxSession.setNetworkPolicy?.(policy)`); a
      * missing implementation is a no-op.
      */
@@ -147,7 +140,7 @@ interface HarnessV1NetworkSandboxSession extends Experimental_SandboxSession {
     /**
      * Replace the set of ports exposed by the sandbox. Full-replacement
      * semantics: ports omitted from the array are deregistered. Optional —
-     * implementations that cannot expose ports (e.g. just-bash) omit this.
+     * implementations that cannot expose ports omit this.
      */
     readonly setPorts?: (ports: ReadonlyArray<number>, options?: {
         abortSignal?: AbortSignal;
@@ -1095,6 +1088,7 @@ type HarnessV1BuiltinTool<INPUT = unknown, OUTPUT = unknown> = Tool<INPUT, OUTPU
  * `LanguageModelV4` providers, no I/O performed at construction. The actual
  * sandbox is created (or wrapped) when `HarnessAgent` calls `createSession()`.
  */
+/** @deprecated Supply a sandbox session to `HarnessAgent.createSession()` instead. */
 interface HarnessV1SandboxProvider {
     readonly specificationVersion: 'harness-sandbox-v1';
     readonly providerId: string;
@@ -1139,8 +1133,8 @@ interface HarnessV1SandboxProvider {
     }) => PromiseLike<HarnessV1NetworkSandboxSession>;
     /**
      * Reattach to an existing sandbox previously created with the same
-     * `sessionId`. Optional — providers that cannot rehydrate by id (e.g.
-     * just-bash) omit this; the harness throws
+     * `sessionId`. Optional — providers that cannot rehydrate by id omit
+     * this; the harness throws
      * `HarnessCapabilityUnsupportedError` when resume is attempted against
      * them.
      *
@@ -1154,6 +1148,14 @@ interface HarnessV1SandboxProvider {
     }) => PromiseLike<HarnessV1NetworkSandboxSession>;
 }
 
+type HarnessV1SandboxTemplate = {
+    readonly identity: string;
+    readonly prepare: (options: {
+        readonly session: Experimental_SandboxSession;
+        readonly abortSignal?: AbortSignal;
+    }) => Promise<void>;
+};
+
 /** Severity of a diagnostic. */
 type HarnessDebugLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
 /**
@@ -1224,6 +1226,7 @@ interface HarnessDiagnosticConsumer {
 }
 
 type HarnessAgentAdapter<TBuiltinTools extends ToolSet = ToolSet> = HarnessV1<TBuiltinTools>;
+type HarnessSandboxTemplate = HarnessV1SandboxTemplate;
 type HarnessAgentBuiltinTool<INPUT = unknown, OUTPUT = unknown> = HarnessV1BuiltinTool<INPUT, OUTPUT>;
 type HarnessAgentBuiltinToolName = HarnessV1BuiltinToolName;
 type HarnessAgentBuiltinToolUseKind = HarnessV1BuiltinToolUseKind;
@@ -1462,6 +1465,7 @@ type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAge
      * sessions. When omitted, every `createSession()` call must provide an
      * existing network sandbox session.
      */
+    /** @deprecated Supply `sandboxSession` to `HarnessAgent.createSession()` instead. */
     readonly sandbox?: HarnessV1SandboxProvider;
     /**
      * Sandbox working-directory and lifecycle hook configuration.
@@ -1743,6 +1747,7 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
     get harnessId(): string;
     /** Whether this agent parses completed turns with its configured output. */
     get hasOutput(): boolean;
+    getSandboxTemplate(): Promise<HarnessSandboxTemplate | undefined>;
     /**
      * Start a fresh session, or resume from state previously returned by
      * `session.detach()` or `session.stop()`. The returned
@@ -1837,6 +1842,11 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
     private _resolveResponseFormat;
 }
 
+declare function createHarnessSandboxTemplate(options: {
+    readonly harnesses: ReadonlyArray<HarnessAgentAdapter>;
+    readonly sandboxConfig?: Omit<HarnessAgentSandboxConfig, 'onSession'>;
+}): Promise<HarnessSandboxTemplate | undefined>;
+
 /**
  * Extract approval decisions that should continue a suspended harness turn.
  *
@@ -1870,8 +1880,8 @@ type SandboxBootstrapSettings = Omit<HarnessAgentSandboxConfig, 'onSession'>;
  *
  * The temporary network sandbox session created during preparation is stopped
  * before the function resolves; the snapshot/template state persists in the
- * provider's native storage (for Vercel: as the `currentSnapshotId` of the
- * named template sandbox).
+ * provider's native storage.
+ * @deprecated Use `createHarnessSandboxTemplate` and pass its template to a sandbox session creator instead.
  */
 declare function prepareHarnessSandboxTemplate(options: {
     readonly harness: HarnessAgentAdapter;
@@ -1882,6 +1892,7 @@ declare function prepareHarnessSandboxTemplate(options: {
 /** @deprecated Use `prepareHarnessSandboxTemplate` instead. */
 declare const prewarmHarness: typeof prepareHarnessSandboxTemplate;
 
+/** @deprecated Use `createHarnessSandboxTemplate` and `template.prepare` instead. */
 type PrepareSandboxForHarnessResult = {
     readonly identity?: string;
     readonly recipeIdentities: Record<string, string>;
@@ -1906,6 +1917,7 @@ type PrepareSandboxForHarnessResult = {
  *
  * Repeated harness IDs are prepared once. When multiple adapters use the same
  * ID, the last adapter in `harnesses` is used.
+ * @deprecated Use `createHarnessSandboxTemplate` and `template.prepare` instead.
  */
 declare function prepareSandboxForHarness(options: {
     readonly session: Experimental_SandboxSession;
@@ -2015,4 +2027,4 @@ interface TraceTreeReporterOptions {
 }
 declare function createTraceTreeReporter(options?: TraceTreeReporterOptions): Telemetry;
 
-export { type FileReporter, type FileReporterOptions, HarnessAgent, type HarnessAgentAdapter, type HarnessAgentAdapterSession, type HarnessAgentBuiltinTool, type HarnessAgentBuiltinToolName, type HarnessAgentBuiltinToolUseKind, type HarnessAgentBuiltinTools, type HarnessAgentContinueTurnOptions, type HarnessAgentContinueTurnState, type HarnessAgentLifecycleState, type HarnessAgentPendingToolApproval, type HarnessAgentPendingToolResult, type HarnessAgentPermissionMode, type HarnessAgentPrompt, type HarnessAgentPromptControl, type HarnessAgentPromptTurnOptions, type HarnessAgentResumeSessionState, type HarnessAgentSandboxConfig, HarnessAgentSession, type HarnessAgentSettings, type HarnessAgentSkill, type HarnessAgentStartOptions, type HarnessAgentStreamPart, type HarnessAgentToolApprovalConfiguration, type HarnessAgentToolSpec, type HarnessAllTools, HarnessCapabilityUnsupportedError, type HarnessDebugConfig, type HarnessDebugLevel, type HarnessDiagnostic, type HarnessDiagnosticConsumer, HarnessError, HarnessSandboxAuthenticationError, type PrepareSandboxForHarnessResult, type TraceTreeReporterOptions, collectHarnessAgentToolApprovalContinuations, collectHarnessAgentToolResultContinuations, createFileReporter, createTraceTreeReporter, getHarnessErrorMessage, prepareHarnessSandboxTemplate, prepareSandboxForHarness, prewarmHarness };
+export { type FileReporter, type FileReporterOptions, HarnessAgent, type HarnessAgentAdapter, type HarnessAgentAdapterSession, type HarnessAgentBuiltinTool, type HarnessAgentBuiltinToolName, type HarnessAgentBuiltinToolUseKind, type HarnessAgentBuiltinTools, type HarnessAgentContinueTurnOptions, type HarnessAgentContinueTurnState, type HarnessAgentLifecycleState, type HarnessAgentPendingToolApproval, type HarnessAgentPendingToolResult, type HarnessAgentPermissionMode, type HarnessAgentPrompt, type HarnessAgentPromptControl, type HarnessAgentPromptTurnOptions, type HarnessAgentResumeSessionState, type HarnessAgentSandboxConfig, HarnessAgentSession, type HarnessAgentSettings, type HarnessAgentSkill, type HarnessAgentStartOptions, type HarnessAgentStreamPart, type HarnessAgentToolApprovalConfiguration, type HarnessAgentToolSpec, type HarnessAllTools, HarnessCapabilityUnsupportedError, type HarnessDebugConfig, type HarnessDebugLevel, type HarnessDiagnostic, type HarnessDiagnosticConsumer, HarnessError, HarnessSandboxAuthenticationError, type HarnessSandboxTemplate, type PrepareSandboxForHarnessResult, type TraceTreeReporterOptions, collectHarnessAgentToolApprovalContinuations, collectHarnessAgentToolResultContinuations, createFileReporter, createHarnessSandboxTemplate, createTraceTreeReporter, getHarnessErrorMessage, prepareHarnessSandboxTemplate, prepareSandboxForHarness, prewarmHarness };