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.

15.2 KB
Raw Blame
import { describe, expect, it } from 'vitest'
import type { AgentJournalRenderItem } from './agent-session-journal-types'
import type { AgentSessionHistoryPage } from './agent-session-wire'
import {
  EMPTY_STRUCTURED_AGENT_SESSION,
  oldestStructuredAgentSessionCursor,
  reduceStructuredAgentSession,
  type StructuredAgentSessionState
} from './structured-agent-session-reducer'

const CAP = 1024
const BACKSTOP = 4 * CAP

function item(sequence: number): AgentJournalRenderItem {
  return {
    itemId: `item-${sequence}`,
    revision: 1,
    sequence,
    observedAt: sequence,
    body: { kind: 'message', role: 'assistant', blocks: [{ type: 'text', text: `t-${sequence}` }] }
  }
}

function childItem(sequence: number): AgentJournalRenderItem {
  return { ...item(sequence), agentId: 'task-1', producerKind: 'agent' }
}

const range = (from: number, length: number): number[] =>
  Array.from({ length }, (_, index) => from + index)

function page(items: AgentJournalRenderItem[], hasOlder: boolean): AgentSessionHistoryPage {
  const oldest = items[0]?.sequence ?? 0
  const newest = items.at(-1)?.sequence ?? 0
  return {
    sessionId: 'session-a',
    epoch: 'epoch-a',
    direction: 'tail',
    items,
    removedItemIds: [],
    submissions: [],
    window: {
      oldest: { epoch: 'epoch-a', sequence: oldest },
      newest: { epoch: 'epoch-a', sequence: newest },
      nextCursor: { epoch: 'epoch-a', sequence: oldest }
    },
    liveCursor: { epoch: 'epoch-a', sequence: newest },
    hasOlder,
    hasNewer: false
  }
}

function hydrate(items: AgentJournalRenderItem[], hasOlder = false): StructuredAgentSessionState {
  return reduceStructuredAgentSession(EMPTY_STRUCTURED_AGENT_SESSION, {
    type: 'event',
    event: { type: 'snapshot', sessionId: 'session-a', fence: 1, page: page(items, hasOlder) }
  })
}

function streamItems(
  state: StructuredAgentSessionState,
  sequences: number[]
): StructuredAgentSessionState {
  return sequences.reduce(
    (current, sequence) =>
      reduceStructuredAgentSession(current, {
        type: 'event',
        event: {
          type: 'batch',
          sessionId: 'session-a',
          batch: {
            cursor: { epoch: 'epoch-a', sequence },
            items: [item(sequence)],
            removedItemIds: [],
            submissions: []
          }
        }
      }),
    state
  )
}

/** Batch bursts so tests exercise merges without one per row. */
function streamBatches(
  state: StructuredAgentSessionState,
  rows: AgentJournalRenderItem[],
  size = 1_000
): StructuredAgentSessionState {
  let current = state
  for (let offset = 0; offset < rows.length; offset += size) {
    const batch = rows.slice(offset, offset + size)
    current = reduceStructuredAgentSession(current, {
      type: 'event',
      event: {
        type: 'batch',
        sessionId: 'session-a',
        batch: {
          cursor: { epoch: 'epoch-a', sequence: batch.at(-1)?.sequence ?? 0 },
          items: batch,
          removedItemIds: [],
          submissions: []
        }
      }
    })
  }
  return current
}

function streamRevision(
  state: StructuredAgentSessionState,
  row: AgentJournalRenderItem,
  cursorSequence: number
): StructuredAgentSessionState {
  return reduceStructuredAgentSession(state, {
    type: 'event',
    event: {
      type: 'batch',
      sessionId: 'session-a',
      batch: {
        cursor: { epoch: 'epoch-a', sequence: cursorSequence },
        items: [row],
        removedItemIds: [],
        submissions: []
      }
    }
  })
}

describe('structured agent session item retention', () => {
  it('bounds retained items on a long live session', () => {
    const streamed = streamItems(
      hydrate([item(0)]),
      Array.from({ length: CAP + 500 }, (_, index) => index + 1)
    )

    expect(streamed.items).toHaveLength(CAP)
    expect(streamed.items.at(-1)?.sequence).toBe(CAP + 500)
    expect(streamed.items[0]?.sequence).toBe(501)
  })

  it('offers paging for items the cap dropped', () => {
    const streamed = streamItems(
      hydrate([item(0)]),
      Array.from({ length: CAP + 10 }, (_, index) => index + 1)
    )

    expect(streamed.hasOlder).toBe(true)
    expect(oldestStructuredAgentSessionCursor(streamed)).toEqual({
      epoch: 'epoch-a',
      sequence: streamed.items[0]?.sequence
    })
  })

  it('leaves a session under the cap untouched', () => {
    const hydrated = hydrate([item(0)])
    const streamed = streamItems(
      hydrated,
      Array.from({ length: 200 }, (_, index) => index + 1)
    )

    expect(streamed.items).toHaveLength(201)
    expect(streamed.hasOlder).toBe(false)
  })

  it('widens the retained window when older items are paged in', () => {
    const streamed = streamItems(
      hydrate([item(1_000)], true),
      Array.from({ length: CAP + 10 }, (_, index) => index + 1_001)
    )
    const older = reduceStructuredAgentSession(streamed, {
      type: 'older-page',
      requestedCursor: { epoch: 'epoch-a', sequence: streamed.items[0]?.sequence ?? 0 },
      page: page(
        Array.from({ length: 300 }, (_, index) => item(index + 700)),
        true
      )
    })
    expect(older.items).toHaveLength(CAP + 300)

    // A live batch slides the widened window by one instead of collapsing it back to the cap.
    const afterLive = streamItems(older, [3_000])

    expect(afterLive.items).toHaveLength(CAP + 300)
    expect(afterLive.items[0]?.sequence).toBe(701)
    expect(afterLive.items.some((entry) => entry.sequence === 800)).toBe(true)
  })

  it('drops an older page whose anchor a live batch trimmed past', () => {
    const streamed = streamItems(
      hydrate([item(0)], false),
      Array.from({ length: CAP + 200 }, (_, index) => index + 1)
    )
    // The read captures this cursor, then a live batch trims three items off the head.
    const anchor = oldestStructuredAgentSessionCursor(streamed)
    const slid = streamItems(streamed, [CAP + 201, CAP + 202, CAP + 203])
    expect(slid.items[0]?.sequence).toBeGreaterThan(anchor?.sequence ?? 0)

    const merged = reduceStructuredAgentSession(slid, {
      type: 'older-page',
      requestedCursor: anchor ?? { epoch: 'epoch-a', sequence: 0 },
      page: page(
        Array.from({ length: 200 }, (_, index) => item((anchor?.sequence ?? 0) - 200 + index)),
        true
      )
    })

    // Merging would have left a hole between the page and the retained window.
    expect(merged).toBe(slid)
  })

  it('accepts an older page whose anchor still matches the retained head', () => {
    const streamed = streamItems(
      hydrate([item(0)], false),
      Array.from({ length: CAP + 200 }, (_, index) => index + 1)
    )
    const anchor = oldestStructuredAgentSessionCursor(streamed)
    const merged = reduceStructuredAgentSession(streamed, {
      type: 'older-page',
      requestedCursor: anchor ?? { epoch: 'epoch-a', sequence: 0 },
      page: page(
        Array.from({ length: 200 }, (_, index) => item((anchor?.sequence ?? 0) - 200 + index)),
        true
      )
    })

    expect(merged.items).toHaveLength(CAP + 200)
    expect(merged.items[0]?.sequence).toBe((anchor?.sequence ?? 0) - 200)
  })

  it('keeps the anchor on the oldest loaded row when a live batch revises a row older than the window', () => {
    // Tail snapshot of a long session: rows 200..239 loaded, 199 rows older on the host.
    const hydrated = hydrate(
      Array.from({ length: 40 }, (_, index) => item(index + 200)),
      true
    )
    expect(oldestStructuredAgentSessionCursor(hydrated)?.sequence).toBe(200)

    // The host revises row 50 in place; the revision keeps its original sequence.
    const revised = reduceStructuredAgentSession(hydrated, {
      type: 'event',
      event: {
        type: 'batch',
        sessionId: 'session-a',
        batch: {
          cursor: { epoch: 'epoch-a', sequence: 240 },
          items: [{ ...item(50), revision: 2 }, item(240)],
          removedItemIds: [],
          submissions: []
        }
      }
    })

    // Anchoring on row 50 would page `before: 50` and never load rows 51..199.
    expect(oldestStructuredAgentSessionCursor(revised)?.sequence).toBe(200)
    expect(revised.items.some((entry) => entry.sequence === 50)).toBe(false)
    expect(revised.items.at(-1)?.sequence).toBe(240)
    expect(revised.cursor?.sequence).toBe(240)
    expect(revised.hasOlder).toBe(true)

    // The page reader serves the row at its current revision once the window reaches it.
    const older = reduceStructuredAgentSession(revised, {
      type: 'older-page',
      requestedCursor: { epoch: 'epoch-a', sequence: 200 },
      page: page(
        [{ ...item(50), revision: 2 }, ...Array.from({ length: 149 }, (_, i) => item(i + 51))],
        false
      )
    })
    expect(older.items.find((entry) => entry.sequence === 50)?.revision).toBe(2)
    expect(oldestStructuredAgentSessionCursor(older)?.sequence).toBe(50)
    expect(older.hasOlder).toBe(false)
  })

  it('applies a live revision of a row the window holds, including its oldest row', () => {
    const hydrated = hydrate(
      Array.from({ length: 3 }, (_, index) => item(index + 200)),
      true
    )
    const revised = streamRevision(hydrated, { ...item(200), revision: 2 }, 203)

    expect(revised.items.find((entry) => entry.sequence === 200)?.revision).toBe(2)
    expect(oldestStructuredAgentSessionCursor(revised)?.sequence).toBe(200)
  })

  it('admits a live row below the head when nothing older is left on the host', () => {
    // Whole journal starts at 2 after a tombstone; reviving row 1 creates no paging hole.
    const hydrated = hydrate(
      Array.from({ length: 3 }, (_, index) => item(index + 2)),
      false
    )
    const revived = streamRevision(hydrated, { ...item(1), revision: 2 }, 5)

    expect(oldestStructuredAgentSessionCursor(revived)?.sequence).toBe(1)
    expect(revived.hasOlder).toBe(false)
  })

  it('counts a live turn-row revision the window could not take, and nothing else', () => {
    const hydrated = hydrate(
      Array.from({ length: 3 }, (_, index) => item(index + 200)),
      true
    )
    const turnRow = (sequence: number, revision: number): AgentJournalRenderItem => ({
      ...item(sequence),
      revision,
      body: { kind: 'turn', turnId: `turn-${sequence}`, state: 'running' }
    })

    const olderMessage = streamRevision(hydrated, { ...item(50), revision: 2 }, 203)
    expect(olderMessage.unloadedTurnRevisions).toBeUndefined()
    const loadedTurn = streamRevision(hydrated, turnRow(201, 2), 203)
    expect(loadedTurn.unloadedTurnRevisions).toBeUndefined()

    const olderTurn = streamRevision(hydrated, turnRow(50, 2), 203)
    expect(olderTurn.items.some((entry) => entry.sequence === 50)).toBe(false)
    expect(olderTurn.unloadedTurnRevisions).toBe(1)
    expect(streamRevision(olderTurn, turnRow(50, 3), 204).unloadedTurnRevisions).toBe(2)
  })

  it('counts a turn row the cap trims out of a live window', () => {
    const turnRow: AgentJournalRenderItem = {
      ...item(0),
      body: { kind: 'turn', turnId: 'turn-0', state: 'running' }
    }
    const full = streamItems(
      hydrate([turnRow]),
      Array.from({ length: CAP - 1 }, (_, index) => index + 1)
    )
    expect(full.unloadedTurnRevisions).toBeUndefined()
    const trimmed = streamItems(full, [CAP])
    expect(trimmed.items[0]?.sequence).toBe(1)
    expect(trimmed.unloadedTurnRevisions).toBe(1)
    expect(streamItems(trimmed, [CAP + 1]).unloadedTurnRevisions).toBe(1)
  })

  it('keeps item identity stable when a batch carries no journal change', () => {
    const hydrated = hydrate([item(0)])
    const unchanged = reduceStructuredAgentSession(hydrated, {
      type: 'event',
      event: {
        type: 'batch',
        sessionId: 'session-a',
        fence: 2,
        batch: {
          cursor: { epoch: 'epoch-a', sequence: 0 },
          items: [],
          removedItemIds: [],
          submissions: []
        }
      }
    })

    expect(unchanged.items).toBe(hydrated.items)
  })

  it("counts the session's own rows, so a subagent's burst keeps the rows before it", () => {
    const streamed = streamBatches(hydrate([item(0), item(1)]), range(2, CAP + 500).map(childItem))

    expect(streamed.items).toHaveLength(CAP + 502)
    expect(streamed.items.slice(0, 2).map(({ itemId }) => itemId)).toEqual(['item-0', 'item-1'])
    expect(streamed.hasOlder).toBe(false)
  })

  it("trims through the oldest own row the limit passes, with the subagent's rows before it", () => {
    const rows = range(1, CAP + 1).flatMap((sequence) =>
      sequence === 1 ? [childItem(sequence)] : [item(sequence)]
    )
    const streamed = streamBatches(hydrate([item(0)]), rows)

    // Own rows 0 and 2..CAP+1 are CAP+1 of them: row 0 goes, and child row 1 after it stays.
    expect(streamed.items[0]?.itemId).toBe('item-1')
    expect(streamed.items).toHaveLength(CAP + 1)
    expect(streamed.hasOlder).toBe(true)
  })

  it("bounds every agent's rows at the backstop, which paging back raises like the limit", () => {
    const streamed = streamBatches(hydrate([item(0)]), range(1, BACKSTOP + 10).map(childItem))

    expect(streamed.items).toHaveLength(BACKSTOP)
    expect(streamed.items.at(-1)?.sequence).toBe(BACKSTOP + 10)
    expect(streamed.hasOlder).toBe(true)

    const older = reduceStructuredAgentSession(streamed, {
      type: 'older-page',
      requestedCursor: { epoch: 'epoch-a', sequence: streamed.items[0]?.sequence ?? 0 },
      page: page(range(0, 11).map(childItem), false)
    })
    expect(older.items).toHaveLength(BACKSTOP + 11)
    // A live batch slides the widened window by one instead of collapsing it back to the cap.
    const afterLive = streamBatches(older, [childItem(BACKSTOP + 11)])
    expect(afterLive.items).toHaveLength(BACKSTOP + 11)
    expect(afterLive.items[0]?.sequence).toBe(1)
  })

  it("keeps a paged-in run of a subagent's rows at the head until an own row pushes it out", () => {
    // A full window of own rows, then a page back that holds only a subagent's rows.
    const hydrated = hydrate(range(2_000, CAP).map(item), true)
    const older = reduceStructuredAgentSession(hydrated, {
      type: 'older-page',
      requestedCursor: { epoch: 'epoch-a', sequence: 2_000 },
      page: page(range(1_800, 200).map(childItem), true)
    })
    expect(older.items[0]?.sequence).toBe(1_800)

    const afterChild = streamBatches(older, [childItem(3_100)])
    expect(afterChild.items[0]?.sequence).toBe(1_800)

    const afterOwn = streamBatches(afterChild, [item(3_101)])
    expect(afterOwn.items[0]?.sequence).toBe(2_001)
  })

  it('trims a transcript with no subagent rows to its newest rows, exactly as before', () => {
    const hydrated = hydrate(range(0, 300).map(item), true)
    const streamed = streamBatches(hydrated, range(300, CAP + 77).map(item), 97)
    const older = reduceStructuredAgentSession(streamed, {
      type: 'older-page',
      requestedCursor: { epoch: 'epoch-a', sequence: streamed.items[0]?.sequence ?? 0 },
      page: page(range((streamed.items[0]?.sequence ?? 0) - 200, 200).map(item), true)
    })
    const afterLive = streamBatches(older, range(CAP + 377, 5).map(item))

    const newest = (from: number, length: number) => range(from, length)
    expect(streamed.items.map(({ sequence }) => sequence)).toEqual(newest(377, CAP))
    expect(older.items.map(({ sequence }) => sequence)).toEqual(newest(177, CAP + 200))
    expect(afterLive.items.map(({ sequence }) => sequence)).toEqual(newest(182, CAP + 200))
  })
})