@ai-sdk/sandbox-just-bash 0.0.0 → 1.0.0-beta.15

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# @ai-sdk/sandbox-just-bash
+
+## 1.0.0-beta.15
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-beta.15
+
+## 1.0.0-beta.14
+
+### Patch Changes
+
+- b8396f0: trigger initial beta release
+- Updated dependencies [b8396f0]
+  - @ai-sdk/harness@1.0.0-beta.14
+  - @ai-sdk/provider-utils@5.0.0-beta.49
+
+## 1.0.0-canary.13
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-canary.13
+
+## 1.0.0-canary.12
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-canary.12
+
+## 1.0.0-canary.11
+
+### Patch Changes
+
+- Updated dependencies [be83911]
+  - @ai-sdk/harness@1.0.0-canary.11
+
+## 1.0.0-canary.10
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-canary.10
+
+## 1.0.0-canary.9
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-canary.9
+
+## 1.0.0-canary.8
+
+### Patch Changes
+
+- Updated dependencies [aae0138]
+  - @ai-sdk/harness@1.0.0-canary.8
+
+## 1.0.0-canary.7
+
+### Patch Changes
+
+- e551763: fix(harness): avoid using peer dependencies for underlying harness and sandbox SDKs
+- Updated dependencies [3d87086]
+- Updated dependencies [aeda373]
+- Updated dependencies [1ea15a3]
+- Updated dependencies [375fdd7]
+- Updated dependencies [b4507d5]
+  - @ai-sdk/harness@1.0.0-canary.7
+  - @ai-sdk/provider-utils@5.0.0-canary.48
+
+## 1.0.0-canary.6
+
+### Patch Changes
+
+- @ai-sdk/harness@1.0.0-canary.6
+
+## 1.0.0-canary.5
+
+### Patch Changes
+
+- Updated dependencies [d77bed4]
+- Updated dependencies [bae5e2b]
+  - @ai-sdk/harness@1.0.0-canary.5
+  - @ai-sdk/provider-utils@5.0.0-canary.47
+
+## 1.0.0-canary.4
+
+### Patch Changes
+
+- Updated dependencies [3d9a50c]
+  - @ai-sdk/harness@1.0.0-canary.4
+
+## 1.0.0-canary.3
+
+### Patch Changes
+
+- Updated dependencies [21d3d60]
+  - @ai-sdk/harness@1.0.0-canary.3
+
+## 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.
+- Updated dependencies [6c7a3e5]
+  - @ai-sdk/harness@1.0.0-canary.2
+
+## 0.0.0-canary.1
+
+### Major Changes
+
+- 9d6dbe0: feat(harness): add sandbox specific expansion for harness abstraction, add `sandbox-just-bash` and `sandbox-vercel`
+
+### Patch Changes
+
+- Updated dependencies [9d6dbe0]
+  - @ai-sdk/harness@0.0.0-canary.1

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,47 @@
+# AI SDK - just-bash Sandbox
+
+_This package is **experimental**._
+
+`HarnessV1SandboxProvider` implementation for [`just-bash`](https://github.com/vercel-labs/just-bash), an in-process JavaScript bash environment with a virtual filesystem. File operations and spawned processes share the same in-memory state.
+
+This provider does not expose ports, so it cannot be used with features that require actual network sandboxes. It is primarily useful for handing a local `Experimental_SandboxSession` to AI SDK tools that accept `experimental_sandbox`.
+
+## Setup
+
+```bash
+npm i @ai-sdk/sandbox-just-bash
+```
+
+## Usage
+
+The factory is synchronous. The returned provider is stable; the actual `just-bash` `Sandbox` is created on demand inside `provider.createSession()`.
+
+```ts
+import { createJustBashSandbox } from '@ai-sdk/sandbox-just-bash';
+
+const justBashSandbox = createJustBashSandbox({ cwd: '/work' });
+
+const networkSandboxSession = await justBashSandbox.createSession();
+const sandboxSession = networkSandboxSession.restricted();
+
+await sandboxSession.writeTextFile({ path: '/work/hello.txt', content: 'hi' });
+
+const { stdout } = await sandboxSession.run({
+  command: 'cat /work/hello.txt',
+});
+console.log(stdout); // "hi"
+```
+
+`networkSandboxSession.restricted()` is typed as `Experimental_SandboxSession` and is the surface to hand to user tools. The network sandbox session's `getPortUrl` throws (just-bash has no port story) and `setNetworkPolicy` is omitted (no local enforcement primitive).
+
+To wrap an already-created `just-bash` `Sandbox` (e.g. with a custom `fs`), pass it via `sandbox`. Install `just-bash` directly if your application imports `Sandbox`, `OverlayFs`, or other `just-bash` exports:
+
+```ts
+import { createJustBashSandbox } from '@ai-sdk/sandbox-just-bash';
+import { OverlayFs, Sandbox } from 'just-bash';
+
+const overlay = new OverlayFs({ root: process.cwd() });
+const sandbox = createJustBashSandbox({
+  sandbox: await Sandbox.create({ fs: overlay, cwd: overlay.getMountPoint() }),
+});
+```

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { HarnessV1SandboxProvider, HarnessV1NetworkSandboxSession } from '@ai-sdk/harness';
+import { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
+import { Sandbox } from 'just-bash';
+
+/**
+ * Parameters forwarded to `just-bash`'s `Sandbox.create` when creating a
+ * sandbox from scratch. Aliased directly from the underlying SDK so the full
+ * surface is available without us re-declaring it.
+ */
+type JustBashSandboxCreateParams = NonNullable<Parameters<typeof Sandbox.create>[0]>;
+/**
+ * Settings for {@link createJustBashSandbox}. Two mutually-exclusive shapes:
+ *
+ * - `{ sandbox }` — wrap an already-created `just-bash` `Sandbox`. The caller
+ *   owns its lifecycle.
+ * - {@link JustBashSandboxCreateParams} fields — provider calls
+ *   `Sandbox.create(settings)` on every `createSession()`.
+ *
+ * just-bash has no port exposure and no snapshot mechanism, so image
+ * management is a per-call no-op: if an adapter declares a bootstrap recipe
+ * the provider runs it once on the freshly-created sandbox before returning.
+ */
+type JustBashSandboxSettings = {
+    sandbox: Sandbox;
+} | (JustBashSandboxCreateParams & {
+    sandbox?: never;
+});
+declare function createJustBashSandbox(settings?: JustBashSandboxSettings): HarnessV1SandboxProvider;
+/**
+ * `HarnessV1SandboxProvider` implementation backed by `just-bash`. Useful for
+ * non-bridge harness flows and for handing a local `Experimental_SandboxSession`
+ * to AI SDK tools — use `provider.createSession()` then
+ * `sandboxSession.restricted()` to get the latter.
+ *
+ * Note: just-bash cannot expose ports, so bridge-backed harness adapters
+ * (claude-code, codex) will reject this provider at start.
+ */
+declare class JustBashSandboxProvider implements HarnessV1SandboxProvider {
+    private readonly settings;
+    readonly specificationVersion: "harness-sandbox-v1";
+    readonly providerId = "just-bash-sandbox";
+    constructor(settings: JustBashSandboxSettings);
+    createSession: (options?: {
+        sessionId?: string;
+        abortSignal?: AbortSignal;
+        identity?: string;
+        onFirstCreate?: (session: Experimental_SandboxSession, opts: {
+            abortSignal?: AbortSignal;
+        }) => Promise<void>;
+    }) => Promise<HarnessV1NetworkSandboxSession>;
+}
+
+export { JustBashSandboxProvider, type JustBashSandboxSettings, createJustBashSandbox };

package/dist/index.js

@@ -0,0 +1,284 @@
+// src/just-bash-sandbox.ts
+import { Sandbox } from "just-bash";
+
+// src/just-bash-network-sandbox-session.ts
+import {
+  HarnessCapabilityUnsupportedError
+} from "@ai-sdk/harness";
+import { randomUUID } from "crypto";
+
+// src/just-bash-sandbox-session.ts
+import { isAbsolute, posix } from "path";
+import {
+  extractLines
+} from "@ai-sdk/provider-utils";
+var JustBashSandboxSession = class {
+  constructor(sandbox) {
+    this.sandbox = sandbox;
+  }
+  get description() {
+    return [
+      "just-bash JavaScript bash environment with a virtual filesystem.",
+      "Filesystem changes and spawned processes share the same in-memory state.",
+      `Current working directory: ${this.sandbox.bashEnvInstance.getCwd()}`
+    ].join("\n");
+  }
+  resolvePath(path) {
+    return isAbsolute(path) ? path : posix.join(this.sandbox.bashEnvInstance.getCwd(), path);
+  }
+  async run({
+    command,
+    workingDirectory,
+    env,
+    abortSignal
+  }) {
+    abortSignal == null ? void 0 : abortSignal.throwIfAborted();
+    const finished = await this.sandbox.runCommand({
+      cmd: "bash",
+      args: ["-c", command],
+      ...workingDirectory !== void 0 ? { cwd: workingDirectory } : {},
+      ...env !== void 0 ? { env } : {},
+      ...abortSignal !== void 0 ? { signal: abortSignal } : {}
+    });
+    const [stdout, stderr] = await Promise.all([
+      finished.stdout(),
+      finished.stderr()
+    ]);
+    return {
+      exitCode: finished.exitCode,
+      stdout,
+      stderr
+    };
+  }
+  async spawn({
+    command,
+    workingDirectory,
+    env,
+    abortSignal
+  }) {
+    abortSignal == null ? void 0 : abortSignal.throwIfAborted();
+    const live = await this.sandbox.runCommand({
+      cmd: "bash",
+      args: ["-c", command],
+      detached: true,
+      ...workingDirectory !== void 0 ? { cwd: workingDirectory } : {},
+      ...env !== void 0 ? { env } : {},
+      ...abortSignal !== void 0 ? { signal: abortSignal } : {}
+    });
+    return createSandboxProcess(live, abortSignal);
+  }
+  async readFile({
+    path,
+    abortSignal
+  }) {
+    const bytes = await this.readBinaryFile({ path, abortSignal });
+    if (bytes == null) return null;
+    return bytesToStream(bytes);
+  }
+  async readBinaryFile({
+    path,
+    abortSignal
+  }) {
+    abortSignal == null ? void 0 : abortSignal.throwIfAborted();
+    const resolved = this.resolvePath(path);
+    try {
+      const bytes = await this.sandbox.bashEnvInstance.fs.readFileBuffer(resolved);
+      return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    } catch (error) {
+      if (isFileNotFoundError(error)) return null;
+      throw error;
+    }
+  }
+  async readTextFile({
+    path,
+    encoding = "utf-8",
+    startLine,
+    endLine,
+    abortSignal
+  }) {
+    const bytes = await this.readBinaryFile({ path, abortSignal });
+    if (bytes == null) return null;
+    const text = Buffer.from(bytes).toString(encoding);
+    return extractLines({ text, startLine, endLine });
+  }
+  async writeFile({
+    path,
+    content,
+    abortSignal
+  }) {
+    const bytes = await collectStream(content);
+    await this.writeBinaryFile({ path, content: bytes, abortSignal });
+  }
+  async writeBinaryFile({
+    path,
+    content,
+    abortSignal
+  }) {
+    abortSignal == null ? void 0 : abortSignal.throwIfAborted();
+    const resolved = this.resolvePath(path);
+    await this.sandbox.bashEnvInstance.fs.writeFile(resolved, content);
+  }
+  async writeTextFile({
+    path,
+    content,
+    encoding = "utf-8",
+    abortSignal
+  }) {
+    const buffer = Buffer.from(content, encoding);
+    await this.writeBinaryFile({
+      path,
+      content: new Uint8Array(
+        buffer.buffer,
+        buffer.byteOffset,
+        buffer.byteLength
+      ),
+      abortSignal
+    });
+  }
+};
+function createSandboxProcess(command, abortSignal) {
+  const encoder = new TextEncoder();
+  const controllers = {};
+  const stdout = new ReadableStream({
+    start(controller) {
+      controllers.stdout = controller;
+    }
+  });
+  const stderr = new ReadableStream({
+    start(controller) {
+      controllers.stderr = controller;
+    }
+  });
+  const drained = (async () => {
+    var _a, _b, _c, _d;
+    try {
+      for await (const message of command.logs()) {
+        const target = message.type === "stdout" ? controllers.stdout : controllers.stderr;
+        target == null ? void 0 : target.enqueue(encoder.encode(message.data));
+      }
+      (_a = controllers.stdout) == null ? void 0 : _a.close();
+      (_b = controllers.stderr) == null ? void 0 : _b.close();
+    } catch (error) {
+      (_c = controllers.stdout) == null ? void 0 : _c.error(error);
+      (_d = controllers.stderr) == null ? void 0 : _d.error(error);
+    }
+  })();
+  return {
+    stdout,
+    stderr,
+    async wait() {
+      var _a;
+      const finished = await command.wait();
+      await drained;
+      if (abortSignal == null ? void 0 : abortSignal.aborted) {
+        throw (_a = abortSignal.reason) != null ? _a : new DOMException("Aborted", "AbortError");
+      }
+      return { exitCode: finished.exitCode };
+    },
+    async kill() {
+      await command.kill();
+    }
+  };
+}
+function bytesToStream(bytes) {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    }
+  });
+}
+async function collectStream(stream) {
+  const reader = stream.getReader();
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    if (value) {
+      chunks.push(value);
+      total += value.byteLength;
+    }
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}
+function isFileNotFoundError(error) {
+  if (error == null || typeof error !== "object") return false;
+  const code = error.code;
+  if (code === "ENOENT") return true;
+  const message = error.message;
+  return typeof message === "string" && /no such file|not found|does not exist|ENOENT/i.test(message);
+}
+
+// src/just-bash-network-sandbox-session.ts
+var JUST_BASH_PROVIDER_ID = "just-bash-sandbox";
+var JustBashNetworkSandboxSession = class extends JustBashSandboxSession {
+  constructor(input) {
+    super(input.sandbox);
+    this.ports = [];
+    this.getPortUrl = async (_options) => {
+      throw new HarnessCapabilityUnsupportedError({
+        harnessId: JUST_BASH_PROVIDER_ID,
+        message: "just-bash sandboxes run in-process and cannot expose a port URL. Use a hosted sandbox (e.g. @ai-sdk/sandbox-vercel) for bridge-backed harness adapters."
+      });
+    };
+    this.stop = async () => {
+      if (!this.ownsLifecycle) return;
+    };
+    this.destroy = async () => {
+      await this.stop();
+    };
+    this.ownsLifecycle = input.ownsLifecycle;
+    this.id = randomUUID();
+    this.defaultWorkingDirectory = input.sandbox.bashEnvInstance.getCwd();
+  }
+  restricted() {
+    return new JustBashSandboxSession(this.sandbox);
+  }
+};
+
+// src/just-bash-sandbox.ts
+var JUST_BASH_PROVIDER_ID2 = "just-bash-sandbox";
+function createJustBashSandbox(settings = {}) {
+  return new JustBashSandboxProvider(settings);
+}
+var JustBashSandboxProvider = class {
+  constructor(settings) {
+    this.settings = settings;
+    this.specificationVersion = "harness-sandbox-v1";
+    this.providerId = JUST_BASH_PROVIDER_ID2;
+    this.createSession = async (options) => {
+      var _a;
+      (_a = options == null ? void 0 : options.abortSignal) == null ? void 0 : _a.throwIfAborted();
+      if ("sandbox" in this.settings && this.settings.sandbox) {
+        return new JustBashNetworkSandboxSession({
+          sandbox: this.settings.sandbox,
+          ownsLifecycle: false
+        });
+      }
+      const createParams = this.settings;
+      const sandbox = await Sandbox.create(createParams);
+      const sandboxSession = new JustBashNetworkSandboxSession({
+        sandbox,
+        ownsLifecycle: true
+      });
+      if ((options == null ? void 0 : options.onFirstCreate) != null) {
+        await options.onFirstCreate(sandboxSession.restricted(), {
+          abortSignal: options == null ? void 0 : options.abortSignal
+        });
+      }
+      return sandboxSession;
+    };
+  }
+};
+export {
+  JustBashSandboxProvider,
+  createJustBashSandbox
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/just-bash-sandbox.ts","../src/just-bash-network-sandbox-session.ts","../src/just-bash-sandbox-session.ts"],"sourcesContent":["import type {\n  HarnessV1NetworkSandboxSession,\n  HarnessV1SandboxProvider,\n} from '@ai-sdk/harness';\nimport type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';\nimport { Sandbox } from 'just-bash';\nimport { JustBashNetworkSandboxSession } from './just-bash-network-sandbox-session';\n\n/**\n * Parameters forwarded to `just-bash`'s `Sandbox.create` when creating a\n * sandbox from scratch. Aliased directly from the underlying SDK so the full\n * surface is available without us re-declaring it.\n */\ntype JustBashSandboxCreateParams = NonNullable<\n  Parameters<typeof Sandbox.create>[0]\n>;\n\n/**\n * Settings for {@link createJustBashSandbox}. Two mutually-exclusive shapes:\n *\n * - `{ sandbox }` — wrap an already-created `just-bash` `Sandbox`. The caller\n *   owns its lifecycle.\n * - {@link JustBashSandboxCreateParams} fields — provider calls\n *   `Sandbox.create(settings)` on every `createSession()`.\n *\n * just-bash has no port exposure and no snapshot mechanism, so image\n * management is a per-call no-op: if an adapter declares a bootstrap recipe\n * the provider runs it once on the freshly-created sandbox before returning.\n */\nexport type JustBashSandboxSettings =\n  | { sandbox: Sandbox }\n  | (JustBashSandboxCreateParams & { sandbox?: never });\n\nconst JUST_BASH_PROVIDER_ID = 'just-bash-sandbox';\n\nexport function createJustBashSandbox(\n  settings: JustBashSandboxSettings = {} as JustBashSandboxSettings,\n): HarnessV1SandboxProvider {\n  return new JustBashSandboxProvider(settings);\n}\n\n/**\n * `HarnessV1SandboxProvider` implementation backed by `just-bash`. Useful for\n * non-bridge harness flows and for handing a local `Experimental_SandboxSession`\n * to AI SDK tools — use `provider.createSession()` then\n * `sandboxSession.restricted()` to get the latter.\n *\n * Note: just-bash cannot expose ports, so bridge-backed harness adapters\n * (claude-code, codex) will reject this provider at start.\n */\nexport class JustBashSandboxProvider implements HarnessV1SandboxProvider {\n  readonly specificationVersion = 'harness-sandbox-v1' as const;\n  readonly providerId = JUST_BASH_PROVIDER_ID;\n\n  constructor(private readonly settings: JustBashSandboxSettings) {}\n\n  createSession = async (options?: {\n    sessionId?: string;\n    abortSignal?: AbortSignal;\n    identity?: string;\n    onFirstCreate?: (\n      session: SandboxSession,\n      opts: { abortSignal?: AbortSignal },\n    ) => Promise<void>;\n  }): Promise<HarnessV1NetworkSandboxSession> => {\n    options?.abortSignal?.throwIfAborted();\n\n    if ('sandbox' in this.settings && this.settings.sandbox) {\n      return new JustBashNetworkSandboxSession({\n        sandbox: this.settings.sandbox,\n        ownsLifecycle: false,\n      });\n    }\n\n    const createParams = this.settings as JustBashSandboxCreateParams;\n\n    const sandbox = await Sandbox.create(createParams);\n    const sandboxSession = new JustBashNetworkSandboxSession({\n      sandbox,\n      ownsLifecycle: true,\n    });\n\n    if (options?.onFirstCreate != null) {\n      await options.onFirstCreate(sandboxSession.restricted(), {\n        abortSignal: options?.abortSignal,\n      });\n    }\n\n    return sandboxSession;\n  };\n}\n","import {\n  HarnessCapabilityUnsupportedError,\n  type HarnessV1NetworkSandboxSession,\n} from '@ai-sdk/harness';\nimport type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';\nimport { randomUUID } from 'node:crypto';\nimport type { Sandbox } from 'just-bash';\nimport { JustBashSandboxSession } from './just-bash-sandbox-session';\n\nconst JUST_BASH_PROVIDER_ID = 'just-bash-sandbox';\n\n/**\n * `HarnessV1NetworkSandboxSession` backed by a `just-bash` `Sandbox`. It extends\n * {@link JustBashSandboxSession} with the infra surface. Exposes no ports —\n * there is no network namespace and no way to publish an HTTP endpoint\n * reachable from outside the host process. Bridge-backed harness adapters that\n * need `getPortUrl` will fail with `HarnessCapabilityUnsupportedError` at start.\n *\n * Network policy is not implementable locally either — `setNetworkPolicy` is\n * omitted.\n */\nexport class JustBashNetworkSandboxSession\n  extends JustBashSandboxSession\n  implements HarnessV1NetworkSandboxSession\n{\n  /**\n   * Minted at construct time. just-bash has no native identifier and no\n   * cross-process reattach surface; the value exists only to satisfy the\n   * `HarnessV1NetworkSandboxSession.id` contract.\n   */\n  readonly id: string;\n  readonly defaultWorkingDirectory: string;\n  private readonly ownsLifecycle: boolean;\n\n  constructor(input: { sandbox: Sandbox; ownsLifecycle: boolean }) {\n    super(input.sandbox);\n    this.ownsLifecycle = input.ownsLifecycle;\n    this.id = randomUUID();\n    this.defaultWorkingDirectory = input.sandbox.bashEnvInstance.getCwd();\n  }\n\n  readonly ports: ReadonlyArray<number> = [];\n\n  restricted(): SandboxSession {\n    return new JustBashSandboxSession(this.sandbox);\n  }\n\n  getPortUrl = async (_options: {\n    port: number;\n    protocol?: 'http' | 'https' | 'ws';\n  }): Promise<string> => {\n    throw new HarnessCapabilityUnsupportedError({\n      harnessId: JUST_BASH_PROVIDER_ID,\n      message:\n        'just-bash sandboxes run in-process and cannot expose a port URL. ' +\n        'Use a hosted sandbox (e.g. @ai-sdk/sandbox-vercel) for bridge-backed harness adapters.',\n    });\n  };\n\n  stop = async (): Promise<void> => {\n    if (!this.ownsLifecycle) return;\n    // just-bash has no explicit shutdown; the sandbox is garbage-collected\n    // along with its in-memory filesystem once references drop.\n  };\n\n  destroy = async (): Promise<void> => {\n    await this.stop();\n  };\n}\n","import { isAbsolute, posix } from 'node:path';\nimport {\n  extractLines,\n  type Experimental_SandboxSession,\n  type Experimental_SandboxProcess,\n} from '@ai-sdk/provider-utils';\nimport type { Sandbox, SandboxCommand } from 'just-bash';\n\n/**\n * `Experimental_SandboxSession` implementation backed by a `just-bash`\n * `Sandbox`. File operations and spawned processes share the same in-memory\n * filesystem, so a bridge process spawned via `spawn` can read files the host\n * wrote via `writeTextFile` (and vice versa).\n *\n * This is the tool-safe surface returned by\n * `JustBashNetworkSandboxSession.restricted()` — not constructed directly by\n * consumers.\n */\nexport class JustBashSandboxSession implements Experimental_SandboxSession {\n  constructor(protected readonly sandbox: Sandbox) {}\n\n  get description(): string {\n    return [\n      'just-bash JavaScript bash environment with a virtual filesystem.',\n      'Filesystem changes and spawned processes share the same in-memory state.',\n      `Current working directory: ${this.sandbox.bashEnvInstance.getCwd()}`,\n    ].join('\\n');\n  }\n\n  private resolvePath(path: string): string {\n    return isAbsolute(path)\n      ? path\n      : posix.join(this.sandbox.bashEnvInstance.getCwd(), path);\n  }\n\n  async run({\n    command,\n    workingDirectory,\n    env,\n    abortSignal,\n  }: {\n    command: string;\n    workingDirectory?: string;\n    env?: Record<string, string>;\n    abortSignal?: AbortSignal;\n  }): Promise<{ exitCode: number; stdout: string; stderr: string }> {\n    abortSignal?.throwIfAborted();\n\n    const finished = await this.sandbox.runCommand({\n      cmd: 'bash',\n      args: ['-c', command],\n      ...(workingDirectory !== undefined ? { cwd: workingDirectory } : {}),\n      ...(env !== undefined ? { env } : {}),\n      ...(abortSignal !== undefined ? { signal: abortSignal } : {}),\n    });\n\n    const [stdout, stderr] = await Promise.all([\n      finished.stdout(),\n      finished.stderr(),\n    ]);\n\n    return {\n      exitCode: finished.exitCode,\n      stdout,\n      stderr,\n    };\n  }\n\n  async spawn({\n    command,\n    workingDirectory,\n    env,\n    abortSignal,\n  }: {\n    command: string;\n    workingDirectory?: string;\n    env?: Record<string, string>;\n    abortSignal?: AbortSignal;\n  }): Promise<Experimental_SandboxProcess> {\n    abortSignal?.throwIfAborted();\n\n    const live = await this.sandbox.runCommand({\n      cmd: 'bash',\n      args: ['-c', command],\n      detached: true,\n      ...(workingDirectory !== undefined ? { cwd: workingDirectory } : {}),\n      ...(env !== undefined ? { env } : {}),\n      ...(abortSignal !== undefined ? { signal: abortSignal } : {}),\n    });\n\n    return createSandboxProcess(live, abortSignal);\n  }\n\n  async readFile({\n    path,\n    abortSignal,\n  }: {\n    path: string;\n    abortSignal?: AbortSignal;\n  }): Promise<ReadableStream<Uint8Array> | null> {\n    const bytes = await this.readBinaryFile({ path, abortSignal });\n    if (bytes == null) return null;\n    return bytesToStream(bytes);\n  }\n\n  async readBinaryFile({\n    path,\n    abortSignal,\n  }: {\n    path: string;\n    abortSignal?: AbortSignal;\n  }): Promise<Uint8Array | null> {\n    abortSignal?.throwIfAborted();\n    const resolved = this.resolvePath(path);\n    try {\n      const bytes =\n        await this.sandbox.bashEnvInstance.fs.readFileBuffer(resolved);\n      return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);\n    } catch (error) {\n      if (isFileNotFoundError(error)) return null;\n      throw error;\n    }\n  }\n\n  async readTextFile({\n    path,\n    encoding = 'utf-8',\n    startLine,\n    endLine,\n    abortSignal,\n  }: {\n    path: string;\n    encoding?: string;\n    startLine?: number;\n    endLine?: number;\n    abortSignal?: AbortSignal;\n  }): Promise<string | null> {\n    const bytes = await this.readBinaryFile({ path, abortSignal });\n    if (bytes == null) return null;\n    const text = Buffer.from(bytes).toString(encoding as BufferEncoding);\n    return extractLines({ text, startLine, endLine });\n  }\n\n  async writeFile({\n    path,\n    content,\n    abortSignal,\n  }: {\n    path: string;\n    content: ReadableStream<Uint8Array>;\n    abortSignal?: AbortSignal;\n  }): Promise<void> {\n    const bytes = await collectStream(content);\n    await this.writeBinaryFile({ path, content: bytes, abortSignal });\n  }\n\n  async writeBinaryFile({\n    path,\n    content,\n    abortSignal,\n  }: {\n    path: string;\n    content: Uint8Array;\n    abortSignal?: AbortSignal;\n  }): Promise<void> {\n    abortSignal?.throwIfAborted();\n    const resolved = this.resolvePath(path);\n    await this.sandbox.bashEnvInstance.fs.writeFile(resolved, content);\n  }\n\n  async writeTextFile({\n    path,\n    content,\n    encoding = 'utf-8',\n    abortSignal,\n  }: {\n    path: string;\n    content: string;\n    encoding?: string;\n    abortSignal?: AbortSignal;\n  }): Promise<void> {\n    const buffer = Buffer.from(content, encoding as BufferEncoding);\n    await this.writeBinaryFile({\n      path,\n      content: new Uint8Array(\n        buffer.buffer,\n        buffer.byteOffset,\n        buffer.byteLength,\n      ),\n      abortSignal,\n    });\n  }\n}\n\nfunction createSandboxProcess(\n  command: SandboxCommand,\n  abortSignal: AbortSignal | undefined,\n): Experimental_SandboxProcess {\n  const encoder = new TextEncoder();\n  const controllers: {\n    stdout?: ReadableStreamDefaultController<Uint8Array>;\n    stderr?: ReadableStreamDefaultController<Uint8Array>;\n  } = {};\n\n  const stdout = new ReadableStream<Uint8Array>({\n    start(controller) {\n      controllers.stdout = controller;\n    },\n  });\n\n  const stderr = new ReadableStream<Uint8Array>({\n    start(controller) {\n      controllers.stderr = controller;\n    },\n  });\n\n  const drained = (async () => {\n    try {\n      for await (const message of command.logs()) {\n        const target =\n          message.type === 'stdout' ? controllers.stdout : controllers.stderr;\n        target?.enqueue(encoder.encode(message.data));\n      }\n      controllers.stdout?.close();\n      controllers.stderr?.close();\n    } catch (error) {\n      controllers.stdout?.error(error);\n      controllers.stderr?.error(error);\n    }\n  })();\n\n  return {\n    stdout,\n    stderr,\n    async wait(): Promise<{ exitCode: number }> {\n      const finished = await command.wait();\n      await drained;\n      if (abortSignal?.aborted) {\n        throw abortSignal.reason ?? new DOMException('Aborted', 'AbortError');\n      }\n      return { exitCode: finished.exitCode };\n    },\n    async kill(): Promise<void> {\n      await command.kill();\n    },\n  };\n}\n\nfunction bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {\n  return new ReadableStream<Uint8Array>({\n    start(controller) {\n      controller.enqueue(bytes);\n      controller.close();\n    },\n  });\n}\n\nasync function collectStream(\n  stream: ReadableStream<Uint8Array>,\n): Promise<Uint8Array> {\n  const reader = stream.getReader();\n  const chunks: Uint8Array[] = [];\n  let total = 0;\n  while (true) {\n    const { value, done } = await reader.read();\n    if (done) break;\n    if (value) {\n      chunks.push(value);\n      total += value.byteLength;\n    }\n  }\n  const out = new Uint8Array(total);\n  let offset = 0;\n  for (const chunk of chunks) {\n    out.set(chunk, offset);\n    offset += chunk.byteLength;\n  }\n  return out;\n}\n\nfunction isFileNotFoundError(error: unknown): boolean {\n  if (error == null || typeof error !== 'object') return false;\n  const code = (error as { code?: unknown }).code;\n  if (code === 'ENOENT') return true;\n  const message = (error as { message?: unknown }).message;\n  return (\n    typeof message === 'string' &&\n    /no such file|not found|does not exist|ENOENT/i.test(message)\n  );\n}\n"],"mappings":"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","names":["JUST_BASH_PROVIDER_ID"]}

package/package.json

@@ -1 +1,69 @@
-{"name":"@ai-sdk/sandbox-just-bash","version":"0.0.0"}
+{
+  "name": "@ai-sdk/sandbox-just-bash",
+  "version": "1.0.0-beta.15",
+  "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",
+    "README.md"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "just-bash": "^2.14.5",
+    "@ai-sdk/harness": "1.0.0-beta.15",
+    "@ai-sdk/provider-utils": "5.0.0-beta.49"
+  },
+  "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/sandbox-just-bash"
+  },
+  "bugs": {
+    "url": "https://github.com/vercel/ai/issues"
+  },
+  "keywords": [
+    "ai",
+    "sandbox",
+    "just-bash"
+  ],
+  "scripts": {
+    "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
+    "build:watch": "pnpm clean && tsup --watch",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "type-check": "tsc --build",
+    "test": "pnpm test:node",
+    "test:watch": "vitest --config vitest.node.config.js",
+    "test:node": "vitest --config vitest.node.config.js --run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export {
+  createJustBashSandbox,
+  JustBashSandboxProvider,
+  type JustBashSandboxSettings,
+} from './just-bash-sandbox';

package/src/just-bash-network-sandbox-session.ts

@@ -0,0 +1,69 @@
+import {
+  HarnessCapabilityUnsupportedError,
+  type HarnessV1NetworkSandboxSession,
+} from '@ai-sdk/harness';
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import { randomUUID } from 'node:crypto';
+import type { Sandbox } from 'just-bash';
+import { JustBashSandboxSession } from './just-bash-sandbox-session';
+
+const JUST_BASH_PROVIDER_ID = 'just-bash-sandbox';
+
+/**
+ * `HarnessV1NetworkSandboxSession` backed by a `just-bash` `Sandbox`. It extends
+ * {@link JustBashSandboxSession} with the infra surface. Exposes no ports —
+ * there is no network namespace and no way to publish an HTTP endpoint
+ * reachable from outside the host process. Bridge-backed harness adapters that
+ * need `getPortUrl` will fail with `HarnessCapabilityUnsupportedError` at start.
+ *
+ * Network policy is not implementable locally either — `setNetworkPolicy` is
+ * omitted.
+ */
+export class JustBashNetworkSandboxSession
+  extends JustBashSandboxSession
+  implements HarnessV1NetworkSandboxSession
+{
+  /**
+   * Minted at construct time. just-bash has no native identifier and no
+   * cross-process reattach surface; the value exists only to satisfy the
+   * `HarnessV1NetworkSandboxSession.id` contract.
+   */
+  readonly id: string;
+  readonly defaultWorkingDirectory: string;
+  private readonly ownsLifecycle: boolean;
+
+  constructor(input: { sandbox: Sandbox; ownsLifecycle: boolean }) {
+    super(input.sandbox);
+    this.ownsLifecycle = input.ownsLifecycle;
+    this.id = randomUUID();
+    this.defaultWorkingDirectory = input.sandbox.bashEnvInstance.getCwd();
+  }
+
+  readonly ports: ReadonlyArray<number> = [];
+
+  restricted(): SandboxSession {
+    return new JustBashSandboxSession(this.sandbox);
+  }
+
+  getPortUrl = async (_options: {
+    port: number;
+    protocol?: 'http' | 'https' | 'ws';
+  }): Promise<string> => {
+    throw new HarnessCapabilityUnsupportedError({
+      harnessId: JUST_BASH_PROVIDER_ID,
+      message:
+        'just-bash sandboxes run in-process and cannot expose a port URL. ' +
+        'Use a hosted sandbox (e.g. @ai-sdk/sandbox-vercel) for bridge-backed harness adapters.',
+    });
+  };
+
+  stop = async (): Promise<void> => {
+    if (!this.ownsLifecycle) return;
+    // just-bash has no explicit shutdown; the sandbox is garbage-collected
+    // along with its in-memory filesystem once references drop.
+  };
+
+  destroy = async (): Promise<void> => {
+    await this.stop();
+  };
+}

package/src/just-bash-sandbox-session.ts

@@ -0,0 +1,290 @@
+import { isAbsolute, posix } from 'node:path';
+import {
+  extractLines,
+  type Experimental_SandboxSession,
+  type Experimental_SandboxProcess,
+} from '@ai-sdk/provider-utils';
+import type { Sandbox, SandboxCommand } from 'just-bash';
+
+/**
+ * `Experimental_SandboxSession` implementation backed by a `just-bash`
+ * `Sandbox`. File operations and spawned processes share the same in-memory
+ * filesystem, so a bridge process spawned via `spawn` can read files the host
+ * wrote via `writeTextFile` (and vice versa).
+ *
+ * This is the tool-safe surface returned by
+ * `JustBashNetworkSandboxSession.restricted()` — not constructed directly by
+ * consumers.
+ */
+export class JustBashSandboxSession implements Experimental_SandboxSession {
+  constructor(protected readonly sandbox: Sandbox) {}
+
+  get description(): string {
+    return [
+      'just-bash JavaScript bash environment with a virtual filesystem.',
+      'Filesystem changes and spawned processes share the same in-memory state.',
+      `Current working directory: ${this.sandbox.bashEnvInstance.getCwd()}`,
+    ].join('\n');
+  }
+
+  private resolvePath(path: string): string {
+    return isAbsolute(path)
+      ? path
+      : posix.join(this.sandbox.bashEnvInstance.getCwd(), path);
+  }
+
+  async run({
+    command,
+    workingDirectory,
+    env,
+    abortSignal,
+  }: {
+    command: string;
+    workingDirectory?: string;
+    env?: Record<string, string>;
+    abortSignal?: AbortSignal;
+  }): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+    abortSignal?.throwIfAborted();
+
+    const finished = await this.sandbox.runCommand({
+      cmd: 'bash',
+      args: ['-c', command],
+      ...(workingDirectory !== undefined ? { cwd: workingDirectory } : {}),
+      ...(env !== undefined ? { env } : {}),
+      ...(abortSignal !== undefined ? { signal: abortSignal } : {}),
+    });
+
+    const [stdout, stderr] = await Promise.all([
+      finished.stdout(),
+      finished.stderr(),
+    ]);
+
+    return {
+      exitCode: finished.exitCode,
+      stdout,
+      stderr,
+    };
+  }
+
+  async spawn({
+    command,
+    workingDirectory,
+    env,
+    abortSignal,
+  }: {
+    command: string;
+    workingDirectory?: string;
+    env?: Record<string, string>;
+    abortSignal?: AbortSignal;
+  }): Promise<Experimental_SandboxProcess> {
+    abortSignal?.throwIfAborted();
+
+    const live = await this.sandbox.runCommand({
+      cmd: 'bash',
+      args: ['-c', command],
+      detached: true,
+      ...(workingDirectory !== undefined ? { cwd: workingDirectory } : {}),
+      ...(env !== undefined ? { env } : {}),
+      ...(abortSignal !== undefined ? { signal: abortSignal } : {}),
+    });
+
+    return createSandboxProcess(live, abortSignal);
+  }
+
+  async readFile({
+    path,
+    abortSignal,
+  }: {
+    path: string;
+    abortSignal?: AbortSignal;
+  }): Promise<ReadableStream<Uint8Array> | null> {
+    const bytes = await this.readBinaryFile({ path, abortSignal });
+    if (bytes == null) return null;
+    return bytesToStream(bytes);
+  }
+
+  async readBinaryFile({
+    path,
+    abortSignal,
+  }: {
+    path: string;
+    abortSignal?: AbortSignal;
+  }): Promise<Uint8Array | null> {
+    abortSignal?.throwIfAborted();
+    const resolved = this.resolvePath(path);
+    try {
+      const bytes =
+        await this.sandbox.bashEnvInstance.fs.readFileBuffer(resolved);
+      return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    } catch (error) {
+      if (isFileNotFoundError(error)) return null;
+      throw error;
+    }
+  }
+
+  async readTextFile({
+    path,
+    encoding = 'utf-8',
+    startLine,
+    endLine,
+    abortSignal,
+  }: {
+    path: string;
+    encoding?: string;
+    startLine?: number;
+    endLine?: number;
+    abortSignal?: AbortSignal;
+  }): Promise<string | null> {
+    const bytes = await this.readBinaryFile({ path, abortSignal });
+    if (bytes == null) return null;
+    const text = Buffer.from(bytes).toString(encoding as BufferEncoding);
+    return extractLines({ text, startLine, endLine });
+  }
+
+  async writeFile({
+    path,
+    content,
+    abortSignal,
+  }: {
+    path: string;
+    content: ReadableStream<Uint8Array>;
+    abortSignal?: AbortSignal;
+  }): Promise<void> {
+    const bytes = await collectStream(content);
+    await this.writeBinaryFile({ path, content: bytes, abortSignal });
+  }
+
+  async writeBinaryFile({
+    path,
+    content,
+    abortSignal,
+  }: {
+    path: string;
+    content: Uint8Array;
+    abortSignal?: AbortSignal;
+  }): Promise<void> {
+    abortSignal?.throwIfAborted();
+    const resolved = this.resolvePath(path);
+    await this.sandbox.bashEnvInstance.fs.writeFile(resolved, content);
+  }
+
+  async writeTextFile({
+    path,
+    content,
+    encoding = 'utf-8',
+    abortSignal,
+  }: {
+    path: string;
+    content: string;
+    encoding?: string;
+    abortSignal?: AbortSignal;
+  }): Promise<void> {
+    const buffer = Buffer.from(content, encoding as BufferEncoding);
+    await this.writeBinaryFile({
+      path,
+      content: new Uint8Array(
+        buffer.buffer,
+        buffer.byteOffset,
+        buffer.byteLength,
+      ),
+      abortSignal,
+    });
+  }
+}
+
+function createSandboxProcess(
+  command: SandboxCommand,
+  abortSignal: AbortSignal | undefined,
+): Experimental_SandboxProcess {
+  const encoder = new TextEncoder();
+  const controllers: {
+    stdout?: ReadableStreamDefaultController<Uint8Array>;
+    stderr?: ReadableStreamDefaultController<Uint8Array>;
+  } = {};
+
+  const stdout = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controllers.stdout = controller;
+    },
+  });
+
+  const stderr = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controllers.stderr = controller;
+    },
+  });
+
+  const drained = (async () => {
+    try {
+      for await (const message of command.logs()) {
+        const target =
+          message.type === 'stdout' ? controllers.stdout : controllers.stderr;
+        target?.enqueue(encoder.encode(message.data));
+      }
+      controllers.stdout?.close();
+      controllers.stderr?.close();
+    } catch (error) {
+      controllers.stdout?.error(error);
+      controllers.stderr?.error(error);
+    }
+  })();
+
+  return {
+    stdout,
+    stderr,
+    async wait(): Promise<{ exitCode: number }> {
+      const finished = await command.wait();
+      await drained;
+      if (abortSignal?.aborted) {
+        throw abortSignal.reason ?? new DOMException('Aborted', 'AbortError');
+      }
+      return { exitCode: finished.exitCode };
+    },
+    async kill(): Promise<void> {
+      await command.kill();
+    },
+  };
+}
+
+function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+async function collectStream(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    if (value) {
+      chunks.push(value);
+      total += value.byteLength;
+    }
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return out;
+}
+
+function isFileNotFoundError(error: unknown): boolean {
+  if (error == null || typeof error !== 'object') return false;
+  const code = (error as { code?: unknown }).code;
+  if (code === 'ENOENT') return true;
+  const message = (error as { message?: unknown }).message;
+  return (
+    typeof message === 'string' &&
+    /no such file|not found|does not exist|ENOENT/i.test(message)
+  );
+}

package/src/just-bash-sandbox.ts

@@ -0,0 +1,91 @@
+import type {
+  HarnessV1NetworkSandboxSession,
+  HarnessV1SandboxProvider,
+} from '@ai-sdk/harness';
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import { Sandbox } from 'just-bash';
+import { JustBashNetworkSandboxSession } from './just-bash-network-sandbox-session';
+
+/**
+ * Parameters forwarded to `just-bash`'s `Sandbox.create` when creating a
+ * sandbox from scratch. Aliased directly from the underlying SDK so the full
+ * surface is available without us re-declaring it.
+ */
+type JustBashSandboxCreateParams = NonNullable<
+  Parameters<typeof Sandbox.create>[0]
+>;
+
+/**
+ * Settings for {@link createJustBashSandbox}. Two mutually-exclusive shapes:
+ *
+ * - `{ sandbox }` — wrap an already-created `just-bash` `Sandbox`. The caller
+ *   owns its lifecycle.
+ * - {@link JustBashSandboxCreateParams} fields — provider calls
+ *   `Sandbox.create(settings)` on every `createSession()`.
+ *
+ * just-bash has no port exposure and no snapshot mechanism, so image
+ * management is a per-call no-op: if an adapter declares a bootstrap recipe
+ * the provider runs it once on the freshly-created sandbox before returning.
+ */
+export type JustBashSandboxSettings =
+  | { sandbox: Sandbox }
+  | (JustBashSandboxCreateParams & { sandbox?: never });
+
+const JUST_BASH_PROVIDER_ID = 'just-bash-sandbox';
+
+export function createJustBashSandbox(
+  settings: JustBashSandboxSettings = {} as JustBashSandboxSettings,
+): HarnessV1SandboxProvider {
+  return new JustBashSandboxProvider(settings);
+}
+
+/**
+ * `HarnessV1SandboxProvider` implementation backed by `just-bash`. Useful for
+ * non-bridge harness flows and for handing a local `Experimental_SandboxSession`
+ * to AI SDK tools — use `provider.createSession()` then
+ * `sandboxSession.restricted()` to get the latter.
+ *
+ * Note: just-bash cannot expose ports, so bridge-backed harness adapters
+ * (claude-code, codex) will reject this provider at start.
+ */
+export class JustBashSandboxProvider implements HarnessV1SandboxProvider {
+  readonly specificationVersion = 'harness-sandbox-v1' as const;
+  readonly providerId = JUST_BASH_PROVIDER_ID;
+
+  constructor(private readonly settings: JustBashSandboxSettings) {}
+
+  createSession = async (options?: {
+    sessionId?: string;
+    abortSignal?: AbortSignal;
+    identity?: string;
+    onFirstCreate?: (
+      session: SandboxSession,
+      opts: { abortSignal?: AbortSignal },
+    ) => Promise<void>;
+  }): Promise<HarnessV1NetworkSandboxSession> => {
+    options?.abortSignal?.throwIfAborted();
+
+    if ('sandbox' in this.settings && this.settings.sandbox) {
+      return new JustBashNetworkSandboxSession({
+        sandbox: this.settings.sandbox,
+        ownsLifecycle: false,
+      });
+    }
+
+    const createParams = this.settings as JustBashSandboxCreateParams;
+
+    const sandbox = await Sandbox.create(createParams);
+    const sandboxSession = new JustBashNetworkSandboxSession({
+      sandbox,
+      ownsLifecycle: true,
+    });
+
+    if (options?.onFirstCreate != null) {
+      await options.onFirstCreate(sandboxSession.restricted(), {
+        abortSignal: options?.abortSignal,
+      });
+    }
+
+    return sandboxSession;
+  };
+}