agentmetrics-openclaw 0.2.0 → 0.2.3

package/README.md

@@ -1,76 +1,95 @@
 # agentmetrics-openclaw
 
-Full observability for every OpenClaw agent. Tokens, tools, latency, cost, and reliability — automatically.
+[![npm](https://img.shields.io/npm/v/agentmetrics-openclaw?color=009E80&label=npm&logo=npm&logoColor=white)](https://www.npmjs.com/package/agentmetrics-openclaw)
+[![License: MIT](https://img.shields.io/badge/license-MIT-009E80)](../LICENSE)
 
-## What it captures
+Zero-code observability for [OpenClaw](https://openclaw.dev) agents. Install the plugin, set your API key, and every agent session is tracked automatically — tokens, cost, tools, subagents, context health, and reliability.
 
-Every agent run produces one event in AgentMetrics with:
+→ **[agentmetrics.dev/docs/integrations/openclaw](https://agentmetrics.dev/docs/integrations/openclaw)**
 
-| Field | Source |
-|---|---|
-| Status (success / failed) | `agent_end.success` |
-| Duration | `agent_end.durationMs` |
-| Model & provider | `llm_output` |
-| Input tokens | `llm_output.usage.input` |
-| Output tokens | `llm_output.usage.output` |
-| Cache read tokens | `llm_output.usage.cacheRead` |
-| Cache write tokens | `llm_output.usage.cacheWrite` |
-| Tool call count | `after_tool_call` (counted) |
-| Tool error count | `after_tool_call.error` (counted) |
-| Step count | `agent_end.messages.length` |
-| Error message | `agent_end.error` |
-
-All token buckets are accumulated across the full run — multi-turn, multi-LLM-call runs are handled correctly.
+---
 
-## Setup
+## Requirements
+
+- OpenClaw 2026.3.2 or later
+- Node.js 22 or later
+- An AgentMetrics API key — [get one at agentmetrics.dev](https://agentmetrics.dev/signup)
 
-### 1. Install
+---
 
-```sh
+## Install
+
+```bash
 openclaw plugins install agentmetrics-openclaw
 ```
 
-### 2. Set your API key
+---
 
-```sh
-export AGENTMETRICS_API_KEY=am_your_key_here
+## Setup
+
+**1. Set your API key**
+
+```bash
+# macOS / Linux
+echo 'export AGENTMETRICS_API_KEY=am_live_...' >> ~/.bashrc && source ~/.bashrc
+
+# Windows (PowerShell)
+$Env:AGENTMETRICS_API_KEY = "am_live_..."
 ```
 
-Add this to your shell profile (`.bashrc`, `.zshrc`, etc.) to persist it.
+**2. Trust the plugin** (silences the security scan advisory)
 
-### 3. Restart the gateway
+```bash
+openclaw config set plugins.allow '["agentmetrics"]'
+```
 
-```sh
+**3. Restart the gateway**
+
+```bash
 openclaw gateway restart
 ```
 
-That's it. Sessions appear in your [AgentMetrics dashboard](https://agentmetrics.dev) within seconds.
+**4. Verify**
+
+```bash
+openclaw plugins list
+# agentmetrics   loaded
+```
 
-## Configuration (optional)
+---
 
-You can also set credentials in `openclaw.yml` instead of environment variables:
+## What gets tracked
 
-```yaml
-plugins:
-  agentmetrics:
-    apiKey: am_your_key_here
-    endpoint: https://api.agentmetrics.dev  # optional
-```
+Every agent session reports automatically:
 
-## Auto-enable
+| Signal | Detail |
+|---|---|
+| **Cost** | Computed from token counts and model pricing |
+| **Latency** | Wall-clock duration per run |
+| **Tokens** | Input, output, cache read, cache write |
+| **Tools** | Call count, errors, per-tool duration |
+| **Subagents** | Spawned count, error count |
+| **Context health** | Compaction count, reset count |
+| **Reliability** | Success/failure, full error message |
 
-If `AGENTMETRICS_API_KEY` is present in your environment, the plugin enables itself automatically — no manual `openclaw plugins enable agentmetrics` needed.
+---
 
-## CLI
+## Troubleshooting
 
-```sh
-openclaw agentmetrics status
-```
+**"dangerous code patterns" warning on install**
+Safe to ignore. The plugin reads `AGENTMETRICS_API_KEY` and sends it as a Bearer token to the AgentMetrics API. Add `agentmetrics` to `plugins.allow` to suppress it permanently.
+
+**"manifest id does not match package name" warning**
+Not an error. The plugin's internal manifest id is `agentmetrics`; the npm package name is `agentmetrics-openclaw`. Use `agentmetrics` (not the npm name) in `plugins.allow`.
+
+**Runs not appearing in the dashboard**
+1. Check the key is set: `echo $AGENTMETRICS_API_KEY`
+2. Verify the plugin loads: `openclaw plugins list`
+3. Restart the gateway after any env var change
+4. Confirm your `openclaw.json` has a `name` field
 
-Shows the active API key, endpoint, and current session/run counts.
+---
 
-## Links
+## License
 
-- Dashboard: [agentmetrics.dev](https://agentmetrics.dev)
-- Docs: [agentmetrics.dev/docs](https://agentmetrics.dev/docs)
-- GitHub: [github.com/andausman/agentmetrics](https://github.com/andausman/agentmetrics)
+[MIT](../LICENSE)

package/index.ts

@@ -1,9 +1,21 @@
 import { randomUUID } from "crypto";
 
-// Resolved once in register() — pluginConfig overrides env vars
+// pluginConfig overrides env vars — set once in register()
 let API_KEY: string | undefined;
 let BASE_URL: string;
 
+interface PluginApi {
+  config:         Record<string, unknown>;
+  pluginConfig?:  Record<string, unknown>;
+  registerAutoEnableProbe?: (probe: () => boolean) => void;
+  registerCli?: (registrar: {
+    name:        string;
+    description: string;
+    commands:    Array<{ name: string; description: string; handler: () => void }>;
+  }) => void;
+  on: (hookName: string, handler: (...args: unknown[]) => void) => void;
+}
+
 // ─── Types (sourced from openclaw/src/plugins/hook-types.ts) ──────────────────
 
 type AgentContext = {
@@ -164,6 +176,7 @@ interface RunMeta {
   model?:           string;
   provider?:        string;
   sessionKey?:      string;
+  startedAt:        number; // run-level start time for accurate duration
 }
 
 const sessions = new Map<string, SessionMeta>();
@@ -226,6 +239,7 @@ function emptyRun(sessionKey?: string): RunMeta {
     toolCalls: 0, toolErrors: 0, toolNames: new Set(),
     subagentsSpawned: 0, subagentErrors: 0,
     sessionKey,
+    startedAt: Date.now(),
   };
 }
 
@@ -250,21 +264,33 @@ const plugin = {
     additionalProperties: false,
   } as const,
 
-  register(api: any) {
+  register(api: PluginApi) {
     // Config: pluginConfig > env vars
-    API_KEY  = api.config?.apiKey  ?? process.env.AGENTMETRICS_API_KEY;
+    API_KEY  = (api.pluginConfig?.apiKey  as string | undefined) ?? process.env.AGENTMETRICS_API_KEY;
     BASE_URL = (
-      api.config?.endpoint ??
+      (api.pluginConfig?.endpoint as string | undefined) ??
       process.env.AGENTMETRICS_URL ??
       "https://api.agentmetrics.dev"
     ).replace(/\/$/, "");
 
-    // Auto-enable when env var is present — no manual enable needed
+    // Auto-enable when a key is available (env var or plugin config)
     if (typeof api.registerAutoEnableProbe === "function") {
-      api.registerAutoEnableProbe(() => !!process.env.AGENTMETRICS_API_KEY);
+      api.registerAutoEnableProbe(() => !!API_KEY);
     }
 
-    if (!API_KEY) return;
+    if (!API_KEY) {
+      console.log(
+        "\n  AgentMetrics: no API key found.\n" +
+        "  Your agent runs are not being tracked.\n" +
+        "  Get an API key at https://agentmetrics.dev and set AGENTMETRICS_API_KEY.\n"
+      );
+      return;
+    }
+
+    console.log(
+      `\n  AgentMetrics active — sending data to ${BASE_URL}\n` +
+      `  View your dashboard → https://agentmetrics.dev\n`
+    );
 
     // CLI: openclaw agentmetrics status
     if (typeof api.registerCli === "function") {
@@ -291,16 +317,12 @@ const plugin = {
     }
 
     // ── gateway_start ─────────────────────────────────────────────────────
+    // Activity only — gateway events are infrastructure, not agent runs.
+    // We do NOT call send() here to avoid polluting the agents list.
     api.on("gateway_start", (event: GatewayStartEvent, _ctx: GatewayContext) => {
       sendActivity("gateway_start", "openclaw-gateway", undefined, undefined, {
         port: event.port,
       });
-      send({
-        trace_id: randomUUID(),
-        agent_id: "openclaw-gateway",
-        status:   "success",
-        metadata: { event_type: "gateway_start", port: event.port },
-      });
     });
 
     // ── gateway_stop ──────────────────────────────────────────────────────
@@ -308,12 +330,6 @@ const plugin = {
       sendActivity("gateway_stop", "openclaw-gateway", undefined, undefined, {
         reason: event.reason,
       });
-      send({
-        trace_id: randomUUID(),
-        agent_id: "openclaw-gateway",
-        status:   "success",
-        metadata: { event_type: "gateway_stop", reason: event.reason },
-      });
     });
 
     // ── session_start ─────────────────────────────────────────────────────
@@ -400,7 +416,6 @@ const plugin = {
         output_tokens: event.usage?.output,
         cache_read:    event.usage?.cacheRead,
         cache_write:   event.usage?.cacheWrite,
-        // Running totals for the dashboard
         total_input:   run.inputTokens,
         total_output:  run.outputTokens,
       });
@@ -535,10 +550,13 @@ const plugin = {
         (run?.cacheReadTokens  ?? 0) +
         (run?.cacheWriteTokens ?? 0);
 
+      // Use run-level duration (accurate) — fall back to session duration only if unavailable
+      const durationMs = event.durationMs ?? (run ? Date.now() - run.startedAt : undefined);
+
       // Real-time: notify dashboard the run finished
       sendActivity("run_end", agentId, sessionKey, ctx.runId, {
         status:       event.success ? "success" : "failed",
-        duration_ms:  event.durationMs ?? (session ? Date.now() - session.startedAt : undefined),
+        duration_ms:  durationMs,
         total_tokens: totalTokens || undefined,
         tool_calls:   run?.toolCalls,
         error:        event.error?.slice(0, 200),
@@ -549,7 +567,7 @@ const plugin = {
         trace_id:            session?.traceId ?? randomUUID(),
         agent_id:            agentId,
         status:              event.success ? "success" : "failed",
-        duration_ms:         event.durationMs ?? (session ? Date.now() - session.startedAt : undefined),
+        duration_ms:         durationMs,
         model:               run?.model,
         model_provider:      run?.provider,
         input_tokens:        run?.inputTokens      ?? 0,

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "agentmetrics-openclaw",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "type": "module",
   "description": "AgentMetrics observability plugin for OpenClaw agents",
   "license": "MIT",
   "homepage": "https://agentmetrics.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/andausman/agentmetrics.git"
+    "url": "git+https://github.com/andalabx/agentmetrics-sdk.git"
   },
   "keywords": ["openclaw", "agentmetrics", "observability", "ai-agents", "monitoring"],
   "peerDependencies": {