/** * Domain/business entity types for claude-devtools. * * These types represent the application's domain model: * - Projects and sessions * - Repository and worktree grouping * - Search and pagination * - Token usage and metrics */ import { type UsageMetadata } from './jsonl'; // =============================================================================// Application-Specific Type Aliases// ============================================================================= /** * Token usage statistics (alias for API compatibility). * Maps to UsageMetadata from the spec. */export type TokenUsage = UsageMetadata; /** * Message type classification for parsed messages. */export type MessageType =  | 'user'  | 'assistant'  | 'system'  | 'summary'  | 'file-history-snapshot'  | 'queue-operation'; /** * Message category for chunk building. * Used to classify messages into one of four categories for independent chunk creation. */export type MessageCategory = 'user' | 'system' | 'hardNoise' | 'ai' | 'compact'; // =============================================================================// Project & Session Types// ============================================================================= /** * Project information derived from ~/.claude/projects/ directory. */export interface Project {  /** Encoded directory name (e.g., "-Users-username-projectname") */  id: string;  /** Decoded actual filesystem path */  path: string;  /** Display name (last path segment) */  name: string;  /** List of session IDs (JSONL filenames without extension) */  sessions: string[];  /** Unix timestamp when project directory was created */  createdAt: number;  /** Unix timestamp of most recent session activity */  mostRecentSession?: number;} /** * Session metadata and summary. */export type SessionMetadataLevel = 'light' | 'deep'; /** * Per-phase token breakdown for compaction-aware context consumption. */export interface PhaseTokenBreakdown {  /** 1-based phase number */  phaseNumber: number;  /** Tokens added during this phase */  contribution: number;  /** Context window at peak (pre-compaction or final) */  peakTokens: number;  /** Tokens after compaction (undefined for the last/current phase) */  postCompaction?: number;} export interface Session {  /** Session UUID (JSONL filename without extension) */  id: string;  /** Parent project ID */  projectId: string;  /** Project filesystem path */  projectPath: string;  /** Task list data from ~/.claude/todos/{id}.json if exists */  todoData?: unknown;  /** Unix timestamp when session file was created */  createdAt: number;  /** First user message text (for preview) */  firstMessage?: string;  /** Timestamp of first user message (RFC3339) */  messageTimestamp?: string;  /** Whether this session has subagents */  hasSubagents: boolean;  /** Total message count in the session */  messageCount: number;  /** Whether the session is ongoing (last AI response has no output yet) */  isOngoing?: boolean;  /** Git branch name if available */  gitBranch?: string;  /** Metadata completeness level */  metadataLevel?: SessionMetadataLevel;  /** Total context consumed (compaction-aware sum of all phases) */  contextConsumption?: number;  /** Number of compaction events */  compactionCount?: number;  /** Per-phase token breakdown for tooltip display */  phaseBreakdown?: PhaseTokenBreakdown[];} /** * Aggregated metrics for a session or chunk. */export interface SessionMetrics {  /** Duration in milliseconds */  durationMs: number;  /** Total tokens (input + output) */  totalTokens: number;  /** Input tokens */  inputTokens: number;  /** Output tokens */  outputTokens: number;  /** Cache read tokens */  cacheReadTokens: number;  /** Cache creation tokens */  cacheCreationTokens: number;  /** Number of messages */  messageCount: number;  /** Estimated cost in USD */  costUsd?: number;} // =============================================================================// Repository & Worktree Grouping Types// ============================================================================= /** * Worktree source identifies how/where the worktree was created. * Used for badge display and source-specific naming strategies. */export type WorktreeSource =  | 'vibe-kanban' // /tmp/vibe-kanban/worktrees/{issue-branch}/{repo}  | 'conductor' // /Users/.../conductor/workspaces/{repo}/{workspace}  | 'auto-claude' // /Users/.../.auto-claude/worktrees/tasks/{task-id}  | '21st' // /Users/.../.21st/worktrees/{id}/{name [bracket-id]}  | 'claude-desktop' // /Users/.../.claude-worktrees/{repo}/{name}  | 'ccswitch' // /Users/.../.ccswitch/worktrees/{repo}/{name}  | 'git' // Standard git worktree (main repo or detached)  | 'unknown'; // Non-git project or undetectable /** * Git repository identity for grouping worktrees. * Multiple projects (worktrees) can share the same RepositoryIdentity. */export interface RepositoryIdentity {  /** Unique identifier - hash of remote URL or main repo path */  id: string;  /** Git remote URL if available (e.g., "https://github.com/org/repo.git") */  remoteUrl?: string;  /** Path to the main git directory (e.g., "/Users/username/projectname/.git") */  mainGitDir: string;  /** Display name for the repository (e.g., "projectname") */  name: string;} /** * A worktree represents a single working directory of a git repository. * In the grouped view, projects become worktrees under a RepositoryGroup. */export interface Worktree {  /** Encoded directory name (same as Project.id) */  id: string;  /** Decoded actual filesystem path */  path: string;  /** Display name (worktree-specific, e.g., branch name or "main") */  name: string;  /** Git branch name if available */  gitBranch?: string;  /** Whether this is the main worktree (not a detached worktree) */  isMainWorktree: boolean;  /** Worktree source for badge display (vibe-kanban, conductor, etc.) */  source: WorktreeSource;  /** List of session IDs */  sessions: string[];  /** Unix timestamp when first session was created */  createdAt: number;  /** Unix timestamp of most recent session activity */  mostRecentSession?: number;} /** * A repository group contains all worktrees of a single git repository. * This is the top-level entity when worktree grouping is enabled. * Non-git projects are represented as single-worktree RepositoryGroups. */export interface RepositoryGroup {  /** Unique identifier from RepositoryIdentity.id (or project.id for non-git) */  id: string;  /** Repository identity information (null for non-git projects) */  identity: RepositoryIdentity | null;  /** All worktrees of this repository */  worktrees: Worktree[];  /** Display name (derived from repo name) */  name: string;  /** Unix timestamp of most recent session across all worktrees */  mostRecentSession?: number;  /** Total session count across all worktrees */  totalSessions: number;} // =============================================================================// Search Types// ============================================================================= /** * A single search result from searching sessions. */export interface SearchResult {  /** Session ID where match was found */  sessionId: string;  /** Project ID */  projectId: string;  /** Session title/first message */  sessionTitle: string;  /** The matched text (trimmed) */  matchedText: string;  /** Context around the match */  context: string;  /** Message type (user/assistant) */  messageType: 'user' | 'assistant';  /** Timestamp of the message */  timestamp: number;  /** Stable chat group ID used by in-session navigation (e.g., "user-..." or "ai-...") */  groupId?: string;  /** Searchable item type used for in-session matching */  itemType?: 'user' | 'ai';  /** Match index within the item's searchable text (0-based) */  matchIndexInItem?: number;  /** Character offset of the match within the searchable text */  matchStartOffset?: number;  /** Source message UUID for diagnostics/fallback mapping */  messageUuid?: string;} /** * Result of a search operation. */export interface SearchSessionsResult {  /** Search results */  results: SearchResult[];  /** Total matches found */  totalMatches: number;  /** Sessions searched */  sessionsSearched: number;  /** Search query used */  query: string;  /** True when fast mode intentionally returns only a recent subset */  isPartial?: boolean;} // =============================================================================// Pagination Types// ============================================================================= /** * Cursor for session pagination. * Uses timestamp + sessionId as a composite cursor for stable pagination. */export interface SessionCursor {  /** Unix timestamp (birthtimeMs) of the session file */  timestamp: number;  /** Session ID for tie-breaking when timestamps are equal */  sessionId: string;} /** * Result of paginated session listing. */export interface PaginatedSessionsResult {  /** Sessions for this page */  sessions: Session[];  /** Cursor for next page (null if no more pages) */  nextCursor: string | null;  /** Whether there are more sessions to load */  hasMore: boolean;  /** Total count of sessions (for display purposes) */  totalCount: number;} /** * Options controlling paginated session listing behavior. */export interface SessionsPaginationOptions {  /**   * Whether to compute an accurate totalCount by scanning all sessions.   * Disable for faster background refreshes.   * @default true   */  includeTotalCount?: boolean;  /**   * Whether to pre-filter all session files before paging.   * Disable for faster top-of-list refreshes.   * @default true   */  prefilterAll?: boolean;  /**   * Metadata depth to return for listed sessions.   * - light: filesystem metadata only (fast)   * - deep: includes parsed session content summary fields (slower)   * @default 'deep'   */  metadataLevel?: SessionMetadataLevel;} /** * Options for targeted session fetches by session ID. */export interface SessionsByIdsOptions {  /**   * Metadata depth to return for each session.   * - light: fast preview fields suitable for list/sidebar   * - deep: full summary metadata (slower)   * @default provider-specific default (SSH=light, local=deep)   */  metadataLevel?: SessionMetadataLevel;}