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.6 KB
Raw Blame
// WHICH CANVAS answers a canvas-control request — the routing half of the `nodeterm` CLI's
// authorization boundary (Canvas's onAgentControl effect). Pure, so it is unit-testable where the
// React component is not (vitest runs in the node environment); same reasoning as presenceTravel,
// whose project-travel rules this reuses.
//
// WHY IT EXISTS: React Flow only ever holds the ACTIVE project's nodes, but tmux sessions of every
// OTHER open project keep running — they survive an app restart and are re-adopted on boot. Their
// agents still hold NODETERM_CANVAS_CONTROL and still reach the (rewritten) hook endpoint, so their
// control calls arrive at a canvas that has never heard of the source node. Looking the source up
// in the live canvas alone therefore rejected every agent outside the project the app happened to
// come up on — reported as "source node is not a control-capable agent", which is what a node
// carrying a non-control agent gets, so the failure read as a lost capability rather than as the
// wrong canvas answering. Resolve the OWNING project instead, then travel to it (or, for a verb
// that reads and changes nothing, answer straight out of its serialized nodes).

import { canControlCanvas, type AgentId } from '@shared/agents/config'
import { formatIssueRef } from '@shared/github-issue-ref'
import { formatPrWaits, normalizePrWaitHold } from '@shared/pr-wait'
import {
  normalizeSuccessWaitHold,
  outcomeOf,
  successWaitStatus,
  successWaitSummary,
  type StationOutcomeRecord
} from '@shared/station-outcome'
import { prHoldExpired } from './prWait'
import {
  controlLaunchState,
  handedOverDeps,
  holdReason,
  successDepFacts,
  type HandoverById,
  type LaunchDelivery,
  type StatusById
} from './pendingLaunch'
import { projectTravel } from './presenceTravel'
import { geometryText, storedNodeGeometry, type NodeGeometry } from './nodeGeometry'
import {
  projectCapabilityGrantedFor,
  type CapabilityAckMap
} from '@shared/project-capability-consent'

/** The little the routing needs to know about a project (a structural subset of `Project`). */
export interface ControlProject {
  id: string
  closed?: boolean
  unavailable?: boolean
  nodes: readonly { id: string }[]
}

/** A serialized node, as the projects store keeps them for non-active projects. */
export interface StoredNode {
  id: string
  kind?: string
  title?: string
  pendingLaunch?: unknown
  agentId?: string
  /** The GitHub issue the session was started on — hostile until `formatIssueRef` says otherwise. */
  issueRef?: unknown
  /** Persisted geometry (`CanvasNodeState`): an off-screen project's rows derive their place and
   *  size from these (`storedNodeGeometry`). */
  position?: { x: number; y: number }
  size?: { width: number; height: number }
  parentId?: string
  collapsed?: boolean
  /** Precomputed by the LIVE canvas (`liveNodeGeometry` — measured sizes); wins over the fields above. */
  geometry?: NodeGeometry
}

/**
 * Where a control request must be applied:
 * - `active`  — the source is on the live canvas (or its project is already active): apply here.
 * - `switch`  — an open project's canvas: activate that tab first.
 * - `reopen`  — a closed project (its sessions still run): restore the tab, then activate it.
 * - `blocked` — a project whose files are unreadable: travelling there would show an empty canvas.
 * - `unknown` — no open project owns this node id.
 */
export type ControlRoute =
  | { kind: 'active' }
  | { kind: 'switch'; projectId: string }
  | { kind: 'reopen'; projectId: string }
  | { kind: 'blocked'; projectId: string }
  | { kind: 'unknown' }

/** Which project owns `sourceNodeId`, and what Canvas must do to be able to act on it. */
export function routeControlSource(
  projects: readonly ControlProject[],
  activeProjectId: string,
  sourceNodeId: string
): ControlRoute {
  const owner = projects.find((p) => p.nodes.some((n) => n.id === sourceNodeId))
  if (!owner) return { kind: 'unknown' }
  const travel = projectTravel(
    projects.map((p) => ({ id: p.id, closed: p.closed, unavailable: p.unavailable, nodes: [] })),
    activeProjectId,
    owner.id
  )
  // `none` means "already there" — the live canvas is the right one even if its store copy lags.
  if (travel.kind === 'none') return { kind: 'active' }
  if (travel.kind === 'blocked') return { kind: 'blocked', projectId: owner.id }
  return travel
}

/**
 * The off-screen verb table lives in `@shared/control-off-screen` because CORE renders the
 * agent-facing help from it and core cannot import the renderer. Re-exported here so every
 * renderer caller keeps one import for "how does canvas control route".
 */
export {
  needsLiveCanvas,
  canColdOpen,
  answersOffCanvas,
  answersFromStoredNodes,
  offScreenDisposition,
  offScreenRefusal,
  offScreenGuidanceLines,
  controlVerbSetsForTests,
  type OffScreenDisposition
} from '@shared/control-off-screen'

/**
 * The capability half of the guard: may a session in this node drive the canvas?
 *
 * Plain terminals are not agent nodes. Treating missing identity as Claude made a bare shell look
 * control-capable and let recovery code relabel it as an agent. A hand-launched CLI is still
 * observable through its runtime hooks, but the serialized node does not gain agent authority.
 */
export function sourceIsControlCapable(agentId: unknown): boolean {
  return typeof agentId === 'string' && agentId.length > 0 && canControlCanvas(agentId as AgentId)
}

/**
 * The `browser` verb's resolve answer — the two things ONLY the renderer knows, computed purely so
 * Canvas.tsx's IPC handler is a thin wrapper testable here. Main asks over `browserControlResolve`,
 * makes the security decision itself (owner + capability + CDP gate), and does the CDP work; this
 * function NEVER touches a debugger.
 *
 * WHY MAIN STILL DECIDES from these facts: an XSS-in-a-node-title-style bug lands in the renderer,
 * the more attackable half, so the allowlist and the ledger stay main-side. The renderer reports
 * facts (does this node's project exist, is the source control-capable, is the capability on right
 * now — read LIVE via `projectCapabilityGrantedFor`, never cached); main re-orders them into the
 * refusal decision in `browser-drive.ts`.
 */
export interface BrowserResolveNode {
  id: string
  agentId?: unknown
  /** The node's display title — reported so main can make the cookie-read trace human-readable
   *  (PR 9). Never a security input. */
  title?: string
}
export interface BrowserResolveProject {
  id: string
  cwd?: string
  agentBrowserControl?: boolean
  capabilityAck?: CapabilityAckMap
  nodes: readonly BrowserResolveNode[]
}
export type BrowserResolveAnswer =
  | { ok: false; refusal: string }
  | {
      ok: true
      projectId: string
      projectCwd?: string
      sourceControlCapable: boolean
      capabilityOn: boolean
      /** The owner (source) agent node's title and the driven browser node's title — for the cookie
       *  trace only. Empty string when unknown; main falls back to the node id. */
      sourceTitle: string
      browserTitle: string
    }

export function answerBrowserResolve(
  project: BrowserResolveProject | undefined,
  sourceNodeId: string,
  browserNodeId?: string
): BrowserResolveAnswer {
  // No open project owns the source, or the node is not on its canvas: a named, non-revoking
  // refusal. (Same class as every other verb's "source node is not on an open canvas".)
  if (!project) return { ok: false, refusal: 'source node is not on an open canvas' }
  const node = project.nodes.find((n) => n.id === sourceNodeId)
  if (!node) return { ok: false, refusal: 'source node is not on an open canvas' }
  const browserNode = browserNodeId ? project.nodes.find((n) => n.id === browserNodeId) : undefined
  return {
    ok: true,
    projectId: project.id,
    projectCwd: project.cwd,
    sourceControlCapable: sourceIsControlCapable(node.agentId),
    // LIVE read — the drive-time capability check the whole feature's safety rests on. A project.json
    // hand-edit that flipped the switch off is reflected here the next time an agent drives, which is
    // exactly drive time.
    // `{}`: browser control has no machine default (CAPABILITY_MACHINE_DEFAULTS) — an absent switch is
    // off, and no setting on this machine can change that.
    capabilityOn: projectCapabilityGrantedFor(project, 'agentBrowserControl', {}),
    sourceTitle: typeof node.title === 'string' ? node.title : '',
    browserTitle: typeof browserNode?.title === 'string' ? browserNode.title : ''
  }
}

/** `list`'s rows, built from serialized nodes — the same shape the live canvas answers with
 *  (`n.type` is the persisted `kind`, `n.data.title` the persisted `title`). */
export function storedNodeListing(
  nodes: readonly StoredNode[],
  statuses: StatusById & Record<string, { dropped?: boolean } | undefined> = {},
  deliveries: Record<string, LaunchDelivery | undefined> = {},
  now: number = Date.now(),
  /** Every station's latest task report (`report-outcome`, core's store mirrored). */
  outcomes: Readonly<Record<string, StationOutcomeRecord>> = {},
  /** Stations with unfinished handed-over work (core/station-handover.ts, mirrored). */
  handovers: HandoverById = {}
) {
  const live = new Set(nodes.map((n) => n.id))
  // Every row carries its geometry (issue #1288), so a script needs no flag to read it; the TEXT form
  // shows it only behind `list --geometry on`. A row of the live canvas arrives with it measured; a
  // stored row's is derived here from the persisted fields, parent chain included.
  const placed = nodes.filter(
    (n): n is StoredNode & { position: { x: number; y: number }; size: { width: number; height: number } } =>
      !!n.position && !!n.size
  )
  const geometryOf = (n: StoredNode): NodeGeometry | undefined =>
    n.geometry ?? (n.position && n.size ? storedNodeGeometry({ ...n, position: n.position, size: n.size }, placed) : undefined)
  const titleOf = (id: string): string => {
    const t = nodes.find((n) => n.id === id)?.title
    return t ? `${id} "${t}"` : id
  }
  return nodes.map((n) => {
    const status = statuses[n.id]
    // `--after-pr`: the row names what the node waits on (the pull request STATUS is the canvas's
    // to judge; `list` states the wait and whether its deadline has passed, which needs no board).
    const prHold = normalizePrWaitHold((n.pendingLaunch as { afterPr?: unknown } | undefined)?.afterPr)
    const prExpired = !!prHold && prHoldExpired(prHold, now)
    // `--after-success`: judged here in full — every fact it needs (the stations' reports, their
    // turn state, whether they still exist) is already in hand, so the row can say WAITING FOR
    // SUCCESS, BLOCKED BY FAILURE or EXPIRED and name the station and its note.
    const successHold = normalizeSuccessWaitHold(
      (n.pendingLaunch as { afterSuccess?: unknown } | undefined)?.afterSuccess
    )
    const successFacts = (d: string) =>
      successDepFacts(d, statuses, live, outcomes, handovers)
    const successState = successHold ? successWaitStatus(successHold, successFacts, now) : undefined
    // Every agent row names its state: an unlabelled row used to mean idle, waiting on a person, or
    // not an agent at all, so an orchestrator read a station stuck on a permission prompt as finished.
    const launchState = controlLaunchState(!!n.pendingLaunch, deliveries[n.id] ?? ((n.pendingLaunch as { manualOnly?: boolean } | undefined)?.manualOnly ? { kind: 'failed', attempts: 1, at: 0 } : undefined), status, prExpired, successState) ??
      (n.agentId ? agentRowState(status?.state) : undefined)
    // A session started on an issue is told so on its OWN row, so `list` is enough for an agent to
    // learn it is bound (and which card to move). Only a reference `formatIssueRef` vouches for.
    const issue = formatIssueRef(n.issueRef)
    // What this node said about its OWN task, if anything — so an orchestrator reads every
    // station's verdict in the one call it already makes.
    const reported = outcomeOf(outcomes, n.id)
    const successWait =
      successHold && !successHold.invalid && successState !== 'met'
        ? successWaitSummary(successHold, successFacts, titleOf)
        : undefined
    // Plain `--after` deps whose `done` is from BEFORE the work just handed to them: named, so an
    // orchestrator reading QUEUED next to a station that reads idle knows what it is waiting for.
    // (`pendingLaunch` is unvalidated here: only a list of strings is read.)
    const rawAfter = (n.pendingLaunch as { after?: unknown } | undefined)?.after
    const handedOver = Array.isArray(rawAfter)
      ? handedOverDeps(
          {
            id: n.id,
            data: {
              pendingLaunch: {
                after: rawAfter.filter((d): d is string => typeof d === 'string'),
                command: ''
              }
            }
          },
          live,
          handovers
        )
      : []
    const geometry = geometryOf(n)
    return {
      id: n.id, kind: n.kind ?? 'terminal', title: n.title ?? '',
      ...(geometry ?? {}),
      ...(issue ? { issue } : {}),
      ...(status?.lastTurnError ? { lastTurnErrored: true } : {}),
      ...(status?.lastTurnInterrupted && !status.lastTurnError ? { lastTurnInterrupted: true } : {}),
      ...(launchState ? { launchState } : {}),
      ...(launchState === 'queued' && prHold && !prHold.invalid ? { prWait: formatPrWaits(prHold) } : {}),
      ...(successWait ? { successWait } : {}),
      ...(handedOver.some((d) => holdReason(handovers[d]) === 'work')
        ? { handoverWait: handedOver.filter((d) => holdReason(handovers[d]) === 'work').map(titleOf).join(', ') }
        : {}),
      ...(handedOver.some((d) => holdReason(handovers[d]) === 'background')
        ? { backgroundWait: handedOver.filter((d) => holdReason(handovers[d]) === 'background').map(titleOf).join(', ') }
        : {}),
      ...(reported
        ? {
            outcome: reported.outcome,
            ...(reported.note ? { outcomeNote: reported.note } : {}),
            ...(reported.workPending ? { outcomeSuperseded: true } : {})
          }
        : {})
    }
  })
}

/** An agent row with no launch or drop to report: its live state, in the canvas badge's words. */
function agentRowState(state: string | undefined): 'idle' | 'needs-you' | 'unconfirmed' {
  if (state === 'done') return 'idle'
  if (state === 'waiting' || state === 'blocked') return 'needs-you'
  return 'unconfirmed'
}

const launchLabels = {
  idle: 'IDLE',
  'needs-you': 'NEEDS YOU',
  queued: 'QUEUED',
  failed: 'LAUNCH FAILED',
  stalled: 'QUEUED (terminal not ready)',
  starting: 'STARTING',
  'brief-missing': 'HELD (its prompt file no longer exists; run it with `run` to start without it)',
  dropped: 'DROPPED',
  working: 'WORKING',
  unconfirmed: 'AGENT STATUS UNCONFIRMED',
  expired: 'EXPIRED (PR wait deadline passed; run it with `run`)',
  'success-expired': 'EXPIRED (success wait deadline passed; run it with `run`)',
  'waiting-success': 'WAITING FOR SUCCESS',
  'blocked-failure': 'BLOCKED BY FAILURE (will not start on its own; run it with `run`)'
} as const

/** The `--geometry on` suffix of one row (`storedNodeListing` spreads the geometry flat), or '' for a
 *  row that has none. */
function rowGeometryText(n: ReturnType<typeof storedNodeListing>[number]): string {
  const g = n as Partial<NodeGeometry>
  if (typeof g.x !== 'number' || typeof g.y !== 'number' || typeof g.width !== 'number' || typeof g.height !== 'number') {
    return ''
  }
  return geometryText({ x: g.x, y: g.y, width: g.width, height: g.height, parent: g.parent ?? null, collapsed: g.collapsed, expandedHeight: g.expandedHeight })
}

/** `list`'s text answer. `geometry` (`list --geometry on`) adds each node's place and size; off by
 *  default so the line an agent reads most stays short. */
export function controlListingText(
  rows: ReturnType<typeof storedNodeListing>,
  opts: { geometry?: boolean } = {}
): string {
  return rows.map((n) => `${n.id} [${n.kind}] ${n.title}` +
    (opts.geometry ? rowGeometryText(n) : '') +
    (n.issue ? ` — issue ${n.issue}` : '') +
    (n.launchState ? ` — ${launchLabels[n.launchState]}` : '') +
    (n.prWait ? ` — waits on ${n.prWait}` : '') +
    (n.successWait ? ` — needs success from: ${n.successWait}` : '') +
    (n.handoverWait ? ` — waiting for ${n.handoverWait} to finish the work handed to it` : '') +
    (n.backgroundWait ? ` — waiting for ${n.backgroundWait} to finish the tasks still running in its background` : '') +
    (n.outcome ? ` — REPORTED ${n.outcome === 'succeeded' ? 'SUCCESS' : 'FAILURE'}${n.outcomeNote ? ` ("${n.outcomeNote}")` : ''}` : '') +
    (n.outcomeSuperseded ? ' (before new work queued for it; not counted until it reports again)' : '') +
    (n.lastTurnErrored ? ' — LAST TURN ERRORED' : '') +
    (n.lastTurnInterrupted ? ' — LAST TURN INTERRUPTED' : '')
  ).join('\n')
}