@turingpulse/sdk 1.0.1

package/packages/openclaw/src/config.ts

@@ -0,0 +1,139 @@
+/**
+ * Plugin configuration types and defaults.
+ *
+ * The JSON Schema in openclaw.plugin.json validates at config read/write
+ * time. This module provides runtime types and default resolution.
+ */
+
+export interface GovernanceConfig {
+  enabled: boolean;
+  failMode: 'open' | 'closed';
+  timeoutMs: number;
+  excludeTools: string[];
+  scanOutboundMessages: boolean;
+}
+
+export interface TelemetryConfig {
+  enabled: boolean;
+  batchSize: number;
+  flushIntervalMs: number;
+  captureMessageContent: boolean;
+  captureToolParams: boolean;
+  redactPatterns: string[];
+}
+
+export interface TuringPulseOpenClawConfig {
+  apiKey: string;
+  endpoint: string;
+  governance: GovernanceConfig;
+  telemetry: TelemetryConfig;
+  metadata: Record<string, string>;
+}
+
+const DEFAULT_GOVERNANCE: GovernanceConfig = {
+  enabled: true,
+  failMode: 'open',
+  timeoutMs: 3000,
+  excludeTools: [],
+  scanOutboundMessages: false,
+};
+
+const DEFAULT_TELEMETRY: TelemetryConfig = {
+  enabled: true,
+  batchSize: 20,
+  flushIntervalMs: 5000,
+  captureMessageContent: false,
+  captureToolParams: true,
+  redactPatterns: [],
+};
+
+const DEFAULT_ENDPOINT = 'https://api.turingpulse.ai';
+
+/**
+ * Resolve raw plugin config (from openclaw.json) into a fully typed
+ * config object with all defaults applied.
+ */
+export function resolveConfig(
+  raw: Record<string, unknown>,
+): TuringPulseOpenClawConfig {
+  const apiKey = raw.apiKey;
+  if (typeof apiKey !== 'string' || apiKey.trim().length === 0) {
+    throw new Error(
+      'TuringPulse plugin: "apiKey" is required in plugin configuration. ' +
+      'Get an API key from your TuringPulse project settings.',
+    );
+  }
+
+  const endpoint =
+    typeof raw.endpoint === 'string' && raw.endpoint.trim().length > 0
+      ? raw.endpoint.trim().replace(/\/+$/, '')
+      : DEFAULT_ENDPOINT;
+
+  const rawGov = (raw.governance ?? {}) as Record<string, unknown>;
+  const governance: GovernanceConfig = {
+    enabled: typeof rawGov.enabled === 'boolean' ? rawGov.enabled : DEFAULT_GOVERNANCE.enabled,
+    failMode: rawGov.failMode === 'closed' ? 'closed' : DEFAULT_GOVERNANCE.failMode,
+    timeoutMs:
+      typeof rawGov.timeoutMs === 'number' && rawGov.timeoutMs > 0
+        ? rawGov.timeoutMs
+        : DEFAULT_GOVERNANCE.timeoutMs,
+    excludeTools: Array.isArray(rawGov.excludeTools)
+      ? (rawGov.excludeTools as unknown[]).filter((t): t is string => typeof t === 'string')
+      : DEFAULT_GOVERNANCE.excludeTools,
+    scanOutboundMessages:
+      typeof rawGov.scanOutboundMessages === 'boolean'
+        ? rawGov.scanOutboundMessages
+        : DEFAULT_GOVERNANCE.scanOutboundMessages,
+  };
+
+  const rawTel = (raw.telemetry ?? {}) as Record<string, unknown>;
+  const telemetry: TelemetryConfig = {
+    enabled: typeof rawTel.enabled === 'boolean' ? rawTel.enabled : DEFAULT_TELEMETRY.enabled,
+    batchSize:
+      typeof rawTel.batchSize === 'number' && rawTel.batchSize > 0
+        ? rawTel.batchSize
+        : DEFAULT_TELEMETRY.batchSize,
+    flushIntervalMs:
+      typeof rawTel.flushIntervalMs === 'number' && rawTel.flushIntervalMs > 0
+        ? rawTel.flushIntervalMs
+        : DEFAULT_TELEMETRY.flushIntervalMs,
+    captureMessageContent:
+      typeof rawTel.captureMessageContent === 'boolean'
+        ? rawTel.captureMessageContent
+        : DEFAULT_TELEMETRY.captureMessageContent,
+    captureToolParams:
+      typeof rawTel.captureToolParams === 'boolean'
+        ? rawTel.captureToolParams
+        : DEFAULT_TELEMETRY.captureToolParams,
+    redactPatterns: Array.isArray(rawTel.redactPatterns)
+      ? (rawTel.redactPatterns as unknown[]).filter((p): p is string => typeof p === 'string')
+      : DEFAULT_TELEMETRY.redactPatterns,
+  };
+
+  const rawMeta = (raw.metadata ?? {}) as Record<string, unknown>;
+  const metadata: Record<string, string> = {};
+  for (const [k, v] of Object.entries(rawMeta)) {
+    if (typeof v === 'string') {
+      metadata[k] = v;
+    }
+  }
+
+  return { apiKey: apiKey.trim(), endpoint, governance, telemetry, metadata };
+}
+
+/**
+ * Compile redact patterns into a single RegExp for efficient scanning.
+ * Returns null if no patterns are configured.
+ */
+export function compileRedactPatterns(patterns: string[]): RegExp | null {
+  if (patterns.length === 0) return null;
+
+  const DEFAULT_PII_PATTERNS = [
+    '\\b\\d{3}-\\d{2}-\\d{4}\\b',
+    '\\b\\d{4}[- ]?\\d{4}[- ]?\\d{4}[- ]?\\d{4}\\b',
+    '\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b',
+  ];
+
+  const allPatterns = [...DEFAULT_PII_PATTERNS, ...patterns];
+  return new RegExp(`(${allPatterns.join('|')})`, 'g');
+}

package/packages/openclaw/src/hooks/governance.ts

@@ -0,0 +1,267 @@
+/**
+ * Deterministic governance hook for OpenClaw tool execution.
+ *
+ * Intercepts tool.pre events and calls TuringPulse's policy check API
+ * to enforce governance rules OUTSIDE the LLM's decision loop.
+ *
+ * The LLM decides what tool to call → this hook decides whether to allow it.
+ * Policy evaluation is deterministic: if the policy says block, the tool
+ * is cancelled regardless of the LLM's intent.
+ *
+ * Supports:
+ * - fail-open / fail-closed modes for TuringPulse unavailability
+ * - configurable timeout to avoid blocking the agent loop
+ * - tool exclusion lists for trusted/safe tools
+ * - PII scanning on outbound messages (message.pre)
+ */
+
+import type { TuringPulseHttpClient, PolicyCheckParams } from '@turingpulse/sdk';
+import type { GovernanceConfig, TuringPulseOpenClawConfig } from '../config.js';
+import type {
+  ToolPreContext,
+  ToolPreResult,
+  MessageSendingContext,
+  MessageSendingResult,
+  OpenClawPluginAPI,
+} from '../types.js';
+import type { SessionTracker } from '../session-tracker.js';
+
+/**
+ * Register the governance hooks on the OpenClaw plugin API.
+ */
+export function registerGovernanceHooks(
+  api: OpenClawPluginAPI,
+  client: TuringPulseHttpClient,
+  config: TuringPulseOpenClawConfig,
+  sessionTracker: SessionTracker,
+): void {
+  if (!config.governance.enabled) return;
+
+  api.lifecycle.on(
+    'tool.pre',
+    async (rawCtx: unknown): Promise<ToolPreResult | undefined> => {
+      const ctx = rawCtx as ToolPreContext;
+      return handleToolPre(ctx, client, config, sessionTracker);
+    },
+    {
+      priority: 1000,
+      timeoutMs: config.governance.timeoutMs,
+      mode: config.governance.failMode === 'closed' ? 'fail-closed' : 'fail-open',
+      onTimeout: config.governance.failMode === 'closed' ? 'fail-closed' : 'fail-open',
+    },
+  );
+
+  if (config.governance.scanOutboundMessages) {
+    api.lifecycle.on(
+      'message.pre',
+      async (rawCtx: unknown): Promise<MessageSendingResult | undefined> => {
+        const ctx = rawCtx as MessageSendingContext;
+        return handleMessagePre(ctx, client, config, sessionTracker);
+      },
+      {
+        priority: 900,
+        timeoutMs: config.governance.timeoutMs,
+        mode: 'fail-open',
+      },
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tool pre-execution governance check
+// ---------------------------------------------------------------------------
+
+async function handleToolPre(
+  ctx: ToolPreContext,
+  client: TuringPulseHttpClient,
+  config: TuringPulseOpenClawConfig,
+  sessionTracker: SessionTracker,
+): Promise<ToolPreResult | undefined> {
+  if (config.governance.excludeTools.includes(ctx.toolName)) {
+    return undefined;
+  }
+
+  const session = ctx.sessionKey
+    ? sessionTracker.get(ctx.sessionKey)
+    : undefined;
+
+  const params: PolicyCheckParams = {
+    agentId: ctx.agentId ?? session?.agentId,
+    workflowId: ctx.agentId ?? session?.agentId,
+    runId: session?.traceId,
+    nodeName: ctx.toolName,
+    nodeType: 'tool',
+    metadata: {
+      tool_name: ctx.toolName,
+      tool_params: summarizeToolParams(ctx.toolParams),
+      channel: ctx.channelId ?? session?.channelId,
+      session_key: ctx.sessionKey,
+      framework: 'openclaw',
+      ...config.metadata,
+    },
+  };
+
+  if (session) {
+    params.costUsd = session.costUsd;
+  }
+
+  const inputText = buildInputSummary(ctx);
+  if (inputText) {
+    params.inputText = inputText;
+  }
+
+  try {
+    const result = await withTimeout(
+      client.policyCheck(params),
+      config.governance.timeoutMs,
+    );
+
+    if (result.action === 'block') {
+      logGovernanceDecision('BLOCKED', ctx.toolName, result.reason, result.policyIds);
+      return { cancel: true };
+    }
+
+    if (result.action === 'flag') {
+      logGovernanceDecision('FLAGGED', ctx.toolName, result.reason, result.policyIds);
+    }
+
+    return undefined;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // eslint-disable-next-line no-console
+    console.warn(`[turingpulse] Governance check failed for tool "${ctx.toolName}": ${message}`);
+
+    if (config.governance.failMode === 'closed') {
+      logGovernanceDecision('BLOCKED (fail-closed)', ctx.toolName, `check_error: ${message}`);
+      return { cancel: true };
+    }
+
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Outbound message PII scanning
+// ---------------------------------------------------------------------------
+
+async function handleMessagePre(
+  ctx: MessageSendingContext,
+  client: TuringPulseHttpClient,
+  config: TuringPulseOpenClawConfig,
+  sessionTracker: SessionTracker,
+): Promise<MessageSendingResult | undefined> {
+  const content = ctx.context?.content;
+  if (!content || content.length === 0) return undefined;
+
+  const session = ctx.sessionKey
+    ? sessionTracker.get(ctx.sessionKey)
+    : undefined;
+
+  const params: PolicyCheckParams = {
+    agentId: session?.agentId,
+    runId: session?.traceId,
+    nodeName: 'outbound_message',
+    nodeType: 'message',
+    outputText: content.slice(0, 5000),
+    outputLength: content.length,
+    metadata: {
+      channel: ctx.context?.channelId,
+      recipient: ctx.context?.to,
+      framework: 'openclaw',
+      ...config.metadata,
+    },
+  };
+
+  try {
+    const result = await withTimeout(
+      client.policyCheck(params),
+      config.governance.timeoutMs,
+    );
+
+    if (result.action === 'block') {
+      logGovernanceDecision('BLOCKED outbound message', 'message_send', result.reason, result.policyIds);
+      return { cancel: true };
+    }
+
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Summarize tool params for policy evaluation without sending full payloads.
+ * Extracts key identifiers like command strings, file paths, URLs.
+ */
+function summarizeToolParams(params: Record<string, unknown>): string {
+  const parts: string[] = [];
+
+  for (const [key, value] of Object.entries(params)) {
+    if (typeof value === 'string' && value.length > 0) {
+      const truncated = value.length > 500 ? value.slice(0, 500) + '...' : value;
+      parts.push(`${key}=${truncated}`);
+    } else if (typeof value === 'number' || typeof value === 'boolean') {
+      parts.push(`${key}=${String(value)}`);
+    }
+  }
+
+  return parts.join('; ');
+}
+
+/**
+ * Build a human-readable input summary for policy condition matching
+ * (e.g., keyword detection, PII scanning).
+ */
+function buildInputSummary(ctx: ToolPreContext): string | undefined {
+  const command =
+    ctx.toolParams.command ??
+    ctx.toolParams.cmd ??
+    ctx.toolParams.script ??
+    ctx.toolParams.url ??
+    ctx.toolParams.path;
+
+  if (typeof command === 'string') {
+    return `${ctx.toolName}: ${command.slice(0, 2000)}`;
+  }
+
+  return `${ctx.toolName}: ${JSON.stringify(ctx.toolParams).slice(0, 2000)}`;
+}
+
+function logGovernanceDecision(
+  action: string,
+  toolName: string,
+  reason?: string,
+  policyIds?: string[],
+): void {
+  const parts = [`[turingpulse] ${action}: tool="${toolName}"`];
+  if (reason) parts.push(`reason="${reason}"`);
+  if (policyIds && policyIds.length > 0) parts.push(`policies=[${policyIds.join(', ')}]`);
+  // eslint-disable-next-line no-console
+  console.log(parts.join(' '));
+}
+
+/**
+ * Race a promise against a timeout. Rejects with a timeout error
+ * if the promise doesn't resolve in time.
+ */
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`Governance check timed out after ${ms}ms`));
+    }, ms);
+
+    promise
+      .then((value) => {
+        clearTimeout(timer);
+        resolve(value);
+      })
+      .catch((err) => {
+        clearTimeout(timer);
+        reject(err);
+      });
+  });
+}

package/packages/openclaw/src/hooks/lifecycle.ts

@@ -0,0 +1,75 @@
+/**
+ * Gateway lifecycle hooks for plugin initialization and shutdown.
+ *
+ * - boot.post: start the event buffer flush timer
+ * - shutdown.post: flush remaining events and clean up
+ *
+ * Also registers a /turingpulse status command for health reporting.
+ */
+
+import type { EventBuffer } from '../buffer.js';
+import type { SessionTracker } from '../session-tracker.js';
+import type { TuringPulseOpenClawConfig } from '../config.js';
+import type { OpenClawPluginAPI } from '../types.js';
+
+/**
+ * Register gateway lifecycle hooks and status command.
+ */
+export function registerLifecycleHooks(
+  api: OpenClawPluginAPI,
+  config: TuringPulseOpenClawConfig,
+  buffer: EventBuffer,
+  sessionTracker: SessionTracker,
+): void {
+  api.lifecycle.on(
+    'boot.post',
+    async () => {
+      buffer.start();
+      // eslint-disable-next-line no-console
+      console.log(
+        `[turingpulse] Plugin initialized — ` +
+        `governance=${config.governance.enabled ? 'ON' : 'OFF'}, ` +
+        `telemetry=${config.telemetry.enabled ? 'ON' : 'OFF'}, ` +
+        `endpoint=${config.endpoint}`,
+      );
+    },
+    { priority: 100, mode: 'fail-open' },
+  );
+
+  api.lifecycle.on(
+    'shutdown.post',
+    async () => {
+      // eslint-disable-next-line no-console
+      console.log('[turingpulse] Shutting down — flushing remaining events...');
+      await buffer.stop();
+      // eslint-disable-next-line no-console
+      console.log('[turingpulse] Shutdown complete.');
+    },
+    { priority: 100, mode: 'fail-open' },
+  );
+
+  api.registerCommand({
+    name: 'turingpulse',
+    description: 'Show TuringPulse plugin status',
+    handler: () => {
+      const lines = [
+        '--- TuringPulse Plugin Status ---',
+        `Endpoint: ${config.endpoint}`,
+        `Governance: ${config.governance.enabled ? 'ENABLED' : 'DISABLED'}`,
+        `  Fail mode: ${config.governance.failMode}`,
+        `  Timeout: ${config.governance.timeoutMs}ms`,
+        `  Excluded tools: ${config.governance.excludeTools.length > 0 ? config.governance.excludeTools.join(', ') : 'none'}`,
+        `  Outbound PII scan: ${config.governance.scanOutboundMessages ? 'ON' : 'OFF'}`,
+        `Telemetry: ${config.telemetry.enabled ? 'ENABLED' : 'DISABLED'}`,
+        `  Batch size: ${config.telemetry.batchSize}`,
+        `  Flush interval: ${config.telemetry.flushIntervalMs}ms`,
+        `  Capture message content: ${config.telemetry.captureMessageContent ? 'ON' : 'OFF'}`,
+        `  Redact patterns: ${config.telemetry.redactPatterns.length}`,
+        `Active sessions: ${sessionTracker.size}`,
+        `Pending events: ${buffer.pending}`,
+        `Static metadata: ${JSON.stringify(config.metadata)}`,
+      ];
+      return { text: lines.join('\n') };
+    },
+  });
+}

package/packages/openclaw/src/hooks/telemetry.ts

@@ -0,0 +1,207 @@
+/**
+ * Telemetry hooks that capture OpenClaw lifecycle events as TuringPulse
+ * AgentEvent objects.
+ *
+ * Hook flow per interaction:
+ *   message_received → start trace (root span + session)
+ *   agent.pre        → mark agent turn start
+ *   tool.post        → capture tool execution as child span
+ *   agent.post       → capture LLM reasoning as child span
+ *   message_sent     → finalize root span, flush all events
+ */
+
+import { generateUUID } from '@turingpulse/sdk';
+import type { TuringPulseOpenClawConfig } from '../config.js';
+import type { EventBuffer } from '../buffer.js';
+import type { SessionTracker } from '../session-tracker.js';
+import {
+  buildRootSpan,
+  buildToolSpan,
+  buildAgentReasoningSpan,
+} from '../mapper.js';
+import type {
+  OpenClawPluginAPI,
+  MessageReceivedContext,
+  MessageSentContext,
+  ToolPostContext,
+  AgentPreContext,
+  AgentPostContext,
+} from '../types.js';
+
+/**
+ * Register all telemetry lifecycle hooks on the OpenClaw plugin API.
+ */
+export function registerTelemetryHooks(
+  api: OpenClawPluginAPI,
+  config: TuringPulseOpenClawConfig,
+  buffer: EventBuffer,
+  sessionTracker: SessionTracker,
+): void {
+  if (!config.telemetry.enabled) return;
+
+  // ── message_received: start a new trace ──
+  api.lifecycle.on(
+    'request.pre',
+    async (rawCtx: unknown) => {
+      const ctx = rawCtx as MessageReceivedContext;
+      onMessageReceived(ctx, sessionTracker);
+    },
+    { priority: 500, mode: 'fail-open' },
+  );
+
+  // ── agent.pre: mark agent turn start ──
+  api.lifecycle.on(
+    'agent.pre',
+    async (rawCtx: unknown) => {
+      const ctx = rawCtx as AgentPreContext;
+      onAgentPre(ctx, sessionTracker);
+    },
+    { priority: 500, mode: 'fail-open' },
+  );
+
+  // ── tool.post: capture tool execution ──
+  api.lifecycle.on(
+    'tool.post',
+    async (rawCtx: unknown) => {
+      const ctx = rawCtx as ToolPostContext;
+      onToolPost(ctx, config, sessionTracker);
+    },
+    { priority: 500, mode: 'fail-open' },
+  );
+
+  // ── agent.post: capture LLM reasoning ──
+  api.lifecycle.on(
+    'agent.post',
+    async (rawCtx: unknown) => {
+      const ctx = rawCtx as AgentPostContext;
+      onAgentPost(ctx, config, sessionTracker);
+    },
+    { priority: 500, mode: 'fail-open' },
+  );
+
+  // ── message_sent: finalize and flush ──
+  api.lifecycle.on(
+    'message.post',
+    async (rawCtx: unknown) => {
+      const ctx = rawCtx as MessageSentContext;
+      await onMessageSent(ctx, config, buffer, sessionTracker);
+    },
+    { priority: 500, mode: 'fail-open' },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Hook handlers
+// ---------------------------------------------------------------------------
+
+function onMessageReceived(
+  ctx: MessageReceivedContext,
+  sessionTracker: SessionTracker,
+): void {
+  const sessionKey = ctx.sessionKey;
+  if (!sessionKey) return;
+
+  const traceId = generateUUID();
+  const rootSpanId = generateUUID();
+
+  sessionTracker.start(
+    sessionKey,
+    traceId,
+    rootSpanId,
+    ctx.context?.channelId,
+    undefined,
+  );
+}
+
+function onAgentPre(
+  ctx: AgentPreContext,
+  sessionTracker: SessionTracker,
+): void {
+  const sessionKey = ctx.sessionKey;
+  if (!sessionKey) return;
+
+  const session = sessionTracker.get(sessionKey);
+  if (!session) return;
+
+  if (ctx.agentId && !session.agentId) {
+    session.agentId = ctx.agentId;
+  }
+}
+
+function onToolPost(
+  ctx: ToolPostContext,
+  config: TuringPulseOpenClawConfig,
+  sessionTracker: SessionTracker,
+): void {
+  const sessionKey = ctx.sessionKey;
+  if (!sessionKey) return;
+
+  const session = sessionTracker.get(sessionKey);
+  if (!session) return;
+
+  const spanId = generateUUID();
+  const event = buildToolSpan(ctx, session, spanId, config);
+
+  sessionTracker.addChildEvent(sessionKey, event);
+  sessionTracker.addMetrics(sessionKey, { toolCalls: 1 });
+}
+
+function onAgentPost(
+  ctx: AgentPostContext,
+  config: TuringPulseOpenClawConfig,
+  sessionTracker: SessionTracker,
+): void {
+  const sessionKey = ctx.sessionKey;
+  if (!sessionKey) return;
+
+  const session = sessionTracker.get(sessionKey);
+  if (!session) return;
+
+  if (ctx.agentId && !session.agentId) {
+    session.agentId = ctx.agentId;
+  }
+
+  const promptTokens = ctx.usage?.promptTokens ?? 0;
+  const completionTokens = ctx.usage?.completionTokens ?? 0;
+
+  if (promptTokens > 0 || completionTokens > 0 || ctx.durationMs) {
+    const spanId = generateUUID();
+    const event = buildAgentReasoningSpan(ctx, session, spanId, config);
+    sessionTracker.addChildEvent(sessionKey, event);
+  }
+
+  sessionTracker.addMetrics(sessionKey, {
+    promptTokens,
+    completionTokens,
+  });
+}
+
+async function onMessageSent(
+  ctx: MessageSentContext,
+  config: TuringPulseOpenClawConfig,
+  buffer: EventBuffer,
+  sessionTracker: SessionTracker,
+): Promise<void> {
+  const sessionKey = ctx.sessionKey;
+  if (!sessionKey) return;
+
+  const session = sessionTracker.finish(sessionKey);
+  if (!session) return;
+
+  const inputText = '';
+  const outputText = ctx.context?.content ?? '';
+  const status = ctx.context?.success === false ? 'error' : 'success';
+  const error = ctx.context?.error;
+
+  const rootEvent = buildRootSpan(session, config, {
+    inputText,
+    outputText,
+    status,
+    error,
+  });
+
+  buffer.push(rootEvent);
+  buffer.pushMany(session.childEvents);
+
+  await buffer.flush();
+}