Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
// Shared terminal file-drop/paste logic — used by both the canvas TerminalNode and the kanban card
// modal's co-attach terminal (ModalTerminal), so a file dropped onto or pasted into either becomes
// a path the same way.
/** Backslash-escape shell-special characters, like a native terminal does on file drop. */
export function escapeDroppedPath(p: string): string {
return p.replace(/([ \t"'`\\()&;|<>$!*?[\]{}#~])/g, '\\$1')
}
/**
* How a dropped path is spelled for the program reading the pane.
*
* - `posix`: backslash-escape (`escapeDroppedPath`) — zsh/bash/fish and the agent CLIs on
* macOS/Linux, every SSH host, and Git Bash on Windows. Byte-identical to the pre-dialect output.
* - `win-cmd` / `win-pwsh`: a Windows path, where `\` IS the separator and must never be doubled.
* Bare when nothing in it needs quoting, else double-quoted — what Windows Terminal and Explorer
* write on a drag-drop, and what cmd, PowerShell and the Windows agent CLIs read as one token.
* `win-pwsh` single-quotes (doubling `'`) a path holding `$` or a backtick, because PowerShell
* expands both inside double quotes. cmd cannot quote `%` at the prompt at all; a `%` filename
* is accepted as a known miss (vanishingly rare, and no spelling would fix it).
*/
export type DropDialect = 'posix' | 'win-cmd' | 'win-pwsh'
const WIN_BARE = /^[A-Za-z0-9_\-.:\\/]+$/
export function quoteDroppedPath(p: string, dialect: DropDialect = 'posix'): string {
if (dialect === 'posix') return escapeDroppedPath(p)
if (WIN_BARE.test(p)) return p
if (dialect === 'win-pwsh' && /[$`]/.test(p)) return `'${p.replace(/'/g, "''")}'`
return `"${p}"`
}
export interface DropDialectFacts {
/** `process.platform` reported by the core that owns the pane; null = not observed (yet). */
corePlatform: string | null
/** The pane runs on another (POSIX) machine: an SSH project, or a standalone `ssh` node. */
remote: boolean
/** The node's shell, or the resolved default. Unknown reads as PowerShell — the core's own
* Windows default. */
shell?: string | null
/** An agent CLI owns the pane, so the reader is its composer, not the shell. */
agentPane?: boolean
/** Fallback when `corePlatform` is null — the SAME rule `terminalKillLine` applies: the viewer's
* OS stands in only for the desktop's own local core, never for a Server Edition/relay tab. */
localDesktop?: boolean
viewerWindows?: boolean
}
/** Which `DropDialect` a pane reads. Anything that is not provably a Windows core is `posix`, so
* every macOS/Linux/SSH drop is spelled exactly as before. */
export function dropDialect(f: DropDialectFacts): DropDialect {
if (f.remote) return 'posix'
const platform = f.corePlatform ?? (f.localDesktop && f.viewerWindows ? 'win32' : null)
if (platform !== 'win32') return 'posix'
// Agent composers take a double-quoted path; `$`/backtick get pwsh's single quotes, which the
// CLIs read as quoting too.
if (f.agentPane) return 'win-pwsh'
const exe = (f.shell ?? '').split(/[\\/]/).pop()?.toLowerCase().replace(/\.exe$/, '') ?? ''
if (exe === 'pwsh' || exe === 'powershell') return 'win-pwsh'
// Git Bash / MSYS / WSL bash read backslash escapes; `C:\\Users\\Jane\ Doe` is right there.
if (exe === 'bash' || exe === 'sh' || exe === 'zsh' || exe === 'fish' || exe === 'wsl') return 'posix'
if (exe === 'cmd') return 'win-cmd'
// No shell configured (or one we do not recognise): the core's own Windows default is PowerShell
// (`resolveWindowsShell`: pwsh, then the powershell.exe every install ships; COMSPEC only after
// both), so spell it for PowerShell. The two dialects differ only for a `$`/backtick path, which
// double quotes would let PowerShell expand into a different path.
return 'win-pwsh'
}
/** Extension for a clipboard blob that arrives with no filename, keyed off its MIME type. A
* screenshot is `image/png` with an empty `name`, and an agent asked to look at `pasted-<ts>`
* with no suffix has to guess what it is holding. */
const EXT_BY_TYPE: Record<string, string> = {
'image/png': 'png',
'image/jpeg': 'jpg',
'image/gif': 'gif',
'image/webp': 'webp',
'image/svg+xml': 'svg',
'image/bmp': 'bmp',
'image/tiff': 'tiff',
'application/pdf': 'pdf',
'text/plain': 'txt'
}
const CANVAS_IMAGE_EXTENSIONS = new Set([
'png',
'jpg',
'jpeg',
'gif',
'webp',
'bmp',
'ico',
'svg',
'avif'
])
const CANVAS_IMAGE_MIME = new Set([
'image/png',
'image/jpeg',
'image/gif',
'image/webp',
'image/bmp',
'image/x-icon',
'image/svg+xml',
'image/avif'
])
/** Only image files become canvas preview nodes; other dropped files keep the existing no-op. */
export function canvasImageFiles(files: File[]): File[] {
return files.filter((file) => {
if (CANVAS_IMAGE_MIME.has(file.type.toLowerCase())) return true
const ext = file.name.split('.').pop()?.toLowerCase() ?? ''
return CANVAS_IMAGE_EXTENSIONS.has(ext)
})
}
/** The name to store a file under. Clipboard bytes usually have none, so one is generated from
* the MIME type + a timestamp — recognizable in a prompt and unique enough to read back. */
export function uploadNameFor(file: { name: string; type: string }): string {
if (file.name) return file.name
const ext = EXT_BY_TYPE[file.type] ?? (file.type.split('/')[1] || 'bin')
const stamp = new Date()
.toISOString()
.replace(/[-:]/g, '')
.replace(/\..+$/, '')
.replace('T', '-')
return `pasted-${stamp}.${ext}`
}
/** Files carried by a paste. Chromium exposes an OS file-manager copy on `files`, and raw
* clipboard bytes (a screenshot) as an `items` entry of kind 'file' — read both, since a paste
* that carries neither must fall through to xterm as ordinary text. */
export function pastedFiles(dt: DataTransfer | null): File[] {
if (!dt) return []
const files = Array.from(dt.files)
if (files.length) return files
return Array.from(dt.items)
.filter((it) => it.kind === 'file')
.map((it) => it.getAsFile())
.filter((f): f is File => !!f)
}
/** True when the paste carried text. That text is xterm's to handle — and its ABSENCE, on a paste
* that carried no files either, is the signature of the filtered clipboard `clipboardImages`
* exists for. */
export function pasteHasText(dt: DataTransfer | null): boolean {
return !!dt && !!dt.getData('text/plain')
}
/**
* Images that are ON the clipboard but that the paste event refused to hand over.
*
* Chromium fills `clipboardData` only with formats the paste TARGET can hold, and the element
* holding focus inside a terminal node is xterm's helper `<textarea>` — text, and nothing else. A
* clipboard carrying just a screenshot has no text flavour to survive that filter, so the handler
* is handed an EMPTY `clipboardData` (files 0, items []) and the paste looks like it did nothing.
* Observed on Chrome/Windows against the Server Edition; it is why apps that accept pasted images
* focus a `contenteditable` rather than a textarea.
*
* The async Clipboard API is not filtered by the focused element, so ask it directly. It needs a
* secure context and the `clipboard-read` permission (granted once per origin, prompted on first
* use); a browser without either, or a user who declines, resolves to [] and the paste stays the
* no-op it already was. Never throws — same fail-open contract as the rest of this module.
*/
export async function clipboardImages(): Promise<File[]> {
try {
if (!navigator.clipboard?.read) return []
const out: File[] = []
for (const item of await navigator.clipboard.read()) {
const type = item.types.find((t) => t.startsWith('image/'))
if (!type) continue
const blob = await item.getType(type)
// Named here rather than left to `localPathFor`: the upload overlay prints this name, and
// the clipboard hands over a bare Blob with none.
out.push(new File([blob], uploadNameFor({ name: '', type }), { type }))
}
return out
} catch {
return []
}
}
export const readAsBase64 = (file: File): Promise<string | null> =>
new Promise((resolve) => {
const reader = new FileReader()
reader.onerror = () => resolve(null)
reader.onload = () => {
const res = typeof reader.result === 'string' ? reader.result : ''
const comma = res.indexOf(',')
resolve(comma >= 0 ? res.slice(comma + 1) : null)
}
reader.readAsDataURL(file)
})
/**
* The file's path ON THE MACHINE THE TERMINAL RUNS ON.
*
* A desktop drag-drop already has one (Electron can name the OS file), and using it copies
* nothing. Everything else has bytes and no usable path — clipboard images have never been a file
* anywhere, and a browser client's file lives on a different machine entirely — so the bytes are
* written into the managed uploads dir over there and THAT path is what the terminal gets.
*/
/**
* Where bytes with no usable path get written. The default is the managed uploads staging area,
* which is right for a terminal paste — the path is consumed within seconds. A CANVAS image is
* remembered in project.json instead, so it passes a sink that writes somewhere equally durable
* (`canvasImageSink`); the choice belongs to the caller because only it knows how long the path
* has to stay true.
*/
export type UploadSink = (name: string, dataBase64: string) => Promise<string | null>
const uploadsSink: UploadSink = (name, data) => window.nodeTerminal.files.saveUpload(name, data)
/** Store into the project's own `.nodeterm/images/` — see core/canvas-images.ts for the fallbacks
* (SSH project / relay tab / cwd-less canvas all land in a durable app-local folder instead). */
export const canvasImageSink =
(projectId: string): UploadSink =>
(name, data) =>
window.nodeTerminal.files.saveCanvasImage(projectId, name, data)
async function localPathFor(file: File, sink: UploadSink): Promise<string | null> {
const direct = window.nodeTerminal.getPathForFile(file)
if (direct) return direct
const data = await readAsBase64(file)
if (!data) return null
return sink(uploadNameFor(file), data).catch(() => null)
}
async function localFilesWithPaths(
files: File[],
sink: UploadSink
): Promise<Array<{ file: File; path: string }>> {
const local = await Promise.all(files.map((f) => localPathFor(f, sink).catch(() => null)))
return files
.map((file, i) => ({ file, path: local[i] }))
.filter((pair): pair is { file: File; path: string } => !!pair.path)
}
/** Resolve local/clipboard/browser files to raw local paths for non-terminal consumers. `sink` is
* required: only the caller knows how long the returned path has to stay true, and defaulting it
* to the 7-day staging area is exactly the wrong answer for the one caller there is. */
export async function localPathsForFiles(files: File[], sink: UploadSink): Promise<string[]> {
return (await localFilesWithPaths(files, sink)).map((pair) => pair.path)
}
/**
* Resolve dropped/pasted files to terminal-pasteable paths. For an SSH-project terminal a local
* path is useless on the host, so each file is uploaded over the project's ControlMaster and its
* REMOTE absolute path is returned (always POSIX-escaped — the host is POSIX whatever `dialect`
* says); for a local terminal the local path is used, spelled for `dialect` (default `posix`).
* Fail-open: files that can't be resolved/uploaded are dropped from the result (never throws).
*/
export async function droppedPaths(
files: File[],
opts: { sshRemoteTmux: boolean; projectId: string; dialect?: DropDialect }
): Promise<string[]> {
const pairs = await localFilesWithPaths(files, uploadsSink)
if (!opts.sshRemoteTmux) return pairs.map((p) => quoteDroppedPath(p.path, opts.dialect))
const uploaded = await Promise.all(
pairs.map((p) =>
window.nodeTerminal.sshProject
.uploadFile(opts.projectId, p.path, uploadNameFor(p.file))
.catch(() => null)
)
)
return uploaded.filter((p): p is string => !!p).map(escapeDroppedPath)
}