openclaw-trace 1.0.0 → 1.0.1

package/README.md

@@ -28,35 +28,38 @@ An extension for OpenClaw that provides comprehensive visibility into agent exec
 - 🔍 **Step inspection** - Full tool call/result details with expandable views
 - 📤 **API access** - Programmatic access to all metrics via REST API
 
-## Installation
+## Prerequisites
 
-### Prerequisites
-- **OpenClaw** installed and configured at `~/.openclaw`
+- **[OpenClaw](https://github.com/nicholasgriffintn/openclaw)** installed and configured at `~/.openclaw`
 - **Node.js** v14+ (already required by OpenClaw)
+- At least one agent session (`.jsonl` files in `~/.openclaw/agents/*/sessions/`)
 
-### Quick Start (recommended)
+## Quick Start
 
 ```bash
 npx openclaw-trace
 ```
 
-No installation needed — runs directly from npm.
+No installation needed — runs directly from npm on macOS, Linux, and Windows.
 
-### Global Install
+Open **http://localhost:3141** in your browser.
 
-```bash
-npm install -g openclaw-trace
-openclaw-trace
-```
+## Usage
 
-Output:
-```
-  🦞 OpenClaw Trace → http://localhost:3141
+```bash
+npx openclaw-trace          # run in foreground
+npx openclaw-trace --bg     # run as background daemon
+npx openclaw-trace --stop   # stop background daemon
 ```
 
-### Access the Dashboard
+### Global Install (optional)
 
-Open your browser to **http://localhost:3141**
+```bash
+npm install -g openclaw-trace
+openclaw-trace
+openclaw-trace --bg
+openclaw-trace --stop
+```
 
 ### Navigation
 
@@ -67,63 +70,38 @@ Open your browser to **http://localhost:3141**
 - **Compare Mode** - Click "Compare" button in header → select 2 heartbeats → view delta
 - **API Buttons** - Each heartbeat has 📋 API and ⚠ API buttons to copy URLs for programmatic access
 
-### API Access for Agents
+## API
 
-The dashboard provides REST API endpoints that agents can use for self-improvement and optimization:
+REST API available at `http://localhost:3141/api/`:
 
-```bash
-# Source helper functions
-source ~/.openclaw/canvas/dashboard-helper.sh
-
-# Check if budget allows running
-if dashboard_check_budget; then
-  echo "Budget OK, running agent..."
-else
-  echo "Budget exceeded, skipping"
-  exit 1
-fi
-
-# Get latest heartbeat data
-latest=$(dashboard_latest_hb "promo-assistant-reddit")
-cost=$(echo $latest | jq -r '.totalCost')
-errors=$(echo $latest | jq -r '.errorCount')
-
-# Get only error steps from previous run
-errors_only=$(dashboard_latest_errors_only "promo-assistant-reddit")
-```
+| Endpoint | Description |
+|---|---|
+| `/api/agents` | List all agents with stats |
+| `/api/agent/:id` | Get specific agent details |
+| `/api/latest?agent=X` | Get latest heartbeat |
+| `/api/heartbeat?agent=X&hb=N` | Get specific heartbeat by index |
+| `/api/heartbeats?agent=X&errors=true` | Query heartbeats with filters |
+| `/api/budget` | Get current budget status |
+| `/api/daily?days=N` | Get daily cost breakdown |
+| `/api/stats` | Overall system statistics |
 
-**Available API endpoints:**
-- `/api/agents` - List all agents with stats
-- `/api/agent/:id` - Get specific agent details
-- `/api/latest?agent=X` - Get latest heartbeat
-- `/api/heartbeat?agent=X&hb=N` - Get specific heartbeat by index
-- `/api/heartbeats?agent=X&errors=true` - Query heartbeats with filters
-- `/api/budget` - Get current budget status
-- `/api/daily?days=N` - Get daily cost breakdown
-- `/api/stats` - Overall system statistics
+Add `&errors_only=true` to any heartbeat endpoint to get only steps with errors.
 
-**Error filtering:**
-Add `&errors_only=true` to any heartbeat endpoint to get only steps with errors. Perfect for debugging and self-correction loops.
-
-See [API.md](API.md) and [ERRORS_ONLY_FEATURE.md](ERRORS_ONLY_FEATURE.md) for complete documentation.
+See [API.md](API.md) for complete documentation.
 
 ## Configuration
 
 ### Budget Settings
 
-Edit `~/.openclaw/canvas/budget.json`:
+Create `~/.openclaw/canvas/budget.json`:
 
 ```json
 {
-  "daily": 10.00,     // Daily spending limit in USD
-  "monthly": 200.00   // Monthly spending limit in USD
+  "daily": 10.00,
+  "monthly": 200.00
 }
 ```
 
-The dashboard calculates:
-- **Daily progress**: Today's spend vs daily limit
-- **Projected monthly**: (7-day average × 30) vs monthly limit
-
 ### Port Configuration
 
 To change the default port (3141), edit `openclaw-trace.js`:
@@ -132,24 +110,6 @@ To change the default port (3141), edit `openclaw-trace.js`:
 const PORT = 3141;  // Change to your preferred port
 ```
 
-## Understanding the Metrics
-
-### Live Status Dots
-- 🟢 **Green**: Active (heartbeat < 15min ago)
-- 🟡 **Yellow**: Idle (heartbeat < 1hr ago)
-- ⚫ **Grey**: Inactive (heartbeat > 1hr ago)
-
-### Cache Hit Rate
-- **>70%**: Excellent (green) - prompt caching is working well
-- **50-70%**: Good (blue) - normal for varied workloads
-- **<50%**: Low (orange) - possible prompt drift or cold starts
-
-### Waste Flags
-- **Runaway loop**: >30 steps in one heartbeat
-- **Low cache hit**: <50% cache efficiency (>5 steps)
-- **Large result**: >10k char tool result (likely unscoped snapshot)
-- **Bloated context**: >50k tokens in one step
-
 ## How It Works
 
 The dashboard reads OpenClaw's session JSONL files from:
@@ -164,17 +124,14 @@ It parses:
 - Tool calls (browser, read, write, bash, etc.)
 - Errors and timing data
 
-**No external dependencies** - pure Node.js stdlib + embedded HTML/CSS/JS.
+**No external dependencies** — single file, pure Node.js stdlib + embedded HTML/CSS/JS.
 
 ## Troubleshooting
 
 ### Dashboard won't start
 ```bash
-# Check if port 3141 is already in use
-lsof -ti:3141
-
-# Kill existing process
-lsof -ti:3141 | xargs kill -9
+npx openclaw-trace --stop   # stop any existing instance
+npx openclaw-trace           # start fresh
 ```
 
 ### No data showing
@@ -186,61 +143,10 @@ lsof -ti:3141 | xargs kill -9
 - Create `~/.openclaw/canvas/budget.json` with valid JSON
 - Ensure at least one heartbeat exists for today
 
-## Integration with OpenClaw
-
-This dashboard is designed as a **drop-in extension** for OpenClaw. It:
-- ✅ Reads existing OpenClaw session files (no schema changes)
-- ✅ Works with all 10 platform agents (Threads, Twitter, Reddit, HN, PH, IH, Dev.to, LinkedIn, Medium, TikTok)
-- ✅ Runs independently on a separate port (doesn't interfere with gateway)
-- ✅ Auto-discovers agents from `openclaw.json`
-
-### Using with OpenClaw Gateway
-
-If you're running the OpenClaw gateway (`openclaw serve`), the dashboard runs alongside it:
-- **Gateway**: `http://localhost:18789`
-- **Dashboard**: `http://localhost:3141`
-
-Both can run simultaneously with no conflicts.
-
-## Development
-
-The entire application is a single `openclaw-trace.js` file (~1350 lines):
-- **Backend**: Node.js HTTP server + JSONL parser
-- **Frontend**: Embedded HTML/CSS/JS (no build step)
-- **Rendering**: Vanilla JS with SVG charts
-
-To modify:
-1. Edit `openclaw-trace.js`
-2. Restart the server
-3. Refresh browser (auto-refresh will pick up data changes)
-
-## Performance
-
-- **Session file reads**: ~50ms for 10 agents with 100+ heartbeats each
-- **Memory usage**: ~30MB RSS
-- **Browser performance**: Handles 1000+ heartbeats smoothly
-
-## Roadmap
-
-Potential future enhancements:
-- [ ] Webhook alerts when budget exceeds threshold
-- [ ] Per-agent budget allocation
-- [ ] Model comparison (Opus vs Sonnet vs Haiku costs)
-- [ ] Browser extension for inline metrics
-- [ ] Prometheus/Grafana exporter
-
 ## Contributing
 
 Contributions welcome! Please open an issue or PR at https://github.com/Tell-Me-Mo/openclaw-trace
 
 ## License
 
-MIT License - see LICENSE file for details
-
-## Acknowledgments
-
-Built for the OpenClaw multi-agent framework.
-
----
-
-**Need help?** Open an issue or reach out in the OpenClaw community.
+MIT License - see [LICENSE](LICENSE) for details.

package/openclaw-trace.js

@@ -1,10 +1,39 @@
 #!/usr/bin/env node
 // OpenClaw Trace
 // Repository: https://github.com/Tell-Me-Mo/openclaw-trace
-// Usage: npx openclaw-trace
-// Then open: http://localhost:3141
+// Usage: npx openclaw-trace        (foreground)
+//        npx openclaw-trace --bg   (background daemon)
 'use strict';
 
+// ── Stop: gracefully shut down a running instance ────────────────────────────
+if (process.argv.includes('--stop')) {
+  const http = require('http');
+  const req = http.get('http://127.0.0.1:3141/api/shutdown', (res) => {
+    console.log('\n  🦞 OpenClaw Trace stopped\n');
+    process.exit(0);
+  });
+  req.on('error', () => {
+    console.log('\n  No running instance found on port 3141\n');
+    process.exit(1);
+  });
+  req.setTimeout(3000, () => { req.destroy(); process.exit(1); });
+} else
+
+// ── Background mode: re-spawn as detached process ────────────────────────────
+if (process.argv.includes('--bg')) {
+  const { spawn } = require('child_process');
+  const args = process.argv.slice(1).filter(a => a !== '--bg');
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+  console.log(`\n  🦞 OpenClaw Trace running in background (pid ${child.pid})`);
+  console.log(`  → http://localhost:3141`);
+  console.log(`  Stop: npx openclaw-trace --stop\n`);
+  process.exit(0);
+}
+
 const http = require('http');
 const fs   = require('fs');
 const path = require('path');
@@ -910,6 +939,13 @@ http.createServer(async (req, res) => {
     return;
   }
 
+  // GET /api/shutdown - graceful shutdown
+  if (url === '/api/shutdown') {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ status: 'shutting down' }));
+    process.exit(0);
+  }
+
   res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
   res.end(HTML);
 }).listen(PORT, () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-trace",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "End-to-end tracing and observability for OpenClaw multi-agent systems",
   "bin": {
     "openclaw-trace": "openclaw-trace.js"