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.

6.3 KB
Raw Blame
import { describe, it, expect } from 'vitest'
import { parseRpcMessage, encodeArgs, encodePtyData, decodePtyData } from './rpc'

/** What a sender actually puts on the wire: encode the arg slots, then JSON. */
const wire = (method: string, ...args: unknown[]): string =>
  JSON.stringify({ t: 'cast', method, ...encodeArgs(args) })

describe('rpc protocol', () => {
  it('parses each message kind and rejects malformed input', () => {
    expect(parseRpcMessage('{"t":"req","id":1,"method":"pty:create","args":[{}]}')).toEqual({
      t: 'req', id: 1, method: 'pty:create', args: [{}]
    })
    expect(parseRpcMessage('{"t":"cast","method":"pty:write","args":["s1","ls\\r"]}')).toEqual({
      t: 'cast', method: 'pty:write', args: ['s1', 'ls\r']
    })
    expect(parseRpcMessage('{"t":"res","id":1,"ok":true,"result":42}')).toEqual({
      t: 'res', id: 1, ok: true, result: 42
    })
    expect(parseRpcMessage('{"t":"ev","channel":"pty:exit:s1","args":[0]}')).toEqual({
      t: 'ev', channel: 'pty:exit:s1', args: [0]
    })
    expect(parseRpcMessage('not json')).toBeNull()
    expect(parseRpcMessage('{"t":"nope"}')).toBeNull()
    expect(parseRpcMessage('{"t":"req","id":"x","method":1}')).toBeNull()
  })

  // `JSON.stringify([a, undefined])` is `[a, null]` — raw JSON has no `undefined`. A browser call
  // that omits a trailing optional argument (`git.history(cwd)`, `worktreeMerge(repo, b, base)`)
  // would therefore reach the handler as an EXPLICIT `null`, which does NOT trigger a default
  // parameter: `worktreeMerge(…, push = false)` would run with `push === null` (`git.history` broke
  // exactly this way). `encodeArgs` marks the `undefined` slots explicitly, so the decoder RESTORES
  // them instead of guessing from `null`.
  it('round-trips an omitted trailing argument as undefined, so default parameters apply', () => {
    const req = parseRpcMessage(
      JSON.stringify({
        t: 'req',
        id: 1,
        method: 'git:worktree-merge',
        ...encodeArgs(['/repo', 'feat', 'main', undefined])
      })
    )
    expect(req).toEqual({
      t: 'req', id: 1, method: 'git:worktree-merge', args: ['/repo', 'feat', 'main', undefined]
    })
    // Arity is preserved (the slot stays), and `undefined` is what makes `push = false` fire.
    const args = (req as { args: unknown[] }).args
    expect(args.length).toBe(4)
    const push = args[3] as boolean | undefined
    expect(((p = false) => p)(push)).toBe(false)

    // Interior undefined slots survive too.
    expect(parseRpcMessage(wire('m', undefined, 2))).toEqual({
      t: 'cast', method: 'm', args: [undefined, 2]
    })
  })

  // The counterpart, and the reason the old blanket `null → undefined` decode was a BUG: several
  // methods take a MEANINGFUL top-level `null` — `pty.resize(sid, null, null)` is the co-attach
  // "park" signal (drop me from the size ledger), `presence.cursor/focus/chat/project(null)` clear
  // state, `git.setActiveRemote(null)` clears the remote. Rewriting those to `undefined` collapsed
  // the shared pty to 1×1 (the strict `cols === null` park check missed, and `normalizeSize(
  // undefined, undefined)` clamps to 1). A null the caller MEANT must arrive as null.
  it('preserves a meaningful top-level null (park signal / clear-state casts)', () => {
    expect(parseRpcMessage(wire('pty:resize', 's1', null, null))).toEqual({
      t: 'cast', method: 'pty:resize', args: ['s1', null, null]
    })
    expect(parseRpcMessage(wire('presence:cursor', null))).toEqual({
      t: 'cast', method: 'presence:cursor', args: [null]
    })
    // …and a null and an omitted slot are distinguishable in the SAME call.
    expect(parseRpcMessage(wire('m', null, undefined))).toEqual({
      t: 'cast', method: 'm', args: [null, undefined]
    })
  })

  // The `undef` index list must be OUT OF BAND: an in-band sentinel string was compared with `===`
  // against every top-level argument, and several methods take one whole attacker-CHOOSABLE string
  // in a top-level slot — `pty.write(sid, data)` (a paste, or an agent-driven write),
  // `fs.write(path, content)`, presence chat. A payload equal to the sentinel decoded to
  // `undefined`: `pty.write` would have written nothing, `fs.write` would have thrown or truncated.
  it('never lets an argument VALUE pose as the undefined marker', () => {
    const evil = '\0__rpc_undefined__' // the old in-band sentinel, sent as real pty input
    expect(parseRpcMessage(wire('pty:write', 's1', evil))).toEqual({
      t: 'cast', method: 'pty:write', args: ['s1', evil]
    })
    // Even alongside a genuinely omitted slot in the same call.
    expect(parseRpcMessage(wire('fs:write', evil, undefined))).toEqual({
      t: 'cast', method: 'fs:write', args: [evil, undefined]
    })
  })

  it('ignores a junk `undef` list (it can never invent an argument slot)', () => {
    // Straight off a hostile socket: out-of-range / non-integer indexes mark nothing, and the arity
    // the sender chose is what the handler sees.
    expect(
      parseRpcMessage('{"t":"cast","method":"m","args":["a"],"undef":[5,-1,"x",1.5,null]}')
    ).toEqual({ t: 'cast', method: 'm', args: ['a'] })
    expect(parseRpcMessage('{"t":"cast","method":"m","args":["a"],"undef":"nope"}')).toEqual({
      t: 'cast', method: 'm', args: ['a']
    })
  })

  it('leaves a null NESTED inside an argument alone (encoding only marks top-level slots)', () => {
    // A null inside an object/array is real data the sender meant to send — `{cwd: null}` is not the
    // same as `{}` to a handler that checks `'cwd' in opts`. Only the top-level arg slots are the
    // ones JSON mangled, so only those are restored.
    expect(parseRpcMessage('{"t":"req","id":2,"method":"m","args":[{"cwd":null},[null]]}')).toEqual({
      t: 'req', id: 2, method: 'm', args: [{ cwd: null }, [null]]
    })
  })

  it('round-trips pty data through the binary codec (incl. multibyte)', () => {
    const buf = encodePtyData('nt-abc', 'çıktı ✓[31m')
    expect(buf[0]).toBe(0x01)
    expect(decodePtyData(buf)).toEqual({ sessionId: 'nt-abc', data: 'çıktı ✓[31m' })
  })

  it('decode returns null on truncated or unknown frames', () => {
    expect(decodePtyData(new Uint8Array([0x02, 0, 1, 65]))).toBeNull()
    expect(decodePtyData(new Uint8Array([0x01, 0, 9, 65]))).toBeNull() // len beyond buffer
    expect(decodePtyData(new Uint8Array([]))).toBeNull()
  })
})