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.

17.4 KB
Raw Blame
import { describe, expect, it } from 'vitest'
import { grokRawFields, normalizeClaude, normalizeGrok, type RawHookEnvelope } from './normalize'

/**
 * Grok's hook envelope is its own dialect: camelCase keys whose `hookEventName` VALUE is
 * snake_case ("pre_tool_use"), and the grok SDK path converts the top-level keys to snake_case.
 * Both spellings are therefore read, and the event name is canonicalized rather than matched
 * literally — read out of the shipped 1.0.0 docs, not inferred from claude's shape. Payloads WERE
 * captured on 1.0.13 (`__fixtures__/grok/hook-payloads.json`); the cases
 * below that are built from a capture say so. The behavioural pin over the live
 * subagent payloads is `normalize.grok.capture.test.ts`, not the hand-built cases here.
 */
function env(payload: Record<string, unknown>): RawHookEnvelope {
  return { nodeId: 'n1', agentId: 'grok', payload }
}

describe('normalizeGrok — lifecycle', () => {
  it('maps session_start / session_end to the session phases', () => {
    expect(normalizeGrok(env({ hookEventName: 'session_start', sessionId: 's1' }))).toEqual({
      nodeId: 'n1',
      agentId: 'grok',
      sessionId: 's1',
      kind: 'session',
      sessionPhase: 'start'
    })
    expect(normalizeGrok(env({ hookEventName: 'session_end', sessionId: 's1' }))?.sessionPhase).toBe('end')
  })

  it('treats user_prompt_submit as the turn start (newTurn)', () => {
    const e = normalizeGrok(env({ hookEventName: 'user_prompt_submit', sessionId: 's1', prompt: 'ship it' }))
    expect(e).toMatchObject({ kind: 'state', state: 'working', newTurn: true, task: 'ship it' })
  })

  it('keeps the node working across every tool event, including a tool FAILURE', () => {
    for (const ev of ['pre_tool_use', 'post_tool_use', 'post_tool_use_failure']) {
      expect(normalizeGrok(env({ hookEventName: ev, sessionId: 's1' }))).toMatchObject({
        kind: 'state',
        state: 'working'
      })
    }
  })
})

describe('normalizeGrok — Stop', () => {
  it('a genuine turn end is done, carrying the last assistant message', () => {
    const e = normalizeGrok(
      env({ hookEventName: 'stop', sessionId: 's1', reason: 'end_turn', lastAssistantMessage: 'done' })
    )
    expect(e).toMatchObject({ state: 'done', lastMessage: 'done' })
    // Not interrupted — a genuine turn end DOES earn the completion alert. Asserted separately
    // (as normalize.test.ts does for claude's Stop) because toMatchObject demands the key exist.
    expect(e?.interrupted).toBeFalsy()
  })

  it('an ABSENT reason is still a real turn end (never swallow the badge event)', () => {
    expect(normalizeGrok(env({ hookEventName: 'stop', sessionId: 's1' }))).toMatchObject({ state: 'done' })
  })

  /**
   * The two observe-only reasons are a DENYLIST, not 'end_turn' an allowlist: only grok's session
   * close is observe-only, so any turn-end reason grok labels later must still report its badge and
   * its completion alert. An allowlist would silently mark all of these `interrupted`.
   */
  it('an UNKNOWN reason is a real turn end too, alert and message intact', () => {
    for (const reason of ['max_tokens', 'refusal', 'something_new']) {
      const e = normalizeGrok(env({ hookEventName: 'stop', sessionId: 's1', reason, lastAssistantMessage: 'text' }))
      expect(e, reason).toMatchObject({ state: 'done', lastMessage: 'text' })
      expect(e?.interrupted, reason).toBeFalsy()
    }
  })

  it('the observe-only session-close Stop is marked interrupted, so no completion alert fires', () => {
    for (const reason of ['channel_closed', 'shutdown']) {
      const e = normalizeGrok(env({ hookEventName: 'stop', sessionId: 's1', reason, lastAssistantMessage: 'x' }))
      expect(e).toMatchObject({ state: 'done', interrupted: true })
      expect(e?.lastMessage).toBeUndefined()
    }
  })

  it.each([
    'rate_limit',
    'authentication_failed',
    'invalid_request',
    'server_error',
    'max_output_tokens',
    'unknown'
  ])('stop_failure %s ends the turn so the badge cannot stick on working', (error) => {
    expect(
      normalizeGrok(
        env({ hookEventName: 'stop_failure', sessionId: 's1', error, lastAssistantMessage: error })
      )
    ).toMatchObject({ state: 'done', lastMessage: error })
  })

  it.each([
    ['a future dialect', 'future_error'],
    ['an absent class', undefined],
    ['an empty class', '']
  ])('stop_failure with %s STILL ends the turn — the node must not stay RUNNING', (_name, error) => {
    // This used to return null, on the closed-vocabulary discipline the rest of this file follows.
    // That discipline is for values that DECIDE something; this one decides nothing — every class
    // ends the turn. Gating on it left the node on RUNNING until the idle_prompt backstop, or
    // forever if none arrived: the silent half of the failure, the one nobody reports because
    // nothing looks broken.
    //
    // Asserted as `done` and NOT as "not null", because "not null" would also pass if some future
    // edit returned `working` here — which is the very state this exists to prevent.
    const out = normalizeGrok(env({ hookEventName: 'stop_failure', sessionId: 's1', error }))
    expect(out).toMatchObject({ kind: 'state', state: 'done' })
    expect(out?.state).not.toBe('working')
  })
})

describe('normalizeGrok — published 1.0.13 events', () => {
  it('keeps working after PermissionDenied because the turn continues after the tool decision', () => {
    expect(
      normalizeGrok(env({ hookEventName: 'permission_denied', sessionId: 's1', toolName: 'write_file' }))
    ).toMatchObject({ kind: 'state', state: 'working' })
  })

  it.each([
    'user_interrupt',
    'permission_rejected',
    'permission_cancelled',
    'max_turns',
    'no_progress',
    'unknown'
  ] as const)('carries closed StopCancelled reason %s without deciding the badge transition yet', (reason) => {
    expect(
      normalizeGrok(
        env({
          hookEventName: 'stop_cancelled',
          sessionId: 's1',
          reason,
          subagentType: 'explore',
          lastAssistantMessage: 'not allowed'
        })
      )
    ).toEqual({
      nodeId: 'n1',
      agentId: 'grok',
      sessionId: 's1',
      kind: 'state',
      cancelReason: reason,
      subagentType: 'explore',
      lastMessage: 'not allowed'
    })
  })

  it('rejects an unrecognized StopCancelled reason', () => {
    expect(normalizeGrok(env({ hookEventName: 'stop_cancelled', reason: 'future_reason' }))).toBeNull()
  })

  // REPLACED after measuring. This case used to build payloads with NO `subagentId` and assert that
  // the result carried `sessionId` — "without inventing an instance id". Both halves are wrong
  // against the wire: all four captured subagent payloads (1.0.13) carry `subagentId`, so the
  // id-less shape does not occur; and passing `sessionId` through is the trap, because on the STOP
  // that id is the CHILD's own. The measured behaviour is pinned in the `normalizeGrok — subagents`
  // block at the end of this file. What survives here is the id-less input, which must map to
  // NOTHING rather than to a card no store can key.
  it('returns null for a subagent event with no instance id, rather than an unkeyable card', () => {
    expect(
      normalizeGrok(env({ hookEventName: 'subagent_start', sessionId: 's1', subagentType: 'explore' }))
    ).toBeNull()
    expect(
      normalizeGrok(env({ hook_event_name: 'subagent_stop', session_id: 's1', subagent_type: 'explore' }))
    ).toBeNull()
  })

  it('carries the closed compaction phase while leaving the current badge untouched', () => {
    expect(
      normalizeGrok(env({ hookEventName: 'pre_compact', sessionId: 'old', trigger: 'manual' }))
    ).toEqual({
      nodeId: 'n1',
      agentId: 'grok',
      sessionId: 'old',
      kind: 'state',
      compactionPhase: 'pre'
    })
    expect(
      normalizeGrok(env({ hook_event_name: 'post_compact', session_id: 'new', trigger: 'auto' }))
    ).toEqual({
      nodeId: 'n1',
      agentId: 'grok',
      sessionId: 'new',
      kind: 'state',
      compactionPhase: 'post'
    })
    expect(normalizeGrok(env({ hookEventName: 'post_compact', trigger: 'future' }))).toBeNull()
  })
})

/** Grok 1.0.13 publishes the closed Notification vocabulary in
 * `~/.grok/docs/user-guide/10-hooks.md:99`; `:162` says permission_prompt fires only while its UI
 * actually waits. The literal unknown cases keep that contract closed. */
describe('normalizeGrok — Notification', () => {
  it.each([
    {
      name: 'permission_prompt',
      payload: {
        hookEventName: 'notification',
        notificationType: 'permission_prompt',
        message: 'Tool permission requested',
        level: 'info'
      },
      want: {
        nodeId: 'n1',
        agentId: 'grok',
        sessionId: undefined,
        kind: 'state',
        state: 'blocked',
        lastMessage: undefined
      }
    },
    {
      name: 'idle_prompt',
      payload: { hookEventName: 'notification', notificationType: 'idle_prompt' },
      want: {
        nodeId: 'n1',
        agentId: 'grok',
        sessionId: undefined,
        kind: 'state',
        state: 'done',
        interrupted: true,
        idle: true
      }
    },
    {
      name: 'task_complete',
      payload: { hookEventName: 'notification', notificationType: 'task_complete' },
      want: null
    },
    {
      name: 'unknown',
      payload: { hookEventName: 'notification', notificationType: 'some_future_type' },
      want: null
    },
    {
      name: 'unknown containing permission',
      payload: { hookEventName: 'notification', notificationType: 'permission_reminder' },
      want: null
    },
    {
      name: 'unknown camelCase near-alias',
      payload: { hookEventName: 'notification', notificationType: 'permissionPrompt' },
      want: null
    },
    {
      name: 'unknown hyphenated near-alias',
      payload: { hookEventName: 'notification', notificationType: 'permission-prompt' },
      want: null
    }
  ])('maps published and unknown type: $name', ({ payload, want }) => {
    expect(normalizeGrok(env(payload))).toEqual(want)
  })

  it.each([
    'approval_required',
    'agent_needs_input',
    'elicitation_dialog',
    'session_ready',
    'permission_request'
  ])('retires the old inferred Notification type %s', (notificationType) => {
    expect(normalizeGrok(env({ hookEventName: 'notification', notificationType }))).toBeNull()
  })

  it('does not infer idle state from prose attached to an unknown type', () => {
    expect(
      normalizeGrok(
        env({
          hookEventName: 'notification',
          notificationType: 'session_ready',
          message: 'Type your message or @path/to/file'
        })
      )
    ).toBeNull()
  })

  it('reads the published types through the SDK key dialect', () => {
    expect(
      normalizeGrok(env({ hook_event_name: 'notification', notification_type: 'permission_prompt' }))
    ).toEqual({
      nodeId: 'n1',
      agentId: 'grok',
      sessionId: undefined,
      kind: 'state',
      state: 'blocked',
      lastMessage: undefined
    })
    expect(
      normalizeGrok(env({ hook_event_name: 'notification', notification_type: 'idle_prompt' }))
    ).toEqual({
      nodeId: 'n1',
      agentId: 'grok',
      sessionId: undefined,
      kind: 'state',
      state: 'done',
      interrupted: true,
      idle: true
    })
  })

  it('reads a published type through the legacy bare type key', () => {
    expect(normalizeGrok(env({ hookEventName: 'notification', type: 'permission_prompt' }))).toEqual({
      nodeId: 'n1',
      agentId: 'grok',
      sessionId: undefined,
      kind: 'state',
      state: 'blocked',
      lastMessage: undefined
    })
  })
})

describe('normalizeGrok — dialects', () => {
  it('reads the SDK snake_case key spelling too', () => {
    expect(
      normalizeGrok(env({ hook_event_name: 'stop', session_id: 's9', last_assistant_message: 'ok' }))
    ).toMatchObject({ sessionId: 's9', state: 'done', lastMessage: 'ok' })
  })

  it('accepts a PascalCase event name (canonicalized, not matched literally)', () => {
    expect(normalizeGrok(env({ hookEventName: 'PreToolUse' }))).toMatchObject({ state: 'working' })
  })

})

/**
 * Grok also merges `~/.claude/settings.json`, where nodeterm's CLAUDE managed hook already lives —
 * so every grok event ALSO fires claude.sh and POSTs to /hook/claude. That leg must stay inert:
 * this is the test that keeps it a property instead of a coincidence.
 */
describe('the claude-compat cross-fire is inert', () => {
  const GROK_EVENTS = ['session_start', 'user_prompt_submit', 'pre_tool_use', 'post_tool_use', 'stop', 'session_end']

  it('normalizeClaude returns null for every grok payload (camelCase dialect)', () => {
    for (const ev of GROK_EVENTS) {
      expect(
        normalizeClaude({ nodeId: 'n1', agentId: 'claude', payload: { hookEventName: ev, sessionId: 's1' } }),
        ev
      ).toBeNull()
    }
  })

  /**
   * This is the leg that actually carries the property: in the SDK dialect grok writes the key
   * claude DOES read (`hook_event_name`), so inertness rests entirely on claude's compare being
   * case-sensitive and literal — 'stop' is not 'Stop'. Anyone who "helpfully" lowercases claude's
   * event name breaks this and nothing else.
   */
  it('normalizeClaude returns null for every grok payload (SDK snake_case dialect)', () => {
    for (const ev of GROK_EVENTS) {
      expect(
        normalizeClaude({ nodeId: 'n1', agentId: 'claude', payload: { hook_event_name: ev, session_id: 's1' } }),
        ev
      ).toBeNull()
    }
  })
})

describe('grokRawFields', () => {
  it('hands the shells ONE canonical field set from either dialect', () => {
    expect(
      grokRawFields({
        hookEventName: 'pre_tool_use',
        sessionId: 's1',
        cwd: '/w',
        toolName: 'spawn_subagent',
        toolUseId: 't1',
        toolInput: { subagent_type: 'explore' }
      })
    ).toEqual({
      event: 'pretooluse',
      sessionId: 's1',
      cwd: '/w',
      toolName: 'spawn_subagent',
      toolUseId: 't1',
      toolInput: { subagent_type: 'explore' }
    })
    // Every field the function reads, in the SDK dialect — dual-dialect reading is its whole reason
    // to exist, so dropping any one `?? p.snake_case` fallback has to fail here.
    expect(
      grokRawFields({
        hook_event_name: 'post_tool_use',
        session_id: 's2',
        cwd: '/w2',
        tool_name: 'read_file',
        tool_use_id: 't2',
        tool_input: { path: '/w2/a.ts' }
      })
    ).toEqual({
      event: 'posttooluse',
      sessionId: 's2',
      cwd: '/w2',
      toolName: 'read_file',
      toolUseId: 't2',
      toolInput: { path: '/w2/a.ts' }
    })
  })
})

/**
 * Subagent cards. Every payload below is copied from the 1.0.13 capture
 * (`__fixtures__/grok/hook-payloads.json`, two parallel `explore` children), field names and all.
 * The live-payload pin is `normalize.grok.capture.test.ts`; these cases keep the mapping
 * reachable when someone edits `normalizeGrok` without opening the fixture.
 *
 * These assert the mapped EVENT, not list membership: a test that only checks `canSubagent('grok')`
 * passes while `normalizeGrok` returns null and no card can ever render, which is exactly how the
 * feature reached review claiming to work.
 */
describe('normalizeGrok — subagents', () => {
  const START = {
    hookEventName: 'subagent_start',
    sessionId: 'parent-1',
    subagentId: 'child-a',
    subagentType: 'explore',
    description: 'Read a.txt contents'
  }
  const STOP = {
    hookEventName: 'subagent_stop',
    // The captured stop carries the CHILD's own id here, not the parent's.
    sessionId: 'child-a',
    subagentId: 'child-a',
    subagentType: 'explore',
    lastAssistantMessage: 'alfa'
  }

  it('maps subagent_start to a card keyed on subagentId, carrying type and task', () => {
    expect(normalizeGrok(env(START))).toEqual({
      nodeId: 'n1',
      agentId: 'grok',
      kind: 'subagent-start',
      toolUseId: 'child-a',
      subagentType: 'explore',
      task: 'Read a.txt contents'
    })
  })

  it('maps subagent_stop to the end, carrying the last assistant message as the result', () => {
    expect(normalizeGrok(env(STOP))).toEqual({
      nodeId: 'n1',
      agentId: 'grok',
      kind: 'subagent-end',
      toolUseId: 'child-a',
      subagentType: 'explore',
      result: 'alfa'
    })
  })

  it('gives two children of the SAME type different cards — one per instance, not per type', () => {
    const a = normalizeGrok(env(START))
    const b = normalizeGrok(env({ ...START, subagentId: 'child-b' }))
    expect(a?.subagentType).toBe(b?.subagentType)
    expect(a?.toolUseId).not.toBe(b?.toolUseId)
  })

  it('never re-points the node session: neither event carries a sessionId', () => {
    // The stop's own sessionId is the CHILD's; passing it through as `sessionId` would move the
    // node's session onto the child and take the context meter with it.
    expect(normalizeGrok(env(START))).not.toHaveProperty('sessionId')
    expect(normalizeGrok(env(STOP))).not.toHaveProperty('sessionId')
  })

  it('reads the snake_case dialect the SDK path presents', () => {
    expect(
      normalizeGrok(
        env({
          hook_event_name: 'subagent_start',
          subagent_id: 'child-a',
          subagent_type: 'explore'
        })
      )
    ).toMatchObject({ kind: 'subagent-start', toolUseId: 'child-a', subagentType: 'explore' })
  })

  it('returns null for a subagent event with no id, rather than an unkeyable card', () => {
    expect(normalizeGrok(env({ hookEventName: 'subagent_start', subagentType: 'explore' }))).toBeNull()
  })
})