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.

13.7 KB
Raw Blame
// The app-server protocol client, against a real WebSocket server on a real unix socket.
//
// Two of its answers are load-bearing in ways a mocked test would not show: `codexThreadExistsAt`
// is what stands between a stale session id and a node that dies AFTER exec (where no fallback is
// left), and both readers must answer the conservative thing when the server is simply not there —
// which, for a CLI whose app-server starts on demand, is a completely ordinary state.
import { describe, it, expect, beforeAll, afterAll } from 'vitest'
import fs from 'node:fs'
import os from 'node:os'
import http from 'node:http'
import path from 'node:path'
import { WebSocketServer, type WebSocket } from 'ws'
import { createHash } from 'node:crypto'
import {
  codexThreadExistsAt,
  codexUnixWebSocketUrl,
  forgetCodexSessionNames,
  readCodexAccountAt,
  readCodexSessionName,
  readCodexSessionNameAt,
  readCodexThreadAt,
  relayedCodexSessionName,
  rememberCodexSessionName,
  waitForCodexAppServer
} from './codex-session-name'

let dir = ''
let sock = ''
let server: http.Server
let wss: WebSocketServer
/** Threads the fake app-server knows about, id → name. */
const threads = new Map<string, string | null>([
  ['thread-known', 'Named by codex'],
  ['thread-nameless', null]
])
let initializeFails = false

function handle(ws: WebSocket): void {
  ws.on('message', (raw) => {
    const msg = JSON.parse(raw.toString()) as Record<string, any>
    if (msg.method === 'initialize') {
      ws.send(
        JSON.stringify(
          initializeFails
            ? { id: msg.id, error: { message: 'not authenticated' } }
            : { id: msg.id, result: {} }
        )
      )
      return
    }
    if (msg.method === 'thread/read') {
      const id = msg.params?.threadId as string
      if (!threads.has(id)) {
        ws.send(JSON.stringify({ id: msg.id, error: { message: 'no rollout found' } }))
        return
      }
      ws.send(JSON.stringify({ id: msg.id, result: { thread: { id, name: threads.get(id) } } }))
    }
  })
}

beforeAll(async () => {
  // Short prefix and short socket name ON PURPOSE. Unix socket paths are capped at `sun_path`
  // (104 bytes on macOS), and macOS's `os.tmpdir()` is already ~49 of them
  // (`/var/folders/ab/…/T/`); a descriptive prefix plus `app-server-control.sock` lands exactly on
  // the limit and fails to bind on a developer's machine while passing in CI. Everything still
  // lives inside the mkdtemp directory, so the path stays unpredictable.
  dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-cx-'))
  sock = path.join(dir, 'as.sock')
  server = http.createServer()
  wss = new WebSocketServer({ server })
  wss.on('connection', handle)
  await new Promise<void>((resolve) => server.listen(sock, resolve))
})

afterAll(async () => {
  await new Promise<void>((resolve) => wss.close(() => resolve()))
  await new Promise<void>((resolve) => server.close(() => resolve()))
  fs.rmSync(dir, { recursive: true, force: true })
})

describe('codexThreadExistsAt', () => {
  it('confirms a thread the app-server knows', async () => {
    expect(await codexThreadExistsAt(sock, 'thread-known')).toBe(true)
    expect(await codexThreadExistsAt(sock, 'thread-nameless')).toBe(true)
  })

  it('refuses an id the app-server never heard of (the stale-session-id case)', async () => {
    // This is the whole point: the launcher's bind falls back to plain codex instead of exec'ing
    // a resume that dies with "no rollout found" where nothing can catch it.
    expect(await codexThreadExistsAt(sock, 'thread-from-a-past-life')).toBe(false)
  })

  it('refuses when the app-server is not running at all', async () => {
    expect(await codexThreadExistsAt(path.join(dir, 'nope.sock'), 'thread-known', 500, 1)).toBe(
      false
    )
  })

  it('waits out a daemon whose socket is still binding, instead of refusing a good resume', async () => {
    // `codex app-server daemon start` exiting 0 does not mean the socket is listening yet, and
    // this check runs immediately after it on the cold/reboot path. Without the retry, a daemon
    // that binds a beat late turns a legitimate resume into `thread-bind-refused` → plain codex:
    // a NEW way to lose shared identity on exactly the path the feature exists for.
    const latePath = path.join(dir, 'lt.sock')
    const late = http.createServer()
    const lateWss = new WebSocketServer({ server: late })
    lateWss.on('connection', handle)
    const listening = new Promise<void>((resolve) =>
      setTimeout(() => late.listen(latePath, resolve), 250)
    )
    try {
      expect(await codexThreadExistsAt(latePath, 'thread-known', 500)).toBe(true)
    } finally {
      await listening
      await new Promise<void>((resolve) => lateWss.close(() => resolve()))
      await new Promise<void>((resolve) => late.close(() => resolve()))
    }
  })

  it('does NOT retry a server that answered — "I do not have it" is an answer', async () => {
    // Retrying a definite no just delays it. Measured by the clock: three attempts with the
    // default 200ms gap could not come back this fast.
    const started = Date.now()
    expect(await codexThreadExistsAt(sock, 'thread-from-a-past-life')).toBe(false)
    expect(Date.now() - started).toBeLessThan(200)
  })

  it('refuses an id that is not shaped like one, without opening a socket', async () => {
    expect(await codexThreadExistsAt(sock, '../../etc/passwd')).toBe(false)
  })

  it('refuses when the server will not initialize (a logged-out CLI)', async () => {
    initializeFails = true
    try {
      expect(await codexThreadExistsAt(sock, 'thread-known')).toBe(false)
    } finally {
      initializeFails = false
    }
  })
})

describe('waitForCodexAppServer', () => {
  it('answers true for a live socket and false for a dead one, without throwing', async () => {
    expect(await waitForCodexAppServer(sock, 1)).toBe(true)
    expect(await waitForCodexAppServer(path.join(dir, 'nope.sock'), 2, 10)).toBe(false)
  })
})

describe('readCodexSessionNameAt', () => {
  it("reads the thread's own name", async () => {
    expect(await readCodexSessionNameAt(sock, 'thread-known')).toBe('Named by codex')
  })

  it('answers null for a nameless or unknown thread, and for a dead server', async () => {
    // Null means "the node keeps its own title" — never a wrong one.
    expect(await readCodexSessionNameAt(sock, 'thread-nameless')).toBeNull()
    expect(await readCodexSessionNameAt(sock, 'thread-from-a-past-life')).toBeNull()
    expect(await readCodexSessionNameAt(path.join(dir, 'nope.sock'), 'thread-known', 500)).toBeNull()
  })
})

describe('codexUnixWebSocketUrl', () => {
  it('refuses a socket path that could not survive being put in a URL', () => {
    expect(() => codexUnixWebSocketUrl('relative/app-server.sock')).toThrow()
    expect(() => codexUnixWebSocketUrl('/tmp/with space/app.sock')).toThrow()
    expect(() => codexUnixWebSocketUrl('/tmp/a?b/app.sock')).toThrow()
  })
})

describe('relayedCodexSessionName (the on-disk relay fallback)', () => {
  it('reads, trims and caps the name the relay stored under the socket-scoped path', () => {
    const home = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-relay-name-'))
    const socketPath = '/home/x/.codex/app-server-control/app-server-control.sock'
    const scope = createHash('sha256').update(socketPath).digest('hex').slice(0, 16)
    const nameDir = path.join(home, '.nodeterm', 'codex-thread-names', scope)
    fs.mkdirSync(nameDir, { recursive: true })
    fs.writeFileSync(path.join(nameDir, 'thread-1'), `  ${'z'.repeat(600)}  `)
    const value = relayedCodexSessionName(socketPath, 'thread-1', home)
    expect(value).toBe('z'.repeat(500))
    expect(relayedCodexSessionName(socketPath, 'thread-missing', home)).toBeNull()
    expect(relayedCodexSessionName(socketPath, '../escape', home)).toBeNull()
    fs.rmSync(home, { recursive: true, force: true })
  })
})

describe('readCodexSessionName relay fallback wiring', () => {
  it('falls back to the relayed name when the app-server reports none, and a real name wins', async () => {
    const savedHome = process.env.HOME
    const home = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-name-wire-'))
    process.env.HOME = home
    forgetCodexSessionNames()
    try {
      const scope = createHash('sha256').update(sock).digest('hex').slice(0, 16)
      const nameDir = path.join(home, '.nodeterm', 'codex-thread-names', scope)
      fs.mkdirSync(nameDir, { recursive: true })
      fs.writeFileSync(path.join(nameDir, 'thread-nameless'), 'Relayed title')
      // The server has this thread but with a null name → the relay copy fills in.
      expect(await readCodexSessionName('thread-nameless', sock)).toBe('Relayed title')
      forgetCodexSessionNames()
      // A real server name always wins over the relay copy.
      fs.writeFileSync(path.join(nameDir, 'thread-known'), 'Stale relayed title')
      expect(await readCodexSessionName('thread-known', sock)).toBe('Named by codex')
    } finally {
      forgetCodexSessionNames()
      if (savedHome === undefined) delete process.env.HOME
      else process.env.HOME = savedHome
      fs.rmSync(home, { recursive: true, force: true })
    }
  })
})

describe('rememberCodexSessionName', () => {
  it('seeds the cache so the next read serves it without a socket, and rejects a bad id', async () => {
    forgetCodexSessionNames()
    try {
      // A dead socket would answer null; the seeded value is served instead.
      const dead = path.join(dir, 'dead-remember.sock')
      rememberCodexSessionName('thread-seeded', 'Seeded title', dead)
      expect(await readCodexSessionName('thread-seeded', dead)).toBe('Seeded title')
      rememberCodexSessionName('../bad', 'ignored', dead)
      expect(relayedCodexSessionName(dead, '../bad')).toBeNull()
    } finally {
      forgetCodexSessionNames()
    }
  })
})

describe('readCodexThreadAt / readCodexAccountAt', () => {
  let d = ''
  let s = ''
  let srv: http.Server
  let w: WebSocketServer

  beforeAll(async () => {
    d = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-cx2-'))
    s = path.join(d, 'as.sock')
    srv = http.createServer()
    w = new WebSocketServer({ server: srv })
    w.on('connection', (ws) => {
      ws.on('message', (raw) => {
        const msg = JSON.parse(raw.toString()) as Record<string, any>
        if (msg.method === 'initialize') return ws.send(JSON.stringify({ id: msg.id, result: {} }))
        if (msg.method === 'thread/read') {
          const id = msg.params?.threadId as string
          if (id === 'thread-a')
            return ws.send(
              JSON.stringify({
                id: msg.id,
                result: { thread: { id, name: 'A', path: '/abs/rollout-thread-a.jsonl' } }
              })
            )
          if (id === 'thread-b')
            return ws.send(
              JSON.stringify({ id: msg.id, result: { thread: { id, name: null, path: 'relative' } } })
            )
          if (id === 'thread-forked')
            // The server answers with a DIFFERENT id — must be refused.
            return ws.send(
              JSON.stringify({ id: msg.id, result: { thread: { id: 'other', path: '/abs/x.jsonl' } } })
            )
          return ws.send(JSON.stringify({ id: msg.id, error: { message: 'no rollout found' } }))
        }
        if (msg.method === 'account/read')
          return ws.send(
            JSON.stringify({ id: msg.id, result: { account: { email: '  [email protected]  ' } } })
          )
      })
    })
    await new Promise<void>((resolve) => srv.listen(s, resolve))
  })

  afterAll(async () => {
    await new Promise<void>((resolve) => w.close(() => resolve()))
    await new Promise<void>((resolve) => srv.close(() => resolve()))
    fs.rmSync(d, { recursive: true, force: true })
  })

  it('reads id, name and absolute path; drops a non-absolute path to null', async () => {
    expect(await readCodexThreadAt(s, 'thread-a')).toEqual({
      id: 'thread-a',
      name: 'A',
      path: '/abs/rollout-thread-a.jsonl'
    })
    expect(await readCodexThreadAt(s, 'thread-b')).toEqual({ id: 'thread-b', name: null, path: null })
  })

  it('refuses a response whose thread id does not match the one asked for', async () => {
    expect(await readCodexThreadAt(s, 'thread-forked')).toBeNull()
    expect(await readCodexThreadAt(s, 'thread-unknown')).toBeNull()
    expect(await readCodexThreadAt(s, '../../etc/passwd')).toBeNull()
  })

  it('reads and trims the account email', async () => {
    expect(await readCodexAccountAt(s)).toEqual({ email: '[email protected]' })
  })
})

describe('readCodexSessionName on a host with no reachable app-server (Windows)', () => {
  it('serves the relayed copy without dialing the socket', async () => {
    const savedHome = process.env.HOME
    const home = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-name-win-'))
    process.env.HOME = home
    forgetCodexSessionNames()
    try {
      // `thread-known` has a real server name; on win32 the socket is never asked, so the relayed
      // copy is the answer — proof that no WebSocket was dialed.
      const scope = createHash('sha256').update(sock).digest('hex').slice(0, 16)
      const nameDir = path.join(home, '.nodeterm', 'codex-thread-names', scope)
      fs.mkdirSync(nameDir, { recursive: true })
      fs.writeFileSync(path.join(nameDir, 'thread-known'), 'Relayed only')
      expect(await readCodexSessionName('thread-known', sock, 'win32')).toBe('Relayed only')
      expect(await readCodexSessionName('thread-absent', sock, 'win32')).toBeNull()
      // A seeded cache still wins first.
      rememberCodexSessionName('thread-seeded-win', 'Seeded', sock)
      expect(await readCodexSessionName('thread-seeded-win', sock, 'win32')).toBe('Seeded')
    } finally {
      forgetCodexSessionNames()
      if (savedHome === undefined) delete process.env.HOME
      else process.env.HOME = savedHome
      fs.rmSync(home, { recursive: true, force: true })
    }
  })
})