cognitive-core 0.1.2 → 0.2.0

package/references/sessionlog/src/utils/todo-extract.ts

@@ -0,0 +1,188 @@
+/**
+ * Todo Extraction
+ *
+ * Parses TodoWrite tool_input JSON to extract todo content for
+ * incremental checkpoint commit messages.
+ *
+ * Ported from Go: strategy/messages.go
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface TodoItem {
+  content: string;
+  activeForm?: string;
+  status: string;
+}
+
+// ============================================================================
+// Extraction Functions
+// ============================================================================
+
+/**
+ * Extract the content of the last completed todo item from a todos JSON array.
+ * Returns the work that was just finished (used for commit messages).
+ *
+ * Returns empty string if no completed items exist or JSON is invalid.
+ */
+export function extractLastCompletedTodo(todosJSON: string | Buffer): string {
+  const todos = parseTodos(todosJSON);
+  if (!todos) return '';
+
+  let lastCompleted = '';
+  for (const todo of todos) {
+    if (todo.status === 'completed') {
+      lastCompleted = todo.content;
+    }
+  }
+  return lastCompleted;
+}
+
+/**
+ * Return the number of todo items in the JSON array.
+ * Returns 0 if the JSON is invalid or empty.
+ */
+export function countTodos(todosJSON: string | Buffer): number {
+  const todos = parseTodos(todosJSON);
+  return todos ? todos.length : 0;
+}
+
+/**
+ * Extract the content of the in-progress todo item from tool_input.
+ * Used for commit messages in incremental checkpoints.
+ *
+ * Priority order:
+ *  1. in_progress item (current work)
+ *  2. first pending item (next work - fallback)
+ *  3. last completed item (work just finished)
+ *  4. first item with unknown status (edge case)
+ *  5. empty string (no items)
+ */
+export function extractInProgressTodo(todosJSON: string | Buffer): string {
+  const todos = parseTodos(todosJSON);
+  if (!todos || todos.length === 0) return '';
+
+  // 1. in_progress item
+  for (const todo of todos) {
+    if (todo.status === 'in_progress') {
+      return todo.content;
+    }
+  }
+
+  // 2. first pending item
+  for (const todo of todos) {
+    if (todo.status === 'pending') {
+      return todo.content;
+    }
+  }
+
+  // 3. last completed item
+  let lastCompleted = '';
+  for (const todo of todos) {
+    if (todo.status === 'completed') {
+      lastCompleted = todo.content;
+    }
+  }
+  if (lastCompleted) return lastCompleted;
+
+  // 4. first item with content (unknown status edge case)
+  if (todos[0].content) return todos[0].content;
+
+  return '';
+}
+
+// ============================================================================
+// Tool Input Wrappers
+// ============================================================================
+
+/**
+ * Extract todo content from a TodoWrite tool_input object.
+ * Handles unwrapping the outer { todos: [...] } structure.
+ */
+export function extractTodoContentFromToolInput(toolInput: unknown): string {
+  const todosJSON = extractTodosArrayJSON(toolInput);
+  if (!todosJSON) return '';
+  return extractInProgressTodo(todosJSON);
+}
+
+/**
+ * Extract last completed todo from a TodoWrite tool_input object.
+ */
+export function extractLastCompletedTodoFromToolInput(toolInput: unknown): string {
+  const todosJSON = extractTodosArrayJSON(toolInput);
+  if (!todosJSON) return '';
+  return extractLastCompletedTodo(todosJSON);
+}
+
+/**
+ * Count todos from a TodoWrite tool_input object.
+ */
+export function countTodosFromToolInput(toolInput: unknown): number {
+  const todosJSON = extractTodosArrayJSON(toolInput);
+  if (!todosJSON) return 0;
+  return countTodos(todosJSON);
+}
+
+// ============================================================================
+// Formatting
+// ============================================================================
+
+/** Maximum length for descriptions in commit messages */
+const MAX_DESCRIPTION_LENGTH = 60;
+
+/**
+ * Format a commit message for an incremental checkpoint.
+ * Format: "<todo-content> (<tool-use-id>)"
+ * Fallback: "Checkpoint #<sequence>: <tool-use-id>"
+ */
+export function formatIncrementalMessage(
+  todoContent: string,
+  sequence: number,
+  toolUseID: string,
+): string {
+  if (!todoContent) {
+    return `Checkpoint #${sequence}: ${toolUseID}`;
+  }
+
+  const truncated = truncateDescription(todoContent, MAX_DESCRIPTION_LENGTH);
+  return `${truncated} (${toolUseID})`;
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+function parseTodos(todosJSON: string | Buffer): TodoItem[] | null {
+  try {
+    const str = typeof todosJSON === 'string' ? todosJSON : todosJSON.toString('utf-8');
+    if (!str) return null;
+    const parsed = JSON.parse(str) as unknown;
+    if (!Array.isArray(parsed)) return null;
+    return parsed as TodoItem[];
+  } catch {
+    return null;
+  }
+}
+
+function extractTodosArrayJSON(toolInput: unknown): string | null {
+  if (!toolInput || typeof toolInput !== 'object') return null;
+  const input = toolInput as Record<string, unknown>;
+  const todos = input.todos;
+  if (!Array.isArray(todos)) return null;
+  try {
+    return JSON.stringify(todos);
+  } catch {
+    return null;
+  }
+}
+
+function truncateDescription(s: string, maxLen: number): string {
+  const runes = [...s];
+  if (runes.length <= maxLen) return s;
+  const suffix = '...';
+  const suffixRunes = [...suffix];
+  const truncateAt = Math.max(0, maxLen - suffixRunes.length);
+  return runes.slice(0, truncateAt).join('') + suffix;
+}

package/references/sessionlog/src/utils/trailers.ts

@@ -0,0 +1,187 @@
+/**
+ * Commit Message Trailers
+ *
+ * Parsing and formatting for Sessionlog commit message trailers.
+ * Trailers are key-value metadata appended to git commit messages
+ * following the git trailer convention (key: value format after a blank line).
+ */
+
+import { CHECKPOINT_ID_PATTERN, type CheckpointID } from '../types.js';
+
+// ============================================================================
+// Trailer Key Constants
+// ============================================================================
+
+export const MetadataTrailerKey = 'Sessionlog-Metadata';
+export const MetadataTaskTrailerKey = 'Sessionlog-Metadata-Task';
+export const StrategyTrailerKey = 'Sessionlog-Strategy';
+export const BaseCommitTrailerKey = 'Base-Commit';
+export const SessionTrailerKey = 'Sessionlog-Session';
+export const CondensationTrailerKey = 'Sessionlog-Condensation';
+export const SourceRefTrailerKey = 'Sessionlog-Source-Ref';
+export const CheckpointTrailerKey = 'Sessionlog-Checkpoint';
+export const EphemeralBranchTrailerKey = 'Ephemeral-branch';
+export const AgentTrailerKey = 'Sessionlog-Agent';
+
+// ============================================================================
+// Pre-compiled Regex Patterns
+// ============================================================================
+
+const strategyTrailerRegex = new RegExp(`${StrategyTrailerKey}:\\s*(.+)`);
+const metadataTrailerRegex = new RegExp(`${MetadataTrailerKey}:\\s*(.+)`);
+const taskMetadataTrailerRegex = new RegExp(`${MetadataTaskTrailerKey}:\\s*(.+)`);
+const baseCommitTrailerRegex = new RegExp(`${BaseCommitTrailerKey}:\\s*([a-f0-9]{40})`);
+const condensationTrailerRegex = new RegExp(`${CondensationTrailerKey}:\\s*(.+)`);
+const sessionTrailerRegexSingle = new RegExp(`${SessionTrailerKey}:\\s*(.+)`);
+const checkpointTrailerRegex = new RegExp(`${CheckpointTrailerKey}:\\s*([0-9a-f]{12})(?:\\s|$)`);
+
+// ============================================================================
+// Parse Functions
+// ============================================================================
+
+export function parseStrategy(commitMessage: string): [string, boolean] {
+  const matches = strategyTrailerRegex.exec(commitMessage);
+  if (matches && matches[1]) {
+    return [matches[1].trim(), true];
+  }
+  return ['', false];
+}
+
+export function parseMetadata(commitMessage: string): [string, boolean] {
+  const matches = metadataTrailerRegex.exec(commitMessage);
+  if (matches && matches[1]) {
+    return [matches[1].trim(), true];
+  }
+  return ['', false];
+}
+
+export function parseTaskMetadata(commitMessage: string): [string, boolean] {
+  const matches = taskMetadataTrailerRegex.exec(commitMessage);
+  if (matches && matches[1]) {
+    return [matches[1].trim(), true];
+  }
+  return ['', false];
+}
+
+export function parseBaseCommit(commitMessage: string): [string, boolean] {
+  const matches = baseCommitTrailerRegex.exec(commitMessage);
+  if (matches && matches[1]) {
+    return [matches[1], true];
+  }
+  return ['', false];
+}
+
+export function parseCondensation(commitMessage: string): [string, boolean] {
+  const matches = condensationTrailerRegex.exec(commitMessage);
+  if (matches && matches[1]) {
+    return [matches[1].trim(), true];
+  }
+  return ['', false];
+}
+
+export function parseSession(commitMessage: string): [string, boolean] {
+  const matches = sessionTrailerRegexSingle.exec(commitMessage);
+  if (matches && matches[1]) {
+    return [matches[1].trim(), true];
+  }
+  return ['', false];
+}
+
+export function parseCheckpoint(commitMessage: string): [CheckpointID | null, boolean] {
+  const matches = checkpointTrailerRegex.exec(commitMessage);
+  if (matches && matches[1]) {
+    const idStr = matches[1].trim();
+    if (CHECKPOINT_ID_PATTERN.test(idStr)) {
+      return [idStr as CheckpointID, true];
+    }
+  }
+  return [null, false];
+}
+
+export function parseAllSessions(commitMessage: string): string[] {
+  const seen = new Set<string>();
+  const sessionIDs: string[] = [];
+  const regex = new RegExp(`${SessionTrailerKey}:\\s*(.+)`, 'g');
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(commitMessage)) !== null) {
+    if (match[1]) {
+      const sessionID = match[1].trim();
+      if (!seen.has(sessionID)) {
+        seen.add(sessionID);
+        sessionIDs.push(sessionID);
+      }
+    }
+  }
+  return sessionIDs;
+}
+
+// ============================================================================
+// Format Functions
+// ============================================================================
+
+export function formatStrategy(message: string, strategy: string): string {
+  return `${message}\n\n${StrategyTrailerKey}: ${strategy}\n`;
+}
+
+export function formatTaskMetadata(message: string, taskMetadataDir: string): string {
+  return `${message}\n\n${MetadataTaskTrailerKey}: ${taskMetadataDir}\n`;
+}
+
+export function formatTaskMetadataWithStrategy(
+  message: string,
+  taskMetadataDir: string,
+  strategy: string,
+): string {
+  return `${message}\n\n${MetadataTaskTrailerKey}: ${taskMetadataDir}\n${StrategyTrailerKey}: ${strategy}\n`;
+}
+
+export function formatSourceRef(branch: string, commitHash: string): string {
+  const shortHash = commitHash.length > 7 ? commitHash.slice(0, 7) : commitHash;
+  return `${branch}@${shortHash}`;
+}
+
+export function formatMetadata(message: string, metadataDir: string): string {
+  return `${message}\n\n${MetadataTrailerKey}: ${metadataDir}\n`;
+}
+
+export function formatMetadataWithStrategy(
+  message: string,
+  metadataDir: string,
+  strategy: string,
+): string {
+  return `${message}\n\n${MetadataTrailerKey}: ${metadataDir}\n${StrategyTrailerKey}: ${strategy}\n`;
+}
+
+export function formatShadowCommit(
+  message: string,
+  metadataDir: string,
+  sessionID: string,
+): string {
+  return [
+    message,
+    '',
+    `${MetadataTrailerKey}: ${metadataDir}`,
+    `${SessionTrailerKey}: ${sessionID}`,
+    `${StrategyTrailerKey}: manual-commit`,
+    '',
+  ].join('\n');
+}
+
+export function formatShadowTaskCommit(
+  message: string,
+  taskMetadataDir: string,
+  sessionID: string,
+): string {
+  return [
+    message,
+    '',
+    `${MetadataTaskTrailerKey}: ${taskMetadataDir}`,
+    `${SessionTrailerKey}: ${sessionID}`,
+    `${StrategyTrailerKey}: manual-commit`,
+    '',
+  ].join('\n');
+}
+
+export function formatCheckpoint(message: string, cpID: CheckpointID): string {
+  return `${message}\n\n${CheckpointTrailerKey}: ${cpID}\n`;
+}

package/references/sessionlog/src/utils/transcript-parse.ts

@@ -0,0 +1,177 @@
+/**
+ * Transcript Parsing
+ *
+ * Shared JSONL transcript parsing utilities used by agents
+ * that share the same format (Claude Code, Cursor).
+ */
+
+import { stripIDEContextTags } from './ide-tags.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export const TYPE_USER = 'user';
+export const TYPE_ASSISTANT = 'assistant';
+export const CONTENT_TYPE_TEXT = 'text';
+export const CONTENT_TYPE_TOOL_USE = 'tool_use';
+
+export interface TranscriptLine {
+  type: string;
+  role?: string;
+  uuid?: string;
+  message: unknown;
+}
+
+export interface UserMessage {
+  content: unknown;
+}
+
+export interface AssistantMessage {
+  content: ContentBlock[];
+}
+
+export interface ContentBlock {
+  type: string;
+  text?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+}
+
+export interface ToolInput {
+  file_path?: string;
+  notebook_path?: string;
+  description?: string;
+  command?: string;
+  pattern?: string;
+  skill?: string;
+  url?: string;
+  prompt?: string;
+}
+
+// ============================================================================
+// Parsing
+// ============================================================================
+
+/**
+ * Parse JSONL transcript content from a byte buffer.
+ */
+export function parseFromBytes(content: Buffer | string): TranscriptLine[] {
+  const text = typeof content === 'string' ? content : content.toString('utf-8');
+  const lines: TranscriptLine[] = [];
+
+  for (const rawLine of text.split('\n')) {
+    if (rawLine.trim().length === 0) continue;
+    try {
+      const line = JSON.parse(rawLine) as TranscriptLine;
+      normalizeLineType(line);
+      lines.push(line);
+    } catch {
+      // Skip malformed JSON lines
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * Parse JSONL transcript from a buffer starting from a specific line.
+ */
+export function parseFromBytesAtLine(
+  content: Buffer | string,
+  startLine: number,
+): TranscriptLine[] {
+  const text = typeof content === 'string' ? content : content.toString('utf-8');
+  const rawLines = text.split('\n');
+  const lines: TranscriptLine[] = [];
+
+  for (let i = startLine; i < rawLines.length; i++) {
+    const rawLine = rawLines[i];
+    if (rawLine.trim().length === 0) continue;
+    try {
+      const line = JSON.parse(rawLine) as TranscriptLine;
+      normalizeLineType(line);
+      lines.push(line);
+    } catch {
+      // Skip malformed
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * Normalize line type: Cursor uses "role" while Claude Code uses "type".
+ */
+function normalizeLineType(line: TranscriptLine): void {
+  if (!line.type && line.role) {
+    line.type = line.role;
+  }
+}
+
+/**
+ * Return bytes starting from line N (0-indexed).
+ */
+export function sliceFromLine(content: Buffer, startLine: number): Buffer {
+  if (content.length === 0 || startLine <= 0) {
+    return content;
+  }
+
+  let lineCount = 0;
+  let offset = 0;
+
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === 0x0a) {
+      // '\n'
+      lineCount++;
+      if (lineCount === startLine) {
+        offset = i + 1;
+        break;
+      }
+    }
+  }
+
+  if (lineCount < startLine) return Buffer.alloc(0);
+  if (offset >= content.length) return Buffer.alloc(0);
+
+  return content.subarray(offset);
+}
+
+/**
+ * Extract user content from a raw transcript message.
+ * Handles both string and array content formats.
+ * IDE-injected tags are stripped.
+ */
+export function extractUserContent(message: unknown): string {
+  if (!message || typeof message !== 'object') return '';
+
+  const msg = message as Record<string, unknown>;
+  const content = msg.content;
+
+  // Handle string content
+  if (typeof content === 'string') {
+    return stripIDEContextTags(content);
+  }
+
+  // Handle array content
+  if (Array.isArray(content)) {
+    const texts: string[] = [];
+    for (const item of content) {
+      if (
+        item &&
+        typeof item === 'object' &&
+        (item as Record<string, unknown>).type === CONTENT_TYPE_TEXT
+      ) {
+        const text = (item as Record<string, unknown>).text;
+        if (typeof text === 'string') {
+          texts.push(text);
+        }
+      }
+    }
+    if (texts.length > 0) {
+      return stripIDEContextTags(texts.join('\n\n'));
+    }
+  }
+
+  return '';
+}

package/references/sessionlog/src/utils/transcript-timestamp.ts

@@ -0,0 +1,59 @@
+/**
+ * JSONL Timestamp Extraction
+ *
+ * Utilities for extracting timestamps from JSONL transcript files.
+ * Used for session staleness detection and ordering.
+ */
+
+import * as fs from 'node:fs';
+
+/**
+ * Parse a timestamp from a single JSONL line.
+ * Returns null if the line is empty or doesn't contain a valid ISO timestamp.
+ */
+export function parseTimestampFromJSONL(line: string): Date | null {
+  if (!line) return null;
+
+  try {
+    const entry = JSON.parse(line) as { timestamp?: string };
+    if (!entry.timestamp) return null;
+
+    const date = new Date(entry.timestamp);
+    if (isNaN(date.getTime())) return null;
+
+    return date;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract the timestamp from the last non-empty line of JSONL content.
+ * Returns null if not found.
+ */
+export function getLastTimestampFromBytes(data: Buffer | string): Date | null {
+  const str = typeof data === 'string' ? data : data.toString('utf-8');
+  const lines = str.split('\n');
+
+  let lastLine = '';
+  for (const line of lines) {
+    if (line.trim()) {
+      lastLine = line;
+    }
+  }
+
+  return parseTimestampFromJSONL(lastLine);
+}
+
+/**
+ * Read the last non-empty line from a JSONL file and extract the timestamp.
+ * Returns null if file doesn't exist or no valid timestamp is found.
+ */
+export async function getLastTimestampFromFile(filePath: string): Promise<Date | null> {
+  try {
+    const content = await fs.promises.readFile(filePath, 'utf-8');
+    return getLastTimestampFromBytes(content);
+  } catch {
+    return null;
+  }
+}