cognitive-core 0.0.2 → 0.1.2

package/src/session-bank/git-reader.ts

@@ -0,0 +1,190 @@
+import { execFile } from 'node:child_process';
+
+// ─── EntireGitReader ────────────────────────────────────────────────
+// Low-level git plumbing for reading from the Entire orphan branch
+// without checking it out. Uses only git commands, no fs access.
+// ─────────────────────────────────────────────────────────────────────
+
+export interface GitReaderOptions {
+  repoPath: string;
+  branch?: string;
+}
+
+export class EntireGitReader {
+  private repoPath: string;
+  private branch: string;
+
+  constructor(options: GitReaderOptions) {
+    this.repoPath = options.repoPath;
+    this.branch = options.branch ?? 'entire/checkpoints/v1';
+  }
+
+  /** Check if the orphan branch exists in this repo */
+  async branchExists(): Promise<boolean> {
+    try {
+      await this.git(['rev-parse', '--verify', this.branch]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * List all checkpoint directories.
+   * Returns paths like ["a3/b2c4d5e6f7", "f1/0a9b8c7d6e5f", ...]
+   */
+  async listCheckpoints(): Promise<string[]> {
+    // First list shard directories (2-char hex prefixes)
+    let shardOutput: string;
+    try {
+      shardOutput = await this.git([
+        'ls-tree',
+        '--name-only',
+        this.branch,
+      ]);
+    } catch {
+      return [];
+    }
+
+    const shards = shardOutput
+      .split('\n')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+
+    // For each shard, list checkpoint subdirectories
+    const checkpoints: string[] = [];
+    for (const shard of shards) {
+      try {
+        const innerOutput = await this.git([
+          'ls-tree',
+          '--name-only',
+          this.branch,
+          shard + '/',
+        ]);
+        const entries = innerOutput
+          .split('\n')
+          .map((e) => e.trim())
+          .filter((e) => e.length > 0);
+        checkpoints.push(...entries);
+      } catch {
+        // Skip shards that fail to list
+      }
+    }
+
+    return checkpoints;
+  }
+
+  /**
+   * List session subdirectories within a checkpoint.
+   * Returns numeric session indices like ["0", "1"].
+   */
+  async listSessions(checkpointPath: string): Promise<string[]> {
+    try {
+      const output = await this.git([
+        'ls-tree',
+        '--name-only',
+        this.branch,
+        checkpointPath + '/',
+      ]);
+      return output
+        .split('\n')
+        .map((e) => e.trim())
+        .filter((e) => e.length > 0)
+        // Extract just the directory name from the full path
+        .map((e) => {
+          const parts = e.split('/');
+          return parts[parts.length - 1];
+        })
+        // Keep only numeric directories (sessions), skip "tasks", "metadata.json" etc.
+        .filter((e) => /^\d+$/.test(e));
+    } catch {
+      return [];
+    }
+  }
+
+  /** Read a single file from the orphan branch */
+  async readFile(path: string): Promise<string> {
+    return this.git(['show', `${this.branch}:${path}`]);
+  }
+
+  /**
+   * Read multiple files in batch.
+   * Returns Map<path, content>. Missing files are omitted.
+   */
+  async readFiles(paths: string[]): Promise<Map<string, string>> {
+    const result = new Map<string, string>();
+
+    // Use parallel readFile calls (git show is fast for individual files)
+    const settled = await Promise.allSettled(
+      paths.map(async (path) => {
+        const content = await this.readFileOrNull(path);
+        return { path, content };
+      }),
+    );
+
+    for (const entry of settled) {
+      if (entry.status === 'fulfilled' && entry.value.content !== null) {
+        result.set(entry.value.path, entry.value.content);
+      }
+    }
+
+    return result;
+  }
+
+  /** Read a file, returning null if it doesn't exist */
+  async readFileOrNull(path: string): Promise<string | null> {
+    try {
+      return await this.readFile(path);
+    } catch {
+      return null;
+    }
+  }
+
+  /** Get the HEAD commit SHA of the orphan branch */
+  async getBranchHead(): Promise<string | null> {
+    try {
+      const sha = await this.git(['rev-parse', this.branch]);
+      return sha.trim();
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Find the Entire-Checkpoint trailer value for a given commit.
+   * Returns the checkpoint ID or null.
+   */
+  async getCheckpointTrailer(commitSha: string): Promise<string | null> {
+    try {
+      const output = await this.git([
+        'log',
+        '--format=%(trailers:key=Entire-Checkpoint,valueonly)',
+        commitSha,
+        '-1',
+      ]);
+      const value = output.trim();
+      return value || null;
+    } catch {
+      return null;
+    }
+  }
+
+  // ── Private ──────────────────────────────────────────────────
+
+  private git(args: string[]): Promise<string> {
+    return new Promise((resolve, reject) => {
+      execFile(
+        'git',
+        ['-C', this.repoPath, ...args],
+        { maxBuffer: 100 * 1024 * 1024 }, // 100MB for large transcripts
+        (error, stdout, stderr) => {
+          if (error) {
+            reject(new Error(`git ${args[0]} failed: ${stderr || error.message}`));
+          } else {
+            resolve(stdout);
+          }
+        },
+      );
+    });
+  }
+}

package/src/session-bank/index.ts

@@ -0,0 +1,24 @@
+export { SessionBank } from './session-bank.js';
+export { EntireGitReader, type GitReaderOptions } from './git-reader.js';
+export {
+  EntireTranscriptParser,
+  type ParsedMetadata,
+} from './parser.js';
+export type {
+  SessionRecord,
+  SessionMetadata,
+  TranscriptMessage,
+  ContentBlock,
+  TextBlock,
+  ToolUseBlock,
+  ToolResultBlock,
+  SessionSummary,
+  TokenUsage,
+  Attribution,
+  SessionSource,
+  CheckpointRef,
+  SessionQuery,
+  SessionQueryResult,
+  ProcessingLogEntry,
+  SessionBankOptions,
+} from './types.js';

package/src/session-bank/parser.ts

@@ -0,0 +1,366 @@
+import type {
+  SessionRecord,
+  SessionMetadata,
+  TranscriptMessage,
+  ContentBlock,
+  SessionSummary,
+  TokenUsage,
+  Attribution,
+  CheckpointRef,
+} from './types.js';
+
+// ─── Raw Entire JSON shapes (snake_case, matching Go structs) ───────
+
+interface RawMetadata {
+  cli_version?: string;
+  checkpoint_id?: string;
+  session_id?: string;
+  strategy?: string;
+  created_at?: string;
+  branch?: string;
+  files_touched?: string[];
+  agent?: string;
+  is_task?: boolean;
+  tool_use_id?: string;
+  checkpoint_transcript_start?: number;
+  token_usage?: RawTokenUsage;
+  summary?: RawSummary;
+  initial_attribution?: RawAttribution;
+}
+
+interface RawTokenUsage {
+  input_tokens?: number;
+  cache_creation_tokens?: number;
+  cache_read_tokens?: number;
+  output_tokens?: number;
+  api_call_count?: number;
+  subagent_usage?: RawTokenUsage[];
+}
+
+interface RawSummary {
+  intent?: string;
+  outcome?: string;
+  learnings?: {
+    repo_patterns?: string[];
+    code_findings?: string[];
+    workflow_practices?: string[];
+  };
+  friction_points?: string[];
+  open_items?: string[];
+}
+
+interface RawAttribution {
+  agent_lines_added?: number;
+  human_additions?: number;
+  human_modifications?: number;
+  human_removals?: number;
+  total_committed_lines?: number;
+  agent_contribution?: number;
+}
+
+interface RawTranscriptLine {
+  type?: string;
+  uuid?: string;
+  message?: {
+    role?: string;
+    content?: string | RawContentBlock[];
+  };
+  // Real Entire CLI uses these for tool_result lines
+  tool_use_id?: string;
+  content?: string | RawContentBlock[];
+  is_error?: boolean;
+  timestamp?: string;
+}
+
+interface RawContentBlock {
+  type?: string;
+  text?: string;
+  id?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+  tool_use_id?: string;
+  content?: string;
+  is_error?: boolean;
+}
+
+interface RawCheckpointSummary {
+  sessions?: Array<{
+    metadata?: string;
+    transcript?: string;
+    context?: string;
+    content_hash?: string;
+    prompt?: string;
+  }>;
+}
+
+// ─── Parser ─────────────────────────────────────────────────────────
+
+export interface ParsedMetadata {
+  sessionId: string;
+  checkpointId: string;
+  metadata: SessionMetadata;
+  summary?: SessionSummary;
+  tokenUsage: TokenUsage;
+  attribution?: Attribution;
+}
+
+export class EntireTranscriptParser {
+  /**
+   * Parse a full session from its component files.
+   */
+  parseSession(
+    metadataJson: string,
+    transcriptJsonl: string,
+    checkpointPath: string,
+    sessionIndex: string,
+  ): SessionRecord {
+    const parsed = this.parseMetadata(metadataJson);
+    const transcript = this.parseTranscript(transcriptJsonl);
+
+    return {
+      sessionId: parsed.sessionId,
+      checkpointId: parsed.checkpointId,
+      metadata: parsed.metadata,
+      transcript,
+      summary: parsed.summary,
+      tokenUsage: parsed.tokenUsage,
+      attribution: parsed.attribution,
+      source: {
+        branch: 'entire/checkpoints/v1',
+        checkpointPath,
+        sessionIndex,
+      },
+    };
+  }
+
+  /**
+   * Parse per-session metadata.json (fast path — no transcript).
+   */
+  parseMetadata(metadataJson: string): ParsedMetadata {
+    const raw: RawMetadata = JSON.parse(metadataJson);
+
+    const tokenUsage = this.parseTokenUsage(raw.token_usage);
+    const summary = raw.summary ? this.parseSummary(raw.summary) : undefined;
+    const attribution = raw.initial_attribution
+      ? this.parseAttribution(raw.initial_attribution)
+      : undefined;
+
+    return {
+      sessionId: raw.session_id ?? '',
+      checkpointId: raw.checkpoint_id ?? '',
+      metadata: {
+        cliVersion: raw.cli_version ?? '',
+        strategy: raw.strategy === 'auto-commit' ? 'auto-commit' : 'manual-commit',
+        createdAt: raw.created_at ? new Date(raw.created_at) : new Date(0),
+        branch: raw.branch ?? '',
+        agent: raw.agent ?? '',
+        filesTouched: raw.files_touched ?? [],
+        isTask: raw.is_task ?? false,
+        toolUseId: raw.tool_use_id,
+        checkpointTranscriptStart: raw.checkpoint_transcript_start ?? 0,
+      },
+      summary,
+      tokenUsage,
+      attribution,
+    };
+  }
+
+  /**
+   * Parse a JSONL transcript into structured messages.
+   * Tolerant of malformed lines — skips them silently.
+   */
+  parseTranscript(jsonlContent: string): TranscriptMessage[] {
+    const messages: TranscriptMessage[] = [];
+    const lines = jsonlContent.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (!line) continue;
+
+      try {
+        const raw: RawTranscriptLine = JSON.parse(line);
+        const msg = this.parseTranscriptLine(raw, i);
+        if (msg) messages.push(msg);
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    return messages;
+  }
+
+  /**
+   * Parse chunked transcripts (full.jsonl.001, .002, etc.)
+   */
+  parseChunkedTranscript(chunks: string[]): TranscriptMessage[] {
+    const combined = chunks.join('\n');
+    return this.parseTranscript(combined);
+  }
+
+  /**
+   * Parse the root checkpoint summary to discover session subdirectories.
+   */
+  parseCheckpointSummary(
+    metadataJson: string,
+    checkpointPath: string,
+  ): CheckpointRef {
+    const raw: RawCheckpointSummary = JSON.parse(metadataJson);
+    const sessions = raw.sessions ?? [];
+    const checkpointId = this.checkpointIdFromPath(checkpointPath);
+
+    return {
+      checkpointId,
+      sessionIds: [], // populated later from per-session metadata
+      path: checkpointPath,
+      sessionCount: sessions.length,
+    };
+  }
+
+  // ── Private helpers ──────────────────────────────────────────
+
+  private parseTranscriptLine(
+    raw: RawTranscriptLine,
+    lineIndex: number,
+  ): TranscriptMessage | null {
+    // Map Entire CLI's "human" → "user", keep "assistant" as-is.
+    // Also support the role field nested under message.role.
+    let role: 'user' | 'assistant';
+    if (raw.type === 'user' || raw.type === 'human') {
+      role = 'user';
+    } else if (raw.type === 'assistant') {
+      role = 'assistant';
+    } else if (raw.type === 'tool_result') {
+      // Real Entire CLI emits tool_result as a top-level JSONL line.
+      // Wrap it as a user message containing a tool_result block.
+      const toolResultBlock: ContentBlock = {
+        type: 'tool_result',
+        toolUseId: raw.tool_use_id ?? '',
+        content: typeof raw.content === 'string'
+          ? raw.content
+          : Array.isArray(raw.content)
+            ? raw.content
+                .filter((b) => b.type === 'text')
+                .map((b) => b.text ?? '')
+                .join('\n')
+            : '',
+        isError: raw.is_error,
+      };
+      return {
+        role: 'user',
+        uuid: raw.uuid ?? `line-${lineIndex}`,
+        content: [toolResultBlock],
+        lineIndex,
+      };
+    } else {
+      return null;
+    }
+
+    // UUID may not be present in real Entire CLI output
+    const uuid = raw.uuid ?? `line-${lineIndex}`;
+
+    const rawContent = raw.message?.content;
+    let content: ContentBlock[];
+
+    if (typeof rawContent === 'string') {
+      content = [{ type: 'text', text: rawContent }];
+    } else if (Array.isArray(rawContent)) {
+      content = rawContent
+        .map((block) => this.parseContentBlock(block))
+        .filter((b): b is ContentBlock => b !== null);
+    } else {
+      content = [];
+    }
+
+    return { role, uuid, content, lineIndex };
+  }
+
+  private parseContentBlock(raw: RawContentBlock): ContentBlock | null {
+    switch (raw.type) {
+      case 'text':
+        return { type: 'text', text: raw.text ?? '' };
+      case 'tool_use':
+        return {
+          type: 'tool_use',
+          id: raw.id ?? '',
+          name: raw.name ?? '',
+          input: raw.input ?? {},
+        };
+      case 'tool_result':
+        return {
+          type: 'tool_result',
+          toolUseId: raw.tool_use_id ?? '',
+          content: raw.content ?? '',
+          isError: raw.is_error,
+        };
+      default:
+        return null;
+    }
+  }
+
+  private parseTokenUsage(raw?: RawTokenUsage): TokenUsage {
+    if (!raw) {
+      return {
+        inputTokens: 0,
+        cacheCreationTokens: 0,
+        cacheReadTokens: 0,
+        outputTokens: 0,
+        apiCallCount: 0,
+        total: 0,
+      };
+    }
+
+    const inputTokens = raw.input_tokens ?? 0;
+    const cacheCreationTokens = raw.cache_creation_tokens ?? 0;
+    const cacheReadTokens = raw.cache_read_tokens ?? 0;
+    const outputTokens = raw.output_tokens ?? 0;
+    const apiCallCount = raw.api_call_count ?? 0;
+
+    const subagentUsage = raw.subagent_usage?.map((s) =>
+      this.parseTokenUsage(s),
+    );
+
+    return {
+      inputTokens,
+      cacheCreationTokens,
+      cacheReadTokens,
+      outputTokens,
+      apiCallCount,
+      subagentUsage,
+      total: inputTokens + cacheCreationTokens + cacheReadTokens + outputTokens,
+    };
+  }
+
+  private parseSummary(raw: RawSummary): SessionSummary {
+    return {
+      intent: raw.intent ?? '',
+      outcome: raw.outcome ?? '',
+      learnings: {
+        repoPatterns: raw.learnings?.repo_patterns ?? [],
+        codeFindings: raw.learnings?.code_findings ?? [],
+        workflowPractices: raw.learnings?.workflow_practices ?? [],
+      },
+      frictionPoints: raw.friction_points ?? [],
+      openItems: raw.open_items ?? [],
+    };
+  }
+
+  private parseAttribution(raw: RawAttribution): Attribution {
+    return {
+      agentLinesAdded: raw.agent_lines_added ?? 0,
+      humanAdditions: raw.human_additions ?? 0,
+      humanModifications: raw.human_modifications ?? 0,
+      humanRemovals: raw.human_removals ?? 0,
+      totalCommittedLines: raw.total_committed_lines ?? 0,
+      agentContribution: raw.agent_contribution ?? 0,
+    };
+  }
+
+  private checkpointIdFromPath(path: string): string {
+    // Path is "<shard>/<rest>" → checkpoint ID is shard + rest
+    const parts = path.split('/');
+    if (parts.length >= 2) {
+      return parts[0] + parts[1];
+    }
+    return path;
+  }
+}