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
// `nodeterm://` LINKS — the parser. Pure: no electron, no fs (main does the checks that need a disk).
//
// An app outside nodeterm (a review tool, a script, a bookmark) has no node identity, so canvas control
// refuses it by design. A link does not weaken that: it proves NOTHING about who sent it — any web
// page can build one. It only FILLS IN a form, and the human approves every `open` link in a confirm
// sheet before anything is created. So this parser is strict on shape and size, and every value it
// returns is treated as hostile text by everyone downstream:
//
// - unknown params, a param given twice, an over-cap value, a relative path → the whole link is
// refused (a typo in a link is a refusal the caller can see, never a silently dropped option);
// - none of canvas control's power flags exist here (count, group, after, run-now, model, issue,
// permission mode): a link opens ONE node in its project's default permission mode, and can never
// ask for a looser one;
// - `source` is a display label only. Nothing may branch on it.
//
// `nodeterm://pair?code=…` and `nodeterm://join?code=…` are recognised and handed back verbatim so
// the app can route them to its existing pairing / join flows, which have their own approval.
// Design: docs/superpowers/specs/2026-10-13-open-link-design.md.
import { BUILTIN_AGENT_IDS, type BuiltinAgentId } from './agents/config'
export const OPEN_LINK_SCHEME = 'nodeterm:'
/** The agents a link may open: the builtins, plus a plain terminal. */
export type OpenLinkAgent = BuiltinAgentId | 'terminal'
/** Caps, after decoding. Prompt and paths in UTF-8 bytes, labels in code points. */
export const OPEN_LINK_LIMITS = {
/** The whole raw URL. Larger than every cap below combined after %-encoding, small enough that
* nothing pathological reaches the decoder. */
url: 48 * 1024,
prompt: 8 * 1024,
/** `prompt-file` content, checked by main when the file is read. */
promptFile: 64 * 1024,
path: 4096,
title: 80,
source: 40,
projectId: 200,
/** A pairing offer / join code (base64url JSON). */
code: 8 * 1024
} as const
export interface OpenLinkRequest {
agent: OpenLinkAgent
/** A project id from the workspace index. */
project?: string
/** Absolute path: the project whose cwd is exactly this. */
projectCwd?: string
/** Absolute path: where the node runs. Defaults to the chosen project's cwd. */
cwd?: string
/** The agent's first message (≤ 8 KB). */
prompt?: string
/** Absolute path to a file holding the first message, read by main on accept. */
promptFile?: string
title?: string
/** UNVERIFIED display label. */
source?: string
}
export type ParsedLink =
| { kind: 'open'; request: OpenLinkRequest }
| { kind: 'pair' | 'join'; url: string }
export type ParseLinkResult = { ok: true; link: ParsedLink } | { ok: false; reason: string }
const OPEN_PARAMS = ['agent', 'project', 'project-cwd', 'cwd', 'prompt', 'prompt-file', 'title', 'source'] as const
type OpenParam = (typeof OPEN_PARAMS)[number]
const refuse = (reason: string): ParseLinkResult => ({ ok: false, reason })
const utf8Bytes = (s: string): number => new TextEncoder().encode(s).length
const codePoints = (s: string): number => Array.from(s).length
// C0 (except tab/newline/CR), DEL and C1 — never legitimate in a link value. A prompt keeps tab and
// newlines (a multi-line brief); every other value refuses those too.
// eslint-disable-next-line no-control-regex
const CONTROL_EXCEPT_WS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/
// eslint-disable-next-line no-control-regex
const ANY_CONTROL = /[\u0000-\u001f\u007f-\u009f]/
// Bidi and zero-width formatting controls: a label must render as what it says.
const FORMAT_CONTROL = /[\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/
// Text a human cannot see but a model reads: every format character (bidi overrides, zero-width
// characters, Unicode TAG characters U+E0000–E007F — "ASCII smuggling"), plus C1. ZWJ (U+200D) is
// allowed, so an emoji sequence in a prompt survives. One character class, no backtracking.
const HIDDEN_TEXT = /[\u0080-\u009f]|(?!\u200d)\p{Cf}/u
/** Would part of this text be invisible or reordered in the sheet? Shared with main's prompt-file
* check, so the inline prompt and a file's text follow one rule. */
export function hasHiddenText(s: string): boolean {
return HIDDEN_TEXT.test(s)
}
/** A refusal echoes link text: keep it short (the whole link may be 48 KB). */
const clip = (s: string): string => {
const cps = Array.from(s)
return cps.length > 40 ? `${cps.slice(0, 40).join('')}…` : s
}
/** `+` is a space (form encoding: what `URLSearchParams` and most link builders emit), then %-decode.
* A malformed escape refuses rather than passing the raw text through. */
function decodeValue(raw: string): string | null {
try {
return decodeURIComponent(raw.replace(/\+/g, ' '))
} catch {
return null
}
}
/**
* Absolute on THIS machine's dialects: POSIX `/…`, or a Windows drive path `C:\…` / `C:/…`.
* Refused: relative paths, `~` (the shell's, not ours), UNC `\\server\share` (a read there reaches
* another machine over SMB), and any `.`/`..` segment — an absolute path never needs one, and
* refusing it keeps "the path the sheet shows" equal to "the path that is opened".
*
* A POSIX-form path may not contain a backslash: Windows reads `/\host\share` as the UNC path
* `\\host\share`, and main stats a link's paths before the sheet appears, so that alone would
* make Windows connect (and authenticate) to another machine. For the same reason the macOS
* automount roots `/net` and `/Network` are refused. Hidden or reordering characters are refused so
* the path on screen is the path opened.
*/
export function isAcceptableAbsolutePath(p: string): boolean {
if (!p || utf8Bytes(p) > OPEN_LINK_LIMITS.path || ANY_CONTROL.test(p) || hasHiddenText(p)) return false
if (/^\/(?:net|network)(?:\/|$)/i.test(p)) return false
const posix = p.startsWith('/') && !p.startsWith('//') && !p.includes('\\')
const win = /^[A-Za-z]:[\\/]/.test(p)
if (!posix && !win) return false
const segments = (win ? p.slice(3) : p.slice(1)).split(/[\\/]/)
return !segments.some((s) => s === '.' || s === '..')
}
function isOpenLinkAgent(a: string): a is OpenLinkAgent {
return a === 'terminal' || (BUILTIN_AGENT_IDS as readonly string[]).includes(a)
}
/** Split the query into decoded pairs. Refuses a duplicate key and a malformed escape. Empty
* segments (`a=1&&b=2`, a trailing `&`) are ignored. */
function readQuery(query: string): Map<string, string> | string {
const out = new Map<string, string>()
for (const part of query.split('&')) {
if (!part) continue
const eq = part.indexOf('=')
const rawKey = eq === -1 ? part : part.slice(0, eq)
const rawVal = eq === -1 ? '' : part.slice(eq + 1)
const key = decodeValue(rawKey)
const val = decodeValue(rawVal)
if (key === null || val === null) return 'it is not correctly encoded'
if (out.has(key)) return `"${key}" is given more than once`
out.set(key, val)
}
return out
}
/** Parse a `nodeterm://` URL. Never throws. */
export function parseNodetermLink(input: unknown): ParseLinkResult {
if (typeof input !== 'string') return refuse('the link is not text')
const url = input.trim()
if (url.length > OPEN_LINK_LIMITS.url) return refuse('the link is too long')
if (url.slice(0, OPEN_LINK_SCHEME.length + 2).toLowerCase() !== `${OPEN_LINK_SCHEME}//`) {
return refuse('it is not a nodeterm:// link')
}
if (url.includes('#')) return refuse('it has a fragment (#)')
const rest = url.slice(OPEN_LINK_SCHEME.length + 2)
const q = rest.indexOf('?')
// `nodeterm://open?…` and `nodeterm://open/?…` both name the host `open`.
const host = (q === -1 ? rest : rest.slice(0, q)).replace(/\/$/, '').toLowerCase()
const query = q === -1 ? '' : rest.slice(q + 1)
if (host === 'pair' || host === 'join') {
const params = readQuery(query)
if (typeof params === 'string') return refuse(`the ${host} link: ${params}`)
for (const key of params.keys()) {
if (key !== 'code') return refuse(`the ${host} link has an unknown parameter "${clip(key)}"`)
}
const code = params.get('code')
if (!code) return refuse(`the ${host} link has no code`)
if (code.length > OPEN_LINK_LIMITS.code || ANY_CONTROL.test(code)) return refuse(`the ${host} code is not valid`)
// Rebuilt from the decoded code so the existing decoders see the canonical prefix form.
return { ok: true, link: { kind: host, url: `nodeterm://${host}?code=${code}` } }
}
if (host !== 'open') return refuse(host ? `nodeterm://${host} is not a link nodeterm opens` : 'it names no action')
const params = readQuery(query)
if (typeof params === 'string') return refuse(params)
for (const key of params.keys()) {
if (!(OPEN_PARAMS as readonly string[]).includes(key)) return refuse(`unknown parameter "${clip(key)}"`)
}
const get = (k: OpenParam): string | undefined => params.get(k)
const agent = get('agent')
if (!agent) return refuse('it does not say which agent to open (agent=)')
if (!isOpenLinkAgent(agent)) return refuse(`"${clip(agent)}" is not an agent nodeterm can open`)
const request: OpenLinkRequest = { agent }
const project = get('project')
const projectCwd = get('project-cwd')
if (project !== undefined && projectCwd !== undefined) {
return refuse('"project" and "project-cwd" cannot be combined')
}
if (project !== undefined) {
if (!project || project.length > OPEN_LINK_LIMITS.projectId || ANY_CONTROL.test(project) || FORMAT_CONTROL.test(project) || hasHiddenText(project)) {
return refuse('"project" is not a valid project id')
}
request.project = project
}
if (projectCwd !== undefined) {
if (!isAcceptableAbsolutePath(projectCwd)) return refuse('"project-cwd" must be an absolute path')
request.projectCwd = projectCwd
}
const cwd = get('cwd')
if (cwd !== undefined) {
if (!isAcceptableAbsolutePath(cwd)) return refuse('"cwd" must be an absolute path')
request.cwd = cwd
}
const prompt = get('prompt')
const promptFile = get('prompt-file')
if (prompt !== undefined && promptFile !== undefined) {
return refuse('"prompt" and "prompt-file" cannot be combined')
}
if ((prompt !== undefined || promptFile !== undefined) && agent === 'terminal') {
// Typing text into a shell is running a command, not sending a message.
return refuse('a terminal link cannot carry a prompt')
}
if (prompt !== undefined) {
if (utf8Bytes(prompt) > OPEN_LINK_LIMITS.prompt) return refuse('"prompt" is longer than 8 KB (use prompt-file)')
if (CONTROL_EXCEPT_WS.test(prompt)) return refuse('"prompt" contains control characters')
if (hasHiddenText(prompt)) return refuse('"prompt" contains invisible or direction-changing characters')
if (prompt.trim()) request.prompt = prompt
}
if (promptFile !== undefined) {
if (!isAcceptableAbsolutePath(promptFile)) return refuse('"prompt-file" must be an absolute path')
request.promptFile = promptFile
}
const title = get('title')
if (title !== undefined) {
if (codePoints(title) > OPEN_LINK_LIMITS.title) return refuse('"title" is longer than 80 characters')
if (ANY_CONTROL.test(title) || FORMAT_CONTROL.test(title) || hasHiddenText(title)) return refuse('"title" contains control characters')
if (title.trim()) request.title = title.trim()
}
const source = get('source')
if (source !== undefined) {
if (codePoints(source) > OPEN_LINK_LIMITS.source) return refuse('"source" is longer than 40 characters')
if (ANY_CONTROL.test(source) || FORMAT_CONTROL.test(source) || hasHiddenText(source)) return refuse('"source" contains control characters')
if (source.trim()) request.source = source.trim()
}
return { ok: true, link: { kind: 'open', request } }
}
/** A title the human edited in the sheet, checked again by main: one line, ≤ 80, no controls.
* Empty / whitespace = no title. Returns null when it is not acceptable. */
export function normalizeLinkTitle(raw: unknown): string | undefined | null {
if (raw === undefined || raw === null) return undefined
if (typeof raw !== 'string') return null
const t = raw.trim()
if (!t) return undefined
if (codePoints(t) > OPEN_LINK_LIMITS.title || ANY_CONTROL.test(t) || FORMAT_CONTROL.test(t) || hasHiddenText(t)) return null
return t
}
/** The first `nodeterm://` URL in a process argv (Windows/Linux deliver a clicked link that way:
* on first launch in `process.argv`, afterwards in `second-instance`'s argv). */
export function nodetermUrlFromArgv(argv: readonly string[]): string | null {
for (const a of argv) {
if (typeof a === 'string' && a.slice(0, OPEN_LINK_SCHEME.length + 2).toLowerCase() === `${OPEN_LINK_SCHEME}//`) {
return a
}
}
return null
}
// ─── Choosing the project ────────────────────────────────────────────────────────────────────────
/** A project as main's workspace index knows it — the only source of candidates (the renderer is
* the more attackable half and may only pick among what main offered). */
export interface LinkProjectEntry {
id: string
name: string
cwd?: string
closed?: boolean
/** SSH projects are out of scope for v1. */
ssh?: boolean
/** Handed to a hosted team: reopening it asks first everywhere else, so a link never offers it. */
handedOff?: boolean
}
export interface LinkProjectCandidate {
id: string
name: string
cwd?: string
closed: boolean
}
export type LinkProjectNote =
/** `project=<id>` names nothing in the index. */
| 'not-found'
/** `project=<id>` names an SSH project (or one handed to a team). */
| 'unsupported'
/** `project-cwd=` matched no project. */
| 'no-match'
export interface LinkProjectResolution {
/** Every project the sheet may offer, preselected / matching ones first. */
candidates: LinkProjectCandidate[]
/** The suggestion; null = none (the sheet falls back to the active project if offerable). */
preselectId: string | null
note?: LinkProjectNote
/** "Open <folder> as a new project", offered when no project owns that exact folder. */
newProjectCwd?: string
}
/** Comparable form of a path: separators unified, no trailing separator (root kept). */
export function comparablePath(p: string): string {
const s = p.replace(/\\/g, '/')
// A scan, not /\/+$/: that regex is quadratic on a run of slashes.
let end = s.length
while (end > 1 && s.charCodeAt(end - 1) === 47) end--
return s.slice(0, end)
}
/** Is `child` the folder `dir` or inside it — segment-wise, so `/repo-x` is not inside `/repo`. */
export function pathWithin(child: string, dir: string): boolean {
const c = comparablePath(child)
const d = comparablePath(dir)
if (c === d) return true
return c.startsWith(d.endsWith('/') ? d : `${d}/`)
}
export function resolveLinkProject(req: OpenLinkRequest, entries: readonly LinkProjectEntry[]): LinkProjectResolution {
const offerable = entries.filter((e) => !e.ssh && !e.handedOff)
const toCandidate = (e: LinkProjectEntry): LinkProjectCandidate => ({
id: e.id,
name: e.name,
...(e.cwd ? { cwd: e.cwd } : {}),
closed: !!e.closed
})
// Open projects before closed ones; otherwise index order.
const ordered = [...offerable.filter((e) => !e.closed), ...offerable.filter((e) => e.closed)]
const front = (first: LinkProjectEntry[]): LinkProjectCandidate[] => {
const ids = new Set(first.map((e) => e.id))
return [...first, ...ordered.filter((e) => !ids.has(e.id))].map(toCandidate)
}
const folder = req.cwd ?? req.projectCwd
const ownsFolder = folder
? offerable.some((e) => e.cwd && comparablePath(e.cwd) === comparablePath(folder))
: true
const newProjectCwd = folder && !ownsFolder ? folder : undefined
const withNew = (r: LinkProjectResolution): LinkProjectResolution =>
newProjectCwd ? { ...r, newProjectCwd } : r
if (req.project !== undefined) {
const hit = entries.find((e) => e.id === req.project)
if (!hit) return withNew({ candidates: front([]), preselectId: null, note: 'not-found' })
if (hit.ssh || hit.handedOff) return withNew({ candidates: front([]), preselectId: null, note: 'unsupported' })
return withNew({ candidates: front([hit]), preselectId: hit.id })
}
if (req.projectCwd !== undefined) {
const want = comparablePath(req.projectCwd)
const matches = ordered.filter((e) => e.cwd && comparablePath(e.cwd) === want)
if (!matches.length) return withNew({ candidates: front([]), preselectId: null, note: 'no-match' })
return withNew({ candidates: front(matches), preselectId: matches[0].id })
}
if (req.cwd !== undefined) {
let best: LinkProjectEntry | null = null
for (const e of ordered) {
if (!e.cwd || !pathWithin(req.cwd, e.cwd)) continue
if (!best || comparablePath(e.cwd).length > comparablePath(best.cwd as string).length) best = e
}
if (best) return withNew({ candidates: front([best]), preselectId: best.id })
}
return withNew({ candidates: front([]), preselectId: null })
}
// ─── The wire between main and the sheet ─────────────────────────────────────────────────────────
/** What main sends the renderer for an `open` link, every path already checked by main. */
export interface OpenLinkPrompt {
id: string
agent: OpenLinkAgent
cwd?: string
prompt?: string
/** The `prompt-file` path, and its content as main read it for display (re-read on accept). */
promptFile?: string
promptFileText?: string
title?: string
source?: string
resolution: LinkProjectResolution
/** The agent's command was not found on the login-shell PATH. A warning, not a refusal: a launch
* command override can make the bare binary irrelevant. */
agentMissing?: boolean
}
/** The human's answer. Only a choice among what main offered: never a path, never a prompt. */
export interface OpenLinkChoice {
/** One of `resolution.candidates`, or omitted with `newProject`. */
projectId?: string
/** Open `resolution.newProjectCwd` as a new project. */
newProject?: boolean
title?: string
}
/** Main's verdict on a choice: the final, re-checked open. */
export type OpenLinkAcceptResult =
| {
ok: true
open: {
agent: OpenLinkAgent
projectId?: string
newProjectCwd?: string
cwd?: string
prompt?: string
/** A copy of the prompt file under nodeterm's own launch-prompt store. */
promptFile?: string
title?: string
}
}
| { ok: false; reason: string }