@maestro-js/agent-container 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,233 @@
+# @maestro-js/agent-container
+
+Docker-based isolated agent execution environment with patch-based sync.
+
+Creates sandboxed Docker containers pre-loaded with Node.js 22, pnpm, Claude CLI, Playwright, git, and zsh. Your repo is copied in (excluding `node_modules`), dependencies are installed, and a `maestro-base` git tag marks the starting point so `pull` can extract only the agent's changes as a patch.
+
+This is a **standalone utility** — it does not use the service-registry provider pattern.
+
+## Quick Setup
+
+```ts
+import { AgentContainer } from '@maestro-js/agent-container'
+
+const container = await AgentContainer.create({
+  repoPath: '/path/to/my-project',
+  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! }
+})
+
+await container.exec('npx vitest run')
+
+const { applied, conflicts } = await container.pull() // patches container changes onto host working tree
+await container.stop()
+```
+
+## Container Lifecycle
+
+```
+create(config)
+  │
+  ├─ Build/cache Docker image (base + user)
+  ├─ Start container
+  ├─ Copy repo files (via git ls-files, excluding node_modules)
+  ├─ Run pnpm install
+  ├─ git init + commit + tag "maestro-base"
+  │
+  ▼
+Container ready
+  │
+  ├─ exec(command)     Run commands programmatically
+  ├─ shell(name)       Open interactive bash session
+  ├─ open(name)        Attach VS Code to container
+  │
+  ▼
+pull()
+  │
+  ├─ Stage pending changes in container (git add -A)
+  ├─ git diff --binary maestro-base → patch file
+  ├─ git apply --3way onto host working tree
+  │
+  ▼
+stop()
+  └─ docker rm -f
+```
+
+## Configuration
+
+Options for `AgentContainer.create()`. Only `repoPath` is required.
+
+| Field        | Type                      | Default          | Description                                                                     |
+| ------------ | ------------------------- | ---------------- | ------------------------------------------------------------------------------- |
+| `repoPath`   | `string`                  | —                | Absolute path to the host repo to copy into the container                       |
+| `name`       | `string?`                 | auto-incremented | Custom container name suffix (e.g. `'my-task'` → `maestro-agent-my-task`)       |
+| `dockerfile` | `string?`                 | built-in         | Custom Dockerfile content. Must use `ARG MAESTRO_BASE` / `FROM ${MAESTRO_BASE}` |
+| `workDir`    | `string?`                 | `'/workspace'`   | Working directory inside the container                                          |
+| `env`        | `Record<string, string>?` | `{}`             | Extra environment variables passed to `docker run -e`                           |
+| `memory`     | `string?`                 | `'8gb'`          | Docker memory limit                                                             |
+| `cpus`       | `number?`                 | `2`              | Docker CPU limit                                                                |
+| `volume`     | `string?`                 | per-repo hash    | Docker volume name for `/home/node`. Defaults to `maestro-claude-<sha256>`      |
+
+## API Reference
+
+### `create(config)`
+
+```ts
+function create(config: AgentContainer.Config): Promise<AgentContainer.Container>
+```
+
+Creates a new isolated container from the given repo. Builds/caches the Docker image, copies repo files, installs dependencies, and initializes git.
+
+```ts
+const container = await AgentContainer.create({
+  repoPath: '/path/to/repo',
+  name: 'feature-work',
+  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! }
+})
+```
+
+### `list()`
+
+```ts
+function list(): Promise<AgentContainer.ContainerInfo[]>
+```
+
+Lists all running agent containers (filtered by the `maestro-agent` prefix).
+
+```ts
+const containers = await AgentContainer.list()
+// [{ id: 'abc123', name: 'maestro-agent-1', status: 'Up 2 hours' }]
+```
+
+### `kill(name)`
+
+```ts
+function kill(name: string): Promise<void>
+```
+
+Force-removes a container by name (`docker rm -f`).
+
+```ts
+await AgentContainer.kill('maestro-agent-1')
+```
+
+### `pull(name, repoPath, workDir?)`
+
+```ts
+function pull(name: string, repoPath: string, workDir?: string): Promise<AgentContainer.PatchResult>
+```
+
+Patches container changes onto the host working tree. Stages all container changes, generates a binary diff since `maestro-base`, and applies it to the host via `git apply --3way`. Host changes are temporarily staged so three-way merge can handle conflicts.
+
+```ts
+const { applied, conflicts } = await AgentContainer.pull(
+  'maestro-agent-1',
+  '/path/to/repo'
+)
+if (applied && !conflicts) console.log('Clean patch applied')
+if (conflicts) console.log('Patch applied with conflict markers')
+```
+
+### `shell(name)`
+
+```ts
+function shell(name: string): Promise<void>
+```
+
+Opens an interactive bash session inside the container. Inherits stdio — not suitable for programmatic use.
+
+### `open(name, workDir?)`
+
+```ts
+function open(name: string, workDir?: string): Promise<void>
+```
+
+Opens VS Code attached to the container via the `vscode-remote://attached-container` URI scheme.
+
+## Container Handle
+
+`AgentContainer.create()` returns a `Container` object scoped to that container:
+
+```ts
+interface Container {
+  id: string                                     // Container name (e.g. 'maestro-agent-1')
+  exec(command: string): Promise<ExecResult>     // Run a command
+  stop(): Promise<void>                          // Force-remove container
+  pull(): Promise<PatchResult>                   // Patch container changes onto host
+}
+```
+
+The handle methods use the config from `create()`, so you don't need to pass `repoPath` or `workDir` again:
+
+```ts
+const container = await AgentContainer.create({ repoPath: '.' })
+const { stdout } = await container.exec('node --version')
+const { applied } = await container.pull()  // false if no changes
+await container.stop()
+```
+
+### `PatchResult`
+
+```ts
+interface PatchResult {
+  applied: boolean    // true if a non-empty patch was applied
+  conflicts: boolean  // true if patch applied with merge conflict markers
+}
+```
+
+## Common Patterns
+
+### Agent Task Runner
+
+```ts
+const container = await AgentContainer.create({
+  repoPath: '/path/to/repo',
+  env: { ANTHROPIC_API_KEY: key }
+})
+
+try {
+  await container.exec('claude "Fix the failing tests"')
+  const { applied, conflicts } = await container.pull()
+  if (applied && !conflicts) console.log('Agent changes applied cleanly')
+} finally {
+  await container.stop()
+}
+```
+
+### Multiple Agents in Parallel
+
+```ts
+const tasks = ['Fix auth bug', 'Add input validation', 'Write tests']
+
+const results = await Promise.all(
+  tasks.map(async (task) => {
+    const container = await AgentContainer.create({
+      repoPath: '/path/to/repo',
+      env: { ANTHROPIC_API_KEY: key }
+    })
+    try {
+      await container.exec(`claude "${task}"`)
+      return await container.pull()
+    } finally {
+      await container.stop()
+    }
+  })
+)
+```
+
+## Warnings and Gotchas
+
+> **Warning:** Docker must be running — all operations shell out to `docker` and will fail if the daemon is not available.
+
+> **Warning:** `pull()` applies patches directly to the host working tree — not to a branch. Stage or commit host changes before pulling to avoid losing work.
+
+> **Warning:** `pull()` temporarily runs `git add -A` on the host repo (then `git reset` after) so `--3way` can resolve conflicts. Unstaged host changes are preserved but briefly staged during the operation.
+
+> **Note:** `pnpm install` runs during `create()` — can be slow on first run or large repos. Dependencies are installed inside the container, not on the host.
+
+> **Note:** `node_modules` is excluded from copy — uses `git ls-files` to enumerate tracked/untracked files, so gitignored paths are never copied.
+
+> **Note:** `shell()` and `open()` inherit stdio — they are interactive and block the process. Not suitable for programmatic use.
+
+> **Note:** Image builds are cached by content hash — Dockerfile changes trigger rebuilds. The base image and user image are tagged with a SHA-256 prefix of their Dockerfile content.
+
+> **Note:** `/home/node` is a Docker volume — a per-repo volume (e.g. `maestro-claude-a1b2c3d4`) persists Claude CLI config and zsh history across containers for the same repo. Pass `volume` to `create()` to override.

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+declare const AgentContainer: {
+    create: typeof create;
+    list: typeof list;
+    kill: typeof kill;
+    shell: typeof shell;
+    open: typeof open;
+    pull: typeof pull;
+};
+/**
+ * Docker-based isolated agent execution environment with patch-based sync.
+ *
+ * Creates sandboxed Docker containers pre-loaded with Node.js 22, pnpm,
+ * Claude CLI, Playwright, git, and zsh. Your repo is copied in (excluding
+ * `node_modules`), dependencies are installed, and a `maestro-base` git tag
+ * marks the starting point so {@link pull} can extract only the agent's changes
+ * as a patch.
+ *
+ * This is a standalone utility — it does **not** use the service-registry
+ * provider pattern. Import `AgentContainer` and call methods directly.
+ *
+ * @example
+ * ```ts
+ * import { AgentContainer } from '@maestro-js/agent-container'
+ *
+ * const container = await AgentContainer.create({ repoPath: '/path/to/repo' })
+ * await container.exec('npx vitest run')
+ * const { applied } = await container.pull() // patches container changes onto host
+ * await container.stop()
+ * ```
+ */
+declare namespace AgentContainer {
+    /** Options for {@link AgentContainer.create}. Only `repoPath` is required. */
+    interface Config {
+        /** Custom container name suffix. Auto-incremented if omitted. */
+        name?: string;
+        /** Absolute path to the host repo to copy into the container. */
+        repoPath: string;
+        /** Custom Dockerfile content. Defaults to the built-in image with Node.js 22, pnpm, Claude CLI, and Playwright. */
+        dockerfile?: string;
+        /** Working directory inside the container. @default '/workspace' */
+        workDir?: string;
+        /** Extra environment variables passed to `docker run -e`. */
+        env?: Record<string, string>;
+        /** Docker memory limit (e.g. `'8gb'`). @default '8gb' */
+        memory?: string;
+        /** Docker CPU limit. @default 2 */
+        cpus?: number;
+        /** Docker volume name for persisting `/home/node` (Claude CLI config, zsh history). Defaults to a per-repo name based on `repoPath`. */
+        volume?: string;
+    }
+    /** Result of running a command inside the container via {@link Container.exec}. */
+    interface ExecResult {
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }
+    /**
+     * Handle to a running agent container returned by {@link AgentContainer.create}.
+     *
+     * @example
+     * ```ts
+     * const container = await AgentContainer.create({ repoPath: '.' })
+     * const result = await container.exec('echo hello')
+     * await container.pull()
+     * await container.stop()
+     * ```
+     */
+    interface Container {
+        /** Docker container name (e.g. `maestro-agent-1`). */
+        id: string;
+        /** Runs a shell command inside the container and returns stdout, stderr, and exit code. */
+        exec(command: string): Promise<ExecResult>;
+        /** Force-removes the container (`docker rm -f`). */
+        stop(): Promise<void>;
+        /** Patches container changes (since `maestro-base`) onto the host working tree. */
+        pull(): Promise<PatchResult>;
+    }
+    /** Result of a {@link Container.pull} call. */
+    interface PatchResult {
+        /** `true` if a non-empty patch was applied, `false` if there was nothing to apply. */
+        applied: boolean;
+        /** `true` if the patch applied with merge conflicts (conflict markers left in files). */
+        conflicts: boolean;
+    }
+    /** Metadata for a running agent container, returned by {@link AgentContainer.list}. */
+    interface ContainerInfo {
+        /** Docker container ID (short hash). */
+        id: string;
+        /** Container name (e.g. `maestro-agent-1`). */
+        name: string;
+        /** Docker status string (e.g. `Up 2 hours`). */
+        status: string;
+    }
+}
+declare function create(config: AgentContainer.Config): Promise<AgentContainer.Container>;
+declare function list(): Promise<AgentContainer.ContainerInfo[]>;
+declare function kill(name: string): Promise<void>;
+declare function shell(name: string): Promise<void>;
+declare function open(name: string, workDir?: string): Promise<void>;
+declare function pull(name: string, repoPath: string, workDir?: string): Promise<AgentContainer.PatchResult>;
+
+export { AgentContainer };

package/dist/index.js

@@ -0,0 +1,318 @@
+// src/index.ts
+import { spawn } from "child_process";
+import { mkdtemp, writeFile, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+
+// src/docker.ts
+var BASE_DOCKERFILE = `
+FROM node:22
+
+ARG TZ
+ENV TZ="$TZ"
+
+# Install basic development tools and iptables/ipset
+RUN apt-get update && apt-get install -y --no-install-recommends   less   git   procps   sudo   fzf   zsh   man-db   unzip   gnupg2   gh   iptables   ipset   iproute2   dnsutils   aggregate   jq   nano   vim   && apt-get clean && rm -rf /var/lib/apt/lists/*
+
+# Persist bash history.
+RUN SNIPPET="export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history"   && mkdir /commandhistory   && touch /commandhistory/.bash_history
+
+# Set \`DEVCONTAINER\` environment variable to help with orientation
+ENV DEVCONTAINER=true
+
+WORKDIR /workspace
+
+ARG GIT_DELTA_VERSION=0.18.2
+RUN ARCH=$(dpkg --print-architecture) &&   wget "https://github.com/dandavison/delta/releases/download/\${GIT_DELTA_VERSION}/git-delta_\${GIT_DELTA_VERSION}_\${ARCH}.deb" &&   sudo dpkg -i "git-delta_\${GIT_DELTA_VERSION}_\${ARCH}.deb" &&   rm "git-delta_\${GIT_DELTA_VERSION}_\${ARCH}.deb"
+
+# Install global packages
+ENV NPM_CONFIG_PREFIX=/usr/local
+
+# Set the default shell to zsh rather than sh
+ENV SHELL=/bin/zsh
+
+# Set the default editor and visual
+ENV EDITOR=nano
+ENV VISUAL=nano
+
+# Default powerline10k theme
+ARG ZSH_IN_DOCKER_VERSION=1.2.0
+RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/v\${ZSH_IN_DOCKER_VERSION}/zsh-in-docker.sh)" --   -p git   -p fzf   -a "source /usr/share/doc/fzf/examples/key-bindings.zsh"   -a "source /usr/share/doc/fzf/examples/completion.zsh"   -a "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history"   -x
+
+# Save default zshrc outside /root/ so it can be seeded into the volume on first use
+RUN cp /root/.zshrc /usr/local/share/zshrc.default
+
+# Give node user ownership of dirs it needs at runtime
+RUN chown -R node:node /usr/local /workspace /commandhistory
+
+USER node
+`;
+var DEFAULT_DOCKERFILE = `ARG MAESTRO_BASE
+FROM \${MAESTRO_BASE}
+
+# Install pnpm
+ARG PNPM_VERSION
+RUN npm install -g pnpm@\${PNPM_VERSION}
+
+# Playwright needs root for apt-get system deps
+USER root
+RUN npx -y playwright@1.58.2 install --with-deps
+USER node
+
+# Install Claude
+RUN npm install -g @anthropic-ai/claude-code@latest
+`;
+
+// src/helpers.ts
+import { createHash } from "crypto";
+var CONTAINER_PREFIX = "maestro-agent";
+function getImageTag(prefix, content) {
+  const hash = createHash("sha256").update(content).digest("hex").slice(0, 8);
+  return `${prefix}:${hash}`;
+}
+function parseContainerList(stdout) {
+  if (!stdout.trim()) return [];
+  return stdout.trim().split("\n").map((line) => {
+    const [id, name, status] = line.split("	");
+    return { id: id ?? "", name: name ?? "", status: status ?? "" };
+  });
+}
+function resolveContainerName(customName, existing, prefix) {
+  if (customName !== void 0) {
+    const name = `${prefix}-${customName}`;
+    if (existing.some((c) => c.name === name)) {
+      throw new Error(`Agent container name "${customName}" is already in use`);
+    }
+    return name;
+  }
+  const usedNumbers = existing.map((c) => parseInt(c.name.replace(`${prefix}-`, ""), 10)).filter(Number.isFinite);
+  const next = usedNumbers.length > 0 ? Math.max(...usedNumbers) + 1 : 1;
+  return `${prefix}-${next}`;
+}
+function getVolumeName(volume, repoPath) {
+  if (volume) return volume;
+  const hash = createHash("sha256").update(repoPath).digest("hex").slice(0, 8);
+  return `maestro-claude-${hash}`;
+}
+function buildVscodeUri(containerName, workDir) {
+  const hex = Buffer.from(JSON.stringify({ containerName })).toString("hex");
+  return `vscode-remote://attached-container+${hex}${workDir}`;
+}
+
+// src/index.ts
+var BASE_IMAGE_TAG = getImageTag("maestro-agent-base", BASE_DOCKERFILE);
+var AgentContainer = { create, list, kill, shell, open, pull };
+async function create(config) {
+  const {
+    name: customName,
+    repoPath,
+    dockerfile,
+    workDir = "/workspace",
+    env = {},
+    memory = "8gb",
+    cpus = 2,
+    volume
+  } = config;
+  const dockerfileContent = dockerfile ?? DEFAULT_DOCKERFILE;
+  const userImageTag = await ensureImage(dockerfileContent);
+  const existing = await list();
+  const name = resolveContainerName(customName, existing, CONTAINER_PREFIX);
+  const envFlags = Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+  const memoryFlags = memory ? ["--memory", memory] : [];
+  const cpuFlags = cpus !== void 0 ? ["--cpus", String(cpus)] : [];
+  const runResult = await runDocker([
+    "run",
+    "-d",
+    "--name",
+    name,
+    "-v",
+    `${getVolumeName(volume, repoPath)}:/home/node`,
+    ...envFlags,
+    ...memoryFlags,
+    ...cpuFlags,
+    userImageTag,
+    "tail",
+    "-f",
+    "/dev/null"
+  ]);
+  if (runResult.exitCode !== 0) {
+    throw new Error(runResult.stderr || `docker run failed with exit code ${runResult.exitCode}`);
+  }
+  await exec(name, "/home/node", "test -f /home/node/.zshrc || cp /usr/local/share/zshrc.default /home/node/.zshrc");
+  const cpResult = await copyExcludingNodeModules(repoPath, name, workDir);
+  if (cpResult.exitCode !== 0) {
+    await runDocker(["rm", "-f", name]);
+    throw new Error(cpResult.stderr || `docker cp failed with exit code ${cpResult.exitCode}`);
+  }
+  await runDocker(["exec", "-u", "root", name, "chown", "-R", "node:node", workDir]);
+  const installResult = await exec(name, workDir, "pnpm install");
+  if (installResult.exitCode !== 0) {
+    throw new Error(installResult.stderr || `pnpm install failed with exit code ${installResult.exitCode}`);
+  }
+  const headResult = await runGit(["-C", repoPath, "rev-parse", "HEAD"]);
+  const hostBase = headResult.stdout.trim();
+  const initResult = await exec(
+    name,
+    workDir,
+    `git init && echo '._*' >> .git/info/exclude && git add -A && git -c user.email="agent@maestro" -c user.name="Maestro Agent" commit -m "Initial" -m "host-base:${hostBase}" && git tag maestro-base`
+  );
+  if (initResult.exitCode !== 0) {
+    await runDocker(["rm", "-f", name]);
+    throw new Error(initResult.stderr || "git init failed in container");
+  }
+  return {
+    id: name,
+    exec: (command) => exec(name, workDir, command),
+    stop: () => stop(name),
+    pull: () => pull(name, repoPath, workDir)
+  };
+}
+async function list() {
+  const result = await runDocker([
+    "ps",
+    "--filter",
+    `name=${CONTAINER_PREFIX}`,
+    "--format",
+    "{{.ID}}	{{.Names}}	{{.Status}}"
+  ]);
+  if (result.exitCode !== 0) return [];
+  return parseContainerList(result.stdout);
+}
+async function kill(name) {
+  await runDocker(["rm", "-f", name]);
+}
+function shell(name) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("docker", ["exec", "-it", name, "bash"], { stdio: "inherit" });
+    proc.on("error", reject);
+    proc.on("close", () => resolve());
+  });
+}
+function open(name, workDir = "/workspace") {
+  const uri = buildVscodeUri(name, workDir);
+  return new Promise((resolve, reject) => {
+    const proc = spawn("code", ["--folder-uri", uri], { stdio: "inherit" });
+    proc.on("error", reject);
+    proc.on("close", () => resolve());
+  });
+}
+async function pull(name, repoPath, workDir = "/workspace") {
+  await exec(name, workDir, "git add -A");
+  const diffResult = await exec(name, workDir, "git diff --binary --no-color maestro-base");
+  if (!diffResult.stdout.trim()) return { applied: false, conflicts: false };
+  await runGit(["-C", repoPath, "add", "-A"]);
+  const hostTmpDir = await mkdtemp(join(tmpdir(), "maestro-patch-"));
+  const patchPath = join(hostTmpDir, "maestro.patch");
+  try {
+    await writeFile(patchPath, stripAppleDoublePatchSections(diffResult.stdout));
+    const applyResult = await runGit(["-C", repoPath, "apply", "--3way", "--whitespace=nowarn", patchPath]);
+    if (applyResult.exitCode !== 0) {
+      if (applyResult.stderr.includes("with conflicts")) return { applied: true, conflicts: true };
+      throw new Error(applyResult.stderr || "git apply failed on host");
+    }
+  } finally {
+    await runGit(["-C", repoPath, "reset"]);
+    await rm(hostTmpDir, { recursive: true, force: true });
+  }
+  return { applied: true, conflicts: false };
+}
+async function exec(name, workDir, command) {
+  return runDocker(["exec", "-w", workDir, name, "sh", "-c", command]);
+}
+async function stop(name) {
+  await runDocker(["rm", "-f", name]);
+}
+async function ensureImage(dockerfileContent) {
+  const userImageTag = getImageTag("maestro-agent", dockerfileContent);
+  const baseResult = await runDocker(["image", "inspect", BASE_IMAGE_TAG]);
+  if (baseResult.exitCode !== 0) await buildBaseImage();
+  const userResult = await runDocker(["image", "inspect", userImageTag]);
+  if (userResult.exitCode !== 0) await buildUserImage(dockerfileContent, userImageTag);
+  return userImageTag;
+}
+async function buildBaseImage() {
+  const pnpmVersionResult = await run("pnpm", ["--version"]);
+  if (pnpmVersionResult.exitCode !== 0) throw new Error("Could not detect pnpm version");
+  const pnpmVersion = pnpmVersionResult.stdout.trim();
+  const tmpDir = await mkdtemp(join(tmpdir(), "maestro-agent-base-"));
+  try {
+    await writeFile(join(tmpDir, "Dockerfile"), BASE_DOCKERFILE);
+    const result = await runDocker(["build", "-t", BASE_IMAGE_TAG, "--build-arg", `PNPM_VERSION=${pnpmVersion}`, tmpDir]);
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || `docker build failed with exit code ${result.exitCode}`);
+    }
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+}
+async function buildUserImage(dockerfileContent, userImageTag) {
+  const tmpDir = await mkdtemp(join(tmpdir(), "maestro-agent-"));
+  try {
+    const dockerfilePath = join(tmpDir, "Dockerfile");
+    await writeFile(dockerfilePath, dockerfileContent);
+    const result = await runDocker([
+      "build",
+      "-t",
+      userImageTag,
+      "--build-arg",
+      `MAESTRO_BASE=${BASE_IMAGE_TAG}`,
+      "-f",
+      dockerfilePath,
+      tmpDir
+    ]);
+    if (result.exitCode !== 0) {
+      throw new Error(result.stderr || `docker build failed with exit code ${result.exitCode}`);
+    }
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+}
+function copyExcludingNodeModules(repoPath, containerName, workDir) {
+  return new Promise((resolve) => {
+    const gitLsFiles = spawn("git", ["-C", repoPath, "ls-files", "--cached", "--others", "--exclude-standard"]);
+    const tar = spawn("tar", ["-cf", "-", "-C", repoPath, "--files-from", "-"]);
+    const dockerCp = spawn("docker", ["cp", "-", `${containerName}:${workDir}`]);
+    const stderrChunks = [];
+    gitLsFiles.stdout.pipe(tar.stdin);
+    tar.stdout.pipe(dockerCp.stdin);
+    gitLsFiles.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+    tar.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+    dockerCp.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+    gitLsFiles.on("error", (err) => resolve({ stdout: "", stderr: err.message, exitCode: 1 }));
+    tar.on("error", (err) => resolve({ stdout: "", stderr: err.message, exitCode: 1 }));
+    dockerCp.on("error", (err) => resolve({ stdout: "", stderr: err.message, exitCode: 1 }));
+    dockerCp.on(
+      "close",
+      (code) => resolve({ stdout: "", stderr: Buffer.concat(stderrChunks).toString(), exitCode: code ?? 1 })
+    );
+  });
+}
+function stripAppleDoublePatchSections(patch) {
+  const sections = patch.split(/(?=^diff --git )/m);
+  return sections.filter((section) => !section.match(/^diff --git a\/(?:.*\/)?\._/m)).join("");
+}
+function runGit(args) {
+  return run("git", args);
+}
+function runDocker(args) {
+  return run("docker", args);
+}
+function run(cmd, args) {
+  return new Promise((resolve) => {
+    const proc = spawn(cmd, args);
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    proc.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+    proc.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+    proc.on("close", (code) => {
+      resolve({
+        stdout: Buffer.concat(stdoutChunks).toString(),
+        stderr: Buffer.concat(stderrChunks).toString(),
+        exitCode: code ?? 1
+      });
+    });
+  });
+}
+export {
+  AgentContainer
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@maestro-js/agent-container",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11"
+  },
+  "description": "Docker-based isolated agent execution environment with patch-based sync. Use when you need to create sandboxed containers for AI agents, run code in isolated Docker environments, pull container changes back to the host working tree as patches, or manage container lifecycles. Provides create, list, kill, shell, open (VS Code), and pull operations. Containers include Node.js 22, pnpm, Claude CLI, Playwright, git, and zsh.",
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "test": "beartest ./tests/**/*",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write src/",
+    "lint": "prettier --check src/",
+    "watch": "tsup --watch --config ../../tsup.config.ts"
+  }
+}