ai-sdk-sandbox-sbx 1.0.0

package/dist/open-sandbox.js

@@ -0,0 +1,54 @@
+import { PROBE } from './sandbox-scripts.js';
+import { SbxNetworkSandboxSession } from './sbx-network-sandbox-session.js';
+import { SbxSandboxNotFoundError } from './sbx-sandbox-not-found-error.js';
+import { assertEnvNames } from './sbx-sandbox-session.js';
+const ENV_LINE = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+/** Where a credential lives: `ANTHROPIC_API_KEY`, `GH_TOKEN`…, but not `MCP_SENTINEL_TOKEN_NAME`. */
+const CREDENTIAL_NAME = /(?:API_KEY|TOKEN)$/;
+/** A credential Docker Sandboxes leaves for its own proxy to fill in. */
+const isProxyManaged = (variable, value) => CREDENTIAL_NAME.test(variable) &&
+    (value === 'proxy-managed' || value.includes('sbxproxymanaged'));
+/** The sandboxes `sbx` knows of, by name and, for cloud ones, by `sbx_*` id too. */
+export async function listSandboxes(cli, abortSignal) {
+    const listed = JSON.parse(await cli.check(['ls', '--json'], { abortSignal }));
+    const sandboxes = Array.isArray(listed) ? listed : (listed.sandboxes ?? []);
+    return new Set(sandboxes.flatMap(({ name, id }) => [name, id].filter((key) => key !== undefined)));
+}
+/** Throws {@link SbxSandboxNotFoundError} unless a sandbox named `name` exists. */
+export async function assertSandboxExists(cli, name, abortSignal) {
+    if (!(await listSandboxes(cli, abortSignal)).has(name))
+        throw new SbxSandboxNotFoundError(name);
+}
+/**
+ * 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 async function runSetup(cli, name, { setup, abortSignal }) {
+    for (const command of setup) {
+        await cli.check(['exec', name, 'sh', '-c', command], { abortSignal });
+    }
+}
+/**
+ * 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 async function openSandbox(cli, name, settings) {
+    const { clearEnv = [], keepProxyManagedEnv = false } = settings;
+    assertEnvNames(clearEnv);
+    const [workingDirectory = '', ...env] = (await cli.check(['exec', name, 'sh', '-c', PROBE], { abortSignal: settings.abortSignal })).split('\n');
+    const proxyManaged = keepProxyManagedEnv
+        ? []
+        : env.flatMap((line) => {
+            const [, variable, value] = ENV_LINE.exec(line) ?? [];
+            return variable !== undefined && value !== undefined && isProxyManaged(variable, value)
+                ? [variable]
+                : [];
+        });
+    return new SbxNetworkSandboxSession({
+        cli,
+        name,
+        workingDirectory: workingDirectory.trim(),
+        processes: new Set(),
+        clearEnv: [...new Set([...proxyManaged, ...clearEnv])],
+    }, settings.ports ?? [], settings.brokerCredentials ?? true);
+}

package/dist/port-publisher.d.ts

@@ -0,0 +1,30 @@
+import type { SbxCli } from './sbx-cli.js';
+/** A sandbox port made reachable from this process. */
+export interface PublishedPort {
+    /** Where it is reached: `http://127.0.0.1:<port>` locally, a public `https://` URL in the cloud. */
+    readonly url: string;
+    /** What `sbx ports --unpublish` takes to withdraw it. */
+    readonly binding: string;
+}
+/** How a sandbox port becomes reachable: on this host's loopback, or through the cloud. */
+export interface PortPublisher {
+    publish(port: number): Promise<PublishedPort>;
+    unpublish(published: PublishedPort): Promise<void>;
+}
+/**
+ * Local sandboxes: each port is published on this host's loopback only, on a free port picked here
+ * rather than by `sbx`, since an ephemeral binding comes back under another port once unpublished.
+ */
+export declare function loopbackPorts(cli: SbxCli, sandbox: string): PortPublisher;
+/**
+ * Cloud sandboxes: the control plane exposes the port and assigns it a public URL, read back from
+ * the port listing, or from what publishing printed when the listing does not carry it.
+ */
+export declare function cloudPorts(cli: SbxCli, sandbox: string): PortPublisher;
+/** The URL to reach `base` with `protocol`, keeping it secure when the base is. */
+export declare function endpointUrl(base: string, protocol: 'http' | 'https' | 'ws'): string;
+/**
+ * The URL of `port` in a port listing, whatever its exact shape: the first object that names the
+ * port in a `*port*` field and carries an `http(s)` URL.
+ */
+export declare function findPortUrl(listing: unknown, port: number): string | undefined;

package/dist/port-publisher.js

@@ -0,0 +1,75 @@
+import { freeLoopbackPort } from './free-loopback-port.js';
+const URL_PATTERN = /^https?:\/\//;
+/**
+ * Local sandboxes: each port is published on this host's loopback only, on a free port picked here
+ * rather than by `sbx`, since an ephemeral binding comes back under another port once unpublished.
+ */
+export function loopbackPorts(cli, sandbox) {
+    return {
+        publish: async (port) => {
+            const hostPort = await freeLoopbackPort();
+            const binding = `127.0.0.1:${hostPort}:${port}`;
+            await cli.check(['ports', sandbox, '--publish', binding]);
+            return { url: `http://127.0.0.1:${hostPort}`, binding };
+        },
+        unpublish: async ({ binding }) => {
+            await cli.run(['ports', sandbox, '--unpublish', binding]);
+        },
+    };
+}
+/**
+ * Cloud sandboxes: the control plane exposes the port and assigns it a public URL, read back from
+ * the port listing, or from what publishing printed when the listing does not carry it.
+ */
+export function cloudPorts(cli, sandbox) {
+    return {
+        publish: async (port) => {
+            const printed = await cli.check(['ports', sandbox, '--publish', String(port)]);
+            const listed = await cli.check(['ports', sandbox, '--json']);
+            const url = findPortUrl(parseJson(listed), port) ?? printed.match(/https?:\/\/\S+/)?.[0];
+            if (url === undefined) {
+                throw new Error(`sbx exposed port ${port} of the cloud sandbox "${sandbox}" without saying at which URL.`);
+            }
+            return { url: url.replace(/\/$/, ''), binding: String(port) };
+        },
+        unpublish: async ({ binding }) => {
+            await cli.run(['ports', sandbox, '--unpublish', binding]);
+        },
+    };
+}
+/** The URL to reach `base` with `protocol`, keeping it secure when the base is. */
+export function endpointUrl(base, protocol) {
+    const secure = base.startsWith('https:');
+    const scheme = protocol === 'ws' ? (secure ? 'wss' : 'ws') : secure ? 'https' : 'http';
+    return base.replace(/^https?/, scheme);
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The URL of `port` in a port listing, whatever its exact shape: the first object that names the
+ * port in a `*port*` field and carries an `http(s)` URL.
+ */
+export function findPortUrl(listing, port) {
+    if (Array.isArray(listing)) {
+        for (const item of listing) {
+            const url = findPortUrl(item, port);
+            if (url !== undefined)
+                return url;
+        }
+        return undefined;
+    }
+    if (typeof listing !== 'object' || listing === null)
+        return undefined;
+    const entries = Object.entries(listing);
+    const namesPort = entries.some(([key, value]) => /port/i.test(key) && Number(value) === port);
+    const url = entries.find(([, value]) => typeof value === 'string' && URL_PATTERN.test(value));
+    if (namesPort && url)
+        return url[1];
+    return findPortUrl(entries.map(([, value]) => value).filter((value) => typeof value === 'object'), port);
+}

package/dist/sandbox-scripts.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The shell snippets run inside the sandbox. Each takes its inputs as positional arguments
+ * (`sh -c SCRIPT $0 $1 …`), never spliced into the script, so no path or command is ever parsed
+ * as shell code it was not meant to be.
+ */
+/** Where a spawned process leaves its pid, so it can be stopped from outside. */
+export declare const PROCESS_DIR = "/tmp/.ai-sdk-sbx-processes";
+/**
+ * Runs `$1` under a shell whose pid is recorded in `$0` first. Killing the `sbx exec` client does
+ * not reach the process inside the sandbox, so this pid is the only handle on it.
+ */
+export declare const TRACKED = "mkdir -p /tmp/.ai-sdk-sbx-processes && echo $$ > \"$0\" && sh -c \"$1\"; code=$?; rm -f \"$0\"; exit $code";
+/** Stops the process recorded in `$0` and everything it started, children first. */
+export declare const KILL_TREE: string;
+/**
+ * Stops every process recorded in {@link PROCESS_DIR}, whichever session started it, sparing the
+ * shells running this very script, which `sbx exec` started like any other.
+ */
+export declare const KILL_ALL: string;
+/** Exit status of {@link READ} for a path that does not exist. */
+export declare const READ_MISSING = 44;
+/** Exit status of {@link READ} for a path that is a directory. */
+export declare const READ_DIRECTORY = 45;
+/** `cat` the file `$0`, with exit statuses of its own for a missing path and for a directory. */
+export declare const READ = "[ -d \"$0\" ] && exit 45; [ -e \"$0\" ] || exit 44; exec cat -- \"$0\"";
+/** Writes stdin to the file `$0`, creating its parent directories. */
+export declare const WRITE = "mkdir -p \"$(dirname \"$0\")\" && cat > \"$0\"";
+/** The sandbox's working directory on the first line, then its environment. */
+export declare const PROBE = "pwd; env";

package/dist/sandbox-scripts.js

@@ -0,0 +1,41 @@
+/**
+ * The shell snippets run inside the sandbox. Each takes its inputs as positional arguments
+ * (`sh -c SCRIPT $0 $1 …`), never spliced into the script, so no path or command is ever parsed
+ * as shell code it was not meant to be.
+ */
+/** Where a spawned process leaves its pid, so it can be stopped from outside. */
+export const PROCESS_DIR = '/tmp/.ai-sdk-sbx-processes';
+/**
+ * Runs `$1` under a shell whose pid is recorded in `$0` first. Killing the `sbx exec` client does
+ * not reach the process inside the sandbox, so this pid is the only handle on it.
+ */
+export const TRACKED = `mkdir -p ${PROCESS_DIR} && echo $$ > "$0" && sh -c "$1"; code=$?; rm -f "$0"; exit $code`;
+/** Stops the process recorded in `$0` and everything it started, children first. */
+export const KILL_TREE = 'kill_tree() { for child in $(pgrep -P "$1"); do kill_tree "$child"; done; kill -TERM "$1" 2>/dev/null; }; ' +
+    'pid=$(cat "$0" 2>/dev/null) && kill_tree "$pid"; rm -f "$0"';
+/**
+ * Stops every process recorded in {@link PROCESS_DIR}, whichever session started it, sparing the
+ * shells running this very script, which `sbx exec` started like any other.
+ */
+export const KILL_ALL = [
+    'kill_tree() { for child in $(pgrep -P "$1"); do kill_tree "$child"; done; kill -TERM "$1" 2>/dev/null; }',
+    'mine=" $$ "; p=$$',
+    'while [ "$p" -gt 1 ] 2>/dev/null; do p=$(ps -o ppid= -p "$p" | tr -d " "); mine="$mine$p "; done',
+    `for file in ${PROCESS_DIR}/*; do`,
+    '  [ -f "$file" ] || continue',
+    '  pid=$(cat "$file" 2>/dev/null) || continue',
+    '  case "$mine" in *" $pid "*) continue ;; esac',
+    '  kill_tree "$pid"; rm -f "$file"',
+    'done',
+    'true',
+].join('\n');
+/** Exit status of {@link READ} for a path that does not exist. */
+export const READ_MISSING = 44;
+/** Exit status of {@link READ} for a path that is a directory. */
+export const READ_DIRECTORY = 45;
+/** `cat` the file `$0`, with exit statuses of its own for a missing path and for a directory. */
+export const READ = `[ -d "$0" ] && exit ${READ_DIRECTORY}; [ -e "$0" ] || exit ${READ_MISSING}; exec cat -- "$0"`;
+/** Writes stdin to the file `$0`, creating its parent directories. */
+export const WRITE = 'mkdir -p "$(dirname "$0")" && cat > "$0"';
+/** The sandbox's working directory on the first line, then its environment. */
+export const PROBE = 'pwd; env';

package/dist/sandbox-template.d.ts

@@ -0,0 +1,26 @@
+import type { HarnessV1SandboxTemplate } from '@ai-sdk/harness';
+import type { SbxCli } from './sbx-cli.js';
+/** The name templates are saved under: an image repository locally, a template name prefix in the cloud. */
+export declare const TEMPLATE_REPOSITORY = "ai-sdk-harness-template";
+/** What a template is built from: the harness's recipe, and the base it is laid on. */
+export interface TemplateSource {
+    template: HarnessV1SandboxTemplate;
+    agent: string;
+    image?: string;
+    setup: readonly string[];
+}
+/**
+ * The image of a sandbox prepared by `source.template`, built the first time and reused afterwards:
+ * one sandbox is created, set up, prepared and saved with `sbx template save`, then removed. Every
+ * later sandbox starts from that image, with the harness already installed. A local template lives
+ * in this host's image store, a cloud one in the cloud registry, where saving takes minutes.
+ *
+ * The reference derives from the template's identity and from the base it is laid on, so a new
+ * harness version or another kit gets an image of its own.
+ */
+export declare function ensureTemplateImage(cli: SbxCli, source: TemplateSource, abortSignal?: AbortSignal): Promise<string>;
+/**
+ * The template's reference: `docker.io/library/ai-sdk-harness-template:<digest>` locally, the name
+ * `ai-sdk-harness-template-<digest>` in the cloud.
+ */
+export declare function templateReference({ template, agent, image, setup }: TemplateSource, cloud?: boolean): string;

package/dist/sandbox-template.js

@@ -0,0 +1,74 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { openSandbox, runSetup } from './open-sandbox.js';
+/** The name templates are saved under: an image repository locally, a template name prefix in the cloud. */
+export const TEMPLATE_REPOSITORY = 'ai-sdk-harness-template';
+/** Where `sbx template save` puts a local template: the sandbox runtime's own image store. */
+const LOCAL_STORE = 'docker.io/library/';
+/** Images being built by this process, by reference: one build per reference at a time. */
+const building = new Map();
+/**
+ * The image of a sandbox prepared by `source.template`, built the first time and reused afterwards:
+ * one sandbox is created, set up, prepared and saved with `sbx template save`, then removed. Every
+ * later sandbox starts from that image, with the harness already installed. A local template lives
+ * in this host's image store, a cloud one in the cloud registry, where saving takes minutes.
+ *
+ * The reference derives from the template's identity and from the base it is laid on, so a new
+ * harness version or another kit gets an image of its own.
+ */
+export async function ensureTemplateImage(cli, source, abortSignal) {
+    const reference = templateReference(source, cli.cloud);
+    let image = building.get(reference);
+    if (image === undefined) {
+        image = imageExists(cli, reference, abortSignal).then((exists) => exists ? reference : buildImage({ cli, source, reference, abortSignal }));
+        building.set(reference, image);
+        // A failed build is not remembered: the next sandbox tries again.
+        image.catch(() => building.delete(reference));
+    }
+    return image;
+}
+/**
+ * The template's reference: `docker.io/library/ai-sdk-harness-template:<digest>` locally, the name
+ * `ai-sdk-harness-template-<digest>` in the cloud.
+ */
+export function templateReference({ template, agent, image, setup }, cloud = false) {
+    const digest = createHash('sha256')
+        .update(JSON.stringify([1, template.identity, agent, image ?? null, setup]))
+        .digest('hex')
+        .slice(0, 24);
+    return cloud
+        ? `${TEMPLATE_REPOSITORY}-${digest}`
+        : `${LOCAL_STORE}${TEMPLATE_REPOSITORY}:${digest}`;
+}
+/** Whether `needle` is one of the strings anywhere in `value`. */
+function containsString(value, needle) {
+    if (typeof value === 'string')
+        return value === needle;
+    if (typeof value !== 'object' || value === null)
+        return false;
+    return Object.values(value).some((item) => containsString(item, needle));
+}
+async function imageExists(cli, reference, abortSignal) {
+    const listed = JSON.parse(await cli.check(['template', 'ls', '--json'], { abortSignal }));
+    if (cli.cloud)
+        return containsString(listed, reference);
+    return (listed.images ?? []).some(({ repository, tag }) => `${repository}:${tag}` === reference);
+}
+async function buildImage({ cli, source: { template, agent, image, setup }, reference, abortSignal, }) {
+    const builder = `${TEMPLATE_REPOSITORY}-${reference.slice(-12)}-${randomBytes(3).toString('hex')}`;
+    await cli.check(['create', '--name', builder, '--quiet', ...(image ? ['--template', image] : []), agent], { abortSignal });
+    try {
+        await runSetup(cli, builder, { setup, abortSignal });
+        const session = await openSandbox(cli, builder, { abortSignal });
+        await template.prepare({ session: session.restricted(), abortSignal });
+        // A local `sbx template save` refuses a running sandbox; a cloud one snapshots it running.
+        if (!cli.cloud)
+            await cli.check(['stop', builder], { abortSignal });
+        await cli.check(['template', 'save', builder, reference.replace(LOCAL_STORE, '')], {
+            abortSignal,
+        });
+        return reference;
+    }
+    finally {
+        await cli.run(['rm', '--force', builder]);
+    }
+}

package/dist/sbx-cli.d.ts

@@ -0,0 +1,42 @@
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+/** What a finished `sbx` invocation left behind. */
+export interface SbxResult {
+    exitCode: number;
+    /** Kept as bytes: `sbx exec … cat` hands back a file, which need not be text. */
+    stdout: Buffer;
+    stderr: string;
+}
+export interface SbxCallOptions {
+    /** Written to the command's stdin, which is then closed. */
+    stdin?: ReadableStream<Uint8Array> | Uint8Array;
+    /**
+     * Variables the `sbx` client itself sees, on top of this process's environment. `sbx exec -e NAME`
+     * without a value forwards the client's own `NAME` into the sandbox, so a value never has to
+     * appear on a command line.
+     */
+    env?: Record<string, string>;
+    abortSignal?: AbortSignal;
+}
+/** Why `signal` was aborted, as an error to reject with. */
+export declare const abortReason: (signal: AbortSignal) => Error;
+/**
+ * The `sbx` command line of Docker Sandboxes, run as a child process: the only way this package
+ * reaches a sandbox. Every argument is passed as-is, never through a host shell.
+ */
+export declare class SbxCli {
+    readonly binary: string;
+    readonly cloud: boolean;
+    /**
+     * @param binary The `sbx` binary.
+     * @param cloud Address Docker Sandboxes Cloud rather than this host's sandboxes: every command
+     *   goes out as `sbx --cloud …`.
+     */
+    constructor(binary?: string, cloud?: boolean);
+    /** Starts `sbx` and hands back the running process, streams untouched. */
+    start(args: readonly string[], options?: SbxCallOptions): ChildProcessWithoutNullStreams;
+    /** Runs `sbx` to completion, whatever its exit code. */
+    run(args: readonly string[], options?: SbxCallOptions): Promise<SbxResult>;
+    /** Runs `sbx` and returns its standard output as text, throwing {@link SbxError} on failure. */
+    check(args: readonly string[], options?: SbxCallOptions): Promise<string>;
+    private notFound;
+}

package/dist/sbx-cli.js

@@ -0,0 +1,77 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+import { Readable } from 'node:stream';
+import { SbxError } from './sbx-error.js';
+/** Why `signal` was aborted, as an error to reject with. */
+export const abortReason = (signal) => {
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : new DOMException('Aborted', 'AbortError');
+};
+const exitCodeOf = (code, signal) => code ?? (signal === null ? 0 : 128 + (constants.signals[signal] ?? 0));
+/**
+ * The `sbx` command line of Docker Sandboxes, run as a child process: the only way this package
+ * reaches a sandbox. Every argument is passed as-is, never through a host shell.
+ */
+export class SbxCli {
+    binary;
+    cloud;
+    /**
+     * @param binary The `sbx` binary.
+     * @param cloud Address Docker Sandboxes Cloud rather than this host's sandboxes: every command
+     *   goes out as `sbx --cloud …`.
+     */
+    constructor(binary = 'sbx', cloud = false) {
+        this.binary = binary;
+        this.cloud = cloud;
+    }
+    /** Starts `sbx` and hands back the running process, streams untouched. */
+    start(args, options = {}) {
+        const child = spawn(this.binary, this.cloud ? ['--cloud', ...args] : args, {
+            env: { ...process.env, ...options.env },
+            signal: options.abortSignal,
+            stdio: 'pipe',
+        });
+        // A command that exits before reading its stdin must not crash this process on EPIPE.
+        child.stdin.on('error', () => undefined);
+        const { stdin } = options;
+        if (stdin === undefined) {
+            child.stdin.end();
+        }
+        else if (stdin instanceof Uint8Array) {
+            child.stdin.end(stdin);
+        }
+        else {
+            Readable.fromWeb(stdin).pipe(child.stdin);
+        }
+        return child;
+    }
+    /** Runs `sbx` to completion, whatever its exit code. */
+    run(args, options = {}) {
+        if (options.abortSignal?.aborted)
+            return Promise.reject(abortReason(options.abortSignal));
+        const child = this.start(args, options);
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on('data', (chunk) => stdout.push(chunk));
+        child.stderr.on('data', (chunk) => stderr.push(chunk));
+        return new Promise((resolve, reject) => {
+            child.once('error', (error) => reject(error.code === 'ENOENT' ? this.notFound() : error));
+            child.once('close', (code, signal) => resolve({
+                exitCode: exitCodeOf(code, signal),
+                stdout: Buffer.concat(stdout),
+                stderr: Buffer.concat(stderr).toString(),
+            }));
+        });
+    }
+    /** Runs `sbx` and returns its standard output as text, throwing {@link SbxError} on failure. */
+    async check(args, options = {}) {
+        const result = await this.run(args, options);
+        if (result.exitCode !== 0)
+            throw new SbxError(args, result);
+        return result.stdout.toString();
+    }
+    notFound() {
+        return new Error(`The Docker Sandboxes CLI \`${this.binary}\` was not found. Install it ` +
+            '(https://docs.docker.com/ai/sandboxes/get-started/) or point the `binary` option at it.');
+    }
+}

package/dist/sbx-error.d.ts

@@ -0,0 +1,11 @@
+/** An `sbx` command exited with a non-zero status. */
+export declare class SbxError extends Error {
+    /** The `sbx` sub-command and its arguments, as they were passed. */
+    readonly args: readonly string[];
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(args: readonly string[], result: {
+        exitCode: number;
+        stderr: string;
+    });
+}

package/dist/sbx-error.js

@@ -0,0 +1,14 @@
+/** An `sbx` command exited with a non-zero status. */
+export class SbxError extends Error {
+    /** The `sbx` sub-command and its arguments, as they were passed. */
+    args;
+    exitCode;
+    stderr;
+    constructor(args, result) {
+        super(`\`sbx ${args[0] ?? ''}\` exited with ${result.exitCode}: ${result.stderr.trim()}`);
+        this.name = 'SbxError';
+        this.args = args;
+        this.exitCode = result.exitCode;
+        this.stderr = result.stderr;
+    }
+}

package/dist/sbx-network-sandbox-session.d.ts

@@ -0,0 +1,74 @@
+import type { HarnessV1NetworkSandboxSession, HarnessV1PortEndpoint, HarnessV1RequestTransformation } from '@ai-sdk/harness';
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import type { SbxSandboxHandle } from './sbx-sandbox-session.js';
+import { SbxSandboxSession } from './sbx-sandbox-session.js';
+export { SBX_SANDBOX_PROVIDER_ID } from './credential-broker.js';
+type Protocol = 'http' | 'https' | 'ws';
+/**
+ * The whole of a Docker Sandbox, as `HarnessAgent.createSession({ sandboxSession })` expects it:
+ * files and processes, plus the ports a harness bridge listens on and the credentials the sandbox
+ * must never see.
+ *
+ * - **Ports** are published the first time the harness asks for them: on this host's loopback for
+ *   a local sandbox, at the public URL the control plane assigns for a cloud one.
+ * - **Credentials** stay out of the sandbox. Each request transformation the harness asks for
+ *   becomes a custom secret of the Docker Sandboxes proxy, scoped to this sandbox: the value only
+ *   exists on the host and in the proxy.
+ *
+ * Obtain one from `createSbxNetworkSandboxSession()` or `resumeSbxNetworkSandboxSession()`.
+ */
+export declare class SbxNetworkSandboxSession extends SbxSandboxSession implements HarnessV1NetworkSandboxSession {
+    readonly id: string;
+    readonly defaultWorkingDirectory: string;
+    /** Absent when brokering is off: the harness then forwards the real credential instead. */
+    readonly addRequestTransformations?: (transformations: ReadonlyArray<HarnessV1RequestTransformation>) => Promise<void>;
+    /** Absent when brokering is off, like {@link addRequestTransformations}. */
+    readonly setRequestTransformations?: (transformations: ReadonlyArray<HarnessV1RequestTransformation>) => Promise<void>;
+    /** Whether the sandbox runs in Docker Sandboxes Cloud rather than on this host. */
+    readonly cloud: boolean;
+    private exposed;
+    private readonly broker;
+    private readonly publisher;
+    /** Sandbox port → where it is published. */
+    private readonly published;
+    constructor(handle: SbxSandboxHandle, ports: readonly number[], brokerCredentials: boolean);
+    /** Ports the sandbox exposes, resolvable with {@link getPortEndpoint}. */
+    get ports(): readonly number[];
+    restricted: () => SandboxSession;
+    getPortEndpoint: ({ port, protocol, }: {
+        port: number;
+        protocol?: Protocol;
+    }) => Promise<HarnessV1PortEndpoint>;
+    /** @deprecated Use {@link getPortEndpoint}. */
+    getPortUrl: (options: {
+        port: number;
+        protocol?: Protocol;
+    }) => Promise<string>;
+    /** Replaces the exposed ports; a port left out is unpublished. */
+    setPorts: (ports: ReadonlyArray<number>) => Promise<void>;
+    /**
+     * Hands the sandbox back without stopping it: the processes this session started are stopped,
+     * its ports unpublished and its secrets withdrawn from the proxy. What an application that
+     * keeps one sandbox across harness sessions calls between them.
+     */
+    release: () => Promise<void>;
+    /**
+     * Stops every process any session started in this sandbox, including those a previous run of the
+     * application left behind, such as a harness bridge still holding its port. Call it right after
+     * resuming a sandbox no other process uses.
+     */
+    killAllProcesses: () => Promise<void>;
+    /**
+     * Extends the time-to-live of a cloud sandbox by `duration` (`30m`, `2h`), within the 24 hours
+     * after its creation the platform allows. Local sandboxes have no time-to-live.
+     */
+    extendTtl: (duration: string) => Promise<void>;
+    /**
+     * Stops the sandbox, keeping it for the next `sbx exec`: a local microVM keeps its filesystem, a
+     * cloud one is suspended with its memory. Idempotent.
+     */
+    stop: () => Promise<void>;
+    /** Removes the sandbox, with its filesystem and the secrets scoped to it. Idempotent. */
+    destroy: () => Promise<void>;
+    private unpublish;
+}