@cuylabs/agent-sandbox-docker 0.10.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,119 @@
+# @cuylabs/agent-sandbox-docker
+
+Docker-backed sandbox sessions and execution hosts for `@cuylabs/agent-core`.
+
+Use this package when you want host-aware tools to run inside Docker instead of
+on the local machine. The package supports:
+
+- low-level `ToolHost` adaptation for an existing container via `dockerHost()`
+- higher-level `DockerSandboxSession` lifecycle for a managed Docker environment
+  with `snapshot()`, `extendTimeout()`, and `getPreviewUrl()` support
+- `registerDockerHostProvider()` for registry-based host discovery
+
+The agent loop, model calls, middleware, and sessions still live in your
+Node.js process. Only host-backed tool operations are redirected into the
+container through the `ToolHost` interface from `@cuylabs/agent-core/tool/host`.
+
+## Package Boundary
+
+`@cuylabs/agent-core` owns:
+
+- the `ToolHost` interface
+- the `SandboxSession` interface
+- the default `localHost()`
+- the `ToolHostRegistry` and `defaultToolHostRegistry`
+- the executor path that passes `ctx.host` into tools
+
+`@cuylabs/agent-sandbox-docker` owns:
+
+- connecting `ToolHost` to a running Docker container
+- path resolution inside the container
+- file and shell operations implemented through Docker exec sessions (with stdin piping for large files)
+- `DockerSandboxSession` class implementing the full `SandboxSession` contract
+- container snapshot via `commit()`, lease/timeout tracking, and preview URL construction
+- optional self-registration into `ToolHostRegistry` via `registerDockerHostProvider()`
+
+That same pattern is intended for other host packages too. Docker is one concrete backend implementing the public `ToolHost` contract from `agent-core`.
+
+## Quick Start
+
+### Managed Session (recommended)
+
+```ts
+import { createAgent } from "@cuylabs/agent-core";
+import { createDockerSandboxSession } from "@cuylabs/agent-sandbox-docker";
+
+const sandbox = await createDockerSandboxSession({
+  create: {
+    image: "node:20",
+    workdir: "/workspace",
+  },
+  timeoutMs: 300_000,     // 5 minute lease
+  hostAddress: "localhost", // for preview URLs
+});
+
+const agent = createAgent({
+  model,
+  sandbox,
+});
+
+// Snapshot the environment
+const snap = await sandbox.snapshot();
+
+// Extend the lease
+await sandbox.extendTimeout(60_000);
+
+// Get preview URL for an exposed port
+const url = sandbox.getPreviewUrl(3000); // "http://localhost:3000"
+
+// Clean up
+await sandbox.stop();
+```
+
+### Attach to Existing Container
+
+```ts
+import { createDockerSandboxSession } from "@cuylabs/agent-sandbox-docker";
+
+const sandbox = await createDockerSandboxSession({
+  container: "my-workspace",
+  workdir: "/workspace",
+});
+```
+
+### Low-Level Host Only
+
+If you already manage the container lifecycle yourself:
+
+```ts
+import { dockerHost } from "@cuylabs/agent-sandbox-docker";
+
+const host = await dockerHost({
+  container: "my-sandbox",
+  workdir: "/workspace",
+});
+```
+
+### Registry Integration
+
+```ts
+import { registerDockerHostProvider } from "@cuylabs/agent-sandbox-docker";
+import { defaultToolHostRegistry } from "@cuylabs/agent-core/tool/host";
+
+// Call once at startup
+registerDockerHostProvider();
+
+// Then create hosts by name
+const host = await defaultToolHostRegistry.create("docker", {
+  container: "my-workspace",
+});
+```
+
+## Start Here
+
+- [docs/README.md](./docs/README.md) for the package documentation map
+- [docs/how-it-works.md](./docs/how-it-works.md) for the implementation details
+- [examples/README.md](./examples/README.md) for a runnable end-to-end example
+
+`agent-core` keeps the host contract and the default local host. Concrete
+non-local hosts live in separate packages so they can evolve independently.

package/dist/index.d.ts

@@ -0,0 +1,180 @@
+import * as _cuylabs_agent_core_tool_host from '@cuylabs/agent-core/tool/host';
+import { ToolHost } from '@cuylabs/agent-core/tool/host';
+import { SandboxSession, SandboxSessionMetadata, SandboxSnapshotResult } from '@cuylabs/agent-core';
+
+/**
+ * A Docker container reference understood by this package.
+ */
+interface DockerContainerRefLike {
+    id: string;
+    modem?: unknown;
+    start?: () => Promise<void>;
+    stop?: (options?: {
+        t?: number;
+    }) => Promise<void>;
+    remove?: (options?: {
+        force?: boolean;
+    }) => Promise<void>;
+    inspect?: () => Promise<{
+        Id?: string;
+        Name?: string;
+        State?: {
+            Running?: boolean;
+        };
+        NetworkSettings?: {
+            Ports?: Record<string, Array<{
+                HostIp?: string;
+                HostPort?: string;
+            }> | null>;
+        };
+    }>;
+    commit?: (options?: Record<string, unknown>) => Promise<{
+        Id?: string;
+    }>;
+    pause?: () => Promise<void>;
+    unpause?: () => Promise<void>;
+}
+/**
+ * Configuration for creating a Docker-backed execution host.
+ */
+interface DockerHostOptions {
+    /**
+     * The container to connect to. Either:
+     * - a container name or ID
+     * - a Dockerode `Container`-like object
+     */
+    container: string | DockerContainerRefLike;
+    /** User to run commands as inside the container. */
+    user?: string;
+    /** Default working directory inside the container. */
+    workdir?: string;
+    /**
+     * Dockerode constructor options.
+     * Only used when `container` is a string.
+     */
+    dockerOptions?: Record<string, unknown>;
+}
+/**
+ * Provisioning options for a managed Docker sandbox session.
+ */
+interface DockerSandboxProvisionOptions {
+    /** Container image to create. */
+    image: string;
+    /** Optional container name. */
+    name?: string;
+    /** Optional container command. */
+    command?: string[];
+    /** Environment variables for the container. */
+    env?: Record<string, string | undefined>;
+    /** Working directory inside the container. */
+    workdir?: string;
+    /** Default user inside the container. */
+    user?: string;
+    /** Dockerode constructor options. */
+    dockerOptions?: Record<string, unknown>;
+    /** Additional raw options merged into `docker.createContainer(...)`. */
+    containerOptions?: Record<string, unknown>;
+    /** Pull the image before create. Default: `true`. */
+    pull?: boolean;
+    /**
+     * Remove an existing container with the same name before create.
+     * Default: `false`.
+     */
+    removeExisting?: boolean;
+}
+/**
+ * Configuration for a managed Docker sandbox session.
+ *
+ * Choose exactly one source:
+ * - `container` to attach to an existing container
+ * - `create` to provision a new one
+ */
+interface DockerSandboxSessionOptions {
+    /** Existing container to attach to. */
+    container?: DockerHostOptions["container"];
+    /** Provision a new container and manage its lifecycle. */
+    create?: DockerSandboxProvisionOptions;
+    /** User exposed through the embedded ToolHost. */
+    user?: string;
+    /** Working directory exposed through the embedded ToolHost. */
+    workdir?: string;
+    /** Dockerode constructor options when attaching by container name. */
+    dockerOptions?: Record<string, unknown>;
+    /**
+     * Stop the container when the sandbox session stops.
+     * Default: `true` for provisioned containers, `false` for attached ones.
+     */
+    stopOnClose?: boolean;
+    /**
+     * Remove the container when the sandbox session stops.
+     * Default: `true` for provisioned containers, `false` for attached ones.
+     */
+    removeOnStop?: boolean;
+    /**
+     * Session timeout/lease in milliseconds.
+     * When set, the session tracks an expiration timestamp and supports
+     * `extendTimeout()`. Default: no timeout.
+     */
+    timeoutMs?: number;
+    /**
+     * Host address for building preview URLs.
+     * Used by `getPreviewUrl()` to construct `http://{hostAddress}:{hostPort}` URLs.
+     * Default: `"localhost"`.
+     */
+    hostAddress?: string;
+}
+
+interface DockerRuntime {
+    docker: any;
+    container: any;
+    label: string;
+}
+
+declare function dockerHost(options: DockerHostOptions): Promise<ToolHost>;
+
+declare class DockerSandboxSession implements SandboxSession {
+    readonly id: string;
+    readonly host: ToolHost;
+    readonly metadata: SandboxSessionMetadata;
+    private closed;
+    private readonly runtime;
+    private readonly stopOnClose;
+    private readonly removeOnStop;
+    private readonly hostAddress;
+    private expiresAt;
+    private timeoutMs;
+    private snapshotCounter;
+    constructor(options: {
+        runtime: DockerRuntime;
+        host: ToolHost;
+        managed: boolean;
+        workdir: string;
+        stopOnClose: boolean;
+        removeOnStop: boolean;
+        hostAddress: string;
+        timeoutMs?: number;
+    });
+    stop(): Promise<void>;
+    snapshot(): Promise<SandboxSnapshotResult>;
+    extendTimeout(additionalMs: number): Promise<{
+        expiresAt: number;
+    } | void>;
+    getPreviewUrl(port: number): string | undefined;
+}
+declare function createDockerSandboxSession(options: DockerSandboxSessionOptions): Promise<DockerSandboxSession>;
+
+/**
+ * Register the "docker" host provider on a ToolHostRegistry.
+ *
+ * Call this once at startup to enable `registry.create("docker", options)`.
+ * When called without arguments, registers on the default global registry.
+ */
+declare function registerDockerHostProvider(registry?: {
+    register(provider: {
+        name: string;
+        description?: string;
+        create(options?: DockerHostOptions): Promise<_cuylabs_agent_core_tool_host.ToolHost>;
+    }): unknown;
+}): void;
+
+export { type DockerContainerRefLike, type DockerHostOptions, type DockerSandboxProvisionOptions, DockerSandboxSession, type DockerSandboxSessionOptions, createDockerSandboxSession, dockerHost, registerDockerHostProvider };

package/dist/index.js

@@ -0,0 +1,506 @@
+// src/exec.ts
+async function loadDockerode() {
+  try {
+    const module = await import("dockerode");
+    return module.default ?? module;
+  } catch {
+    throw new Error(
+      "dockerHost requires the 'dockerode' package. Install it with: npm install dockerode"
+    );
+  }
+}
+async function resolveDockerRuntime(options) {
+  const Dockerode = await loadDockerode();
+  if (typeof options.container === "string") {
+    const docker = new Dockerode(options.dockerOptions);
+    const container2 = docker.getContainer(options.container);
+    return {
+      docker,
+      container: container2,
+      label: options.container
+    };
+  }
+  const container = options.container;
+  return {
+    docker: { modem: container.modem },
+    container,
+    label: container.id?.slice(0, 12) ?? "unknown"
+  };
+}
+async function containerExec(runtime, command, options = {}) {
+  const envEntries = options.env ? Object.entries(options.env).filter((entry) => entry[1] !== void 0).map(([key, value]) => `${key}=${value}`) : void 0;
+  const attachStdin = options.stdin !== void 0;
+  const exec = await runtime.container.exec({
+    Cmd: ["sh", "-c", command],
+    ...options.user ? { User: options.user } : {},
+    ...options.workdir ? { WorkingDir: options.workdir } : {},
+    ...envEntries && envEntries.length > 0 ? { Env: envEntries } : {},
+    AttachStdout: true,
+    AttachStderr: true,
+    ...attachStdin ? { AttachStdin: true } : {}
+  });
+  const stream = await exec.start({
+    ...attachStdin ? { hijack: true, stdin: true } : {}
+  });
+  if (attachStdin && options.stdin) {
+    stream.write(options.stdin);
+    stream.end();
+  }
+  let timedOut = false;
+  let aborted = false;
+  return await new Promise((resolve, reject) => {
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    runtime.docker.modem.demuxStream(
+      stream,
+      {
+        write: (chunk) => {
+          stdoutChunks.push(chunk);
+          options.onStdout?.(chunk);
+          return true;
+        },
+        end: function() {
+          return this;
+        }
+      },
+      {
+        write: (chunk) => {
+          stderrChunks.push(chunk);
+          options.onStderr?.(chunk);
+          return true;
+        },
+        end: function() {
+          return this;
+        }
+      }
+    );
+    let timer;
+    if (options.timeout && options.timeout > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        stream.destroy?.();
+      }, options.timeout);
+    }
+    const onAbort = () => {
+      aborted = true;
+      stream.destroy?.();
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    stream.on("end", async () => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+      options.signal?.removeEventListener("abort", onAbort);
+      try {
+        const info = await exec.inspect();
+        resolve({
+          stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+          stderr: Buffer.concat(stderrChunks).toString("utf-8"),
+          exitCode: timedOut || aborted ? null : info.ExitCode ?? 0,
+          timedOut
+        });
+      } catch (error) {
+        reject(error);
+      }
+    });
+    stream.on("error", (error) => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+      options.signal?.removeEventListener("abort", onAbort);
+      if (timedOut || aborted) {
+        resolve({
+          stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+          stderr: Buffer.concat(stderrChunks).toString("utf-8"),
+          exitCode: null,
+          timedOut
+        });
+        return;
+      }
+      reject(error);
+    });
+  });
+}
+async function runDockerCommand(options) {
+  const { runtime, command, defaultUser, defaultWorkdir, execOptions, stdin } = options;
+  return await containerExec(runtime, command, {
+    user: defaultUser,
+    workdir: execOptions?.workdir ?? execOptions?.cwd ?? defaultWorkdir,
+    env: execOptions?.env,
+    timeout: execOptions?.timeout,
+    signal: execOptions?.signal,
+    onStdout: execOptions?.onStdout,
+    onStderr: execOptions?.onStderr,
+    stdin
+  });
+}
+
+// src/shell.ts
+function sq(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function resolveDockerPath(path, defaultWorkdir) {
+  if (path.startsWith("/")) {
+    return path;
+  }
+  const base = defaultWorkdir.endsWith("/") ? defaultWorkdir : `${defaultWorkdir}/`;
+  return `${base}${path}`;
+}
+
+// src/host.ts
+var STDIN_WRITE_THRESHOLD = 128 * 1024;
+function createDockerToolHost(options) {
+  const runtime = options.runtime;
+  const defaultUser = options.user;
+  const defaultWorkdir = options.workdir ?? "/";
+  async function run(command, execOptions) {
+    return await runDockerCommand({
+      runtime,
+      command,
+      defaultUser,
+      defaultWorkdir,
+      execOptions
+    });
+  }
+  return {
+    name: `docker:${runtime.label}`,
+    async readFile(filePath) {
+      const absPath = resolveDockerPath(filePath, defaultWorkdir);
+      const result = await run(`cat ${sq(absPath)}`);
+      if (result.exitCode !== 0) {
+        throw new Error(`readFile failed (${absPath}): ${result.stderr.trim()}`);
+      }
+      return result.stdout;
+    },
+    async readBytes(filePath, offset, length) {
+      const absPath = resolveDockerPath(filePath, defaultWorkdir);
+      const result = await run(
+        `dd if=${sq(absPath)} bs=1 skip=${offset} count=${length} 2>/dev/null`
+      );
+      if (result.exitCode !== 0) {
+        throw new Error(
+          `readBytes failed (${absPath}): ${result.stderr.trim()}`
+        );
+      }
+      return Buffer.from(result.stdout, "binary");
+    },
+    async writeFile(filePath, content) {
+      const absPath = resolveDockerPath(filePath, defaultWorkdir);
+      const dir = absPath.substring(0, absPath.lastIndexOf("/")) || "/";
+      await run(`mkdir -p ${sq(dir)}`);
+      const contentBytes = Buffer.from(content, "utf-8");
+      if (contentBytes.length > STDIN_WRITE_THRESHOLD) {
+        const result = await containerExec(
+          runtime,
+          `cat > ${sq(absPath)}`,
+          { user: defaultUser, workdir: defaultWorkdir, stdin: contentBytes }
+        );
+        if (result.exitCode !== 0) {
+          throw new Error(
+            `writeFile failed (${absPath}): ${result.stderr.trim()}`
+          );
+        }
+      } else {
+        const encoded = contentBytes.toString("base64");
+        const result = await run(
+          `echo ${sq(encoded)} | base64 -d > ${sq(absPath)}`
+        );
+        if (result.exitCode !== 0) {
+          throw new Error(
+            `writeFile failed (${absPath}): ${result.stderr.trim()}`
+          );
+        }
+      }
+    },
+    async exists(filePath) {
+      const absPath = resolveDockerPath(filePath, defaultWorkdir);
+      const result = await run(`test -e ${sq(absPath)}`);
+      return result.exitCode === 0;
+    },
+    async stat(filePath) {
+      const absPath = resolveDockerPath(filePath, defaultWorkdir);
+      const result = await run(
+        `stat -c '%s %Y %F' ${sq(absPath)} 2>/dev/null || stat -f '%z %m %HT' ${sq(absPath)}`
+      );
+      if (result.exitCode !== 0) {
+        throw new Error(`stat failed (${absPath}): ${result.stderr.trim()}`);
+      }
+      const parts = result.stdout.trim().split(/\s+/);
+      if (parts.length < 3) {
+        throw new Error(
+          `stat: unexpected output format for ${absPath}: ${result.stdout}`
+        );
+      }
+      const size = parseInt(parts[0], 10);
+      const mtimeSec = parseInt(parts[1], 10);
+      const typeStr = parts.slice(2).join(" ").toLowerCase();
+      return {
+        size,
+        mtime: new Date(mtimeSec * 1e3),
+        isDirectory: typeStr.includes("directory"),
+        isFile: typeStr.includes("regular") || typeStr.includes("file")
+      };
+    },
+    async readdir(dirPath) {
+      const absPath = resolveDockerPath(dirPath, defaultWorkdir);
+      const result = await run(
+        `find ${sq(absPath)} -maxdepth 1 -mindepth 1 -printf '%f\\t%y\\n' 2>/dev/null || for f in ${sq(absPath)}/*; do [ -e "$f" ] || continue; n=$(basename "$f"); if [ -d "$f" ]; then printf '%s\\td\\n' "$n"; else printf '%s\\tf\\n' "$n"; fi; done`
+      );
+      if (result.exitCode !== 0) {
+        throw new Error(
+          `readdir failed (${absPath}): ${result.stderr.trim()}`
+        );
+      }
+      return result.stdout.trim().split("\n").filter(Boolean).map((line) => {
+        const [name, type] = line.split("	");
+        return {
+          name,
+          isDirectory: type === "d",
+          isFile: type === "f"
+        };
+      });
+    },
+    async mkdir(dirPath) {
+      const absPath = resolveDockerPath(dirPath, defaultWorkdir);
+      const result = await run(`mkdir -p ${sq(absPath)}`);
+      if (result.exitCode !== 0) {
+        throw new Error(`mkdir failed (${absPath}): ${result.stderr.trim()}`);
+      }
+    },
+    async exec(command, execOptions) {
+      return await run(command, execOptions);
+    }
+  };
+}
+async function dockerHost(options) {
+  const runtime = await resolveDockerRuntime(options);
+  return createDockerToolHost({
+    runtime,
+    user: options.user,
+    workdir: options.workdir
+  });
+}
+
+// src/session.ts
+function ensureExactlyOneSource(options) {
+  const hasContainer = options.container !== void 0;
+  const hasCreate = options.create !== void 0;
+  if (hasContainer === hasCreate) {
+    throw new Error(
+      "createDockerSandboxSession requires exactly one of 'container' or 'create'."
+    );
+  }
+}
+function toEnvList(env) {
+  if (!env) {
+    return void 0;
+  }
+  const entries = Object.entries(env).filter((entry) => entry[1] !== void 0).map(([key, value]) => `${key}=${value}`);
+  return entries.length > 0 ? entries : void 0;
+}
+async function pullImage(docker, image) {
+  await new Promise((resolve, reject) => {
+    docker.pull(
+      image,
+      {},
+      (error, stream) => {
+        if (error || !stream) {
+          reject(error ?? new Error("Docker did not return a pull stream"));
+          return;
+        }
+        docker.modem.followProgress(stream, (progressError) => {
+          if (progressError) {
+            reject(progressError);
+            return;
+          }
+          resolve();
+        });
+      }
+    );
+  });
+}
+async function removeExistingNamedContainer(docker, name) {
+  const existing = docker.getContainer(name);
+  await existing.stop?.({ t: 0 }).catch(() => {
+  });
+  await existing.remove?.({ force: true }).catch(() => {
+  });
+}
+async function provisionDockerRuntime(options) {
+  const Dockerode = await loadDockerode();
+  const docker = new Dockerode(options.dockerOptions);
+  if (options.pull !== false) {
+    await pullImage(docker, options.image);
+  }
+  if (options.name && options.removeExisting) {
+    await removeExistingNamedContainer(docker, options.name);
+  }
+  const container = await docker.createContainer({
+    Image: options.image,
+    ...options.name ? { name: options.name } : {},
+    ...options.command ? { Cmd: options.command } : {},
+    ...options.workdir ? { WorkingDir: options.workdir } : {},
+    ...options.user ? { User: options.user } : {},
+    ...toEnvList(options.env) ? { Env: toEnvList(options.env) } : {},
+    ...options.containerOptions ?? {}
+  });
+  await container.start?.();
+  return {
+    docker,
+    container,
+    label: options.name ?? container.id?.slice(0, 12) ?? options.image
+  };
+}
+async function ensureRunning(runtime) {
+  try {
+    const info = await runtime.container.inspect?.();
+    if (info?.State?.Running === false) {
+      await runtime.container.start?.();
+    }
+  } catch {
+  }
+}
+var DockerSandboxSession = class {
+  id;
+  host;
+  metadata;
+  closed = false;
+  runtime;
+  stopOnClose;
+  removeOnStop;
+  hostAddress;
+  expiresAt;
+  timeoutMs;
+  snapshotCounter = 0;
+  constructor(options) {
+    this.runtime = options.runtime;
+    this.host = options.host;
+    this.stopOnClose = options.stopOnClose;
+    this.removeOnStop = options.removeOnStop;
+    this.hostAddress = options.hostAddress;
+    this.timeoutMs = options.timeoutMs;
+    if (options.timeoutMs && options.timeoutMs > 0) {
+      this.expiresAt = Date.now() + options.timeoutMs;
+    }
+    this.id = options.runtime.container.id?.slice(0, 12) ?? options.runtime.label;
+    this.metadata = {
+      kind: "docker",
+      label: options.runtime.label,
+      workingDirectory: options.workdir,
+      containerId: options.runtime.container.id,
+      managed: options.managed,
+      ...this.expiresAt !== void 0 ? { expiresAt: this.expiresAt } : {},
+      ...this.timeoutMs !== void 0 ? { timeoutMs: this.timeoutMs } : {}
+    };
+  }
+  async stop() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    if (this.removeOnStop) {
+      await this.runtime.container.remove?.({ force: true }).catch(() => {
+      });
+      return;
+    }
+    if (this.stopOnClose) {
+      await this.runtime.container.stop?.({ t: 0 }).catch(() => {
+      });
+    }
+  }
+  async snapshot() {
+    if (this.closed) {
+      throw new Error("Cannot snapshot a stopped session.");
+    }
+    const commit = this.runtime.container.commit;
+    if (!commit) {
+      throw new Error(
+        "Snapshot is not supported: the container reference does not expose commit()."
+      );
+    }
+    const label = `snapshot-${++this.snapshotCounter}-${Date.now()}`;
+    const result = await commit.call(this.runtime.container, {
+      repo: `${this.runtime.label}-snapshots`,
+      tag: label,
+      comment: `Snapshot of ${this.runtime.label} at ${(/* @__PURE__ */ new Date()).toISOString()}`,
+      pause: true
+    });
+    return {
+      id: result?.Id ?? label,
+      label,
+      metadata: {
+        repo: `${this.runtime.label}-snapshots`,
+        tag: label,
+        containerId: this.runtime.container.id
+      }
+    };
+  }
+  async extendTimeout(additionalMs) {
+    if (this.closed) {
+      throw new Error("Cannot extend timeout of a stopped session.");
+    }
+    if (this.expiresAt === void 0) {
+      this.expiresAt = Date.now() + additionalMs;
+    } else {
+      const base = Math.max(this.expiresAt, Date.now());
+      this.expiresAt = base + additionalMs;
+    }
+    this.metadata.expiresAt = this.expiresAt;
+    return { expiresAt: this.expiresAt };
+  }
+  getPreviewUrl(port) {
+    return `http://${this.hostAddress}:${port}`;
+  }
+};
+async function createDockerSandboxSession(options) {
+  ensureExactlyOneSource(options);
+  const managed = options.create !== void 0;
+  const runtime = managed ? await provisionDockerRuntime(options.create) : await resolveDockerRuntime({
+    container: options.container,
+    user: options.user,
+    workdir: options.workdir,
+    dockerOptions: options.dockerOptions
+  });
+  await ensureRunning(runtime);
+  const workdir = options.workdir ?? options.create?.workdir ?? "/";
+  const host = createDockerToolHost({
+    runtime,
+    user: options.user ?? options.create?.user,
+    workdir
+  });
+  const stopOnClose = options.stopOnClose ?? managed;
+  const removeOnStop = options.removeOnStop ?? managed;
+  return new DockerSandboxSession({
+    runtime,
+    host,
+    managed,
+    workdir,
+    stopOnClose,
+    removeOnStop,
+    hostAddress: options.hostAddress ?? "localhost",
+    timeoutMs: options.timeoutMs
+  });
+}
+
+// src/index.ts
+import { defaultToolHostRegistry } from "@cuylabs/agent-core/tool/host";
+function registerDockerHostProvider(registry = defaultToolHostRegistry) {
+  registry.register({
+    name: "docker",
+    description: "Run tools inside a Docker container. Requires 'dockerode' peer dependency.",
+    create: (options) => {
+      if (!options?.container) {
+        throw new Error(
+          'Docker host provider requires at least { container: "<name-or-id>" }.'
+        );
+      }
+      return dockerHost(options);
+    }
+  });
+}
+export {
+  DockerSandboxSession,
+  createDockerSandboxSession,
+  dockerHost,
+  registerDockerHostProvider
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@cuylabs/agent-sandbox-docker",
+  "version": "0.10.0",
+  "description": "Docker-backed sandbox sessions and execution hosts for @cuylabs/agent-core",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@cuylabs/agent-core": "^0.10.0"
+  },
+  "peerDependencies": {
+    "dockerode": "^4.0.9"
+  },
+  "devDependencies": {
+    "@ai-sdk/openai": "^3.0.25",
+    "@types/dockerode": "^3.3.47",
+    "@types/node": "^22.0.0",
+    "dockerode": "^4.0.9",
+    "dotenv": "^17.2.3",
+    "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18",
+    "zod": "^3.25.76 || ^4.1.8"
+  },
+  "keywords": [
+    "agent",
+    "docker",
+    "sandbox",
+    "host",
+    "execution",
+    "environment"
+  ],
+  "author": "cuylabs",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cuylabs-ai/agents-ts.git",
+    "directory": "packages/agent-sandbox-docker"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}