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.

10.1 KB
Raw Blame
import { create } from 'zustand'
import type { ProjectLaunchInfo } from '@shared/project-settings'
import type { ProjectVisualOverrides } from '../terminal/terminal-config'

/**
 * Warmed renderer cache of `project-settings:launch-info` (`projectLaunchInfoNow` /
 * `ensureProjectLaunchInfo` / `invalidateProjectLaunchInfo`) — the `permissionMode.ts`
 * `ensureClaudeCliCaps`/`claudeCliCapsNow` shape, keyed per project instead of app-global.
 *
 * Module-level, NOT zustand: nothing renders directly off this — it is read at the moment a launch
 * needs to know whether a shared-sourced value is trusted, same reasoning permissionMode.ts gives
 * for its own memo.
 *
 * `cache`/`generation` are BOTH keyed by projectId so one project's invalidate never disturbs
 * another's warm entry. `generation` is claimed FRESH by every fetch this module actually issues
 * (not merely bumped by `invalidate`): a write is honored only while its own claimed value is still
 * the current one. This closes two distinct ways an abandoned fetch can otherwise clobber a fresher
 * answer:
 *  - `invalidateProjectLaunchInfo` bumps it directly and drops the in-flight entry, so an in-flight
 *    fetch that predates the invalidate is superseded even if nothing ever re-`ensure`s.
 *  - the ENSURE_WAIT_MS timeout (below) drops the in-flight entry WITHOUT touching the generation —
 *    on its own, a fetch that never settles (a dropped Server Edition WS-RPC request neither times
 *    out nor rejects — see permissionMode.ts's `CAPS_WAIT_MS` doc) would otherwise leave `inFlight`
 *    pointing at an exhausted promise forever, so every later `ensure` for that project just
 *    rejoins it and NO fresh wire call is ever made again. Dropping the entry lets the next `ensure`
 *    issue a real new fetch, which claims its OWN generation — so if the original fetch finally
 *    answers after that, its stale generation no longer matches and its write is silently dropped,
 *    exactly like the invalidate case.
 * Neither path cancels the abandoned fetch (there is nothing to cancel it with) — only its write is
 * ever silenced, never the promise itself.
 */
const cache = new Map<string, { info: ProjectLaunchInfo | null; fetchedAt: number }>()
const inFlight = new Map<string, Promise<void>>()
const generation = new Map<string, number>()

/** How long `ensureProjectLaunchInfo` waits on the round trip before giving up on it — same bound
 *  as `permissionMode.ts`'s `CAPS_WAIT_MS`. A launch must never block on this. */
const ENSURE_WAIT_MS = 3000

/**
 * The REACTIVE mirror of the cache above — and only of the two cosmetic terminal values
 * (`terminal.theme` / `terminal.fontFamily`), never of the trust verdict.
 *
 * The cache is deliberately not a store: a launch READS it at the moment it launches, so nothing
 * needs to re-render when it changes. Live terminal appearance is the one consumer that does — a
 * project's theme has to reach terminals that are already on screen — and a module-level `Map` can
 * never notify them. Rather than turn the whole cache into a store (which would re-render every
 * terminal on the canvas whenever an unrelated launch field or trust bit moved), this carries the
 * appearance slice alone, so `useXtermVisualSettings` can subscribe shallowly to exactly what it
 * renders.
 *
 * Written ONLY by `syncVisuals`, on the same generation-guarded branch that writes `cache` — and
 * deliberately NOT cleared by `invalidateProjectLaunchInfo`. The mirror is last-known appearance,
 * not a cache entry, and the difference matters because `invalidate` runs after EVERY project
 * settings commit of any family: clearing here would drop the project's theme (and, with a project
 * font, re-fit the grid of a possibly co-attached pty twice) on its way to re-reading the very
 * document that is about to hand the same value back — a visible flash on every committed field,
 * seconds wide on an SSH project.
 *
 * Holding is self-healing, which is why it needs no expiry: all three `invalidate` call sites
 * re-`ensure` immediately, and that answer OVERWRITES this entry unconditionally — a project whose
 * override was just deleted answers `{ theme: undefined, fontFamily: undefined }`, which clears it.
 * The only state that can persist a stale value is one where the re-read never lands at all, and
 * there the honest thing to show is the appearance the project last actually asked for.
 */
interface ProjectVisualsState {
  byProject: Record<string, ProjectVisualOverrides>
}
export const useProjectVisuals = create<ProjectVisualsState>(() => ({ byProject: {} }))

function sameVisuals(a: ProjectVisualOverrides | undefined, b: ProjectVisualOverrides): boolean {
  return a !== undefined && a.theme === b.theme && a.fontFamily === b.fontFamily
}

/** Push one project's appearance slice into the mirror. No-ops when nothing changed, INCLUDING the
 *  object identity — a re-ensure that answers the same values must not re-render a canvas full of
 *  terminals (the subscription is shallow, but the entry itself is what it compares). */
function syncVisuals(projectId: string, info: ProjectLaunchInfo | null): void {
  const terminal = info?.resolved.terminal
  const next: ProjectVisualOverrides = {
    theme: terminal?.theme?.value,
    fontFamily: terminal?.fontFamily?.value
  }
  useProjectVisuals.setState((s) => {
    if (sameVisuals(s.byProject[projectId], next)) return s
    return { byProject: { ...s.byProject, [projectId]: next } }
  })
}

function currentGeneration(projectId: string): number {
  return generation.get(projectId) ?? 0
}

/** Claims and returns a generation strictly newer than whatever the project is currently at —
 *  called once per fetch actually issued (never on a joined in-flight call), so two fetches for the
 *  same project always hold distinguishable values regardless of which one (invalidate, timeout, or
 *  a plain re-ensure) triggered the reissue. */
function claimGeneration(projectId: string): number {
  const next = currentGeneration(projectId) + 1
  generation.set(projectId, next)
  return next
}

/** The last-known answer, synchronously — null when nothing has been fetched yet (or the project
 *  was never warmed, or the fetch itself found no shared executable content to gate at all: a
 *  caller reading null must treat it as "no override behavior", i.e. fail open, exactly like an
 *  unknown project id answers over the wire). */
export function projectLaunchInfoNow(projectId: string): ProjectLaunchInfo | null {
  return cache.get(projectId)?.info ?? null
}

/**
 * Kick off (or join) the launch-info fetch for one project. Never rejects, and never takes longer
 * than `ENSURE_WAIT_MS` — on timeout the promise resolves with whatever is cached (possibly
 * nothing), and a late answer still lands in `cache` for the NEXT read PROVIDED nothing fresher
 * has claimed the project's generation since (see the module doc). Memoized per project: a second
 * caller while one is already in flight joins the same promise rather than firing a second request;
 * once a fetch's own in-flight entry is cleared (settled, or timed out), the NEXT caller always
 * issues a brand new wire call — a project is never left permanently cold by one dropped request.
 */
export function ensureProjectLaunchInfo(projectId: string): Promise<void> {
  const existing = inFlight.get(projectId)
  if (existing) return existing

  const gen = claimGeneration(projectId)
  const fetch = Promise.resolve()
    .then(() => window.nodeTerminal.projectSettings.launchInfo(projectId))
    .then((info) => {
      // A newer claim since this fetch started means it was superseded (an invalidate, or this
      // very fetch having already been abandoned by a timeout and reissued) — never let a stale
      // answer land over whatever a fresher fetch already wrote.
      if (currentGeneration(projectId) !== gen) return
      cache.set(projectId, { info, fetchedAt: Date.now() })
      // Same branch, same guard: the reactive mirror only ever reflects what the cache accepted.
      syncVisuals(projectId, info)
    })
    .catch(() => {
      // Fail open: leave whatever is cached (possibly nothing) alone.
    })

  // `bounded` is referenced inside the timeout callback before its own declaration below — safe
  // because the callback only runs asynchronously, well after `bounded` is assigned.
  let bounded!: Promise<void>
  const timeout = new Promise<void>((resolve) => {
    setTimeout(() => {
      // The wire call may simply never answer (see the module doc). Clear OUR OWN in-flight entry
      // — guarded on identity, since a fetch that already finished (and cleared itself in the
      // `finally` below) may have already been superseded by a newer `ensure` by the time this
      // timer fires, and that newer entry must not be touched.
      if (inFlight.get(projectId) === bounded) inFlight.delete(projectId)
      resolve()
    }, ENSURE_WAIT_MS)
  })
  bounded = Promise.race([fetch, timeout])
  // Same identity guard as the timeout branch: a fetch that answers after ITS OWN timeout already
  // cleared (and possibly a newer fetch is now in flight) must not delete that newer entry.
  fetch.finally(() => {
    if (inFlight.get(projectId) === bounded) inFlight.delete(projectId)
  })
  inFlight.set(projectId, bounded)
  return bounded
}

/** Drops the cached answer and abandons any in-flight fetch's write (see the module doc) — the
 *  next `projectLaunchInfoNow` reads null and the next `ensureProjectLaunchInfo` starts fresh.
 *  Called on `onTrustChanged` for the affected project, and after a settings-panel save. */
export function invalidateProjectLaunchInfo(projectId: string): void {
  cache.delete(projectId)
  // NOT `useProjectVisuals`: the appearance mirror is held across an invalidate on purpose — see
  // its doc comment. Dropping it here would repaint every terminal of the project twice on its way
  // to re-reading the same values.
  generation.set(projectId, currentGeneration(projectId) + 1)
  inFlight.delete(projectId)
}

/** Test seam: drop every memo (cache, in-flight, generation counters). */
export function resetProjectLaunchInfoForTests(): void {
  cache.clear()
  inFlight.clear()
  generation.clear()
  useProjectVisuals.setState({ byProject: {} })
}