agentacta 2026.3.6 → 2026.3.12

package/README.md

@@ -118,18 +118,20 @@ On first run, AgentActa creates:
 - `~/.config/agentacta/config.json`
 - or `agentacta.config.json` in current directory (if present)
 
-Default config:
+Default config (auto-generated on first run — session directories are detected automatically):
 
 ```json
 {
   "port": 4003,
   "storage": "reference",
-  "sessionsPath": null,
+  "sessionsPath": ["~/.claude/projects", "~/.openclaw/sessions"],
   "dbPath": "./agentacta.db",
   "projectAliases": {}
 }
 ```
 
+`sessionsPath` accepts a string, a colon-delimited string, or a JSON array.
+
 ### Storage modes
 
 - `reference` (default): index parsed events in SQLite, keep source JSONL on disk. Lightweight.
@@ -163,6 +165,76 @@ Default config:
 | `GET /api/health` | Server status, version, uptime, session count |
 | `GET /api/export/search?q=<query>&format=md` | Export search results |
 
+### Context API
+
+The Context API gives agents historical context before they start working. Instead of exploring a codebase from scratch, an agent can query what's happened before.
+
+| Endpoint | Description |
+|---|---|
+| `GET /api/context/file?path=<filepath>` | History for a specific file |
+| `GET /api/context/repo?path=<repo-path>` | Aggregates for a repo/project |
+| `GET /api/context/agent?name=<agent-name>` | Stats for a specific agent |
+
+**File context** — how many sessions touched this file, when it was last modified, recent change summaries, operation breakdown (reads vs edits), related files, and recent errors:
+
+```bash
+curl http://localhost:4003/api/context/file?path=/home/user/project/server.js
+```
+```json
+{
+  "file": "/home/user/project/server.js",
+  "sessionCount": 34,
+  "lastModified": "3h ago",
+  "recentChanges": ["Added OAuth state validation", "Fixed password masking"],
+  "operations": { "edit": 105, "read": 56 },
+  "relatedFiles": [{ "path": "public/app.js", "count": 28 }],
+  "recentErrors": []
+}
+```
+
+**Agent context** — total sessions, cost, average duration, most-used tools, recent work:
+
+```bash
+curl http://localhost:4003/api/context/agent?name=claude-code
+```
+```json
+{
+  "agent": "claude-code",
+  "sessionCount": 60,
+  "totalCost": 18.83,
+  "avgDuration": 288,
+  "topTools": [{ "tool": "edit", "count": 190 }, { "tool": "exec", "count": 560 }],
+  "recentSessions": [{ "id": "...", "summary": "Added context API...", "timestamp": "..." }],
+  "successRate": 100
+}
+```
+
+**Repo context** — aggregate cost, tokens, distinct agents, most-touched files, common tools:
+
+```bash
+curl http://localhost:4003/api/context/repo?path=agentacta
+```
+
+#### Using the Context API with agents
+
+Inject context into agent prompts so new sessions start informed:
+
+```bash
+# Fetch context before starting Claude Code
+CONTEXT=$(curl -s http://localhost:4003/api/context/file?path=$(pwd)/server.js)
+claude --print "Context from previous sessions: $CONTEXT
+
+Your task: refactor the auth module"
+```
+
+Or add it to a CLAUDE.md / AGENTS.md:
+
+```markdown
+## Project Context API
+Before modifying key files, query AgentActa for history:
+curl http://localhost:4003/api/context/file?path={filepath}
+```
+
 Agent integration example:
 
 ```javascript

package/config.js

@@ -14,6 +14,12 @@ function resolveConfigFile() {
 
 const CONFIG_FILE = resolveConfigFile();
 
+const KNOWN_SESSION_DIRS = [
+  path.join(os.homedir(), '.claude', 'projects'),    // Claude Code
+  path.join(os.homedir(), '.codex', 'sessions'),     // Codex CLI
+  path.join(os.homedir(), '.openclaw', 'sessions'),  // OpenClaw
+];
+
 const DEFAULTS = {
   port: 4003,
   storage: 'reference',
@@ -22,6 +28,11 @@ const DEFAULTS = {
   projectAliases: {}
 };
 
+function detectSessionDirs() {
+  const found = KNOWN_SESSION_DIRS.filter(d => fs.existsSync(d));
+  return found.length > 0 ? found : null;
+}
+
 function loadConfig() {
   let fileConfig = {};
 
@@ -32,11 +43,18 @@ function loadConfig() {
       console.error(`Warning: Could not parse ${CONFIG_FILE}:`, err.message);
     }
   } else {
-    // First-run: create default config in XDG location
+    // First-run: create default config with auto-detected session dirs
+    const detected = detectSessionDirs();
+    const firstRunDefaults = { ...DEFAULTS, sessionsPath: detected };
     const dir = path.dirname(CONFIG_FILE);
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-    fs.writeFileSync(CONFIG_FILE, JSON.stringify(DEFAULTS, null, 2) + '\n');
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(firstRunDefaults, null, 2) + '\n');
+    // Apply to in-memory config so this run also benefits
+    fileConfig = firstRunDefaults;
     console.log(`Created default config: ${CONFIG_FILE}`);
+    if (detected) {
+      console.log(`Auto-detected session directories:\n${detected.map(d => `  - ${d}`).join('\n')}`);
+    }
   }
 
   const config = { ...DEFAULTS, ...fileConfig };

package/index.js

@@ -105,6 +105,15 @@ function getDbSize() {
   }
 }
 
+function relativeTime(ts) {
+  if (!ts) return null;
+  const diff = Math.floor((Date.now() - new Date(ts).getTime()) / 1000);
+  if (diff < 60) return 'just now';
+  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`;
+  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`;
+  return `${Math.floor(diff / 86400)}d ago`;
+}
+
 function normalizeAgentLabel(agent) {
   if (!agent) return agent;
   if (agent === 'main') return 'openclaw-main';
@@ -514,6 +523,182 @@ const server = http.createServer((req, res) => {
       const sizeAfter = getDbSize();
       json(res, { ok: true, sizeBefore, sizeAfter });
     }
+    // --- Context API ---
+    else if (pathname === '/api/context/file') {
+      const fp = query.path || '';
+      if (!fp) return json(res, { error: 'path parameter is required' }, 400);
+
+      const sessionCount = db.prepare(
+        'SELECT COUNT(DISTINCT session_id) as c FROM file_activity WHERE file_path = ?'
+      ).get(fp).c;
+
+      if (sessionCount === 0) {
+        return json(res, { file: fp, sessionCount: 0, lastModified: null, recentChanges: [], operations: {}, relatedFiles: [], recentErrors: [] });
+      }
+
+      const lastTouched = db.prepare(
+        'SELECT MAX(timestamp) as t FROM file_activity WHERE file_path = ?'
+      ).get(fp).t;
+
+      const recentChanges = db.prepare(
+        `SELECT DISTINCT s.summary FROM file_activity fa
+         JOIN sessions s ON s.id = fa.session_id
+         WHERE fa.file_path = ? AND s.summary IS NOT NULL
+         ORDER BY s.start_time DESC LIMIT 5`
+      ).all(fp).map(r => r.summary);
+
+      const opsRows = db.prepare(
+        'SELECT operation, COUNT(*) as c FROM file_activity WHERE file_path = ? GROUP BY operation'
+      ).all(fp);
+      const operations = {};
+      for (const r of opsRows) operations[r.operation] = r.c;
+
+      const relatedFiles = db.prepare(
+        `SELECT fa2.file_path, COUNT(DISTINCT fa1.session_id) as c
+         FROM file_activity fa1
+         JOIN file_activity fa2 ON fa1.session_id = fa2.session_id
+         WHERE fa1.file_path = ? AND fa2.file_path != ?
+         GROUP BY fa2.file_path
+         ORDER BY c DESC LIMIT 5`
+      ).all(fp, fp).map(r => ({ path: r.file_path, count: r.c }));
+
+      const sessionIds = db.prepare(
+        'SELECT DISTINCT session_id FROM file_activity WHERE file_path = ?'
+      ).all(fp).map(r => r.session_id);
+
+      let recentErrors = [];
+      if (sessionIds.length) {
+        const placeholders = sessionIds.map(() => '?').join(',');
+        recentErrors = db.prepare(
+          `SELECT tool_result FROM events
+           WHERE session_id IN (${placeholders})
+             AND tool_result IS NOT NULL
+             AND (tool_result LIKE '%error%' OR tool_result LIKE '%Error%' OR tool_result LIKE '%ERROR%')
+           ORDER BY timestamp DESC LIMIT 3`
+        ).all(...sessionIds).map(r => r.tool_result.slice(0, 200));
+      }
+
+      return json(res, {
+        file: fp, sessionCount,
+        lastModified: relativeTime(lastTouched),
+        recentChanges, operations, relatedFiles, recentErrors
+      });
+    }
+    else if (pathname === '/api/context/repo') {
+      const repoPath = query.path || '';
+      if (!repoPath) return json(res, { error: 'path parameter is required' }, 400);
+
+      // Find sessions matching the repo path via file_activity or initial_prompt
+      const sessionIds = db.prepare(
+        `SELECT DISTINCT session_id FROM file_activity WHERE file_path = ? OR file_path LIKE ?`
+      ).all(repoPath, repoPath + '/%').map(r => r.session_id);
+
+      const promptSessions = db.prepare(
+        `SELECT id FROM sessions WHERE initial_prompt LIKE ?`
+      ).all('%' + repoPath + '%').map(r => r.id);
+
+      const allIds = [...new Set([...sessionIds, ...promptSessions])];
+
+      if (allIds.length === 0) {
+        return json(res, { repo: repoPath, sessionCount: 0, totalCost: 0, totalTokens: 0, agents: [], topFiles: [], recentSessions: [], commonTools: [], commonErrors: [] });
+      }
+
+      const ph = allIds.map(() => '?').join(',');
+
+      const agg = db.prepare(
+        `SELECT COUNT(*) as c, SUM(total_cost) as cost, SUM(total_tokens) as tokens
+         FROM sessions WHERE id IN (${ph})`
+      ).get(...allIds);
+
+      const agents = [...new Set(
+        db.prepare(`SELECT DISTINCT agent FROM sessions WHERE id IN (${ph}) AND agent IS NOT NULL`).all(...allIds)
+          .map(r => normalizeAgentLabel(r.agent)).filter(Boolean)
+      )];
+
+      const topFiles = db.prepare(
+        `SELECT file_path, COUNT(*) as c FROM file_activity
+         WHERE session_id IN (${ph})
+         GROUP BY file_path ORDER BY c DESC LIMIT 10`
+      ).all(...allIds).map(r => ({ path: r.file_path, count: r.c }));
+
+      const recentSessions = db.prepare(
+        `SELECT id, summary, agent, start_time, end_time FROM sessions
+         WHERE id IN (${ph})
+         ORDER BY start_time DESC LIMIT 5`
+      ).all(...allIds).map(r => ({
+        id: r.id, summary: r.summary, agent: normalizeAgentLabel(r.agent),
+        timestamp: r.start_time, status: r.end_time ? 'completed' : 'in-progress'
+      }));
+
+      const commonTools = db.prepare(
+        `SELECT tool_name, COUNT(*) as c FROM events
+         WHERE session_id IN (${ph}) AND tool_name IS NOT NULL
+         GROUP BY tool_name ORDER BY c DESC LIMIT 10`
+      ).all(...allIds).map(r => ({ tool: r.tool_name, count: r.c }));
+
+      const commonErrors = db.prepare(
+        `SELECT DISTINCT SUBSTR(tool_result, 1, 200) as err FROM events
+         WHERE session_id IN (${ph})
+           AND tool_result IS NOT NULL
+           AND (tool_result LIKE '%error%' OR tool_result LIKE '%Error%' OR tool_result LIKE '%ERROR%')
+         ORDER BY timestamp DESC LIMIT 5`
+      ).all(...allIds).map(r => r.err);
+
+      return json(res, {
+        repo: repoPath, sessionCount: allIds.length,
+        totalCost: agg.cost || 0, totalTokens: agg.tokens || 0,
+        agents, topFiles, recentSessions, commonTools, commonErrors
+      });
+    }
+    else if (pathname === '/api/context/agent') {
+      const name = query.name || '';
+      if (!name) return json(res, { error: 'name parameter is required' }, 400);
+
+      // Try exact match first, then check all sessions with normalized label match
+      let sessions = db.prepare(
+        'SELECT * FROM sessions WHERE agent = ?'
+      ).all(name);
+      if (sessions.length === 0) {
+        sessions = db.prepare('SELECT * FROM sessions WHERE agent IS NOT NULL').all()
+          .filter(s => normalizeAgentLabel(s.agent) === name);
+      }
+
+      if (sessions.length === 0) {
+        return json(res, { agent: name, sessionCount: 0, totalCost: 0, avgDuration: 0, topTools: [], recentSessions: [], successRate: 0 });
+      }
+
+      const totalCost = sessions.reduce((s, r) => s + (r.total_cost || 0), 0);
+      let totalDuration = 0;
+      let durationCount = 0;
+      for (const s of sessions) {
+        if (s.start_time && s.end_time) {
+          totalDuration += (new Date(s.end_time) - new Date(s.start_time)) / 1000;
+          durationCount++;
+        }
+      }
+      const avgDuration = durationCount > 0 ? Math.round(totalDuration / durationCount) : 0;
+
+      const withSummary = sessions.filter(s => s.summary).length;
+      const successRate = Math.round((withSummary / sessions.length) * 100);
+
+      const ids = sessions.map(s => s.id);
+      const ph = ids.map(() => '?').join(',');
+      const topTools = db.prepare(
+        `SELECT tool_name, COUNT(*) as c FROM events
+         WHERE session_id IN (${ph}) AND tool_name IS NOT NULL
+         GROUP BY tool_name ORDER BY c DESC LIMIT 10`
+      ).all(...ids).map(r => ({ tool: r.tool_name, count: r.c }));
+
+      const recentSessions = sessions
+        .sort((a, b) => (b.start_time || '').localeCompare(a.start_time || ''))
+        .slice(0, 5)
+        .map(s => ({ id: s.id, summary: s.summary, timestamp: s.start_time }));
+
+      return json(res, {
+        agent: name, sessionCount: sessions.length,
+        totalCost, avgDuration, topTools, recentSessions, successRate
+      });
+    }
     else if (pathname === '/api/files') {
       const limit = parseInt(query.limit) || 100;
       const offset = parseInt(query.offset) || 0;

package/indexer.js

@@ -29,16 +29,36 @@ function discoverSessionDirs(config) {
   const dirs = [];
   const home = process.env.HOME;
 
+  // Expand a single path into session dirs, handling Claude Code's per-project structure
+  function expandPath(p) {
+    if (!fs.existsSync(p)) return;
+    const stat = fs.statSync(p);
+    if (!stat.isDirectory()) return;
+    // Claude Code: ~/.claude/projects contains per-project subdirs with JSONL files
+    if (p.replace(/\/$/, '').endsWith('/.claude/projects')) {
+      for (const proj of fs.readdirSync(p)) {
+        const projDir = path.join(p, proj);
+        if (fs.statSync(projDir).isDirectory()) {
+          const hasJsonl = fs.readdirSync(projDir).some(f => f.endsWith('.jsonl'));
+          if (hasJsonl) dirs.push({ path: projDir, agent: 'claude-code' });
+        }
+      }
+    } else {
+      dirs.push({ path: p, agent: path.basename(path.dirname(p)) });
+    }
+  }
+
   // Config sessionsPath or env var override
   const sessionsOverride = process.env.AGENTACTA_SESSIONS_PATH || (config && config.sessionsPath);
   if (sessionsOverride) {
-    for (const p of sessionsOverride.split(':')) {
-      if (fs.existsSync(p)) dirs.push({ path: p, agent: path.basename(path.dirname(p)) });
-    }
+    const overridePaths = Array.isArray(sessionsOverride)
+      ? sessionsOverride
+      : sessionsOverride.split(':');
+    overridePaths.forEach(expandPath);
     if (dirs.length) return dirs;
   }
 
-  // Scan ~/.openclaw/agents/*/sessions/
+  // Auto-discover: ~/.openclaw/agents/*/sessions/
   const oclawAgents = path.join(home, '.openclaw/agents');
   if (fs.existsSync(oclawAgents)) {
     for (const agent of fs.readdirSync(oclawAgents)) {
@@ -49,23 +69,8 @@ function discoverSessionDirs(config) {
     }
   }
 
-  // Scan ~/.claude/projects/*/ (Claude Code stores JSONL directly in project dirs)
-  const claudeProjects = path.join(home, '.claude/projects');
-  if (fs.existsSync(claudeProjects)) {
-    for (const proj of fs.readdirSync(claudeProjects)) {
-      const projDir = path.join(claudeProjects, proj);
-      // Claude Code: JSONL files directly in project dir
-      if (fs.existsSync(projDir) && fs.statSync(projDir).isDirectory()) {
-        const hasJsonl = fs.readdirSync(projDir).some(f => f.endsWith('.jsonl'));
-        if (hasJsonl) dirs.push({ path: projDir, agent: 'claude-code' });
-      }
-      // Also check sessions/ subdirectory (future-proofing)
-      const sp = path.join(projDir, 'sessions');
-      if (fs.existsSync(sp) && fs.statSync(sp).isDirectory()) {
-        dirs.push({ path: sp, agent: 'claude-code' });
-      }
-    }
-  }
+  // Auto-discover: ~/.claude/projects/
+  expandPath(path.join(home, '.claude/projects'));
 
   // Scan ~/.codex/sessions recursively (Codex CLI stores nested YYYY/MM/DD/*.jsonl)
   const codexSessions = path.join(home, '.codex/sessions');
@@ -289,11 +294,16 @@ function indexFile(db, filePath, agentName, stmts, archiveMode, config) {
     if (firstLine.agent) agent = firstLine.agent;
     if (firstLine.sessionType) sessionType = firstLine.sessionType;
     if (sessionId.includes('subagent')) sessionType = 'subagent';
-  } else if (firstLine.type === 'user' || firstLine.type === 'assistant' || firstLine.type === 'file-history-snapshot') {
-    // Claude Code format — no session header, extract from first message line
+  } else if (firstLine.type === 'user' || firstLine.type === 'assistant' || firstLine.type === 'file-history-snapshot' || firstLine.type === 'queue-operation') {
+    // Claude Code format — no session header, extract from first message or queue-operation line
     isClaudeCode = true;
     for (const line of lines) {
       let obj; try { obj = JSON.parse(line); } catch { continue; }
+      if (obj.sessionId && obj.timestamp) {
+        sessionId = obj.sessionId;
+        sessionStart = obj.timestamp;
+        break;
+      }
       if ((obj.type === 'user' || obj.type === 'assistant') && obj.sessionId) {
         sessionId = obj.sessionId;
         sessionStart = obj.timestamp;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentacta",
-  "version": "2026.3.6",
+  "version": "2026.3.12",
   "description": "Audit trail and search engine for AI agent sessions",
   "main": "index.js",
   "bin": {