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
// PresenceHub — the peer table for team presence (docs/team-presence.md).
//
// One hub, two adapters: the Server Edition joins/leaves each authenticated WebSocket
// (src/server/ws.ts), and the desktop joins its own window plus every bridged relay peer
// (src/main/index.ts, src/main/remote/standing-host.ts). The hub itself is a dumb reflector:
// it holds Map<clientId, PeerState>, applies events, and emits diffs. No electron, no ws, no
// disk, no timers — it talks to its shell only through platform() (see src/core/platform.ts).
//
// PRESENCE IS NEVER PERSISTED. Nothing here reaches workspace.json / project.json / settings.json.
import { IPC } from '../../shared/ipc'
import { platform } from '../platform'
import {
CHAT_MAX_LEN,
REF_MAX_LEN,
capCodePoints,
defaultNameFor,
nextFreeColor,
sanitizeDinoPayload,
sanitizeIdentity,
type ClientId,
type PeerDiff,
type PeerIdentity,
type PeerState
} from '../../shared/presence'
/** A typing badge re-broadcasts at most this often per (client, node) — see noteTyping. */
export const TYPING_THROTTLE_MS = 500
/**
* Per-(client, channel) token buckets: `perSec` is the sustained rate, `burst` the bucket size
* (how far a client may run ahead of it). Everything the hub takes from a client fans out to every
* peer, so an unlimited ingest is an unlimited N-way amplifier: the ~20 Hz cursor throttle lives in
* the HONEST renderer only, and a tab that simply doesn't run it — or a scripted client on the
* shared Server Edition password — would otherwise be free to broadcast at loop speed and fill
* every peer's WS send buffer (the same sink pty output rides, so terminals stall behind it).
*
* The budgets are sized to the app's own behaviour, so a well-behaved client can never hit one:
* - cursor: 20/s, exactly the renderer's CURSOR_MIN_INTERVAL_MS (50 ms) throttle, with 2 s of
* burst for scheduling jitter,
* - chat: one cast per keystroke — faster than any human types,
* - focus: one per node hover — orders of magnitude of headroom,
* - project: one per tab switch. DELIBERATELY generous (see isClearingCast): a dropped project
* switch is not a lost frame but LOST STATE — the hub, and so every teammate's canvas, chips
* and facepile, would stay on the project you left, forever. A human input path cannot come
* near this: holding ⌘1 repeats the SAME id (the renderer dedups it, and the hub's setter
* ignores an unchanged value anyway), so only DISTINCT switches spend a token.
* - hello: sent at connect (and once more when the user names themselves).
* Excess casts are DROPPED silently. Never disconnect: an honest client that hits a burst edge
* (a wedged event loop suddenly flushing) would lose a frame, not its session — and the next
* cursor sample carries the current position anyway, so a dropped one is invisible.
*/
export const PRESENCE_RATE_BUDGETS: Record<string, { perSec: number; burst: number }> = {
[IPC.presenceCursor]: { perSec: 20, burst: 40 },
[IPC.presenceChat]: { perSec: 25, burst: 50 },
// The dino snapshot is a ~20 Hz cast like chat/cursor; sized the same as chat.
[IPC.presenceDino]: { perSec: 25, burst: 50 },
[IPC.presenceFocus]: { perSec: 10, burst: 20 },
[IPC.presenceProject]: { perSec: 20, burst: 60 },
[IPC.presenceHello]: { perSec: 2, burst: 5 }
}
/**
* Does this cast CLEAR the client's state (a null cursor, a closed chat, a released focus)?
*
* Such a cast is EXEMPT from the bucket, because a bucket may only ever drop a signal whose loss
* is self-correcting. A cursor sample is superseded by the next one, so dropping it costs a frame.
* A clear is an EDGE: nothing supersedes it, no client acks it, nothing re-announces it — the
* renderer has already recorded "I retracted that" (publishedRef / lastFocus) and will never send
* it again. Drop one and the hub keeps the last value it accepted: a chat bubble pinned to a
* teammate's cursor forever, a ghost cursor, a "who is here" chip on a node nobody is in.
* Reachable in practice: a held key at X11's ~25/s repeat drains the chat bucket, and the keyup
* retraction is the very next cast.
*
* And it CANNOT become a flood vector, by construction: the setters ignore an unchanged value, so
* a clear broadcasts at most ONCE — re-arming it takes an intervening value cast, which IS bucketed.
* The clears' fan-out rate is therefore bounded by the (rate-limited) value casts, not by the
* client's send loop; an unlimited null flood is a no-op loop inside the hub.
*
* The predicates mirror each setter's own "is this null?" rule exactly — keep them in sync.
*/
function isClearingCast(channel: string, payload: unknown): boolean {
if (channel === IPC.presenceCursor) return !payload
if (channel === IPC.presenceChat) return typeof payload !== 'string'
if (channel === IPC.presenceFocus) return typeof payload !== 'string' || payload === ''
// A dino "stop" (the authority quit / closed the node) is an EDGE — nothing supersedes it, and a
// dropped one leaves a frozen ghost game on every spectator, so the genuine stop (`null`) is
// exempt. A MALFORMED non-null cast is NOT a stop — it goes through the rate bucket (so a garbage
// flood is bounded), and setDino sanitizes it to null (a no-op if the peer wasn't playing). Cheap
// `== null` here, not a full sanitize, so the common exempt path allocates nothing.
if (channel === IPC.presenceDino) return payload == null
return false
}
// Relay peers (phones) have no webContents id and no ServerPlatform uiId, so their ClientIds are
// minted here from a high range that can never collide with either (both start small and count up).
let nextRelayId = 1_000_000
/** Mint a ClientId for a relay peer (a bridged HostSession). Monotonic, collision-free. */
export function allocateRelayClientId(): ClientId {
return nextRelayId++
}
/** A peer copy safe to hand out: the nested `cursor`/`typing`/`dino` objects are cloned too, so a
* caller holding a peers()/join-diff result cannot reach back into the hub's table through them.
* (The setters already assign fresh objects, so these are the only nested state.) */
function copyPeer(p: PeerState): PeerState {
return {
...p,
cursor: p.cursor ? { ...p.cursor } : null,
typing: p.typing ? { ...p.typing } : null,
dino: p.dino
? { nodeId: p.dino.nodeId, snap: { ...p.dino.snap, obstacles: [...p.dino.snap.obstacles] } }
: null
}
}
export class PresenceHub {
private table = new Map<ClientId, PeerState>()
/** `${clientId}:${nodeId}` → last typing broadcast (throttle window). */
private lastTyping = new Map<string, number>()
/** `${clientId}:${channel}` → its token bucket (see PRESENCE_RATE_BUDGETS / allow). */
private buckets = new Map<string, { tokens: number; at: number }>()
private ipcRegistered = false
/** A UI connected. Colors are assigned next-free; the name is a placeholder until hello. */
join(clientId: ClientId, kind: PeerState['kind']): void {
if (this.table.has(clientId)) return
const peer: PeerState = {
clientId,
name: defaultNameFor(kind),
color: nextFreeColor([...this.table.values()].map((p) => p.color)),
cursor: null,
focus: null,
chat: null,
typing: null,
// Unknown until the client reports its active project (a phone never does in Stage 1) —
// so it is drawn on nobody's canvas and lives in the facepile only.
projectId: null,
dino: null,
kind
}
this.table.set(clientId, peer)
// The newcomer gets the whole table up front. A relay/phone peer cannot make a request, and a
// browser's ws-bridge buffers events that land before it subscribes — so this is safe for both.
platform().sendTo(clientId, IPC.presenceSync, this.peers())
// A COPY, never the live PeerState: the diff crosses the shell (and, in-process on the
// desktop, is handed to listeners as-is), so broadcasting the table's own object would let a
// consumer hold — or mutate — hub state, and would make every later setter retroactively
// rewrite an already-delivered diff.
this.emit({ op: 'join', peer: copyPeer(peer) })
}
/** A UI disconnected. Its color frees up for the next joiner. */
leave(clientId: ClientId): void {
if (!this.table.delete(clientId)) return
for (const key of [...this.lastTyping.keys()]) {
if (key.startsWith(`${clientId}:`)) this.lastTyping.delete(key)
}
// Drop the rate-limit state too, or the maps would grow for the life of the process (a
// long-lived server sees every reconnect as a new ClientId).
for (const key of [...this.buckets.keys()]) {
if (key.startsWith(`${clientId}:`)) this.buckets.delete(key)
}
this.emit({ op: 'leave', clientId })
}
/**
* Take one token from this client's bucket for `channel`, or report that it is empty.
*
* WHERE THIS LIVES, AND WHY: at the CAST/REQUEST entry point (registerIpc) — not inside the
* setters. The hub is a dumb reflector whose setters are also the API the shells and Stage 2's
* internal callers use (noteTyping from the pty:write path, a relay bridge patching a phone's
* peer); rate-limiting those would throttle the app's own trusted plumbing. The entry point is
* the exact seam where an untrusted client's message becomes hub state, which is what needs a
* budget — and it is the one place ALL shells funnel through, so no shell can forget it.
*
* A CLEARING cast (see isClearingCast) is exempt and spends no token: the bucket may only drop
* signals whose loss is self-correcting, and a clear is an edge — losing it is lost state.
*/
private allow(clientId: ClientId, channel: string, payload?: unknown): boolean {
const budget = PRESENCE_RATE_BUDGETS[channel]
if (!budget) return true
if (isClearingCast(channel, payload)) return true
const key = `${clientId}:${channel}`
const now = Date.now()
const prev = this.buckets.get(key)
// A fresh client starts with a full bucket; an existing one refills at `perSec`, capped at
// `burst` (so an idle minute does not bank a minute's worth of casts).
const tokens = prev
? Math.min(budget.burst, prev.tokens + ((now - prev.at) / 1000) * budget.perSec)
: budget.burst
if (tokens < 1) {
this.buckets.set(key, { tokens, at: now })
return false
}
this.buckets.set(key, { tokens: tokens - 1, at: now })
return true
}
/** The client claims an identity. Returns its own clientId (so it never draws its own cursor)
* plus the current table. Names are unverified by design — see docs/team-presence.md. */
hello(clientId: ClientId, id: PeerIdentity): { clientId: ClientId; peers: PeerState[] } {
const peer = this.table.get(clientId)
if (!peer) return { clientId, peers: this.peers() }
const { name, color } = sanitizeIdentity(id, { name: peer.name, color: peer.color })
// A reconnecting client re-sends its stored identity: unchanged → no broadcast (same rule as
// every setter below). The RETURN is unconditional — it is how the renderer learns its own
// ClientId, without which it would draw its own cursor as a peer's.
if (peer.name !== name || peer.color !== color) {
peer.name = name
peer.color = color
this.emit({ op: 'update', clientId, patch: { name, color } })
}
return { clientId, peers: this.peers() }
}
/** Flow coordinates, or null for a peer that has no cursor (a phone, or a mouse that left). */
setCursor(clientId: ClientId, cursor: { x: number; y: number } | null): void {
const peer = this.table.get(clientId)
if (!peer) return
let next: PeerState['cursor'] = null
if (cursor) {
if (!Number.isFinite(cursor.x) || !Number.isFinite(cursor.y)) return
next = { x: cursor.x, y: cursor.y }
}
// Unchanged → no broadcast. The renderer recomputes the flow position on every pan/zoom frame
// and sends null on both mouse-leave and blur, so identical values are common — and each one
// would otherwise fan out to every peer for zero visual change.
const prev = peer.cursor
if (prev === null ? next === null : next !== null && prev.x === next.x && prev.y === next.y) {
return
}
peer.cursor = next
this.emit({ op: 'update', clientId, patch: { cursor: next } })
}
/** The node this client is working in. The id is client-supplied and reflected to every peer, so
* it goes through the shared truncation rule (REF_MAX_LEN) exactly like chat — see presence.ts. */
setFocus(clientId: ClientId, nodeId: string | null): void {
const peer = this.table.get(clientId)
if (!peer) return
const next = typeof nodeId === 'string' && nodeId ? capCodePoints(nodeId, REF_MAX_LEN) : null
if (peer.focus === next) return
peer.focus = next
this.emit({ op: 'update', clientId, patch: { focus: next } })
}
/** Live cursor-chat text; null closes the bubble. THE single ingest point for chat, so the
* CHAT_MAX_LEN cap lives here and cannot drift between the hub and the renderer. Capped by
* code point (capCodePoints), never by UTF-16 slice: a bubble ending in half an emoji would
* render as "�" for every peer. */
setChat(clientId: ClientId, text: string | null): void {
const peer = this.table.get(clientId)
if (!peer) return
const next = typeof text === 'string' ? capCodePoints(text, CHAT_MAX_LEN) : null
// Unchanged → no broadcast (Esc-then-blur closes the bubble twice). Compared AFTER the cap:
// two different over-long strings that cap to the same 200 code points are the same peer state.
if (peer.chat === next) return
peer.chat = next
this.emit({ op: 'update', clientId, patch: { chat: next } })
}
/** The live dino game this client is the AUTHORITY for; a malformed/absent payload clears it
* (stopped playing / closed the node / took-over elsewhere). THE single ingest point, so the
* sanitize + obstacle clamp (sanitizeDinoPayload) lives here and cannot drift — the hub applies
* ONLY the sanitized value, never the raw cast. Spectators render `snap` for the matching node
* id. A repeated clear (null → null) is a silent no-op, exactly like the other setters. */
setDino(clientId: ClientId, payload: unknown): void {
const peer = this.table.get(clientId)
if (!peer) return
const next = sanitizeDinoPayload(payload)
// Stop repeats (null → null) fan out nothing. A non-null snapshot changes every frame, so it
// is always reflected — no deep compare (that would cost more than the broadcast it saves).
if (next === null && peer.dino === null) return
peer.dino = next
this.emit({ op: 'update', clientId, patch: { dino: next } })
}
/** Which project (canvas) this client is on. Everyone else uses it to decide whether this
* peer's cursor/focus belongs on THEIR screen (peersOnProject) — a project is a separate
* canvas with its own nodes and its own flow coordinates. null = no project open.
* Client-supplied, so capped with the shared truncation rule (REF_MAX_LEN) like every other
* string off the wire. */
setProject(clientId: ClientId, projectId: string | null): void {
const peer = this.table.get(clientId)
if (!peer) return
const next =
typeof projectId === 'string' && projectId ? capCodePoints(projectId, REF_MAX_LEN) : null
if (peer.projectId === next) return
peer.projectId = next
const patch: Partial<Omit<PeerState, 'clientId'>> = { projectId: next }
// The cursor belonged to the OLD canvas. A project switch can be keyboard-driven (⌘1/⌘2, the
// palette) with the mouse parked, so no pointermove follows it and the renderer's sampler
// never sends a new position — the stale coordinates would then be drawn on the NEW project's
// canvas, forever, for everyone on it. Drop it HERE (the one place that knows the canvas
// changed) and carry both changes in ONE diff, so no peer can ever apply the new project with
// the old cursor still attached.
if (peer.cursor !== null) {
peer.cursor = null
patch.cursor = null
}
this.emit({ op: 'update', clientId, patch })
}
/** Someone wrote into a node's terminal. Throttled to 1 broadcast / TYPING_THROTTLE_MS per
* (client, node) — a keystroke storm must not become a broadcast storm. The badge's ~2s decay
* is the renderer's job (TYPING_DECAY_MS): the hub keeps no timers.
* Stage 2 calls this from the sender-aware pty:write handler; nothing calls it in Stage 1.
*
* `nodeId` is a REFLECTED ref like focus/projectId — it is re-broadcast to every peer (up to
* twice a second, per node) — and it is no more trusted than they are: it is the session's
* persistKey, which the client chose at `pty:create`. So it goes through the same truncation
* rule (capCodePoints/REF_MAX_LEN). Capping is done FIRST, so the throttle key and the
* broadcast payload can never disagree about which node this is. */
noteTyping(clientId: ClientId, nodeId: string): void {
const peer = this.table.get(clientId)
if (!peer || !nodeId) return
const id = capCodePoints(nodeId, REF_MAX_LEN)
const now = Date.now()
// The throttle key is (client, node) ALONE — never the peer's *current* typing badge. Someone
// writing alternately into two nodes (agent + shell) would never match `peer.typing.nodeId`,
// so every keystroke would broadcast to every peer. Each node keeps its own window; a
// different node is a different key and so still re-fires immediately.
const key = `${clientId}:${id}`
const last = this.lastTyping.get(key) ?? 0
if (last && now - last < TYPING_THROTTLE_MS) return
this.lastTyping.set(key, now)
const typing = { nodeId: id, at: now }
peer.typing = typing
this.emit({ op: 'update', clientId, patch: { typing } })
}
/** The current table, in join order. Copies so a caller can't mutate hub state. */
peers(): PeerState[] {
return [...this.table.values()].map(copyPeer)
}
/** How many UIs are connected. Lets a caller skip work that only matters to OTHER people: the
* pty:write path uses it to not report typing while the user is alone (a badge nobody but the
* typist would receive — and their own is never drawn). See PtyManager.write. */
peerCount(): number {
return this.table.size
}
/** Wire the presence channels into the shell. Idempotent on purpose: the shell's listener
* registry does not dedup identical function references, so a second registration would make
* every cast fire (and broadcast) twice. */
registerIpc(): void {
if (this.ipcRegistered) return
this.ipcRegistered = true
const p = platform()
// Every entry point is rate-limited here (see allow): this is the seam where an untrusted
// client's message becomes hub state — and every shell funnels through it.
p.handleWithSender(IPC.presenceHello, (senderId: number, id: PeerIdentity) => {
// A dropped hello still ANSWERS (the response is how a client learns its own ClientId, and
// silence would hang its promise); it just doesn't apply the identity or broadcast.
if (!this.allow(senderId, IPC.presenceHello)) return { clientId: senderId, peers: this.peers() }
return this.hello(senderId, id)
})
// The payload goes to allow() too: a cast that CLEARS state is exempt from the bucket (a
// dropped clear is permanent, and it cannot flood — see isClearingCast).
p.onWithSender(
IPC.presenceCursor,
(senderId: number, cursor: { x: number; y: number } | null) => {
if (!this.allow(senderId, IPC.presenceCursor, cursor)) return
this.setCursor(senderId, cursor)
}
)
p.onWithSender(IPC.presenceFocus, (senderId: number, nodeId: string | null) => {
if (!this.allow(senderId, IPC.presenceFocus, nodeId)) return
this.setFocus(senderId, nodeId)
})
p.onWithSender(IPC.presenceChat, (senderId: number, text: string | null) => {
if (!this.allow(senderId, IPC.presenceChat, text)) return
this.setChat(senderId, text)
})
// The dino snapshot is a dumb-reflector cast like chat: rate-limit (a stop is an exempt clear —
// see isClearingCast), then sanitize/clamp and set. The sanitize guard cannot be bypassed.
p.onWithSender(IPC.presenceDino, (senderId: number, payload: unknown) => {
if (!this.allow(senderId, IPC.presenceDino, payload)) return
this.setDino(senderId, payload)
})
p.onWithSender(IPC.presenceProject, (senderId: number, projectId: string | null) => {
// NOT exempted, unlike the clears: every project cast may carry a NEW id, so it always
// broadcasts — an unlimited one would hand a hostile tab the same N-way amplifier the buckets
// exist to stop (a clear cannot do that: it broadcasts at most once). Its budget is instead
// sized so far above any human input path that an honest client can never lose a switch.
if (!this.allow(senderId, IPC.presenceProject, projectId)) return
this.setProject(senderId, projectId)
})
}
private emit(diff: PeerDiff): void {
platform().broadcast(IPC.presencePeer, diff)
}
}
/** The process-wide hub. Both shells (and the relay host) feed this one instance. */
export const presenceHub = new PresenceHub()