agentmetrics-openclaw 0.2.3 → 0.3.0

package/README.md

@@ -1,11 +1,9 @@
 # agentmetrics-openclaw
 
-[![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)
+[![npm](https://img.shields.io/npm/v/agentmetrics-openclaw?color=6366f1&label=npm&logo=npm&logoColor=white)](https://www.npmjs.com/package/agentmetrics-openclaw)
+[![License: MIT](https://img.shields.io/badge/license-MIT-6366f1)](../LICENSE)
 
-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.
-
-→ **[agentmetrics.dev/docs/integrations/openclaw](https://agentmetrics.dev/docs/integrations/openclaw)**
+AgentMetrics integration for [OpenClaw](https://openclaw.dev). Install the plugin, point it at your server, and every agent session reports back to your dashboard automatically showing tokens, cost, tools, subagents, context health, and reliability, all without changing your agent code.
 
 ---
 
@@ -13,7 +11,7 @@ Zero-code observability for [OpenClaw](https://openclaw.dev) agents. Install the
 
 - OpenClaw 2026.3.2 or later
 - Node.js 22 or later
-- An AgentMetrics API key — [get one at agentmetrics.dev](https://agentmetrics.dev/signup)
+- A running AgentMetrics server (see the [main README](../../../README.md) for setup)
 
 ---
 
@@ -27,35 +25,60 @@ openclaw plugins install agentmetrics-openclaw
 
 ## Setup
 
-**1. Set your API key**
+**1. Start AgentMetrics** (if not already running)
+
+```bash
+# Docker
+docker compose up
+
+# Or Python CLI
+pip install agentmetrics
+agentmetrics dashboard
+```
+
+**2. Set the server URL** (if not running on localhost)
 
 ```bash
-# macOS / Linux
-echo 'export AGENTMETRICS_API_KEY=am_live_...' >> ~/.bashrc && source ~/.bashrc
+# macOS / Linux, permanent
+echo 'export AGENTMETRICS_BASE_URL=http://your-server:8099' >> ~/.bashrc && source ~/.bashrc
 
 # Windows (PowerShell)
-$Env:AGENTMETRICS_API_KEY = "am_live_..."
+$Env:AGENTMETRICS_BASE_URL = "http://your-server:8099"
 ```
 
-**2. Trust the plugin** (silences the security scan advisory)
+Omit this step if your server runs on `http://localhost:8099` (the default).
+
+**3. Trust the plugin** (silences the security scan advisory)
 
 ```bash
 openclaw config set plugins.allow '["agentmetrics"]'
 ```
 
-**3. Restart the gateway**
+**4. Restart the gateway**
 
 ```bash
 openclaw gateway restart
 ```
 
-**4. Verify**
+**5. Verify**
 
 ```bash
 openclaw plugins list
 # agentmetrics   loaded
 ```
 
+**6. Set your agent name** (recommended)
+
+In your agent's `openclaw.json`:
+
+```json
+{
+  "name": "my-agent"
+}
+```
+
+The `name` field becomes the agent ID in your dashboard. Give each agent a distinct name.
+
 ---
 
 ## What gets tracked
@@ -76,15 +99,15 @@ Every agent session reports automatically:
 
 ## Troubleshooting
 
-**"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.
+**"dangerous code patterns" warning on install**  
+Safe to ignore. The plugin reads `AGENTMETRICS_BASE_URL` and makes network calls to the AgentMetrics API. Add `agentmetrics` to `plugins.allow` to suppress it permanently.
 
-**"manifest id does not match package name" warning**
+**"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`
+**Runs not appearing in the dashboard**  
+1. Verify the plugin loads: `openclaw plugins list`
+2. Check the server is reachable: `openclaw agentmetrics test`
 3. Restart the gateway after any env var change
 4. Confirm your `openclaw.json` has a `name` field
 

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "agentmetrics",
   "name": "AgentMetrics",
-  "description": "360-degree observability for every OpenClaw agent — tokens, tools, latency, cost, subagents, context health, and reliability.",
+  "description": "360-degree observability for every OpenClaw agent - tokens, tools, latency, cost, subagents, context health, and reliability.",
   "configSchema": {
     "type": "object",
     "properties": {
@@ -11,7 +11,55 @@
       },
       "endpoint": {
         "type": "string",
-        "description": "Custom API endpoint (default: https://api.agentmetrics.dev)"
+        "description": "Custom API endpoint (default: http://localhost:8099)"
+      },
+      "enabled": {
+        "type": "boolean",
+        "description": "Master toggle - set to false to disable all telemetry without uninstalling (default: true)",
+        "default": true
+      },
+      "flushIntervalSeconds": {
+        "type": "integer",
+        "description": "How often to flush the event batch to the API in seconds (default: 10)",
+        "default": 10
+      },
+      "maxBatchSize": {
+        "type": "integer",
+        "description": "Maximum number of events per batch request (default: 100)",
+        "default": 100
+      },
+      "maxQueueSize": {
+        "type": "integer",
+        "description": "Maximum number of events to hold in the local queue before dropping (FIFO, default: 10000)",
+        "default": 10000
+      },
+      "retryMaxAttempts": {
+        "type": "integer",
+        "description": "Maximum retry attempts per event batch before moving to dead-letter queue (default: 5)",
+        "default": 5
+      },
+      "redactionMode": {
+        "type": "string",
+        "enum": ["strict", "moderate", "debug"],
+        "description": "Redaction policy: strict = all sensitive fields scrubbed (default); moderate = errors and secrets only; debug = opt-in full detail, auto-expires after 1h",
+        "default": "strict"
+      },
+      "toolNameExport": {
+        "type": "string",
+        "enum": ["allowlist", "blocklist", "hash", "off"],
+        "description": "How tool names are exported: blocklist = export all except redactToolNames (default); allowlist = export only listed; hash = pseudonymise; off = never export",
+        "default": "blocklist"
+      },
+      "redactToolNames": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Tool names to always redact regardless of toolNameExport mode (default: [])",
+        "default": []
+      },
+      "compressPayloads": {
+        "type": "boolean",
+        "description": "Gzip-compress batch payloads before sending (requires server-side Content-Encoding: gzip support, default: false)",
+        "default": false
       }
     },
     "additionalProperties": false

package/package.json

@@ -1,26 +1,53 @@
 {
   "name": "agentmetrics-openclaw",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "type": "module",
   "description": "AgentMetrics observability plugin for OpenClaw agents",
   "license": "MIT",
-  "homepage": "https://agentmetrics.dev",
+  "homepage": "https://github.com/andalabx/agentmetrics",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/andalabx/agentmetrics-sdk.git"
+    "url": "git+https://github.com/andalabx/agentmetrics.git"
   },
-  "keywords": ["openclaw", "agentmetrics", "observability", "ai-agents", "monitoring"],
-  "peerDependencies": {
-    "openclaw": ">=2026.3.2"
+  "keywords": [
+    "openclaw",
+    "agentmetrics",
+    "observability",
+    "ai-agents",
+    "monitoring"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
   },
   "openclaw": {
-    "extensions": ["./index.ts"]
+    "extensions": [
+      "./dist/index.js"
+    ]
   },
   "files": [
-    "index.ts",
+    "dist",
     "openclaw.plugin.json",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.2"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
   "engines": {
     "node": ">=22"
   }

package/index.ts

@@ -1,604 +0,0 @@
-import { randomUUID } from "crypto";
-
-// 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 = {
-  runId?:           string;
-  agentId?:         string;
-  sessionKey?:      string;
-  sessionId?:       string;
-  modelId?:         string;
-  modelProviderId?: string;
-};
-
-type SessionContext = {
-  sessionId:   string;
-  sessionKey?: string;
-  agentId?:    string;
-};
-
-type SessionStartEvent = {
-  sessionId:    string;
-  sessionKey?:  string;
-  resumedFrom?: string;
-};
-
-type SessionEndEvent = {
-  sessionId:           string;
-  sessionKey?:         string;
-  durationMs?:         number;
-  messageCount:        number;
-  reason?:             string;
-  transcriptArchived?: boolean;
-};
-
-type LlmInputEvent = {
-  runId:           string;
-  sessionId:       string;
-  provider:        string;
-  model:           string;
-  systemPrompt?:   string;
-  prompt:          string;
-  historyMessages: unknown[];
-  imagesCount:     number;
-};
-
-type LlmOutputEvent = {
-  runId:          string;
-  sessionId:      string;
-  provider:       string;
-  model:          string;
-  assistantTexts: string[];
-  usage?: {
-    input?:      number;
-    output?:     number;
-    cacheRead?:  number;
-    cacheWrite?: number;
-    total?:      number;
-  };
-};
-
-type BeforeToolCallEvent = {
-  toolName:    string;
-  params:      Record<string, unknown>;
-  runId?:      string;
-  toolCallId?: string;
-};
-
-type AfterToolCallEvent = {
-  toolName:    string;
-  params:      Record<string, unknown>;
-  runId?:      string;
-  toolCallId?: string;
-  result?:     unknown;
-  error?:      string;
-  durationMs?: number;
-};
-
-type ToolContext = {
-  agentId?:    string;
-  sessionKey?: string;
-  sessionId?:  string;
-  runId?:      string;
-  toolName:    string;
-  toolCallId?: string;
-};
-
-type AgentEndEvent = {
-  messages:    unknown[];
-  success:     boolean;
-  error?:      string;
-  durationMs?: number;
-};
-
-type BeforeAgentStartEvent = {
-  agentId?:    string;
-  sessionKey?: string;
-  sessionId?:  string;
-};
-
-type SubagentSpawningEvent = {
-  childSessionKey: string;
-  agentId:         string;
-  label?:          string;
-  mode:            "run" | "session";
-  threadRequested: boolean;
-};
-
-type SubagentEndedEvent = {
-  targetSessionKey: string;
-  reason:           string;
-  runId?:           string;
-  outcome?:         "ok" | "error" | "timeout" | "killed" | "reset" | "deleted";
-  error?:           string;
-};
-
-type SubagentContext = {
-  runId?:               string;
-  childSessionKey?:     string;
-  requesterSessionKey?: string;
-};
-
-type CompactionEvent = {
-  messageCount:     number;
-  compactingCount?: number;
-  tokenCount?:      number;
-  sessionFile?:     string;
-};
-
-type ResetEvent = {
-  sessionFile?: string;
-  reason?:      string;
-};
-
-type GatewayStartEvent = { port: number };
-type GatewayStopEvent  = { reason?: string };
-type GatewayContext    = { port?: number };
-
-// ─── Per-session and per-run state ────────────────────────────────────────────
-
-interface SessionMeta {
-  traceId:     string;
-  agentId:     string;
-  startedAt:   number;
-  compactions: number;
-  resets:      number;
-}
-
-interface RunMeta {
-  inputTokens:      number;
-  outputTokens:     number;
-  cacheReadTokens:  number;
-  cacheWriteTokens: number;
-  llmCalls:         number;
-  imagesCount:      number;
-  toolCalls:        number;
-  toolErrors:       number;
-  toolNames:        Set<string>;
-  subagentsSpawned: number;
-  subagentErrors:   number;
-  model?:           string;
-  provider?:        string;
-  sessionKey?:      string;
-  startedAt:        number; // run-level start time for accurate duration
-}
-
-const sessions = new Map<string, SessionMeta>();
-const runs     = new Map<string, RunMeta>();
-
-// ─── HTTP helpers ─────────────────────────────────────────────────────────────
-
-/** Send a completed run summary to /v1/events (persisted to DB). */
-async function send(payload: Record<string, unknown>): Promise<void> {
-  if (!API_KEY) return;
-  try {
-    await fetch(`${BASE_URL}/v1/events`, {
-      method: "POST",
-      headers: {
-        "Content-Type":  "application/json",
-        "Authorization": `Bearer ${API_KEY}`,
-      },
-      body: JSON.stringify(payload),
-    });
-  } catch {
-    // Never crash the agent on observability failure
-  }
-}
-
-/**
- * Send a real-time intermediate event to /v1/activity (in-memory, streamed
- * to dashboard via SSE). Fire-and-forget — no retry, no crash on failure.
- */
-function sendActivity(
-  type:        string,
-  agentId:     string,
-  sessionKey:  string | undefined,
-  runId:       string | undefined,
-  data?:       Record<string, unknown>,
-): void {
-  if (!API_KEY) return;
-  const payload = JSON.stringify({
-    type,
-    agent_id:    agentId,
-    session_key: sessionKey,
-    run_id:      runId,
-    ts:          Date.now(),
-    data:        data ?? null,
-  });
-  fetch(`${BASE_URL}/v1/activity`, {
-    method: "POST",
-    headers: {
-      "Content-Type":  "application/json",
-      "Authorization": `Bearer ${API_KEY}`,
-    },
-    body: payload,
-  }).catch(() => {});
-}
-
-function emptyRun(sessionKey?: string): RunMeta {
-  return {
-    inputTokens: 0, outputTokens: 0,
-    cacheReadTokens: 0, cacheWriteTokens: 0,
-    llmCalls: 0, imagesCount: 0,
-    toolCalls: 0, toolErrors: 0, toolNames: new Set(),
-    subagentsSpawned: 0, subagentErrors: 0,
-    sessionKey,
-    startedAt: Date.now(),
-  };
-}
-
-// ─── Plugin ───────────────────────────────────────────────────────────────────
-
-const plugin = {
-  id:          "agentmetrics",
-  name:        "AgentMetrics",
-  description: "360-degree observability for every OpenClaw agent — real-time streaming, tokens, tools, latency, cost, subagents, and reliability.",
-  configSchema: {
-    type: "object",
-    properties: {
-      apiKey: {
-        type:        "string",
-        description: "AgentMetrics API key (overrides AGENTMETRICS_API_KEY env var)",
-      },
-      endpoint: {
-        type:        "string",
-        description: "Custom API endpoint (default: https://api.agentmetrics.dev)",
-      },
-    },
-    additionalProperties: false,
-  } as const,
-
-  register(api: PluginApi) {
-    // Config: pluginConfig > env vars
-    API_KEY  = (api.pluginConfig?.apiKey  as string | undefined) ?? process.env.AGENTMETRICS_API_KEY;
-    BASE_URL = (
-      (api.pluginConfig?.endpoint as string | undefined) ??
-      process.env.AGENTMETRICS_URL ??
-      "https://api.agentmetrics.dev"
-    ).replace(/\/$/, "");
-
-    // Auto-enable when a key is available (env var or plugin config)
-    if (typeof api.registerAutoEnableProbe === "function") {
-      api.registerAutoEnableProbe(() => !!API_KEY);
-    }
-
-    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") {
-      api.registerCli({
-        name:        "agentmetrics",
-        description: "AgentMetrics observability commands",
-        commands: [
-          {
-            name:        "status",
-            description: "Show current AgentMetrics plugin status",
-            handler() {
-              const keyPreview = API_KEY
-                ? `${API_KEY.slice(0, 8)}...${API_KEY.slice(-4)}`
-                : "(not set)";
-              console.log("AgentMetrics — active");
-              console.log(`  API key  : ${keyPreview}`);
-              console.log(`  Endpoint : ${BASE_URL}`);
-              console.log(`  Sessions : ${sessions.size} tracked`);
-              console.log(`  Runs     : ${runs.size} in flight`);
-            },
-          },
-        ],
-      });
-    }
-
-    // ── 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,
-      });
-    });
-
-    // ── gateway_stop ──────────────────────────────────────────────────────
-    api.on("gateway_stop", (event: GatewayStopEvent, _ctx: GatewayContext) => {
-      sendActivity("gateway_stop", "openclaw-gateway", undefined, undefined, {
-        reason: event.reason,
-      });
-    });
-
-    // ── session_start ─────────────────────────────────────────────────────
-    api.on("session_start", (event: SessionStartEvent, ctx: SessionContext) => {
-      const key = event.sessionKey ?? event.sessionId;
-      if (!key || sessions.has(key)) return;
-
-      sessions.set(key, {
-        traceId:     randomUUID(),
-        agentId:     ctx.agentId ?? "openclaw-agent",
-        startedAt:   Date.now(),
-        compactions: 0,
-        resets:      0,
-      });
-    });
-
-    // ── before_agent_start ────────────────────────────────────────────────
-    // Fires at the start of each run. Sends run_start for real-time UI.
-    api.on("before_agent_start", (event: BeforeAgentStartEvent, ctx: AgentContext) => {
-      const sessionKey = ctx.sessionKey ?? ctx.sessionId;
-      const agentId    = ctx.agentId ?? "openclaw-agent";
-      const runId      = ctx.runId;
-
-      if (!runId && !sessionKey) return;
-
-      sendActivity("run_start", agentId, sessionKey, runId, {
-        model:    ctx.modelId,
-        provider: ctx.modelProviderId,
-      });
-    });
-
-    // ── llm_input ─────────────────────────────────────────────────────────
-    // Fires before each LLM call. Sends llm_start for real-time "thinking"
-    // indicator. Also accumulates LLM call count and image count.
-    api.on("llm_input", (event: LlmInputEvent, ctx: AgentContext) => {
-      const { runId } = event;
-      if (!runId) return;
-
-      const sessionKey = ctx.sessionKey ?? ctx.sessionId ?? event.sessionId;
-      const agentId    = ctx.agentId ?? sessions.get(sessionKey ?? "")?.agentId ?? "openclaw-agent";
-      const run = runs.get(runId) ?? emptyRun(sessionKey);
-
-      run.llmCalls    += 1;
-      run.imagesCount += event.imagesCount ?? 0;
-      if (!run.model    && event.model)    run.model    = event.model;
-      if (!run.provider && event.provider) run.provider = event.provider;
-      if (!run.sessionKey) run.sessionKey = sessionKey;
-      runs.set(runId, run);
-
-      sendActivity("llm_start", agentId, sessionKey, runId, {
-        model:    event.model,
-        provider: event.provider,
-        images:   event.imagesCount,
-        history:  event.historyMessages?.length ?? 0,
-      });
-    });
-
-    // ── llm_output ────────────────────────────────────────────────────────
-    // Fires after each LLM response. Accumulates tokens and sends llm_end
-    // so the dashboard can show token counts updating in real time.
-    api.on("llm_output", (event: LlmOutputEvent, ctx: AgentContext) => {
-      const { runId } = event;
-      if (!runId) return;
-
-      const sessionKey = ctx.sessionKey ?? ctx.sessionId ?? event.sessionId;
-      const agentId    = ctx.agentId ?? sessions.get(sessionKey ?? "")?.agentId ?? "openclaw-agent";
-      const run = runs.get(runId) ?? emptyRun(sessionKey);
-
-      if (event.usage) {
-        run.inputTokens      += event.usage.input      ?? 0;
-        run.outputTokens     += event.usage.output     ?? 0;
-        run.cacheReadTokens  += event.usage.cacheRead  ?? 0;
-        run.cacheWriteTokens += event.usage.cacheWrite ?? 0;
-      }
-      if (event.model)    run.model    = event.model;
-      if (event.provider) run.provider = event.provider;
-      if (!run.sessionKey) run.sessionKey = sessionKey;
-      runs.set(runId, run);
-
-      sendActivity("llm_end", agentId, sessionKey, runId, {
-        model:         event.model,
-        provider:      event.provider,
-        input_tokens:  event.usage?.input,
-        output_tokens: event.usage?.output,
-        cache_read:    event.usage?.cacheRead,
-        cache_write:   event.usage?.cacheWrite,
-        total_input:   run.inputTokens,
-        total_output:  run.outputTokens,
-      });
-    });
-
-    // ── before_tool_call ──────────────────────────────────────────────────
-    // Fires before each tool execution. Sends tool_start immediately so
-    // the live visualizer shows tool activity in real time.
-    api.on("before_tool_call", (event: BeforeToolCallEvent, ctx: ToolContext) => {
-      const runId      = event.runId ?? ctx.runId;
-      const sessionKey = ctx.sessionKey ?? ctx.sessionId;
-      const agentId    = ctx.agentId ?? sessions.get(sessionKey ?? "")?.agentId ?? "openclaw-agent";
-
-      sendActivity("tool_start", agentId, sessionKey, runId, {
-        tool_name: event.toolName,
-      });
-    });
-
-    // ── after_tool_call ───────────────────────────────────────────────────
-    // Fires after every tool execution. Counts calls/errors and sends
-    // tool_end with outcome and duration.
-    api.on("after_tool_call", (event: AfterToolCallEvent, ctx: ToolContext) => {
-      const runId      = event.runId ?? ctx.runId;
-      const sessionKey = ctx.sessionKey ?? ctx.sessionId;
-      const agentId    = ctx.agentId ?? sessions.get(sessionKey ?? "")?.agentId ?? "openclaw-agent";
-
-      if (runId) {
-        const run = runs.get(runId) ?? emptyRun(sessionKey);
-        run.toolCalls += 1;
-        if (event.error) run.toolErrors += 1;
-        run.toolNames.add(event.toolName);
-        if (!run.sessionKey) run.sessionKey = sessionKey;
-        runs.set(runId, run);
-      }
-
-      sendActivity("tool_end", agentId, sessionKey, runId, {
-        tool_name:   event.toolName,
-        duration_ms: event.durationMs,
-        error:       event.error?.slice(0, 200),
-      });
-    });
-
-    // ── subagent_spawning ─────────────────────────────────────────────────
-    api.on("subagent_spawning", (event: SubagentSpawningEvent, ctx: SubagentContext) => {
-      const runId      = ctx.runId;
-      const sessionKey = ctx.requesterSessionKey;
-      const agentId    = sessions.get(sessionKey ?? "")?.agentId ?? "openclaw-agent";
-
-      if (runId) {
-        const run = runs.get(runId);
-        if (run) {
-          run.subagentsSpawned += 1;
-          runs.set(runId, run);
-        }
-      }
-
-      sendActivity("subagent_start", agentId, sessionKey, runId, {
-        child_agent_id:    event.agentId,
-        child_session_key: event.childSessionKey,
-        mode:              event.mode,
-        label:             event.label,
-      });
-    });
-
-    // ── subagent_ended ────────────────────────────────────────────────────
-    api.on("subagent_ended", (event: SubagentEndedEvent, ctx: SubagentContext) => {
-      const runId      = event.runId ?? ctx.runId;
-      const sessionKey = ctx.requesterSessionKey;
-      const agentId    = sessions.get(sessionKey ?? "")?.agentId ?? "openclaw-agent";
-
-      if (runId) {
-        const run = runs.get(runId);
-        if (run && event.outcome && event.outcome !== "ok") {
-          run.subagentErrors += 1;
-          runs.set(runId, run);
-        }
-      }
-
-      sendActivity("subagent_end", agentId, sessionKey, runId, {
-        child_session_key: event.targetSessionKey,
-        outcome:           event.outcome,
-        error:             event.error?.slice(0, 200),
-      });
-    });
-
-    // ── before_compaction ─────────────────────────────────────────────────
-    api.on("before_compaction", (_event: CompactionEvent, ctx: AgentContext) => {
-      const key     = ctx.sessionKey ?? ctx.sessionId;
-      const agentId = ctx.agentId ?? sessions.get(key ?? "")?.agentId ?? "openclaw-agent";
-      if (!key) return;
-
-      const session = sessions.get(key);
-      if (session) {
-        session.compactions += 1;
-        sessions.set(key, session);
-      }
-
-      sendActivity("compaction", agentId, key, ctx.runId);
-    });
-
-    // ── before_reset ──────────────────────────────────────────────────────
-    api.on("before_reset", (event: ResetEvent, ctx: AgentContext) => {
-      const key     = ctx.sessionKey ?? ctx.sessionId;
-      const agentId = ctx.agentId ?? sessions.get(key ?? "")?.agentId ?? "openclaw-agent";
-      if (!key) return;
-
-      const session = sessions.get(key);
-      if (session) {
-        session.resets += 1;
-        sessions.set(key, session);
-      }
-
-      sendActivity("reset", agentId, key, ctx.runId, { reason: event.reason });
-    });
-
-    // ── agent_end ─────────────────────────────────────────────────────────
-    // Fires when the agent finishes a run. Sends run_end for real-time UI,
-    // then the full persisted event to /v1/events with all accumulated data.
-    api.on("agent_end", (event: AgentEndEvent, ctx: AgentContext) => {
-      const sessionKey = ctx.sessionKey ?? ctx.sessionId;
-      if (!sessionKey) return;
-
-      const session = sessions.get(sessionKey);
-      const run     = ctx.runId ? runs.get(ctx.runId) : undefined;
-      const agentId = ctx.agentId ?? session?.agentId ?? "openclaw-agent";
-
-      if (session) session.agentId = agentId;
-
-      const totalTokens =
-        (run?.inputTokens      ?? 0) +
-        (run?.outputTokens     ?? 0) +
-        (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:  durationMs,
-        total_tokens: totalTokens || undefined,
-        tool_calls:   run?.toolCalls,
-        error:        event.error?.slice(0, 200),
-      });
-
-      // Persistent: full summary stored in DB
-      send({
-        trace_id:            session?.traceId ?? randomUUID(),
-        agent_id:            agentId,
-        status:              event.success ? "success" : "failed",
-        duration_ms:         durationMs,
-        model:               run?.model,
-        model_provider:      run?.provider,
-        input_tokens:        run?.inputTokens      ?? 0,
-        output_tokens:       run?.outputTokens     ?? 0,
-        cache_read_tokens:   run?.cacheReadTokens  ?? 0,
-        cache_write_tokens:  run?.cacheWriteTokens ?? 0,
-        total_tokens:        totalTokens || undefined,
-        tool_calls:          run?.toolCalls  ?? 0,
-        tool_errors:         run?.toolErrors ?? 0,
-        step_count:          event.messages?.length,
-        ...(event.error ? { error: event.error.slice(0, 500) } : {}),
-        metadata: {
-          llm_calls:         run?.llmCalls         ?? 0,
-          images_count:      run?.imagesCount       ?? 0,
-          subagents_spawned: run?.subagentsSpawned  ?? 0,
-          subagent_errors:   run?.subagentErrors    ?? 0,
-          compactions:       session?.compactions   ?? 0,
-          resets:            session?.resets        ?? 0,
-          tool_names:        run ? [...run.toolNames] : [],
-        },
-      });
-
-      if (ctx.runId) runs.delete(ctx.runId);
-    });
-
-    // ── session_end ───────────────────────────────────────────────────────
-    api.on("session_end", (event: SessionEndEvent, _ctx: SessionContext) => {
-      const key = event.sessionKey ?? event.sessionId;
-      sessions.delete(key);
-    });
-  },
-};
-
-export default plugin;