ai-sdk-sandbox-sbx 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# ai-sdk-sandbox-sbx
+
+## 1.0.0
+
+### Major Changes
+
+- 1f6ebc7: First stable release: run AI SDK harness agents (Claude Code, Codex…) in a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/) microVM through the `sbx` CLI. `createSbxNetworkSandboxSession()` creates a sandbox, optionally from a template image baked once by `agent.getSandboxTemplate()`, and `resumeSbxNetworkSandboxSession()` reattaches to it. Ports are published on demand, on the host loopback only, and credentials stay outside the sandbox: the Docker Sandboxes proxy puts them in the requests on the way out.
+  
+  Docker Sandboxes Cloud is supported with `cloud: true`, as an experimental feature that may change in a minor release while it settles.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabien Pasquet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# ai-sdk-sandbox-sbx
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ai-sdk-sandbox-sbx"><img alt="npm" src="https://img.shields.io/npm/v/ai-sdk-sandbox-sbx" /></a>
+  <a href="https://github.com/fpasquet/ai-sdk-harness/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/fpasquet/ai-sdk-harness/actions/workflows/ci.yml/badge.svg" /></a>
+  <img alt="Node &gt;= 24" src="https://img.shields.io/badge/node-%3E%3D24-3c873a" />
+  <img alt="TypeScript strict" src="https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white" />
+  <a href="https://github.com/fpasquet/ai-sdk-harness/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg" /></a>
+</p>
+
+Run [AI SDK harness agents](https://ai-sdk.dev/docs/ai-sdk-harnesses/harness-agent) (Claude Code, Codex, OpenCode…) in a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/): a microVM on your machine, or in Docker Sandboxes Cloud, driven through the `sbx` CLI.
+
+The package gives `HarnessAgent.createSession({ sandboxSession })` what it expects, a `HarnessV1NetworkSandboxSession`, the same way [`@ai-sdk/sandbox-vercel`](https://www.npmjs.com/package/@ai-sdk/sandbox-vercel) does for Vercel Sandbox:
+
+- **Isolation**: every command and file operation is an `sbx exec` into the microVM. Nothing runs on the host, and nothing of the host is mounted unless you ask for it.
+- **Credentials stay on the host**: the harness hands the sandbox a placeholder; the Docker Sandboxes proxy swaps the real value in on the way out.
+- **The harness is installed once**: pass `agent.getSandboxTemplate()` and the first sandbox is saved as a template image; every later one starts from it in seconds.
+- **Local or cloud**: the same API runs the sandbox on your machine, its ports on the loopback only, or in [Docker Sandboxes Cloud](#docker-sandboxes-cloud) with `cloud: true`.
+
+![Claude Code running in a Docker Sandbox, in the Next.js example of the repository](https://raw.githubusercontent.com/fpasquet/ai-sdk-harness/main/docs/public/screenshots/next-chat/conversation.png)
+
+> This package follows [Semantic Versioning](https://semver.org). The AI SDK harnesses it plugs into are themselves experimental, and its [cloud mode](#docker-sandboxes-cloud) is too. It is a community package, not affiliated with Vercel or Docker.
+
+## Requirements
+
+- Node.js 24 or later.
+- [Docker Sandboxes](https://docs.docker.com/ai/sandboxes/get-started/) installed, with `sbx` on the `PATH` (or pointed at by the `binary` option), and signed in (`sbx login`).
+- `@ai-sdk/harness` and a harness adapter, such as `@ai-sdk/harness-claude-code`.
+
+## Installation
+
+```bash
+pnpm add ai-sdk-sandbox-sbx @ai-sdk/harness @ai-sdk/harness-claude-code
+```
+
+## Usage
+
+```ts title="agent.ts"
+import { HarnessAgent } from '@ai-sdk/harness/agent';
+import { createClaudeCode } from '@ai-sdk/harness-claude-code';
+import { createSbxNetworkSandboxSession } from 'ai-sdk-sandbox-sbx';
+
+// Authenticated from CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY.
+const agent = new HarnessAgent({ id: 'coder', harness: createClaudeCode() });
+
+const sandboxSession = await createSbxNetworkSandboxSession({
+  // The Claude Code bridge listens on the first port; the harness reaches it on the loopback.
+  ports: [4000],
+  // The bridge installs its dependencies with pnpm, which the `shell` kit does not ship.
+  setup: ['npm install --global --silent pnpm@10'],
+  // Bakes Claude Code into a local image the first time, reused afterwards.
+  template: await agent.getSandboxTemplate(),
+});
+const session = await agent.createSession({ sandboxSession });
+
+try {
+  const result = await agent.generate({
+    session,
+    prompt: 'Write a script that prints the first ten primes, then run it.',
+  });
+  console.log(result.text);
+} finally {
+  await session.destroy();
+  await sandboxSession.destroy();
+}
+```
+
+The caller owns the sandbox: ending the harness session leaves it running. `stop()` stops its microVM and keeps its files; `destroy()` removes it.
+
+`agent.stream()` works the same way, and its result's `toUIMessageStreamResponse()` feeds `useChat` straight away. The [Next.js example](https://github.com/fpasquet/ai-sdk-harness/tree/main/examples/next-chat) is a complete chat on top of it.
+
+## Templates
+
+A harness bootstraps itself in the sandbox before its first turn: Claude Code installs `@anthropic-ai/claude-agent-sdk` and the `claude` CLI, which takes a minute or two. Pass the agent's template and it happens once:
+
+```ts
+const sandboxSession = await createSbxNetworkSandboxSession({
+  ports: [4000],
+  setup: ['npm install --global --silent pnpm@10'],
+  template: await agent.getSandboxTemplate(),
+});
+```
+
+The first call creates a throwaway sandbox, runs `setup` in it, lets the harness prepare it, saves it with `sbx template save` and removes it. The image is named `ai-sdk-harness-template:<digest>`, the digest covering the harness recipe, the agent kit, the `image` and the `setup` commands, so a new harness version gets an image of its own. Every later sandbox starts from it with `sbx create --template … --pull never`.
+
+The images stay in the sandbox runtime's store: list them with `sbx template ls`, remove an outdated one with `sbx template rm`.
+
+## Resuming a sandbox
+
+Creation never resumes: a sandbox already named `sandboxId` is a conflict. Name the sandbox, keep its id, and reattach to it, from the same process or another one:
+
+```ts
+import {
+  createSbxNetworkSandboxSession,
+  resumeSbxNetworkSandboxSession,
+  SbxSandboxNotFoundError,
+} from 'ai-sdk-sandbox-sbx';
+
+async function openSandbox() {
+  try {
+    const sandbox = await resumeSbxNetworkSandboxSession({ sandboxId: 'my-agent', ports: [4000] });
+    // A previous run may have left a bridge behind, holding the port.
+    await sandbox.killAllProcesses();
+    return sandbox;
+  } catch (error) {
+    if (!(error instanceof SbxSandboxNotFoundError)) throw error;
+    return createSbxNetworkSandboxSession({ sandboxId: 'my-agent', ports: [4000] });
+  }
+}
+```
+
+A stopped sandbox starts again on the first command. `sbx` does not remember which ports a harness uses until they are published, so pass the same `ports` again.
+
+## Working on your files
+
+By default the sandbox mounts nothing of the host: the agent works on the microVM's own filesystem. Mount a directory to let it work on yours:
+
+```ts
+// Read-write: the agent edits the directory itself.
+await createSbxNetworkSandboxSession({ workspace: '/path/to/project', ports: [4000] });
+
+// A private clone of a Git repository instead: the host repository is mounted read-only, and
+// the agent's commits come back through the `sandbox-<name>` git remote on the host.
+await createSbxNetworkSandboxSession({ workspace: '/path/to/repo', clone: true, ports: [4000] });
+
+// More directories, read-only.
+await createSbxNetworkSandboxSession({ readOnlyWorkspaces: ['/path/to/docs'], ports: [4000] });
+```
+
+The sandbox's working directory (`defaultWorkingDirectory`, under which the harness creates each session's own directory) is read from the live sandbox: the workspace when one is mounted, `/home/agent/workspace` otherwise.
+
+## Docker Sandboxes Cloud
+
+With `cloud: true`, the sandbox runs in Docker Sandboxes Cloud rather than on your machine: every `sbx` command goes out as `sbx --cloud …`. It needs a [Docker Agentic Platform](https://agentic-platform.docker.com) subscription and `sbx login` (personal access tokens carry no cloud access).
+
+```ts
+const sandboxSession = await createSbxNetworkSandboxSession({
+  cloud: true,
+  ports: [4000],
+  setup: ['npm install --global --silent pnpm@10'],
+  template: await agent.getSandboxTemplate(),
+  ttl: '2h',
+  onTimeout: 'stop',
+});
+```
+
+What changes from a local sandbox:
+
+- **Nothing of your machine is mounted**: `workspace`, `clone` and `readOnlyWorkspaces` are refused. Copy what the agent needs in with `writeFile()`, or clone it from inside the sandbox.
+- **Ports get a public URL** assigned by the control plane, instead of a loopback port. The harness bridges authenticate their connections with a token of their own.
+- **Credentials are set by the proxy**: the cloud proxy puts the whole header on the requests to the host, under a secret named after the sandbox, the host and the header. Cloud secrets belong to the account, so `destroy()` removes them too.
+- **Templates live in the cloud registry**, named `ai-sdk-harness-template-<digest>`. Saving one snapshots the running sandbox and takes several minutes; list them with `sbx --cloud template ls`.
+- **A cloud sandbox has a time-to-live**, 24 hours at most: set it with `ttl` and `onTimeout`, extend it with `extendTtl('1h')`. `stop()` suspends it with its memory.
+- **Sizing** comes in billable shapes: `cpus` and `memory` together, 2 / `4g` by default. `allowNetwork` and `platform` are cloud-only settings.
+
+**Cloud support is experimental**: it follows the `sbx --cloud` command reference, and may change in a minor release while it settles. Its e2e suite runs with `SBX_E2E_CLOUD=1 pnpm test:e2e`.
+
+## Credentials
+
+A harness that supports credential brokering never puts the real credential in the sandbox. It hands the sandbox a random placeholder and asks the sandbox session to transform the requests on their way out. This package turns each transformation into an `sbx secret set-custom` scoped to the sandbox, so the Docker Sandboxes proxy replaces the placeholder with the real value (a cloud proxy sets the whole header instead), which only exists on the host and in the proxy. The placeholders are withdrawn by `release()` and `stop()`, and removed with the sandbox by `destroy()`.
+
+Turn it off with `brokerCredentials: false` for an `sbx` without custom secrets: the harness then forwards the real credential into the sandbox environment.
+
+Docker Sandboxes also pre-sets its own credential variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GH_TOKEN`…) to a `proxy-managed` placeholder, for credentials stored with `sbx secret set`. Left in place, one can take precedence over the credential the harness passes (the `claude` CLI prefers `ANTHROPIC_API_KEY` to `CLAUDE_CODE_OAUTH_TOKEN`), so they are dropped from every command that does not set them itself. Keep them with `keepProxyManagedEnv: true`; drop more with `clearEnv`.
+
+Variables a command does set are forwarded as bare `sbx exec -e NAME`: `sbx` reads the value from its own environment, so it never appears on a command line.
+
+## Network
+
+Outbound traffic goes through the Docker Sandboxes proxy and its policy (`sbx policy`). `denyNetwork` adds deny rules for the new sandbox only. A local deny can only narrow egress, so it holds whatever the global policy allows:
+
+```ts
+await createSbxNetworkSandboxSession({
+  denyNetwork: ['github.com', '*.github.com'],
+  ports: [4000],
+});
+```
+
+`setNetworkPolicy` is not implemented: the harness treats it as optional, and `sbx policy` remains the place to manage what the sandbox may reach.
+
+## Ports
+
+`ports` lists the ports inside the sandbox the harness may reach. Each one is published the first time `getPortEndpoint()` asks for it, on this host's loopback (`127.0.0.1:<free port>`) or, for a cloud sandbox, at the public `https://` URL the control plane assigns, and unpublished by `release()`, `stop()` or `setPorts()`. A port outside the list is refused with `HarnessCapabilityUnsupportedError`.
+
+## Lifecycle
+
+| Method                | What it does                                                                                      |
+| --------------------- | ------------------------------------------------------------------------------------------------- |
+| `release()`           | Stops the processes this session started, unpublishes its ports, withdraws its placeholders       |
+| `killAllProcesses()`  | Stops every process any session started in the sandbox, including what a previous run left behind |
+| `stop()`              | `release()`, then stops the microVM. Its files stay; the next command starts it again             |
+| `extendTtl(duration)` | Extends the time-to-live of a cloud sandbox (`'1h'`), within its 24 hours                         |
+| `destroy()`           | Removes the sandbox, its files and its secrets                                                    |
+| `restricted()`        | The files-and-processes view of the same sandbox, to hand to tools (see below)                    |
+
+`restricted()` returns an `Experimental_SandboxSession`: it can run commands and read and write files, but cannot stop the sandbox, publish ports or touch credentials. Pass it to AI SDK tools that accept `experimental_sandbox`.
+
+## Options
+
+`createSbxNetworkSandboxSession(options)` takes every option below; `resumeSbxNetworkSandboxSession(options)` takes `sandboxId`, `abortSignal`, `cloud` and the connection settings.
+
+| Option                | Default        | Description                                                                                     |
+| --------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
+| `sandboxId`           | `ai-sdk-<hex>` | The sandbox's name in `sbx ls`. Creation fails if it is taken                                   |
+| `template`            | none           | `await agent.getSandboxTemplate()`: prepare once, start every later sandbox from the image      |
+| `abortSignal`         | none           | Aborts the creation or the resume                                                               |
+| `agent`               | `'shell'`      | The Docker Sandboxes agent kit: its image and network rules                                     |
+| `image`               | the kit's own  | Container image to use instead (`sbx create --template`)                                        |
+| `cloud`               | `false`        | Run in Docker Sandboxes Cloud (`sbx --cloud`) rather than on this host                          |
+| `workspace`           | none           | Host directory to mount read-write as the working directory (local only)                        |
+| `clone`               | `false`        | With `workspace`: a private clone of the Git repository instead (local only)                    |
+| `readOnlyWorkspaces`  | `[]`           | More host directories, mounted read-only (local only)                                           |
+| `denyNetwork`         | `[]`           | Hosts the sandbox may never reach (`sbx create --deny-network`)                                 |
+| `allowNetwork`        | `[]`           | Hosts a cloud sandbox may reach, on top of the account's policy (cloud only)                    |
+| `cpus`                | decided by sbx | CPUs of the microVM                                                                             |
+| `memory`              | decided by sbx | Memory limit of the microVM (`4g`, `512m`)                                                      |
+| `platform`            | decided by sbx | `linux/amd64` or `linux/arm64` (cloud only)                                                     |
+| `ttl`                 | decided by sbx | Time-to-live of a cloud sandbox, 24 hours at most (cloud only)                                  |
+| `onTimeout`           | decided by sbx | `stop`, `restart` or `delete` the cloud sandbox when its `ttl` lapses (cloud only)              |
+| `setup`               | `[]`           | Commands run once after creation, as the sandbox user (who has `sudo`), baked into the template |
+| `ports`               | `[]`           | _Connection._ Ports the harness may reach, published on demand                                  |
+| `brokerCredentials`   | `true`         | _Connection._ Keep credentials out of the sandbox, swapped in by the proxy                      |
+| `clearEnv`            | `[]`           | _Connection._ More variables to drop from commands that do not set them                         |
+| `keepProxyManagedEnv` | `false`        | _Connection._ Keep the `proxy-managed` credential variables Docker Sandboxes pre-sets           |
+| `binary`              | `'sbx'`        | _Connection._ The `sbx` binary                                                                  |
+
+## Errors
+
+- `SbxSandboxNotFoundError`: `resumeSbxNetworkSandboxSession()` found no sandbox of that name. Carries `sandboxId`.
+- `SbxError`: an `sbx` command exited with a non-zero status. Carries `args`, `exitCode` and `stderr`.
+- `HarnessCapabilityUnsupportedError` (from `@ai-sdk/harness`): a port that is not exposed, or a credential the proxy cannot broker.
+
+## Limitations
+
+- **One bridge per port.** A bridge-backed harness listens on the first port: run one harness session at a time per sandbox, or give each its own port.
+
+## Development
+
+This package lives in the [`ai-sdk-harness`](https://github.com/fpasquet/ai-sdk-harness) monorepo. `pnpm test` runs the unit tests against a fake `sbx`; `pnpm test:e2e` runs them against the real one, creating and removing sandboxes on your machine.
+
+## License
+
+[MIT](https://github.com/fpasquet/ai-sdk-harness/blob/main/LICENSE)

package/dist/create-args.d.ts

@@ -0,0 +1,11 @@
+import type { SbxCreationSettings } from './sbx-settings.js';
+export declare function assertSandboxName(name: string, cloud: boolean): void;
+/** Fails on a setting the sandbox's side, local or cloud, would ignore or refuse. */
+export declare function assertSettingsFit(settings: SbxCreationSettings, cloud: boolean): void;
+/** The `sbx create` command line of a new sandbox, made from `image` when there is one. */
+export declare function createArgs({ name, image, fromTemplate, settings, }: {
+    name: string;
+    image: string | undefined;
+    fromTemplate: boolean;
+    settings: SbxCreationSettings;
+}): string[];

package/dist/create-args.js

@@ -0,0 +1,78 @@
+/** What `sbx create --name` accepts: two characters or more, starting with a letter or a digit. */
+const LOCAL_NAME = /^[A-Za-z0-9][A-Za-z0-9.-]+$/;
+/** The same, without periods, which cloud sandbox names refuse. */
+const CLOUD_NAME = /^[A-Za-z0-9][A-Za-z0-9-]+$/;
+/** Settings that only mean something on one side: a cloud sandbox mounts nothing of this host. */
+const LOCAL_ONLY = ['workspace', 'clone', 'readOnlyWorkspaces'];
+const CLOUD_ONLY = ['allowNetwork', 'ttl', 'onTimeout', 'platform'];
+export function assertSandboxName(name, cloud) {
+    if (!(cloud ? CLOUD_NAME : LOCAL_NAME).test(name) || name === 'default') {
+        const characters = cloud
+            ? 'letters, digits and hyphens'
+            : 'letters, digits, hyphens and periods';
+        throw new Error(`"${name}" is not a valid sandbox id: use two characters or more (${characters}), ` +
+            'starting with a letter or a digit ("default" is reserved).');
+    }
+}
+/** Fails on a setting the sandbox's side, local or cloud, would ignore or refuse. */
+export function assertSettingsFit(settings, cloud) {
+    const misplaced = (cloud ? LOCAL_ONLY : CLOUD_ONLY).filter((key) => settings[key] !== undefined && settings[key] !== false);
+    if (misplaced.length > 0) {
+        const names = misplaced.map((key) => `\`${key}\``).join(', ');
+        throw new Error(cloud
+            ? `${names}: a cloud sandbox mounts nothing of this host.`
+            : `${names}: only apply to a cloud sandbox (\`cloud: true\`).`);
+    }
+    if (settings.clone && settings.workspace === undefined) {
+        throw new Error('`clone` needs a `workspace`: the Git repository of this host to clone.');
+    }
+}
+/** `--template`, for a sandbox made from an image rather than from its kit's own. */
+function imageFlags(image, localTemplate) {
+    if (image === undefined)
+        return [];
+    // A local template image only exists in the local store: never look for it in a registry.
+    return localTemplate ? ['--template', image, '--pull', 'never'] : ['--template', image];
+}
+function resourceFlags({ cpus, memory, platform }) {
+    return [
+        ...(cpus === undefined ? [] : ['--cpus', String(cpus)]),
+        ...(memory === undefined ? [] : ['--memory', memory]),
+        ...(platform === undefined ? [] : ['--platform', platform]),
+    ];
+}
+function networkFlags({ denyNetwork = [], allowNetwork = [] }) {
+    return [
+        ...denyNetwork.flatMap((host) => ['--deny-network', host]),
+        ...allowNetwork.flatMap((host) => ['--allow-network', host]),
+    ];
+}
+function lifetimeFlags({ ttl, onTimeout }) {
+    return [
+        ...(ttl === undefined ? [] : ['--ttl', ttl]),
+        ...(onTimeout === undefined ? [] : ['--on-timeout', onTimeout]),
+    ];
+}
+/** The agent kit, then the host directories the sandbox mounts. */
+function workspaceArgs({ agent = 'shell', workspace, clone = false, readOnlyWorkspaces = [], }) {
+    return [
+        ...(clone ? ['--clone'] : []),
+        agent,
+        ...(workspace === undefined ? [] : [workspace]),
+        ...readOnlyWorkspaces.map((path) => `${path}:ro`),
+    ];
+}
+/** The `sbx create` command line of a new sandbox, made from `image` when there is one. */
+export function createArgs({ name, image, fromTemplate, settings, }) {
+    return [
+        'create',
+        '--name',
+        name,
+        '--quiet',
+        ...imageFlags(image, fromTemplate && settings.cloud !== true),
+        ...resourceFlags(settings),
+        ...networkFlags(settings),
+        ...lifetimeFlags(settings),
+        ...workspaceArgs(settings),
+    ];
+}

package/dist/credential-broker.d.ts

@@ -0,0 +1,35 @@
+import type { HarnessV1RequestTransformation } from '@ai-sdk/harness';
+import type { SbxCli } from './sbx-cli.js';
+type Transformations = ReadonlyArray<HarnessV1RequestTransformation>;
+/** Recorded on the errors this package raises through the harness's own error types. */
+export declare const SBX_SANDBOX_PROVIDER_ID = "sbx";
+/**
+ * Keeps credentials out of the sandbox: each request transformation becomes a custom secret of the
+ * Docker Sandboxes proxy, scoped to the sandbox, so the real value only exists on this host and in
+ * the proxy.
+ */
+export interface CredentialBroker {
+    add(transformations: Transformations): Promise<void>;
+    /** Withdraws the secrets this broker registered. */
+    release(): Promise<void>;
+    /** Withdraws every secret scoped to the sandbox, a previous process's included. */
+    clear(): Promise<void>;
+}
+/**
+ * Local sandboxes: the proxy swaps one string for another in the requests to the host. The
+ * sandbox sends the harness's placeholder, `Bearer <placeholder>`, and the proxy puts the secret
+ * in its place: only the part that differs is registered.
+ *
+ * A header the request does not carry, the proxy cannot add. When the same transformation does
+ * protect a credential, such a header is left out with a warning: Codex, logged in with ChatGPT,
+ * asks for a `ChatGPT-Account-ID` its backend does without. A transformation that would protect
+ * no credential at all is refused.
+ */
+export declare function placeholderBroker(cli: SbxCli, sandbox: string): CredentialBroker;
+/**
+ * Cloud sandboxes: the proxy sets the whole header on the requests to the host, whatever the
+ * sandbox sent in it. Each secret is named after the sandbox, the host and the header, so
+ * registering it again replaces it rather than piling up.
+ */
+export declare function headerBroker(cli: SbxCli, sandbox: string): CredentialBroker;
+export {};

package/dist/credential-broker.js

@@ -0,0 +1,143 @@
+import { HarnessCapabilityUnsupportedError } from '@ai-sdk/harness';
+/** Recorded on the errors this package raises through the harness's own error types. */
+export const SBX_SANDBOX_PROVIDER_ID = 'sbx';
+/**
+ * Local sandboxes: the proxy swaps one string for another in the requests to the host. The
+ * sandbox sends the harness's placeholder, `Bearer <placeholder>`, and the proxy puts the secret
+ * in its place: only the part that differs is registered.
+ *
+ * A header the request does not carry, the proxy cannot add. When the same transformation does
+ * protect a credential, such a header is left out with a warning: Codex, logged in with ChatGPT,
+ * asks for a `ChatGPT-Account-ID` its backend does without. A transformation that would protect
+ * no credential at all is refused.
+ */
+export function placeholderBroker(cli, sandbox) {
+    const placeholders = new Set();
+    const remove = (placeholder) => cli.run(['secret', 'rm', '--sandbox', sandbox, '--placeholder', placeholder, '--force']);
+    return {
+        add: async (transformations) => {
+            for (const { match, header, secret } of swappableHeaders(transformations)) {
+                const [placeholder, value] = placeholderOf(match, header, secret);
+                await cli.check([
+                    'secret',
+                    'set-custom',
+                    '--sandbox',
+                    sandbox,
+                    '--host',
+                    match.host,
+                    '--placeholder',
+                    placeholder,
+                    // On this host's command line for as long as `sbx` runs, never inside the sandbox.
+                    '--value',
+                    value,
+                ]);
+                placeholders.add(placeholder);
+            }
+        },
+        release: async () => {
+            for (const placeholder of placeholders)
+                await remove(placeholder);
+            placeholders.clear();
+        },
+        clear: async () => {
+            const listed = await cli.check(['secret', 'ls', '--sandbox', sandbox, '--json']);
+            const { custom_secrets: secrets = [] } = JSON.parse(listed);
+            for (const { scope, placeholder } of secrets) {
+                if (scope === sandbox)
+                    await remove(placeholder);
+            }
+            placeholders.clear();
+        },
+    };
+}
+/**
+ * Cloud sandboxes: the proxy sets the whole header on the requests to the host, whatever the
+ * sandbox sent in it. Each secret is named after the sandbox, the host and the header, so
+ * registering it again replaces it rather than piling up.
+ */
+export function headerBroker(cli, sandbox) {
+    const names = new Set();
+    const remove = (name) => cli.run(['secret', 'rm', name, '--force']);
+    const release = async () => {
+        for (const name of names)
+            await remove(name);
+        names.clear();
+    };
+    return {
+        add: async (transformations) => {
+            for (const { match, header, secret } of headersOf(transformations)) {
+                const name = `${sandbox}-${match.host}-${header}`.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+                await cli.check([
+                    'secret',
+                    'set-custom',
+                    '--sandbox',
+                    sandbox,
+                    '--name',
+                    name,
+                    '--host',
+                    match.host,
+                    '--header',
+                    header,
+                    '--format',
+                    '%s',
+                    '--value',
+                    secret,
+                ]);
+                names.add(name);
+            }
+        },
+        release,
+        // Names are derived from the sandbox: what a previous process registered is overwritten, not
+        // left behind, so withdrawing this broker's own is all there is to do.
+        clear: release,
+    };
+}
+function headersOf(transformations) {
+    return transformations.flatMap(({ match, transform }) => Object.entries(transform.headers).map(([header, secret]) => ({ match, header, secret })));
+}
+/** The value the sandbox sends for `header`, when it is an exact placeholder. */
+function sentValue(match, header) {
+    const sent = match.headers?.find(({ key }) => key && 'exact' in key ? key.exact.toLowerCase() === header.toLowerCase() : false)?.value;
+    return sent && 'exact' in sent ? sent.exact : undefined;
+}
+/** Headers already warned about, so a long-running process says it once. */
+const warned = new Set();
+/**
+ * The headers a placeholder-swapping proxy can set: those the request carries a placeholder for.
+ * The others are left out, with a warning, when their transformation protects a credential.
+ */
+function swappableHeaders(transformations) {
+    return transformations.flatMap((transformation) => {
+        const headers = headersOf([transformation]);
+        const swappable = headers.filter(({ match, header }) => sentValue(match, header) !== undefined);
+        // Nothing to swap: the request carries no credential to protect. Let placeholderOf say so.
+        if (swappable.length === 0)
+            return headers;
+        for (const { match, header } of headers) {
+            const key = `${match.host} ${header}`;
+            if (swappable.some((kept) => kept.header === header) || warned.has(key))
+                continue;
+            warned.add(key);
+            process.emitWarning(`The ${header} header of ${match.host} is left out: a local Docker Sandboxes proxy swaps ` +
+                'placeholders, and cannot add a header the request does not carry.', { code: 'AI_SDK_SANDBOX_SBX_HEADER_LEFT_OUT' });
+        }
+        return swappable;
+    });
+}
+/**
+ * The placeholder the sandbox sends for `header`, and the value the proxy must put in its place,
+ * without the prefix they share.
+ */
+function placeholderOf(match, header, secret) {
+    const sent = sentValue(match, header);
+    if (sent === undefined) {
+        throw new HarnessCapabilityUnsupportedError({
+            harnessId: SBX_SANDBOX_PROVIDER_ID,
+            message: `Cannot broker the ${header} header of ${match.host}: Docker Sandboxes swaps a placeholder, and the request carries none.`,
+        });
+    }
+    let shared = 0;
+    while (shared < sent.length && sent[shared] === secret[shared])
+        shared += 1;
+    return [sent.slice(shared), secret.slice(shared)];
+}

package/dist/free-loopback-port.d.ts

@@ -0,0 +1,2 @@
+/** A TCP port free on this host's loopback right now. */
+export declare function freeLoopbackPort(): Promise<number>;

package/dist/free-loopback-port.js

@@ -0,0 +1,12 @@
+import { createServer } from 'node:net';
+/** A TCP port free on this host's loopback right now. */
+export function freeLoopbackPort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const { port } = server.address();
+            server.close(() => resolve(port));
+        });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { SbxError } from './sbx-error.js';
+export { SBX_SANDBOX_PROVIDER_ID, SbxNetworkSandboxSession, } from './sbx-network-sandbox-session.js';
+export { createSbxNetworkSandboxSession, resumeSbxNetworkSandboxSession, } from './sbx-network-sandbox.js';
+export { SbxSandboxNotFoundError } from './sbx-sandbox-not-found-error.js';
+export { SbxSandboxSession } from './sbx-sandbox-session.js';
+export type { SbxConnectionSettings, SbxCreationSettings, SbxNetworkSandboxSessionCreateOptions, SbxNetworkSandboxSessionResumeOptions, } from './sbx-settings.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { SbxError } from './sbx-error.js';
+export { SBX_SANDBOX_PROVIDER_ID, SbxNetworkSandboxSession, } from './sbx-network-sandbox-session.js';
+export { createSbxNetworkSandboxSession, resumeSbxNetworkSandboxSession, } from './sbx-network-sandbox.js';
+export { SbxSandboxNotFoundError } from './sbx-sandbox-not-found-error.js';
+export { SbxSandboxSession } from './sbx-sandbox-session.js';

package/dist/open-sandbox.d.ts

@@ -0,0 +1,22 @@
+import type { SbxCli } from './sbx-cli.js';
+import type { SbxConnectionSettings } from './sbx-settings.js';
+import { SbxNetworkSandboxSession } from './sbx-network-sandbox-session.js';
+/** The sandboxes `sbx` knows of, by name and, for cloud ones, by `sbx_*` id too. */
+export declare function listSandboxes(cli: SbxCli, abortSignal?: AbortSignal): Promise<Set<string>>;
+/** Throws {@link SbxSandboxNotFoundError} unless a sandbox named `name` exists. */
+export declare function assertSandboxExists(cli: SbxCli, name: string, abortSignal?: AbortSignal): Promise<void>;
+/**
+ * Runs each of `setup` in the sandbox `name`, in order, stopping at the first failure. They run as
+ * the sandbox user: `sbx --cloud exec` refuses `--user`, and the kits give that user `sudo`.
+ */
+export declare function runSetup(cli: SbxCli, name: string, { setup, abortSignal }: {
+    setup: readonly string[];
+    abortSignal?: AbortSignal;
+}): Promise<void>;
+/**
+ * A session on the existing sandbox `name`. Its working directory and its environment are read from
+ * the live sandbox: they belong to its image, not to this package.
+ */
+export declare function openSandbox(cli: SbxCli, name: string, settings: SbxConnectionSettings & {
+    abortSignal?: AbortSignal;
+}): Promise<SbxNetworkSandboxSession>;