@tangle-network/agent-provider-cli-bridge 2.0.3 → 2.0.5

package/README.md

@@ -195,3 +195,21 @@ Those five surfaces are never claimed in the capability document and always carr
 The usage of one run is summed across its events and attributed to that run's execution id, which the observation carries as the provenance source.
 An environment rebuilt with `provider.get(id)` has measured nothing yet, so it reports the usage surface as unavailable until a turn completes through it.
 The endpoint holds only a scheme, a host, and an explicit port; userinfo, path, and query are dropped, and the bearer beside the base URL is never read.
+
+## Cloud sandboxes (`./sandbox`)
+
+`@tangle-network/agent-provider-cli-bridge/sandbox` turns a vendor sandbox that runs CLI Bridge into an `AgentEnvironmentProvider`.
+The vendor adapter implements `BridgeSandboxVendor`: `create`, `connect`, `list`, and per sandbox `exec`, `spawn`, `read`, `write`, `endpoint`, `status` and `destroy`.
+`createBridgeSandboxProvider({ vendor, router: { key } })` does the rest:
+
+- It refuses every create field the vendor cannot honor with an `EnvironmentProviderError` that names the field, before any vendor call, and validates the profile with the materializer the Bridge in the box uses.
+- It creates the sandbox from the box image with a finite lifetime and a run tag, starts the Bridge with a random bearer and the per-run Router key on that process only, waits for the selected backend to report ready, checks the harness CLI against the registry's pin, clones `workspace.repoUrl`, and creates the environment through `createCliBridgeProvider` at the exposed URL.
+- Any failure after the vendor create destroys the sandbox before the error surfaces; a destroy that fails carries the sandbox id as `cleanupHandle`.
+- Turns run through the Bridge. `turn.timeoutMs` cancels the run and ends the stream with a failed `result` that names the timeout, an abort rejects with `AbortError`, and a second turn on a busy environment is refused with `conflict`.
+- Events carry `execution.started` with the declared model and a terminal `result` with the model the harness reported serving. The Bridge's dollar figure is the harness's catalog estimate, so events omit `usage.cost`.
+
+The box image is `renderBoxDockerfile()`: Node, CLI Bridge at the commit in `BOX_PINS`, and each harness CLI at the version `@tangle-network/cli-agent-registry` pins.
+A harness joins `BOX_HARNESSES` only after a live turn through the Router completed in a box; `claude-code` is the proven row.
+Build the image for a cloud with `pnpm build:sandbox-image --target e2b|daytona|docker` from the repository root.
+`@tangle-network/agent-provider-testkit` runs the live profile conformance suite against the result.
+

package/dist/sandbox/box.d.ts

@@ -0,0 +1,62 @@
+import type { HarnessType } from "@tangle-network/agent-interface";
+/**
+ * The box: one image every cloud runs, holding Node, CLI Bridge and the pinned
+ * harness CLIs. The Bridge listens on {@link BRIDGE_PORT}, materializes the
+ * exact profile and starts the selected harness exactly as it does for Braid
+ * on a local machine.
+ */
+export declare const BRIDGE_PORT = 3344;
+/** The box user's home. */
+export declare const BOX_HOME = "/home/node";
+/** The default workspace directory; `workspace.cwd` with `base: "repository"` resolves under it. */
+export declare const BOX_WORKSPACE_DIR = "/home/node/workspace";
+export declare const BRIDGE_DATA_DIR = "/home/node/.cli-bridge";
+export declare const BOX_NODE_IMAGE = "node:24.22.1-trixie-slim";
+/**
+ * The CLI Bridge source revision the box installs, reviewed as a commit.
+ * `agentProfileMaterialize` is the exact version of the planner that revision
+ * pins; {@link createBridgeSandboxProvider} plans with the same version, and
+ * the image build refuses a revision whose pin differs.
+ */
+export declare const BOX_PINS: {
+    readonly cliBridgeRepository: "drewstone/cli-bridge";
+    readonly cliBridgeCommit: "263f700dc5ca8b7b6e53b986d376102e0d82b42f";
+    readonly agentProfileMaterialize: "1.1.4";
+};
+/** The E2B template and Daytona snapshot name `pnpm build:sandbox-image` publishes for these pins. */
+export declare const BOX_TEMPLATE_NAME: string;
+export interface BoxRouter {
+    /** Router root URL, without a path. */
+    baseUrl: string;
+    /** The per-run capped Router key. */
+    key: string;
+}
+/**
+ * A harness the box carries and routes through the Tangle Router.
+ *
+ * A harness joins this table only after a live turn through the Router
+ * completed in a box, so the declared set is the proven set.
+ */
+export interface BoxHarness {
+    readonly harness: HarnessType;
+    /** The Bridge backend name in `BRIDGE_BACKENDS`. */
+    readonly bridgeBackend: string;
+    /** The npm package that installs the CLI. */
+    readonly npmPackage: string;
+    /** The CLI binary; `<bin> --version` prints the pinned version first. */
+    readonly bin: string;
+    /** Environment that points this harness at the Router, set on the Bridge process only. */
+    routerEnv(router: BoxRouter): Record<string, string>;
+}
+export declare const BOX_HARNESSES: Readonly<Partial<Record<HarnessType, BoxHarness>>>;
+export declare function boxHarness(harness: string | undefined): BoxHarness | undefined;
+/** The CLI version the harness registry pins; the box image installs exactly this. */
+export declare function boxHarnessVersion(harness: HarnessType): string;
+/** The command that starts the Bridge; its settings come from the process environment. */
+export declare const BRIDGE_START_COMMAND = "cli-bridge";
+/**
+ * The Bridge process environment. `bearer` guards the exposed port; the Router
+ * variables reach the harness through the Bridge's child environment and
+ * appear in no command line or file.
+ */
+export declare function bridgeProcessEnv(harness: BoxHarness, bearer: string, router: BoxRouter): Record<string, string>;

package/dist/sandbox/box.js

@@ -0,0 +1,70 @@
+import { NATIVE_SESSION_CONTRACTS } from "@tangle-network/cli-agent-registry/native-session-contracts";
+/**
+ * The box: one image every cloud runs, holding Node, CLI Bridge and the pinned
+ * harness CLIs. The Bridge listens on {@link BRIDGE_PORT}, materializes the
+ * exact profile and starts the selected harness exactly as it does for Braid
+ * on a local machine.
+ */
+export const BRIDGE_PORT = 3344;
+/** The box user's home. */
+export const BOX_HOME = "/home/node";
+/** The default workspace directory; `workspace.cwd` with `base: "repository"` resolves under it. */
+export const BOX_WORKSPACE_DIR = `${BOX_HOME}/workspace`;
+export const BRIDGE_DATA_DIR = `${BOX_HOME}/.cli-bridge`;
+export const BOX_NODE_IMAGE = "node:24.22.1-trixie-slim";
+/**
+ * The CLI Bridge source revision the box installs, reviewed as a commit.
+ * `agentProfileMaterialize` is the exact version of the planner that revision
+ * pins; {@link createBridgeSandboxProvider} plans with the same version, and
+ * the image build refuses a revision whose pin differs.
+ */
+export const BOX_PINS = {
+    cliBridgeRepository: "drewstone/cli-bridge",
+    cliBridgeCommit: "263f700dc5ca8b7b6e53b986d376102e0d82b42f",
+    agentProfileMaterialize: "1.1.4",
+};
+/** The E2B template and Daytona snapshot name `pnpm build:sandbox-image` publishes for these pins. */
+export const BOX_TEMPLATE_NAME = `tangle-cli-bridge-box-${BOX_PINS.cliBridgeCommit.slice(0, 12)}`;
+export const BOX_HARNESSES = {
+    "claude-code": {
+        harness: "claude-code",
+        bridgeBackend: "claude",
+        npmPackage: "@anthropic-ai/claude-code",
+        bin: "claude",
+        // The Router authenticates a Bearer token. ANTHROPIC_API_KEY sends x-api-key, which it rejects.
+        routerEnv: (router) => ({
+            ANTHROPIC_BASE_URL: router.baseUrl,
+            ANTHROPIC_AUTH_TOKEN: router.key,
+        }),
+    },
+};
+export function boxHarness(harness) {
+    return harness === undefined ? undefined : BOX_HARNESSES[harness];
+}
+/** The CLI version the harness registry pins; the box image installs exactly this. */
+export function boxHarnessVersion(harness) {
+    const contract = NATIVE_SESSION_CONTRACTS[harness];
+    if (contract?.cliVersion === undefined) {
+        throw new Error(`cli-agent-registry pins no CLI version for harness ${harness}`);
+    }
+    return contract.cliVersion;
+}
+/** The command that starts the Bridge; its settings come from the process environment. */
+export const BRIDGE_START_COMMAND = "cli-bridge";
+/**
+ * The Bridge process environment. `bearer` guards the exposed port; the Router
+ * variables reach the harness through the Bridge's child environment and
+ * appear in no command line or file.
+ */
+export function bridgeProcessEnv(harness, bearer, router) {
+    return {
+        BRIDGE_HOST: "0.0.0.0",
+        BRIDGE_PORT: String(BRIDGE_PORT),
+        BRIDGE_BEARER: bearer,
+        BRIDGE_BACKENDS: harness.bridgeBackend,
+        BRIDGE_DATA_DIR: BRIDGE_DATA_DIR,
+        BRIDGE_JAIL_MODE: "off",
+        HOME: BOX_HOME,
+        ...harness.routerEnv(router),
+    };
+}

package/dist/sandbox/image.d.ts

@@ -0,0 +1,9 @@
+import type { HarnessType } from "@tangle-network/agent-interface";
+/**
+ * The box image as one Dockerfile.
+ *
+ * Every cloud builds from this text: E2B and Daytona build their template and
+ * image from it, and a local Docker build of it is the same box. Harness
+ * versions come from the registry that owns the pins.
+ */
+export declare function renderBoxDockerfile(harnesses?: readonly HarnessType[]): string;

package/dist/sandbox/image.js

@@ -0,0 +1,31 @@
+import { BOX_HARNESSES, BOX_HOME, BOX_NODE_IMAGE, BOX_PINS, BOX_WORKSPACE_DIR, boxHarnessVersion } from "./box.js";
+/**
+ * The box image as one Dockerfile.
+ *
+ * Every cloud builds from this text: E2B and Daytona build their template and
+ * image from it, and a local Docker build of it is the same box. Harness
+ * versions come from the registry that owns the pins.
+ */
+export function renderBoxDockerfile(harnesses = Object.keys(BOX_HARNESSES)) {
+    const installs = harnesses.map((name) => {
+        const entry = BOX_HARNESSES[name];
+        if (entry === undefined)
+            throw new Error(`harness ${name} is not in the box harness table`);
+        return { entry, version: boxHarnessVersion(name) };
+    });
+    const bridge = `https://github.com/${BOX_PINS.cliBridgeRepository}/archive/${BOX_PINS.cliBridgeCommit}.tar.gz`;
+    const packages = installs.map(({ entry, version }) => `${entry.npmPackage}@${version}`);
+    const probes = installs.map(({ entry, version }) => `test "$(${entry.bin} --version | cut -d' ' -f1)" = "${version}"`);
+    return [
+        `FROM ${BOX_NODE_IMAGE}`,
+        "RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates python3 make g++ ripgrep procps \\",
+        "    && rm -rf /var/lib/apt/lists/*",
+        `RUN npm install -g ${[...packages, bridge].join(" ")} \\`,
+        `    && ${[...probes, "command -v cli-bridge >/dev/null"].join(" \\\n    && ")}`,
+        `RUN mkdir -p ${BOX_WORKSPACE_DIR} && chown -R node:node ${BOX_HOME}`,
+        "USER node",
+        `ENV HOME=${BOX_HOME}`,
+        `WORKDIR ${BOX_WORKSPACE_DIR}`,
+        "",
+    ].join("\n");
+}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,6 @@
+export { createBridgeSandboxProvider, BRIDGE_RUN_TAG } from "./provider.js";
+export type { BridgeSandboxProviderOptions } from "./provider.js";
+export type { BridgeSandbox, BridgeSandboxCreateRequest, BridgeSandboxSummary, BridgeSandboxVendor, BridgeVendorSupport, } from "./vendor.js";
+export { validateBoxProfile } from "./refusal.js";
+export { BOX_HARNESSES, BOX_HOME, BOX_PINS, BOX_TEMPLATE_NAME, BOX_WORKSPACE_DIR, BRIDGE_PORT, boxHarnessVersion, } from "./box.js";
+export { renderBoxDockerfile } from "./image.js";

package/dist/sandbox/index.js

@@ -0,0 +1,4 @@
+export { createBridgeSandboxProvider, BRIDGE_RUN_TAG } from "./provider.js";
+export { validateBoxProfile } from "./refusal.js";
+export { BOX_HARNESSES, BOX_HOME, BOX_PINS, BOX_TEMPLATE_NAME, BOX_WORKSPACE_DIR, BRIDGE_PORT, boxHarnessVersion, } from "./box.js";
+export { renderBoxDockerfile } from "./image.js";

package/dist/sandbox/provider.d.ts

@@ -0,0 +1,23 @@
+import { type HarnessType } from "@tangle-network/agent-interface";
+import { type AgentEnvironmentProvider } from "@tangle-network/agent-interface/environment-provider";
+import type { BridgeSandboxVendor } from "./vendor.js";
+export declare const BRIDGE_RUN_TAG = "tangle-bridge-run";
+export interface BridgeSandboxProviderOptions {
+    vendor: BridgeSandboxVendor;
+    /** The Router that serves the model, with the per-run capped key. The key reaches the Bridge process only. */
+    router: {
+        key: string | (() => string | Promise<string>);
+        baseUrl?: string;
+    };
+    /** Harnesses this provider accepts. Defaults to every harness in the box table. */
+    harnesses?: readonly HarnessType[];
+    /** Finite sandbox lifetime the vendor enforces. Must exceed the longest turn plus capture. */
+    lifetimeMs?: number;
+    readyTimeoutMs?: number;
+}
+/**
+ * An {@link AgentEnvironmentProvider} for a vendor cloud: each environment is a
+ * vendor sandbox created from the box image, running CLI Bridge, and every turn
+ * is delegated to {@link createCliBridgeProvider} at the sandbox's exposed URL.
+ */
+export declare function createBridgeSandboxProvider(options: BridgeSandboxProviderOptions): AgentEnvironmentProvider;

package/dist/sandbox/provider.js

@@ -0,0 +1,472 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { posix } from "node:path";
+import { Agent, fetch as undiciFetch } from "undici";
+import { canonicalAgentProfileDigest, TANGLE_ROUTER_DEFAULT_ROOT_URL, } from "@tangle-network/agent-interface";
+import { AgentEnvironmentGetOptionsSchema, AgentTurnInputSchema, EnvironmentProviderError, } from "@tangle-network/agent-interface/environment-provider";
+import { harnessModelSupportFor } from "@tangle-network/cli-agent-registry";
+import { createCliBridgeProvider, defaultCliBridgeCapabilities } from "../index.js";
+import { BOX_WORKSPACE_DIR, BRIDGE_PORT, BRIDGE_START_COMMAND, bridgeProcessEnv, boxHarness, boxHarnessVersion, } from "./box.js";
+import { assertProfileValid, declarableHarnesses, plannerLowers, refuseUnsupportedCreateInput, resolveBoxHarness, validateBoxProfile } from "./refusal.js";
+export const BRIDGE_RUN_TAG = "tangle-bridge-run";
+const DEFAULT_LIFETIME_MS = 2 * 60 * 60 * 1000;
+const DEFAULT_READY_TIMEOUT_MS = 120_000;
+const UNSUPPORTED_TURN_FIELDS = [
+    "contextTransfer",
+    "nativeContinuation",
+    "nativeResume",
+    "interactions",
+    "controlRef",
+    "lastEventId",
+];
+/**
+ * An {@link AgentEnvironmentProvider} for a vendor cloud: each environment is a
+ * vendor sandbox created from the box image, running CLI Bridge, and every turn
+ * is delegated to {@link createCliBridgeProvider} at the sandbox's exposed URL.
+ */
+export function createBridgeSandboxProvider(options) {
+    const { vendor } = options;
+    const declared = options.harnesses ?? declarableHarnesses();
+    const supported = new Set(declarableHarnesses());
+    for (const harness of declared) {
+        if (!supported.has(harness))
+            throw new Error(`harness ${harness} is not in the box harness table`);
+    }
+    const routerBaseUrl = (options.router.baseUrl ?? TANGLE_ROUTER_DEFAULT_ROOT_URL).replace(/\/+$/, "");
+    const lifetimeMs = options.lifetimeMs ?? DEFAULT_LIFETIME_MS;
+    const readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+    const providerCapabilities = (harness) => environmentCapabilities(defaultCliBridgeCapabilities(harness), vendor, harness === undefined ? false : plannerLowers(harness, "hooks"));
+    async function create(input) {
+        input.signal?.throwIfAborted();
+        refuseUnsupportedCreateInput(input, vendor.support);
+        const profile = input.profile;
+        const validation = validateBoxProfile(profile, input.backend, declared);
+        assertProfileValid(validation);
+        const harness = resolveBoxHarness(profile, input.backend, declared);
+        const box = boxHarness(harness);
+        const runTag = randomUUID();
+        const bearer = randomBytes(32).toString("hex");
+        const routerKey = typeof options.router.key === "function" ? await options.router.key() : options.router.key;
+        const secrets = [bearer, routerKey];
+        const workspaceDir = repositoryCwd(input);
+        let sandbox;
+        let dispatcher;
+        try {
+            sandbox = await vendor.create({
+                ...(input.name === undefined ? {} : { name: input.name }),
+                metadata: { ...stringMetadata(input.metadata), [BRIDGE_RUN_TAG]: runTag },
+                env: input.env ?? {},
+                lifetimeMs,
+                ...(input.workspace?.environment === undefined ? {} : { environment: input.workspace.environment }),
+                ...(input.workspace?.image === undefined ? {} : { image: input.workspace.image }),
+                ...(input.resources === undefined ? {} : { resources: input.resources }),
+                ...(input.egress === undefined ? {} : { egress: egressFor(input, routerBaseUrl) }),
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+            input.signal?.throwIfAborted();
+            await sandbox.spawn(BRIDGE_START_COMMAND, {
+                cwd: BOX_WORKSPACE_DIR,
+                env: bridgeProcessEnv(box, bearer, { baseUrl: routerBaseUrl, key: routerKey }),
+            });
+            const endpoint = await sandbox.endpoint(BRIDGE_PORT, signalOption(input.signal));
+            dispatcher = new Agent({ headersTimeout: 0, bodyTimeout: 0 });
+            const bridgeFetch = vendorFetch(endpoint.headers ?? {}, dispatcher);
+            await waitForBridge(endpoint.url, bearer, bridgeFetch, box.bridgeBackend, readyTimeoutMs, input.signal, secrets);
+            await assertHarnessVersion(sandbox, harness, input.signal);
+            await cloneRepository(sandbox, input, secrets);
+            await ensureDirectory(sandbox, workspaceDir);
+            const bridge = createCliBridgeProvider({
+                baseUrl: endpoint.url,
+                bearerToken: bearer,
+                fetch: bridgeFetch,
+                name: vendor.name,
+            });
+            const { workspace: _workspace, egress: _egress, resources: _resources, ...forwarded } = input;
+            const inner = await bridge.create({
+                ...forwarded,
+                backend: harness,
+                requestedId: sandbox.id,
+                workspace: { cwd: { base: "host", path: workspaceDir } },
+            });
+            input.signal?.throwIfAborted();
+            return wrapEnvironment({ inner, sandbox, vendor, harness, profile, workspaceDir, dispatcher, capabilities: environmentCapabilities(inner.capabilities ?? providerCapabilities(harness), vendor, plannerLowers(harness, "hooks")), input });
+        }
+        catch (error) {
+            await dispatcher?.close().catch(() => undefined);
+            throw await failAfterProvision(error, sandbox, vendor.name, secrets);
+        }
+    }
+    return {
+        name: vendor.name,
+        capabilities: () => providerCapabilities(declared.length === 1 ? declared[0] : undefined),
+        validateProfile(ref) {
+            if (typeof ref === "string") {
+                return { ok: false, issues: [{ level: "error", code: "named_profile_refused", path: "profile", message: `named profile ${ref} is unsupported; pass an inline AgentProfile` }] };
+            }
+            return validateBoxProfile(ref, undefined, declared);
+        },
+        create,
+        async get(id, getOptions) {
+            assertGetOptionsSupported(getOptions);
+            AgentEnvironmentGetOptionsSchema.parse(getOptions ?? {});
+            getOptions?.signal?.throwIfAborted();
+            const sandbox = await vendor.connect(id, signalOption(getOptions?.signal));
+            if (sandbox === null)
+                return null;
+            if (sandbox.id !== id) {
+                throw new EnvironmentProviderError("transport", `vendor returned sandbox ${sandbox.id} for ${id}`, { provider: vendor.name });
+            }
+            return reconstructedEnvironment(sandbox, vendor, providerCapabilities());
+        },
+        async list(query, listOptions) {
+            const summaries = await vendor.list({
+                ...(query?.name === undefined ? {} : { name: query.name }),
+                ...(query?.metadata === undefined ? {} : { metadata: stringMetadata(query.metadata) }),
+            }, signalOption(listOptions?.signal));
+            return summaries.map((summary) => ({
+                id: summary.id,
+                provider: vendor.name,
+                status: summary.status,
+                ...(summary.name === undefined ? {} : { name: summary.name }),
+                metadata: summary.metadata,
+            }));
+        },
+    };
+}
+function signalOption(signal) {
+    return signal === undefined ? {} : { signal };
+}
+function stringMetadata(metadata) {
+    const out = {};
+    for (const [key, value] of Object.entries(metadata ?? {})) {
+        if (typeof value !== "string") {
+            throw new EnvironmentProviderError("refused", `vendor tags hold string values; ${key} is not a string`, { path: `metadata.${key}` });
+        }
+        out[key] = value;
+    }
+    return out;
+}
+function repositoryCwd(input) {
+    const cwd = input.workspace?.cwd;
+    return cwd === undefined || cwd.path === "." ? BOX_WORKSPACE_DIR : posix.join(BOX_WORKSPACE_DIR, cwd.path);
+}
+function egressFor(input, routerBaseUrl) {
+    const policy = input.egress;
+    const routerHost = new URL(routerBaseUrl).host;
+    const allowed = policy.mode === "strict"
+        ? (policy.allowDomains ?? []).map((entry) => (typeof entry === "string" ? entry : entry.domain))
+        : [];
+    return { mode: policy.mode, allowDomains: policy.mode === "strict" ? [...new Set([...allowed, routerHost])] : allowed };
+}
+/** Requests to the Bridge carry the vendor gateway's headers and no timeouts, because a turn streams for minutes. */
+function vendorFetch(headers, dispatcher) {
+    return ((input, init) => undiciFetch(input, {
+        ...init,
+        headers: { ...headers, ...init?.headers },
+        dispatcher,
+    }));
+}
+async function waitForBridge(baseUrl, bearer, bridgeFetch, backend, timeoutMs, signal, secrets) {
+    const deadline = Date.now() + timeoutMs;
+    let last = "no response";
+    while (Date.now() < deadline) {
+        signal?.throwIfAborted();
+        try {
+            const response = await bridgeFetch(`${baseUrl.replace(/\/+$/, "")}/health`, {
+                headers: { authorization: `Bearer ${bearer}` },
+                signal: AbortSignal.timeout(5_000),
+            });
+            if (response.ok) {
+                const health = (await response.json());
+                const state = health.backends?.find((entry) => entry.name !== undefined && (entry.name === backend || entry.name.startsWith(backend)))?.state;
+                if (state === "ready")
+                    return;
+                if (state !== undefined && state !== "probing") {
+                    throw new EnvironmentProviderError("materialization_failed", `cli-bridge reports the ${backend} backend ${state}`, { secrets });
+                }
+                last = `backend ${state ?? "absent"}`;
+            }
+            else {
+                last = `health status ${response.status}`;
+                if (response.status === 401 || response.status === 403) {
+                    throw new EnvironmentProviderError("auth_failed", `cli-bridge health answered ${response.status}`, { status: response.status, secrets });
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof EnvironmentProviderError || signal?.aborted)
+                throw error;
+            last = error instanceof Error ? error.message : String(error);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    throw new EnvironmentProviderError("provision_failed", `cli-bridge was not ready within ${timeoutMs} ms (${last})`, { secrets });
+}
+async function assertHarnessVersion(sandbox, harness, signal) {
+    const box = boxHarness(harness);
+    const pinned = boxHarnessVersion(harness);
+    const result = await sandbox.exec(`${box.bin} --version`, { ...signalOption(signal), timeoutMs: 30_000 });
+    if (result.exitCode !== 0 || result.stdout.trim().split(/\s+/)[0] !== pinned) {
+        throw new EnvironmentProviderError("materialization_failed", `${box.bin} --version reported "${result.stdout.trim() || result.stderr.trim()}" (exit ${result.exitCode}); the registry pins ${pinned}`);
+    }
+}
+async function cloneRepository(sandbox, input, secrets) {
+    const repoUrl = input.workspace?.repoUrl;
+    if (repoUrl === undefined)
+        return;
+    const gitRef = input.workspace?.gitRef;
+    const quote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+    const command = [
+        `rm -rf ${quote(BOX_WORKSPACE_DIR)}/.git`,
+        `git clone ${quote(repoUrl)} ${quote(BOX_WORKSPACE_DIR)}.clone`,
+        ...(gitRef === undefined ? [] : [`git -C ${quote(BOX_WORKSPACE_DIR)}.clone checkout ${quote(gitRef)}`]),
+        `cp -a ${quote(BOX_WORKSPACE_DIR)}.clone/. ${quote(BOX_WORKSPACE_DIR)}/ && rm -rf ${quote(BOX_WORKSPACE_DIR)}.clone`,
+    ].join(" && ");
+    const result = await sandbox.exec(command, { timeoutMs: 600_000, ...signalOption(input.signal) });
+    if (result.exitCode !== 0) {
+        throw new EnvironmentProviderError("provision_failed", `cloning ${repoUrl} failed (exit ${result.exitCode}): ${result.stderr.trim().slice(0, 400)}`, { path: "workspace.repoUrl", secrets });
+    }
+}
+async function ensureDirectory(sandbox, directory) {
+    const result = await sandbox.exec(`mkdir -p '${directory.replace(/'/g, `'\\''`)}'`, { timeoutMs: 30_000 });
+    if (result.exitCode !== 0) {
+        throw new EnvironmentProviderError("provision_failed", `cannot create workspace directory ${directory}: ${result.stderr.trim().slice(0, 200)}`, { path: "workspace.cwd" });
+    }
+}
+/** Destroy the sandbox a failed create left behind; a destroy that fails names the sandbox as a cleanup handle. */
+async function failAfterProvision(error, sandbox, provider, secrets) {
+    const original = error instanceof EnvironmentProviderError || isAbort(error) ? error : new EnvironmentProviderError("provision_failed", error instanceof Error ? error.message : String(error), { cause: error, provider, secrets });
+    if (sandbox === undefined)
+        return original;
+    try {
+        await sandbox.destroy();
+        return original;
+    }
+    catch (cleanup) {
+        return new EnvironmentProviderError("cleanup_failed", `create failed (${original instanceof Error ? original.message : String(original)}) and sandbox ${sandbox.id} could not be destroyed`, { cause: new AggregateError([original, cleanup]), provider, secrets, cleanupHandle: { environmentId: sandbox.id, provider } });
+    }
+}
+function isAbort(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+function assertGetOptionsSupported(options) {
+    if (options === undefined || options === null)
+        return;
+    for (const key of ["readOnly", "proxySecrets", "proxySecretParents", "expectedProxySecretGeneration", "requireInPlace", "contextTransfer"]) {
+        if (key in options) {
+            throw new EnvironmentProviderError("refused", `get does not honor ${key}`, { path: key });
+        }
+    }
+}
+/** The document for one environment: what the Bridge claims, plus the vendor sandbox's workspace and placement. */
+function environmentCapabilities(bridge, vendor, hooks) {
+    const { retainedControl: _retained, nativeContinuation: _native, contextTransfer: _transfer, interactions: _interactions, observation: _observation, ...base } = bridge;
+    return {
+        ...base,
+        profile: { ...base.profile, validation: true, hooks: hooks === true },
+        workspace: { read: true, write: true, exec: true, git: false, upload: false, download: false, cwdBases: { repository: true, host: false } },
+        placement: true,
+        create: {
+            durableIdempotency: false,
+            ...(vendor.support.egress.length === 0 ? {} : { egress: [...vendor.support.egress] }),
+        },
+    };
+}
+function sandboxOperations(sandbox, vendor, workspaceDir) {
+    const resolve = (path) => (path.startsWith("/") ? path : posix.join(workspaceDir, path));
+    return {
+        read: (path, options) => sandbox.read(resolve(path), options),
+        write: (path, content, options) => sandbox.write(resolve(path), content, options),
+        exec: (command, options) => sandbox.exec(command, { ...options, cwd: options?.cwd === undefined ? workspaceDir : resolve(options.cwd) }),
+        placement: async () => ({
+            kind: "provider",
+            sandboxId: sandbox.id,
+            ...(sandbox.region === undefined ? {} : { region: sandbox.region }),
+            providerMetadata: { vendor: vendor.name },
+        }),
+        async status(options) {
+            return sandbox.status(options);
+        },
+    };
+}
+function wrapEnvironment(args) {
+    const { inner, sandbox, vendor, workspaceDir } = args;
+    const operations = sandboxOperations(sandbox, vendor, workspaceDir);
+    const createDigest = canonicalAgentProfileDigest(args.profile);
+    let busy = false;
+    let destroyPromise;
+    const guard = (turn) => {
+        const result = AgentTurnInputSchema.safeParse(turn);
+        if (!result.success) {
+            const issue = result.error.issues[0];
+            throw new EnvironmentProviderError("invalid_input", issue?.message ?? "invalid turn input", { path: `turn.${(issue?.path ?? []).join(".")}`.replace(/\.$/, ""), cause: result.error });
+        }
+        const parsed = result.data;
+        for (const field of UNSUPPORTED_TURN_FIELDS) {
+            if (parsed[field] !== undefined) {
+                throw new EnvironmentProviderError("refused", `this environment does not honor turn.${field}`, { path: `turn.${field}` });
+            }
+        }
+        const turnProfile = parsed.profile ?? parsed.providerOptions?.backend?.profile;
+        if (turnProfile !== undefined && canonicalAgentProfileDigest(turnProfile) !== createDigest) {
+            throw new EnvironmentProviderError("refused", "a turn profile that differs from the create profile is refused, never run under the old profile", { path: "turn.profile" });
+        }
+        if (parsed.model !== undefined) {
+            const support = harnessModelSupportFor(args.harness, parsed.model);
+            if (!support.supported)
+                throw new EnvironmentProviderError("refused", support.message, { path: "turn.model" });
+        }
+        return turn;
+    };
+    const exclusive = async function* (turn) {
+        const checked = guard(turn);
+        if (checked.detach === true) {
+            throw new EnvironmentProviderError("refused", "stream does not honor detach; use dispatch", { path: "turn.detach" });
+        }
+        if (busy)
+            throw new EnvironmentProviderError("conflict", "a turn is already running on this environment", { provider: vendor.name });
+        busy = true;
+        try {
+            yield* projectTurn(inner, checked, checked.model ?? args.profile.model?.default);
+        }
+        catch (error) {
+            // An aborted turn rejects with AbortError whatever the Bridge says about confirming the cancel; the Bridge's error stays as the cause.
+            if (checked.signal?.aborted === true && !isAbort(error)) {
+                throw new DOMException("turn aborted", { name: "AbortError", cause: error });
+            }
+            throw error;
+        }
+        finally {
+            busy = false;
+        }
+    };
+    return {
+        id: sandbox.id,
+        provider: vendor.name,
+        creation: "created",
+        ...(inner.name === undefined ? {} : { name: inner.name }),
+        capabilities: args.capabilities,
+        status: operations.status,
+        stream: exclusive,
+        ...(inner.session === undefined ? {} : { session: (id, options) => inner.session(id, options) }),
+        ...(inner.dispatch === undefined
+            ? {}
+            : {
+                async dispatch(turn) {
+                    const checked = guard(turn);
+                    if (busy)
+                        throw new EnvironmentProviderError("conflict", "a turn is already running on this environment", { provider: vendor.name });
+                    return inner.dispatch(checked);
+                },
+            }),
+        read: operations.read,
+        write: operations.write,
+        exec: operations.exec,
+        placement: operations.placement,
+        destroy(options) {
+            destroyPromise ??= (async () => {
+                try {
+                    await inner.destroy?.(options).catch(() => undefined);
+                }
+                finally {
+                    await sandbox.destroy(options);
+                    await args.dispatcher.close().catch(() => undefined);
+                }
+            })().catch((error) => {
+                destroyPromise = undefined;
+                throw error;
+            });
+            return destroyPromise;
+        },
+    };
+}
+const isTerminalResult = (event) => event.type === "result";
+/** The Bridge's own dollar figure is the harness's catalog estimate, never a receipt, so no event carries it. */
+function withoutHarnessCost(event) {
+    if (event.usage?.cost === undefined)
+        return event;
+    const { cost: _cost, ...usage } = event.usage;
+    return { ...event, usage };
+}
+/** The model the harness reported serving, read from the Bridge's terminal frame. */
+function reportedModel(event) {
+    const models = event.data.provider_models;
+    const reported = event.data.provider_model ?? (Array.isArray(models) ? models[0] : undefined);
+    return typeof reported === "string" ? reported : undefined;
+}
+/**
+ * One turn as the contract states it: an `execution.started` event naming the
+ * declared model, the Bridge's events without harness dollar estimates, a
+ * terminal `result` that names the model the harness reported serving, and
+ * `turn.timeoutMs` ending the run (the Bridge cancels it, and a failed terminal
+ * event names the timeout and carries the usage observed so far).
+ */
+async function* projectTurn(inner, turn, declaredModel) {
+    const { timeoutMs, ...rest } = turn;
+    yield {
+        type: "execution.started",
+        data: { ...(rest.sessionId === undefined ? {} : { sessionId: rest.sessionId }), effectiveBackend: { ...(declaredModel === undefined ? {} : { model: declaredModel }), source: "profile" } },
+    };
+    const timeout = new AbortController();
+    let timedOut = false;
+    const timer = timeoutMs === undefined ? undefined : setTimeout(() => {
+        timedOut = true;
+        timeout.abort(new DOMException(`turn exceeded ${timeoutMs} ms`, "TimeoutError"));
+    }, timeoutMs);
+    const signal = rest.signal === undefined ? timeout.signal : AbortSignal.any([rest.signal, timeout.signal]);
+    let lastUsage;
+    try {
+        for await (const raw of inner.stream({ ...rest, signal })) {
+            const event = withoutHarnessCost(raw);
+            if (event.usage !== undefined)
+                lastUsage = event;
+            if (!isTerminalResult(event)) {
+                yield event;
+                continue;
+            }
+            const served = reportedModel(event);
+            yield served === undefined ? event : { ...event, data: { ...event.data, effectiveBackend: { model: served, source: "harness" } } };
+        }
+    }
+    catch (error) {
+        if (!timedOut)
+            throw error;
+        yield {
+            type: "result",
+            data: { status: "failed", error: `turn timed out after ${timeoutMs} ms`, errorCode: "timeout", finalText: "" },
+            ...(lastUsage?.usage === undefined ? {} : { usage: lastUsage.usage, usageMode: lastUsage.usageMode ?? "cumulative" }),
+        };
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** An environment rebuilt by `get`: it reaches the sandbox but starts no turn. */
+function reconstructedEnvironment(sandbox, vendor, providerCapabilities) {
+    const operations = sandboxOperations(sandbox, vendor, BOX_WORKSPACE_DIR);
+    const refuse = () => {
+        throw new EnvironmentProviderError("refused", "a reconstructed environment starts no turn; create one", { path: "turn", provider: vendor.name });
+    };
+    let destroyPromise;
+    return {
+        id: sandbox.id,
+        provider: vendor.name,
+        capabilities: providerCapabilities,
+        status: operations.status,
+        // eslint-disable-next-line require-yield
+        stream: async function* () {
+            refuse();
+        },
+        read: operations.read,
+        write: operations.write,
+        exec: operations.exec,
+        placement: operations.placement,
+        destroy(options) {
+            destroyPromise ??= sandbox.destroy(options).catch((error) => {
+                destroyPromise = undefined;
+                throw error;
+            });
+            return destroyPromise;
+        },
+    };
+}

package/dist/sandbox/refusal.d.ts

@@ -0,0 +1,23 @@
+import { type AgentProfile, type AgentProfileValidationResult, type HarnessType } from "@tangle-network/agent-interface";
+import type { CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+import type { BridgeVendorSupport } from "./vendor.js";
+/** The harness a request selects, or the refusal that names why none can be. */
+export declare function resolveBoxHarness(profile: AgentProfile, backend: string | undefined, declared: readonly HarnessType[]): HarnessType;
+/**
+ * Validate a profile against what the box can run, without any sandbox call.
+ *
+ * It plans with the same materializer the Bridge in the box uses, so a
+ * dimension the planner cannot lower is refused here with its own reason.
+ */
+export declare function validateBoxProfile(profile: AgentProfile, backend: string | undefined, declared: readonly HarnessType[]): AgentProfileValidationResult;
+/** Throw the first refusal of a validation result as a typed error that names its path. */
+export declare function assertProfileValid(result: AgentProfileValidationResult): void;
+/**
+ * Refuse every create-input field this provider cannot honor, before any
+ * vendor call. A field is never accepted and dropped.
+ */
+export declare function refuseUnsupportedCreateInput(input: CreateAgentEnvironmentInput, support: BridgeVendorSupport): void;
+/** The harnesses this module can declare. */
+export declare function declarableHarnesses(): HarnessType[];
+/** Whether the shared planner lowers this profile dimension for the harness. */
+export declare function plannerLowers(harness: HarnessType, dimension: "hooks"): boolean;

package/dist/sandbox/refusal.js

@@ -0,0 +1,159 @@
+import { harnessSystemPromptIntents, } from "@tangle-network/agent-interface";
+import { EnvironmentProviderError } from "@tangle-network/agent-interface/environment-provider";
+import { materializeProfile } from "@tangle-network/agent-profile-materialize";
+import { harnessModelSupportFor } from "@tangle-network/cli-agent-registry";
+import { BOX_HARNESSES, boxHarness } from "./box.js";
+/** A profile axis no workspace control enforces here, with the reason it is refused. */
+const REFUSED_PROFILE_AXES = [
+    { path: "profile.confidential", present: (p) => p.confidential !== undefined, reason: "confidential execution needs placement and attestation this provider does not offer" },
+    { path: "profile.seats", present: (p) => p.seats !== undefined, reason: "an ordered subscription chain is not implemented; this provider runs one Router-routed model" },
+    { path: "profile.connections", present: (p) => (p.connections?.length ?? 0) > 0, reason: "connections must be resolved to MCP servers before create" },
+    { path: "profile.proxySecrets", present: (p) => p.proxySecrets !== undefined, reason: "proxy-held credentials are not supported" },
+    { path: "profile.resources.knowledge", present: (p) => Array.isArray(Reflect.get(p.resources ?? {}, "knowledge")) && Reflect.get(p.resources ?? {}, "knowledge").length > 0, reason: "knowledge must be resolved by the runtime before materialization" },
+    { path: "profile.model.maxVisibleOutputTokens", present: (p) => p.model?.maxVisibleOutputTokens !== undefined, reason: "no workspace control enforces an output token cap" },
+    { path: "profile.model.maxReasoningTokens", present: (p) => p.model?.maxReasoningTokens !== undefined, reason: "no workspace control enforces a reasoning token cap" },
+    { path: "profile.model.maxTotalOutputTokens", present: (p) => p.model?.maxTotalOutputTokens !== undefined, reason: "no workspace control enforces a total output token cap" },
+    { path: "profile.extensions", present: (p) => Object.values(p.extensions ?? {}).some((value) => value !== undefined), reason: "no backend extension namespace is implemented" },
+];
+function metadataCredentialSource(profile) {
+    const metadata = profile.model?.metadata;
+    return metadata !== null && typeof metadata === "object" ? metadata.credentialSource : undefined;
+}
+/** The harness a request selects, or the refusal that names why none can be. */
+export function resolveBoxHarness(profile, backend, declared) {
+    const selected = profile.harness ?? backend;
+    if (selected === undefined) {
+        throw new EnvironmentProviderError("refused", "a profile or backend must name a harness; a prompt is never run as a shell command", { path: "profile.harness" });
+    }
+    if (profile.harness !== undefined && backend !== undefined && profile.harness !== backend) {
+        throw new EnvironmentProviderError("refused", `backend ${backend} conflicts with profile.harness ${profile.harness}`, { path: "backend" });
+    }
+    if (!declared.includes(selected) || boxHarness(selected) === undefined) {
+        throw new EnvironmentProviderError("refused", `harness ${selected} is not in this provider's declared set (${declared.join(", ")})`, { path: backend === undefined ? "profile.harness" : "backend" });
+    }
+    return selected;
+}
+/**
+ * Validate a profile against what the box can run, without any sandbox call.
+ *
+ * It plans with the same materializer the Bridge in the box uses, so a
+ * dimension the planner cannot lower is refused here with its own reason.
+ */
+export function validateBoxProfile(profile, backend, declared) {
+    const issues = [];
+    const error = (code, path, message) => {
+        issues.push({ level: "error", code, path, message });
+    };
+    let harness;
+    try {
+        harness = resolveBoxHarness(profile, backend, declared);
+    }
+    catch (caught) {
+        const refusal = caught;
+        error("harness_refused", refusal.path ?? "profile.harness", refusal.message);
+    }
+    for (const axis of REFUSED_PROFILE_AXES) {
+        if (axis.present(profile))
+            error("axis_refused", axis.path, axis.reason);
+    }
+    if (metadataCredentialSource(profile) === "subscription") {
+        error("subscription_refused", "profile.model.metadata.credentialSource", "subscription credentials are not delivered into a cloud box; the model routes through the Router, and a subscription profile is never run on a managed key");
+    }
+    if (harness !== undefined) {
+        const intents = harnessSystemPromptIntents(harness);
+        if (profile.prompt?.systemPrompt !== undefined && !intents.replace)
+            error("system_prompt_refused", "profile.prompt.systemPrompt", `${harness} cannot replace its system prompt`);
+        if (profile.prompt?.appendSystemPrompt !== undefined && !intents.append)
+            error("system_prompt_refused", "profile.prompt.appendSystemPrompt", `${harness} cannot append to its system prompt`);
+        const model = profile.model?.default;
+        if (model !== undefined) {
+            const support = harnessModelSupportFor(harness, { provider: profile.model?.provider, model });
+            if (!support.supported)
+                error("model_refused", "profile.model.default", support.message);
+        }
+        try {
+            const plan = materializeProfile(profile, harness);
+            for (const entry of plan.unsupported)
+                error("unsupported", `profile.${entry.dimension}`, entry.reason);
+        }
+        catch (caught) {
+            error("materialization_refused", "profile", caught instanceof Error ? caught.message : String(caught));
+        }
+    }
+    return { ok: !issues.some((issue) => issue.level === "error"), issues };
+}
+/** Throw the first refusal of a validation result as a typed error that names its path. */
+export function assertProfileValid(result) {
+    const first = result.issues.find((issue) => issue.level === "error");
+    if (first !== undefined) {
+        throw new EnvironmentProviderError("refused", first.message, { ...(first.path === undefined ? {} : { path: first.path }) });
+    }
+}
+/**
+ * Refuse every create-input field this provider cannot honor, before any
+ * vendor call. A field is never accepted and dropped.
+ */
+export function refuseUnsupportedCreateInput(input, support) {
+    const refuse = (path, message) => {
+        throw new EnvironmentProviderError("refused", message, { path });
+    };
+    if (typeof input.profile === "string")
+        refuse("profile", `named profile ${input.profile} is unsupported; pass an inline AgentProfile`);
+    if (input.requestedId !== undefined)
+        refuse("requestedId", "the vendor issues sandbox ids");
+    if (input.runtimeAttachments !== undefined)
+        refuse("runtimeAttachments", "runtime MCP attachments are not supported");
+    if (input.idempotencyKey !== undefined)
+        refuse("idempotencyKey", "durable keyed create is not implemented");
+    if (input.billingOwner !== undefined)
+        refuse("billingOwner", "billing owners are not supported");
+    if (input.secrets !== undefined)
+        refuse("secrets", "secrets are not supported; pass env");
+    if (input.proxySecrets !== undefined)
+        refuse("proxySecrets", "proxy secrets are not supported");
+    if (input.proxySecretParents !== undefined)
+        refuse("proxySecretParents", "proxy secret parents are not supported");
+    if (input.providerOptions !== undefined && Object.keys(input.providerOptions).length > 0)
+        refuse("providerOptions", "no provider option is implemented");
+    const workspace = input.workspace;
+    if (workspace !== undefined) {
+        if (workspace.snapshot !== undefined)
+            refuse("workspace.snapshot", "workspace snapshots are not supported");
+        if (workspace.checkpoint !== undefined)
+            refuse("workspace.checkpoint", "workspace checkpoints are not supported");
+        if (workspace.cwd?.base === "host")
+            refuse("workspace.cwd", "a host cwd is refused; use base \"repository\"");
+        if (workspace.providerOptions !== undefined && Object.keys(workspace.providerOptions).length > 0)
+            refuse("workspace.providerOptions", "no workspace provider option is implemented");
+        if (workspace.environment !== undefined && workspace.image !== undefined)
+            refuse("workspace.image", "workspace cannot specify both environment and image");
+        if (workspace.environment !== undefined && !support.environment)
+            refuse("workspace.environment", "this vendor selects no template or snapshot");
+        if (workspace.image !== undefined && !support.image)
+            refuse("workspace.image", "this vendor selects no image");
+    }
+    if (input.resources !== undefined) {
+        if (!support.resources)
+            refuse("resources", "this vendor sets no resources at create");
+        if (input.resources.providerOptions !== undefined)
+            refuse("resources.providerOptions", "no resource provider option is implemented");
+    }
+    if (input.egress !== undefined && !support.egress.includes(input.egress.mode)) {
+        refuse("egress", `egress mode ${input.egress.mode} is not enforced by this vendor`);
+    }
+}
+/** The harnesses this module can declare. */
+export function declarableHarnesses() {
+    return Object.keys(BOX_HARNESSES);
+}
+/** Whether the shared planner lowers this profile dimension for the harness. */
+export function plannerLowers(harness, dimension) {
+    const probe = { hooks: { PostToolUse: [{ command: "true" }] } };
+    try {
+        const plan = materializeProfile(probe, harness);
+        return !plan.unsupported.some((entry) => entry.dimension === dimension);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/sandbox/vendor.d.ts

@@ -0,0 +1,105 @@
+import type { AgentEnvironmentEgressMode, AgentEnvironmentStatus, ExecRequest, ExecResult, ResourceRequest } from "@tangle-network/agent-interface/environment-provider";
+/**
+ * What a cloud sandbox must expose so a CLI Bridge can run inside it.
+ *
+ * A vendor adapter is only this: create the sandbox from the box image, run
+ * commands in it, expose the Bridge port, report status, destroy it. Profile
+ * materialization, turns, events, usage, cancellation and refusals all belong
+ * to the Bridge and to {@link createBridgeSandboxProvider}.
+ */
+export interface BridgeSandbox {
+    /** The vendor's own sandbox id. It becomes `AgentEnvironment.id`. */
+    readonly id: string;
+    readonly region?: string;
+    /**
+     * Run a command to completion as the box user.
+     *
+     * A non-zero exit is a result, never a throw. `signal` and `timeoutMs` end
+     * the remote command itself, not only the client call.
+     */
+    exec(command: string, options?: ExecRequest): Promise<ExecResult>;
+    /**
+     * Start a process that outlives this call, with `env` set on that process
+     * only. The Bridge runs this way, so its credentials never enter the sandbox
+     * default environment or any command line.
+     */
+    spawn(command: string, options: {
+        cwd?: string;
+        env: Record<string, string>;
+    }): Promise<void>;
+    /** Exact bytes written by `write`; a relative path resolves against the workspace directory. */
+    read(path: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /** Creates parent directories. */
+    write(path: string, content: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** The URL that reaches `port` inside the sandbox, plus any headers the vendor's gateway requires. */
+    endpoint(port: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        url: string;
+        headers?: Record<string, string>;
+    }>;
+    /** The vendor's current lifecycle state; `stopped` or `expired` after destroy or expiry. */
+    status(options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentEnvironmentStatus>;
+    /** Delete the sandbox. Resolves when it is already gone. */
+    destroy(options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+export interface BridgeSandboxCreateRequest {
+    name?: string;
+    /** Tags the vendor stores with the sandbox, string values only. Always carries the run tag. */
+    metadata: Record<string, string>;
+    /** Caller environment for the sandbox's default exec environment. */
+    env: Record<string, string>;
+    /** Finite lifetime the vendor enforces; longer than any turn the caller may run. */
+    lifetimeMs: number;
+    /** Vendor template, snapshot or image the caller chose; absent selects the published box image. */
+    environment?: string;
+    image?: string;
+    resources?: ResourceRequest;
+    egress?: {
+        mode: AgentEnvironmentEgressMode;
+        allowDomains: readonly string[];
+    };
+    /** Aborting must cancel the vendor create and destroy a sandbox that arrives late. */
+    signal?: AbortSignal;
+}
+export interface BridgeSandboxSummary {
+    id: string;
+    status: AgentEnvironmentStatus;
+    name?: string;
+    metadata: Record<string, string>;
+}
+/** Create-input fields a vendor honors beyond the always-honored ones. Everything else is refused. */
+export interface BridgeVendorSupport {
+    /** `workspace.environment` selects a vendor template or snapshot. */
+    environment: boolean;
+    /** `workspace.image` selects a vendor image. */
+    image: boolean;
+    resources: boolean;
+    /** Egress modes the vendor enforces; absent modes are refused. */
+    egress: readonly AgentEnvironmentEgressMode[];
+}
+export interface BridgeSandboxVendor {
+    /** Provider name reported on every environment, for example `e2b`. */
+    readonly name: string;
+    readonly support: BridgeVendorSupport;
+    create(request: BridgeSandboxCreateRequest): Promise<BridgeSandbox>;
+    /** `null` only when the vendor definitively reports no such sandbox; transport failures throw. */
+    connect(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<BridgeSandbox | null>;
+    /** Sandboxes whose tags contain every entry of `metadata`, with their true status. */
+    list(query: {
+        name?: string;
+        metadata?: Record<string, string>;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<BridgeSandboxSummary[]>;
+}

package/dist/sandbox/vendor.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "AgentEnvironmentProvider adapter for cli-bridge retained sessions and one-shot turns",
   "type": "module",
   "license": "MIT",
@@ -14,6 +14,11 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./sandbox": {
+      "import": "./dist/sandbox/index.js",
+      "types": "./dist/sandbox/index.d.ts",
+      "default": "./dist/sandbox/index.js"
     }
   },
   "repository": {
@@ -60,15 +65,29 @@
     "dist/transport.js",
     "dist/wire.d.ts",
     "dist/wire.js",
+    "dist/sandbox/index.d.ts",
+    "dist/sandbox/index.js",
+    "dist/sandbox/box.d.ts",
+    "dist/sandbox/box.js",
+    "dist/sandbox/image.d.ts",
+    "dist/sandbox/image.js",
+    "dist/sandbox/provider.d.ts",
+    "dist/sandbox/provider.js",
+    "dist/sandbox/refusal.d.ts",
+    "dist/sandbox/refusal.js",
+    "dist/sandbox/vendor.d.ts",
+    "dist/sandbox/vendor.js",
     "README.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^5.10.2",
-    "undici": "8.12.3"
+    "@tangle-network/agent-interface": "^5.10.12",
+    "undici": "8.12.3",
+    "@tangle-network/agent-profile-materialize": "1.1.4",
+    "@tangle-network/cli-agent-registry": "^0.14.0"
   },
   "devDependencies": {
-    "@tangle-network/agent-provider-testkit": "0.12.1",
+    "@tangle-network/agent-provider-testkit": "0.12.4",
     "@types/node": "26.6.5",
     "typescript": "6.0.3",
     "vitest": "5.0.5"