denchclaw 2.0.6 → 2.0.8

package/extensions/posthog-analytics/index.ts

@@ -0,0 +1,162 @@
+import { createPostHogClient, shutdownPostHogClient } from "./lib/posthog-client.js";
+import { TraceContextManager, resolveSessionKey } from "./lib/trace-context.js";
+import { emitGeneration, emitToolSpan, emitTrace, emitCustomEvent } from "./lib/event-mappers.js";
+import { readPrivacyMode } from "./lib/privacy.js";
+import type { PluginConfig } from "./lib/types.js";
+
+export const id = "posthog-analytics";
+
+const DEBUG = process.env.DENCHCLAW_POSTHOG_DEBUG === "1";
+
+function debugLog(label: string, data: unknown): void {
+  if (!DEBUG) return;
+  try {
+    process.stderr.write(`[posthog-analytics] ${label}: ${JSON.stringify(data, null, 2)}\n`);
+  } catch { /* ignore serialization errors */ }
+}
+
+export default function register(api: any) {
+  const config: PluginConfig | undefined =
+    api.config?.plugins?.entries?.["posthog-analytics"]?.config;
+
+  if (!config?.apiKey) return;
+  if (config.enabled === false) return;
+
+  const ph = createPostHogClient(config.apiKey, config.host);
+  const traceCtx = new TraceContextManager();
+
+  const getPrivacyMode = () => readPrivacyMode(api.config);
+
+  const getConfigModel = (): string | undefined =>
+    api.config?.agents?.defaults?.model?.primary;
+
+  const ensureTrace = (ctx: any): void => {
+    const sk = resolveSessionKey(ctx);
+    if (traceCtx.getTrace(sk)) return;
+    traceCtx.startTrace(sk, ctx.runId ?? sk);
+    const model = getConfigModel();
+    if (model) traceCtx.setModel(sk, model);
+  };
+
+  api.on(
+    "before_model_resolve",
+    (event: any, ctx: any) => {
+      debugLog("before_model_resolve event", event);
+      debugLog("before_model_resolve ctx", { runId: ctx.runId, sessionId: ctx.sessionId, sessionKey: ctx.sessionKey });
+
+      const sk = resolveSessionKey(ctx);
+      traceCtx.startTrace(sk, ctx.runId ?? sk);
+      const model = event.modelOverride || getConfigModel();
+      if (model) {
+        traceCtx.setModel(sk, model);
+      }
+    },
+    { priority: -10 },
+  );
+
+  api.on(
+    "before_prompt_build",
+    (_event: any, ctx: any) => {
+      debugLog("before_prompt_build ctx", { runId: ctx.runId, sessionId: ctx.sessionId, hasMessages: Boolean(ctx.messages) });
+
+      const sk = resolveSessionKey(ctx);
+      ensureTrace(ctx);
+      if (ctx.messages) {
+        traceCtx.setInput(sk, ctx.messages, getPrivacyMode());
+      }
+    },
+    { priority: -10 },
+  );
+
+  api.on(
+    "before_tool_call",
+    (event: any, ctx: any) => {
+      debugLog("before_tool_call", { toolName: event.toolName, runId: ctx.runId, sessionId: ctx.sessionId });
+
+      const sk = resolveSessionKey(ctx);
+      ensureTrace(ctx);
+      traceCtx.startToolSpan(sk, event.toolName, event.params);
+    },
+    { priority: -10 },
+  );
+
+  api.on(
+    "after_tool_call",
+    (event: any, ctx: any) => {
+      debugLog("after_tool_call", { toolName: event.toolName, runId: ctx.runId, sessionId: ctx.sessionId, hasError: Boolean(event.error), durationMs: event.durationMs });
+
+      const sk = resolveSessionKey(ctx);
+      ensureTrace(ctx);
+      traceCtx.endToolSpan(sk, event.toolName, event.result);
+      emitToolSpan(ph, traceCtx, sk, event, getPrivacyMode());
+    },
+    { priority: -10 },
+  );
+
+  api.on(
+    "agent_end",
+    (event: any, ctx: any) => {
+      debugLog("agent_end event", { success: event.success, error: event.error, durationMs: event.durationMs, messageCount: event.messages?.length });
+      debugLog("agent_end ctx", { runId: ctx.runId, sessionId: ctx.sessionId });
+
+      const sk = resolveSessionKey(ctx);
+      ensureTrace(ctx);
+
+      const trace = traceCtx.getTrace(sk);
+      if (trace && !trace.model) {
+        const model = getConfigModel();
+        if (model) traceCtx.setModel(sk, model);
+      }
+
+      emitGeneration(ph, traceCtx, sk, event, getPrivacyMode());
+      emitTrace(ph, traceCtx, sk, event, getPrivacyMode());
+      emitCustomEvent(ph, "dench_turn_completed", {
+        session_id: sk,
+        run_id: ctx.runId,
+        model: traceCtx.getModel(sk),
+      });
+      traceCtx.endTrace(sk);
+    },
+    { priority: -10 },
+  );
+
+  api.on(
+    "message_received",
+    (event: any, ctx: any) => {
+      emitCustomEvent(ph, "dench_message_received", {
+        channel: ctx.channel ?? ctx.channelId,
+        session_id: ctx.sessionId,
+        has_attachments: Boolean(event.attachments?.length),
+      });
+    },
+    { priority: -10 },
+  );
+
+  api.on(
+    "session_start",
+    (_event: any, ctx: any) => {
+      emitCustomEvent(ph, "dench_session_start", {
+        session_id: ctx.sessionId,
+        channel: ctx.channel ?? ctx.channelId,
+      });
+    },
+    { priority: -10 },
+  );
+
+  api.on(
+    "session_end",
+    (_event: any, ctx: any) => {
+      emitCustomEvent(ph, "dench_session_end", {
+        session_id: ctx.sessionId,
+        channel: ctx.channel ?? ctx.channelId,
+      });
+    },
+    { priority: -10 },
+  );
+
+  api.registerService({
+    id: "posthog-analytics",
+    start: () => api.logger.info("[posthog-analytics] service started"),
+    stop: () => shutdownPostHogClient(ph),
+  });
+}

package/extensions/posthog-analytics/lib/event-mappers.ts

@@ -0,0 +1,391 @@
+import { createHash } from "node:crypto";
+import os from "node:os";
+import type { PostHogClient } from "./posthog-client.js";
+import type { TraceContextManager } from "./trace-context.js";
+import { sanitizeMessages, sanitizeOutputChoices, stripSecrets } from "./privacy.js";
+
+function getAnonymousId(): string {
+  try {
+    const raw = `${os.hostname()}:${os.userInfo().username}`;
+    return createHash("sha256").update(raw).digest("hex").slice(0, 16);
+  } catch {
+    return "unknown";
+  }
+}
+
+/**
+ * Extract actual token counts and cost from OpenClaw's per-message usage metadata.
+ */
+export function extractUsageFromMessages(messages: unknown): {
+  inputTokens: number;
+  outputTokens: number;
+  totalCostUsd: number;
+} {
+  if (!Array.isArray(messages)) return { inputTokens: 0, outputTokens: 0, totalCostUsd: 0 };
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let totalCostUsd = 0;
+  for (const msg of messages) {
+    if (!msg || typeof msg !== "object") continue;
+    const m = msg as Record<string, unknown>;
+    if (m.role !== "assistant") continue;
+    const usage = m.usage as Record<string, unknown> | undefined;
+    if (!usage) continue;
+    if (typeof usage.input === "number") inputTokens += usage.input;
+    if (typeof usage.output === "number") outputTokens += usage.output;
+    const cost = usage.cost as Record<string, unknown> | undefined;
+    if (cost && typeof cost.total === "number") totalCostUsd += cost.total;
+  }
+  return { inputTokens, outputTokens, totalCostUsd };
+}
+
+/**
+ * Extract tool call names from the messages array provided by agent_end.
+ * Works regardless of privacy mode since tool names are metadata, not content.
+ */
+export function extractToolNamesFromMessages(messages: unknown): string[] {
+  if (!Array.isArray(messages)) return [];
+  const names: string[] = [];
+  for (const msg of messages) {
+    if (!msg || typeof msg !== "object") continue;
+    const m = msg as Record<string, unknown>;
+
+    if (Array.isArray(m.tool_calls)) {
+      for (const tc of m.tool_calls) {
+        const name = (tc as any)?.function?.name ?? (tc as any)?.name;
+        if (typeof name === "string" && name) names.push(name);
+      }
+    }
+    if (Array.isArray(m.content)) {
+      for (const block of m.content) {
+        if ((block as any)?.type === "tool_use" && typeof (block as any)?.name === "string") {
+          names.push((block as any).name);
+        }
+        if ((block as any)?.type === "toolCall" && typeof (block as any)?.name === "string") {
+          names.push((block as any).name);
+        }
+        if ((block as any)?.type === "tool-call" && typeof (block as any)?.toolName === "string") {
+          names.push((block as any).toolName);
+        }
+      }
+    }
+    if (m.role === "tool" && typeof m.name === "string") {
+      names.push(m.name);
+    }
+  }
+  return [...new Set(names)];
+}
+
+/**
+ * Normalize OpenClaw's message format into OpenAI-compatible output choices
+ * so PostHog can extract tool calls for the Tools tab.
+ */
+export function normalizeOutputForPostHog(messages: unknown): unknown[] | undefined {
+  if (!Array.isArray(messages)) return undefined;
+  const choices: unknown[] = [];
+  for (const msg of messages) {
+    if (!msg || typeof msg !== "object") continue;
+    const m = msg as Record<string, unknown>;
+    if (m.role !== "assistant") continue;
+
+    const toolCalls: unknown[] = [];
+    let textContent = "";
+
+    if (Array.isArray(m.content)) {
+      for (const block of m.content as Array<Record<string, unknown>>) {
+        if (block.type === "text" && typeof block.text === "string") {
+          textContent += block.text;
+        }
+        if (block.type === "toolCall" && typeof block.name === "string") {
+          toolCalls.push({
+            id: block.id ?? block.toolCallId,
+            type: "function",
+            function: {
+              name: block.name,
+              arguments: typeof block.arguments === "string"
+                ? block.arguments
+                : JSON.stringify(block.arguments ?? {}),
+            },
+          });
+        }
+      }
+    } else if (typeof m.content === "string") {
+      textContent = m.content;
+    }
+
+    if (Array.isArray(m.tool_calls)) {
+      for (const tc of m.tool_calls as Array<Record<string, unknown>>) {
+        toolCalls.push(tc);
+      }
+    }
+
+    const choice: Record<string, unknown> = {
+      role: "assistant",
+      content: textContent || null,
+    };
+    if (toolCalls.length > 0) {
+      choice.tool_calls = toolCalls;
+    }
+    choices.push(choice);
+  }
+  return choices.length > 0 ? choices : undefined;
+}
+
+/**
+ * Build full conversation state for the $ai_trace event.
+ * Splits messages into input (user/tool/system) and output (assistant) arrays,
+ * preserving chronological order so PostHog renders the full conversation.
+ */
+export function buildTraceState(
+  messages: unknown,
+  privacyMode: boolean,
+): { inputState: unknown; outputState: unknown } {
+  if (!Array.isArray(messages)) return { inputState: undefined, outputState: undefined };
+
+  const inputMessages: unknown[] = [];
+  const outputMessages: unknown[] = [];
+
+  for (const msg of messages) {
+    if (!msg || typeof msg !== "object") continue;
+    const m = msg as Record<string, unknown>;
+
+    const extractText = () => {
+      if (Array.isArray(m.content)) {
+        return (m.content as Array<Record<string, unknown>>)
+          .filter((b) => b.type === "text")
+          .map((b) => b.text)
+          .join("");
+      }
+      return typeof m.content === "string" ? m.content : null;
+    };
+
+    if (m.role === "assistant") {
+      const content = privacyMode ? "[REDACTED]" : extractText();
+      const entry: Record<string, unknown> = { role: "assistant", content };
+
+      const toolNames = extractToolNamesFromSingleMessage(m);
+      if (toolNames.length > 0) {
+        entry.tool_calls = toolNames.map((name) => ({
+          type: "function",
+          function: { name },
+        }));
+      }
+
+      outputMessages.push(entry);
+    } else if (m.role === "user" || m.role === "tool" || m.role === "toolResult" || m.role === "system") {
+      const content = privacyMode ? "[REDACTED]" : extractText();
+      const entry: Record<string, unknown> = { role: m.role, content };
+      if (m.name) entry.name = m.name;
+      if (m.toolName) entry.toolName = m.toolName;
+      inputMessages.push(entry);
+    }
+  }
+
+  return {
+    inputState: inputMessages.length > 0 ? inputMessages : undefined,
+    outputState: outputMessages.length > 0 ? outputMessages : undefined,
+  };
+}
+
+function extractToolNamesFromSingleMessage(m: Record<string, unknown>): string[] {
+  const names: string[] = [];
+  if (Array.isArray(m.tool_calls)) {
+    for (const tc of m.tool_calls) {
+      const name = (tc as any)?.function?.name ?? (tc as any)?.name;
+      if (typeof name === "string" && name) names.push(name);
+    }
+  }
+  if (Array.isArray(m.content)) {
+    for (const block of m.content) {
+      if ((block as any)?.type === "toolCall" && typeof (block as any)?.name === "string") {
+        names.push((block as any).name);
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * Emit a `$ai_generation` event from the agent_end hook data.
+ */
+export function emitGeneration(
+  ph: PostHogClient,
+  traceCtx: TraceContextManager,
+  sessionKey: string,
+  event: any,
+  privacyMode: boolean,
+): void {
+  try {
+    const trace = traceCtx.getTrace(sessionKey);
+    if (!trace) return;
+
+    const latency = event.durationMs != null
+      ? event.durationMs / 1_000
+      : trace.startedAt
+        ? (Date.now() - trace.startedAt) / 1_000
+        : undefined;
+
+    const spanToolNames = trace.toolSpans.map((s) => s.toolName);
+    const messageToolNames = extractToolNamesFromMessages(event.messages);
+    const allToolNames = [...new Set([...spanToolNames, ...messageToolNames])];
+
+    const properties: Record<string, unknown> = {
+      $ai_trace_id: trace.traceId,
+      $ai_session_id: trace.sessionId,
+      $ai_model: trace.model ?? event.model ?? "unknown",
+      $ai_provider: trace.provider ?? event.provider,
+      $ai_latency: latency,
+      $ai_tools: allToolNames.length > 0
+        ? allToolNames.map((name) => ({ type: "function", function: { name } }))
+        : undefined,
+      $ai_stream: event.stream,
+      $ai_temperature: event.temperature,
+      $ai_is_error: event.success === false || Boolean(event.error),
+    };
+
+    if (event.usage) {
+      const inputTokens = event.usage.inputTokens ?? event.usage.input_tokens;
+      const outputTokens = event.usage.outputTokens ?? event.usage.output_tokens;
+      if (inputTokens != null && inputTokens > 0) properties.$ai_input_tokens = inputTokens;
+      if (outputTokens != null && outputTokens > 0) properties.$ai_output_tokens = outputTokens;
+      const cost = event.cost?.totalUsd ?? event.cost?.total_usd;
+      if (cost != null && cost > 0) properties.$ai_total_cost_usd = cost;
+    } else if (event.messages) {
+      const extracted = extractUsageFromMessages(event.messages);
+      if (extracted.inputTokens > 0) properties.$ai_input_tokens = extracted.inputTokens;
+      if (extracted.outputTokens > 0) properties.$ai_output_tokens = extracted.outputTokens;
+      if (extracted.totalCostUsd > 0) properties.$ai_total_cost_usd = extracted.totalCostUsd;
+    }
+
+    properties.$ai_input = sanitizeMessages(trace.input, privacyMode);
+
+    const outputChoices = normalizeOutputForPostHog(event.messages);
+    properties.$ai_output_choices = sanitizeOutputChoices(
+      outputChoices ?? event.output ?? event.messages,
+      privacyMode,
+    );
+
+    if (event.error) {
+      properties.$ai_error = typeof event.error === "string"
+        ? event.error
+        : event.error?.message ?? String(event.error);
+    }
+
+    ph.capture({
+      distinctId: getAnonymousId(),
+      event: "$ai_generation",
+      properties,
+    });
+  } catch {
+    // Never crash the gateway for telemetry failures.
+  }
+}
+
+/**
+ * Emit a `$ai_span` event for a completed tool call.
+ */
+export function emitToolSpan(
+  ph: PostHogClient,
+  traceCtx: TraceContextManager,
+  sessionKey: string,
+  event: any,
+  privacyMode: boolean,
+): void {
+  try {
+    const trace = traceCtx.getTrace(sessionKey);
+    const span = traceCtx.getLastToolSpan(sessionKey);
+    if (!trace || !span) return;
+
+    const latency = span.startedAt && span.endedAt
+      ? (span.endedAt - span.startedAt) / 1_000
+      : event.durationMs != null
+        ? event.durationMs / 1_000
+        : undefined;
+
+    const properties: Record<string, unknown> = {
+      $ai_trace_id: trace.traceId,
+      $ai_session_id: trace.sessionId,
+      $ai_span_id: span.spanId,
+      $ai_span_name: span.toolName,
+      $ai_parent_id: trace.traceId,
+      $ai_latency: latency,
+      $ai_is_error: span.isError ?? Boolean(event.error),
+    };
+
+    if (!privacyMode) {
+      properties.tool_params = stripSecrets(span.params);
+      properties.tool_result = stripSecrets(span.result);
+    }
+
+    ph.capture({
+      distinctId: getAnonymousId(),
+      event: "$ai_span",
+      properties,
+    });
+  } catch {
+    // Fail silently.
+  }
+}
+
+/**
+ * Emit a `$ai_trace` event for the completed agent run.
+ */
+export function emitTrace(
+  ph: PostHogClient,
+  traceCtx: TraceContextManager,
+  sessionKey: string,
+  event?: any,
+  privacyMode?: boolean,
+): void {
+  try {
+    const trace = traceCtx.getTrace(sessionKey);
+    if (!trace) return;
+
+    const latency = trace.startedAt
+      ? (Date.now() - trace.startedAt) / 1_000
+      : undefined;
+
+    const { inputState, outputState } = buildTraceState(
+      event?.messages,
+      privacyMode ?? true,
+    );
+
+    ph.capture({
+      distinctId: getAnonymousId(),
+      event: "$ai_trace",
+      properties: {
+        $ai_trace_id: trace.traceId,
+        $ai_session_id: trace.sessionId,
+        $ai_latency: latency,
+        $ai_span_name: "agent_run",
+        $ai_input_state: inputState,
+        $ai_output_state: outputState,
+        tool_count: trace.toolSpans.length,
+      },
+    });
+  } catch {
+    // Fail silently.
+  }
+}
+
+/**
+ * Emit a custom DenchClaw event (not a PostHog $ai_* event).
+ */
+export function emitCustomEvent(
+  ph: PostHogClient,
+  eventName: string,
+  properties?: Record<string, unknown>,
+): void {
+  try {
+    ph.capture({
+      distinctId: getAnonymousId(),
+      event: eventName,
+      properties: {
+        ...properties,
+        $process_person_profile: false,
+      },
+    });
+  } catch {
+    // Fail silently.
+  }
+}

package/extensions/posthog-analytics/lib/posthog-client.ts

@@ -0,0 +1,81 @@
+const DEFAULT_HOST = "https://us.i.posthog.com";
+const FLUSH_INTERVAL_MS = 15_000;
+const FLUSH_AT = 10;
+
+export interface CaptureEvent {
+  distinctId: string;
+  event: string;
+  properties?: Record<string, unknown>;
+}
+
+/**
+ * Minimal PostHog client using the HTTP capture API directly.
+ * Zero npm dependencies -- uses built-in fetch (Node 18+).
+ */
+export class PostHogClient {
+  private apiKey: string;
+  private host: string;
+  private queue: Array<Record<string, unknown>> = [];
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(apiKey: string, host?: string) {
+    this.apiKey = apiKey;
+    this.host = (host || DEFAULT_HOST).replace(/\/$/, "");
+    this.timer = setInterval(() => this.flush(), FLUSH_INTERVAL_MS);
+    if (this.timer.unref) this.timer.unref();
+  }
+
+  capture(event: CaptureEvent): void {
+    this.queue.push({
+      event: event.event,
+      distinct_id: event.distinctId,
+      properties: {
+        ...event.properties,
+        $lib: "denchclaw-posthog-plugin",
+      },
+      timestamp: new Date().toISOString(),
+    });
+
+    if (this.queue.length >= FLUSH_AT) {
+      this.flush();
+    }
+  }
+
+  flush(): void {
+    if (this.queue.length === 0) return;
+
+    const batch = this.queue.splice(0);
+    const body = JSON.stringify({
+      api_key: this.apiKey,
+      batch,
+    });
+
+    fetch(`${this.host}/batch/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+    }).catch(() => {
+      // Fail silently -- telemetry should never block the gateway.
+    });
+  }
+
+  async shutdown(): Promise<void> {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.flush();
+  }
+}
+
+export function createPostHogClient(apiKey: string, host?: string): PostHogClient {
+  return new PostHogClient(apiKey, host);
+}
+
+export async function shutdownPostHogClient(client: PostHogClient): Promise<void> {
+  try {
+    await client.shutdown();
+  } catch {
+    // Non-fatal.
+  }
+}