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
// openRelayTab — turn an approved (or approving) relay connection into a project TAB.
//
// docs/remote-sessions.md, Stage 4 Task 6: a remote desktop is a client of the host's core, so it
// opens as an ordinary project tab (not a full-screen overlay). This is the join point that wires
// Task 5's `buildRelayApi` into the 4a session registry:
// buildRelayApi(id) → createSession('relay', api, label) → a `projects` tab bound to it → active.
//
// TWO obligations this bootstrap owns (both would silently break the tab):
// • Construction order (relay-api.ts gotcha 2): `buildRelayApi` is called FIRST — its
// `RelayFrameTransport` registers the one-shot `onApproved` listener BEFORE we await `ready()`.
// Build it after approval already fired and `ready()` stays pending forever.
// • ready() can HANG (Task 5 review): `RelayFrameTransport.ready()` resolves only on `onApproved`
// and NEVER rejects; a socket drop BEFORE the SAS is approved would leave the bootstrap awaiting
// forever — a dead tab that never errors. So we RACE `ready()` against the connection's real
// close signal (relayClient.onClosed) plus a timeout backstop, and reject on either.
import type { HostedRole, HostedSessionApi, Project, RelayClientApi } from '@shared/types'
import { buildRelayApi, type RelayApiHandle } from '../bridge/relay-api'
import { E_DISCONNECTED } from '../../shared/rpc'
import { onLocalRelayClose } from '../bridge/relay-local-close'
import { sanitizeRelayProject } from './relay-ssh'
import { wireRelayAgentStatus } from './relay-agent-status'
import { closedReasonMessage, RelayApprovalError } from '../lib/hostedTeam'
import { attachHostedOwner } from '../lib/hostedOwner'
import { useHostedTeams, type HostedTeamInfo } from '../state/hostedTeams'
import { hostedPendingSink } from '../state/hostedPending'
import {
createSession,
bindProjectToSession,
setActiveSession,
holdSessionTeardown,
disposeSession,
getSessionStores,
takeSessionOffline,
projectIdsBoundToSession,
type SessionSource,
} from './session'
/** Backstop for a `ready()` that neither approves nor closes (the network vanished without a FIN). */
const APPROVAL_TIMEOUT_MS = 60_000
export interface RelayTabDeps {
/** The preload relay surface — only `onClosed` is needed here (to catch a pre-approval drop). */
relayClient: Pick<RelayClientApi, 'onClosed'>
/** Add an EMPTY relay tab (`addRelayTab` — marked `remote`, never a plain local project) → the
* new project's id. The fallback when the host shared nothing (no scoped project) and the
* reconnect lever (Canvas overrides it to reuse the existing project id in place). */
addProject: (label: string) => { id: string }
/** Adopt the host's shared project as a tab (`useProjects.getState().adoptProject`) → fresh
* project id, node ids kept. Used on FIRST connect to populate the tab with the host's actual
* nodes. Omitted on reconnect, where the existing tab (and its nodes) is reused via `addProject`. */
adoptProject?: (project: Project) => { id: string }
/** Make the new tab active (`useProjects.getState().setActive`). */
setActiveProject: (projectId: string) => void
/** TEST SEAM: build the relay api handle. Production omits it → `buildRelayApi`. */
buildApi?: (connectionId: string) => RelayApiHandle
/** Approval-timeout backstop (default `APPROVAL_TIMEOUT_MS`). A hosted team's first join passes
* the host's own pending TTL: an owner has ten minutes to answer, not one. */
timeoutMs?: number
/** The connection was made from a hosted team's join code: build the hosted api (its `hosted`
* verbs and role gate). Absent = a Team Access relay tab, byte-identical to before. */
hosted?: boolean
/** Switch to the tab once it is live (default true). A reconnect nobody clicked (boot, a dropped
* tab coming back) binds its tab without taking the screen from whatever the user is on. */
activate?: boolean
/** HOSTED only: place the host's shared projects as tabs (one per project, reusing a reconnecting
* team's greyed tabs) and return their ids in host order — never empty (a team with nothing
* shared gets one placeholder). Absent = a Team Access tab: `projects[0]` exactly as before. */
placeProjects?: (projects: Project[]) => string[]
/** Activate this tab when it is among the placed ones (the one the user just shared). */
focusProjectId?: string
}
export interface RelayTab {
sessionId: string
/** The tab activated on open: the focused one, else the first placed. */
projectId: string
/** Every tab this connection serves (one for a Team Access tab, one per shared project for a
* hosted team), in the host's order. */
projectIds: string[]
/** A hosted team's tab: this device's role there and the team's name. Absent otherwise. */
hosted?: HostedTeamInfo
/** Tear the tab's session down (runs the held presence teardown + relay socket close, once). */
dispose(): void
}
const ROLES: readonly HostedRole[] = ['owner', 'editor', 'commenter', 'viewer']
/**
* Ask a hosted host which role this device has, and publish it to the api's role gate BEFORE
* anything mounts (nothing but this request has been sent yet). An answer that cannot be read is the
* LOWEST role: the host enforces the real one either way, and the direction a wrong guess must err
* in is "shows less", never "sends what will be refused".
*/
async function learnHostedRole(hosted: HostedSessionApi, handle: RelayApiHandle, label: string): Promise<HostedTeamInfo> {
const self = await hosted.self().catch((err: unknown) => {
// The connection itself is gone (closed from either side): there is no tab to open — never a
// Viewer guess over a dead socket (R41).
if ((err as { code?: unknown } | null)?.code === E_DISCONNECTED) throw err
return null
})
const role: HostedRole = self && ROLES.includes(self.role) ? self.role : 'viewer'
handle.setHostedRole?.(role)
const hostLabel = self && typeof self.hostLabel === 'string' ? self.hostLabel.trim() : ''
return { role, teamLabel: hostLabel || label }
}
/**
* Bootstrap a relay project tab. Resolves once the connection is mutually approved and the tab is
* live; REJECTS (never hangs) if the socket drops or times out before approval.
*/
export async function openRelayTab(
connectionId: string,
label: string,
deps: RelayTabDeps
): Promise<RelayTab> {
const build = deps.buildApi ?? ((id: string) => buildRelayApi(id, undefined, deps.hosted ? { hosted: true } : undefined))
// Built BEFORE we await ready() so the one-shot onApproved listener is registered in time.
const handle = build(connectionId)
let hostedInfo: HostedTeamInfo | undefined
try {
await raceApproval(handle, connectionId, deps)
// A hosted team's tab learns its role before its session exists, so nothing a component sends
// on mount is sent under the wrong one (see bridge/hosted-gate.ts).
if (handle.api.hosted) hostedInfo = await learnHostedRole(handle.api.hosted, handle, label)
} catch (err) {
handle.close() // tear the dead/stuck relay socket down before surfacing the failure
throw err
}
const session = createSession('relay', handle.api, label)
if (hostedInfo) useHostedTeams.getState().set(session.id, hostedInfo)
// The teardowns the tab owes on disconnect (obligation 1): the presence subscription this session
// just opened, its agent-status subscription, and the relay socket. All run exactly once, in
// disposeSession or takeSessionOffline.
holdSessionTeardown(session.id, getSessionStores(session.id).presence.connect())
// The host's agent status, into THIS session's own store (bug D) — subscribed by this session's
// api, never through a project lookup (two sessions may serve one project id). Before any await,
// so the RpcClient's early buffer flushes into it.
holdSessionTeardown(session.id, wireRelayAgentStatus(handle.api, getSessionStores(session.id).agentStatus))
holdSessionTeardown(session.id, () => handle.close())
// Populate the tab from the host's workspace, which the relay boundary already SCOPED to the one
// shared project (Task 2). Adopt that single project — fresh project id, node ids kept — so the
// Canvas active-project effect loads the host's nodes and the SessionProvider routes their
// transport to the relay api; Stage-3 sync then keeps it live. If the host shared nothing (or the
// project was deleted), OR we're reconnecting (no `adoptProject` dep — the existing tab is reused),
// fall back to the labelled tab so it still opens rather than throwing.
// A hosted team shares several projects through one connection: `placeProjects` turns each into
// its own tab (id = the host's project id, since the relay api translates no ids), and every one
// of them is bound to this session.
// The load runs AFTER createSession + the held teardowns, so a host that vanishes between approval
// and load would leave the SESSIONS entry, its presence subscription (the peer lingers in host
// facepiles) and the relay socket all leaking. Dispose the just-created session before rethrowing
// — `disposeSession` runs the held teardowns exactly once (idempotent).
try {
const ws = await handle.api.workspace.load()
let projectIds: string[]
if (deps.placeProjects) {
projectIds = deps.placeProjects(ws.projects.map(sanitizeRelayProject))
} else {
const hostProject = ws.projects[0]
projectIds = [
hostProject && deps.adoptProject
? deps.adoptProject(sanitizeRelayProject(hostProject)).id
: deps.addProject(label).id
]
}
if (projectIds.length === 0) projectIds = [deps.addProject(label).id]
for (const id of projectIds) bindProjectToSession(id, session.id)
const projectId =
deps.focusProjectId && projectIds.includes(deps.focusProjectId) ? deps.focusProjectId : projectIds[0]
if (deps.activate !== false) {
setActiveSession(session.id)
deps.setActiveProject(projectId)
}
// An OWNER answers the devices asking to join. Its subscription (and its queued requests) go
// with the session: a drop or a close runs this teardown, a reconnect subscribes and pulls anew.
if (hostedInfo?.role === 'owner' && handle.api.hosted) {
holdSessionTeardown(
session.id,
attachHostedOwner(handle.api.hosted, { projectId, teamLabel: hostedInfo.teamLabel }, hostedPendingSink)
)
}
return {
sessionId: session.id,
projectId,
projectIds,
...(hostedInfo ? { hosted: hostedInfo } : {}),
dispose: () => disposeSession(session.id),
}
} catch (err) {
disposeSession(session.id)
if (hostedInfo) useHostedTeams.getState().forget(session.id)
throw err
}
}
// ── Stage 4 Task 7: offline "unavailable" tab + reconnect ────────────────────────────────────────
//
// A relay tab is a connection BOOKMARK, not a workspace on the peer's disk (docs/remote-sessions.md
// "Persistence"). So an involuntary socket drop must NOT vanish the tab — it greys to "unavailable"
// (reusing the workspace-index rendering) and reconnects on click. This is DISTINCT from a
// user-initiated close (`RelayTab.dispose` → `disposeSession`, which drops the tab): closing by hand
// is deliberate destruction; a dropped socket is a temporary outage the host's tmux survives.
export interface RelayDropDeps {
/** Grey the tab without dropping it (`useProjects.getState().setProjectUnavailable`). */
setProjectUnavailable(projectId: string, unavailable: boolean): void
}
/** Handle an INVOLUNTARY relay socket drop (host/relay gone): take the session offline — its
* presence teardown runs ONCE so the peer leaves every facepile, the already-dead socket close
* no-ops — but KEEP the project tab and its 'relay' binding so it greys to "unavailable" and can
* reconnect in place. NEVER removes the project (that is only a user close). Idempotent. */
export function handleRelayDrop(tab: RelayTab, deps: RelayDropDeps): void {
takeSessionOffline(tab.sessionId)
// Every tab the connection served greys, so each one can reconnect in place: the ones placed at
// mount and any a share event bound to the session since (bindings survive going offline).
const ids = new Set([...tab.projectIds, ...projectIdsBoundToSession(tab.sessionId)])
for (const id of ids) deps.setProjectUnavailable(id, true)
}
export interface RelayReconnectDeps {
/** Prompt the human for a FRESH pairing code. The relay offer carries a SINGLE-USE token
* (main/remote/pairing.ts), so v1 has no silent/pinned reconnect — the host must mint a new
* offer. Returns null when cancelled. */
promptForOffer(): Promise<string | null>
/** `relayClient.connect` — resolves a fresh connectionId. */
connect(offer: string): Promise<string>
/** Confirm the SAS + mount the fresh connection onto the EXISTING project id (reuses the tab —
* never a duplicate). Disposes the stale offline session only after the fresh one rebinds, and
* clears `unavailable` once the tab is live again. */
mount(connectionId: string, projectId: string): void
onError(message: string): void
}
/** Reconnect an offline relay tab IN PLACE — same project id, so no duplicate tab is spawned. v1:
* the offer is single-use, so this prompts for a FRESH pairing code, connects, and mounts onto the
* existing tab. Cancelling the prompt reconnects nothing.
*
* The stale offline session is NOT torn down here: `mount` disposes it only once the fresh session
* has rebound the project (see Canvas `mountRemoteMirror`). Disposing it up-front would unbind the
* project before anything replaced the binding, so a connect failure or a declined SAS would leave
* the tab with no session of its own. It would still be reconnectable (an unbound remote tab
* resolves to the offline relay session, a relay source), but its own session (label, status
* stores) would be gone and `boundSessionForProject` would find nothing for the next reconnect to
* hand over. Keeping the binding until the fresh one lands leaves a failed reconnect exactly where
* it started. */
export async function reconnectRelayTab(projectId: string, deps: RelayReconnectDeps): Promise<void> {
const offer = (await deps.promptForOffer())?.trim()
if (!offer) return
try {
const connectionId = await deps.connect(offer)
deps.mount(connectionId, projectId)
} catch (err) {
deps.onError(err instanceof Error ? err.message : String(err))
}
}
/** Which behavior a tab click gets. An available tab switches. An unavailable tab distinguishes by
* its bound session SOURCE: a relay/server drop is clickable-to-reconnect; a local unavailable tab
* is a missing folder — inert (there is nothing to reconnect to). */
export function tabClickAction(
unavailable: boolean,
source: SessionSource
): 'switch' | 'reconnect' | 'ignore' {
if (!unavailable) return 'switch'
return source === 'local' ? 'ignore' : 'reconnect'
}
/** Resolve on approval (`handle.ready()`); reject on a pre-approval socket drop or a timeout. */
function raceApproval(
handle: RelayApiHandle,
connectionId: string,
deps: RelayTabDeps
): Promise<void> {
return new Promise<void>((resolve, reject) => {
let settled = false
let unClose: () => void = () => {}
let unLocal: () => void = () => {}
let timer: ReturnType<typeof setTimeout> | null = null
const finish = (fn: () => void) => {
if (settled) return
settled = true
unClose()
unLocal()
if (timer) clearTimeout(timer)
fn()
}
// A hosted connection this renderer closed itself (the SAS was declined) is closed NOW: main
// never reports it, and the approval wait would otherwise run its full ten minutes.
if (handle.api.hosted) {
unLocal = onLocalRelayClose(connectionId, () =>
finish(() => reject(new RelayApprovalError('The relay connection closed before it was approved.')))
)
}
// A hosted host may say WHY before it closes (an owner declined, nobody answered); a close
// without a reason keeps the old sentence exactly.
unClose = deps.relayClient.onClosed(connectionId, (reason) =>
finish(() =>
reject(
new RelayApprovalError(
closedReasonMessage(reason) ?? 'The relay connection closed before it was approved.',
reason
)
)
)
)
timer = setTimeout(
() =>
finish(() =>
reject(
new Error(
handle.api.hosted
? (closedReasonMessage('expired') as string)
: 'Timed out waiting for the host to approve.'
)
)
),
deps.timeoutMs ?? APPROVAL_TIMEOUT_MS
)
handle.ready().then(
() => finish(resolve),
(err) => finish(() => reject(err instanceof Error ? err : new Error(String(err))))
)
})
}