@ai-sdk/harness 0.0.0 → 1.0.0-canary.2

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @ai-sdk/harness
+
+## 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,15 @@
+# AI SDK - Harness
+
+_This package is **experimental**._
+
+Harness abstraction, including an expanded network session sandbox interface to support harness sandbox needs.
+
+## Setup
+
+```bash
+npm i @ai-sdk/harness
+```
+
+## Usage
+
+TBD.

package/dist/index.d.ts

@@ -0,0 +1,220 @@
+import { AISDKError } from '@ai-sdk/provider';
+import { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
+
+declare const symbol$1: unique symbol;
+/**
+ * Base error type for failures originating in or signalled by a harness
+ * adapter. Specific failure modes (e.g. unsupported capability) extend this
+ * class.
+ */
+declare class HarnessError extends AISDKError {
+    private readonly [symbol$1];
+    constructor({ message, cause }: {
+        message: string;
+        cause?: unknown;
+    });
+    static isInstance(error: unknown): error is HarnessError;
+}
+
+declare const symbol: unique symbol;
+/**
+ * Thrown when a caller asks the harness to do something the adapter (or the
+ * supplied sandbox) does not support, e.g. requesting manual compaction from
+ * an adapter that only auto-compacts, or invoking `getPortUrl` on a sandbox
+ * that does not expose one.
+ *
+ * The caller supplies the full human-readable message. Optional `harnessId`
+ * is recorded as structured context for tooling.
+ */
+declare class HarnessCapabilityUnsupportedError extends HarnessError {
+    private readonly [symbol];
+    readonly harnessId?: string;
+    constructor({ message, harnessId, cause, }: {
+        message: string;
+        harnessId?: string;
+        cause?: unknown;
+    });
+    static isInstance(error: unknown): error is HarnessCapabilityUnsupportedError;
+}
+
+/**
+ * Network sandbox session returned by `HarnessV1SandboxProvider.createSession()`. 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.
+ *
+ * Code that should only touch the filesystem and spawn processes receives the
+ * reduced view from {@link HarnessV1NetworkSandboxSession.restricted}, never the
+ * network sandbox session itself — so it cannot stop the sandbox or change its
+ * network policy.
+ */
+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 the resume payload 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).
+     */
+    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.
+     *
+     * The framework composes each session's working directory underneath this
+     * path (`<defaultWorkingDirectory>/<harnessId>-<sessionId>`) so adapters do
+     * not bake a provider-specific base into their own paths.
+     */
+    readonly defaultWorkingDirectory: string;
+    /** Ports the sandbox exposes; resolvable to public URLs via `getPortUrl`. */
+    readonly ports: ReadonlyArray<number>;
+    /**
+     * Resolve a publicly-reachable URL for a sandbox-exposed port. Bridge-backed
+     * adapters call this to open their WebSocket to the in-sandbox bridge.
+     */
+    readonly getPortUrl: (options: {
+        port: number;
+        protocol?: 'http' | 'https' | 'ws';
+    }) => PromiseLike<string>;
+    /** Stop the sandbox. Idempotent. */
+    readonly stop: () => PromiseLike<void>;
+    /**
+     * Destroy/delete the sandbox resource when supported. Optional because some
+     * providers only have a stop/dispose concept. Implementations must handle
+     * both a still-running sandbox and a previously stopped sandbox.
+     */
+    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
+     * use optional-call (`sandboxSession.setNetworkPolicy?.(policy)`); a
+     * missing implementation is a no-op.
+     */
+    readonly setNetworkPolicy?: (policy: HarnessV1NetworkPolicy) => PromiseLike<void>;
+    /**
+     * 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.
+     */
+    readonly setPorts?: (ports: ReadonlyArray<number>, options?: {
+        abortSignal?: AbortSignal;
+    }) => PromiseLike<void>;
+    /**
+     * Reduced view of this session, typed as the bare {@link SandboxSession}
+     * (file I/O, exec, spawn) — nothing that could stop the sandbox or change
+     * its network policy. Pass this to user-tool `execute()` calls and other
+     * code that must not reach the infra surface.
+     *
+     * The returned object points at exactly the same underlying sandbox
+     * resource as the network sandbox session it was produced from; it is only a
+     * narrower surface over the same resource, not a separate sandbox.
+     */
+    readonly restricted: () => Experimental_SandboxSession;
+}
+/**
+ * Outbound network policy applied by the sandbox runtime.
+ *
+ * `'allow-all'` and `'deny-all'` are convenience presets. `'custom'` is an
+ * allow-list with an optional CIDR deny-list that takes precedence:
+ *
+ * - Reachable hosts are the union of `allowedHosts` and `allowedCIDRs`.
+ * - `deniedCIDRs` wins over both, useful for blocking cloud-metadata IPs while
+ *   otherwise allowing broad access.
+ *
+ * The two `'custom'` branches share the same discriminator but each requires
+ * a different allow field. Specifying `'custom'` with only `deniedCIDRs`
+ * (deny-only) is rejected at compile time — functionally it would be
+ * equivalent to `'deny-all'`.
+ */
+type HarnessV1NetworkPolicy = {
+    mode: 'allow-all';
+} | {
+    mode: 'deny-all';
+} | {
+    mode: 'custom';
+    allowedHosts: ReadonlyArray<string>;
+    allowedCIDRs?: ReadonlyArray<string>;
+    deniedCIDRs?: ReadonlyArray<string>;
+} | {
+    mode: 'custom';
+    allowedHosts?: ReadonlyArray<string>;
+    allowedCIDRs: ReadonlyArray<string>;
+    deniedCIDRs?: ReadonlyArray<string>;
+};
+
+/**
+ * Provider that produces network sandbox sessions for harness sessions. Lives at
+ * module scope as a stable, synchronous object — analogous to
+ * `LanguageModelV4` providers, no I/O performed at construction. The actual
+ * sandbox is created (or wrapped) when `HarnessAgent` calls `createSession()`.
+ */
+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>;
+    readonly createSession: (options?: {
+        /**
+         * Stable per-session identifier. When supplied, the provider names the
+         * underlying resource deterministically so a future call to `resume`
+         * (potentially from a different process) can find the same sandbox.
+         * Omitted from prewarm and other paths that don't need a resumable
+         * resource — in that case the provider falls back to its native
+         * auto-naming.
+         */
+        sessionId?: string;
+        abortSignal?: AbortSignal;
+        /**
+         * Stable identity for snapshot-based reuse. Providers that support
+         * persistence/snapshots use this as part of the persistent sandbox
+         * name; subsequent calls with the same identity resume from snapshot.
+         *
+         * Ignored when the provider is wrapping a caller-provided sandbox.
+         */
+        identity?: string;
+        /**
+         * Called exactly once per identity, on fresh creation. Snapshot-capable
+         * providers wire this into the platform's one-time-setup hook so the
+         * side effects are baked into the snapshot. Providers without snapshot
+         * support run it immediately after fresh create.
+         *
+         * Not called when the provider is wrapping a caller-provided sandbox
+         * (the caller owns the sandbox; the framework applies its own
+         * idempotent bootstrap post-create instead).
+         */
+        onFirstCreate?: (session: Experimental_SandboxSession, opts: {
+            abortSignal?: AbortSignal;
+        }) => Promise<void>;
+    }) => 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
+     * `HarnessCapabilityUnsupportedError` when resume is attempted against
+     * them.
+     *
+     * The provider derives the sandbox identifier from `sessionId` using the
+     * same deterministic naming scheme it used in `createSession`. Returns a
+     * network sandbox session bound to the existing resource.
+     */
+    readonly resumeSession?: (options: {
+        sessionId: string;
+        abortSignal?: AbortSignal;
+    }) => PromiseLike<HarnessV1NetworkSandboxSession>;
+}
+
+export { HarnessCapabilityUnsupportedError, HarnessError, type HarnessV1NetworkPolicy, type HarnessV1NetworkSandboxSession, type HarnessV1SandboxProvider };

package/dist/index.js

@@ -0,0 +1,42 @@
+// src/errors/harness-error.ts
+import { AISDKError } from "@ai-sdk/provider";
+var name = "AI_HarnessError";
+var marker = `vercel.ai.error.${name}`;
+var symbol = Symbol.for(marker);
+var _a, _b;
+var HarnessError = class extends (_b = AISDKError, _a = symbol, _b) {
+  constructor({ message, cause }) {
+    super({ name, message, cause });
+    this[_a] = true;
+  }
+  static isInstance(error) {
+    return AISDKError.hasMarker(error, marker);
+  }
+};
+
+// src/errors/harness-capability-unsupported-error.ts
+import { AISDKError as AISDKError2 } from "@ai-sdk/provider";
+var name2 = "AI_HarnessCapabilityUnsupportedError";
+var marker2 = `vercel.ai.error.${name2}`;
+var symbol2 = Symbol.for(marker2);
+var _a2, _b2;
+var HarnessCapabilityUnsupportedError = class extends (_b2 = HarnessError, _a2 = symbol2, _b2) {
+  constructor({
+    message,
+    harnessId,
+    cause
+  }) {
+    super({ message, cause });
+    this[_a2] = true;
+    Object.defineProperty(this, "name", { value: name2 });
+    this.harnessId = harnessId;
+  }
+  static isInstance(error) {
+    return AISDKError2.hasMarker(error, marker2);
+  }
+};
+export {
+  HarnessCapabilityUnsupportedError,
+  HarnessError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors/harness-error.ts","../src/errors/harness-capability-unsupported-error.ts"],"sourcesContent":["import { AISDKError } from '@ai-sdk/provider';\n\nconst name = 'AI_HarnessError';\nconst marker = `vercel.ai.error.${name}`;\nconst symbol = Symbol.for(marker);\n\n/**\n * Base error type for failures originating in or signalled by a harness\n * adapter. Specific failure modes (e.g. unsupported capability) extend this\n * class.\n */\nexport class HarnessError extends AISDKError {\n  private readonly [symbol] = true;\n\n  constructor({ message, cause }: { message: string; cause?: unknown }) {\n    super({ name, message, cause });\n  }\n\n  static isInstance(error: unknown): error is HarnessError {\n    return AISDKError.hasMarker(error, marker);\n  }\n}\n","import { AISDKError } from '@ai-sdk/provider';\nimport { HarnessError } from './harness-error';\n\nconst name = 'AI_HarnessCapabilityUnsupportedError';\nconst marker = `vercel.ai.error.${name}`;\nconst symbol = Symbol.for(marker);\n\n/**\n * Thrown when a caller asks the harness to do something the adapter (or the\n * supplied sandbox) does not support, e.g. requesting manual compaction from\n * an adapter that only auto-compacts, or invoking `getPortUrl` on a sandbox\n * that does not expose one.\n *\n * The caller supplies the full human-readable message. Optional `harnessId`\n * is recorded as structured context for tooling.\n */\nexport class HarnessCapabilityUnsupportedError extends HarnessError {\n  private readonly [symbol] = true;\n\n  readonly harnessId?: string;\n\n  constructor({\n    message,\n    harnessId,\n    cause,\n  }: {\n    message: string;\n    harnessId?: string;\n    cause?: unknown;\n  }) {\n    super({ message, cause });\n    Object.defineProperty(this, 'name', { value: name });\n    this.harnessId = harnessId;\n  }\n\n  static isInstance(\n    error: unknown,\n  ): error is HarnessCapabilityUnsupportedError {\n    return AISDKError.hasMarker(error, marker);\n  }\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;AAE3B,IAAM,OAAO;AACb,IAAM,SAAS,mBAAmB,IAAI;AACtC,IAAM,SAAS,OAAO,IAAI,MAAM;AAJhC;AAWO,IAAM,eAAN,eAA2B,iBACd,aADc,IAAW;AAAA,EAG3C,YAAY,EAAE,SAAS,MAAM,GAAyC;AACpE,UAAM,EAAE,MAAM,SAAS,MAAM,CAAC;AAHhC,SAAkB,MAAU;AAAA,EAI5B;AAAA,EAEA,OAAO,WAAW,OAAuC;AACvD,WAAO,WAAW,UAAU,OAAO,MAAM;AAAA,EAC3C;AACF;;;ACrBA,SAAS,cAAAA,mBAAkB;AAG3B,IAAMC,QAAO;AACb,IAAMC,UAAS,mBAAmBD,KAAI;AACtC,IAAME,UAAS,OAAO,IAAID,OAAM;AALhC,IAAAE,KAAAC;AAgBO,IAAM,oCAAN,eAAgDA,MAAA,cACnCD,MAAAD,SADmCE,KAAa;AAAA,EAKlE,YAAY;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,EACF,GAIG;AACD,UAAM,EAAE,SAAS,MAAM,CAAC;AAb1B,SAAkBD,OAAU;AAc1B,WAAO,eAAe,MAAM,QAAQ,EAAE,OAAOH,MAAK,CAAC;AACnD,SAAK,YAAY;AAAA,EACnB;AAAA,EAEA,OAAO,WACL,OAC4C;AAC5C,WAAOK,YAAW,UAAU,OAAOJ,OAAM;AAAA,EAC3C;AACF;","names":["AISDKError","name","marker","symbol","_a","_b","AISDKError"]}

package/package.json

@@ -1 +1,64 @@
-{"name":"@ai-sdk/harness","version":"0.0.0"}
+{
+  "name": "@ai-sdk/harness",
+  "version": "1.0.0-canary.2",
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "source": "./src/index.ts",
+  "files": [
+    "dist/**/*",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "!src/**/__snapshots__",
+    "!src/**/__fixtures__",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@ai-sdk/provider": "4.0.0-canary.18",
+    "@ai-sdk/provider-utils": "5.0.0-canary.46"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.19",
+    "tsup": "^8.5.1",
+    "typescript": "5.8.3",
+    "@vercel/ai-tsconfig": "0.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "homepage": "https://ai-sdk.dev/docs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vercel/ai",
+    "directory": "packages/harness"
+  },
+  "bugs": {
+    "url": "https://github.com/vercel/ai/issues"
+  },
+  "keywords": [
+    "ai",
+    "harness",
+    "agent"
+  ],
+  "scripts": {
+    "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
+    "build:watch": "pnpm clean && tsup --watch",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "type-check": "tsc --build"
+  }
+}

package/src/errors/harness-capability-unsupported-error.ts

@@ -0,0 +1,41 @@
+import { AISDKError } from '@ai-sdk/provider';
+import { HarnessError } from './harness-error';
+
+const name = 'AI_HarnessCapabilityUnsupportedError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Thrown when a caller asks the harness to do something the adapter (or the
+ * supplied sandbox) does not support, e.g. requesting manual compaction from
+ * an adapter that only auto-compacts, or invoking `getPortUrl` on a sandbox
+ * that does not expose one.
+ *
+ * The caller supplies the full human-readable message. Optional `harnessId`
+ * is recorded as structured context for tooling.
+ */
+export class HarnessCapabilityUnsupportedError extends HarnessError {
+  private readonly [symbol] = true;
+
+  readonly harnessId?: string;
+
+  constructor({
+    message,
+    harnessId,
+    cause,
+  }: {
+    message: string;
+    harnessId?: string;
+    cause?: unknown;
+  }) {
+    super({ message, cause });
+    Object.defineProperty(this, 'name', { value: name });
+    this.harnessId = harnessId;
+  }
+
+  static isInstance(
+    error: unknown,
+  ): error is HarnessCapabilityUnsupportedError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/errors/harness-error.ts

@@ -0,0 +1,22 @@
+import { AISDKError } from '@ai-sdk/provider';
+
+const name = 'AI_HarnessError';
+const marker = `vercel.ai.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Base error type for failures originating in or signalled by a harness
+ * adapter. Specific failure modes (e.g. unsupported capability) extend this
+ * class.
+ */
+export class HarnessError extends AISDKError {
+  private readonly [symbol] = true;
+
+  constructor({ message, cause }: { message: string; cause?: unknown }) {
+    super({ name, message, cause });
+  }
+
+  static isInstance(error: unknown): error is HarnessError {
+    return AISDKError.hasMarker(error, marker);
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './errors/harness-error';
+export * from './errors/harness-capability-unsupported-error';
+export type { HarnessV1SandboxProvider } from './v1/harness-v1-sandbox-provider';
+export type {
+  HarnessV1NetworkPolicy,
+  HarnessV1NetworkSandboxSession,
+} from './v1/harness-v1-network-sandbox-session';

package/src/v1/harness-v1-network-sandbox-session.ts

@@ -0,0 +1,123 @@
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+
+/**
+ * Network sandbox session returned by `HarnessV1SandboxProvider.createSession()`. 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.
+ *
+ * Code that should only touch the filesystem and spawn processes receives the
+ * reduced view from {@link HarnessV1NetworkSandboxSession.restricted}, never the
+ * network sandbox session itself — so it cannot stop the sandbox or change its
+ * network policy.
+ */
+export interface HarnessV1NetworkSandboxSession extends 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 the resume payload 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).
+   */
+  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.
+   *
+   * The framework composes each session's working directory underneath this
+   * path (`<defaultWorkingDirectory>/<harnessId>-<sessionId>`) so adapters do
+   * not bake a provider-specific base into their own paths.
+   */
+  readonly defaultWorkingDirectory: string;
+
+  /** Ports the sandbox exposes; resolvable to public URLs via `getPortUrl`. */
+  readonly ports: ReadonlyArray<number>;
+
+  /**
+   * Resolve a publicly-reachable URL for a sandbox-exposed port. Bridge-backed
+   * adapters call this to open their WebSocket to the in-sandbox bridge.
+   */
+  readonly getPortUrl: (options: {
+    port: number;
+    protocol?: 'http' | 'https' | 'ws';
+  }) => PromiseLike<string>;
+
+  /** Stop the sandbox. Idempotent. */
+  readonly stop: () => PromiseLike<void>;
+
+  /**
+   * Destroy/delete the sandbox resource when supported. Optional because some
+   * providers only have a stop/dispose concept. Implementations must handle
+   * both a still-running sandbox and a previously stopped sandbox.
+   */
+  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
+   * use optional-call (`sandboxSession.setNetworkPolicy?.(policy)`); a
+   * missing implementation is a no-op.
+   */
+  readonly setNetworkPolicy?: (
+    policy: HarnessV1NetworkPolicy,
+  ) => PromiseLike<void>;
+
+  /**
+   * 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.
+   */
+  readonly setPorts?: (
+    ports: ReadonlyArray<number>,
+    options?: { abortSignal?: AbortSignal },
+  ) => PromiseLike<void>;
+
+  /**
+   * Reduced view of this session, typed as the bare {@link SandboxSession}
+   * (file I/O, exec, spawn) — nothing that could stop the sandbox or change
+   * its network policy. Pass this to user-tool `execute()` calls and other
+   * code that must not reach the infra surface.
+   *
+   * The returned object points at exactly the same underlying sandbox
+   * resource as the network sandbox session it was produced from; it is only a
+   * narrower surface over the same resource, not a separate sandbox.
+   */
+  readonly restricted: () => SandboxSession;
+}
+
+/**
+ * Outbound network policy applied by the sandbox runtime.
+ *
+ * `'allow-all'` and `'deny-all'` are convenience presets. `'custom'` is an
+ * allow-list with an optional CIDR deny-list that takes precedence:
+ *
+ * - Reachable hosts are the union of `allowedHosts` and `allowedCIDRs`.
+ * - `deniedCIDRs` wins over both, useful for blocking cloud-metadata IPs while
+ *   otherwise allowing broad access.
+ *
+ * The two `'custom'` branches share the same discriminator but each requires
+ * a different allow field. Specifying `'custom'` with only `deniedCIDRs`
+ * (deny-only) is rejected at compile time — functionally it would be
+ * equivalent to `'deny-all'`.
+ */
+export type HarnessV1NetworkPolicy =
+  | { mode: 'allow-all' }
+  | { mode: 'deny-all' }
+  | {
+      mode: 'custom';
+      allowedHosts: ReadonlyArray<string>;
+      allowedCIDRs?: ReadonlyArray<string>;
+      deniedCIDRs?: ReadonlyArray<string>;
+    }
+  | {
+      mode: 'custom';
+      allowedHosts?: ReadonlyArray<string>;
+      allowedCIDRs: ReadonlyArray<string>;
+      deniedCIDRs?: ReadonlyArray<string>;
+    };

package/src/v1/harness-v1-sandbox-provider.ts

@@ -0,0 +1,76 @@
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import type { HarnessV1NetworkSandboxSession } from './harness-v1-network-sandbox-session';
+
+/**
+ * Provider that produces network sandbox sessions for harness sessions. Lives at
+ * module scope as a stable, synchronous object — analogous to
+ * `LanguageModelV4` providers, no I/O performed at construction. The actual
+ * sandbox is created (or wrapped) when `HarnessAgent` calls `createSession()`.
+ */
+export 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>;
+
+  readonly createSession: (options?: {
+    /**
+     * Stable per-session identifier. When supplied, the provider names the
+     * underlying resource deterministically so a future call to `resume`
+     * (potentially from a different process) can find the same sandbox.
+     * Omitted from prewarm and other paths that don't need a resumable
+     * resource — in that case the provider falls back to its native
+     * auto-naming.
+     */
+    sessionId?: string;
+    abortSignal?: AbortSignal;
+    /**
+     * Stable identity for snapshot-based reuse. Providers that support
+     * persistence/snapshots use this as part of the persistent sandbox
+     * name; subsequent calls with the same identity resume from snapshot.
+     *
+     * Ignored when the provider is wrapping a caller-provided sandbox.
+     */
+    identity?: string;
+    /**
+     * Called exactly once per identity, on fresh creation. Snapshot-capable
+     * providers wire this into the platform's one-time-setup hook so the
+     * side effects are baked into the snapshot. Providers without snapshot
+     * support run it immediately after fresh create.
+     *
+     * Not called when the provider is wrapping a caller-provided sandbox
+     * (the caller owns the sandbox; the framework applies its own
+     * idempotent bootstrap post-create instead).
+     */
+    onFirstCreate?: (
+      session: SandboxSession,
+      opts: { abortSignal?: AbortSignal },
+    ) => Promise<void>;
+  }) => 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
+   * `HarnessCapabilityUnsupportedError` when resume is attempted against
+   * them.
+   *
+   * The provider derives the sandbox identifier from `sessionId` using the
+   * same deterministic naming scheme it used in `createSession`. Returns a
+   * network sandbox session bound to the existing resource.
+   */
+  readonly resumeSession?: (options: {
+    sessionId: string;
+    abortSignal?: AbortSignal;
+  }) => PromiseLike<HarnessV1NetworkSandboxSession>;
+}