deepclaw-openclaw 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+## 0.1.0 - Public release candidate
+
+- Initial OpenClaw plugin package metadata.
+- DeepClaw plugin manifest.
+- Runtime service for `llm_output` and `session_end` telemetry.
+- Provider-aware pricing table with cache and reasoning token support.
+- TypeScript validation, Vitest tests, and package dry-run workflow.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Digitizers
+
+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,134 @@
+# DeepClaw OpenClaw Plugin
+
+[![CI](https://github.com/Digitizers/deepclaw-openclaw/actions/workflows/ci.yml/badge.svg)](https://github.com/Digitizers/deepclaw-openclaw/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![OpenClaw Plugin](https://img.shields.io/badge/OpenClaw-plugin-111827.svg)](https://github.com/Digitizers/deepclaw-openclaw)
+[![Category: Observability](https://img.shields.io/badge/category-observability-7c3aed.svg)](https://github.com/Digitizers/deepclaw-openclaw)
+
+**DeepClaw for OpenClaw** streams LLM usage telemetry from OpenClaw into DeepClaw: model, provider, input/output tokens, cache reads/writes, reasoning tokens, and calculated cost breakdowns.
+
+It is built for teams that run multi-provider AI agents and need to know, in near real time, where LLM spend is going.
+
+## Highlights
+
+- **Real-time telemetry** from OpenClaw `llm_output` hooks.
+- **Per-session batching** with periodic flush and final `session_end` flush.
+- **Token-level breakdowns**: input, output, cache read, cache write, reasoning/thinking tokens.
+- **Cost attribution** using a maintained pricing table with explicit `costSource` metadata.
+- **Provider-aware pricing** for Gemini, OpenAI, Anthropic, DeepSeek, and xAI models.
+- **Safe by default**: disabled until configured with an explicit sync token.
+- **Small package surface**: only runtime files, plugin manifest, README, license, changelog, and security policy are published.
+
+## Why this plugin exists
+
+Agent cost tracking often breaks around preview models, cache tokens, reasoning tokens, or provider-specific usage fields. The result is usually either `$0` cost, inflated estimates, or numbers that cannot be audited later.
+
+This plugin captures the raw usage shape exposed by OpenClaw, normalizes the important fields, calculates a structured cost breakdown, and sends it to DeepClaw for long-term analysis.
+
+## Installation
+
+```bash
+npm install deepclaw-openclaw
+```
+
+For local development or manual installation:
+
+```bash
+git clone https://github.com/Digitizers/deepclaw-openclaw.git
+cd deepclaw-openclaw
+npm install
+npm run ci
+```
+
+## Configuration
+
+Configure the plugin in your OpenClaw agent config:
+
+```yaml
+plugins:
+  deepclaw-openclaw:
+    enabled: true
+    syncToken: "YOUR_DEEPCLAW_SYNC_TOKEN"
+    instanceId: "prod-agent-01"
+    apiUrl: "https://app.deep-claw.com"
+    flushIntervalMs: 5000
+    debug: false
+```
+
+Environment variables are also supported:
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `DEEPCLAW_SYNC_TOKEN` | Yes | Bearer token used to authenticate with DeepClaw. |
+| `DEEPCLAW_INSTANCE_ID` | Recommended | Stable identifier for this OpenClaw runtime. Defaults to `default`. |
+| `DEEPCLAW_API_URL` | No | DeepClaw base URL. Defaults to `https://app.deep-claw.com`. |
+
+## Data flow
+
+| OpenClaw hook | What happens |
+| --- | --- |
+| `llm_output` | Capture provider, model, usage counters, cache counters, reasoning tokens, and calculated cost. |
+| Periodic timer | Flush accumulated records every `flushIntervalMs` milliseconds. |
+| `session_end` | Flush final session data and clear the local accumulator. |
+
+Payloads are sent to:
+
+```text
+POST /api/sync/session
+Authorization: Bearer <syncToken>
+```
+
+## Cost source semantics
+
+Each LLM record includes `costSource`:
+
+| Value | Meaning |
+| --- | --- |
+| `table` | Cost was calculated using the plugin's pricing table. |
+| `unknown` | No supported pricing entry was found; cost is sent as `0` so DeepClaw can estimate or flag it. |
+
+> Note: usage counters come from OpenClaw/provider response metadata. Dollar cost is calculated locally by this plugin unless OpenClaw adds a trusted provider-cost field in a future hook shape.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm pack --dry-run
+```
+
+Useful scripts:
+
+| Script | Purpose |
+| --- | --- |
+| `npm run typecheck` | Strict TypeScript validation. |
+| `npm test` | Run Vitest tests. |
+| `npm run ci` | Typecheck, test, and dry-run package contents. |
+| `npm run smoke` | Run plugin smoke tests. |
+
+## Published package contents
+
+The package is intentionally narrow:
+
+- `index.ts`
+- `src/config.ts`
+- `src/pricing.ts`
+- `src/service.ts`
+- `openclaw.plugin.json`
+- `README.md`
+- `LICENSE`
+- `SECURITY.md`
+- `CHANGELOG.md`
+
+## Security
+
+Do not commit sync tokens or OpenClaw runtime state. See [SECURITY.md](SECURITY.md) for reporting and handling guidance.
+
+## Status
+
+`0.1.0` is an initial public release candidate. APIs may still evolve with OpenClaw plugin hook changes.
+
+## License
+
+MIT © Ben Kalsky / Digitizers.

package/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are handled on the latest `main` branch until the first stable release line is established.
+
+## Reporting a Vulnerability
+
+Please do **not** open public GitHub issues for secrets, authentication bypasses, or data exposure reports.
+
+Report privately via one of these channels:
+
+- GitHub Security Advisory: https://github.com/Digitizers/deepclaw-openclaw/security/advisories/new
+- Email: ben@digitizer.co.il
+
+Please include:
+
+- Affected version or commit SHA
+- Reproduction steps
+- Expected vs. actual behavior
+- Any relevant logs with secrets redacted
+
+## Secret Handling
+
+This plugin uses a DeepClaw sync token for outbound telemetry. Never commit:
+
+- `DEEPCLAW_SYNC_TOKEN`
+- `.env` files
+- OpenClaw runtime config containing credentials
+- Session dumps or raw provider responses that may include user data

package/index.ts

@@ -0,0 +1,26 @@
+// DeepClaw OpenClaw Plugin — real-time LLM cost & usage tracking
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { createDeepClawService } from "./src/service.js";
+import { parseDeepClawConfig } from "./src/config.js";
+
+const plugin = {
+  id: "deepclaw-openclaw",
+  name: "DeepClaw",
+  description: "Export real-time LLM cost & usage data to DeepClaw analytics",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    const config = parseDeepClawConfig(api.pluginConfig);
+    if (!config.enabled || !config.syncToken) {
+      api.logger.info(
+        "[deepclaw] plugin loaded but disabled (set enabled=true and syncToken in config)"
+      );
+      return;
+    }
+    const service = createDeepClawService(api, config);
+    service.registerHooks();
+    api.logger.info(`[deepclaw] started — tracking to ${config.apiUrl}`);
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,47 @@
+{
+  "id": "deepclaw-openclaw",
+  "name": "DeepClaw",
+  "description": "Export real-time LLM cost & usage data to DeepClaw analytics",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": { "type": "boolean" },
+      "apiUrl": { "type": "string" },
+      "syncToken": { "type": "string" },
+      "instanceId": { "type": "string" },
+      "flushIntervalMs": { "type": "number" },
+      "debug": { "type": "boolean" }
+    }
+  },
+  "uiHints": {
+    "enabled": {
+      "label": "Enabled",
+      "help": "Enable DeepClaw cost tracking."
+    },
+    "apiUrl": {
+      "label": "DeepClaw API URL",
+      "placeholder": "https://deepclaw.app",
+      "help": "Base URL of your DeepClaw instance."
+    },
+    "syncToken": {
+      "label": "Sync Token",
+      "sensitive": true,
+      "help": "Token from DeepClaw → Settings → API."
+    },
+    "instanceId": {
+      "label": "Instance ID",
+      "placeholder": "srv1421692",
+      "help": "Identifies this OpenClaw instance in DeepClaw."
+    },
+    "flushIntervalMs": {
+      "label": "Flush Interval (ms)",
+      "placeholder": "5000",
+      "help": "How often to batch-send accumulated usage. Default: 5000."
+    },
+    "debug": {
+      "label": "Debug Logging",
+      "help": "Log each LLM event to console."
+    }
+  }
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "deepclaw-openclaw",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "DeepClaw observability plugin for OpenClaw — real-time LLM usage, token, cache, reasoning, and cost telemetry.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Digitizers/deepclaw-openclaw.git"
+  },
+  "homepage": "https://github.com/Digitizers/deepclaw-openclaw#readme",
+  "bugs": {
+    "url": "https://github.com/Digitizers/deepclaw-openclaw/issues"
+  },
+  "author": "Ben Kalsky <ben@digitizer.co.il> (https://digitizer.co.il)",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0",
+    "npm": ">=10"
+  },
+  "scripts": {
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "smoke": "vitest run src/**/*.test.ts",
+    "ci": "npm run typecheck && npm test && npm pack --dry-run",
+    "prepack": "npm run typecheck && npm test"
+  },
+  "keywords": [
+    "ai-gateway",
+    "ai-observability",
+    "analytics",
+    "cache-tokens",
+    "cost-tracking",
+    "deepclaw",
+    "llm-analytics",
+    "llm-costs",
+    "llm-observability",
+    "monitoring",
+    "openclaw",
+    "openclaw-extension",
+    "openclaw-plugin",
+    "reasoning-tokens",
+    "token-usage"
+  ],
+  "dependencies": {},
+  "peerDependencies": {
+    "openclaw": ">=2026.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.5",
+    "openclaw": "^2026.4.24"
+  },
+  "files": [
+    "index.ts",
+    "src/config.ts",
+    "src/pricing.ts",
+    "src/service.ts",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "openclaw": {
+    "type": "plugin",
+    "category": "observability",
+    "tags": [
+      "deepclaw",
+      "cost-tracking",
+      "tokens",
+      "llm-observability",
+      "monitoring"
+    ],
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/config.ts

@@ -0,0 +1,22 @@
+export interface DeepClawConfig {
+  enabled: boolean;
+  apiUrl: string;
+  syncToken: string;
+  instanceId: string;
+  flushIntervalMs: number;
+  debug: boolean;
+}
+
+export function parseDeepClawConfig(raw: unknown): DeepClawConfig {
+  const cfg = (raw ?? {}) as Record<string, unknown>;
+  return {
+    enabled: cfg["enabled"] !== false && cfg["enabled"] !== undefined
+      ? Boolean(cfg["enabled"])
+      : false,
+    apiUrl: String(cfg["apiUrl"] ?? process.env["DEEPCLAW_API_URL"] ?? "https://app.deep-claw.com"),
+    syncToken: String(cfg["syncToken"] ?? process.env["DEEPCLAW_SYNC_TOKEN"] ?? ""),
+    instanceId: String(cfg["instanceId"] ?? process.env["DEEPCLAW_INSTANCE_ID"] ?? "default"),
+    flushIntervalMs: Number(cfg["flushIntervalMs"] ?? 5000),
+    debug: Boolean(cfg["debug"] ?? false),
+  };
+}

package/src/pricing.ts

@@ -0,0 +1,190 @@
+/**
+ * LLM pricing table — cost per 1M tokens in USD.
+ * Source: official provider pricing pages (updated 2025-04).
+ *
+ * For Gemini: step-function tiered pricing (NOT graduated).
+ * If promptTokenCount exceeds the threshold, ALL tokens are billed at the higher rate.
+ */
+
+export interface ModelPricing {
+  inputPerM: number;
+  outputPerM: number;
+  cacheReadPerM?: number;
+  cacheWritePerM?: number;
+  /** If set, all tokens are billed at higher rates when promptTokens > this */
+  tierThreshold?: number;
+  inputPerMAboveTier?: number;
+  outputPerMAboveTier?: number;
+  cacheReadPerMAboveTier?: number;
+  /** Separate rate for thinking tokens (e.g. Gemini 2.5) */
+  thinkingOutputPerM?: number;
+}
+
+const PRICING: Record<string, ModelPricing> = {
+  // ── Gemini ───────────────────────────────────────────────────────────────
+  "gemini-2.5-flash": {
+    inputPerM: 0.15,
+    outputPerM: 0.60,
+    cacheReadPerM: 0.0375,
+    cacheWritePerM: 1.00,
+    thinkingOutputPerM: 3.50,
+    tierThreshold: 200_000,
+    inputPerMAboveTier: 0.30,
+    outputPerMAboveTier: 1.20,
+    cacheReadPerMAboveTier: 0.075,
+  },
+  "gemini-2.5-pro": {
+    inputPerM: 1.25,
+    outputPerM: 10.00,
+    cacheReadPerM: 0.31,
+    tierThreshold: 200_000,
+    inputPerMAboveTier: 2.50,
+    outputPerMAboveTier: 15.00,
+    cacheReadPerMAboveTier: 0.63,
+  },
+  "gemini-2.0-flash": {
+    inputPerM: 0.10,
+    outputPerM: 0.40,
+    cacheReadPerM: 0.025,
+  },
+  "gemini-1.5-pro": {
+    inputPerM: 1.25,
+    outputPerM: 5.00,
+    cacheReadPerM: 0.3125,
+    tierThreshold: 128_000,
+    inputPerMAboveTier: 2.50,
+    outputPerMAboveTier: 10.00,
+    cacheReadPerMAboveTier: 0.625,
+  },
+  "gemini-1.5-flash": {
+    inputPerM: 0.075,
+    outputPerM: 0.30,
+    cacheReadPerM: 0.01875,
+    tierThreshold: 128_000,
+    inputPerMAboveTier: 0.15,
+    outputPerMAboveTier: 0.60,
+    cacheReadPerMAboveTier: 0.0375,
+  },
+  // ── OpenAI ───────────────────────────────────────────────────────────────
+  "gpt-4o": { inputPerM: 2.50, outputPerM: 10.00, cacheReadPerM: 1.25 },
+  "gpt-4o-mini": { inputPerM: 0.15, outputPerM: 0.60, cacheReadPerM: 0.075 },
+  "gpt-4.1": { inputPerM: 2.00, outputPerM: 8.00, cacheReadPerM: 0.50 },
+  "gpt-4.1-mini": { inputPerM: 0.40, outputPerM: 1.60, cacheReadPerM: 0.10 },
+  "gpt-5": { inputPerM: 10.00, outputPerM: 40.00, cacheReadPerM: 2.50 },
+  "gpt-5.4": { inputPerM: 10.00, outputPerM: 40.00, cacheReadPerM: 2.50 },
+  "gpt-5.4-mini": { inputPerM: 0.40, outputPerM: 1.60, cacheReadPerM: 0.10 },
+  "o3": { inputPerM: 10.00, outputPerM: 40.00, cacheReadPerM: 2.50 },
+  "o4-mini": { inputPerM: 1.10, outputPerM: 4.40, cacheReadPerM: 0.275 },
+  // ── Anthropic ────────────────────────────────────────────────────────────
+  "claude-opus-4": { inputPerM: 15.00, outputPerM: 75.00, cacheReadPerM: 1.50, cacheWritePerM: 18.75 },
+  "claude-opus-4-5": { inputPerM: 15.00, outputPerM: 75.00, cacheReadPerM: 1.50, cacheWritePerM: 18.75 },
+  "claude-opus-4-6": { inputPerM: 15.00, outputPerM: 75.00, cacheReadPerM: 1.50, cacheWritePerM: 18.75 },
+  "claude-sonnet-4": { inputPerM: 3.00, outputPerM: 15.00, cacheReadPerM: 0.30, cacheWritePerM: 3.75 },
+  "claude-sonnet-4-5": { inputPerM: 3.00, outputPerM: 15.00, cacheReadPerM: 0.30, cacheWritePerM: 3.75 },
+  "claude-sonnet-4-6": { inputPerM: 3.00, outputPerM: 15.00, cacheReadPerM: 0.30, cacheWritePerM: 3.75 },
+  "claude-haiku-3-5": { inputPerM: 0.80, outputPerM: 4.00, cacheReadPerM: 0.08, cacheWritePerM: 1.00 },
+  // ── DeepSeek ─────────────────────────────────────────────────────────────
+  "deepseek-chat": { inputPerM: 0.27, outputPerM: 1.10, cacheReadPerM: 0.07 },
+  "deepseek-reasoner": { inputPerM: 0.55, outputPerM: 2.19, cacheReadPerM: 0.14 },
+  // ── xAI ──────────────────────────────────────────────────────────────────
+  "grok-3": { inputPerM: 3.00, outputPerM: 15.00 },
+  "grok-3-mini": { inputPerM: 0.30, outputPerM: 0.50 },
+  "grok-2-vision-1212": { inputPerM: 2.00, outputPerM: 10.00 },
+};
+
+/** Normalize model name for lookup (strip provider prefix, version suffixes like -latest) */
+function normalizeModel(raw: string): string {
+  const lower = raw.toLowerCase();
+  // Strip provider prefix (e.g. "google/gemini-2.5-flash" → "gemini-2.5-flash")
+  const slash = lower.lastIndexOf("/");
+  const name = slash >= 0 ? lower.slice(slash + 1) : lower;
+  // Strip common suffixes
+  return name
+    .replace(/-latest$/, "")
+    .replace(/-\d{8}$/, "")   // date suffixes like -20241022
+    .replace(/-exp$/, "")
+    .replace(/-preview$/, "");
+}
+
+export interface CostBreakdown {
+  inputCost: number;
+  outputCost: number;
+  thinkingCost: number;
+  cacheReadCost: number;
+  cacheWriteCost: number;
+  totalCost: number;
+  priceSource: "table" | "unknown";
+  modelKey: string | null;
+}
+
+export function calculateCost(opts: {
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  thinkingTokens?: number;
+}): CostBreakdown {
+  const key = normalizeModel(opts.model);
+
+  // Try exact match, then longest prefix match for dated/preview provider aliases.
+  let modelKey: string | null = PRICING[key] ? key : null;
+  let pricing: ModelPricing | undefined = modelKey ? PRICING[modelKey] : undefined;
+  if (!pricing) {
+    modelKey = Object.keys(PRICING)
+      .filter((k) => key.startsWith(k) || k.startsWith(key))
+      .sort((a, b) => b.length - a.length)[0] ?? null;
+    pricing = modelKey ? PRICING[modelKey] : undefined;
+  }
+
+  if (!pricing) {
+    return {
+      inputCost: 0, outputCost: 0,
+      thinkingCost: 0,
+      cacheReadCost: 0, cacheWriteCost: 0,
+      totalCost: 0,
+      priceSource: "unknown",
+      modelKey: null,
+    };
+  }
+
+  const M = 1_000_000;
+  const totalInput = opts.inputTokens;
+
+  // Gemini step-function tier: if total prompt > threshold, ALL tokens at higher rate
+  const aboveTier = pricing.tierThreshold && totalInput > pricing.tierThreshold;
+  const inputRate = aboveTier ? (pricing.inputPerMAboveTier ?? pricing.inputPerM) : pricing.inputPerM;
+  const outputRate = aboveTier ? (pricing.outputPerMAboveTier ?? pricing.outputPerM) : pricing.outputPerM;
+  const cacheReadRate = aboveTier
+    ? (pricing.cacheReadPerMAboveTier ?? pricing.cacheReadPerM ?? 0)
+    : (pricing.cacheReadPerM ?? 0);
+
+  const cacheReadTokens = opts.cacheReadTokens ?? 0;
+  const cacheWriteTokens = opts.cacheWriteTokens ?? 0;
+  const thinkingTokens = opts.thinkingTokens ?? 0;
+
+  // For cached input: pay cache-read rate instead of full input rate
+  const nonCachedInput = Math.max(0, totalInput - cacheReadTokens);
+  const inputCost = (nonCachedInput / M) * inputRate;
+  const cacheReadCost = (cacheReadTokens / M) * cacheReadRate;
+  const cacheWriteCost = (cacheWriteTokens / M) * (pricing.cacheWritePerM ?? inputRate);
+
+  // Thinking vs normal output (additive — Gemini separates candidatesTokenCount and thoughtsTokenCount)
+  const outputCost = (opts.outputTokens / M) * outputRate;
+  const thinkingCost = pricing.thinkingOutputPerM
+    ? (thinkingTokens / M) * pricing.thinkingOutputPerM
+    : (thinkingTokens / M) * outputRate;
+
+  const totalCost = inputCost + outputCost + thinkingCost + cacheReadCost + cacheWriteCost;
+
+  return {
+    inputCost,
+    outputCost,
+    thinkingCost,
+    cacheReadCost,
+    cacheWriteCost,
+    totalCost,
+    priceSource: "table",
+    modelKey,
+  };
+}

package/src/service.ts

@@ -0,0 +1,202 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { DeepClawConfig } from "./config.js";
+import { calculateCost } from "./pricing.js";
+
+/**
+ * One LLM call record — captured from llm_output hook.
+ * usage.total comes directly from the provider (not estimated).
+ */
+export interface LlmRecord {
+  runId: string;
+  sessionId: string;
+  provider: string;
+  model: string;
+  tokensIn: number;
+  tokensOut: number;
+  cacheRead: number;
+  cacheWrite: number;
+  thinkingTokens: number;  // thinking/reasoning tokens (Gemini thoughtsTokenCount, OpenAI reasoning_tokens)
+  /** Calculated cost in USD */
+  costUsd: number;
+  costSource: "table" | "unknown";
+  /** Per-component breakdown */
+  costBreakdown?: { input: number; output: number; cacheRead: number; cacheWrite: number; thinking: number; };
+  timestamp: number;
+}
+
+/** Aggregated per-session totals */
+interface SessionAccumulator {
+  sessionId: string;
+  records: LlmRecord[];
+  startedAt: number;
+  lastSeenAt: number;
+}
+
+export function createDeepClawService(api: OpenClawPluginApi, config: DeepClawConfig) {
+  const logger = api.logger;
+  const sessions = new Map<string, SessionAccumulator>();
+  let flushTimer: ReturnType<typeof setInterval> | undefined;
+
+  // ─── helpers ────────────────────────────────────────────────────
+
+  function getOrCreateSession(sessionId: string): SessionAccumulator {
+    let acc = sessions.get(sessionId);
+    if (!acc) {
+      acc = { sessionId, records: [], startedAt: Date.now(), lastSeenAt: Date.now() };
+      sessions.set(sessionId, acc);
+    }
+    acc.lastSeenAt = Date.now();
+    return acc;
+  }
+
+  async function postToDeepClaw(path: string, body: unknown): Promise<void> {
+    const url = `${config.apiUrl.replace(/\/$/, "")}${path}`;
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${config.syncToken}`,
+        },
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        logger.warn(`[deepclaw] POST ${path} → ${res.status}: ${await res.text().catch(() => "")}`);
+      }
+    } catch (err) {
+      logger.warn(`[deepclaw] POST ${path} failed: ${String(err)}`);
+    }
+  }
+
+  async function flushSession(sessionId: string, reason: "session_end" | "periodic"): Promise<void> {
+    const acc = sessions.get(sessionId);
+    if (!acc || acc.records.length === 0) return;
+
+    const totalCostUsd = acc.records.reduce((sum, r) => sum + (r.costUsd ?? 0), 0);
+    const totalIn = acc.records.reduce((sum, r) => sum + r.tokensIn, 0);
+    const totalOut = acc.records.reduce((sum, r) => sum + r.tokensOut, 0);
+    const totalCacheRead = acc.records.reduce((sum, r) => sum + r.cacheRead, 0);
+    const totalCacheWrite = acc.records.reduce((sum, r) => sum + r.cacheWrite, 0);
+    const totalThinking = acc.records.reduce((sum, r) => sum + r.thinkingTokens, 0);
+
+    const payload = {
+      instanceId: config.instanceId,
+      sessionId,
+      flushReason: reason,
+      llmCalls: acc.records,
+      summary: {
+        totalCostUsd,
+        costSource: acc.records.some((r) => r.costSource === "table") ? "table" : "unknown",
+        totalTokensIn: totalIn,
+        totalTokensOut: totalOut,
+        totalCacheRead,
+        totalCacheWrite,
+        totalThinkingTokens: totalThinking,
+        callCount: acc.records.length,
+        startedAt: acc.startedAt,
+        lastSeenAt: acc.lastSeenAt,
+      },
+    };
+
+    if (config.debug) {
+      logger.info(`[deepclaw] flushing session ${sessionId}: ${acc.records.length} calls, $${totalCostUsd.toFixed(6)}`);
+    }
+
+    await postToDeepClaw("/api/sync/session", payload);
+
+    if (reason === "session_end") {
+      sessions.delete(sessionId);
+    } else {
+      // Keep session alive but clear records to avoid double-counting
+      acc.records = [];
+    }
+  }
+
+  async function flushAll(reason: "periodic"): Promise<void> {
+    const ids = Array.from(sessions.keys());
+    await Promise.all(ids.map((id) => flushSession(id, reason)));
+  }
+
+  // ─── public ─────────────────────────────────────────────────────
+
+  return {
+    registerHooks() {
+      // Capture actual cost from provider on every LLM completion
+      api.on("llm_output", async (event) => {
+        const tokensIn  = event.usage?.input     ?? 0;
+        const tokensOut = event.usage?.output    ?? 0;
+        const cacheRead = event.usage?.cacheRead ?? 0;
+        const cacheWrite = event.usage?.cacheWrite ?? 0;
+
+        // Try multiple paths — OpenClaw may expose it under different field names
+        const thinkingTokens =
+          (event.usage as any)?.thinking ??
+          (event.usage as any)?.thoughtsTokenCount ??
+          (event.usage as any)?.reasoning ??
+          (event as any)?.rawResponse?.usageMetadata?.thoughtsTokenCount ??
+          0;
+
+        const cost = calculateCost({
+          model: event.model,
+          inputTokens: tokensIn,
+          outputTokens: tokensOut,
+          cacheReadTokens: cacheRead,
+          cacheWriteTokens: cacheWrite,
+          thinkingTokens,
+        });
+
+        const record: LlmRecord = {
+          runId: event.runId,
+          sessionId: event.sessionId,
+          provider: event.provider,
+          model: event.model,
+          tokensIn,
+          tokensOut,
+          cacheRead,
+          cacheWrite,
+          thinkingTokens,
+          costUsd: cost.totalCost,
+          costSource: cost.priceSource,
+          costBreakdown: cost.priceSource === "table" ? {
+            input: cost.inputCost,
+            output: cost.outputCost,
+            cacheRead: cost.cacheReadCost,
+            cacheWrite: cost.cacheWriteCost,
+            thinking: cost.thinkingCost,
+          } : undefined,
+          timestamp: Date.now(),
+        };
+
+        const acc = getOrCreateSession(event.sessionId);
+        acc.records.push(record);
+
+        if (config.debug) {
+          logger.info(
+            `[deepclaw] llm_output session=${event.sessionId} model=${event.model} ` +
+            `in=${tokensIn} out=${tokensOut} cacheRead=${cacheRead} thinking=${thinkingTokens} ` +
+            `cost=$${record.costUsd.toFixed(6)} source=${record.costSource}`
+          );
+        }
+      });
+
+      // Flush & close on session end
+      api.on("session_end", async (event) => {
+        await flushSession(event.sessionId, "session_end");
+      });
+
+      // Start periodic flush timer
+      flushTimer = setInterval(() => {
+        flushAll("periodic").catch((err) => {
+          logger.warn(`[deepclaw] periodic flush error: ${String(err)}`);
+        });
+      }, config.flushIntervalMs);
+    },
+
+    async shutdown() {
+      if (flushTimer) clearInterval(flushTimer);
+      // Final flush of all open sessions
+      const ids = Array.from(sessions.keys());
+      await Promise.all(ids.map((id) => flushSession(id, "session_end")));
+    },
+  };
+}