openclaw-trace 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Trace Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,246 @@
+# OpenClaw Trace
+
+**End-to-end tracing and observability for OpenClaw multi-agent systems**
+
+An extension for OpenClaw that provides comprehensive visibility into agent execution traces, token consumption, costs, and performance across all your agents.
+
+![Dashboard Preview](https://img.shields.io/badge/OpenClaw-Extension-blue)
+
+### Main Dashboard View
+<img width="1911" height="524" alt="image" src="https://github.com/user-attachments/assets/48b6a3ce-ddf9-493c-ae3b-c0778629f225" />
+
+*Overview of agent performance with cost and context growth charts. Shows sidebar with all agents, stats cards, and expandable heartbeat rows.*
+
+### Detailed Heartbeat Analysis
+<img width="1884" height="716" alt="image" src="https://github.com/user-attachments/assets/d1e6ec2c-8956-4f49-86da-711fce27075f" />
+
+*Expanded heartbeat view showing cost per step, tool usage breakdown, cost breakdown, and detailed step-by-step execution with full tool call/result inspection.*
+
+## Features
+
+- 📊 **Real-time monitoring** - Live agent status, auto-refresh, cross-agent overview
+- 💰 **Budget tracking** - Daily/monthly limits with projected costs and alerts
+- 📈 **Historical analysis** - 7-day trends, per-heartbeat drill-down, context growth
+- ⚡ **Optimization tools** - Cache hit rates, waste detection, actionable hints
+- 🔍 **A/B comparison** - Side-by-side heartbeat comparison with delta calculations
+- 🎛️ **Collapsible sidebar** - Toggle agent list for more screen space
+- 📊 **Rich charts** - Cost, context, and tool usage visualizations
+- 🔍 **Step inspection** - Full tool call/result details with expandable views
+- 📤 **API access** - Programmatic access to all metrics via REST API
+
+## Installation
+
+### Prerequisites
+- **OpenClaw** installed and configured at `~/.openclaw`
+- **Node.js** v14+ (already required by OpenClaw)
+
+### Quick Start (recommended)
+
+```bash
+npx openclaw-trace
+```
+
+No installation needed — runs directly from npm.
+
+### Global Install
+
+```bash
+npm install -g openclaw-trace
+openclaw-trace
+```
+
+Output:
+```
+  🦞 OpenClaw Trace → http://localhost:3141
+```
+
+### Access the Dashboard
+
+Open your browser to **http://localhost:3141**
+
+### Navigation
+
+- **Sidebar Toggle** - Click ☰ button to hide/show the agent sidebar for more screen space
+- **Sidebar** - Click any agent to view its details
+- **Overview** - Default view showing all agents and 7-day trend
+- **Agent View** - Session cost, heartbeats, cache stats, and full drill-down
+- **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
+
+The dashboard provides REST API endpoints that agents can use for self-improvement and optimization:
+
+```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")
+```
+
+**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
+
+**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.
+
+## Configuration
+
+### Budget Settings
+
+Edit `~/.openclaw/canvas/budget.json`:
+
+```json
+{
+  "daily": 10.00,     // Daily spending limit in USD
+  "monthly": 200.00   // Monthly spending limit in USD
+}
+```
+
+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`:
+
+```javascript
+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:
+```
+~/.openclaw/agents/*/sessions/sessions.json
+~/.openclaw/agents/*/sessions/*.jsonl
+```
+
+It parses:
+- Token usage (`input`, `output`, `cacheRead`, `cacheWrite`)
+- Costs per step (from Claude API usage metadata)
+- Tool calls (browser, read, write, bash, etc.)
+- Errors and timing data
+
+**No external dependencies** - 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
+```
+
+### No data showing
+- Ensure OpenClaw agents have run at least once
+- Check `~/.openclaw/agents/*/sessions/` contains `.jsonl` files
+- Verify `~/.openclaw/openclaw.json` exists with agent definitions
+
+### Budget bar not showing
+- 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.

package/budget.json

@@ -0,0 +1,4 @@
+{
+  "daily": 5.00,
+  "monthly": 100.00
+}

package/dashboard-helper.sh

@@ -0,0 +1,169 @@
+#!/bin/bash
+# OpenClaw Trace Helper Functions
+# Source this file in your agent scripts: source ~/.openclaw/canvas/dashboard-helper.sh
+
+DASHBOARD_API="http://127.0.0.1:3141/api"
+
+# Check if budget is OK to run
+# Returns 0 if OK, 1 if over budget
+dashboard_check_budget() {
+  local status=$(curl -s "$DASHBOARD_API/budget" | jq -r '.status // "error"')
+  case "$status" in
+    ok|warning) return 0 ;;
+    over|error) return 1 ;;
+  esac
+}
+
+# Get budget percentage used today
+dashboard_budget_pct() {
+  curl -s "$DASHBOARD_API/budget" | jq -r '.dailyPct // 0'
+}
+
+# Get latest heartbeat for agent
+# Usage: dashboard_latest_hb "promo-assistant-reddit"
+dashboard_latest_hb() {
+  local agent_id="$1"
+  curl -s "$DASHBOARD_API/latest?agent=$agent_id"
+}
+
+# Get specific heartbeat by index (0 = latest, 1 = second-to-latest, etc.)
+# Usage: dashboard_get_hb "promo-assistant-reddit" 2
+dashboard_get_hb() {
+  local agent_id="$1"
+  local index="${2:-0}"
+  curl -s "$DASHBOARD_API/heartbeat?agent=$agent_id&index=$index"
+}
+
+# Get only error steps from latest heartbeat
+# Usage: dashboard_latest_errors_only "promo-assistant-reddit"
+dashboard_latest_errors_only() {
+  local agent_id="$1"
+  curl -s "$DASHBOARD_API/latest?agent=$agent_id&errors_only=true"
+}
+
+# Get only error steps from specific heartbeat
+# Usage: dashboard_get_hb_errors "promo-assistant-reddit" 1
+dashboard_get_hb_errors() {
+  local agent_id="$1"
+  local index="${2:-0}"
+  curl -s "$DASHBOARD_API/heartbeat?agent=$agent_id&index=$index&errors_only=true"
+}
+
+# Get latest heartbeat cost
+# Usage: dashboard_latest_cost "promo-assistant-reddit"
+dashboard_latest_cost() {
+  local agent_id="$1"
+  curl -s "$DASHBOARD_API/latest?agent=$agent_id" | jq -r '.totalCost // 0'
+}
+
+# Get latest heartbeat error count
+# Usage: dashboard_latest_errors "promo-assistant-reddit"
+dashboard_latest_errors() {
+  local agent_id="$1"
+  curl -s "$DASHBOARD_API/latest?agent=$agent_id" | jq -r '.errorCount // 0'
+}
+
+# Get agent summary
+# Usage: dashboard_agent_info "promo-assistant-reddit"
+dashboard_agent_info() {
+  local agent_id="$1"
+  curl -s "$DASHBOARD_API/agent/$agent_id"
+}
+
+# Get recent heartbeats with errors
+# Usage: dashboard_recent_errors "promo-assistant-reddit" 10
+dashboard_recent_errors() {
+  local agent_id="$1"
+  local limit="${2:-10}"
+  curl -s "$DASHBOARD_API/heartbeats?agent=$agent_id&errors=true&limit=$limit"
+}
+
+# Get expensive heartbeats (above threshold)
+# Usage: dashboard_expensive_hbs 0.01 20
+dashboard_expensive_hbs() {
+  local min_cost="${1:-0.01}"
+  local limit="${2:-10}"
+  curl -s "$DASHBOARD_API/heartbeats?minCost=$min_cost&limit=$limit"
+}
+
+# Get today's cost
+dashboard_today_cost() {
+  curl -s "$DASHBOARD_API/daily?days=1" | jq -r '.[0].cost // 0'
+}
+
+# Get today's heartbeat count
+dashboard_today_count() {
+  curl -s "$DASHBOARD_API/daily?days=1" | jq -r '.[0].heartbeats // 0'
+}
+
+# Get all agents list
+dashboard_list_agents() {
+  curl -s "$DASHBOARD_API/agents"
+}
+
+# Get overall stats
+dashboard_stats() {
+  curl -s "$DASHBOARD_API/stats"
+}
+
+# Check if agent has recent errors (last 5 heartbeats)
+# Returns 0 if no errors, 1 if errors found
+dashboard_has_errors() {
+  local agent_id="$1"
+  local error_count=$(curl -s "$DASHBOARD_API/heartbeats?agent=$agent_id&errors=true&limit=5" | jq 'length')
+  [ "$error_count" -gt 0 ] && return 1 || return 0
+}
+
+# Pretty print budget status
+dashboard_budget_status() {
+  local budget=$(curl -s "$DASHBOARD_API/budget")
+  echo "Budget Status:"
+  echo "  Today: \$$(echo $budget | jq -r '.todayCost') / \$$(echo $budget | jq -r '.daily') ($(echo $budget | jq -r '.dailyPct')%)"
+  echo "  Projected Monthly: \$$(echo $budget | jq -r '.projectedMonthly') / \$$(echo $budget | jq -r '.monthly')"
+  echo "  Status: $(echo $budget | jq -r '.status')"
+}
+
+# Pretty print agent stats
+dashboard_agent_stats() {
+  local agent_id="$1"
+  local info=$(curl -s "$DASHBOARD_API/agent/$agent_id")
+  echo "Agent: $(echo $info | jq -r '.name')"
+  echo "  Total Cost: \$$(echo $info | jq -r '.totalCost')"
+  echo "  Heartbeats: $(echo $info | jq -r '.heartbeats | length')"
+  echo "  Errors: $(echo $info | jq -r '.totalErrors')"
+  echo "  Cache Hit: $(echo $info | jq -r '.avgCacheHit')%"
+  echo "  Context: $(echo $info | jq -r '.totalTokens') / $(echo $info | jq -r '.contextTokens')"
+}
+
+# Example usage guard
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  echo "OpenClaw Trace Helper Functions"
+  echo "Usage: source $0"
+  echo ""
+  echo "Available functions:"
+  echo "  dashboard_check_budget          - Check if budget allows running (exit 0 = OK)"
+  echo "  dashboard_budget_pct            - Get budget % used today"
+  echo "  dashboard_latest_hb AGENT       - Get latest heartbeat JSON"
+  echo "  dashboard_get_hb AGENT INDEX    - Get specific heartbeat by index (0=latest)"
+  echo "  dashboard_latest_errors_only AGENT - Get only error steps from latest heartbeat"
+  echo "  dashboard_get_hb_errors AGENT INDEX - Get only error steps from specific heartbeat"
+  echo "  dashboard_latest_cost AGENT     - Get latest heartbeat cost"
+  echo "  dashboard_latest_errors AGENT   - Get latest heartbeat error count"
+  echo "  dashboard_agent_info AGENT      - Get agent summary"
+  echo "  dashboard_recent_errors AGENT [LIMIT] - Get recent error heartbeats"
+  echo "  dashboard_expensive_hbs [MIN_COST] [LIMIT] - Get expensive heartbeats"
+  echo "  dashboard_today_cost            - Get today's total cost"
+  echo "  dashboard_today_count           - Get today's heartbeat count"
+  echo "  dashboard_list_agents           - List all agents"
+  echo "  dashboard_stats                 - Get overall statistics"
+  echo "  dashboard_has_errors AGENT      - Check if agent has recent errors (exit 1 = yes)"
+  echo "  dashboard_budget_status         - Pretty print budget status"
+  echo "  dashboard_agent_stats AGENT     - Pretty print agent stats"
+  echo ""
+  echo "Example:"
+  echo "  if dashboard_check_budget; then"
+  echo "    echo 'Budget OK, running agent...'"
+  echo "  else"
+  echo "    echo 'Budget exceeded, skipping'"
+  echo "  fi"
+fi