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.

24.6 KB
Raw Blame
/**
 * The desktop's client for the ONE shared `codex app-server`.
 *
 * Two jobs, both of which the sh launcher cannot do itself:
 *  - `startCodexThreadAt` — mint the thread a fresh Codex node will own.
 *  - `readCodexSessionName` — the READ leg of codex's session name (`TITLE_READ_CAPABLE`).
 *
 * The name lives in the app-server's `Thread.name`, not in a file on disk, so this is the only
 * place it can be read from. There is no WRITE leg: codex has no rename command NodeTerm can
 * drive, which is exactly the gemini situation `TITLE_READ_CAPABLE` was split out for.
 *
 * Everything here fails to `null`/reject rather than throwing into a caller's poll loop: a name we
 * cannot read means the node keeps its own title, and a thread we cannot start means the launcher
 * falls back to plain codex.
 */
import { createHash } from 'crypto'
import { readFileSync } from 'fs'
import { homedir } from 'os'
import path from 'path'
import { WebSocket } from 'ws'
// Minting a thread is a multi-step conversation with a typically COLD server, so it needs a real
// budget — and the hook route serving it must raise its socket guard to match (handleCodexThread).
// Shared with the launcher's client budget so the two cannot drift apart.
// `isSafeThreadId` comes from the same module, and deliberately: this file used to keep its own
// copy of the bare charset, which accepted `.` and `..` — harmless over the RPC wire here, but the
// ids it validates (a thread the app-server just minted, one a node persisted) are handed straight
// to the record store, where they ARE path segments. One rule, so the two cannot drift apart.
import { codexAppServerReachable } from './codex-accounts-core'
import { CODEX_THREAD_START_TIMEOUT_MS, isSafeThreadId } from './codex-identity-proxy'

/**
 * `codex app-server daemon start` exiting 0 does NOT mean its control socket is accepting
 * connections yet — the daemon binds a beat later. Everything here runs immediately after that
 * command, on the cold/reboot path this feature exists for, so a single failed connect must not be
 * read as an answer. Three tries over ~600 ms: long enough for a daemon that is coming up, short
 * enough that a daemon that is not there costs nothing worth noticing.
 */
const SOCKET_WAIT_ATTEMPTS = 3
const SOCKET_WAIT_MS = 200

const delay = (ms: number): Promise<void> =>
  new Promise((resolve) => {
    const t = setTimeout(resolve, ms)
    t.unref?.()
  })

/** Resolve once the app-server's socket accepts a connection, or after the attempts run out. */
export function waitForCodexAppServer(
  socketPath: string,
  attempts = SOCKET_WAIT_ATTEMPTS,
  gapMs = SOCKET_WAIT_MS
): Promise<boolean> {
  const tryOnce = (): Promise<boolean> =>
    new Promise((resolve) => {
      let ws: WebSocket
      let settled = false
      const finish = (ok: boolean): void => {
        if (settled) return
        settled = true
        clearTimeout(timer)
        try {
          ws.close()
        } catch {
          /* the connection may never have opened */
        }
        resolve(ok)
      }
      const timer = setTimeout(() => finish(false), REQUEST_TIMEOUT_MS)
      timer.unref?.()
      try {
        ws = connectCodexAppServer(socketPath)
      } catch {
        clearTimeout(timer)
        resolve(false)
        return
      }
      ws.once('open', () => finish(true))
      ws.once('error', () => finish(false))
      ws.once('close', () => finish(false))
    })
  return (async () => {
    for (let i = 0; i < attempts; i++) {
      if (await tryOnce()) return true
      if (i < attempts - 1) await delay(gapMs)
    }
    return false
  })()
}
const CACHE_MS = 3_000
const REQUEST_TIMEOUT_MS = 2_000

const names = new Map<string, { name: string | null; at: number }>()
const inflight = new Map<string, Promise<string | null>>()

/** The app-server's control socket, under the CLI's own `CODEX_HOME` (default `~/.codex`). */
export function defaultCodexAppServerSocket(): string {
  const configured = process.env.CODEX_HOME
  const codexHome =
    configured && path.isAbsolute(configured) ? configured : path.join(homedir(), '.codex')
  return path.join(codexHome, 'app-server-control', 'app-server-control.sock')
}

export function codexUnixWebSocketUrl(socketPath: string): string {
  if (!path.isAbsolute(socketPath) || /[\s:%?#]/.test(socketPath)) {
    throw new Error('Unsupported Codex app-server socket path')
  }
  return `ws+unix://${socketPath}:/rpc`
}

function connectCodexAppServer(socketPath: string): WebSocket {
  return new WebSocket(codexUnixWebSocketUrl(socketPath), { perMessageDeflate: false })
}

export function readCodexSessionNameAt(
  socketPath: string,
  threadId: string,
  timeoutMs = REQUEST_TIMEOUT_MS
): Promise<string | null> {
  if (!isSafeThreadId(threadId)) return Promise.resolve(null)
  return new Promise((resolve) => {
    let settled = false
    let ws: WebSocket
    const finish = (name: string | null): void => {
      if (settled) return
      settled = true
      clearTimeout(timer)
      try {
        ws.close()
      } catch {
        /* the connection may never have opened */
      }
      resolve(name)
    }
    const timer = setTimeout(() => finish(null), timeoutMs)
    timer.unref?.()
    try {
      ws = connectCodexAppServer(socketPath)
    } catch {
      clearTimeout(timer)
      resolve(null)
      return
    }
    ws.once('open', () => {
      ws.send(
        JSON.stringify({
          id: 1,
          method: 'initialize',
          params: { clientInfo: { name: 'nodeterm', version: '1' } }
        })
      )
    })
    ws.on('message', (raw) => {
      let message: Record<string, any>
      try {
        message = JSON.parse(raw.toString())
      } catch {
        return
      }
      if (message.id === 1) {
        if (message.error) return finish(null)
        ws.send(JSON.stringify({ method: 'initialized' }))
        ws.send(
          JSON.stringify({
            id: 2,
            method: 'thread/read',
            params: { threadId, includeTurns: false }
          })
        )
      } else if (message.id === 2) {
        const name = message.result?.thread?.name
        finish(typeof name === 'string' && name.trim() ? name.trim() : null)
      }
    })
    ws.once('error', () => finish(null))
    ws.once('close', () => finish(null))
  })
}

/**
 * Does the shared app-server actually know this thread?
 *
 * The bind route writes a record claiming a node owns a conversation. Without this check ANY
 * id the caller hands us binds happily — a stale session id, or one persisted from a
 * plain-codex-era session that the app-server has never heard of — and the launcher then execs
 * `codex --remote unix:// resume <id>`, which dies with "no rollout found" AFTER exec, where
 * there is no fallback left. Asking first turns that dead node into an ordinary fallback.
 *
 * A server we cannot reach answers `false`, which is the safe direction here: refusing costs a
 * plain codex session, accepting costs the node.
 */
function probeCodexThread(
  socketPath: string,
  threadId: string,
  timeoutMs: number
): Promise<'yes' | 'no' | 'unreachable'> {
  return new Promise((resolve) => {
    let settled = false
    let answered = false
    let ws: WebSocket
    const finish = (result: 'yes' | 'no' | 'unreachable'): void => {
      if (settled) return
      settled = true
      clearTimeout(timer)
      try {
        ws.close()
      } catch {
        /* the connection may never have opened */
      }
      resolve(result)
    }
    const timer = setTimeout(() => finish(answered ? 'no' : 'unreachable'), timeoutMs)
    timer.unref?.()
    try {
      ws = connectCodexAppServer(socketPath)
    } catch {
      clearTimeout(timer)
      resolve('unreachable')
      return
    }
    ws.once('open', () => {
      ws.send(
        JSON.stringify({
          id: 1,
          method: 'initialize',
          params: { clientInfo: { name: 'nodeterm', version: '1' } }
        })
      )
    })
    ws.on('message', (raw) => {
      let message: Record<string, any>
      try {
        message = JSON.parse(raw.toString())
      } catch {
        return
      }
      if (message.id === 1) {
        answered = true
        // A server that will not initialize is a definite NO, not a transient one: retrying a
        // logged-out CLI just delays the same answer.
        if (message.error) return finish('no')
        ws.send(JSON.stringify({ method: 'initialized' }))
        ws.send(
          JSON.stringify({ id: 2, method: 'thread/read', params: { threadId, includeTurns: false } })
        )
      } else if (message.id === 2) {
        // The id must come back UNCHANGED: a server that answers with some other thread has not
        // confirmed the one we asked about.
        finish(!message.error && message.result?.thread?.id === threadId ? 'yes' : 'no')
      }
    })
    ws.once('error', () => finish(answered ? 'no' : 'unreachable'))
    ws.once('close', () => finish(answered ? 'no' : 'unreachable'))
  })
}

/**
 * Does the shared app-server actually know this thread?
 *
 * The bind route writes a record claiming a node owns a conversation. Without this check ANY
 * id the caller hands us binds happily — a stale session id, or one persisted from a
 * plain-codex-era session that the app-server has never heard of — and the launcher then execs
 * `codex --remote unix:// resume <id>`, which dies with "no rollout found" AFTER exec, where
 * there is no fallback left. Asking first turns that dead node into an ordinary fallback.
 *
 * A server we could not REACH is retried (the daemon may still be binding its socket — see
 * SOCKET_WAIT_ATTEMPTS), because this check runs on the cold path and a not-yet-listening daemon
 * would otherwise turn a perfectly good resume into a fallback. A server that ANSWERED is never
 * retried: "I do not have that thread" is an answer, and asking again just delays it.
 *
 * Out of retries, the answer is `false` — the safe direction: refusing costs a plain codex
 * session, accepting costs the node.
 */
export async function codexThreadExistsAt(
  socketPath: string,
  threadId: string,
  timeoutMs = REQUEST_TIMEOUT_MS,
  attempts = SOCKET_WAIT_ATTEMPTS,
  gapMs = SOCKET_WAIT_MS
): Promise<boolean> {
  if (!isSafeThreadId(threadId)) return false
  for (let i = 0; i < attempts; i++) {
    const result = await probeCodexThread(socketPath, threadId, timeoutMs)
    if (result !== 'unreachable') return result === 'yes'
    if (i < attempts - 1) await delay(gapMs)
  }
  return false
}

export function codexThreadExists(threadId: string): Promise<boolean> {
  return codexThreadExistsAt(defaultCodexAppServerSocket(), threadId)
}

/**
 * Create one new, immediately RESUMABLE thread on the shared app-server and return its id.
 *
 * `thread/start` alone only creates app-server metadata: it deliberately does not materialize the
 * rollout file, and a second client's `thread/resume` then fails with "no rollout found" — which
 * is precisely what the launcher does one line later. So the rollout is materialized by running
 * one empty turn, interrupting it the moment the server announces it, forking immediately BEFORE
 * that turn, and deleting the seed. The result is a thread with zero user turns and a valid
 * rollout, without the deprecated rollback API.
 */
export async function startCodexThreadAt(
  socketPath: string,
  cwd: string,
  timeoutMs = CODEX_THREAD_START_TIMEOUT_MS
): Promise<string> {
  // Same cold-socket window as the bind check: `daemon start` has exited, the socket may still be
  // binding. Bounded (~600 ms) and charged against the 20 s budget below, which has room for it.
  await waitForCodexAppServer(socketPath)
  return startCodexThreadOnce(socketPath, cwd, timeoutMs)
}

function startCodexThreadOnce(
  socketPath: string,
  cwd: string,
  timeoutMs: number
): Promise<string> {
  if (!path.isAbsolute(cwd) || cwd.includes('\0')) {
    return Promise.reject(new Error('Unsupported Codex thread cwd'))
  }
  return new Promise((resolve, reject) => {
    let settled = false
    let ws: WebSocket
    const finish = (error: Error | null, threadId?: string): void => {
      if (settled) return
      settled = true
      clearTimeout(timer)
      try {
        ws.close()
      } catch {
        /* the connection may never have opened */
      }
      if (error) reject(error)
      else resolve(threadId as string)
    }
    const timer = setTimeout(
      () => finish(new Error('Codex app-server thread start timed out')),
      timeoutMs
    )
    timer.unref?.()
    try {
      ws = connectCodexAppServer(socketPath)
    } catch {
      clearTimeout(timer)
      reject(new Error('Codex app-server is unavailable'))
      return
    }
    ws.once('open', () => {
      ws.send(
        JSON.stringify({
          id: 1,
          method: 'initialize',
          params: {
            clientInfo: { name: 'nodeterm', version: '1' },
            capabilities: { experimentalApi: true }
          }
        })
      )
    })
    let threadId = ''
    let bootstrapTurnId = ''
    let announcedBootstrapTurnId = ''
    let announcedCompletedTurnId = ''
    let bootstrapStarted = false
    let interruptSent = false
    let interruptAcknowledged = false
    let bootstrapCompleted = false
    let cleanupForkSent = false
    const maybeInterrupt = (): void => {
      if (!bootstrapTurnId || !bootstrapStarted || bootstrapCompleted || interruptSent) return
      interruptSent = true
      ws.send(
        JSON.stringify({
          id: 4,
          method: 'turn/interrupt',
          params: { threadId, turnId: bootstrapTurnId }
        })
      )
    }
    const maybeCreateCleanThread = (): void => {
      if (!bootstrapCompleted || cleanupForkSent) return
      if (interruptSent && !interruptAcknowledged) return
      cleanupForkSent = true
      ws.send(
        JSON.stringify({
          id: 5,
          method: 'thread/fork',
          params: { threadId, beforeTurnId: bootstrapTurnId, cwd, ephemeral: false }
        })
      )
    }
    ws.on('message', (raw) => {
      let message: Record<string, any>
      try {
        message = JSON.parse(raw.toString())
      } catch {
        return
      }
      if (message.id === 1) {
        if (message.error) {
          finish(new Error('Codex app-server initialization failed'))
          return
        }
        ws.send(JSON.stringify({ method: 'initialized' }))
        ws.send(JSON.stringify({ id: 2, method: 'thread/start', params: { cwd } }))
      } else if (message.id === 2) {
        const startedThreadId = message.result?.thread?.id
        if (
          message.error ||
          typeof startedThreadId !== 'string' ||
          !isSafeThreadId(startedThreadId)
        ) {
          finish(new Error('Codex app-server returned no valid thread identity'))
          return
        }
        threadId = startedThreadId
        ws.send(JSON.stringify({ id: 3, method: 'turn/start', params: { threadId, input: [] } }))
      } else if (message.id === 3) {
        const turnId = message.result?.turn?.id
        if (message.error || typeof turnId !== 'string' || !isSafeThreadId(turnId)) {
          finish(new Error('Codex app-server could not materialize the new thread'))
          return
        }
        bootstrapTurnId = turnId
        if (announcedBootstrapTurnId === turnId) bootstrapStarted = true
        if (announcedCompletedTurnId === turnId) bootstrapCompleted = true
        maybeInterrupt()
        maybeCreateCleanThread()
      } else if (message.method === 'turn/started') {
        const turnId = message.params?.turn?.id
        if (typeof turnId === 'string') {
          announcedBootstrapTurnId = turnId
          if (turnId === bootstrapTurnId) {
            bootstrapStarted = true
            maybeInterrupt()
          }
        }
      } else if (message.id === 4) {
        if (message.error) {
          finish(new Error('Codex app-server could not interrupt thread materialization'))
          return
        }
        interruptAcknowledged = true
        maybeCreateCleanThread()
      } else if (message.method === 'turn/completed') {
        const turnId = message.params?.turn?.id
        if (typeof turnId === 'string') {
          announcedCompletedTurnId = turnId
          if (turnId === bootstrapTurnId) {
            bootstrapCompleted = true
            maybeCreateCleanThread()
          }
        }
      } else if (message.id === 5) {
        const readyThreadId = message.result?.thread?.id
        if (
          message.error ||
          typeof readyThreadId !== 'string' ||
          !isSafeThreadId(readyThreadId)
        ) {
          finish(new Error('Codex app-server could not clean up thread materialization'))
          return
        }
        const seedThreadId = threadId
        threadId = readyThreadId
        ws.send(JSON.stringify({ id: 6, method: 'thread/delete', params: { threadId: seedThreadId } }))
      } else if (message.id === 6) {
        if (message.error) {
          finish(new Error('Codex app-server could not remove thread materialization seed'))
          return
        }
        finish(null, threadId)
      }
    })
    ws.once('error', () => finish(new Error('Codex app-server is unavailable')))
    ws.once('close', () => finish(new Error('Codex app-server closed before thread start')))
  })
}

export function startCodexThread(cwd: string): Promise<string> {
  return startCodexThreadAt(defaultCodexAppServerSocket(), cwd)
}

/**
 * The relay's on-disk fallback for a session name the shared app-server no longer reports.
 *
 * A native in-TUI `/resume` can fork a cloud conversation into a local app-server thread whose
 * `Thread.name` is `null`; the persistent relay observed the source id at bind time and copied its
 * `session_index` title to `~/.nodeterm/codex-thread-names/<sha256(socket)[..16]>/<threadId>` (the
 * exact path the relay daemon's `nameFile` writes — one definition, kept in step). Read as DATA and
 * capped; a later real `Thread.name` from the server always wins. Fails to `null`.
 */
export function relayedCodexSessionName(
  socketPath: string,
  threadId: string,
  home = homedir()
): string | null {
  if (!isSafeThreadId(threadId)) return null
  try {
    const scope = createHash('sha256').update(socketPath).digest('hex').slice(0, 16)
    const value = readFileSync(
      path.join(home, '.nodeterm', 'codex-thread-names', scope, threadId),
      'utf8'
    ).trim()
    return value ? value.slice(0, 500) : null
  } catch {
    return null
  }
}

/** Seed the in-process name cache from a name observed elsewhere (e.g. a relay bind), so the next
 * sweep serves it without a socket round-trip. A blank name caches an explicit `null`. */
export function rememberCodexSessionName(
  threadId: string,
  name: unknown,
  socketPath = defaultCodexAppServerSocket()
): void {
  if (!isSafeThreadId(threadId)) return
  const value = typeof name === 'string' && name.trim() ? name.trim() : null
  names.set(`${socketPath}\0${threadId}`, { name: value, at: Date.now() })
}

/** Read a thread's full identity from an app-server socket: its id (must come back UNCHANGED), name,
 * and absolute rollout path. Used by the cross-account switch to locate a foreign rollout. Fails to
 * `null` rather than throwing into a poll loop. */
export function readCodexThreadAt(
  socketPath: string,
  threadId: string,
  timeoutMs = REQUEST_TIMEOUT_MS
): Promise<{ id: string; name: string | null; path: string | null } | null> {
  if (!isSafeThreadId(threadId)) return Promise.resolve(null)
  return new Promise((resolve) => {
    let settled = false
    let ws: WebSocket
    const finish = (value: { id: string; name: string | null; path: string | null } | null): void => {
      if (settled) return
      settled = true
      clearTimeout(timer)
      try {
        ws.close()
      } catch {
        /* the connection may never have opened */
      }
      resolve(value)
    }
    const timer = setTimeout(() => finish(null), timeoutMs)
    timer.unref?.()
    try {
      ws = connectCodexAppServer(socketPath)
    } catch {
      clearTimeout(timer)
      resolve(null)
      return
    }
    ws.once('open', () => {
      ws.send(
        JSON.stringify({
          id: 1,
          method: 'initialize',
          params: { clientInfo: { name: 'nodeterm', version: '1' } }
        })
      )
    })
    ws.on('message', (raw) => {
      let message: Record<string, any>
      try {
        message = JSON.parse(raw.toString())
      } catch {
        return
      }
      if (message.id === 1) {
        if (message.error) return finish(null)
        ws.send(JSON.stringify({ method: 'initialized' }))
        ws.send(
          JSON.stringify({ id: 2, method: 'thread/read', params: { threadId, includeTurns: false } })
        )
      } else if (message.id === 2) {
        const thread = message.result?.thread
        if (message.error || typeof thread?.id !== 'string' || thread.id !== threadId) {
          finish(null)
          return
        }
        finish({
          id: thread.id,
          name: typeof thread.name === 'string' && thread.name.trim() ? thread.name.trim() : null,
          path: typeof thread.path === 'string' && path.isAbsolute(thread.path) ? thread.path : null
        })
      }
    })
    ws.once('error', () => finish(null))
    ws.once('close', () => finish(null))
  })
}

/** Read the logged-in account's email from an app-server socket (`account/read`). Fails to `null`. */
export function readCodexAccountAt(
  socketPath: string,
  timeoutMs = REQUEST_TIMEOUT_MS
): Promise<{ email: string | null } | null> {
  return new Promise((resolve) => {
    let settled = false
    let ws: WebSocket
    const finish = (value: { email: string | null } | null): void => {
      if (settled) return
      settled = true
      clearTimeout(timer)
      try {
        ws.close()
      } catch {
        /* the connection may never have opened */
      }
      resolve(value)
    }
    const timer = setTimeout(() => finish(null), timeoutMs)
    timer.unref?.()
    try {
      ws = connectCodexAppServer(socketPath)
    } catch {
      clearTimeout(timer)
      resolve(null)
      return
    }
    ws.once('open', () => {
      ws.send(
        JSON.stringify({
          id: 1,
          method: 'initialize',
          params: { clientInfo: { name: 'nodeterm', version: '1' } }
        })
      )
    })
    ws.on('message', (raw) => {
      let message: Record<string, any>
      try {
        message = JSON.parse(raw.toString())
      } catch {
        return
      }
      if (message.id === 1) {
        if (message.error) return finish(null)
        ws.send(JSON.stringify({ method: 'initialized' }))
        ws.send(JSON.stringify({ id: 2, method: 'account/read', params: {} }))
      } else if (message.id === 2) {
        const account = message.result?.account
        const email =
          typeof account?.email === 'string' && account.email.trim()
            ? account.email.trim()
            : typeof message.result?.email === 'string' && message.result.email.trim()
              ? message.result.email.trim()
              : null
        finish(message.error ? null : { email })
      }
    })
    ws.once('error', () => finish(null))
    ws.once('close', () => finish(null))
  })
}

/** Drop the memoized/coalesced name state — for tests and for a relay/account-set change. */
export function forgetCodexSessionNames(): void {
  names.clear()
  inflight.clear()
}

/**
 * The READ leg for `TITLE_READ_CAPABLE`. Memoized for `CACHE_MS` and coalesced, because the
 * session-name sweep asks once a minute PER NODE and every ask is a socket connect.
 *
 * When the shared app-server reports no name, fall back to the relay's on-disk copy
 * (`relayedCodexSessionName`) so a conversation forked in the TUI still shows its title.
 *
 * On a host that cannot reach the app-server at all (Windows — see `codexAppServerReachable`) the
 * relayed copy IS the read: no socket connect that can only fail, on every sweep. A named-pipe
 * app-server endpoint is the follow-up once one is confirmed on a device.
 */
export function readCodexSessionName(
  threadId: string,
  socketPath = defaultCodexAppServerSocket(),
  hostPlatform: NodeJS.Platform = process.platform
): Promise<string | null> {
  if (!isSafeThreadId(threadId)) return Promise.resolve(null)
  const key = `${socketPath}\0${threadId}`
  const cached = names.get(key)
  if (cached && Date.now() - cached.at < CACHE_MS) return Promise.resolve(cached.name)
  if (!codexAppServerReachable(hostPlatform)) {
    return Promise.resolve(relayedCodexSessionName(socketPath, threadId))
  }
  const running = inflight.get(key)
  if (running) return running
  const request = readCodexSessionNameAt(socketPath, threadId).then(
    (serverName) => {
      const name = serverName ?? relayedCodexSessionName(socketPath, threadId)
      names.set(key, { name, at: Date.now() })
      inflight.delete(key)
      return name
    },
    () => {
      inflight.delete(key)
      return null
    }
  )
  inflight.set(key, request)
  return request
}