@giselles-ai/agent-kit 0.1.0

package/dist/cli.js

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+#!/usr/bin/env node
+
+// src/cli.ts
+import process from "process";
+
+// src/build-snapshot.ts
+import { readdir, readFile, stat } from "fs/promises";
+import path from "path";
+import { Sandbox } from "@vercel/sandbox";
+
+// src/sandbox-utils.ts
+async function runCommandOrThrow(sandbox, input) {
+  const result = await sandbox.runCommand({
+    cmd: input.cmd,
+    args: input.args,
+    cwd: input.cwd,
+    env: input.env
+  });
+  const stdout = await result.stdout().catch(() => "");
+  const stderr = await result.stderr().catch(() => "");
+  if (result.exitCode !== 0) {
+    const errorLines = [
+      `Command failed: ${input.cmd} ${(input.args ?? []).join(" ")}`,
+      `Exit code: ${result.exitCode}`
+    ];
+    if (stdout.trim().length > 0) {
+      errorLines.push(`stdout:
+${stdout}`);
+    }
+    if (stderr.trim().length > 0) {
+      errorLines.push(`stderr:
+${stderr}`);
+    }
+    throw new Error(errorLines.join("\n\n"));
+  }
+  return { stdout, stderr };
+}
+
+// src/build-snapshot.ts
+var SKIP_DIR_NAMES = /* @__PURE__ */ new Set([
+  "node_modules",
+  "dist",
+  ".next",
+  ".git",
+  ".jj"
+]);
+function toPosixPath(inputPath) {
+  return inputPath.split(path.sep).join("/");
+}
+async function collectFiles(targetPath, acc) {
+  const targetStat = await stat(targetPath);
+  if (targetStat.isFile()) {
+    acc.push(targetPath);
+    return;
+  }
+  if (!targetStat.isDirectory()) {
+    return;
+  }
+  const entries = await readdir(targetPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = path.join(targetPath, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIR_NAMES.has(entry.name)) {
+        continue;
+      }
+      await collectFiles(absolutePath, acc);
+      continue;
+    }
+    if (entry.isFile()) {
+      if (entry.name.endsWith(".tsbuildinfo")) {
+        continue;
+      }
+      acc.push(absolutePath);
+    }
+  }
+}
+async function buildUploadFileList(repoRoot, includePaths) {
+  const files = [];
+  for (const relativePath of includePaths) {
+    const absolutePath = path.join(repoRoot, relativePath);
+    await collectFiles(absolutePath, files);
+  }
+  files.sort();
+  return files;
+}
+async function installAllAgentCLIs(sandbox) {
+  console.log("[snapshot] installing gemini cli...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "npm",
+    args: ["install", "-g", "@google/gemini-cli"]
+  });
+  console.log("[snapshot] installing codex cli...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "npm",
+    args: ["install", "-g", "@openai/codex"]
+  });
+  console.log("[snapshot] validating agent CLIs...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "bash",
+    args: [
+      "-lc",
+      ["set -e", "which gemini", "which codex", "codex --version"].join("\n")
+    ]
+  });
+}
+async function setupBrowserToolFromNpm(sandbox, version) {
+  const packageSpec = version ? `@giselles-ai/browser-tool@${version}` : "@giselles-ai/browser-tool";
+  console.log(`[snapshot] installing ${packageSpec} globally...`);
+  await runCommandOrThrow(sandbox, {
+    cmd: "npm",
+    args: ["install", "-g", packageSpec]
+  });
+  console.log("[snapshot] locating mcp-server entry point...");
+  const { stdout: globalRoot } = await runCommandOrThrow(sandbox, {
+    cmd: "npm",
+    args: ["root", "-g"]
+  });
+  const mcpServerPath = `${globalRoot.trim()}/@giselles-ai/browser-tool/dist/mcp-server/index.js`;
+  console.log(`[snapshot] mcp-server resolved at: ${mcpServerPath}`);
+  return mcpServerPath;
+}
+async function setupBrowserToolFromLocal(sandbox, sandboxRoot, repoRoot, includePaths) {
+  console.log("[snapshot] collecting local files...");
+  const uploadFiles = await buildUploadFileList(repoRoot, includePaths);
+  if (uploadFiles.length === 0) {
+    throw new Error("No files collected for snapshot upload.");
+  }
+  console.log(`[snapshot] files to upload: ${uploadFiles.length}`);
+  const filesForSandbox = await Promise.all(
+    uploadFiles.map(async (absolutePath) => {
+      const relativePath = path.relative(repoRoot, absolutePath);
+      const content = await readFile(absolutePath);
+      return {
+        path: toPosixPath(path.join(sandboxRoot, relativePath)),
+        content
+      };
+    })
+  );
+  console.log("[snapshot] uploading repository files...");
+  await sandbox.writeFiles(filesForSandbox);
+  console.log("[snapshot] preparing pnpm...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "bash",
+    args: ["-lc", ["set -e", "corepack pnpm --version"].join("\n")]
+  });
+  console.log("[snapshot] installing dependencies...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "bash",
+    args: [
+      "-lc",
+      [
+        "set -e",
+        `cd ${sandboxRoot}`,
+        [
+          "corepack pnpm install --no-frozen-lockfile",
+          "--filter @giselles-ai/browser-tool..."
+        ].join(" ")
+      ].join("\n")
+    ]
+  });
+  console.log("[snapshot] building browser-tool (mcp-server)...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "bash",
+    args: [
+      "-lc",
+      [
+        "set -e",
+        `cd ${sandboxRoot}`,
+        "corepack pnpm --filter @giselles-ai/browser-tool run build"
+      ].join("\n")
+    ]
+  });
+  const mcpServerPath = `${sandboxRoot}/packages/browser-tool/dist/mcp-server/index.js`;
+  console.log("[snapshot] validating artifacts...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "bash",
+    args: ["-lc", `set -e
+test -f ${mcpServerPath}`]
+  });
+  return mcpServerPath;
+}
+function writeAgentConfigs(sandbox, mcpServerPath, sandboxRoot) {
+  const geminiSettings = {
+    security: {
+      auth: {
+        selectedType: "gemini-api-key"
+      }
+    },
+    mcpServers: {
+      browser_tool_relay: {
+        command: "node",
+        args: [mcpServerPath],
+        cwd: sandboxRoot,
+        env: {}
+      }
+    }
+  };
+  const codexConfigToml = `[mcp_servers.browser_tool_relay]
+command = "node"
+args = ["${mcpServerPath}"]
+cwd = "${sandboxRoot}"
+
+[mcp_servers.browser_tool_relay.env]
+`;
+  return Promise.all([
+    sandbox.writeFiles([
+      {
+        path: "/home/vercel-sandbox/.gemini/settings.json",
+        content: Buffer.from(JSON.stringify(geminiSettings, null, 2))
+      }
+    ]),
+    sandbox.writeFiles([
+      {
+        path: "/home/vercel-sandbox/.codex/config.toml",
+        content: Buffer.from(codexConfigToml)
+      }
+    ])
+  ]);
+}
+var DEFAULT_LOCAL_INCLUDE_PATHS = [
+  "package.json",
+  "pnpm-lock.yaml",
+  "pnpm-workspace.yaml",
+  "tsconfig.base.json",
+  "packages/browser-tool"
+];
+async function buildSnapshot(options = {}) {
+  const sandboxRoot = options.sandboxRoot ?? "/vercel/sandbox";
+  const runtime = options.runtime ?? "node24";
+  const timeoutMs = options.timeoutMs ?? 27e5;
+  const isLocal = options.local ?? false;
+  if (isLocal && !options.repoRoot) {
+    throw new Error("repoRoot is required when local mode is enabled.");
+  }
+  let baseSnapshotId = options.baseSnapshotId ?? "";
+  if (baseSnapshotId) {
+    console.log(`[snapshot] using existing base snapshot: ${baseSnapshotId}`);
+  } else {
+    console.log(
+      "[snapshot] BASE_SNAPSHOT_ID not set, creating base snapshot with all agent CLIs..."
+    );
+    const baseSandbox = await Sandbox.create({
+      runtime,
+      timeout: timeoutMs
+    });
+    console.log(`[snapshot] base sandbox created: ${baseSandbox.sandboxId}`);
+    try {
+      await installAllAgentCLIs(baseSandbox);
+      console.log("[snapshot] creating base snapshot...");
+      const baseSnapshot = await baseSandbox.snapshot();
+      baseSnapshotId = baseSnapshot.snapshotId;
+      console.log(`[snapshot] base snapshot created: ${baseSnapshotId}`);
+      console.log(
+        `[snapshot] reuse with: BASE_SNAPSHOT_ID="${baseSnapshotId}"`
+      );
+    } catch (error) {
+      console.error("[snapshot] base snapshot creation failed:");
+      console.error(error instanceof Error ? error.message : String(error));
+      try {
+        await baseSandbox.stop();
+      } catch {
+      }
+      throw error;
+    }
+  }
+  console.log(
+    `[snapshot] creating sandbox from base snapshot runtime=${runtime} timeoutMs=${timeoutMs}...`
+  );
+  const sandbox = await Sandbox.create({
+    source: { type: "snapshot", snapshotId: baseSnapshotId },
+    runtime,
+    timeout: timeoutMs
+  });
+  console.log(`[snapshot] sandbox created: ${sandbox.sandboxId}`);
+  try {
+    let mcpServerPath;
+    if (isLocal && options.repoRoot) {
+      mcpServerPath = await setupBrowserToolFromLocal(
+        sandbox,
+        sandboxRoot,
+        options.repoRoot,
+        options.localIncludePaths ?? DEFAULT_LOCAL_INCLUDE_PATHS
+      );
+    } else {
+      mcpServerPath = await setupBrowserToolFromNpm(
+        sandbox,
+        options.browserToolVersion
+      );
+    }
+    console.log("[snapshot] validating agent CLIs...");
+    await runCommandOrThrow(sandbox, {
+      cmd: "bash",
+      args: [
+        "-lc",
+        ["set -e", "which gemini", "which codex", "codex --version"].join("\n")
+      ]
+    });
+    console.log("[snapshot] writing agent configs...");
+    await writeAgentConfigs(sandbox, mcpServerPath, sandboxRoot);
+    console.log("[snapshot] creating snapshot (sandbox will be stopped)...");
+    const snapshot = await sandbox.snapshot();
+    console.log("\n=== Snapshot Created ===");
+    console.log(`snapshotId: ${snapshot.snapshotId}`);
+    console.log(`sourceSandboxId: ${snapshot.sourceSandboxId}`);
+    console.log(`status: ${snapshot.status}`);
+    console.log(`createdAt: ${snapshot.createdAt.toISOString()}`);
+    console.log(`expiresAt: ${snapshot.expiresAt?.toISOString()}`);
+    console.log("\nSet this in your .env.local:");
+    console.log(`SANDBOX_SNAPSHOT_ID=${snapshot.snapshotId}`);
+    return snapshot;
+  } catch (error) {
+    console.error("[snapshot] failed:");
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error(`sandboxId: ${sandbox.sandboxId}`);
+    try {
+      await sandbox.stop();
+      console.error("[snapshot] sandbox stopped.");
+    } catch {
+    }
+    throw error;
+  }
+}
+
+// src/cli.ts
+function printUsage() {
+  const usage = `Usage:
+  agent-kit build-snapshot [options]
+
+Options:
+  --local                  Copy local files instead of npm install (monorepo only)
+  --repo-root <path>       Monorepo root directory (required with --local)
+  --base-snapshot-id <id>  Reuse an existing base snapshot
+  --sandbox-root <path>    Sandbox working directory (default: /vercel/sandbox)
+  --runtime <runtime>      Sandbox runtime (default: node24)
+  --timeout-ms <ms>        Sandbox timeout in ms (default: 2700000)
+  --browser-tool-version <version>  Version of @giselles-ai/browser-tool to install
+  --help, -h               Show this help message
+`;
+  process.stderr.write(usage);
+}
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const options = {};
+  let command;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === void 0) continue;
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "--local") {
+      options.local = true;
+      continue;
+    }
+    if (arg.startsWith("--") && i + 1 < args.length) {
+      const key = arg.slice(2);
+      i++;
+      const value = args[i];
+      if (value !== void 0) {
+        options[key] = value;
+      }
+      continue;
+    }
+    if (!arg.startsWith("-") && !command) {
+      command = arg;
+    }
+  }
+  return { command, options };
+}
+async function main() {
+  const { command, options } = parseArgs(process.argv);
+  if (options.help) {
+    printUsage();
+    process.exit(0);
+  }
+  if (command !== "build-snapshot") {
+    printUsage();
+    process.exit(command ? 1 : 1);
+  }
+  const isLocal = options.local === true;
+  const repoRoot = options["repo-root"] ?? process.env.BROWSER_TOOL_REPO_ROOT?.trim();
+  if (isLocal && !repoRoot) {
+    console.error("Error: --repo-root is required when --local is specified.");
+    process.exit(1);
+  }
+  const timeoutMsRaw = options["timeout-ms"] ?? process.env.BROWSER_TOOL_SNAPSHOT_TIMEOUT_MS?.trim();
+  const timeoutMs = timeoutMsRaw ? Number.parseInt(timeoutMsRaw, 10) : void 0;
+  if (timeoutMs !== void 0 && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+    console.error(`Error: Invalid timeout-ms: ${timeoutMsRaw}`);
+    process.exit(1);
+  }
+  try {
+    await buildSnapshot({
+      local: isLocal,
+      repoRoot,
+      baseSnapshotId: options["base-snapshot-id"] ?? process.env.BASE_SNAPSHOT_ID?.trim(),
+      sandboxRoot: options["sandbox-root"] ?? process.env.BROWSER_TOOL_SANDBOX_ROOT?.trim(),
+      runtime: options.runtime ?? process.env.BROWSER_TOOL_SNAPSHOT_RUNTIME?.trim(),
+      timeoutMs,
+      browserToolVersion: options["browser-tool-version"]
+    });
+  } catch {
+    process.exitCode = 1;
+  }
+}
+main().catch((err) => {
+  console.error(
+    `Unexpected error: ${err instanceof Error ? err.message : String(err)}`
+  );
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import * as _vercel_sandbox from '@vercel/sandbox';
+
+interface BuildSnapshotOptions {
+    sandboxRoot?: string;
+    runtime?: string;
+    timeoutMs?: number;
+    baseSnapshotId?: string;
+    browserToolVersion?: string;
+    /**
+     * When true, copy local files into the sandbox and build from source.
+     * When false (default), install @giselles-ai/browser-tool from npm.
+     */
+    local?: boolean;
+    /**
+     * Required when `local` is true. The root directory of the monorepo.
+     */
+    repoRoot?: string;
+    /**
+     * Paths to include when `local` is true.
+     * Defaults to the standard set for this monorepo.
+     */
+    localIncludePaths?: string[];
+}
+declare function buildSnapshot(options?: BuildSnapshotOptions): Promise<_vercel_sandbox.Snapshot>;
+
+export { type BuildSnapshotOptions, buildSnapshot };

package/dist/index.js

@@ -0,0 +1,320 @@
+// src/build-snapshot.ts
+import { readdir, readFile, stat } from "fs/promises";
+import path from "path";
+import { Sandbox } from "@vercel/sandbox";
+
+// src/sandbox-utils.ts
+async function runCommandOrThrow(sandbox, input) {
+  const result = await sandbox.runCommand({
+    cmd: input.cmd,
+    args: input.args,
+    cwd: input.cwd,
+    env: input.env
+  });
+  const stdout = await result.stdout().catch(() => "");
+  const stderr = await result.stderr().catch(() => "");
+  if (result.exitCode !== 0) {
+    const errorLines = [
+      `Command failed: ${input.cmd} ${(input.args ?? []).join(" ")}`,
+      `Exit code: ${result.exitCode}`
+    ];
+    if (stdout.trim().length > 0) {
+      errorLines.push(`stdout:
+${stdout}`);
+    }
+    if (stderr.trim().length > 0) {
+      errorLines.push(`stderr:
+${stderr}`);
+    }
+    throw new Error(errorLines.join("\n\n"));
+  }
+  return { stdout, stderr };
+}
+
+// src/build-snapshot.ts
+var SKIP_DIR_NAMES = /* @__PURE__ */ new Set([
+  "node_modules",
+  "dist",
+  ".next",
+  ".git",
+  ".jj"
+]);
+function toPosixPath(inputPath) {
+  return inputPath.split(path.sep).join("/");
+}
+async function collectFiles(targetPath, acc) {
+  const targetStat = await stat(targetPath);
+  if (targetStat.isFile()) {
+    acc.push(targetPath);
+    return;
+  }
+  if (!targetStat.isDirectory()) {
+    return;
+  }
+  const entries = await readdir(targetPath, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = path.join(targetPath, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIR_NAMES.has(entry.name)) {
+        continue;
+      }
+      await collectFiles(absolutePath, acc);
+      continue;
+    }
+    if (entry.isFile()) {
+      if (entry.name.endsWith(".tsbuildinfo")) {
+        continue;
+      }
+      acc.push(absolutePath);
+    }
+  }
+}
+async function buildUploadFileList(repoRoot, includePaths) {
+  const files = [];
+  for (const relativePath of includePaths) {
+    const absolutePath = path.join(repoRoot, relativePath);
+    await collectFiles(absolutePath, files);
+  }
+  files.sort();
+  return files;
+}
+async function installAllAgentCLIs(sandbox) {
+  console.log("[snapshot] installing gemini cli...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "npm",
+    args: ["install", "-g", "@google/gemini-cli"]
+  });
+  console.log("[snapshot] installing codex cli...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "npm",
+    args: ["install", "-g", "@openai/codex"]
+  });
+  console.log("[snapshot] validating agent CLIs...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "bash",
+    args: [
+      "-lc",
+      ["set -e", "which gemini", "which codex", "codex --version"].join("\n")
+    ]
+  });
+}
+async function setupBrowserToolFromNpm(sandbox, version) {
+  const packageSpec = version ? `@giselles-ai/browser-tool@${version}` : "@giselles-ai/browser-tool";
+  console.log(`[snapshot] installing ${packageSpec} globally...`);
+  await runCommandOrThrow(sandbox, {
+    cmd: "npm",
+    args: ["install", "-g", packageSpec]
+  });
+  console.log("[snapshot] locating mcp-server entry point...");
+  const { stdout: globalRoot } = await runCommandOrThrow(sandbox, {
+    cmd: "npm",
+    args: ["root", "-g"]
+  });
+  const mcpServerPath = `${globalRoot.trim()}/@giselles-ai/browser-tool/dist/mcp-server/index.js`;
+  console.log(`[snapshot] mcp-server resolved at: ${mcpServerPath}`);
+  return mcpServerPath;
+}
+async function setupBrowserToolFromLocal(sandbox, sandboxRoot, repoRoot, includePaths) {
+  console.log("[snapshot] collecting local files...");
+  const uploadFiles = await buildUploadFileList(repoRoot, includePaths);
+  if (uploadFiles.length === 0) {
+    throw new Error("No files collected for snapshot upload.");
+  }
+  console.log(`[snapshot] files to upload: ${uploadFiles.length}`);
+  const filesForSandbox = await Promise.all(
+    uploadFiles.map(async (absolutePath) => {
+      const relativePath = path.relative(repoRoot, absolutePath);
+      const content = await readFile(absolutePath);
+      return {
+        path: toPosixPath(path.join(sandboxRoot, relativePath)),
+        content
+      };
+    })
+  );
+  console.log("[snapshot] uploading repository files...");
+  await sandbox.writeFiles(filesForSandbox);
+  console.log("[snapshot] preparing pnpm...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "bash",
+    args: ["-lc", ["set -e", "corepack pnpm --version"].join("\n")]
+  });
+  console.log("[snapshot] installing dependencies...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "bash",
+    args: [
+      "-lc",
+      [
+        "set -e",
+        `cd ${sandboxRoot}`,
+        [
+          "corepack pnpm install --no-frozen-lockfile",
+          "--filter @giselles-ai/browser-tool..."
+        ].join(" ")
+      ].join("\n")
+    ]
+  });
+  console.log("[snapshot] building browser-tool (mcp-server)...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "bash",
+    args: [
+      "-lc",
+      [
+        "set -e",
+        `cd ${sandboxRoot}`,
+        "corepack pnpm --filter @giselles-ai/browser-tool run build"
+      ].join("\n")
+    ]
+  });
+  const mcpServerPath = `${sandboxRoot}/packages/browser-tool/dist/mcp-server/index.js`;
+  console.log("[snapshot] validating artifacts...");
+  await runCommandOrThrow(sandbox, {
+    cmd: "bash",
+    args: ["-lc", `set -e
+test -f ${mcpServerPath}`]
+  });
+  return mcpServerPath;
+}
+function writeAgentConfigs(sandbox, mcpServerPath, sandboxRoot) {
+  const geminiSettings = {
+    security: {
+      auth: {
+        selectedType: "gemini-api-key"
+      }
+    },
+    mcpServers: {
+      browser_tool_relay: {
+        command: "node",
+        args: [mcpServerPath],
+        cwd: sandboxRoot,
+        env: {}
+      }
+    }
+  };
+  const codexConfigToml = `[mcp_servers.browser_tool_relay]
+command = "node"
+args = ["${mcpServerPath}"]
+cwd = "${sandboxRoot}"
+
+[mcp_servers.browser_tool_relay.env]
+`;
+  return Promise.all([
+    sandbox.writeFiles([
+      {
+        path: "/home/vercel-sandbox/.gemini/settings.json",
+        content: Buffer.from(JSON.stringify(geminiSettings, null, 2))
+      }
+    ]),
+    sandbox.writeFiles([
+      {
+        path: "/home/vercel-sandbox/.codex/config.toml",
+        content: Buffer.from(codexConfigToml)
+      }
+    ])
+  ]);
+}
+var DEFAULT_LOCAL_INCLUDE_PATHS = [
+  "package.json",
+  "pnpm-lock.yaml",
+  "pnpm-workspace.yaml",
+  "tsconfig.base.json",
+  "packages/browser-tool"
+];
+async function buildSnapshot(options = {}) {
+  const sandboxRoot = options.sandboxRoot ?? "/vercel/sandbox";
+  const runtime = options.runtime ?? "node24";
+  const timeoutMs = options.timeoutMs ?? 27e5;
+  const isLocal = options.local ?? false;
+  if (isLocal && !options.repoRoot) {
+    throw new Error("repoRoot is required when local mode is enabled.");
+  }
+  let baseSnapshotId = options.baseSnapshotId ?? "";
+  if (baseSnapshotId) {
+    console.log(`[snapshot] using existing base snapshot: ${baseSnapshotId}`);
+  } else {
+    console.log(
+      "[snapshot] BASE_SNAPSHOT_ID not set, creating base snapshot with all agent CLIs..."
+    );
+    const baseSandbox = await Sandbox.create({
+      runtime,
+      timeout: timeoutMs
+    });
+    console.log(`[snapshot] base sandbox created: ${baseSandbox.sandboxId}`);
+    try {
+      await installAllAgentCLIs(baseSandbox);
+      console.log("[snapshot] creating base snapshot...");
+      const baseSnapshot = await baseSandbox.snapshot();
+      baseSnapshotId = baseSnapshot.snapshotId;
+      console.log(`[snapshot] base snapshot created: ${baseSnapshotId}`);
+      console.log(
+        `[snapshot] reuse with: BASE_SNAPSHOT_ID="${baseSnapshotId}"`
+      );
+    } catch (error) {
+      console.error("[snapshot] base snapshot creation failed:");
+      console.error(error instanceof Error ? error.message : String(error));
+      try {
+        await baseSandbox.stop();
+      } catch {
+      }
+      throw error;
+    }
+  }
+  console.log(
+    `[snapshot] creating sandbox from base snapshot runtime=${runtime} timeoutMs=${timeoutMs}...`
+  );
+  const sandbox = await Sandbox.create({
+    source: { type: "snapshot", snapshotId: baseSnapshotId },
+    runtime,
+    timeout: timeoutMs
+  });
+  console.log(`[snapshot] sandbox created: ${sandbox.sandboxId}`);
+  try {
+    let mcpServerPath;
+    if (isLocal && options.repoRoot) {
+      mcpServerPath = await setupBrowserToolFromLocal(
+        sandbox,
+        sandboxRoot,
+        options.repoRoot,
+        options.localIncludePaths ?? DEFAULT_LOCAL_INCLUDE_PATHS
+      );
+    } else {
+      mcpServerPath = await setupBrowserToolFromNpm(
+        sandbox,
+        options.browserToolVersion
+      );
+    }
+    console.log("[snapshot] validating agent CLIs...");
+    await runCommandOrThrow(sandbox, {
+      cmd: "bash",
+      args: [
+        "-lc",
+        ["set -e", "which gemini", "which codex", "codex --version"].join("\n")
+      ]
+    });
+    console.log("[snapshot] writing agent configs...");
+    await writeAgentConfigs(sandbox, mcpServerPath, sandboxRoot);
+    console.log("[snapshot] creating snapshot (sandbox will be stopped)...");
+    const snapshot = await sandbox.snapshot();
+    console.log("\n=== Snapshot Created ===");
+    console.log(`snapshotId: ${snapshot.snapshotId}`);
+    console.log(`sourceSandboxId: ${snapshot.sourceSandboxId}`);
+    console.log(`status: ${snapshot.status}`);
+    console.log(`createdAt: ${snapshot.createdAt.toISOString()}`);
+    console.log(`expiresAt: ${snapshot.expiresAt?.toISOString()}`);
+    console.log("\nSet this in your .env.local:");
+    console.log(`SANDBOX_SNAPSHOT_ID=${snapshot.snapshotId}`);
+    return snapshot;
+  } catch (error) {
+    console.error("[snapshot] failed:");
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error(`sandboxId: ${sandbox.sandboxId}`);
+    try {
+      await sandbox.stop();
+      console.error("[snapshot] sandbox stopped.");
+    } catch {
+    }
+    throw error;
+  }
+}
+export {
+  buildSnapshot
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@giselles-ai/agent-kit",
+	"version": "0.1.0",
+	"private": false,
+	"type": "module",
+	"bin": {
+		"agent-kit": "./dist/cli.js"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "pnpm clean && tsup --config tsup.ts",
+		"clean": "rm -rf dist *.tsbuildinfo",
+		"dev": "tsx src/cli.ts",
+		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"format": "pnpm exec biome check --write ."
+	},
+	"files": [
+		"dist"
+	],
+	"license": "Apache-2.0",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/giselles-ai/agent-container.git",
+		"directory": "packages/agent-kit"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@vercel/sandbox": "1.8.0"
+	},
+	"devDependencies": {
+		"@types/node": "25.3.0",
+		"tsup": "8.5.1",
+		"tsx": "4.21.0",
+		"typescript": "5.9.3"
+	}
+}