@fitlab-ai/agent-infra 0.8.2 → 0.8.4

package/README.zh-CN.md

@@ -207,3 +207,13 @@ my-project/
 ## 许可协议
 
 [MIT](License.txt)
+
+## 社区
+
+- 微信公众号：`FitFramework`
+- QQ 技术交流群：`1029802553`
+
+<p align="center">
+  <img src="./assets/qrcode_for_wechat_gh.png" alt="FitFramework 微信公众号二维码" width="250">
+  <img src="./assets/qrcode_for_qq_01.png" alt="FitFramework QQ 技术交流群二维码" width="250">
+</p>

package/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

package/dist/bin/cli.js

@@ -7,7 +7,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { VERSION } from "../lib/version.js";
+import { VERSION } from '../lib/version.js';
 // Node.js version check
 const [major = 0, minor = 0] = process.versions.node.split('.').map((part) => parseInt(part, 10));
 if (major < 22 || (major === 22 && minor < 9)) {
@@ -19,7 +19,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

package/dist/lib/cp.js

@@ -4,8 +4,9 @@ import fs from 'node:fs';
 import { platform as currentPlatform, tmpdir as defaultTmpdir } from 'node:os';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
-import { createClipboardAdapter } from "./sandbox/clipboard/index.js";
-const USAGE = 'Usage: ai cp <ssh-alias>\n\nCopy the local clipboard image (PNG) to a remote macOS NSPasteboard over ssh/scp.\n';
+import { createClipboardAdapter } from './sandbox/clipboard/index.js';
+import { RECEIVER_CAPABILITY, receiveRemoteClipboardPng } from './sandbox/clipboard/inbox.js';
+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 function runCommand(cmd, args, input) {
     const result = spawnSync(cmd, args, {
@@ -23,6 +24,22 @@ export function runCommand(cmd, args, input) {
 }
 export async function cmdCp(args, deps = {}) {
     const { platform = currentPlatform(), createAdapter = createClipboardAdapter, spawnFn = runCommand, randomId = randomUUID, mkdtempFn = fs.mkdtempSync, writeFileFn = fs.writeFileSync, rmFn = fs.rmSync, tmpdir = defaultTmpdir, writeStdout = (chunk) => process.stdout.write(chunk), writeStderr = (chunk) => 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;
@@ -62,6 +79,34 @@ export async function cmdCp(args, deps = {}) {
         const localPng = path.join(localTmpDir, 'clipboard.png');
         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',
@@ -75,24 +120,20 @@ export async function cmdCp(args, deps = {}) {
             return 1;
         }
         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 {

package/dist/lib/decide.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { VERSION } from "./version.js";
-import { resolveTaskRef } from "./task/resolve-ref.js";
+import { VERSION } from './version.js';
+import { resolveTaskRef } from './task/resolve-ref.js';
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 function detectRepoRoot() {
     return execFileSync('git', ['rev-parse', '--show-toplevel'], {

package/dist/lib/defaults.json

@@ -14,6 +14,7 @@
       "gemini-cli",
       "opencode"
     ],
+    "refreshIntervalDays": 7,
     "dockerfile": null,
     "vm": {
       "cpu": null,
@@ -51,6 +52,7 @@
       "**/test-integration.*",
       "**/test.*",
       "**/upgrade-dependency.*",
+      ".agents/rules/testing-discipline.*",
       ".agents/skills/post-release/SKILL.*",
       ".agents/skills/release/SKILL.*",
       ".agents/skills/test-integration/SKILL.*",

package/dist/lib/init.js

@@ -2,13 +2,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { platform } from 'node:os';
-import { info, ok, err } from "./log.js";
-import { prompt, select, multiSelect, closePrompt } from "./prompt.js";
-import { resolveTemplateDir } from "./paths.js";
-import { renderFile, copySkillDir, KNOWN_PLATFORMS } from "./render.js";
-import { enginesForPlatform } from "./sandbox/engines/index.js";
-import { VERSION } from "./version.js";
-import { BUILTIN_TUI_IDS, BUILTIN_TUI_DISPLAY, isPathOwnedByDisabledTUI, resolveEnabledTUIs } from "./builtin-tuis.js";
+import { info, ok, err } from './log.js';
+import { prompt, select, multiSelect, closePrompt } from './prompt.js';
+import { resolveTemplateDir } from './paths.js';
+import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.js';
+import { enginesForPlatform } from './sandbox/engines/index.js';
+import { VERSION } from './version.js';
+import { BUILTIN_TUI_IDS, BUILTIN_TUI_DISPLAY, isPathOwnedByDisabledTUI, resolveEnabledTUIs } from './builtin-tuis.js';
 const defaults = JSON.parse(fs.readFileSync(new URL('./defaults.json', import.meta.url), 'utf8'));
 const PLATFORM_DEFAULT_ENGINES = Object.freeze({
     linux: 'native',

package/dist/lib/merge.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { info, ok } from "./log.js";
+import { info, ok } from './log.js';
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 const TITLE_RE = /^# (.+)$/m;

package/dist/lib/prompt.js

@@ -1,5 +1,5 @@
 import readline from 'node:readline';
-import { ask } from "./log.js";
+import { ask } from './log.js';
 let _rl = null;
 let _lines = [];
 let _lineResolve = null;

package/dist/lib/run/index.js

@@ -1,12 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { loadServerConfig } from "../server/config.js";
-import { resolveTaskBranch } from "../sandbox/task-resolver.js";
-import { createRunId, runInSandbox } from "../sandbox/capture.js";
-import { loadShortIdByTaskId, normalizeShortIdInput } from "../task/short-id.js";
-import { buildTuiCommand, renderPrompt, selectTui } from "./tui.js";
-import { getSkillRunSpec } from "./skills.js";
-import { runHostCommand } from "./host.js";
+import { loadServerConfig } from '../server/config.js';
+import { resolveTaskBranch } from '../sandbox/task-resolver.js';
+import { createRunId, runInSandbox } from '../sandbox/capture.js';
+import { loadShortIdByTaskId, normalizeShortIdInput } from '../task/short-id.js';
+import { buildTuiCommand, renderPrompt, selectTui } from './tui.js';
+import { getSkillRunSpec } from './skills.js';
+import { runHostCommand } from './host.js';
 const USAGE = `Usage: ai run <skill> [task-ref] [args...] [--tui <name>]
 
 Task skills are scheduled inside the sandbox tmux session; ai run returns once

package/dist/lib/run/prompt.js

@@ -1,2 +1,2 @@
-export { renderPrompt } from "./tui.js";
+export { renderPrompt } from './tui.js';
 //# sourceMappingURL=prompt.js.map

package/dist/lib/sandbox/capture.js

@@ -1,9 +1,10 @@
 import { spawn } from 'node:child_process';
-import { loadConfig } from "./config.js";
-import { containerNameCandidates, sandboxBranchLabel, sandboxLabel } from "./constants.js";
-import { detectEngine } from "./engine.js";
-import { hostTimezoneEnvFlags, terminalEnvFlags } from "./commands/enter.js";
-import { fetchSandboxRows, selectSandboxContainer, startSandboxContainer } from "./commands/list-running.js";
+import { loadConfig } from './config.js';
+import { containerNameCandidates, sandboxBranchLabel, sandboxLabel } from './constants.js';
+import { detectEngine } from './engine.js';
+import { commandForEngine } from './shell.js';
+import { hostTimezoneEnvFlags, terminalEnvFlags } from './commands/enter.js';
+import { fetchSandboxRows, selectSandboxContainer, startSandboxContainer } from './commands/list-running.js';
 async function spawnCapture(file, args) {
     return new Promise((resolve, reject) => {
         const child = spawn(file, args, { stdio: ['ignore', 'pipe', 'pipe'] });
@@ -49,12 +50,12 @@ function buildRunScript(params) {
     return `#!/bin/sh
 set -u
 cd /workspace
-date "+%Y-%m-%d %H:%M:%S%:z" > ${runDir}/started_at
+date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\\([+-][0-9][0-9]\\)\\([0-9][0-9]\\)$/\\1:\\2/' > ${runDir}/started_at
 printf '%s\\n' running > ${runDir}/status
 ${command}
 code=$?
 printf '%s\\n' "$code" > ${runDir}/exit_code
-date "+%Y-%m-%d %H:%M:%S%:z" > ${runDir}/finished_at
+date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\\([+-][0-9][0-9]\\)\\([0-9][0-9]\\)$/\\1:\\2/' > ${runDir}/finished_at
 if [ "$code" -eq 0 ]; then
   printf '%s\\n' completed > ${runDir}/status
 else
@@ -144,7 +145,8 @@ export async function runInSandbox(request, options = {}) {
         '-lc',
         buildTmuxLauncher({ request, runId })
     ];
-    const result = await (options.spawn ?? spawnCapture)('docker', dockerArgs);
+    const command = commandForEngine(engine, 'docker', dockerArgs);
+    const result = await (options.spawn ?? spawnCapture)(command.cmd, command.args);
     return {
         ...result,
         run: {

package/dist/lib/sandbox/clipboard/bridge.js

@@ -1,12 +1,14 @@
 import { StringDecoder } from 'node:string_decoder';
 import { spawnSync } from 'node:child_process';
-import { createClipboardAdapter } from "./index.js";
-import { buildBracketedPaste, CtrlVDetector } from "./keys.js";
-import { clipboardHostDir, containerClipboardPath, pngClipboardFilename, pruneClipboardDir, writeClipboardPngAtomic } from "./paths.js";
-import { commandForEngine, restoreTerminal, runInteractiveEngine, runOkEngine } from "../shell.js";
-import { loadNodePty } from "./node-pty.js";
+import { createClipboardAdapter } from './index.js';
+import { buildBracketedPaste, CtrlVDetector } from './keys.js';
+import { clipboardHostDir, containerClipboardPath, pngClipboardFilename, pruneClipboardDir, writeClipboardPngAtomic } from './paths.js';
+import { isClipboardInboxReadable, readPendingClipboardPath } from './inbox.js';
+import { commandForEngine, restoreTerminal, runInteractiveEngine, runOkEngine } from '../shell.js';
+import { loadNodePty } from './node-pty.js';
 const FALLBACK_PREFIX = 'Warning: clipboard image paste bridge disabled';
 const PARTIAL_ESCAPE_FLUSH_MS = 30;
+const BRACKETED_PASTE_RE = /^\x1b\[200~([\s\S]*)\x1b\[201~$/u;
 // Node's stdin.setRawMode(true) uses libuv's RAW mode, which (unlike the
 // cfmakeraw that `docker exec -it` applies on the non-bridge path) keeps ONLCR
 // set on the shared host TTY. With ONLCR on, the kernel rewrites the bare \n
@@ -36,13 +38,10 @@ export async function runInteractiveWithClipboardBridge(options) {
     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) {
+    const available = adapter?.available() ?? { ok: false, 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');
     }
@@ -68,7 +67,7 @@ export async function runInteractiveWithClipboardBridge(options) {
     return runBridge({
         child,
         home,
-        adapter,
+        adapter: available.ok ? adapter : null,
         writeStderr,
         stdin,
         stdout,
@@ -83,7 +82,7 @@ async function runBridge({ child, home, adapter, writeStderr, stdin, stdout, det
         clearFlushTimer();
         for (const token of detector.feed(inputDecoder.write(chunk))) {
             if (token.kind === 'text') {
-                child.write(token.raw);
+                handleText(token.raw, child);
             }
             else {
                 handleCtrlV(token, child);
@@ -94,7 +93,7 @@ async function runBridge({ child, home, adapter, writeStderr, stdin, stdout, det
                 flushTimer = null;
                 for (const token of detector.flush()) {
                     if (token.kind === 'text') {
-                        child.write(token.raw);
+                        handleText(token.raw, child);
                     }
                     else {
                         handleCtrlV(token, child);
@@ -106,22 +105,53 @@ async function runBridge({ child, home, adapter, writeStderr, stdin, stdout, det
     const onResize = () => child.resize(stdout.columns || 120, stdout.rows || 40);
     const onSigint = () => child.kill('SIGINT');
     const onSigterm = () => child.kill('SIGTERM');
+    function writeImagePaste(png, target) {
+        const filename = pngClipboardFilename(png);
+        writeClipboardPngAtomic(clipboardHostDir(home), filename, png);
+        pruneClipboardDir(clipboardHostDir(home));
+        target.write(buildBracketedPaste(containerClipboardPath(filename)));
+    }
+    function handleText(raw, target) {
+        const textAdapter = adapter;
+        const pastedText = extractSinglePathPaste(raw);
+        if (!textAdapter || !textAdapter.readImageFromText || pastedText === null) {
+            target.write(raw);
+            return;
+        }
+        try {
+            const png = textAdapter.readImageFromText(pastedText);
+            if (!png) {
+                target.write(raw);
+                return;
+            }
+            writeImagePaste(png, target);
+        }
+        catch (error) {
+            target.write(raw);
+            if (!warnedPasteFailure) {
+                warnedPasteFailure = true;
+                writeStderr(`Warning: clipboard image paste failed; forwarded pasted text (${error instanceof Error ? error.message : 'unknown error'})\n`);
+            }
+        }
+    }
     function handleCtrlV(match, target) {
         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;
             }
-            const filename = pngClipboardFilename(png);
-            writeClipboardPngAtomic(clipboardHostDir(home), filename, png);
-            pruneClipboardDir(clipboardHostDir(home));
-            target.write(buildBracketedPaste(containerClipboardPath(filename)));
+            writeImagePaste(png, target);
         }
         catch (error) {
             target.write(match.raw);
@@ -155,7 +185,7 @@ async function runBridge({ child, home, adapter, writeStderr, stdin, stdout, det
         try {
             for (const token of detector.feed(inputDecoder.end())) {
                 if (token.kind === 'text') {
-                    child.write(token.raw);
+                    handleText(token.raw, child);
                 }
                 else {
                     handleCtrlV(token, child);
@@ -163,7 +193,7 @@ async function runBridge({ child, home, adapter, writeStderr, stdin, stdout, det
             }
             for (const token of detector.flush()) {
                 if (token.kind === 'text') {
-                    child.write(token.raw);
+                    handleText(token.raw, child);
                 }
             }
         }
@@ -181,6 +211,14 @@ async function runBridge({ child, home, adapter, writeStderr, stdin, stdout, det
         restoreTerminal();
     }
 }
+function extractSinglePathPaste(raw) {
+    const match = raw.match(BRACKETED_PASTE_RE);
+    const text = (match ? match[1] : raw)?.trim();
+    if (!text || /[\r\n]/u.test(text)) {
+        return null;
+    }
+    return text;
+}
 function onceExit(child, stdin) {
     return new Promise((resolve) => {
         let settled = false;

package/dist/lib/sandbox/clipboard/inbox.js

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { clipboardHostDir, containerClipboardPath, pngClipboardFilename, pruneClipboardDir, writeClipboardPngAtomic } from './paths.js';
+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) {
+    const dir = clipboardHostDir(home);
+    try {
+        fs.accessSync(dir, fs.constants.R_OK);
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function receiveRemoteClipboardPng(home, tempPath, platformName = process.platform) {
+    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;
+    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) {
+    const dir = clipboardHostDir(home);
+    const markerPath = path.join(dir, MARKER);
+    let markerText;
+    try {
+        markerText = fs.readFileSync(markerPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new Error('invalid clipboard pending marker', { cause: error });
+    }
+    let marker;
+    try {
+        marker = JSON.parse(markerText);
+    }
+    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);
+}
+//# sourceMappingURL=inbox.js.map

package/dist/lib/sandbox/clipboard/index.js

@@ -1,16 +1,15 @@
 import { platform } from 'node:os';
-import { createDarwinClipboardAdapter } from "./darwin.js";
+import { createDarwinClipboardAdapter } from './darwin.js';
+import { createLinuxClipboardAdapter } from './linux.js';
+import { createWin32ClipboardAdapter } from './win32.js';
 export function createClipboardAdapter({ platformName = platform() } = {}) {
     switch (platformName) {
         case 'darwin':
             return createDarwinClipboardAdapter();
         case 'linux':
-            // Future work: dispatch based on $WAYLAND_DISPLAY (wl-paste) or $DISPLAY (xclip);
-            // see Issue #386 follow-up. Returning null disables the bridge for now.
-            return null;
+            return createLinuxClipboardAdapter();
         case 'win32':
-            // Future work: native Win32 clipboard reader. Returning null disables the bridge.
-            return null;
+            return createWin32ClipboardAdapter();
         default:
             return null;
     }

package/dist/lib/sandbox/clipboard/linux.js

@@ -0,0 +1,91 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const PROBE_TIMEOUT_MS = 2_000;
+const READ_IMAGE_TIMEOUT_MS = 5_000;
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+export function createLinuxClipboardAdapter({ env = process.env, execFn = execFileSync, execToFileFn = execToFile, mkdtempFn = fs.mkdtempSync, readFileFn = fs.readFileSync, rmFn = fs.rmSync } = {}) {
+    return {
+        available() {
+            const backend = selectBackend(env);
+            try {
+                execFn(backend.command, versionArgs(backend), {
+                    encoding: 'utf8',
+                    timeout: PROBE_TIMEOUT_MS
+                });
+                return { ok: true };
+            }
+            catch {
+                return { ok: false, reason: unavailableReason(backend) };
+            }
+        },
+        readImagePng() {
+            const backend = selectBackend(env);
+            try {
+                const mimeTypes = String(execFn(backend.command, mimeArgs(backend), {
+                    encoding: 'utf8',
+                    timeout: PROBE_TIMEOUT_MS
+                }));
+                if (!hasPngMime(mimeTypes)) {
+                    return null;
+                }
+                const tmpDir = mkdtempFn(path.join(os.tmpdir(), 'agent-infra-clipboard-'));
+                const outputPath = path.join(tmpDir, 'clipboard.png');
+                try {
+                    execToFileFn(backend.command, imageArgs(backend), outputPath, READ_IMAGE_TIMEOUT_MS);
+                    const png = Buffer.from(readFileFn(outputPath));
+                    return isPng(png) ? png : null;
+                }
+                finally {
+                    rmFn(tmpDir, { recursive: true, force: true });
+                }
+            }
+            catch {
+                return null;
+            }
+        }
+    };
+}
+function selectBackend(env) {
+    return env.WAYLAND_DISPLAY?.trim()
+        ? { kind: 'wayland', command: 'wl-paste' }
+        : { kind: 'x11', command: 'xclip' };
+}
+function versionArgs(backend) {
+    return backend.kind === 'wayland' ? ['--version'] : ['-version'];
+}
+function mimeArgs(backend) {
+    return backend.kind === 'wayland'
+        ? ['--list-types']
+        : ['-selection', 'clipboard', '-t', 'TARGETS', '-o'];
+}
+function imageArgs(backend) {
+    return backend.kind === 'wayland'
+        ? ['-t', 'image/png']
+        : ['-selection', 'clipboard', '-t', 'image/png', '-o'];
+}
+function unavailableReason(backend) {
+    return backend.kind === 'wayland'
+        ? 'Wayland clipboard tool wl-paste is unavailable; install wl-clipboard to enable image paste'
+        : 'X11 clipboard tool xclip is unavailable; install xclip to enable image paste';
+}
+function hasPngMime(output) {
+    return output.split(/\s+/u).some((type) => type === 'image/png');
+}
+function execToFile(cmd, args, outputPath, timeout) {
+    const fd = fs.openSync(outputPath, 'w', 0o600);
+    try {
+        execFileSync(cmd, args, {
+            timeout,
+            stdio: ['ignore', fd, 'pipe']
+        });
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function isPng(buffer) {
+    return buffer.length >= PNG_MAGIC.length && PNG_MAGIC.every((byte, index) => buffer[index] === byte);
+}
+//# sourceMappingURL=linux.js.map

package/dist/lib/sandbox/clipboard/paths.js

@@ -1,7 +1,7 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { hostJoin } from "../engines/wsl2-paths.js";
+import { hostJoin } from '../engines/wsl2-paths.js';
 export const CONTAINER_CLIPBOARD_MOUNT = '/clipboard';
 const DEFAULT_KEEP = 20;
 const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;