feat(cli): Cursor scanner with multi-format token extraction

[adamhenson]

Summary

• Implements the Cursor scanner reading agent sessions from Cursor's global SQLite DB (state.vscdb)
• Handles all three token storage formats Cursor has used across versions:
  • agentKv:bubbleCheckpoint:* (mid-era, protobuf): batched in 2 queries, decodes context tokens + model name
  • bubbleId:* JSON tokenCount (older): per-session BETWEEN range scans (B-tree indexed; LIKE was ~1s/session × 211 sessions = timeout)
  • composerData.contextTokensUsed (newest): final context-window size as fallback
• Covers ~139 of 211 agent sessions locally (72 have no local token data)
• All Cursor tokens marked isApproximate: true (subscription-based, no exact API billing data)
• Adds isApproximate field to TokensSchema and threads it through api.ts
• Mocks CursorScanner in sync tests to prevent hitting real Cursor data during CI
• Bumps tsup target to node22 for node:sqlite support

Test plan

• pnpm typecheck passes
• pnpm test passes (29 tests)
• node dist/index.js sync --dry-run --engine cursor returns sessions without timeout
• launchctl restart picks up new scanner and syncs Cursor sessions to dashboard

[github-actions]

Review: feat(cli): Cursor scanner with multi-format token extraction

The core scanner logic is well-structured: Zod schemas for all external data shapes, defensive parsing throughout, try/catch on every DB call, proper finally on globalDb.close(), noUncheckedIndexedAccess handled correctly across all array/map accesses. The protobuf decoder handles malformed input gracefully and the batch query approach to avoid LIKE per-session scans is the right call.

Two issues worth addressing:

Important — no unit tests for CursorScanner: 560+ lines of new code with zero test coverage. __tests__/scanners/ only has claude.test.ts. The pure functions (decodeBubbleCheckpoint, normalizeCursorModel) and _scanWithDb are the right starting points — see the inline comment for a sketch.

Notable — systemd ExecStart unescaped: programArgs.join(' ') breaks for paths with spaces; the plist version correctly isolates args in <string> tags. Low-probability but worth fixing for consistency.

No any types, no unhandled exceptions, no security issues found.

Generated by Agent: Code Review for issue #1 · ● 250.2K

[github-actions]

Missing unit tests for CursorScanner

This PR adds 560+ lines of new scanner logic — protobuf decoding, three distinct token storage formats, model name normalization — but there's no cursor.test.ts (the __tests__/scanners/ directory only has claude.test.ts). The sync tests mock out CursorScanner entirely, so nothing exercises the real paths.

decodeBubbleCheckpoint and normalizeCursorModel are pure functions that can be tested directly with hex fixtures:

// __tests__/scanners/cursor.test.ts
import { describe, it, expect } from 'vitest';

describe('normalizeCursorModel', () => {
  it('converts Cursor claude naming to AgentMeter format', () => {
    expect(normalizeCursorModel('claude-4.5-sonnet')).toBe('claude-sonnet-4-5');
    expect(normalizeCursorModel('claude-3.7-sonnet-thinking')).toBe('claude-sonnet-3-7');
    expect(normalizeCursorModel('gpt-4o-high')).toBe('gpt-4o');
    expect(normalizeCursorModel('unknown-model')).toBe('unknown-model');
  });
});

describe('decodeBubbleCheckpoint', () => {
  it('returns nulls for an empty/malformed hex string', () => {
    expect(decodeBubbleCheckpoint('')).toEqual({ modelName: null, contextTokens: null });
    expect(decodeBubbleCheckpoint('not-hex')).toEqual({ modelName: null, contextTokens: null });
  });
});

_scanWithDb can be tested by mocking node:sqlite (via vi.mock('node:sqlite', ...)) and passing a DatabaseSync-shaped stub. The project pattern for this kind of thing is in claude.test.ts.

[github-actions]

ExecStart breaks for paths containing spaces

programArgs.join(' ') produces a malformed systemd unit if any path component has a space. The macOS plist version handles this correctly — each arg is wrapped in its own <string> element. The Linux path doesn't get that protection.

which tsx can return paths like /home/user name/.nvm/versions/node/v22/bin/tsx on some systems, and the tsx shell wrapper itself can live in a directory with spaces.

Fix: quote args that contain spaces:

const escapedArgs = programArgs
  .map((a) => (a.includes(' ') ? `"\$\{a}"` : a))
  .join(' ');
// ExecStart=\$\{escapedArgs}

Same consideration applies to the Environment= lines if config.apiUrl were ever set to a URL with a space (unlikely but the plist escapes these with escapeXml, so it's worth being consistent).