@agen-ai/sandbox-docker 0.0.0-stage → 0.4.4

package/dist/process/owner.js

@@ -0,0 +1,129 @@
+import { randomUUID } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod/v4";
+import { parseSandboxProcessId, SandboxOperationError, SandboxStateError, SandboxUnsupportedError } from "@agen-ai/sandbox";
+import { DOCKER_API } from "../policy/config.js";
+import { DOCKER_ENVIRONMENT } from "../policy/container.js";
+import { DockerProcessAttachment } from "./attachment.js";
+const createdSchema = z.object({ Id: z.string().regex(/^[a-f0-9]{64}$/u) });
+const inspectionSchema = z.object({
+  ID: z.string().regex(/^[a-f0-9]{64}$/u),
+  ContainerID: z.string().regex(/^[a-f0-9]{64}$/u),
+  Running: z.boolean(),
+  ExitCode: z.number().int().min(0).max(255).nullable()
+});
+const fixedEnvironment = Object.freeze(Object.fromEntries(DOCKER_ENVIRONMENT.map((entry) => {
+  const separator = entry.indexOf("=");
+  return [entry.slice(0, separator), entry.slice(separator + 1)];
+})));
+class DockerProcessOwner {
+  constructor(api, config, containerId, spec, policy, assertActive, stopSandbox) {
+    this.api = api;
+    this.config = config;
+    this.containerId = containerId;
+    this.spec = spec;
+    this.policy = policy;
+    this.assertActive = assertActive;
+    this.stopSandbox = stopSandbox;
+    for (const [name, value] of Object.entries(fixedEnvironment)) {
+      if (spec.env[name] !== void 0 && spec.env[name] !== value) {
+        throw new SandboxUnsupportedError(`Docker requires its fixed safe ${name} environment value.`);
+      }
+    }
+    void this.exited.promise.catch(() => {
+    });
+  }
+  id = parseSandboxProcessId(`docker-process-${randomUUID()}`);
+  stopping = new AbortController();
+  exited = Promise.withResolvers();
+  entered = false;
+  startActual;
+  exitSettled = false;
+  attachment;
+  monitoring;
+  start(options) {
+    if (this.entered || this.stopping.signal.aborted) return Promise.reject(new SandboxStateError("Docker process startup is once-only and cannot follow shutdown."));
+    this.entered = true;
+    this.startActual = this.launch(options);
+    return this.startActual;
+  }
+  async launch(options) {
+    const signal = options?.signal ? AbortSignal.any([options.signal, this.stopping.signal]) : this.stopping.signal;
+    signal.throwIfAborted();
+    await this.assertActive(signal);
+    signal.throwIfAborted();
+    const created = await this.api.json("POST", `${DOCKER_API}/containers/${this.containerId}/exec`, createdSchema, { signal, body: {
+      AttachStdin: true,
+      AttachStdout: true,
+      AttachStderr: true,
+      Tty: false,
+      Privileged: false,
+      Cmd: [this.spec.executable, ...this.spec.args],
+      Env: Object.entries({ ...fixedEnvironment, ...this.spec.env }).map(([key, value]) => `${key}=${value}`),
+      WorkingDir: this.spec.cwd,
+      User: `${this.config.user.uid}:${this.config.user.gid}`
+    } });
+    signal.throwIfAborted();
+    await this.assertActive(signal);
+    signal.throwIfAborted();
+    const attached = await this.api.upgrade(`${DOCKER_API}/exec/${created.Id}/start`, { Detach: false, Tty: false }, signal);
+    this.attachment = new DockerProcessAttachment(attached, this.policy.streams, (error) => this.fail(error));
+    if (signal.aborted) {
+      this.attachment.close();
+      throw new SandboxOperationError("cancelled", "Docker process attached after shutdown entered.");
+    }
+    this.monitoring = this.monitor(created.Id).catch((error) => {
+      if (!this.stopping.signal.aborted) this.fail(error instanceof Error ? error : new SandboxOperationError("driver_failure", "Docker process inspection failed.", { cause: error }));
+    });
+    return Object.freeze({ stdin: this.attachment.stdin, stdout: this.attachment.stdout, stderr: this.attachment.stderr, exit: this.exited.promise });
+  }
+  closeAdmission() {
+    if (!this.stopping.signal.aborted) this.stopping.abort(new SandboxOperationError("cancelled", "Docker sandbox compute is stopping."));
+    this.attachment?.close();
+  }
+  async computeStopped() {
+    this.closeAdmission();
+    this.exit({ kind: "unavailable", reason: "sandbox_stopped" });
+    await this.startActual?.catch(() => {
+    });
+    await this.monitoring;
+    await this.attachment?.settled;
+  }
+  async monitor(execId) {
+    while (!this.stopping.signal.aborted) {
+      const response = await this.api.request("GET", `${DOCKER_API}/exec/${execId}/json`, { statuses: [200, 404], signal: this.stopping.signal });
+      if (this.stopping.signal.aborted) return;
+      if (response.statusCode === 404) {
+        throw new SandboxOperationError("driver_failure", "Docker lost the owned exec before sandbox removal was confirmed.");
+      }
+      let value;
+      try {
+        value = JSON.parse(Buffer.from(response.body).toString("utf8"));
+      } catch (cause) {
+        throw new SandboxOperationError("driver_failure", "Docker exec inspection returned invalid JSON.", { cause });
+      }
+      const result = inspectionSchema.safeParse(value);
+      if (!result.success || result.data.ID !== execId || result.data.ContainerID !== this.containerId) {
+        throw new SandboxOperationError("driver_failure", "Docker exec inspection differs from the exact owned exec and workload.");
+      }
+      if (!result.data.Running && result.data.ExitCode !== null) {
+        this.exit({ kind: "exited", code: result.data.ExitCode });
+        return;
+      }
+      await delay(100, void 0, { signal: this.stopping.signal });
+    }
+  }
+  exit(result) {
+    if (this.exitSettled) return;
+    this.exitSettled = true;
+    this.exited.resolve(Object.freeze(result));
+  }
+  fail(error) {
+    this.attachment?.close(error);
+    void this.stopSandbox().catch(() => {
+    });
+  }
+}
+export {
+  DockerProcessOwner
+};

package/dist/recovery/identity.d.ts

@@ -0,0 +1,11 @@
+import type { SandboxRecoveryRecord, SandboxRecoveryResource, SandboxRequest } from '@agen-ai/sandbox';
+import type { DockerSandboxConfig } from '../policy/config.js';
+export type ResourceRole = SandboxRecoveryResource['role'];
+export declare function digest(value: unknown): string;
+export declare function resourceName(namespace: string, operationId: string, role: ResourceRole): string;
+export declare function configurationDigest(config: DockerSandboxConfig): string;
+export declare function newRecoveryRecord(config: DockerSandboxConfig, request: SandboxRequest): SandboxRecoveryRecord;
+export declare function resourceLabels(record: SandboxRecoveryRecord, role: ResourceRole): Readonly<Record<string, string>>;
+export declare function assertLabels(actual: Readonly<Record<string, string>>, record: SandboxRecoveryRecord, role: ResourceRole): void;
+export declare function validateRecord(record: SandboxRecoveryRecord, config: DockerSandboxConfig): boolean;
+//# sourceMappingURL=identity.d.ts.map

package/dist/recovery/identity.js

@@ -0,0 +1,78 @@
+import { createHash, randomUUID } from "node:crypto";
+import { parseSandboxId, parseSandboxNamespace, parseSandboxRecoveryRecord, SandboxStateError } from "@agen-ai/sandbox";
+import { DOCKER_BACKEND_ID } from "../policy/config.js";
+import { dockerBackendRevision } from "../policy/profiles.js";
+function digest(value) {
+  return `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}
+function resourceName(namespace, operationId, role) {
+  return `agenai-sbx-${createHash("sha256").update(`${namespace}\0${operationId}`).digest("hex").slice(0, 32)}-${role}`;
+}
+function configurationDigest(config) {
+  return digest({ profile: config.profile, user: config.user, imageDigest: config.imageDigest, datasets: config.datasets });
+}
+function newRecoveryRecord(config, request) {
+  const operationId = randomUUID();
+  const roles = ["compute", "storage", "export"];
+  if (request.policy.network.kind === "outbound") roles.push("network");
+  return parseSandboxRecoveryRecord({
+    format: "agenai.sandbox-recovery.v2",
+    backendId: DOCKER_BACKEND_ID,
+    backendRevision: dockerBackendRevision(config.profile),
+    namespace: parseSandboxNamespace(config.namespace),
+    operationId,
+    sandboxId: parseSandboxId(`docker-${operationId}`),
+    imageDigest: config.imageDigest,
+    configurationDigest: configurationDigest(config),
+    policyDigest: digest(request.policy),
+    phase: "reserved",
+    authority: { kind: "unverified" },
+    resources: roles.map((role) => ({ role, name: resourceName(config.namespace, operationId, role), identity: { kind: "planned" } }))
+  });
+}
+function recordBinding(record) {
+  return digest({
+    format: record.format,
+    backendId: record.backendId,
+    backendRevision: record.backendRevision,
+    namespace: record.namespace,
+    operationId: record.operationId,
+    sandboxId: record.sandboxId,
+    imageDigest: record.imageDigest,
+    configurationDigest: record.configurationDigest,
+    policyDigest: record.policyDigest,
+    resources: record.resources.map(({ role, name }) => ({ role, name }))
+  });
+}
+function resourceLabels(record, role) {
+  return Object.freeze({
+    "ai.agen.sandbox.record": recordBinding(record),
+    "ai.agen.sandbox.role": role,
+    "ai.agen.sandbox.namespace": record.namespace,
+    "ai.agen.sandbox.operation": record.operationId,
+    "ai.agen.sandbox.backend": record.backendId,
+    "ai.agen.sandbox.revision": record.backendRevision,
+    "ai.agen.sandbox.image": record.imageDigest,
+    "ai.agen.sandbox.configuration": record.configurationDigest,
+    "ai.agen.sandbox.policy": record.policyDigest
+  });
+}
+function assertLabels(actual, record, role) {
+  const expected = resourceLabels(record, role);
+  if (Object.entries(expected).some(([key, value]) => actual[key] !== value)) {
+    throw new SandboxStateError("Docker resource labels do not bind the original reserved ownership record.");
+  }
+}
+function validateRecord(record, config) {
+  const roles = record.resources.map((resource) => resource.role);
+  return record.backendId === DOCKER_BACKEND_ID && record.backendRevision === dockerBackendRevision(config.profile) && record.namespace === config.namespace && record.imageDigest === config.imageDigest && record.configurationDigest === configurationDigest(config) && /^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u.test(record.operationId) && record.sandboxId === `docker-${record.operationId}` && roles.length >= 3 && roles.length <= 4 && ["compute", "storage", "export"].every((role) => roles.includes(role)) && record.resources.every((resource) => resource.name === resourceName(config.namespace, record.operationId, resource.role));
+}
+export {
+  assertLabels,
+  configurationDigest,
+  digest,
+  newRecoveryRecord,
+  resourceLabels,
+  resourceName,
+  validateRecord
+};

package/dist/recovery/reconcile.d.ts

@@ -0,0 +1,5 @@
+import type { OperationOptions, SandboxReconciliation, SandboxRecoveryRecord } from '@agen-ai/sandbox';
+import type { DockerSandboxConfig } from '../policy/config.js';
+import type { DockerApi } from '../resources/api.js';
+export declare function reconcileDocker(api: DockerApi, config: DockerSandboxConfig, original: SandboxRecoveryRecord, options?: OperationOptions): Promise<SandboxReconciliation>;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/recovery/reconcile.js

@@ -0,0 +1,44 @@
+import { SandboxStateError, parseSandboxRecoveryRecord } from "@agen-ai/sandbox";
+import { verifyDaemon } from "../policy/preflight.js";
+import { inspectResource } from "../resources/inspect.js";
+import { DockerResourceOwner } from "../resources/owner.js";
+import { validateRecord } from "./identity.js";
+async function reconcileDocker(api, config, original, options) {
+  if (!validateRecord(original, config)) return Object.freeze({ kind: "conflict", reason: "Recovery record does not match this Docker backend profile, namespace, image or reserved identity." });
+  const backendIdentity = await verifyDaemon(api, config, options?.signal);
+  if (original.authority.kind === "verified" && original.authority.backendIdentity !== backendIdentity) {
+    return Object.freeze({ kind: "conflict", reason: "Recovery record belongs to another Docker daemon identity." });
+  }
+  let current = original;
+  let present = false;
+  let uncertain = false;
+  for (const resource of original.resources) {
+    const reference = resource.identity.kind === "identified" ? resource.identity.id : resource.name;
+    try {
+      const inspection = await inspectResource(api, current, resource, reference, options?.signal);
+      if (!inspection) {
+        if (resource.identity.kind === "creating") uncertain = true;
+        continue;
+      }
+      if (resource.identity.kind === "planned") {
+        return Object.freeze({ kind: "conflict", reason: "A planned resource name is already present; recover from the latest durable record after the previous controller is quiescent." });
+      }
+      present = true;
+      if (resource.identity.kind === "creating") current = parseSandboxRecoveryRecord({
+        ...current,
+        resources: current.resources.map((candidate) => candidate.role === resource.role ? {
+          ...candidate,
+          identity: { kind: "identified", id: inspection.id, fingerprint: inspection.fingerprint }
+        } : candidate)
+      });
+    } catch (error) {
+      if (!(error instanceof SandboxStateError)) throw error;
+      return Object.freeze({ kind: "conflict", reason: "Docker resource identity, configuration or original recovery binding does not match." });
+    }
+  }
+  if (!present && !uncertain) return Object.freeze({ kind: "absent", record: current });
+  return Object.freeze({ kind: uncertain ? "uncertain" : "matched", owner: new DockerResourceOwner(api, config, void 0, current) });
+}
+export {
+  reconcileDocker
+};

package/dist/resources/api.d.ts

@@ -0,0 +1,23 @@
+import type { ZodType } from 'zod/v4';
+import { DockerEngine } from '../engine/client.js';
+import type { DockerEngineStreamOptions, DockerEngineStreamResponse, DockerEngineStreamResult } from '../engine/contracts.js';
+export declare class DockerApi {
+    readonly engine: DockerEngine;
+    readonly timeoutMs: number;
+    constructor(engine: DockerEngine, timeoutMs: number);
+    stream<Value>(method: 'GET' | 'HEAD' | 'PUT', path: string, options: DockerEngineStreamOptions, consume: (response: DockerEngineStreamResponse) => Promise<Value>): Promise<DockerEngineStreamResult<Value>>;
+    upgrade(path: string, body: unknown, signal?: AbortSignal): Promise<import("../engine/upgrade.js").DockerEngineAttachment>;
+    json<Value>(method: 'GET' | 'POST' | 'DELETE', path: string, schema: ZodType<Value>, options?: {
+        body?: unknown;
+        signal?: AbortSignal;
+        statuses?: readonly number[];
+    }): Promise<Value>;
+    request(method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, options?: {
+        body?: Uint8Array;
+        contentType?: 'application/json' | 'application/x-tar';
+        maxResponseBytes?: number;
+        signal?: AbortSignal;
+        statuses?: readonly number[];
+    }): Promise<import("../engine/contracts.js").DockerEngineResponse>;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/resources/api.js

@@ -0,0 +1,70 @@
+import { SandboxOperationError } from "@agen-ai/sandbox";
+import { DockerEngineTransportError } from "../engine/client.js";
+class DockerApi {
+  constructor(engine, timeoutMs) {
+    this.engine = engine;
+    this.timeoutMs = timeoutMs;
+  }
+  async stream(method, path, options, consume) {
+    try {
+      return await this.engine.stream(method, path, options, async (response) => {
+        if (response.statusCode !== 200) throw new SandboxOperationError("driver_failure", `Docker transfer returned HTTP ${response.statusCode}.`);
+        return consume(response);
+      });
+    } catch (cause) {
+      throw transportFailure(cause);
+    }
+  }
+  async upgrade(path, body, signal) {
+    try {
+      return await this.engine.upgrade(path, {
+        body: Buffer.from(JSON.stringify(body)),
+        contentType: "application/json",
+        timeoutMs: this.timeoutMs,
+        maxResponseBytes: 1024 * 1024,
+        signal
+      });
+    } catch (cause) {
+      throw transportFailure(cause);
+    }
+  }
+  async json(method, path, schema, options = {}) {
+    const body = options.body === void 0 ? void 0 : Buffer.from(JSON.stringify(options.body), "utf8");
+    const response = await this.request(method, path, { ...options, body, maxResponseBytes: 1024 * 1024, contentType: "application/json" });
+    let value;
+    try {
+      value = JSON.parse(Buffer.from(response.body).toString("utf8"));
+    } catch (cause) {
+      throw new SandboxOperationError("driver_failure", "Docker returned invalid JSON.", { cause });
+    }
+    const parsed = schema.safeParse(value);
+    if (!parsed.success) throw new SandboxOperationError("driver_failure", "Docker returned an invalid resource response.");
+    return parsed.data;
+  }
+  async request(method, path, options = {}) {
+    let response;
+    try {
+      response = await this.engine.request(method, path, {
+        timeoutMs: this.timeoutMs,
+        maxResponseBytes: options.maxResponseBytes ?? 1024 * 1024,
+        body: options.body,
+        contentType: options.contentType,
+        signal: options.signal
+      });
+    } catch (cause) {
+      throw transportFailure(cause);
+    }
+    if (!(options.statuses ?? [200, 201, 204]).includes(response.statusCode)) {
+      throw new SandboxOperationError("driver_failure", `Docker resource operation returned HTTP ${response.statusCode}.`);
+    }
+    return response;
+  }
+}
+function transportFailure(cause) {
+  if (!(cause instanceof DockerEngineTransportError)) return cause;
+  const code = cause.code === "deadline" ? "deadline_exceeded" : cause.code === "aborted" ? "cancelled" : "driver_failure";
+  return new SandboxOperationError(code, "Docker resource transport did not settle successfully.", { cause });
+}
+export {
+  DockerApi
+};

package/dist/resources/fingerprint.d.ts

@@ -0,0 +1,3 @@
+import type { ContainerInspection } from './inspect.js';
+export declare function containerFingerprint(container: ContainerInspection): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/resources/fingerprint.js

@@ -0,0 +1,94 @@
+import { digest } from "../recovery/identity.js";
+const CONFIGURATION_FIELDS = [
+  "Image",
+  "User",
+  "WorkingDir",
+  "Entrypoint",
+  "Cmd",
+  "Env",
+  "Labels",
+  "Tty",
+  "OpenStdin",
+  "AttachStdin",
+  "AttachStdout",
+  "AttachStderr",
+  "NetworkDisabled",
+  "Healthcheck",
+  "Volumes",
+  "ExposedPorts",
+  "StopSignal",
+  "StopTimeout"
+];
+const HOST_POLICY_FIELDS = [
+  "ReadonlyRootfs",
+  "Privileged",
+  "CapDrop",
+  "CapAdd",
+  "SecurityOpt",
+  "PidMode",
+  "IpcMode",
+  "CgroupnsMode",
+  "UsernsMode",
+  "UTSMode",
+  "CgroupParent",
+  "NetworkMode",
+  "PublishAllPorts",
+  "PortBindings",
+  "ExtraHosts",
+  "Links",
+  "Dns",
+  "DnsOptions",
+  "DnsSearch",
+  "Devices",
+  "DeviceRequests",
+  "DeviceCgroupRules",
+  "Binds",
+  "Mounts",
+  "Tmpfs",
+  "VolumesFrom",
+  "NanoCpus",
+  "Memory",
+  "MemorySwap",
+  "MemoryReservation",
+  "MemorySwappiness",
+  "PidsLimit",
+  "CpuShares",
+  "CpuPeriod",
+  "CpuQuota",
+  "CpuRealtimePeriod",
+  "CpuRealtimeRuntime",
+  "CpusetCpus",
+  "CpusetMems",
+  "RestartPolicy",
+  "AutoRemove",
+  "Runtime",
+  "Init",
+  "StorageOpt",
+  "Ulimits"
+];
+function selected(value, keys) {
+  return Object.fromEntries(keys.map((key) => [key, value[key]]));
+}
+function containerFingerprint(container) {
+  return digest({
+    Id: container.Id,
+    Name: container.Name,
+    Image: container.Image,
+    Config: selected(container.Config, CONFIGURATION_FIELDS),
+    HostConfig: selected(container.HostConfig, HOST_POLICY_FIELDS),
+    // Moby clears an unsupported false OOM switch to null when starting on cgroup v2.
+    OomKillDisabled: container.HostConfig.OomKillDisable === true,
+    Mounts: [...container.Mounts].sort((left, right) => left.Destination < right.Destination ? -1 : left.Destination > right.Destination ? 1 : 0).map((mount) => ({
+      Type: mount.Type,
+      Name: mount.Name,
+      Source: mount.Source,
+      Destination: mount.Destination,
+      RW: mount.RW,
+      Driver: mount.Driver,
+      Propagation: mount.Propagation
+    }))
+  });
+}
+export {
+  containerFingerprint
+};

package/dist/resources/inspect.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod/v4';
+import type { SandboxRecoveryRecord, SandboxRecoveryResource } from '@agen-ai/sandbox';
+import type { DockerApi } from './api.js';
+export declare const containerSchema: z.ZodObject<{
+    Id: z.ZodString;
+    Name: z.ZodString;
+    Image: z.ZodString;
+    Config: z.ZodObject<{
+        Labels: z.ZodRecord<z.ZodString, z.ZodString>;
+        Image: z.ZodString;
+        User: z.ZodString;
+        WorkingDir: z.ZodString;
+        Entrypoint: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        Cmd: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        Env: z.ZodNullable<z.ZodArray<z.ZodString>>;
+        Tty: z.ZodBoolean;
+        OpenStdin: z.ZodBoolean;
+        Volumes: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$loose>;
+    HostConfig: z.ZodObject<{}, z.core.$loose>;
+    Mounts: z.ZodArray<z.ZodObject<{
+        Type: z.ZodString;
+        Name: z.ZodOptional<z.ZodString>;
+        Source: z.ZodString;
+        Destination: z.ZodString;
+        RW: z.ZodBoolean;
+        Propagation: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    NetworkSettings: z.ZodObject<{
+        Networks: z.ZodRecord<z.ZodString, z.ZodObject<{
+            NetworkID: z.ZodString;
+        }, z.core.$strip>>;
+        Ports: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+    State: z.ZodObject<{
+        Running: z.ZodBoolean;
+        Status: z.ZodString;
+    }, z.core.$loose>;
+    AppArmorProfile: z.ZodString;
+}, z.core.$loose>;
+export type ContainerInspection = z.infer<typeof containerSchema>;
+export interface ResourceInspection {
+    readonly id: string;
+    readonly fingerprint: string;
+    readonly container?: ContainerInspection;
+}
+export declare function inspectPath(resource: SandboxRecoveryResource, identity: string): string;
+export declare function inspectResource(api: DockerApi, record: SandboxRecoveryRecord, resource: SandboxRecoveryResource, reference: string, signal?: AbortSignal): Promise<ResourceInspection | undefined>;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/resources/inspect.js

@@ -0,0 +1,103 @@
+import { z } from "zod/v4";
+import { SandboxStateError } from "@agen-ai/sandbox";
+import { DOCKER_API } from "../policy/config.js";
+import { assertLabels, digest } from "../recovery/identity.js";
+import { containerFingerprint } from "./fingerprint.js";
+const labelsSchema = z.record(z.string(), z.string());
+const mountSchema = z.object({ Type: z.string(), Name: z.string().optional(), Source: z.string(), Destination: z.string(), RW: z.boolean(), Propagation: z.string().optional() }).passthrough();
+const containerSchema = z.object({
+  Id: z.string().regex(/^[a-f0-9]{64}$/u),
+  Name: z.string(),
+  Image: z.string(),
+  Config: z.object({
+    Labels: labelsSchema,
+    Image: z.string(),
+    User: z.string(),
+    WorkingDir: z.string(),
+    Entrypoint: z.array(z.string()).nullable(),
+    Cmd: z.array(z.string()).nullable(),
+    Env: z.array(z.string()).nullable(),
+    Tty: z.boolean(),
+    OpenStdin: z.boolean(),
+    Volumes: z.record(z.string(), z.unknown()).nullish()
+  }).passthrough(),
+  HostConfig: z.object({}).passthrough(),
+  Mounts: z.array(mountSchema),
+  NetworkSettings: z.object({ Networks: z.record(z.string(), z.object({ NetworkID: z.string() })), Ports: z.record(z.string(), z.unknown()).nullable() }),
+  State: z.object({ Running: z.boolean(), Status: z.string() }).passthrough(),
+  AppArmorProfile: z.string()
+}).passthrough();
+const volumeSchema = z.object({
+  Name: z.string(),
+  Driver: z.string(),
+  Mountpoint: z.string(),
+  CreatedAt: z.string(),
+  Labels: labelsSchema,
+  Options: z.record(z.string(), z.string()).nullable(),
+  Scope: z.string()
+});
+const networkSchema = z.object({
+  Id: z.string().regex(/^[a-f0-9]{64}$/u),
+  Name: z.string(),
+  Created: z.string(),
+  Driver: z.string(),
+  Scope: z.string(),
+  Internal: z.boolean(),
+  Attachable: z.boolean(),
+  Ingress: z.boolean(),
+  EnableIPv6: z.boolean(),
+  ConfigOnly: z.boolean(),
+  IPAM: z.object({}).passthrough(),
+  Options: z.record(z.string(), z.string()),
+  Labels: labelsSchema
+});
+function inspectPath(resource, identity) {
+  const encoded = encodeURIComponent(identity);
+  if (resource.role === "compute" || resource.role === "export") return `${DOCKER_API}/containers/${encoded}/json`;
+  if (resource.role === "storage") return `${DOCKER_API}/volumes/${encoded}`;
+  return `${DOCKER_API}/networks/${encoded}`;
+}
+async function inspectResource(api, record, resource, reference, signal) {
+  const response = await api.request("GET", inspectPath(resource, reference), { statuses: [200, 404], signal });
+  if (response.statusCode === 404) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(response.body).toString("utf8"));
+  } catch {
+    throw new SandboxStateError("Docker resource inspection returned invalid JSON.");
+  }
+  let result;
+  if (resource.role === "compute" || resource.role === "export") {
+    const value = containerSchema.safeParse(parsed);
+    if (!value.success) throw new SandboxStateError("Docker returned an invalid container inspection.");
+    const container = value.data;
+    assertLabels(container.Config.Labels, record, resource.role);
+    if (container.Name !== `/${resource.name}` || container.Image !== record.imageDigest || container.Config.Image !== record.imageDigest) {
+      throw new SandboxStateError("Docker container name or image differs from reserved ownership.");
+    }
+    result = { id: container.Id, fingerprint: containerFingerprint(container), container };
+  } else if (resource.role === "storage") {
+    const value = volumeSchema.safeParse(parsed);
+    if (!value.success) throw new SandboxStateError("Docker returned an invalid volume inspection.");
+    const volume = value.data;
+    assertLabels(volume.Labels, record, resource.role);
+    if (volume.Name !== resource.name || volume.Driver !== "local" || volume.Scope !== "local" || Object.keys(volume.Options ?? {}).length !== 0) throw new SandboxStateError("Docker volume does not match the owned local volume profile.");
+    result = { id: volume.Name, fingerprint: digest(value.data) };
+  } else {
+    const value = networkSchema.safeParse(parsed);
+    if (!value.success) throw new SandboxStateError("Docker returned an invalid network inspection.");
+    const network = value.data;
+    assertLabels(network.Labels, record, resource.role);
+    if (network.Name !== resource.name || network.Driver !== "bridge" || network.Scope !== "local" || network.Internal || network.Attachable || network.Ingress || network.ConfigOnly || network.EnableIPv6 || Object.keys(network.Options).length !== 0) throw new SandboxStateError("Docker network does not match the owned outbound bridge profile.");
+    result = { id: network.Id, fingerprint: digest(network) };
+  }
+  if (resource.identity.kind === "identified" && (resource.identity.id !== result.id || resource.identity.fingerprint !== result.fingerprint)) {
+    throw new SandboxStateError("Docker resource no longer matches its exact inspected identity and fingerprint.");
+  }
+  return result;
+}
+export {
+  containerSchema,
+  inspectPath,
+  inspectResource
+};

package/dist/resources/owner.d.ts

@@ -0,0 +1,46 @@
+import type { SandboxCleanupOwner, SandboxRecoveryRecord, SandboxRequest } from '@agen-ai/sandbox';
+import type { SandboxDriverReady, SandboxDriverReservation, SandboxDriverStartOptions } from '@agen-ai/sandbox/backend';
+import type { DockerSandboxConfig } from '../policy/config.js';
+import type { ResourceRole } from '../recovery/identity.js';
+import { DockerApi } from './api.js';
+import type { ResourceInspection } from './inspect.js';
+export declare class DockerResourceOwner implements SandboxDriverReservation, SandboxCleanupOwner {
+    private readonly api;
+    private readonly config;
+    private readonly request;
+    private current;
+    private closed;
+    private startActual;
+    private stopActual;
+    private destroyActual;
+    private checkpoint;
+    private checkpointTail;
+    private readonly returnedIds;
+    private readonly createEffects;
+    private readonly absent;
+    private process;
+    constructor(api: DockerApi, config: DockerSandboxConfig, request: SandboxRequest | undefined, record?: SandboxRecoveryRecord);
+    get id(): import("@agen-ai/sandbox").SandboxId;
+    get recoveryRecord(): SandboxRecoveryRecord;
+    start(options: SandboxDriverStartOptions): Promise<SandboxDriverReady>;
+    private acquire;
+    private importTree;
+    private exportTree;
+    private createResource;
+    stop(): Promise<void>;
+    private cleanupCompute;
+    destroy(): Promise<void>;
+    private cleanupAll;
+    resolveResource(role: ResourceRole, signal?: AbortSignal): Promise<ResourceInspection | undefined>;
+    private requirePresent;
+    private deleteResource;
+    private resource;
+    private updateIdentity;
+    private cleanupPhase;
+    private publishCleanup;
+    private publish;
+    private submitCheckpoint;
+    private assertAuthority;
+    private assertOpen;
+}
+//# sourceMappingURL=owner.d.ts.map