@groundtrack/hooks 0.1.9 → 0.1.11

package/dist/session-import/cli.js

@@ -1,21 +1,26 @@
 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 { uploadCodexSession } from "./client.js";
-import { discoverCodexSessions, normalizeRepositoryUrl, repositoryIdentity } from "./discovery.js";
-import { pruneCodexSession } from "./prune.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";
-import { CODEX_CANONICAL_IMPORT_MAX_BYTES } from "./codex.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 codex] [--repo PATH | --all-repos] [--since DATE]
+  groundtrack import [--agent ${importAgentChoices}] [--repo PATH | --all-repos] [--since DATE]
                      [--include-subagents] [--include-unscoped]
                      [--visibility private|organization] [--dry-run] [--yes] [--json]
 
 Import options:
-  --agent codex          Session format to discover (default: codex)
+  --agent VALUE          ${importAgentDescription} (default: ${DEFAULT_SESSION_IMPORT_AGENT})
   --repo PATH            Import sessions for this Git repository (default: current repository)
-  --all-repos            Import sessions carrying repository metadata
-  --include-unscoped     With --all-repos, also import sessions without repository metadata
+  --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
@@ -53,6 +58,7 @@ export function parseImportArguments(argv) {
     };
     let repoDir;
     let homeDir;
+    let agent = DEFAULT_SESSION_IMPORT_AGENT;
     let allRepositories = false;
     let includeUnscoped = false;
     let includeSubagents = false;
@@ -67,9 +73,10 @@ export function parseImportArguments(argv) {
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg === "--agent") {
-            const agent = valueAfter(index++, arg);
-            if (agent !== "codex")
-                throw new Error("Session import currently supports --agent codex.");
+            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);
@@ -109,6 +116,7 @@ export function parseImportArguments(argv) {
     if (includeUnscoped && !allRepositories)
         throw new Error("Use --include-unscoped together with --all-repos.");
     return {
+        agent,
         repoDir,
         homeDir,
         allRepositories,
@@ -148,8 +156,10 @@ function printPlan(input) {
         .map((item) => item.candidate.metadata.timestamp?.getTime())
         .filter((value) => value !== undefined);
     process.stdout.write([
-        `\nGroundtrack · import Codex sessions`,
+        `\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
             ? [
@@ -194,142 +204,162 @@ export async function runImportCli(argv) {
         return;
     }
     const context = environment({ repoDir: args.repoDir, homeDir: args.homeDir });
-    const codexHome = resolve(context.env.CODEX_HOME || resolve(context.homeDir, ".codex"));
+    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 = discoverCodexSessions({
-        codexHome,
+    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,
     });
-    const apiKey = args.apiKey ?? context.env.GROUNDTRACK_API_KEY;
-    const receipts = apiKey ? readReceipts(context) : { version: 1, receipts: {} };
-    const prepared = [];
-    const preparationErrors = [];
-    for (const candidate of discovery.included) {
-        try {
-            const pruned = await pruneCodexSession(candidate.path, { emitBytes: false });
-            if (pruned.prunedBytes > CODEX_CANONICAL_IMPORT_MAX_BYTES)
-                throw new Error(`Pruned session exceeds ${formatBytes(CODEX_CANONICAL_IMPORT_MAX_BYTES)}`);
-            const key = apiKey
-                ? receiptKey({
-                    apiBaseUrl: args.apiBaseUrl,
-                    apiKey,
-                    sourceContentHash: pruned.sourceContentHash,
-                    visibility: args.visibility,
-                })
-                : null;
-            prepared.push({
-                candidate,
-                sourceContentHash: pruned.sourceContentHash,
-                prunedBytes: pruned.prunedBytes,
-                originalBytes: pruned.originalBytes,
-                receiptKey: key,
-                alreadyImported: Boolean(key && receipts.receipts[key]),
-            });
+    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),
+                });
+            }
         }
-        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 scope = args.allRepositories ? "all repositories" : repository.root;
-    const plan = {
-        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
+        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 (preparationErrors.length)
-            process.exitCode = 1;
-        return;
-    }
-    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !args.json);
-    if (!args.json)
-        printPlan({
-            scope,
-            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} Codex 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 pruneCodexSession(item.candidate.path);
-            if (session.sourceContentHash !== item.sourceContentHash ||
-                session.prunedBytes !== item.prunedBytes)
-                throw new Error("Session changed after the import plan was created.");
-            const result = await uploadCodexSession({
-                apiBaseUrl: args.apiBaseUrl,
-                apiKey,
-                session,
-                visibility: args.visibility,
+        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 (result.duplicate)
-                duplicate += 1;
-            else
-                imported += 1;
-            saveReceipt(context, receipts, item.receiptKey, result.sessionId);
+            if (prompts.isCancel(approved) || !approved) {
+                prompts.cancel("Nothing uploaded.");
+                return;
+            }
         }
-        catch (error) {
-            failures.push({
-                path: item.candidate.path,
-                error: error instanceof Error ? error.message : String(error),
-            });
+        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?.();
     }
-    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;
 }

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

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

package/dist/session-import/client.js

@@ -1,4 +1,4 @@
-import { CODEX_CANONICALIZATION_VERSION } from "./codex.js";
+import { CANONICALIZATION_VERSION } from "./canonical.js";
 function retryable(status) {
     return status === 408 || status === 429 || status >= 500;
 }
@@ -22,7 +22,7 @@ async function responseError(response) {
     }
     return response.statusText || `HTTP ${response.status}`;
 }
-export async function uploadCodexSession(input) {
+export async function uploadAgentSession(input) {
     const request = input.fetch ?? globalThis.fetch;
     let lastError = null;
     for (let attempt = 0; attempt < 3; attempt += 1) {
@@ -32,8 +32,9 @@ export async function uploadCodexSession(input) {
                 headers: {
                     "content-type": "application/vnd.groundtrack.session+jsonl; version=1",
                     "x-api-key": input.apiKey,
-                    "x-groundtrack-canonicalization": String(CODEX_CANONICALIZATION_VERSION),
+                    "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,

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

@@ -1,37 +1,10 @@
-type UnknownRecord = Record<string, unknown>;
-export declare const CODEX_CANONICALIZATION_VERSION = 1;
-export declare const CODEX_CANONICAL_IMPORT_MAX_BYTES: number;
-export declare const CODEX_CANONICAL_IMPORT_MAX_RECORD_BYTES: number;
-export type CanonicalSessionEntry = Readonly<{
-    kind: "user_message" | "assistant_message" | "tool_call" | "tool_result";
-    occurredAt: string | null;
-    payload: Record<string, unknown>;
-}>;
-export type CanonicalCodexMetadata = Readonly<{
-    type: "session";
-    version: 1;
-    externalSessionId: string;
-    repositoryUrl: string | null;
-    repositoryBranch: string | null;
-    repositoryCommitSha: string | null;
-    workingDirectory: string | null;
-    originator: string | null;
-    model: string | null;
-    startedAt: string | null;
-    endedAt: string | null;
-    statistics: {
-        totalRecordCount: number;
-        importedEntryCount: number;
-        skippedRecordCount: number;
-        unsupportedRecordCount: number;
-        malformedRecordCount: number;
-        sensitiveRecordCount: number;
-    };
-}>;
-export declare function isSessionRecord(value: unknown): value is UnknownRecord;
-export declare function sessionString(value: unknown): string | null;
+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<CanonicalCodexMetadata, "model" | "startedAt" | "endedAt" | "statistics"> | 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

@@ -1,13 +1,6 @@
 import { containsInternalInstructionText, redactCredentialText, sanitizeRepositoryUrl, sanitizeSessionValue, sanitizeWorkingDirectory, } from "./redaction.js";
-export const CODEX_CANONICALIZATION_VERSION = 1;
-export const CODEX_CANONICAL_IMPORT_MAX_BYTES = 50 * 1024 * 1024;
-export const CODEX_CANONICAL_IMPORT_MAX_RECORD_BYTES = 4 * 1024 * 1024;
-export function isSessionRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-export function sessionString(value) {
-    return typeof value === "string" && value.length > 0 ? value : null;
-}
+import { isSessionRecord, sessionString, } from "./canonical.js";
+import { sessionImportFormatIdentity, } from "./format.js";
 function messageText(content) {
     if (!Array.isArray(content))
         return null;
@@ -132,3 +125,63 @@ export function codexSessionMetadata(record) {
         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 {};