clearctx 3.0.0

package/src/decision-journal.js

@@ -0,0 +1,229 @@
+/**
+ * Decision Journal — tracks architectural decisions, choices, and rationale
+ * Part of the Session Continuity Engine (Layer 0)
+ *
+ * This module helps maintain a record of important decisions made during
+ * development, including the reasoning behind them. This helps future sessions
+ * understand why certain choices were made.
+ *
+ * Storage: JSONL format (one JSON object per line)
+ * Location: ~/.clearctx/continuity/{projectHash}/journal.jsonl
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { readJsonSafe, appendJsonl } = require('./atomic-io');
+
+/**
+ * DecisionJournal class
+ *
+ * Manages a journal of decisions for a specific project.
+ * Each decision includes:
+ * - What was decided
+ * - Why it was decided
+ * - Related files
+ * - Tags for categorization
+ * - Additional context
+ */
+class DecisionJournal {
+  /**
+   * Create a new Decision Journal
+   *
+   * @param {string} projectPath - Absolute path to the project directory
+   *
+   * The journal is stored in a directory based on a hash of the project path,
+   * so each project gets its own isolated journal.
+   */
+  constructor(projectPath) {
+    // Create a unique hash for this project (16 characters)
+    // This ensures each project has its own journal storage
+    const projectHash = crypto
+      .createHash('sha256')
+      .update(projectPath)
+      .digest('hex')
+      .slice(0, 16);
+
+    // Set up storage directory: ~/.clearctx/continuity/{hash}
+    this.storageDir = path.join(
+      os.homedir(),
+      '.clearctx',
+      'continuity',
+      projectHash
+    );
+
+    // The journal file is a JSONL file (one JSON object per line)
+    this.journalPath = path.join(this.storageDir, 'journal.jsonl');
+
+    // Create the storage directory if it doesn't exist yet
+    if (!fs.existsSync(this.storageDir)) {
+      fs.mkdirSync(this.storageDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Add a new decision to the journal
+   *
+   * @param {Object} params - Decision parameters
+   * @param {string} params.decision - The decision that was made (required)
+   * @param {string} [params.reason] - Why this decision was made
+   * @param {string[]} [params.files] - Related file paths
+   * @param {string[]} [params.tags] - Tags for categorization (e.g., ['auth', 'security'])
+   * @param {string} [params.context] - Additional context or notes
+   * @returns {Object} The created decision entry with ID and timestamp
+   *
+   * Example:
+   *   journal.add({
+   *     decision: 'Use bcrypt for password hashing',
+   *     reason: 'More mature and widely tested than argon2',
+   *     files: ['src/auth.js'],
+   *     tags: ['security', 'auth']
+   *   })
+   */
+  add({ decision, reason, files, tags, context }) {
+    // Generate a unique ID for this decision
+    // Format: d_{timestamp}_{random} (e.g., d_1707840000000_a3f2b1c4)
+    const id = 'd_' + Date.now() + '_' + crypto.randomBytes(4).toString('hex');
+
+    // Build the decision entry
+    const entry = {
+      id,
+      decision,                      // The decision itself (required)
+      reason: reason || '',          // Why it was made (optional)
+      files: files || [],            // Related files (optional)
+      tags: tags || [],              // Tags for filtering (optional)
+      context: context || '',        // Extra context (optional)
+      createdAt: new Date().toISOString()  // When it was created
+    };
+
+    // Append to the journal file (one line per decision)
+    appendJsonl(this.journalPath, entry);
+
+    // Return the entry so the caller knows what was saved
+    return entry;
+  }
+
+  /**
+   * List decisions from the journal
+   *
+   * @param {Object} [options] - Filter and pagination options
+   * @param {number} [options.limit=50] - Maximum number of decisions to return
+   * @param {string} [options.tag] - Only return decisions with this tag
+   * @param {string} [options.since] - Only return decisions after this date (ISO string)
+   * @returns {Object[]} Array of decision entries, newest first
+   *
+   * Example:
+   *   journal.list({ limit: 10, tag: 'auth' })
+   *   journal.list({ since: '2024-01-01T00:00:00Z' })
+   */
+  list({ limit = 50, tag, since } = {}) {
+    // If the journal file doesn't exist yet, return empty array
+    if (!fs.existsSync(this.journalPath)) {
+      return [];
+    }
+
+    // Read the entire journal file
+    const content = fs.readFileSync(this.journalPath, 'utf-8');
+
+    // Parse each line as JSON (JSONL format)
+    const entries = content
+      .split('\n')                    // Split into lines
+      .filter(line => line.trim())   // Remove empty lines
+      .map(line => JSON.parse(line)); // Parse each line as JSON
+
+    // Start with all entries
+    let filtered = entries;
+
+    // Filter by tag if specified
+    if (tag) {
+      filtered = filtered.filter(entry => entry.tags.includes(tag));
+    }
+
+    // Filter by date if specified
+    if (since) {
+      const sinceDate = new Date(since);
+      filtered = filtered.filter(entry => new Date(entry.createdAt) >= sinceDate);
+    }
+
+    // Sort by creation date, newest first
+    // (Reverse because JSONL is in chronological order)
+    filtered.reverse();
+
+    // Return only the requested number of entries
+    return filtered.slice(0, limit);
+  }
+
+  /**
+   * Search for decisions by keyword
+   *
+   * @param {string} keyword - Search term (case-insensitive)
+   * @returns {Object[]} Array of matching decision entries, newest first
+   *
+   * Searches across the decision text, reason, and context fields.
+   *
+   * Example:
+   *   journal.search('bcrypt')
+   *   journal.search('authentication')
+   */
+  search(keyword) {
+    // If the journal file doesn't exist yet, return empty array
+    if (!fs.existsSync(this.journalPath)) {
+      return [];
+    }
+
+    // Read and parse all entries (same as list())
+    const content = fs.readFileSync(this.journalPath, 'utf-8');
+    const entries = content
+      .split('\n')
+      .filter(line => line.trim())
+      .map(line => JSON.parse(line));
+
+    // Convert keyword to lowercase for case-insensitive search
+    const searchTerm = keyword.toLowerCase();
+
+    // Find entries where the keyword appears in decision, reason, or context
+    const matches = entries.filter(entry => {
+      return (
+        entry.decision.toLowerCase().includes(searchTerm) ||
+        entry.reason.toLowerCase().includes(searchTerm) ||
+        entry.context.toLowerCase().includes(searchTerm)
+      );
+    });
+
+    // Return matches, newest first
+    return matches.reverse();
+  }
+
+  /**
+   * Get a specific decision by its ID
+   *
+   * @param {string} decisionId - The decision ID to retrieve
+   * @returns {Object|null} The decision entry, or null if not found
+   *
+   * Example:
+   *   journal.get('d_1707840000000_a3f2b1c4')
+   */
+  get(decisionId) {
+    // If the journal file doesn't exist yet, return null
+    if (!fs.existsSync(this.journalPath)) {
+      return null;
+    }
+
+    // Read and parse all entries
+    const content = fs.readFileSync(this.journalPath, 'utf-8');
+    const entries = content
+      .split('\n')
+      .filter(line => line.trim())
+      .map(line => JSON.parse(line));
+
+    // Find the entry with matching ID
+    const entry = entries.find(e => e.id === decisionId);
+
+    // Return the entry or null if not found
+    return entry || null;
+  }
+}
+
+// Export the class so other modules can use it
+module.exports = DecisionJournal;

package/src/delegate.js

@@ -0,0 +1,348 @@
+/**
+ * Delegate — The Control Loop for intelligent task delegation.
+ *
+ * This is what makes the system truly human-like. Instead of just
+ * sending messages and getting responses, the Delegate system:
+ *
+ * 1. Spawns a child session with the right permissions
+ * 2. Sends the task
+ * 3. Monitors the response for issues (permission denials, errors, going off-track)
+ * 4. Auto-handles common problems (permission retries, error recovery)
+ * 5. Returns structured output for the parent Claude to evaluate
+ * 6. Accepts follow-up instructions and continues the loop
+ *
+ * The parent Claude acts as the "brain" — it reads the structured output,
+ * decides if the work is good, and sends corrections or approvals.
+ *
+ * Usage:
+ *   const delegate = new Delegate(manager);
+ *
+ *   // Simple one-shot delegation
+ *   const result = await delegate.run('fix-auth', {
+ *     task: 'Fix the authentication bug in auth.service.ts',
+ *     model: 'sonnet',
+ *     maxCost: 0.50,
+ *   });
+ *   console.log(result.status);  // 'completed', 'needs_input', 'failed', 'budget_exceeded'
+ *   console.log(result.response); // The actual work done
+ *
+ *   // Multi-step delegation with evaluation
+ *   const r1 = await delegate.run('build-feature', { task: 'Build login page' });
+ *   // Parent evaluates r1.response...
+ *   const r2 = await delegate.continue('build-feature', 'Good, now add form validation');
+ *   // Parent evaluates r2.response...
+ *   const r3 = await delegate.continue('build-feature', 'Perfect. Now write tests.');
+ *   delegate.finish('build-feature');
+ */
+
+const SafetyNet = require('./safety-net');
+
+// Permission mode recommendations based on task type
+const PERMISSION_PRESETS = {
+  // Read-only: can search and read but not modify
+  'read-only': {
+    permissionMode: 'default',
+    allowedTools: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'Task', 'TaskOutput'],
+  },
+  // Code review: read + analyze
+  'review': {
+    permissionMode: 'default',
+    allowedTools: ['Read', 'Glob', 'Grep', 'WebSearch', 'WebFetch', 'Task', 'TaskOutput'],
+  },
+  // Edit files: can read and edit but limited bash
+  'edit': {
+    permissionMode: 'acceptEdits',
+    allowedTools: [], // All tools, but auto-accept edits
+  },
+  // Full access: can do anything (use with caution)
+  'full': {
+    permissionMode: 'bypassPermissions',
+    allowedTools: [],
+  },
+  // Plan only: can explore but not execute
+  'plan': {
+    permissionMode: 'plan',
+    allowedTools: [],
+  },
+};
+
+class Delegate {
+  /**
+   * @param {SessionManager} manager - The session manager instance
+   */
+  constructor(manager) {
+    this.manager = manager;
+    this.safetyNets = new Map(); // name -> SafetyNet
+  }
+
+  /**
+   * Run a task in a new delegated session.
+   *
+   * This is the main entry point. It:
+   * 1. Creates a session with appropriate permissions
+   * 2. Attaches safety limits
+   * 3. Sends the task
+   * 4. Detects and auto-handles permission issues
+   * 5. Returns structured output
+   *
+   * @param {string} name - Session name
+   * @param {object} options - Task configuration
+   * @param {string} options.task - The task description
+   * @param {string} [options.model='sonnet'] - Model to use
+   * @param {string} [options.preset='edit'] - Permission preset
+   * @param {string} [options.workDir] - Working directory
+   * @param {number} [options.maxCost=2.00] - Max cost in USD
+   * @param {number} [options.maxTurns=50] - Max agent turns
+   * @param {string} [options.context] - Extra context to prepend
+   * @param {string} [options.systemPrompt] - System prompt append
+   * @param {string} [options.agent] - Agent to use
+   * @param {boolean} [options.safety=true] - Enable safety net (set false to disable)
+   * @returns {Promise<DelegateResult>} Structured result
+   */
+  async run(name, options = {}) {
+    const task = options.task;
+    if (!task) throw new Error('options.task is required');
+
+    // Get permission preset
+    const preset = PERMISSION_PRESETS[options.preset || 'edit'] || PERMISSION_PRESETS.edit;
+
+    // Create safety net (only if not disabled)
+    // options.safety defaults to true — pass safety: false to disable
+    const useSafety = options.safety !== false;
+    const safety = useSafety
+      ? new SafetyNet({
+          maxCostUsd: options.maxCost ?? 2.00,
+          maxTurns: options.maxTurns ?? 50,
+          maxDurationMs: options.maxDuration ?? 300000,
+          protectedPaths: options.protectedPaths,
+        })
+      : null;
+
+    // Build the full prompt with context and instructions
+    const fullPrompt = this._buildPrompt(task, options.context, name);
+
+    // Spawn the session
+    let spawnResult;
+    try {
+      spawnResult = await this.manager.spawn(name, {
+        prompt: fullPrompt,
+        model: options.model || 'sonnet',
+        workDir: options.workDir || process.cwd(),
+        permissionMode: preset.permissionMode,
+        allowedTools: preset.allowedTools.length > 0 ? preset.allowedTools : undefined,
+        systemPrompt: options.systemPrompt,
+        agent: options.agent,
+      });
+    } catch (err) {
+      return this._makeResult('failed', null, null, {
+        error: err.message,
+        name,
+      });
+    }
+
+    // Attach safety net to the live session (only if enabled)
+    if (safety) {
+      const session = this.manager.sessions.get(name);
+      if (session) {
+        safety.attach(session);
+        this.safetyNets.set(name, safety);
+      }
+    }
+
+    const response = spawnResult.response;
+
+    // Check if the response indicates a permission issue
+    if (response && this._isPermissionDenied(response.text)) {
+      // Auto-retry with permission granted
+      const retryResult = await this._handlePermissionRetry(name, response.text);
+      if (retryResult) {
+        return this._makeResult('completed', retryResult, safety, { name });
+      }
+    }
+
+    // Check safety violations (only if safety is enabled)
+    if (safety && safety.violations.length > 0) {
+      const lastViolation = safety.violations[safety.violations.length - 1];
+      return this._makeResult(lastViolation.type, response, safety, { name });
+    }
+
+    // Return structured result
+    return this._makeResult('completed', response, safety, { name });
+  }
+
+  /**
+   * Continue a delegated task with follow-up instructions.
+   *
+   * The parent Claude evaluates the previous result and sends corrections,
+   * additional instructions, or approval.
+   *
+   * @param {string} name - Session name
+   * @param {string} message - Follow-up instruction
+   * @returns {Promise<DelegateResult>} Structured result
+   */
+  async continue(name, message) {
+    const safety = this.safetyNets.get(name);
+
+    let response;
+    try {
+      response = await this.manager.send(name, message);
+    } catch (err) {
+      // Session might be stopped — try auto-resume
+      try {
+        response = await this.manager.resume(name, message);
+        // Re-attach safety net to new session
+        const session = this.manager.sessions.get(name);
+        if (session && safety) {
+          safety.attach(session);
+        }
+      } catch (resumeErr) {
+        return this._makeResult('failed', null, safety, {
+          error: resumeErr.message,
+          name,
+        });
+      }
+    }
+
+    // Check for permission issues
+    if (response && this._isPermissionDenied(response.text)) {
+      const retryResult = await this._handlePermissionRetry(name, response.text);
+      if (retryResult) {
+        return this._makeResult('completed', retryResult, safety, { name });
+      }
+    }
+
+    // Check safety violations
+    if (safety && safety.violations.length > 0) {
+      const lastViolation = safety.violations[safety.violations.length - 1];
+      return this._makeResult(lastViolation.type, response, safety, { name });
+    }
+
+    return this._makeResult('completed', response, safety, { name });
+  }
+
+  /**
+   * Finish a delegated task — stop the session.
+   */
+  finish(name) {
+    try {
+      this.manager.stop(name);
+    } catch (e) {
+      // Session might already be stopped
+    }
+    this.safetyNets.delete(name);
+  }
+
+  /**
+   * Kill a delegated task immediately.
+   */
+  abort(name) {
+    try {
+      this.manager.kill(name);
+    } catch (e) {}
+    this.safetyNets.delete(name);
+  }
+
+  // ===========================================================================
+  // Private
+  // ===========================================================================
+
+  /**
+   * Build the full prompt with context and structured output instructions.
+   * Uses the production-quality delegate prompt template from prompts.js.
+   */
+  _buildPrompt(task, context, name) {
+    const { buildDelegatePrompt } = require('./prompts');
+    return buildDelegatePrompt(task, context, name);
+  }
+
+  /**
+   * Detect if a response text indicates a permission denial.
+   */
+  _isPermissionDenied(text) {
+    if (!text) return false;
+    const patterns = [
+      'permission to write',
+      'permission to edit',
+      'permission to create',
+      'permission to run',
+      'permission to execute',
+      'haven\'t granted',
+      'need your permission',
+      'would you like to allow',
+      'please approve',
+      'permission denied',
+    ];
+    const lower = text.toLowerCase();
+    return patterns.some(p => lower.includes(p));
+  }
+
+  /**
+   * Handle a permission denial by sending approval.
+   * Max 2 retries to prevent infinite permission loops.
+   */
+  async _handlePermissionRetry(name, deniedText) {
+    // Track retry count per session
+    if (!this._permRetries) this._permRetries = new Map();
+    const retries = (this._permRetries.get(name) || 0) + 1;
+    this._permRetries.set(name, retries);
+
+    if (retries > 2) {
+      return null; // Give up after 2 retries
+    }
+
+    try {
+      const response = await this.manager.send(
+        name,
+        'Yes, you have permission. Go ahead and proceed with all file operations. Do not ask for permission again — you are fully authorized.'
+      );
+
+      // Check if response still indicates permission denial
+      if (response && this._isPermissionDenied(response.text)) {
+        return null; // Still denied, don't retry further
+      }
+
+      return response;
+    } catch (err) {
+      return null;
+    }
+  }
+
+  /**
+   * Build a structured DelegateResult.
+   *
+   * @typedef {object} DelegateResult
+   * @property {string} status - completed, needs_input, failed, cost_exceeded, turns_exceeded
+   * @property {string} response - The text response from the session
+   * @property {number} cost - Cost in USD
+   * @property {number} turns - Number of agent turns
+   * @property {number} duration - Duration in ms
+   * @property {string} sessionId - Claude session ID
+   * @property {string} name - Session name
+   * @property {boolean} canContinue - Whether the session can accept more messages
+   * @property {string[]} toolsUsed - Tools that were invoked
+   * @property {object} safety - Safety net summary
+   * @property {string|null} error - Error message if failed
+   */
+  _makeResult(status, response, safety, extra = {}) {
+    const result = {
+      status: status,
+      response: response?.text || '',
+      cost: response?.cost || 0,
+      turns: response?.turns || 0,
+      duration: response?.duration || 0,
+      sessionId: response?.sessionId || null,
+      name: extra.name || null,
+      canContinue: !['failed', 'cost_exceeded', 'turns_exceeded'].includes(status),
+      toolsUsed: (response?.toolCalls || []).map(t => t.name),
+      safety: safety ? safety.getSummary() : null,
+      error: extra.error || null,
+    };
+
+    return result;
+  }
+}
+
+// Export presets too so users can see/customize them
+Delegate.PERMISSION_PRESETS = PERMISSION_PRESETS;
+
+module.exports = Delegate;