clearctx 3.0.0

package/src/safety-net.js

@@ -0,0 +1,170 @@
+/**
+ * SafetyNet — Automatic limits and protection for automated sessions.
+ *
+ * Enforces:
+ *   - Cost limit — Kill session if cumulative cost exceeds threshold
+ *   - Turn limit — Kill session if total agent turns exceed threshold
+ *   - Time limit — Kill session if a single interaction takes too long
+ *   - File protection — Prevent modifications to critical files/paths
+ *
+ * Integrates with StreamSession via the 'result' event.
+ *
+ * Usage:
+ *   const safety = new SafetyNet({
+ *     maxCostUsd: 1.00,    // Kill if total cost exceeds $1
+ *     maxTurns: 30,        // Kill if total turns exceed 30
+ *     maxDurationMs: 300000, // Kill if single interaction > 5 min
+ *     protectedPaths: ['.env', 'node_modules', '.git'],
+ *   });
+ *   safety.attach(streamSession);
+ */
+
+const { EventEmitter } = require('events');
+
+// Default safety limits
+const DEFAULTS = {
+  maxCostUsd: 2.00,       // $2 per session
+  maxTurns: 50,           // 50 agent turns
+  maxDurationMs: 300000,  // 5 minutes per interaction
+  protectedPaths: [       // Files that should never be modified
+    '.env',
+    '.env.local',
+    '.env.production',
+    'credentials',
+    'secrets',
+    '.git/',
+    'node_modules/',
+  ],
+};
+
+class SafetyNet extends EventEmitter {
+  /**
+   * @param {object} [limits] - Override default limits
+   * @param {number} [limits.maxCostUsd] - Max total cost in USD
+   * @param {number} [limits.maxTurns] - Max total agent turns
+   * @param {number} [limits.maxDurationMs] - Max time per interaction
+   * @param {string[]} [limits.protectedPaths] - Paths that can't be modified
+   */
+  constructor(limits = {}) {
+    super();
+    this.maxCostUsd = limits.maxCostUsd ?? DEFAULTS.maxCostUsd;
+    this.maxTurns = limits.maxTurns ?? DEFAULTS.maxTurns;
+    this.maxDurationMs = limits.maxDurationMs ?? DEFAULTS.maxDurationMs;
+    this.protectedPaths = limits.protectedPaths || DEFAULTS.protectedPaths;
+
+    this.violations = [];   // Record of all limit violations
+    this.attached = null;   // The session we're monitoring
+  }
+
+  /**
+   * Attach to a StreamSession to monitor it.
+   * @param {StreamSession} session
+   */
+  attach(session) {
+    this.attached = session;
+
+    // Check limits after each result
+    session.on('result', (response) => {
+      this._checkCost(session, response);
+      this._checkTurns(session, response);
+    });
+
+    // Check for protected file access in tool calls
+    session.on('tool-use', (toolCall) => {
+      this._checkProtectedPaths(session, toolCall);
+    });
+  }
+
+  /**
+   * Check if cost limit is exceeded.
+   */
+  _checkCost(session, response) {
+    if (this.maxCostUsd && session.totalCostUsd > this.maxCostUsd) {
+      const violation = {
+        type: 'cost_exceeded',
+        limit: this.maxCostUsd,
+        actual: session.totalCostUsd,
+        message: `Cost limit exceeded: $${session.totalCostUsd.toFixed(4)} > $${this.maxCostUsd.toFixed(2)} limit`,
+        timestamp: new Date().toISOString(),
+      };
+      this.violations.push(violation);
+      this.emit('violation', violation);
+      this.emit('kill', violation);
+
+      // Force kill the session
+      session.kill();
+    }
+  }
+
+  /**
+   * Check if turn limit is exceeded.
+   */
+  _checkTurns(session, response) {
+    if (this.maxTurns && session.totalTurns > this.maxTurns) {
+      const violation = {
+        type: 'turns_exceeded',
+        limit: this.maxTurns,
+        actual: session.totalTurns,
+        message: `Turn limit exceeded: ${session.totalTurns} > ${this.maxTurns} limit`,
+        timestamp: new Date().toISOString(),
+      };
+      this.violations.push(violation);
+      this.emit('violation', violation);
+      this.emit('kill', violation);
+
+      session.kill();
+    }
+  }
+
+  /**
+   * Check if a tool call targets a protected path.
+   */
+  _checkProtectedPaths(session, toolCall) {
+    if (!toolCall.input) return;
+
+    // Check common file path fields in tool inputs
+    const pathFields = ['file_path', 'path', 'command'];
+    for (const field of pathFields) {
+      const value = toolCall.input[field];
+      if (typeof value !== 'string') continue;
+
+      for (const protected_path of this.protectedPaths) {
+        if (value.includes(protected_path)) {
+          // Only flag write operations
+          const writeTools = ['Write', 'Edit', 'NotebookEdit', 'Bash'];
+          if (writeTools.includes(toolCall.name)) {
+            const violation = {
+              type: 'protected_path',
+              tool: toolCall.name,
+              path: value,
+              protectedPattern: protected_path,
+              message: `Attempted to modify protected path: ${value} (matches "${protected_path}")`,
+              timestamp: new Date().toISOString(),
+            };
+            this.violations.push(violation);
+            this.emit('violation', violation);
+            // Don't kill — just warn. The permission system handles blocking.
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Get a summary of all violations.
+   */
+  getSummary() {
+    return {
+      totalViolations: this.violations.length,
+      violations: this.violations,
+      limits: {
+        maxCostUsd: this.maxCostUsd,
+        maxTurns: this.maxTurns,
+        maxDurationMs: this.maxDurationMs,
+        protectedPaths: this.protectedPaths,
+      },
+    };
+  }
+}
+
+module.exports = SafetyNet;

package/src/session-snapshot.js

@@ -0,0 +1,508 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+const { atomicWriteJson, readJsonSafe } = require('./atomic-io');
+const { acquireLock, releaseLock } = require('./file-lock');
+
+/**
+ * SessionSnapshot - Captures lightweight snapshots of project state for the Session Continuity Engine.
+ *
+ * This module provides snapshot capabilities for tracking project state across sessions.
+ * It captures git state, file tree information, and working context to enable session continuity.
+ *
+ * Features:
+ * - Lightweight git state capture (branch, commits, dirty files)
+ * - Working context tracking (active files, tasks, blockers)
+ * - Snapshot history management
+ * - Project-specific storage using content-addressed directories
+ *
+ * Storage structure:
+ * ~/.clearctx/continuity/{projectHash}/
+ *   ├── snapshots/        # Individual snapshot files
+ *   ├── locks/            # Lock files for safe concurrent access
+ *   └── meta.json         # Project metadata and latest snapshot pointer
+ */
+class SessionSnapshot {
+  /**
+   * Creates a new SessionSnapshot instance for a project.
+   *
+   * @param {string} projectPath - Absolute path to the project directory (e.g., 'E:\MyProject')
+   *
+   * How it works:
+   * 1. Computes a unique hash from the project path to create isolated storage
+   * 2. Sets up storage directories in the user's home directory
+   * 3. Creates necessary subdirectories (snapshots/, locks/)
+   * 4. Initializes meta.json with project information if it doesn't exist
+   */
+  constructor(projectPath) {
+    // Store the absolute path to the project we're tracking
+    this.projectPath = projectPath;
+
+    // Create a unique hash from the project path
+    // This allows us to store snapshots for different projects separately
+    // We use SHA256 and take the first 16 characters for a short, unique identifier
+    this.projectHash = crypto
+      .createHash('sha256')
+      .update(projectPath)
+      .digest('hex')
+      .slice(0, 16);
+
+    // Set up the main storage directory for this project's continuity data
+    // Example: C:\Users\username\.clearctx\continuity\a1b2c3d4e5f6g7h8\
+    this.storageDir = path.join(
+      os.homedir(),
+      '.clearctx',
+      'continuity',
+      this.projectHash
+    );
+
+    // Set up subdirectories for organizing different types of data
+    this.snapshotsDir = path.join(this.storageDir, 'snapshots');
+    this.locksDir = path.join(this.storageDir, 'locks');
+    this.metaPath = path.join(this.storageDir, 'meta.json');
+
+    // Create all necessary directories if they don't exist
+    // recursive: true means it will create parent directories too
+    fs.mkdirSync(this.snapshotsDir, { recursive: true });
+    fs.mkdirSync(this.locksDir, { recursive: true });
+
+    // Initialize meta.json if it doesn't exist
+    // This file stores project metadata and points to the latest snapshot
+    if (!fs.existsSync(this.metaPath)) {
+      const metaData = {
+        projectPath: this.projectPath,
+        projectHash: this.projectHash,
+        createdAt: new Date().toISOString()
+      };
+      atomicWriteJson(this.metaPath, metaData);
+    }
+  }
+
+  /**
+   * Captures a lightweight snapshot of the current project state.
+   *
+   * This is the main method for creating snapshots. It captures:
+   * - Git state (branch, commits, modified files, staged files)
+   * - File tree information (tracked file count)
+   * - Working context (active files, tasks, questions, blockers)
+   *
+   * @param {string} sessionName - Name of the session capturing this snapshot
+   * @param {object} workingContext - Optional context object with:
+   *   - activeFiles: Array of file paths currently being worked on
+   *   - taskSummary: Brief description of current task
+   *   - openQuestions: Array of questions or uncertainties
+   *   - blockers: Array of blocking issues
+   * @returns {object} The complete snapshot object
+   *
+   * Example:
+   * const snapshot = sessionSnapshot.capture('build-session', {
+   *   activeFiles: ['src/auth.js', 'src/routes.js'],
+   *   taskSummary: 'Implementing user authentication',
+   *   openQuestions: ['Which hash algorithm to use?'],
+   *   blockers: ['Need API key from client']
+   * });
+   */
+  capture(sessionName, workingContext = {}) {
+    // Generate a unique ID for this snapshot using timestamp
+    // Example: 'snap_1707849600000'
+    const snapshotId = 'snap_' + Date.now();
+
+    // Capture git state by running git commands
+    const gitState = this._captureGitState();
+
+    // Capture file tree information
+    const fileTree = this._captureFileTree();
+
+    // Build the complete snapshot object
+    const snapshot = {
+      snapshotId: snapshotId,
+      projectPath: this.projectPath,
+      capturedAt: new Date().toISOString(),
+      capturedBy: sessionName,
+      git: gitState,
+      fileTree: fileTree,
+      workingContext: {
+        activeFiles: workingContext.activeFiles || [],
+        taskSummary: workingContext.taskSummary || '',
+        openQuestions: workingContext.openQuestions || [],
+        blockers: workingContext.blockers || []
+      }
+    };
+
+    // Write the snapshot to disk using atomic write for safety
+    const snapshotPath = path.join(this.snapshotsDir, `${snapshotId}.json`);
+    atomicWriteJson(snapshotPath, snapshot);
+
+    // Update meta.json to point to this latest snapshot
+    // We use locks to prevent concurrent writes from corrupting the file
+    acquireLock(this.locksDir, 'meta');
+    try {
+      const meta = readJsonSafe(this.metaPath, {});
+      meta.lastSnapshotId = snapshotId;
+      atomicWriteJson(this.metaPath, meta);
+    } finally {
+      // Always release the lock, even if there was an error
+      releaseLock(this.locksDir, 'meta');
+    }
+
+    return snapshot;
+  }
+
+  /**
+   * Captures git state by running git commands.
+   *
+   * This is an internal helper method that executes various git commands
+   * to gather information about the repository state.
+   *
+   * @private
+   * @returns {object|null} Git state object, or null if not a git repository
+   *
+   * The returned object contains:
+   * - branch: Current branch name (or 'DETACHED' if in detached HEAD)
+   * - headCommit: SHA hash of the current commit
+   * - headMessage: Commit message of the current commit
+   * - isDirty: Boolean indicating if there are uncommitted changes
+   * - untrackedCount: Number of untracked files
+   * - modifiedFiles: Array of modified file paths (unstaged)
+   * - stagedFiles: Array of staged file paths
+   * - recentCommits: Array of recent commit objects [{hash, message}, ...]
+   */
+  _captureGitState() {
+    try {
+      // First, verify this is a git repository
+      // This will throw an error if we're not in a git repo
+      execSync('git rev-parse --show-toplevel', {
+        cwd: this.projectPath,
+        encoding: 'utf-8',
+        timeout: 10000,
+        stdio: ['pipe', 'pipe', 'pipe'] // Suppress stderr
+      });
+
+      // Get the current commit hash (HEAD)
+      const headCommit = execSync('git rev-parse HEAD', {
+        cwd: this.projectPath,
+        encoding: 'utf-8',
+        timeout: 10000,
+        stdio: ['pipe', 'pipe', 'pipe'] // Suppress stderr
+      }).trim();
+
+      // Get the current branch name
+      // If we're in detached HEAD state, this will be empty
+      let branch = execSync('git branch --show-current', {
+        cwd: this.projectPath,
+        encoding: 'utf-8',
+        timeout: 10000,
+        stdio: ['pipe', 'pipe', 'pipe'] // Suppress stderr
+      }).trim();
+
+      // Handle detached HEAD state
+      if (!branch) {
+        branch = 'DETACHED';
+      }
+
+      // Get recent commits (last 10)
+      // Format: "abc1234 Commit message here"
+      const logOutput = execSync('git log --oneline -n 10', {
+        cwd: this.projectPath,
+        encoding: 'utf-8',
+        timeout: 10000,
+        stdio: ['pipe', 'pipe', 'pipe'] // Suppress stderr
+      }).trim();
+
+      // Parse the log output into an array of commit objects
+      const recentCommits = logOutput
+        .split('\n')
+        .filter(line => line.trim()) // Remove empty lines
+        .map(line => {
+          // Split the line into hash and message
+          const spaceIndex = line.indexOf(' ');
+          if (spaceIndex === -1) {
+            return { hash: line, message: '' };
+          }
+          return {
+            hash: line.substring(0, spaceIndex),
+            message: line.substring(spaceIndex + 1)
+          };
+        });
+
+      // Get the message of the current commit (first line only)
+      const headMessage = recentCommits.length > 0 ? recentCommits[0].message : '';
+
+      // Get status information using porcelain format
+      // Porcelain format is machine-readable and stable across git versions
+      const statusOutput = execSync('git status --porcelain', {
+        cwd: this.projectPath,
+        encoding: 'utf-8',
+        timeout: 10000,
+        stdio: ['pipe', 'pipe', 'pipe'] // Suppress stderr
+      }).trim();
+
+      // Parse the status output to extract file states
+      const statusInfo = this._parseGitStatus(statusOutput);
+
+      return {
+        branch: branch,
+        headCommit: headCommit,
+        headMessage: headMessage,
+        isDirty: statusInfo.isDirty,
+        untrackedCount: statusInfo.untrackedCount,
+        modifiedFiles: statusInfo.modifiedFiles,
+        stagedFiles: statusInfo.stagedFiles,
+        recentCommits: recentCommits
+      };
+    } catch (error) {
+      // If any git command fails, this is likely not a git repository
+      // or git is not available, so we return null
+      return null;
+    }
+  }
+
+  /**
+   * Parses git status --porcelain output into structured information.
+   *
+   * Git status porcelain format uses two columns:
+   * - First column (X): staged status
+   * - Second column (Y): unstaged status
+   *
+   * Examples:
+   * "M  file.js"  → staged modification
+   * " M file.js"  → unstaged modification
+   * "MM file.js"  → staged and unstaged modifications
+   * "?? file.js"  → untracked file
+   * "A  file.js"  → newly added (staged)
+   *
+   * @private
+   * @param {string} statusOutput - Raw output from 'git status --porcelain'
+   * @returns {object} Parsed status information
+   */
+  _parseGitStatus(statusOutput) {
+    const modifiedFiles = [];
+    const stagedFiles = [];
+    let untrackedCount = 0;
+    let isDirty = false;
+
+    // If there's any status output, the working tree is dirty
+    if (statusOutput.length > 0) {
+      isDirty = true;
+    }
+
+    // Parse each line of the status output
+    const lines = statusOutput.split('\n').filter(line => line.trim());
+
+    for (const line of lines) {
+      if (line.length < 4) continue; // Skip invalid lines
+
+      // Extract the status codes and file path
+      // Format: "XY filename" where X=staged, Y=unstaged
+      const stagedCode = line[0];
+      const unstagedCode = line[1];
+      const filePath = line.substring(3); // Skip "XY " prefix
+
+      // Check for untracked files (marked with ??)
+      if (stagedCode === '?' && unstagedCode === '?') {
+        untrackedCount++;
+        continue;
+      }
+
+      // Check for staged changes (first column is not space)
+      // Staged codes: M (modified), A (added), D (deleted), R (renamed), C (copied)
+      if (stagedCode !== ' ' && stagedCode !== '?') {
+        stagedFiles.push(filePath);
+      }
+
+      // Check for unstaged modifications (second column is M)
+      if (unstagedCode === 'M') {
+        modifiedFiles.push(filePath);
+      }
+    }
+
+    return {
+      isDirty: isDirty,
+      untrackedCount: untrackedCount,
+      modifiedFiles: modifiedFiles,
+      stagedFiles: stagedFiles
+    };
+  }
+
+  /**
+   * Captures file tree information.
+   *
+   * For git repositories, this counts the number of tracked files.
+   * For non-git projects, returns null.
+   *
+   * @private
+   * @returns {object|null} File tree information
+   */
+  _captureFileTree() {
+    try {
+      // Use 'git ls-files' to list all tracked files
+      const lsOutput = execSync('git ls-files', {
+        cwd: this.projectPath,
+        encoding: 'utf-8',
+        timeout: 10000,
+        stdio: ['pipe', 'pipe', 'pipe'] // Suppress stderr
+      });
+
+      // Count the lines (each line is a file)
+      const lines = lsOutput.trim().split('\n').filter(line => line.trim());
+      const trackedFileCount = lines.length;
+
+      return {
+        trackedFileCount: trackedFileCount
+      };
+    } catch (error) {
+      // Not a git repository or git command failed
+      return null;
+    }
+  }
+
+  /**
+   * Returns the most recent snapshot, or null if none exist.
+   *
+   * This method first checks meta.json for the lastSnapshotId pointer.
+   * If that's not available, it scans the snapshots directory for the
+   * most recent file based on filename timestamp.
+   *
+   * @returns {object|null} The latest snapshot object, or null if none exist
+   */
+  getLatest() {
+    // Try to get the latest snapshot ID from meta.json
+    const meta = readJsonSafe(this.metaPath, {});
+
+    if (meta.lastSnapshotId) {
+      // We have a pointer to the latest snapshot
+      const snapshotPath = path.join(this.snapshotsDir, `${meta.lastSnapshotId}.json`);
+      const snapshot = readJsonSafe(snapshotPath, null);
+      if (snapshot) {
+        return snapshot;
+      }
+    }
+
+    // If meta.json doesn't have lastSnapshotId or the file doesn't exist,
+    // scan the snapshots directory for the most recent file
+    try {
+      const files = fs.readdirSync(this.snapshotsDir);
+
+      // Filter for snapshot files (snap_*.json)
+      const snapshotFiles = files.filter(f => f.startsWith('snap_') && f.endsWith('.json'));
+
+      if (snapshotFiles.length === 0) {
+        return null;
+      }
+
+      // Sort by timestamp (extracted from filename) in descending order
+      snapshotFiles.sort((a, b) => {
+        // Extract timestamp from filename: snap_1707849600000.json → 1707849600000
+        const timestampA = parseInt(a.replace('snap_', '').replace('.json', ''));
+        const timestampB = parseInt(b.replace('snap_', '').replace('.json', ''));
+        return timestampB - timestampA; // Descending order
+      });
+
+      // Read and return the most recent snapshot
+      const latestFile = snapshotFiles[0];
+      const snapshotPath = path.join(this.snapshotsDir, latestFile);
+      return readJsonSafe(snapshotPath, null);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  /**
+   * Returns a specific snapshot by ID, or null if not found.
+   *
+   * @param {string} snapshotId - The snapshot ID to retrieve (e.g., 'snap_1707849600000')
+   * @returns {object|null} The snapshot object, or null if not found
+   */
+  get(snapshotId) {
+    const snapshotPath = path.join(this.snapshotsDir, `${snapshotId}.json`);
+    return readJsonSafe(snapshotPath, null);
+  }
+
+  /**
+   * Returns an array of snapshot summaries, newest first.
+   *
+   * This method lists all snapshots and returns basic information about each one.
+   * Useful for displaying snapshot history to users or finding specific snapshots.
+   *
+   * @param {number} limit - Maximum number of snapshots to return (default: 20)
+   * @returns {Array} Array of snapshot summary objects
+   *
+   * Each summary contains:
+   * - snapshotId: The unique snapshot identifier
+   * - capturedAt: ISO timestamp of when the snapshot was captured
+   * - capturedBy: Session name that captured the snapshot
+   * - branch: Git branch at the time of capture
+   * - headCommit: Git commit hash at the time of capture
+   */
+  list(limit = 20) {
+    try {
+      // Read all files in the snapshots directory
+      const files = fs.readdirSync(this.snapshotsDir);
+
+      // Filter for snapshot files
+      const snapshotFiles = files.filter(f => f.startsWith('snap_') && f.endsWith('.json'));
+
+      // Read each snapshot and extract summary information
+      const summaries = [];
+      for (const file of snapshotFiles) {
+        const snapshotPath = path.join(this.snapshotsDir, file);
+        const snapshot = readJsonSafe(snapshotPath, null);
+
+        if (snapshot) {
+          // Extract only the summary fields we need
+          summaries.push({
+            snapshotId: snapshot.snapshotId,
+            capturedAt: snapshot.capturedAt,
+            capturedBy: snapshot.capturedBy,
+            branch: snapshot.git ? snapshot.git.branch : null,
+            headCommit: snapshot.git ? snapshot.git.headCommit : null
+          });
+        }
+      }
+
+      // Sort by capturedAt timestamp in descending order (newest first)
+      summaries.sort((a, b) => {
+        return new Date(b.capturedAt) - new Date(a.capturedAt);
+      });
+
+      // Return only the first 'limit' items
+      return summaries.slice(0, limit);
+    } catch (error) {
+      // If there's an error reading the directory, return empty array
+      return [];
+    }
+  }
+
+  /**
+   * Returns the continuity storage directory path for this project.
+   *
+   * This is the root directory where all continuity data is stored
+   * for the current project.
+   *
+   * @returns {string} Absolute path to the storage directory
+   *
+   * Example: 'C:\Users\username\.clearctx\continuity\a1b2c3d4e5f6g7h8'
+   */
+  getProjectDir() {
+    return this.storageDir;
+  }
+
+  /**
+   * Returns the SHA256 hash prefix used for storage.
+   *
+   * This is the 16-character hash derived from the project path,
+   * used to create a unique storage directory for each project.
+   *
+   * @returns {string} The project hash (16 hex characters)
+   *
+   * Example: 'a1b2c3d4e5f6g7h8'
+   */
+  getProjectHash() {
+    return this.projectHash;
+  }
+}
+
+// Export the class directly (CommonJS style)
+module.exports = SessionSnapshot;