cognitive-core 0.1.0 → 0.2.0

package/references/sessionlog/src/store/provider-types.ts

@@ -0,0 +1,99 @@
+/**
+ * Sessionlog Provider Types
+ *
+ * These types define the public interface for accessing Sessionlog session
+ * and checkpoint data. They are the contract between the Sessionlog module
+ * and external consumers (providers, daemon, etc.).
+ *
+ * This file is the canonical source of truth — external code should
+ * import these types from the sessionlog package rather than redefining them.
+ */
+
+// ============================================================================
+// Session
+// ============================================================================
+
+/**
+ * Sessionlog session state (from .git/sessionlog-sessions/<id>.json)
+ */
+export interface SessionlogSession {
+  id: string;
+  agent: string;
+  phase: 'ACTIVE' | 'IDLE' | 'ENDED';
+  baseCommit?: string;
+  branch?: string;
+  startedAt?: string;
+  endedAt?: string;
+  checkpoints?: string[];
+  tokenUsage?: SessionlogTokenUsage;
+  filesTouched?: string[];
+  summary?: string;
+
+  /** Skills used during this session (populated by SkillTracker) */
+  skillsUsed?: SessionlogSkillUsage;
+}
+
+/**
+ * Skill usage data embedded in session metadata
+ */
+export interface SessionlogSkillUsage {
+  /** Distinct skill names used */
+  skills: string[];
+
+  /** Total invocation count across all skills */
+  totalInvocations: number;
+
+  /** Per-skill invocation counts */
+  counts: Record<string, number>;
+
+  /** Per-skill success/failure counts */
+  outcomes: Record<string, { success: number; failure: number }>;
+}
+
+// ============================================================================
+// Checkpoint
+// ============================================================================
+
+/**
+ * Sessionlog checkpoint metadata
+ */
+export interface SessionlogCheckpoint {
+  id: string;
+  sessionId?: string;
+  commitHash?: string;
+  commitMessage?: string;
+  promptCount?: number;
+  filesModified?: string[];
+  filesNew?: string[];
+  filesDeleted?: string[];
+  tokenUsage?: SessionlogTokenUsage;
+  context?: string;
+}
+
+// ============================================================================
+// Token Usage
+// ============================================================================
+
+/**
+ * Token usage statistics (provider-facing, simplified)
+ */
+export interface SessionlogTokenUsage {
+  input?: number;
+  output?: number;
+  cache?: number;
+}
+
+// ============================================================================
+// Store Interface
+// ============================================================================
+
+/**
+ * Interface for accessing Sessionlog data (CLI or direct reads)
+ */
+export interface SessionlogStore {
+  getSession(id: string): Promise<SessionlogSession | null>;
+  listSessions(): Promise<SessionlogSession[]>;
+  getCheckpoint(id: string): Promise<SessionlogCheckpoint | null>;
+  listCheckpoints(): Promise<SessionlogCheckpoint[]>;
+  search(query: string): Promise<Array<SessionlogSession | SessionlogCheckpoint>>;
+}

package/references/sessionlog/src/store/session-store.ts

@@ -0,0 +1,266 @@
+/**
+ * Session Store
+ *
+ * Manages session state files in .git/sessionlog-sessions/.
+ * Each active session has a JSON state file that tracks
+ * its lifecycle, files touched, checkpoints, and token usage.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  type SessionState,
+  type SessionPhase,
+  type TokenUsage,
+  type PlanEntry,
+  STALE_SESSION_DAYS,
+} from '../types.js';
+import { getSessionsDir, atomicWriteFile } from '../git-operations.js';
+
+// ============================================================================
+// Session Store Interface
+// ============================================================================
+
+export interface SessionStore {
+  /** Load a session state by ID */
+  load(sessionID: string): Promise<SessionState | null>;
+
+  /** List all session states */
+  list(): Promise<SessionState[]>;
+
+  /** Save a session state */
+  save(state: SessionState): Promise<void>;
+
+  /** Delete a session state */
+  delete(sessionID: string): Promise<void>;
+
+  /** Get the sessions directory path */
+  getDir(): Promise<string>;
+
+  /** Check if a session exists */
+  exists(sessionID: string): Promise<boolean>;
+}
+
+// ============================================================================
+// Filesystem Session Store
+// ============================================================================
+
+/**
+ * Create a session store.
+ *
+ * @param cwd - The project working directory (used to locate .git/sessionlog-sessions/)
+ * @param sessionsDir - Optional explicit directory for session state files.
+ *   When provided, session files are stored here instead of .git/sessionlog-sessions/.
+ *   This is used when a separate session repo is configured.
+ */
+export function createSessionStore(cwd?: string, sessionsDir?: string): SessionStore {
+  let sessionsDirCache: string | null = sessionsDir ?? null;
+
+  async function getDir(): Promise<string> {
+    if (sessionsDirCache) return sessionsDirCache;
+    sessionsDirCache = await getSessionsDir(cwd);
+    return sessionsDirCache;
+  }
+
+  function sessionFilePath(dir: string, sessionID: string): string {
+    return path.join(dir, `${sessionID}.json`);
+  }
+
+  function parseSessionFile(filePath: string): SessionState | null {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const data = JSON.parse(content) as Record<string, unknown>;
+      const id = path.basename(filePath, '.json');
+
+      return normalizeSessionState(id, data);
+    } catch {
+      return null;
+    }
+  }
+
+  function isStale(state: SessionState): boolean {
+    if (state.phase !== 'ended' || !state.endedAt) return false;
+    const endedAt = new Date(state.endedAt);
+    const staleThreshold = Date.now() - STALE_SESSION_DAYS * 24 * 60 * 60 * 1000;
+    return endedAt.getTime() < staleThreshold;
+  }
+
+  return {
+    async load(sessionID: string): Promise<SessionState | null> {
+      const dir = await getDir();
+      const filePath = sessionFilePath(dir, sessionID);
+
+      const state = parseSessionFile(filePath);
+      if (!state) return null;
+
+      // Auto-delete stale sessions
+      if (isStale(state)) {
+        try {
+          await fs.promises.unlink(filePath);
+        } catch {
+          // Ignore deletion errors
+        }
+        return null;
+      }
+
+      return state;
+    },
+
+    async list(): Promise<SessionState[]> {
+      const dir = await getDir();
+
+      try {
+        const files = await fs.promises.readdir(dir);
+        const states: SessionState[] = [];
+
+        for (const file of files) {
+          if (!file.endsWith('.json')) continue;
+          const filePath = path.join(dir, file);
+          const state = parseSessionFile(filePath);
+
+          if (!state) continue;
+
+          // Auto-delete stale sessions
+          if (isStale(state)) {
+            try {
+              await fs.promises.unlink(filePath);
+            } catch {
+              // Ignore
+            }
+            continue;
+          }
+
+          states.push(state);
+        }
+
+        return states;
+      } catch {
+        return [];
+      }
+    },
+
+    async save(state: SessionState): Promise<void> {
+      const dir = await getDir();
+      const filePath = sessionFilePath(dir, state.sessionID);
+      const content = JSON.stringify(serializeSessionState(state), null, 2);
+      await atomicWriteFile(filePath, content);
+    },
+
+    async delete(sessionID: string): Promise<void> {
+      const dir = await getDir();
+      const filePath = sessionFilePath(dir, sessionID);
+      try {
+        await fs.promises.unlink(filePath);
+      } catch {
+        // Ignore if already deleted
+      }
+    },
+
+    async getDir(): Promise<string> {
+      return getDir();
+    },
+
+    async exists(sessionID: string): Promise<boolean> {
+      const dir = await getDir();
+      const filePath = sessionFilePath(dir, sessionID);
+      try {
+        await fs.promises.access(filePath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+// ============================================================================
+// Normalization
+// ============================================================================
+
+/**
+ * Normalize raw JSON data into a SessionState, handling field name variations
+ */
+export function normalizeSessionState(id: string, data: Record<string, unknown>): SessionState {
+  return {
+    sessionID: String(data.sessionID ?? data.session_id ?? id),
+    cliVersion: data.cliVersion as string | undefined,
+    baseCommit: String(data.baseCommit ?? data.base_commit ?? ''),
+    attributionBaseCommit: data.attributionBaseCommit as string | undefined,
+    worktreePath: data.worktreePath as string | undefined,
+    worktreeID: data.worktreeID as string | undefined,
+    startedAt: String(data.startedAt ?? data.started_at ?? new Date().toISOString()),
+    endedAt: (data.endedAt ?? data.ended_at) as string | undefined,
+    phase: normalizePhase(String(data.phase ?? data.state ?? 'idle')),
+    turnID: data.turnID as string | undefined,
+    turnCheckpointIDs: Array.isArray(data.turnCheckpointIDs)
+      ? data.turnCheckpointIDs.map(String)
+      : [],
+    lastInteractionTime: (data.lastInteractionTime ?? data.last_interaction_time) as
+      | string
+      | undefined,
+    stepCount: Number(data.stepCount ?? data.step_count ?? 0),
+    checkpointTranscriptStart: Number(data.checkpointTranscriptStart ?? 0),
+    untrackedFilesAtStart: Array.isArray(data.untrackedFilesAtStart)
+      ? data.untrackedFilesAtStart.map(String)
+      : [],
+    filesTouched: Array.isArray(data.filesTouched) ? data.filesTouched.map(String) : [],
+    lastCheckpointID: data.lastCheckpointID as string | undefined,
+    agentType: String(data.agentType ?? data.agent ?? data.agent_type ?? 'Agent'),
+    tokenUsage: data.tokenUsage as TokenUsage | undefined,
+    transcriptIdentifierAtStart: data.transcriptIdentifierAtStart as string | undefined,
+    transcriptPath: data.transcriptPath as string | undefined,
+    firstPrompt: data.firstPrompt as string | undefined,
+    promptAttributions: data.promptAttributions as SessionState['promptAttributions'],
+    pendingPromptAttribution:
+      data.pendingPromptAttribution as SessionState['pendingPromptAttribution'],
+    tasks: data.tasks as SessionState['tasks'],
+    inPlanMode: data.inPlanMode as boolean | undefined,
+    planModeEntries: data.planModeEntries as number | undefined,
+    planEntries: normalizePlanEntries(data),
+    skillsUsed: Array.isArray(data.skillsUsed)
+      ? (data.skillsUsed as SessionState['skillsUsed'])
+      : undefined,
+  };
+}
+
+function normalizePhase(phase: string): SessionPhase {
+  const lower = phase.toLowerCase();
+  if (lower === 'active') return 'active';
+  if (lower === 'idle') return 'idle';
+  if (lower === 'ended') return 'ended';
+  return 'idle';
+}
+
+function normalizePlanEntries(data: Record<string, unknown>): PlanEntry[] | undefined {
+  if (Array.isArray(data.planEntries)) {
+    return data.planEntries as PlanEntry[];
+  }
+
+  // Migration: synthesize from old planFilePath/planContent fields
+  const filePath = data.planFilePath as string | undefined;
+  const content = data.planContent as string | undefined;
+  if (filePath || content) {
+    return [
+      {
+        enteredAt: (data.startedAt as string) ?? new Date().toISOString(),
+        exitedAt: (data.startedAt as string) ?? new Date().toISOString(),
+        filePath,
+        content,
+      },
+    ];
+  }
+
+  return undefined;
+}
+
+/**
+ * Serialize a SessionState for writing to disk
+ */
+function serializeSessionState(state: SessionState): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...state };
+  // Remove undefined values
+  for (const [key, value] of Object.entries(result)) {
+    if (value === undefined) delete result[key];
+  }
+  return result;
+}

package/references/sessionlog/src/strategy/attribution.ts

@@ -0,0 +1,296 @@
+/**
+ * Attribution Logic
+ *
+ * Computes line-level attribution between agent-generated and human-edited code.
+ * Uses diff-based analysis to track who wrote which lines.
+ */
+
+import type { InitialAttribution } from '../types.js';
+import { countLines } from '../utils/string-utils.js';
+import type { PromptAttribution } from './types.js';
+
+// ============================================================================
+// Diff-based Attribution
+// ============================================================================
+
+/**
+ * Compare two strings and return line-level diff stats.
+ * Returns [unchanged, added, removed] line counts.
+ *
+ * Uses a simple line-by-line comparison. For production-grade diffing,
+ * we compare line sets since we only need counts, not actual patches.
+ */
+export function diffLines(
+  oldContent: string,
+  newContent: string,
+): [unchanged: number, added: number, removed: number] {
+  if (oldContent === newContent) {
+    return [countLines(newContent), 0, 0];
+  }
+  if (oldContent === '') {
+    return [0, countLines(newContent), 0];
+  }
+  if (newContent === '') {
+    return [0, 0, countLines(oldContent)];
+  }
+
+  // Line-by-line LCS-based diff for accurate counting
+  const oldLines = oldContent.split('\n');
+  const newLines = newContent.split('\n');
+
+  // Remove trailing empty string from split if content ends with newline
+  if (oldLines[oldLines.length - 1] === '' && oldContent.endsWith('\n')) {
+    oldLines.pop();
+  }
+  if (newLines[newLines.length - 1] === '' && newContent.endsWith('\n')) {
+    newLines.pop();
+  }
+
+  // Build a set-based approximation for line counts
+  // This is simpler than full LCS but gives good accuracy for attribution
+  const oldSet = new Map<string, number>();
+  for (const line of oldLines) {
+    oldSet.set(line, (oldSet.get(line) ?? 0) + 1);
+  }
+
+  let unchanged = 0;
+  const matchedOld = new Map<string, number>();
+
+  for (const line of newLines) {
+    const available = (oldSet.get(line) ?? 0) - (matchedOld.get(line) ?? 0);
+    if (available > 0) {
+      unchanged++;
+      matchedOld.set(line, (matchedOld.get(line) ?? 0) + 1);
+    }
+  }
+
+  const removed = oldLines.length - unchanged;
+  const added = newLines.length - unchanged;
+
+  return [unchanged, added, removed];
+}
+
+/**
+ * Get all changed files between two sets of file contents.
+ */
+export function getAllChangedFiles(
+  tree1: Map<string, string>,
+  tree2: Map<string, string>,
+): string[] {
+  const changed = new Set<string>();
+
+  for (const [path, hash1] of tree1) {
+    const hash2 = tree2.get(path);
+    if (hash2 === undefined || hash1 !== hash2) {
+      changed.add(path);
+    }
+  }
+
+  for (const path of tree2.keys()) {
+    if (!tree1.has(path)) {
+      changed.add(path);
+    }
+  }
+
+  return Array.from(changed);
+}
+
+/**
+ * Calculate attribution with accumulated prompt data.
+ *
+ * This provides more accurate attribution than tree-only comparison because
+ * it captures user edits between checkpoints.
+ *
+ * @param baseFiles - File contents at session start
+ * @param shadowFiles - File contents at last checkpoint
+ * @param headFiles - File contents at commit time (HEAD)
+ * @param filesTouched - Files the agent modified
+ * @param promptAttributions - Per-prompt user edit tracking
+ */
+export function calculateAttributionWithAccumulated(
+  baseFiles: Map<string, string>,
+  shadowFiles: Map<string, string>,
+  headFiles: Map<string, string>,
+  filesTouched: string[],
+  promptAttributions: PromptAttribution[],
+): InitialAttribution | null {
+  if (filesTouched.length === 0) return null;
+
+  // Sum accumulated user lines from prompt attributions
+  let accumulatedUserRemoved = 0;
+  const accumulatedUserAddedPerFile = new Map<string, number>();
+
+  for (const pa of promptAttributions) {
+    accumulatedUserRemoved += pa.userLinesRemoved;
+    for (const [filePath, added] of Object.entries(pa.userAddedPerFile)) {
+      accumulatedUserAddedPerFile.set(
+        filePath,
+        (accumulatedUserAddedPerFile.get(filePath) ?? 0) + added,
+      );
+    }
+  }
+
+  // Calculate for agent-touched files
+  let totalAgentAndUserWork = 0;
+  let postCheckpointUserAdded = 0;
+  let postCheckpointUserRemoved = 0;
+  const postCheckpointUserRemovedPerFile = new Map<string, number>();
+
+  for (const filePath of filesTouched) {
+    const baseContent = baseFiles.get(filePath) ?? '';
+    const shadowContent = shadowFiles.get(filePath) ?? '';
+    const headContent = headFiles.get(filePath) ?? '';
+
+    // Total work in shadow: base → shadow
+    const [, workAdded] = diffLines(baseContent, shadowContent);
+    totalAgentAndUserWork += workAdded;
+
+    // Post-checkpoint user edits: shadow → head
+    const [, postUserAdded, postUserRemoved] = diffLines(shadowContent, headContent);
+    postCheckpointUserAdded += postUserAdded;
+    postCheckpointUserRemoved += postUserRemoved;
+
+    if (postUserRemoved > 0) {
+      postCheckpointUserRemovedPerFile.set(filePath, postUserRemoved);
+    }
+  }
+
+  // User edits to non-agent files
+  const nonAgentFiles = getAllChangedFiles(baseFiles, headFiles);
+  const touchedSet = new Set(filesTouched);
+  let allUserEditsToNonAgentFiles = 0;
+
+  for (const filePath of nonAgentFiles) {
+    if (touchedSet.has(filePath)) continue;
+    const baseContent = baseFiles.get(filePath) ?? '';
+    const headContent = headFiles.get(filePath) ?? '';
+    const [, userAdded] = diffLines(baseContent, headContent);
+    allUserEditsToNonAgentFiles += userAdded;
+  }
+
+  // Separate accumulated edits by file type
+  const committedNonAgentSet = new Set(nonAgentFiles.filter((f) => !touchedSet.has(f)));
+
+  let accumulatedToAgentFiles = 0;
+  let accumulatedToCommittedNonAgentFiles = 0;
+  for (const [filePath, added] of accumulatedUserAddedPerFile) {
+    if (touchedSet.has(filePath)) {
+      accumulatedToAgentFiles += added;
+    } else if (committedNonAgentSet.has(filePath)) {
+      accumulatedToCommittedNonAgentFiles += added;
+    }
+  }
+
+  // Agent work = (base→shadow for agent files) - (accumulated user edits to agent files)
+  const totalAgentAdded = Math.max(0, totalAgentAndUserWork - accumulatedToAgentFiles);
+
+  // Post-checkpoint edits to non-agent files
+  const postToNonAgentFiles = Math.max(
+    0,
+    allUserEditsToNonAgentFiles - accumulatedToCommittedNonAgentFiles,
+  );
+
+  // Total user contribution
+  const relevantAccumulatedUser = accumulatedToAgentFiles + accumulatedToCommittedNonAgentFiles;
+  const totalUserAdded = relevantAccumulatedUser + postCheckpointUserAdded + postToNonAgentFiles;
+  const totalUserRemoved = accumulatedUserRemoved + postCheckpointUserRemoved;
+
+  // Estimate modified lines
+  const totalHumanModified = Math.min(totalUserAdded, totalUserRemoved);
+
+  // Estimate user self-modifications
+  const userSelfModified = estimateUserSelfModifications(
+    accumulatedUserAddedPerFile,
+    postCheckpointUserRemovedPerFile,
+  );
+
+  const humanModifiedAgent = Math.max(0, totalHumanModified - userSelfModified);
+  const pureUserAdded = totalUserAdded - totalHumanModified;
+  const pureUserRemoved = totalUserRemoved - totalHumanModified;
+
+  let totalCommitted = totalAgentAdded + pureUserAdded - pureUserRemoved;
+  if (totalCommitted <= 0) {
+    totalCommitted = Math.max(0, totalAgentAdded);
+  }
+
+  const agentLinesInCommit = Math.max(0, totalAgentAdded - pureUserRemoved - humanModifiedAgent);
+
+  let agentPercentage = 0;
+  if (totalCommitted > 0) {
+    agentPercentage = (agentLinesInCommit / totalCommitted) * 100;
+  }
+
+  return {
+    calculatedAt: new Date().toISOString(),
+    agentLines: agentLinesInCommit,
+    humanAdded: pureUserAdded,
+    humanModified: totalHumanModified,
+    humanRemoved: pureUserRemoved,
+    totalCommitted,
+    agentPercentage,
+  };
+}
+
+/**
+ * Estimate how many removed lines were the user's own additions.
+ * Uses LIFO assumption: user removes their own recent additions first.
+ */
+function estimateUserSelfModifications(
+  accumulatedUserAddedPerFile: Map<string, number>,
+  postCheckpointUserRemovedPerFile: Map<string, number>,
+): number {
+  let selfModified = 0;
+  for (const [filePath, removed] of postCheckpointUserRemovedPerFile) {
+    const userAddedToFile = accumulatedUserAddedPerFile.get(filePath) ?? 0;
+    selfModified += Math.min(removed, userAddedToFile);
+  }
+  return selfModified;
+}
+
+/**
+ * Calculate prompt attribution at the start of a prompt.
+ * Captures user edits since the last checkpoint BEFORE the agent makes changes.
+ */
+export function calculatePromptAttribution(
+  baseFiles: Map<string, string>,
+  lastCheckpointFiles: Map<string, string> | null,
+  worktreeFiles: Map<string, string>,
+  checkpointNumber: number,
+): PromptAttribution {
+  const result: PromptAttribution = {
+    checkpointNumber,
+    userLinesAdded: 0,
+    userLinesRemoved: 0,
+    agentLinesAdded: 0,
+    agentLinesRemoved: 0,
+    userAddedPerFile: {},
+  };
+
+  if (worktreeFiles.size === 0) return result;
+
+  const referenceFiles = lastCheckpointFiles ?? baseFiles;
+
+  for (const [filePath, worktreeContent] of worktreeFiles) {
+    const referenceContent = referenceFiles.get(filePath) ?? '';
+    const baseContent = baseFiles.get(filePath) ?? '';
+
+    // User changes: diff(reference, worktree)
+    const [, userAdded, userRemoved] = diffLines(referenceContent, worktreeContent);
+    result.userLinesAdded += userAdded;
+    result.userLinesRemoved += userRemoved;
+
+    if (userAdded > 0) {
+      result.userAddedPerFile[filePath] = userAdded;
+    }
+
+    // Agent lines so far: diff(base, lastCheckpoint)
+    if (lastCheckpointFiles) {
+      const checkpointContent = lastCheckpointFiles.get(filePath) ?? '';
+      const [, agentAdded, agentRemoved] = diffLines(baseContent, checkpointContent);
+      result.agentLinesAdded += agentAdded;
+      result.agentLinesRemoved += agentRemoved;
+    }
+  }
+
+  return result;
+}