@groundtrack/hooks 0.1.9 → 0.1.10

package/dist/session-import/cursor.js

@@ -0,0 +1,268 @@
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isSessionRecord, sessionString, } from "./canonical.js";
+import { sessionImportFormatIdentity, } from "./format.js";
+import { containsInternalInstructionText, sanitizeSessionValue, sanitizeWorkingDirectory, } from "./redaction.js";
+function timestamp(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+function defaultDatabasePath(context) {
+    if (context.env.CURSOR_STATE_DB)
+        return context.env.CURSOR_STATE_DB;
+    if (context.platform === "darwin")
+        return join(context.userHome, "Library", "Application Support", "Cursor", "User", "globalStorage", "state.vscdb");
+    if (context.platform === "win32" && context.env.APPDATA)
+        return join(context.env.APPDATA, "Cursor", "User", "globalStorage", "state.vscdb");
+    return join(context.env.XDG_CONFIG_HOME || join(context.userHome, ".config"), "Cursor", "User", "globalStorage", "state.vscdb");
+}
+function readHeaders(context) {
+    const path = defaultDatabasePath(context);
+    if (!existsSync(path))
+        throw new Error(`Cursor session database not found: ${path}`);
+    let DatabaseSync;
+    try {
+        const sqlite = createRequire(import.meta.url)("node:sqlite");
+        DatabaseSync = sqlite.DatabaseSync;
+    }
+    catch {
+        throw new Error("Cursor session import requires unflagged node:sqlite support (Node.js 22.13+, 23.4+, or 24+).");
+    }
+    const database = new DatabaseSync(path, { readOnly: true });
+    try {
+        return database
+            .prepare(`
+        SELECT
+          composerId,
+          createdAt,
+          lastUpdatedAt,
+          isSubagent,
+          CASE WHEN json_valid(value)
+            THEN COALESCE(
+              json_extract(value, '$.workspaceIdentifier.uri.fsPath'),
+              json_extract(value, '$.trackedGitRepos[0].repoPath')
+            )
+            ELSE NULL
+          END AS workingDirectory
+        FROM composerHeaders
+      `)
+            .all();
+    }
+    finally {
+        database.close();
+    }
+}
+function cursorProjectName(path) {
+    return path.replace(/^[/\\]+/, "").replaceAll(/[:/\\]+/g, "-");
+}
+function transcriptPaths(projectsRoot) {
+    const result = new Map();
+    if (!existsSync(projectsRoot))
+        return result;
+    for (const project of readdirSync(projectsRoot, { withFileTypes: true })) {
+        if (!project.isDirectory())
+            continue;
+        const transcripts = join(projectsRoot, project.name, "agent-transcripts");
+        if (!existsSync(transcripts))
+            continue;
+        for (const session of readdirSync(transcripts, { withFileTypes: true })) {
+            if (!session.isDirectory())
+                continue;
+            const path = join(transcripts, session.name, `${session.name}.jsonl`);
+            if (!existsSync(path))
+                continue;
+            const paths = result.get(session.name) ?? [];
+            paths.push(path);
+            result.set(session.name, paths);
+        }
+    }
+    return result;
+}
+function selectTranscript(paths, workingDirectory) {
+    if (!workingDirectory)
+        return paths.length === 1 ? paths[0] : null;
+    const expectedProject = cursorProjectName(workingDirectory);
+    const matching = paths.filter((path) => dirname(dirname(dirname(path)))
+        .split(/[/\\]/)
+        .at(-1) === expectedProject);
+    return matching.length === 1 ? matching[0] : null;
+}
+function isEmptyTranscript(path) {
+    if (statSync(path).size > 64 * 1024)
+        return false;
+    let records;
+    try {
+        records = readFileSync(path, "utf8")
+            .split(/\r?\n/)
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return false;
+    }
+    return !records.some((record) => isSessionRecord(record) &&
+        (record.role === "user" || record.role === "assistant") &&
+        isSessionRecord(record.message) &&
+        Array.isArray(record.message.content));
+}
+export function cursorCandidates(context, headers = readHeaders(context)) {
+    const projectsRoot = context.env.CURSOR_PROJECTS_DIR ?? join(context.sessionHome, "projects");
+    const transcripts = transcriptPaths(projectsRoot);
+    const included = [];
+    const skipped = [];
+    const headerSessionIds = new Set();
+    for (const header of headers) {
+        const externalSessionId = sessionString(header.composerId);
+        if (!externalSessionId)
+            continue;
+        headerSessionIds.add(externalSessionId);
+        const paths = transcripts.get(externalSessionId);
+        if (!paths?.length)
+            continue;
+        const workingDirectory = sessionString(header.workingDirectory);
+        const path = selectTranscript(paths, workingDirectory);
+        if (!path) {
+            for (const duplicate of paths)
+                skipped.push({
+                    path: duplicate,
+                    reason: workingDirectory ? "workspace_mismatch" : "conflicting_duplicates",
+                });
+            continue;
+        }
+        for (const other of paths) {
+            if (other !== path)
+                skipped.push({ path: other, reason: "workspace_mismatch" });
+        }
+        const startedAt = timestamp(header.createdAt);
+        const endedAt = timestamp(header.lastUpdatedAt);
+        const discoveredAt = endedAt ?? new Date(statSync(path).mtimeMs);
+        if (!startedAt ||
+            (header.lastUpdatedAt != null && !endedAt) ||
+            (endedAt && endedAt < startedAt)) {
+            skipped.push({ path, reason: "invalid_metadata" });
+            continue;
+        }
+        if (isEmptyTranscript(path)) {
+            skipped.push({ path, reason: "empty_trace" });
+            continue;
+        }
+        included.push({
+            path,
+            metadata: {
+                externalSessionId,
+                timestamp: discoveredAt,
+                cwd: workingDirectory,
+                repositoryUrl: null,
+                repositoryBranch: null,
+                repositoryCommitSha: null,
+                originator: "cursor",
+                isSubagent: header.isSubagent === 1,
+                startedAt,
+                endedAt,
+            },
+        });
+    }
+    for (const [sessionId, paths] of transcripts) {
+        if (headerSessionIds.has(sessionId))
+            continue;
+        for (const path of paths)
+            skipped.push({ path, reason: "missing_metadata" });
+    }
+    return { included, skipped };
+}
+function normalizeMessage(record) {
+    const role = sessionString(record.role);
+    if (role !== "user" && role !== "assistant")
+        return null;
+    const message = isSessionRecord(record.message) ? record.message : null;
+    if (!message || !Array.isArray(message.content))
+        return null;
+    const entries = [];
+    let sensitive = false;
+    let unsupported = false;
+    for (const block of message.content) {
+        if (!isSessionRecord(block)) {
+            unsupported = true;
+            continue;
+        }
+        const type = sessionString(block.type);
+        if (type === "thinking" || type === "redacted_thinking") {
+            sensitive = true;
+            continue;
+        }
+        if (type === "text") {
+            const text = sessionString(block.text);
+            if (!text)
+                continue;
+            if (containsInternalInstructionText(text))
+                sensitive = true;
+            else
+                entries.push({
+                    kind: role === "user" ? "user_message" : "assistant_message",
+                    occurredAt: null,
+                    payload: { text: sanitizeSessionValue(text) },
+                });
+            continue;
+        }
+        if (role === "assistant" && type === "tool_use") {
+            const toolName = sessionString(block.name);
+            if (!toolName)
+                unsupported = true;
+            else
+                entries.push({
+                    kind: "tool_call",
+                    occurredAt: null,
+                    payload: {
+                        callId: sessionString(block.id),
+                        toolName,
+                        input: sanitizeSessionValue(block.input),
+                    },
+                });
+            continue;
+        }
+        unsupported = true;
+    }
+    return { entries, sensitive, unsupported };
+}
+export function createCursorSessionNormalizer(metadata) {
+    return {
+        normalizeRecord: (record, entryBudget = Number.POSITIVE_INFINITY) => {
+            if (record.type === "turn_ended")
+                return { entries: [], sensitive: false, unsupported: false };
+            const normalized = normalizeMessage(record) ?? {
+                entries: [],
+                sensitive: false,
+                unsupported: true,
+            };
+            const overflowed = normalized.entries.length > entryBudget;
+            return overflowed
+                ? { ...normalized, entries: normalized.entries.slice(0, entryBudget), overflowed }
+                : normalized;
+        },
+        canonicalMetadata: () => metadata
+            ? {
+                type: "session",
+                version: 1,
+                externalSessionId: metadata.externalSessionId,
+                repositoryUrl: metadata.repositoryUrl,
+                repositoryBranch: metadata.repositoryBranch,
+                repositoryCommitSha: metadata.repositoryCommitSha,
+                workingDirectory: sanitizeWorkingDirectory(metadata.cwd),
+                originator: "cursor",
+                model: null,
+            }
+            : null,
+    };
+}
+export const cursorSessionFormat = {
+    ...sessionImportFormatIdentity("cursor"),
+    discovery: "custom",
+    homeEnvironmentVariable: "CURSOR_HOME",
+    defaultHomeDirectory: ".cursor",
+    discoverCandidates: cursorCandidates,
+    createNormalizer: createCursorSessionNormalizer,
+    sourceHashSeed: (metadata) => metadata.externalSessionId,
+};

package/dist/session-import/discovery.d.ts

@@ -1,13 +1,14 @@
-import type { CodexSessionCandidate, CodexSessionMetadata, SkippedCodexSession } from "./types.js";
-export declare function parseCodexMetadata(line: string): CodexSessionMetadata | null;
+import type { SessionImportFormat } from "./format.js";
+import type { AgentSessionCandidate, FailedAgentSession, SkippedAgentSession } from "./types.js";
 export declare function normalizeRepositoryUrl(value: string): string | null;
 export type RepositoryIdentity = Readonly<{
     root: string;
     remotes: ReadonlySet<string>;
 }>;
 export declare function repositoryIdentity(path: string): RepositoryIdentity;
-export type DiscoverCodexSessionsOptions = Readonly<{
-    codexHome: string;
+export type DiscoverSessionsOptions = Readonly<{
+    home: string;
+    format: SessionImportFormat;
     repository?: RepositoryIdentity;
     allRepositories: boolean;
     includeUnscoped: boolean;
@@ -15,8 +16,16 @@ export type DiscoverCodexSessionsOptions = Readonly<{
     since: Date | null;
     nowMs?: number;
     liveWindowMs?: number;
+    resolveRepositoryRoot?: (path: string) => string;
+    resolveRepositoryIdentity?: (path: string) => RepositoryIdentity;
+    userHome?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    workingDirectory?: string;
 }>;
-export declare function discoverCodexSessions(options: DiscoverCodexSessionsOptions): {
-    included: CodexSessionCandidate[];
-    skipped: SkippedCodexSession[];
+export declare function discoverSessions(options: DiscoverSessionsOptions): {
+    included: AgentSessionCandidate[];
+    skipped: SkippedAgentSession[];
+    failed: FailedAgentSession[];
+    cleanup?: () => void;
 };

package/dist/session-import/discovery.js

@@ -1,69 +1,46 @@
 import { execFileSync } from "node:child_process";
 import { closeSync, existsSync, lstatSync, openSync, readSync, readdirSync, realpathSync, } from "node:fs";
 import { isAbsolute, relative, resolve, sep } from "node:path";
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function stringValue(value) {
-    return typeof value === "string" && value.trim() ? value.trim() : null;
-}
-function firstLine(path, maxBytes = 1024 * 1024) {
+import { homedir } from "node:os";
+import { isSessionRecord } from "./canonical.js";
+function initialRecords(path, maxRecords, maxBytes = 1024 * 1024) {
     const file = openSync(path, "r");
     try {
         const chunks = [];
         let offset = 0;
-        while (offset < maxBytes) {
+        let newlineCount = 0;
+        while (offset < maxBytes && newlineCount < maxRecords) {
             const chunk = Buffer.alloc(Math.min(64 * 1024, maxBytes - offset));
             const read = readSync(file, chunk, 0, chunk.length, offset);
             if (read === 0)
                 break;
             const bytes = chunk.subarray(0, read);
-            const newline = bytes.indexOf(10);
-            chunks.push(newline >= 0 ? bytes.subarray(0, newline) : bytes);
-            offset += newline >= 0 ? newline : read;
-            if (newline >= 0)
-                break;
+            chunks.push(bytes);
+            offset += read;
+            for (const byte of bytes) {
+                if (byte === 10 && ++newlineCount >= maxRecords)
+                    break;
+            }
         }
-        return Buffer.concat(chunks).toString("utf8").replace(/\r$/, "");
+        return Buffer.concat(chunks)
+            .toString("utf8")
+            .split(/\r?\n/, maxRecords)
+            .flatMap((line) => {
+            if (!line.trim())
+                return [];
+            try {
+                const record = JSON.parse(line);
+                return isSessionRecord(record) ? [record] : [];
+            }
+            catch {
+                return [];
+            }
+        });
     }
     finally {
         closeSync(file);
     }
 }
-function isSubagentMetadata(payload) {
-    if (stringValue(payload.parent_thread_id) || stringValue(payload.agent_path))
-        return true;
-    if (isRecord(payload.source) && "subagent" in payload.source)
-        return true;
-    return ["subagent", "agent_forked_thread", "guardian_review"].includes(stringValue(payload.thread_source) ?? "");
-}
-export function parseCodexMetadata(line) {
-    try {
-        const record = JSON.parse(line);
-        if (!isRecord(record) || record.type !== "session_meta" || !isRecord(record.payload))
-            return null;
-        const payload = record.payload;
-        const git = isRecord(payload.git) ? payload.git : {};
-        const externalSessionId = stringValue(payload.session_id) ?? stringValue(payload.id);
-        if (!externalSessionId)
-            return null;
-        const timestampValue = stringValue(payload.timestamp) ?? stringValue(record.timestamp);
-        const timestamp = timestampValue ? new Date(timestampValue) : null;
-        return {
-            externalSessionId,
-            timestamp: timestamp && !Number.isNaN(timestamp.getTime()) ? timestamp : null,
-            cwd: stringValue(payload.cwd),
-            repositoryUrl: stringValue(git.repository_url),
-            repositoryBranch: stringValue(git.branch),
-            repositoryCommitSha: stringValue(git.commit_hash),
-            originator: stringValue(payload.originator),
-            isSubagent: isSubagentMetadata(payload),
-        };
-    }
-    catch {
-        return null;
-    }
-}
 function walkJsonl(root) {
     if (!existsSync(root))
         return [];
@@ -102,12 +79,15 @@ export function normalizeRepositoryUrl(value) {
         return null;
     return parts.slice(-2).join("/").toLowerCase();
 }
-export function repositoryIdentity(path) {
-    const root = realpathSync(execFileSync("git", ["-C", path, "rev-parse", "--show-toplevel"], {
+function repositoryRoot(path) {
+    return realpathSync(execFileSync("git", ["-C", path, "rev-parse", "--show-toplevel"], {
         encoding: "utf8",
         stdio: ["ignore", "pipe", "ignore"],
         timeout: 5_000,
     }).trim());
+}
+export function repositoryIdentity(path) {
+    const root = repositoryRoot(path);
     const names = execFileSync("git", ["-C", root, "remote"], {
         encoding: "utf8",
         stdio: ["ignore", "pipe", "ignore"],
@@ -136,25 +116,78 @@ function isInside(candidate, root) {
     const child = relative(root, resolve(candidate));
     return child === "" || (!child.startsWith(`..${sep}`) && child !== "..");
 }
-export function discoverCodexSessions(options) {
+export function discoverSessions(options) {
     const nowMs = options.nowMs ?? Date.now();
     const liveWindowMs = options.liveWindowMs ?? 5 * 60_000;
-    const roots = [
-        resolve(options.codexHome, "sessions"),
-        resolve(options.codexHome, "archived_sessions"),
-    ];
     const included = [];
-    const skipped = [];
-    for (const path of roots.flatMap(walkJsonl)) {
-        const metadata = parseCodexMetadata(firstLine(path));
-        if (!metadata) {
-            skipped.push({ path, reason: "invalid_metadata" });
-            continue;
+    const discoveryContext = {
+        sessionHome: options.home,
+        userHome: options.userHome ?? homedir(),
+        workingDirectory: options.workingDirectory ?? options.repository?.root ?? process.cwd(),
+        env: options.env ?? process.env,
+        platform: options.platform ?? process.platform,
+    };
+    const discovered = options.format.discovery === "custom"
+        ? options.format.discoverCandidates(discoveryContext)
+        : (() => {
+            const candidates = [];
+            const rejected = [];
+            for (const path of options.format.sessionRoots(options.home).flatMap(walkJsonl)) {
+                const metadata = options.format.parseDiscoveryMetadata(initialRecords(path, options.format.discoveryRecordLimit));
+                if (metadata)
+                    candidates.push({ path, metadata });
+                else
+                    rejected.push({ path, reason: "invalid_metadata" });
+            }
+            return { included: candidates, skipped: rejected };
+        })();
+    const skipped = [...discovered.skipped];
+    const repositoryRootsByCwd = new Map();
+    const repositoryIdentitiesByRoot = new Map();
+    const repositoryRootForCwd = (cwd) => {
+        if (!cwd)
+            return null;
+        const cached = repositoryRootsByCwd.get(cwd);
+        if (cached !== undefined)
+            return cached;
+        let root = null;
+        try {
+            root = (options.resolveRepositoryRoot ?? repositoryRoot)(cwd);
         }
-        const stat = lstatSync(path);
-        if (!stat.isFile())
+        catch { }
+        repositoryRootsByCwd.set(cwd, root);
+        return root;
+    };
+    const repositoryIdentityForCwd = (cwd) => {
+        const root = repositoryRootForCwd(cwd);
+        if (!root)
+            return null;
+        const cached = repositoryIdentitiesByRoot.get(root);
+        if (cached !== undefined)
+            return cached;
+        let identity = null;
+        try {
+            identity = (options.resolveRepositoryIdentity ?? repositoryIdentity)(root);
+        }
+        catch { }
+        repositoryIdentitiesByRoot.set(root, identity);
+        return identity;
+    };
+    const soleRemote = (identity) => {
+        if (!identity || identity.remotes.size !== 1)
+            return null;
+        return identity.remotes.values().next().value ?? null;
+    };
+    for (const candidate of discovered.included) {
+        const { path, metadata } = candidate;
+        const modifiedAtMs = candidate.modifiedAt?.getTime() ??
+            (() => {
+                const file = lstatSync(path);
+                return file.isFile() ? file.mtimeMs : Number.NaN;
+            })();
+        if (!Number.isFinite(modifiedAtMs))
             continue;
-        if (nowMs - stat.mtimeMs < liveWindowMs) {
+        if (nowMs - modifiedAtMs < liveWindowMs) {
             skipped.push({ path, reason: "live" });
             continue;
         }
@@ -178,11 +211,31 @@ export function discoverCodexSessions(options) {
             skipped.push({ path, reason: "other_repository" });
             continue;
         }
-        if (options.allRepositories && !normalizedRemote && !options.includeUnscoped) {
+        if (options.allRepositories &&
+            !options.includeUnscoped &&
+            !normalizedRemote &&
+            !repositoryRootForCwd(metadata.cwd)) {
             skipped.push({ path, reason: "unscoped" });
             continue;
         }
-        included.push({ path, metadata });
+        const inferredRemote = normalizedRemote
+            ? null
+            : options.repository && matchesCurrentRepository
+                ? soleRemote(options.repository)
+                : options.allRepositories
+                    ? soleRemote(repositoryIdentityForCwd(metadata.cwd))
+                    : null;
+        included.push(inferredRemote
+            ? { ...candidate, metadata: { ...metadata, repositoryUrl: inferredRemote } }
+            : candidate);
     }
-    return { included, skipped };
+    if (!options.format.materializeCandidates)
+        return { included, skipped, failed: [] };
+    const materialized = options.format.materializeCandidates(included, discoveryContext);
+    return {
+        included: [...materialized.included],
+        skipped,
+        failed: [...materialized.failed],
+        cleanup: materialized.cleanup,
+    };
 }

package/dist/session-import/format.d.ts

@@ -0,0 +1,51 @@
+import type { CanonicalSessionEntry, CanonicalSessionMetadata, SessionRecord } from "./canonical.js";
+import type { AgentSessionCandidate, AgentSessionMetadata, AgentSessionSource, FailedAgentSession, ImportAgent, SkippedAgentSession } from "./types.js";
+export type SessionRecordNormalization = Readonly<{
+    entries: readonly CanonicalSessionEntry[];
+    sensitive: boolean;
+    unsupported: boolean;
+    overflowed?: boolean;
+}>;
+export type SessionNormalizer = Readonly<{
+    normalizeRecord(record: SessionRecord, entryBudget?: number): SessionRecordNormalization;
+    canonicalMetadata(): Omit<CanonicalSessionMetadata, "startedAt" | "endedAt" | "statistics"> | null;
+}>;
+export type SessionDiscoveryContext = Readonly<{
+    sessionHome: string;
+    userHome: string;
+    workingDirectory: string;
+    env: NodeJS.ProcessEnv;
+    platform: NodeJS.Platform;
+}>;
+export type SessionDiscoveryCandidates = Readonly<{
+    included: readonly AgentSessionCandidate[];
+    skipped: readonly SkippedAgentSession[];
+}>;
+export type MaterializedSessionCandidates = Readonly<{
+    included: readonly AgentSessionCandidate[];
+    failed: readonly FailedAgentSession[];
+    cleanup(): void;
+}>;
+type SessionImportFormatBase = Readonly<{
+    agent: ImportAgent;
+    source: AgentSessionSource;
+    displayName: string;
+    homeEnvironmentVariable: string;
+    defaultHomeDirectory: string;
+    materializeCandidates?(candidates: readonly AgentSessionCandidate[], context: SessionDiscoveryContext): MaterializedSessionCandidates;
+    createNormalizer(metadata?: AgentSessionMetadata): SessionNormalizer;
+    sourceHashSeed?(metadata: AgentSessionMetadata): string;
+}>;
+type FileSessionDiscovery = Readonly<{
+    discovery: "files";
+    discoveryRecordLimit: number;
+    sessionRoots(home: string): readonly string[];
+    parseDiscoveryMetadata(records: readonly SessionRecord[]): AgentSessionMetadata | null;
+}>;
+type CustomSessionDiscovery = Readonly<{
+    discovery: "custom";
+    discoverCandidates(context: SessionDiscoveryContext): SessionDiscoveryCandidates;
+}>;
+export type SessionImportFormat = SessionImportFormatBase & (FileSessionDiscovery | CustomSessionDiscovery);
+export declare function sessionImportFormatIdentity(agent: ImportAgent): Pick<SessionImportFormat, "agent" | "source" | "displayName">;
+export {};

package/dist/session-import/format.js

@@ -0,0 +1,11 @@
+import { SESSION_IMPORT_AGENTS } from "../agents.js";
+export function sessionImportFormatIdentity(agent) {
+    const definition = SESSION_IMPORT_AGENTS.find((candidate) => candidate.id === agent);
+    if (!definition)
+        throw new Error(`Unsupported session import agent: ${agent}`);
+    return {
+        agent: definition.id,
+        source: definition.source,
+        displayName: definition.name,
+    };
+}

package/dist/session-import/formats.d.ts

@@ -0,0 +1,4 @@
+import type { SessionImportFormat } from "./format.js";
+import type { ImportAgent } from "./types.js";
+export declare const sessionImportFormats: Readonly<Record<ImportAgent, SessionImportFormat>>;
+export declare function sessionImportFormat(agent: ImportAgent): SessionImportFormat;

package/dist/session-import/formats.js

@@ -0,0 +1,13 @@
+import { claudeSessionFormat } from "./claude.js";
+import { codexSessionFormat } from "./codex.js";
+import { cursorSessionFormat } from "./cursor.js";
+import { opencodeSessionFormat } from "./opencode-cli.js";
+export const sessionImportFormats = {
+    claude: claudeSessionFormat,
+    codex: codexSessionFormat,
+    cursor: cursorSessionFormat,
+    opencode: opencodeSessionFormat,
+};
+export function sessionImportFormat(agent) {
+    return sessionImportFormats[agent];
+}

package/dist/session-import/normalize.d.ts

@@ -0,0 +1,21 @@
+import { type CanonicalSessionEntry, type CanonicalSessionMetadata } from "./canonical.js";
+import type { SessionNormalizer } from "./format.js";
+import type { AgentSessionMetadata } from "./types.js";
+export type SessionNormalizationErrorCode = "too_many_entries" | "missing_session_metadata" | "empty_trace";
+export declare class SessionNormalizationError extends Error {
+    readonly code: SessionNormalizationErrorCode;
+    constructor(code: SessionNormalizationErrorCode, message: string);
+}
+export type NormalizedSession = Readonly<{
+    metadata: CanonicalSessionMetadata;
+    entries: readonly CanonicalSessionEntry[];
+}>;
+export declare function createSessionNormalizationAccumulator(normalizer: SessionNormalizer, options?: Readonly<{
+    discoveryMetadata?: AgentSessionMetadata;
+    collectEntries?: boolean;
+    onEntry?: (entry: CanonicalSessionEntry) => void;
+}>): {
+    add(record: unknown): void;
+    finish(): NormalizedSession;
+};
+export declare function normalizeSessionRecords(records: readonly unknown[], normalizer: SessionNormalizer, discoveryMetadata?: AgentSessionMetadata): NormalizedSession;