@turingpulse/sdk 1.0.1

package/packages/openclaw/src/types.ts

@@ -0,0 +1,220 @@
+/**
+ * Type definitions for OpenClaw plugin API and hook contexts.
+ *
+ * These mirror the OpenClaw plugin SDK interfaces. Since OpenClaw
+ * may not publish stable type packages yet, we define the subset
+ * we depend on here.
+ */
+
+// ---------------------------------------------------------------------------
+// Hook context types — what OpenClaw passes to lifecycle hooks
+// ---------------------------------------------------------------------------
+
+export interface ToolPreContext {
+  /** Name of the tool being invoked (e.g., "exec", "browser", "file_write"). */
+  toolName: string;
+  /** Parameters passed to the tool. */
+  toolParams: Record<string, unknown>;
+  /** OpenClaw session key (unique per sender+agent+workspace). */
+  sessionKey?: string;
+  /** Numeric or string session identifier. */
+  sessionId?: string;
+  /** Channel the message originated from (e.g., "whatsapp", "telegram"). */
+  channelId?: string;
+  /** Agent identifier within the gateway. */
+  agentId?: string;
+}
+
+export interface ToolPostContext {
+  toolName: string;
+  toolParams: Record<string, unknown>;
+  /** Result returned by the tool. */
+  result: unknown;
+  /** Error thrown during tool execution, if any. */
+  error?: Error;
+  /** Duration of the tool execution in milliseconds. */
+  durationMs?: number;
+  sessionKey?: string;
+  sessionId?: string;
+  channelId?: string;
+  agentId?: string;
+}
+
+export interface MessageReceivedContext {
+  type: 'message';
+  action: 'received';
+  sessionKey: string;
+  timestamp: Date;
+  messages: string[];
+  context: {
+    from: string;
+    content: string;
+    timestamp?: number;
+    channelId: string;
+    accountId?: string;
+    conversationId?: string;
+    messageId?: string;
+    metadata?: {
+      to?: string;
+      provider?: string;
+      surface?: string;
+      threadId?: string;
+      senderId?: string;
+      senderName?: string;
+      senderUsername?: string;
+      senderE164?: string;
+    };
+  };
+}
+
+export interface MessageSendingContext {
+  type: 'message';
+  action: 'sending';
+  sessionKey?: string;
+  sessionId?: string;
+  timestamp: Date;
+  messages: string[];
+  context: {
+    to: string;
+    content: string;
+    channelId: string;
+    accountId?: string;
+    conversationId?: string;
+  };
+}
+
+export interface MessageSentContext {
+  type: 'message';
+  action: 'sent';
+  sessionKey?: string;
+  sessionId?: string;
+  timestamp: Date;
+  messages: string[];
+  context: {
+    to: string;
+    content: string;
+    success: boolean;
+    error?: string;
+    channelId: string;
+    accountId?: string;
+    conversationId?: string;
+    messageId?: string;
+  };
+}
+
+export interface AgentPreContext {
+  sessionKey?: string;
+  sessionId?: string;
+  channelId?: string;
+  agentId?: string;
+  /** Model being used for this agent turn. */
+  model?: string;
+}
+
+export interface AgentPostContext {
+  sessionKey?: string;
+  sessionId?: string;
+  channelId?: string;
+  agentId?: string;
+  model?: string;
+  /** Token usage reported by the agent runtime, if available. */
+  usage?: {
+    promptTokens?: number;
+    completionTokens?: number;
+  };
+  /** Duration of the agent turn in milliseconds. */
+  durationMs?: number;
+  error?: Error;
+}
+
+export interface GatewayStartContext {
+  /** Gateway configuration object. */
+  config?: Record<string, unknown>;
+}
+
+export interface GatewayStopContext {
+  /** Reason for shutdown (e.g., "SIGTERM", "manual"). */
+  reason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Hook return types — what the plugin can return to modify behavior
+// ---------------------------------------------------------------------------
+
+export interface ToolPreResult {
+  /** If true, the tool call is cancelled and not executed. */
+  cancel?: boolean;
+  /** Optionally replace tool parameters. */
+  params?: Record<string, unknown>;
+}
+
+export interface MessageSendingResult {
+  /** If true, the outgoing message is cancelled. */
+  cancel?: boolean;
+  /** Optionally rewrite the message content. */
+  content?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Hook registration options
+// ---------------------------------------------------------------------------
+
+export interface HookOptions {
+  /** Execution priority (higher = earlier). */
+  priority?: number;
+  /** Hook timeout in milliseconds. */
+  timeoutMs?: number;
+  /** Behavior on hook error. */
+  mode?: 'fail-open' | 'fail-closed';
+  /** Behavior on hook timeout. */
+  onTimeout?: 'fail-open' | 'fail-closed';
+  /** Retry configuration. */
+  retry?: {
+    count: number;
+    backoffMs?: number;
+  };
+  /** Filter scope. */
+  scope?: {
+    channels?: string[];
+    agentIds?: string[];
+    toolNames?: string[];
+  };
+  /** Custom filter predicate. */
+  condition?: (context: unknown) => boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin API — the `api` object OpenClaw passes to register()
+// ---------------------------------------------------------------------------
+
+export interface OpenClawLifecycleAPI {
+  on(
+    phase: string,
+    handler: (context: unknown) => Promise<unknown> | unknown,
+    options?: HookOptions,
+  ): void;
+}
+
+export interface OpenClawCommandRegistration {
+  name: string;
+  description: string;
+  handler: (ctx: { channel?: string; sessionKey?: string }) => { text: string };
+}
+
+export interface OpenClawPluginAPI {
+  /** Plugin configuration from openclaw.json entries. */
+  config: Record<string, unknown>;
+
+  /** Lifecycle hook registration. */
+  lifecycle: OpenClawLifecycleAPI;
+
+  /** Basic hook registration for command events. */
+  registerHook(
+    event: string,
+    handler: (event: unknown) => Promise<void> | void,
+    meta?: { name?: string; description?: string },
+  ): void;
+
+  /** Register a slash command. */
+  registerCommand(registration: OpenClawCommandRegistration): void;
+}

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

@@ -0,0 +1,148 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { EventBuffer } from '../src/buffer.js';
+import type { AgentEvent } from '@turingpulse/interfaces';
+
+function makeEvent(id: string): AgentEvent {
+  return {
+    runId: `run-${id}`,
+    agentId: `agent-${id}`,
+    timestamp: new Date().toISOString(),
+    type: 'span',
+    payload: { name: `test-${id}` },
+  };
+}
+
+function makeMockClient() {
+  return {
+    emitEvents: vi.fn().mockResolvedValue(undefined),
+    maxSerializedFieldLength: 50_000,
+  };
+}
+
+describe('EventBuffer', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('buffers events and flushes when batch size reached', async () => {
+    const client = makeMockClient();
+    const buffer = new EventBuffer(client as never, 3, 60_000);
+
+    buffer.push(makeEvent('1'));
+    buffer.push(makeEvent('2'));
+    expect(client.emitEvents).not.toHaveBeenCalled();
+
+    buffer.push(makeEvent('3'));
+
+    await vi.waitFor(() => {
+      expect(client.emitEvents).toHaveBeenCalledTimes(1);
+    });
+
+    const sentEvents = client.emitEvents.mock.calls[0][0];
+    expect(sentEvents).toHaveLength(3);
+  });
+
+  it('flushes on explicit flush call', async () => {
+    const client = makeMockClient();
+    const buffer = new EventBuffer(client as never, 100, 60_000);
+
+    buffer.push(makeEvent('1'));
+    buffer.push(makeEvent('2'));
+
+    await buffer.flush();
+
+    expect(client.emitEvents).toHaveBeenCalledTimes(1);
+    expect(client.emitEvents.mock.calls[0][0]).toHaveLength(2);
+  });
+
+  it('does nothing when flushing empty buffer', async () => {
+    const client = makeMockClient();
+    const buffer = new EventBuffer(client as never, 10, 60_000);
+
+    await buffer.flush();
+    expect(client.emitEvents).not.toHaveBeenCalled();
+  });
+
+  it('flushes on interval timer', async () => {
+    const client = makeMockClient();
+    const buffer = new EventBuffer(client as never, 100, 1000);
+
+    buffer.start();
+    buffer.push(makeEvent('1'));
+
+    vi.advanceTimersByTime(1100);
+
+    await vi.waitFor(() => {
+      expect(client.emitEvents).toHaveBeenCalledTimes(1);
+    });
+
+    await buffer.stop();
+  });
+
+  it('reports pending count', () => {
+    const client = makeMockClient();
+    const buffer = new EventBuffer(client as never, 100, 60_000);
+
+    expect(buffer.pending).toBe(0);
+
+    buffer.push(makeEvent('1'));
+    buffer.push(makeEvent('2'));
+    expect(buffer.pending).toBe(2);
+  });
+
+  it('pushMany adds multiple events', async () => {
+    const client = makeMockClient();
+    const buffer = new EventBuffer(client as never, 100, 60_000);
+
+    buffer.pushMany([makeEvent('1'), makeEvent('2'), makeEvent('3')]);
+    expect(buffer.pending).toBe(3);
+
+    await buffer.flush();
+    expect(client.emitEvents.mock.calls[0][0]).toHaveLength(3);
+  });
+
+  it('silently handles emit errors without crashing', async () => {
+    const client = makeMockClient();
+    client.emitEvents.mockRejectedValueOnce(new Error('network failure'));
+
+    const buffer = new EventBuffer(client as never, 2, 60_000);
+    buffer.push(makeEvent('1'));
+    buffer.push(makeEvent('2'));
+
+    await vi.waitFor(() => {
+      expect(client.emitEvents).toHaveBeenCalled();
+    });
+
+    expect(buffer.pending).toBe(0);
+  });
+
+  it('stop drains remaining events', async () => {
+    const client = makeMockClient();
+    const buffer = new EventBuffer(client as never, 100, 1000);
+
+    buffer.start();
+    buffer.push(makeEvent('1'));
+    buffer.push(makeEvent('2'));
+
+    await buffer.stop();
+
+    expect(client.emitEvents).toHaveBeenCalledTimes(1);
+    expect(client.emitEvents.mock.calls[0][0]).toHaveLength(2);
+    expect(buffer.pending).toBe(0);
+  });
+
+  it('caps buffer at MAX_BUFFER_SIZE by dropping oldest events', () => {
+    const client = makeMockClient();
+    const buffer = new EventBuffer(client as never, 1000, 60_000);
+
+    for (let i = 0; i < 510; i++) {
+      buffer.push(makeEvent(String(i)));
+    }
+
+    expect(buffer.pending).toBe(500);
+  });
+});

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

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest';
+import { resolveConfig, compileRedactPatterns } from '../src/config.js';
+
+describe('resolveConfig', () => {
+  it('resolves a minimal valid config with defaults', () => {
+    const config = resolveConfig({ apiKey: 'tp-abc123' });
+
+    expect(config.apiKey).toBe('tp-abc123');
+    expect(config.endpoint).toBe('https://api.turingpulse.ai');
+    expect(config.governance.enabled).toBe(true);
+    expect(config.governance.failMode).toBe('open');
+    expect(config.governance.timeoutMs).toBe(3000);
+    expect(config.governance.excludeTools).toEqual([]);
+    expect(config.governance.scanOutboundMessages).toBe(false);
+    expect(config.telemetry.enabled).toBe(true);
+    expect(config.telemetry.batchSize).toBe(20);
+    expect(config.telemetry.flushIntervalMs).toBe(5000);
+    expect(config.telemetry.captureMessageContent).toBe(false);
+    expect(config.telemetry.captureToolParams).toBe(true);
+    expect(config.telemetry.redactPatterns).toEqual([]);
+    expect(config.metadata).toEqual({});
+  });
+
+  it('throws when apiKey is missing', () => {
+    expect(() => resolveConfig({})).toThrow('apiKey');
+  });
+
+  it('throws when apiKey is empty string', () => {
+    expect(() => resolveConfig({ apiKey: '  ' })).toThrow('apiKey');
+  });
+
+  it('trims trailing slashes from endpoint', () => {
+    const config = resolveConfig({
+      apiKey: 'tp-key',
+      endpoint: 'https://custom.host.com///',
+    });
+    expect(config.endpoint).toBe('https://custom.host.com');
+  });
+
+  it('resolves governance overrides', () => {
+    const config = resolveConfig({
+      apiKey: 'tp-key',
+      governance: {
+        enabled: false,
+        failMode: 'closed',
+        timeoutMs: 5000,
+        excludeTools: ['jq', 'cat'],
+        scanOutboundMessages: true,
+      },
+    });
+
+    expect(config.governance.enabled).toBe(false);
+    expect(config.governance.failMode).toBe('closed');
+    expect(config.governance.timeoutMs).toBe(5000);
+    expect(config.governance.excludeTools).toEqual(['jq', 'cat']);
+    expect(config.governance.scanOutboundMessages).toBe(true);
+  });
+
+  it('resolves telemetry overrides', () => {
+    const config = resolveConfig({
+      apiKey: 'tp-key',
+      telemetry: {
+        enabled: false,
+        batchSize: 50,
+        flushIntervalMs: 10000,
+        captureMessageContent: true,
+        captureToolParams: false,
+        redactPatterns: ['\\bsecret\\b'],
+      },
+    });
+
+    expect(config.telemetry.enabled).toBe(false);
+    expect(config.telemetry.batchSize).toBe(50);
+    expect(config.telemetry.flushIntervalMs).toBe(10000);
+    expect(config.telemetry.captureMessageContent).toBe(true);
+    expect(config.telemetry.captureToolParams).toBe(false);
+    expect(config.telemetry.redactPatterns).toEqual(['\\bsecret\\b']);
+  });
+
+  it('filters non-string metadata values', () => {
+    const config = resolveConfig({
+      apiKey: 'tp-key',
+      metadata: { team: 'engineering', count: 42, valid: 'yes' },
+    });
+
+    expect(config.metadata).toEqual({ team: 'engineering', valid: 'yes' });
+  });
+
+  it('ignores invalid governance values and uses defaults', () => {
+    const config = resolveConfig({
+      apiKey: 'tp-key',
+      governance: {
+        timeoutMs: -100,
+        failMode: 'invalid-value',
+        excludeTools: 'not-an-array',
+      },
+    });
+
+    expect(config.governance.timeoutMs).toBe(3000);
+    expect(config.governance.failMode).toBe('open');
+    expect(config.governance.excludeTools).toEqual([]);
+  });
+});
+
+describe('compileRedactPatterns', () => {
+  it('returns null for empty patterns', () => {
+    expect(compileRedactPatterns([])).toBeNull();
+  });
+
+  it('compiles custom patterns with default PII patterns', () => {
+    const regex = compileRedactPatterns(['\\bpassword\\b']);
+    expect(regex).toBeInstanceOf(RegExp);
+
+    const text = 'my password is secret, ssn 123-45-6789, email user@test.com';
+    const redacted = text.replace(regex!, '[REDACTED]');
+
+    expect(redacted).toContain('[REDACTED]');
+    expect(redacted).not.toContain('123-45-6789');
+    expect(redacted).not.toContain('user@test.com');
+    expect(redacted).not.toContain('password');
+  });
+});