@turingpulse/sdk 1.0.1

package/src/config.ts

@@ -0,0 +1,164 @@
+import { DEFAULT_FINGERPRINT_CONFIG, FingerprintConfig } from './fingerprint';
+
+export type FetchLike = (url: string | URL, init?: RequestInit) => Promise<Response>;
+
+const CRLF_RE = /[\r\n\x00]/g;
+
+function stripControlChars(value: string): string {
+  return value.replace(CRLF_RE, '');
+}
+
+const BLOCKED_HOSTS = /^(127\.\d{1,3}\.\d{1,3}\.\d{1,3}|10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|192\.168\.\d{1,3}\.\d{1,3}|169\.254\.\d{1,3}\.\d{1,3}|0\.0\.0\.0|localhost|\[::1\]|\[fd[0-9a-f]{2}:|\[fe80:)$/i;
+
+function checkEndpointSsrf(endpoint: string): void {
+  try {
+    const parsed = new URL(endpoint);
+    if (BLOCKED_HOSTS.test(parsed.hostname)) {
+      throw new Error(
+        'TuringPulse endpoint must not point to private/internal networks.',
+      );
+    }
+  } catch (e) {
+    if (e instanceof Error && e.message.includes('private/internal')) throw e;
+  }
+}
+
+export interface GovernanceDefaults {
+  hitl?: boolean;
+  reviewers?: string[];
+  escalationChannels?: string[];
+  metadata?: Record<string, string>;
+  severity?: string;
+  autoEscalateAfterSeconds?: number;
+}
+
+/**
+ * Configuration options for the TuringPulse SDK.
+ *
+ * Required:
+ *   apiKey       - SDK API key. The backend resolves tenant and project from it.
+ *   workflowName - Display name for this workflow.
+ *
+ * Optional:
+ *   endpoint     - Base URL for the TuringPulse API (default: https://api.turingpulse.ai).
+ */
+export interface TuringPulseConfigOptions {
+  /** SDK API key (required). */
+  apiKey: string;
+  /** Workflow display name (required). */
+  workflowName: string;
+  /** Base URL for the TuringPulse API. Override for self-hosted or staging. */
+  endpoint?: string;
+  defaultLabels?: Record<string, string>;
+  traceEnabled?: boolean;
+  traceServiceName?: string;
+  triggerNamespace?: string;
+  timeoutMs?: number;
+  maxRetries?: number;
+  fetchImpl?: FetchLike;
+  governanceDefaults?: GovernanceDefaults;
+  fingerprint?: FingerprintConfig;
+  captureArguments?: boolean;
+  captureReturnValue?: boolean;
+  maxSerializedFieldLength?: number;
+  redactFields?: string[];
+}
+
+export const DEFAULT_ENDPOINT = 'https://api.turingpulse.ai';
+
+interface ResolvedGovernanceDefaults {
+  hitl: boolean;
+  reviewers: string[];
+  escalationChannels: string[];
+  metadata: Record<string, string>;
+  severity: string;
+  autoEscalateAfterSeconds: number | undefined;
+}
+
+const DEFAULT_GOVERNANCE: ResolvedGovernanceDefaults = {
+  hitl: false,
+  reviewers: [],
+  escalationChannels: [],
+  metadata: {},
+  severity: 'medium',
+  autoEscalateAfterSeconds: undefined,
+};
+
+export class TuringPulseConfig {
+  readonly apiKey: string;
+  readonly workflowName: string;
+  readonly endpoint: string;
+  readonly defaultLabels: Record<string, string>;
+  readonly traceEnabled: boolean;
+  readonly traceServiceName: string;
+  readonly triggerNamespace: string;
+  readonly timeoutMs: number;
+  readonly maxRetries: number;
+  readonly fetchImpl?: FetchLike;
+  readonly governanceDefaults: ResolvedGovernanceDefaults;
+  readonly fingerprint: Required<FingerprintConfig>;
+  readonly captureArguments: boolean;
+  readonly captureReturnValue: boolean;
+  readonly maxSerializedFieldLength: number;
+  readonly redactFields: string[];
+
+  constructor(options: TuringPulseConfigOptions) {
+    if (!options.apiKey || !options.apiKey.trim()) {
+      throw new Error(
+        'TuringPulse apiKey is required and cannot be empty. ' +
+        'Set the TP_API_KEY environment variable or pass apiKey to init().',
+      );
+    }
+    this.apiKey = stripControlChars(options.apiKey.trim());
+
+    if (!options.workflowName || !options.workflowName.trim()) {
+      throw new Error(
+        'TuringPulse workflowName is required and cannot be empty. ' +
+        'Pass workflowName to init(). Example: init({ apiKey: "...", workflowName: "My Agent" })',
+      );
+    }
+    this.workflowName = options.workflowName.trim();
+
+    const raw = stripControlChars(options.endpoint ?? DEFAULT_ENDPOINT);
+    this.endpoint = raw.replace(/\/$/, '');
+    if (this.endpoint && !/^https?:\/\//.test(this.endpoint)) {
+      throw new Error('TuringPulse endpoint must start with https:// or http://');
+    }
+    checkEndpointSsrf(this.endpoint);
+    if (this.endpoint.startsWith('http://')) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        'TuringPulse endpoint uses http:// \u2014 API key will be sent in cleartext. Use https:// in production.',
+      );
+    }
+
+    this.defaultLabels = { ...(options.defaultLabels ?? {}) };
+    this.traceEnabled = options.traceEnabled ?? true;
+    this.traceServiceName = options.traceServiceName ?? 'turingpulse.sdk';
+    this.triggerNamespace = options.triggerNamespace ?? 'default';
+    this.timeoutMs = Math.min(options.timeoutMs ?? 10_000, 120_000);
+    this.maxRetries = options.maxRetries ?? 3;
+    this.fetchImpl = options.fetchImpl;
+    this.governanceDefaults = {
+      hitl: options.governanceDefaults?.hitl ?? DEFAULT_GOVERNANCE.hitl,
+      reviewers: options.governanceDefaults?.reviewers ?? DEFAULT_GOVERNANCE.reviewers,
+      escalationChannels: options.governanceDefaults?.escalationChannels ?? DEFAULT_GOVERNANCE.escalationChannels,
+      metadata: { ...DEFAULT_GOVERNANCE.metadata, ...(options.governanceDefaults?.metadata ?? {}) },
+      severity: options.governanceDefaults?.severity ?? DEFAULT_GOVERNANCE.severity,
+      autoEscalateAfterSeconds:
+        options.governanceDefaults?.autoEscalateAfterSeconds ?? DEFAULT_GOVERNANCE.autoEscalateAfterSeconds,
+    };
+    this.fingerprint = {
+      ...DEFAULT_FINGERPRINT_CONFIG,
+      ...(options.fingerprint ?? {}),
+    };
+    this.captureArguments = options.captureArguments ?? false;
+    this.captureReturnValue = options.captureReturnValue ?? false;
+    this.maxSerializedFieldLength = options.maxSerializedFieldLength ?? 50_000;
+    this.redactFields = options.redactFields ?? [];
+  }
+
+  mergedLabels(labels?: Record<string, string>): Record<string, string> {
+    return { ...this.defaultLabels, ...(labels ?? {}) };
+  }
+}

package/src/context.ts

@@ -0,0 +1,258 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import type { FingerprintBuilder } from './fingerprint';
+import { GovernanceBlockedError } from './errors';
+
+export function generateUUID(): string {
+  if (typeof globalThis.crypto?.randomUUID === 'function') {
+    return globalThis.crypto.randomUUID();
+  }
+  try {
+    return randomUUID();
+  } catch {
+    if (typeof globalThis.crypto?.getRandomValues === 'function') {
+      const bytes = new Uint8Array(16);
+      globalThis.crypto.getRandomValues(bytes);
+      bytes[6] = (bytes[6] & 0x0f) | 0x40;
+      bytes[8] = (bytes[8] & 0x3f) | 0x80;
+      const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+      return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+      const r = (Math.random() * 16) | 0;
+      return (c === 'x' ? r : (r & 0x3) | 0x8).toString(16);
+    });
+  }
+}
+
+/** Structured tool call record matching the shared ToolCallInfo model. */
+export interface ToolCallRecord {
+  toolName: string;
+  toolArgs: Record<string, unknown>;
+  toolResult?: string;
+  toolId?: string;
+  success: boolean;
+  errorMessage?: string;
+}
+
+const AsyncLocalStorageCtor: (new <T>() => AsyncLocalStorage<T>) | undefined =
+  AsyncLocalStorage as unknown as (new <T>() => AsyncLocalStorage<T>) | undefined;
+
+/**
+ * Initialization options for ExecutionContext.
+ *
+ * REFACTORED:
+ * - Added workflowName for display name (from @instrument(name="..."))
+ * - agentId is kept for backward compatibility
+ * - Backend auto-registers workflows based on workflowName
+ */
+export interface ExecutionContextInit {
+  runId: string;
+  /** @deprecated Use workflowName instead */
+  agentId?: string;
+  operation: string;
+  triggerKey?: string;
+  hiddenEntrypoint?: boolean;
+  labels: Record<string, string>;
+  metadata: Record<string, string>;
+  args: unknown[];
+  fingerprintBuilder?: FingerprintBuilder;
+  /** @deprecated Backend assigns UUID */
+  workflowId?: string;
+  /** Display name from @instrument(name="...") */
+  workflowName?: string;
+  /** Unique identifier for this span (auto-generated if not provided). */
+  spanId?: string;
+  /** Parent span ID for trace hierarchy (root spans have no parent). */
+  parentSpanId?: string;
+  /** Nesting depth: 0 for root, parent.depth + 1 for children. */
+  depth?: number;
+}
+
+/**
+ * Execution context for instrumented functions.
+ *
+ * REFACTORED:
+ * - workflowName: Display name from @instrument(name="...") - sent to backend
+ * - agentId: DEPRECATED - kept for backward compatibility
+ * - Backend auto-registers workflows based on workflowName and assigns UUID
+ */
+export class ExecutionContext {
+  readonly runId: string;
+  /** @deprecated Use workflowName instead */
+  readonly agentId: string;
+  readonly operation: string;
+  readonly triggerKey?: string;
+  readonly hiddenEntrypoint: boolean;
+  readonly labels: Record<string, string>;
+  readonly metadata: Record<string, string>;
+  readonly args: unknown[];
+  readonly startedAt: Date;
+  readonly fingerprintBuilder?: FingerprintBuilder;
+  /** @deprecated Backend assigns UUID */
+  readonly workflowId?: string;
+  /** Display name from @instrument(name="...") - sent to backend */
+  readonly workflowName?: string;
+  completedAt?: Date;
+  error?: unknown;
+  result?: unknown;
+  status: 'pending' | 'success' | 'error' | 'blocked' = 'pending';
+
+  // ── Structural fields for trace hierarchy ──
+  readonly spanId: string;
+  readonly parentSpanId?: string;
+  readonly depth: number;
+
+  // ── Telemetry fields (parity with Python SDK) ──
+  tokensInput = 0;
+  tokensOutput = 0;
+  costUsd = 0;
+  model?: string;
+  provider?: string;
+  nodeType?: string;
+  framework?: string;
+  promptText?: string;
+  systemPrompt?: string;
+  inputData?: string;
+  outputData?: string;
+  availableTools?: string[];
+  toolCalls: ToolCallRecord[] = [];
+  attachments: Record<string, unknown>[] = [];
+  inputContext?: string;  // RAG retrieval context for faithfulness evals
+
+  constructor(init: ExecutionContextInit) {
+    this.runId = init.runId;
+    this.agentId = init.agentId ?? init.workflowName ?? '';
+    this.operation = init.operation;
+    this.triggerKey = init.triggerKey;
+    this.hiddenEntrypoint = Boolean(init.hiddenEntrypoint);
+    this.labels = init.labels;
+    this.metadata = init.metadata;
+    this.args = init.args;
+    this.startedAt = new Date();
+    this.fingerprintBuilder = init.fingerprintBuilder;
+    this.workflowId = init.workflowId ?? init.agentId;
+    this.workflowName = init.workflowName ?? init.agentId;
+
+    // Structural fields
+    this.spanId = init.spanId ?? generateUUID();
+    this.parentSpanId = init.parentSpanId;
+    this.depth = init.depth ?? 0;
+  }
+
+  finish(result?: unknown, error?: unknown): void {
+    this.completedAt = new Date();
+    this.result = result;
+    this.error = error;
+    if (error) {
+      this.status = error instanceof GovernanceBlockedError ? 'blocked' : 'error';
+    } else {
+      this.status = 'success';
+    }
+  }
+
+  get durationMs(): number | undefined {
+    if (!this.completedAt) {
+      return undefined;
+    }
+    return this.completedAt.getTime() - this.startedAt.getTime();
+  }
+
+  // ── Telemetry setters (matching Python SDK API) ──
+
+  /** Record token counts for this span. */
+  setTokens(input: number, output: number): void {
+    this.tokensInput = input;
+    this.tokensOutput = output;
+  }
+
+  /** Record LLM cost in USD. */
+  setCost(cost: number): void {
+    this.costUsd = cost;
+  }
+
+  /** Record the LLM model and provider used. */
+  setModel(model: string, provider?: string): void {
+    this.model = model;
+    if (provider) this.provider = provider;
+  }
+
+  /** Record prompt and optional system prompt. */
+  setPrompt(prompt: string, systemPrompt?: string): void {
+    this.promptText = prompt;
+    if (systemPrompt) this.systemPrompt = systemPrompt;
+  }
+
+  /** Record input/output data for this span. */
+  setIO(inputData?: string, outputData?: string): void {
+    if (inputData !== undefined) this.inputData = inputData;
+    if (outputData !== undefined) this.outputData = outputData;
+  }
+
+  /** Record RAG retrieval context for faithfulness evaluation. */
+  setInputContext(context: string): void {
+    this.inputContext = context.slice(0, 500_000);
+  }
+
+  /** Add a structured tool call record (capped at 200 per span). */
+  addToolCall(record: ToolCallRecord): void {
+    if (this.toolCalls.length >= 200) return;
+    this.toolCalls.push(record);
+  }
+
+  /**
+   * Record a node in the fingerprint.
+   *
+   * Called automatically during instrumentation to track workflow structure.
+   *
+   * @param name - Node name (typically the function name)
+   * @param nodeType - Type of node (llm, tool, function, retriever, etc.)
+   * @param config - Configuration dict for the node
+   * @param prompt - System prompt for LLM nodes
+   */
+  recordNode(
+    name: string,
+    nodeType: string,
+    config?: unknown,
+    prompt?: string,
+  ): void {
+    if (this.fingerprintBuilder) {
+      this.fingerprintBuilder.recordNode(name, nodeType, config, prompt);
+    }
+  }
+}
+
+class ContextStorage {
+  private readonly storage = AsyncLocalStorageCtor ? new AsyncLocalStorageCtor<ExecutionContext>() : undefined;
+  private fallback?: ExecutionContext;
+
+  run<T>(context: ExecutionContext, fn: () => T): T {
+    if (this.storage) {
+      return this.storage.run(context, fn);
+    }
+    const previous = this.fallback;
+    this.fallback = context;
+    const result = fn();
+    if (typeof (result as Promise<unknown>)?.then === 'function') {
+      return (result as unknown as Promise<unknown>).finally(() => {
+        this.fallback = previous;
+      }) as T;
+    }
+    this.fallback = previous;
+    return result;
+  }
+
+  get(): ExecutionContext | undefined {
+    if (this.storage) {
+      return this.storage.getStore() ?? undefined;
+    }
+    return this.fallback;
+  }
+}
+
+export const contextStorage = new ContextStorage();
+
+export function currentContext(): ExecutionContext | undefined {
+  return contextStorage.get();
+}
+

package/src/decorators.ts

@@ -0,0 +1,61 @@
+import { PluginNotInitializedError } from './errors';
+import { InstrumentationOptions, validateOptions } from './instrumentation';
+import { TuringPulsePlugin, getInstance } from './plugin';
+import { queueTrigger } from './triggerState';
+import { isTriggerRegistered, markTriggerRegistered } from './utils';
+
+type Method = (...args: unknown[]) => unknown;
+
+export function instrument(options: InstrumentationOptions) {
+  return function instrumentDecorator(
+    _target: unknown,
+    _propertyKey: string | symbol,
+    descriptor: PropertyDescriptor,
+  ): void {
+    if (!descriptor || typeof descriptor.value !== 'function') {
+      throw new Error('@instrument can only be applied to methods');
+    }
+    descriptor.value = createInstrumentedFunction(descriptor.value, options);
+  };
+}
+
+export function withInstrumentation<T extends Method>(fn: T, options: InstrumentationOptions): T {
+  return createInstrumentedFunction(fn, options);
+}
+
+function createInstrumentedFunction<T extends Method>(fn: T, options: InstrumentationOptions): T {
+  validateOptions(options);
+  const wrapper = function instrumented(this: unknown, ...args: unknown[]) {
+    const plugin = getInstance();
+    ensureTriggerRegistration(plugin, options, wrapper);
+    return plugin.execute(fn, this, args, options);
+  };
+
+  maybeRegisterTrigger(options, wrapper);
+  return wrapper as T;
+}
+
+function maybeRegisterTrigger(options: InstrumentationOptions, wrapper: Method): void {
+  if (!options.triggerKey) {
+    return;
+  }
+  try {
+    const plugin = getInstance();
+    plugin.registerTrigger(options.triggerKey, wrapper, options.triggerDescription);
+    markTriggerRegistered(wrapper);
+  } catch (error) {
+    if (error instanceof PluginNotInitializedError) {
+      queueTrigger(options.triggerKey, wrapper, options.triggerDescription);
+    } else {
+      throw error;
+    }
+  }
+}
+
+function ensureTriggerRegistration(plugin: TuringPulsePlugin, options: InstrumentationOptions, wrapper: Method): void {
+  if (!options.triggerKey || isTriggerRegistered(wrapper)) {
+    return;
+  }
+  plugin.registerTrigger(options.triggerKey, wrapper, options.triggerDescription);
+  markTriggerRegistered(wrapper);
+}