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.5 KB
Raw Blame
import { describe, it, expect } from 'vitest'
import {
  buildLinkDoc,
  buildContextLinkSkillBody,
  buildLinkedContextInstructions,
  mergeInstructionsBlock,
  resolveLinkTranscript,
  setNodeTranscript,
  transcriptPathOf,
  CONTEXT_SHIM_SCRIPT,
  CONTEXT_UNREACHABLE_MSG
} from './context-link-core'
import { CODEX_SANDBOX_BLOCKED_LINE } from './agents/hook-sandbox-hint-sh'
import { FOREIGN_ENDPOINT_HINT, OWNER_UNREACHABLE_LEAD, TUNNEL_DOWN_HINT } from './agents/hook-endpoint-failover-sh'

describe('buildLinkDoc', () => {
  it('enriches each link with tmux name, injected transcript path, and cwd', () => {
    const doc = buildLinkDoc(
      'node-A',
      [
        { id: 'node-B', title: 'Builder', cwd: '/proj' },
        { id: 'node-C', title: 'Tester' }
      ],
      {
        transcriptOf: (id) => (id === 'node-B' ? '/t/b.jsonl' : ''),
        tmuxBin: '/usr/bin/tmux',
        tmuxSocket: 'node-terminal'
      }
    )
    expect(doc.self).toEqual({ id: 'node-A' })
    expect(doc.tmuxBin).toBe('/usr/bin/tmux')
    expect(doc.tmuxSocket).toBe('node-terminal')
    expect(doc.links).toEqual([
      { id: 'node-B', title: 'Builder', cwd: '/proj', transcriptPath: '/t/b.jsonl', tmux: 'nt-node-B' },
      { id: 'node-C', title: 'Tester', cwd: '', transcriptPath: '', tmux: 'nt-node-C' }
    ])
  })

  it('carries a sticky note through with empty transcript/tmux', () => {
    const doc = buildLinkDoc('node-A', [{ id: 'note-1', title: 'Deploy notes', note: 'use staging' }], {
      transcriptOf: () => '/should/not/be/used.jsonl',
      tmuxBin: '/usr/bin/tmux',
      tmuxSocket: 'node-terminal'
    })
    expect(doc.links).toEqual([
      { id: 'note-1', title: 'Deploy notes', cwd: '', transcriptPath: '', tmux: '', note: 'use staging' }
    ])
  })

  it('sanitizes the tmux session name like the pty manager', () => {
    const doc = buildLinkDoc('x', [{ id: 'a b/c.d', title: 'T' }], {
      transcriptOf: () => '',
      tmuxBin: null,
      tmuxSocket: 's'
    })
    expect(doc.links[0].tmux).toBe('nt-a_b_c_d')
  })
})

describe('buildLinkDoc agent field', () => {
  it('copies agentId onto the entry; notes get none', () => {
    const doc = buildLinkDoc(
      'node-A',
      [
        { id: 'node-B', title: 'B', cwd: '', agentId: 'codex' },
        { id: 'note-1', title: 'N', note: 'txt' }
      ],
      { transcriptOf: () => '', tmuxBin: null, tmuxSocket: 's' }
    )
    expect(doc.links[0].agent).toBe('codex')
    expect(doc.links[1].agent).toBeUndefined()
  })
})

describe('buildLinkDoc sessionId field', () => {
  it('copies sessionId onto the entry (opencode exports by id); notes get none', () => {
    const doc = buildLinkDoc(
      'node-A',
      [
        { id: 'node-O', title: 'O', cwd: '', agentId: 'opencode', sessionId: 'ses_1' },
        { id: 'node-B', title: 'B', cwd: '', agentId: 'codex' },
        { id: 'note-1', title: 'N', note: 'txt' }
      ],
      { transcriptOf: () => '', tmuxBin: null, tmuxSocket: 's' }
    )
    expect(doc.links[0].sessionId).toBe('ses_1')
    expect(doc.links[1].sessionId).toBeUndefined()
    expect(doc.links[2].sessionId).toBeUndefined()
  })
})

describe('resolveLinkTranscript', () => {
  const locators = {
    claude: async (sid: string, acct?: string) => `/c/${acct ?? 'default'}/${sid}.jsonl`,
    codex: async (sid: string) => `/x/${sid}.jsonl`,
    gemini: async (sid: string) => `/g/${sid}.jsonl`
  }
  // A REMOTE node's transcript is on the host; these locators search THIS machine's disk. Without
  // the guard they resolve happily and the agent reads an unrelated local session's conversation
  // with no sign anything is wrong — so the guard must win even where a locator WOULD have answered.
  it('never consults the local locators for a remote node', async () => {
    const link = { id: 'n1', title: 'T', agentId: 'codex', sessionId: 's1' }
    const local = await resolveLinkTranscript(link, { hooked: () => '', locators })
    expect(local).toBe('/x/s1.jsonl') // proves the locator WOULD have answered
    const remote = await resolveLinkTranscript(link, {
      hooked: () => '',
      locators,
      isRemote: () => true
    })
    expect(remote).toBe('')
  })

  it("still prefers a remote node's hook-fed path (the only trustworthy source there)", async () => {
    const p = await resolveLinkTranscript(
      { id: 'n1', title: 'T', agentId: 'claude', sessionId: 's1' },
      { hooked: () => '/remote/jailed.jsonl', locators, isRemote: () => true }
    )
    expect(p).toBe('/remote/jailed.jsonl')
  })

  it('claude prefers the hook-fed path', async () => {
    const p = await resolveLinkTranscript(
      { id: 'n1', title: 'T', agentId: 'claude', sessionId: 's1' },
      { hooked: () => '/hooked.jsonl', locators }
    )
    expect(p).toBe('/hooked.jsonl')
  })
  it('claude falls back to the locator with accountId when hooks have nothing', async () => {
    const p = await resolveLinkTranscript(
      { id: 'n1', title: 'T', agentId: 'claude', sessionId: 's1', accountId: 'a1' },
      { hooked: () => '', locators }
    )
    expect(p).toBe('/c/a1/s1.jsonl')
  })
  it('a legacy entry without agentId behaves like claude', async () => {
    const p = await resolveLinkTranscript(
      { id: 'n1', title: 'T' },
      { hooked: () => '/hooked.jsonl', locators }
    )
    expect(p).toBe('/hooked.jsonl')
  })
  it('codex and gemini resolve via their locator by sessionId', async () => {
    expect(
      await resolveLinkTranscript({ id: 'n', title: 'T', agentId: 'codex', sessionId: 's2' }, { hooked: () => '/hooked', locators })
    ).toBe('/x/s2.jsonl')
    expect(
      await resolveLinkTranscript({ id: 'n', title: 'T', agentId: 'gemini', sessionId: 's3' }, { hooked: () => '/hooked', locators })
    ).toBe('/g/s3.jsonl')
  })
  it('resolves empty on: note entries, missing sessionId, unknown agent, locator throw', async () => {
    const base = { hooked: () => '', locators }
    expect(await resolveLinkTranscript({ id: 'n', title: 'T', note: 'x' }, base)).toBe('')
    expect(await resolveLinkTranscript({ id: 'n', title: 'T', agentId: 'codex' }, base)).toBe('')
    expect(await resolveLinkTranscript({ id: 'n', title: 'T', agentId: 'custom:x', sessionId: 's' }, base)).toBe('')
    expect(
      await resolveLinkTranscript(
        { id: 'n', title: 'T', agentId: 'codex', sessionId: 's' },
        { hooked: () => '', locators: { codex: async () => { throw new Error('boom') } } }
      )
    ).toBe('')
  })
})

describe('setNodeTranscript / transcriptPathOf', () => {
  it('stores and returns the transcript path by node id', () => {
    setNodeTranscript('n1', 'sess', '/path/one.jsonl')
    expect(transcriptPathOf('n1')).toBe('/path/one.jsonl')
  })
  it('ignores empty node id or path', () => {
    setNodeTranscript('', 's', '/p.jsonl')
    setNodeTranscript('n2', 's', '')
    expect(transcriptPathOf('n2')).toBe('')
  })
  it('returns empty string for an unknown node', () => {
    expect(transcriptPathOf('nope')).toBe('')
  })
})

describe('mergeInstructionsBlock', () => {
  const block = 'Use the CLI: sh "/x/context.sh" list'
  it('appends the marker-delimited block to existing content', () => {
    const out = mergeInstructionsBlock('# My rules\n\nBe nice.\n', block)
    expect(out).toContain('# My rules')
    expect(out).toContain('<!-- nodeterm:get-linked-context:start -->')
    expect(out).toContain(block)
    expect(out).toContain('<!-- nodeterm:get-linked-context:end -->')
  })
  it('is idempotent: re-merging replaces the block in place', () => {
    const once = mergeInstructionsBlock('# My rules\n', block)
    const twice = mergeInstructionsBlock(once, 'UPDATED body')
    expect(twice.match(/nodeterm:get-linked-context:start/g)).toHaveLength(1)
    expect(twice).toContain('UPDATED body')
    expect(twice).not.toContain('sh "/x/context.sh" list')
    expect(twice).toContain('# My rules')
  })
  it('works on an empty file', () => {
    const out = mergeInstructionsBlock('', block)
    expect(out.startsWith('<!-- nodeterm:get-linked-context:start -->')).toBe(true)
  })
  it('a stray end marker BEFORE the block does not make every merge append another copy', () => {
    // A user who deletes our block by hand but leaves its end line: the end marker is found first,
    // and a merge that took the first end marker anywhere read "no block" and appended — again on
    // every connect, forever. The end marker is searched AFTER the start marker.
    const stray = '# mine\n<!-- nodeterm:get-linked-context:end -->\n'
    const once = mergeInstructionsBlock(stray, block)
    expect(mergeInstructionsBlock(once, block)).toBe(once)
    expect(once.match(/get-linked-context:start/g)).toHaveLength(1)
    expect(once.startsWith(stray)).toBe(true)
  })
})

describe('buildLinkedContextInstructions', () => {
  it('embeds the shim path and the four commands', () => {
    const s = buildLinkedContextInstructions('/x/context.sh')
    expect(s).toContain('sh "/x/context.sh" list')
    expect(s).toContain('summary')
    expect(s).toContain('transcript')
    expect(s).toContain('terminal')
  })

  // Issue #367 — same parity discipline as canvas-control-core.test.ts: the shim's error
  // sentences and the docs explaining them share constants, so neither can drift alone. The
  // runtime behaviour is proven against real /bin/sh in context-link.cli.test.ts.
  it('both agent-facing texts carry the codex-sandbox transport guidance (issue #367)', () => {
    for (const body of [buildContextLinkSkillBody('/x/context.sh'), buildLinkedContextInstructions('/x/context.sh')]) {
      expect(body).toContain(CONTEXT_UNREACHABLE_MSG.replace(/\.$/, ''))
      expect(body).toContain(CODEX_SANDBOX_BLOCKED_LINE)
      expect(body.toLowerCase()).toContain('escalated permissions')
      expect(body).toMatch(/never relink, reinstall or restart nodeterm/)
      expect(body).toContain('network.allow_unix_sockets')
      expect(body).toContain('~/.codex/config.toml')
    }
  })

  // Same pin as canvas-control-core.test.ts: the context shim printed the foreign instance's
  // "No linked nodes" on 2026-09-28/29, and the bodies tell an agent not to retry THAT. The
  // owner-unreachable sentence that replaces it must be taught as temporary, in its own words.
  it('both agent-facing texts teach the owner-unreachable failure as temporary', () => {
    expect(CONTEXT_SHIM_SCRIPT).toContain(`echo "${FOREIGN_ENDPOINT_HINT}" >&2`)
    // The tunnel variant (no foreign endpoint, SSH tunnel primary) opens with the same quoted lead.
    expect(TUNNEL_DOWN_HINT.startsWith(OWNER_UNREACHABLE_LEAD)).toBe(true)
    expect(CONTEXT_SHIM_SCRIPT).toContain(`echo "${TUNNEL_DOWN_HINT}" >&2`)
    for (const body of [buildContextLinkSkillBody('/x/context.sh'), buildLinkedContextInstructions('/x/context.sh')]) {
      expect(body).toContain(OWNER_UNREACHABLE_LEAD.replace(/\.$/, ''))
      expect(body).toMatch(/This is temporary: *\n?retry the same *\n?command later/)
    }
  })

  it('the shim embeds the sandbox hint, keeping the generic sentence for the non-sandbox case', () => {
    expect(CONTEXT_SHIM_SCRIPT).toContain('nt_codex_sandbox_hint() {')
    expect(CONTEXT_SHIM_SCRIPT).toContain('nt_codex_sandbox_hint && exit 1')
    expect(CONTEXT_SHIM_SCRIPT).toContain(`echo "${CONTEXT_UNREACHABLE_MSG}" >&2`)
  })
})

// The context-link shim is generated source that no compiler ever checks, and it is the only
// context-link client. A quoting or `for`-list slip in it fails silently on the user's machine —
// and, for an SSH project, on a machine we cannot inspect. `sh -n` is the cheap half of the
// discipline the canvas-control shim gets in full (canvas-control-shim.test.ts runs that one for
// real); the two share `nt_read_node_token`, so the behaviour is covered there.
describe('the context-link shim', () => {
  it('is valid POSIX sh', async () => {
    const { execFile } = await import('node:child_process')
    const { promisify } = await import('node:util')
    const fs = await import('node:fs')
    const os = await import('node:os')
    const path = await import('node:path')
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'nodeterm-context-shim-'))
    const file = path.join(dir, 'context.sh')
    fs.writeFileSync(file, CONTEXT_SHIM_SCRIPT, { mode: 0o755 })
    try {
      await expect(promisify(execFile)('/bin/sh', ['-n', file])).resolves.toBeTruthy()
    } finally {
      fs.rmSync(dir, { recursive: true, force: true })
    }
  })

  it('resolves the per-node token through the one shared reader (#384)', () => {
    // Not a second copy of `head -n 1 "$NODETERM_NODE_TOKEN_DIR/…"`: that copy is what left a
    // session pinned to a pre-v2 endpoint file presenting nothing for its whole life.
    expect(CONTEXT_SHIM_SCRIPT).toContain('nt_read_node_token')
    expect(CONTEXT_SHIM_SCRIPT).not.toContain('nt_node_token=$(head -n 1 "$NODETERM_NODE_TOKEN_DIR')
  })
})

describe('buildContextLinkSkillBody — shim invocation dialect', () => {
  it('the default is the historical `sh` block, unchanged', () => {
    const body = buildContextLinkSkillBody('/x/context.sh')
    expect(body).toContain('```sh\nsh "/x/context.sh" <command> [--node <id|title>] [-n <N>]\n```\n\nCommands:')
    expect(body).toBe(buildContextLinkSkillBody('/x/context.sh', 'posix'))
  })

  it('windows-cmd: names context.cmd through PowerShell and keeps the command reference', () => {
    const body = buildContextLinkSkillBody('C:\\d\\context.sh', 'windows-cmd')
    expect(body).toContain('```powershell\n& "C:\\d\\context.cmd" <command> [--node <id|title>] [-n <N>]\n```')
    expect(body).toContain('Git for Windows')
    const tail = (b: string) => b.slice(b.indexOf('Commands:'))
    expect(tail(body)).toBe(tail(buildContextLinkSkillBody('C:\\d\\context.sh')))
  })
})