Skip to content

Replay your coding agent sessions as a map and a timeline

19.3 KB
Raw Blame
import { describe, expect, it } from 'vitest';
import {
  SESSION_MAP_SCHEMA_V1,
  sessionMapSchema,
  type SessionMap,
} from './schema';
import {
  INNER_MAX,
  INNER_MIN,
  activeSet,
  agentLabel,
  buildTree,
  countersAt,
  cumulativeCost,
  deriveLensDoc,
  describeEvent,
  eventNodeRefs,
  fileCoverage,
  findNext,
  initialPlayhead,
  lastTouch,
  layoutTree,
  nextTouchOf,
  recentTargets,
  recomputeTotals,
  reviewMetrics,
  shiftStartedAt,
  stateAt,
} from './sessionMapModel';

type RawEvent = Record<string, unknown> & { kind: string };

function makeMap(events: RawEvent[], overrides: Record<string, unknown> = {}) {
  return sessionMapSchema.parse({
    schema: SESSION_MAP_SCHEMA_V1,
    session: {
      id: 'local:claude-code:abc12345-0000',
      agentTool: 'claude-code',
      startedAt: '2026-09-10T01:00:00Z',
      durationMs: 60_000,
      models: ['claude-opus-5'],
    },
    totals: { calls: 0, requests: 0 },
    repos: [
      { id: 'r0', name: 'backend', remote: 'org/backend' },
      { id: 'r1', name: 'cli' },
    ],
    files: [
      {
        id: 0,
        repo: 'r0',
        path: 'billing_core/deep/nested/controller.py',
        reads: 1,
        edits: 3,
      },
      {
        id: 1,
        repo: 'r0',
        path: 'billing_core/views.py',
        reads: 2,
        edits: 0,
      },
      { id: 2, repo: 'r1', path: 'README.md', reads: 0, edits: 1 },
      {
        id: 3,
        repo: 'r0',
        path: 'billing_core/new_file.py',
        reads: 0,
        edits: 1,
      },
    ],
    agents: [
      { id: 'main', parent: null, kind: 'main', cost: 3, calls: 5 },
      {
        id: 'sa-ae824d54211f',
        parent: 'main',
        kind: 'subagent',
        subagentType: 'general-purpose',
        cost: 1,
        calls: 2,
      },
    ],
    events: events.map((e, i) => ({
      seq: i,
      t: i * 1000,
      agent: 'main',
      err: false,
      ...e,
    })),
    ...overrides,
  });
}

const EVENTS: RawEvent[] = [
  { kind: 'user', chars: 120 }, // 0
  {
    kind: 'llm',
    model: 'claude-opus-5',
    in: 10,
    cw: 100,
    cr: 1000,
    out: 50,
    cost: 0.5,
  }, // 1
  { kind: 'read', tool: 'Read', targets: [{ file: 1, touch: 'read' }] }, // 2
  { kind: 'edit', tool: 'Edit', targets: [{ file: 0, touch: 'edit' }] }, // 3 blind
  { kind: 'read', tool: 'Read', targets: [{ file: 0, touch: 'read' }] }, // 4
  { kind: 'edit', tool: 'Write', targets: [{ file: 3, touch: 'edit' }] }, // 5 creates, not blind
  { kind: 'mcp', server: 'acme-context', tool: 'find_expert' }, // 6
  { kind: 'skill', skill: 'artifact-design' }, // 7
  { kind: 'web', tool: 'WebFetch', host: 'docs.example.com' }, // 8
  {
    kind: 'subagent',
    tool: 'Agent',
    subagentType: 'general-purpose',
    child: 'sa-ae824d54211f',
  }, // 9
  {
    kind: 'read',
    tool: 'Read',
    agent: 'sa-ae824d54211f',
    targets: [{ file: 1, touch: 'read' }],
  }, // 10 re-read
  {
    kind: 'exec',
    tool: 'Bash',
    verb: 'git log',
    err: true,
    targets: [{ scope: 'outside', label: '/tmp (scratch)', touch: 'read' }],
  }, // 11
  { kind: 'verify', tool: 'Bash', verb: 'pytest' }, // 12
  { kind: 'edit', tool: 'Edit', targets: [{ file: 0, touch: 'edit' }] }, // 13 after verify
  {
    kind: 'llm',
    model: 'claude-sonnet-5',
    in: 5,
    cw: 0,
    cr: 500,
    out: 20,
    cost: 0.25,
  }, // 14
  { kind: 'edit', tool: 'Edit', targets: [{ file: 2, touch: 'edit' }] }, // 15 blind (never read)
];

describe('sessionMapSchema', () => {
  it('rejects a map that is not v1', () => {
    const r = sessionMapSchema.safeParse({
      schema: 'agentplay/v2',
      session: { id: 'x', startedAt: '2026-01-01T00:00:00Z' },
      totals: {},
    });
    expect(r.success).toBe(false);
  });

  it('keeps unknown fields and defaults optional ones', () => {
    const m = makeMap([{ kind: 'read', futureField: 7 }], { extra: true });
    expect(m.events[0].agent).toBe('main');
    expect((m.events[0] as Record<string, unknown>).futureField).toBe(7);
    expect((m as Record<string, unknown>).extra).toBe(true);
    expect(m.session.truncated).toBe(false);
  });
});

describe('buildTree', () => {
  const map = makeMap(EVENTS);
  const tree = buildTree(map);

  it('puts repos first, then the named groups', () => {
    const names = tree.root.children.map((c) => `${c.type}:${c.name}`);
    expect(names.slice(0, 2)).toEqual(['repo:backend', 'repo:cli']);
    expect(names).toEqual(
      expect.arrayContaining([
        'group:outside repos',
        'group:MCP',
        'group:skills',
        'group:web',
        'group:subagents',
      ])
    );
  });

  it('collapses single-child directory chains and keeps folded ids resolvable', () => {
    const collapsed = tree.byId.get('dir:r0/billing_core/deep');
    expect(collapsed?.name).toBe('deep/nested');
    expect(tree.byId.get('dir:r0/billing_core/deep/nested')).toBe(collapsed);
    // billing_core has 3 children (deep/nested, views.py, new_file.py): not collapsed
    expect(tree.byId.get('dir:r0/billing_core')?.name).toBe('billing_core');
  });

  it('nests MCP tools under their server and labels subagents by type', () => {
    const tool = tree.byId.get('mcp:acme-context/find_expert');
    expect(tool?.parent?.id).toBe('srv:acme-context');
    expect(tool?.parent?.parent?.id).toBe('g:mcp');
    expect(tree.byId.get('agent:sa-ae824d54211f')?.name).toBe(
      'Sub 1: general-purpose'
    );
  });
});

describe('layoutTree', () => {
  it('puts leaves on the outer ring and internals between 0.32R and 0.78R', () => {
    const R = 200;
    const tree = buildTree(makeMap(EVENTS));
    const nodes = layoutTree(tree, R);
    for (const n of nodes) {
      if (n === tree.root) {
        expect(n.r).toBe(0);
      } else if (!n.children.length) {
        expect(n.r).toBeCloseTo(R);
        expect(Math.hypot(n.x, n.y)).toBeCloseTo(R);
      } else {
        expect(n.r).toBeGreaterThanOrEqual(R * INNER_MIN - 1e-9);
        expect(n.r).toBeLessThanOrEqual(R * INNER_MAX + 1e-9);
      }
    }
  });
});

describe('playhead state', () => {
  const map = makeMap(EVENTS);
  const tree = buildTree(map);
  const refs = eventNodeRefs(map, tree);

  it('counts touches and keeps the highest touch level', () => {
    const st = stateAt(refs, 4);
    const f0 = st.get('file:0');
    expect(f0?.cnt).toBe(2);
    expect(f0?.lvl).toBe(3);
    expect(f0?.first).toBe(3);
    expect(st.get('file:1')?.lvl).toBe(2);
    expect(st.has('file:2')).toBe(false);
  });

  it('keeps only the most recent distinct nodes active', () => {
    const active = activeSet(refs, 11, 3);
    // #11 failed: its place and the error-class node are both active
    expect([...active]).toEqual([
      'place:/tmp (scratch)',
      'errc:tool/other',
      'file:1',
    ]);
  });

  it('builds the trail oldest first', () => {
    const trail = recentTargets(refs, 5, 9);
    expect(trail.map((t) => t.i)).toEqual([2, 3, 4, 5]);
  });

  it('finds the one step the playhead lights: the last real touch', () => {
    expect(lastTouch(refs, 5)).toEqual({ i: 5, ids: ['file:3'] });
    // #12 (a verify) touches nothing: the failed #11 stays lit, with its
    // error class
    expect(lastTouch(refs, 12)).toEqual({
      i: 11,
      ids: ['place:/tmp (scratch)', 'errc:tool/other'],
    });
    // #1's model ref is passive, and #0 touches nothing
    expect(lastTouch(refs, 1)).toBeNull();
  });

  it('jumps to the next touch of a node or anything under it, wrapping', () => {
    expect(nextTouchOf(tree, refs, 3, 'file:0')).toBe(4);
    expect(nextTouchOf(tree, refs, 13, 'file:0')).toBe(3);
    expect(nextTouchOf(tree, refs, 0, 'dir:r0/billing_core')).toBe(2);
    expect(nextTouchOf(tree, refs, 0, 'nope')).toBeNull();
  });
});

describe('navigation helpers', () => {
  const map = makeMap(EVENTS);

  it('findNext wraps around and handles errors', () => {
    expect(findNext(map.events, 3, 'edit')).toBe(5);
    expect(findNext(map.events, 15, 'edit')).toBe(3);
    expect(findNext(map.events, 0, 'err')).toBe(11);
    expect(findNext(map.events, 0, 'subagent')).toBe(9);
    expect(findNext(makeMap([{ kind: 'read' }]).events, 0, 'user')).toBeNull();
  });

  it('opens just past the first edit, or 40% in without edits', () => {
    expect(initialPlayhead(map.events)).toBe(15);
    const noEdits = makeMap(
      Array.from({ length: 10 }, () => ({ kind: 'read' }))
    );
    expect(initialPlayhead(noEdits.events)).toBe(4);
    expect(initialPlayhead([])).toBe(0);
  });
});

describe('counters and costs', () => {
  const map = makeMap(EVENTS);

  it('counts calls, requests and files at the playhead', () => {
    const c = countersAt(map.events, 11);
    expect(c.requests).toBe(1);
    expect(c.tokens).toBe(1160);
    expect(c.cost).toBeCloseTo(0.5);
    expect(c.calls).toBe(10);
    expect(c.errors).toBe(1);
    expect(c.mcp).toBe(1);
    expect(c.skills).toBe(1);
    expect(c.subagents).toBe(1);
    expect(c.filesRead).toBe(2);
    expect(c.filesEdited).toBe(2);
  });

  it('accumulates cost as a prefix sum', () => {
    const cum = cumulativeCost(map.events);
    expect(cum[0]).toBe(0);
    expect(cum[1]).toBeCloseTo(0.5);
    expect(cum[cum.length - 1]).toBeCloseTo(0.75);
  });
});

describe('reviewMetrics', () => {
  it('flags blind edits but not a Write that creates a file', () => {
    const r = reviewMetrics(makeMap(EVENTS));
    expect(r.blindEdits).toBe(2); // #3 file 0, #15 file 2
    expect(r.errors).toBe(1);
    expect(r.churnFiles).toBe(1);
    // 3 file reads; #10 re-reads file 1 unchanged since #2
    expect(r.reReadPct).toBe(33);
    expect(r.verification).toBe('edits_after_verify');
  });

  it('reports verification after the final edit, and never', () => {
    const after = makeMap([
      { kind: 'edit', tool: 'Write', targets: [{ file: 3, touch: 'edit' }] },
      { kind: 'verify', tool: 'Bash', verb: 'pytest' },
    ]);
    expect(reviewMetrics(after).verification).toBe('after_final_edit');
    expect(reviewMetrics(after).blindEdits).toBe(0);
    expect(reviewMetrics(makeMap([{ kind: 'read' }])).verification).toBe(
      'never'
    );
  });

  it('does not count a read after an edit as a re-read', () => {
    const m = makeMap([
      { kind: 'read', tool: 'Read', targets: [{ file: 1, touch: 'read' }] },
      { kind: 'edit', tool: 'Edit', targets: [{ file: 1, touch: 'edit' }] },
      { kind: 'read', tool: 'Read', targets: [{ file: 1, touch: 'read' }] },
    ]);
    expect(reviewMetrics(m).reReadPct).toBe(0);
  });
});

describe('describeEvent and labels', () => {
  const map: SessionMap = makeMap(EVENTS);

  it('describes LLM, user and file events without leaking content', () => {
    expect(describeEvent(map, map.events[1]).title).toBe(
      'claude-opus-5 · $0.50'
    );
    expect(describeEvent(map, map.events[0]).detail).toBe(
      '120 chars (text not stored)'
    );
    const edit = describeEvent(map, map.events[3]);
    expect(edit.title).toBe('controller.py');
    expect(edit.detail).toBe(
      'backend/billing_core/deep/nested/controller.py'
    );
    expect(describeEvent(map, map.events[11]).title).toBe('/tmp (scratch)');
    expect(describeEvent(map, map.events[9]).detail).toBe(
      'spawned Sub 1: general-purpose'
    );
  });

  it('labels agents', () => {
    expect(agentLabel(map, 'main')).toBe('Main agent');
    expect(agentLabel(map, 'sa-ae824d54211f')).toBe('Sub 1: general-purpose');
  });

  it('summarises file coverage', () => {
    expect(fileCoverage(map)).toEqual({ edited: 3, read: 1, seen: 0 });
  });
});

describe('agent lens (deriveLensDoc / recomputeTotals)', () => {
  // `main` touches file 0 and file 2; `sa-1` (spawned by main at #2) has its
  // own lane: a failed exec, a retry of it, a tool delay caused by
  // it, a file it creates (file 1), and a confirmed PR create.
  const LENS_EVENTS: RawEvent[] = [
    { kind: 'user', chars: 10 }, // 0 main
    {
      kind: 'edit',
      tool: 'Write',
      targets: [{ file: 0, touch: 'edit', op: 'modify' }],
    }, // 1 main touches file 0
    {
      kind: 'subagent',
      tool: 'Agent',
      subagentType: 'general-purpose',
      child: 'sa-1',
    }, // 2 main spawns sa-1
    {
      kind: 'exec',
      tool: 'Bash',
      verb: 'pytest',
      agent: 'sa-1',
      err: true,
      errClass: 'exit_code',
    }, // 3 sa-1 fails
    { kind: 'exec', tool: 'Bash', verb: 'pytest', agent: 'sa-1', retryOf: 3 }, // 4 sa-1 retries #3
    { kind: 'delay', agent: 'sa-1', cause: 'tool', ms: 45_000, ref: 3 }, // 5 sa-1 delay caused by #3
    {
      kind: 'edit',
      tool: 'Write',
      agent: 'sa-1',
      targets: [{ file: 1, touch: 'edit', op: 'create' }],
    }, // 6 sa-1 creates file 1
    {
      kind: 'exec',
      tool: 'gh',
      verb: 'pr create',
      agent: 'sa-1',
      vcs: {
        provider: 'github',
        action: 'pr_create',
        repo: 'org/backend',
        number: 42,
      },
    }, // 7 sa-1 opens a PR
    {
      kind: 'edit',
      tool: 'Write',
      targets: [{ file: 2, touch: 'edit', op: 'modify' }],
    }, // 8 main touches file 2 (sa-1 never touches this file)
  ];
  const lensMap = makeMap(LENS_EVENTS, {
    prs: [
      {
        provider: 'github',
        repo: 'org/backend',
        number: 42,
        url: 'https://github.com/org/backend/pull/42',
        seq: 7,
      },
    ],
    files: [
      { id: 0, repo: 'r0', path: 'a.py' },
      { id: 1, repo: 'r0', path: 'b.py' },
      { id: 2, repo: 'r0', path: 'c.py' },
    ],
    agents: [
      { id: 'main', parent: null, kind: 'main', cost: 3, calls: 5 },
      {
        id: 'sa-1',
        parent: 'main',
        kind: 'subagent',
        subagentType: 'general-purpose',
        cost: 2,
        calls: 4,
      },
    ],
  });

  it('returns the full doc unchanged for "main"', () => {
    expect(deriveLensDoc(lensMap, 'main')).toBe(lensMap);
  });

  it('returns the full doc unchanged for an agent with no events of its own', () => {
    expect(deriveLensDoc(lensMap, 'nope')).toBe(lensMap);
  });

  it('reindexes events to a local 0-based sequence rebased at t=0', () => {
    const lens = deriveLensDoc(lensMap, 'sa-1');
    expect(lens.events.map((e) => e.seq)).toEqual([0, 1, 2, 3, 4]);
    expect(lens.events[0]?.t).toBe(0);
    expect(lens.events.map((e) => e.t)).toEqual([0, 1000, 2000, 3000, 4000]);
    expect(lens.events.every((e) => e.agent === 'main')).toBe(true);
  });

  it('remaps retryOf/ref to the new local sequence numbers', () => {
    const lens = deriveLensDoc(lensMap, 'sa-1');
    // event #4 (retryOf: 3) is local index 1; its retryOf must point at
    // local index 0 (the original #3), not the stale original seq.
    expect(lens.events[1]?.retryOf).toBe(0);
    // event #5 (ref: 3) is local index 2; same remap for `ref`.
    expect(lens.events[2]?.ref).toBe(0);
  });

  it('remaps retryOf/ref by original position even when events omit seq', () => {
    // `seq` is schema-optional; the remap must key off each event's own
    // position in `full.events`, not a `seq` field that may be absent.
    const noSeqMap = makeMap(
      LENS_EVENTS.map((e) => ({ ...e, seq: undefined })),
      {
        prs: lensMap.prs,
        files: lensMap.files,
        agents: lensMap.agents,
      }
    );
    expect(noSeqMap.events.every((e) => e.seq === undefined)).toBe(true);
    const lens = deriveLensDoc(noSeqMap, 'sa-1');
    expect(lens.events[1]?.retryOf).toBe(0);
    expect(lens.events[2]?.ref).toBe(0);
  });

  it("scopes totals to the lens's own events, not the full session", () => {
    const lens = deriveLensDoc(lensMap, 'sa-1');
    expect(lens.totals).toEqual(recomputeTotals(lens.events));
    expect(lens.totals.errors).toBe(1);
    expect(lens.totals.retries).toBe(1);
    expect(lens.totals.delays).toBe(1);
    expect(lens.totals.delayMs).toBe(45_000);
    expect(lens.totals.prsCreated).toBe(1);
    expect(lens.totals.filesCreated).toBe(1);
    expect(lens.totals.filesTouched).toBe(1);
    expect(lens.totals.subagents).toBe(0);
  });

  it('carries only PRs created within the lens, and derives its outcome', () => {
    const lens = deriveLensDoc(lensMap, 'sa-1');
    expect(lens.prs).toEqual(lensMap.prs);
    expect(lens.session.outcome).toBe('pr_created');
  });

  it('exposes itself as the sole "main" agent, with no further nesting', () => {
    const lens = deriveLensDoc(lensMap, 'sa-1');
    expect(lens.agents).toHaveLength(1);
    expect(lens.agents[0]?.id).toBe('main');
    expect(lens.agents[0]?.subagentType).toBe('general-purpose');
  });

  it(
    "does not leak the shared files[] aggregate into the lens's coverage " +
      "(file-touch counts must come from the lens's own " +
      'events, not the full-document file records)',
    () => {
      const lens = deriveLensDoc(lensMap, 'sa-1');
      // main's touches (file 0, file 2) must not appear; only file 1, which
      // sa-1 itself created.
      expect(fileCoverage(lens)).toEqual({ edited: 1, read: 0, seen: 0 });
    }
  );
});

describe('recomputeTotals', () => {
  it('computes calls/requests/errors/PRs/file-ops from a bare event list', () => {
    const events = sessionMapSchema.parse({
      schema: SESSION_MAP_SCHEMA_V1,
      session: { id: 'x', startedAt: '2026-01-01T00:00:00Z' },
      totals: {},
      files: [{ id: 0, repo: 'r0', path: 'a.py' }],
      events: [
        { seq: 0, t: 0, kind: 'user', agent: 'main', err: false, chars: 5 },
        {
          seq: 1,
          t: 100,
          kind: 'llm',
          agent: 'main',
          err: false,
          model: 'claude-opus-5',
          in: 10,
          out: 5,
          cost: 0.1,
          latency: 500,
        },
        {
          seq: 2,
          t: 200,
          kind: 'edit',
          agent: 'main',
          err: false,
          targets: [{ file: 0, touch: 'edit', op: 'create' }],
        },
        {
          seq: 3,
          t: 300,
          kind: 'error',
          agent: 'main',
          err: true,
          source: 'tool',
          errClass: 'timeout',
        },
        {
          seq: 4,
          t: 400,
          kind: 'exec',
          agent: 'main',
          err: false,
          tool: 'gh',
          vcs: { provider: 'github', action: 'pr_create', number: 1 },
        },
      ],
    }).events;
    const totals = recomputeTotals(events);
    expect(totals.calls).toBe(2); // edit + exec, not llm/user/error
    expect(totals.requests).toBe(1);
    expect(totals.errors).toBe(1);
    expect(totals.errorsBySource).toEqual({ tool: 1 });
    expect(totals.errorsByClass).toEqual({ timeout: 1 });
    expect(totals.prsCreated).toBe(1);
    expect(totals.filesCreated).toBe(1);
    expect(totals.filesTouched).toBe(1);
    expect(totals.subagents).toBe(0);
  });
});

describe('describeEvent for failed hooks', () => {
  const title = (e: Record<string, unknown>) => {
    const m = makeMap([{ ...e, kind: 'error', err: true, source: 'hook' }]);
    return describeEvent(m, m.events[0]).title;
  };

  it('names the hook and whether it blocked', () => {
    expect(title({ errClass: 'hook_error', hook: 'PostToolUse:Bash' })).toBe('PostToolUse:Bash hook error');
    expect(title({ errClass: 'hook_blocking', hook: 'Stop' })).toBe('Stop hook blocked');
    expect(title({ errClass: 'hook_error' })).toBe('Hook error');
  });
});

describe('shiftStartedAt', () => {
  it('moves a valid timestamp forward as ISO', () => {
    expect(shiftStartedAt('2026-09-10T01:00:00Z', 6000)).toBe(
      '2026-09-10T01:00:06.000Z'
    );
  });

  it('returns an unparseable timestamp unchanged instead of throwing', () => {
    expect(shiftStartedAt('not a date', 6000)).toBe('not a date');
    expect(shiftStartedAt('', 0)).toBe('');
  });
});