@analytix402/openclaw-skill 0.1.0

package/src/index.ts

@@ -0,0 +1,335 @@
+/**
+ * Analytix402 OpenClaw Skill
+ *
+ * Provides AI agent spend tracking, budget enforcement,
+ * and observability for OpenClaw agents.
+ *
+ * Integrates with the Analytix402 platform to give operators
+ * real-time visibility into what their agents are spending.
+ */
+
+import { createClient } from '../../sdk/src/client';
+import type { Analytix402Client } from '../../sdk/src/types';
+
+// ============================================================
+// Configuration
+// ============================================================
+
+const API_KEY = process.env.ANALYTIX402_API_KEY || '';
+const BASE_URL = (process.env.ANALYTIX402_BASE_URL || 'https://analytix402.com').replace(/\/$/, '');
+const AGENT_ID = process.env.ANALYTIX402_AGENT_ID || `openclaw-${Date.now()}`;
+const AGENT_NAME = process.env.ANALYTIX402_AGENT_NAME || 'OpenClaw Agent';
+const DAILY_BUDGET = parseFloat(process.env.ANALYTIX402_DAILY_BUDGET || '0') || 0;
+const PER_CALL_LIMIT = parseFloat(process.env.ANALYTIX402_PER_CALL_LIMIT || '0') || 0;
+const TRACK_LLM = process.env.ANALYTIX402_TRACK_LLM !== 'false';
+
+// ============================================================
+// State
+// ============================================================
+
+let client: Analytix402Client | null = null;
+let sessionSpend = 0;
+let sessionCalls = 0;
+let dailySpend = 0;
+const dailySpendDate = new Date().toISOString().slice(0, 10);
+
+function getClient(): Analytix402Client {
+  if (!client) {
+    if (!API_KEY) {
+      throw new Error(
+        'ANALYTIX402_API_KEY is not set. Add it to your OpenClaw skill config.'
+      );
+    }
+    client = createClient({
+      apiKey: API_KEY,
+      baseUrl: BASE_URL,
+      agentId: AGENT_ID,
+      agentName: AGENT_NAME,
+    });
+  }
+  return client;
+}
+
+// ============================================================
+// API helper (for dashboard queries)
+// ============================================================
+
+async function apiRequest(method: string, path: string, body?: unknown): Promise<unknown> {
+  const url = `${BASE_URL}/api${path}`;
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${API_KEY}`,
+    'X-API-Key': API_KEY,
+  };
+
+  const opts: RequestInit = { method, headers };
+  if (body && method !== 'GET') {
+    opts.body = JSON.stringify(body);
+  }
+
+  const res = await fetch(url, opts);
+  const text = await res.text();
+
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = { raw: text };
+  }
+
+  if (!res.ok) {
+    throw new Error(`Analytix402 API ${res.status}: ${(data as Record<string, string>).error || text}`);
+  }
+
+  return data;
+}
+
+// ============================================================
+// Tool: analytix402_spend_report
+// ============================================================
+
+export async function analytix402_spend_report(): Promise<string> {
+  const c = getClient();
+
+  // Send a heartbeat while we're at it
+  c.heartbeat('healthy', { sessionCalls, sessionSpend });
+
+  try {
+    const overview = await apiRequest('GET', '/agents/overview');
+    const insights = await apiRequest('GET', '/agents/insights');
+
+    return JSON.stringify({
+      session: {
+        totalCalls: sessionCalls,
+        totalSpend: `$${sessionSpend.toFixed(4)}`,
+        dailySpend: `$${dailySpend.toFixed(4)}`,
+        dailyBudget: DAILY_BUDGET > 0 ? `$${DAILY_BUDGET.toFixed(2)}` : 'unlimited',
+        budgetRemaining: DAILY_BUDGET > 0
+          ? `$${(DAILY_BUDGET - dailySpend).toFixed(4)}`
+          : 'unlimited',
+      },
+      platform: overview,
+      insights,
+    }, null, 2);
+  } catch (error) {
+    return JSON.stringify({
+      session: {
+        totalCalls: sessionCalls,
+        totalSpend: `$${sessionSpend.toFixed(4)}`,
+        dailySpend: `$${dailySpend.toFixed(4)}`,
+        dailyBudget: DAILY_BUDGET > 0 ? `$${DAILY_BUDGET.toFixed(2)}` : 'unlimited',
+      },
+      error: error instanceof Error ? error.message : String(error),
+    }, null, 2);
+  }
+}
+
+// ============================================================
+// Tool: analytix402_set_budget
+// ============================================================
+
+export interface SetBudgetParams {
+  daily_limit?: number;
+  per_call_limit?: number;
+}
+
+export function analytix402_set_budget(params: SetBudgetParams): string {
+  const updates: string[] = [];
+
+  if (params.daily_limit !== undefined && params.daily_limit >= 0) {
+    // Update the runtime budget (persists for this session)
+    Object.defineProperty(globalThis, '__ax402_daily_budget', {
+      value: params.daily_limit,
+      writable: true,
+      configurable: true,
+    });
+    updates.push(`Daily budget set to $${params.daily_limit.toFixed(2)}`);
+  }
+
+  if (params.per_call_limit !== undefined && params.per_call_limit >= 0) {
+    Object.defineProperty(globalThis, '__ax402_per_call_limit', {
+      value: params.per_call_limit,
+      writable: true,
+      configurable: true,
+    });
+    updates.push(`Per-call limit set to $${params.per_call_limit.toFixed(2)}`);
+  }
+
+  if (updates.length === 0) {
+    return 'No budget parameters provided. Use daily_limit and/or per_call_limit.';
+  }
+
+  return updates.join('. ') + '.';
+}
+
+// ============================================================
+// Tool: analytix402_check_budget
+// ============================================================
+
+export interface CheckBudgetParams {
+  estimated_cost?: number;
+}
+
+export function analytix402_check_budget(params: CheckBudgetParams): string {
+  const budget = DAILY_BUDGET ||
+    ((globalThis as Record<string, unknown>).__ax402_daily_budget as number) || 0;
+  const callLimit = PER_CALL_LIMIT ||
+    ((globalThis as Record<string, unknown>).__ax402_per_call_limit as number) || 0;
+  const estimated = params.estimated_cost || 0;
+
+  const remaining = budget > 0 ? budget - dailySpend : Infinity;
+  const allowed = (budget === 0 || remaining >= estimated) &&
+                  (callLimit === 0 || estimated <= callLimit);
+
+  return JSON.stringify({
+    allowed,
+    dailyBudget: budget > 0 ? `$${budget.toFixed(2)}` : 'unlimited',
+    dailySpent: `$${dailySpend.toFixed(4)}`,
+    remaining: budget > 0 ? `$${remaining.toFixed(4)}` : 'unlimited',
+    estimatedCost: `$${estimated.toFixed(4)}`,
+    perCallLimit: callLimit > 0 ? `$${callLimit.toFixed(2)}` : 'unlimited',
+    withinPerCallLimit: callLimit === 0 || estimated <= callLimit,
+    withinDailyBudget: budget === 0 || remaining >= estimated,
+  }, null, 2);
+}
+
+// ============================================================
+// Tool: analytix402_flag_purchase
+// ============================================================
+
+export interface FlagPurchaseParams {
+  url: string;
+  reason?: string;
+  estimated_cost?: number;
+}
+
+export function analytix402_flag_purchase(params: FlagPurchaseParams): string {
+  const c = getClient();
+
+  c.track({
+    type: 'request',
+    method: 'FLAG',
+    path: params.url,
+    endpoint: params.url,
+    statusCode: 0,
+    responseTimeMs: 0,
+    timestamp: new Date().toISOString(),
+    agentId: AGENT_ID,
+    metadata: {
+      flagged: true,
+      reason: params.reason || 'Potential duplicate or unnecessary purchase',
+      estimatedCost: params.estimated_cost,
+    },
+  });
+
+  return `Flagged: ${params.url} — ${params.reason || 'potential duplicate purchase'}. This will appear in your Analytix402 dashboard for review.`;
+}
+
+// ============================================================
+// Hooks: auto-track LLM and API calls
+// ============================================================
+
+/**
+ * Call this after any LLM invocation to track usage.
+ * OpenClaw skills can hook into the agent lifecycle.
+ */
+export function trackLLMCall(params: {
+  model: string;
+  provider: string;
+  inputTokens: number;
+  outputTokens: number;
+  costUsd?: number;
+  durationMs?: number;
+  taskId?: string;
+}): void {
+  if (!TRACK_LLM) return;
+
+  const c = getClient();
+  const cost = params.costUsd || 0;
+
+  c.trackLLM({
+    model: params.model,
+    provider: params.provider,
+    inputTokens: params.inputTokens,
+    outputTokens: params.outputTokens,
+    costUsd: params.costUsd,
+    durationMs: params.durationMs,
+    taskId: params.taskId,
+  });
+
+  sessionSpend += cost;
+  sessionCalls += 1;
+
+  // Reset daily spend if date changed
+  const today = new Date().toISOString().slice(0, 10);
+  if (today !== dailySpendDate) {
+    dailySpend = 0;
+  }
+  dailySpend += cost;
+}
+
+/**
+ * Call this after any API call to track spend.
+ */
+export function trackAPICall(params: {
+  method: string;
+  url: string;
+  statusCode: number;
+  responseTimeMs: number;
+  paymentAmount?: number;
+  paymentCurrency?: string;
+  txHash?: string;
+}): void {
+  const c = getClient();
+
+  const payment = params.paymentAmount
+    ? {
+        amount: String(params.paymentAmount),
+        currency: params.paymentCurrency || 'USDC',
+        wallet: '',
+        status: 'success' as const,
+        txHash: params.txHash,
+      }
+    : undefined;
+
+  c.track({
+    type: 'request',
+    method: params.method,
+    path: params.url,
+    endpoint: params.url,
+    statusCode: params.statusCode,
+    responseTimeMs: params.responseTimeMs,
+    timestamp: new Date().toISOString(),
+    agentId: AGENT_ID,
+    payment,
+  });
+
+  if (params.paymentAmount) {
+    sessionSpend += params.paymentAmount;
+    dailySpend += params.paymentAmount;
+  }
+  sessionCalls += 1;
+}
+
+/**
+ * Send a heartbeat — call periodically to show agent is alive.
+ */
+export function sendHeartbeat(status: 'healthy' | 'degraded' | 'error' = 'healthy'): void {
+  const c = getClient();
+  c.heartbeat(status, {
+    sessionCalls,
+    sessionSpend,
+    dailySpend,
+    uptime: process.uptime(),
+  });
+}
+
+/**
+ * Gracefully shutdown — flush all pending events.
+ */
+export async function shutdown(): Promise<void> {
+  if (client) {
+    await client.shutdown();
+    client = null;
+  }
+}