@groundtrack/hooks 0.1.8 → 0.1.10

package/dist/session-import/cli.js

@@ -0,0 +1,365 @@
+import { resolve } from "node:path";
+import * as prompts from "@clack/prompts";
+import { DEFAULT_SESSION_IMPORT_AGENT, isSessionImportAgent, SESSION_IMPORT_AGENTS, } from "../agents.js";
+import { environment } from "../setup/agents.js";
+import { CANONICAL_IMPORT_MAX_BYTES } from "./canonical.js";
+import { uploadAgentSession } from "./client.js";
+import { discoverSessions, normalizeRepositoryUrl, repositoryIdentity } from "./discovery.js";
+import { sessionImportFormat } from "./formats.js";
+import { pruneSession } from "./prune.js";
+import { readReceipts, receiptKey, saveReceipt } from "./receipts.js";
+const importAgentIds = SESSION_IMPORT_AGENTS.map((agent) => agent.id);
+const importAgentChoices = importAgentIds.join("|");
+const importAgentDescription = importAgentIds.join(", ");
+export const IMPORT_USAGE = `Usage:
+  groundtrack import [--agent ${importAgentChoices}] [--repo PATH | --all-repos] [--since DATE]
+                     [--include-subagents] [--include-unscoped]
+                     [--visibility private|organization] [--dry-run] [--yes] [--json]
+
+Import options:
+  --agent VALUE          ${importAgentDescription} (default: ${DEFAULT_SESSION_IMPORT_AGENT})
+  --repo PATH            Import sessions for this Git repository (default: current repository)
+  --all-repos            Import sessions associated with any Git repository
+  --include-unscoped     With --all-repos, also import sessions outside a Git repository
+  --since DATE           Import sessions at or after an ISO timestamp or local YYYY-MM-DD
+  --include-subagents    Include subagent, forked-agent, and guardian sessions
+  --visibility VALUE     private (default) or organization
+  --api-key KEY          API key; prefer the GROUNDTRACK_API_KEY environment variable
+  --url URL              Groundtrack app or API URL (default: https://app.groundtrack.dev)
+  --dry-run              Discover and prune without authentication or network calls
+  --yes, -y              Upload without another confirmation
+  --json                 Emit exactly one machine-readable result object
+`;
+function parseDate(value) {
+    const date = /^\d{4}-\d{2}-\d{2}$/.test(value) ? new Date(`${value}T00:00:00`) : new Date(value);
+    if (Number.isNaN(date.getTime()))
+        throw new Error(`Invalid --since date: ${value}`);
+    return date;
+}
+export function normalizeApiBaseUrl(value) {
+    const url = new URL(value);
+    if ((url.protocol !== "https:" &&
+        !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash)
+        throw new Error("Use an HTTPS Groundtrack URL (or local HTTP), without credentials or query parameters.");
+    url.pathname = url.pathname.replace(/\/(?:api(?:\/mcp)?)\/?$/, "");
+    return `${url.href.replace(/\/$/, "")}/api`;
+}
+export function parseImportArguments(argv) {
+    const args = [...argv];
+    const valueAfter = (index, flag) => {
+        const value = args[index + 1];
+        if (!value || value.startsWith("-"))
+            throw new Error(`${flag} requires a value.`);
+        return value;
+    };
+    let repoDir;
+    let homeDir;
+    let agent = DEFAULT_SESSION_IMPORT_AGENT;
+    let allRepositories = false;
+    let includeUnscoped = false;
+    let includeSubagents = false;
+    let visibility = "private";
+    let since = null;
+    let dryRun = false;
+    let yes = false;
+    let json = false;
+    let apiKey;
+    let apiBaseUrl = normalizeApiBaseUrl("https://app.groundtrack.dev");
+    let help = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--agent") {
+            const value = valueAfter(index++, arg);
+            if (!isSessionImportAgent(value))
+                throw new Error(`Unsupported session import agent: ${value}.`);
+            agent = value;
+        }
+        else if (arg === "--repo")
+            repoDir = valueAfter(index++, arg);
+        else if (arg === "--home")
+            homeDir = valueAfter(index++, arg);
+        else if (arg === "--all-repos")
+            allRepositories = true;
+        else if (arg === "--include-unscoped")
+            includeUnscoped = true;
+        else if (arg === "--include-subagents")
+            includeSubagents = true;
+        else if (arg === "--visibility") {
+            const value = valueAfter(index++, arg);
+            if (value !== "private" && value !== "organization")
+                throw new Error("--visibility must be private or organization.");
+            visibility = value;
+        }
+        else if (arg === "--since")
+            since = parseDate(valueAfter(index++, arg));
+        else if (arg === "--api-key")
+            apiKey = valueAfter(index++, arg);
+        else if (arg === "--url")
+            apiBaseUrl = normalizeApiBaseUrl(valueAfter(index++, arg));
+        else if (arg === "--dry-run")
+            dryRun = true;
+        else if (arg === "--yes" || arg === "-y")
+            yes = true;
+        else if (arg === "--json")
+            json = true;
+        else if (arg === "--help" || arg === "-h")
+            help = true;
+        else
+            throw new Error(`Unknown import option: ${arg}. Run groundtrack import --help.`);
+    }
+    if (allRepositories && repoDir)
+        throw new Error("Choose --repo or --all-repos, not both.");
+    if (includeUnscoped && !allRepositories)
+        throw new Error("Use --include-unscoped together with --all-repos.");
+    return {
+        agent,
+        repoDir,
+        homeDir,
+        allRepositories,
+        includeUnscoped,
+        includeSubagents,
+        visibility,
+        since,
+        dryRun,
+        yes,
+        json,
+        apiKey,
+        apiBaseUrl,
+        help,
+    };
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 ** 2)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 ** 3)
+        return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+    return `${(bytes / 1024 ** 3).toFixed(2)} GB`;
+}
+function skippedCounts(skipped) {
+    const result = {};
+    for (const item of skipped)
+        result[item.reason] = (result[item.reason] ?? 0) + 1;
+    return result;
+}
+function printPlan(input) {
+    const originalBytes = input.sessions.reduce((sum, session) => sum + session.originalBytes, 0);
+    const prunedBytes = input.sessions.reduce((sum, session) => sum + session.prunedBytes, 0);
+    const skippedByReason = skippedCounts(input.skipped);
+    const repositories = sessionRepositoryCounts(input.sessions);
+    const timestamps = input.sessions
+        .map((item) => item.candidate.metadata.timestamp?.getTime())
+        .filter((value) => value !== undefined);
+    process.stdout.write([
+        `\nGroundtrack · import ${input.displayName} sessions`,
+        `Scope: ${input.scope}`,
+        `Transcript visibility: ${input.visibility}`,
+        "Learning: high-confidence lessons may enter your organization's shared knowledge",
+        `Sessions: ${input.sessions.length} (${input.sessions.filter((item) => item.alreadyImported).length} in local receipts)`,
+        ...(timestamps.length
+            ? [
+                `Date range: ${new Date(Math.min(...timestamps)).toISOString()} to ${new Date(Math.max(...timestamps)).toISOString()}`,
+            ]
+            : []),
+        ...Object.entries(repositories).map(([repository, count]) => `  ${repository}: ${count}`),
+        `Upload size: ${formatBytes(prunedBytes)} after pruning (${formatBytes(originalBytes)} raw)`,
+        `Skipped: ${input.skipped.length}${Object.entries(skippedByReason)
+            .map(([reason, count]) => ` · ${reason} ${count}`)
+            .join("")}`,
+        ...(input.failed ? [`Unreadable/oversized: ${input.failed}`] : []),
+        "",
+    ].join("\n"));
+}
+function sessionRepositoryCounts(sessions) {
+    const result = {};
+    for (const session of sessions) {
+        const repository = session.candidate.metadata.repositoryUrl
+            ? normalizeRepositoryUrl(session.candidate.metadata.repositoryUrl)
+            : null;
+        const label = repository ?? session.candidate.metadata.cwd ?? "(no repository)";
+        result[label] = (result[label] ?? 0) + 1;
+    }
+    return result;
+}
+function sessionDateRange(sessions) {
+    const timestamps = sessions
+        .map((item) => item.candidate.metadata.timestamp?.getTime())
+        .filter((value) => value !== undefined);
+    return timestamps.length
+        ? {
+            from: new Date(Math.min(...timestamps)).toISOString(),
+            to: new Date(Math.max(...timestamps)).toISOString(),
+        }
+        : null;
+}
+export async function runImportCli(argv) {
+    const args = parseImportArguments(argv);
+    if (args.help) {
+        process.stdout.write(IMPORT_USAGE);
+        return;
+    }
+    const context = environment({ repoDir: args.repoDir, homeDir: args.homeDir });
+    const format = sessionImportFormat(args.agent);
+    const home = resolve(context.env[format.homeEnvironmentVariable] ||
+        resolve(context.homeDir, format.defaultHomeDirectory));
+    const repository = args.allRepositories ? undefined : repositoryIdentity(context.repoDir);
+    const discovery = discoverSessions({
+        home,
+        format,
+        repository,
+        allRepositories: args.allRepositories,
+        includeUnscoped: args.includeUnscoped,
+        includeSubagents: args.includeSubagents,
+        since: args.since,
+        userHome: context.homeDir,
+        env: context.env,
+        platform: context.platform,
+        workingDirectory: context.repoDir,
+    });
+    try {
+        const apiKey = args.apiKey ?? context.env.GROUNDTRACK_API_KEY;
+        const receipts = apiKey ? readReceipts(context) : { version: 1, receipts: {} };
+        const prepared = [];
+        const preparationErrors = [...discovery.failed];
+        for (const candidate of discovery.included) {
+            try {
+                const pruned = await pruneSession(candidate.path, format, {
+                    emitBytes: false,
+                    metadata: candidate.metadata,
+                });
+                if (pruned.prunedBytes > CANONICAL_IMPORT_MAX_BYTES)
+                    throw new Error(`Pruned session exceeds ${formatBytes(CANONICAL_IMPORT_MAX_BYTES)}`);
+                const key = apiKey
+                    ? receiptKey({
+                        apiBaseUrl: args.apiBaseUrl,
+                        apiKey,
+                        source: format.source,
+                        sourceContentHash: pruned.sourceContentHash,
+                        visibility: args.visibility,
+                    })
+                    : null;
+                prepared.push({
+                    ...pruned,
+                    candidate,
+                    receiptKey: key,
+                    alreadyImported: Boolean(key && receipts.receipts[key]),
+                });
+            }
+            catch (error) {
+                preparationErrors.push({
+                    path: candidate.path,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        const scope = args.allRepositories ? "all repositories" : repository.root;
+        const plan = {
+            agent: args.agent,
+            scope,
+            selected: prepared.length,
+            alreadyImported: prepared.filter((item) => item.alreadyImported).length,
+            originalBytes: prepared.reduce((sum, item) => sum + item.originalBytes, 0),
+            prunedBytes: prepared.reduce((sum, item) => sum + item.prunedBytes, 0),
+            repositories: sessionRepositoryCounts(prepared),
+            dateRange: sessionDateRange(prepared),
+            skipped: skippedCounts(discovery.skipped),
+            failed: preparationErrors,
+        };
+        if (args.dryRun) {
+            if (args.json)
+                process.stdout.write(`${JSON.stringify({ dryRun: true, plan }, null, 2)}\n`);
+            else
+                printPlan({
+                    displayName: format.displayName,
+                    scope,
+                    visibility: args.visibility,
+                    sessions: prepared,
+                    skipped: discovery.skipped,
+                    failed: preparationErrors.length,
+                });
+            if (preparationErrors.length)
+                process.exitCode = 1;
+            return;
+        }
+        const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !args.json);
+        if (!args.json)
+            printPlan({
+                displayName: format.displayName,
+                scope,
+                visibility: args.visibility,
+                sessions: prepared,
+                skipped: discovery.skipped,
+                failed: preparationErrors.length,
+            });
+        if (!apiKey)
+            throw new Error("Set GROUNDTRACK_API_KEY or pass --api-key before uploading.");
+        if (!args.yes && !interactive)
+            throw new Error("Import needs confirmation. Use --yes, or run it in an interactive terminal.");
+        if (!args.yes) {
+            const approved = await prompts.confirm({
+                message: `Upload ${prepared.filter((item) => !item.alreadyImported).length} ${format.displayName} sessions?`,
+                initialValue: false,
+            });
+            if (prompts.isCancel(approved) || !approved) {
+                prompts.cancel("Nothing uploaded.");
+                return;
+            }
+        }
+        let imported = 0;
+        let duplicate = 0;
+        let receiptSkipped = 0;
+        const failures = [...preparationErrors];
+        for (const item of prepared) {
+            if (item.alreadyImported) {
+                receiptSkipped += 1;
+                continue;
+            }
+            try {
+                const session = await pruneSession(item.candidate.path, format, {
+                    plan: item,
+                    metadata: item.candidate.metadata,
+                });
+                const result = await uploadAgentSession({
+                    apiBaseUrl: args.apiBaseUrl,
+                    apiKey,
+                    source: format.source,
+                    session,
+                    visibility: args.visibility,
+                });
+                if (result.duplicate)
+                    duplicate += 1;
+                else
+                    imported += 1;
+                saveReceipt(context, receipts, item.receiptKey, result.sessionId);
+            }
+            catch (error) {
+                failures.push({
+                    path: item.candidate.path,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        const result = {
+            imported,
+            duplicate,
+            skipped: receiptSkipped + discovery.skipped.length,
+            failed: failures,
+            sessionsUrl: args.apiBaseUrl.replace(/\/api$/, "/sessions"),
+            plan,
+        };
+        if (args.json)
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        else
+            process.stdout.write(`Imported ${imported}; duplicates ${duplicate}; skipped ${result.skipped}; failed ${failures.length}.\n${result.sessionsUrl}\n`);
+        if (failures.length)
+            process.exitCode = 1;
+    }
+    finally {
+        discovery.cleanup?.();
+    }
+}

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

@@ -0,0 +1,14 @@
+import type { AgentSessionSource, ImportVisibility, PrunedAgentSession } from "./types.js";
+type ImportResponse = Readonly<{
+    duplicate: boolean;
+    sessionId: string;
+}>;
+export declare function uploadAgentSession(input: {
+    apiBaseUrl: string;
+    apiKey: string;
+    source: AgentSessionSource;
+    session: PrunedAgentSession;
+    visibility: ImportVisibility;
+    fetch?: typeof globalThis.fetch;
+}): Promise<ImportResponse>;
+export {};

package/dist/session-import/client.js

@@ -0,0 +1,74 @@
+import { CANONICALIZATION_VERSION } from "./canonical.js";
+function retryable(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+function retryDelay(response, attempt) {
+    const retryAfter = response.headers.get("retry-after");
+    if (retryAfter && /^\d+$/.test(retryAfter))
+        return Math.min(Number(retryAfter) * 1000, 10_000);
+    return 250 * 2 ** attempt;
+}
+function wait(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+async function responseError(response) {
+    try {
+        const body = await response.json();
+        if (body && typeof body === "object" && "error" in body && typeof body.error === "string")
+            return body.error;
+    }
+    catch {
+        // Fall through to the status text.
+    }
+    return response.statusText || `HTTP ${response.status}`;
+}
+export async function uploadAgentSession(input) {
+    const request = input.fetch ?? globalThis.fetch;
+    let lastError = null;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            const response = await request(`${input.apiBaseUrl}/sessions/imports`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/vnd.groundtrack.session+jsonl; version=1",
+                    "x-api-key": input.apiKey,
+                    "x-groundtrack-canonicalization": String(CANONICALIZATION_VERSION),
+                    "x-groundtrack-content-hash": input.session.sourceContentHash,
+                    "x-groundtrack-session-source": input.source,
+                    "x-groundtrack-visibility": input.visibility,
+                },
+                body: input.session.bytes,
+                signal: AbortSignal.timeout(300_000),
+            });
+            if (!response.ok) {
+                const error = new Error(`Import failed (${response.status}): ${await responseError(response)}`);
+                if (!retryable(response.status) || attempt === 2)
+                    throw error;
+                await wait(retryDelay(response, attempt));
+                lastError = error;
+                continue;
+            }
+            const body = await response.json();
+            if (!body ||
+                typeof body !== "object" ||
+                !("duplicate" in body) ||
+                typeof body.duplicate !== "boolean" ||
+                !("session" in body) ||
+                !body.session ||
+                typeof body.session !== "object" ||
+                !("id" in body.session) ||
+                typeof body.session.id !== "string")
+                throw new Error("Import endpoint returned an invalid response.");
+            return { duplicate: body.duplicate, sessionId: body.session.id };
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt === 2 ||
+                (lastError.message.startsWith("Import failed") &&
+                    !/\((408|429|5\d\d)\)/.test(lastError.message)))
+                throw lastError;
+            await wait(250 * 2 ** attempt);
+        }
+    }
+    throw lastError ?? new Error("Import failed.");
+}

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

@@ -0,0 +1,10 @@
+import { type CanonicalSessionEntry, type CanonicalSessionMetadata, type SessionRecord } from "./canonical.js";
+import { type SessionImportFormat, type SessionNormalizer } from "./format.js";
+type UnknownRecord = SessionRecord;
+export declare function isSensitiveCodexRecord(record: UnknownRecord): boolean;
+export declare function isKnownSkippedCodexRecord(record: UnknownRecord): boolean;
+export declare function normalizeCodexResponseItem(record: UnknownRecord): CanonicalSessionEntry | null;
+export declare function codexSessionMetadata(record: UnknownRecord): Omit<CanonicalSessionMetadata, "model" | "startedAt" | "endedAt" | "statistics"> | null;
+export declare function createCodexSessionNormalizer(): SessionNormalizer;
+export declare const codexSessionFormat: SessionImportFormat;
+export {};

package/dist/session-import/codex.js

@@ -0,0 +1,187 @@
+import { containsInternalInstructionText, redactCredentialText, sanitizeRepositoryUrl, sanitizeSessionValue, sanitizeWorkingDirectory, } from "./redaction.js";
+import { isSessionRecord, sessionString, } from "./canonical.js";
+import { sessionImportFormatIdentity, } from "./format.js";
+function messageText(content) {
+    if (!Array.isArray(content))
+        return null;
+    const text = content
+        .filter(isSessionRecord)
+        .filter((part) => part.type === "input_text" || part.type === "output_text")
+        .map((part) => sessionString(part.text))
+        .filter((part) => part !== null)
+        .join("\n");
+    return text ? sanitizeSessionValue(text) : null;
+}
+function messageContainsInternalInstructions(payload) {
+    if (!Array.isArray(payload.content))
+        return false;
+    return payload.content
+        .filter(isSessionRecord)
+        .map((part) => sessionString(part.text) ?? "")
+        .some(containsInternalInstructionText);
+}
+export function isSensitiveCodexRecord(record) {
+    const type = sessionString(record.type);
+    const payload = isSessionRecord(record.payload) ? record.payload : {};
+    const payloadType = sessionString(payload.type);
+    const role = sessionString(payload.role);
+    return (type === "turn_context" ||
+        type === "world_state" ||
+        type === "compacted" ||
+        type === "inter_agent_communication_metadata" ||
+        payloadType === "reasoning" ||
+        payloadType === "agent_reasoning" ||
+        payloadType === "agent_message" ||
+        role === "system" ||
+        role === "developer" ||
+        (type === "response_item" &&
+            payloadType === "message" &&
+            messageContainsInternalInstructions(payload)));
+}
+export function isKnownSkippedCodexRecord(record) {
+    const type = sessionString(record.type);
+    const payload = isSessionRecord(record.payload) ? record.payload : {};
+    return (type === "session_meta" ||
+        type === "token_usage_record" ||
+        type === "event_msg" ||
+        sessionString(payload.type) === "reasoning");
+}
+function structuredValue(value) {
+    if (typeof value !== "string")
+        return sanitizeSessionValue(value);
+    try {
+        return sanitizeSessionValue(JSON.parse(value));
+    }
+    catch {
+        return sanitizeSessionValue(value);
+    }
+}
+export function normalizeCodexResponseItem(record) {
+    if (record.type !== "response_item" || !isSessionRecord(record.payload))
+        return null;
+    const payload = record.payload;
+    const payloadType = sessionString(payload.type);
+    const role = sessionString(payload.role);
+    const occurredAt = sessionString(record.timestamp);
+    if (payloadType === "message") {
+        if ((role !== "user" && role !== "assistant") || messageContainsInternalInstructions(payload))
+            return null;
+        const text = messageText(payload.content);
+        if (!text)
+            return null;
+        const phase = role === "assistant" ? sessionString(payload.phase) : null;
+        return {
+            kind: role === "user" ? "user_message" : "assistant_message",
+            occurredAt,
+            payload: {
+                text,
+                ...(phase ? { phase } : {}),
+            },
+        };
+    }
+    if (payloadType === "custom_tool_call" || payloadType === "function_call") {
+        const toolName = sessionString(payload.name);
+        if (!toolName)
+            return null;
+        return {
+            kind: "tool_call",
+            occurredAt,
+            payload: {
+                callId: sessionString(payload.call_id),
+                toolName,
+                input: structuredValue(payload.input ?? payload.arguments),
+            },
+        };
+    }
+    if (payloadType === "custom_tool_call_output" || payloadType === "function_call_output") {
+        return {
+            kind: "tool_result",
+            occurredAt,
+            payload: {
+                callId: sessionString(payload.call_id),
+                output: structuredValue(payload.output),
+            },
+        };
+    }
+    return null;
+}
+export function codexSessionMetadata(record) {
+    if (record.type !== "session_meta" || !isSessionRecord(record.payload))
+        return null;
+    const payload = record.payload;
+    const git = isSessionRecord(payload.git) ? payload.git : {};
+    const externalSessionId = sessionString(payload.session_id) ?? sessionString(payload.id);
+    if (!externalSessionId)
+        return null;
+    const originator = sessionString(payload.originator);
+    return {
+        type: "session",
+        version: 1,
+        externalSessionId,
+        repositoryUrl: sanitizeRepositoryUrl(git.repository_url),
+        repositoryBranch: sessionString(git.branch),
+        repositoryCommitSha: sessionString(git.commit_hash),
+        workingDirectory: sanitizeWorkingDirectory(payload.cwd),
+        originator: originator ? redactCredentialText(originator) : null,
+    };
+}
+export function createCodexSessionNormalizer() {
+    let metadata = null;
+    let model = null;
+    return {
+        normalizeRecord: (record) => {
+            metadata ??= codexSessionMetadata(record);
+            if (record.type === "turn_context" && isSessionRecord(record.payload))
+                model ??= sessionString(record.payload.model);
+            if (isSensitiveCodexRecord(record))
+                return { entries: [], sensitive: true, unsupported: false };
+            const entry = normalizeCodexResponseItem(record);
+            if (entry)
+                return { entries: [entry], sensitive: false, unsupported: false };
+            return {
+                entries: [],
+                sensitive: false,
+                unsupported: !isKnownSkippedCodexRecord(record),
+            };
+        },
+        canonicalMetadata: () => (metadata ? { ...metadata, model } : null),
+    };
+}
+function isSubagentMetadata(payload) {
+    if (sessionString(payload.parent_thread_id) || sessionString(payload.agent_path))
+        return true;
+    if (isSessionRecord(payload.source) && "subagent" in payload.source)
+        return true;
+    return ["subagent", "agent_forked_thread", "guardian_review"].includes(sessionString(payload.thread_source) ?? "");
+}
+function discoveryMetadata(record) {
+    if (record.type !== "session_meta" || !isSessionRecord(record.payload))
+        return null;
+    const payload = record.payload;
+    const git = isSessionRecord(payload.git) ? payload.git : {};
+    const externalSessionId = sessionString(payload.session_id) ?? sessionString(payload.id);
+    if (!externalSessionId)
+        return null;
+    const timestampValue = sessionString(payload.timestamp) ?? sessionString(record.timestamp);
+    const timestamp = timestampValue ? new Date(timestampValue) : null;
+    return {
+        externalSessionId,
+        timestamp: timestamp && !Number.isNaN(timestamp.getTime()) ? timestamp : null,
+        cwd: sessionString(payload.cwd),
+        repositoryUrl: sessionString(git.repository_url),
+        repositoryBranch: sessionString(git.branch),
+        repositoryCommitSha: sessionString(git.commit_hash),
+        originator: sessionString(payload.originator),
+        isSubagent: isSubagentMetadata(payload),
+    };
+}
+export const codexSessionFormat = {
+    ...sessionImportFormatIdentity("codex"),
+    discovery: "files",
+    homeEnvironmentVariable: "CODEX_HOME",
+    defaultHomeDirectory: ".codex",
+    discoveryRecordLimit: 1,
+    sessionRoots: (home) => [`${home}/sessions`, `${home}/archived_sessions`],
+    parseDiscoveryMetadata: (records) => (records[0] ? discoveryMetadata(records[0]) : null),
+    createNormalizer: createCodexSessionNormalizer,
+};

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

@@ -0,0 +1,13 @@
+import { type SessionDiscoveryCandidates, type SessionDiscoveryContext, type SessionImportFormat, type SessionNormalizer } from "./format.js";
+import type { AgentSessionMetadata } from "./types.js";
+type CursorHeader = Readonly<{
+    composerId: unknown;
+    createdAt: unknown;
+    lastUpdatedAt: unknown;
+    isSubagent: unknown;
+    workingDirectory: unknown;
+}>;
+export declare function cursorCandidates(context: SessionDiscoveryContext, headers?: readonly CursorHeader[]): SessionDiscoveryCandidates;
+export declare function createCursorSessionNormalizer(metadata?: AgentSessionMetadata): SessionNormalizer;
+export declare const cursorSessionFormat: SessionImportFormat;
+export {};