amicus 1.0.0

package/src/context.js

@@ -0,0 +1,199 @@
+/**
+ * Context Filtering Module
+ *
+ * Spec Reference: Section 5.3 Context Filtering Algorithm
+ * Extracts and filters context from Claude Code sessions for sidecar use.
+ */
+
+const { readJSONL, formatContext } = require('./jsonl-parser');
+
+/**
+ * Parse a duration string into milliseconds
+ * Spec Reference: §4.1 --context-since option
+ *
+ * @param {string} durationStr - Duration string (e.g., "30m", "2h", "1d")
+ * @returns {number} Duration in milliseconds, or 0 if invalid
+ *
+ * @example
+ * parseDuration('30m') // Returns: 1800000 (30 * 60 * 1000)
+ * parseDuration('2h')  // Returns: 7200000 (2 * 60 * 60 * 1000)
+ * parseDuration('1d')  // Returns: 86400000 (24 * 60 * 60 * 1000)
+ */
+function parseDuration(durationStr) {
+  if (!durationStr || typeof durationStr !== 'string') {
+    return 0;
+  }
+
+  const match = durationStr.match(/^(\d+)([mhd])$/);
+  if (!match) {
+    return 0;
+  }
+
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+
+  const multipliers = {
+    m: 60 * 1000,           // minutes to ms
+    h: 60 * 60 * 1000,      // hours to ms
+    d: 24 * 60 * 60 * 1000  // days to ms
+  };
+
+  return value * multipliers[unit];
+}
+
+/**
+ * Estimate token count from text
+ * Spec Reference: §5.3 "~4 chars per token"
+ *
+ * @param {string} text - Text to estimate tokens for
+ * @returns {number} Estimated token count
+ */
+function estimateTokens(text) {
+  if (!text || typeof text !== 'string') {
+    return 0;
+  }
+  // Spec specifies ~4 chars per token
+  return Math.floor(text.length / 4);
+}
+
+/**
+ * Extract the last N user turns from messages
+ * A "turn" is defined as a user message plus all subsequent messages until the next user message.
+ *
+ * @param {object[]} messages - Array of message objects
+ * @param {number} n - Number of turns to keep
+ * @returns {object[]} Messages from the last N turns
+ *
+ * @example
+ * // Given messages: [user1, assistant1, user2, assistant2, user3, assistant3]
+ * // takeLastNTurns(messages, 2) returns: [user2, assistant2, user3, assistant3]
+ */
+function takeLastNTurns(messages, n) {
+  if (!messages || messages.length === 0 || n <= 0) {
+    return [];
+  }
+
+  // Find indices of all user messages (turns)
+  const userIndices = [];
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i].type === 'user') {
+      userIndices.push(i);
+    }
+  }
+
+  // If we have fewer turns than requested, return all messages
+  if (userIndices.length <= n) {
+    return messages;
+  }
+
+  // Get the starting index for the last N turns
+  const startTurnIndex = userIndices.length - n;
+  const startIdx = userIndices[startTurnIndex];
+
+  // Return all messages from that point
+  return messages.slice(startIdx);
+}
+
+/**
+ * Filter messages by time
+ *
+ * @param {object[]} messages - Array of message objects
+ * @param {number} sinceMs - Duration in milliseconds
+ * @returns {object[]} Messages within the time window
+ */
+function filterByTime(messages, sinceMs) {
+  const cutoff = Date.now() - sinceMs;
+
+  return messages.filter(msg => {
+    if (!msg.timestamp) {
+      return false;
+    }
+    const msgTime = new Date(msg.timestamp).getTime();
+    return msgTime >= cutoff;
+  });
+}
+
+/**
+ * Truncate context from start to fit within token limit
+ * Spec Reference: §5.3 "Truncate from start if over limit, prepend [Earlier context truncated...]"
+ *
+ * @param {string} context - Formatted context string
+ * @param {number} maxTokens - Maximum token limit
+ * @returns {string} Truncated context with notice if needed
+ */
+function truncateToTokenLimit(context, maxTokens) {
+  const maxChars = maxTokens * 4; // ~4 chars per token
+
+  if (context.length <= maxChars) {
+    return context;
+  }
+
+  // Truncate from start, keeping the end (most recent)
+  const truncated = context.slice(-maxChars);
+
+  // Prepend truncation notice
+  return '[Earlier context truncated...]\n\n' + truncated;
+}
+
+/**
+ * Filter context from a Claude Code session
+ * Spec Reference: §5.3 Context Filtering Algorithm
+ *
+ * @param {string} sessionPath - Path to the session JSONL file
+ * @param {object} options - Filtering options
+ * @param {number} [options.turns=50] - Max conversation turns to include
+ * @param {string} [options.since] - Time filter (e.g., "2h"). Overrides turns if specified.
+ * @param {number} [options.maxTokens=80000] - Hard cap on context tokens
+ * @returns {string} Filtered and formatted context string
+ *
+ * @throws {Error} If session file cannot be read
+ *
+ * @example
+ * // Filter last 50 turns, max 80000 tokens
+ * filterContext('/path/to/session.jsonl', { turns: 50, maxTokens: 80000 })
+ *
+ * @example
+ * // Filter by time (last 2 hours), overrides turns
+ * filterContext('/path/to/session.jsonl', { since: '2h', turns: 50, maxTokens: 80000 })
+ */
+function filterContext(sessionPath, options = {}) {
+  const {
+    turns = 50,
+    since,
+    maxTokens = 80000
+  } = options;
+
+  // Read and parse the session file
+  let messages = readJSONL(sessionPath);
+
+  if (messages.length === 0) {
+    return '';
+  }
+
+  // Apply filtering: time-based filter takes precedence over turns
+  if (since) {
+    const sinceMs = parseDuration(since);
+    if (sinceMs > 0) {
+      messages = filterByTime(messages, sinceMs);
+    }
+  } else if (turns) {
+    messages = takeLastNTurns(messages, turns);
+  }
+
+  // Format messages into context string
+  let context = formatContext(messages);
+
+  // Truncate to token limit if needed
+  if (estimateTokens(context) > maxTokens) {
+    context = truncateToTokenLimit(context, maxTokens);
+  }
+
+  return context;
+}
+
+module.exports = {
+  filterContext,
+  parseDuration,
+  estimateTokens,
+  takeLastNTurns
+};

package/src/drift.js

@@ -0,0 +1,144 @@
+/**
+ * Context Drift Detection Module
+ *
+ * Spec Reference: Section 7.3 Context Drift Indicator
+ * Detects and reports context staleness in sidecar sessions.
+ */
+
+const fs = require('fs');
+const { readJSONL } = require('./jsonl-parser');
+
+/**
+ * Count user turns in a session since a given time
+ * A "turn" is defined as a user message.
+ *
+ * @param {string} sessionPath - Path to the session JSONL file
+ * @param {Date|string} sinceTime - Count turns after this time
+ * @returns {number} Number of user turns since the specified time
+ */
+function countTurnsSince(sessionPath, sinceTime) {
+  // Handle non-existent file
+  if (!fs.existsSync(sessionPath)) {
+    return 0;
+  }
+
+  // Normalize time to Date
+  const since = sinceTime instanceof Date ? sinceTime : new Date(sinceTime);
+
+  let messages;
+  try {
+    messages = readJSONL(sessionPath);
+  } catch (error) {
+    return 0;
+  }
+
+  // Count user messages after sinceTime
+  let count = 0;
+  for (const msg of messages) {
+    if (msg.type !== 'user') {
+      continue;
+    }
+
+    // Skip messages without timestamps
+    if (!msg.timestamp) {
+      continue;
+    }
+
+    const msgTime = new Date(msg.timestamp);
+    if (msgTime > since) {
+      count++;
+    }
+  }
+
+  return count;
+}
+
+/**
+ * Check if drift is significant
+ * Spec Reference: §7.3 "Significant threshold: >10 min OR >5 turns"
+ *
+ * @param {number} ageMinutes - Age of the sidecar session in minutes
+ * @param {number} mainTurns - Number of turns in main session since sidecar started
+ * @returns {boolean} True if drift is significant
+ */
+function isDriftSignificant(ageMinutes, mainTurns) {
+  // Spec §7.3: isSignificant: ageMinutes > 10 || mainTurns > 5
+  return ageMinutes > 10 || mainTurns > 5;
+}
+
+/**
+ * Calculate context drift for a sidecar session
+ * Spec Reference: §7.3 Context Drift Indicator
+ *
+ * @param {Date|string} sessionStartTime - When the sidecar session started
+ * @param {string} mainSessionPath - Path to the main Claude Code session JSONL
+ * @returns {object} Drift information
+ * @returns {number} returns.ageMinutes - Minutes since sidecar started
+ * @returns {number} returns.mainTurns - Turns in main session since sidecar started
+ * @returns {boolean} returns.isSignificant - Whether drift exceeds thresholds
+ *
+ * @example
+ * const drift = calculateDrift(sessionStartTime, '/path/to/main-session.jsonl');
+ * // Returns: { ageMinutes: 23, mainTurns: 15, isSignificant: true }
+ */
+function calculateDrift(sessionStartTime, mainSessionPath) {
+  // Normalize session start time
+  const startTime = sessionStartTime instanceof Date
+    ? sessionStartTime
+    : new Date(sessionStartTime);
+
+  // Calculate age in minutes
+  const ageMs = Date.now() - startTime.getTime();
+  const ageMinutes = Math.round(ageMs / 60000);
+
+  // Count turns in main session since sidecar started
+  const mainTurns = countTurnsSince(mainSessionPath, startTime);
+
+  // Determine if drift is significant per spec §7.3
+  const isSignificant = isDriftSignificant(ageMinutes, mainTurns);
+
+  return {
+    ageMinutes,
+    mainTurns,
+    isSignificant
+  };
+}
+
+/**
+ * Format drift warning for summary output
+ * Spec Reference: §7.3 Context Drift Indicator format
+ *
+ * @param {object} drift - Drift object from calculateDrift
+ * @returns {string} Formatted drift indicator string
+ *
+ * @example
+ * formatDriftWarning({ ageMinutes: 23, mainTurns: 15, isSignificant: true })
+ * // Returns:
+ * // 📍 **Context Age:** 23 minutes (15 conversation turns in main session)
+ * //
+ * // ⚠️ **Drift Warning:** Main session has continued significantly since this
+ * // sidecar started. Verify recommendations against current project state.
+ */
+function formatDriftWarning(drift) {
+  if (!drift) {
+    return '';
+  }
+
+  const lines = [
+    `\uD83D\uDCCD **Context Age:** ${drift.ageMinutes} minutes (${drift.mainTurns} conversation turns in main session)`
+  ];
+
+  if (drift.isSignificant) {
+    lines.push('');
+    lines.push('\u26A0\uFE0F **Drift Warning:** Main session has continued significantly since this sidecar started. Verify recommendations against current project state.');
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  calculateDrift,
+  formatDriftWarning,
+  countTurnsSince,
+  isDriftSignificant
+};

package/src/environment.js

@@ -0,0 +1,157 @@
+/**
+ * Environment Detection Module
+ *
+ * Detects the client type (code-local, code-web, cowork), determines
+ * display availability, and resolves the session root directory based
+ * on platform and CLI arguments.
+ */
+
+const path = require('path');
+const os = require('os');
+const { logger } = require('./utils/logger');
+
+/**
+ * Valid client types for the --client flag
+ * @type {string[]}
+ */
+const VALID_CLIENTS = ['code-local', 'code-web', 'cowork'];
+
+/**
+ * Infer the client type from args and platform
+ *
+ * @param {object} args - Parsed CLI arguments
+ * @param {string} [args.client] - Explicit client type
+ * @param {string} platform - OS platform (e.g., 'darwin', 'linux', 'win32')
+ * @returns {string} The inferred client type
+ * @throws {Error} If args.client is provided but not a valid value
+ */
+function inferClient(args, platform) {
+  if (args.client) {
+    if (!VALID_CLIENTS.includes(args.client)) {
+      throw new Error(
+        `Invalid client '${args.client}'. Valid values: ${VALID_CLIENTS.join(', ')}`
+      );
+    }
+    logger.debug('Using explicit client', { client: args.client });
+    return args.client;
+  }
+
+  if (platform === 'darwin') {
+    logger.debug('Detected code-local on macOS');
+    return 'code-local';
+  }
+
+  if (process.env.DISPLAY || process.env.WAYLAND_DISPLAY) {
+    logger.debug('Detected code-local via display env var', {
+      DISPLAY: process.env.DISPLAY || null,
+      WAYLAND_DISPLAY: process.env.WAYLAND_DISPLAY || null
+    });
+    return 'code-local';
+  }
+
+  logger.debug('No display detected, defaulting to code-web', { platform });
+  return 'code-web';
+}
+
+/**
+ * Encode a filesystem path for use as a directory name.
+ * Replaces /, \, the drive-letter colon, and _ with dashes (matches Claude Code).
+ *
+ * @param {string} cwdPath - The working directory path
+ * @returns {string} Encoded path safe for directory names
+ */
+function encodePath(cwdPath) {
+  return cwdPath.replace(/[/\\:_]/g, '-');
+}
+
+/**
+ * Resolve the cowork local-agent-mode-sessions root for the given platform.
+ * Cowork stores session audit logs inside Claude Desktop's Application Support
+ * under local-agent-mode-sessions/<org>/<user>/local_<id>/audit.jsonl.
+ *
+ * @param {string} platform - OS platform
+ * @returns {string} Cowork session root directory
+ */
+function getCoworkRoot(platform) {
+  const homedir = os.homedir();
+
+  if (platform === 'darwin') {
+    return path.join(homedir, 'Library', 'Application Support', 'Claude', 'local-agent-mode-sessions');
+  }
+
+  if (platform === 'win32') {
+    const appdata = process.env.APPDATA || path.join(homedir, 'AppData', 'Roaming');
+    return path.join(appdata, 'Claude', 'local-agent-mode-sessions');
+  }
+
+  // Linux and other Unix-like systems
+  return path.join(homedir, '.config', 'Claude', 'local-agent-mode-sessions');
+}
+
+/**
+ * Get the session root directory based on client type and platform
+ *
+ * @param {object} args - Parsed CLI arguments
+ * @param {string} [args.sessionDir] - Explicit session directory
+ * @param {string} args.client - Client type (code-local, code-web, cowork)
+ * @param {string} [args.cwd] - Working directory (defaults to process.cwd())
+ * @param {string} platform - OS platform
+ * @returns {string} Resolved session root directory path
+ * @throws {Error} If client is code-web and --session-dir is not provided
+ */
+function getSessionRoot(args, platform) {
+  if (args.sessionDir) {
+    logger.debug('Using explicit session directory', { sessionDir: args.sessionDir });
+    return args.sessionDir;
+  }
+
+  const { client } = args;
+
+  if (client === 'code-local') {
+    const cwd = args.cwd || process.cwd();
+    const encodedPath = encodePath(cwd);
+    const sessionRoot = path.join(os.homedir(), '.claude', 'projects', encodedPath);
+    logger.debug('Resolved code-local session root', { cwd, sessionRoot });
+    return sessionRoot;
+  }
+
+  if (client === 'code-web') {
+    throw new Error('--session-dir is required when --client is code-web');
+  }
+
+  if (client === 'cowork') {
+    const sessionRoot = getCoworkRoot(platform);
+    logger.debug('Resolved cowork session root', { platform, sessionRoot });
+    return sessionRoot;
+  }
+
+  throw new Error(`Unknown client type: ${client}`);
+}
+
+/**
+ * Detect the full environment configuration
+ *
+ * @param {object} args - Parsed CLI arguments
+ * @param {string} [args.client] - Explicit client type
+ * @param {string} [args.sessionDir] - Explicit session directory
+ * @param {string} [args.cwd] - Working directory
+ * @param {string} platform - OS platform
+ * @returns {{ client: string, hasDisplay: boolean, sessionRoot: string }}
+ */
+function detectEnvironment(args, platform) {
+  const client = inferClient(args, platform);
+  const hasDisplay = client !== 'code-web';
+  const resolvedArgs = { ...args, client };
+  const sessionRoot = getSessionRoot(resolvedArgs, platform);
+
+  logger.info('Environment detected', { client, hasDisplay, sessionRoot });
+
+  return { client, hasDisplay, sessionRoot };
+}
+
+module.exports = {
+  inferClient,
+  getSessionRoot,
+  detectEnvironment,
+  VALID_CLIENTS
+};