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 { IPC } from './ipc'
/**
* HOST-ONLY channels: the RPC methods a relay GUEST may never reach, in ONE list both shells read.
*
* A relay peer (a paired phone, another desktop over 4c) is a first-class client of this machine's
* core — that is the point of the peer registry — but it is NOT the host's user. A small set of
* methods are the host's own control plane, and admitting one of them from a guest hands over
* something the guest could not otherwise have:
*
* - `githubControl:*` — the token/approval plane for the host's GitHub credentials.
* - `project-setup:run` — starts a script ON the host, in the host's shell, as the host's user.
* - `project-setup:consent-submit` — the ANSWER to the host's own trust prompt. Admitting `run`
* and this one together is the whole attack: a guest raises the prompt and then approves it
* itself, so a shared `.nodeterm/project.json` script executes with no human ever looking at a
* dialog. Either one alone is much weaker; the pair is a complete self-approval loop.
* - `project-setup:cancel` — the other side of the same run's control: a guest must not be able to
* kill the host's setup mid-write.
* - `project-setup:request-trust` — RAISES the host's own consent dialog for a project's launch
* settings. Alone it is prompt spam on someone else's screen; paired with an admitted
* consent-submit it is the same self-approval loop as run+consent-submit, ending in a shared
* `launchCmd`/`env` (or shell) approved for the host's own agent launches.
*
* - `pty:launch-headless` (#925) — the desktop's canvas-control `--run-now` / `run`: it starts a
* node's session with no viewer and types its launch on the host. The relay guest's own bridge
* already refuses it (a relay tab inherits ws-bridge's `pty`), and this makes the refusal hold
* host-side for a peer that sends the raw request (spec §6: "Relay tab | Refuses").
* - `station-notice:dropped` — a DROPPED verdict makes the host tell an orchestrator, possibly in
* its own session, that one of its stations died. It is a pane measurement only the HOST's
* renderer makes (a relay tab takes the inert stub), so a guest sending it is claiming a fact
* about the host's panes it never measured.
* - `station-notice:list` — every project's failed-station ids and titles, unscoped. A relay tab
* never asks (it takes the inert stub), and a guest bound to ONE project must not read the rest.
*
* DELIBERATELY NOT LISTED: `project-setup:subscribe`/`unsubscribe` and the `project-setup:event:*`
* push. They neither start nor authorize anything, and a peer that can see the canvas can already
* see that a setup is running. The gate is on ACTION, not on the namespace — which is also why
* this is an explicit list rather than a `project-setup:` prefix.
*
* This lives in `shared/` because it is a policy question, not a shell mechanism: two shells each
* carrying their own `startsWith` is exactly how one of them ends up a release behind the other.
*/
export const HOST_ONLY_CHANNEL_PREFIXES: readonly string[] = [
'githubControl:',
// The host's credential and identity planes. None of these crosses the relay for a legitimate
// tab (relay-api.ts keeps license/accounts/usage LOCAL), and each is something the invite never
// granted: the license key and its seats, the managed Claude/Codex logins (a login node writes
// credentials into the account dir, removal deletes one), and account usage read with the
// host's stored tokens.
'license:',
// The free-tier open-project allowance: refuses a relay peer's INBOUND `projectLimit:state` /
// `projectLimit:claim` requests — a claim spends THIS device's allowance under this machine's hash,
// and the state reports the host's Pro and DO_NOT_TRACK facts. A relay tab never sends them (it
// keeps its local preload; relay-api.ts spreads `...local`). This list gates inbound req/cast ONLY:
// the outbound `projectLimit:changed` push is kept off relay peers separately, by sending it to
// this machine's own windows only (core/project-limit.ts), never through `platform().broadcast`,
// which fans out to every relay peer.
'projectLimit:',
'claude-accounts:',
'codex-accounts:',
'usage:',
// The trust plane itself: who is paired, who may connect, and the invites that mint seats. A
// peer that could reach these could pin its own key or revoke the host's other devices. Note the
// trailing colons: `relay:host:` does not match the hosted-team verbs (`relay:hosted:*`), which
// the Server Edition's hosted service intercepts and judges itself.
'pairing:',
'remote:',
'relay:host:',
'relay:client:',
// Agent-integration consent status: paths in the host's home it kept or wrote. The consent itself
// is in settings (already host-only).
'integrations:',
// Simulator node: the host's iOS simulators / Android emulators — boot, erase, install, input.
// A relay tab never offers the node (relay-api keeps the namespace local), so a peer sending one
// of these is asking to drive the host's devices.
'simulator:',
// `nodeterm://` links: a link clicked on THIS machine opens a node here after THIS machine's user
// approves it. Raw ipcMain handlers (no peer reaches them); listed so a move onto the platform
// table cannot quietly open them.
'open-link:'
]
export const HOST_ONLY_CHANNELS: ReadonlySet<string> = new Set([
IPC.projectSetupRun,
IPC.projectSetupCancel,
IPC.projectSetupConsentSubmit,
IPC.projectSetupRequestTrust,
IPC.ptyLaunchHeadless,
// A relay peer never delivers a held launch (commitOwnedLaunchAttempt), and a peer that could
// claim one would make every viewer of the host stand down from it (#1173).
IPC.workspaceClaimLaunch,
// Executes an agent launch on the host and reads a host-local `--prompt-file` into it. A relay
// tab never sends it (its pty bridge omits the member); this holds the refusal host-side too.
IPC.ptyExecuteLaunch,
// Types into a pane of THIS machine (or its SSH host); a relay peer must never reach it.
IPC.ptySendPaneKeys,
// Prepare-for-update ends EVERY session on this machine's session host and quits the app. Only
// the host's own user may do that. Raw ipcMain handlers (no peer reaches them); listed here too
// so moving them onto the platform table later cannot quietly open them.
IPC.appUpdatePrepInspect,
IPC.appUpdatePrepShutdown,
IPC.appUpdatePrepQuit,
// A board comment that @mentions a session types into that session's pane. Only the host's own
// user may do that: a relay peer's comment is display-only. Registered with a raw ipcMain handler
// (so no peer can reach it at all); listed here too, so moving it onto the platform table later
// cannot quietly open it.
IPC.agentBoardCommentDeliver,
IPC.stationNoticeDropped,
// The host's own dispatcher state; a relay tab's board belongs to the host and its dispatch is
// refused, so a peer has nothing true to report.
IPC.boardDispatchReport,
IPC.stationNoticeList,
// Unscoped: every project's station outcomes and their notes. A relay guest bound to one project
// must not read another's, and a relay tab's launch loop is refused anyway (its stub is inert).
IPC.stationOutcomeList,
// Same class: which of the host's stations (any project) have work handed to them.
IPC.stationHandoverList,
// "Open recent": the host's conversation history — titles are prompts the host's user typed, in
// every project. A relay tab lists its OWN machine's history (relay-api keeps it `...local`), so
// no legitimate peer asks the host for this.
IPC.recentConversationsList,
// The host's settings. `settings:save` is the dangerous half: `modelGateway.baseUrl` is the TRUST
// ANCHOR `agent:discover-models` uses to decide whether it may resolve the stored
// `${secret:model-gateway-api-key}` (core/agent-env-ipc.ts), so a peer that could save settings
// and then ask for discovery would have the keychain-held key sent to a URL of its choosing.
// `settings:load` goes too: settings.json carries custom agents' launch env (API keys), and a
// relay tab keeps its settings LOCAL (relay-api.ts), so no legitimate peer reads the host's.
IPC.settingsLoad,
IPC.settingsSave,
// Model-gateway discovery and the write-only gateway credential. Discovery resolves host-side
// secrets against the saved gateway; the credential verbs write/clear the keychain-held key.
IPC.agentDiscoverModels,
IPC.agentGatewayCredentialStatus,
IPC.agentGatewayCredentialSave,
IPC.agentGatewayCredentialClear,
// Dev-server ports: a scan lists the host's listening ports, and a forward binds a port on the
// HOST machine's loopback over one of its SSH masters. Neither is a peer's to ask for.
IPC.devPortsScan,
IPC.devPortsForward,
IPC.devPortsUnforward
])
/** What a refused peer is told. One wording, so the two shells answer identically. */
export const HOST_ONLY_REFUSAL = 'host-control method is not available to relay peers'
export function isHostOnlyChannel(channel: string): boolean {
// The method name arrives off the wire; a non-string is never a channel (and must not throw).
if (typeof channel !== 'string') return false
if (HOST_ONLY_CHANNELS.has(channel)) return true
return HOST_ONLY_CHANNEL_PREFIXES.some((prefix) => channel.startsWith(prefix))
}