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 type { LaunchClaim } from './launch-attempt'
import type { PendingLaunch } from '@shared/types'
import { deliverCommand, type DeliveryIo, type DeliveryOutcome } from '@shared/command-delivery'
// A writer belongs to the PTY lifetime (including a parked view), not a Canvas render.
// A durable write-ahead claim distinguishes a never-attempted warm launch from an uncertain
// earlier submission whose clearing autosave may have been lost.
// `'elsewhere'`: another viewer of the project claimed this launch (#1173); nothing was typed and
// nothing failed.
type LaunchOutcome = DeliveryOutcome | 'deferred' | 'elsewhere'
type Writer = (command: string, manual: boolean) => Promise<LaunchOutcome>
const defaultScope = {}
const scopedWriters = new WeakMap<object, Map<string, Writer>>()
function writersFor(scope: object): Map<string, Writer> {
let writers = scopedWriters.get(scope)
if (!writers) { writers = new Map(); scopedWriters.set(scope, writers) }
return writers
}
export function registerLaunchWriter(id: string, writer: Writer, scope: object = defaultScope): () => void {
const writers = writersFor(scope)
writers.set(id, writer)
return () => { if (writers.get(id) === writer) writers.delete(id) }
}
export function launchCommand(id: string, command: string, manual = false, scope: object = defaultScope): Promise<LaunchOutcome> {
return writersFor(scope).get(id)?.(command, manual) ?? Promise.resolve('cancelled')
}
/** Is a writer registered for `id` (its PTY is mounted, or parked with the writer alive)? */
export function hasLaunchWriter(id: string, scope: object = defaultScope): boolean {
return writersFor(scope).has(id)
}
export function createLaunchWriter(opts: {
claimAttempt(manual: boolean, command: string): Promise<LaunchClaim>
io: DeliveryIo
shellReady(manual: boolean): Promise<boolean>
killLine: string
cleanup(cancel: () => void): void
/**
* Optional direct executor, asked AFTER the claim and the ready re-check — the same exactly-once
* gates the typed line passes. `'fallback'` = it delivered nothing (not its kind of pane, or it
* refused before touching the pane) and the typed line runs as before; any other answer is the
* delivery outcome itself. Today: a local Windows session-host pane's semantic launch
* (terminal/launch-intent.ts).
*/
execute?(command: string, manual: boolean): Promise<DeliveryOutcome | 'fallback'>
}): Writer {
let attempted = false
let elsewhere = false
let submitted = false
let inFlight: Promise<LaunchOutcome> | undefined
let disposed = false
opts.cleanup(() => { disposed = true })
return (command, manual) => {
if (submitted) return Promise.resolve('submitted') // stale UI/save; never paste twice
if (inFlight) return inFlight
// Another viewer owns this launch: an automatic retry stands down again rather than reading
// as a failure. Run now (manual) still goes through, as everywhere else.
if (!manual && elsewhere && !disposed) return Promise.resolve('elsewhere')
if (disposed || (!manual && attempted)) return Promise.resolve('cancelled')
inFlight = (async () => {
if (!(await opts.shellReady(manual)) || disposed) return 'cancelled' as const
const claim = await opts.claimAttempt(manual, command)
if (claim === 'deferred' && !disposed) return 'deferred' as const
if (claim === 'elsewhere' && !disposed) {
elsewhere = true
return 'elsewhere' as const
}
if (!claim || disposed) return 'cancelled' as const
attempted = true
// Saving can take a remote round trip. Recheck after the barrier, before any input.
if (!(await opts.shellReady(manual)) || disposed) return 'cancelled' as const
if (opts.execute) {
const direct = await opts.execute(command, manual)
if (direct !== 'fallback') return direct
if (disposed) return 'cancelled' as const
}
return new Promise<DeliveryOutcome>((resolve) => {
try {
// A cancelled delivery may have left an unsubmitted prefix in the shell editor.
// Explicit recovery starts a new line rather than appending another CLI command.
if (manual) opts.io.write(opts.killLine)
opts.cleanup(deliverCommand(opts.io, command, resolve, { killLine: opts.killLine }))
} catch { resolve('cancelled') }
})
})().then((outcome) => {
submitted = outcome === 'submitted'
return outcome
}).catch(() => 'cancelled' as const).finally(() => { inFlight = undefined })
return inFlight
}
}
/** Keep UI launch intent through the asynchronous shell settle and submission boundary. */
export function deliverInitialLaunch(command: string, opts: {
pending?: PendingLaunch
whenReady(run: () => void): void
write: Writer
update(patch: {
initialCommand?: undefined
pendingLaunch?: { after: string[]; command: string; attempted: boolean; manualOnly?: boolean }
}): void
onFailure(outcome: DeliveryOutcome): void
}): void {
if (opts.pending && opts.pending.attempted !== false) {
// A park/remount can retain the live initialCommand alias while its first submission is
// still settling. Never let that alias reset the durable attempted mark.
opts.update({ initialCommand: undefined })
opts.onFailure('cancelled')
return
}
const pendingLaunch = { after: [], command, attempted: false }
// Do not discard the live initialCommand before settle. The durable pending record also
// survives a project switch. Canvas and this callback share the same in-flight writer.
opts.update({ pendingLaunch })
opts.whenReady(() => {
void opts.write(command, false).then((outcome) => {
if (outcome === 'deferred') return // no input/claim; retain never-attempted intent
if (outcome === 'elsewhere') {
// Another viewer of this project claimed and is typing it (#1173). Drop only the live
// alias; the durable record converges from that viewer over the canvas sync.
opts.update({ initialCommand: undefined })
return
}
opts.update({ initialCommand: undefined,
pendingLaunch: outcome === 'submitted' ? undefined : { ...pendingLaunch, attempted: true, manualOnly: true } })
if (outcome !== 'submitted') opts.onFailure(outcome)
})
})
}