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.

22.3 KB
Raw Blame
import { describe, it, expect } from 'vitest'
import {
  normalizeClaude,
  normalizeCodex,
  normalizeCopilot,
  normalizeFor,
  type RawHookEnvelope
} from './normalize'

function env(payload: Record<string, unknown>): RawHookEnvelope {
  return { nodeId: 'n1', agentId: 'claude', payload }
}

function copilotEnv(payload: Record<string, unknown>): RawHookEnvelope {
  return { nodeId: 'n1', agentId: 'copilot', payload }
}

describe('normalizeCopilot', () => {
  it('maps session boundaries and captures the CLI session id', () => {
    expect(normalizeCopilot(copilotEnv({ hook_event_name: 'SessionStart', session_id: 's1' }))).toEqual({
      nodeId: 'n1',
      agentId: 'copilot',
      sessionId: 's1',
      kind: 'session',
      sessionPhase: 'start'
    })
    expect(normalizeCopilot(copilotEnv({ hook_event_name: 'SessionEnd', session_id: 's1' }))).toMatchObject({
      kind: 'session',
      sessionPhase: 'end'
    })
  })

  it('maps turn and tool lifecycle without treating a failed tool as a finished turn', () => {
    expect(
      normalizeCopilot(copilotEnv({ hook_event_name: 'UserPromptSubmit', prompt: 'fix it' }))
    ).toMatchObject({ state: 'working', newTurn: true, task: 'fix it' })
    for (const hook_event_name of ['PreToolUse', 'PostToolUse', 'PostToolUseFailure']) {
      expect(normalizeCopilot(copilotEnv({ hook_event_name })), hook_event_name).toMatchObject({
        state: 'working'
      })
    }
    expect(
      normalizeCopilot(
        copilotEnv({ hook_event_name: 'Stop', last_assistant_message: 'finished' })
      )
    ).toMatchObject({ state: 'done', lastMessage: 'finished' })
  })

  it('maps only the documented needs-user notifications', () => {
    expect(
      normalizeCopilot(
        copilotEnv({
          hook_event_name: 'Notification',
          notification_type: 'permission_prompt',
          message: 'Approve command?'
        })
      )
    ).toMatchObject({ state: 'blocked', lastMessage: 'Approve command?' })
    expect(
      normalizeCopilot(
        copilotEnv({
          hook_event_name: 'Notification',
          notification_type: 'elicitation_dialog',
          message: 'Which option?'
        })
      )
    ).toMatchObject({ state: 'waiting', lastMessage: 'Which option?' })
    for (const notification_type of ['agent_idle', 'agent_completed', 'unknown_future_type']) {
      expect(
        normalizeCopilot(copilotEnv({ hook_event_name: 'Notification', notification_type })),
        notification_type
      ).toBeNull()
    }
  })

  it('routes through the shared dispatcher', () => {
    expect(normalizeFor('copilot', copilotEnv({ hook_event_name: 'Stop' }))).toMatchObject({
      agentId: 'copilot',
      state: 'done'
    })
  })
})

describe('normalizeClaude — turn-end signals', () => {
  it('Stop → done, not interrupted', () => {
    const e = normalizeClaude(env({ hook_event_name: 'Stop', session_id: 's1' }))
    expect(e).toMatchObject({ kind: 'state', state: 'done', sessionId: 's1' })
    expect(e?.interrupted).toBeFalsy()
  })

  it('Stop with is_interrupt → done + interrupted (user pressed Esc)', () => {
    const e = normalizeClaude(env({ hook_event_name: 'Stop', is_interrupt: true }))
    expect(e).toMatchObject({ kind: 'state', state: 'done', interrupted: true })
  })

  // Claude Code skips the normal Stop hook when the turn dies on an API/model error and
  // fires StopFailure instead — without mapping it, the badge sticks on RUNNING forever.
  it('StopFailure → done (API-error turn end)', () => {
    const e = normalizeClaude(env({ hook_event_name: 'StopFailure' }))
    expect(e).toMatchObject({ kind: 'state', state: 'done' })
  })
})

describe('normalizeClaude — PermissionRequest (deterministic approvals)', () => {
  it('PermissionRequest → blocked, threading the merged nodeterm_pending_id', () => {
    const e = normalizeClaude(
      env({
        hook_event_name: 'PermissionRequest',
        session_id: 's1',
        last_assistant_message: 'Approve write',
        nodeterm_pending_id: 'n1-1720-42'
      })
    )
    expect(e).toMatchObject({ kind: 'state', state: 'blocked', pendingId: 'n1-1720-42' })
  })

  it('omits pendingId when the hook did not arm the wait branch (legacy prompt path)', () => {
    const e = normalizeClaude(env({ hook_event_name: 'PermissionRequest', session_id: 's1' }))
    expect(e).toMatchObject({ kind: 'state', state: 'blocked' })
    expect(e && 'pendingId' in e).toBe(false)
  })
})

describe('normalizeClaude — held tool (structured answers)', () => {
  it('names the held tool beside the ticket, for plans, questions and ordinary tools alike', () => {
    for (const tool of ['ExitPlanMode', 'AskUserQuestion', 'Bash', 'mcp__srv__do']) {
      const e = normalizeClaude(
        env({ hook_event_name: 'PermissionRequest', tool_name: tool, nodeterm_pending_id: 'n1-1-1' })
      )
      expect(e).toMatchObject({ state: 'blocked', held: { pendingId: 'n1-1-1', toolName: tool } })
    }
  })
  it('no held request without a ticket, and an unsafe tool name is dropped rather than carried', () => {
    const none = normalizeClaude(env({ hook_event_name: 'PermissionRequest', tool_name: 'ExitPlanMode' }))
    expect(none && 'held' in none).toBe(false)
    const bad = normalizeClaude(
      env({ hook_event_name: 'PermissionRequest', tool_name: 'a b<script>', nodeterm_pending_id: 'n1-1-1' })
    )
    expect(bad && 'held' in bad).toBe(false)
    expect(bad).toMatchObject({ pendingId: 'n1-1-1' }) // the approval ticket itself is untouched
  })
  it('a held question also carries its exact question texts, so a surface can match its card', () => {
    const e = normalizeClaude(
      env({
        hook_event_name: 'PermissionRequest',
        tool_name: 'AskUserQuestion',
        nodeterm_pending_id: 'n1-1-1',
        tool_input: { questions: [{ question: 'Pick one?', options: [{ label: 'A' }] }, { question: 'And?' }] }
      })
    )
    expect(e).toMatchObject({ held: { pendingId: 'n1-1-1', toolName: 'AskUserQuestion', questions: ['Pick one?', 'And?'] } })
  })
  it('an unreadable question input keeps the held ticket but carries no texts (no controls)', () => {
    const e = normalizeClaude(
      env({
        hook_event_name: 'PermissionRequest',
        tool_name: 'AskUserQuestion',
        nodeterm_pending_id: 'n1-1-1',
        tool_input: { questions: 'nope' }
      })
    )
    expect(e && e.held).toEqual({ pendingId: 'n1-1-1', toolName: 'AskUserQuestion' })
    // A plan never carries question texts.
    const plan = normalizeClaude(
      env({ hook_event_name: 'PermissionRequest', tool_name: 'ExitPlanMode', nodeterm_pending_id: 'n1-1-1', tool_input: { plan: 'p' } })
    )
    expect(plan && plan.held).toEqual({ pendingId: 'n1-1-1', toolName: 'ExitPlanMode' })
  })
  it('the answered signal carries no held request (the hold is over)', () => {
    const e = normalizeClaude(
      env({ hook_event_name: 'PermissionRequest', tool_name: 'ExitPlanMode', nodeterm_pending_id: 'n1-1-1', nodeterm_answered: 'allow' })
    )
    expect(e && 'held' in e).toBe(false)
  })
})

describe('normalizeClaude — deterministic-approval "answered" signal', () => {
  // The signal rides ALONGSIDE the original PermissionRequest payload, so it must be matched BEFORE
  // hook_event_name (which would otherwise map to blocked) and yield a synthetic working transition.
  it('nodeterm_answered=allow → working, threading pendingId, over the PermissionRequest payload', () => {
    const e = normalizeClaude(
      env({
        hook_event_name: 'PermissionRequest',
        session_id: 's1',
        nodeterm_pending_id: 'n1-1720-42',
        nodeterm_answered: 'allow'
      })
    )
    expect(e).toMatchObject({ kind: 'state', state: 'working', pendingId: 'n1-1720-42', sessionId: 's1' })
    // A working state carries no blocked/waiting signal — it never produces a new inbox ask.
    expect(e?.state).not.toBe('blocked')
  })

  it('nodeterm_answered=deny also → working (the agent typically continues the turn)', () => {
    const e = normalizeClaude(
      env({ hook_event_name: 'PermissionRequest', nodeterm_pending_id: 'n1-9-9', nodeterm_answered: 'deny' })
    )
    expect(e).toMatchObject({ kind: 'state', state: 'working', pendingId: 'n1-9-9' })
  })

  it('an unrecognized nodeterm_answered value is ignored (falls through to the PermissionRequest map)', () => {
    const e = normalizeClaude(env({ hook_event_name: 'PermissionRequest', nodeterm_answered: 'maybe' }))
    expect(e).toMatchObject({ kind: 'state', state: 'blocked' })
  })
})

describe('normalizeClaude — async subagents', () => {
  it('PostToolUse for a sync subagent → subagent-end with stats', () => {
    const e = normalizeClaude(
      env({
        hook_event_name: 'PostToolUse',
        tool_name: 'Task',
        tool_use_id: 'tu1',
        tool_response: { content: [{ type: 'text', text: 'the answer' }], totalDurationMs: 1200 }
      })
    )
    expect(e).toMatchObject({ kind: 'subagent-end', toolUseId: 'tu1', durationMs: 1200, result: 'the answer' })
  })

  // Claude Code launches subagents async by default: PostToolUse fires ~immediately with a
  // launch acknowledgment ({isAsync, status:'async_launched'}), NOT the finished result. That
  // must not end the card — the real end arrives later via the parent's <task-notification>.
  it('PostToolUse for an async launch → NOT subagent-end (card stays working)', () => {
    const e = normalizeClaude(
      env({
        hook_event_name: 'PostToolUse',
        tool_name: 'Task',
        tool_use_id: 'tu1',
        tool_response: { isAsync: true, status: 'async_launched', agentId: 'a1' }
      })
    )
    expect(e?.kind).not.toBe('subagent-end')
    expect(e).toMatchObject({ kind: 'state', state: 'working' })
  })

  it('UserPromptSubmit → working with newTurn', () => {
    const e = normalizeClaude(env({ hook_event_name: 'UserPromptSubmit', prompt: 'do things' }))
    expect(e).toMatchObject({ kind: 'state', state: 'working', newTurn: true, task: 'do things' })
  })

  // A completed async subagent is delivered back as a queued <task-notification> prompt.
  // That is not a genuine user turn: flagging it newTurn would clear the whole subagent
  // fan-out at the exact moment one of the cards completes.
  it('UserPromptSubmit of a <task-notification> → working but NOT a new turn', () => {
    const e = normalizeClaude(
      env({
        hook_event_name: 'UserPromptSubmit',
        prompt: '<task-notification>\n<task-id>a1</task-id>\n<tool-use-id>tu1</tool-use-id>\n</task-notification>'
      })
    )
    expect(e).toMatchObject({ kind: 'state', state: 'working' })
    expect(e?.newTurn).toBeFalsy()
  })
})

describe('normalizeClaude — recurring (cron/schedule/loop)', () => {
  it('CronCreate PreToolUse → recurring cron with schedule + task', () => {
    const e = normalizeClaude(
      env({
        hook_event_name: 'PreToolUse',
        tool_name: 'CronCreate',
        tool_input: { cron: '0 9 * * *', prompt: 'daily report' }
      })
    )
    expect(e).toMatchObject({
      kind: 'recurring',
      recurringKind: 'cron',
      schedule: '0 9 * * *',
      task: 'daily report'
    })
    expect(e?.recurringEnd).toBeFalsy()
  })

  // A cron outlives turns and sessions — its card should only leave the canvas when the
  // cron itself is removed. CronDelete is that signal.
  it('CronDelete PreToolUse → recurring END (clears the cron card)', () => {
    const e = normalizeClaude(env({ hook_event_name: 'PreToolUse', tool_name: 'CronDelete' }))
    expect(e).toMatchObject({ kind: 'recurring', recurringEnd: true })
  })
})

describe('normalizeClaude — background shell tasks', () => {
  // A background shell task lives INSIDE the CLI process, so `/exit` (Eco hibernation, the bulk
  // restart) kills it silently. This event is the stamp those two exclude on.
  it('claude PreToolUse Bash with run_in_background=true is a background-task event', () => {
    const e = normalizeClaude(
      env({
        hook_event_name: 'PreToolUse',
        tool_name: 'Bash',
        tool_input: { command: 'sleep 999', run_in_background: true }
      })
    )
    expect(e?.kind).toBe('background-task')
  })

  // The mutation guard: dropping the `tool_name` check, the `ev` check, or matching truthily
  // instead of `=== true` each flips a row here — the truthy match flips two. Those two
  // truthy-but-not-`true` rows are what pin the strict compare: the boolean rows below are both
  // falsy, so on their own they would pass a `!!p.tool_input?.run_in_background` implementation.
  it('foreground Bash, false/absent/truthy-non-true flags, PostToolUse and other tools stay generic working', () => {
    for (const payload of [
      { hook_event_name: 'PreToolUse', tool_name: 'Bash', tool_input: { command: 'ls' } },
      {
        hook_event_name: 'PreToolUse',
        tool_name: 'Bash',
        tool_input: { command: 'ls', run_in_background: false }
      },
      {
        hook_event_name: 'PreToolUse',
        tool_name: 'Bash',
        // A hand-rolled/forwarded payload could carry 1 or "true"; only a real boolean counts.
        tool_input: { command: 'ls', run_in_background: 1 }
      },
      {
        hook_event_name: 'PreToolUse',
        tool_name: 'Bash',
        tool_input: { command: 'ls', run_in_background: 'true' }
      },
      {
        hook_event_name: 'PostToolUse',
        tool_name: 'Bash',
        tool_input: { command: 'ls', run_in_background: true }
      },
      { hook_event_name: 'PreToolUse', tool_name: 'Read', tool_input: { run_in_background: true } }
    ]) {
      const e = normalizeClaude(env(payload))
      expect(e?.kind, JSON.stringify(payload)).toBe('state')
      expect(e?.state, JSON.stringify(payload)).toBe('working')
    }
  })
})

describe('normalizeClaude — permission signals', () => {
  it('PermissionRequest → blocked', () => {
    const e = normalizeClaude(env({ hook_event_name: 'PermissionRequest' }))
    expect(e).toMatchObject({ kind: 'state', state: 'blocked' })
  })

  it('Notification permission_prompt still maps to blocked', () => {
    const e = normalizeClaude(
      env({ hook_event_name: 'Notification', notification_type: 'permission_prompt' })
    )
    expect(e).toMatchObject({ kind: 'state', state: 'blocked' })
  })

  // Claude Code fires an idle_prompt Notification whenever it is sitting at its prompt: after a
  // normally-finished turn (already done → the consumers' working-only rule makes it a no-op) AND
  // after an Esc that aborted a tool call without ever running Stop — the one case that left a node
  // stuck on `working`. It is a RESCUE, hence `idle` + `interrupted`, never a celebration.
  // Mapping it to `waiting` (the obvious reading) is what used to stick NEEDS YOU on finished nodes.
  it('Notification idle_prompt → an idle, interrupted done (the stuck-working rescue)', () => {
    const e = normalizeClaude(
      env({
        hook_event_name: 'Notification',
        notification_type: 'idle_prompt',
        message: 'Claude is waiting for your input'
      })
    )
    expect(e).toMatchObject({ kind: 'state', state: 'done', idle: true, interrupted: true })
  })

  it('Notification elicitation_dialog / agent_needs_input → waiting', () => {
    for (const t of ['elicitation_dialog', 'agent_needs_input']) {
      const e = normalizeClaude(env({ hook_event_name: 'Notification', notification_type: t }))
      expect(e).toMatchObject({ kind: 'state', state: 'waiting' })
    }
  })

  it('informational / unknown Notification types do not change state', () => {
    for (const t of ['auth_success', 'elicitation_complete', 'elicitation_response', 'agent_completed', 'something_new', undefined]) {
      const e = normalizeClaude(env({ hook_event_name: 'Notification', notification_type: t }))
      expect(e).toBeNull()
    }
  })
})

describe('normalizeOpencode', () => {
  const ocEnv = (payload: Record<string, unknown>): RawHookEnvelope => ({
    nodeId: 'n1',
    agentId: 'opencode',
    payload
  })

  it('maps session.created to a session start with the id', () => {
    expect(normalizeFor('opencode', ocEnv({ event: 'session.created', sessionID: 'ses_1' }))).toEqual({
      nodeId: 'n1',
      agentId: 'opencode',
      sessionId: 'ses_1',
      kind: 'session',
      sessionPhase: 'start'
    })
  })

  it('maps a user message.updated to working + newTurn', () => {
    expect(
      normalizeFor('opencode', ocEnv({ event: 'message.updated', role: 'user', sessionID: 'ses_1' }))
    ).toMatchObject({ kind: 'state', state: 'working', newTurn: true })
  })

  it('maps tool.execute.before to working (no newTurn)', () => {
    const e = normalizeFor('opencode', ocEnv({ event: 'tool.execute.before' }))
    expect(e).toMatchObject({ kind: 'state', state: 'working' })
    expect(e?.newTurn).toBeUndefined()
  })

  it('maps permission.asked to blocked and permission.replied back to working', () => {
    expect(normalizeFor('opencode', ocEnv({ event: 'permission.asked' }))).toMatchObject({ state: 'blocked' })
    expect(normalizeFor('opencode', ocEnv({ event: 'permission.replied' }))).toMatchObject({ state: 'working' })
    // Question (elicitation) dialog, measured on 1.18.3 — blocks the turn without idling.
    expect(normalizeFor('opencode', ocEnv({ event: 'question.asked' }))).toMatchObject({ state: 'blocked' })
    expect(normalizeFor('opencode', ocEnv({ event: 'question.replied' }))).toMatchObject({ state: 'working' })
    expect(normalizeFor('opencode', ocEnv({ event: 'question.rejected' }))).toMatchObject({ state: 'working' })
  })

  it('maps session.idle and session.error to done', () => {
    expect(normalizeFor('opencode', ocEnv({ event: 'session.idle' }))).toMatchObject({ state: 'done' })
    expect(normalizeFor('opencode', ocEnv({ event: 'session.error' }))).toMatchObject({ state: 'done' })
  })

  it('ignores unknown events', () => {
    expect(normalizeFor('opencode', ocEnv({ event: 'tui.toast.show' }))).toBeNull()
  })
})

describe('normalizeCodex — request_user_input (ask-the-user)', () => {
  function cenv(payload: Record<string, unknown>): RawHookEnvelope {
    return { nodeId: 'n1', agentId: 'codex', payload }
  }

  it('PreToolUse(request_user_input) → waiting + awaitingInput, carrying the question', () => {
    const e = normalizeCodex(
      cenv({
        hook_event_name: 'PreToolUse',
        session_id: 's1',
        tool_name: 'request_user_input',
        tool_input: { questions: [{ question: 'Choose A or B?' }] }
      })
    )
    expect(e).toMatchObject({
      kind: 'state',
      state: 'waiting',
      awaitingInput: true,
      lastMessage: 'Choose A or B?',
      sessionId: 's1'
    })
  })

  // The ask ends the turn; a PostToolUse for the ask itself is an immediate ack, not the
  // user's answer (that arrives as a fresh UserPromptSubmit) — it must not clear the ask.
  it('PostToolUse(request_user_input) → null (must not clear the ask)', () => {
    const e = normalizeCodex(cenv({ hook_event_name: 'PostToolUse', tool_name: 'request_user_input' }))
    expect(e).toBeNull()
  })

  it('other tool events still map to working, without the flag', () => {
    const e = normalizeCodex(cenv({ hook_event_name: 'PreToolUse', tool_name: 'shell' }))
    expect(e).toMatchObject({ kind: 'state', state: 'working' })
    expect(e?.awaitingInput).toBeFalsy()
  })
})

// Payload shapes below are the LIVE capture from codex-cli 0.146.0 (spawn_agent measurement run,
// 2026-08-24): parent session_id + the child's agent_id/agent_type; SubagentStart's
// transcript_path is the CHILD's rollout; a child's own tool events carry agent_id too.
describe('normalizeCodex — subagents (spawn_agent)', () => {
  function cenv(payload: Record<string, unknown>): RawHookEnvelope {
    return { nodeId: 'n1', agentId: 'codex', payload }
  }

  it('SubagentStart → subagent-start keyed by agent_id, typed by agent_type', () => {
    const e = normalizeCodex(
      cenv({
        hook_event_name: 'SubagentStart',
        session_id: '01a0343d-d249-73e2-a462-e824df60d95c',
        turn_id: '01a0343d-ef3a-7840-b6ed-683b7b024519',
        transcript_path: '/home/u/.codex/sessions/2026/08/24/rollout-child.jsonl',
        agent_id: '01a0343d-ef01-7700-b32f-c32ee1fc21f9',
        agent_type: 'default'
      })
    )
    expect(e).toMatchObject({
      kind: 'subagent-start',
      toolUseId: '01a0343d-ef01-7700-b32f-c32ee1fc21f9',
      subagentType: 'default',
      sessionId: '01a0343d-d249-73e2-a462-e824df60d95c'
    })
    // The spawn message is encrypted end-to-end — there is no task text to label the card with.
    expect(e?.taskLabel).toBeUndefined()
  })

  it('SubagentStop → subagent-end carrying the child final answer as result', () => {
    const e = normalizeCodex(
      cenv({
        hook_event_name: 'SubagentStop',
        session_id: '01a0343d-d249-73e2-a462-e824df60d95c',
        agent_id: '01a0343d-ef01-7700-b32f-c32ee1fc21f9',
        agent_type: 'default',
        agent_transcript_path: '/home/u/.codex/sessions/2026/08/24/rollout-child.jsonl',
        last_assistant_message: 'The command output was:\n\n`hello-from-subagent`'
      })
    )
    expect(e).toMatchObject({
      kind: 'subagent-end',
      toolUseId: '01a0343d-ef01-7700-b32f-c32ee1fc21f9',
      result: 'The command output was:\n\n`hello-from-subagent`'
    })
  })

  // After an async spawn the parent's turn can end while the child still runs; a child Bash
  // event mapping to 'working' would flip the finished parent back to RUNNING with nothing to
  // clear it. Child activity reaches the card via the rollout tail, not the state machine.
  it("a child's own tool events (agent_id-tagged) do not drive the parent state", () => {
    for (const ev of ['PreToolUse', 'PostToolUse']) {
      const e = normalizeCodex(
        cenv({
          hook_event_name: ev,
          session_id: '01a0343d-d249-73e2-a462-e824df60d95c',
          agent_id: '01a0343d-ef01-7700-b32f-c32ee1fc21f9',
          agent_type: 'default',
          tool_name: 'Bash',
          tool_input: { command: 'echo hello-from-subagent' }
        })
      )
      expect(e).toBeNull()
    }
  })

  // The PARENT's spawn/wait tool calls carry no agent_id and stay ordinary working events —
  // the card is keyed off SubagentStart, never off the spawn tool call.
  it('the parent spawn_agent tool call remains a plain working event', () => {
    const e = normalizeCodex(
      cenv({
        hook_event_name: 'PreToolUse',
        session_id: 's1',
        tool_name: 'collaborationspawn_agent',
        tool_input: { task_name: 'echo_check', fork_turns: 'all', message: 'gAAAA…' }
      })
    )
    expect(e).toMatchObject({ kind: 'state', state: 'working' })
  })
})