@turingpulse/sdk 1.0.1

package/src/http.ts

@@ -0,0 +1,241 @@
+/**
+ * HTTP client for TuringPulse SDK.
+ *
+ * All outbound HTTP flows through this class.  Authentication is done
+ * exclusively via the `X-API-Key` header — the backend resolves
+ * tenant_id and project_id from the key.
+ */
+
+import type { AgentEvent } from '@turingpulse/interfaces';
+import { safeErrorMessage } from './utils';
+
+import { TuringPulseConfig } from './config';
+import { toSnakeCaseDeep } from './utils';
+
+const _fetch: typeof globalThis.fetch = globalThis.fetch;
+const _Headers: typeof globalThis.Headers = globalThis.Headers;
+
+export const SDK_VERSION = '0.1.0';
+const SDK_LANGUAGE = 'typescript';
+const MAX_PAYLOAD_BYTES = 5 * 1024 * 1024; // 5 MB
+const SAFE_PATH_SEGMENT = /^[a-zA-Z0-9_-]+$/;
+const TERMINAL_STATUS_CODES = new Set([401, 402, 403, 404]);
+
+interface JsonValue {
+  [key: string]: unknown;
+}
+
+/** Parameters for SDK policy_check() */
+export interface PolicyCheckParams {
+  agentId?: string;
+  workflowId?: string;
+  workflowName?: string;
+  runId?: string;
+  nodeName?: string;
+  modelName?: string;
+  confidenceScore?: number;
+  costUsd?: number;
+  latencyMs?: number;
+  outputText?: string;
+  inputText?: string;
+  outputLength?: number;
+  errorOccurred?: boolean;
+  category?: string;
+  metadata?: Record<string, unknown>;
+  spanId?: string;
+  nodeType?: string;
+}
+
+/** Result of a policy check */
+export interface PolicyCheckResult {
+  /** "allow", "block", or "flag" */
+  action: string;
+  /** Whether any policy was triggered */
+  triggered: boolean;
+  /** Human-readable reason */
+  reason?: string;
+  /** IDs of triggered policies */
+  policyIds: string[];
+}
+
+export class TuringPulseHttpClient {
+  private readonly baseUrl: string;
+
+  constructor(private readonly config: TuringPulseConfig) {
+    this.baseUrl = config.endpoint;
+  }
+
+  get maxSerializedFieldLength(): number {
+    return this.config.maxSerializedFieldLength;
+  }
+
+  private get fetchImpl() {
+    return this.config.fetchImpl ?? _fetch;
+  }
+
+  // ------------------------------------------------------------------
+  // Event emission
+  // ------------------------------------------------------------------
+
+  async emitEvents(events: AgentEvent[]): Promise<void> {
+    if (!events.length) return;
+    const snakeEvents = toSnakeCaseDeep(events);
+    const url = `${this.baseUrl}/api/v1/sdk/events`;
+    await this.post(url, { events: snakeEvents } as unknown as JsonValue);
+  }
+
+  // ------------------------------------------------------------------
+  // Task / HITL helpers
+  // ------------------------------------------------------------------
+
+  async createTask(payload: JsonValue): Promise<string | undefined> {
+    const url = `${this.baseUrl}/api/v1/tasks`;
+    const response = await this.post(url, payload);
+    if (response && typeof response === 'object' && 'taskId' in response && typeof response.taskId === 'string') {
+      return response.taskId;
+    }
+    if (typeof payload.taskId === 'string') {
+      return payload.taskId;
+    }
+    return undefined;
+  }
+
+  async addHitlAction(taskId: string, payload: JsonValue): Promise<void> {
+    if (!SAFE_PATH_SEGMENT.test(taskId)) {
+      // eslint-disable-next-line no-console
+      console.warn('TuringPulse: invalid taskId rejected (possible path traversal)');
+      return;
+    }
+    const url = `${this.baseUrl}/api/v1/tasks/${taskId}/hitl`;
+    await this.post(url, payload);
+  }
+
+  // ------------------------------------------------------------------
+  // Fingerprint / deploy / custom-change helpers
+  // ------------------------------------------------------------------
+
+  async postFingerprint(payload: JsonValue): Promise<unknown> {
+    const url = `${this.baseUrl}/api/v1/fingerprints`;
+    return this.post(url, payload);
+  }
+
+  async postDeploy(payload: JsonValue): Promise<unknown> {
+    const url = `${this.baseUrl}/api/v1/deploys`;
+    return this.post(url, payload);
+  }
+
+  async postCustomChange(payload: JsonValue): Promise<unknown> {
+    const url = `${this.baseUrl}/api/v1/changes`;
+    return this.post(url, payload);
+  }
+
+  // ------------------------------------------------------------------
+  // Core POST with retries + timeout + payload limit
+  // ------------------------------------------------------------------
+
+  private async post(url: string, body: JsonValue): Promise<unknown> {
+    let serialized = JSON.stringify(body);
+    if (serialized.length > MAX_PAYLOAD_BYTES) {
+      // eslint-disable-next-line no-console
+      console.warn(`TuringPulse payload exceeds ${MAX_PAYLOAD_BYTES} bytes, truncating`);
+      const events = (body as Record<string, unknown>).events;
+      if (Array.isArray(events) && events.length > 1) {
+        const overhead = serialized.length - JSON.stringify(events).length;
+        const avgPerEvent = Math.ceil((serialized.length - overhead) / events.length);
+        const targetCount = Math.max(1, Math.floor((MAX_PAYLOAD_BYTES - overhead) / avgPerEvent));
+        if (targetCount < events.length) {
+          body = { ...body, events: events.slice(0, targetCount) } as unknown as JsonValue;
+        }
+      }
+      serialized = JSON.stringify(body);
+    }
+
+    const headers = this.buildHeaders();
+    let lastError: unknown;
+    for (let attempt = 0; attempt <= this.config.maxRetries; attempt += 1) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+      try {
+        const response = await this.fetchImpl(url, {
+          method: 'POST',
+          headers,
+          body: serialized,
+          signal: controller.signal as AbortSignal,
+        });
+        clearTimeout(timeout);
+        if (!response.ok) {
+          const err = new Error(`TuringPulse request failed with ${response.status}`);
+          const retryAfterHeader = response.headers.get('retry-after');
+          if (retryAfterHeader) {
+            (err as Error & { retryAfter?: number }).retryAfter = parseFloat(retryAfterHeader) || undefined;
+          }
+          throw err;
+        }
+        if (response.headers.get('content-type')?.includes('application/json')) {
+          return await response.json();
+        }
+        return undefined;
+      } catch (error) {
+        clearTimeout(timeout);
+        lastError = error;
+        const statusMatch = error instanceof Error && error.message.match(/failed with (\d+)/);
+        if (statusMatch && TERMINAL_STATUS_CODES.has(Number(statusMatch[1]))) {
+          break;
+        }
+        if (attempt === this.config.maxRetries) break;
+        const retryAfter = (error as { retryAfter?: number })?.retryAfter;
+        const delay = retryAfter && retryAfter > 0
+          ? Math.min(retryAfter * 1000, 2000)
+          : Math.min(500 * (attempt + 1), 2000);
+        await sleep(delay);
+      }
+    }
+    // eslint-disable-next-line no-console
+    console.warn(`TuringPulse request to ${url} failed: ${safeErrorMessage(lastError)}`);
+    return undefined;
+  }
+
+  // ------------------------------------------------------------------
+  // Policy check — uses the same centralized post() with retries
+  // ------------------------------------------------------------------
+
+  async policyCheck(params: PolicyCheckParams): Promise<PolicyCheckResult> {
+    const url = `${this.baseUrl}/api/v1/hitl/policy/check`;
+    const body = toSnakeCaseDeep(params) as unknown as JsonValue;
+
+    try {
+      const data = (await this.post(url, body)) as Record<string, unknown> | undefined;
+      if (!data) {
+        return { action: 'flag', triggered: true, reason: 'check_error: no response', policyIds: [] };
+      }
+      return {
+        action: (data.action as string) || 'allow',
+        triggered: Boolean(data.triggered),
+        reason: (data.reason as string) || undefined,
+        policyIds: (data.policy_ids as string[]) || [],
+      };
+    } catch (err) {
+      const safeMessage = err instanceof Error ? err.message : 'unknown error';
+      // eslint-disable-next-line no-console
+      console.warn('TuringPulse policy check failed (fail-open):', safeMessage);
+      return { action: 'flag', triggered: true, reason: `check_error: ${safeMessage}`, policyIds: [] };
+    }
+  }
+
+  // ------------------------------------------------------------------
+  // Headers — only X-API-Key, never tenant/project/roles
+  // ------------------------------------------------------------------
+
+  private buildHeaders(): Headers {
+    return new _Headers({
+      'Content-Type': 'application/json',
+      'X-API-Key': this.config.apiKey,
+      'X-SDK-Version': SDK_VERSION,
+      'X-SDK-Language': SDK_LANGUAGE,
+    });
+  }
+}
+
+async function sleep(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+// Config
+export { TuringPulseConfig, type TuringPulseConfigOptions, type GovernanceDefaults, DEFAULT_ENDPOINT } from './config';
+
+// Plugin
+export { TuringPulsePlugin, init, getInstance } from './plugin';
+
+// Decorators
+export { instrument, withInstrumentation } from './decorators';
+
+// Governance
+export { GovernanceDirective, type GovernanceDirectiveOptions, type GovernanceTaskResult } from './governance';
+
+// Instrumentation
+export { type InstrumentationOptions } from './instrumentation';
+
+// KPIs
+export { type KPIConfig, type KPIResult, type KPIComparator } from './kpi';
+
+// Context
+export { currentContext, ExecutionContext, type ToolCallRecord, generateUUID } from './context';
+
+// Errors
+export {
+  TriggerNotFoundError,
+  PluginNotInitializedError,
+  GovernanceBlockedError,
+  ConfigurationError,
+} from './errors';
+
+// Fingerprinting
+export {
+  type FingerprintConfig,
+  type FingerprintData,
+} from './fingerprint';
+
+// Deploy Tracking
+export {
+  registerDeploy,
+  type DeployInfo,
+  type RegisterDeployOptions,
+} from './deploy';
+
+// Policy Check & HTTP Client
+export { type PolicyCheckParams, type PolicyCheckResult, TuringPulseHttpClient, SDK_VERSION } from './http';
+
+// Attachments
+export { AttachmentManager, type AttachmentResult } from './attachments';
+
+// Utils
+export { safeEnv, safeErrorMessage, toSnakeCaseDeep } from './utils';
+
+// Framework Integrations
+export {
+  instrumentMastra,
+  type MastraInstrumentOptions,
+  type MastraToolCallRecord,
+} from './integrations/mastra';

package/src/instrumentation.ts

@@ -0,0 +1,68 @@
+/**
+ * Instrumentation options for @instrument decorator.
+ *
+ * REFACTORED:
+ * - Added `name` parameter for workflow display name
+ * - `agentId` is DEPRECATED - use `name` instead
+ * - Backend auto-registers workflows based on `name` and assigns UUID
+ */
+
+import { GovernanceDirective } from './governance';
+import { KPIConfig } from './kpi';
+
+export interface InstrumentationOptions {
+  /**
+   * Display name for the workflow (e.g., "Order Processing Agent").
+   * This is the preferred parameter. The backend will auto-register
+   * workflows based on this name and assign a UUID.
+   */
+  name?: string;
+
+  /**
+   * @deprecated Use `name` instead.
+   * Kept for backward compatibility.
+   */
+  agentId?: string;
+
+  operation?: string;
+  labels?: Record<string, string>;
+  trace?: boolean;
+  governance?: GovernanceDirective;
+  kpis?: KPIConfig[];
+  triggerKey?: string;
+  triggerDescription?: string;
+  hiddenEntrypoint?: boolean;
+  metadata?: Record<string, string>;
+}
+
+export function resolveOperation(options: InstrumentationOptions, fallback: string): string {
+  return options.operation ?? fallback;
+}
+
+export function tracingEnabled(options: InstrumentationOptions, defaultEnabled: boolean): boolean {
+  return options.trace ?? defaultEnabled;
+}
+
+/**
+ * Validate instrumentation options.
+ * @throws Error if neither name nor agentId is provided.
+ */
+export function validateOptions(options: InstrumentationOptions): void {
+  if (!options.name && !options.agentId) {
+    throw new Error(
+      "Either 'name' or 'agentId' must be provided to @instrument. " +
+      "Example: @instrument({ name: 'My Workflow' })"
+    );
+  }
+
+  // Emit console warning for deprecated agentId usage
+  if (options.agentId && !options.name) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      "The 'agentId' parameter is deprecated. Use 'name' instead. " +
+      "Example: @instrument({ name: 'Order Processing Agent' })"
+    );
+  }
+}
+
+

package/src/integrations/mastra.ts

@@ -0,0 +1,335 @@
+/**
+ * Mastra 1.2.x instrumentation for TuringPulse SDK (TypeScript).
+ *
+ * Wraps `agent.generate()` to capture:
+ * - Token counts from `response.usage` (ai-sdk format: promptTokens / completionTokens).
+ * - Per-tool-call child spans.
+ * - Agent instructions as system prompt.
+ *
+ * This integration uses the centralized TuringPulseHttpClient when a plugin
+ * instance is available (preferred), or falls back to standalone HTTP when
+ * used without the full SDK.
+ */
+
+import type {
+  AgentEvent,
+} from '@turingpulse/interfaces';
+
+import type { ToolCallRecord } from '../context';
+import { generateUUID } from '../context';
+import { DEFAULT_ENDPOINT } from '../config';
+import type { TuringPulseHttpClient } from '../http';
+import { SDK_VERSION } from '../http';
+import { safeEnv, safeErrorMessage, toSnakeCaseDeep } from '../utils';
+
+const FRAMEWORK_NAME = 'mastra';
+const FRAMEWORK_VERSION = '1.2.0';
+
+/** Mastra tool call with required result/id fields. */
+interface MastraToolCallRecord extends ToolCallRecord {
+  toolResult: string;
+  toolId: string;
+}
+
+interface MastraInstrumentOptions {
+  /** Workflow display name for TuringPulse. */
+  name: string;
+  /** LLM model name (default: gpt-4o-mini). */
+  model?: string;
+  /** LLM provider (default: openai). */
+  provider?: string;
+  /**
+   * Preferred: pass the plugin's HTTP client for centralized retries, timeouts, headers.
+   * If not provided, falls back to standalone fetch using apiKey + endpoint.
+   */
+  httpClient?: TuringPulseHttpClient;
+  /** TuringPulse API endpoint — only needed if httpClient is not provided. */
+  endpoint?: string;
+  /** TuringPulse API key — only needed if httpClient is not provided. */
+  apiKey?: string;
+  /** Tool names available to the agent. */
+  toolNames?: string[];
+  /**
+   * A reference to the mutable tool-call log array. Tool execute()
+   * callbacks push records here during agent.generate(). The integration
+   * reads from this array after execution completes.
+   */
+  toolCallLog?: MastraToolCallRecord[];
+  kpis?: Array<{ kpiId: string; value: number | (() => number); alertThreshold?: number; comparator?: string; description?: string }>;
+  metadata?: Record<string, string>;
+}
+
+/**
+ * Instrument a Mastra Agent for TuringPulse observability.
+ *
+ * Returns an async function that runs `agent.generate()` and emits
+ * a root workflow span plus per-tool/LLM child spans.
+ */
+export function instrumentMastra(
+  agent: { generate: (prompt: string) => Promise<unknown>; [key: string]: unknown },
+  options: MastraInstrumentOptions,
+): (prompt: string) => Promise<unknown> {
+  const {
+    name,
+    model = 'gpt-4o-mini',
+    provider = 'openai',
+    httpClient,
+    endpoint = safeEnv('TP_ENDPOINT') || DEFAULT_ENDPOINT,
+    apiKey = (safeEnv('TP_API_KEY') || '').trim(),
+    toolNames = [],
+    toolCallLog: externalLog,
+  } = options;
+
+  if (!httpClient && !apiKey) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      'TuringPulse: No httpClient or apiKey provided. Telemetry will be skipped. ' +
+      'Pass the plugin\'s client via httpClient for best results.',
+    );
+  }
+
+  const systemPrompt: string =
+    typeof (agent as Record<string, unknown>).instructions === 'string'
+      ? ((agent as Record<string, unknown>).instructions as string).slice(0, 500)
+      : '';
+
+  return async function runInstrumented(prompt: string): Promise<unknown> {
+    const traceId = generateUUID();
+    const rootSpanId = generateUUID();
+    const t0 = Date.now();
+
+    if (externalLog) externalLog.length = 0;
+
+    const maxFieldLen = httpClient?.maxSerializedFieldLength ?? 50_000;
+
+    let response: unknown;
+    let generationError: Error | null = null;
+    try {
+      response = await agent.generate(prompt);
+    } catch (err) {
+      generationError = err instanceof Error ? err : new Error(String(err));
+      response = null;
+    }
+    const totalDurationMs = Date.now() - t0;
+
+    const resp = (response as Record<string, unknown>) || {};
+    const finalOutput = (resp.text as string) || '';
+    const usage = (resp.usage as { promptTokens?: number; completionTokens?: number }) || {};
+    const promptTokens = usage.promptTokens || 0;
+    const completionTokens = usage.completionTokens || 0;
+
+    const estPrompt = promptTokens || Math.max(Math.round(prompt.length / 4), 400);
+    const estCompletion = completionTokens || Math.max(Math.round(finalOutput.length / 4), 200);
+
+    const tcLog = externalLog ? [...externalLog] : [];
+
+    // ── Build child spans ──
+    const childEvents: AgentEvent[] = [];
+    const now = new Date();
+    let offset = 100;
+
+    for (const tc of tcLog) {
+      const spanId = generateUUID();
+      const ts = new Date(now.getTime() + offset).toISOString();
+      childEvents.push({
+        runId: traceId,
+        agentId: `tool_${tc.toolName}`,
+        timestamp: ts,
+        type: 'span',
+        payload: {
+          name: `${name}.tool_${tc.toolName}`,
+          durationMs: Math.floor(totalDurationMs / (tcLog.length + 1)),
+          status: tc.success ? 'success' : 'error',
+          metadata: {
+            span_id: spanId,
+            parent_span_id: rootSpanId,
+            trace_id: traceId,
+            workflow_name: name,
+            framework: FRAMEWORK_NAME,
+            node_type: 'tool',
+            depth: '1',
+            input: JSON.stringify(tc.toolArgs).slice(0, maxFieldLen),
+            output: JSON.stringify({ result: tc.toolResult.slice(0, maxFieldLen) }),
+            available_tools: JSON.stringify(toolNames),
+            tool_name: tc.toolName,
+            ...(tc.errorMessage ? { error_message: tc.errorMessage } : {}),
+            mastra_tool_id: tc.toolName,
+            mastra_version: FRAMEWORK_VERSION,
+          },
+          toolCalls: [{
+            toolName: tc.toolName,
+            toolArgs: tc.toolArgs,
+            toolResult: tc.toolResult.slice(0, maxFieldLen),
+            toolId: tc.toolId,
+            success: tc.success,
+            errorMessage: tc.errorMessage,
+          }],
+        },
+      });
+      offset += Math.floor(totalDurationMs / (tcLog.length + 1)) + 50;
+    }
+
+    // LLM reasoning span
+    const llmSpanId = generateUUID();
+    childEvents.push({
+      runId: traceId,
+      agentId: 'agent_reasoning',
+      timestamp: new Date(now.getTime() + offset).toISOString(),
+      type: 'span',
+      payload: {
+        name: `${name}.agent_reasoning`,
+        durationMs: Math.floor(totalDurationMs / (tcLog.length + 1)),
+        status: 'success',
+        tokens: { prompt: Math.round(estPrompt), completion: Math.round(estCompletion) },
+        costUsd: 0,
+        metadata: {
+          span_id: llmSpanId,
+          parent_span_id: rootSpanId,
+          trace_id: traceId,
+          workflow_name: name,
+          framework: FRAMEWORK_NAME,
+          node_type: 'llm',
+          depth: '1',
+          prompt: prompt.slice(0, maxFieldLen),
+          user_query: prompt.slice(0, maxFieldLen),
+          system_prompt: systemPrompt,
+          model,
+          provider,
+          available_tools: JSON.stringify(toolNames),
+          mastra_agent_name: (agent as Record<string, unknown>).name as string || name,
+          mastra_model: model,
+          mastra_tool_count: String(tcLog.length),
+          mastra_version: FRAMEWORK_VERSION,
+        },
+      },
+    });
+
+    // ── Root span ──
+    const totalTokensIn = childEvents.reduce((s, e) => s + (e.payload.tokens?.prompt || 0), 0);
+    const totalTokensOut = childEvents.reduce((s, e) => s + (e.payload.tokens?.completion || 0), 0);
+
+    const rootEvent: AgentEvent = {
+      runId: traceId,
+      agentId: name,
+      timestamp: now.toISOString(),
+      type: 'span',
+      payload: {
+        name: `${name}.execute`,
+        durationMs: totalDurationMs,
+        status: generationError ? 'error' : 'success',
+        tokens: {
+          prompt: totalTokensIn || Math.round(estPrompt),
+          completion: totalTokensOut || Math.round(estCompletion),
+        },
+        costUsd: 0,
+        metadata: {
+          workflow_name: name,
+          framework: FRAMEWORK_NAME,
+          environment: safeEnv('NODE_ENV') || 'unknown',
+          input: prompt.slice(0, maxFieldLen),
+          output: finalOutput.slice(0, maxFieldLen),
+          span_id: rootSpanId,
+          trace_id: traceId,
+          node_type: 'workflow',
+          mastra_version: FRAMEWORK_VERSION,
+          ...(generationError ? { error_message: generationError.message.slice(0, 500) } : {}),
+          ...(options.metadata ?? {}),
+          ...(_evalKpis(options.kpis, totalDurationMs)),
+        },
+      },
+    };
+
+    // ── Send all events via centralized client or standalone ──
+    const allEvents = [rootEvent, ...childEvents];
+
+    if (httpClient) {
+      await httpClient.emitEvents(allEvents);
+    } else if (apiKey && endpoint) {
+      await sendEventsStandalone(allEvents, endpoint, apiKey);
+    }
+
+    if (generationError) throw generationError;
+    return response;
+  };
+}
+
+/**
+ * Standalone fallback when no httpClient is available.
+ * Prefer passing httpClient for retries, timeouts, and consistent headers.
+ */
+const STANDALONE_TIMEOUT_MS = 10_000;
+const STANDALONE_MAX_PAYLOAD_BYTES = 5 * 1024 * 1024;
+
+async function sendEventsStandalone(
+  events: AgentEvent[],
+  baseUrl: string,
+  apiKey: string,
+): Promise<void> {
+  const url = `${baseUrl.replace(/\/$/, '')}/api/v1/sdk/events`;
+  const snakeEvents = toSnakeCaseDeep(events);
+  let body = JSON.stringify({ events: snakeEvents });
+  if (body.length > STANDALONE_MAX_PAYLOAD_BYTES && Array.isArray(snakeEvents) && (snakeEvents as unknown[]).length > 1) {
+    const arr = snakeEvents as unknown[];
+    const overhead = body.length - JSON.stringify(arr).length;
+    const avg = Math.ceil((body.length - overhead) / arr.length);
+    const target = Math.max(1, Math.floor((STANDALONE_MAX_PAYLOAD_BYTES - overhead) / avg));
+    body = JSON.stringify({ events: arr.slice(0, target) });
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), STANDALONE_TIMEOUT_MS);
+  try {
+    const resp = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': apiKey,
+        'X-SDK-Version': SDK_VERSION,
+        'X-SDK-Language': 'typescript',
+      },
+      body,
+      signal: controller.signal as AbortSignal,
+    });
+    if (!resp.ok) {
+      // eslint-disable-next-line no-console
+      console.warn(`TuringPulse telemetry FAILED: ${resp.status}`);
+    }
+  } catch (e) {
+    // eslint-disable-next-line no-console
+    console.warn(`TuringPulse telemetry ERROR: ${safeErrorMessage(e)}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export type { MastraInstrumentOptions, MastraToolCallRecord };
+
+type KpiEntry = MastraInstrumentOptions['kpis'] extends (infer U)[] | undefined ? U : never;
+
+function _evalKpis(
+  kpis: MastraInstrumentOptions['kpis'],
+  durationMs: number,
+): Record<string, string> {
+  if (!kpis || kpis.length === 0) return {};
+  const out: Record<string, string> = {};
+  for (const kpi of kpis) {
+    try {
+      const raw = typeof kpi.value === 'function' ? kpi.value() : kpi.value;
+      if (raw == null || !isFinite(raw)) continue;
+      out[`metric.${kpi.kpiId}`] = String(raw);
+      if (kpi.alertThreshold != null) {
+        const cmp = kpi.comparator ?? 'gt';
+        const t = kpi.alertThreshold;
+        const triggered =
+          cmp === 'gt' ? raw > t :
+          cmp === 'gte' ? raw >= t :
+          cmp === 'lt' ? raw < t :
+          cmp === 'lte' ? raw <= t :
+          raw === t;
+        if (triggered) out[`metric.alert.${kpi.kpiId}`] = 'true';
+      }
+    } catch {
+      /* user function threw — silently skip */
+    }
+  }
+  return out;
+}