@fitlab-ai/agent-infra 0.6.2 → 0.6.3

package/lib/sandbox/clipboard/bridge.ts

@@ -0,0 +1,285 @@
+import { StringDecoder } from 'node:string_decoder';
+import { createClipboardAdapter, type ClipboardAdapter } from './index.ts';
+import { buildBracketedPaste, CtrlVDetector, type CtrlVMatch } from './keys.ts';
+import {
+  clipboardHostDir,
+  containerClipboardPath,
+  pngClipboardFilename,
+  pruneClipboardDir,
+  writeClipboardPngAtomic
+} from './paths.ts';
+import { commandForEngine, restoreTerminal, runInteractiveEngine, runOkEngine } from '../shell.ts';
+import { loadNodePty, type NodePty, type PtyProcess } from './node-pty.ts';
+
+type BridgeOptions = {
+  engine: string;
+  dockerArgs: string[];
+  container: string;
+  home: string;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  platformName?: NodeJS.Platform;
+  adapter?: ClipboardAdapter | null;
+  loadPty?: () => Promise<NodePty | null>;
+  runInteractive?: typeof runInteractiveEngine;
+  runOk?: typeof runOkEngine;
+  writeStderr?: (chunk: string) => unknown;
+  stdin?: NodeJS.ReadStream;
+  stdout?: NodeJS.WriteStream;
+  createDetector?: () => CtrlVDetector;
+};
+
+const FALLBACK_PREFIX = 'Warning: clipboard image paste bridge disabled';
+const PARTIAL_ESCAPE_FLUSH_MS = 30;
+
+export async function runInteractiveWithClipboardBridge(options: BridgeOptions): Promise<number> {
+  const {
+    engine,
+    dockerArgs,
+    container,
+    home,
+    cwd = process.cwd(),
+    env = process.env,
+    platformName = process.platform,
+    adapter = createClipboardAdapter({ platformName }),
+    loadPty = loadNodePty,
+    runInteractive = runInteractiveEngine,
+    runOk = runOkEngine,
+    writeStderr = (chunk) => process.stderr.write(chunk),
+    stdin = process.stdin,
+    stdout = process.stdout,
+    createDetector = () => new CtrlVDetector()
+  } = options;
+
+  function fallback(reason: string): number {
+    writeStderr(`${FALLBACK_PREFIX}: ${reason}\n`);
+    return runInteractive(engine, 'docker', dockerArgs);
+  }
+
+  if (platformName !== 'darwin') {
+    return runInteractive(engine, 'docker', dockerArgs);
+  }
+  if (!stdin.isTTY || !stdout.isTTY) {
+    return fallback('host stdin/stdout is not a TTY');
+  }
+  if (!adapter) {
+    return fallback('macOS clipboard adapter is unavailable');
+  }
+  const available = adapter.available();
+  if (!available.ok) {
+    return fallback(available.reason);
+  }
+  if (!runOk(engine, 'docker', ['exec', container, 'sh', '-c', '[ -d /clipboard ] && [ -r /clipboard ]'])) {
+    return fallback('container /clipboard mount is missing; rebuild the sandbox to enable image paste');
+  }
+
+  const pty = await loadPty();
+  if (!pty) {
+    return fallback('node-pty optional dependency is unavailable');
+  }
+
+  const command = commandForEngine(engine, 'docker', dockerArgs);
+  let child: PtyProcess;
+  try {
+    child = pty.spawn(command.cmd, command.args, {
+      name: env.TERM || 'xterm-256color',
+      cols: stdout.columns || 120,
+      rows: stdout.rows || 40,
+      cwd,
+      env
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'unknown error';
+    return fallback(`node-pty spawn failed: ${message}`);
+  }
+
+  return runBridge({
+    child,
+    home,
+    adapter,
+    writeStderr,
+    stdin,
+    stdout,
+    detector: createDetector()
+  });
+}
+
+async function runBridge({
+  child,
+  home,
+  adapter,
+  writeStderr,
+  stdin,
+  stdout,
+  detector
+}: {
+  child: PtyProcess;
+  home: string;
+  adapter: ClipboardAdapter;
+  writeStderr: (chunk: string) => unknown;
+  stdin: NodeJS.ReadStream;
+  stdout: NodeJS.WriteStream;
+  detector: CtrlVDetector;
+}): Promise<number> {
+  let warnedPasteFailure = false;
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+  const inputDecoder = new StringDecoder('utf8');
+
+  const onData = (chunk: Buffer) => {
+    clearFlushTimer();
+    for (const token of detector.feed(inputDecoder.write(chunk))) {
+      if (token.kind === 'text') {
+        child.write(token.raw);
+      } else {
+        handleCtrlV(token, child);
+      }
+    }
+    if (detector.hasPending()) {
+      flushTimer = setTimeout(() => {
+        flushTimer = null;
+        for (const token of detector.flush()) {
+          if (token.kind === 'text') {
+            child.write(token.raw);
+          } else {
+            handleCtrlV(token, child);
+          }
+        }
+      }, PARTIAL_ESCAPE_FLUSH_MS);
+    }
+  };
+  const onResize = () => child.resize(stdout.columns || 120, stdout.rows || 40);
+  const onSigint = () => child.kill('SIGINT');
+  const onSigterm = () => child.kill('SIGTERM');
+
+  function handleCtrlV(match: CtrlVMatch, target: PtyProcess): void {
+    try {
+      if (!adapter.hasImage()) {
+        target.write(match.raw);
+        return;
+      }
+
+      const png = adapter.readImagePng();
+      if (!png) {
+        throw new Error('clipboard image could not be read');
+      }
+      const filename = pngClipboardFilename(png);
+      writeClipboardPngAtomic(clipboardHostDir(home), filename, png);
+      pruneClipboardDir(clipboardHostDir(home));
+      target.write(buildBracketedPaste(containerClipboardPath(filename)));
+    } catch (error) {
+      target.write(match.raw);
+      if (!warnedPasteFailure) {
+        warnedPasteFailure = true;
+        writeStderr(`Warning: clipboard image paste failed; forwarded original Ctrl+V (${error instanceof Error ? error.message : 'unknown error'})\n`);
+      }
+    }
+  }
+
+  function clearFlushTimer(): void {
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+  }
+
+  try {
+    stdin.setRawMode?.(true);
+    stdin.resume();
+    stdin.on('data', onData);
+    stdout.on('resize', onResize);
+    process.on('SIGINT', onSigint);
+    process.on('SIGTERM', onSigterm);
+    child.onData((data) => stdout.write(data));
+
+    return exitCode(await onceExit(child, stdin));
+  } finally {
+    clearFlushTimer();
+    // The child pty is already exiting here; flushing buffered input is
+    // best-effort and must never block terminal/stdin cleanup below.
+    try {
+      for (const token of detector.feed(inputDecoder.end())) {
+        if (token.kind === 'text') {
+          child.write(token.raw);
+        } else {
+          handleCtrlV(token, child);
+        }
+      }
+      for (const token of detector.flush()) {
+        if (token.kind === 'text') {
+          child.write(token.raw);
+        }
+      }
+    } catch {
+      // Writing to an already-closed pty can throw; ignore on teardown.
+    }
+    stdin.off('data', onData);
+    stdout.off('resize', onResize);
+    process.off('SIGINT', onSigint);
+    process.off('SIGTERM', onSigterm);
+    stdin.setRawMode?.(false);
+    // Release stdin so the resumed TTY handle stops keeping the event loop
+    // alive; without this the CLI hangs after the sandbox exits until Ctrl+C.
+    stdin.pause?.();
+    restoreTerminal();
+  }
+}
+
+function onceExit(
+  child: PtyProcess,
+  stdin: NodeJS.ReadStream
+): Promise<{ exitCode: number; signal?: number | string }> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (event: { exitCode: number; signal?: number | string }) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      stdin.off('end', onStdinEnd);
+      stdin.off('close', onStdinEnd);
+      resolve(event);
+    };
+    const onStdinEnd = () => {
+      child.kill('SIGHUP');
+      finish({ exitCode: 0, signal: 'SIGHUP' });
+    };
+
+    child.onExit(finish);
+    stdin.once('end', onStdinEnd);
+    stdin.once('close', onStdinEnd);
+  });
+}
+
+function exitCode(event: { exitCode: number; signal?: number | string }): number {
+  if (event.signal !== undefined && event.signal !== null) {
+    return signalExitCode(event.signal);
+  }
+  if (event.exitCode !== undefined && event.exitCode !== null) {
+    return event.exitCode;
+  }
+  return 1;
+}
+
+function signalExitCode(signal: number | string): number {
+  if (typeof signal === 'number') {
+    return 128 + signal;
+  }
+  const signals: Record<string, number> = {
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGQUIT: 3,
+    SIGILL: 4,
+    SIGTRAP: 5,
+    SIGABRT: 6,
+    SIGBUS: 7,
+    SIGFPE: 8,
+    SIGKILL: 9,
+    SIGUSR1: 10,
+    SIGSEGV: 11,
+    SIGUSR2: 12,
+    SIGPIPE: 13,
+    SIGALRM: 14,
+    SIGTERM: 15
+  };
+  return 128 + (signals[signal] ?? 0);
+}

package/lib/sandbox/clipboard/darwin.ts

@@ -0,0 +1,90 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { ExecFileSyncOptions } from 'node:child_process';
+
+const HAS_IMAGE_TIMEOUT_MS = 500;
+const READ_IMAGE_TIMEOUT_MS = 5_000;
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+type ExecFn = (cmd: string, args: string[], options?: ExecFileSyncOptions) => Buffer | string;
+
+export type DarwinClipboardAdapter = {
+  available(): { ok: true } | { ok: false; reason: string };
+  hasImage(): boolean;
+  readImagePng(): Buffer | null;
+};
+
+export function createDarwinClipboardAdapter({
+  execFn = execFileSync,
+  mkdtempFn = fs.mkdtempSync,
+  readFileFn = fs.readFileSync,
+  rmFn = fs.rmSync
+}: {
+  execFn?: ExecFn;
+  mkdtempFn?: typeof fs.mkdtempSync;
+  readFileFn?: typeof fs.readFileSync;
+  rmFn?: typeof fs.rmSync;
+} = {}): DarwinClipboardAdapter {
+  return {
+    available() {
+      try {
+        execFn('osascript', ['-e', 'return "ok"'], { encoding: 'utf8', timeout: HAS_IMAGE_TIMEOUT_MS });
+        return { ok: true };
+      } catch {
+        return { ok: false, reason: 'macOS osascript is unavailable' };
+      }
+    },
+    hasImage() {
+      try {
+        const output = String(execFn('osascript', ['-e', 'clipboard info'], {
+          encoding: 'utf8',
+          timeout: HAS_IMAGE_TIMEOUT_MS
+        }));
+        return /\b(PNGf|TIFF|JPEG|GIFf)\b/.test(output);
+      } catch {
+        return false;
+      }
+    },
+    readImagePng() {
+      const tmpDir = mkdtempFn(path.join(os.tmpdir(), 'agent-infra-clipboard-'));
+      const outputPath = path.join(tmpDir, 'clipboard.png');
+      try {
+        try {
+          execFn('osascript', ['-e', pngWriteScript(outputPath)], {
+            encoding: 'utf8',
+            timeout: READ_IMAGE_TIMEOUT_MS
+          });
+        } catch {
+          execFn('pngpaste', [outputPath], {
+            encoding: 'utf8',
+            timeout: READ_IMAGE_TIMEOUT_MS
+          });
+        }
+        const png = Buffer.from(readFileFn(outputPath));
+        return isPng(png) ? png : null;
+      } catch {
+        return null;
+      } finally {
+        rmFn(tmpDir, { recursive: true, force: true });
+      }
+    }
+  };
+}
+
+function isPng(buffer: Buffer): boolean {
+  return buffer.length >= PNG_MAGIC.length && PNG_MAGIC.every((byte, index) => buffer[index] === byte);
+}
+
+function pngWriteScript(outputPath: string): string {
+  const escapedPath = outputPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  return [
+    'set pngData to the clipboard as «class PNGf»',
+    `set outFile to POSIX file "${escapedPath}"`,
+    'set fileRef to open for access outFile with write permission',
+    'set eof fileRef to 0',
+    'write pngData to fileRef',
+    'close access fileRef'
+  ].join('\n');
+}

package/lib/sandbox/clipboard/index.ts

@@ -0,0 +1,13 @@
+import { platform } from 'node:os';
+import { createDarwinClipboardAdapter, type DarwinClipboardAdapter } from './darwin.ts';
+
+export type ClipboardAdapter = DarwinClipboardAdapter;
+
+export function createClipboardAdapter({
+  platformName = platform()
+}: { platformName?: NodeJS.Platform } = {}): ClipboardAdapter | null {
+  if (platformName !== 'darwin') {
+    return null;
+  }
+  return createDarwinClipboardAdapter();
+}

package/lib/sandbox/clipboard/keys.ts

@@ -0,0 +1,78 @@
+export type CtrlVMatch = {
+  kind: 'ctrl-v';
+  raw: string;
+  label: string;
+};
+
+export type KeyToken =
+  | { kind: 'text'; raw: string }
+  | CtrlVMatch;
+
+const CTRL_V_SEQUENCES = [
+  { raw: '\x16', label: 'ctrl-v 0x16' },
+  { raw: '\x1b[118;5u', label: 'ctrl-v csi-u ESC[118;5u' },
+  { raw: '\x1b[27;5;118~', label: 'ctrl-v modifyOtherKeys ESC[27;5;118~' }
+];
+
+export class CtrlVDetector {
+  #pending = '';
+
+  hasPending(): boolean {
+    return this.#pending.length > 0;
+  }
+
+  feed(raw: string): KeyToken[] {
+    let input = this.#pending + raw;
+    this.#pending = '';
+    const tokens: KeyToken[] = [];
+
+    while (input.length > 0) {
+      const match = CTRL_V_SEQUENCES.find((sequence) => input.startsWith(sequence.raw));
+      if (match) {
+        tokens.push({ kind: 'ctrl-v', raw: match.raw, label: match.label });
+        input = input.slice(match.raw.length);
+        continue;
+      }
+
+      const partial = CTRL_V_SEQUENCES.some((sequence) =>
+        sequence.raw.startsWith(input) && input.length < sequence.raw.length
+      );
+      if (partial) {
+        this.#pending = input;
+        break;
+      }
+
+      const first = input.slice(0, 1);
+      tokens.push({ kind: 'text', raw: first });
+      input = input.slice(first.length);
+    }
+
+    return coalesceText(tokens);
+  }
+
+  flush(): KeyToken[] {
+    if (!this.#pending) {
+      return [];
+    }
+    const raw = this.#pending;
+    this.#pending = '';
+    return [{ kind: 'text', raw }];
+  }
+}
+
+function coalesceText(tokens: KeyToken[]): KeyToken[] {
+  const result: KeyToken[] = [];
+  for (const token of tokens) {
+    const previous = result.at(-1);
+    if (token.kind === 'text' && previous?.kind === 'text') {
+      previous.raw += token.raw;
+    } else {
+      result.push(token);
+    }
+  }
+  return result;
+}
+
+export function buildBracketedPaste(text: string): string {
+  return `\x1b[200~${text}\x1b[201~`;
+}

package/lib/sandbox/clipboard/node-pty.d.ts

@@ -0,0 +1,19 @@
+declare module '@lydell/node-pty' {
+  export function spawn(
+    file: string,
+    args: string[],
+    options: {
+      name: string;
+      cols: number;
+      rows: number;
+      cwd: string;
+      env: NodeJS.ProcessEnv;
+    }
+  ): {
+    onData(callback: (data: string) => void): void;
+    onExit(callback: (event: { exitCode: number; signal?: number | string }) => void): void;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+  };
+}

package/lib/sandbox/clipboard/node-pty.ts

@@ -0,0 +1,34 @@
+import { createRequire } from 'node:module';
+
+export type PtyProcess = {
+  onData(callback: (data: string) => void): void;
+  onExit(callback: (event: { exitCode: number; signal?: number | string }) => void): void;
+  write(data: string): void;
+  resize(cols: number, rows: number): void;
+  kill(signal?: string): void;
+};
+
+export type NodePty = {
+  spawn(
+    file: string,
+    args: string[],
+    options: {
+      name: string;
+      cols: number;
+      rows: number;
+      cwd: string;
+      env: NodeJS.ProcessEnv;
+    }
+  ): PtyProcess;
+};
+
+export async function loadNodePty(): Promise<NodePty | null> {
+  try {
+    const require = createRequire(import.meta.url);
+    const mod = require('@lydell/node-pty') as NodePty | { default?: NodePty };
+    const maybeDefault = mod as { default?: NodePty };
+    return maybeDefault.default ?? (mod as NodePty);
+  } catch {
+    return null;
+  }
+}

package/lib/sandbox/clipboard/paths.ts

@@ -0,0 +1,71 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { hostJoin } from '../engines/wsl2-paths.ts';
+
+export const CONTAINER_CLIPBOARD_MOUNT = '/clipboard';
+const DEFAULT_KEEP = 20;
+const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+export function clipboardHostDir(home: string): string {
+  return hostJoin(home, '.agent-infra', 'clipboard');
+}
+
+export function containerClipboardPath(filename: string): string {
+  return path.posix.join(CONTAINER_CLIPBOARD_MOUNT, filename);
+}
+
+export function pngClipboardFilename(buffer: Buffer): string {
+  return `${crypto.createHash('sha256').update(buffer).digest('hex').slice(0, 16)}.png`;
+}
+
+export function writeClipboardPngAtomic(dir: string, filename: string, buffer: Buffer): string {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(dir, 0o700);
+  } catch {
+    // Best effort: existing directories may live on filesystems that ignore chmod.
+  }
+
+  const target = path.join(dir, filename);
+  const tmp = path.join(dir, `.${filename}.${process.pid}.tmp`);
+  fs.writeFileSync(tmp, buffer);
+  fs.renameSync(tmp, target);
+  return target;
+}
+
+export function pruneClipboardDir(
+  dir: string,
+  { keep = DEFAULT_KEEP, maxAgeMs = DEFAULT_MAX_AGE_MS, now = Date.now() }:
+  { keep?: number; maxAgeMs?: number; now?: number } = {}
+): string[] {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+
+  const entries = fs.readdirSync(dir)
+    .filter((name) => name.endsWith('.png'))
+    .map((name) => {
+      const fullPath = path.join(dir, name);
+      const stat = fs.statSync(fullPath);
+      return { fullPath, mtimeMs: stat.mtimeMs };
+    })
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  const keepSet = new Set(entries.slice(0, keep).map((entry) => entry.fullPath));
+  const removed: string[] = [];
+
+  for (const entry of entries) {
+    if (keepSet.has(entry.fullPath) && now - entry.mtimeMs <= maxAgeMs) {
+      continue;
+    }
+    try {
+      fs.rmSync(entry.fullPath, { force: true });
+      removed.push(entry.fullPath);
+    } catch {
+      // Cleanup is opportunistic; a failed prune should not break paste.
+    }
+  }
+
+  return removed;
+}

package/lib/sandbox/commands/create.ts

@@ -17,9 +17,9 @@ import {
   sandboxBranchLabel,
   sandboxImageConfigLabel,
   sandboxLabel,
-  sanitizeBranchName,
   shareBranchDir,
   shareCommonDir,
+  shellConfigDir,
   worktreeDirCandidates
 } from '../constants.ts';
 import { prepareDockerfile } from '../dockerfile.ts';
@@ -39,6 +39,7 @@ import { resolveTaskBranch } from '../task-resolver.ts';
 import { resolveTools, toolConfigDirCandidates, toolNpmPackagesArg } from '../tools.ts';
 import type { SandboxTool } from '../tools.ts';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.ts';
+import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.ts';
 import { validateSelinuxDisableEnv } from '../engines/selinux.ts';
 import { resolveBuildUid } from '../engines/native.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
@@ -127,7 +128,17 @@ function resolveToolDirs(config: Pick<SandboxCreateConfig, 'project'>, tools: Sa
 }
 
 export function hostShellConfigDir(home: string, project: string, branch: string): string {
-  return hostJoin(home, '.agent-infra', 'config', project, sanitizeBranchName(branch));
+  return shellConfigDir(
+    { shellConfigBase: hostJoin(home, '.agent-infra', 'config', project) },
+    branch
+  );
+}
+
+export function buildClipboardVolumeArgs(engine: string, home: string): string[] {
+  return [
+    '-v',
+    volumeArg(engine, clipboardHostDir(home), CONTAINER_CLIPBOARD_MOUNT, ':ro')
+  ];
 }
 
 function runtimeChecks(runtimes: string[]): RuntimeCheck[] {
@@ -1344,6 +1355,7 @@ export async function create(args: string[]): Promise<void> {
             fs.mkdirSync(workspaceDir, { recursive: true });
             fs.mkdirSync(shareCommon, { recursive: true });
             fs.mkdirSync(shareBranch, { recursive: true });
+            fs.mkdirSync(clipboardHostDir(effectiveConfig.home), { recursive: true, mode: 0o700 });
 
             const dotfilesSnapshot = materializeDotfiles(
               effectiveConfig.dotfilesDir,
@@ -1372,6 +1384,7 @@ export async function create(args: string[]): Promise<void> {
               volumeArg(engine, shareCommon, '/share/common'),
               '-v',
               volumeArg(engine, shareBranch, '/share/branch'),
+              ...buildClipboardVolumeArgs(engine, effectiveConfig.home),
               '-v',
               volumeArg(
                 engine,

package/lib/sandbox/commands/enter.ts

@@ -11,6 +11,7 @@ import {
 import { runInteractiveEngine, runSafeEngine } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
+import { runInteractiveWithClipboardBridge } from '../clipboard/bridge.ts';
 
 const USAGE = `Usage: ai sandbox exec <branch> [cmd...]`;
 const TMUX_ENTRY_PATH = '/usr/local/bin/sandbox-tmux-entry';
@@ -65,7 +66,7 @@ export function formatCredentialSyncStatus(
   return null;
 }
 
-export function enter(args: string[]): number {
+export async function enter(args: string[]): Promise<number> {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(`${USAGE}\n`);
     if (args.length === 0) {
@@ -108,7 +109,12 @@ export function enter(args: string[]): number {
       process.stderr.write(`Warning: dotfiles snapshot rebuild failed: ${redactCommandError(error instanceof Error ? error.message : 'unknown error')}\n`);
     }
 
-    return runInteractiveEngine(engine, 'docker', ['exec', '-it', ...envFlags, container, 'bash', TMUX_ENTRY_PATH]);
+    return runInteractiveWithClipboardBridge({
+      engine,
+      dockerArgs: ['exec', '-it', ...envFlags, container, 'bash', TMUX_ENTRY_PATH],
+      container,
+      home: config.home
+    });
   }
 
   return runInteractiveEngine(engine, 'docker', ['exec', '-it', ...envFlags, container, ...cmd]);