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.

12.5 KB
Raw Blame
import {
  AUTO_PERMISSION_MODE_MIN_VERSION,
  gatePermissionMode,
  resolvePermissionMode,
  type AgentId,
  type AgentPermissionMode
} from '@shared/agents/config'
import {
  UNKNOWN_CLAUDE_CLI_CAPS,
  UNKNOWN_GROK_CLI_CAPS,
  UNKNOWN_CURSOR_CLI_CAPS,
  type CursorCliCaps,
  type ClaudeCliCaps,
  type GrokCliCaps,
  type Project
} from '@shared/types'
import { useProjects } from './projects'
import { useSettings } from './settings'
import { useSshConn, type SshAutoPermAnswer } from './sshConn'

/**
 * Local Claude CLI capabilities, probed once per app run through `claude.cliCaps()` (main/server →
 * core/claude-cli.ts). Kept as a module-level memo rather than a zustand store: nothing renders
 * from it — it is read only at the moment a launch command is built — and a store would invite
 * re-renders on a value that never changes while the app runs.
 *
 * Until the probe answers, `caps` is the FAIL-OPEN unknown: no `auto` flag, i.e. the bare `claude`
 * command. A launch is never blocked on the probe.
 */
let caps: ClaudeCliCaps = UNKNOWN_CLAUDE_CLI_CAPS
let capsPromise: Promise<ClaudeCliCaps> | null = null

/** How long a launch may wait on the probe before giving up on it and using the bare command. */
const CAPS_WAIT_MS = 3000

/**
 * Kick off (or join) the local CLI probe. Never rejects, and never takes longer than
 * `CAPS_WAIT_MS`. Called once at boot; awaited by any launch path that can run before boot settles
 * (a cold-restored agent node).
 *
 * The timeout is what makes "a launch is never blocked on the probe" true BY CONSTRUCTION. On the
 * desktop the IPC round-trip is bounded by the main-process probe, but in the Server Edition the
 * call goes over WS-RPC, which neither times out nor rejects its pending requests when the socket
 * drops — a drop between send and response would leave this promise (and the memo) unsettled
 * forever, and with it the agent relaunch that awaits it. On timeout we resolve to the caps we
 * have (unknown ⇒ no `auto` flag ⇒ bare command); a late answer still lands in `caps`, so the
 * NEXT launch picks it up.
 */
export function ensureClaudeCliCaps(): Promise<ClaudeCliCaps> {
  if (!capsPromise) {
    const probe = Promise.resolve()
      .then(() => window.nodeTerminal.claude.cliCaps())
      .then((c) => (caps = c ?? UNKNOWN_CLAUDE_CLI_CAPS))
      .catch(() => UNKNOWN_CLAUDE_CLI_CAPS)
    const timeout = new Promise<ClaudeCliCaps>((resolve) =>
      setTimeout(() => resolve(caps), CAPS_WAIT_MS)
    )
    capsPromise = Promise.race([probe, timeout])
  }
  return capsPromise
}

/**
 * The last-known caps, synchronously. For callers that cannot await — node creation is a sync
 * factory — and whose correct answer when nothing has been probed yet is simply "assume nothing"
 * (UNKNOWN, i.e. the pre-feature command line). `ensureClaudeCliCaps` runs at boot, so by the time
 * a user creates a node this is the real answer.
 */
export function claudeCliCapsNow(): ClaudeCliCaps {
  return caps
}

/**
 * The same memo, for grok. A SEPARATE probe and a separate memo on purpose: rule 9 — a capability
 * gate fed by a version probe belongs to the agent it probes. grok and claude are installed and
 * upgraded independently, so claude's answer says nothing about grok's, and borrowing it would be a
 * guess dressed as a measurement.
 *
 * Same fail-open shape: until it answers, "no flag", i.e. the bare `grok` command. A launch is never
 * blocked on a probe.
 */
let grokCaps: GrokCliCaps = UNKNOWN_GROK_CLI_CAPS
let grokCapsPromise: Promise<GrokCliCaps> | null = null

export function ensureGrokCliCaps(): Promise<GrokCliCaps> {
  if (!grokCapsPromise) {
    const probe = Promise.resolve()
      .then(() => window.nodeTerminal.grok.cliCaps())
      .then((c) => (grokCaps = c ?? UNKNOWN_GROK_CLI_CAPS))
      .catch(() => UNKNOWN_GROK_CLI_CAPS)
    const timeout = new Promise<GrokCliCaps>((resolve) =>
      setTimeout(() => resolve(grokCaps), CAPS_WAIT_MS)
    )
    grokCapsPromise = Promise.race([probe, timeout])
  }
  return grokCapsPromise
}

/** Last-known grok caps, synchronously — node creation is a sync factory. */
export function grokCliCapsNow(): GrokCliCaps {
  return grokCaps
}

/** cursor's catalogue, same shape: fail-open [] until `cursor.cliCaps()` answers. Own memo (rule 9). */
let cursorCaps: CursorCliCaps = UNKNOWN_CURSOR_CLI_CAPS
let cursorCapsPromise: Promise<CursorCliCaps> | null = null

export function ensureCursorCliCaps(): Promise<CursorCliCaps> {
  if (!cursorCapsPromise) {
    const probe = Promise.resolve()
      .then(() => window.nodeTerminal.cursor.cliCaps())
      .then((c) => (cursorCaps = c ?? UNKNOWN_CURSOR_CLI_CAPS))
      .catch(() => UNKNOWN_CURSOR_CLI_CAPS)
      .then((c) => {
        // An empty catalogue (offline, signed out, CLI missing) is not remembered: core does not
        // cache it either (core/cursor-cli.ts), so the next ask retries instead of hiding the model
        // menu until an app reload (review 2026-10-02). A real catalogue stays memoized.
        if (c.models.length === 0) cursorCapsPromise = null
        return c
      })
    const timeout = new Promise<CursorCliCaps>((resolve) =>
      setTimeout(() => resolve(cursorCaps), CAPS_WAIT_MS)
    )
    cursorCapsPromise = Promise.race([probe, timeout])
  }
  return cursorCapsPromise
}

/** Last-known cursor caps, synchronously. With nothing known yet it starts a retry in the
 *  background, so the menu that asked finds the catalogue the next time it opens. */
export function cursorCliCapsNow(): CursorCliCaps {
  if (cursorCaps.models.length === 0) void ensureCursorCliCaps()
  return cursorCaps
}

/** Test seam for the cursor memo. */
export function resetCursorCliCapsForTests(): void {
  cursorCaps = UNKNOWN_CURSOR_CLI_CAPS
  cursorCapsPromise = null
}

/** Test seam for the grok memo. */
export function resetGrokCliCapsForTests(next?: GrokCliCaps): void {
  grokCaps = next ?? UNKNOWN_GROK_CLI_CAPS
  grokCapsPromise = null
}

/** Test seam: drop the memo (and optionally preload a known answer). */
export function resetClaudeCliCapsForTests(next?: ClaudeCliCaps): void {
  caps = next ?? UNKNOWN_CLAUDE_CLI_CAPS
  capsPromise = null
}

/**
 * Does the CLI that will actually RUN this project's sessions accept `--permission-mode auto`?
 *
 * An SSH project's terminals run on the remote host, whose claude can be OLDER than the local one
 * — so the local probe's answer is never applied to a remote launch. The remote is probed on its
 * own host at connect (SshProjectManager) and cached in `useSshConn`; not connected / not yet
 * probed / older CLI all answer false, which omits the flag (conservative, and exactly the
 * command nodeterm shipped before this setting existed).
 */
function autoSupportedFor(project: Project | undefined): boolean {
  if (project?.ssh) return useSshConn.getState().supportsAutoPermissionMode(project.id)
  return caps.autoPermissionMode
}

/**
 * The permission mode a session launched RIGHT NOW actually starts in: the active project's
 * override, else the global setting — with `auto` degraded to `manual` (no flag → bare command)
 * when the CLI that will run it is too old to know the value (Claude Code < 2.1.71, which exits 1
 * on it) or hasn't been probed yet. The other four modes are never touched by the gate.
 *
 * `agentId` defaults to `'claude'`, so every call site written before a second agent had a
 * permission mode keeps its exact behavior.
 *
 * Lives in its own module rather than in workspace.ts because projects.ts imports workspace.ts
 * (createProject) — importing the projects store from workspace.ts would close that cycle.
 */
export function activePermissionMode(agentId: AgentId = 'claude'): AgentPermissionMode {
  const { getProject, activeProjectId } = useProjects.getState()
  return projectPermissionMode(getProject(activeProjectId), agentId)
}

/**
 * The same resolution for an EXPLICIT project — the `--project`-targeted opens (issue #338) need
 * the TARGET project's override + gate, not the active one's: a node opened into another project
 * must start with that project's permission mode (spec §2.2 defaults), never the caller's.
 */
export function projectPermissionMode(
  project: Project | undefined,
  agentId: AgentId = 'claude'
): AgentPermissionMode {
  const { settings } = useSettings.getState()
  const mode = resolvePermissionMode(project, settings)
  // The version gate is CLAUDE-specific BY CONSTRUCTION: it exists because Claude Code < 2.1.71
  // exits 1 on `--permission-mode auto`, and it is fed by a `claude --version` probe (local, or the
  // SSH host's). grok has accepted every mode we emit since 1.0.0, its first release, so applying
  // the gate to it would downgrade a grok session to `default` on a machine whose CLAUDE is old —
  // or absent entirely. An agent that needs its own gate adds it here, beside this one, rather than
  // inheriting claude's.
  return agentId === 'claude' ? gatePermissionMode(mode, autoSupportedFor(project)) : mode
}

/** How long a launch on an SSH project may wait for the REMOTE probe's first answer. The probe
 *  fires right after connect and pushes every attempt's answer immediately, so this usually
 *  resolves in the first couple of seconds; the cap keeps a dead probe from stalling a relaunch. */
export const SSH_AUTO_PROBE_WAIT_MS = 10_000

/** Resolve once the project's remote probe has ANY answer (yes/no), or after `ms`. Fail-open:
 *  a timeout just means the caller gates on 'unknown' — bare command, never a blocked launch. */
function waitForSshAutoAnswer(projectId: string, ms: number): Promise<void> {
  if (useSshConn.getState().autoPermAnswer(projectId) !== 'unknown') return Promise.resolve()
  return new Promise((resolve) => {
    let settled = false
    const finish = (): void => {
      if (settled) return
      settled = true
      clearTimeout(timer)
      unsub()
      resolve()
    }
    const unsub = useSshConn.subscribe((s) => {
      if (s.autoPermByProject[projectId] !== undefined) finish()
    })
    const timer = setTimeout(finish, ms)
  })
}

/**
 * `activePermissionMode()` for callers that can run BEFORE the boot-time probe has answered — the
 * cold-restore agent relaunch fires on node mount. Awaiting the (memoized, warmed in the shell)
 * probe there means a rebooted machine still gets `auto`, instead of silently falling back to the
 * bare command for one session.
 *
 * On an SSH project the gate consults the REMOTE probe, which races the same mount (it fires
 * after connect, through a slow login shell) — so when the resolved mode is `auto`, this also
 * waits (bounded) for that probe's first answer. Any other mode never waits: the gate only ever
 * touches `auto`.
 *
 * BOTH waits are for claude's gate, and nothing else — so a non-claude agent waits on neither:
 * blocking a grok launch on a `claude --version` probe (or on an SSH host's claude probe, which on
 * a host without claude never answers at all) would be a delay bought for no decision.
 */
export async function ensureActivePermissionMode(
  agentId: AgentId = 'claude'
): Promise<AgentPermissionMode> {
  if (agentId !== 'claude') return activePermissionMode(agentId)
  await ensureClaudeCliCaps()
  const { settings } = useSettings.getState()
  const { getProject, activeProjectId } = useProjects.getState()
  const project = getProject(activeProjectId)
  if (project?.ssh && resolvePermissionMode(project, settings) === 'auto') {
    await waitForSshAutoAnswer(project.id, SSH_AUTO_PROBE_WAIT_MS)
  }
  return activePermissionMode('claude')
}

/**
 * Why `auto` may not apply on this SSH project, for the tab menu's Auto rows — null when the
 * remote CLI is confirmed and Auto works as chosen. The silent fail-open degrade is correct for
 * launches but indistinguishable from "the dropdown is broken" without this.
 *
 * Every sentence names CLAUDE explicitly: the gate this describes is claude's alone (grok accepts
 * `auto` on every version), so an unprefixed warning on a project that also runs grok sessions
 * would read as a limitation of the mode itself.
 */
export function sshAutoModeHint(
  answer: SshAutoPermAnswer,
  version: string | null | undefined
): string | null {
  if (answer === 'yes') return null
  if (answer === 'no') {
    const v = version?.match(/\d+\.\d+\.\d+/)?.[0]
    return v
      ? `The server's Claude CLI is ${v} — Auto needs ${AUTO_PERMISSION_MODE_MIN_VERSION} or newer, so Claude sessions start without a mode flag until it is upgraded.`
      : 'Claude CLI was not found on the server, so Auto cannot apply to Claude sessions — they start without a mode flag.'
  }
  return `Claude sessions: not verified on this server yet — Auto applies to them once the server's Claude CLI (≥ ${AUTO_PERMISSION_MODE_MIN_VERSION}) is confirmed.`
}