@turingpulse/sdk 1.0.1

package/src/plugin.ts

@@ -0,0 +1,384 @@
+import { TuringPulseConfig, TuringPulseConfigOptions } from './config';
+import { contextStorage, currentContext, ExecutionContext, generateUUID } from './context';
+import { GovernanceBlockedError, PluginNotInitializedError, TriggerNotFoundError } from './errors';
+import { EventBuilder } from './eventBuilder';
+import { FingerprintBuilder, FingerprintData } from './fingerprint';
+import { GovernanceDirective, GovernanceManager } from './governance';
+import { PolicyCheckResult, TuringPulseHttpClient } from './http';
+import { InstrumentationOptions, resolveOperation, tracingEnabled } from './instrumentation';
+import { evaluateKpis } from './kpi';
+import { detectNodeType } from './llmDetector';
+import { TriggerRegistry } from './registry';
+import { TracingManager } from './tracing';
+import { flushPending } from './triggerState';
+import { FORBIDDEN_KEYS, isAsyncIterable, isPromise, safeErrorMessage } from './utils';
+
+export class TuringPulsePlugin {
+  readonly config: TuringPulseConfig;
+  /** @internal — used by deploy.ts and other SDK modules; not part of the public API. */
+  readonly client: TuringPulseHttpClient;
+  private readonly tracing: TracingManager;
+  private readonly governance: GovernanceManager;
+  private readonly eventBuilder: EventBuilder;
+  private readonly registry = new TriggerRegistry();
+
+  constructor(config: TuringPulseConfig) {
+    this.config = config;
+    this.client = new TuringPulseHttpClient(config);
+    this.tracing = new TracingManager(config);
+    this.governance = new GovernanceManager(this.client, config);
+    this.eventBuilder = new EventBuilder(config);
+  }
+
+  // ------------------------------------------------------------------
+  // Trigger management
+  // ------------------------------------------------------------------
+
+  registerTrigger(key: string, fn: (...args: unknown[]) => unknown, description?: string): string {
+    const namespaced = this.namespacedKey(key);
+    this.registry.register(namespaced, fn, description);
+    return namespaced;
+  }
+
+  unregisterTrigger(key: string): void {
+    this.registry.unregister(this.namespacedKey(key));
+  }
+
+  async triggerAgent(key: string, ...args: unknown[]): Promise<unknown> {
+    const namespaced = this.namespacedKey(key);
+    const entry = this.registry.get(namespaced);
+    if (!entry) throw new TriggerNotFoundError(namespaced);
+    const result = entry.fn(...args);
+    return isPromise(result) ? result : Promise.resolve(result);
+  }
+
+  listTriggers() {
+    return this.registry.list();
+  }
+
+  // ------------------------------------------------------------------
+  // Execution
+  // ------------------------------------------------------------------
+
+  execute(
+    fn: (...args: unknown[]) => unknown,
+    thisArg: unknown,
+    args: unknown[],
+    options: InstrumentationOptions,
+  ): unknown {
+    const context = this.buildContext(fn, args, options);
+    const spanName = resolveOperation(options, fn.name || options.agentId || 'agent');
+    const enabled = tracingEnabled(options, this.config.traceEnabled);
+
+    return this.tracing.withSpan(spanName, context.labels, enabled, () =>
+      contextStorage.run(context, () => this.invokeFunction(fn, thisArg, args, context, options)),
+    );
+  }
+
+  // ------------------------------------------------------------------
+  // Pre-execution governance (HITL blocking)
+  // ------------------------------------------------------------------
+
+  private resolveGovernance(options: InstrumentationOptions): GovernanceDirective | undefined {
+    const directive = options.governance;
+    const defaults = this.config.governanceDefaults;
+    const defaultHitl = defaults.hitl ?? false;
+
+    if (!directive && !defaultHitl) return undefined;
+
+    if (!directive) {
+      return new GovernanceDirective({
+        hitl: defaultHitl,
+        reviewers: defaults.reviewers,
+        escalationChannels: defaults.escalationChannels,
+        metadata: defaults.metadata ? { ...defaults.metadata } : undefined,
+        severity: defaults.severity,
+        autoEscalateAfterSeconds: defaults.autoEscalateAfterSeconds,
+      });
+    }
+
+    if (!directive.hitl && defaultHitl) {
+      return new GovernanceDirective({ ...directive, hitl: true });
+    }
+
+    return directive;
+  }
+
+  private async preExecutionPolicyCheck(
+    context: ExecutionContext,
+    options: InstrumentationOptions,
+  ): Promise<void> {
+    const directive = this.resolveGovernance(options);
+    if (!directive?.hitl) return;
+
+    let result: PolicyCheckResult;
+    try {
+      result = await this.client.policyCheck({
+        workflowName: context.workflowName,
+        spanId: context.spanId,
+        nodeType: context.nodeType,
+      });
+    } catch {
+      return;
+    }
+
+    if (result.action === 'block') {
+      throw new GovernanceBlockedError(result.reason, result.policyIds);
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Function invocation
+  // ------------------------------------------------------------------
+
+  private invokeFunction(
+    fn: (...args: unknown[]) => unknown,
+    thisArg: unknown,
+    args: unknown[],
+    context: ExecutionContext,
+    options: InstrumentationOptions,
+  ): unknown {
+    this.recordNode(context, fn, args);
+
+    const directive = this.resolveGovernance(options);
+    const needsPreCheck = Boolean(directive?.hitl);
+
+    if (needsPreCheck) {
+      return this.preExecutionPolicyCheck(context, options)
+        .then(() => {
+          const result = fn.apply(thisArg, args);
+          return this.handleResult(result, context, options);
+        })
+        .catch((error: unknown) => {
+          context.finish(undefined, error);
+          this.popNode(context);
+          return this.finalize(context, options).then(() => { throw error; });
+        });
+    }
+
+    try {
+      const result = fn.apply(thisArg, args);
+      return this.handleResult(result, context, options);
+    } catch (error) {
+      context.finish(undefined, error);
+      this.popNode(context);
+      void this.finalize(context, options);
+      throw error;
+    }
+  }
+
+  private handleResult(
+    result: unknown,
+    context: ExecutionContext,
+    options: InstrumentationOptions,
+  ): unknown {
+    if (isAsyncIterable(result)) {
+      return this.wrapAsyncIterable(result, context, options) as unknown;
+    }
+
+    if (isPromise(result)) {
+      return result
+        .then((value: unknown) => {
+          if (isAsyncIterable(value)) {
+            return this.wrapAsyncIterable(value, context, options);
+          }
+          context.finish(value);
+          this.popNode(context);
+          return this.finalize(context, options).then(() => value);
+        })
+        .catch((error: unknown) => {
+          context.finish(undefined, error);
+          this.popNode(context);
+          return this.finalize(context, options).then(() => { throw error; });
+        });
+    }
+
+    context.finish(result);
+    this.popNode(context);
+    void this.finalize(context, options);
+    return result;
+  }
+
+  // ------------------------------------------------------------------
+  // Context building
+  // ------------------------------------------------------------------
+
+  private buildContext(
+    fn: (...args: unknown[]) => unknown,
+    args: unknown[],
+    options: InstrumentationOptions,
+  ): ExecutionContext {
+    const triggerKey = options.triggerKey ? this.namespacedKey(options.triggerKey) : undefined;
+    const labels = this.config.mergedLabels(options.labels);
+    const metadata = { ...(options.metadata ?? {}), 'agent.function': fn.name || 'anonymous' };
+
+    let fingerprintBuilder: FingerprintBuilder | undefined;
+    if (this.config.fingerprint.enabled) {
+      fingerprintBuilder = new FingerprintBuilder(this.config.fingerprint);
+    }
+
+    const parent = currentContext();
+    const isChild = parent !== undefined;
+
+    return new ExecutionContext({
+      runId: isChild ? parent.runId : generateUUID(),
+      agentId: options.agentId,
+      operation: resolveOperation(options, fn.name || 'agent-operation'),
+      triggerKey,
+      hiddenEntrypoint: Boolean(options.hiddenEntrypoint),
+      labels,
+      metadata,
+      args,
+      fingerprintBuilder,
+      workflowId: options.agentId,
+      workflowName: options.name || options.agentId || this.config.workflowName,
+      parentSpanId: isChild ? parent.spanId : undefined,
+      depth: isChild ? parent.depth + 1 : 0,
+    });
+  }
+
+  // ------------------------------------------------------------------
+  // Streaming — wrap async iterables so span covers full iteration
+  // ------------------------------------------------------------------
+
+  private wrapAsyncIterable(
+    iterable: AsyncIterable<unknown>,
+    context: ExecutionContext,
+    options: InstrumentationOptions,
+  ): AsyncIterable<unknown> {
+    const self = this;
+    async function* wrappedGenerator() {
+      const chunks: unknown[] = [];
+      try {
+        for await (const chunk of iterable) {
+          chunks.push(chunk);
+          yield chunk;
+        }
+        context.finish(chunks);
+      } catch (error) {
+        context.finish(undefined, error);
+        throw error;
+      } finally {
+        self.popNode(context);
+        await self.finalize(context, options);
+      }
+    }
+    return wrappedGenerator();
+  }
+
+  // ------------------------------------------------------------------
+  // Finalize — emit event, governance, fingerprint
+  // ------------------------------------------------------------------
+
+  private async finalize(context: ExecutionContext, options: InstrumentationOptions): Promise<void> {
+    const kpiResults = evaluateKpis(options.kpis ?? [], context);
+    const event = this.eventBuilder.build(context, options, kpiResults);
+    try {
+      await this.client.emitEvents([event]);
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.warn('Failed to emit TuringPulse event:', safeErrorMessage(error));
+    }
+    if (!(context.error instanceof GovernanceBlockedError)) {
+      try {
+        await this.governance.enforce(options.governance, context, kpiResults);
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.warn('Failed to enforce governance directive:', safeErrorMessage(error));
+      }
+    }
+    if (context.fingerprintBuilder) {
+      await this.sendFingerprint(context);
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Fingerprinting
+  // ------------------------------------------------------------------
+
+  private recordNode(context: ExecutionContext, fn: (...args: unknown[]) => unknown, args: unknown[]): void {
+    if (!context.fingerprintBuilder) return;
+    const funcName = fn.name || 'anonymous';
+    const kwargs: Record<string, unknown> = Object.create(null);
+    if (args.length === 1 && typeof args[0] === 'object' && args[0] !== null) {
+      for (const [k, v] of Object.entries(args[0] as Record<string, unknown>)) {
+        if (!FORBIDDEN_KEYS.has(k)) kwargs[k] = v;
+      }
+    }
+    const [nodeType, llmInfo] = detectNodeType(funcName, funcName, args, kwargs);
+    if (llmInfo) {
+      context.recordNode(funcName, nodeType, llmInfo.config, llmInfo.prompt);
+    } else {
+      context.recordNode(funcName, nodeType);
+    }
+    context.fingerprintBuilder.pushParent(funcName);
+  }
+
+  private popNode(context: ExecutionContext): void {
+    context.fingerprintBuilder?.popParent();
+  }
+
+  private async sendFingerprint(context: ExecutionContext): Promise<void> {
+    if (!this.config.fingerprint.enabled || !context.fingerprintBuilder) return;
+    if (context.error && !this.config.fingerprint.sendOnFailure) return;
+
+    const payload = {
+      run_id: context.runId,
+      workflow_id: context.workflowId || context.agentId,
+      fingerprint: context.fingerprintBuilder.getFingerprint(),
+    };
+
+    const emit = () =>
+      this.client
+        .postFingerprint(payload as unknown as Record<string, unknown>)
+        .catch((error: unknown) => {
+          // eslint-disable-next-line no-console
+          console.warn('Failed to send fingerprint:', safeErrorMessage(error));
+        });
+
+    if (this.config.fingerprint.sendAsync) {
+      void emit();
+    } else {
+      await emit();
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Helpers
+  // ------------------------------------------------------------------
+
+  private namespacedKey(key: string): string {
+    return key.includes(':') ? key : `${this.config.triggerNamespace}:${key}`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Module-level singleton
+// ---------------------------------------------------------------------------
+
+let pluginInstance: TuringPulsePlugin | undefined;
+
+export function init(options: TuringPulseConfig | TuringPulseConfigOptions): TuringPulsePlugin {
+  const config = options instanceof TuringPulseConfig ? options : new TuringPulseConfig(options);
+  pluginInstance = new TuringPulsePlugin(config);
+  flushPending(pluginInstance);
+  return pluginInstance;
+}
+
+export function getInstance(): TuringPulsePlugin {
+  if (!pluginInstance) {
+    const apiKey = typeof process !== 'undefined' ? process.env?.TP_API_KEY : undefined;
+    const workflowName = typeof process !== 'undefined' ? process.env?.TP_WORKFLOW_NAME : undefined;
+
+    if (apiKey && workflowName) {
+      // eslint-disable-next-line no-console
+      console.info('Auto-initializing TuringPulse SDK from environment variables');
+      return init({ apiKey, workflowName });
+    }
+
+    throw new PluginNotInitializedError();
+  }
+  return pluginInstance;
+}
+
+export type TuringPulseDecoratorTarget = (...args: unknown[]) => unknown;

package/src/registry.ts

@@ -0,0 +1,27 @@
+export interface TriggerEntry {
+  key: string;
+  fn: (...args: unknown[]) => unknown;
+  description?: string;
+}
+
+export class TriggerRegistry {
+  private readonly entries = new Map<string, TriggerEntry>();
+
+  register(key: string, fn: (...args: unknown[]) => unknown, description?: string): void {
+    this.entries.set(key, { key, fn, description });
+  }
+
+  unregister(key: string): void {
+    this.entries.delete(key);
+  }
+
+  get(key: string): TriggerEntry | undefined {
+    return this.entries.get(key);
+  }
+
+  list(): TriggerEntry[] {
+    return Array.from(this.entries.values());
+  }
+}
+
+

package/src/tracing.ts

@@ -0,0 +1,39 @@
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+
+import { TuringPulseConfig } from './config';
+import { isPromise } from './utils';
+
+type Attributes = Record<string, string>;
+
+export class TracingManager {
+  private readonly tracer;
+
+  constructor(private readonly config: TuringPulseConfig) {
+    this.tracer = trace.getTracer(config.traceServiceName);
+  }
+
+  withSpan<T>(name: string, attributes: Attributes, enabled: boolean, fn: () => T): T {
+    if (!this.config.traceEnabled || !enabled) {
+      return fn();
+    }
+    return this.tracer.startActiveSpan(
+      name,
+      { attributes },
+      (span) => {
+        try {
+          const result = fn();
+          if (isPromise(result)) {
+            return result.finally(() => span.end()) as T;
+          }
+          span.end();
+          return result;
+        } catch (error) {
+          span.recordException(error as Error);
+          span.setStatus({ code: SpanStatusCode.ERROR });
+          span.end();
+          throw error;
+        }
+      },
+    );
+  }
+}

package/src/triggerState.ts

@@ -0,0 +1,27 @@
+import { markTriggerRegistered } from './utils';
+
+interface PendingTrigger {
+  key: string;
+  fn: (...args: unknown[]) => unknown;
+  description?: string;
+}
+
+const pending: PendingTrigger[] = [];
+
+export function queueTrigger(key: string, fn: (...args: unknown[]) => unknown, description?: string): void {
+  pending.push({ key, fn, description });
+}
+
+export function flushPending(plugin: { registerTrigger: (key: string, fn: (...args: unknown[]) => unknown, description?: string) => string }): void {
+  if (!pending.length) {
+    return;
+  }
+  while (pending.length) {
+    const item = pending.shift();
+    if (!item) {
+      continue;
+    }
+    plugin.registerTrigger(item.key, item.fn, item.description);
+    markTriggerRegistered(item.fn);
+  }
+}

package/src/utils.ts

@@ -0,0 +1,78 @@
+/**
+ * Convert a camelCase string to snake_case.
+ * e.g. "runId" → "run_id", "durationMs" → "duration_ms"
+ */
+export function toSnake(s: string): string {
+  return s.replace(/[A-Z]/g, (ch) => `_${ch.toLowerCase()}`);
+}
+
+/** Type guard for thenables (Promises). Shared by plugin and tracing. */
+export function isPromise<T>(value: T | Promise<T>): value is Promise<T> {
+  return typeof (value as Promise<T>)?.then === 'function';
+}
+
+/** Type guard for async iterables (streaming responses). */
+export function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof (value as AsyncIterable<unknown>)[Symbol.asyncIterator] === 'function'
+  );
+}
+
+/** Safe access to process.env — returns undefined in browser environments. */
+export function safeEnv(key: string): string | undefined {
+  try {
+    return typeof process !== 'undefined' && process.env ? process.env[key] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Keys that must never be assigned as own properties to prevent prototype pollution. */
+export const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/** Extract only the safe message string from an unknown error. */
+export function safeErrorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === 'string') return err;
+  return 'unknown error';
+}
+
+const TRIGGER_PROP = '__turingpulseTriggerRegistered';
+
+/** Mark a function as having its trigger registered. */
+export function markTriggerRegistered(fn: (...args: unknown[]) => unknown): void {
+  Object.defineProperty(fn, TRIGGER_PROP, {
+    value: true,
+    configurable: true,
+    writable: true,
+  });
+}
+
+/** Check whether a function's trigger has been registered. */
+export function isTriggerRegistered(fn: (...args: unknown[]) => unknown): boolean {
+  return Boolean((fn as unknown as Record<string, unknown>)[TRIGGER_PROP]);
+}
+
+/**
+ * Deep-convert all object keys from camelCase to snake_case.
+ * Arrays are recursed; primitives are returned as-is.
+ * This is necessary because the ingestion service (Python) expects
+ * snake_case keys while the TypeScript interfaces use camelCase.
+ */
+export function toSnakeCaseDeep(obj: unknown): unknown {
+  if (Array.isArray(obj)) {
+    return obj.map(toSnakeCaseDeep);
+  }
+  if (obj !== null && typeof obj === 'object' && !(obj instanceof Date)) {
+    const out: Record<string, unknown> = Object.create(null);
+    for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+      const snaked = toSnake(k);
+      if (FORBIDDEN_KEYS.has(k) || FORBIDDEN_KEYS.has(snaked)) continue;
+      out[snaked] = toSnakeCaseDeep(v);
+    }
+    return out;
+  }
+  return obj;
+}

package/tests/compat/anthropic.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Compatibility tests for the Anthropic TypeScript SDK.
+ */
+import { describe, it, expect } from 'vitest';
+import { FingerprintBuilder, classifyConfigKey } from '../../src/fingerprint.js';
+
+// ── Import guard ──────────────────────────────────────────────────────────
+
+describe('Anthropic import', () => {
+  it('anthropic package is importable', async () => {
+    const mod = await import('@anthropic-ai/sdk');
+    expect(mod).toBeDefined();
+  });
+});
+
+// ── Key classification ────────────────────────────────────────────────────
+
+describe('Anthropic key classification', () => {
+  const modelKeys = ['model', 'temperature', 'top_p', 'top_k', 'max_tokens', 'stop_sequences'];
+  const camelKeys = ['topP', 'topK', 'maxTokens', 'stopSequences'];
+  const generalKeys = ['stream', 'system', 'metadata'];
+
+  it.each(modelKeys)('classifies %s as model', (key) => {
+    expect(classifyConfigKey(key)).toBe('model');
+  });
+
+  it.each(camelKeys)('classifies camelCase %s as model', (key) => {
+    expect(classifyConfigKey(key)).toBe('model');
+  });
+
+  it.each(generalKeys)('classifies %s as general', (key) => {
+    expect(classifyConfigKey(key)).toBe('general');
+  });
+});
+
+// ── Fingerprint hashing ──────────────────────────────────────────────────
+
+describe('Anthropic fingerprint', () => {
+  it('produces model hash', () => {
+    const builder = new FingerprintBuilder({ captureConfigs: true, capturePrompts: true });
+    builder.recordNode('claude', 'llm', {
+      model: 'claude-3-sonnet-20240229',
+      temperature: 0.5,
+      max_tokens: 1024,
+      top_k: 40,
+    });
+    const fp = builder.getFingerprint();
+    expect(fp.node_model_hashes['claude']).toBeDefined();
+  });
+
+  it('model swap changes model hash', () => {
+    const before = new FingerprintBuilder({ captureConfigs: true, capturePrompts: true });
+    const after = new FingerprintBuilder({ captureConfigs: true, capturePrompts: true });
+
+    before.recordNode('llm', 'llm', { model: 'claude-3-haiku-20240307', max_tokens: 1024 });
+    after.recordNode('llm', 'llm', { model: 'claude-3-sonnet-20240229', max_tokens: 1024 });
+
+    expect(before.getFingerprint().node_model_hashes['llm'])
+      .not.toBe(after.getFingerprint().node_model_hashes['llm']);
+  });
+});

package/tests/compat/cohere.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Compatibility tests for the Cohere TypeScript SDK.
+ */
+import { describe, it, expect } from 'vitest';
+import { FingerprintBuilder, classifyConfigKey } from '../../src/fingerprint.js';
+
+// ── Import guard ──────────────────────────────────────────────────────────
+
+describe('Cohere import', () => {
+  it('cohere-ai package is importable', async () => {
+    const mod = await import('cohere-ai');
+    expect(mod).toBeDefined();
+  });
+});
+
+// ── Key classification ────────────────────────────────────────────────────
+
+describe('Cohere key classification', () => {
+  const modelKeys = ['model', 'temperature', 'max_tokens', 'top_p', 'top_k', 'p', 'k', 'frequency_penalty', 'presence_penalty', 'stop_sequences'];
+  const generalKeys = ['stream', 'preamble', 'connectors'];
+
+  it.each(modelKeys)('classifies %s as model', (key) => {
+    expect(classifyConfigKey(key)).toBe('model');
+  });
+
+  it.each(generalKeys)('classifies %s as general', (key) => {
+    expect(classifyConfigKey(key)).toBe('general');
+  });
+});
+
+// ── Fingerprint hashing ──────────────────────────────────────────────────
+
+describe('Cohere fingerprint', () => {
+  it('produces model hash with p/k aliases', () => {
+    const builder = new FingerprintBuilder({ captureConfigs: true, capturePrompts: true });
+    builder.recordNode('cohere_chat', 'llm', {
+      model: 'command-r-plus',
+      temperature: 0.3,
+      p: 0.75,
+      k: 50,
+      stream: true,
+    });
+    const fp = builder.getFingerprint();
+    expect(fp.node_model_hashes['cohere_chat']).toBeDefined();
+  });
+
+  it('p/k change alters model hash', () => {
+    const before = new FingerprintBuilder({ captureConfigs: true, capturePrompts: true });
+    const after = new FingerprintBuilder({ captureConfigs: true, capturePrompts: true });
+
+    before.recordNode('llm', 'llm', { model: 'command-r-plus', p: 0.75, k: 50 });
+    after.recordNode('llm', 'llm', { model: 'command-r-plus', p: 0.9, k: 10 });
+
+    expect(before.getFingerprint().node_model_hashes['llm'])
+      .not.toBe(after.getFingerprint().node_model_hashes['llm']);
+  });
+});