@turingpulse/sdk 1.0.1

package/src/deploy.ts

@@ -0,0 +1,260 @@
+/**
+ * Deploy tracking for change detection and root cause analysis.
+ */
+
+import { getInstance } from './plugin';
+import { PluginNotInitializedError } from './errors';
+import { safeEnv, safeErrorMessage } from './utils';
+
+/**
+ * Information about a deployment.
+ */
+export interface DeployInfo {
+  /** CI/CD provider (github, gitlab, jenkins, etc.) */
+  provider: string;
+  /** Git commit SHA */
+  gitSha?: string;
+  /** Version tag or branch name */
+  versionTag?: string;
+  /** Commit message */
+  commitMessage?: string;
+  /** Deployment timestamp */
+  deployedAt?: Date;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * CI/CD provider detection and variable mapping.
+ */
+const PROVIDERS: Record<
+  string,
+  {
+    detect: string[];
+    sha?: string[];
+    ref?: string[];
+    message?: string[];
+    [key: string]: string[] | undefined;
+  }
+> = {
+  github: {
+    detect: ['GITHUB_ACTIONS'],
+    sha: ['GITHUB_SHA'],
+    ref: ['GITHUB_REF', 'GITHUB_REF_NAME'],
+    message: ['GITHUB_EVENT_HEAD_COMMIT_MESSAGE'],
+    run_id: ['GITHUB_RUN_ID'],
+    workflow: ['GITHUB_WORKFLOW'],
+    actor: ['GITHUB_ACTOR'],
+  },
+  gitlab: {
+    detect: ['GITLAB_CI'],
+    sha: ['CI_COMMIT_SHA'],
+    ref: ['CI_COMMIT_REF_NAME', 'CI_COMMIT_TAG'],
+    message: ['CI_COMMIT_MESSAGE'],
+    pipeline_id: ['CI_PIPELINE_ID'],
+    job_name: ['CI_JOB_NAME'],
+    user: ['GITLAB_USER_LOGIN'],
+  },
+  circleci: {
+    detect: ['CIRCLECI'],
+    sha: ['CIRCLE_SHA1'],
+    ref: ['CIRCLE_TAG', 'CIRCLE_BRANCH'],
+    build_num: ['CIRCLE_BUILD_NUM'],
+    workflow_id: ['CIRCLE_WORKFLOW_ID'],
+    username: ['CIRCLE_USERNAME'],
+  },
+  jenkins: {
+    detect: ['JENKINS_URL', 'BUILD_NUMBER'],
+    sha: ['GIT_COMMIT'],
+    ref: ['GIT_BRANCH', 'BUILD_TAG'],
+    build_num: ['BUILD_NUMBER'],
+    job_name: ['JOB_NAME'],
+    user: ['BUILD_USER'],
+  },
+  azure: {
+    detect: ['TF_BUILD', 'AZURE_PIPELINES'],
+    sha: ['BUILD_SOURCEVERSION'],
+    ref: ['BUILD_SOURCEBRANCH', 'BUILD_SOURCEBRANCHNAME'],
+    build_id: ['BUILD_BUILDID'],
+    pipeline_name: ['BUILD_DEFINITIONNAME'],
+    requester: ['BUILD_REQUESTEDFOR'],
+  },
+  bitbucket: {
+    detect: ['BITBUCKET_PIPELINE_UUID'],
+    sha: ['BITBUCKET_COMMIT'],
+    ref: ['BITBUCKET_TAG', 'BITBUCKET_BRANCH'],
+    build_num: ['BITBUCKET_BUILD_NUMBER'],
+    pipeline_uuid: ['BITBUCKET_PIPELINE_UUID'],
+  },
+  travis: {
+    detect: ['TRAVIS'],
+    sha: ['TRAVIS_COMMIT'],
+    ref: ['TRAVIS_TAG', 'TRAVIS_BRANCH'],
+    message: ['TRAVIS_COMMIT_MESSAGE'],
+    build_id: ['TRAVIS_BUILD_ID'],
+    job_id: ['TRAVIS_JOB_ID'],
+  },
+};
+
+/**
+ * Get the first non-empty environment variable value.
+ */
+function getFirstEnv(envVars: string[]): string | undefined {
+  for (const varName of envVars) {
+    const value = safeEnv(varName);
+    if (value) {
+      return value;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Automatically detect deployment info from CI/CD environment variables.
+ * 
+ * Supports:
+ * - GitHub Actions
+ * - GitLab CI
+ * - CircleCI
+ * - Jenkins
+ * - Azure DevOps
+ * - Bitbucket Pipelines
+ * - Travis CI
+ */
+export class AutoDeployDetector {
+  /**
+   * Detect deployment info from environment variables.
+   * 
+   * @returns DeployInfo if running in a known CI/CD environment, undefined otherwise
+   */
+  static detect(): DeployInfo | undefined {
+    for (const [provider, config] of Object.entries(PROVIDERS)) {
+      const detectVars = config.detect || [];
+      if (!detectVars.every((v) => safeEnv(v))) {
+        continue;
+      }
+
+      const gitSha = getFirstEnv(config.sha || []);
+      const versionTag = getFirstEnv(config.ref || []);
+      const commitMessage = getFirstEnv(config.message || []);
+
+      const metadata: Record<string, string> = {};
+      for (const [key, envVars] of Object.entries(config)) {
+        if (['detect', 'sha', 'ref', 'message'].includes(key)) {
+          continue;
+        }
+        const value = getFirstEnv(envVars || []);
+        if (value) {
+          metadata[key] = value;
+        }
+      }
+
+      return {
+        provider,
+        gitSha,
+        versionTag,
+        commitMessage,
+        deployedAt: new Date(),
+        metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+      };
+    }
+
+    return undefined;
+  }
+}
+
+/**
+ * Options for registering a deploy.
+ */
+export interface RegisterDeployOptions {
+  /** The workflow ID this deployment affects */
+  workflowId: string;
+  /** Version tag (e.g., "v1.2.3") */
+  version?: string;
+  /** Git commit SHA */
+  gitSha?: string;
+  /** Git commit message */
+  commitMessage?: string;
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+  /** Deployment timestamp (defaults to now) */
+  deployedAt?: Date;
+  /** If true, auto-detect from CI/CD environment variables */
+  autoDetect?: boolean;
+}
+
+/**
+ * Register a deployment event with TuringPulse.
+ * 
+ * Call this from your CI/CD pipeline or application startup to track deployments.
+ * Deployment events are correlated with anomalies and drifts for root cause analysis.
+ * 
+ * @param options - Deploy registration options
+ * @returns True if deploy was registered successfully, false otherwise
+ * 
+ * @example
+ * ```typescript
+ * import { registerDeploy } from '@turingpulse/sdk';
+ * 
+ * // Manual registration
+ * await registerDeploy({
+ *   workflowId: 'chat-assistant',
+ *   version: 'v1.2.3',
+ *   gitSha: process.env.GIT_SHA,
+ *   commitMessage: process.env.GIT_COMMIT_MSG,
+ * });
+ * 
+ * // Auto-detect from CI/CD environment
+ * await registerDeploy({
+ *   workflowId: 'chat-assistant',
+ *   autoDetect: true,
+ * });
+ * ```
+ */
+export async function registerDeploy(options: RegisterDeployOptions): Promise<boolean> {
+  let { version, gitSha, commitMessage, metadata, deployedAt } = options;
+  const { workflowId, autoDetect = true } = options;
+
+  if (autoDetect) {
+    const detected = AutoDeployDetector.detect();
+    if (detected) {
+      gitSha = gitSha || detected.gitSha;
+      version = version || detected.versionTag;
+      commitMessage = commitMessage || detected.commitMessage;
+      deployedAt = deployedAt || detected.deployedAt;
+      if (detected.metadata) {
+        metadata = { ...(detected.metadata || {}), ...(metadata || {}) };
+      }
+    }
+  }
+
+  let plugin;
+  try {
+    plugin = getInstance();
+  } catch (error) {
+    if (error instanceof PluginNotInitializedError) {
+      // eslint-disable-next-line no-console
+      console.warn('Cannot register deploy: TuringPulse plugin not initialized');
+      return false;
+    }
+    throw error;
+  }
+
+  const payload = {
+    workflow_id: workflowId,
+    version_tag: version,
+    git_sha: gitSha,
+    commit_message: commitMessage,
+    deployed_at: (deployedAt || new Date()).toISOString(),
+    metadata: metadata || {},
+  };
+
+  try {
+    const result = (await plugin.client.postDeploy(payload)) as { success?: boolean } | undefined;
+    return result?.success ?? false;
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.warn('Failed to register deploy:', safeErrorMessage(error));
+    return false;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,44 @@
+export class TuringPulsePluginError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TuringPulsePluginError';
+  }
+}
+
+export class PluginNotInitializedError extends TuringPulsePluginError {
+  constructor() {
+    super(
+      'TuringPulse plugin is not initialized. ' +
+      'Call init(...) once or set TP_API_KEY env var.',
+    );
+    this.name = 'PluginNotInitializedError';
+  }
+}
+
+export class TriggerNotFoundError extends TuringPulsePluginError {
+  constructor(key: string) {
+    super(`No trigger registered for key "${key}".`);
+    this.name = 'TriggerNotFoundError';
+  }
+}
+
+export class GovernanceBlockedError extends TuringPulsePluginError {
+  readonly reason: string | undefined;
+  readonly policyIds: string[];
+
+  constructor(reason?: string, policyIds?: string[]) {
+    super(
+      `Execution blocked by governance policy: ${reason ?? 'no reason provided'}`,
+    );
+    this.name = 'GovernanceBlockedError';
+    this.reason = reason;
+    this.policyIds = policyIds ?? [];
+  }
+}
+
+export class ConfigurationError extends TuringPulsePluginError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConfigurationError';
+  }
+}

package/src/eventBuilder.ts

@@ -0,0 +1,153 @@
+/**
+ * Event construction extracted from the plugin to satisfy SRP.
+ *
+ * EventBuilder handles AgentEvent assembly from ExecutionContext,
+ * including metadata, tokens, tool calls, and KPI results.
+ */
+
+import type { AgentEvent } from '@turingpulse/interfaces';
+
+import { TuringPulseConfig } from './config';
+import { ExecutionContext } from './context';
+import { GovernanceDirective } from './governance';
+import { InstrumentationOptions } from './instrumentation';
+import { KPIResult, kpiMetadata } from './kpi';
+
+const MAX_FIELD_SIZE = 500_000;
+
+export class EventBuilder {
+  private readonly redactFieldNames: Set<string>;
+
+  constructor(private readonly config: TuringPulseConfig) {
+    this.redactFieldNames = new Set(
+      (config.redactFields ?? []).map((f) => f.toLowerCase()),
+    );
+  }
+
+  build(
+    context: ExecutionContext,
+    options: InstrumentationOptions,
+    kpiResults: KPIResult[],
+  ): AgentEvent {
+    const metadata = this.assembleMetadata(context, options, kpiResults);
+
+    return {
+      runId: context.runId,
+      agentId: context.agentId,
+      timestamp: (context.completedAt ?? context.startedAt).toISOString(),
+      type: 'agent_step',
+      payload: {
+        name: context.operation,
+        durationMs: context.durationMs,
+        status: context.status,
+        metadata,
+        tokens:
+          context.tokensInput > 0 || context.tokensOutput > 0
+            ? { prompt: context.tokensInput, completion: context.tokensOutput }
+            : undefined,
+        costUsd: context.costUsd > 0 ? context.costUsd : undefined,
+      },
+    };
+  }
+
+  private assembleMetadata(
+    context: ExecutionContext,
+    options: InstrumentationOptions,
+    kpiResults: KPIResult[],
+  ): Record<string, string> {
+    const metadata: Record<string, string> = {
+      ...Object.fromEntries(
+        Object.entries(context.labels).map(([k, v]) => [k, String(v)]),
+      ),
+      ...Object.fromEntries(
+        Object.entries(context.metadata).map(([k, v]) => [k, String(v)]),
+      ),
+      'agent.status': context.status,
+      'agent.hidden_entrypoint': String(context.hiddenEntrypoint),
+      'agent.run_id': context.runId,
+      'agent.operation': context.operation,
+      span_id: context.spanId,
+      depth: String(context.depth),
+    };
+
+    if (context.parentSpanId) metadata['parent_span_id'] = context.parentSpanId;
+    if (context.model) metadata['model'] = context.model;
+    if (context.provider) metadata['provider'] = context.provider;
+    if (context.nodeType) metadata['node_type'] = context.nodeType;
+    if (context.framework) metadata['framework'] = context.framework;
+    if (context.promptText) metadata['prompt'] = context.promptText.slice(0, MAX_FIELD_SIZE);
+    if (context.systemPrompt) metadata['system_prompt'] = context.systemPrompt.slice(0, MAX_FIELD_SIZE);
+    if (context.inputData) metadata['input'] = context.inputData.slice(0, MAX_FIELD_SIZE);
+    if (context.outputData) metadata['output'] = context.outputData.slice(0, MAX_FIELD_SIZE);
+    if (context.availableTools?.length) {
+      metadata['available_tools'] = JSON.stringify(context.availableTools);
+    }
+    if (context.workflowName) metadata['workflow_name'] = context.workflowName;
+    if (context.triggerKey) metadata['agent.trigger_key'] = context.triggerKey;
+
+    if (context.error instanceof Error) {
+      metadata['error.type'] = context.error.name;
+      metadata['error.message'] = context.error.message;
+    }
+
+    if (options.governance) {
+      metadata['governance.hitl'] = String(options.governance.hitl);
+      metadata['governance.hatl'] = String(options.governance.hatl);
+      metadata['governance.hotl'] = String(options.governance.hotl);
+    }
+
+    for (const result of kpiResults) {
+      Object.assign(metadata, kpiMetadata(result));
+    }
+
+    if (context.attachments.length > 0) {
+      metadata['attachments'] = JSON.stringify(context.attachments);
+    }
+    if (context.inputContext) {
+      metadata['input_context'] = context.inputContext.slice(0, MAX_FIELD_SIZE);
+    }
+
+    if (context.toolCalls.length > 0) {
+      metadata['tool_calls'] = JSON.stringify(
+        context.toolCalls.map((tc) => ({
+          tool_name: tc.toolName,
+          tool_args: this.redactValue(tc.toolArgs),
+          tool_result: tc.toolResult ?? '',
+          tool_id: tc.toolId ?? '',
+          success: tc.success,
+          error_message: tc.errorMessage,
+        })),
+      );
+    }
+
+    this.applyRedaction(metadata);
+
+    return metadata;
+  }
+
+  private applyRedaction(metadata: Record<string, string>): void {
+    if (this.redactFieldNames.size === 0) return;
+    for (const key of Object.keys(metadata)) {
+      if (this.redactFieldNames.has(key.toLowerCase())) {
+        metadata[key] = '[REDACTED]';
+      }
+    }
+  }
+
+  private redactValue(value: unknown, depth = 0): unknown {
+    if (depth > 20 || this.redactFieldNames.size === 0) return value;
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      const result: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(value)) {
+        result[k] = this.redactFieldNames.has(k.toLowerCase())
+          ? '[REDACTED]'
+          : this.redactValue(v, depth + 1);
+      }
+      return result;
+    }
+    if (Array.isArray(value)) {
+      return value.map((item) => this.redactValue(item, depth + 1));
+    }
+    return value;
+  }
+}