@fitlab-ai/agent-infra 0.6.5 → 0.7.1

package/lib/sandbox/commands/rebuild.ts

@@ -7,8 +7,14 @@ import type { SandboxConfig } from '../config.ts';
 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 { runEngine, runSafeEngine, runVerboseEngine } from '../shell.ts';
+import { pruneSandboxDanglingImages } from '../image-prune.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';
@@ -23,7 +29,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);
@@ -66,6 +72,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',
@@ -82,12 +90,6 @@ export function buildArgs(
   return args;
 }
 
-function removeImageIfPresent(imageName: string, engine: string): void {
-  if (runOkEngine(engine, 'docker', ['image', 'inspect', imageName])) {
-    runEngine(engine, 'docker', ['rmi', imageName]);
-  }
-}
-
 export async function rebuild(args: string[]): Promise<void> {
   const { values } = parseArgs({
     args,
@@ -119,17 +121,12 @@ export async function rebuild(args: string[]): Promise<void> {
   try {
     if (quiet) {
       const spinner = p.spinner();
-      spinner.start(`Removing old image ${config.imageName}...`);
-      removeImageIfPresent(config.imageName, engine);
-      spinner.stop('Old image removed');
       spinner.start('Building image...');
       runEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine, refresh }), {
         cwd: config.repoRoot
       });
       spinner.stop(pc.green('Sandbox image rebuilt'));
     } else {
-      p.log.step(`Removing old image ${config.imageName}`);
-      removeImageIfPresent(config.imageName, engine);
       p.log.step('Building image');
       runVerboseEngine(
         engine,
@@ -139,6 +136,7 @@ export async function rebuild(args: string[]): Promise<void> {
       );
       p.log.success(pc.green('Sandbox image rebuilt'));
     }
+    pruneSandboxDanglingImages(config, engine);
   } finally {
     preparedDockerfile.cleanup();
   }

package/lib/sandbox/commands/rm.ts

@@ -15,6 +15,7 @@ import {
   worktreeDirCandidates
 } from '../constants.ts';
 import { ENGINES, detectEngine, engineDisplayName, isManagedEngine, stopManagedVm } from '../engine.ts';
+import { pruneSandboxDanglingImages } from '../image-prune.ts';
 import { removeManagedDir, removeWorktreeDir } from '../managed-fs.ts';
 import { runOk, runSafe, runSafeEngine } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
@@ -208,6 +209,8 @@ async function rmAll(config: SandboxConfig, tools: SandboxTool[]): Promise<void>
     runSafeEngine(engine, 'docker', ['rmi', config.imageName]);
   }
 
+  pruneSandboxDanglingImages(config, engine);
+
   if (isManagedEngine(engine)) {
     if (engine === ENGINES.WSL2) {
       p.log.warn('Windows uses Docker Desktop with WSL2. Stop it from Docker Desktop or run "wsl --shutdown" manually.');

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/image-prune.ts

@@ -0,0 +1,23 @@
+import * as p from '@clack/prompts';
+import type { SandboxConfig } from './config.ts';
+import { sandboxLabel } from './constants.ts';
+import { runEngine } from './shell.ts';
+
+export function pruneSandboxDanglingImages(
+  config: Pick<SandboxConfig, 'project'>,
+  engine: string
+): void {
+  try {
+    runEngine(engine, 'docker', [
+      'image',
+      'prune',
+      '-f',
+      '--filter',
+      `label=${sandboxLabel(config)}`
+    ]);
+  } catch {
+    p.log.warn(
+      `Failed to prune dangling sandbox images (label=${sandboxLabel(config)}); leaving them in place.`
+    );
+  }
+}

package/lib/sandbox/index.ts

@@ -2,7 +2,8 @@ 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
+  exec <branch | '#N'> [cmd...]
+                               Enter sandbox or run a command (use leftmost '#' column from 'ls')
   ls                           List sandboxes for the current project
   prune [--dry-run]            Remove orphaned per-branch state dirs
   rebuild [--quiet] [--refresh]

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

@@ -4,16 +4,20 @@ 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/task-resolver.ts

@@ -1,9 +1,27 @@
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+const SHORT_ID_RE = /^#\d+$/;
 const WORKSPACE_DIRS = ['active', 'completed', 'blocked', 'archive'];
 
+function resolveShortIdStrict(arg: string, repoRoot: string): string {
+  const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
+  if (!fs.existsSync(scriptPath)) {
+    throw new Error(
+      `Short id '${arg}' provided but task-short-id.js script is missing at ${scriptPath}`
+    );
+  }
+  const result = spawnSync('node', [scriptPath, 'resolve', arg], { encoding: 'utf8', cwd: repoRoot });
+  if (result.status !== 0) {
+    throw new Error(
+      `Short id '${arg}' not found in active task registry: ${(result.stderr || '').trim()}`
+    );
+  }
+  return result.stdout.trim();
+}
+
 function stripQuotes(value: string): string {
   return value.replace(/^(["'])(.*)\1$/, '$2');
 }
@@ -33,10 +51,14 @@ function resolveBranchFromTaskContent(content: string, taskId: string): string {
 }
 
 export function resolveTaskBranch(arg: string, repoRoot: string): string {
+  if (SHORT_ID_RE.test(arg)) {
+    const taskId = resolveShortIdStrict(arg, repoRoot);
+    const content = readTaskContent(repoRoot, taskId);
+    return resolveBranchFromTaskContent(content, taskId);
+  }
   if (!TASK_ID_RE.test(arg)) {
     return arg;
   }
-
   const content = readTaskContent(repoRoot, arg);
   return resolveBranchFromTaskContent(content, arg);
 }

package/lib/sandbox/tools.ts

@@ -1,10 +1,14 @@
 import { safeNameCandidates, sanitizeBranchName } from './constants.ts';
 import { hostJoin } from './engines/wsl2-paths.ts';
 
+export type SandboxToolInstall =
+  | { type: 'npm'; cmd: string }
+  | { type: 'shell'; cmd: string };
+
 export type SandboxTool = {
   id: string;
   name: string;
-  npmPackage: string;
+  install: SandboxToolInstall;
   sandboxBase: string;
   containerMount: string;
   versionCmd: string;
@@ -21,14 +25,17 @@ type ToolsConfig = {
   home: string;
   project: string;
   tools: string[];
+  customTools?: SandboxTool[];
 };
 
+const TOOL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
 function createBuiltinTools(home: string, project: string): Record<string, SandboxTool> {
   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',
@@ -58,7 +65,7 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
     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',
@@ -73,7 +80,7 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
     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',
@@ -92,7 +99,7 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
     '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',
@@ -108,16 +115,224 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
   };
 }
 
+export function builtinToolIds(): string[] {
+  return Object.keys(createBuiltinTools('', ''));
+}
+
 function validateTool(tool: SandboxTool): void {
-  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: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function asString(value: unknown, field: string, context: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`${context}: field "${field}" must be a string`);
+  }
+  return value;
+}
+
+function asOptionalNonEmptyString(value: unknown, field: string, context: string): string | undefined {
+  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: unknown, field: string, context: string): Record<string, string> | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!isPlainObject(value)) {
+    throw new Error(`${context}: field "${field}" must be an object when provided`);
+  }
+  const out: Record<string, string> = {};
+  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: unknown, field: string, context: string): string[] | undefined {
+  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: unknown, context: string): SandboxToolInstall {
+  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: unknown, context: string): SandboxTool['hostPreSeedFiles'] {
+  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: unknown, context: string): SandboxTool['hostPreSeedDirs'] {
+  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: unknown, context: string): SandboxTool['hostLiveMounts'] {
+  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: unknown,
+  index: number,
+  options: { home: string }
+): SandboxTool {
+  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: SandboxTool = {
+    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: unknown, options: { home: string }): SandboxTool[] {
+  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: ToolsConfig): SandboxTool[] {
   const builtins = createBuiltinTools(config.home, config.project);
+  const customs = config.customTools ?? [];
+
+  const seen = new Set<string>();
+  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: Record<string, SandboxTool> = { ...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}`);
     }
@@ -139,5 +354,29 @@ export function toolProjectDirCandidates(tool: SandboxTool, project: string): st
 }
 
 export function toolNpmPackagesArg(tools: SandboxTool[]): string {
-  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: SandboxTool[]): string {
+  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: SandboxTool[]): string {
+  const script = toolShellInstallScript(tools);
+  return script ? Buffer.from(script, 'utf8').toString('base64') : '';
+}
+
+export function imageSignatureFields(tools: SandboxTool[]): Array<{ id: string; install: SandboxToolInstall }> {
+  return tools.map((tool) => ({ id: tool.id, install: tool.install }));
 }