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
// A LAUNCH PROMPT TOO BIG FOR A TYPED LINE GOES INTO A FILE INSTEAD (issue #706).
//
// `--prompt` becomes a quoted argument on a command line that is TYPED into the pane, and a
// canonical-mode tty silently discards everything past its buffer (1024 bytes on macOS — see
// @shared/canonical-line). The closing quote is what gets dropped, so the shell is left at
// `quote>` and the agent never launches. `verify` reaches that length with no user input at all:
// two of its three default lenses assemble to > 1024 bytes with a nine-character node title.
//
// The mechanism to avoid it already exists and is already the documented answer for a prompt with
// structure: `--prompt-file` (issue #520), which the assembler composes as `"$(cat '<path>')"` —
// the pane's own shell reads the file at execution, so the TYPED line stays short whatever the
// prompt weighs. All this module adds is doing it automatically for a prompt we generated.
//
// Three properties, in order of importance:
//
// 1. **It never makes things worse.** A spill that fails for any reason (no writer on this
// surface, a full disk, a relay tab) returns `null` and the caller passes the prompt inline
// exactly as before. The delivery layer's own refusal (`deliverCommand`'s `line-too-long`)
// is what stops a truncated line from being submitted in that case, so failing open here
// costs a visible refusal, never a half-run command.
// 2. **It only fires when needed.** Under the budget the caller's command line is byte-identical
// to what it has always been — no file is written for `--prompt "hello"`.
// 3. **It writes on the machine the terminals run on.** `files.saveUpload` is that seam by
// definition (it is what a clipboard paste and a browser-side drop already use), which makes
// this correct on the desktop and in the Server Edition without a branch. An SSH project's
// pane runs on the HOST, where this cannot reach — so those callers must not spill, and
// `shouldSpillPrompt` takes that as an explicit argument rather than guessing.
import { MAX_LAUNCH_LINE_BYTES, lineBytes } from '@shared/canonical-line'
import { LAUNCH_PROMPT_FILE_PREFIX } from '@shared/launch-prompt'
/**
* How many bytes of PROMPT we will put on a typed line before spilling.
*
* The rest of the line is the program, its args, the permission-mode flag, a minted `--session-id`
* and an optional `--model`. Measured against `assembleLaunchCommand` (2026-09) the worst builtin
* is claude at **122 bytes** of overhead with every one of those present; grok is 90, copilot 74,
* codex 41, gemini 35, opencode 20. The reserve is set well above the worst measured value because
* two inputs are NOT bounded by anything here — a per-builtin launch-command override (a wrapper
* script the user names in Settings) and a custom agent's `args` — and being a little eager to
* spill costs one file, while being a little short costs a truncated launch.
*
* Deliberately a budget on the prompt rather than a check on the finished command: the command is
* assembled inside `createAgentNode`, which also MINTS a session id, so it cannot be dry-run to
* measure. The finished line is still checked at delivery, which is the backstop for the cases
* this reserve does not cover.
*/
export const LAUNCH_LINE_OVERHEAD_RESERVE = 200
export const LAUNCH_PROMPT_BUDGET_BYTES = MAX_LAUNCH_LINE_BYTES - LAUNCH_LINE_OVERHEAD_RESERVE
/**
* What actually reaches the pane for an inline `--prompt`: the assembler collapses every run of
* whitespace to one space (`assembleLaunchCommand`), and the agent-facing docs promise exactly
* that. **The spilled file must hold the SAME text**, or a prompt's meaning would change with its
* length — under the budget it arrives flattened, over the budget it would arrive with its
* newlines intact. `--prompt-file` remains the way to ask for structure, and it is untouched by
* this module. Kept here rather than imported so the invariant is stated where the file is
* written.
*/
export function flattenPrompt(prompt: string): string {
return prompt.replace(/\s+/g, ' ').trim()
}
/** Would this prompt, typed inline, risk a truncated launch line? Measured on what will actually
* be typed — the flattened form, which is never longer than the original. */
export function promptExceedsLineBudget(prompt: string | undefined): boolean {
return !!prompt && lineBytes(flattenPrompt(prompt)) > LAUNCH_PROMPT_BUDGET_BYTES
}
/**
* Should this prompt be spilled to a file?
*
* `localFs` is the caller's answer to "will the pane read the filesystem `saveUpload` writes to?".
* It is FALSE for an SSH project, whose pane runs on the host — spilling there would compose a
* `cat` of a path that exists only on this machine, turning a prompt that is merely at risk of
* truncation into one that is guaranteed empty. Those callers pass the prompt inline and rely on
* the delivery refusal instead, which also means a host with a larger canonical buffer (Linux is
* 4096) keeps working exactly as it does today.
*/
export function shouldSpillPrompt(prompt: string | undefined, localFs: boolean): boolean {
return localFs && promptExceedsLineBudget(prompt)
}
export interface PromptSpillIo {
/** `window.nodeTerminal.files.saveUpload` — writes on the machine the terminals run on. */
saveUpload(name: string, dataBase64: string): Promise<string | null>
/** Injected so the module tests without a DOM. */
encodeBase64(text: string): string
}
let spillSeq = 0
/** UTF-8 → base64, which is what `saveUpload` takes. `btoa` is Latin-1 only, so the text is
* encoded to bytes first — a prompt is full of `—` and `…` and would otherwise throw. */
export function encodeUtf8Base64(text: string): string {
const bytes = new TextEncoder().encode(text)
let binary = ''
for (const b of bytes) binary += String.fromCharCode(b)
return btoa(binary)
}
/**
* Write `prompt` to a file on the machine the terminals run on and resolve its ABSOLUTE path, or
* `null` if it could not be written — in which case the caller keeps its inline prompt.
*
* Never throws: `saveUpload` is a `window.nodeTerminal` member, and a surface that stubs it
* (a relay tab) rejects rather than resolving null.
*/
export async function spillPromptToFile(
prompt: string,
io: PromptSpillIo
): Promise<string | null> {
try {
// The prefix is what makes the core keep this file out of the 7-day uploads sweep
// (@shared/launch-prompt): it is read at LAUNCH, which for a cold open can be weeks away.
const name = `${LAUNCH_PROMPT_FILE_PREFIX}${Date.now().toString(36)}-${(spillSeq++).toString(36)}.txt`
const path = await io.saveUpload(name, io.encodeBase64(flattenPrompt(prompt)))
return path || null
} catch {
return null
}
}
/**
* The prompt an open types, decided ONCE for every canvas-control open path — live, cold (the
* caller's own project, not on screen) and `--project`. Two of the three used to type the prompt
* inline whatever its length, so the docs' promise that a long `--prompt` is safe on a local
* project held only on the live one.
*
* - An explicit `--prompt-file` passes through untouched: the file is already the whole brief.
* - A prompt within budget, or any prompt for a pane that cannot read this machine's files
* (`localFs` false: an SSH project), stays inline. The delivery layer's `line-too-long` refusal is
* the backstop there.
* - Otherwise it is spilled; a spill that cannot be written keeps the prompt inline (fail open).
*/
export async function launchPromptFor(
input: { prompt?: string; promptFile?: string; localFs: boolean },
io: PromptSpillIo
): Promise<{ prompt?: string; promptFile?: string }> {
if (input.promptFile) return { promptFile: input.promptFile }
if (!shouldSpillPrompt(input.prompt, input.localFs)) return { prompt: input.prompt }
const path = await spillPromptToFile(input.prompt as string, io)
return path ? { promptFile: path } : { prompt: input.prompt }
}