claw-insights 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claw Insights 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,112 @@
+<div align="center">
+  <img src="packages/web/public/logo/icon-dark.svg" width="80" alt="Claw Insights" />
+  <h1>Claw Insights</h1>
+  <p><strong>Replay, metrics, logs &amp; shareable snapshots for <a href="https://github.com/openclaw/openclaw">OpenClaw</a> agents</strong></p>
+  <p>
+    <img src="https://img.shields.io/badge/%F0%9F%94%8C_Zero_Intrusion-read--only_sidecar-10b981" alt="Zero Intrusion" />
+    <img src="https://img.shields.io/badge/%F0%9F%94%8D_Full_Replay-session_transcripts-6366f1" alt="Full Replay" />
+    <img src="https://img.shields.io/badge/%F0%9F%93%B8_Shareable_Snapshots-PNG_%7C_SVG-f59e0b" alt="Shareable Snapshots" />
+  </p>
+  <p>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-%E2%89%A522.5-green" alt="Node.js" /></a>
+    <img src="https://img.shields.io/badge/macOS-supported-blue" alt="macOS" />
+    <img src="https://img.shields.io/badge/Linux-supported-blue" alt="Linux" />
+  </p>
+  <br />
+  <img src="docs/assets/hero-montage.png" width="100%" alt="Dashboard, Session Transcript, and Snapshot API" />
+</div>
+
+---
+
+<p align="center">
+  <strong>English</strong> ·
+  <a href="README.zh-CN.md">中文</a>
+</p>
+
+## Features
+
+- **Zero Intrusion** — Pure read-only sidecar; no code changes, no cloud calls, data never leaves your machine
+- **Session Replay** — Full transcript timeline with role separation, tool calls, and per-turn token tracking
+- **Shareable Snapshots** — Generate PNG/SVG status cards via REST API with themes, languages, and detail levels
+- **Metrics Dashboard** — Per-model token breakdown, error rates, and uptime over 30m / 1h / 6h / 12h / 24h
+- **Event Logs** — Structured viewer with density heatmap, filtering, and search
+- **One Command Setup** — Auto-discovers your running gateway, lightweight SQLite storage
+- **Dark / Light · EN / 中文** — Full theming and i18n with runtime toggle
+
+## Quick Start
+
+```bash
+# Install
+npm install -g claw-insights
+
+# Start (auto-connects to your running OpenClaw gateway)
+claw-insights start
+```
+
+On launch you'll see an access URL:
+
+```
+✅ Claw Insights v0.1.0    ready in 1.2s
+
+➜  Open:  http://127.0.0.1:41041/?token=abc123...
+   Auth:  token (auto-generated)
+
+PID 12345 · daemon · Port 41041
+```
+
+Open the URL — token is exchanged for a session cookie, and you're in.
+
+```bash
+claw-insights status          # Show current access URL
+claw-insights stop            # Stop daemon
+claw-insights start --no-auth # Disable authentication
+```
+
+→ Full install options, snapshot API, and troubleshooting: [docs/configuration.md](docs/configuration.md)
+
+## 🤖 AI Agent Friendly
+
+Ships with structured resources for AI agents — see **[AGENTS.md](AGENTS.md)** for the full index:
+
+| Skill                                     | Use case                                          |
+| ----------------------------------------- | ------------------------------------------------- |
+| [install](docs/skills/install/SKILL.md)   | Install, configure, and launch                    |
+| [snapshot](docs/skills/snapshot/SKILL.md) | Capture dashboard as PNG/SVG/JSON via REST or CLI |
+
+## Architecture
+
+```
+claw-insights/
+├── packages/
+│   ├── server/     Express + GraphQL Yoga + SQLite + Satori renderer
+│   ├── web/        React 19 + Vite + Tailwind + ECharts + urql
+│   └── shared/     Codegen TypeScript types (shared between server & web)
+├── bin/            CLI entry (start/stop/restart/status/logs/snapshot/run)
+└── codegen.ts      GraphQL codegen config (3 targets)
+```
+
+**Data flow:** OpenClaw gateway → log tailing + CLI → SQLite → GraphQL (SSE subscriptions) → React
+
+→ Full architecture, dev setup, and codegen: [docs/architecture.md](docs/architecture.md)
+
+## Documentation
+
+| Document                               | Description                           |
+| -------------------------------------- | ------------------------------------- |
+| [Configuration](docs/configuration.md) | All env vars, config file, auth model |
+| [Architecture](docs/architecture.md)   | System design, dev setup, testing     |
+| [API Reference](docs/api-reference.md) | GraphQL + REST endpoint signatures    |
+| [AGENTS.md](AGENTS.md)                 | AI agent skill index                  |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, PR guidelines, and code conventions.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting and security model.
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "claw-insights",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Real-time monitoring dashboard for OpenClaw gateway",
   "type": "module",
   "bin": {
     "claw-insights": "./bin/claw-insights"
   },
-  "files": ["bin/", "server/", "web/", "assets/"],
+  "files": ["bin/", "server/", "web/", "assets/", "README.md", "LICENSE"],
   "engines": { "node": ">=22" },
   "license": "MIT",
   "author": "Luca Liao",

package/server/{chunk-TGTG7GUF.js → chunk-MU2QNIHA.js}

@@ -12,6 +12,11 @@ import { execFile } from "child_process";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
 var log = createChildLogger("cli-adapter");
+var DEFAULT_TIMEOUT_MS = 8e3;
+var STATUS_JSON_TIMEOUT_MS = 15e3;
+function resolveTimeoutMs(argv) {
+  return argv[0] === "status" && argv.includes("--json") ? STATUS_JSON_TIMEOUT_MS : DEFAULT_TIMEOUT_MS;
+}
 var PosixCliAdapter = class {
   constructor(cliPath, env) {
     this.cliPath = cliPath;
@@ -21,7 +26,7 @@ var PosixCliAdapter = class {
     try {
       log.debug({ argv }, "CLI exec");
       const { stdout, stderr: _stderr } = await execFileAsync(this.cliPath, argv, {
-        timeout: 8e3,
+        timeout: resolveTimeoutMs(argv),
         encoding: "utf-8",
         env: this.env
       });

package/server/{darwin-DLFRTJ37.js → darwin-IIBM6CQD.js}

@@ -1,7 +1,7 @@
 import {
   PosixCliAdapter,
   PosixProcessAdapter
-} from "./chunk-TGTG7GUF.js";
+} from "./chunk-MU2QNIHA.js";
 import {
   CLI_ENV,
   config,

package/server/index.js

@@ -1594,9 +1594,9 @@ async function loadPlatform() {
   log7.info({ os }, "loading platform adapter");
   switch (os) {
     case "darwin":
-      return (await import("./darwin-DLFRTJ37.js")).platform;
+      return (await import("./darwin-IIBM6CQD.js")).platform;
     case "linux":
-      return (await import("./linux-VBQVTPRU.js")).platform;
+      return (await import("./linux-ZEULX5H5.js")).platform;
     default:
       throw new Error(`Unsupported platform: ${os}`);
   }
@@ -3513,6 +3513,7 @@ var CACHE_TTL = 1e4;
 var FAIL_CACHE_TTL = 3e3;
 var VERSION_CACHE_TTL = 6e4;
 var VERSION_FAIL_CACHE_TTL = 5e3;
+var STATUS_STALE_FALLBACK_MS = 3e4;
 function createGatewayClient(platform, options) {
   const logPath = options?.gatewayLogPath ?? config.openclawDir + "/logs/gateway.log";
   async function getStartedAtFromLog(pid) {
@@ -3551,6 +3552,7 @@ function createGatewayClient(platform, options) {
   let versionCache = null;
   let statusInFlight = null;
   let lastStatusJson = "";
+  let lastSuccessfulStatus = null;
   async function getVersion() {
     if (isCacheValid(versionCache)) {
       return versionCache.data;
@@ -3561,58 +3563,83 @@ function createGatewayClient(platform, options) {
     return version;
   }
   async function parseStatusJson(json, version) {
+    if (json.trim() === "") {
+      return { ok: false, reason: "empty" };
+    }
+    let d;
+    try {
+      d = JSON.parse(json);
+    } catch {
+      return { ok: false, reason: "invalid-json" };
+    }
     try {
-      const d = JSON.parse(json);
-      const gw = d?.gateway ?? {};
-      const svc = d?.gatewayService ?? {};
-      const channelSummary = d?.channelSummary ?? [];
-      const update = d?.update ?? {};
-      const pidMatch = svc?.runtimeShort?.match(/pid\s+(\d+)/);
+      const gw = d.gateway ?? {};
+      const svc = d.gatewayService ?? {};
+      const channelSummary = d.channelSummary ?? [];
+      const update = d.update ?? {};
+      const updateRegistry = update.registry ?? {};
+      const securityAudit = d.securityAudit ?? {};
+      const secAudit = securityAudit.summary ?? { critical: 0, warn: 0, info: 0 };
+      const sessions = d.sessions ?? {};
+      const runtimeShort = typeof svc.runtimeShort === "string" ? svc.runtimeShort : "";
+      const pidMatch = runtimeShort.match(/pid\s+(\d+)/);
       let pid = pidMatch ? Number(pidMatch[1]) : null;
-      const running = Boolean(gw?.reachable) || svc?.runtimeShort?.includes("running");
+      const running = gw.reachable === true || runtimeShort.includes("running");
       if (!pid && running) {
-        pid = await platform.process.findPidByPort(gw?.port ?? 18789);
+        const port = typeof gw.port === "number" ? gw.port : 18789;
+        pid = await platform.process.findPidByPort(port);
       }
-      const latest = update?.registry?.latestVersion ?? update?.latestVersion ?? null;
+      const latestFromRegistry = typeof updateRegistry.latestVersion === "string" ? updateRegistry.latestVersion : null;
+      const latestFromUpdate = typeof update.latestVersion === "string" ? update.latestVersion : null;
+      const latest = latestFromRegistry ?? latestFromUpdate;
       const updateAvailable = latest && latest !== version ? latest : null;
-      const connectLatencyMs = gw?.connectLatencyMs ?? null;
-      const latestVersion = update?.registry?.latestVersion ?? update?.latestVersion ?? null;
-      const secAudit = d?.securityAudit?.summary ?? { critical: 0, warn: 0, info: 0 };
-      const sessionDefaults = d?.sessions?.defaults ?? null;
+      const connectLatencyMs = typeof gw.connectLatencyMs === "number" ? gw.connectLatencyMs : null;
+      const latestVersion = latestFromRegistry ?? latestFromUpdate;
+      const rawSessionDefaults = sessions.defaults;
+      const sessionDefaults = rawSessionDefaults && typeof rawSessionDefaults.model === "string" && typeof rawSessionDefaults.contextTokens === "number" ? { model: rawSessionDefaults.model, contextTokens: rawSessionDefaults.contextTokens } : null;
+      const critical = typeof secAudit.critical === "number" ? secAudit.critical : 0;
+      const warn = typeof secAudit.warn === "number" ? secAudit.warn : 0;
+      const info = typeof secAudit.info === "number" ? secAudit.info : 0;
       const startedAt = pid ? await getStartedAtFromLog(pid) : null;
       return {
-        running: Boolean(running),
-        pid,
-        version: version ?? "unknown",
-        updateAvailable,
-        uptime: pid ? await platform.process.getUptime(pid) : "unknown",
-        startedAt,
-        channels: parseChannels(channelSummary),
-        connectLatencyMs,
-        latestVersion,
-        securitySummary: {
-          critical: secAudit.critical ?? 0,
-          warn: secAudit.warn ?? 0,
-          info: secAudit.info ?? 0
-        },
-        sessionDefaults
+        ok: true,
+        data: {
+          running,
+          pid,
+          version: version ?? "unknown",
+          updateAvailable,
+          uptime: pid ? await platform.process.getUptime(pid) : "unknown",
+          startedAt,
+          channels: parseChannels(channelSummary),
+          connectLatencyMs,
+          latestVersion,
+          securitySummary: {
+            critical,
+            warn,
+            info
+          },
+          sessionDefaults
+        }
       };
     } catch {
-      return {
-        running: false,
-        pid: null,
-        version: "unknown",
-        updateAvailable: null,
-        uptime: "unknown",
-        startedAt: null,
-        channels: [],
-        connectLatencyMs: null,
-        latestVersion: null,
-        securitySummary: { critical: 0, warn: 0, info: 0 },
-        sessionDefaults: null
-      };
+      return { ok: false, reason: "invalid-json" };
     }
   }
+  function unavailableStatus() {
+    return {
+      running: false,
+      pid: null,
+      version: "unknown",
+      updateAvailable: null,
+      uptime: "unknown",
+      startedAt: null,
+      channels: [],
+      connectLatencyMs: null,
+      latestVersion: null,
+      securitySummary: { critical: 0, warn: 0, info: 0 },
+      sessionDefaults: null
+    };
+  }
   async function getGatewayStatus() {
     if (isCacheValid(statusCache)) {
       return statusCache.data;
@@ -3623,9 +3650,24 @@ function createGatewayClient(platform, options) {
     statusInFlight = (async () => {
       try {
         const [raw, version] = await Promise.all([platform.cli.exec(["status", "--json"]), getVersion()]);
-        const status = await parseStatusJson(raw, version);
+        const parsed = await parseStatusJson(raw, version);
+        let status;
+        let ttl;
+        if (parsed.ok) {
+          status = parsed.data;
+          lastSuccessfulStatus = { data: status, ts: Date.now() };
+          ttl = status.running ? CACHE_TTL : FAIL_CACHE_TTL;
+        } else {
+          const staleAge = lastSuccessfulStatus ? Date.now() - lastSuccessfulStatus.ts : Number.POSITIVE_INFINITY;
+          if (lastSuccessfulStatus && staleAge <= STATUS_STALE_FALLBACK_MS) {
+            status = lastSuccessfulStatus.data;
+            ttl = FAIL_CACHE_TTL;
+          } else {
+            status = unavailableStatus();
+            ttl = FAIL_CACHE_TTL;
+          }
+        }
         const curJson = JSON.stringify(status);
-        const ttl = status.running ? CACHE_TTL : FAIL_CACHE_TTL;
         statusCache = { data: status, ts: Date.now(), ttl };
         if (curJson !== lastStatusJson) {
           lastStatusJson = curJson;

package/server/{linux-VBQVTPRU.js → linux-ZEULX5H5.js}

@@ -1,7 +1,7 @@
 import {
   PosixCliAdapter,
   PosixProcessAdapter
-} from "./chunk-TGTG7GUF.js";
+} from "./chunk-MU2QNIHA.js";
 import {
   CLI_ENV,
   config