@tangle-network/agent-provider-cli-bridge 2.0.6 → 2.0.8

package/dist/sandbox/checkpoint.d.ts

@@ -0,0 +1,26 @@
+import { type CheckpointRef, type CheckpointRequest, type CreateAgentEnvironmentInput, type ForkRequest } from "@tangle-network/agent-interface/environment-provider";
+import type { BridgeSandboxVendor, BridgeVendorSnapshots } from "./vendor.js";
+/**
+ * Vendor-snapshot checkpointing: the portable seam between the optional
+ * `AgentEnvironment.checkpoint`/`fork` surface and a vendor's snapshot
+ * lifecycle. A vendor without {@link BridgeVendorSnapshots} refuses both,
+ * exactly as it refuses every capability it cannot honor.
+ */
+/** The vendor snapshot lifecycle, or a refusal naming the vendor. */
+export declare function vendorSnapshots(vendor: BridgeSandboxVendor): BridgeVendorSnapshots;
+/** A checkpoint name that cannot collide with a caller-chosen vendor snapshot name. */
+export declare function checkpointSnapshotName(name: string | undefined): string;
+/** Snapshot one running sandbox and return the portable checkpoint reference. */
+export declare function createVendorSnapshot(vendor: BridgeSandboxVendor, sandboxId: string, options?: CheckpointRequest & {
+    signal?: AbortSignal;
+}): Promise<CheckpointRef>;
+/** A fork must restore this vendor's snapshot; a foreign checkpoint reference is refused. */
+export declare function assertForkableCheckpoint(ref: CheckpointRef, vendorName: string): void;
+/**
+ * The create input a fork runs with: the source environment's input, minus
+ * everything the snapshot already carries. A repository clone would overwrite
+ * the snapshot's workspace, and a caller-chosen environment would boot a
+ * different image than the checkpoint captured; both are dropped, while the
+ * requested working directory keeps its placement.
+ */
+export declare function forkCreateInput(source: CreateAgentEnvironmentInput, request?: ForkRequest): CreateAgentEnvironmentInput;

package/dist/sandbox/checkpoint.js

@@ -0,0 +1,82 @@
+import { randomUUID } from "node:crypto";
+import { EnvironmentProviderError, } from "@tangle-network/agent-interface/environment-provider";
+/**
+ * Vendor-snapshot checkpointing: the portable seam between the optional
+ * `AgentEnvironment.checkpoint`/`fork` surface and a vendor's snapshot
+ * lifecycle. A vendor without {@link BridgeVendorSnapshots} refuses both,
+ * exactly as it refuses every capability it cannot honor.
+ */
+/** The vendor snapshot lifecycle, or a refusal naming the vendor. */
+export function vendorSnapshots(vendor) {
+    if (vendor.snapshots === undefined) {
+        throw new EnvironmentProviderError("refused", `vendor ${vendor.name} exposes no snapshot lifecycle`, { provider: vendor.name });
+    }
+    return vendor.snapshots;
+}
+/** Snapshot metadata must be string-valued, exactly like vendor sandbox tags. */
+function snapshotMetadata(metadata, provider) {
+    if (metadata === undefined)
+        return undefined;
+    const out = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (typeof value !== "string") {
+            throw new EnvironmentProviderError("refused", `snapshot metadata holds string values; ${key} is not a string`, { path: `metadata.${key}`, provider });
+        }
+        out[key] = value;
+    }
+    return out;
+}
+/** A checkpoint name that cannot collide with a caller-chosen vendor snapshot name. */
+export function checkpointSnapshotName(name) {
+    return name ?? `tangle-ckpt-${randomUUID()}`;
+}
+/** Snapshot one running sandbox and return the portable checkpoint reference. */
+export async function createVendorSnapshot(vendor, sandboxId, options) {
+    const snapshots = vendorSnapshots(vendor);
+    const request = options === undefined
+        ? {}
+        : {
+            ...(options.name === undefined ? {} : { name: options.name }),
+            ...(options.metadata === undefined ? {} : { metadata: snapshotMetadata(options.metadata, vendor.name) }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        };
+    const record = await snapshots.create(sandboxId, Object.keys(request).length === 0 ? undefined : request);
+    if (typeof record.id !== "string" || record.id.length === 0) {
+        throw new EnvironmentProviderError("provision_failed", `vendor ${vendor.name} returned no snapshot id for ${sandboxId}`, { provider: vendor.name });
+    }
+    return {
+        id: record.id,
+        provider: vendor.name,
+        ...(record.createdAt === undefined ? {} : { metadata: { createdAt: record.createdAt } }),
+    };
+}
+/** A fork must restore this vendor's snapshot; a foreign checkpoint reference is refused. */
+export function assertForkableCheckpoint(ref, vendorName) {
+    if (typeof ref.id !== "string" || ref.id.length === 0) {
+        throw new EnvironmentProviderError("invalid_input", "a checkpoint reference carries a non-empty id", { path: "checkpoint.id", provider: vendorName });
+    }
+    if (ref.provider !== undefined && ref.provider !== vendorName) {
+        throw new EnvironmentProviderError("refused", `checkpoint from provider ${ref.provider} cannot restore on ${vendorName}`, { path: "checkpoint.provider", provider: vendorName });
+    }
+}
+/**
+ * The create input a fork runs with: the source environment's input, minus
+ * everything the snapshot already carries. A repository clone would overwrite
+ * the snapshot's workspace, and a caller-chosen environment would boot a
+ * different image than the checkpoint captured; both are dropped, while the
+ * requested working directory keeps its placement.
+ */
+export function forkCreateInput(source, request) {
+    const { workspace, name, metadata, signal, ...rest } = source;
+    const cwd = workspace?.cwd;
+    return {
+        ...rest,
+        ...(request?.name === undefined
+            ? (name === undefined ? {} : { name })
+            : { name: request.name }),
+        ...(metadata === undefined && request?.metadata === undefined
+            ? {}
+            : { metadata: { ...metadata, ...request?.metadata } }),
+        ...(cwd === undefined ? {} : { workspace: { cwd } }),
+    };
+}

package/dist/sandbox/image.d.ts

@@ -4,6 +4,8 @@ import type { HarnessType } from "@tangle-network/agent-interface";
  *
  * 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.
+ * versions come from the registry that owns the pins. `baseImage` overrides
+ * the Node base for a box that carries more than the pins; the install layer
+ * is unchanged, so every box keeps the same Bridge and harness versions.
  */
-export declare function renderBoxDockerfile(harnesses?: readonly HarnessType[]): string;
+export declare function renderBoxDockerfile(harnesses?: readonly HarnessType[], baseImage?: string): string;

package/dist/sandbox/image.js

@@ -4,9 +4,11 @@ import { BOX_HARNESSES, BOX_HOME, BOX_NODE_IMAGE, BOX_PINS, BOX_WORKSPACE_DIR, b
  *
  * 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.
+ * versions come from the registry that owns the pins. `baseImage` overrides
+ * the Node base for a box that carries more than the pins; the install layer
+ * is unchanged, so every box keeps the same Bridge and harness versions.
  */
-export function renderBoxDockerfile(harnesses = Object.keys(BOX_HARNESSES)) {
+export function renderBoxDockerfile(harnesses = Object.keys(BOX_HARNESSES), baseImage = BOX_NODE_IMAGE) {
     const installs = harnesses.map((name) => {
         const entry = BOX_HARNESSES[name];
         if (entry === undefined)
@@ -17,7 +19,7 @@ export function renderBoxDockerfile(harnesses = Object.keys(BOX_HARNESSES)) {
     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}`,
+        `FROM ${baseImage}`,
         "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(" ")} \\`,

package/dist/sandbox/index.d.ts

@@ -1,6 +1,7 @@
 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 type { BridgeSandbox, BridgeSandboxCreateRequest, BridgeSandboxSummary, BridgeSandboxVendor, BridgeVendorSnapshot, BridgeVendorSnapshots, BridgeVendorSupport, } from "./vendor.js";
+export { checkpointSnapshotName } from "./checkpoint.js";
 export { validateBoxProfile } from "./refusal.js";
 export { envFileLaunch, markedExec, untilAborted } from "./shell.js";
 export { BOX_HARNESSES, BOX_HOME, BOX_PINS, BOX_TEMPLATE_NAME, BOX_WORKSPACE_DIR, BRIDGE_PORT, boxHarnessVersion, } from "./box.js";

package/dist/sandbox/index.js

@@ -1,4 +1,5 @@
 export { createBridgeSandboxProvider, BRIDGE_RUN_TAG } from "./provider.js";
+export { checkpointSnapshotName } from "./checkpoint.js";
 export { validateBoxProfile } from "./refusal.js";
 export { envFileLaunch, markedExec, untilAborted } from "./shell.js";
 export { BOX_HARNESSES, BOX_HOME, BOX_PINS, BOX_TEMPLATE_NAME, BOX_WORKSPACE_DIR, BRIDGE_PORT, boxHarnessVersion, } from "./box.js";

package/dist/sandbox/provider.js

@@ -8,6 +8,7 @@ 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";
+import { assertForkableCheckpoint, createVendorSnapshot, forkCreateInput, } from "./checkpoint.js";
 export const BRIDGE_RUN_TAG = "tangle-bridge-run";
 const DEFAULT_LIFETIME_MS = 2 * 60 * 60 * 1000;
 const DEFAULT_READY_TIMEOUT_MS = 120_000;
@@ -36,9 +37,20 @@ export function createBridgeSandboxProvider(options) {
     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) {
+    async function create(input, restore) {
         input.signal?.throwIfAborted();
         refuseUnsupportedCreateInput(input, vendor.support);
+        // A caller's requested lifetime can only shorten the configured one; the vendor still enforces the wall clock.
+        let lifetimeRequested = lifetimeMs;
+        if (input.maxLifetimeMs !== undefined) {
+            if (!Number.isSafeInteger(input.maxLifetimeMs) || input.maxLifetimeMs < 1) {
+                throw new EnvironmentProviderError("invalid_input", "maxLifetimeMs must be a positive safe integer of milliseconds", { path: "maxLifetimeMs" });
+            }
+            lifetimeRequested = Math.min(lifetimeMs, input.maxLifetimeMs);
+        }
+        if (restore !== undefined && input.workspace?.environment !== undefined) {
+            throw new EnvironmentProviderError("refused", "a fork restores its checkpoint; workspace.environment names a different one", { path: "workspace.environment" });
+        }
         const profile = input.profile;
         const validation = validateBoxProfile(profile, input.backend, declared);
         assertProfileValid(validation);
@@ -56,8 +68,9 @@ export function createBridgeSandboxProvider(options) {
                 ...(input.name === undefined ? {} : { name: input.name }),
                 metadata: { ...stringMetadata(input.metadata), [BRIDGE_RUN_TAG]: runTag },
                 env: input.env ?? {},
-                lifetimeMs,
+                lifetimeMs: lifetimeRequested,
                 ...(input.workspace?.environment === undefined ? {} : { environment: input.workspace.environment }),
+                ...(restore === undefined ? {} : { snapshot: restore.snapshot }),
                 ...(input.workspace?.image === undefined ? {} : { image: input.workspace.image }),
                 ...(input.resources === undefined ? {} : { resources: input.resources }),
                 ...(input.egress === undefined ? {} : { egress: egressFor(input, routerBaseUrl) }),
@@ -89,7 +102,8 @@ export function createBridgeSandboxProvider(options) {
                 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 });
+            const forkFromCheckpoint = vendor.snapshots === undefined ? undefined : (checkpoint, request, signal) => create({ ...forkCreateInput(input, request), ...(signal === undefined ? {} : { signal }) }, { snapshot: checkpoint.id });
+            return wrapEnvironment({ inner, sandbox, vendor, harness, profile, workspaceDir, dispatcher, capabilities: environmentCapabilities(inner.capabilities ?? providerCapabilities(harness), vendor, plannerLowers(harness, "hooks")), input, ...(forkFromCheckpoint === undefined ? {} : { forkFromCheckpoint }) });
         }
         catch (error) {
             await dispatcher?.close().catch(() => undefined);
@@ -264,10 +278,12 @@ function environmentCapabilities(bridge, vendor, hooks) {
         ...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 } },
+        branching: { checkpoint: vendor.snapshots !== undefined, fork: vendor.snapshots !== undefined },
         placement: true,
         create: {
             durableIdempotency: false,
             ...(vendor.support.egress.length === 0 ? {} : { egress: [...vendor.support.egress] }),
+            ...(vendor.snapshots === undefined ? {} : { workspaceSnapshot: false }),
         },
     };
 }
@@ -348,6 +364,14 @@ function wrapEnvironment(args) {
         status: operations.status,
         stream: exclusive,
         ...(inner.session === undefined ? {} : { session: (id, options) => inner.session(id, options) }),
+        ...(vendor.snapshots === undefined ? {} : {
+            checkpoint: (options) => createVendorSnapshot(vendor, sandbox.id, options),
+            fork: async (checkpoint, options) => {
+                assertForkableCheckpoint(checkpoint, vendor.name);
+                const { signal, ...request } = options ?? {};
+                return args.forkFromCheckpoint(checkpoint, Object.keys(request).length === 0 ? undefined : request, signal);
+            },
+        }),
         ...(inner.dispatch === undefined
             ? {}
             : {

package/dist/sandbox/refusal.js

@@ -107,6 +107,8 @@ export function refuseUnsupportedCreateInput(input, support) {
         refuse("idempotencyKey", "durable keyed create is not implemented");
     if (input.billingOwner !== undefined)
         refuse("billingOwner", "billing owners are not supported");
+    if (input.idleTimeoutMs !== undefined)
+        refuse("idleTimeoutMs", "these sandboxes enforce a lifetime, not an idle timeout");
     if (input.secrets !== undefined)
         refuse("secrets", "secrets are not supported; pass env");
     if (input.proxySecrets !== undefined)

package/dist/sandbox/vendor.d.ts

@@ -61,6 +61,8 @@ export interface BridgeSandboxCreateRequest {
     lifetimeMs: number;
     /** Vendor template, snapshot or image the caller chose; absent selects the published box image. */
     environment?: string;
+    /** Snapshot id {@link BridgeVendorSnapshots.create} returned; restores that exact state. */
+    snapshot?: string;
     image?: string;
     resources?: ResourceRequest;
     egress?: {
@@ -86,10 +88,33 @@ export interface BridgeVendorSupport {
     /** Egress modes the vendor enforces; absent modes are refused. */
     egress: readonly AgentEnvironmentEgressMode[];
 }
+/** A vendor snapshot of one sandbox's state, restorable through `create`. */
+export interface BridgeVendorSnapshot {
+    /** Vendor snapshot identifier; restores via `BridgeSandboxCreateRequest.snapshot`. */
+    readonly id: string;
+    /** Vendor-reported creation time, when the vendor reports one. */
+    readonly createdAt?: string;
+}
+/** Snapshot lifecycle a vendor may expose beyond create, exec and destroy. */
+export interface BridgeVendorSnapshots {
+    /**
+     * Snapshot a running sandbox. The returned id restores via
+     * `create({ snapshot: id })`, producing a sandbox that starts from the
+     * source's captured state. What a snapshot carries (filesystem only, or
+     * memory too) is vendor truth, reported nowhere else.
+     */
+    create(sandboxId: string, options?: {
+        name?: string;
+        metadata?: Record<string, string>;
+        signal?: AbortSignal;
+    }): Promise<BridgeVendorSnapshot>;
+}
 export interface BridgeSandboxVendor {
     /** Provider name reported on every environment, for example `e2b`. */
     readonly name: string;
     readonly support: BridgeVendorSupport;
+    /** Present only when the vendor snapshots running sandboxes. */
+    readonly snapshots?: BridgeVendorSnapshots;
     create(request: BridgeSandboxCreateRequest): Promise<BridgeSandbox>;
     /** `null` only when the vendor definitively reports no such sandbox; transport failures throw. */
     connect(id: string, options?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "AgentEnvironmentProvider adapter for cli-bridge retained sessions and one-shot turns",
   "type": "module",
   "license": "MIT",
@@ -37,7 +37,7 @@
   ],
   "dependencies": {
     "@tangle-network/agent-core": "^1.0.2",
-    "@tangle-network/agent-interface": "^5.10.12",
+    "@tangle-network/agent-interface": "^5.10.17",
     "@tangle-network/agent-profile-materialize": "1.1.4",
     "@tangle-network/cli-agent-registry": "^0.14.0",
     "undici": "8.12.3"