Skip to content

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.

16.3 KB
Raw Blame
// The shape of "who owns this pane", and the predicate that reads it.
//
// The TYPE lives here, in `src/shared`, because both directions need it: `src/core` PRODUCES it
// (`core/agents/pane-owner.ts` parses it out of tmux + ps, `PtyManager.paneOwner` assembles it) and
// the predicate below CONSUMES it. `src/shared` is the leaf every shell already imports, so this is
// the one placement that does not make `src/shared` depend on `src/core`.

/**
 * Kernel truth about a tmux pane at one instant.
 *
 *  - `panePid`  — `#{pane_pid}`, the process tmux forked for the pane (usually the login shell).
 *  - `tty`      — `#{pane_tty}`, the pane's pty. This is the handle the foreground process GROUP is
 *                 read through, because the kernel tracks that per terminal, not per process.
 *  - `command`  — `#{pane_current_command}`, tmux's own shallow answer. Kept because it is free and
 *                 because it is what the old gate used; it is NOT what the predicate decides on.
 *                 Measured on this host: a pane running `node …/claude --resume x` reports
 *                 `command: 'node'`. A name-based gate cannot see the difference between that and
 *                 any other node process.
 *  - `argv`     — every member of the pane's FOREGROUND process group, full command line, in the
 *                 order `ps` listed them (pid order, so the group leader is first).
 */
export interface PaneOwner {
  panePid: number
  tty: string
  command: string
  argv: readonly string[]
  /**
   * `#{pane_id}` — tmux's own handle for the pane (`%17`). Unique for the life of the server and
   * NEVER reused, which is what `panePid` and `tty` are not: a tty number is recycled aggressively,
   * and `panePid` is the pane's ROOT process (the login shell), which survives the agent it
   * launched. Absent only when the read predates this field or the format expanded to nothing.
   */
  paneId?: string
  /**
   * The pid of each foreground-group member, in the same order as `argv`.
   *
   * `ps` already prints it — `foregroundArgvArgs` asks for `pid=` as its first column — so this
   * costs nothing extra, and it is the only thing that can distinguish "the same agent process is
   * still there" from "an agent process is there again". A wrapper loop (`while :; do claude; done`)
   * makes the second case ordinary rather than exotic.
   */
  pids?: readonly number[]
  /** Native Windows process birth times, paired with pids. Guards PID reuse when the
   * console root outlives a child. POSIX readers retain their existing contract. */
  processBirths?: readonly string[]
}

/**
 * Three-valued on purpose — `unknown` is NOT a shade of `not-agent`.
 *
 *  - `agent`     — the kernel answered and the expected agent binary owns the foreground group.
 *  - `not-agent` — the kernel answered and the answer was no. Terminal; do not retry.
 *  - `unknown`   — the probe failed (no tmux, dead pane, `ps` unavailable, deadline lapsed). The
 *                  caller may retry. It must never be upgraded to `agent`.
 */
export type AgentPaneVerdict = 'agent' | 'not-agent' | 'unknown'

/**
 * The binary names each built-in agent's CLI actually runs as. Mirrors `AGENT_CONFIG[x].launchCmd`
 * / `.expectedProcess`, kept as its own list so a launch-command change (a wrapper, a flag) cannot
 * silently widen or narrow a SECURITY predicate. A custom agent (`custom:<uuid>`) has no entry —
 * see `isAgentPane`'s `unknown` for what that means.
 */
export const AGENT_BINARIES: Record<string, readonly string[]> = {
  claude: ['claude'],
  codex: ['codex'],
  copilot: ['copilot'],
  gemini: ['gemini'],
  opencode: ['opencode'],
  grok: ['grok'],
  // `agy-bin` (issue #1373): on Linux `agy` is commonly a shell wrapper that ends in
  // `exec …/agy-bin "$@"`, so after the exec the foreground group holds `agy-bin` and no `agy` at
  // all. Reported from the field, not measured here — the name is Antigravity's own and collides
  // with nothing a plain terminal runs, so admitting it widens the predicate by that one binary.
  antigravity: ['agy', 'agy-bin'],
  cursor: ['cursor-agent']
}

/**
 * Names that must NEVER become an agent's binary, however a launch command was written.
 *
 * Every one of them is a program the user's own plain terminals run. Admitting `bash` as "the
 * codex-custom binary" would make every idle shell on the canvas a valid delivery target — the
 * exact hole `isShellCommand`'s negation had, re-opened through the custom-agent door. When a
 * launch command's first meaningful token is one of these, the honest answer is that we cannot name
 * the binary (null ⇒ `unknown` ⇒ refuse), not that we can.
 */
const NEVER_A_BINARY = new Set([
  'sh', 'bash', 'zsh', 'fish', 'dash', 'ksh', 'tcsh', 'nu', 'pwsh', 'powershell', 'xonsh', 'elvish',
  'ssh', 'sudo', 'doas', 'su', 'tmux', 'screen', 'script'
])

/** Package runners: the interesting name is the package they fetch, not the runner. */
const RUNNERS = new Set(['npx', 'bunx', 'pnpx', 'npm', 'pnpm', 'yarn', 'bun', 'deno', 'uvx', 'pipx'])

/** Tokens that stand between a runner/interpreter and the name we are after. */
const RUNNER_VERBS = new Set(['exec', 'run', 'dlx', 'x', '--'])

/**
 * Interpreters that are followed by the script they run. `node /usr/local/bin/claude` is the shape
 * every npm-installed agent CLI actually has on this host (measured), so argv[0]'s basename alone
 * would answer `node` for every one of them.
 *
 * Resolution applies ONLY when the next token is not an option: `sh -c 'grep -r claude .'` must not
 * resolve to `grep`, and `python3 -i` must not resolve to anything. An interpreter whose next token
 * starts with `-` keeps its own name.
 */
const INTERPRETERS = new Set(['node', 'nodejs', 'bun', 'deno', 'python', 'python3', 'ruby', 'perl'])

/** basename, with a login shell's leading `-` stripped (`-zsh` → `zsh`). */
function baseName(token: string): string {
  const noDash = token.replace(/^-/, '')
  return noDash.split('/').pop() ?? ''
}

/**
 * The binary a command line actually runs, as a bare name. Splits on whitespace only — this is a
 * `ps` line, already tokenised by the kernel's argv, and a quoted path with a space in it is not
 * worth a shell-grammar parser here: the failure mode is a name that matches nothing, i.e. a
 * refusal, which is the safe direction.
 */
function effectiveBinary(commandLine: string): string {
  const tokens = commandLine.trim().split(/\s+/).filter(Boolean)
  if (tokens.length === 0) return ''
  const head = baseName(tokens[0])
  if (!INTERPRETERS.has(head)) return head
  const next = tokens[1]
  if (!next || next.startsWith('-')) return head
  return baseName(next)
}

/**
 * The binary a LAUNCH COMMAND will end up running, as a bare name — or null when it cannot be named
 * safely.
 *
 * `launchCmd` is free text the user typed into Settings → Agents, so it is not a program name: it
 * is `npx -y my-agent`, `bash -lc "…"`, `env FOO=1 my-agent --flag`. The walk below skips wrappers
 * to the first thing that looks like the program, and refuses outright when that thing is something
 * every plain terminal also runs (`NEVER_A_BINARY`) — a wrong name here does not merely fail to
 * match, it matches everything.
 *
 * A trailing npm version specifier is dropped (`@acme/[email protected]` → `my-agent`) because that is
 * how the process will appear in argv. A `.js` extension is kept, for the same reason.
 */
export function binaryFromLaunchCmd(launchCmd: string | null | undefined): string | null {
  if (!launchCmd) return null
  const tokens = launchCmd.trim().split(/\s+/).filter(Boolean)
  for (let i = 0; i < tokens.length && i < 16; i++) {
    const token = tokens[i]
    if (token.startsWith('-') || RUNNER_VERBS.has(token)) continue // an option or a runner verb
    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) continue // `env FOO=1 …`'s assignments
    const base = baseName(token)
    if (!base) continue
    if (NEVER_A_BINARY.has(base)) return null
    if (RUNNERS.has(base) || INTERPRETERS.has(base) || base === 'env') continue
    // Strip an npm version specifier, but never a leading scope: `@acme/x@1` → `x`, `@acme` → `@acme`.
    const at = base.lastIndexOf('@')
    return at > 0 ? base.slice(0, at) : base
  }
  return null
}

/**
 * The binary names to expect for an agent id — built-in from the table, custom from its launch
 * command.
 *
 * Without this a `custom:<uuid>` agent has no entry, `isAgentPane` answers `unknown`, and because
 * `unknown` means "the caller may retry", a delivery gate refuses that pane on every attempt
 * forever behind a retryable-looking error. That is a dead end wearing a transient error's clothes.
 * The information to avoid it already exists — `resolveAgent`
 * (`src/renderer/state/workspace.ts`) resolves exactly this `launchCmd`, and falls back to the
 * agent id itself for an id it does not know, which is mirrored here.
 *
 * A custom agent with a BLANK launch command and a builtin `baseAgent` answers that base's binaries,
 * because that is what `resolveAgentConfig` launches (`launchCmd.trim() || base.launchCmd`).
 *
 * Still null (⇒ `unknown`, ⇒ refuse) in the three cases where no honest answer exists: a
 * `custom:<uuid>` whose definition is not in the list handed to us; a launch command whose program
 * cannot be named without naming something every plain shell also runs; and a blank (or non-string)
 * launch command with no valid builtin `baseAgent`. Null is a refusal, not a guess — but a caller
 * holding the settings can now avoid it for every configured agent.
 *
 * `customAgents` is structural rather than `CustomAgent[]` so this stays a leaf module.
 */
export function binariesFor(
  agentId: string,
  customAgents?: readonly { id: string; launchCmd: string; baseAgent?: string }[]
): readonly string[] | null {
  // Own property only: `constructor` / `__proto__` / `toString` must not resolve to a prototype
  // member — an agent id is hand-editable (project.json, settings.json).
  const builtin = Object.prototype.hasOwnProperty.call(AGENT_BINARIES, agentId)
    ? AGENT_BINARIES[agentId]
    : undefined
  if (builtin) return builtin
  // Settings are hand-editable JSON: a null / non-object entry is skipped, never dereferenced.
  const custom = customAgents?.find((c) => !!c && typeof c === 'object' && c.id === agentId)
  if (custom) {
    // A BLANK command with a base harness runs the base's own command — `resolveAgentConfig`
    // (`shared/agents/custom-agent.ts`) resolves `launchCmd.trim() || base.launchCmd`, so the pane
    // runs e.g. `claude`, and that is what argv will show. Without this the most common custom shape
    // (a claude-compatible proxy configured by env alone) was unverifiable on every surface. Own
    // property only: `baseAgent` is hand-editable JSON, and `constructor` must not index the table.
    // Hand-editable JSON: a non-string command is treated as blank, never dereferenced (a number
    // here used to throw inside the desktop gates). `mirrorCustomAgents` coerces the same way.
    const launchCmd = typeof custom.launchCmd === 'string' ? custom.launchCmd : ''
    if (!launchCmd.trim()) {
      const base = custom.baseAgent
      return base && Object.prototype.hasOwnProperty.call(AGENT_BINARIES, base) ? AGENT_BINARIES[base] : null
    }
    const name = binaryFromLaunchCmd(launchCmd)
    return name ? [name] : null
  }
  // A `custom:` id we were given no definition for is unknowable — deriving from the id would yield
  // `custom:<uuid>`, a name that matches nothing, i.e. `not-agent`: a terminal answer to a question
  // we never actually asked. Anything else is treated as its own launch command, which is what
  // resolveAgent does for an agent id it does not recognise.
  if (agentId.startsWith('custom:')) return null
  const name = binaryFromLaunchCmd(agentId)
  return name ? [name] : null
}

/**
 * POSITIVE and kernel-truth, replacing `!isShellCommand(pane)`, which was neither.
 *
 * The old gate asked a persisted field what the pane SHOULD be running. `agentId` is durable and
 * outlives the CLI, so a plain terminal whose claude exited weeks ago still read as an agent — and
 * `isShellCommand` was then a SEVEN-NAME allowlist (zsh/bash/sh/fish/dash/ksh/tcsh), so `nu`, `pwsh`,
 * `xonsh`, `ssh` and `python` all fell through its negation and were admitted as agents. Text
 * delivered to any of those EXECUTES, because sendText appends Enter.
 *
 * `unknown` is a third answer, not a shade of `not-agent`, because the two need different replies:
 * `unknown` means the probe failed and the caller may retry; `not-agent` means the kernel answered
 * and the answer was no.
 *
 * Matched on the BASENAME of argv[0] (after interpreter resolution), never on a substring of the
 * command line — `vim /etc/claude.conf` and `grep -r claude .` are not claude panes.
 *
 * `binaries` overrides the derived list. A caller holding the settings should pass
 * `binariesFor(agentId, settings.customAgents)` so a CUSTOM agent is verifiable too; without it a
 * `custom:<uuid>` cannot be named and answers `unknown`, which is a refusal, not a licence.
 *
 * ── WHAT THIS DOES NOT PROVE (carry into the delivery gate) ─────────────────────────────────────
 *
 *  1. **It proves the agent is IN the foreground process group, not that it is the thing READING
 *     the tty.** `sh -c "sleep 600 | claude"` answers `agent`, and correctly so — claude really is
 *     in the group. But claude's stdin is the PIPE, so text written to the pane sits in the tty
 *     buffer until the shell reads it after the pipeline exits. That is the "rename splice = lost
 *     launch" shape: the write succeeds and the payload surfaces later, somewhere else. A gate that
 *     needs "the agent is reading" needs a further check; this predicate is not it.
 *  2. **Two false negatives are terminal and deliberate**, documented rather than fixed because the
 *     alternative is guessing: a script path containing a SPACE (the argv split cannot tell it from
 *     two tokens), and a differently-named SYMLINK to the agent binary (argv carries the name it
 *     was invoked as, not the target). Both answer `not-agent` — a refusal, which is the safe
 *     direction.
 *
 * `isShellCommand` is deliberately NOT deleted — its existing callers (the restart exit poll, the
 * reconnect resync) ask a genuinely different question ("has the CLI let go of the pane?") for
 * which a shell allowlist is the right shape.
 */
export function isAgentPane(
  owner: PaneOwner | null | undefined,
  expected: string,
  binaries?: readonly string[] | null
): AgentPaneVerdict {
  if (!owner) return 'unknown'
  if (!owner.argv || owner.argv.length === 0) return 'unknown'
  const wanted = binaries ?? binariesFor(expected)
  if (!wanted || wanted.length === 0) return 'unknown'
  for (const line of owner.argv) {
    if (wanted.includes(effectiveBinary(line))) return 'agent'
  }
  return 'not-agent'
}

/**
 * The PID of the agent process this pane's verdict rests on — the identity `isAgentPane` finds but
 * throws away.
 *
 * It exists because "an agent owns this pane" is not the same claim as "the SAME agent owns this
 * pane", and a delivery's post-write re-verify needs the second one. The failure it closes is
 * ordinary rather than exotic:
 *
 *   pane root = bash(1000), claude(2000) in the foreground group  → we write
 *   claude exits before reading; bash reads the pasted lines and EXECUTES them
 *   a wrapper (`while :; do claude; done`) starts claude(2100)
 *   post-probe: same tty, same pane_pid (bash is the pane's ROOT process), an agent in the group
 *
 * On name alone that reads as "unchanged", and the delivery is reported as `delivered` when the body
 * in fact ran as shell commands. The pid moved, so the pid is what has to be compared.
 *
 * `null` when the pane is not an agent's, when the read carries no `pids` (an older read — treat it
 * as unknown, never as unchanged), or when the matching row has no pid.
 */
export function agentPidIn(
  owner: PaneOwner | null | undefined,
  expected: string,
  binaries?: readonly string[] | null
): number | null {
  if (!owner || !owner.argv || !owner.pids) return null
  const wanted = binaries ?? binariesFor(expected)
  if (!wanted || wanted.length === 0) return null
  for (let i = 0; i < owner.argv.length; i++) {
    if (!wanted.includes(effectiveBinary(owner.argv[i]))) continue
    const pid = owner.pids[i]
    return typeof pid === 'number' && pid > 0 ? pid : null
  }
  return null
}