auxilo-mcp 0.7.0 → 0.8.2

package/scripts/sources/claude-code.js

@@ -0,0 +1,182 @@
+/**
+ * scripts/sources/claude-code.js — Claude Code Transcript Source (P2.1a §4.2)
+ *
+ * Discovers and reads conversation transcripts from the Claude Code JSONL format.
+ * Default location: ~/.claude/projects/{name}/conversations/{id}.jsonl
+ *
+ * @module sources/claude-code
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { TranscriptSource } = require('./source.interface');
+
+class ClaudeCodeSource extends TranscriptSource {
+  static id = 'claude-code';
+  static displayName = 'Claude Code (Anthropic)';
+  static version = '1.0.0';
+
+  constructor(config = {}) {
+    super(config);
+    /** @type {string} Root dir for Claude Code projects */
+    this.dataDir = config.dataDir || path.join(os.homedir(), '.claude', 'projects');
+    /** @type {string} Path to settings.json for hook registration */
+    this.settingsPath = config.settingsPath || path.join(os.homedir(), '.claude', 'settings.json');
+  }
+
+  /**
+   * Detect if Claude Code is installed: ~/.claude/projects exists AND
+   * ~/.claude/settings.json is readable.
+   */
+  async detect() {
+    try {
+      if (!fs.existsSync(this.dataDir)) return false;
+      fs.accessSync(this.settingsPath, fs.constants.R_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Discover sessions modified after `since`.
+   * Walks ~/.claude/projects/*\/conversations/*.jsonl
+   */
+  async discoverSessions({ since } = {}) {
+    const results = [];
+    if (!fs.existsSync(this.dataDir)) return results;
+
+    const sinceMs = since ? new Date(since).getTime() : 0;
+
+    let projects;
+    try {
+      projects = fs.readdirSync(this.dataDir).filter(p => {
+        const full = path.join(this.dataDir, p);
+        try { return fs.statSync(full).isDirectory(); } catch { return false; }
+      });
+    } catch {
+      return results;
+    }
+
+    // Real Claude Code layout: ~/.claude/projects/<project>/<session-id>.jsonl
+    // The jsonl files sit directly under the project directory. Historical
+    // versions put them under a `conversations/` subdir — we still check
+    // that as a fallback for safety, but the modern layout is the default.
+    for (const project of projects) {
+      const projectDir = path.join(this.dataDir, project);
+      const candidateDirs = [
+        projectDir,
+        path.join(projectDir, 'conversations'), // legacy fallback
+      ];
+
+      for (const dir of candidateDirs) {
+        if (!fs.existsSync(dir)) continue;
+
+        let files;
+        try { files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')); }
+        catch { continue; }
+
+        for (const file of files) {
+          const filePath = path.join(dir, file);
+          try {
+            const stat = fs.statSync(filePath);
+            // Skip directories masquerading via .jsonl suffix (shouldn't happen,
+            // but be defensive); the readdirSync already excludes non-files in
+            // practice, but stat check is cheap.
+            if (!stat.isFile()) continue;
+            if (stat.mtimeMs <= sinceMs) continue;
+            results.push({
+              sessionId: path.basename(file, '.jsonl'),
+              path: filePath,
+              mtime: stat.mtime.toISOString(),
+              bytes: stat.size,
+            });
+          } catch { /* skip unreadable files */ }
+        }
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Read a session transcript. JSONL → plain "ROLE: text" blocks.
+   */
+  async readSession(sessionRef) {
+    const filePath = sessionRef.path;
+    if (!filePath || !fs.existsSync(filePath)) {
+      throw new Error(`Transcript file not found: ${filePath}`);
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n').filter(l => l.trim());
+
+    // Real Claude Code JSONL shape:
+    //   { type: 'user'|'assistant'|'system'|'queue-operation'|'attachment'|...,
+    //     message: { role, content } }
+    // For user:      message.content is a string OR [{type:'text', text:'...'}]
+    // For assistant: message.content is [{type:'text'|'thinking'|'tool_use'|'tool_result', ...}]
+    // We want user + assistant text content only, concatenated in order.
+    const turns = [];
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        // Skip meta types — they don't contribute to the conversation
+        if (entry.type && !['user', 'assistant', 'system'].includes(entry.type)) continue;
+
+        const role = entry.message?.role || entry.role || entry.type || 'unknown';
+        const raw = entry.message?.content ?? entry.content;
+        if (raw == null) continue;
+
+        let text = '';
+        if (typeof raw === 'string') {
+          text = raw;
+        } else if (Array.isArray(raw)) {
+          // Concatenate text-like blocks. Skip tool_use/tool_result payloads
+          // and thinking blocks (internal reasoning, not conversation).
+          text = raw
+            .filter(b => b && (b.type === 'text' || b.type === 'input_text' || typeof b.text === 'string'))
+            .map(b => b.text || '')
+            .filter(Boolean)
+            .join('\n');
+        } else if (typeof raw === 'object' && typeof raw.text === 'string') {
+          text = raw.text;
+        }
+
+        if (text.trim().length > 0) {
+          turns.push(`[${role}]: ${text}`);
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    return {
+      transcript: turns.join('\n\n'),
+      metadata: {
+        sessionId: sessionRef.sessionId,
+        source: 'claude-code',
+        mtime: sessionRef.mtime,
+        bytes: sessionRef.bytes,
+      },
+    };
+  }
+
+  /**
+   * Register SessionEnd hook via ~/.claude/settings.json.
+   * Returns an unregister function.
+   */
+  async registerSessionEndHook(cb) {
+    // Hook registration is handled by installHooks() in runner.js.
+    // This method returns null to indicate that the runner should
+    // use the installHooks() path for setup, and poll for discovery.
+    // Live hook support via settings.json SessionEnd array is wired
+    // through the bash hook script, not through this JS method.
+    return null;
+  }
+}
+
+module.exports = { ClaudeCodeSource };

package/scripts/sources/openclaw.js

@@ -0,0 +1,171 @@
+/**
+ * scripts/sources/openclaw.js — OpenClaw Transcript Source (P2.1a §4.3)
+ *
+ * Discovers and reads session transcripts from the OpenClaw runtime directory.
+ * A5.4 FIX: Correct path is ~/.openclaw/agents/{agentId}/sessions/{sessionId}.jsonl
+ * (NOT data/openclaw/ inside the repo)
+ *
+ * Storage layout (from BUILD-1 research, spec §4.3):
+ *   ~/.openclaw/agents/{agentId}/sessions/{sessionId}.jsonl
+ *   with sessions.json index in that same directory.
+ *   First line of each JSONL = session metadata; subsequent lines = messages.
+ *
+ * @module sources/openclaw
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { TranscriptSource } = require('./source.interface');
+
+class OpenClawSource extends TranscriptSource {
+  static id = 'openclaw';
+  static displayName = 'OpenClaw Memory System';
+  static version = '1.0.0';
+
+  constructor(config = {}) {
+    super(config);
+    // A5.4: Correct path — ~/.openclaw/agents (NOT data/openclaw/ inside repo)
+    this.dataDir = config.dataDir || path.join(os.homedir(), '.openclaw', 'agents');
+  }
+
+  /**
+   * Detect if OpenClaw is installed: ~/.openclaw/agents exists AND
+   * contains at least one agent directory.
+   */
+  async detect() {
+    try {
+      if (!fs.existsSync(this.dataDir)) return false;
+      const agents = fs.readdirSync(this.dataDir).filter(d => {
+        try { return fs.statSync(path.join(this.dataDir, d)).isDirectory(); }
+        catch { return false; }
+      });
+      return agents.length > 0;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Discover sessions modified after `since`.
+   * Reads sessions.json index in each agent's sessions dir, filters by updatedAt.
+   */
+  async discoverSessions({ since } = {}) {
+    const results = [];
+    if (!fs.existsSync(this.dataDir)) return results;
+
+    const sinceMs = since ? new Date(since).getTime() : 0;
+
+    let agents;
+    try {
+      agents = fs.readdirSync(this.dataDir).filter(d => {
+        try { return fs.statSync(path.join(this.dataDir, d)).isDirectory(); }
+        catch { return false; }
+      });
+    } catch {
+      return results;
+    }
+
+    for (const agentId of agents) {
+      const sessionsDir = path.join(this.dataDir, agentId, 'sessions');
+      if (!fs.existsSync(sessionsDir)) continue;
+
+      // Try sessions.json index first
+      const indexPath = path.join(sessionsDir, 'sessions.json');
+      if (fs.existsSync(indexPath)) {
+        try {
+          const index = JSON.parse(fs.readFileSync(indexPath, 'utf-8'));
+          const sessions = Array.isArray(index) ? index : (index.sessions || []);
+          for (const entry of sessions) {
+            const updatedAt = entry.updatedAt || entry.updated_at || entry.mtime;
+            if (updatedAt && new Date(updatedAt).getTime() <= sinceMs) continue;
+            const sessionFile = path.join(sessionsDir, `${entry.sessionId || entry.id}.jsonl`);
+            if (!fs.existsSync(sessionFile)) continue;
+            const stat = fs.statSync(sessionFile);
+            results.push({
+              sessionId: entry.sessionId || entry.id,
+              path: sessionFile,
+              mtime: stat.mtime.toISOString(),
+              bytes: stat.size,
+            });
+          }
+          continue; // Used index, skip file scan for this agent
+        } catch {
+          // Fall through to direct file scan
+        }
+      }
+
+      // Fallback: direct .jsonl scan
+      try {
+        const files = fs.readdirSync(sessionsDir).filter(f => f.endsWith('.jsonl'));
+        for (const file of files) {
+          const filePath = path.join(sessionsDir, file);
+          try {
+            const stat = fs.statSync(filePath);
+            if (stat.mtimeMs <= sinceMs) continue;
+            results.push({
+              sessionId: path.basename(file, '.jsonl'),
+              path: filePath,
+              mtime: stat.mtime.toISOString(),
+              bytes: stat.size,
+            });
+          } catch { /* skip unreadable */ }
+        }
+      } catch { /* skip unreadable dir */ }
+    }
+
+    return results;
+  }
+
+  /**
+   * Read a session transcript. Skip first (metadata) line per spec §4.3.
+   * Convert messages into "ROLE: text" format.
+   */
+  async readSession(sessionRef) {
+    const filePath = sessionRef.path;
+    if (!filePath || !fs.existsSync(filePath)) {
+      throw new Error(`Session file not found: ${filePath}`);
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n').filter(l => l.trim());
+
+    // First line is session metadata per spec §4.3 — skip it
+    const turns = [];
+    for (let i = 1; i < lines.length; i++) {
+      try {
+        const msg = JSON.parse(lines[i]);
+        const role = msg.role || msg.type || 'unknown';
+        const text = typeof msg.content === 'string'
+          ? msg.content
+          : (msg.content && msg.content[0]?.text) || JSON.stringify(msg.content || '');
+        turns.push(`[${role}]: ${text}`);
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    return {
+      transcript: turns.join('\n\n'),
+      metadata: {
+        sessionId: sessionRef.sessionId,
+        source: 'openclaw',
+        mtime: sessionRef.mtime,
+        bytes: sessionRef.bytes,
+      },
+    };
+  }
+
+  /**
+   * Register session-end hook.
+   * Returns null — OpenClaw is poll-only at launch per spec §4.3.
+   * Live hooks deferred pending SPEC-2 confirmation of plugin manifest.
+   */
+  async registerSessionEndHook(cb) {
+    return null;
+  }
+}
+
+module.exports = { OpenClawSource };

package/scripts/sources/source.interface.js

@@ -0,0 +1,85 @@
+/**
+ * scripts/sources/source.interface.js — Transcript Source Interface (P2.1a §4.1)
+ *
+ * Base class for all transcript source adapters.
+ * Spec contract from BUILD-SPEC-P2.1a §4.1:
+ *   - detect()                      → boolean (installed on host?)
+ *   - discoverSessions({ since })   → [{ sessionId, path, mtime, bytes }]
+ *   - readSession(sessionRef)       → { transcript: string, metadata: {...} }
+ *   - registerSessionEndHook(cb)    → unregister fn | null (null = poll-only)
+ *
+ * @module sources/source.interface
+ */
+
+'use strict';
+
+/**
+ * Abstract base class for transcript source adapters.
+ *
+ * Subclasses MUST set the static fields and implement all four methods.
+ *
+ * @abstract
+ */
+class TranscriptSource {
+  /** @type {string} Source type identifier, e.g. "claude-code" */
+  static id = 'abstract';
+
+  /** @type {string} Human-readable display name */
+  static displayName = 'Abstract Source';
+
+  /** @type {string} Semantic version of this adapter */
+  static version = '0.0.0';
+
+  constructor(config = {}) {
+    /** @type {string} Instance-level reference to the source type */
+    this.type = this.constructor.id || config.type || 'abstract';
+    /** @type {string} Instance-level display name */
+    this.label = this.constructor.displayName || config.label || '';
+  }
+
+  /**
+   * Detect whether this source is installed on the host.
+   *
+   * @returns {Promise<boolean>} true if the source data directory exists and is readable
+   */
+  async detect() {
+    throw new Error('TranscriptSource.detect() must be implemented by subclass');
+  }
+
+  /**
+   * Discover new sessions since a high-water mark.
+   *
+   * @param {object} opts
+   * @param {string} [opts.since] - ISO timestamp; only return sessions modified after this time
+   * @returns {Promise<Array<{sessionId: string, path: string, mtime: string, bytes: number}>>}
+   */
+  async discoverSessions({ since } = {}) {
+    throw new Error('TranscriptSource.discoverSessions() must be implemented by subclass');
+  }
+
+  /**
+   * Read a session's transcript.
+   *
+   * @param {object} sessionRef - A session reference object from discoverSessions()
+   * @returns {Promise<{transcript: string, metadata: {sessionId: string, source: string, mtime: string, bytes: number}}>}
+   */
+  async readSession(sessionRef) {
+    throw new Error('TranscriptSource.readSession() must be implemented by subclass');
+  }
+
+  /**
+   * Register a callback for session-end events (live hook mode).
+   *
+   * Returns null if the source only supports poll-based discovery (no live hooks).
+   * Returns an unregister function if hooks are supported.
+   *
+   * @param {Function} cb - Callback invoked with session path on session end
+   * @returns {Promise<Function|null>} Unregister function, or null for poll-only sources
+   */
+  async registerSessionEndHook(cb) {
+    // Default: poll-only source — no live hooks available
+    return null;
+  }
+}
+
+module.exports = { TranscriptSource };