@fitlab-ai/agent-infra 0.8.4 → 0.9.0

package/lib/sandbox/commands/start.ts

@@ -6,33 +6,57 @@ import {
   sandboxLabel
 } from '../constants.ts';
 import { detectEngine } from '../engine.ts';
+import { ensureSandboxReady } from '../recovery.ts';
 import {
   fetchSandboxRows,
   resolveBranchArg,
   selectSandboxContainer,
-  startSandboxContainer
 } from './list-running.ts';
 
-const USAGE = `Usage: ai sandbox start <branch | TASK-id | N | '#N'>
+const USAGE = `Usage: ai sandbox start [--recreate] <branch | TASK-id | N>
 
 Start an existing sandbox container that has stopped (for example after the
 Docker daemon was restarted or replaced). The container must already exist:
 if none is found, run 'ai sandbox create <branch>' first. A container that is
-already running is left untouched.`;
+already running is checked without modifying healthy runtime state. --recreate
+allows container-only replacement after in-place recovery fails.`;
+
+export function parseStartArgs(args: string[]): { target: string; recreate: boolean; help: boolean } {
+  let recreate = false;
+  let help = false;
+  const positionals: string[] = [];
+  for (const arg of args) {
+    if (arg === '--recreate') {
+      recreate = true;
+    } else if (arg === '--help' || arg === '-h') {
+      help = true;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}\n${USAGE}`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+  if (!help && positionals.length !== 1) {
+    throw new Error(USAGE);
+  }
+  return { target: positionals[0] ?? '', recreate, help };
+}
 
 export async function start(args: string[]): Promise<void> {
-  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  if (args.length === 0) {
+    process.stdout.write(`${USAGE}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const parsed = parseStartArgs(args);
+  if (parsed.help) {
     process.stdout.write(`${USAGE}\n`);
-    if (args.length === 0) {
-      process.exitCode = 1;
-    }
     return;
   }
 
-  const [firstArg = ''] = args;
   const config = loadConfig();
   const engine = detectEngine(config);
-  const branch = resolveBranchArg(firstArg, { repoRoot: config.repoRoot });
+  const branch = resolveBranchArg(parsed.target, { repoRoot: config.repoRoot });
   assertValidBranchName(branch);
 
   const { running, nonRunning } = fetchSandboxRows(
@@ -51,11 +75,21 @@ export async function start(args: string[]): Promise<void> {
     );
   }
 
-  if (found.running) {
-    process.stdout.write(`Sandbox '${found.name}' is already running.\n`);
-    return;
-  }
-
-  startSandboxContainer(engine, found.name);
-  process.stdout.write(`Started sandbox '${found.name}'.\n`);
+  const ready = await ensureSandboxReady({
+    config,
+    engine,
+    branch,
+    row: found,
+    allowRecreate: parsed.recreate,
+    recreate: async (targetBranch) => {
+      const { create } = await import('./create.ts');
+      await create([targetBranch, '--no-refresh']);
+    }
+  });
+  const message = ready.path === 'healthy'
+    ? `Sandbox '${ready.container}' is already running and healthy.`
+    : ready.path === 'recreated'
+      ? `Recreated sandbox '${ready.container}' and verified readiness.`
+      : `Recovered sandbox '${ready.container}' and verified readiness.`;
+  process.stdout.write(`${message}\n`);
 }

package/lib/sandbox/engine.ts

@@ -2,7 +2,7 @@ import { platform } from 'node:os';
 import { detectHostResources } from './constants.ts';
 import { ADAPTERS, enginesForPlatform, getAdapter } from './engines/index.ts';
 import type { EffectiveSandboxConfig, OnMessage, RunFns, SandboxAdapter, SandboxVmConfig } from './engines/index.ts';
-import { run, runOk, runSafe, runVerbose } from './shell.ts';
+import { run, runOk, runOkEngine, runSafe, runVerbose } from './shell.ts';
 
 export const ENGINES = Object.freeze({
   COLIMA: 'colima',
@@ -26,6 +26,7 @@ type EngineDependencies = {
   platformFn?: typeof platform;
   runFn?: RunFns['run'];
   runOkFn?: RunFns['runOk'];
+  runOkEngineFn?: typeof runOkEngine;
   runSafeFn?: RunFns['runSafe'];
   runVerboseFn?: RunFns['runVerbose'];
 };
@@ -50,6 +51,37 @@ function applyDockerContext(adapter: SandboxAdapter): void {
   }
 }
 
+function buildKitError(engine: string): Error {
+  let repair: string;
+  switch (engine) {
+    case ENGINES.COLIMA:
+      repair = 'Install the Docker Buildx plugin with: brew install docker-buildx';
+      break;
+    case ENGINES.DOCKER_DESKTOP:
+    case ENGINES.WSL2:
+      repair = 'Upgrade or repair Docker Desktop so Docker Buildx and BuildKit are available.';
+      break;
+    case ENGINES.NATIVE:
+      repair = 'Install the Docker Buildx plugin for your Docker Engine installation.';
+      break;
+    default:
+      repair = `Upgrade or repair ${engineDisplayName(engine)} so Docker Buildx and BuildKit are available.`;
+  }
+
+  return new Error([
+    `Docker BuildKit is not available for ${engineDisplayName(engine)}.`,
+    repair,
+    'Verify the builder with: docker buildx inspect --bootstrap',
+    'Then retry the sandbox create or rebuild command.'
+  ].join('\n'));
+}
+
+function ensureBuildKit(engine: string, runOkEngineFn: typeof runOkEngine): void {
+  if (!runOkEngineFn(engine, 'docker', ['buildx', 'inspect', '--bootstrap'])) {
+    throw buildKitError(engine);
+  }
+}
+
 export function validateSandboxEngine(
   engine: string | null | undefined,
   { platformFn = platform }: Pick<EngineDependencies, 'platformFn'> = {}
@@ -144,10 +176,12 @@ export async function ensureDocker(
   const engine = detectEngine(config, dependencies);
   const adapter = getAdapter(engine);
   const effectiveConfig = effectiveConfigFor(adapter, config);
+  const fns = runFns(dependencies);
 
   applyDockerContext(adapter);
-  const vmJustStarted = await adapter.ensure(effectiveConfig, onMessage, runFns(dependencies));
-  adapter.syncResources(effectiveConfig, onMessage, runFns(dependencies), { vmJustStarted });
+  const vmJustStarted = await adapter.ensure(effectiveConfig, onMessage, fns);
+  ensureBuildKit(engine, dependencies.runOkEngineFn ?? runOkEngine);
+  adapter.syncResources(effectiveConfig, onMessage, fns, { vmJustStarted });
 }
 
 export function isVmManaged(config: EngineConfig = {}, dependencies: EngineDependencies = {}): boolean {

package/lib/sandbox/engines/colima.ts

@@ -35,8 +35,8 @@ export const colimaAdapter: SandboxAdapter = {
     let started = false;
 
     if (!runOk('which', ['colima'])) {
-      onMessage?.('Installing colima + docker via Homebrew...');
-      runVerbose('brew', ['install', 'colima', 'docker']);
+      onMessage?.('Installing colima + docker + docker-buildx via Homebrew...');
+      runVerbose('brew', ['install', 'colima', 'docker', 'docker-buildx']);
     }
 
     if (!runOk('colima', ['status'])) {

package/lib/sandbox/index.ts

@@ -2,14 +2,14 @@ const USAGE = `Usage: ai sandbox <command> [options]
 
 Commands:
   create <branch> [base]       Create a sandbox (VM + image + worktree + container)
-  exec <branch | TASK-id | N | '#N'> [cmd...]
+  exec [--recreate] <branch | TASK-id | N> [cmd...]
                                Enter sandbox or run a command. N (bare) is the
                                recommended form for task short ids (e.g.
-                               'ai sandbox exec 11'); '#N' is also accepted.
+                               'ai sandbox exec 11').
   ls                           List sandboxes for the current project (the '#'
                                column is a display-only row number; the 'SHORT'
                                column shows the active task short id, '-' if none)
-  show <branch | TASK-id | N | '#N'>
+  show <branch | TASK-id | N>
                                Show one sandbox's worktree and per-tool state paths
   prune [--dry-run]            Remove orphaned per-branch state dirs
   rebuild [--quiet] [--refresh]
@@ -18,9 +18,9 @@ Commands:
   rm <branch> | --all | --purge
                                Remove one sandbox, all sandboxes not bound to an
                                active task (--all), or tear down everything (--purge)
-  start <branch | TASK-id | N | '#N'>
-                               Start an existing stopped sandbox container
-                               (e.g. after the Docker daemon restarted)
+  start [--recreate] <branch | TASK-id | N>
+                               Verify or recover an existing sandbox container;
+                               optionally replace only the container on failure
   vm status|start|stop         Manage the sandbox VM (macOS) or check the backend (Windows)
 
 Run 'ai sandbox <command> --help' for details.`;

package/lib/sandbox/mounts.ts

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import {
+  shareBranchDir,
+  shareCommonDir,
+  shellConfigDirCandidates,
+  worktreeDirCandidates
+} from './constants.ts';
+import type { SandboxConfig } from './config.ts';
+
+export type SandboxBindMountDeclaration = {
+  hostPaths: string[];
+  containerPath: string;
+  readOnly: boolean;
+};
+
+export function sandboxCoreBindMounts(
+  config: Pick<
+    SandboxConfig,
+    'repoRoot' | 'worktreeBase' | 'shareBase' | 'shellConfigBase'
+  >,
+  branch: string,
+  overrides: { worktree?: string; shellConfigHostDir?: string } = {}
+): SandboxBindMountDeclaration[] {
+  return [
+    {
+      hostPaths: overrides.worktree
+        ? [overrides.worktree]
+        : worktreeDirCandidates(config, branch),
+      containerPath: '/workspace',
+      readOnly: false
+    },
+    {
+      hostPaths: [path.join(config.repoRoot, '.agents', 'workspace')],
+      containerPath: '/workspace/.agents/workspace',
+      readOnly: false
+    },
+    {
+      hostPaths: [shareCommonDir(config)],
+      containerPath: '/share/common',
+      readOnly: false
+    },
+    {
+      hostPaths: [shareBranchDir(config, branch)],
+      containerPath: '/share/branch',
+      readOnly: false
+    },
+    {
+      hostPaths: overrides.shellConfigHostDir
+        ? [overrides.shellConfigHostDir]
+        : shellConfigDirCandidates(config, branch),
+      containerPath: '/home/devuser/.host-shell-config',
+      readOnly: true
+    }
+  ];
+}