feat(cli): 支持云端 Linux TUI 剪贴板图片桥接 (#602)

* feat(cli): bridge clipboard images to Linux

- detect remote platforms and receive PNGs through a versioned Linux inbox
- inject pending clipboard paths in headless sandbox sessions with safe validation

Co-Authored-By: Codex <noreply@openai.com>
Co-Authored-By: Claude <noreply@anthropic.com>

* test(clipboard): guard Linux receiver cases

---------

Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

bin/cli.ts

@@ -15,7 +15,7 @@ const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructur
 Usage: ai <command> [options]
 
 Commands:
-  cp <ssh-alias>  Copy local clipboard image to a remote macOS NSPasteboard
+  cp <ssh-alias>  Copy local clipboard image to a remote macOS clipboard or Linux sandbox over SSH
   decide          Record a human decision for a task HD item
   help            Show this help message
   init            Initialize a new project with update-agent-infra seed command

docs/en/sandbox.md

@@ -22,7 +22,7 @@ Host `~/.ssh` is not bind-mounted into the sandbox. GitHub access is expected to
 
 On macOS, interactive `ai sandbox exec <branch>` sessions can bridge image paste into the sandbox. When you press `Ctrl+V` and the host clipboard currently holds an image, agent-infra reads the image from the host clipboard, writes a PNG under `~/.agent-infra/clipboard/`, and injects the container path as bracketed paste so Claude Code, Codex, Gemini CLI, and OpenCode can attach it. The host clipboard is only read, never rewritten. The bridge is best-effort: existing sandboxes must be rebuilt to receive the `/clipboard` mount, and if the optional pty dependency or clipboard probe is unavailable the session falls back to the normal interactive path. Set `AI_SANDBOX_NO_CLIPBOARD_BRIDGE=1` to skip the bridge and enter the normal interactive path directly when diagnosing mouse, scrolling, or other input issues.
 
-When you run the sandbox from a remote Mac over SSH, use `ai cp <ssh-alias>` on the Mac in front of you to push the local clipboard image to that remote Mac first. Copy an image with Cmd+C, run `ai cp mini`, then return to the existing SSH session and press `Ctrl+V`; the sandbox bridge reads the remote Mac's NSPasteboard and injects the image as usual. This command handles PNG images only and uses non-interactive ssh/scp with key-based authentication. For now both the sender and the remote must be macOS—the remote NSPasteboard is written via `osascript`—but the remote-write step is the natural extension point for other platforms later.
+When you run the sandbox over SSH, use `ai cp <ssh-alias>` on the Mac in front of you to push the local PNG clipboard image to a remote Mac or headless Linux host. Copy an image with Cmd+C, run `ai cp mini`, then return to the existing SSH session and press `Ctrl+V`. Darwin keeps the NSPasteboard path; Linux requires a compatible agent-infra receiver and stores the image under `~/.agent-infra/clipboard/` for the sandbox's read-only `/clipboard` mount. The command uses non-interactive ssh/scp with key-based authentication.
 
 `ai sandbox exec` and `ai sandbox refresh` reconcile Claude Code credentials in both directions across the host credential store and every sandbox project copy under `~/.agent-infra/credentials/*`. When a long-running sandbox refreshes OAuth tokens first, the next entry or refresh command writes the freshest valid copy back to the host Keychain or `~/.claude/.credentials.json`; when the host is fresher, it updates the project copies. If every copy is stale, `ai sandbox refresh` probes `claude /status` and asks you to log in only when the probe cannot recover credentials.
 

docs/zh-CN/sandbox.md

@@ -22,7 +22,7 @@
 
 在 macOS 上，交互式 `ai sandbox exec <branch>` 会尽力桥接宿主图片粘贴。当你按下 `Ctrl+V` 且宿主剪贴板当前是图片时，agent-infra 会从宿主剪贴板读取图片，将 PNG 写到 `~/.agent-infra/clipboard/`，再以 bracketed paste 注入容器内路径，让 Claude Code、Codex、Gemini CLI 和 OpenCode 按图片附件处理。宿主剪贴板只读，不会被改写。该能力会自动降级：已有沙箱需要重建后才有 `/clipboard` 挂载；如果可选 pty 依赖或剪贴板探测不可用，会回退到原本的交互进入方式。排查鼠标、滚动或其他输入异常时，可以设置 `AI_SANDBOX_NO_CLIPBOARD_BRIDGE=1` 跳过桥接，直接进入原本的交互路径。
 
-当你通过 SSH 在远端 Mac 上运行沙箱时，可先在手边这台 Mac 上执行 `ai cp <ssh-alias>`，把本机剪贴板图片推送到远端 Mac。典型流程是：Cmd+C 复制图片，运行 `ai cp mini`，回到已有 SSH session 后按 `Ctrl+V`；沙箱桥会读取远端 Mac 的 NSPasteboard，并按原路径注入图片。该命令只处理 PNG 图片，并使用基于 ssh key 的非交互 ssh/scp。目前发送端与远端都需为 macOS（远端通过 `osascript` 写入 NSPasteboard），后续可扩展支持其他远端平台。
+当你通过 SSH 运行远端沙箱时，可先在手边这台 Mac 上执行 `ai cp <ssh-alias>`，把本机剪贴板 PNG 推送到远端 Mac 或无桌面 Linux 主机。典型流程是：Cmd+C 复制图片，运行 `ai cp mini`，回到已有 SSH session 后按 `Ctrl+V`。Darwin 继续写入 NSPasteboard；Linux 需要远端已安装兼容版本的 agent-infra，图片会写入 `~/.agent-infra/clipboard/`，再由沙箱的只读 `/clipboard` 挂载注入。命令使用基于 ssh key 的非交互 ssh/scp。
 
 `ai sandbox exec` 和 `ai sandbox refresh` 会在宿主机凭证存储与 `~/.agent-infra/credentials/*` 下的所有沙箱项目副本之间做双向 reconcile。长时间运行的沙箱如果先刷新了 OAuth token，下一次进入或刷新命令会把最新有效副本回写到宿主 Keychain 或 `~/.claude/.credentials.json`；宿主机更新时也会继续覆盖项目副本。如果所有副本都已失效，`ai sandbox refresh` 会尝试 `claude /status` 探活，只有探活无法恢复时才提示重新登录。
 

lib/cp.ts

@@ -5,8 +5,9 @@ import { platform as currentPlatform, tmpdir as defaultTmpdir } from 'node:os';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { createClipboardAdapter, type ClipboardAdapter } from './sandbox/clipboard/index.ts';
+import { RECEIVER_CAPABILITY, receiveRemoteClipboardPng } from './sandbox/clipboard/inbox.ts';
 
-const USAGE = 'Usage: ai cp <ssh-alias>\n\nCopy the local clipboard image (PNG) to a remote macOS NSPasteboard over ssh/scp.\n';
+const USAGE = 'Usage: ai cp <ssh-alias>\n\nCopy the local clipboard image (PNG) to a remote macOS clipboard or Linux sandbox over SSH.\n';
 const COMMAND_TIMEOUT_MS = 30_000;
 
 export type SpawnResult = {
@@ -65,6 +66,21 @@ export async function cmdCp(args: string[], deps: CpDeps = {}): Promise<number>
     writeStderr = (chunk: string) => process.stderr.write(chunk)
   } = deps;
 
+  if (args.length === 1 && args[0] === '--remote-receive-capability') {
+    if (platform === 'linux') writeStdout(`${RECEIVER_CAPABILITY}\n`);
+    return platform === 'linux' ? 0 : 1;
+  }
+  if (args.length === 2 && args[0] === '--remote-receive-v1') {
+    try {
+      const result = receiveRemoteClipboardPng(process.env.HOME || process.env.USERPROFILE || '', args[1]!, platform);
+      writeStdout(`${result}\n`);
+      return 0;
+    } catch (error) {
+      writeStderr(`${error instanceof Error ? error.message : 'clipboard receive failed'}\n`);
+      return 1;
+    }
+  }
+
   if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
     writeStdout(USAGE);
     return 0;
@@ -110,6 +126,35 @@ export async function cmdCp(args: string[], deps: CpDeps = {}): Promise<number>
     writeFileFn(localPng, png);
 
     remotePath = `/tmp/agent-infra-cp-${randomId()}.png`;
+    const remoteSystem = spawnFn('ssh', [
+      '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'uname', '-s'
+    ]);
+    if (remoteSystem.status !== 0) {
+      writeStderr(`failed to detect remote platform on ${alias}:\n${commandDetail(remoteSystem)}\n`);
+      return 1;
+    }
+    const remotePlatform = remoteSystem.stdout.trim();
+    if (remotePlatform !== 'Darwin' && remotePlatform !== 'Linux') {
+      writeStderr(`unsupported remote platform on ${alias}: ${remotePlatform || 'unknown'}\n`);
+      return 1;
+    }
+    if (remotePlatform === 'Linux') {
+      const homeCheck = spawnFn('ssh', [
+        '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'test', '-d', '$HOME/.agent-infra'
+      ]);
+      if (homeCheck.status !== 0) {
+        writeStderr(`remote agent-infra installation is missing on ${alias}\n`);
+        return 1;
+      }
+      const capability = spawnFn('ssh', [
+        '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'ai', 'cp', '--remote-receive-capability'
+      ]);
+      if (capability.status !== 0 || capability.stderr !== '' || capability.stdout.replace(/\n$/u, '') !== RECEIVER_CAPABILITY) {
+        writeStderr(`remote agent-infra clipboard receiver is unavailable or incompatible on ${alias}; update agent-infra\n`);
+        return 1;
+      }
+    }
+
     const upload = spawnFn('scp', [
       '-o',
       'BatchMode=yes',
@@ -124,25 +169,21 @@ export async function cmdCp(args: string[], deps: CpDeps = {}): Promise<number>
     }
     uploaded = true;
 
-    // Remote write currently targets macOS only: it pipes an AppleScript to the
-    // remote `osascript` to set its NSPasteboard. This is the extension point for
-    // other remote platforms later (e.g. dispatch on remote OS to wl-copy/xclip
-    // on Linux); a non-macOS remote fails here with a clear non-zero error today.
-    const setRemote = spawnFn('ssh', [
-      '-o',
-      'BatchMode=yes',
-      '-o',
-      'ConnectTimeout=10',
-      alias,
-      'osascript',
-      '-'
-    ], remoteSetScript(remotePath));
+    const setRemote = remotePlatform === 'Darwin'
+      ? spawnFn('ssh', [
+        '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'osascript', '-'
+      ], remoteSetScript(remotePath))
+      : spawnFn('ssh', [
+        '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'ai', 'cp', '--remote-receive-v1', remotePath
+      ]);
     if (setRemote.status !== 0) {
       writeStderr(`failed to set remote clipboard on ${alias}:\n${commandDetail(setRemote)}\n`);
       return 1;
     }
 
-    writeStdout(`copied clipboard image to ${alias}\n`);
+    writeStdout(remotePlatform === 'Linux'
+      ? `uploaded clipboard image to ${alias}; return to the SSH session and press Ctrl+V\n`
+      : `copied clipboard image to ${alias}\n`);
     return 0;
   } finally {
     if (uploaded && remotePath) {

lib/sandbox/clipboard/bridge.ts

@@ -9,6 +9,7 @@ import {
   pruneClipboardDir,
   writeClipboardPngAtomic
 } from './paths.ts';
+import { isClipboardInboxReadable, readPendingClipboardPath } from './inbox.ts';
 import { commandForEngine, restoreTerminal, runInteractiveEngine, runOkEngine } from '../shell.ts';
 import { loadNodePty, type NodePty, type PtyProcess } from './node-pty.ts';
 
@@ -85,13 +86,9 @@ export async function runInteractiveWithClipboardBridge(options: BridgeOptions):
   if (!stdin.isTTY || !stdout.isTTY) {
     return fallback('host stdin/stdout is not a TTY');
   }
-  if (!adapter) {
-    return fallback('no clipboard adapter available on this platform');
-  }
-  const available = adapter.available();
-  if (!available.ok) {
-    return fallback(available.reason);
-  }
+  const available = adapter?.available() ?? { ok: false as const, reason: 'no clipboard adapter available on this platform' };
+  const inboxReady = isClipboardInboxReadable(home);
+  if (!available.ok && !inboxReady) 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');
   }
@@ -119,7 +116,7 @@ export async function runInteractiveWithClipboardBridge(options: BridgeOptions):
   return runBridge({
     child,
     home,
-    adapter,
+    adapter: available.ok ? adapter : null,
     writeStderr,
     stdin,
     stdout,
@@ -138,7 +135,7 @@ async function runBridge({
 }: {
   child: PtyProcess;
   home: string;
-  adapter: ClipboardAdapter;
+  adapter: ClipboardAdapter | null;
   writeStderr: (chunk: string) => unknown;
   stdin: NodeJS.ReadStream;
   stdout: NodeJS.WriteStream;
@@ -182,9 +179,9 @@ async function runBridge({
   }
 
   function handleText(raw: string, target: PtyProcess): void {
-    const textAdapter = adapter as TextImageClipboardAdapter;
+    const textAdapter = adapter as TextImageClipboardAdapter | null;
     const pastedText = extractSinglePathPaste(raw);
-    if (!textAdapter.readImageFromText || pastedText === null) {
+    if (!textAdapter || !textAdapter.readImageFromText || pastedText === null) {
       target.write(raw);
       return;
     }
@@ -207,12 +204,17 @@ async function runBridge({
 
   function handleCtrlV(match: CtrlVMatch, target: PtyProcess): void {
     try {
+      const pendingPath = readPendingClipboardPath(home);
+      if (pendingPath) {
+        target.write(buildBracketedPaste(pendingPath));
+        return;
+      }
       // readImagePng returns null both for "no image on clipboard" and for
       // unexpected read failures; both cases forward the original Ctrl+V so
       // the container app handles it as a regular keystroke. The throw branch
       // below only fires on truly unexpected exceptions (e.g. fs write
       // errors writing to the host clipboard dir).
-      const png = adapter.readImagePng();
+      const png = adapter?.readImagePng() ?? null;
       if (!png) {
         target.write(match.raw);
         return;

lib/sandbox/clipboard/inbox.ts

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  clipboardHostDir,
+  containerClipboardPath,
+  pngClipboardFilename,
+  pruneClipboardDir,
+  writeClipboardPngAtomic
+} from './paths.ts';
+
+export const RECEIVER_CAPABILITY = 'AGENT_INFRA_CLIPBOARD_RECEIVER:v1';
+const MARKER = '.pending.json';
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const HASHED_PNG = /^[a-f0-9]{16}\.png$/u;
+const REMOTE_TEMP = /^agent-infra-cp-[0-9a-f-]{36}\.png$/u;
+
+export function isClipboardInboxReadable(home: string): boolean {
+  const dir = clipboardHostDir(home);
+  try {
+    fs.accessSync(dir, fs.constants.R_OK);
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function receiveRemoteClipboardPng(home: string, tempPath: string, platformName: NodeJS.Platform = process.platform): string {
+  if (platformName !== 'linux') throw new Error('remote clipboard receiver requires Linux');
+  if (path.dirname(tempPath) !== '/tmp' || !REMOTE_TEMP.test(path.basename(tempPath))) {
+    throw new Error('invalid clipboard upload path');
+  }
+  const signature = Buffer.alloc(PNG_SIGNATURE.length);
+  const fd = fs.openSync(tempPath, 'r');
+  let signatureBytes: number;
+  try {
+    signatureBytes = fs.readSync(fd, signature, 0, signature.length, 0);
+  } finally {
+    fs.closeSync(fd);
+  }
+  if (signatureBytes !== PNG_SIGNATURE.length || !signature.equals(PNG_SIGNATURE)) {
+    throw new Error('uploaded clipboard file is not a PNG');
+  }
+  const png = fs.readFileSync(tempPath);
+  const dir = clipboardHostDir(home);
+  if (!fs.existsSync(path.dirname(dir))) throw new Error('agent-infra is not installed on this host');
+  const filename = pngClipboardFilename(png);
+  writeClipboardPngAtomic(dir, filename, png);
+  pruneClipboardDir(dir);
+  const markerTmp = path.join(dir, `.${MARKER}.${process.pid}.tmp`);
+  fs.writeFileSync(markerTmp, JSON.stringify({ version: 1, filename, createdAt: new Date().toISOString() }) + '\n', { mode: 0o600 });
+  fs.renameSync(markerTmp, path.join(dir, MARKER));
+  return containerClipboardPath(filename);
+}
+
+export function readPendingClipboardPath(home: string): string | null {
+  const dir = clipboardHostDir(home);
+  const markerPath = path.join(dir, MARKER);
+  let markerText: string;
+  try {
+    markerText = fs.readFileSync(markerPath, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw new Error('invalid clipboard pending marker', { cause: error });
+  }
+
+  let marker: { version?: unknown; filename?: unknown };
+  try {
+    marker = JSON.parse(markerText) as { version?: unknown; filename?: unknown };
+  } catch (error) {
+    throw new Error('invalid clipboard pending marker', { cause: error });
+  }
+  if (marker.version !== 1 || typeof marker.filename !== 'string' || !HASHED_PNG.test(marker.filename)) {
+    throw new Error('invalid clipboard pending marker');
+  }
+  const filePath = path.join(dir, marker.filename);
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('pending clipboard image is not a regular file');
+  } catch (error) {
+    throw new Error('invalid clipboard pending marker', { cause: error });
+  }
+  return containerClipboardPath(marker.filename);
+}