deepclaw-openclaw 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented here.
 
+## 0.1.2 - GitHub Packages publishing prep
+
+- Add GitHub Actions workflow support for publishing to npmjs and GitHub Packages.
+- Document the scoped GitHub Packages install path as `@digitizers/deepclaw-openclaw`.
+
 ## 0.1.1 - Metadata cleanup
 
 - Mark `syncToken` as required in the OpenClaw plugin config schema for clearer marketplace/security metadata.

package/README.md

@@ -27,10 +27,24 @@ This plugin captures the raw usage shape exposed by OpenClaw, normalizes the imp
 
 ## Installation
 
+From the public npm registry:
+
 ```bash
 npm install deepclaw-openclaw
 ```
 
+From GitHub Packages, once the scoped mirror package has been published:
+
+```bash
+# .npmrc
+@digitizers:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+
+npm install @digitizers/deepclaw-openclaw
+```
+
+The GitHub Packages build is published as the scoped alias `@digitizers/deepclaw-openclaw`; the canonical npmjs package remains `deepclaw-openclaw` for easier public installation.
+
 For local development or manual installation:
 
 ```bash
@@ -128,7 +142,7 @@ Do not commit sync tokens or OpenClaw runtime state. See [SECURITY.md](SECURITY.
 
 ## Status
 
-`0.1.1` is an initial public release candidate. APIs may still evolve with OpenClaw plugin hook changes.
+`0.1.2` is an initial public release candidate. APIs may still evolve with OpenClaw plugin hook changes.
 
 ## License
 

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk").OpenClawPluginConfigSchema;
+    register(api: OpenClawPluginApi): void;
+};
+export default plugin;

package/dist/index.js

@@ -0,0 +1,20 @@
+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) {
+        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/dist/src/config.d.ts

@@ -0,0 +1,9 @@
+export interface DeepClawConfig {
+    enabled: boolean;
+    apiUrl: string;
+    syncToken: string;
+    instanceId: string;
+    flushIntervalMs: number;
+    debug: boolean;
+}
+export declare function parseDeepClawConfig(raw: unknown): DeepClawConfig;

package/dist/src/config.js

@@ -0,0 +1,13 @@
+export function parseDeepClawConfig(raw) {
+    const cfg = (raw ?? {});
+    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/dist/src/pricing.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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;
+}
+export interface CostBreakdown {
+    inputCost: number;
+    outputCost: number;
+    thinkingCost: number;
+    cacheReadCost: number;
+    cacheWriteCost: number;
+    totalCost: number;
+    priceSource: "table" | "unknown";
+    modelKey: string | null;
+}
+export declare function calculateCost(opts: {
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    thinkingTokens?: number;
+}): CostBreakdown;

package/dist/src/pricing.js

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+const PRICING = {
+    // ── 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) {
+    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 function calculateCost(opts) {
+    const key = normalizeModel(opts.model);
+    // Try exact match, then longest prefix match for dated/preview provider aliases.
+    let modelKey = PRICING[key] ? key : null;
+    let pricing = 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/dist/src/service.d.ts

@@ -0,0 +1,33 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import type { DeepClawConfig } from "./config.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;
+    /** 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;
+}
+export declare function createDeepClawService(api: OpenClawPluginApi, config: DeepClawConfig): {
+    registerHooks(): void;
+    shutdown(): Promise<void>;
+};

package/dist/src/service.js

@@ -0,0 +1,150 @@
+import { calculateCost } from "./pricing.js";
+export function createDeepClawService(api, config) {
+    const logger = api.logger;
+    const sessions = new Map();
+    let flushTimer;
+    // ─── helpers ────────────────────────────────────────────────────
+    function getOrCreateSession(sessionId) {
+        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, body) {
+        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, reason) {
+        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) {
+        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?.thinking ??
+                    event.usage?.thoughtsTokenCount ??
+                    event.usage?.reasoning ??
+                    event?.rawResponse?.usageMetadata?.thoughtsTokenCount ??
+                    0;
+                const cost = calculateCost({
+                    model: event.model,
+                    inputTokens: tokensIn,
+                    outputTokens: tokensOut,
+                    cacheReadTokens: cacheRead,
+                    cacheWriteTokens: cacheWrite,
+                    thinkingTokens,
+                });
+                const record = {
+                    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")));
+        },
+    };
+}

package/openclaw.plugin.json

@@ -2,10 +2,12 @@
   "id": "deepclaw-openclaw",
   "name": "DeepClaw",
   "description": "Export real-time LLM cost & usage data to DeepClaw analytics",
+  "activation": {
+    "onStartup": true
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "required": ["syncToken"],
     "properties": {
       "enabled": { "type": "boolean" },
       "apiUrl": { "type": "string" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepclaw-openclaw",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "license": "MIT",
   "description": "DeepClaw observability plugin for OpenClaw — real-time LLM usage, token, cache, reasoning, and cost telemetry.",
   "repository": {
@@ -18,12 +18,14 @@
     "npm": ">=10"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json",
     "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"
+    "check:clawhub": "node scripts/check-clawhub-version.mjs",
+    "ci": "npm run typecheck && npm test && npm run build && npm pack --dry-run",
+    "prepack": "npm run typecheck && npm test && npm run build"
   },
   "keywords": [
     "ai-gateway",
@@ -54,6 +56,7 @@
     "openclaw": "^2026.4.24"
   },
   "files": [
+    "dist/**",
     "index.ts",
     "src/config.ts",
     "src/pricing.ts",
@@ -73,7 +76,7 @@
       "minGatewayVersion": "2026.3.2"
     },
     "build": {
-      "openclawVersion": "2026.4.24"
+      "openclawVersion": "2026.5.6"
     },
     "tags": [
       "deepclaw",
@@ -84,6 +87,9 @@
     ],
     "extensions": [
       "./index.ts"
+    ],
+    "runtimeExtensions": [
+      "./dist/index.js"
     ]
   },
   "publishConfig": {