cognitive-core 0.2.1 → 0.2.2

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

@@ -1,99 +0,0 @@
-/**
- * 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

@@ -1,266 +0,0 @@
-/**
- * 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

@@ -1,296 +0,0 @@
-/**
- * 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;
-}