agentacta 1.3.4 → 1.5.0

package/README.md

@@ -4,9 +4,11 @@
 [![npm](https://img.shields.io/npm/v/agentacta)](https://www.npmjs.com/package/agentacta)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-**Your AI agent does hundreds of things. Can you find them?**
+**Your agent did 1000s of things today. Can you find the 1 that broke prod?**
 
-AgentActa is an audit trail and search engine for AI agent sessions. It indexes everything your agent did — every message, tool call, file edit, web search, and decision — into a fast, searchable local interface.
+AgentActa is a local audit trail and search engine for AI agent sessions.
+
+It indexes messages, tool calls, file edits, searches, and decisions into a fast UI you can query in seconds.
 
 One command. Zero config. Full visibility.
 
@@ -18,95 +20,105 @@ npx agentacta
   <img src="screenshots/demo.gif" alt="AgentActa demo" width="800">
 </p>
 
----
-
-## Why
-
-AI agents are powerful. They write code, send emails, manage infrastructure, make decisions on your behalf. But when you need to know *what happened* — what was changed, when, and why — you're digging through scattered logs or asking the agent to remember (it won't).
+## Why this exists
 
-AgentActa gives you a single, searchable view of everything.
+Agents move fast. Your memory of what happened doesn’t.
 
-## What You Get
+When you need to answer “what changed, when, and why,” you’re usually scraping logs, scrolling transcripts, or asking the same assistant that forgot 20 minutes ago.
 
-🔍 **Full-text search** across all messages, tool calls, and results
-📋 **Session browser** with summaries, token breakdowns (input/output), and model info
-📅 **Timeline view** — everything that happened on any given day
-📁 **File activity** — every file your agent touched, across all sessions
-📊 **Stats** — sessions, messages, tool usage, token counts
-⚡ **Live indexing** — new sessions appear automatically via file watching
-📱 **Mobile-friendly** — responsive UI with bottom tab navigation
-💡 **Smart suggestions** — quick search chips derived from your actual session data
+AgentActa gives you one place to inspect the full trail.
 
-## Demo
+## What you get
 
-https://github.com/mirajchokshi/agentacta/raw/main/screenshots/demo-final.mp4
+- 🔍 Full-text search across messages, tool calls, and results
+- 📋 Session browser with summaries, token breakdowns, and model info
+- 📅 Timeline view with live updates for today
+- 📁 File activity across all indexed sessions
+- 🌗 Light and dark themes
+- 📊 Stats for sessions, messages, tools, and tokens
+- ⚡ Live indexing via file watching
+- 📱 Mobile-friendly UI
+- 💡 Search suggestions based on real data
+- ⌨️ Command palette (⌘K / Ctrl+K) for quick navigation
+- 🎨 Theme settings (system, light, dark, OLED)
+- 🏥 Health endpoint for monitoring (`/api/health`)
 
-## Screenshots
 
-![Search](screenshots/search.png)
-![Sessions](screenshots/sessions.png)
-![Session Detail](screenshots/session-detail.png)
-![Timeline](screenshots/timeline.png)
-![Files](screenshots/files.png)
-![Stats](screenshots/stats.png)
-![Search Results](screenshots/search-results.png)
-
-## Quick Start
+## Quick start
 
 ```bash
-# Run directly (no install needed)
+# run directly
 npx agentacta
 
-# Or install globally
+# or install globally
 npm install -g agentacta
 agentacta
 ```
 
-Open `http://localhost:4003` in your browser.
+Open: `http://localhost:4003`
 
-AgentActa automatically finds your sessions in:
+Auto-detected session paths:
 - `~/.openclaw/agents/*/sessions/` (OpenClaw)
 - `~/.claude/projects/*/` (Claude Code)
 - `~/.codex/sessions/` (Codex CLI)
 
-Or point it at a custom path:
+Custom path:
 
 ```bash
 AGENTACTA_SESSIONS_PATH=/path/to/sessions agentacta
 ```
 
-## Features
+## Core features
 
 ### Search
-Full-text search powered by SQLite FTS5. Filter by message type (messages, tool calls, results) and role (user, assistant). Quick search suggestions are generated from your actual data — most-used tools, common topics, frequently touched files.
+
+SQLite FTS5 full-text search with filters for message type (messages, tool calls, results) and role (user, assistant).
+
+Suggestions come from your own dataset: top tools, common topics, frequently touched files.
 
 ### Sessions
-Browse all indexed sessions with auto-generated summaries, token breakdowns (output vs input), and model info. Sessions are automatically tagged by type — cron jobs, sub-agent tasks, and heartbeat sessions get distinct badges. Click into any session to see the full event history, most recent first.
+
+Browse indexed sessions with auto-generated summaries, token splits (input/output), and model details. Click into any session to see the full event history.
+
+Session types get tagged so noisy categories are easier to spot (cron, sub-agent, heartbeat).
 
 ### Timeline
-Pick a date, see everything that happened. Messages, tool invocations, file changes — most recent first.
+
+Pick a date, see everything that happened, newest first. Today's view updates live as new events come in.
 
 ### File Activity
-See every file your agent read, wrote, or edited. Sort by most touched, most recent, or most sessions. Filter by extension, group by directory. Click any file to see which sessions touched it and what was done.
+
+See what files were touched, how often, and by which sessions.
+
+Sort by recency, frequency, or session count. Filter by extension. Group by directory. Click any file to see which sessions touched it.
 
 ### Export
-Download any session or search results as Markdown or JSON. Great for sharing, auditing, or archiving.
 
-## How It Works
+Export sessions or search results as Markdown or JSON.
 
-AgentActa reads JSONL session files (including OpenClaw, Claude Code, and Codex CLI formats), parses every message and tool call, and indexes them into a local SQLite database with FTS5 full-text search.
+Useful for handoffs, incident writeups, and audit archives.
 
-The web UI is a single-page app served by a lightweight Node.js HTTP server. No frameworks, no build step, no external dependencies beyond `better-sqlite3`.
+## How it works
 
-```
-Session JSONL files → SQLite + FTS5 index → HTTP API → Web UI
+AgentActa parses JSONL session files (OpenClaw, Claude Code, Codex CLI), then indexes events into local SQLite with FTS5.
+
+The UI is a single-page app served by a lightweight Node HTTP server.
+
+No framework build pipeline. Minimal moving parts.
+
+```text
+Session JSONL files -> SQLite + FTS5 index -> HTTP API -> Web UI
 ```
 
-Data never leaves your machine.
+Everything stays on your machine.
 
 ## Configuration
 
-On first run, AgentActa creates a config file with sensible defaults at `~/.config/agentacta/config.json` (or `agentacta.config.json` in the current directory if it exists):
+On first run, AgentActa creates:
+- `~/.config/agentacta/config.json`
+- or `agentacta.config.json` in current directory (if present)
+
+Default config:
 
 ```json
 {
@@ -118,85 +130,70 @@ On first run, AgentActa creates a config file with sensible defaults at `~/.conf
 }
 ```
 
-### Storage Modes
+### Storage modes
 
-- **`reference`** (default) — Lightweight index. Stores parsed events in SQLite but not the raw JSONL. Source files must remain on disk.
-- **`archive`** — Full JSONL stored in SQLite. Sessions survive even if the original files are deleted. Uses more disk space.
+- `reference` (default): index parsed events in SQLite, keep source JSONL on disk. Lightweight.
+- `archive`: store full JSONL in SQLite. Sessions survive even if original files are deleted. Uses more disk.
 
-### Environment Variables
+### Environment variables
 
 | Variable | Default | Description |
 |---|---|---|
 | `PORT` | `4003` | Server port |
-| `AGENTACTA_HOST` | `127.0.0.1` | Bind address (see [Security](#security)) |
-| `AGENTACTA_SESSIONS_PATH` | Auto-detected | Custom sessions directory |
-| `AGENTACTA_DB_PATH` | `./agentacta.db` | Database file location |
-| `AGENTACTA_STORAGE` | `reference` | Storage mode (`reference` or `archive`) |
-| `AGENTACTA_PROJECT_ALIASES_JSON` | unset | JSON object mapping inferred project names (e.g. `{"old-name":"new-name"}`) |
+| `AGENTACTA_HOST` | `127.0.0.1` | Bind address |
+| `AGENTACTA_SESSIONS_PATH` | auto-detected | Custom sessions directory |
+| `AGENTACTA_DB_PATH` | `./agentacta.db` | Database path |
+| `AGENTACTA_STORAGE` | `reference` | `reference` or `archive` |
+| `AGENTACTA_PROJECT_ALIASES_JSON` | unset | Rename inferred project labels |
 
 ## API
 
-AgentActa exposes a JSON API for programmatic access — useful for integrating search into your agent's workflow.
-
 | Endpoint | Description |
 |---|---|
-| `GET /api/stats` | Overview: session count, messages, tools, tokens |
-| `GET /api/sessions` | List sessions with metadata and token breakdowns |
-| `GET /api/sessions/:id` | Full session with all events |
-| `GET /api/search?q=<query>` | Full-text search with type/role/date filters |
-| `GET /api/suggestions` | Data-driven search suggestions |
-| `GET /api/timeline?date=YYYY-MM-DD` | All events for a given day |
-| `GET /api/files` | All files touched across sessions |
-| `GET /api/export/session/:id?format=md` | Export session as Markdown or JSON |
+| `GET /api/stats` | Session/message/tool/token totals |
+| `GET /api/sessions` | Session list with metadata |
+| `GET /api/sessions/:id` | Full session events |
+| `GET /api/search?q=<query>` | Full-text search + filters |
+| `GET /api/suggestions` | Search suggestions |
+| `GET /api/timeline?date=YYYY-MM-DD` | Events for one day |
+| `GET /api/files` | Touched-file inventory |
+| `GET /api/export/session/:id?format=md` | Export one session |
+| `GET /api/timeline/stream?after=<ts>` | SSE stream for live timeline updates |
+| `POST /api/maintenance` | VACUUM + WAL checkpoint (returns size before/after) |
+| `GET /api/health` | Server status, version, uptime, session count |
 | `GET /api/export/search?q=<query>&format=md` | Export search results |
 
-### Agent Integration
-
-Your AI agent can query AgentActa for better recall:
+Agent integration example:
 
 ```javascript
-const results = await fetch('http://localhost:4003/api/search?q=deployment+issue&limit=5');
-const data = await results.json();
-// Agent now has context from past sessions
-```
-
-### Demo Mode
-
-Want to see what AgentActa looks like with data? Run with demo sessions:
-
-```bash
-# Generate demo data and start in demo mode
-npm run demo
-
-# Or separately:
-node scripts/seed-demo.js
-node index.js --demo
+const res = await fetch('http://localhost:4003/api/search?q=deployment+issue&limit=5');
+const data = await res.json();
 ```
 
-This creates 7 realistic sessions simulating a developer building a weather app — scaffolding, API integration, frontend, debugging, deployment, tests, and a sub-agent task.
-
 ## Security
 
-**AgentActa is a local tool.** It binds to `127.0.0.1` by default — only accessible from your machine.
+AgentActa binds to `127.0.0.1` by default.
 
-To expose on your network (e.g., for Tailscale access):
+If you expose it on a network, do it intentionally:
 
 ```bash
 AGENTACTA_HOST=0.0.0.0 agentacta
 ```
 
-⚠️ **Important:** Agent session data can contain sensitive information — file contents, API responses, personal messages, tool call arguments. If you expose AgentActa on a network, ensure it's a trusted one. There is no built-in authentication.
+**Important:** Session data can contain sensitive content (file snippets, API payloads, personal messages, tool args). There is no built-in auth yet, so only expose on trusted networks.
 
-## Tech Stack
+## Tech stack
 
-- **Node.js** — HTTP server (built-in `http`, no Express)
-- **better-sqlite3** — Fast SQLite with FTS5 full-text search
-- **Vanilla HTML/CSS/JS** — No framework, no build step
-- **PWA** — Installable as a home screen app
+- Node.js (built-in `http`)
+- `better-sqlite3` + SQLite FTS5
+- Vanilla HTML/CSS/JS
+- PWA support
 
 ## Privacy
 
-All data stays local. AgentActa runs entirely on your machine — no cloud services, no telemetry, no external requests. Your agent history is yours.
+No telemetry. No cloud sync. No external indexing service.
+
+Your session history stays local.
 
 ## Compatibility
 
@@ -207,13 +204,15 @@ All data stays local. AgentActa runs entirely on your machine — no cloud servi
 
 ## Contributing
 
-PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup and guidelines. If you're adding support for a new agent format, add a parser in `indexer.js` and open a PR.
+PRs welcome.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). If you’re adding a new agent format, start in `indexer.js`.
 
-## Etymology
+## Name
 
-*Acta* (Latin) — "things done." In ancient Rome, the *acta diurna* were daily public records of official proceedings — senate decisions, military victories, births and deaths — posted in public spaces for all citizens to read.
+*Acta* is Latin for “things done.”
 
-AgentActa is the same idea: a complete, searchable record of everything your AI agent did.
+That’s the job here: keep a readable record of what your agents actually did.
 
 ## License
 
@@ -221,4 +220,4 @@ MIT
 
 ---
 
-Built in Chicago by humans and agents working together.
+Built in Chicago by humans and agents.

package/db.js

@@ -54,6 +54,7 @@ function init(dbPath) {
       FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE
     );
 
+    CREATE INDEX IF NOT EXISTS idx_sessions_start_time ON sessions(start_time DESC);
     CREATE INDEX IF NOT EXISTS idx_events_session ON events(session_id);
     CREATE INDEX IF NOT EXISTS idx_events_timestamp ON events(timestamp);
     CREATE INDEX IF NOT EXISTS idx_events_type ON events(type);

package/index.js

@@ -1,9 +1,25 @@
 #!/usr/bin/env node
+
+// Bridge release for users on ^1.x semver ranges
+if (require('./package.json').version === '1.5.0') {
+  console.log('\n\x1b[33m⚠  AgentActa has moved to CalVer versioning (2026.x.x).\x1b[0m');
+  console.log('\x1b[33m   You are running an old 1.x version.\x1b[0m\n');
+  console.log('   Update with:  \x1b[36mnpx agentacta@latest\x1b[0m');
+  console.log('   Or install:   \x1b[36mnpm install -g agentacta@latest\x1b[0m\n');
+}
+
 const http = require('http');
 const fs = require('fs');
 const path = require('path');
 const { EventEmitter } = require('events');
 
+// --version / -v flag: print version and exit
+if (process.argv.includes('--version') || process.argv.includes('-v')) {
+  const pkg = require('./package.json');
+  console.log(`${pkg.name} v${pkg.version}`);
+  process.exit(0);
+}
+
 // --demo flag: use demo session data (must run before config load)
 if (process.argv.includes('--demo')) {
   const demoDir = path.join(__dirname, 'demo');
@@ -193,6 +209,20 @@ const server = http.createServer((req, res) => {
       return json(res, { ok: true, sessions: result.sessions, events: result.events });
     }
 
+    else if (pathname === '/api/health') {
+      const pkg = require('./package.json');
+      const sessions = db.prepare('SELECT COUNT(*) as c FROM sessions').get().c;
+      const dbSize = getDbSize();
+      return json(res, {
+        status: 'ok',
+        version: pkg.version,
+        uptime: Math.round(process.uptime()),
+        sessions,
+        dbSizeBytes: dbSize.bytes,
+        node: process.version
+      });
+    }
+
     else if (pathname === '/api/config') {
       const dbSize = getDbSize();
       const archiveCount = db.prepare('SELECT COUNT(*) as c FROM archive').get().c;
@@ -428,13 +458,70 @@ const server = http.createServer((req, res) => {
       const date = query.date || (() => { const n = new Date(); return `${n.getFullYear()}-${String(n.getMonth()+1).padStart(2,'0')}-${String(n.getDate()).padStart(2,'0')}`; })();
       const from = new Date(date + 'T00:00:00').toISOString();
       const to = new Date(date + 'T23:59:59.999').toISOString();
+      const limit = Math.min(parseInt(query.limit || '100', 10) || 100, 500);
+      const offset = Math.max(parseInt(query.offset || '0', 10) || 0, 0);
       const events = db.prepare(
         `SELECT e.*, s.summary as session_summary FROM events e
          JOIN sessions s ON s.id = e.session_id
          WHERE e.timestamp >= ? AND e.timestamp <= ?
-         ORDER BY e.timestamp DESC`
-      ).all(from, to);
-      json(res, { date, events, total: events.length });
+         ORDER BY e.timestamp DESC
+         LIMIT ? OFFSET ?`
+      ).all(from, to, limit, offset);
+      const total = db.prepare(
+        `SELECT COUNT(*) as c FROM events e
+         WHERE e.timestamp >= ? AND e.timestamp <= ?`
+      ).get(from, to).c;
+      json(res, { date, events, total, limit, offset, hasMore: offset + events.length < total });
+    }
+    else if (pathname === '/api/timeline/stream') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'X-Accel-Buffering': 'no'
+      });
+      res.write(': connected\n\n');
+
+      let lastTs = query.after || new Date().toISOString();
+      let lastId = query.afterId || '';
+
+      const onUpdate = () => {
+        try {
+          const rows = db.prepare(
+            `SELECT e.*, s.summary as session_summary FROM events e
+             JOIN sessions s ON s.id = e.session_id
+             WHERE (e.timestamp > ?) OR (e.timestamp = ? AND e.id > ?)
+             ORDER BY e.timestamp ASC, e.id ASC`
+          ).all(lastTs, lastTs, lastId);
+          if (rows.length) {
+            const tail = rows[rows.length - 1];
+            lastTs = tail.timestamp || lastTs;
+            lastId = tail.id || lastId;
+            res.write(`id: ${lastTs}:${lastId}\ndata: ${JSON.stringify(rows)}\n\n`);
+          }
+        } catch (err) {
+          console.error('Timeline SSE error:', err.message);
+        }
+      };
+
+      sseEmitter.on('session-update', onUpdate);
+
+      const ping = setInterval(() => {
+        try { res.write(': ping\n\n'); } catch {}
+      }, 30000);
+
+      req.on('close', () => {
+        sseEmitter.off('session-update', onUpdate);
+        clearInterval(ping);
+      });
+    }
+    else if (pathname === '/api/maintenance') {
+      if (req.method !== 'POST') return json(res, { error: 'Method not allowed' }, 405);
+      const sizeBefore = getDbSize();
+      db.pragma('wal_checkpoint(TRUNCATE)');
+      db.exec('VACUUM');
+      const sizeAfter = getDbSize();
+      json(res, { ok: true, sizeBefore, sizeAfter });
     }
     else if (pathname === '/api/files') {
       const limit = parseInt(query.limit) || 100;

package/package.json

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