@fitlab-ai/agent-infra 0.6.4 → 0.7.0

package/dist/lib/sandbox/index.js

@@ -2,13 +2,15 @@ const USAGE = `Usage: ai sandbox <command> [options]
 
 Commands:
   create <branch> [base]       Create a sandbox (VM + image + worktree + container)
-  exec <branch> [cmd...]       Enter sandbox or run a command
-  refresh                      Sync host Claude Code credentials to all sandbox copies
+  exec <branch | '#N'> [cmd...]
+                               Enter sandbox or run a command (use leftmost '#' column from 'ls')
   ls                           List sandboxes for the current project
-  rm <branch> [--all]          Remove a sandbox or all sandboxes
   prune [--dry-run]            Remove orphaned per-branch state dirs
+  rebuild [--quiet] [--refresh]
+                               Rebuild the sandbox image (--refresh pulls base + tools)
+  refresh                      Sync host Claude Code credentials to all sandbox copies
+  rm <branch> [--all]          Remove a sandbox or all sandboxes
   vm status|start|stop         Manage the sandbox VM (macOS) or check the backend (Windows)
-  rebuild [--quiet]            Rebuild the sandbox image
 
 Run 'ai sandbox <command> --help' for details.`;
 export async function runSandbox(args) {

package/dist/lib/sandbox/readme-scaffold.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { shareBranchDir, shareCommonDir } from "./constants.js";
+const DOTFILES_README = `# User-level dotfiles channel
+
+This directory is mounted **read-only** into every sandbox container at
+\`/dotfiles\`. On entry, \`sandbox-dotfiles-link\` mirrors every file here as a
+symlink under \`$HOME\` (e.g. \`.tmux.conf\` -> \`/home/devuser/.tmux.conf\`),
+overriding image defaults so your editor, shell, and tool preferences follow
+you across \`ai sandbox destroy + create\`.
+
+See: https://github.com/fitlab-ai/agent-infra/blob/main/README.md#user-level-dotfiles-channel
+
+Common usage - drop files or symlinks here:
+
+\`\`\`sh
+# Real files
+echo "set -g mouse on" > ~/.agent-infra/dotfiles/.tmux.conf
+
+# Symlinks to live host paths
+ln -s ~/.tmux.conf       ~/.agent-infra/dotfiles/.tmux.conf
+ln -s ~/.config/lazygit  ~/.agent-infra/dotfiles/.config/lazygit
+\`\`\`
+
+> Do **not** put secrets here. Use the dedicated SSH / credential mounts.
+
+If you delete this file, the next \`ai sandbox create\` will re-create it
+verbatim. To stop seeing it, edit or empty the file in place - the scaffold
+only writes \`README.md\` when it is missing, never when it already exists.
+
+---
+
+# 用户级 dotfiles 通道
+
+该目录被以**只读**方式挂载到每个 sandbox 容器的 \`/dotfiles\`。容器启动时，
+\`sandbox-dotfiles-link\` 会把这里的每个文件 \`ln -sfn\` 到 \`$HOME\` 对应路径
+（例如 \`.tmux.conf -> /home/devuser/.tmux.conf\`），覆盖镜像默认值，让你的编辑器、
+shell、工具偏好跨 \`ai sandbox destroy + create\` 持久存在。
+
+参考：https://github.com/fitlab-ai/agent-infra/blob/main/README.zh-CN.md#用户级-dotfiles-通道
+
+常见用法：把文件或符号链接放进来：
+
+\`\`\`sh
+# 直接放文件
+echo "set -g mouse on" > ~/.agent-infra/dotfiles/.tmux.conf
+
+# 用符号链接指向 host 实际文件
+ln -s ~/.tmux.conf       ~/.agent-infra/dotfiles/.tmux.conf
+ln -s ~/.config/lazygit  ~/.agent-infra/dotfiles/.config/lazygit
+\`\`\`
+
+> **不要**在此放任何凭证。SSH / 凭证请使用专用挂载通道。
+
+如果你删除该文件，下一次 \`ai sandbox create\` 会原样重新生成。如果你不想再
+看到它，**就地编辑或清空内容**即可：scaffold 仅在 \`README.md\` **缺失**时
+写入，文件存在（哪怕被清空）就不会被重写。
+`;
+const SHARE_COMMON_README = `# /share/common - host <-> sandbox shared scratch (cross-branch)
+
+This directory is mounted **read-write** into every sandbox container of this
+project at \`/share/common\`, regardless of branch. Drop files here to share
+between host and any sandbox without polluting the git worktree.
+
+See: https://github.com/fitlab-ai/agent-infra/blob/main/README.md#host-sandbox-file-exchange
+
+This file is safe to delete; the next \`ai sandbox create\` will re-create it.
+
+---
+
+# /share/common - 宿主 <-> sandbox 共享暂存（跨分支）
+
+该目录被以**读写**方式挂载到本项目所有 sandbox 容器的 \`/share/common\`，
+跨分支可见。可用来在宿主和任意 sandbox 之间传文件，无需弄脏 git worktree。
+
+参考：https://github.com/fitlab-ai/agent-infra/blob/main/README.zh-CN.md#宿主-沙箱文件交换
+
+该文件可以安全删除；下一次 \`ai sandbox create\` 会重新生成。
+`;
+const SHARE_BRANCH_README = `# /share/branch - host <-> sandbox shared scratch (branch-exclusive)
+
+This directory is mounted **read-write** into the sandbox container of this
+project's current branch at \`/share/branch\`. Files here are exclusive to this
+branch's sandbox and do not leak across branches.
+
+See: https://github.com/fitlab-ai/agent-infra/blob/main/README.md#host-sandbox-file-exchange
+
+This file is safe to delete; the next \`ai sandbox create\` will re-create it.
+
+---
+
+# /share/branch - 宿主 <-> sandbox 共享暂存（分支独占）
+
+该目录被以**读写**方式挂载到本项目当前分支 sandbox 容器的 \`/share/branch\`，
+仅当前分支可见，不会跨分支泄漏。
+
+参考：https://github.com/fitlab-ai/agent-infra/blob/main/README.zh-CN.md#宿主-沙箱文件交换
+
+该文件可以安全删除；下一次 \`ai sandbox create\` 会重新生成。
+`;
+function errorDetail(error) {
+    return error instanceof Error ? error.message : 'unknown error';
+}
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code)
+        : '';
+}
+function ensureFile(target, content, options) {
+    const writeStderr = options.writeStderr ?? ((chunk) => process.stderr.write(chunk));
+    const fsModule = options.fsModule ?? fs;
+    const result = { created: false, path: target };
+    try {
+        fsModule.mkdirSync(path.dirname(target), { recursive: true });
+    }
+    catch (error) {
+        writeStderr(`sandbox-readme-scaffold: skipping ${target} (${errorDetail(error)})\n`);
+        return result;
+    }
+    try {
+        fsModule.writeFileSync(target, content, { encoding: 'utf8', flag: 'wx' });
+        result.created = true;
+    }
+    catch (error) {
+        if (errorCode(error) === 'EEXIST') {
+            return result;
+        }
+        writeStderr(`sandbox-readme-scaffold: skipping ${target} (${errorDetail(error)})\n`);
+    }
+    return result;
+}
+export function ensureDotfilesReadme(dotfilesDir, options = {}) {
+    return ensureFile(path.join(dotfilesDir, 'README.md'), DOTFILES_README, options);
+}
+export function ensureShareCommonReadme(config, options = {}) {
+    return ensureFile(path.join(shareCommonDir(config), 'README.md'), SHARE_COMMON_README, options);
+}
+export function ensureShareBranchReadme(config, branch, options = {}) {
+    return ensureFile(path.join(shareBranchDir(config, branch), 'README.md'), SHARE_BRANCH_README, options);
+}
+export function ensureSandboxDiscoveryReadmes(config, branch, options = {}) {
+    return [
+        ensureDotfilesReadme(config.dotfilesDir, options),
+        ensureShareCommonReadme(config, options),
+        ensureShareBranchReadme(config, branch, options)
+    ];
+}
+//# sourceMappingURL=readme-scaffold.js.map

package/dist/lib/sandbox/runtimes/ai-tools.dockerfile

@@ -1,17 +1,23 @@
 USER devuser
+ENV DISABLE_UPDATES=1
+ENV OPENCODE_DISABLE_AUTOUPDATE=1
 ENV NPM_CONFIG_PREFIX=/home/devuser/.npm-global
 ENV PATH="/home/devuser/.npm-global/bin:${PATH}"
 
-ARG AI_TOOL_PACKAGES
-RUN if [ -z "${AI_TOOL_PACKAGES}" ]; then \
-      echo "AI_TOOL_PACKAGES build arg is required"; \
-      exit 1; \
-    fi && \
-    set -e && \
+ARG AI_TOOL_PACKAGES=
+RUN set -e && \
     for pkg in ${AI_TOOL_PACKAGES}; do \
       npm install -g "$pkg"; \
     done
 
+ARG AI_TOOLS_SHELL_INSTALL_B64=
+RUN if [ -n "${AI_TOOLS_SHELL_INSTALL_B64}" ]; then \
+      set -e && \
+      echo "${AI_TOOLS_SHELL_INSTALL_B64}" | base64 -d > /tmp/ai-tools-install.sh && \
+      bash /tmp/ai-tools-install.sh && \
+      rm /tmp/ai-tools-install.sh; \
+    fi
+
 RUN npm install -g pyright
 
 RUN mkdir -p /home/devuser/.local/share /home/devuser/.local/state

package/dist/lib/sandbox/runtimes/base.dockerfile

@@ -1,4 +1,4 @@
-FROM ubuntu:22.04
+FROM ubuntu:24.04
 
 LABEL description="AI coding sandbox"
 
@@ -28,7 +28,7 @@ RUN apt-get update && apt-get install -y \
     && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
         > /etc/apt/sources.list.d/github-cli.list \
     && apt-get update && apt-get install -y gh \
-    && TMUX_VERSION=3.6a \
+    && TMUX_VERSION=3.6b \
     && wget -qO /tmp/tmux.tar.gz \
         "https://github.com/tmux/tmux/releases/download/${TMUX_VERSION}/tmux-${TMUX_VERSION}.tar.gz" \
     && tar xzf /tmp/tmux.tar.gz -C /tmp \
@@ -126,7 +126,7 @@ find . -type f -print | while IFS= read -r rel; do
     .config/opencode|.config/opencode/*|\
     .local/share/opencode|.local/share/opencode/*|\
     .host-shell-config|.host-shell-config/*|\
-    .gitconfig|.gitignore_global|.stCommitMsg|.bash_aliases)
+    .gitconfig|.gitignore_global|.stCommitMsg|.bash_aliases|README.md)
       continue ;;
   esac
 

package/dist/lib/sandbox/tools.js

@@ -1,11 +1,12 @@
 import { safeNameCandidates, sanitizeBranchName } from "./constants.js";
 import { hostJoin } from "./engines/wsl2-paths.js";
+const TOOL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 function createBuiltinTools(home, project) {
     return {
         'claude-code': {
             id: 'claude-code',
             name: 'Claude Code',
-            npmPackage: '@anthropic-ai/claude-code@stable',
+            install: { type: 'npm', cmd: '@anthropic-ai/claude-code@stable' },
             sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'claude-code'),
             containerMount: '/home/devuser/.claude',
             versionCmd: 'claude --version',
@@ -35,7 +36,7 @@ function createBuiltinTools(home, project) {
         codex: {
             id: 'codex',
             name: 'Codex',
-            npmPackage: '@openai/codex',
+            install: { type: 'npm', cmd: '@openai/codex' },
             sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'codex'),
             containerMount: '/home/devuser/.codex',
             versionCmd: 'codex --version',
@@ -50,7 +51,7 @@ function createBuiltinTools(home, project) {
         opencode: {
             id: 'opencode',
             name: 'OpenCode',
-            npmPackage: 'opencode-ai',
+            install: { type: 'npm', cmd: 'opencode-ai' },
             sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'opencode'),
             containerMount: '/home/devuser/.local/share/opencode',
             versionCmd: 'opencode version',
@@ -69,7 +70,7 @@ function createBuiltinTools(home, project) {
         'gemini-cli': {
             id: 'gemini-cli',
             name: 'Gemini CLI',
-            npmPackage: '@google/gemini-cli',
+            install: { type: 'npm', cmd: '@google/gemini-cli' },
             sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'gemini-cli'),
             containerMount: '/home/devuser/.gemini',
             versionCmd: 'gemini --version',
@@ -84,15 +85,200 @@ function createBuiltinTools(home, project) {
         }
     };
 }
+export function builtinToolIds() {
+    return Object.keys(createBuiltinTools('', ''));
+}
 function validateTool(tool) {
-    if (!tool.npmPackage || !tool.containerMount.startsWith('/')) {
-        throw new Error(`Invalid sandbox tool descriptor: ${tool.id}`);
+    if (!tool.id || !TOOL_ID_PATTERN.test(tool.id)) {
+        throw new Error(`Invalid sandbox tool id: ${String(tool.id)}`);
+    }
+    if (!tool.install || (tool.install.type !== 'npm' && tool.install.type !== 'shell')) {
+        throw new Error(`Sandbox tool ${tool.id} has invalid install.type`);
+    }
+    if (!tool.install.cmd) {
+        throw new Error(`Sandbox tool ${tool.id} has empty install.cmd`);
+    }
+    if (!tool.containerMount || !tool.containerMount.startsWith('/')) {
+        throw new Error(`Sandbox tool ${tool.id} containerMount must be an absolute path`);
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asString(value, field, context) {
+    if (typeof value !== 'string') {
+        throw new Error(`${context}: field "${field}" must be a string`);
+    }
+    return value;
+}
+function asOptionalNonEmptyString(value, field, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`${context}: field "${field}" must be a string when provided`);
+    }
+    if (value.length === 0) {
+        throw new Error(`${context}: field "${field}" must be non-empty when provided`);
+    }
+    return value;
+}
+function asStringRecord(value, field, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isPlainObject(value)) {
+        throw new Error(`${context}: field "${field}" must be an object when provided`);
+    }
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+        if (typeof val !== 'string') {
+            throw new Error(`${context}: field "${field}.${key}" must be a string`);
+        }
+        out[key] = val;
+    }
+    return out;
+}
+function asStringArray(value, field, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${context}: field "${field}" must be an array when provided`);
+    }
+    return value.map((item, index) => {
+        if (typeof item !== 'string') {
+            throw new Error(`${context}: field "${field}[${index}]" must be a string`);
+        }
+        return item;
+    });
+}
+function parseInstall(value, context) {
+    if (!isPlainObject(value)) {
+        throw new Error(`${context}: field "install" must be an object`);
+    }
+    const type = value.type;
+    if (type !== 'npm' && type !== 'shell') {
+        throw new Error(`${context}: field "install.type" must be "npm" or "shell"`);
+    }
+    const cmd = asString(value.cmd, 'install.cmd', context);
+    if (!cmd) {
+        throw new Error(`${context}: field "install.cmd" must be non-empty`);
+    }
+    return { type, cmd };
+}
+function parseHostPreSeedFiles(value, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${context}: field "hostPreSeedFiles" must be an array when provided`);
     }
+    return value.map((item, index) => {
+        if (!isPlainObject(item)) {
+            throw new Error(`${context}: field "hostPreSeedFiles[${index}]" must be an object`);
+        }
+        return {
+            hostPath: asString(item.hostPath, `hostPreSeedFiles[${index}].hostPath`, context),
+            sandboxName: asString(item.sandboxName, `hostPreSeedFiles[${index}].sandboxName`, context)
+        };
+    });
+}
+function parseHostPreSeedDirs(value, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${context}: field "hostPreSeedDirs" must be an array when provided`);
+    }
+    return value.map((item, index) => {
+        if (!isPlainObject(item)) {
+            throw new Error(`${context}: field "hostPreSeedDirs[${index}]" must be an object`);
+        }
+        return {
+            hostDir: asString(item.hostDir, `hostPreSeedDirs[${index}].hostDir`, context),
+            sandboxSubdir: asString(item.sandboxSubdir, `hostPreSeedDirs[${index}].sandboxSubdir`, context)
+        };
+    });
+}
+function parseHostLiveMounts(value, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${context}: field "hostLiveMounts" must be an array when provided`);
+    }
+    return value.map((item, index) => {
+        if (!isPlainObject(item)) {
+            throw new Error(`${context}: field "hostLiveMounts[${index}]" must be an object`);
+        }
+        return {
+            hostPath: asString(item.hostPath, `hostLiveMounts[${index}].hostPath`, context),
+            containerSubpath: asString(item.containerSubpath, `hostLiveMounts[${index}].containerSubpath`, context)
+        };
+    });
+}
+export function parseCustomTool(entry, index, options) {
+    const context = `customTools[${index}]`;
+    if (!isPlainObject(entry)) {
+        throw new Error(`${context} must be an object`);
+    }
+    const id = asString(entry.id, 'id', context);
+    if (!TOOL_ID_PATTERN.test(id)) {
+        throw new Error(`${context}: field "id" must match ${TOOL_ID_PATTERN.source}`);
+    }
+    const containerMount = asOptionalNonEmptyString(entry.containerMount, 'containerMount', context)
+        ?? `/home/devuser/.${id}`;
+    if (!containerMount.startsWith('/')) {
+        throw new Error(`${context}: field "containerMount" must be an absolute path`);
+    }
+    const tool = {
+        id,
+        name: asOptionalNonEmptyString(entry.name, 'name', context) ?? id,
+        install: parseInstall(entry.install, context),
+        sandboxBase: hostJoin(options.home, '.agent-infra', 'sandboxes', id),
+        containerMount,
+        versionCmd: asOptionalNonEmptyString(entry.versionCmd, 'versionCmd', context) ?? `which ${id}`,
+        setupHint: asOptionalNonEmptyString(entry.setupHint, 'setupHint', context)
+            ?? `Run \`${id}\` inside the container to set up.`,
+        envVars: asStringRecord(entry.envVars, 'envVars', context),
+        hostPreSeedFiles: parseHostPreSeedFiles(entry.hostPreSeedFiles, context),
+        hostPreSeedDirs: parseHostPreSeedDirs(entry.hostPreSeedDirs, context),
+        pathRewriteFiles: asStringArray(entry.pathRewriteFiles, 'pathRewriteFiles', context),
+        hostLiveMounts: parseHostLiveMounts(entry.hostLiveMounts, context),
+        postSetupCmds: asStringArray(entry.postSetupCmds, 'postSetupCmds', context)
+    };
+    validateTool(tool);
+    return tool;
+}
+export function parseCustomTools(value, options) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error('sandbox: "customTools" must be an array');
+    }
+    return value.map((entry, index) => parseCustomTool(entry, index, options));
 }
 export function resolveTools(config) {
     const builtins = createBuiltinTools(config.home, config.project);
+    const customs = config.customTools ?? [];
+    const seen = new Set();
+    for (const tool of customs) {
+        if (builtins[tool.id]) {
+            throw new Error(`Custom sandbox tool id "${tool.id}" collides with a built-in tool`);
+        }
+        if (seen.has(tool.id)) {
+            throw new Error(`Duplicate sandbox tool id "${tool.id}" in customTools`);
+        }
+        seen.add(tool.id);
+    }
+    const merged = { ...builtins };
+    for (const tool of customs) {
+        merged[tool.id] = tool;
+    }
     return config.tools.map((id) => {
-        const tool = builtins[id];
+        const tool = merged[id];
         if (!tool) {
             throw new Error(`Unknown sandbox tool: ${id}`);
         }
@@ -110,6 +296,25 @@ export function toolProjectDirCandidates(tool, project) {
     return [hostJoin(tool.sandboxBase, project)];
 }
 export function toolNpmPackagesArg(tools) {
-    return tools.map((tool) => tool.npmPackage).join(' ');
+    return tools
+        .filter((tool) => tool.install.type === 'npm')
+        .map((tool) => tool.install.cmd)
+        .join(' ');
+}
+export function toolShellInstallScript(tools) {
+    const blocks = tools
+        .filter((tool) => tool.install.type === 'shell')
+        .map((tool) => `# install: ${tool.id}\n${tool.install.cmd}`);
+    if (blocks.length === 0) {
+        return '';
+    }
+    return ['#!/bin/bash', 'set -e', '', ...blocks, ''].join('\n');
+}
+export function toolShellInstallScriptBase64(tools) {
+    const script = toolShellInstallScript(tools);
+    return script ? Buffer.from(script, 'utf8').toString('base64') : '';
+}
+export function imageSignatureFields(tools) {
+    return tools.map((tool) => ({ id: tool.id, install: tool.install }));
 }
 //# sourceMappingURL=tools.js.map

package/dist/lib/update.js

@@ -121,6 +121,7 @@ async function cmdUpdate() {
     const platformAdded = !config.platform;
     const sandboxAdded = !config.sandbox;
     const labelsAdded = !config.labels;
+    const requiresPullRequestAdded = config.requiresPullRequest === undefined;
     let configChanged = changed;
     if (platformAdded) {
         config.platform = structuredClone(defaults.platform);
@@ -134,6 +135,10 @@ async function cmdUpdate() {
         config.labels = structuredClone(defaults.labels);
         configChanged = true;
     }
+    if (requiresPullRequestAdded) {
+        config.requiresPullRequest = defaults.requiresPullRequest;
+        configChanged = true;
+    }
     if (configChanged) {
         console.log('');
         if (hasNewEntries) {
@@ -145,7 +150,7 @@ async function cmdUpdate() {
                 ok(`  merged: ${entry}`);
             }
         }
-        else if (platformAdded || sandboxAdded || labelsAdded) {
+        else if (platformAdded || sandboxAdded || labelsAdded || requiresPullRequestAdded) {
             if (platformAdded) {
                 info(`Default platform config added to ${CONFIG_PATH}.`);
             }
@@ -155,6 +160,9 @@ async function cmdUpdate() {
             if (labelsAdded) {
                 info(`Default labels.in config added to ${CONFIG_PATH}.`);
             }
+            if (requiresPullRequestAdded) {
+                info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+            }
         }
         else {
             info(`File registry changed in ${CONFIG_PATH}.`);
@@ -168,6 +176,9 @@ async function cmdUpdate() {
         if (hasNewEntries && platformAdded) {
             info(`Default platform config added to ${CONFIG_PATH}.`);
         }
+        if (hasNewEntries && requiresPullRequestAdded) {
+            info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+        }
         fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
         ok(`Updated ${CONFIG_PATH}`);
     }