Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

13.7 KB
Raw Blame
import { mkdtempSync, rmSync } from 'node:fs'
import { stat } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { randomUUID } from 'node:crypto'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type { RegisteredSession } from '../lib/registry.js'
import { AgentCreationReceipts } from '../lib/agentCreationReceipt.js'
import { shellContextReply } from '../lib/shellContextReply.js'
import { checkPidRuntime } from '../lib/deleteAgentFallback.js'
import type { TerminalPaneRead, TerminalRuntimeRef } from '../lib/terminalTypes.js'
import { fakeCore } from '../testing/fakeCore.js'
import { SHELL_REQUESTS, startShell } from './shell.js'
import { createTerminalSessions } from '../core/terminals/sessions.js'

vi.mock('node:fs/promises', async importOriginal => ({
  ...await importOriginal<typeof import('node:fs/promises')>(), stat: vi.fn(async () => ({ isDirectory: () => true })),
}))
vi.mock('../lib/shellContextReply.js', () => ({ shellContextReply: vi.fn(() => true) }))
vi.mock('../lib/deleteAgentFallback.js', () => ({ checkPidRuntime: vi.fn() }))
/** The pane's state as its own backend reads it (`TerminalBackend.paneState`), asked with the row's runtime. */
const tmuxPaneState = vi.fn<(runtime: TerminalRuntimeRef) => Promise<TerminalPaneRead>>()
const OWNER = { local: false, owner: true }
let dataDir: string
function setup() {
  const row = { agentId: 'shell', sessionId: '', engine: 'terminal', cwd: '/work/project', projectDir: 'project', launch: { state: 'ready' } } as RegisteredSession
  const core = fakeCore({ dataDir, terminals: { open: vi.fn(async () => ({ ok: true as const, agentId: 'shell' })) }, agents: {
    byAgent: vi.fn(() => row), displayName: () => 'project', terminalAvailable: () => true,
  } })
  Object.assign(core.terminals, createTerminalSessions({ agents: core.agents, paneState: tmuxPaneState, processState: checkPidRuntime }))
  const requests = startShell(core)
  const ask = (type: string, payload: Record<string, unknown> = {}, asker = OWNER) => requests[type]!(payload, asker)
  const payload = { creationId: randomUUID(), cwd: '/work/project', argv: ['/bin/zsh', '/work/a script', '$(touch nope)', 'a; b', ''] }
  return { core, requests, ask, payload }
}

describe('shells through a service', () => {
  beforeEach(() => { dataDir = mkdtempSync(join(tmpdir(), 'shell-service-')) })
  afterEach(() => { vi.useRealTimers(); vi.restoreAllMocks(); vi.clearAllMocks(); rmSync(dataDir, { recursive: true, force: true }) })
  it('declares every request and refuses every non-owner, regardless of the payload', async () => {
    const { requests, core, ask, payload } = setup()
    expect(Object.keys(requests).sort()).toEqual([...SHELL_REQUESTS].sort())
    for (const type of SHELL_REQUESTS) {
      expect(await ask(type, { ...payload, owner: true }, { local: false, owner: false })).toEqual({ error: 'OWNER_REQUIRED' })
    }
    expect(core.terminals.open).not.toHaveBeenCalled()
    expect(shellContextReply).not.toHaveBeenCalled()
    expect(await ask('shell_capabilities')).toEqual({ protocol: 1 })
    expect(await ask('shell_context_reply', { id: 'reply' })).toEqual({ ok: true })
    expect(shellContextReply).toHaveBeenCalledWith({ id: 'reply' })
    vi.mocked(shellContextReply).mockReturnValueOnce(false)
    expect(await ask('shell_context_reply')).toEqual({ ok: false })
  })
  it('opens exact argv once, recovers a lost reply and keeps the receipt across service restarts', async () => {
    const { core, ask, payload } = setup()
    const reply = await ask('shell_open', payload)
    expect(reply).toEqual({ creationId: payload.creationId, state: 'created', agent: {
      id: 'shell', sessionId: '', engine: 'terminal', name: 'project', status: 'active', launch: { state: 'ready' },
      terminal: { available: true }, project: { cwd: payload.cwd, root: payload.cwd, name: 'project' },
    } })
    expect(core.terminals.open).toHaveBeenCalledWith({ argv: payload.argv, cwd: payload.cwd })
    expect(vi.mocked(core.terminals.open).mock.calls[0]![0].argv).not.toBe(payload.argv)
    expect(await ask('shell_open', payload)).toEqual(reply)
    expect(await ask('shell_open_status', payload)).toEqual(reply)
    expect(await startShell(core).shell_open!(payload, OWNER)).toEqual(reply)
    expect(core.terminals.open).toHaveBeenCalledTimes(1)
    expect(await ask('shell_open', { ...payload, argv: ['/bin/bash'] })).toEqual({ error: 'CREATION_CONFLICT' })
    vi.mocked(core.agents.byAgent).mockReturnValue(undefined)
    expect(await ask('shell_open_status', payload)).toEqual({ creationId: payload.creationId, state: 'unavailable' })
  })
  it('requires a durable creation id, an absolute folder, and bounded literal argv', async () => {
    const { core, ask, payload } = setup()
    for (const type of ['shell_open', 'shell_open_status']) expect(await ask(type, { creationId: 'bad' })).toEqual({ error: 'INVALID_CREATION_ID' })
    for (const argv of [undefined, 'echo hello', [], new Array(257).fill('x'), [null], [1], ['x\0y'], [''], ['x'.repeat(32 * 1024)]]) {
      expect(await ask('shell_open', { ...payload, argv })).toEqual({ error: 'INVALID_ARGV' })
    }
    expect(await ask('shell_open', { ...payload, command: 'echo unsafe' })).toEqual({ error: 'INVALID_ARGV' })
    for (const cwd of [undefined, 'relative', '/x\0y', '/' + 'x'.repeat(4096)]) {
      expect(await ask('shell_open', { ...payload, cwd })).toEqual({ error: 'INVALID_CWD' })
    }
    expect(core.terminals.open).not.toHaveBeenCalled()
    expect(await ask('shell_open_status', payload)).toEqual({ creationId: payload.creationId, state: 'missing' })
  })
  it('records launch failures, and never retries an unconfirmed launch', async () => {
    const { core, ask, payload } = setup()
    vi.mocked(core.terminals.open).mockResolvedValueOnce({ ok: false, error: 'TMUX_UNAVAILABLE', detail: 'gone' })
    expect(await ask('shell_open', payload)).toEqual({ creationId: payload.creationId, state: 'failed', error: 'TMUX_UNAVAILABLE', detail: 'gone' })
    const next = { ...payload, creationId: randomUUID() }
    vi.mocked(core.terminals.open).mockRejectedValueOnce(new Error('the reply was lost'))
    expect(await ask('shell_open', next)).toEqual({ creationId: next.creationId, state: 'unconfirmed' })
    expect(await ask('shell_open', next)).toEqual({ creationId: next.creationId, state: 'unconfirmed' })
    expect(core.terminals.open).toHaveBeenCalledTimes(2)
  })
  it('refuses unreadable folders and files without opening a terminal', async () => {
    const { core, ask, payload } = setup()
    vi.mocked(stat).mockRejectedValueOnce(new Error('ENOENT'))
    expect(await ask('shell_open', payload)).toMatchObject({ state: 'failed', error: 'CWD_NOT_FOUND' })
    vi.mocked(stat).mockResolvedValueOnce({ isDirectory: () => false } as Awaited<ReturnType<typeof stat>>)
    expect(await ask('shell_open', { ...payload, creationId: randomUUID() })).toMatchObject({ state: 'failed', error: 'CWD_NOT_FOUND' })
    expect(core.terminals.open).not.toHaveBeenCalled()
  })
  it('bounds a filesystem provider that never answers', async () => {
    vi.useFakeTimers()
    const { core, ask, payload } = setup()
    vi.mocked(stat).mockImplementationOnce(() => new Promise(() => {}))
    const opening = ask('shell_open', payload)
    await vi.advanceTimersByTimeAsync(4001)
    expect(await opening).toMatchObject({ state: 'failed', error: 'CWD_NOT_FOUND' })
    expect(core.terminals.open).not.toHaveBeenCalled()
  })
  it('leaves unexpected failures to the service host instead of reporting a successful launch', async () => {
    const { ask, payload } = setup()
    vi.spyOn(AgentCreationReceipts.prototype, 'status').mockImplementationOnce(() => { throw new Error('unexpected') })
    await expect(ask('shell_open_status', payload)).rejects.toThrow('unexpected')
  })
  it('returns a shell view only after independent exit evidence for the same ready process', async () => {
    const { core, ask } = setup()
    const row = { agentId: 'agent', active: true, engine: 'claude', sessionId: 'chat', tmuxPane: '%2', runtimes: [{ backend: 'tmux', paneId: '%2' }], launch: { state: 'ready' },
      processIdentity: { pid: 22, startMarker: 'start', executable: '/bin/claude' } } as RegisteredSession
    for (const agentId of [undefined, '', 4, 'x'.repeat(257)]) expect(await ask('shell_visit_status', { agentId })).toEqual({ error: 'INVALID_AGENT_ID' })
    for (const current of [undefined, { ...row, engine: 'terminal' },
      { ...row, launch: { state: 'starting' } }, { ...row, launch: { state: 'failed' } }, { ...row, tmuxPane: '', runtimes: [] }, { ...row, processIdentity: undefined },
      { ...row, processIdentity: { ...row.processIdentity!, startMarker: '' } }]) {
      vi.mocked(core.agents.byAgent).mockReturnValue(current as RegisteredSession | undefined)
      expect(await ask('shell_visit_status', { agentId: 'agent' })).toEqual({ exited: false })
    }
    expect(tmuxPaneState).not.toHaveBeenCalled()
    vi.mocked(core.agents.byAgent).mockReturnValue(row)
    for (const pane of ['gone', 'unknown', { dead: false }]) {
      tmuxPaneState.mockClear()
      vi.mocked(tmuxPaneState).mockResolvedValueOnce(pane as Awaited<ReturnType<typeof tmuxPaneState>>)
      expect(await ask('shell_visit_status', { agentId: 'agent' })).toEqual({ exited: false })
      expect(tmuxPaneState).toHaveBeenCalledExactlyOnceWith({ backend: 'tmux', paneId: '%2' })
    }
    expect(checkPidRuntime).not.toHaveBeenCalled()
    vi.mocked(tmuxPaneState).mockResolvedValue({ dead: false, engineExit: 0 } as Awaited<ReturnType<typeof tmuxPaneState>>)
    for (const state of ['alive', 'unknown', 'gone'] as const) {
      vi.mocked(checkPidRuntime).mockResolvedValue({ state, reason: 'fixture' })
      expect(await ask('shell_visit_status', { agentId: 'agent' })).toEqual({ exited: state === 'gone' })
    }
    vi.mocked(core.agents.byAgent).mockReturnValue({ ...row, launch: undefined })
    expect(await ask('shell_visit_status', { agentId: 'agent' })).toEqual({ exited: true })
    vi.mocked(core.agents.byAgent).mockReturnValue(row)
    for (const replacement of [undefined, { ...row, sessionId: 'different' }, { ...row, launch: { state: 'starting' } },
      { ...row, processIdentity: { ...row.processIdentity!, startMarker: 'reused-pid' } }]) {
      vi.mocked(core.agents.byAgent).mockReturnValueOnce(row).mockReturnValueOnce(replacement as RegisteredSession | undefined)
      expect(await ask('shell_visit_status', { agentId: 'agent' })).toEqual({ exited: false })
    }
    expect(core.terminals.open).not.toHaveBeenCalled()
    expect(core.agents.sync).not.toHaveBeenCalled()
  })
  it('asks a ptyhost row\'s own runtime for its pane, never a tmux pane of the same id', async () => {
    const { core, ask } = setup()
    const pty = { backend: 'ptyhost' as const, instance: 'p1', paneId: '%2' }
    const row = { agentId: 'agent', active: true, engine: 'claude', sessionId: 'chat', tmuxPane: '%2', runtimes: [pty], launch: { state: 'ready' },
      processIdentity: { pid: 22, startMarker: 'start', executable: '/bin/claude' } } as RegisteredSession
    vi.mocked(core.agents.byAgent).mockReturnValue(row)
    tmuxPaneState.mockResolvedValue({ dead: false, engineExit: 0 } as TerminalPaneRead)
    vi.mocked(checkPidRuntime).mockResolvedValue({ state: 'gone', reason: 'fixture' })
    expect(await ask('shell_visit_status', { agentId: 'agent' })).toEqual({ exited: true })
    expect(tmuxPaneState).toHaveBeenCalledExactlyOnceWith(pty)
  })
  it('verifies an inactive resumed engine instead of stranding its parked shell', async () => {
    const { core, ask } = setup()
    const row = { agentId: 'agent', active: false, engine: 'claude', sessionId: 'chat', tmuxPane: '%2', runtimes: [{ backend: 'tmux', paneId: '%2' }], launch: { state: 'ready' },
      processIdentity: { pid: 22, startMarker: 'resumed', executable: '/bin/claude' } } as RegisteredSession
    vi.mocked(core.agents.byAgent).mockReturnValue(row)
    vi.mocked(tmuxPaneState).mockResolvedValue({ dead: false, engineExit: 0 } as Awaited<ReturnType<typeof tmuxPaneState>>)
    for (const state of ['alive', 'unknown', 'gone'] as const) {
      vi.mocked(checkPidRuntime).mockResolvedValue({ state, reason: 'fixture' })
      expect(await ask('shell_visit_status', { agentId: 'agent' })).toEqual({ exited: state === 'gone' })
    }
    expect(core.agents.sync).not.toHaveBeenCalled()
    expect(row.active).toBe(false)
  })
  it('coalesces exit probes, keeps a value snapshot and releases failed probes', async () => {
    const { core, ask } = setup()
    const row = { agentId: 'agent', active: true, engine: 'claude', tmuxPane: '%2', runtimes: [{ backend: 'tmux', paneId: '%2' }], launch: { state: 'ready' },
      processIdentity: { pid: 22, startMarker: 'start', executable: '/bin/claude' } } as RegisteredSession
    vi.mocked(core.agents.byAgent).mockReturnValue(row)
    let finish!: (value: Awaited<ReturnType<typeof tmuxPaneState>>) => void
    vi.mocked(tmuxPaneState).mockImplementationOnce(() => new Promise(resolve => { finish = resolve }))
    const first = ask('shell_visit_status', { agentId: 'agent' })
    const second = ask('shell_visit_status', { agentId: 'agent' })
    expect(first).toBe(second)
    row.processIdentity!.startMarker = 'replacement'
    vi.mocked(checkPidRuntime).mockResolvedValue({ state: 'gone', reason: 'fixture' })
    finish({ dead: false, engineExit: 1 } as Awaited<ReturnType<typeof tmuxPaneState>>)
    expect(await first).toEqual({ exited: false })
    expect(checkPidRuntime).toHaveBeenCalledWith(expect.objectContaining({ processIdentity: expect.objectContaining({ startMarker: 'start' }) }))
    vi.mocked(tmuxPaneState).mockRejectedValueOnce(new Error('probe failed'))
    await expect(ask('shell_visit_status', { agentId: 'agent' })).rejects.toThrow('probe failed')
    vi.mocked(tmuxPaneState).mockResolvedValueOnce('unknown')
    expect(await ask('shell_visit_status', { agentId: 'agent' })).toEqual({ exited: false })
  })
})