@groundtrack/hooks 0.1.8 → 0.1.10

package/README.md

@@ -87,16 +87,54 @@ The lower-level `runDoctor` API remains for existing consumers. New setup uses
 client-specific plans for MCP, hooks/plugins, and instructions, so it can preview
 and repair several selected agents safely.
 
+## Import coding-agent sessions
+
+Import completed Codex, Claude Code, Cursor, or OpenCode sessions with an API key created in Groundtrack
+Settings. The default scope is the current Git repository; subagents and files modified
+in the last five minutes are excluded. Groundtrack reads Codex sessions from `CODEX_HOME`
+(default `~/.codex`), Claude sessions from `CLAUDE_CONFIG_DIR` (default `~/.claude`),
+and Cursor transcripts from `CURSOR_HOME` (default `~/.cursor`). Cursor metadata comes from
+its local `state.vscdb`; set `CURSOR_STATE_DB` to override that database path. Cursor import
+is CLI-only and requires unflagged `node:sqlite` support (Node.js 22.13+, 23.4+, or 24+).
+OpenCode import invokes the installed `opencode` CLI (override it with `OPENCODE_BIN`) and uses
+private temporary files for its session inventory and exports. This avoids OpenCode's large piped
+export truncation while ensuring the unsanitized source export is removed after local pruning.
+
+```sh
+GROUNDTRACK_API_KEY=... groundtrack import --dry-run
+GROUNDTRACK_API_KEY=... groundtrack import --yes
+GROUNDTRACK_API_KEY=... groundtrack import --agent claude --dry-run
+GROUNDTRACK_API_KEY=... groundtrack import --agent claude --all-repos --yes
+GROUNDTRACK_API_KEY=... groundtrack import --agent cursor --dry-run
+GROUNDTRACK_API_KEY=... groundtrack import --agent cursor --all-repos --yes
+GROUNDTRACK_API_KEY=... groundtrack import --agent opencode --dry-run
+GROUNDTRACK_API_KEY=... groundtrack import --agent opencode --all-repos --yes
+```
+
+The command streams source files through a deterministic privacy filter before upload.
+Reasoning, system/developer instructions, turn context other than the model name, and
+recognized credentials are removed locally. Uploads are sequential and retry only
+transient failures. Successful imports are recorded atomically under
+`$XDG_CONFIG_HOME/groundtrack`; receipts are scoped to the endpoint, API-key fingerprint,
+visibility, source hash, and canonicalization version. Use `--json` for one machine-readable
+result object and `--url` for a preview or self-hosted deployment.
+
+Imported transcripts are private by default. Groundtrack analyzes completed imports and may add
+high-confidence extracted lessons—not transcript content—to the organization's shared knowledge.
+Changing transcript visibility does not change this learning behavior; deleting an imported
+session retracts its derived knowledge.
+
 `templates/AGENTS.md` is the source of truth for the managed repository policy.
 After changing it, run `pnpm sync:agent-instructions`; tests reject drift between
 the setup guide, this repository's managed `AGENTS.md` block, and the packaged template.
 
 ## Development
 
-Agent IDs, names, aliases, event sources, and enrichment kinds are defined once in
-`src/agents.ts`, exported as `@groundtrack/hooks/agents`. The CLI, web UI, hooks,
-and server consume that catalog and its derived types. Keep it dependency-free
-so browser bundles can load it without the Node-only hook runtime.
+Agent IDs, names, aliases, event sources, enrichment kinds, and session-import
+capabilities are defined once in `src/agents.ts`, exported as
+`@groundtrack/hooks/agents`. The CLI, web UI, hooks, and server consume that
+catalog and its derived types. Keep it dependency-free so browser bundles can
+load it without the Node-only hook runtime.
 
 Build and test the CLI from the repository:
 

package/dist/agents.d.ts

@@ -5,24 +5,56 @@ export declare const AGENTS: readonly [{
     readonly aliases: readonly ["claude-code"];
     readonly source: "claude_code";
     readonly enrichment: "command";
+    readonly sessionImport: {
+        readonly cli: true;
+        readonly web: {
+            readonly extension: ".jsonl";
+            readonly accept: ".jsonl";
+            readonly fileLabel: "Claude Code session JSONL";
+            readonly location: "~/.claude/projects/<project>/*.jsonl";
+        };
+    };
 }, {
     readonly id: "codex";
     readonly name: "Codex";
     readonly aliases: readonly [];
     readonly source: "codex";
     readonly enrichment: "command";
+    readonly sessionImport: {
+        readonly cli: true;
+        readonly web: {
+            readonly extension: ".jsonl";
+            readonly accept: ".jsonl";
+            readonly fileLabel: "Codex rollout JSONL";
+            readonly location: "~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl";
+        };
+    };
 }, {
     readonly id: "cursor";
     readonly name: "Cursor";
     readonly aliases: readonly [];
     readonly source: "cursor";
     readonly enrichment: "command";
+    readonly sessionImport: {
+        readonly cli: true;
+        readonly web: null;
+    };
 }, {
     readonly id: "opencode";
     readonly name: "OpenCode";
     readonly aliases: readonly [];
     readonly source: "opencode";
     readonly enrichment: "plugin";
+    readonly sessionImport: {
+        readonly cli: true;
+        readonly web: {
+            readonly extension: ".json";
+            readonly accept: ".json,application/json";
+            readonly fileLabel: "OpenCode session export JSON";
+            readonly location: "opencode export <session-id> --pure > opencode-session.json";
+            readonly note: "Use direct file redirection as shown. Do not add --sanitize; Groundtrack removes sensitive records during import.";
+        };
+    };
 }];
 export type AgentDefinition = (typeof AGENTS)[number];
 export type Agent = AgentDefinition["id"];
@@ -30,7 +62,30 @@ export type CommandHookAgent = Extract<AgentDefinition, {
     enrichment: "command";
 }>["id"];
 export declare const AGENT_IDS: ("claude" | "codex" | "cursor" | "opencode")[];
+export type SessionImportAgentDefinition = Extract<AgentDefinition, {
+    sessionImport: {
+        cli: true;
+    };
+}>;
+export type SessionImportAgent = SessionImportAgentDefinition["id"];
+export type AgentSessionSource = SessionImportAgentDefinition["source"];
+export type WebSessionImportAgentDefinition = Extract<SessionImportAgentDefinition, {
+    sessionImport: {
+        web: object;
+    };
+}>;
+export type WebSessionImportSource = WebSessionImportAgentDefinition["source"];
+export declare const SESSION_IMPORT_AGENTS: SessionImportAgentDefinition[];
+export declare const WEB_SESSION_IMPORT_AGENTS: WebSessionImportAgentDefinition[];
+export declare const WEB_SESSION_IMPORT_SOURCES: ("claude_code" | "codex" | "opencode")[];
+export declare const DEFAULT_SESSION_IMPORT_AGENT: SessionImportAgent;
+export declare const DEFAULT_WEB_SESSION_IMPORT_SOURCE: WebSessionImportSource;
 export declare function isAgent(value: unknown): value is Agent;
 export declare function resolveAgent(value: string): AgentDefinition | undefined;
+export declare function isSessionImportAgent(value: string): value is SessionImportAgent;
+export declare function normalizeAgentSessionSource(value: string): AgentSessionSource | undefined;
+export declare function isWebSessionImportSource(value: string): value is WebSessionImportSource;
+export declare function resolveSessionImportAgentFromSource(source: string | undefined): SessionImportAgentDefinition | undefined;
+export declare function webSessionImportAgentFromSource(source: WebSessionImportSource): WebSessionImportAgentDefinition;
 export declare function agentFromClientName(value: string | null | undefined): AgentDefinition | undefined;
 export declare function requiresHookRuntime(id: Agent): boolean;

package/dist/agents.js

@@ -6,18 +6,92 @@ export const AGENTS = [
         aliases: ["claude-code"],
         source: "claude_code",
         enrichment: "command",
+        sessionImport: {
+            cli: true,
+            web: {
+                extension: ".jsonl",
+                accept: ".jsonl",
+                fileLabel: "Claude Code session JSONL",
+                location: "~/.claude/projects/<project>/*.jsonl",
+            },
+        },
+    },
+    {
+        id: "codex",
+        name: "Codex",
+        aliases: [],
+        source: "codex",
+        enrichment: "command",
+        sessionImport: {
+            cli: true,
+            web: {
+                extension: ".jsonl",
+                accept: ".jsonl",
+                fileLabel: "Codex rollout JSONL",
+                location: "~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl",
+            },
+        },
+    },
+    {
+        id: "cursor",
+        name: "Cursor",
+        aliases: [],
+        source: "cursor",
+        enrichment: "command",
+        sessionImport: { cli: true, web: null },
+    },
+    {
+        id: "opencode",
+        name: "OpenCode",
+        aliases: [],
+        source: "opencode",
+        enrichment: "plugin",
+        sessionImport: {
+            cli: true,
+            web: {
+                extension: ".json",
+                accept: ".json,application/json",
+                fileLabel: "OpenCode session export JSON",
+                location: "opencode export <session-id> --pure > opencode-session.json",
+                note: "Use direct file redirection as shown. Do not add --sanitize; Groundtrack removes sensitive records during import.",
+            },
+        },
     },
-    { id: "codex", name: "Codex", aliases: [], source: "codex", enrichment: "command" },
-    { id: "cursor", name: "Cursor", aliases: [], source: "cursor", enrichment: "command" },
-    { id: "opencode", name: "OpenCode", aliases: [], source: "opencode", enrichment: "plugin" },
 ];
 export const AGENT_IDS = AGENTS.map((agent) => agent.id);
+export const SESSION_IMPORT_AGENTS = AGENTS.filter((agent) => agent.sessionImport.cli);
+export const WEB_SESSION_IMPORT_AGENTS = SESSION_IMPORT_AGENTS.filter((agent) => agent.sessionImport.web !== null);
+export const WEB_SESSION_IMPORT_SOURCES = WEB_SESSION_IMPORT_AGENTS.map((agent) => agent.source);
+export const DEFAULT_SESSION_IMPORT_AGENT = "codex";
+export const DEFAULT_WEB_SESSION_IMPORT_SOURCE = "codex";
 export function isAgent(value) {
     return AGENTS.some((agent) => agent.id === value);
 }
 export function resolveAgent(value) {
     return AGENTS.find((agent) => agent.id === value || agent.aliases.some((alias) => alias === value));
 }
+export function isSessionImportAgent(value) {
+    return SESSION_IMPORT_AGENTS.some((agent) => agent.id === value);
+}
+function isAgentSessionSource(value) {
+    return SESSION_IMPORT_AGENTS.some((agent) => agent.source === value);
+}
+export function normalizeAgentSessionSource(value) {
+    const source = value === "codex_cli" ? "codex" : value;
+    return isAgentSessionSource(source) ? source : undefined;
+}
+export function isWebSessionImportSource(value) {
+    return WEB_SESSION_IMPORT_AGENTS.some((agent) => agent.source === value);
+}
+export function resolveSessionImportAgentFromSource(source) {
+    return SESSION_IMPORT_AGENTS.find((agent) => agent.source === source);
+}
+export function webSessionImportAgentFromSource(source) {
+    const agent = WEB_SESSION_IMPORT_AGENTS.find((candidate) => candidate.source === source);
+    if (!agent)
+        throw new Error(`Unsupported web session import source: ${source}`);
+    return agent;
+}
 export function agentFromClientName(value) {
     const normalized = value?.trim().toLowerCase() ?? "";
     return AGENTS.find((agent) => normalized.includes(agent.id));

package/dist/groundtrack.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 import { runCli } from "./setup/cli.js";
-runCli(process.argv.slice(2)).catch((error) => {
-    const message = error instanceof Error ? error.message : "Groundtrack setup failed.";
+import { runImportCli } from "./session-import/cli.js";
+const argv = process.argv.slice(2);
+const operation = argv[0] === "import" ? runImportCli(argv.slice(1)) : runCli(argv);
+operation.catch((error) => {
+    const message = error instanceof Error ? error.message : "Groundtrack command failed.";
     if (process.argv.includes("--json"))
         process.stdout.write(`${JSON.stringify({ error: message, applied: false })}\n`);
     else

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

@@ -0,0 +1,33 @@
+export declare const CANONICALIZATION_VERSION = 1;
+export declare const CANONICAL_IMPORT_MAX_BYTES: number;
+export declare const CANONICAL_IMPORT_MAX_RECORD_BYTES: number;
+export declare const CANONICAL_IMPORT_MAX_ENTRIES = 25000;
+export type SessionRecord = Record<string, unknown>;
+export type CanonicalSessionEntry = Readonly<{
+    kind: "user_message" | "assistant_message" | "tool_call" | "tool_result";
+    occurredAt: string | null;
+    payload: Record<string, unknown>;
+}>;
+export type CanonicalSessionMetadata = 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 SessionRecord;
+export declare function sessionString(value: unknown): string | null;

package/dist/session-import/canonical.js

@@ -0,0 +1,10 @@
+export const CANONICALIZATION_VERSION = 1;
+export const CANONICAL_IMPORT_MAX_BYTES = 50 * 1024 * 1024;
+export const CANONICAL_IMPORT_MAX_RECORD_BYTES = 4 * 1024 * 1024;
+export const CANONICAL_IMPORT_MAX_ENTRIES = 25_000;
+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;
+}

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

@@ -0,0 +1,20 @@
+import { type CanonicalSessionMetadata, type SessionRecord } from "./canonical.js";
+import { type SessionImportFormat, type SessionRecordNormalization } from "./format.js";
+import type { AgentSessionMetadata } from "./types.js";
+type ClaudeMetadata = Readonly<{
+    externalSessionId: string | null;
+    timestamp: Date | null;
+    cwd: string | null;
+    repositoryBranch: string | null;
+    model: string | null;
+    isSubagent: boolean;
+}>;
+export declare function parseClaudeDiscoveryMetadata(records: readonly SessionRecord[]): AgentSessionMetadata | null;
+export type ClaudeSessionNormalizer = Readonly<{
+    normalizeRecord(record: SessionRecord, entryBudget?: number): SessionRecordNormalization;
+    canonicalMetadata(): Omit<CanonicalSessionMetadata, "startedAt" | "endedAt" | "statistics"> | null;
+    metadata(): ClaudeMetadata;
+}>;
+export declare function createClaudeSessionNormalizer(): ClaudeSessionNormalizer;
+export declare const claudeSessionFormat: SessionImportFormat;
+export {};

package/dist/session-import/claude.js

@@ -0,0 +1,237 @@
+import { isSessionRecord, sessionString, } from "./canonical.js";
+import { sessionImportFormatIdentity, } from "./format.js";
+import { containsInternalInstructionText, redactCredentialText, sanitizeSessionValue, sanitizeWorkingDirectory, } from "./redaction.js";
+const knownSkippedRecordTypes = new Set([
+    "agent-name",
+    "ai-title",
+    "atis-latch",
+    "attachment",
+    "cost-state",
+    "file-history-delta",
+    "file-history-snapshot",
+    "last-prompt",
+    "mode",
+    "permission-mode",
+    "pr-link",
+    "progress",
+    "queue-operation",
+    "summary",
+]);
+function validDate(value) {
+    const text = sessionString(value);
+    if (!text)
+        return null;
+    const date = new Date(text);
+    return Number.isNaN(date.getTime()) ? null : date;
+}
+function structuredValue(value) {
+    if (typeof value !== "string")
+        return sanitizeSessionValue(value);
+    try {
+        return sanitizeSessionValue(JSON.parse(value));
+    }
+    catch {
+        return redactCredentialText(value);
+    }
+}
+function toolOutput(value) {
+    if (!Array.isArray(value))
+        return { output: structuredValue(value), unsupported: false };
+    const output = [];
+    let unsupported = false;
+    for (const part of value) {
+        if (!isSessionRecord(part)) {
+            unsupported = true;
+            continue;
+        }
+        const text = sessionString(part.text);
+        if (!text) {
+            unsupported = true;
+            continue;
+        }
+        output.push({
+            type: sessionString(part.type) ?? "text",
+            text: redactCredentialText(text),
+        });
+    }
+    return { output, unsupported };
+}
+function normalizeMessage(record, entryBudget = Number.POSITIVE_INFINITY) {
+    const type = sessionString(record.type);
+    if (type !== "user" && type !== "assistant")
+        return null;
+    const message = isSessionRecord(record.message) ? record.message : null;
+    if (!message || sessionString(message.role) !== type)
+        return null;
+    const occurredAt = validDate(record.timestamp)?.toISOString() ?? null;
+    const content = Array.isArray(message.content) ? message.content : [message.content];
+    const entries = [];
+    let sensitive = false;
+    let unsupported = false;
+    for (const block of content) {
+        if (entries.length > entryBudget)
+            break;
+        if (typeof block === "string") {
+            if (block && containsInternalInstructionText(block))
+                sensitive = true;
+            else if (block)
+                entries.push({
+                    kind: type === "user" ? "user_message" : "assistant_message",
+                    occurredAt,
+                    payload: { text: redactCredentialText(block) },
+                });
+            continue;
+        }
+        if (!isSessionRecord(block)) {
+            if (block != null)
+                unsupported = true;
+            continue;
+        }
+        const blockType = sessionString(block.type);
+        if (blockType === "thinking" || blockType === "redacted_thinking") {
+            sensitive = true;
+            continue;
+        }
+        if (blockType === "text") {
+            const text = sessionString(block.text);
+            if (text && containsInternalInstructionText(text))
+                sensitive = true;
+            else if (text)
+                entries.push({
+                    kind: type === "user" ? "user_message" : "assistant_message",
+                    occurredAt,
+                    payload: { text: redactCredentialText(text) },
+                });
+            continue;
+        }
+        if (type === "assistant" && blockType === "tool_use") {
+            const toolName = sessionString(block.name);
+            if (toolName)
+                entries.push({
+                    kind: "tool_call",
+                    occurredAt,
+                    payload: {
+                        callId: sessionString(block.id),
+                        toolName,
+                        input: structuredValue(block.input),
+                    },
+                });
+            else
+                unsupported = true;
+            continue;
+        }
+        if (type === "user" && blockType === "tool_result") {
+            const result = toolOutput(block.content);
+            unsupported ||= result.unsupported;
+            entries.push({
+                kind: "tool_result",
+                occurredAt,
+                payload: {
+                    callId: sessionString(block.tool_use_id),
+                    output: result.output,
+                    ...(typeof block.is_error === "boolean" ? { isError: block.is_error } : {}),
+                },
+            });
+        }
+        else
+            unsupported = true;
+    }
+    const overflowed = entries.length > entryBudget;
+    return {
+        entries: overflowed ? entries.slice(0, entryBudget) : entries,
+        sensitive,
+        unsupported,
+        overflowed,
+    };
+}
+function emptyMetadata() {
+    return {
+        externalSessionId: null,
+        timestamp: null,
+        cwd: null,
+        repositoryBranch: null,
+        model: null,
+        isSubagent: false,
+    };
+}
+function mergeMetadata(metadata, record) {
+    metadata.externalSessionId ??=
+        sessionString(record.sessionId) ?? sessionString(record.session_id);
+    metadata.timestamp ??= validDate(record.timestamp);
+    metadata.cwd ??= sessionString(record.cwd);
+    metadata.repositoryBranch ??= sessionString(record.gitBranch);
+    metadata.isSubagent ||= record.isSidechain === true || sessionString(record.agentId) !== null;
+    if (record.type === "assistant" && isSessionRecord(record.message))
+        metadata.model ??= sessionString(record.message.model);
+}
+function collectMetadata(records) {
+    const metadata = emptyMetadata();
+    for (const record of records)
+        mergeMetadata(metadata, record);
+    return metadata;
+}
+export function parseClaudeDiscoveryMetadata(records) {
+    const metadata = collectMetadata(records);
+    if (!metadata.externalSessionId)
+        return null;
+    return {
+        externalSessionId: metadata.externalSessionId,
+        timestamp: metadata.timestamp,
+        cwd: metadata.cwd,
+        repositoryUrl: null,
+        repositoryBranch: metadata.repositoryBranch,
+        repositoryCommitSha: null,
+        originator: null,
+        isSubagent: metadata.isSubagent,
+    };
+}
+export function createClaudeSessionNormalizer() {
+    const metadata = emptyMetadata();
+    return {
+        normalizeRecord: (record, entryBudget) => {
+            mergeMetadata(metadata, record);
+            if (record.type === "system" || record.isMeta === true)
+                return { entries: [], sensitive: true, unsupported: false };
+            const type = sessionString(record.type);
+            if (type !== "user" && type !== "assistant")
+                return {
+                    entries: [],
+                    sensitive: false,
+                    unsupported: !type || !knownSkippedRecordTypes.has(type),
+                };
+            return (normalizeMessage(record, entryBudget) ?? {
+                entries: [],
+                sensitive: false,
+                unsupported: true,
+            });
+        },
+        canonicalMetadata: () => {
+            if (!metadata.externalSessionId)
+                return null;
+            return {
+                type: "session",
+                version: 1,
+                externalSessionId: metadata.externalSessionId,
+                repositoryUrl: null,
+                repositoryBranch: metadata.repositoryBranch
+                    ? redactCredentialText(metadata.repositoryBranch)
+                    : null,
+                repositoryCommitSha: null,
+                workingDirectory: sanitizeWorkingDirectory(metadata.cwd),
+                originator: null,
+                model: metadata.model ? redactCredentialText(metadata.model) : null,
+            };
+        },
+        metadata: () => ({ ...metadata }),
+    };
+}
+export const claudeSessionFormat = {
+    ...sessionImportFormatIdentity("claude"),
+    discovery: "files",
+    homeEnvironmentVariable: "CLAUDE_CONFIG_DIR",
+    defaultHomeDirectory: ".claude",
+    discoveryRecordLimit: 16,
+    sessionRoots: (home) => [`${home}/projects`],
+    parseDiscoveryMetadata: parseClaudeDiscoveryMetadata,
+    createNormalizer: createClaudeSessionNormalizer,
+};

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

@@ -0,0 +1,22 @@
+import type { ImportAgent, ImportVisibility } from "./types.js";
+export declare const IMPORT_USAGE: string;
+type ImportArguments = Readonly<{
+    agent: ImportAgent;
+    repoDir?: string;
+    homeDir?: string;
+    allRepositories: boolean;
+    includeUnscoped: boolean;
+    includeSubagents: boolean;
+    visibility: ImportVisibility;
+    since: Date | null;
+    dryRun: boolean;
+    yes: boolean;
+    json: boolean;
+    apiKey?: string;
+    apiBaseUrl: string;
+    help: boolean;
+}>;
+export declare function normalizeApiBaseUrl(value: string): string;
+export declare function parseImportArguments(argv: readonly string[]): ImportArguments;
+export declare function runImportCli(argv: readonly string[]): Promise<void>;
+export {};