@fitlab-ai/agent-infra 0.6.4 → 0.7.0

package/lib/sandbox/commands/rebuild.ts

@@ -8,12 +8,17 @@ import { prepareDockerfile } from '../dockerfile.ts';
 import { sandboxImageConfigLabel, sandboxLabel } from '../constants.ts';
 import { detectEngine, ensureDocker } from '../engine.ts';
 import { runEngine, runOkEngine, runSafeEngine, runVerboseEngine } from '../shell.ts';
-import { resolveTools, toolNpmPackagesArg } from '../tools.ts';
+import {
+  imageSignatureFields,
+  resolveTools,
+  toolNpmPackagesArg,
+  toolShellInstallScriptBase64
+} from '../tools.ts';
 import type { SandboxTool } from '../tools.ts';
 import { toEnginePath } from '../engines/wsl2-paths.ts';
 import { resolveBuildUid } from '../engines/native.ts';
 
-const USAGE = `Usage: ai sandbox rebuild [--quiet]`;
+const USAGE = `Usage: ai sandbox rebuild [--quiet] [--refresh]`;
 
 type PreparedDockerfile = ReturnType<typeof prepareDockerfile>;
 type EngineRunFn = (engine: string, cmd: string, args: string[], opts?: { cwd?: string }) => string;
@@ -23,7 +28,7 @@ function buildSignature(preparedDockerfile: PreparedDockerfile, tools: SandboxTo
   return createHash('sha256')
     .update(JSON.stringify({
       dockerfile: preparedDockerfile.signature,
-      tools: tools.map((tool) => tool.npmPackage)
+      tools: imageSignatureFields(tools)
     }))
     .digest('hex')
     .slice(0, 12);
@@ -38,12 +43,14 @@ export function buildArgs(
     engine,
     runFn = runEngine,
     runSafeFn = runSafeEngine,
-    env = process.env
+    env = process.env,
+    refresh = false
   }: {
     engine?: string;
     runFn?: EngineRunFn;
     runSafeFn?: EngineRunSafeFn;
     env?: NodeJS.ProcessEnv;
+    refresh?: boolean;
   } = {}
 ): string[] {
   const selectedEngine = engine ?? detectEngine(config);
@@ -54,7 +61,7 @@ export function buildArgs(
     env
   });
 
-  return [
+  const args = [
     'build',
     '-t',
     config.imageName,
@@ -64,6 +71,8 @@ export function buildArgs(
     `HOST_GID=${hostGid}`,
     '--build-arg',
     `AI_TOOL_PACKAGES=${toolNpmPackagesArg(tools)}`,
+    '--build-arg',
+    `AI_TOOLS_SHELL_INSTALL_B64=${toolShellInstallScriptBase64(tools)}`,
     '--label',
     sandboxLabel(config),
     '--label',
@@ -72,6 +81,12 @@ export function buildArgs(
     toEnginePath(selectedEngine, dockerfilePath),
     toEnginePath(selectedEngine, config.repoRoot)
   ];
+
+  if (refresh) {
+    args.splice(1, 0, '--no-cache', '--pull');
+  }
+
+  return args;
 }
 
 function removeImageIfPresent(imageName: string, engine: string): void {
@@ -86,6 +101,7 @@ export async function rebuild(args: string[]): Promise<void> {
     allowPositionals: true,
     strict: true,
     options: {
+      refresh: { type: 'boolean' },
       quiet: { type: 'boolean', short: 'q' },
       help: { type: 'boolean', short: 'h' }
     }
@@ -101,6 +117,7 @@ export async function rebuild(args: string[]): Promise<void> {
   const preparedDockerfile = prepareDockerfile(config);
   const imageSignature = buildSignature(preparedDockerfile, tools);
   const quiet = values.quiet ?? false;
+  const refresh = values.refresh ?? false;
   const engine = detectEngine(config);
 
   await ensureDocker(config, undefined);
@@ -113,7 +130,7 @@ export async function rebuild(args: string[]): Promise<void> {
       removeImageIfPresent(config.imageName, engine);
       spinner.stop('Old image removed');
       spinner.start('Building image...');
-      runEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine }), {
+      runEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine, refresh }), {
         cwd: config.repoRoot
       });
       spinner.stop(pc.green('Sandbox image rebuilt'));
@@ -124,7 +141,7 @@ export async function rebuild(args: string[]): Promise<void> {
       runVerboseEngine(
         engine,
         'docker',
-        buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine }),
+        buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine, refresh }),
         { cwd: config.repoRoot }
       );
       p.log.success(pc.green('Sandbox image rebuilt'));

package/lib/sandbox/config.ts

@@ -6,6 +6,8 @@ import pc from 'picocolors';
 import { validateSandboxEngine } from './engine.ts';
 import { hostJoin } from './engines/wsl2-paths.ts';
 import { findRuntimeEngineMismatches } from './runtime-engines.ts';
+import { parseCustomTools } from './tools.ts';
+import type { SandboxTool } from './tools.ts';
 
 const DEFAULTS = Object.freeze({
   engine: null,
@@ -26,6 +28,7 @@ type SandboxConfigInput = {
   engine?: string | null;
   runtimes?: string[];
   tools?: string[];
+  customTools?: unknown;
   dockerfile?: string | null;
   vm?: Record<string, unknown>;
 };
@@ -51,6 +54,7 @@ export type SandboxConfig = {
   engine: string | null;
   runtimes: string[];
   tools: string[];
+  customTools: SandboxTool[];
   dockerfile: string | null;
   vm: SandboxVmConfig;
 };
@@ -136,6 +140,8 @@ export function loadConfig({
     }
   }
 
+  const customTools = parseCustomTools(sandbox.customTools, { home });
+
   return {
     repoRoot,
     configPath,
@@ -153,6 +159,7 @@ export function loadConfig({
     tools: Array.isArray(sandbox.tools) && sandbox.tools.length > 0
       ? [...sandbox.tools]
       : defaults.tools,
+    customTools,
     dockerfile,
     vm: {
       cpu: asPositiveNumberOrNull(sandbox.vm?.cpu) ?? defaults.vm.cpu,

package/lib/sandbox/index.ts

@@ -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.`;
 

package/lib/sandbox/readme-scaffold.ts

@@ -0,0 +1,177 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { shareBranchDir, shareCommonDir } from './constants.ts';
+
+type ScaffoldResult = { created: boolean; path: string };
+type WriteStderr = (chunk: string) => void;
+type ScaffoldFs = Pick<typeof fs, 'mkdirSync' | 'writeFileSync'>;
+type ScaffoldOptions = {
+  writeStderr?: WriteStderr;
+  fsModule?: ScaffoldFs;
+};
+
+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: unknown): string {
+  return error instanceof Error ? error.message : 'unknown error';
+}
+
+function errorCode(error: unknown): string {
+  return typeof error === 'object' && error !== null && 'code' in error
+    ? String(error.code)
+    : '';
+}
+
+function ensureFile(target: string, content: string, options: ScaffoldOptions): ScaffoldResult {
+  const writeStderr = options.writeStderr ?? ((chunk) => process.stderr.write(chunk));
+  const fsModule = options.fsModule ?? fs;
+  const result: ScaffoldResult = { 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: string, options: ScaffoldOptions = {}): ScaffoldResult {
+  return ensureFile(path.join(dotfilesDir, 'README.md'), DOTFILES_README, options);
+}
+
+export function ensureShareCommonReadme(
+  config: { shareBase: string },
+  options: ScaffoldOptions = {}
+): ScaffoldResult {
+  return ensureFile(path.join(shareCommonDir(config), 'README.md'), SHARE_COMMON_README, options);
+}
+
+export function ensureShareBranchReadme(
+  config: { shareBase: string },
+  branch: string,
+  options: ScaffoldOptions = {}
+): ScaffoldResult {
+  return ensureFile(path.join(shareBranchDir(config, branch), 'README.md'), SHARE_BRANCH_README, options);
+}
+
+export function ensureSandboxDiscoveryReadmes(
+  config: { shareBase: string; dotfilesDir: string },
+  branch: string,
+  options: ScaffoldOptions = {}
+): ScaffoldResult[] {
+  return [
+    ensureDotfilesReadme(config.dotfilesDir, options),
+    ensureShareCommonReadme(config, options),
+    ensureShareBranchReadme(config, branch, options)
+  ];
+}

package/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/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