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
// The IPty-shim: makes a session-host-backed session look, to `pty-manager.ts`, exactly like the
// small subset of node-pty's `IPty` it actually touches (`onData`/`onExit`/`write`/`resize`/
// `pause`/`resume`/`kill`/`destroy` — see `Session.proc` and `ReleasablePty` in pty-manager.ts /
// pty-release.ts). This is what lets the session-host backend slot into the EXISTING
// subscriber/flow-control/co-attach machinery in `PtyManager` with no changes to any of that: as
// far as that code is concerned, `session.proc` is just a pty, however it is actually implemented.
import type { SessionHostClient, SessionSubscriber } from './session-host-client'
import type { SessionHostSpawnOptions, AttachResult } from '../session-host/protocol'
export class SessionHostPty {
readonly name: string
private readonly client: SessionHostClient
private readonly sub: SessionSubscriber
private readonly dataCbs: Array<(data: string) => void> = []
private readonly exitCbs: Array<(e: { exitCode: number }) => void> = []
private readonly attachErrorCbs: Array<(error: Error) => void> = []
private readonly sizeCbs: Array<(size: { cols: number; rows: number }) => void> = []
private attachError: Error | null = null
private detached = false
/**
* Resolves once the initial attach-or-create round trip completes, carrying exactly what the
* tmux backend gets for free from a warm reattach's own redraw: whether this was a cold start,
* and — when it wasn't — the screen to seed. `spawnNew()` awaits this to build the outer
* `PtyCreateResult` (`fresh`, `screen`) the same way `join()` already does for a same-process
* co-attach. See docs/windows-session-host.md, "The seeding trap".
*/
readonly ready: Promise<AttachResult>
constructor(
client: SessionHostClient,
name: string,
spawn: SessionHostSpawnOptions | null,
scrollback: number,
/** A read-only viewer's attachment (`SessionHostClient.attachWatch`): `spawn` must be null. Its
* writes, resizes and pauses never reach the host. */
mode: 'owner' | 'watch' = 'owner'
) {
this.client = client
this.name = name
this.sub = {
onData: (data) => {
for (const cb of this.dataCbs) cb(data)
},
onExit: (exitCode) => {
for (const cb of this.exitCbs) cb({ exitCode })
},
onSize: (size) => {
for (const cb of this.sizeCbs) cb(size)
},
onAttachError: (error) => {
this.attachError = error
for (const cb of this.attachErrorCbs) cb(error)
}
}
this.ready = spawn
? client.attach(name, spawn, scrollback, this.sub)
: mode === 'watch'
? client.attachWatch(name, this.sub)
: client.attachExisting(name, this.sub)
// node-pty's real spawn never rejects asynchronously (a spawn failure throws synchronously,
// before a Session is even constructed) — an attach failure here is the closest analogue, and
// it must not become an unhandled rejection just because some callers (write/resize/pause/
// resume) never look at `ready` at all. `spawnNew()` DOES await it and will see the failure.
this.ready.catch(() => {})
}
onData(cb: (data: string) => void): void {
this.dataCbs.push(cb)
}
onExit(cb: (e: { exitCode: number }) => void): void {
this.exitCbs.push(cb)
}
/** The size the shared pty actually runs at (issue #914). Not part of node-pty's `IPty`: a real
* pty is exactly the size it was last given, while this one follows whichever viewer of the
* session was most recently active, which may be a different process entirely. */
onSize(cb: (size: { cols: number; rows: number }) => void): void {
this.sizeCbs.push(cb)
}
/** Reconnect replay failed for a previously-confirmed generation. Late registration receives
* the stored error immediately so manager wiring cannot miss a fast rejection. */
onAttachError(cb: (error: Error) => void): void {
this.attachErrorCbs.push(cb)
if (this.attachError) cb(this.attachError)
}
write(data: string): void {
this.client.write(this.name, this.sub, data)
}
/** `bounding`: this pty's viewers cannot adapt to a grid other than their own, so the shared
* session must never grow past this claim (see `latestClaimSize`). */
resize(cols: number, rows: number, bounding = false): void {
this.client.resize(this.name, this.sub, cols, rows, bounding)
}
pause(): void {
this.client.pause(this.name, this.sub)
}
resume(): void {
this.client.resume(this.name, this.sub)
}
/**
* DETACH only — never ends the remote session. Mirrors the tmux backend exactly: there,
* `proc.kill()` kills the LOCAL tmux CLIENT process, not the tmux session it was attached to.
* The real "end this session for good" lives in `pty-manager.ts`'s `destroySession`, via
* `sessionHostBackend.killSession(name)` — the one path that maps to a real `tmux kill-session`.
*/
kill(): void {
this.detach()
}
/** `releasePty` prefers `destroy()` over `kill()` when both exist (deterministic fd close for a
* real pty) — here they are the same detach, so either is safe to call, including both. */
destroy(): void {
this.detach()
}
private detach(): void {
if (this.detached) return
this.detached = true
this.client.unsubscribe(this.name, this.sub)
}
}