Skip to content

armgit / orca

Public Imported from GitHub
0

Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

13.7 KB
Raw Blame
import { describe, expect, it } from 'vitest'
import {
  agentChildRowContextForParent,
  buildAgentChildRowModels,
  buildLegacyAgentChildRowModels,
  buildLegacyTaskRowModels,
  flattenAgentChildRowModels,
  type AgentChildRowContext,
  type AgentChildRowModel
} from './agent-child-row-model'
import type { AgentChildWorkView } from './agent-status-child-work-view'

const FRESH: AgentChildRowContext = {
  parentEvidenceFresh: true,
  transportObservation: 'live',
  parentObservedAt: 900,
  hostClockOffsetMs: 0
}
const STALE: AgentChildRowContext = { ...FRESH, parentEvidenceFresh: false }
const LOST: AgentChildRowContext = { ...FRESH, transportObservation: 'unverifiable' }

function view(id: string, overrides: Partial<AgentChildWorkView> = {}): AgentChildWorkView {
  return {
    id,
    providerId: `task-${id}`,
    kind: 'agent',
    description: `child ${id}`,
    agentType: 'general-purpose',
    state: 'working',
    membership: 'live',
    firstObservedAt: 100,
    observedAt: 500,
    stoppable: true,
    invocation: { invocationId: `spawn-${id}`, generation: 1 },
    ...overrides
  }
}

function settled(
  id: string,
  outcome: NonNullable<AgentChildWorkView['outcome']>,
  overrides: Partial<AgentChildWorkView> = {}
): AgentChildWorkView {
  return view(id, {
    state: 'done',
    membership: 'settled',
    outcome,
    settledAt: 450,
    ...overrides
  })
}

function shell(id: string, owner: string, overrides: Partial<AgentChildWorkView> = {}) {
  return view(id, {
    kind: 'command',
    description: 'npm run dev',
    agentType: undefined,
    state: 'monitoring',
    parentChildWorkId: owner,
    ...overrides
  })
}

function only(views: AgentChildWorkView[], context = FRESH): AgentChildRowModel {
  const [row] = buildAgentChildRowModels(views, context)
  return row
}

describe('buildAgentChildRowModels: the display vocabulary', () => {
  it.each<[string, AgentChildWorkView[], Pick<AgentChildRowModel, 'displayState' | 'detail'>]>([
    [
      'working with no known operation names its role',
      [view('a')],
      { displayState: 'working', detail: { kind: 'role', agentType: 'general-purpose' } }
    ],
    [
      'working with a foreground tool names the tool the way a CLI row does',
      [view('a', { operation: { toolName: 'Read', basis: 'open', observedAt: 400 } })],
      { displayState: 'working', detail: { kind: 'operation', toolName: 'Read' } }
    ],
    [
      'a foreground shell reads as working with its command',
      [
        view('a', {
          operation: { toolName: 'Bash', input: 'npm test', basis: 'open', observedAt: 400 }
        })
      ],
      {
        displayState: 'working',
        detail: { kind: 'operation', toolName: 'Bash', input: 'npm test' }
      }
    ],
    [
      'an idle child whose own shell runs reads monitoring',
      [view('a', { state: 'idle' }), shell('s', 'a')],
      { displayState: 'monitoring', detail: { kind: 'monitoring' } }
    ],
    [
      'a finished child whose own shell runs reads monitoring',
      [settled('a', 'succeeded', { lastMessage: 'All green' }), shell('s', 'a')],
      { displayState: 'monitoring', detail: { kind: 'monitoring' } }
    ],
    [
      'waiting names the tool the approval is for',
      [
        view('a', {
          state: 'waiting',
          operation: { toolName: 'Edit', input: 'src/a.ts', basis: 'open', observedAt: 400 }
        })
      ],
      {
        displayState: 'waiting',
        detail: { kind: 'operation', toolName: 'Edit', input: 'src/a.ts' }
      }
    ],
    [
      'blocked says why',
      [view('a', { state: 'blocked', lastMessage: 'Rate limited' })],
      { displayState: 'blocked', detail: { kind: 'message', text: 'Rate limited' } }
    ],
    [
      'succeeded reads done with its last message',
      [settled('a', 'succeeded', { lastMessage: 'Found 3 call sites' })],
      { displayState: 'done', detail: { kind: 'message', text: 'Found 3 call sites' } }
    ],
    [
      'failed reads failed with its error',
      [settled('a', 'failed', { lastMessage: 'Exit code 1' })],
      { displayState: 'failed', detail: { kind: 'message', text: 'Exit code 1' } }
    ],
    [
      'cancelled reads interrupted and adds no message',
      [settled('a', 'cancelled', { lastMessage: 'half a thought' })],
      { displayState: 'interrupted', detail: { kind: 'role', agentType: 'general-purpose' } }
    ],
    [
      'an ending the lane cannot classify is neutral and says Ended',
      [settled('a', 'unknown')],
      { displayState: 'idle', detail: { kind: 'ended' } }
    ],
    [
      'a parked live child names its role',
      [view('a', { state: 'idle' })],
      { displayState: 'idle', detail: { kind: 'role', agentType: 'general-purpose' } }
    ],
    [
      'a host-reported unverifiable child reports its silence',
      [view('a', { state: 'unverifiable' })],
      { displayState: 'unverifiable', detail: { kind: 'no-update' } }
    ]
  ])('%s', (_name, views, expected) => {
    const row = only(views)
    expect({ displayState: row.displayState, detail: row.detail }).toEqual(expected)
  })

  it('suppresses the tool line while monitoring, even when a stale operation arrives', () => {
    const row = only([
      view('a', {
        state: 'idle',
        operation: { toolName: 'Bash', input: 'npm test', basis: 'reported', observedAt: 400 }
      }),
      shell('s', 'a')
    ])
    expect(row.displayState).toBe('monitoring')
    expect(row.detail).toEqual({ kind: 'monitoring' })
  })

  it('makes every live claim unverifiable under a stale parent or a lost transport', () => {
    for (const context of [STALE, LOST]) {
      expect(only([view('a')], context)).toMatchObject({
        displayState: 'unverifiable',
        detail: { kind: 'no-update' }
      })
      // A finished child's monitoring is a claim about live work; its outcome is history.
      expect(only([settled('a', 'succeeded'), shell('s', 'a')], context).displayState).toBe(
        'unverifiable'
      )
      expect(only([settled('a', 'failed')], context).displayState).toBe('failed')
      expect(only([view('a', { state: 'idle' })], context).displayState).toBe('idle')
    }
  })

  it('gives sibling rows their own clocks, never the parent one', () => {
    const [busy, quiet] = buildAgentChildRowModels(
      [view('busy', { observedAt: 880 }), view('quiet', { firstObservedAt: 200, observedAt: 300 })],
      STALE
    )
    expect([busy.recencyAt, quiet.recencyAt]).toEqual([880, 300])
    expect([busy.observedAt, quiet.observedAt]).toEqual([880, 300])
    expect([busy.firstObservedAt, quiet.firstObservedAt]).toEqual([100, 200])
  })

  it('nests owned work under its owner and keeps host order', () => {
    const rows = buildAgentChildRowModels(
      [
        view('a'),
        shell('s', 'a', { state: 'working' }),
        view('b'),
        view('grandchild', { parentChildWorkId: 'a' })
      ],
      FRESH
    )
    expect(rows.map((row) => row.id)).toEqual(['a', 'b'])
    expect(rows[0].owned.map((row) => row.id)).toEqual(['s', 'grandchild'])
    expect(flattenAgentChildRowModels(rows).map((row) => row.id)).toEqual([
      'a',
      's',
      'grandchild',
      'b'
    ])
    // A shell names itself; only an agent's own tool line can go stale.
    expect(rows[0].owned[0]).toMatchObject({ displayState: 'working', detail: null })
  })

  it('names a row by its label and omits a role that restates it', () => {
    expect(
      only([view('a', { description: '  ', name: 'subagent', agentType: 'Explore' })])
    ).toMatchObject({ name: 'Explore', detail: null })
    expect(only([view('a', { description: undefined, agentType: undefined })])).toMatchObject({
      name: '',
      detail: { kind: 'role', agentType: 'unknown' }
    })
  })

  it('offers a stop only for a live row the host can target', () => {
    expect(only([view('a')]).canStop).toBe(true)
    expect(only([view('a', { providerId: undefined })]).canStop).toBe(false)
    expect(only([view('a', { stoppable: false })]).canStop).toBe(false)
    expect(only([settled('a', 'succeeded')]).canStop).toBe(false)
  })
})

describe('buildLegacyAgentChildRowModels', () => {
  it('reads a legacy snapshot as before: no clock of its own, no outcome, no operation', () => {
    const rows = buildLegacyAgentChildRowModels(
      [
        { id: 'w', state: 'working', startedAt: 10, description: 'Review', agentType: 'Explore' },
        { id: 'i', state: 'idle', startedAt: 20, agentType: 'writer' },
        { id: 'u', state: 'unverifiable', startedAt: 30 }
      ],
      FRESH
    )
    expect(rows).toEqual([
      expect.objectContaining({
        id: 'w',
        providerId: 'w',
        displayState: 'working',
        name: 'Review',
        detail: { kind: 'role', agentType: 'Explore' },
        firstObservedAt: 10,
        recencyAt: 900,
        settled: false,
        canStop: false
      }),
      expect.objectContaining({ id: 'i', displayState: 'idle', name: 'writer', detail: null }),
      expect.objectContaining({
        id: 'u',
        displayState: 'unverifiable',
        detail: { kind: 'no-update' }
      })
    ])
    expect(rows.every((row) => row.observedAt === undefined)).toBe(true)
  })

  it('decays live legacy states under a stale parent, as before', () => {
    const rows = buildLegacyAgentChildRowModels(
      [
        { id: 'w', state: 'working', startedAt: 10 },
        { id: 'q', state: 'waiting', startedAt: 10 },
        { id: 'i', state: 'idle', startedAt: 10 }
      ],
      STALE
    )
    expect(rows.map((row) => row.displayState)).toEqual(['unverifiable', 'unverifiable', 'idle'])
  })
})

describe('buildLegacyTaskRowModels', () => {
  it('keeps the state the host decided and says only its reason', () => {
    const rows = buildLegacyTaskRowModels(
      [
        { id: 'w', kind: 'agent', description: 'Review', state: 'working', startedAt: 10 },
        { id: 'q', kind: 'agent', description: 'Approve', state: 'waiting' },
        { id: 'u', kind: 'agent', description: 'Lost', state: 'unverifiable' },
        { id: 'm', kind: 'monitor', description: 'tail -f log' },
        { id: 'c', kind: 'command', description: 'npm test', stoppable: false }
      ],
      [{ id: 'd', kind: 'agent', description: 'Done', totalTokens: 900 }]
    )
    expect(rows.map((row) => [row.id, row.displayState, row.detail])).toEqual([
      ['d', 'done', null],
      ['w', 'working', null],
      ['q', 'waiting', { kind: 'reason', state: 'waiting' }],
      ['u', 'unverifiable', { kind: 'reason', state: 'unverifiable' }],
      ['m', 'monitoring', null],
      ['c', 'working', null]
    ])
    expect(rows.map((row) => row.canStop)).toEqual([true, true, true, true, true, false])
    expect(rows[0]).toMatchObject({ settled: true, totalTokens: 900 })
  })

  it('lets a resumed live task replace its retained settled row', () => {
    const rows = buildLegacyTaskRowModels(
      [{ id: 'r', kind: 'agent', state: 'working' }],
      [{ id: 'r', kind: 'agent', state: 'done' }]
    )
    expect(rows).toHaveLength(1)
    expect(rows[0]).toMatchObject({ settled: false, displayState: 'working' })
  })
})

describe('one label rule for every shape a host publishes', () => {
  it.each(['task', ' Subagent ', 'unknown', '   '])(
    'skips the placeholder %j on all three',
    (label) => {
      const [fromView] = buildAgentChildRowModels(
        [view('a', { description: label, agentType: 'Explore' })],
        FRESH
      )
      const [fromSnapshot] = buildLegacyAgentChildRowModels(
        [{ id: 'a', state: 'working', startedAt: 10, description: label, agentType: 'Explore' }],
        FRESH
      )
      const [fromRoster] = buildLegacyTaskRowModels(
        [{ id: 'a', kind: 'agent', state: 'working', description: label, name: 'Explore' }],
        []
      )
      expect([fromView.name, fromSnapshot.name, fromRoster.name]).toEqual([
        'Explore',
        'Explore',
        'Explore'
      ])
    }
  )

  it('leaves a row with no usable label unnamed on all three', () => {
    const [fromSnapshot] = buildLegacyAgentChildRowModels(
      [{ id: 'a', state: 'working', startedAt: 10, description: 'task' }],
      FRESH
    )
    const [fromRoster] = buildLegacyTaskRowModels(
      [{ id: 'a', kind: 'agent', state: 'working', description: 'task' }],
      []
    )
    expect([only([view('a', { description: 'task', agentType: undefined })]).name]).toEqual([''])
    expect([fromSnapshot.name, fromRoster.name]).toEqual(['', ''])
  })
})

describe('agentChildRowContextForParent: the reader clock', () => {
  const MIRRORED_PARENT = {
    // The host's clock runs 20 minutes ahead of this machine's.
    updatedAt: 1_200_000 + 20 * 60_000,
    evidenceObservedAt: 1_190_000 + 20 * 60_000,
    mirroredEvidenceReceivedAt: 1_190_000
  }

  it("measures a mirrored parent on this machine's receipt clock, never the host's", () => {
    const context = agentChildRowContextForParent(MIRRORED_PARENT, false)
    expect(context).toEqual({
      parentEvidenceFresh: false,
      transportObservation: 'live',
      parentObservedAt: 1_190_000,
      hostClockOffsetMs: -20 * 60_000
    })
    const [legacy] = buildLegacyAgentChildRowModels(
      [{ id: 'a', state: 'working', startedAt: 10 }],
      context
    )
    expect(legacy.recencyAt).toBe(1_190_000)
    // A view's own host stamp moves onto the reader clock; its host-clock age is kept.
    const [child] = buildAgentChildRowModels(
      [view('a', { observedAt: 1_100_000 + 20 * 60_000 })],
      context
    )
    expect(child.recencyAt).toBe(1_100_000)
    expect(child.observedAt).toBe(1_100_000 + 20 * 60_000)
  })

  it('leaves a parent observed on this machine on its own clock', () => {
    expect(
      agentChildRowContextForParent({ updatedAt: 500, evidenceObservedAt: 400 }, true)
    ).toEqual({
      parentEvidenceFresh: true,
      transportObservation: 'live',
      parentObservedAt: 400,
      hostClockOffsetMs: 0
    })
  })
})