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.

18.8 KB
Raw Blame
import fs from 'node:fs'
import path from 'node:path'

import {
  createDeliveryQueue,
  deliverFromControl,
  deliverStationNotice,
  messagingEnabledVia,
  onMessagingAgentEvent,
  ptyPaneProbeDeps,
  restoreDeliveryQueue,
  type AgentMessagingDeps
} from '../core/agents/agent-messaging'
import { paneOwnerProject } from '../core/agents/pane-ownership'
import { StationNoticeMonitor } from '../core/agents/station-notice'
import {
  StationOutcomeStore,
  clearOutcomesAfterControl,
  handleReportOutcome,
  OUTCOME_FACT
} from '../core/station-outcome-store'
import { DurableFactFile } from '../core/durable-state'
import { QUEUE_FACT } from '../core/agents/delivery-queue'
import { HANDOVER_FACT, StationHandoverTracker } from '../core/station-handover'
import { stationRecipientFromOwner } from '../shared/station-notice'
import {
  mirrorEntry,
  nodeState
} from '../core/agent-status-mirror'
import type { BoardLogHandlers } from '../core/board-log-handlers'
import { buildControlShimScript } from '../core/canvas-control-core'
import { syncWindowsShLauncher } from '../core/agents/hooks/install-helper'
import { codexIdentityCaps } from '../core/codex-identity-caps'
import { codexThreadIdentityRoot } from '../core/codex-identity-proxy'
import { claudeCliCaps, type ClaudeCliCaps } from '../core/claude-cli'
import { grokCliCaps } from '../core/grok-cli'
import { codexCliCaps } from '../core/codex-cli'
import type { CodexCliCaps, GrokCliCaps } from '../shared/types'
import { platform } from '../core/platform'
import type { PtyManager } from '../core/pty-manager'
import type { WorkspaceStore } from '../core/workspace-store'
import type { NormalizedAgentEvent } from '../shared/agents/normalize'
import { IPC } from '../shared/ipc'
import type { Project, Settings } from '../shared/types'
import {
  createServerEditionControlHandler,
  type ServerEditionControlActions
} from './control-unsupported'
import { HeadlessNodeFactory } from './headless-node-factory'
import { sendSettledEnvelope } from './settled-envelope'
import { serverSettingsControl } from './settings-control'
import {
  answerGitHubRead,
  resolveGitHubReadProject,
  type GitHubReadDeps
} from '../core/github/control-read'

export interface ServerCanvasControlDeps {
  workspaceStore: WorkspaceStore
  ptyManager: PtyManager
  settings(): Settings
  boardLog: BoardLogHandlers
  cliCaps?: () => Promise<ClaudeCliCaps>
  /** grok's own `--session-id` probe; defaults to the real one. See HeadlessNodeFactoryDeps. */
  grokCaps?: () => Promise<GrokCliCaps>
  codexCaps?: () => Promise<CodexCliCaps>
  /** Test seam for the boot-populated shared Codex capability answer. */
  codexSharedIdentity?: () => Promise<boolean>
  /** The `owner/repo` a project's kanban board syncs with (the GitHub host controller's answer) —
   *  what `open-agent --issue #N` resolves against. Absent = only an explicitly configured
   *  repository counts. See HeadlessNodeFactoryDeps.issueRepository. */
  issueRepository?: (projectId: string) => Promise<string | null>
  /** The GitHub service's cache reads behind `issues` / `prs` (core/github/control-read.ts).
   *  Absent = those verbs answer that the GitHub lane is unavailable here. */
  githubRead?: Pick<GitHubReadDeps, 'snapshot' | 'dispatch'>
  /**
   * Does this process own the hook endpoint (`hookServer.startForApp()` returned no warning)? The
   * durable orchestration facts (queue, station reports, hand-over holds) belong to the owning
   * instance, like the request ledger: a second instance on the same data dir must neither restore
   * them nor overwrite their files. Absent = owns (every test, and a caller that did not ask).
   */
  ownsDurableState?: boolean
}

export interface ServerCanvasControl {
  handler: ReturnType<typeof createServerEditionControlHandler>
  onAgentEvent(event: NormalizedAgentEvent): void
  /** Station-failure notices for the stations agents opened during THIS server run. */
  stationNotices: StationNoticeMonitor
  /** What each station reported about its own task in THIS server run (`report-outcome`). */
  stationOutcomes: StationOutcomeStore
  /** Stations with unfinished handed-over work in THIS server run (plain `--after` holds on them). */
  stationHandovers: StationHandoverTracker
  stop(): void
}

function canvasControlDir(): string {
  return path.join(platform().userDataDir, 'canvas-control')
}

function shimPath(): string {
  return path.join(canvasControlDir(), 'nodeterm.sh')
}

function writeShim(): void {
  const dir = canvasControlDir()
  fs.mkdirSync(dir, { recursive: true })
  fs.writeFileSync(shimPath(), buildControlShimScript(codexThreadIdentityRoot()), 'utf8')
  try {
    fs.chmodSync(shimPath(), 0o755)
  } catch {
    /* best effort on filesystems without POSIX modes */
  }
  // The `.cmd` launcher the skill names on a Windows host (skillsFor picks that dialect from this
  // core's platform); a no-op removal on the Linux hosts the Server Edition targets.
  syncWindowsShLauncher(dir, 'nodeterm.sh')
  // Same upgrade sweep as desktop: the POSIX shim replaced this Electron-as-Node script.
  try {
    fs.rmSync(path.join(dir, 'canvas-control-cli.mjs'), { force: true })
  } catch {
    /* best effort */
  }
}

/** The canvas-control shim under the server dataDir (what the canvas skill points at). */
export function serverCanvasShimPath(): string {
  return shimPath()
}

/**
 * Boot the Server Edition canvas runtime.
 *
 * The shim itself always lives under the configured server dataDir, never under a hard-coded
 * `~/.nodeterm-server`. Its discovery skill is the consent lifecycle's (core/agent-integrations.ts,
 * issue #744), which also honours `installHooks: false` as a veto.
 */
export async function initServerCanvasControl(
  deps: ServerCanvasControlDeps
): Promise<ServerCanvasControl> {
  try {
    writeShim()
  } catch (error) {
    // The HTTP runtime remains useful even if discovery files cannot be written; fail open and loud.
    console.warn('[server-canvas-control] shim install failed', error)
  }

  // Station task outcomes: built before the factory, which reads them for `--after-success`.
  // Durable across a server restart, each report bound to the session that made it — the same
  // store, file and rules as the desktop (core/station-outcome-store.ts). The status mirror is
  // already restored (server/index.ts runs `initAgentStatusMirror` first), so load it here.
  const outcomesFile = new DurableFactFile(OUTCOME_FACT, { userDataDir: platform().userDataDir })
  const stationOutcomes = new StationOutcomeStore(
    (records) => platform().broadcast(IPC.stationOutcomeChanged, records),
    {
      durable: outcomesFile,
      sessionOf: (id) => {
        const m = mirrorEntry(id)
        return m ? { sessionId: m.sessionId, agentId: m.agentId } : undefined
      }
    }
  )
  // Stations with unfinished handed-over work (core/station-handover.ts): built before the factory,
  // whose plain `--after` holds on them — the same tracker, fed the same events, as the desktop.
  // Every change re-evaluates the factory's arms: a hold can end on an event `refreshArmed` is not
  // otherwise run for (a SessionEnd clearing a background-subagent hold). `factory` is assigned
  // below, before any event can reach the tracker. Durable like the reports; loaded in the same
  // order as the desktop (reports, hand-overs, queue).
  let factoryRef: HeadlessNodeFactory | undefined
  const handoversFile = new DurableFactFile(HANDOVER_FACT, { userDataDir: platform().userDataDir })
  const stationHandovers = new StationHandoverTracker(
    (records) => {
      platform().broadcast(IPC.stationHandoverChanged, records)
      void factoryRef?.refreshArmed()
    },
    Date.now,
    handoversFile
  )
  if (deps.ownsDurableState === false) {
    outcomesFile.standDown()
    handoversFile.standDown()
  }
  stationOutcomes.loadFromDisk()
  stationHandovers.loadFromDisk()
  const factory = new HeadlessNodeFactory({
    workspaceStore: deps.workspaceStore,
    ptyManager: deps.ptyManager,
    settings: deps.settings,
    cliCaps: deps.cliCaps ?? claudeCliCaps,
    // grok answers with its own probe — see HeadlessNodeFactoryDeps.grokCaps.
    grokCaps: deps.grokCaps ?? grokCliCaps,
    // …and so does codex, for the same reason: its `--ask-for-approval` vocabulary is its own and
    // it MOVED (see HeadlessNodeFactoryDeps.codexCaps). The Server Edition runs its Codex sessions
    // on this host's `codex`, so this probe is the right authority for them.
    codexCaps: deps.codexCaps ?? codexCliCaps,
    codexSharedIdentity:
      deps.codexSharedIdentity ?? (() => codexIdentityCaps().then((caps) => caps.shared)),
    stateOf: nodeState,
    agentIdOf: (nodeId) => mirrorEntry(nodeId)?.agentId,
    outcomeOf: (nodeId) => stationOutcomes.get(nodeId),
    handedOver: (nodeId) => stationHandovers.isHandedOver(nodeId),
    // NOT `workspaceExternalChange`. That channel means "somebody else wrote this file" and the
    // renderer answers it with `decideExternalChange`, which compares the whole project shell —
    // and `ropes` is part of it, so every headless spawn (one appended `ctrl-…` rope) read as a
    // conflict while the canvas was dirty, which it almost always is mid-burst. The bar that came
    // up suspends autosave, so it latched on, and "Keep my version" then wrote the browser's edge
    // state over the ropes this factory had just persisted. These writes are OURS; the renderer
    // merges them (renderer/lib/serverChange.ts) and is never asked to choose.
    // The CONTENT of each write (nodes, edges) travels separately, as canvas ops the factory casts
    // through the reflector BEFORE every save (its `castAndSave`; no `publishMutation` here = the
    // reflector). On a project the canvas authority governs, only what it heard as ops is written.
    publishProject: (project: Project) => platform().broadcast(IPC.workspaceServerChange, project),
    issueRepository: deps.issueRepository,
    // An issue card's run history lives in the same board log the messaging trace writes to.
    appendBoardLog: (projectId, entry) => deps.boardLog.append(projectId, entry)
  })

  factoryRef = factory

  const messaging: AgentMessagingDeps = {
    ...ptyPaneProbeDeps(deps.ptyManager),
    // Server delivery has no renderer/xterm echo stream. Capture the headless pane instead and
    // separate paste from Enter so a fresh TUI cannot swallow the first submit keystroke.
    sendEnvelope: (nodeId, envelope) =>
      sendSettledEnvelope(deps.ptyManager, nodeId, envelope),
    // Attached OR released-but-running: see AgentMessagingDeps.hasLiveSession.
    hasLiveSession: (nodeId) => deps.ptyManager.sessionExists(nodeId),
    mirrorEntry,
    projects: () => deps.workspaceStore.persistedCanvases(),
    isRemoteNode: () => false,
    messagingEnabled: messagingEnabledVia(
      (projectId) => deps.workspaceStore.capabilityProjectFor(projectId),
      // The SAME machine default the desktop reads — this shell's own settings.json.
      () => deps.settings()
    ),
    paneOwnerProject,
    heldLaunch: (projectId, nodeId) => deps.workspaceStore.heldLaunch(projectId, nodeId),
    callerOwnsTarget: (sourceNodeId, targetNodeId) =>
      factory.ownsSpawn(sourceNodeId, targetNodeId),
    customAgents: () => deps.settings().customAgents,
    appendBoardLog: (projectId, entry) => deps.boardLog.append(projectId, entry),
    // A `send` / `reply` hands a station new work when it REACHES the pane (queued ⇒ "work pending"
    // until it lands) — the same rule, and the same store method, as the desktop.
    onHandover: (ev) => {
      stationOutcomes.onHandover(ev)
      stationHandovers.onHandover(ev)
    }
  }
  // Durable, like the desktop's (delivery-queue.ts states what a restart does to a message). Note
  // this edition's creator ledger is process-local, so a restored message whose caller→target proof
  // did not survive the restart is refused `caller-not-owner` at flush — with its sender told.
  const queueFile = new DurableFactFile(QUEUE_FACT, { userDataDir: platform().userDataDir })
  if (deps.ownsDurableState === false) queueFile.standDown()
  const queue = createDeliveryQueue(messaging, { durable: queueFile })
  messaging.queue = queue

  // Station-failure notices. The recipient is the CREATOR LEDGER's answer — who opened the station
  // during this server run — which is this edition's ownership rule for every verb; a restart
  // clears it, so a station opened before one has nobody to tell. The pane leg is the same
  // messaging service `send` uses (creator check reversed: the recipient must have opened the
  // station), and the canvas leg is the board log plus a push to every attached browser tab.
  // DROPPED arrives only from a browser tab that shows the node (its liveness check); a server with
  // no tab attached reports errored and long-blocked stations only.
  // Shared with `report-outcome --notify-opener` (#1356): same recipient, same delivery.
  const opener = {
    recipientFor: (stationNodeId: string) =>
      stationRecipientFromOwner(
        deps.workspaceStore.persistedCanvases(),
        stationNodeId,
        factory.openerOf(stationNodeId)
      ),
    deliver: (notice: Parameters<typeof deliverStationNotice>[0]) =>
      deliverStationNotice(notice, messaging)
  }
  const stationNotices = new StationNoticeMonitor({
    now: () => Date.now(),
    recipientFor: opener.recipientFor,
    pendingQuestionOf: (nodeId) => mirrorEntry(nodeId)?.pendingQuestion?.toolUseId,
    appendBoardLog: (projectId, entry) => deps.boardLog.append(projectId, entry),
    deliver: opener.deliver,
    publish: (views) => platform().broadcast(IPC.stationNoticeChanged, views),
    exists: (nodeId) => deps.workspaceStore.projectIdsForNode(nodeId).length > 0
  })
  stationNotices.start()
  messaging.onQueuedResult = (req, outcome) => stationNotices.onQueuedResult(req, outcome)
  // Every listener is wired: bring back what the previous run queued.
  await restoreDeliveryQueue(queue, queueFile)

  const actions: ServerEditionControlActions = {
    openProject: (sourceNodeId, args, verified) =>
      factory.openProject(sourceNodeId, args, verified),
    openTerminal: (sourceNodeId, args, verified) =>
      factory.openTerminal(sourceNodeId, args, verified),
    openAgent: (sourceNodeId, args, verified) => factory.openAgent(sourceNodeId, args, verified),
    close: (sourceNodeId, args, verified) => factory.close(sourceNodeId, args, verified),
    link: (sourceNodeId, args, verified) => factory.link(sourceNodeId, args, verified),
    group: (sourceNodeId, args) => factory.group(sourceNodeId, args),
    rename: (sourceNodeId, args) => factory.rename(sourceNodeId, args),
    color: (sourceNodeId, args) => factory.color(sourceNodeId, args),
    sticky: (sourceNodeId, args) => factory.sticky(sourceNodeId, args),
    run: (sourceNodeId, args, verified) => factory.run(sourceNodeId, args, verified),
    // A station's report about ITSELF (core/station-outcome-store.ts, the same handler the desktop
    // runs). A report can release an armed dependent, so the factory re-evaluates its arms.
    reportOutcome: (sourceNodeId, args, verified) =>
      handleReportOutcome(
        { nodeId: sourceNodeId, args, verified },
        {
          store: stationOutcomes,
          now: () => Date.now(),
          projectIdOfNode: (id) => {
            const ids = deps.workspaceStore.projectIdsForNode(id)
            return ids.length === 1 ? ids[0] : undefined
          },
          appendBoardLog: (projectId, entry) => deps.boardLog.append(projectId, entry),
          onRecorded: () => void factory.refreshArmed(),
          opener
        }
      ),
    // The board's GitHub lane, read-only, from the GitHub service's cache — the same core module the
    // desktop answers with. Own project only: this edition keeps no `open-project` grant ledger.
    githubRead: async (verb, sourceNodeId, args) => {
      const read = deps.githubRead
      if (!read) {
        const msg = `${verb}-unavailable: the GitHub lane is not available on this server. Do not retry.`
        return { ok: false, error: msg, message: msg }
      }
      const ids = deps.workspaceStore.projectIdsForNode(sourceNodeId)
      const resolved = resolveGitHubReadProject({
        verb,
        callerProjectId: ids.length === 1 ? ids[0] : undefined,
        targetProjectId: args.project,
        grantsOtherProjects: false
      })
      if ('refuse' in resolved) return { ok: false, error: resolved.refuse, message: resolved.refuse }
      return answerGitHubRead(verb, resolved.projectId, args, {
        ...read,
        agentState: (id) => nodeState(id),
        now: () => Date.now()
      })
    },
    settings: async (sourceNodeId, args) =>
      serverSettingsControl(
        {
          persistedCanvases: () => deps.workspaceStore.persistedCanvases(),
          capabilityProjectFor: (id) => deps.workspaceStore.capabilityProjectFor(id),
          projectName: (id) => deps.workspaceStore.projectTargetInfo(id)?.name,
          settings: deps.settings
        },
        sourceNodeId,
        args
      ),
    // `runDelivery` applies caller→target creator proof before any pane probe or write, and
    // re-applies it when a queued delivery flushes.
    deliver: async (input) => (await deliverFromControl(input, messaging)).reply
  }

  // Boot deliberately performs no canvas/session adoption. Creator proof is process-local and a
  // restart clears it, so an owner request or browser view is the only cold-spawn authority.
  await factory.start()

  const baseHandler = createServerEditionControlHandler(actions)
  return {
    // New work typed into a station by `run` withdraws its older outcome report — the "new task"
    // rule in core/station-outcome-store.ts, applied on the answer. (`send` / `reply` go through
    // `messaging.onHandover` above, which knows when a queued message actually lands.)
    handler: async (req) => {
      // When the request arrived — before `run` typed anything (see core/station-handover.ts).
      const requestAt = Date.now()
      const reply = await baseHandler(req)
      clearOutcomesAfterControl(stationOutcomes, req.verb, req.args, reply, req.nodeId)
      stationHandovers.noteControlAnswer(req.verb, req.args, reply, req.nodeId, requestAt)
      return reply
    },
    onAgentEvent: (event) => {
      // The hand-over tracker FIRST: it stamps turn starts and ends, and both the queue flush and
      // the factory's `refreshArmed` below act on this very event.
      stationHandovers.onAgentEvent(event)
      // A station starting a DIFFERENT session drops its old report before anything reads it.
      stationOutcomes.onAgentEvent(event)
      onMessagingAgentEvent(event, queue)
      factory.onAgentEvent(event)
      stationNotices.onAgentEvent(event)
    },
    stationNotices,
    stationOutcomes,
    stationHandovers,
    stop: () => {
      factory.stop()
      queue.resetForTests()
      stationNotices.stop()
      // Write what the last save window still holds; the next start loads it.
      queueFile.dispose()
      outcomesFile.dispose()
      handoversFile.dispose()
    }
  }
}