@fitlab-ai/agent-infra 0.5.9 → 0.6.0

package/lib/sandbox/dotfiles.ts

@@ -0,0 +1,236 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { hostJoin } from './engines/wsl2-paths.ts';
+
+type DotfilesWarning = {
+  rel: string;
+  reason: string;
+  detail?: string;
+};
+
+type DotfilesFs = Pick<typeof fs, 'copyFileSync' | 'existsSync' | 'mkdirSync' | 'readdirSync' | 'realpathSync' | 'rmSync' | 'statSync'>;
+
+type MaterializeOptions = {
+  writeStderr?: (message: string) => void;
+  maxDepth?: number;
+  fsModule?: DotfilesFs;
+};
+
+type WalkContext = {
+  srcDir: string;
+  dstDir: string;
+  relParts: string[];
+  depth: number;
+  maxDepth: number;
+  activeDirs: Set<string>;
+  warnings: DotfilesWarning[];
+  writeStderr: (message: string) => void;
+  fsModule: DotfilesFs;
+};
+
+export function dotfilesCacheDir(home: string, project: string): string {
+  return hostJoin(home, '.agent-infra', '.cache', 'dotfiles-resolved', project);
+}
+
+function dotfilesWarning(
+  warnings: DotfilesWarning[],
+  writeStderr: (message: string) => void,
+  relPath: string,
+  reason: string,
+  detail = ''
+): void {
+  const warning: DotfilesWarning = { rel: relPath, reason };
+  if (detail) {
+    warning.detail = detail;
+  }
+  warnings.push(warning);
+
+  const suffix = detail ? `: ${detail}` : '';
+  writeStderr(`sandbox-dotfiles (host): skipping ${relPath} (${reason}${suffix})\n`);
+}
+
+function errorDetail(error: unknown): string {
+  return error instanceof Error ? error.message : 'unknown error';
+}
+
+function errorCodeOrDetail(error: unknown): string {
+  return typeof error === 'object' && error !== null && 'code' in error
+    ? String(error.code)
+    : errorDetail(error);
+}
+
+function copyDotfile(
+  srcPath: string,
+  dstPath: string,
+  context: Pick<WalkContext, 'fsModule' | 'warnings' | 'writeStderr'> & { relPath: string }
+): void {
+  const { fsModule, relPath, warnings, writeStderr } = context;
+  try {
+    fsModule.mkdirSync(path.dirname(dstPath), { recursive: true });
+    fsModule.copyFileSync(srcPath, dstPath);
+  } catch (error) {
+    dotfilesWarning(warnings, writeStderr, relPath, 'copy failed', errorCodeOrDetail(error));
+  }
+}
+
+function walkAndMaterializeDotfiles(context: WalkContext): void {
+  const {
+    srcDir,
+    dstDir,
+    relParts,
+    depth,
+    maxDepth,
+    activeDirs,
+    warnings,
+    writeStderr,
+    fsModule
+  } = context;
+  const relPath = relParts.length > 0 ? relParts.join('/') : '.';
+
+  if (depth > maxDepth) {
+    dotfilesWarning(warnings, writeStderr, relPath, 'depth exceeds limit', String(maxDepth));
+    return;
+  }
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fsModule.readdirSync(srcDir, { withFileTypes: true });
+  } catch (error) {
+    dotfilesWarning(warnings, writeStderr, relPath, 'read failed', errorCodeOrDetail(error));
+    return;
+  }
+
+  for (const entry of entries) {
+    const childSrc = path.join(srcDir, entry.name);
+    const childDst = path.join(dstDir, entry.name);
+    const childRelParts = [...relParts, entry.name];
+    const childRelPath = childRelParts.join('/');
+
+    if (entry.isSymbolicLink()) {
+      let resolvedTarget: string;
+      try {
+        resolvedTarget = fsModule.realpathSync(childSrc);
+      } catch (error) {
+        const code = errorCodeOrDetail(error);
+        const reason = code === 'ELOOP' ? 'symlink loop' : 'dangling symlink';
+        dotfilesWarning(warnings, writeStderr, childRelPath, reason, code || 'unresolved');
+        continue;
+      }
+
+      let targetStat: fs.Stats;
+      try {
+        targetStat = fsModule.statSync(resolvedTarget);
+      } catch (error) {
+        dotfilesWarning(warnings, writeStderr, childRelPath, 'target stat failed', errorCodeOrDetail(error));
+        continue;
+      }
+
+      if (targetStat.isDirectory()) {
+        if (activeDirs.has(resolvedTarget)) {
+          dotfilesWarning(warnings, writeStderr, childRelPath, 'symlink loop');
+          continue;
+        }
+
+        activeDirs.add(resolvedTarget);
+        walkAndMaterializeDotfiles({
+          srcDir: resolvedTarget,
+          dstDir: childDst,
+          relParts: childRelParts,
+          depth: depth + 1,
+          maxDepth,
+          activeDirs,
+          warnings,
+          writeStderr,
+          fsModule
+        });
+        activeDirs.delete(resolvedTarget);
+        continue;
+      }
+
+      if (targetStat.isFile()) {
+        copyDotfile(resolvedTarget, childDst, {
+          fsModule,
+          relPath: childRelPath,
+          warnings,
+          writeStderr
+        });
+      }
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      let childRealPath: string | null = null;
+      try {
+        childRealPath = fsModule.realpathSync(childSrc);
+      } catch {
+        // A real directory may disappear during traversal; readdir will warn below.
+      }
+      if (childRealPath) {
+        activeDirs.add(childRealPath);
+      }
+      walkAndMaterializeDotfiles({
+        srcDir: childSrc,
+        dstDir: childDst,
+        relParts: childRelParts,
+        depth: depth + 1,
+        maxDepth,
+        activeDirs,
+        warnings,
+        writeStderr,
+        fsModule
+      });
+      if (childRealPath) {
+        activeDirs.delete(childRealPath);
+      }
+      continue;
+    }
+
+    if (entry.isFile()) {
+      copyDotfile(childSrc, childDst, {
+        fsModule,
+        relPath: childRelPath,
+        warnings,
+        writeStderr
+      });
+    }
+  }
+}
+
+export function materializeDotfiles(srcDir: string, cacheDir: string, options: MaterializeOptions = {}) {
+  const {
+    writeStderr = (message) => process.stderr.write(message),
+    maxDepth = 32,
+    fsModule = fs
+  } = options;
+
+  if (!srcDir || !fsModule.existsSync(srcDir)) {
+    return null;
+  }
+
+  fsModule.mkdirSync(cacheDir, { recursive: true });
+  for (const entry of fsModule.readdirSync(cacheDir)) {
+    fsModule.rmSync(path.join(cacheDir, entry), { recursive: true, force: true });
+  }
+
+  const warnings: DotfilesWarning[] = [];
+  const activeDirs = new Set<string>();
+  try {
+    activeDirs.add(fsModule.realpathSync(srcDir));
+  } catch {
+    activeDirs.add(srcDir);
+  }
+
+  walkAndMaterializeDotfiles({
+    srcDir,
+    dstDir: cacheDir,
+    relParts: [],
+    depth: 0,
+    maxDepth,
+    activeDirs,
+    warnings,
+    writeStderr,
+    fsModule
+  });
+
+  return { cacheDir, warnings };
+}

package/lib/sandbox/engine.ts

@@ -0,0 +1,231 @@
+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';
+
+export const ENGINES = Object.freeze({
+  COLIMA: 'colima',
+  ORBSTACK: 'orbstack',
+  DOCKER_DESKTOP: 'docker-desktop',
+  NATIVE: 'native',
+  WSL2: 'wsl2'
+});
+
+const PLATFORM_DEFAULTS = Object.freeze({
+  linux: ENGINES.NATIVE,
+  darwin: ENGINES.COLIMA,
+  win32: ENGINES.WSL2
+});
+
+type EngineConfig = EffectiveSandboxConfig & {
+  engine?: string | null;
+};
+
+type EngineDependencies = {
+  platformFn?: typeof platform;
+  runFn?: RunFns['run'];
+  runOkFn?: RunFns['runOk'];
+  runSafeFn?: RunFns['runSafe'];
+  runVerboseFn?: RunFns['runVerbose'];
+};
+
+function runFns({
+  runFn = run,
+  runOkFn = runOk,
+  runSafeFn = runSafe,
+  runVerboseFn = runVerbose
+}: EngineDependencies = {}): RunFns {
+  return {
+    run: runFn,
+    runOk: runOkFn,
+    runSafe: runSafeFn,
+    runVerbose: runVerboseFn
+  };
+}
+
+function applyDockerContext(adapter: SandboxAdapter): void {
+  if (adapter.dockerContext) {
+    process.env.DOCKER_CONTEXT = adapter.dockerContext;
+  }
+}
+
+export function validateSandboxEngine(
+  engine: string | null | undefined,
+  { platformFn = platform }: Pick<EngineDependencies, 'platformFn'> = {}
+): string | null {
+  if (engine === null || engine === undefined) {
+    return null;
+  }
+
+  const os = platformFn();
+  if (!(engine in ADAPTERS)) {
+    const known = Object.keys(ADAPTERS).join(', ');
+    throw new Error(
+      `sandbox: invalid "sandbox.engine" value "${engine}" (unknown sandbox engine). `
+      + `Valid engines: ${known}.`
+    );
+  }
+
+  const adapter = ADAPTERS[engine as keyof typeof ADAPTERS];
+  if (!adapter.supportedPlatforms.includes(os)) {
+    const supported = enginesForPlatform(os);
+    const supportedList = supported.length > 0 ? supported.join(', ') : 'none';
+    throw new Error(
+      `sandbox: "sandbox.engine" value "${engine}" is not supported on ${os}. `
+      + `Supported engines on ${os}: ${supportedList}.`
+    );
+  }
+
+  return engine;
+}
+
+export function detectEngine(
+  config: EngineConfig = {},
+  { platformFn = platform }: Pick<EngineDependencies, 'platformFn'> = {}
+): string {
+  const configured = validateSandboxEngine(config.engine, { platformFn });
+  if (configured) {
+    return configured;
+  }
+
+  const os = platformFn();
+  const fallback = PLATFORM_DEFAULTS[os as keyof typeof PLATFORM_DEFAULTS];
+  if (fallback) {
+    return fallback;
+  }
+
+  throw new Error(
+    `sandbox: platform "${os}" is not supported. `
+    + 'Supported platforms: linux (native), darwin (colima/orbstack/docker-desktop), win32 (wsl2). '
+    + 'Please open an issue at https://github.com/fitlab-ai/agent-infra/issues/new '
+    + 'with your platform details if you need this added.'
+  );
+}
+
+export function hasUserVmConfig(vm: SandboxVmConfig = {}): boolean {
+  return vm.cpu != null || vm.memory != null || vm.disk != null;
+}
+
+export function resolveEffectiveVm(
+  adapter: SandboxAdapter,
+  userVm: SandboxVmConfig = {},
+  { detectHostResourcesFn = detectHostResources }: { detectHostResourcesFn?: typeof detectHostResources } = {}
+): SandboxVmConfig {
+  let host: ReturnType<typeof detectHostResources> | null = null;
+  const getHost = () => {
+    host ??= detectHostResourcesFn();
+    return host;
+  };
+  const defaults = adapter.defaultResources?.(getHost) ?? {};
+
+  return {
+    cpu: userVm.cpu ?? defaults.cpu ?? null,
+    memory: userVm.memory ?? defaults.memory ?? null,
+    disk: userVm.disk ?? defaults.disk ?? null
+  };
+}
+
+function effectiveConfigFor(adapter: SandboxAdapter, config: EngineConfig): EffectiveSandboxConfig {
+  const userVm = config.vm ?? {};
+  return {
+    ...config,
+    userVm,
+    hasUserVmConfig,
+    vm: resolveEffectiveVm(adapter, userVm)
+  };
+}
+
+export async function ensureDocker(
+  config: EngineConfig,
+  onMessage: OnMessage,
+  dependencies: EngineDependencies = {}
+): Promise<void> {
+  const engine = detectEngine(config, dependencies);
+  const adapter = getAdapter(engine);
+  const effectiveConfig = effectiveConfigFor(adapter, config);
+
+  applyDockerContext(adapter);
+  const vmJustStarted = await adapter.ensure(effectiveConfig, onMessage, runFns(dependencies));
+  adapter.syncResources(effectiveConfig, onMessage, runFns(dependencies), { vmJustStarted });
+}
+
+export function isVmManaged(config: EngineConfig = {}, dependencies: EngineDependencies = {}): boolean {
+  try {
+    const engine = detectEngine(config, dependencies);
+    return isManagedEngine(engine);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : '';
+    if (
+      message.startsWith('sandbox: platform "')
+      || / is not supported on [^.]+\. Supported engines on [^:]+: none\./.test(message)
+    ) {
+      return false;
+    }
+
+    throw error;
+  }
+}
+
+export function isManagedEngine(engine: string): boolean {
+  try {
+    return getAdapter(engine).managed;
+  } catch {
+    return false;
+  }
+}
+
+export function engineDisplayName(engine: string): string {
+  try {
+    return getAdapter(engine).displayName;
+  } catch {
+    return engine;
+  }
+}
+
+export function startManagedVm(
+  config: EngineConfig,
+  { platformFn = platform, runOkFn = runOk, runSafeFn = runSafe, runVerboseFn = runVerbose, onMessage }: EngineDependencies & { onMessage?: OnMessage } = {}
+): 'already-running' | 'started' {
+  const engine = detectEngine(config, { platformFn });
+  const adapter = getAdapter(engine);
+  if (!adapter.managed) {
+    throw new Error(`VM management is unavailable for engine '${adapter.displayName}'.`);
+  }
+
+  const effectiveConfig = effectiveConfigFor(adapter, config);
+  applyDockerContext(adapter);
+  if (!adapter.startVm) {
+    throw new Error(`VM management is unavailable for engine '${adapter.displayName}'.`);
+  }
+  const result = adapter.startVm(
+    effectiveConfig,
+    onMessage,
+    runFns({ runOkFn, runSafeFn, runVerboseFn })
+  );
+  adapter.syncResources(
+    effectiveConfig,
+    onMessage,
+    runFns({ runOkFn, runSafeFn, runVerboseFn }),
+    { vmJustStarted: result === 'started' }
+  );
+  return result;
+}
+
+export function stopManagedVm(
+  config: EngineConfig,
+  { platformFn = platform, runFn = run }: Pick<EngineDependencies, 'platformFn' | 'runFn'> = {}
+): 'stopped' {
+  const engine = detectEngine(config, { platformFn });
+  const adapter = getAdapter(engine);
+  if (!adapter.managed) {
+    throw new Error(`VM management is unavailable for engine '${adapter.displayName}'.`);
+  }
+  if (!adapter.stopVm) {
+    throw new Error(`VM management is unavailable for engine '${adapter.displayName}'.`);
+  }
+
+  // Stop commands do not read Docker context or VM resource values; keep the
+  // previous environment unchanged and pass the original config intentionally.
+  return adapter.stopVm(config, null, runFns({ runFn }));
+}

package/lib/sandbox/engines/colima.ts

@@ -0,0 +1,81 @@
+import type { EffectiveSandboxConfig, HostResources, OnMessage, RunFns, SandboxAdapter } from './index.ts';
+
+function colimaArgs(config: EffectiveSandboxConfig, runSafeFn: RunFns['runSafe']): string[] {
+  const arch = runSafeFn('uname', ['-m']);
+  const vm = config.vm ?? {};
+  const args = ['start', '--cpu', String(vm.cpu), '--memory', String(vm.memory), '--disk', String(vm.disk)];
+
+  if (arch === 'arm64') {
+    args.push('--arch', 'aarch64', '--vm-type=vz', '--mount-type=virtiofs');
+  } else {
+    args.push('--arch', 'x86_64');
+  }
+
+  return args;
+}
+
+export const colimaAdapter: SandboxAdapter = {
+  id: 'colima',
+  displayName: 'Colima',
+  supportedPlatforms: ['darwin'],
+  dockerContext: 'colima',
+  managed: true,
+  canApplyResources: 'on-start',
+
+  defaultResources(getHost: () => HostResources) {
+    const host = getHost();
+    return {
+      cpu: host.cpu,
+      memory: host.memory,
+      disk: 60
+    };
+  },
+
+  async ensure(config, onMessage: OnMessage, { runOk, runSafe, runVerbose }) {
+    let started = false;
+
+    if (!runOk('which', ['colima'])) {
+      onMessage?.('Installing colima + docker via Homebrew...');
+      runVerbose('brew', ['install', 'colima', 'docker']);
+    }
+
+    if (!runOk('colima', ['status'])) {
+      onMessage?.('Starting Colima VM...');
+      runVerbose('colima', colimaArgs(config, runSafe));
+      started = true;
+    }
+
+    if (!runOk('docker', ['info'])) {
+      throw new Error('Docker daemon is not available after starting Colima');
+    }
+
+    return started;
+  },
+
+  startVm(config, _onMessage: OnMessage, { runOk, runSafe, runVerbose }) {
+    if (runOk('colima', ['status'])) {
+      return 'already-running';
+    }
+
+    runVerbose('colima', colimaArgs(config, runSafe));
+    return 'started';
+  },
+
+  stopVm(_config, _onMessage: OnMessage, { run }) {
+    run('colima', ['stop']);
+    return 'stopped';
+  },
+
+  syncResources(config, onMessage: OnMessage, _runFns, { vmJustStarted } = {}) {
+    if (vmJustStarted || !config.hasUserVmConfig?.(config.userVm)) {
+      return;
+    }
+
+    onMessage?.(
+      'Warning: Colima VM is already running; restart with '
+      + '`ai sandbox vm stop && ai sandbox vm start` to apply new sandbox.vm.* values.'
+    );
+  }
+};
+
+export default colimaAdapter;

package/lib/sandbox/engines/docker-desktop.ts

@@ -0,0 +1,36 @@
+import type { OnMessage, SandboxAdapter } from './index.ts';
+
+export const dockerDesktopAdapter: SandboxAdapter = {
+  id: 'docker-desktop',
+  displayName: 'Docker Desktop',
+  supportedPlatforms: ['darwin', 'linux', 'win32'],
+  dockerContext: 'desktop-linux',
+  managed: false,
+  canApplyResources: 'never',
+
+  defaultResources() {
+    return null;
+  },
+
+  async ensure(_config, _onMessage: OnMessage, { runOk }) {
+    if (!runOk('docker', ['info'])) {
+      throw new Error('Docker Desktop is not running. Please start Docker Desktop manually.');
+    }
+
+    return false;
+  },
+
+  syncResources(config, onMessage: OnMessage) {
+    if (!config.hasUserVmConfig?.(config.userVm)) {
+      return;
+    }
+
+    onMessage?.(
+      'Warning: Docker Desktop manages CPU/memory/disk via Settings -> Resources. '
+      + 'sandbox.vm.* values and --cpu/--memory flags are not applied for this engine. '
+      + 'Please configure resources in Docker Desktop GUI to match.'
+    );
+  }
+};
+
+export default dockerDesktopAdapter;

package/lib/sandbox/engines/index.ts

@@ -0,0 +1,74 @@
+import { colimaAdapter } from './colima.ts';
+import { dockerDesktopAdapter } from './docker-desktop.ts';
+import { nativeAdapter } from './native.ts';
+import { orbstackAdapter } from './orbstack.ts';
+import { wsl2Adapter } from './wsl2.ts';
+
+export type SandboxVmConfig = {
+  cpu?: number | null;
+  memory?: number | null;
+  disk?: number | null;
+};
+
+export type EffectiveSandboxConfig = {
+  vm?: SandboxVmConfig;
+  userVm?: SandboxVmConfig;
+  hasUserVmConfig?: (vm?: SandboxVmConfig) => boolean;
+};
+
+export type HostResources = {
+  cpu: number;
+  memory: number;
+};
+
+export type RunFns = {
+  run: (cmd: string, args: string[]) => string;
+  runOk: (cmd: string, args: string[]) => boolean;
+  runSafe: (cmd: string, args: string[]) => string;
+  runVerbose: (cmd: string, args: string[]) => void;
+};
+
+export type OnMessage = ((message: string) => void) | undefined | null;
+
+export type SandboxAdapter = {
+  id: string;
+  displayName: string;
+  supportedPlatforms: string[];
+  dockerContext: string | null;
+  managed: boolean;
+  canApplyResources: string;
+  defaultResources: (getHost: () => HostResources) => SandboxVmConfig | null;
+  ensure: (config: EffectiveSandboxConfig, onMessage: OnMessage, runFns: RunFns) => Promise<boolean>;
+  startVm?: (config: EffectiveSandboxConfig, onMessage: OnMessage, runFns: RunFns) => 'already-running' | 'started';
+  stopVm?: (config: EffectiveSandboxConfig, onMessage: OnMessage, runFns: Pick<RunFns, 'run'>) => 'stopped';
+  syncResources: (
+    config: EffectiveSandboxConfig,
+    onMessage: OnMessage,
+    runFns: RunFns,
+    options?: { vmJustStarted?: boolean }
+  ) => void;
+};
+
+export const ADAPTERS = Object.freeze({
+  colima: colimaAdapter,
+  orbstack: orbstackAdapter,
+  'docker-desktop': dockerDesktopAdapter,
+  native: nativeAdapter,
+  wsl2: wsl2Adapter
+});
+
+type SandboxEngineId = keyof typeof ADAPTERS;
+
+export function getAdapter(engineId: string): SandboxAdapter {
+  const adapter = ADAPTERS[engineId as SandboxEngineId];
+  if (!adapter) {
+    throw new Error(`No adapter registered for engine '${engineId}'`);
+  }
+  return adapter;
+}
+
+export function enginesForPlatform(platformName: string): string[] {
+  return Object.values(ADAPTERS)
+    .filter((adapter) => adapter.supportedPlatforms.includes(platformName))
+    .map((adapter) => adapter.id);
+}