@claude-sessions/core 0.3.7 → 0.4.1-beta.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MessagePayload, a as Message, P as Project, T as TodoItem, F as FileChange, C as CompressSessionOptions, S as SummarizeSessionOptions, b as ConversationLine, c as MoveSessionResult, d as SearchResult, e as SummaryInfo, A as AgentInfo } from './types-Cz8chaYQ.js';
-export { l as CleanupPreview, k as ClearSessionsResult, s as CompressSessionResult, f as ContentItem, D as DeleteSessionResult, t as ProjectKnowledge, n as ProjectTreeData, R as RenameSessionResult, o as ResumeSessionOptions, p as ResumeSessionResult, r as SessionAnalysis, i as SessionFilesSummary, g as SessionMeta, h as SessionTodos, m as SessionTreeData, j as SplitSessionResult, u as SummarizeSessionResult, q as ToolUsageStats } from './types-Cz8chaYQ.js';
+import { P as Project, M as MessagePayload$1, a as Message, S as SummaryInfo, b as SessionTodos, c as MoveSessionResult, A as AgentInfo, d as SessionSortOptions, e as ProjectTreeData, C as CompressSessionOptions, f as SummarizeSessionOptions, g as ConversationLine, h as SearchResult, F as FileChange, i as SessionsIndex, j as SessionIndexEntry } from './types-mWa378iC.js';
+export { p as CleanupPreview, o as ClearSessionsResult, v as CompressSessionResult, k as ContentItem, D as DeleteSessionResult, w as ProjectKnowledge, R as RenameSessionResult, r as ResumeSessionOptions, s as ResumeSessionResult, u as SessionAnalysis, m as SessionFilesSummary, l as SessionMeta, y as SessionSortField, z as SessionSortOrder, q as SessionTreeData, n as SplitSessionResult, x as SummarizeSessionResult, T as TodoItem, t as ToolUsageStats } from './types-mWa378iC.js';
 import * as effect_Cause from 'effect/Cause';
 import { Effect } from 'effect';
 
@@ -59,16 +59,37 @@ declare const folderNameToPath: (folderName: string) => string;
 declare const findProjectByWorkspacePath: (workspacePath: string, projectNames: string[], sessionsDir?: string, fileSystem?: FileSystem, logger?: Logger$1) => string | null;
 
 /**
- * Utility functions for message processing
+ * Project-level utilities
  */
 
-declare const extractTextContent: (message: MessagePayload | undefined) => string;
+/**
+ * Sort projects with priority:
+ * 1. Current project (if specified)
+ * 2. Current user's home directory subpaths
+ * 3. Others (alphabetically by displayName)
+ */
+declare const sortProjects: (projects: Project[], options?: {
+    currentProjectName?: string | null;
+    homeDir?: string;
+    filterEmpty?: boolean;
+}) => Project[];
+
+declare const extractTextContent: (message: MessagePayload$1 | undefined) => string;
+/**
+ * Parse command message content (e.g., slash commands like /commit)
+ * Returns the command name and message extracted from XML tags
+ */
+declare const parseCommandMessage: (content?: string) => {
+    name: string;
+    message: string;
+};
 declare const extractTitle: (text: string) => string;
 declare const isInvalidApiKeyMessage: (msg: Message) => boolean;
 declare const isContinuationSummary: (msg: Message) => boolean;
 /**
  * Get display title with fallback logic
  * Priority: customTitle > currentSummary (truncated) > title > fallback
+ * Also handles slash command format in title
  */
 declare const getDisplayTitle: (customTitle: string | undefined, currentSummary: string | undefined, title: string | undefined, maxLength?: number, fallback?: string) => string;
 /**
@@ -77,16 +98,28 @@ declare const getDisplayTitle: (customTitle: string | undefined, currentSummary:
  */
 declare const maskHomePath: (text: string, homeDir: string) => string;
 /**
- * Sort projects with priority:
- * 1. Current project (if specified)
- * 2. Current user's home directory subpaths
- * 3. Others (alphabetically by displayName)
+ * Get sort timestamp for session (Unix timestamp ms)
+ * Priority: summaries[0].timestamp > createdAt > 0
  */
-declare const sortProjects: (projects: Project[], options?: {
-    currentProjectName?: string | null;
-    homeDir?: string;
-    filterEmpty?: boolean;
-}) => Project[];
+declare const getSessionSortTimestamp: (session: {
+    summaries?: SummaryInfo[];
+    createdAt?: string;
+}) => number;
+/**
+ * Try to parse a single JSON line, returning null on failure with optional warning log
+ * Use this when you want to skip invalid lines instead of throwing
+ */
+declare const tryParseJsonLine: <T = Record<string, unknown>>(line: string, lineNumber: number, filePath?: string) => T | null;
+/**
+ * Parse JSONL lines with detailed error messages including file path and line number
+ * @throws Error with "Failed to parse line X in /path/to/file: original error"
+ */
+declare const parseJsonlLines: <T = Record<string, unknown>>(lines: string[], filePath: string) => T[];
+/**
+ * Read and parse JSONL file (Effect wrapper)
+ * Combines file reading and JSONL parsing with proper error messages
+ */
+declare const readJsonlFile: <T = Record<string, unknown>>(filePath: string) => Effect.Effect<T[], effect_Cause.UnknownException, never>;
 
 declare const findLinkedAgents: (projectName: string, sessionId: string) => Effect.Effect<string[], effect_Cause.UnknownException, never>;
 declare const findOrphanAgents: (projectName: string) => Effect.Effect<{
@@ -106,15 +139,7 @@ declare const deleteOrphanAgents: (projectName: string) => Effect.Effect<{
 declare const loadAgentMessages: (projectName: string, _sessionId: string, // Reserved for future validation
 agentId: string) => Effect.Effect<Message[], effect_Cause.UnknownException, never>;
 
-declare const findLinkedTodos: (sessionId: string, agentIds?: string[]) => Effect.Effect<{
-    sessionId: string;
-    sessionTodos: TodoItem[];
-    agentTodos: {
-        agentId: string;
-        todos: TodoItem[];
-    }[];
-    hasTodos: boolean;
-}, effect_Cause.UnknownException, never>;
+declare const findLinkedTodos: (sessionId: string, agentIds?: string[]) => Effect.Effect<SessionTodos, effect_Cause.UnknownException, never>;
 declare const sessionHasTodos: (sessionId: string, agentIds?: string[]) => Effect.Effect<boolean, effect_Cause.UnknownException, never>;
 declare const deleteLinkedTodos: (sessionId: string, agentIds: string[]) => Effect.Effect<{
     deletedCount: number;
@@ -126,16 +151,22 @@ declare const deleteOrphanTodos: () => Effect.Effect<{
 }, effect_Cause.UnknownException, never>;
 
 declare const listProjects: Effect.Effect<Project[], effect_Cause.UnknownException, never>;
+
+declare const updateSessionSummary: (projectName: string, sessionId: string, newSummary: string) => Effect.Effect<{
+    success: boolean;
+}, effect_Cause.UnknownException, never>;
 declare const listSessions: (projectName: string) => Effect.Effect<{
     id: string;
     projectName: string;
     title: string;
+    customTitle: string | undefined;
+    currentSummary: string | undefined;
     messageCount: number;
     createdAt: string | undefined;
     updatedAt: string | undefined;
 }[], effect_Cause.UnknownException, never>;
 declare const readSession: (projectName: string, sessionId: string) => Effect.Effect<Message[], effect_Cause.UnknownException, never>;
-declare const deleteMessage: (projectName: string, sessionId: string, messageUuid: string) => Effect.Effect<{
+declare const deleteMessage: (projectName: string, sessionId: string, messageUuid: string, targetType?: "file-history-snapshot" | "summary") => Effect.Effect<{
     success: boolean;
     error: string;
     deletedMessage?: undefined;
@@ -169,12 +200,41 @@ declare const renameSession: (projectName: string, sessionId: string, newTitle:
     success: true;
     error?: undefined;
 }, effect_Cause.UnknownException, never>;
-declare const getSessionFiles: (projectName: string, sessionId: string) => Effect.Effect<{
-    sessionId: string;
+declare const moveSession: (sourceProject: string, sessionId: string, targetProject: string) => Effect.Effect<MoveSessionResult, Error>;
+declare const splitSession: (projectName: string, sessionId: string, splitAtMessageUuid: string) => Effect.Effect<{
+    success: false;
+    error: string;
+    newSessionId?: undefined;
+    newSessionPath?: undefined;
+    movedMessageCount?: undefined;
+    duplicatedSummary?: undefined;
+} | {
+    success: true;
+    newSessionId: `${string}-${string}-${string}-${string}-${string}`;
+    newSessionPath: string;
+    movedMessageCount: number;
+    duplicatedSummary: boolean;
+    error?: undefined;
+}, effect_Cause.UnknownException, never>;
+
+declare const loadSessionTreeData: (projectName: string, sessionId: string) => Effect.Effect<{
+    id: string;
     projectName: string;
-    files: FileChange[];
-    totalChanges: number;
+    title: string;
+    customTitle: string | undefined;
+    currentSummary: string;
+    messageCount: number;
+    createdAt: string;
+    updatedAt: string;
+    fileMtime: number | undefined;
+    sortTimestamp: number;
+    summaries: SummaryInfo[];
+    agents: AgentInfo[];
+    todos: SessionTodos;
+    lastCompactBoundaryUuid: string | undefined;
 }, effect_Cause.UnknownException, never>;
+declare const loadProjectTreeData: (projectName: string, sortOptions?: SessionSortOptions) => Effect.Effect<ProjectTreeData | null, effect_Cause.UnknownException, never>;
+
 declare const analyzeSession: (projectName: string, sessionId: string) => Effect.Effect<{
     sessionId: string;
     projectName: string;
@@ -203,28 +263,46 @@ declare const analyzeSession: (projectName: string, sessionId: string) => Effect
         messageUuid?: string;
     }[];
 }, effect_Cause.UnknownException, never>;
-declare const moveSession: (sourceProject: string, sessionId: string, targetProject: string) => Effect.Effect<MoveSessionResult, Error>;
-declare const splitSession: (projectName: string, sessionId: string, splitAtMessageUuid: string) => Effect.Effect<{
-    success: false;
-    error: string;
-    newSessionId?: undefined;
-    newSessionPath?: undefined;
-    movedMessageCount?: undefined;
-    duplicatedSummary?: undefined;
-} | {
+declare const compressSession: (projectName: string, sessionId: string, options?: CompressSessionOptions) => Effect.Effect<{
     success: true;
-    newSessionId: `${string}-${string}-${string}-${string}-${string}`;
-    newSessionPath: string;
-    movedMessageCount: number;
-    duplicatedSummary: boolean;
-    error?: undefined;
+    originalSize: number;
+    compressedSize: number;
+    removedSnapshots: number;
+    truncatedOutputs: number;
+}, effect_Cause.UnknownException, never>;
+declare const extractProjectKnowledge: (projectName: string, sessionIds?: string[]) => Effect.Effect<{
+    projectName: string;
+    patterns: never[];
+    hotFiles: {
+        path: string;
+        modifyCount: number;
+        lastModified: string | undefined;
+    }[];
+    workflows: {
+        sequence: string[];
+        count: number;
+    }[];
+    decisions: {
+        context: string;
+        decision: string;
+        sessionId: string;
+    }[];
+}, effect_Cause.UnknownException, never>;
+declare const summarizeSession: (projectName: string, sessionId: string, options?: SummarizeSessionOptions) => Effect.Effect<{
+    sessionId: string;
+    projectName: string;
+    lines: ConversationLine[];
+    formatted: string;
 }, effect_Cause.UnknownException, never>;
+
 declare const previewCleanup: (projectName?: string) => Effect.Effect<{
     project: string;
     emptySessions: {
         id: string;
         projectName: string;
         title: string;
+        customTitle: string | undefined;
+        currentSummary: string | undefined;
         messageCount: number;
         createdAt: string | undefined;
         updatedAt: string | undefined;
@@ -233,6 +311,8 @@ declare const previewCleanup: (projectName?: string) => Effect.Effect<{
         id: string;
         projectName: string;
         title: string;
+        customTitle: string | undefined;
+        currentSummary: string | undefined;
         messageCount: number;
         createdAt: string | undefined;
         updatedAt: string | undefined;
@@ -255,95 +335,113 @@ declare const clearSessions: (options: {
     deletedOrphanAgentCount: number;
     deletedOrphanTodoCount: number;
 }, effect_Cause.UnknownException, never>;
+
 declare const searchSessions: (query: string, options?: {
     projectName?: string;
     searchContent?: boolean;
-}) => Effect.Effect<SearchResult[], effect_Cause.UnknownException, never>;
-declare const loadSessionTreeData: (projectName: string, sessionId: string) => Effect.Effect<{
-    id: string;
+}) => Effect.Effect<(SearchResult | {
+    sessionId: string;
     projectName: string;
     title: string;
-    customTitle: string | undefined;
-    currentSummary: string;
-    messageCount: number;
-    createdAt: string;
-    updatedAt: string;
-    summaries: SummaryInfo[];
-    agents: AgentInfo[];
-    todos: {
-        sessionId: string;
-        sessionTodos: TodoItem[];
-        agentTodos: {
-            agentId: string;
-            todos: TodoItem[];
-        }[];
-        hasTodos: boolean;
-    };
-    lastCompactBoundaryUuid: string | undefined;
-}, effect_Cause.UnknownException, never>;
-declare const loadProjectTreeData: (projectName: string) => Effect.Effect<{
-    name: string;
-    displayName: string;
-    path: string;
-    sessionCount: number;
-    sessions: {
-        id: string;
-        projectName: string;
-        title: string;
-        customTitle: string | undefined;
-        currentSummary: string;
-        messageCount: number;
-        createdAt: string;
-        updatedAt: string;
-        summaries: SummaryInfo[];
-        agents: AgentInfo[];
-        todos: {
-            sessionId: string;
-            sessionTodos: TodoItem[];
-            agentTodos: {
-                agentId: string;
-                todos: TodoItem[];
-            }[];
-            hasTodos: boolean;
-        };
-        lastCompactBoundaryUuid: string | undefined;
-    }[];
-} | null, effect_Cause.UnknownException, never>;
-declare const updateSessionSummary: (projectName: string, sessionId: string, newSummary: string) => Effect.Effect<{
-    success: boolean;
-}, effect_Cause.UnknownException, never>;
-declare const compressSession: (projectName: string, sessionId: string, options?: CompressSessionOptions) => Effect.Effect<{
-    success: true;
-    originalSize: number;
-    compressedSize: number;
-    removedSnapshots: number;
-    truncatedOutputs: number;
-}, effect_Cause.UnknownException, never>;
-declare const extractProjectKnowledge: (projectName: string, sessionIds?: string[]) => Effect.Effect<{
-    projectName: string;
-    patterns: never[];
-    hotFiles: {
-        path: string;
-        modifyCount: number;
-        lastModified: string | undefined;
-    }[];
-    workflows: {
-        sequence: string[];
-        count: number;
-    }[];
-    decisions: {
-        context: string;
-        decision: string;
-        sessionId: string;
-    }[];
-}, effect_Cause.UnknownException, never>;
-declare const summarizeSession: (projectName: string, sessionId: string, options?: SummarizeSessionOptions) => Effect.Effect<{
+    matchType: "title";
+    timestamp: string | undefined;
+})[], effect_Cause.UnknownException, never>;
+
+declare const getSessionFiles: (projectName: string, sessionId: string) => Effect.Effect<{
     sessionId: string;
     projectName: string;
-    lines: ConversationLine[];
-    formatted: string;
+    files: FileChange[];
+    totalChanges: number;
 }, effect_Cause.UnknownException, never>;
 
+/**
+ * Session message chain validation utilities
+ *
+ * Validates:
+ * 1. parentUuid chain integrity (skip file-history-snapshot)
+ * 2. tool_use_id / tool_result matching
+ */
+interface ChainError {
+    type: 'broken_chain' | 'orphan_parent';
+    uuid: string;
+    line: number;
+    parentUuid: string | null;
+    expectedParent?: string;
+}
+interface ToolUseResultError {
+    type: 'orphan_tool_result';
+    uuid: string;
+    line: number;
+    toolUseId: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: (ChainError | ToolUseResultError)[];
+}
+interface MessagePayload {
+    role?: string;
+    content?: unknown;
+}
+interface GenericMessage {
+    type?: string;
+    uuid?: string;
+    parentUuid?: string | null;
+    message?: MessagePayload;
+    messageId?: string;
+}
+/**
+ * Validate parentUuid chain for messages
+ *
+ * Rules:
+ * - Skip file-history-snapshot type (has no uuid, uses messageId instead)
+ * - Skip messages without uuid
+ * - First message can have null parentUuid
+ * - Subsequent messages must have valid parentUuid pointing to existing uuid
+ */
+declare function validateChain(messages: readonly GenericMessage[]): ValidationResult;
+/**
+ * Validate tool_use_id / tool_result matching
+ *
+ * Rules:
+ * - All tool_result blocks must have a corresponding tool_use block in the session
+ * - tool_use blocks are collected from all messages (not just previous)
+ */
+declare function validateToolUseResult(messages: readonly GenericMessage[]): ValidationResult;
+/**
+ * Delete a message and repair the parentUuid chain
+ *
+ * This is a pure function for client-side use (without file I/O)
+ * Server-side deleteMessage in crud.ts uses similar logic with file operations
+ *
+ * @param messages - Array of messages (will be mutated)
+ * @param targetId - uuid, messageId, or leafUuid of message to delete
+ * @param targetType - Optional: 'file-history-snapshot' or 'summary' to disambiguate collisions
+ * @returns Object with deleted message and messages to also delete (orphan tool_results)
+ */
+declare function deleteMessageWithChainRepair<T extends GenericMessage>(messages: T[], targetId: string, targetType?: 'file-history-snapshot' | 'summary'): {
+    deleted: T | null;
+    alsoDeleted: T[];
+};
+
+/**
+ * Load sessions-index.json for a project
+ * Returns null if the file doesn't exist
+ */
+declare const loadSessionsIndex: (projectName: string) => Effect.Effect<SessionsIndex | null, effect_Cause.UnknownException, never>;
+/**
+ * Get display title from index entry
+ * Priority: customTitle > summary > firstPrompt (cleaned)
+ */
+declare const getIndexEntryDisplayTitle: (entry: SessionIndexEntry) => string;
+/**
+ * Sort index entries by modified time (newest first)
+ */
+declare const sortIndexEntriesByModified: (entries: SessionIndexEntry[]) => SessionIndexEntry[];
+/**
+ * Check if sessions-index.json exists for a project
+ */
+declare const hasSessionsIndex: (projectName: string) => Effect.Effect<boolean, effect_Cause.UnknownException, never>;
+
 /**
  * Simple logger abstraction for Claude Sessions
  * Consumers can provide their own logger implementation
@@ -378,4 +476,4 @@ declare const getLogger: () => Logger;
  */
 declare const createLogger: (namespace: string) => Logger;
 
-export { AgentInfo, CompressSessionOptions, ConversationLine, FileChange, type Logger, Message, MessagePayload, MoveSessionResult, Project, SearchResult, SummarizeSessionOptions, SummaryInfo, TodoItem, analyzeSession, clearSessions, compressSession, createLogger, deleteLinkedTodos, deleteMessage, deleteOrphanAgents, deleteOrphanTodos, deleteSession, displayPathToFolderName, extractProjectKnowledge, extractTextContent, extractTitle, findLinkedAgents, findLinkedTodos, findOrphanAgents, findOrphanTodos, findProjectByWorkspacePath, folderNameToDisplayPath, folderNameToPath, getDisplayTitle, getLogger, getRealPathFromSession, getSessionFiles, getSessionsDir, getTodosDir, isContinuationSummary, isInvalidApiKeyMessage, listProjects, listSessions, loadAgentMessages, loadProjectTreeData, loadSessionTreeData, maskHomePath, moveSession, pathToFolderName, previewCleanup, readSession, renameSession, restoreMessage, searchSessions, sessionHasTodos, setLogger, sortProjects, splitSession, summarizeSession, updateSessionSummary };
+export { AgentInfo, type ChainError, CompressSessionOptions, ConversationLine, FileChange, type Logger, Message, MessagePayload$1 as MessagePayload, MoveSessionResult, Project, ProjectTreeData, SearchResult, SessionIndexEntry, SessionSortOptions, SessionTodos, SessionsIndex, SummarizeSessionOptions, SummaryInfo, type ToolUseResultError, type ValidationResult, analyzeSession, clearSessions, compressSession, createLogger, deleteLinkedTodos, deleteMessage, deleteMessageWithChainRepair, deleteOrphanAgents, deleteOrphanTodos, deleteSession, displayPathToFolderName, extractProjectKnowledge, extractTextContent, extractTitle, findLinkedAgents, findLinkedTodos, findOrphanAgents, findOrphanTodos, findProjectByWorkspacePath, folderNameToDisplayPath, folderNameToPath, getDisplayTitle, getIndexEntryDisplayTitle, getLogger, getRealPathFromSession, getSessionFiles, getSessionSortTimestamp, getSessionsDir, getTodosDir, hasSessionsIndex, isContinuationSummary, isInvalidApiKeyMessage, listProjects, listSessions, loadAgentMessages, loadProjectTreeData, loadSessionTreeData, loadSessionsIndex, maskHomePath, moveSession, parseCommandMessage, parseJsonlLines, pathToFolderName, previewCleanup, readJsonlFile, readSession, renameSession, restoreMessage, searchSessions, sessionHasTodos, setLogger, sortIndexEntriesByModified, sortProjects, splitSession, summarizeSession, tryParseJsonLine, updateSessionSummary, validateChain, validateToolUseResult };