@turingpulse/sdk 1.0.1

package/packages/mastra/src/wrapper.ts

@@ -0,0 +1,301 @@
+/**
+ * Mastra 1.2.x instrumentation for TuringPulse SDK (TypeScript).
+ *
+ * Wraps `agent.generate()` to capture:
+ * - Token counts from `response.usage` (ai-sdk format: promptTokens / completionTokens).
+ * - Per-tool-call child spans.
+ * - Agent instructions as system prompt.
+ *
+ * This integration uses the centralized TuringPulseHttpClient when a plugin
+ * instance is available (preferred), or falls back to standalone HTTP when
+ * used without the full SDK.
+ */
+
+import type {
+  AgentEvent,
+} from '@turingpulse/interfaces';
+
+import type { ToolCallRecord } from '@turingpulse/sdk';
+import { generateUUID } from '@turingpulse/sdk';
+import { DEFAULT_ENDPOINT } from '@turingpulse/sdk';
+import type { TuringPulseHttpClient } from '@turingpulse/sdk';
+import { SDK_VERSION } from '@turingpulse/sdk';
+import { safeEnv, safeErrorMessage, toSnakeCaseDeep } from '@turingpulse/sdk';
+
+const FRAMEWORK_NAME = 'mastra';
+const FRAMEWORK_VERSION = '1.2.0';
+
+/** Mastra tool call with required result/id fields. */
+interface MastraToolCallRecord extends ToolCallRecord {
+  toolResult: string;
+  toolId: string;
+}
+
+interface MastraInstrumentOptions {
+  /** Workflow display name for TuringPulse. */
+  name: string;
+  /** LLM model name (default: gpt-4o-mini). */
+  model?: string;
+  /** LLM provider (default: openai). */
+  provider?: string;
+  /**
+   * Preferred: pass the plugin's HTTP client for centralized retries, timeouts, headers.
+   * If not provided, falls back to standalone fetch using apiKey + endpoint.
+   */
+  httpClient?: TuringPulseHttpClient;
+  /** TuringPulse API endpoint — only needed if httpClient is not provided. */
+  endpoint?: string;
+  /** TuringPulse API key — only needed if httpClient is not provided. */
+  apiKey?: string;
+  /** Tool names available to the agent. */
+  toolNames?: string[];
+  /**
+   * A reference to the mutable tool-call log array. Tool execute()
+   * callbacks push records here during agent.generate(). The integration
+   * reads from this array after execution completes.
+   */
+  toolCallLog?: MastraToolCallRecord[];
+}
+
+/**
+ * Instrument a Mastra Agent for TuringPulse observability.
+ *
+ * Returns an async function that runs `agent.generate()` and emits
+ * a root workflow span plus per-tool/LLM child spans.
+ */
+export function instrumentMastra(
+  agent: { generate: (prompt: string) => Promise<unknown>; [key: string]: unknown },
+  options: MastraInstrumentOptions,
+): (prompt: string) => Promise<unknown> {
+  const {
+    name,
+    model = 'gpt-4o-mini',
+    provider = 'openai',
+    httpClient,
+    endpoint = safeEnv('TP_ENDPOINT') || DEFAULT_ENDPOINT,
+    apiKey = (safeEnv('TP_API_KEY') || '').trim(),
+    toolNames = [],
+    toolCallLog: externalLog,
+  } = options;
+
+  if (!httpClient && !apiKey) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'TuringPulse: No httpClient or apiKey provided. Telemetry will be skipped. ' +
+      'Pass the plugin\'s client via httpClient for best results.',
+    );
+  }
+
+  const systemPrompt: string =
+    typeof (agent as Record<string, unknown>).instructions === 'string'
+      ? ((agent as Record<string, unknown>).instructions as string).slice(0, 500)
+      : '';
+
+  return async function runInstrumented(prompt: string): Promise<unknown> {
+    const traceId = generateUUID();
+    const rootSpanId = generateUUID();
+    const t0 = Date.now();
+
+    if (externalLog) externalLog.length = 0;
+
+    const maxFieldLen = httpClient?.maxSerializedFieldLength ?? 50_000;
+
+    let response: unknown;
+    let generationError: Error | null = null;
+    try {
+      response = await agent.generate(prompt);
+    } catch (err) {
+      generationError = err instanceof Error ? err : new Error(String(err));
+      response = null;
+    }
+    const totalDurationMs = Date.now() - t0;
+
+    const resp = (response as Record<string, unknown>) || {};
+    const finalOutput = (resp.text as string) || '';
+    const usage = (resp.usage as { promptTokens?: number; completionTokens?: number }) || {};
+    const promptTokens = usage.promptTokens || 0;
+    const completionTokens = usage.completionTokens || 0;
+
+    const estPrompt = promptTokens || Math.max(Math.round(prompt.length / 4), 400);
+    const estCompletion = completionTokens || Math.max(Math.round(finalOutput.length / 4), 200);
+
+    const tcLog = externalLog ? [...externalLog] : [];
+
+    // ── Build child spans ──
+    const childEvents: AgentEvent[] = [];
+    const now = new Date();
+    let offset = 100;
+
+    for (const tc of tcLog) {
+      const spanId = generateUUID();
+      const ts = new Date(now.getTime() + offset).toISOString();
+      childEvents.push({
+        runId: traceId,
+        agentId: `tool_${tc.toolName}`,
+        timestamp: ts,
+        type: 'span',
+        payload: {
+          name: `${name}.tool_${tc.toolName}`,
+          durationMs: Math.floor(totalDurationMs / (tcLog.length + 1)),
+          status: tc.success ? 'success' : 'error',
+          metadata: {
+            span_id: spanId,
+            parent_span_id: rootSpanId,
+            trace_id: traceId,
+            workflow_name: name,
+            framework: FRAMEWORK_NAME,
+            node_type: 'tool',
+            depth: '1',
+            input: JSON.stringify(tc.toolArgs).slice(0, maxFieldLen),
+            output: JSON.stringify({ result: tc.toolResult.slice(0, maxFieldLen) }),
+            available_tools: JSON.stringify(toolNames),
+            tool_name: tc.toolName,
+            ...(tc.errorMessage ? { error_message: tc.errorMessage } : {}),
+            mastra_tool_id: tc.toolName,
+            mastra_version: FRAMEWORK_VERSION,
+          },
+          toolCalls: [{
+            toolName: tc.toolName,
+            toolArgs: tc.toolArgs,
+            toolResult: tc.toolResult.slice(0, maxFieldLen),
+            toolId: tc.toolId,
+            success: tc.success,
+            errorMessage: tc.errorMessage,
+          }],
+        },
+      });
+      offset += Math.floor(totalDurationMs / (tcLog.length + 1)) + 50;
+    }
+
+    // LLM reasoning span
+    const llmSpanId = generateUUID();
+    childEvents.push({
+      runId: traceId,
+      agentId: 'agent_reasoning',
+      timestamp: new Date(now.getTime() + offset).toISOString(),
+      type: 'span',
+      payload: {
+        name: `${name}.agent_reasoning`,
+        durationMs: Math.floor(totalDurationMs / (tcLog.length + 1)),
+        status: 'success',
+        tokens: { prompt: Math.round(estPrompt), completion: Math.round(estCompletion) },
+        costUsd: 0,
+        metadata: {
+          span_id: llmSpanId,
+          parent_span_id: rootSpanId,
+          trace_id: traceId,
+          workflow_name: name,
+          framework: FRAMEWORK_NAME,
+          node_type: 'llm',
+          depth: '1',
+          prompt: prompt.slice(0, maxFieldLen),
+          user_query: prompt.slice(0, maxFieldLen),
+          system_prompt: systemPrompt,
+          model,
+          provider,
+          available_tools: JSON.stringify(toolNames),
+          mastra_agent_name: (agent as Record<string, unknown>).name as string || name,
+          mastra_model: model,
+          mastra_tool_count: String(tcLog.length),
+          mastra_version: FRAMEWORK_VERSION,
+        },
+      },
+    });
+
+    // ── Root span ──
+    const totalTokensIn = childEvents.reduce((s, e) => s + (e.payload.tokens?.prompt || 0), 0);
+    const totalTokensOut = childEvents.reduce((s, e) => s + (e.payload.tokens?.completion || 0), 0);
+
+    const rootEvent: AgentEvent = {
+      runId: traceId,
+      agentId: name,
+      timestamp: now.toISOString(),
+      type: 'span',
+      payload: {
+        name: `${name}.execute`,
+        durationMs: totalDurationMs,
+        status: generationError ? 'error' : 'success',
+        error: generationError?.message?.slice(0, 500),
+        tokens: {
+          prompt: totalTokensIn || Math.round(estPrompt),
+          completion: totalTokensOut || Math.round(estCompletion),
+        },
+        costUsd: 0,
+        metadata: {
+          workflow_name: name,
+          framework: FRAMEWORK_NAME,
+          environment: safeEnv('NODE_ENV') || 'unknown',
+          input: prompt.slice(0, maxFieldLen),
+          output: finalOutput.slice(0, maxFieldLen),
+          span_id: rootSpanId,
+          trace_id: traceId,
+          node_type: 'workflow',
+          mastra_version: FRAMEWORK_VERSION,
+          ...(generationError ? { error_message: generationError.message.slice(0, 500) } : {}),
+        },
+      },
+    };
+
+    // ── Send all events via centralized client or standalone ──
+    const allEvents = [rootEvent, ...childEvents];
+
+    if (httpClient) {
+      await httpClient.emitEvents(allEvents);
+    } else if (apiKey && endpoint) {
+      await sendEventsStandalone(allEvents, endpoint, apiKey);
+    }
+
+    if (generationError) throw generationError;
+    return response;
+  };
+}
+
+/**
+ * Standalone fallback when no httpClient is available.
+ * Prefer passing httpClient for retries, timeouts, and consistent headers.
+ */
+const STANDALONE_TIMEOUT_MS = 10_000;
+const STANDALONE_MAX_PAYLOAD_BYTES = 5 * 1024 * 1024;
+
+async function sendEventsStandalone(
+  events: AgentEvent[],
+  baseUrl: string,
+  apiKey: string,
+): Promise<void> {
+  const url = `${baseUrl.replace(/\/$/, '')}/api/v1/sdk/events`;
+  const snakeEvents = toSnakeCaseDeep(events);
+  let body = JSON.stringify({ events: snakeEvents });
+  if (body.length > STANDALONE_MAX_PAYLOAD_BYTES && Array.isArray(snakeEvents) && (snakeEvents as unknown[]).length > 1) {
+    const arr = snakeEvents as unknown[];
+    const overhead = body.length - JSON.stringify(arr).length;
+    const avg = Math.ceil((body.length - overhead) / arr.length);
+    const target = Math.max(1, Math.floor((STANDALONE_MAX_PAYLOAD_BYTES - overhead) / avg));
+    body = JSON.stringify({ events: arr.slice(0, target) });
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), STANDALONE_TIMEOUT_MS);
+  try {
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': apiKey,
+        'X-SDK-Version': SDK_VERSION,
+        'X-SDK-Language': 'typescript',
+      },
+      body,
+      signal: controller.signal as AbortSignal,
+    });
+    if (!resp.ok) {
+      // eslint-disable-next-line no-console
+      console.warn(`TuringPulse telemetry FAILED: ${resp.status}`);
+    }
+  } catch (e) {
+    // eslint-disable-next-line no-console
+    console.warn(`TuringPulse telemetry ERROR: ${safeErrorMessage(e)}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export type { MastraInstrumentOptions, MastraToolCallRecord };

package/packages/openai/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@turingpulse/sdk-openai",
+  "version": "1.0.1",
+  "license": "SEE LICENSE IN LICENSE",
+  "description": "TuringPulse SDK integration for OpenAI (TypeScript)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@turingpulse/sdk": ">=1.0.0"
+  },
+  "peerDependencies": {
+    "openai": ">=4.0.0",
+    "typescript": ">=5.0.0"
+  }
+}

package/packages/openai/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * TuringPulse SDK integration for OpenAI (TypeScript).
+ *
+ * Provides patch/unpatch and Proxy patterns for intercepting
+ * OpenAI chat completion calls.
+ */
+
+export { patchOpenAI, unpatchOpenAI } from './wrapper';

package/packages/openai/src/wrapper.ts

@@ -0,0 +1,103 @@
+import { withInstrumentation, GovernanceDirective, ConfigurationError, currentContext } from '@turingpulse/sdk';
+
+let _originalCreate: unknown = null;
+let _patchedProto: Record<string, unknown> | null = null;
+
+interface PatchOpenAIOptions {
+  name?: string;
+  governance?: GovernanceDirective;
+  /**
+   * Pass your own imported OpenAI module to avoid module resolution mismatches.
+   * Accepts the default export class from `import OpenAI from 'openai'`
+   * or the full module namespace from `import * as mod from 'openai'`.
+   */
+  openaiModule?: unknown;
+}
+
+function resolveCompletionsProto(mod: unknown): Record<string, unknown> | undefined {
+  const cls = (mod as Record<string, unknown>)?.default ?? mod;
+  const chat = (cls as Record<string, unknown>)?.Chat as Record<string, unknown> | undefined;
+  const completions = chat?.Completions as Record<string, unknown> | undefined;
+  return completions?.prototype as Record<string, unknown> | undefined;
+}
+
+/**
+ * Monkey-patch OpenAI chat completions for TuringPulse instrumentation.
+ */
+export async function patchOpenAI(options: PatchOpenAIOptions = {}): Promise<void> {
+  const effectiveName = options.name || (typeof process !== 'undefined' ? process.env?.TP_WORKFLOW_NAME : undefined) || '';
+  if (!effectiveName) {
+    throw new ConfigurationError('patchOpenAI() requires name or TP_WORKFLOW_NAME env var.');
+  }
+
+  let completionsProto: Record<string, unknown> | undefined;
+
+  if (options.openaiModule) {
+    completionsProto = resolveCompletionsProto(options.openaiModule);
+  } else {
+    try {
+      const mod = await import('openai');
+      completionsProto = resolveCompletionsProto(mod);
+    } catch {
+      throw new Error('openai package is required: npm install openai');
+    }
+  }
+
+  if (!completionsProto) {
+    console.warn('Cannot locate OpenAI.Chat.Completions.prototype — skipping patch');
+    return;
+  }
+
+  if (_originalCreate !== null) {
+    console.warn('OpenAI is already patched — skipping duplicate patchOpenAI()');
+    return;
+  }
+
+  _originalCreate = completionsProto.create;
+  _patchedProto = completionsProto;
+
+  const wrappedCreate = withInstrumentation(
+    async function openaiCreate(this: unknown, ...args: unknown[]): Promise<unknown> {
+      const original = _originalCreate as (...args: unknown[]) => Promise<unknown>;
+      const response = await original.apply(this, args);
+
+      const ctx = currentContext();
+      if (ctx) {
+        ctx.framework = 'openai';
+        ctx.nodeType = 'llm';
+
+        const resp = response as Record<string, unknown>;
+        const usage = resp?.usage as { prompt_tokens?: number; completion_tokens?: number } | undefined;
+        if (usage) {
+          ctx.setTokens(usage.prompt_tokens ?? 0, usage.completion_tokens ?? 0);
+        }
+        const modelName = (resp?.model as string) ?? 'unknown';
+        ctx.setModel(modelName, 'openai');
+
+        const firstArg = args[0] as Record<string, unknown> | undefined;
+        if (firstArg?.messages) {
+          ctx.setIO(JSON.stringify(firstArg.messages), JSON.stringify(resp?.choices));
+        }
+      }
+
+      return response;
+    },
+    { name: effectiveName, governance: options.governance },
+  );
+
+  completionsProto.create = wrappedCreate;
+}
+
+/**
+ * Restore original OpenAI methods.
+ */
+export async function unpatchOpenAI(): Promise<void> {
+  if (_originalCreate === null) return;
+
+  if (_patchedProto) {
+    _patchedProto.create = _originalCreate;
+    _patchedProto = null;
+  }
+
+  _originalCreate = null;
+}

package/packages/openai/tsconfig.build.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "sourceMap": true,
+    "paths": {
+      "@turingpulse/sdk": ["../../src/index.ts"]
+    }
+  },
+  "include": ["src"]
+}

package/packages/openclaw/openclaw.plugin.json

@@ -0,0 +1,100 @@
+{
+  "id": "turingpulse",
+  "name": "TuringPulse Observability & Governance",
+  "version": "0.1.0",
+  "description": "Deterministic governance, observability, evaluations, and alerting for OpenClaw agents via TuringPulse",
+  "configSchema": {
+    "type": "object",
+    "required": ["apiKey"],
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "TuringPulse API key (scoped to a project)"
+      },
+      "endpoint": {
+        "type": "string",
+        "default": "https://api.turingpulse.ai",
+        "description": "TuringPulse API endpoint"
+      },
+      "governance": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable deterministic policy checks before tool execution"
+          },
+          "failMode": {
+            "type": "string",
+            "enum": ["open", "closed"],
+            "default": "open",
+            "description": "Behavior when TuringPulse is unreachable: 'open' allows execution, 'closed' blocks"
+          },
+          "timeoutMs": {
+            "type": "number",
+            "default": 3000,
+            "description": "Max time to wait for policy check response before applying failMode"
+          },
+          "excludeTools": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Tool names to skip governance checks for (e.g., safe read-only tools)"
+          },
+          "scanOutboundMessages": {
+            "type": "boolean",
+            "default": false,
+            "description": "Scan outgoing messages for PII before delivery to chat channels"
+          }
+        }
+      },
+      "telemetry": {
+        "type": "object",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": true,
+            "description": "Enable telemetry capture and emission"
+          },
+          "batchSize": {
+            "type": "number",
+            "default": 20,
+            "description": "Number of events to buffer before flushing"
+          },
+          "flushIntervalMs": {
+            "type": "number",
+            "default": 5000,
+            "description": "Max time between flushes in milliseconds"
+          },
+          "captureMessageContent": {
+            "type": "boolean",
+            "default": false,
+            "description": "Whether to capture message body text (disabled by default for privacy)"
+          },
+          "captureToolParams": {
+            "type": "boolean",
+            "default": true,
+            "description": "Whether to capture tool call parameters"
+          },
+          "redactPatterns": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Regex patterns to redact from captured content (applied to tool params, messages)"
+          }
+        }
+      },
+      "metadata": {
+        "type": "object",
+        "additionalProperties": { "type": "string" },
+        "description": "Static key-value metadata attached to all events (e.g., environment, team, deployment)"
+      }
+    }
+  },
+  "uiHints": {
+    "apiKey": { "label": "TuringPulse API Key", "sensitive": true },
+    "endpoint": { "label": "API Endpoint", "placeholder": "https://api.turingpulse.ai" },
+    "governance.enabled": { "label": "Enable Governance" },
+    "governance.failMode": { "label": "Fail Mode", "placeholder": "open" },
+    "telemetry.captureMessageContent": { "label": "Capture Message Content (privacy risk)" }
+  }
+}

package/packages/openclaw/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@turingpulse/sdk-openclaw",
+  "version": "1.0.1",
+  "description": "TuringPulse observability, governance, and alerting plugin for OpenClaw",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@turingpulse/sdk": ">=1.0.0",
+    "@turingpulse/interfaces": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.4",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ]
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json"
+  ],
+  "license": "SEE LICENSE IN LICENSE"
+}

package/packages/openclaw/src/buffer.ts

@@ -0,0 +1,99 @@
+/**
+ * Event buffer that batches AgentEvents and flushes them to TuringPulse.
+ *
+ * Flushes on three triggers:
+ * 1. Batch size reached (configurable, default 20)
+ * 2. Timer interval (configurable, default 5s)
+ * 3. Explicit flush (called on message_sent and gateway shutdown)
+ *
+ * Silently drops events on persistent failure — never crashes the host.
+ */
+
+import type { AgentEvent } from '@turingpulse/interfaces';
+import type { TuringPulseHttpClient } from '@turingpulse/sdk';
+
+const MAX_BUFFER_SIZE = 500;
+
+export class EventBuffer {
+  private buffer: AgentEvent[] = [];
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private flushing = false;
+
+  constructor(
+    private readonly client: TuringPulseHttpClient,
+    private readonly batchSize: number,
+    private readonly flushIntervalMs: number,
+  ) {}
+
+  /** Start the periodic flush timer. Call once during plugin init. */
+  start(): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.flushIntervalMs);
+
+    if (typeof this.timer === 'object' && 'unref' in this.timer) {
+      this.timer.unref();
+    }
+  }
+
+  /** Stop the periodic flush timer and drain remaining events. */
+  async stop(): Promise<void> {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    await this.flush();
+  }
+
+  /**
+   * Add an event to the buffer. Triggers a flush if batch size is reached.
+   */
+  push(event: AgentEvent): void {
+    if (this.buffer.length >= MAX_BUFFER_SIZE) {
+      this.buffer.shift();
+    }
+    this.buffer.push(event);
+
+    if (this.buffer.length >= this.batchSize) {
+      void this.flush();
+    }
+  }
+
+  /**
+   * Add multiple events to the buffer.
+   */
+  pushMany(events: AgentEvent[]): void {
+    for (const event of events) {
+      this.push(event);
+    }
+  }
+
+  /**
+   * Flush all buffered events to TuringPulse. Safe to call concurrently
+   * — uses a flushing guard to prevent overlapping requests.
+   */
+  async flush(): Promise<void> {
+    if (this.flushing || this.buffer.length === 0) return;
+
+    this.flushing = true;
+    const batch = this.buffer.splice(0);
+
+    try {
+      await this.client.emitEvents(batch);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[turingpulse] Failed to flush ${batch.length} events:`,
+        err instanceof Error ? err.message : String(err),
+      );
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  /** Number of events currently buffered (for health/status reporting). */
+  get pending(): number {
+    return this.buffer.length;
+  }
+}