@turingpulse/sdk 1.0.1

package/packages/openclaw/tests/governance.test.ts

@@ -0,0 +1,232 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { registerGovernanceHooks } from '../src/hooks/governance.js';
+import { SessionTracker } from '../src/session-tracker.js';
+import type { TuringPulseOpenClawConfig } from '../src/config.js';
+import type { OpenClawPluginAPI } from '../src/types.js';
+
+function makeConfig(overrides?: Partial<TuringPulseOpenClawConfig['governance']>): TuringPulseOpenClawConfig {
+  return {
+    apiKey: 'tp-test-key',
+    endpoint: 'https://api.turingpulse.ai',
+    governance: {
+      enabled: true,
+      failMode: 'open',
+      timeoutMs: 3000,
+      excludeTools: [],
+      scanOutboundMessages: false,
+      ...overrides,
+    },
+    telemetry: {
+      enabled: true,
+      batchSize: 20,
+      flushIntervalMs: 5000,
+      captureMessageContent: false,
+      captureToolParams: true,
+      redactPatterns: [],
+    },
+    metadata: {},
+  };
+}
+
+function makeMockApi() {
+  const handlers = new Map<string, (ctx: unknown) => Promise<unknown>>();
+  const api: OpenClawPluginAPI = {
+    config: {},
+    lifecycle: {
+      on: vi.fn((phase: string, handler: (ctx: unknown) => Promise<unknown>) => {
+        handlers.set(phase, handler);
+      }),
+    },
+    registerHook: vi.fn(),
+    registerCommand: vi.fn(),
+  };
+  return { api, handlers };
+}
+
+function makeMockClient(response?: { action: string; triggered: boolean; reason?: string; policyIds: string[] }) {
+  return {
+    policyCheck: vi.fn().mockResolvedValue(
+      response ?? { action: 'allow', triggered: false, policyIds: [] },
+    ),
+  };
+}
+
+describe('governance hooks', () => {
+  let sessionTracker: SessionTracker;
+
+  beforeEach(() => {
+    sessionTracker = new SessionTracker();
+  });
+
+  it('registers tool.pre hook when governance is enabled', () => {
+    const { api } = makeMockApi();
+    const client = makeMockClient();
+    const config = makeConfig();
+
+    registerGovernanceHooks(api, client as never, config, sessionTracker);
+
+    expect(api.lifecycle.on).toHaveBeenCalledWith(
+      'tool.pre',
+      expect.any(Function),
+      expect.objectContaining({ priority: 1000 }),
+    );
+  });
+
+  it('does not register hooks when governance is disabled', () => {
+    const { api } = makeMockApi();
+    const client = makeMockClient();
+    const config = makeConfig({ enabled: false });
+
+    registerGovernanceHooks(api, client as never, config, sessionTracker);
+
+    expect(api.lifecycle.on).not.toHaveBeenCalled();
+  });
+
+  it('allows tool execution when policy returns allow', async () => {
+    const { api, handlers } = makeMockApi();
+    const client = makeMockClient({ action: 'allow', triggered: false, policyIds: [] });
+    const config = makeConfig();
+
+    registerGovernanceHooks(api, client as never, config, sessionTracker);
+
+    const handler = handlers.get('tool.pre')!;
+    const result = await handler({
+      toolName: 'exec',
+      toolParams: { command: 'git status' },
+      sessionKey: 'sess-1',
+    });
+
+    expect(result).toBeUndefined();
+    expect(client.policyCheck).toHaveBeenCalledTimes(1);
+  });
+
+  it('cancels tool execution when policy returns block', async () => {
+    const { api, handlers } = makeMockApi();
+    const client = makeMockClient({
+      action: 'block',
+      triggered: true,
+      reason: 'Dangerous command detected',
+      policyIds: ['policy-1'],
+    });
+    const config = makeConfig();
+
+    registerGovernanceHooks(api, client as never, config, sessionTracker);
+
+    const handler = handlers.get('tool.pre')!;
+    const result = await handler({
+      toolName: 'exec',
+      toolParams: { command: 'rm -rf /' },
+      sessionKey: 'sess-1',
+    });
+
+    expect(result).toEqual({ cancel: true });
+  });
+
+  it('allows execution on flag (but logs it)', async () => {
+    const { api, handlers } = makeMockApi();
+    const client = makeMockClient({
+      action: 'flag',
+      triggered: true,
+      reason: 'Potentially risky operation',
+      policyIds: ['policy-2'],
+    });
+    const config = makeConfig();
+
+    registerGovernanceHooks(api, client as never, config, sessionTracker);
+
+    const handler = handlers.get('tool.pre')!;
+    const result = await handler({
+      toolName: 'exec',
+      toolParams: { command: 'sudo apt update' },
+      sessionKey: 'sess-1',
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it('skips excluded tools', async () => {
+    const { api, handlers } = makeMockApi();
+    const client = makeMockClient();
+    const config = makeConfig({ excludeTools: ['jq', 'cat'] });
+
+    registerGovernanceHooks(api, client as never, config, sessionTracker);
+
+    const handler = handlers.get('tool.pre')!;
+    const result = await handler({
+      toolName: 'cat',
+      toolParams: { file: '/tmp/test.txt' },
+    });
+
+    expect(result).toBeUndefined();
+    expect(client.policyCheck).not.toHaveBeenCalled();
+  });
+
+  it('fail-open: allows execution when policyCheck throws', async () => {
+    const { api, handlers } = makeMockApi();
+    const client = makeMockClient();
+    client.policyCheck.mockRejectedValueOnce(new Error('network timeout'));
+    const config = makeConfig({ failMode: 'open' });
+
+    registerGovernanceHooks(api, client as never, config, sessionTracker);
+
+    const handler = handlers.get('tool.pre')!;
+    const result = await handler({
+      toolName: 'exec',
+      toolParams: { command: 'ls' },
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it('fail-closed: blocks execution when policyCheck throws', async () => {
+    const { api, handlers } = makeMockApi();
+    const client = makeMockClient();
+    client.policyCheck.mockRejectedValueOnce(new Error('network timeout'));
+    const config = makeConfig({ failMode: 'closed' });
+
+    registerGovernanceHooks(api, client as never, config, sessionTracker);
+
+    const handler = handlers.get('tool.pre')!;
+    const result = await handler({
+      toolName: 'exec',
+      toolParams: { command: 'ls' },
+    });
+
+    expect(result).toEqual({ cancel: true });
+  });
+
+  it('includes session cost in policy check params', async () => {
+    const { api, handlers } = makeMockApi();
+    const client = makeMockClient();
+    const config = makeConfig();
+
+    registerGovernanceHooks(api, client as never, config, sessionTracker);
+
+    sessionTracker.start('sess-1', 'trace-1', 'root-1');
+    sessionTracker.addMetrics('sess-1', { costUsd: 2.50 });
+
+    const handler = handlers.get('tool.pre')!;
+    await handler({
+      toolName: 'exec',
+      toolParams: { command: 'deploy.sh' },
+      sessionKey: 'sess-1',
+    });
+
+    const checkParams = client.policyCheck.mock.calls[0][0];
+    expect(checkParams.costUsd).toBe(2.50);
+    expect(checkParams.runId).toBe('trace-1');
+  });
+
+  it('registers message.pre hook when scanOutboundMessages is enabled', () => {
+    const { api } = makeMockApi();
+    const client = makeMockClient();
+    const config = makeConfig({ scanOutboundMessages: true });
+
+    registerGovernanceHooks(api, client as never, config, sessionTracker);
+
+    const phases = (api.lifecycle.on as ReturnType<typeof vi.fn>).mock.calls.map(
+      (call: unknown[]) => call[0],
+    );
+    expect(phases).toContain('message.pre');
+  });
+});

package/packages/openclaw/tests/mapper.test.ts

@@ -0,0 +1,242 @@
+import { describe, it, expect } from 'vitest';
+import { buildRootSpan, buildToolSpan, buildAgentReasoningSpan } from '../src/mapper.js';
+import type { SessionState } from '../src/session-tracker.js';
+import type { TuringPulseOpenClawConfig } from '../src/config.js';
+import type { ToolPostContext, AgentPostContext } from '../src/types.js';
+
+function makeConfig(overrides?: Partial<TuringPulseOpenClawConfig['telemetry']>): TuringPulseOpenClawConfig {
+  return {
+    apiKey: 'tp-test',
+    endpoint: 'https://api.turingpulse.ai',
+    governance: {
+      enabled: true,
+      failMode: 'open',
+      timeoutMs: 3000,
+      excludeTools: [],
+      scanOutboundMessages: false,
+    },
+    telemetry: {
+      enabled: true,
+      batchSize: 20,
+      flushIntervalMs: 5000,
+      captureMessageContent: false,
+      captureToolParams: true,
+      redactPatterns: [],
+      ...overrides,
+    },
+    metadata: { environment: 'test' },
+  };
+}
+
+function makeSession(overrides?: Partial<SessionState>): SessionState {
+  return {
+    traceId: 'trace-abc',
+    rootSpanId: 'root-123',
+    startedAt: Date.now() - 1000,
+    childEvents: [],
+    channelId: 'whatsapp',
+    agentId: 'agent-pi',
+    tokens: { prompt: 500, completion: 200 },
+    costUsd: 0.05,
+    toolCallCount: 3,
+    currentDepth: 0,
+    ...overrides,
+  };
+}
+
+describe('buildRootSpan', () => {
+  it('creates a root workflow span with correct structure', () => {
+    const session = makeSession();
+    const config = makeConfig();
+
+    const event = buildRootSpan(session, config, {
+      status: 'success',
+    });
+
+    expect(event.runId).toBe('trace-abc');
+    expect(event.agentId).toBe('agent-pi');
+    expect(event.type).toBe('span');
+    expect(event.workflowName).toBe('agent-pi');
+    expect(event.payload.name).toBe('agent-pi.execute');
+    expect(event.payload.status).toBe('success');
+    expect(event.payload.tokens).toEqual({ prompt: 500, completion: 200 });
+    expect(event.payload.costUsd).toBe(0.05);
+    expect(event.payload.durationMs).toBeGreaterThan(0);
+
+    const meta = event.payload.metadata!;
+    expect(meta.framework).toBe('openclaw');
+    expect(meta.node_type).toBe('workflow');
+    expect(meta.trace_id).toBe('trace-abc');
+    expect(meta.span_id).toBe('root-123');
+    expect(meta.channel).toBe('whatsapp');
+    expect(meta.environment).toBe('test');
+  });
+
+  it('includes error in metadata when status is error', () => {
+    const session = makeSession();
+    const config = makeConfig();
+
+    const event = buildRootSpan(session, config, {
+      status: 'error',
+      error: 'Agent crashed',
+    });
+
+    expect(event.payload.status).toBe('error');
+    expect(event.payload.metadata!.error_message).toBe('Agent crashed');
+  });
+
+  it('omits message content when captureMessageContent is false', () => {
+    const session = makeSession();
+    const config = makeConfig({ captureMessageContent: false });
+
+    const event = buildRootSpan(session, config, {
+      inputText: 'secret user message',
+      outputText: 'secret response',
+      status: 'success',
+    });
+
+    expect(event.payload.metadata!.input).toBeUndefined();
+    expect(event.payload.metadata!.output).toBeUndefined();
+  });
+
+  it('includes message content when captureMessageContent is true', () => {
+    const session = makeSession();
+    const config = makeConfig({ captureMessageContent: true });
+
+    const event = buildRootSpan(session, config, {
+      inputText: 'hello world',
+      outputText: 'hi there',
+      status: 'success',
+    });
+
+    expect(event.payload.metadata!.input).toBe('hello world');
+    expect(event.payload.metadata!.output).toBe('hi there');
+  });
+
+  it('falls back to default agent name when agentId is missing', () => {
+    const session = makeSession({ agentId: undefined });
+    const config = makeConfig();
+
+    const event = buildRootSpan(session, config, { status: 'success' });
+
+    expect(event.agentId).toBe('openclaw-agent');
+    expect(event.payload.name).toBe('openclaw-agent.execute');
+  });
+});
+
+describe('buildToolSpan', () => {
+  it('creates a tool child span with correct structure', () => {
+    const session = makeSession();
+    const config = makeConfig();
+    const ctx: ToolPostContext = {
+      toolName: 'exec',
+      toolParams: { command: 'git status' },
+      result: 'On branch main',
+      durationMs: 250,
+      sessionKey: 'sess-1',
+    };
+
+    const event = buildToolSpan(ctx, session, 'span-tool-1', config);
+
+    expect(event.runId).toBe('trace-abc');
+    expect(event.agentId).toBe('tool_exec');
+    expect(event.type).toBe('span');
+    expect(event.payload.name).toBe('agent-pi.tool_exec');
+    expect(event.payload.status).toBe('success');
+    expect(event.payload.durationMs).toBe(250);
+
+    const meta = event.payload.metadata!;
+    expect(meta.span_id).toBe('span-tool-1');
+    expect(meta.parent_span_id).toBe('root-123');
+    expect(meta.trace_id).toBe('trace-abc');
+    expect(meta.node_type).toBe('tool');
+    expect(meta.tool_name).toBe('exec');
+    expect(meta.input).toContain('git status');
+
+    expect(event.payload.toolCalls).toHaveLength(1);
+    expect(event.payload.toolCalls![0].toolName).toBe('exec');
+    expect(event.payload.toolCalls![0].success).toBe(true);
+  });
+
+  it('marks tool span as error when ctx.error is present', () => {
+    const session = makeSession();
+    const config = makeConfig();
+    const ctx: ToolPostContext = {
+      toolName: 'exec',
+      toolParams: { command: 'bad-command' },
+      result: null,
+      error: new Error('command not found'),
+      sessionKey: 'sess-1',
+    };
+
+    const event = buildToolSpan(ctx, session, 'span-err', config);
+
+    expect(event.payload.status).toBe('error');
+    expect(event.payload.metadata!.error_message).toBe('command not found');
+    expect(event.payload.toolCalls![0].success).toBe(false);
+  });
+
+  it('omits tool params when captureToolParams is false', () => {
+    const session = makeSession();
+    const config = makeConfig({ captureToolParams: false });
+    const ctx: ToolPostContext = {
+      toolName: 'exec',
+      toolParams: { command: 'secret-command' },
+      result: 'done',
+      sessionKey: 'sess-1',
+    };
+
+    const event = buildToolSpan(ctx, session, 'span-1', config);
+
+    expect(event.payload.metadata!.input).toBeUndefined();
+    expect(event.payload.toolCalls![0].toolArgs).toEqual({});
+  });
+});
+
+describe('buildAgentReasoningSpan', () => {
+  it('creates an LLM reasoning span with token counts', () => {
+    const session = makeSession();
+    const config = makeConfig();
+    const ctx: AgentPostContext = {
+      sessionKey: 'sess-1',
+      model: 'anthropic/claude-sonnet-4-5',
+      usage: { promptTokens: 400, completionTokens: 150 },
+      durationMs: 2000,
+    };
+
+    const event = buildAgentReasoningSpan(ctx, session, 'span-llm-1', config);
+
+    expect(event.payload.name).toBe('agent-pi.agent_reasoning');
+    expect(event.payload.tokens).toEqual({ prompt: 400, completion: 150 });
+    expect(event.payload.durationMs).toBe(2000);
+
+    const meta = event.payload.metadata!;
+    expect(meta.node_type).toBe('llm');
+    expect(meta.model).toBe('anthropic/claude-sonnet-4-5');
+    expect(meta.provider).toBe('anthropic');
+  });
+
+  it('infers provider from model string', () => {
+    const session = makeSession();
+    const config = makeConfig();
+
+    const cases = [
+      { model: 'openai/gpt-4o', expected: 'openai' },
+      { model: 'anthropic/claude-sonnet-4-5', expected: 'anthropic' },
+      { model: 'google/gemini-2.5-pro', expected: 'google' },
+      { model: 'gpt-4o', expected: 'openai' },
+      { model: 'claude-sonnet-4-5', expected: 'anthropic' },
+      { model: undefined, expected: 'unknown' },
+    ];
+
+    for (const { model, expected } of cases) {
+      const event = buildAgentReasoningSpan(
+        { sessionKey: 'sess-1', model } as AgentPostContext,
+        session,
+        'span-1',
+        config,
+      );
+      expect(event.payload.metadata!.provider).toBe(expected);
+    }
+  });
+});

package/packages/openclaw/tests/session-tracker.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from 'vitest';
+import { SessionTracker } from '../src/session-tracker.js';
+
+describe('SessionTracker', () => {
+  it('starts and retrieves a session', () => {
+    const tracker = new SessionTracker();
+    const session = tracker.start('sess-1', 'trace-1', 'root-1', 'whatsapp', 'agent-pi');
+
+    expect(session.traceId).toBe('trace-1');
+    expect(session.rootSpanId).toBe('root-1');
+    expect(session.channelId).toBe('whatsapp');
+    expect(session.agentId).toBe('agent-pi');
+    expect(session.tokens).toEqual({ prompt: 0, completion: 0 });
+    expect(session.costUsd).toBe(0);
+    expect(session.toolCallCount).toBe(0);
+    expect(session.childEvents).toEqual([]);
+
+    const retrieved = tracker.get('sess-1');
+    expect(retrieved).toBe(session);
+  });
+
+  it('returns undefined for unknown session', () => {
+    const tracker = new SessionTracker();
+    expect(tracker.get('unknown')).toBeUndefined();
+  });
+
+  it('accumulates metrics', () => {
+    const tracker = new SessionTracker();
+    tracker.start('sess-1', 'trace-1', 'root-1');
+
+    tracker.addMetrics('sess-1', { promptTokens: 100, completionTokens: 50, costUsd: 0.01, toolCalls: 1 });
+    tracker.addMetrics('sess-1', { promptTokens: 200, completionTokens: 80, costUsd: 0.02, toolCalls: 2 });
+
+    const session = tracker.get('sess-1')!;
+    expect(session.tokens.prompt).toBe(300);
+    expect(session.tokens.completion).toBe(130);
+    expect(session.costUsd).toBeCloseTo(0.03);
+    expect(session.toolCallCount).toBe(3);
+  });
+
+  it('ignores metrics for unknown session', () => {
+    const tracker = new SessionTracker();
+    expect(() => tracker.addMetrics('unknown', { promptTokens: 100 })).not.toThrow();
+  });
+
+  it('adds child events', () => {
+    const tracker = new SessionTracker();
+    tracker.start('sess-1', 'trace-1', 'root-1');
+
+    const event = {
+      runId: 'trace-1',
+      agentId: 'tool_exec',
+      timestamp: new Date().toISOString(),
+      type: 'span' as const,
+      payload: { name: 'test.tool_exec' },
+    };
+
+    tracker.addChildEvent('sess-1', event);
+    expect(tracker.get('sess-1')!.childEvents).toHaveLength(1);
+  });
+
+  it('finishes a session and returns accumulated state', () => {
+    const tracker = new SessionTracker();
+    tracker.start('sess-1', 'trace-1', 'root-1');
+    tracker.addMetrics('sess-1', { toolCalls: 3 });
+
+    const finished = tracker.finish('sess-1');
+    expect(finished).toBeDefined();
+    expect(finished!.toolCallCount).toBe(3);
+
+    expect(tracker.get('sess-1')).toBeUndefined();
+    expect(tracker.size).toBe(0);
+  });
+
+  it('returns undefined when finishing unknown session', () => {
+    const tracker = new SessionTracker();
+    expect(tracker.finish('unknown')).toBeUndefined();
+  });
+
+  it('enforces capacity limit via LRU eviction', () => {
+    const tracker = new SessionTracker(3);
+
+    tracker.start('sess-1', 't1', 'r1');
+    tracker.start('sess-2', 't2', 'r2');
+    tracker.start('sess-3', 't3', 'r3');
+
+    expect(tracker.size).toBe(3);
+
+    tracker.start('sess-4', 't4', 'r4');
+
+    expect(tracker.size).toBe(3);
+    expect(tracker.get('sess-1')).toBeUndefined();
+    expect(tracker.get('sess-4')).toBeDefined();
+  });
+
+  it('LRU eviction respects access order', () => {
+    const tracker = new SessionTracker(3);
+
+    tracker.start('sess-1', 't1', 'r1');
+    tracker.start('sess-2', 't2', 'r2');
+    tracker.start('sess-3', 't3', 'r3');
+
+    tracker.get('sess-1');
+
+    tracker.start('sess-4', 't4', 'r4');
+
+    expect(tracker.get('sess-1')).toBeDefined();
+    expect(tracker.get('sess-2')).toBeUndefined();
+  });
+
+  it('reports size correctly', () => {
+    const tracker = new SessionTracker();
+    expect(tracker.size).toBe(0);
+
+    tracker.start('sess-1', 't1', 'r1');
+    expect(tracker.size).toBe(1);
+
+    tracker.start('sess-2', 't2', 'r2');
+    expect(tracker.size).toBe(2);
+
+    tracker.finish('sess-1');
+    expect(tracker.size).toBe(1);
+  });
+});

package/packages/openclaw/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"]
+}

package/packages/openclaw/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+    environment: 'node',
+  },
+});

package/packages/vercel-ai/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@turingpulse/sdk-vercel-ai",
+  "version": "1.0.1",
+  "license": "SEE LICENSE IN LICENSE",
+  "description": "TuringPulse SDK integration for Vercel AI SDK",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@turingpulse/sdk": ">=1.0.0"
+  },
+  "peerDependencies": {
+    "ai": ">=6.0.0",
+    "typescript": ">=5.0.0"
+  }
+}

package/packages/vercel-ai/src/index.ts

@@ -0,0 +1,5 @@
+/**
+ * TuringPulse SDK integration for Vercel AI SDK.
+ */
+
+export { instrumentVercelAI } from './wrapper';

package/packages/vercel-ai/src/wrapper.ts

@@ -0,0 +1,49 @@
+import { withInstrumentation, GovernanceDirective, currentContext } from '@turingpulse/sdk';
+
+interface VercelAIInstrumentOptions {
+  name: string;
+  governance?: GovernanceDirective;
+  model?: string;
+  provider?: string;
+}
+
+/**
+ * Wrap Vercel AI SDK's generateText/streamText for TuringPulse observability.
+ */
+export function instrumentVercelAI(
+  generateFn: (...args: unknown[]) => Promise<unknown>,
+  options: VercelAIInstrumentOptions,
+): (...args: unknown[]) => Promise<unknown> {
+  const { name, governance, model, provider = 'openai' } = options;
+
+  const wrappedFn = withInstrumentation(
+    async function vercelAIGenerate(...args: unknown[]): Promise<unknown> {
+      const result = await generateFn(...args);
+
+      const ctx = currentContext();
+      if (ctx) {
+        ctx.framework = 'vercel-ai';
+        ctx.nodeType = 'llm';
+
+        const resp = result as Record<string, unknown>;
+        const usage = resp?.usage as { promptTokens?: number; completionTokens?: number } | undefined;
+        if (usage) {
+          ctx.setTokens(usage.promptTokens ?? 0, usage.completionTokens ?? 0);
+        }
+        if (model) {
+          ctx.setModel(model, provider);
+        }
+
+        const firstArg = args[0] as Record<string, unknown> | undefined;
+        const inputStr = (firstArg?.prompt as string) ?? JSON.stringify(firstArg);
+        const outputStr = (resp?.text as string) ?? JSON.stringify(result);
+        ctx.setIO(inputStr, outputStr);
+      }
+
+      return result;
+    },
+    { name, governance },
+  );
+
+  return wrappedFn as (...args: unknown[]) => Promise<unknown>;
+}