om-memory-system 3.5.0 → 3.6.0-next.38

package/dist/importer/claude-hook-api.js

@@ -0,0 +1,441 @@
+import { readFile } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { CONFIG, refreshConfigIfChanged } from "../config.js";
+import { captureConversation } from "../core/capture.js";
+import { classifyCaptureFailure, quickRetryDelayMs } from "../core/capture-retry-policy.js";
+import { buildRecentMemoriesSection, buildRetrievalSection, formatMemoriesForCompaction, stripRetrievalSections, wrapRetrievalSection, } from "../core/retrieval.js";
+import { resolveClaudeCodeLiveModel } from "../services/ai/live-model-choice.js";
+import { captureFailureOf, drainCaptureRetries, queueFailedCapture, registerCaptureRetryDrain, startCaptureRetryDrain, } from "../services/capture-retry-drain.js";
+import { readClaudeCaptureCursor, writeClaudeCaptureCursor, } from "../services/claude-capture-cursor.js";
+import { memoryClient } from "../services/client.js";
+import { log } from "../services/logger.js";
+import { isFullyPrivate, stripPrivateContent } from "../services/privacy.js";
+import { getTags } from "../services/tags.js";
+import { extractClaudeWindowsAfter, parseClaudeTranscript, } from "./claude-conversation.js";
+// The web app's side of the Claude Code hooks (design decisions 4, 6, 7):
+// retrieval for SessionStart and UserPromptSubmit, a one-worker capture queue
+// for Stop, profile learning, and the once-per-process backfill start. Logs
+// carry event names, session ids, counts, sizes, and codes; never text.
+const HOST = "claude-code";
+/** A hook request the handler cannot use. `status` is the HTTP status. */
+export class ClaudeHookRequestError extends Error {
+    status = 400;
+    constructor(message) {
+        super(message);
+        this.name = "ClaudeHookRequestError";
+    }
+}
+function objectBody(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+        throw new ClaudeHookRequestError("A JSON object is required");
+    }
+    return body;
+}
+function sessionAndCwd(body) {
+    const { session_id: sessionId, cwd } = body;
+    if (typeof sessionId !== "string" || !sessionId.trim()) {
+        throw new ClaudeHookRequestError("session_id is required");
+    }
+    if (typeof cwd !== "string" || !isAbsolute(cwd)) {
+        throw new ClaudeHookRequestError("cwd must be an absolute path");
+    }
+    return { sessionId, cwd };
+}
+function optionalString(body, key) {
+    const value = body[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new ClaudeHookRequestError(`${key} must be a string`);
+    return value;
+}
+function parseRetrieveRequest(body) {
+    const input = objectBody(body);
+    if (input.event !== "session-start" && input.event !== "user-prompt-submit") {
+        throw new ClaudeHookRequestError("event must be session-start or user-prompt-submit");
+    }
+    return {
+        event: input.event,
+        ...sessionAndCwd(input),
+        source: optionalString(input, "source"),
+        prompt: optionalString(input, "prompt"),
+    };
+}
+function parseCaptureRequest(body) {
+    const input = objectBody(body);
+    const transcriptPath = input.transcript_path;
+    if (typeof transcriptPath !== "string" ||
+        !isAbsolute(transcriptPath) ||
+        !transcriptPath.endsWith(".jsonl")) {
+        throw new ClaudeHookRequestError("transcript_path must be an absolute .jsonl path");
+    }
+    return {
+        ...sessionAndCwd(input),
+        transcriptPath,
+        lastAssistantMessage: optionalString(input, "last_assistant_message"),
+        stopHookActive: input.stop_hook_active === true,
+    };
+}
+function errorCode(error) {
+    if (error && typeof error === "object" && "code" in error && typeof error.code === "string") {
+        return error.code;
+    }
+    return error instanceof Error ? error.name : "unknown";
+}
+// --- Retrieval ---
+let backfillRequested = false;
+/** The first session start in this process starts the Claude Code backfill, once. */
+function maybeStartBackfill(deps) {
+    if (backfillRequested || !deps.startBackfill)
+        return;
+    if (!CONFIG.autoBackfill || process.env.OMMS_DISABLE_AUTO_BACKFILL === "1")
+        return;
+    backfillRequested = true;
+    void deps
+        .startBackfill()
+        .catch((error) => log("Claude Code backfill start failed", { code: errorCode(error) }));
+}
+async function retrievalSection(request) {
+    if (request.event === "user-prompt-submit") {
+        const prompt = stripPrivateContent(request.prompt ?? "").trim();
+        if (!CONFIG.chatMessage.enabled || !prompt || isFullyPrivate(request.prompt ?? "")) {
+            return null;
+        }
+        return buildRetrievalSection(prompt, request.cwd, request.sessionId);
+    }
+    const tags = getTags(request.cwd);
+    if (request.source === "compact" || request.source === "resume") {
+        if (!CONFIG.compaction.enabled)
+            return null;
+        const result = await memoryClient.searchMemoriesBySessionID(request.sessionId, tags.project.tag, CONFIG.compaction.memoryLimit);
+        const own = result.success
+            ? result.results.filter((memory) => memory.metadata?.host === HOST)
+            : [];
+        return own.length > 0 ? formatMemoriesForCompaction(own) : null;
+    }
+    if (!CONFIG.chatMessage.enabled)
+        return null;
+    return buildRecentMemoriesSection({
+        projectTag: tags.project.tag,
+        userEmail: tags.user.userEmail,
+        sessionId: request.sessionId,
+        maxMemories: CONFIG.chatMessage.maxMemories,
+        excludeCurrentSession: CONFIG.chatMessage.excludeCurrentSession,
+        maxAgeDays: CONFIG.chatMessage.maxAgeDays,
+    });
+}
+/**
+ * `POST /api/claude/retrieve`: recent project memories for a fresh session,
+ * the session's own memories after compaction or resume, or the retrieval
+ * section for a prompt. Every text is wrapped in the retrieval tag; an empty
+ * string means nothing to add.
+ */
+export async function handleClaudeRetrieve(body, deps = {}) {
+    const request = parseRetrieveRequest(body);
+    refreshConfigIfChanged(request.cwd);
+    if (request.event === "session-start")
+        maybeStartBackfill(deps);
+    try {
+        const section = await retrievalSection(request);
+        return { additionalContext: section ? wrapRetrievalSection(section) : "" };
+    }
+    catch (error) {
+        log("Claude Code retrieval failed", {
+            event: request.event,
+            sessionID: request.sessionId,
+            code: errorCode(error),
+        });
+        return { additionalContext: "" };
+    }
+}
+// --- Capture ---
+let captureChain = Promise.resolve();
+let captureOffReported = false;
+/** Log once per process that capture is off and which settings are missing. */
+function reportCaptureOff(issues) {
+    if (captureOffReported)
+        return;
+    captureOffReported = true;
+    log("Claude Code capture is off", { issues });
+}
+/**
+ * `POST /api/claude/capture`: check the request, queue the turn on the
+ * one-worker queue, and answer at once. Throws `ClaudeHookRequestError` for a
+ * request that cannot be used.
+ */
+export function handleClaudeCapture(body, deps = {}) {
+    const request = parseCaptureRequest(body);
+    captureChain = captureChain
+        .then(() => captureTurn(request, deps))
+        .catch((error) => log("Claude Code capture failed", { sessionID: request.sessionId, code: errorCode(error) }));
+    return { queued: true };
+}
+/** Resolves when every queued capture has finished. */
+export function whenClaudeCaptureIdle() {
+    return captureChain;
+}
+function skipped(request, code, data = {}) {
+    log("Claude Code capture skipped", { sessionID: request.sessionId, code, ...data });
+}
+async function readTranscript(request) {
+    let text;
+    try {
+        text = await readFile(request.transcriptPath, "utf8");
+    }
+    catch (error) {
+        const code = errorCode(error);
+        skipped(request, code === "ENOENT" ? "transcript-missing" : "transcript-unreadable", {
+            error: code,
+        });
+        return null;
+    }
+    const parsed = parseClaudeTranscript(text);
+    if (parsed.entries.length === 0) {
+        skipped(request, "transcript-unreadable", {
+            bytes: Buffer.byteLength(text),
+            unreadableLines: parsed.unreadableLines,
+            unknownTypes: parsed.unknownTypes,
+        });
+        return null;
+    }
+    return parsed.entries;
+}
+/**
+ * The windows after the cursor. The transcript file can lag the hook, so the
+ * hook's final text is added as a last assistant reply when the transcript
+ * does not already end with it. It carries no entry id, so `sourceEntryIds`
+ * stay the reader's ids.
+ */
+export function claudeWindowsToCapture(entries, cursor, finalText) {
+    const tail = finalText?.trim();
+    if (!tail)
+        return extractClaudeWindowsAfter(entries, cursor);
+    const hookReply = {
+        type: "assistant",
+        message: { role: "assistant", content: [{ type: "text", text: tail }] },
+    };
+    const windows = extractClaudeWindowsAfter([...entries, hookReply], cursor);
+    const last = windows.at(-1);
+    const replies = last?.textResponses ?? [];
+    if (replies.length > 1 && replies[replies.length - 2].trim().endsWith(tail))
+        replies.pop();
+    return windows;
+}
+/**
+ * The project a session belongs to: the first prompt's directory, the same rule
+ * the history import uses. Live capture must file a turn under the project the
+ * import would choose, or the import cannot see that the turn is already saved.
+ */
+function sessionDirectory(entries, fallback) {
+    const first = entries.find((entry) => entry.type === "user" && entry.isSidechain !== true);
+    return typeof first?.cwd === "string" && first.cwd ? first.cwd : fallback;
+}
+/** A cleaned work unit, or null for a prompt with nothing left to capture. */
+function workUnitOf(request, window, directory) {
+    const prompt = stripRetrievalSections(window.userPrompt);
+    if (!prompt || isFullyPrivate(prompt))
+        return null;
+    return {
+        host: HOST,
+        hostSessionId: request.sessionId,
+        sourceType: "live-capture",
+        projectDirectory: directory,
+        userPrompt: stripPrivateContent(prompt),
+        promptId: window.userEntryId,
+        textResponses: window.textResponses.map(stripPrivateContent),
+        toolCalls: window.toolCalls.map((call) => ({
+            name: call.name,
+            input: stripPrivateContent(call.input),
+        })),
+        sourceEntryIds: window.sourceEntryIds,
+        ...(window.sourceTimestamp !== undefined ? { sourceTimestamp: window.sourceTimestamp } : {}),
+    };
+}
+/** Try the turn up to `autoCaptureMaxRetries` times, as the other hosts do. */
+async function captureWithQuickRetries(unit, provider, sleep) {
+    const maxRetries = Math.max(1, CONFIG.autoCaptureMaxRetries ?? 3);
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await captureConversation(unit, provider);
+        }
+        catch (error) {
+            if (attempt >= maxRetries)
+                throw error;
+            await sleep(quickRetryDelayMs(attempt));
+        }
+    }
+}
+async function externalModels() {
+    const { selectImportModel } = await import("./model-selection.js");
+    return selectImportModel({});
+}
+async function captureTurn(request, deps) {
+    const started = Date.now();
+    refreshConfigIfChanged(request.cwd);
+    if (!CONFIG.autoCaptureEnabled)
+        return;
+    const live = resolveClaudeCodeLiveModel(CONFIG);
+    if (!live.ready)
+        return reportCaptureOff(live.issues);
+    if (memoryClient.getEmbeddingInitError?.())
+        return skipped(request, "not-ready");
+    const entries = await readTranscript(request);
+    if (!entries)
+        return;
+    const cursor = await readClaudeCaptureCursor(request.sessionId, CONFIG);
+    const windows = claudeWindowsToCapture(entries, cursor, request.lastAssistantMessage);
+    if (windows.length === 0) {
+        // A repeated Stop is the case the flag exists for, so record it even with nothing to capture.
+        if (request.stopHookActive)
+            log("Claude Code capture idle", { sessionID: request.sessionId, stopHookActive: true });
+        return;
+    }
+    const directory = sessionDirectory(entries, request.cwd);
+    let provider;
+    try {
+        provider = deps.captureProvider?.() ?? (await externalModels()).capture;
+    }
+    catch (error) {
+        return skipped(request, "model-unavailable", { error: errorCode(error) });
+    }
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const counts = { captured: 0, skipped: 0, failed: 0, private: 0, queued: 0 };
+    let blocked = null;
+    for (const window of windows) {
+        const unit = workUnitOf(request, window, directory);
+        if (!unit) {
+            counts.private++;
+        }
+        else if (blocked) {
+            // The model is out of reach: queue the rest of the turns without calling it.
+            if (await queueFailedCapture(unit, blocked, CONFIG))
+                counts.queued++;
+        }
+        else {
+            try {
+                const result = await captureWithQuickRetries(unit, provider, sleep);
+                counts[result.status]++;
+                await recordPrompt(request, unit, result.status === "captured" ? result.memoryId : null);
+            }
+            catch (error) {
+                counts.failed++;
+                if (await queueFailedCapture(unit, error, CONFIG))
+                    counts.queued++;
+                if (classifyCaptureFailure(captureFailureOf(error)) === "retryable")
+                    blocked = error;
+            }
+        }
+        await writeClaudeCaptureCursor(request.sessionId, window.userEntryId, CONFIG);
+    }
+    log("Claude Code capture finished", {
+        sessionID: request.sessionId,
+        windows: windows.length,
+        ...counts,
+        stopHookActive: request.stopHookActive,
+        elapsedMs: Date.now() - started,
+    });
+    if (counts.captured > 0) {
+        // The model answers again, so earlier failed turns may go through now.
+        startCaptureRetryDrain(HOST);
+    }
+    if (counts.captured + counts.skipped > 0)
+        await learnProfile(request.cwd, deps);
+}
+// --- Profile learning ---
+async function recordPrompt(request, unit, memoryId) {
+    try {
+        const { userPromptManager } = await import("../services/user-prompt/user-prompt-manager.js");
+        const id = await userPromptManager.savePrompt(request.sessionId, unit.promptId, request.cwd, unit.userPrompt);
+        await userPromptManager.markAsCaptured(id);
+        if (memoryId)
+            await userPromptManager.linkMemoryToPrompt(id, memoryId);
+    }
+    catch (error) {
+        log("Claude Code prompt record failed", {
+            sessionID: request.sessionId,
+            code: errorCode(error),
+        });
+    }
+}
+let learning = false;
+/**
+ * Build or update the user profile from the recorded prompts once there are
+ * `userProfileAnalysisInterval` of them. A failure is logged and never
+ * blocks capture; the prompts stay for the next pass.
+ */
+async function learnProfile(directory, deps) {
+    const interval = CONFIG.userProfileAnalysisInterval ?? 0;
+    if (!(interval > 0) || learning)
+        return;
+    learning = true;
+    try {
+        const [{ userPromptManager }, { userProfileManager }, { analyzeProfile }] = await Promise.all([
+            import("../services/user-prompt/user-prompt-manager.js"),
+            import("../services/user-profile/user-profile-manager.js"),
+            import("../core/profile-analysis.js"),
+        ]);
+        if ((await userPromptManager.countUnanalyzedForUserLearning()) < interval)
+            return;
+        const user = getTags(directory).user;
+        if (!user.userEmail) {
+            log("Claude Code profile learning skipped", { code: "no-user-email" });
+            return;
+        }
+        const batch = await userPromptManager.getPromptsForUserLearning(interval);
+        if (batch.length === 0)
+            return;
+        const model = deps.profileModel?.() ?? (await externalModels()).profile;
+        const existing = await userProfileManager.getActiveProfile(user.userEmail);
+        const context = batch.map((prompt, index) => `${index + 1}. ${prompt.content}`).join("\n");
+        const analysis = await analyzeProfile(model, context, existing ? { id: existing.id, profileData: existing.profileData } : null);
+        if (existing) {
+            const updated = analysis.merged &&
+                (await userProfileManager.updateProfile(existing.id, analysis.merged, batch.length, `Claude Code analysis of ${batch.length} prompts`));
+            if (!updated)
+                throw new Error("Profile update conflict");
+        }
+        else {
+            await userProfileManager.createProfile(user.userEmail, user.displayName || user.userEmail, user.userName || user.userEmail, user.userEmail, analysis.raw, batch.length);
+        }
+        await userPromptManager.markMultipleAsUserLearningCaptured(batch.map((prompt) => prompt.id));
+        log("Claude Code profile learning finished", {
+            prompts: batch.length,
+            hadExisting: Boolean(existing),
+        });
+    }
+    catch (error) {
+        log("Claude Code profile learning failed", { code: errorCode(error) });
+    }
+    finally {
+        learning = false;
+    }
+}
+// --- Web app start ---
+/**
+ * Register the Claude Code retry drain in this web app and start one retry
+ * pass. The drain uses the external API. When capture is off, the first
+ * capture request logs the missing settings, so a web app that never serves
+ * Claude Code does not log them.
+ */
+export function startClaudeCodeWorker() {
+    registerCaptureRetryDrain(HOST, async () => {
+        let provider = null;
+        if (resolveClaudeCodeLiveModel(CONFIG).ready) {
+            provider = await externalModels()
+                .then((models) => models.capture)
+                .catch(() => null);
+        }
+        return drainCaptureRetries({
+            host: HOST,
+            // Never called while isReady is false.
+            provider: provider ?? {
+                summarize: () => Promise.reject(new Error("Claude Code capture model unavailable")),
+            },
+            config: CONFIG,
+            isReady: () => provider !== null && !memoryClient.getEmbeddingInitError?.(),
+        });
+    });
+    if (resolveClaudeCodeLiveModel(CONFIG).ready && CONFIG.autoCaptureEnabled) {
+        startCaptureRetryDrain(HOST);
+    }
+}

package/dist/importer/claude-import.d.ts

@@ -0,0 +1,15 @@
+import { type ImportFilters, type ImporterDeps, type ImportReport } from "./importer.js";
+import { type ClaudeHistoryDeps } from "./claude-reader.js";
+export interface ClaudeImportReport extends ImportReport {
+    /** Transcript lines that were not JSON entries. */
+    unreadableLines: number;
+    /** Entries of a type the reader does not know. */
+    unknownTypes: number;
+}
+export type ClaudeImportDeps = Pick<ImporterDeps, "provider" | "ledger" | "onProgress" | "signal" | "profile"> & ClaudeHistoryDeps;
+/**
+ * Import Claude Code history through the shared capture, ledger, and profile
+ * steps, with host `claude-code`. Mirrors `importPiHistory`: the same filters,
+ * report, and dry-run rules.
+ */
+export declare function importClaudeHistory(deps: ClaudeImportDeps, filters: ImportFilters): Promise<ClaudeImportReport>;

package/dist/importer/claude-import.js

@@ -0,0 +1,62 @@
+import { importHistorySource, } from "./importer.js";
+import { openClaudeHistorySource } from "./claude-reader.js";
+/**
+ * Import Claude Code history through the shared capture, ledger, and profile
+ * steps, with host `claude-code`. Mirrors `importPiHistory`: the same filters,
+ * report, and dry-run rules.
+ */
+export async function importClaudeHistory(deps, filters) {
+    const source = await openClaudeHistorySource({
+        ...(filters.root !== undefined ? { root: filters.root } : {}),
+        ...(filters.since !== undefined ? { since: filters.since } : {}),
+        ...(filters.until !== undefined ? { until: filters.until } : {}),
+        ...(filters.cutoff !== undefined ? { cutoff: filters.cutoff } : {}),
+        ...(filters.session ? { session: filters.session } : {}),
+        ...(filters.selectionKeys ? { selectionKeys: filters.selectionKeys } : {}),
+        ...(filters.maxSessions !== undefined ? { maxSessions: filters.maxSessions } : {}),
+        ...(filters.pathMaps ? { pathMaps: filters.pathMaps } : {}),
+        ...(filters.scope === "current-project" ? { project: filters.currentDirectory } : {}),
+        ...(deps.signal ? { signal: deps.signal } : {}),
+    }, deps.loadSession ? { loadSession: deps.loadSession } : {});
+    const report = {
+        dryRun: Boolean(filters.dryRun),
+        root: filters.root ?? "",
+        sessionsDiscovered: source.sessionsDiscovered,
+        sessionsLoaded: source.sessionsLoaded,
+        sessionsFilteredOut: source.sessionsFilteredOut,
+        sessionsUnrecognized: source.unrecognized.length,
+        unresolvableSessions: source.unresolvableSessions,
+        // Shared with the source, so a session that fails in `open()` is reported too.
+        loadErrors: source.loadErrors,
+        unitsTotal: 0,
+        unitsImported: 0,
+        unitsWouldImport: 0,
+        unitsSkipped: 0,
+        unitsFailed: 0,
+        unitsAlreadyHandled: 0,
+        skipReasons: {},
+        projects: source.projects,
+        units: [],
+        unitsHeldBack: source.unitsHeldBack,
+        unitsUntimed: source.unitsUntimed,
+        unreadableLines: source.unreadableLines,
+        unknownTypes: source.unknownTypes,
+    };
+    if (filters.skipMemories) {
+        report.unitsTotal = source.unitsKept;
+    }
+    else {
+        await importHistorySource(source, "claude-code", deps, filters, report);
+    }
+    if (deps.profile && !deps.signal?.aborted) {
+        const { importProfileFromHistory } = await import("./profile-import.js");
+        report.profile = await importProfileFromHistory(source.open(), {
+            host: "claude-code",
+            signal: deps.signal,
+            dryRun: Boolean(filters.dryRun),
+            model: deps.profile.model,
+            batchSize: deps.profile.batchSize,
+        });
+    }
+    return report;
+}

package/dist/importer/claude-reader.d.ts

@@ -0,0 +1,99 @@
+import { type ClaudeConversationWindow } from "./claude-conversation.js";
+import type { UnrecognizedFile } from "./discovery.js";
+import { type ImportPathMap, type ImportProjectReport, type LazyImportSource } from "./importer.js";
+/**
+ * Discovery and loading of Claude Code transcripts for the history import.
+ * Read-only: transcripts are never written.
+ *
+ * Claude Code keeps one folder per project under `~/.claude/projects/` and one
+ * `<session-id>.jsonl` file per session in it. Subagent transcripts sit one
+ * level lower (`<session-id>/subagents/*.jsonl`) and are not sessions, so the
+ * walk reads only the root and its direct sub-folders. The root may also be a
+ * single project folder or one `.jsonl` file. Symlinks are never followed.
+ *
+ * Discovery reads each file only up to its first user entry, which carries
+ * the working directory and date; units are parsed later, one session at a
+ * time.
+ */
+export declare const CLAUDE_HEADER_READ_LIMIT: number;
+export declare function defaultClaudeProjectsRoot(): string;
+export interface DiscoveredClaudeSession {
+    file: string;
+    /** Path relative to the root, with `/` separators; the file name for a file root. */
+    key: string;
+    sessionId: string;
+    /** Working directory of the first user entry. */
+    cwd: string | null;
+    /** First user entry ISO timestamp converted to epoch ms, when present. */
+    timestamp: number | null;
+}
+export interface ClaudeDiscoveryResult {
+    sessions: DiscoveredClaudeSession[];
+    unrecognized: UnrecognizedFile[];
+}
+export interface ClaudeDiscoveryOptions {
+    root?: string;
+    maxSessions?: number;
+}
+export interface LoadedClaudeSession {
+    sessionId: string;
+    sourceFile: string;
+    cwd: string | null;
+    windows: ClaudeConversationWindow[];
+    unreadableLines: number;
+    unknownTypes: number;
+}
+/** Read one file's first user entry, or say why the file is not a usable session. */
+export declare function readClaudeSessionHead(file: string, key: string): DiscoveredClaudeSession | UnrecognizedFile;
+export declare function discoverClaudeSessions(options?: ClaudeDiscoveryOptions): ClaudeDiscoveryResult;
+/** Parse one transcript into capture windows. Throws when the file cannot be read. */
+export declare function loadClaudeSession(file: string): LoadedClaudeSession;
+export interface ClaudeHistoryOptions {
+    root?: string;
+    /** Inclusive bounds on the prompt timestamp (epoch ms). */
+    since?: number;
+    until?: number;
+    /** Web selection: prompts after this epoch ms are held back for a later run. */
+    cutoff?: number;
+    /** One session, by session ID or file path. */
+    session?: string;
+    /** Web selection: only these discovery keys. */
+    selectionKeys?: string[];
+    maxSessions?: number;
+    pathMaps?: ImportPathMap[];
+    /** Keep only sessions of this project directory (current-project scope). */
+    project?: string;
+    signal?: AbortSignal;
+}
+export interface ClaudeHistoryDeps {
+    loadSession?: (file: string) => LoadedClaudeSession;
+}
+/** A lazy import source plus the discovery figures the import report needs. */
+export interface ClaudeHistorySource extends LazyImportSource {
+    sessionsDiscovered: number;
+    sessionsLoaded: number;
+    sessionsFilteredOut: number;
+    unrecognized: UnrecognizedFile[];
+    unresolvableSessions: Array<{
+        file: string;
+        cwd: string | null;
+    }>;
+    loadErrors: Array<{
+        file: string;
+        error: string;
+    }>;
+    projects: ImportProjectReport[];
+    /** Units kept after the date and cutoff filters. */
+    unitsKept: number;
+    unitsHeldBack: number;
+    unitsUntimed: number;
+    unreadableLines: number;
+    unknownTypes: number;
+}
+/**
+ * Discover Claude Code sessions and return them as a `LazyImportSource`. A
+ * counting pass loads each selected session once for the totals and the
+ * per-project report; `open()` loads them again one at a time, so a large
+ * history never holds every turn at once.
+ */
+export declare function openClaudeHistorySource(options?: ClaudeHistoryOptions, deps?: ClaudeHistoryDeps): Promise<ClaudeHistorySource>;