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
// Every way this desktop (re)joins a hosted team, over ONE attempt owner per team (hostedAttempts.ts):
// - boot: each APPROVED bookmark reconnects on its own, in the background;
// - a drop: a live hosted tab whose connection dropped (no host reason) reconnects in place, in the
// background, while its team is still bookmarked and approved and the tab is still open;
// - a click on the greyed tab: reconnects in place now (no pairing-code prompt — the bookmark is the
// credential) — unless the team was forgotten since, and then it asks for a code;
// - a pasted join code: joins now, into the team's own tab when it has one, and is told why if it
// cannot;
// - the share flow (`joinApproved`): a team this desktop just set up itself joins now, retrying
// while its relay comes up, with no SAS (its bookmark is pre-approved);
// - forgetting a team: stops its loop and removes its bookmark (the host is not touched);
// - closing or deleting a tab: its team's attempt stops, in any phase (R40) — unless the team has
// other tabs open (one connection serves one tab per shared project): then the attempt moves to
// one of those (`tabRemoved`), and tabs a share event opens later join the team (`tabsAdded`).
// And what the user is told for each: one sentence per stop, nothing for a retry in progress, one
// notice when the quick retries of a drop run out, a "remove and rejoin" offer after a revocation,
// and "waiting for an owner" whenever a mount is still unapproved after a moment. Pure over
// injected deps (no React, no window).
// See docs/hosted-team-relay.md.
import type { RelayClosedReason, RelayHostedApi } from '@shared/types'
import { peekJoinCode } from '@shared/relay-join-code'
import { createHostedAttempts, type HostedAttemptRequest, type HostedMountResult } from './hostedAttempts'
import {
closedReasonMessage,
joinStopMessage,
mountFailureMessage,
mountFailureRetries,
stripIpcPrefix,
THROTTLED_NOTICE,
waitingForOwnerText
} from './hostedTeam'
/** How long a hosted mount waits for approval before it says it is waiting for an owner. A
* bookmarked reconnect is normally approved well inside this, so it never flashes the notice; one
* whose device the host no longer knows waits for an owner like a first join (R40). */
export const WAITING_NOTICE_DELAY_MS = 2500
/** Said when a hosted team's invite code is pasted into a Team Access tab's reconnect prompt. */
export const HOSTED_CODE_IN_TEAM_ACCESS_TAB =
'That is a hosted team invite code — paste it with New Remote Connection to open the team in its own tab.'
/** How a mount ended, as the canvas reports it: live tabs, or the error it failed with. `declined`
* = this user declined the SAS themselves (nothing to tell them). `projectIds` = every tab the one
* connection serves (one per project the team shares); `projectId` is the one it activated. */
export type HostedMountOutcome = { projectId: string; projectIds?: string[] } | { error: unknown; declined: boolean }
export interface HostedNotice {
kind: 'info' | 'error'
text: string
/** Stays until cleared (the waiting-for-an-owner notice). */
sticky?: boolean
action?: { label: string; run: () => void }
}
export interface HostedJoinerDeps {
/** `relayClient.connect` — a join code in, a connection id out (or main's `[E_JOIN_…]` refusal). */
connect(code: string): Promise<string>
onClosed(connectionId: string, listener: (reason?: RelayClosedReason) => void): () => void
/** Both humans approved this connection (`relayClient.onApproved`). */
onApproved(connectionId: string, listener: () => void): () => void
/** This connection's SAS arrived, i.e. a comparison prompt is about to show (`relayClient.onSas`). */
onSas(connectionId: string, listener: () => void): () => void
/** Close a connection this joiner no longer wants (it must also count as closed locally). */
disconnect(connectionId: string): void
bookmarks: RelayHostedApi['bookmarks']
removeBookmark: RelayHostedApi['removeBookmark']
/** The SAS (a first join), the owner's approval, the tab. Never rejects on purpose; a rejection
* is read as a failure with that error. `hooks.sasConfirmed` is called once this user confirmed
* the SAS (only a connection that asked for one). */
mount(connectionId: string, req: HostedAttemptRequest, hooks: { sasConfirmed(): void }): Promise<HostedMountOutcome>
/** Is this project still an open tab (not closed, not deleted)? */
tabOpen(projectId: string): boolean
notify(notice: HostedNotice): void
/** Take down the notice with this text, if it is still the one showing. */
clearNotice(text: string): void
/** Ask the user for a fresh invite code for `teamLabel`; null = cancelled. */
promptForCode(teamLabel: string): Promise<string | null>
setTimer(fn: () => void, ms: number): unknown
clearTimer(handle: unknown): void
}
export interface HostedJoiner {
/** A join code the user pasted: joins now, never loops. `reconnectProjectId` = it was pasted
* into a greyed tab's reconnect prompt, so that tab is the one it reconnects. */
joinWithCode(code: string, reconnectProjectId?: string): void
/** A greyed tab was clicked. False when it is not a hosted tab this joiner opened (the caller
* takes its pairing-code path). */
reconnectTab(projectId: string): boolean
isHostedTab(projectId: string): boolean
/** The user closed or deleted this tab: its team's attempt stops now, in any phase (R40). */
tabClosed(projectId: string): void
/** One of a team's tabs went away while `successorId`, another of its tabs, stays open (the user
* closed it, or the host stopped sharing it): the team's attempt follows the successor, so the
* connection lives on and a drop reconnects into a tab that is still there. */
tabRemoved(projectId: string, successorId: string): void
/** A share event opened `projectIds` as more tabs of `hostId`'s live connection: they reconnect
* like the team's other tabs. A no-op for a team this joiner holds no tab for. */
tabsAdded(hostId: string, projectIds: string[]): void
/** Join a team this desktop just set up itself (its bookmark is already approved): retries a
* network failure like an unattended reconnect, confirms on its own (no SAS prompt), and
* activates `focusProjectId` when the mount places it. `busy` = that team already has an
* attempt or a live connection, and the user was told. */
joinApproved(code: string, opts?: { focusProjectId?: string }): 'started' | 'busy'
/** Reconnect every approved bookmark (once, at boot). */
bootReconnect(): Promise<void>
/** Forget a team: its loop stops and its bookmark goes. Refused while it is connecting. */
forget(hostId: string, label: string): Promise<void>
/** Is this team connecting or waiting for the host right now? */
connecting(hostId: string): boolean
dispose(): void
}
const team = (label: string): string => label.trim() || 'the team'
export function createHostedJoiner(deps: HostedJoinerDeps): HostedJoiner {
/** The team each hosted tab this joiner opened belongs to, by project id. `forgotten` = the user
* forgot that team since: the tab asks for a code rather than rejoin with the stored one (which
* would mint a fresh device token and bring the bookmark back). */
const tabs = new Map<string, { hostId: string; code: string; label: string; forgotten?: boolean }>()
let run: (req: HostedAttemptRequest) => 'started' | 'busy' = () => 'busy'
/** A reconnect is wanted only while the tab it reconnects is still open (R40). */
const tabWanted = (req: HostedAttemptRequest): boolean => !req.reconnectProjectId || deps.tabOpen(req.reconnectProjectId)
/** An open tab this joiner opened for `hostId`, if any. */
const tabFor = (hostId: string): string | undefined => {
for (const [projectId, t] of tabs) if (t.hostId === hostId && deps.tabOpen(projectId)) return projectId
return undefined
}
const markForgotten = (hostId: string): void => {
for (const [projectId, t] of tabs) if (t.hostId === hostId) tabs.set(projectId, { ...t, forgotten: true })
}
const attempts = createHostedAttempts({
connect: deps.connect,
onClosed: deps.onClosed,
disconnect: deps.disconnect,
setTimer: deps.setTimer,
clearTimer: deps.clearTimer,
wanted: tabWanted,
throttled() {
deps.notify({ kind: 'info', text: THROTTLED_NOTICE })
},
exhausted(req) {
deps.notify({
kind: 'error',
text: req.reconnectProjectId
? `Couldn't reconnect to ${team(req.label)}. Click its tab to try again.`
: `Couldn't reconnect to ${team(req.label)}. Paste its invite code to try again.`
})
},
async mount(connectionId, req): Promise<HostedMountResult> {
// Any hosted mount still waiting for approval after a moment says so — a first join and a
// bookmarked reconnect alike (the host may no longer know this device and ask an owner). The
// clock starts when there is nothing left for THIS user to do: once they confirmed the SAS
// (a first join), or once the connection exists (a bookmarked reconnect, which confirms on
// its own). Never before a SAS prompt: a comparison that shows up disarms it (R41).
const waiting = waitingForOwnerText(req.label)
let approved = false
let shown = false
let waitTimer: unknown = null
const disarm = (): void => {
if (waitTimer !== null) deps.clearTimer(waitTimer)
waitTimer = null
if (shown) {
shown = false
deps.clearNotice(waiting)
}
}
const arm = (): void => {
disarm()
if (approved) return
waitTimer = deps.setTimer(() => {
waitTimer = null
if (approved) return
shown = true
deps.notify({ kind: 'info', text: waiting, sticky: true })
}, WAITING_NOTICE_DELAY_MS)
}
const unApproved = deps.onApproved(connectionId, () => {
approved = true
disarm()
})
let sasSeen = false
let settled = false
const unSas = deps.onSas(connectionId, () => {
sasSeen = true
disarm()
})
if (req.autoConfirm) arm()
else {
// A PASTED code for a team this device holds an APPROVED bookmark for: main confirms that
// join on its own (the bookmark's approval, for the same host key — a hostId derives from
// it), so no SAS prompt comes and `sasConfirmed` never fires. Arm when the lookup answers —
// unless a SAS showed up first (the host asked for a comparison after all) or the mount has
// already settled.
void deps.bookmarks().then(
(list) => {
if (!settled && !sasSeen && list.some((b) => b.hostId === req.hostId && b.approved)) arm()
},
() => {}
)
}
let outcome: HostedMountOutcome
try {
outcome = await deps.mount(connectionId, req, { sasConfirmed: arm })
} catch (error) {
outcome = { error, declined: false }
} finally {
settled = true
unApproved()
unSas()
disarm()
}
if ('projectId' in outcome) {
// One connection serves every tab the team shares: each one reconnects from this team.
for (const id of outcome.projectIds ?? [outcome.projectId]) {
tabs.set(id, { hostId: req.hostId, code: req.code, label: req.label })
}
return { projectId: outcome.projectId, projectIds: outcome.projectIds }
}
// Declined by this user, or its tab was closed meanwhile (closed for it): nothing to say.
if (outcome.declined || !tabWanted(req)) return { retry: false }
const retry = mountFailureRetries(outcome.error)
// An unattended attempt that will try again says nothing; the next one may well work.
if (retry && req.retry) return { retry: true }
deps.notify({ kind: 'error', text: mountFailureMessage(outcome.error, req.label) })
return { retry: false }
},
stopped(req, failure) {
const text = joinStopMessage(failure, req.label)
if (!text) return
if (failure.code === 'E_JOIN_REVOKED') {
deps.notify({ kind: 'error', text, action: { label: 'Remove and rejoin', run: () => void removeAndRejoin(req) } })
return
}
deps.notify({ kind: 'error', text })
},
ended(req, projectId, reason) {
const said = closedReasonMessage(reason)
if (said) {
deps.notify({ kind: 'error', text: `${team(req.label)}: ${said}` })
return
}
// A drop. Come back in place, unattended — but only for a tab still open, on a team still
// bookmarked and approved (a forgotten team, or one whose approval was withdrawn, waits for
// the user; an approved bookmark reconnects with no SAS on this side).
if (!deps.tabOpen(projectId)) return
void deps.bookmarks().then(
(list) => {
const b = list.find((x) => x.hostId === req.hostId)
if (!b?.approved || !deps.tabOpen(projectId)) return
run({ hostId: b.hostId, code: b.code, label: b.label, manual: false, retry: true, reconnectProjectId: projectId, afterDrop: true, autoConfirm: true })
},
() => {}
)
}
})
run = (req) => attempts.run(req)
const busyText = (hostId: string, label: string): string =>
attempts.phase(hostId) === 'live' ? `You're already connected to ${team(label)}.` : `Already connecting to ${team(label)}…`
async function removeAndRejoin(req: HostedAttemptRequest): Promise<void> {
// The bookmark still holds the revoked token: offering it again would only be refused again.
try {
await deps.removeBookmark(req.hostId)
} catch (err) {
deps.notify({ kind: 'error', text: `Could not forget ${team(req.label)}: ${stripIpcPrefix(err instanceof Error ? err.message : String(err))}` })
return
}
// Gone from this device now, whether or not a fresh code follows: its tab asks for one.
markForgotten(req.hostId)
const code = (await deps.promptForCode(req.label))?.trim()
if (code) joiner.joinWithCode(code, req.reconnectProjectId)
}
const joiner: HostedJoiner = {
joinWithCode(raw, reconnectProjectId) {
const code = raw.trim()
const peek = peekJoinCode(code)
// A code pasted into a hosted tab's own reconnect prompt reconnects THAT team only. A code for
// another team would mount that team inside this tab, under this tab's name: refuse, and say
// where it goes instead. (An unreadable code is main's to answer, below.)
const tab = reconnectProjectId ? tabs.get(reconnectProjectId) : undefined
// A tab this joiner did not open is a Team Access tab: a hosted tab reconnects from its
// bookmark and never reaches the pairing prompt. Rebinding it would mount the team there,
// under that tab's name, with no team to check the code against. Refuse, readable or not.
if (reconnectProjectId && !tab) {
deps.notify({ kind: 'error', text: HOSTED_CODE_IN_TEAM_ACCESS_TAB })
return
}
if (tab && peek && peek.hostId !== tab.hostId) {
const mine = team(tab.label)
const theirs = peek.label.trim()
deps.notify({
kind: 'error',
text:
theirs && theirs !== tab.label.trim()
? `That invite code is for ${theirs}, not ${mine}. To join ${theirs}, paste the code in New Remote Connection.`
: `That invite code is for a different team than ${mine}. To join it, paste the code in New Remote Connection.`
})
return
}
// A code the renderer cannot read still goes to main, which verifies codes and answers for
// this one; its key is the text itself, so a double paste of it is still one attempt.
const hostId = peek?.hostId ?? `unreadable:${code}`
const label = peek?.label ?? ''
// The team's own tab, when it has one open (greyed or not), is the one this code is for: a
// greyed tab reconnects in place, a live one answers "already connected" — never a second tab.
const target = reconnectProjectId ?? tabFor(hostId)
const req: HostedAttemptRequest = { hostId, code, label, manual: true, retry: false, ...(target ? { reconnectProjectId: target } : {}) }
if (run(req) === 'busy') {
deps.notify({ kind: 'info', text: busyText(hostId, label) })
}
},
reconnectTab(projectId) {
const t = tabs.get(projectId)
if (!t) return false
if (t.forgotten) {
// Forgotten: no stored code to rejoin with — ask, as the forget dialog promised.
void deps.promptForCode(t.label).then(
(code) => {
const c = code?.trim()
if (c) joiner.joinWithCode(c, projectId)
},
() => {}
)
return true
}
if (run({ hostId: t.hostId, code: t.code, label: t.label, manual: true, retry: true, reconnectProjectId: projectId, autoConfirm: true }) === 'busy') {
deps.notify({ kind: 'info', text: `Already reconnecting to ${team(t.label)}…` })
}
return true
},
isHostedTab(projectId) {
return tabs.has(projectId)
},
tabClosed(projectId) {
tabs.delete(projectId)
attempts.cancelProject(projectId)
},
tabRemoved(projectId, successorId) {
const t = tabs.get(projectId)
tabs.delete(projectId)
if (t && !tabs.has(successorId)) tabs.set(successorId, t)
attempts.retarget(projectId, successorId)
},
tabsAdded(hostId, projectIds) {
const t = [...tabs.values()].find((x) => x.hostId === hostId)
if (t) for (const id of projectIds) tabs.set(id, t)
},
joinApproved(raw, opts) {
const code = raw.trim()
const peek = peekJoinCode(code)
const hostId = peek?.hostId ?? `unreadable:${code}`
const label = peek?.label ?? ''
const target = tabFor(hostId)
// A team this desktop just set up itself over ssh (its bookmark is pre-approved): retry a
// relay that is still coming up, and confirm on our side with no SAS (main confirms a join
// whose bookmark is approved for the same host key).
const result = run({
hostId,
code,
label,
manual: true,
retry: true,
autoConfirm: true,
...(target ? { reconnectProjectId: target } : {}),
...(opts?.focusProjectId ? { focusProjectId: opts.focusProjectId } : {})
})
if (result === 'busy') deps.notify({ kind: 'info', text: busyText(hostId, label) })
return result
},
async bootReconnect() {
const list = await deps.bookmarks().catch(() => [])
for (const b of list) {
if (b.approved) run({ hostId: b.hostId, code: b.code, label: b.label, manual: false, retry: true, autoConfirm: true })
}
},
async forget(hostId, label) {
if (joiner.connecting(hostId)) {
deps.notify({ kind: 'info', text: `Still connecting to ${team(label)}; forget it once that finishes.` })
return
}
attempts.cancel(hostId)
try {
await deps.removeBookmark(hostId)
} catch (err) {
deps.notify({ kind: 'error', text: `Could not forget ${team(label)}: ${stripIpcPrefix(err instanceof Error ? err.message : String(err))}` })
return
}
markForgotten(hostId)
deps.notify({ kind: 'info', text: `Forgot ${team(label)}. This device will not reconnect to it.` })
},
connecting(hostId) {
const phase = attempts.phase(hostId)
return phase === 'connecting' || phase === 'mounting'
},
dispose() {
attempts.dispose()
}
}
return joiner
}