@turingpulse/sdk 1.0.1

package/packages/openclaw/src/index.ts

@@ -0,0 +1,91 @@
+/**
+ * TuringPulse plugin for OpenClaw.
+ *
+ * Provides deterministic governance, observability, evaluations, and alerting
+ * for OpenClaw agents. Governance rules are enforced OUTSIDE the LLM's
+ * decision loop — if a policy says block, the tool call is cancelled
+ * regardless of the LLM's intent.
+ *
+ * Installation:
+ *   openclaw plugins install @turingpulse/sdk-openclaw
+ *
+ * Configuration (in openclaw.json):
+ *   {
+ *     "plugins": {
+ *       "entries": {
+ *         "turingpulse": {
+ *           "enabled": true,
+ *           "config": {
+ *             "apiKey": "tp-...",
+ *             "governance": { "enabled": true },
+ *             "telemetry": { "enabled": true }
+ *           }
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * Status command:
+ *   /turingpulse — shows plugin health, active sessions, pending events
+ */
+
+import { TuringPulseHttpClient, TuringPulseConfig } from '@turingpulse/sdk';
+import { resolveConfig } from './config.js';
+import { EventBuffer } from './buffer.js';
+import { SessionTracker } from './session-tracker.js';
+import { registerGovernanceHooks } from './hooks/governance.js';
+import { registerTelemetryHooks } from './hooks/telemetry.js';
+import { registerLifecycleHooks } from './hooks/lifecycle.js';
+import type { OpenClawPluginAPI } from './types.js';
+
+/**
+ * OpenClaw plugin entry point. Called by the OpenClaw Gateway when
+ * the plugin is loaded. Receives the plugin API for hook registration.
+ */
+export default function register(api: OpenClawPluginAPI): void {
+  let config;
+  try {
+    config = resolveConfig(api.config);
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.error(
+      '[turingpulse] Configuration error:',
+      err instanceof Error ? err.message : String(err),
+    );
+    return;
+  }
+
+  const sdkConfig = new TuringPulseConfig({
+    apiKey: config.apiKey,
+    endpoint: config.endpoint,
+    workflowName: 'openclaw',
+    timeoutMs: config.governance.timeoutMs,
+    maxRetries: 2,
+  });
+
+  const client = new TuringPulseHttpClient(sdkConfig);
+  const buffer = new EventBuffer(
+    client,
+    config.telemetry.batchSize,
+    config.telemetry.flushIntervalMs,
+  );
+  const sessionTracker = new SessionTracker();
+
+  registerGovernanceHooks(api, client, config, sessionTracker);
+  registerTelemetryHooks(api, config, buffer, sessionTracker);
+  registerLifecycleHooks(api, config, buffer, sessionTracker);
+}
+
+export { resolveConfig } from './config.js';
+export type { TuringPulseOpenClawConfig, GovernanceConfig, TelemetryConfig } from './config.js';
+export type {
+  OpenClawPluginAPI,
+  ToolPreContext,
+  ToolPostContext,
+  MessageReceivedContext,
+  MessageSentContext,
+  AgentPreContext,
+  AgentPostContext,
+} from './types.js';
+export { EventBuffer } from './buffer.js';
+export { SessionTracker } from './session-tracker.js';

package/packages/openclaw/src/mapper.ts

@@ -0,0 +1,233 @@
+/**
+ * Maps OpenClaw hook context objects to TuringPulse AgentEvent format.
+ *
+ * All events emitted by the plugin flow through this module to ensure
+ * consistent structure, metadata enrichment, and content redaction.
+ */
+
+import type { AgentEvent, AgentEventPayload, ToolCallInfo } from '@turingpulse/interfaces';
+import type { TuringPulseOpenClawConfig } from './config.js';
+import type { SessionState } from './session-tracker.js';
+import type { ToolPostContext, AgentPostContext } from './types.js';
+
+const FRAMEWORK_NAME = 'openclaw';
+const MAX_FIELD_LENGTH = 50_000;
+
+/**
+ * Build the root workflow span for a complete interaction
+ * (message_received → message_sent).
+ */
+export function buildRootSpan(
+  session: SessionState,
+  config: TuringPulseOpenClawConfig,
+  opts: {
+    inputText?: string;
+    outputText?: string;
+    status: string;
+    error?: string;
+  },
+): AgentEvent {
+  const durationMs = Date.now() - session.startedAt;
+
+  const metadata: Record<string, unknown> = {
+    span_id: session.rootSpanId,
+    trace_id: session.traceId,
+    node_type: 'workflow',
+    framework: FRAMEWORK_NAME,
+    workflow_name: session.agentId ?? 'openclaw-agent',
+    channel: session.channelId,
+    tool_call_count: String(session.toolCallCount),
+    ...config.metadata,
+  };
+
+  if (opts.inputText && config.telemetry.captureMessageContent) {
+    metadata.input = redact(truncate(opts.inputText), config);
+  }
+  if (opts.outputText && config.telemetry.captureMessageContent) {
+    metadata.output = redact(truncate(opts.outputText), config);
+  }
+  if (opts.error) {
+    metadata.error_message = truncate(opts.error, 500);
+  }
+
+  return {
+    runId: session.traceId,
+    agentId: session.agentId ?? 'openclaw-agent',
+    timestamp: new Date(session.startedAt).toISOString(),
+    type: 'span',
+    payload: {
+      name: `${session.agentId ?? 'openclaw-agent'}.execute`,
+      durationMs,
+      status: opts.status,
+      tokens: {
+        prompt: session.tokens.prompt,
+        completion: session.tokens.completion,
+      },
+      costUsd: session.costUsd,
+      metadata,
+    },
+    workflowName: session.agentId ?? 'openclaw-agent',
+  };
+}
+
+/**
+ * Build a child span for a tool execution (from tool.post context).
+ */
+export function buildToolSpan(
+  ctx: ToolPostContext,
+  session: SessionState,
+  spanId: string,
+  config: TuringPulseOpenClawConfig,
+): AgentEvent {
+  const status = ctx.error ? 'error' : 'success';
+  const durationMs = ctx.durationMs ?? 0;
+
+  const metadata: Record<string, unknown> = {
+    span_id: spanId,
+    parent_span_id: session.rootSpanId,
+    trace_id: session.traceId,
+    node_type: 'tool',
+    framework: FRAMEWORK_NAME,
+    workflow_name: session.agentId ?? 'openclaw-agent',
+    depth: '1',
+    tool_name: ctx.toolName,
+    channel: session.channelId,
+    ...config.metadata,
+  };
+
+  if (config.telemetry.captureToolParams) {
+    metadata.input = redact(
+      truncate(JSON.stringify(ctx.toolParams)),
+      config,
+    );
+  }
+
+  const resultStr = ctx.result != null ? String(ctx.result) : '';
+  if (resultStr.length > 0) {
+    metadata.output = redact(truncate(resultStr), config);
+  }
+
+  if (ctx.error) {
+    metadata.error_message = truncate(ctx.error.message, 500);
+  }
+
+  const toolCalls: ToolCallInfo[] = [
+    {
+      toolName: ctx.toolName,
+      toolArgs: config.telemetry.captureToolParams ? ctx.toolParams : {},
+      toolResult: truncate(resultStr),
+      success: !ctx.error,
+      errorMessage: ctx.error?.message,
+    },
+  ];
+
+  return {
+    runId: session.traceId,
+    agentId: `tool_${ctx.toolName}`,
+    timestamp: new Date().toISOString(),
+    type: 'span',
+    payload: {
+      name: `${session.agentId ?? 'openclaw-agent'}.tool_${ctx.toolName}`,
+      durationMs,
+      status,
+      metadata,
+      toolCalls,
+    },
+    workflowName: session.agentId ?? 'openclaw-agent',
+  };
+}
+
+/**
+ * Build a child span for an agent reasoning turn (from agent.post context).
+ */
+export function buildAgentReasoningSpan(
+  ctx: AgentPostContext,
+  session: SessionState,
+  spanId: string,
+  config: TuringPulseOpenClawConfig,
+): AgentEvent {
+  const status = ctx.error ? 'error' : 'success';
+  const durationMs = ctx.durationMs ?? 0;
+
+  const promptTokens = ctx.usage?.promptTokens ?? 0;
+  const completionTokens = ctx.usage?.completionTokens ?? 0;
+
+  const metadata: Record<string, unknown> = {
+    span_id: spanId,
+    parent_span_id: session.rootSpanId,
+    trace_id: session.traceId,
+    node_type: 'llm',
+    framework: FRAMEWORK_NAME,
+    workflow_name: session.agentId ?? 'openclaw-agent',
+    depth: '1',
+    model: ctx.model ?? 'unknown',
+    provider: inferProvider(ctx.model),
+    channel: session.channelId,
+    ...config.metadata,
+  };
+
+  if (ctx.error) {
+    metadata.error_message = truncate(ctx.error.message, 500);
+  }
+
+  const payload: AgentEventPayload = {
+    name: `${session.agentId ?? 'openclaw-agent'}.agent_reasoning`,
+    durationMs,
+    status,
+    metadata,
+  };
+
+  if (promptTokens > 0 || completionTokens > 0) {
+    payload.tokens = { prompt: promptTokens, completion: completionTokens };
+  }
+
+  return {
+    runId: session.traceId,
+    agentId: 'agent_reasoning',
+    timestamp: new Date().toISOString(),
+    type: 'span',
+    payload,
+    workflowName: session.agentId ?? 'openclaw-agent',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function truncate(value: string, maxLen: number = MAX_FIELD_LENGTH): string {
+  if (value.length <= maxLen) return value;
+  return value.slice(0, maxLen) + '...[truncated]';
+}
+
+/**
+ * Apply redaction patterns to a string. Replaces matches with [REDACTED].
+ */
+function redact(value: string, config: TuringPulseOpenClawConfig): string {
+  if (config.telemetry.redactPatterns.length === 0) return value;
+
+  let result = value;
+  for (const pattern of config.telemetry.redactPatterns) {
+    try {
+      result = result.replace(new RegExp(pattern, 'g'), '[REDACTED]');
+    } catch {
+      // invalid regex — skip
+    }
+  }
+  return result;
+}
+
+/**
+ * Best-effort provider inference from model string.
+ * OpenClaw uses "provider/model" format (e.g., "anthropic/claude-sonnet-4-5").
+ */
+function inferProvider(model?: string): string {
+  if (!model) return 'unknown';
+  const slash = model.indexOf('/');
+  if (slash > 0) return model.slice(0, slash);
+  if (model.startsWith('claude')) return 'anthropic';
+  if (model.startsWith('gpt') || model.startsWith('o1') || model.startsWith('o3')) return 'openai';
+  if (model.startsWith('gemini')) return 'google';
+  if (model.startsWith('mistral')) return 'mistral';
+  return 'unknown';
+}

package/packages/openclaw/src/session-tracker.ts

@@ -0,0 +1,181 @@
+/**
+ * Tracks per-session state across OpenClaw lifecycle hooks.
+ *
+ * Each user interaction (message_received → tool calls → message_sent)
+ * creates a session entry that accumulates trace data, child spans,
+ * and cost metrics. Sessions are identified by OpenClaw's sessionKey.
+ *
+ * Uses LRU eviction to bound memory for long-running gateways.
+ */
+
+import type { AgentEvent } from '@turingpulse/interfaces';
+
+export interface SessionState {
+  /** Trace ID for this interaction (generated on message_received). */
+  traceId: string;
+  /** Root span ID for the top-level workflow span. */
+  rootSpanId: string;
+  /** Timestamp when the interaction started. */
+  startedAt: number;
+  /** Accumulated child span events during this interaction. */
+  childEvents: AgentEvent[];
+  /** Chat channel this session originates from. */
+  channelId?: string;
+  /** OpenClaw agent handling this session. */
+  agentId?: string;
+  /** Cumulative token counts for this interaction. */
+  tokens: { prompt: number; completion: number };
+  /** Cumulative estimated cost in USD. */
+  costUsd: number;
+  /** Number of tool calls in this interaction. */
+  toolCallCount: number;
+  /** Depth counter for nested spans. */
+  currentDepth: number;
+}
+
+const DEFAULT_MAX_SESSIONS = 500;
+const DEFAULT_STALE_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+
+export class SessionTracker {
+  private readonly sessions = new Map<string, SessionState>();
+  private readonly accessOrder: string[] = [];
+  private readonly maxSessions: number;
+  private readonly staleTimeoutMs: number;
+
+  constructor(maxSessions?: number, staleTimeoutMs?: number) {
+    this.maxSessions = maxSessions ?? DEFAULT_MAX_SESSIONS;
+    this.staleTimeoutMs = staleTimeoutMs ?? DEFAULT_STALE_TIMEOUT_MS;
+  }
+
+  /**
+   * Create a new session entry for an incoming interaction.
+   * Returns the new session state with generated trace/span IDs.
+   */
+  start(
+    sessionKey: string,
+    traceId: string,
+    rootSpanId: string,
+    channelId?: string,
+    agentId?: string,
+  ): SessionState {
+    this.evictStale();
+
+    const state: SessionState = {
+      traceId,
+      rootSpanId,
+      startedAt: Date.now(),
+      childEvents: [],
+      channelId,
+      agentId,
+      tokens: { prompt: 0, completion: 0 },
+      costUsd: 0,
+      toolCallCount: 0,
+      currentDepth: 0,
+    };
+
+    this.sessions.set(sessionKey, state);
+    this.touchAccessOrder(sessionKey);
+    this.enforceCapacity();
+
+    return state;
+  }
+
+  /**
+   * Retrieve the active session state. Returns undefined if no session
+   * is active for this key (e.g., message arrived without message_received hook).
+   */
+  get(sessionKey: string): SessionState | undefined {
+    const state = this.sessions.get(sessionKey);
+    if (state) {
+      this.touchAccessOrder(sessionKey);
+    }
+    return state;
+  }
+
+  /**
+   * Add a child span event to the session. Used by telemetry hooks
+   * to accumulate tool call and agent reasoning spans.
+   */
+  addChildEvent(sessionKey: string, event: AgentEvent): void {
+    const state = this.sessions.get(sessionKey);
+    if (!state) return;
+    state.childEvents.push(event);
+  }
+
+  /**
+   * Update cumulative metrics for the session.
+   */
+  addMetrics(
+    sessionKey: string,
+    metrics: {
+      promptTokens?: number;
+      completionTokens?: number;
+      costUsd?: number;
+      toolCalls?: number;
+    },
+  ): void {
+    const state = this.sessions.get(sessionKey);
+    if (!state) return;
+
+    state.tokens.prompt += metrics.promptTokens ?? 0;
+    state.tokens.completion += metrics.completionTokens ?? 0;
+    state.costUsd += metrics.costUsd ?? 0;
+    state.toolCallCount += metrics.toolCalls ?? 0;
+  }
+
+  /**
+   * Finalize and remove a session, returning all accumulated state.
+   * Called on message_sent to flush the complete interaction trace.
+   */
+  finish(sessionKey: string): SessionState | undefined {
+    const state = this.sessions.get(sessionKey);
+    if (!state) return undefined;
+
+    this.sessions.delete(sessionKey);
+    const idx = this.accessOrder.indexOf(sessionKey);
+    if (idx !== -1) this.accessOrder.splice(idx, 1);
+
+    return state;
+  }
+
+  /** Number of active sessions (for health/status reporting). */
+  get size(): number {
+    return this.sessions.size;
+  }
+
+  /**
+   * Remove sessions that have been idle beyond the stale timeout.
+   * Prevents unbounded memory growth from abandoned sessions.
+   */
+  private evictStale(): void {
+    const now = Date.now();
+    const toRemove: string[] = [];
+
+    for (const [key, state] of this.sessions) {
+      if (now - state.startedAt > this.staleTimeoutMs) {
+        toRemove.push(key);
+      }
+    }
+
+    for (const key of toRemove) {
+      this.sessions.delete(key);
+      const idx = this.accessOrder.indexOf(key);
+      if (idx !== -1) this.accessOrder.splice(idx, 1);
+    }
+  }
+
+  /** Evict least-recently-used sessions if capacity is exceeded. */
+  private enforceCapacity(): void {
+    while (this.sessions.size > this.maxSessions && this.accessOrder.length > 0) {
+      const oldest = this.accessOrder.shift();
+      if (oldest) this.sessions.delete(oldest);
+    }
+  }
+
+  /** Move a session key to the end of the access order (most recent). */
+  private touchAccessOrder(key: string): void {
+    const idx = this.accessOrder.indexOf(key);
+    if (idx !== -1) this.accessOrder.splice(idx, 1);
+    this.accessOrder.push(key);
+  }
+}