Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

7.0 KB
Raw Blame
/**
 * Writing image bytes into the HOST OS's native clipboard — the machine this process itself runs
 * on, which for a relayed session is the remote machine, not the desktop client's. This is the
 * other half of native image paste: the engine attached to the tmux pane (Claude Code, Codex CLI,
 * ...) already reads its OWN OS clipboard on a paste keystroke — see terminalStreamManager.ts's
 * `pasteImage()` — so writing the clipboard here and then replaying that keystroke is all that's
 * needed; no OS-level keystroke synthesis is involved.
 */
import { execFile, spawn } from 'node:child_process'
import { release } from 'node:os'
import { binaryOnPath } from './binaryOnPath.js'

export type OsClipboardImageResult =
  | { state: 'written' }
  /** No clipboard reachable at all right now (tool missing, or genuinely no X11/Wayland session) —
   *  not an error, just nothing to write to. Caller falls back to pasting a file path instead. */
  | { state: 'unavailable'; reason: string }
  /** The clipboard mechanism is present but the write itself failed. */
  | { state: 'failed'; reason: string }

function runWithStdin(command: string, args: string[], input: Uint8Array): Promise<{ ok: boolean; message?: string }> {
  return new Promise((resolve) => {
    let child: ReturnType<typeof spawn>
    try {
      child = spawn(command, args, { stdio: ['pipe', 'ignore', 'pipe'] })
    } catch (error) {
      resolve({ ok: false, message: error instanceof Error ? error.message : String(error) })
      return
    }
    let stderr = ''
    child.stderr?.on('data', (chunk) => { stderr += String(chunk) })
    child.once('error', (error) => resolve({ ok: false, message: error.message }))
    // 'exit', NOT 'close': both xclip and wl-copy load the clipboard data and then fork into a
    // background process that STAYS ALIVE to serve paste requests (X11/Wayland clipboard ownership
    // has no concept of "set once" — someone has to keep answering selection requests) — and that
    // forked process inherits this one's stdio pipes. Node's 'close' waits for every stdio stream to
    // close too, which then never happens: confirmed live against real xclip on Ubuntu, where a
    // `close` listener here hung indefinitely even though the write itself completes in milliseconds.
    // 'exit' only waits on the process we actually spawned, which is what answers "did the write
    // succeed" — whatever it forked into afterwards is background clipboard-owner housekeeping we
    // don't need to wait on.
    child.once('exit', (code) => {
      // The stdio PIPE handles this process handed to the child may still be held open by whatever
      // it forked into (see above), and each is its own libuv handle independent of the child
      // process handle — `child.unref()` alone measurably left the pipes still keeping the event
      // loop alive (reproduced live: the write completed but the process needed a hard timeout to
      // return). `stdin`/`stderr` are `net.Socket`s for pipe-based stdio, which do have `.unref()` at
      // runtime even though the general `Writable`/`Readable` types TypeScript sees here don't
      // declare it — hence the cast.
      type Unrefable = { unref?: () => void }
      (child.stdin as unknown as Unrefable | null)?.unref?.()
      ;(child.stderr as unknown as Unrefable | null)?.unref?.()
      child.unref()
      resolve(code === 0 ? { ok: true } : { ok: false, message: stderr.trim() || `exited with code ${code}` })
    })
    child.stdin?.end(Buffer.from(input))
  })
}

/** macOS: `osascript` ships with the OS, nothing to detect. Reads the PNG bytes back off disk (the
 *  `read … as «class PNGf»` idiom needs a POSIX file path, not stdin) — `pngPath` must already hold
 *  `pngBytes`. */
function writeMacClipboard(pngPath: string): Promise<OsClipboardImageResult> {
  return new Promise((resolve) => {
    execFile(
      'osascript',
      ['-e', `set the clipboard to (read (POSIX file ${JSON.stringify(pngPath)}) as «class PNGf»)`],
      { timeout: 5_000 },
      (error, _stdout, stderr) => {
        resolve(error
          ? { state: 'failed', reason: (typeof stderr === 'string' && stderr.trim()) || error.message }
          : { state: 'written' })
      },
    )
  })
}

/** Running inside Windows Subsystem for Linux: WSL sets `WSL_DISTRO_NAME` for every process it
 *  starts, and its kernels name themselves `…-microsoft-standard-WSL2` for one that was not. */
export function isWsl(env: NodeJS.ProcessEnv = process.env, kernel: string = release()): boolean {
  return !!env.WSL_DISTRO_NAME || /microsoft/i.test(kernel)
}

/** Linux: which clipboard tool applies depends on the ACTIVE session, not the distro, so this is
 *  checked per-call rather than once at startup — `$WAYLAND_DISPLAY`/`$DISPLAY` reflect the
 *  session the daemon is currently running under. Neither set means no display server at all
 *  (a genuinely headless box), which no clipboard tool can fix. */
async function writeLinuxClipboard(pngBytes: Uint8Array): Promise<OsClipboardImageResult> {
  // Under WSL the Linux clipboard is WSLg's mirror of the Windows one, and WSLg syncs an image back
  // from Windows as BMP only (microsoft/wslg#833) — a PNG written here is replaced before the engine
  // reads it, and Codex/Claude Code then find no image at all (openharness#107). The path fallback
  // is the one that works there: both engines attach an image whose path is pasted.
  if (isWsl()) return { state: 'unavailable', reason: 'WSL: WSLg replaces a PNG on the clipboard with BMP' }
  if (process.env.WAYLAND_DISPLAY) {
    if (!binaryOnPath('wl-copy')) {
      return { state: 'unavailable', reason: 'wl-copy not found (install the wl-clipboard package)' }
    }
    const result = await runWithStdin('wl-copy', ['--type', 'image/png'], pngBytes)
    return result.ok ? { state: 'written' } : { state: 'failed', reason: result.message ?? 'wl-copy failed' }
  }
  if (process.env.DISPLAY) {
    if (!binaryOnPath('xclip')) {
      return { state: 'unavailable', reason: 'xclip not found (install the xclip package)' }
    }
    const result = await runWithStdin('xclip', ['-selection', 'clipboard', '-t', 'image/png', '-i'], pngBytes)
    return result.ok ? { state: 'written' } : { state: 'failed', reason: result.message ?? 'xclip failed' }
  }
  return { state: 'unavailable', reason: 'no X11 or Wayland display on this machine' }
}

/**
 * Writes `pngBytes` (already saved at `pngPath`) into this machine's native OS clipboard. Never on Windows, where the keystroke
 * replayed after it does nothing: Claude Code takes an image on Alt+V there, not Ctrl+V, and a paste said it worked and attached
 * nothing (Claude Code 2.1.318, DESKTOP-0TFH0OJ, 2026-11-04). The saved file's path, pasted as text, is an image to every engine.
 */
export async function writeImageToOsClipboard(pngPath: string, pngBytes: Uint8Array): Promise<OsClipboardImageResult> {
  if (process.platform === 'darwin') return writeMacClipboard(pngPath)
  if (process.platform === 'linux') return writeLinuxClipboard(pngBytes)
  return { state: 'unavailable', reason: `no clipboard writer for ${process.platform}` }
}