amicus 1.0.0

package/src/session-manager.js

@@ -0,0 +1,414 @@
+/**
+ * Session Manager Module
+ *
+ * Spec Reference: Section 8.1 What Gets Persisted, Section 7.4 Metadata Tracking
+ * Manages persistence of sidecar session data.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Session status constants
+ */
+const SESSION_STATUS = {
+  RUNNING: 'running',
+  COMPLETE: 'complete',
+  ERROR: 'error',
+  TIMEOUT: 'timeout'
+};
+
+/** Canonical session dir name — new sessions are written here. */
+const SESSIONS_DIR = 'amicus_sessions';
+// DEPRECATED(amicus-shim): legacy session dir read for pre-rebrand sessions.
+// Remove in a future revision — see docs/SHIMS.md.
+const LEGACY_SESSIONS_DIR = 'sidecar_sessions';
+
+/**
+ * Get the canonical session directory path for a task (used for WRITES).
+ * Spec Reference: §8.1 Session directory structure
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} taskId - Sidecar task ID
+ * @returns {string} Path to the session directory
+ *
+ * @example
+ * getSessionDir('/path/to/project', 'abc123')
+ * // Returns: '/path/to/project/.claude/amicus_sessions/abc123'
+ */
+function getSessionDir(projectDir, taskId) {
+  return path.join(projectDir, '.claude', SESSIONS_DIR, taskId);
+}
+
+/**
+ * Resolve an EXISTING session dir for reads: prefer amicus, fall back to legacy.
+ * Backward-compat shim so pre-rebrand `.claude/sidecar_sessions/` stay visible.
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} taskId - Sidecar task ID
+ * @returns {string} Path to the resolved session directory (defaults to the new path)
+ */
+function resolveExistingSessionDir(projectDir, taskId) {
+  const current = getSessionDir(projectDir, taskId);
+  if (fs.existsSync(current)) { return current; }
+  const legacy = path.join(projectDir, '.claude', LEGACY_SESSIONS_DIR, taskId);
+  if (fs.existsSync(legacy)) { return legacy; }
+  return current; // default to the new path
+}
+
+/**
+ * Create a new sidecar session
+ * Spec Reference: §8.1 What Gets Persisted
+ *
+ * Creates the session directory structure:
+ * .claude/amicus_sessions/<taskId>/
+ * ├── metadata.json
+ * └── conversation.jsonl
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} taskId - Unique task identifier
+ * @param {object} metadata - Session metadata
+ * @param {string} metadata.model - Model being used (e.g., "google/gemini-2.5")
+ * @param {string} metadata.project - Project path
+ * @param {string} [metadata.briefing] - Task briefing
+ * @param {string} [metadata.mode] - Mode: 'interactive' or 'headless'
+ * @param {string} [metadata.thinking='medium'] - Thinking/reasoning intensity level
+ * @throws {Error} If session already exists
+ */
+function createSession(projectDir, taskId, metadata) {
+  const sessionDir = getSessionDir(projectDir, taskId);
+
+  // Check if session already exists
+  if (fs.existsSync(sessionDir)) {
+    throw new Error(`Session ${taskId} already exists`);
+  }
+
+  // Create session directory
+  fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+
+  // Build metadata per spec §7.4
+  const sessionMetadata = {
+    taskId,
+    model: metadata.model,
+    project: metadata.project || projectDir,
+    briefing: metadata.briefing || '',
+    mode: metadata.mode || 'interactive',
+    thinking: metadata.thinking || 'medium',
+    status: SESSION_STATUS.RUNNING,
+    createdAt: new Date().toISOString(),
+    completedAt: null,
+    // File tracking per spec §7.4
+    filesRead: [],
+    filesWritten: [],
+    conflicts: [],
+    contextDrift: null
+  };
+
+  // Write metadata.json
+  fs.writeFileSync(
+    path.join(sessionDir, 'metadata.json'),
+    JSON.stringify(sessionMetadata, null, 2),
+    { mode: 0o600 }
+  );
+
+  // Create empty conversation.jsonl
+  fs.writeFileSync(path.join(sessionDir, 'conversation.jsonl'), '', { mode: 0o600 });
+}
+
+/**
+ * Update session metadata
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} taskId - Task identifier
+ * @param {object} updates - Fields to update
+ * @throws {Error} If session not found
+ */
+function updateSession(projectDir, taskId, updates) {
+  const sessionDir = getSessionDir(projectDir, taskId);
+  const metaPath = path.join(sessionDir, 'metadata.json');
+
+  if (!fs.existsSync(metaPath)) {
+    throw new Error(`Session ${taskId} not found`);
+  }
+
+  // Read existing metadata
+  const metadata = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+
+  // Merge updates
+  // For array fields, we append rather than replace
+  if (updates.filesRead) {
+    metadata.filesRead = [...new Set([...metadata.filesRead, ...updates.filesRead])];
+    delete updates.filesRead;
+  }
+  if (updates.filesWritten) {
+    metadata.filesWritten = [...new Set([...metadata.filesWritten, ...updates.filesWritten])];
+    delete updates.filesWritten;
+  }
+  if (updates.conflicts) {
+    metadata.conflicts = [...metadata.conflicts, ...updates.conflicts];
+    delete updates.conflicts;
+  }
+
+  // Apply remaining updates
+  Object.assign(metadata, updates);
+
+  // Write updated metadata
+  fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Get session metadata
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} taskId - Task identifier
+ * @returns {object|null} Session metadata or null if not found
+ */
+function getSession(projectDir, taskId) {
+  const sessionDir = getSessionDir(projectDir, taskId);
+  const metaPath = path.join(sessionDir, 'metadata.json');
+
+  if (!fs.existsSync(metaPath)) {
+    return null;
+  }
+
+  return JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+}
+
+/**
+ * Save a message to the conversation log
+ * Spec Reference: §8.2 Conversation Capture
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} taskId - Task identifier
+ * @param {object} message - Message to save
+ * @param {string} message.role - Message role ('user', 'assistant', 'system')
+ * @param {string} message.content - Message content
+ * @param {string} [message.timestamp] - ISO timestamp (auto-generated if not provided)
+ * @throws {Error} If session not found
+ */
+function saveConversation(projectDir, taskId, message) {
+  const sessionDir = getSessionDir(projectDir, taskId);
+  const convPath = path.join(sessionDir, 'conversation.jsonl');
+
+  if (!fs.existsSync(sessionDir)) {
+    throw new Error(`Session ${taskId} not found`);
+  }
+
+  // Ensure timestamp is present
+  const messageWithTimestamp = {
+    ...message,
+    timestamp: message.timestamp || new Date().toISOString()
+  };
+
+  // Append to conversation.jsonl
+  fs.appendFileSync(convPath, JSON.stringify(messageWithTimestamp) + '\n', { mode: 0o600 });
+}
+
+/**
+ * Save the session summary
+ * Spec Reference: §8.1 summary.md
+ *
+ * Also updates session status to complete with completedAt timestamp.
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} taskId - Task identifier
+ * @param {string} summary - Summary content (markdown)
+ * @throws {Error} If session not found
+ */
+function saveSummary(projectDir, taskId, summary) {
+  const sessionDir = getSessionDir(projectDir, taskId);
+  const summaryPath = path.join(sessionDir, 'summary.md');
+
+  if (!fs.existsSync(sessionDir)) {
+    throw new Error(`Session ${taskId} not found`);
+  }
+
+  // Write summary file
+  fs.writeFileSync(summaryPath, summary, { mode: 0o600 });
+
+  // Update session status
+  updateSession(projectDir, taskId, {
+    status: SESSION_STATUS.COMPLETE,
+    completedAt: new Date().toISOString()
+  });
+}
+
+/**
+ * Get the sub-agent session directory path
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} parentTaskId - Parent sidecar task ID
+ * @param {string} subagentId - Sub-agent ID
+ * @returns {string} Path to the sub-agent session directory
+ *
+ * @example
+ * getSubagentDir('/path/to/project', 'abc123', 'subagent-xyz')
+ * // Returns: '/path/to/project/.claude/amicus_sessions/abc123/subagents/subagent-xyz'
+ */
+function getSubagentDir(projectDir, parentTaskId, subagentId) {
+  return path.join(getSessionDir(projectDir, parentTaskId), 'subagents', subagentId);
+}
+
+/**
+ * Create a sub-agent session
+ *
+ * Creates the sub-agent directory structure:
+ * .claude/amicus_sessions/<parentTaskId>/subagents/<subagentId>/
+ * ├── metadata.json
+ * └── conversation.jsonl
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} parentTaskId - Parent sidecar task ID
+ * @param {string} subagentId - Sub-agent ID
+ * @param {object} metadata - Sub-agent metadata
+ * @param {string} metadata.agentType - Agent type (general, explore, security, test)
+ * @param {string} metadata.briefing - Task briefing
+ * @returns {string} Path to the created sub-agent directory
+ */
+function createSubagentSession(projectDir, parentTaskId, subagentId, metadata) {
+  const subagentDir = getSubagentDir(projectDir, parentTaskId, subagentId);
+
+  // Create sub-agent directory
+  fs.mkdirSync(subagentDir, { recursive: true, mode: 0o700 });
+
+  // Build sub-agent metadata
+  const subagentMetadata = {
+    subagentId,
+    parentTaskId,
+    agentType: metadata.agentType,
+    briefing: metadata.briefing,
+    status: SESSION_STATUS.RUNNING,
+    createdAt: new Date().toISOString(),
+    completedAt: null
+  };
+
+  // Write metadata
+  fs.writeFileSync(
+    path.join(subagentDir, 'metadata.json'),
+    JSON.stringify(subagentMetadata, null, 2),
+    { mode: 0o600 }
+  );
+
+  // Initialize empty conversation file
+  fs.writeFileSync(path.join(subagentDir, 'conversation.jsonl'), '', { mode: 0o600 });
+
+  return subagentDir;
+}
+
+/**
+ * Update a sub-agent session
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} parentTaskId - Parent sidecar task ID
+ * @param {string} subagentId - Sub-agent ID
+ * @param {object} updates - Fields to update
+ */
+function updateSubagentSession(projectDir, parentTaskId, subagentId, updates) {
+  const subagentDir = getSubagentDir(projectDir, parentTaskId, subagentId);
+  const metadataPath = path.join(subagentDir, 'metadata.json');
+
+  if (!fs.existsSync(metadataPath)) {
+    throw new Error(`Sub-agent ${subagentId} not found`);
+  }
+
+  const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+  const updated = { ...metadata, ...updates };
+  fs.writeFileSync(metadataPath, JSON.stringify(updated, null, 2), { mode: 0o600 });
+}
+
+/**
+ * Get a sub-agent session
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} parentTaskId - Parent sidecar task ID
+ * @param {string} subagentId - Sub-agent ID
+ * @returns {object|null} Sub-agent metadata or null if not found
+ */
+function getSubagentSession(projectDir, parentTaskId, subagentId) {
+  const metadataPath = path.join(getSubagentDir(projectDir, parentTaskId, subagentId), 'metadata.json');
+
+  if (!fs.existsSync(metadataPath)) {
+    return null;
+  }
+
+  return JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+}
+
+/**
+ * List all sub-agents for a parent session
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} parentTaskId - Parent sidecar task ID
+ * @param {object} [filter] - Optional filter options
+ * @param {string} [filter.status] - Filter by status
+ * @param {string} [filter.agentType] - Filter by agent type
+ * @returns {object[]} Array of sub-agent metadata
+ */
+function listSubagents(projectDir, parentTaskId, filter = {}) {
+  const subagentsDir = path.join(getSessionDir(projectDir, parentTaskId), 'subagents');
+
+  if (!fs.existsSync(subagentsDir)) {
+    return [];
+  }
+
+  const subagentIds = fs.readdirSync(subagentsDir).filter(name => {
+    const stat = fs.statSync(path.join(subagentsDir, name));
+    return stat.isDirectory();
+  });
+
+  let subagents = subagentIds.map(id => {
+    const metadata = getSubagentSession(projectDir, parentTaskId, id);
+    return metadata;
+  }).filter(Boolean);
+
+  // Apply filters
+  if (filter.status) {
+    subagents = subagents.filter(s => s.status === filter.status);
+  }
+  if (filter.agentType) {
+    subagents = subagents.filter(s => s.agentType === filter.agentType);
+  }
+
+  return subagents;
+}
+
+/**
+ * Save sub-agent summary
+ *
+ * @param {string} projectDir - Project directory path
+ * @param {string} parentTaskId - Parent sidecar task ID
+ * @param {string} subagentId - Sub-agent ID
+ * @param {string} summary - Summary content
+ */
+function saveSubagentSummary(projectDir, parentTaskId, subagentId, summary) {
+  const subagentDir = getSubagentDir(projectDir, parentTaskId, subagentId);
+  const summaryPath = path.join(subagentDir, 'summary.md');
+
+  fs.writeFileSync(summaryPath, summary, { mode: 0o600 });
+
+  // Update sub-agent status
+  updateSubagentSession(projectDir, parentTaskId, subagentId, {
+    status: SESSION_STATUS.COMPLETE,
+    completedAt: new Date().toISOString()
+  });
+}
+
+module.exports = {
+  createSession,
+  updateSession,
+  getSession,
+  saveConversation,
+  saveSummary,
+  getSessionDir,
+  resolveExistingSessionDir,
+  SESSIONS_DIR,
+  LEGACY_SESSIONS_DIR,
+  SESSION_STATUS,
+  // Sub-agent functions
+  getSubagentDir,
+  createSubagentSession,
+  updateSubagentSession,
+  getSubagentSession,
+  listSubagents,
+  saveSubagentSummary
+};

package/src/session.js

@@ -0,0 +1,180 @@
+/**
+ * Session Resolver
+ *
+ * Spec Reference: §5.1 Session Resolution, §5.2 Claude Code Conversation Storage
+ * Resolves Claude Code session files using primary (explicit ID) and fallback (most recent) strategies.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+/**
+ * Encode a project path for use as a directory name
+ * Spec Reference: §5.2 Path Encoding
+ *
+ * @param {string} projectPath - Absolute project path (e.g., /Users/john/myproject)
+ * @returns {string} Encoded path suitable for directory name (e.g., -Users-john-myproject)
+ *
+ * @example
+ * encodeProjectPath('/Users/john/myproject')
+ * // Returns: '-Users-john-myproject'
+ */
+function encodeProjectPath(projectPath) {
+  // Replace slashes, backslashes, the drive-letter colon, and underscores with
+  // dashes (matching Claude Code behavior). On Windows: C:\Users\x -> C--Users-x.
+  return projectPath.replace(/[/\\:_]/g, '-');
+}
+
+/**
+ * Decode an encoded path back to original format
+ *
+ * @param {string} encodedPath - Encoded path (e.g., -Users-john-myproject)
+ * @returns {string} Decoded path with dashes converted back to slashes
+ */
+function decodeProjectPath(encodedPath) {
+  // Replace dashes with slashes
+  return encodedPath.replace(/-/g, '/');
+}
+
+/**
+ * Get the session directory path for a project
+ * Spec Reference: §5.2 Claude Code Conversation Storage
+ *
+ * @param {string} projectPath - Absolute project path
+ * @param {string} [homeDir] - Optional home directory override (for testing)
+ * @returns {string} Full path to the session directory
+ *
+ * @example
+ * getSessionDirectory('/Users/john/myproject')
+ * // Returns: '~/.claude/projects/-Users-john-myproject'
+ */
+function getSessionDirectory(projectPath, homeDir = os.homedir()) {
+  const encodedPath = encodeProjectPath(projectPath);
+  return path.join(homeDir, '.claude', 'projects', encodedPath);
+}
+
+/**
+ * Extract session ID from a filename
+ *
+ * @param {string} filename - Session filename (e.g., abc123.jsonl or abc123)
+ * @returns {string} Session ID without extension
+ */
+function getSessionId(filename) {
+  return filename.replace(/\.jsonl$/, '');
+}
+
+/**
+ * Resolve a Claude Code session file
+ * Spec Reference: §5.1 Session Resolution (Primary + Fallback)
+ *
+ * Primary: Explicit session ID passed via --session
+ * Fallback: Most recently modified .jsonl file
+ *
+ * @param {string} projectDir - Path to the session directory
+ * @param {string} [sessionArg] - Session ID argument (explicit ID, 'current', or undefined)
+ * @returns {{ path: string|null, method: string, warning?: string }}
+ *
+ * @example
+ * // Explicit session
+ * resolveSession('/path/to/sessions', 'abc123-def456')
+ * // Returns: { path: '/path/to/sessions/abc123-def456.jsonl', method: 'explicit' }
+ *
+ * @example
+ * // Fallback to most recent
+ * resolveSession('/path/to/sessions', 'current')
+ * // Returns: { path: '/path/to/sessions/most-recent.jsonl', method: 'fallback' }
+ */
+function resolveSession(projectDir, sessionArg) {
+  // Check if directory exists
+  if (!fs.existsSync(projectDir)) {
+    return { path: null, method: 'error' };
+  }
+
+  // Primary: explicit session ID
+  if (sessionArg && sessionArg !== 'current' && sessionArg !== '') {
+    // Handle both full filename and just the UUID
+    const filename = sessionArg.endsWith('.jsonl') ? sessionArg : `${sessionArg}.jsonl`;
+    const sessionPath = path.join(projectDir, filename);
+
+    if (fs.existsSync(sessionPath)) {
+      return { path: sessionPath, method: 'explicit' };
+    }
+
+    // Explicit session not found, fall back to most recent with warning
+    const fallback = findMostRecentSession(projectDir);
+    if (fallback.path) {
+      return {
+        path: fallback.path,
+        method: 'fallback',
+        warning: `Session ${sessionArg} not found, falling back to most recent. For reliability, pass --session <id> explicitly.`
+      };
+    }
+
+    return { path: null, method: 'error', warning: `Session ${sessionArg} not found and no fallback available.` };
+  }
+
+  // Fallback: most recently modified .jsonl file
+  return findMostRecentSession(projectDir);
+}
+
+/**
+ * Find the most recently modified .jsonl file in a directory
+ * Also checks for ambiguity (multiple recent sessions)
+ *
+ * @param {string} projectDir - Path to the session directory
+ * @returns {{ path: string|null, method: string, warning?: string }}
+ */
+function findMostRecentSession(projectDir) {
+  let files;
+  try {
+    files = fs.readdirSync(projectDir);
+  } catch (error) {
+    return { path: null, method: 'error' };
+  }
+
+  // Get all .jsonl files with their modification times
+  const sessions = files
+    .filter(f => f.endsWith('.jsonl'))
+    .map(f => {
+      const filePath = path.join(projectDir, f);
+      try {
+        const stat = fs.statSync(filePath);
+        return {
+          name: f,
+          path: filePath,
+          mtime: stat.mtime.getTime()
+        };
+      } catch (error) {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((a, b) => b.mtime - a.mtime); // Sort by mtime descending
+
+  if (sessions.length === 0) {
+    return { path: null, method: 'fallback' };
+  }
+
+  // Check for ambiguity: multiple sessions modified in last 5 minutes
+  const fiveMinutesAgo = Date.now() - 5 * 60 * 1000;
+  const recentSessions = sessions.filter(s => s.mtime > fiveMinutesAgo);
+
+  if (recentSessions.length > 1) {
+    return {
+      path: sessions[0].path,
+      method: 'fallback',
+      warning: `${recentSessions.length} active sessions detected. Using most recent. For reliability, pass --session <id> explicitly.`
+    };
+  }
+
+  return { path: sessions[0].path, method: 'fallback' };
+}
+
+module.exports = {
+  encodeProjectPath,
+  decodeProjectPath,
+  getSessionDirectory,
+  getSessionId,
+  resolveSession
+};