@sensu-ai/sdk 0.1.5 → 0.5.0

package/src/client.ts

@@ -1,771 +0,0 @@
-import { randomUUID } from 'crypto';
-import type { TelemetryEvent } from '@sensu-ai/shared';
-import type {
-  SensuClientOptions,
-  StartRunOptions,
-  StartStepOptions,
-  TrackLlmOptions,
-  TrackToolOptions,
-  RawLlmCallOptions,
-  ContextBreakdown,
-  TrackRetrievalOptions,
-  RawRetrievalOptions,
-  TrackEmbeddingOptions,
-  RawEmbeddingOptions,
-  RecordFeedbackOptions,
-  RecordEvalScoreOptions,
-  HandoffOptions,
-  SpawnRunOptions,
-  TrackGuardrailOptions,
-  RawGuardrailOptions,
-  RecordPromptRenderOptions,
-  DeployPromptVersionOptions,
-  StartSessionOptions,
-  ResumeSessionOptions,
-} from './types.js';
-
-// ---------------------------------------------------------------------------
-// StepHandle — fluent API for a single step
-// ---------------------------------------------------------------------------
-
-export class StepHandle {
-  private readonly client: SensuClient;
-  readonly stepId: string;
-  readonly runId: string;
-  readonly sessionId: string;
-  readonly agentId: string;
-  readonly orgId: string;
-  readonly traceId: string;
-  readonly spanId: string;
-  private sequence: number;
-  private stepName?: string;
-  private ended = false;
-
-  constructor(
-    client: SensuClient,
-    opts: {
-      stepId: string;
-      runId: string;
-      sessionId: string;
-      agentId: string;
-      orgId: string;
-      traceId: string;
-      spanId: string;
-      sequence: number;
-      name?: string;
-    },
-  ) {
-    this.client = client;
-    this.stepId = opts.stepId;
-    this.runId = opts.runId;
-    this.sessionId = opts.sessionId;
-    this.agentId = opts.agentId;
-    this.orgId = opts.orgId;
-    this.traceId = opts.traceId;
-    this.spanId = opts.spanId;
-    this.sequence = opts.sequence;
-    this.stepName = opts.name;
-  }
-
-  private base() {
-    return {
-      event_id: randomUUID(),
-      timestamp: new Date().toISOString(),
-      org_id: this.orgId,
-      agent_id: this.agentId,
-      session_id: this.sessionId,
-      run_id: this.runId,
-      step_id: this.stepId,
-      trace_id: this.traceId,
-      span_id: randomUUID(),
-      parent_span_id: this.spanId,
-    };
-  }
-
-  /** Track an LLM call — wraps fn(), measures latency, emits event */
-  async trackLlm(opts: TrackLlmOptions): Promise<unknown> {
-    const startMs = Date.now();
-    const spanId = randomUUID();
-
-    this.client.enqueue({
-      ...this.base(),
-      span_id: spanId,
-      event_type: 'llm.request.started',
-      provider: opts.provider,
-      model: opts.model,
-      max_context_tokens: opts.maxContextTokens,
-    });
-
-    let result: unknown;
-    let status: 'success' | 'error' = 'success';
-    let err: unknown;
-
-    try {
-      result = await opts.fn();
-    } catch (e) {
-      status = 'error';
-      err = e;
-    }
-
-    const latencyMs = Date.now() - startMs;
-
-    // Try to extract token usage from common response shapes
-    const usage = extractUsage(result, opts.model);
-    const contextBreakdown = opts.extractContextBreakdown?.(result);
-
-    this.client.enqueue({
-      ...this.base(),
-      span_id: spanId,
-      event_type: 'llm.request.completed',
-      provider: opts.provider,
-      model: opts.model,
-      max_context_tokens: opts.maxContextTokens,
-      latency_ms: latencyMs,
-      status,
-      ...usage,
-      ...(contextBreakdown ? { context_breakdown: contextBreakdown } : {}),
-    });
-
-    if (err) throw err;
-    return result;
-  }
-
-  /** Emit a raw LLM call event (when you have the stats already) */
-  recordLlm(opts: RawLlmCallOptions): void {
-    const { contextBreakdown, ...rest } = opts;
-    this.client.enqueue({
-      ...this.base(),
-      event_type: 'llm.request.completed',
-      ...rest,
-      ...(contextBreakdown ? { context_breakdown: contextBreakdown } : {}),
-    });
-  }
-
-  /** Track a tool call — wraps fn(), measures latency */
-  async trackTool(opts: TrackToolOptions): Promise<unknown> {
-    const startMs = Date.now();
-    let result: unknown;
-    let status: 'success' | 'error' = 'success';
-    let err: unknown;
-
-    try {
-      result = await opts.fn();
-    } catch (e) {
-      status = 'error';
-      err = e;
-    }
-
-    const latencyMs = Date.now() - startMs;
-    const outputSize = estimateBytes(result);
-
-    this.client.enqueue({
-      ...this.base(),
-      event_type: 'tool.call.completed',
-      tool_name: opts.toolName,
-      latency_ms: latencyMs,
-      status,
-      output_size_bytes: outputSize,
-    });
-
-    if (err) throw err;
-    return result;
-  }
-
-  /** Track a retrieval call — wraps fn(), measures latency, emits started + completed */
-  async trackRetrieval(opts: TrackRetrievalOptions): Promise<unknown> {
-    const startMs = Date.now();
-    const spanId = randomUUID();
-
-    this.client.enqueue({
-      ...this.base(),
-      span_id: spanId,
-      event_type: 'retrieval.started',
-      vector_store_id: opts.vectorStoreId,
-      top_k: opts.topK,
-    });
-
-    let result: unknown;
-    let status: 'success' | 'error' = 'success';
-    let err: unknown;
-
-    try {
-      result = await opts.fn();
-    } catch (e) {
-      status = 'error';
-      err = e;
-    }
-
-    const latencyMs = Date.now() - startMs;
-
-    this.client.enqueue({
-      ...this.base(),
-      span_id: spanId,
-      event_type: 'retrieval.completed',
-      vector_store_id: opts.vectorStoreId,
-      top_k: opts.topK,
-      latency_ms: latencyMs,
-      status,
-    });
-
-    if (err) throw err;
-    return result;
-  }
-
-  /** Emit a raw retrieval completed event (when you have the stats already) */
-  recordRetrieval(opts: RawRetrievalOptions): void {
-    this.client.enqueue({
-      ...this.base(),
-      event_type: 'retrieval.completed',
-      ...opts,
-    });
-  }
-
-  /** Track an embedding call — wraps fn(), measures latency */
-  async trackEmbedding(opts: TrackEmbeddingOptions): Promise<unknown> {
-    const startMs = Date.now();
-    let result: unknown;
-    let err: unknown;
-
-    try {
-      result = await opts.fn();
-    } catch (e) {
-      err = e;
-    }
-
-    const latencyMs = Date.now() - startMs;
-
-    this.client.enqueue({
-      ...this.base(),
-      event_type: 'embedding.created',
-      model: opts.model,
-      input_text_length: opts.inputTextLength,
-      batch_size: opts.batchSize,
-      latency_ms: latencyMs,
-    });
-
-    if (err) throw err;
-    return result;
-  }
-
-  /** Emit a raw embedding event */
-  recordEmbedding(opts: RawEmbeddingOptions): void {
-    this.client.enqueue({
-      ...this.base(),
-      event_type: 'embedding.created',
-      model: opts.model,
-      input_text_length: opts.inputTextLength,
-      token_count: opts.tokenCount,
-      latency_ms: opts.latencyMs,
-      cost_usd_estimate: opts.costUsdEstimate,
-      batch_size: opts.batchSize,
-    });
-  }
-
-  /** Track a guardrail check — wraps fn(), measures latency, handles block */
-  async trackGuardrail(opts: TrackGuardrailOptions): Promise<'pass' | 'fail' | 'modified'> {
-    const startMs = Date.now();
-
-    this.client.enqueue({
-      ...this.base(),
-      event_type: 'guardrail.check.started',
-      guardrail_id: opts.guardrailId,
-      guardrail_type: opts.guardrailType,
-      input_hash: opts.inputHash,
-    });
-
-    let result: 'pass' | 'fail' | 'modified' = 'pass';
-    let err: unknown;
-
-    try {
-      result = await opts.fn();
-    } catch (e) {
-      err = e;
-    }
-
-    const latencyMs = Date.now() - startMs;
-
-    this.client.enqueue({
-      ...this.base(),
-      event_type: 'guardrail.check.completed',
-      guardrail_id: opts.guardrailId,
-      guardrail_type: opts.guardrailType,
-      input_hash: opts.inputHash,
-      result,
-      latency_ms: latencyMs,
-    });
-
-    if (err) throw err;
-    return result;
-  }
-
-  /** Emit a raw guardrail result (check or block) */
-  recordGuardrail(opts: RawGuardrailOptions): void {
-    if (opts.blocked) {
-      this.client.enqueue({
-        ...this.base(),
-        event_type: 'guardrail.blocked',
-        guardrail_id: opts.guardrailId,
-        guardrail_type: opts.guardrailType,
-        input_hash: opts.inputHash,
-        block_reason: opts.blockReason,
-        severity: opts.severity,
-      });
-    } else {
-      this.client.enqueue({
-        ...this.base(),
-        event_type: 'guardrail.check.completed',
-        guardrail_id: opts.guardrailId,
-        guardrail_type: opts.guardrailType,
-        input_hash: opts.inputHash,
-        result: opts.result,
-        latency_ms: opts.latencyMs,
-      });
-    }
-  }
-
-  /** Record a prompt template render event */
-  recordPromptRender(opts: RecordPromptRenderOptions): void {
-    this.client.enqueue({
-      ...this.base(),
-      event_type: 'prompt.rendered',
-      template_id: opts.templateId,
-      template_version: opts.templateVersion,
-      rendered_token_count: opts.renderedTokenCount,
-      variable_count: opts.variableCount,
-      latency_ms: opts.latencyMs,
-    });
-  }
-
-  async end(): Promise<void> {
-    if (this.ended) return;
-    this.ended = true;
-    this.client.enqueue({
-      ...this.base(),
-      event_type: 'agent.step.completed',
-    });
-    await this.client.flush();
-  }
-}
-
-// ---------------------------------------------------------------------------
-// RunHandle — fluent API for a single run
-// ---------------------------------------------------------------------------
-
-export class RunHandle {
-  private readonly client: SensuClient;
-  readonly runId: string;
-  readonly sessionId: string;
-  readonly agentId: string;
-  readonly orgId: string;
-  readonly traceId: string;
-  readonly spanId: string;
-  private stepCount = 0;
-  private ended = false;
-
-  constructor(
-    client: SensuClient,
-    opts: {
-      runId: string;
-      sessionId: string;
-      agentId: string;
-      orgId: string;
-      traceId: string;
-      spanId: string;
-    },
-  ) {
-    this.client = client;
-    this.runId = opts.runId;
-    this.sessionId = opts.sessionId;
-    this.agentId = opts.agentId;
-    this.orgId = opts.orgId;
-    this.traceId = opts.traceId;
-    this.spanId = opts.spanId;
-  }
-
-  private base() {
-    return {
-      event_id: randomUUID(),
-      timestamp: new Date().toISOString(),
-      org_id: this.orgId,
-      agent_id: this.agentId,
-      session_id: this.sessionId,
-      run_id: this.runId,
-      trace_id: this.traceId,
-      span_id: randomUUID(),
-      parent_span_id: this.spanId,
-    };
-  }
-
-  startStep(opts: StartStepOptions = {}): StepHandle {
-    const stepId = opts.stepId ?? randomUUID();
-    const sequence = this.stepCount++;
-
-    this.client.enqueue({
-      ...this.base(),
-      step_id: stepId,
-      event_type: 'agent.step.started',
-      step_type: opts.stepType ?? 'llm',
-      step_name: opts.name,
-      sequence: opts.sequence ?? sequence,
-    });
-
-    return new StepHandle(this.client, {
-      stepId,
-      runId: this.runId,
-      sessionId: this.sessionId,
-      agentId: this.agentId,
-      orgId: this.orgId,
-      traceId: this.traceId,
-      spanId: this.spanId,
-      sequence: opts.sequence ?? sequence,
-      name: opts.name,
-    });
-  }
-
-  /** Record user feedback for this run */
-  recordFeedback(opts: RecordFeedbackOptions): void {
-    this.client.enqueue({
-      ...this.base(),
-      event_type: 'feedback.received',
-      type: opts.type,
-      score: opts.score,
-      comment: opts.comment,
-      end_user_id: opts.endUserId,
-    });
-  }
-
-  /** Record an automated eval score for this run */
-  recordEvalScore(opts: RecordEvalScoreOptions): void {
-    this.client.enqueue({
-      ...this.base(),
-      event_type: 'eval.score.recorded',
-      metric: opts.metric,
-      score: opts.score,
-      evaluator_id: opts.evaluatorId,
-      model_used_for_eval: opts.modelUsedForEval,
-    });
-  }
-
-  /** Emit an agent.handoff event from this run to another agent */
-  handoff(opts: HandoffOptions): void {
-    this.client.enqueue({
-      ...this.base(),
-      event_type: 'agent.handoff',
-      to_agent_id: opts.toAgentId,
-      reason: opts.reason,
-      context_tokens_transferred: opts.contextTokensTransferred,
-    });
-  }
-
-  async end(status: 'completed' | 'failed' = 'completed'): Promise<void> {
-    if (this.ended) return;
-    this.ended = true;
-    const eventType =
-      status === 'completed' ? 'agent.run.completed' : 'agent.run.failed';
-    this.client.enqueue({ ...this.base(), event_type: eventType });
-    await this.client.flush();
-  }
-}
-
-// ---------------------------------------------------------------------------
-// SensuClient
-// ---------------------------------------------------------------------------
-
-export class SensuClient {
-  private readonly apiKey: string;
-  private readonly baseUrl: string;
-  private readonly agentId: string;
-  private readonly orgId: string;
-  private readonly batchSize: number;
-  private readonly flushIntervalMs: number;
-  readonly disabled: boolean;
-
-  private buffer: TelemetryEvent[] = [];
-  private flushTimer: ReturnType<typeof setInterval> | null = null;
-
-  constructor(opts: SensuClientOptions = {}) {
-    const fromEnv = opts.fromEnv ?? false;
-
-    this.apiKey =
-      opts.apiKey ??
-      (fromEnv ? (process.env.SENSU_API_KEY ?? '') : '');
-    this.baseUrl =
-      opts.baseUrl ??
-      (fromEnv
-        ? (process.env.SENSU_BASE_URL ?? 'http://localhost:3001')
-        : 'http://localhost:3001');
-    this.agentId =
-      opts.agentId ??
-      (fromEnv ? (process.env.SENSU_AGENT_ID ?? 'unknown-agent') : 'unknown-agent');
-    this.orgId =
-      opts.orgId ??
-      (fromEnv ? (process.env.SENSU_ORG_ID ?? '') : '');
-
-    this.batchSize = opts.batchSize ?? 10;
-    this.flushIntervalMs = opts.flushIntervalMs ?? 2000;
-    this.disabled = opts.disabled ?? false;
-
-    if (!this.disabled) {
-      this.flushTimer = setInterval(() => {
-        void this.flush();
-      }, this.flushIntervalMs);
-      if (this.flushTimer.unref) this.flushTimer.unref();
-    }
-  }
-
-  /** Enqueue an event for batched sending */
-  enqueue(event: TelemetryEvent): void {
-    if (this.disabled) return;
-    this.buffer.push(event);
-    if (this.buffer.length >= this.batchSize) {
-      void this.flush();
-    }
-  }
-
-  /** Flush all buffered events to the Sensu API */
-  async flush(): Promise<void> {
-    if (this.disabled || this.buffer.length === 0) return;
-    const events = this.buffer.splice(0);
-    try {
-      const res = await fetch(`${this.baseUrl}/api/v1/events`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-API-Key': this.apiKey,
-        },
-        body: JSON.stringify({ events }),
-      });
-      if (!res.ok) {
-        const body = await res.text();
-        console.error(`[sensu:sdk] flush failed ${res.status}: ${body}`);
-      }
-    } catch (err) {
-      // Re-queue on network error (best-effort)
-      console.error('[sensu:sdk] flush network error:', err);
-      this.buffer.unshift(...events);
-    }
-  }
-
-  /** Start a new agent run */
-  startRun(opts: StartRunOptions = {}): RunHandle {
-    const runId = opts.runId ?? randomUUID();
-    const sessionId = opts.sessionId ?? randomUUID();
-    const traceId = randomUUID();
-    const spanId = randomUUID();
-
-    this.enqueue({
-      event_id: randomUUID(),
-      event_type: 'agent.run.started',
-      timestamp: new Date().toISOString(),
-      org_id: this.orgId,
-      agent_id: this.agentId,
-      session_id: sessionId,
-      run_id: runId,
-      trace_id: traceId,
-      span_id: spanId,
-      run_type: opts.runType,
-      end_user_id: opts.endUserId,
-    });
-
-    return new RunHandle(this, {
-      runId,
-      sessionId,
-      agentId: this.agentId,
-      orgId: this.orgId,
-      traceId,
-      spanId,
-    });
-  }
-
-  /**
-   * Spawn a child agent run from within a parent run.
-   * Emits `agent.spawned` on the parent and returns a RunHandle for the child.
-   */
-  spawnRun(parentRun: RunHandle, opts: SpawnRunOptions): RunHandle {
-    const childRunId = opts.childRunId ?? randomUUID();
-    const childAgentId = opts.childAgentId;
-    const sessionId = opts.sessionId ?? parentRun.sessionId;
-    const traceId = parentRun.traceId;
-    const spanId = randomUUID();
-
-    // Emit agent.spawned on the parent run
-    this.enqueue({
-      event_id: randomUUID(),
-      event_type: 'agent.spawned',
-      timestamp: new Date().toISOString(),
-      org_id: this.orgId,
-      agent_id: parentRun.agentId,
-      session_id: sessionId,
-      run_id: parentRun.runId,
-      trace_id: traceId,
-      span_id: spanId,
-      child_run_id: childRunId,
-      child_agent_id: childAgentId,
-      spawn_reason: opts.spawnReason,
-    });
-
-    // Emit agent.run.started for the child run (child agent emits this itself in practice,
-    // but the SDK can also do it on behalf of known child agents)
-    this.enqueue({
-      event_id: randomUUID(),
-      event_type: 'agent.run.started',
-      timestamp: new Date().toISOString(),
-      org_id: this.orgId,
-      agent_id: childAgentId,
-      session_id: sessionId,
-      run_id: childRunId,
-      trace_id: traceId,
-      span_id: randomUUID(),
-      run_type: opts.runType,
-    });
-
-    return new RunHandle(this, {
-      runId: childRunId,
-      sessionId,
-      agentId: childAgentId,
-      orgId: this.orgId,
-      traceId,
-      spanId,
-    });
-  }
-
-  /** Explicitly start a session (sets channel and end_user_id) */
-  startSession(opts: StartSessionOptions = {}): string {
-    const sessionId = opts.sessionId ?? randomUUID();
-    const traceId = randomUUID();
-    const spanId = randomUUID();
-
-    this.enqueue({
-      event_id: randomUUID(),
-      event_type: 'session.started',
-      timestamp: new Date().toISOString(),
-      org_id: this.orgId,
-      agent_id: this.agentId,
-      session_id: sessionId,
-      run_id: sessionId, // run_id required by base schema; reuse session_id as placeholder
-      trace_id: traceId,
-      span_id: spanId,
-      channel: opts.channel,
-      end_user_id: opts.endUserId,
-    });
-
-    return sessionId;
-  }
-
-  /** Resume a previous session */
-  resumeSession(opts: ResumeSessionOptions): string {
-    const sessionId = opts.sessionId ?? randomUUID();
-    const traceId = randomUUID();
-    const spanId = randomUUID();
-
-    this.enqueue({
-      event_id: randomUUID(),
-      event_type: 'session.resumed',
-      timestamp: new Date().toISOString(),
-      org_id: this.orgId,
-      agent_id: this.agentId,
-      session_id: sessionId,
-      run_id: sessionId,
-      trace_id: traceId,
-      span_id: spanId,
-      resumed_from_session_id: opts.resumedFromSessionId,
-      channel: opts.channel,
-      end_user_id: opts.endUserId,
-    });
-
-    return sessionId;
-  }
-
-  /** Record a prompt version deployment (org-level event, not tied to a run) */
-  deployPromptVersion(opts: DeployPromptVersionOptions): void {
-    this.enqueue({
-      event_id: randomUUID(),
-      event_type: 'prompt.version.deployed',
-      timestamp: new Date().toISOString(),
-      org_id: this.orgId,
-      agent_id: this.agentId,
-      session_id: 'system',
-      run_id: 'system',
-      trace_id: randomUUID(),
-      span_id: randomUUID(),
-      template_id: opts.templateId,
-      new_version: opts.newVersion,
-      old_version: opts.oldVersion,
-      deployed_by: opts.deployedBy,
-    });
-  }
-
-  destroy(): void {
-    if (this.flushTimer) clearInterval(this.flushTimer);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-// Pricing per 1M tokens [input, output] in USD
-const MODEL_PRICING: Record<string, [number, number]> = {
-  'claude-opus-4-6':             [15.00, 75.00],
-  'claude-sonnet-4-6':           [ 3.00, 15.00],
-  'claude-haiku-4-5-20251001':   [ 0.80,  4.00],
-  'claude-3-5-sonnet-20241022':  [ 3.00, 15.00],
-  'claude-3-5-haiku-20241022':   [ 0.80,  4.00],
-  'claude-3-opus-20240229':      [15.00, 75.00],
-  'gpt-4o':                      [ 5.00, 15.00],
-  'gpt-4o-mini':                 [ 0.15,  0.60],
-  'gpt-4-turbo':                 [10.00, 30.00],
-};
-
-function estimateCost(model: string, inputTokens: number, outputTokens: number): number {
-  const pricing = MODEL_PRICING[model];
-  if (!pricing) return 0;
-  const [inputPrice, outputPrice] = pricing;
-  return (inputTokens / 1_000_000) * inputPrice + (outputTokens / 1_000_000) * outputPrice;
-}
-
-function extractUsage(result: unknown, model: string): Record<string, number | undefined> {
-  if (!result || typeof result !== 'object') return {};
-  const r = result as Record<string, unknown>;
-
-  // Anthropic shape: { usage: { input_tokens, output_tokens, cache_read_input_tokens } }
-  if (r['usage'] && typeof r['usage'] === 'object') {
-    const u = r['usage'] as Record<string, unknown>;
-    const inputTokens = num(u['input_tokens']) ?? 0;
-    const outputTokens = num(u['output_tokens']) ?? 0;
-    return {
-      input_tokens: inputTokens,
-      output_tokens: outputTokens,
-      cached_input_tokens: num(u['cache_read_input_tokens']),
-      total_tokens: inputTokens + outputTokens,
-      cost_usd_estimate: estimateCost(model, inputTokens, outputTokens),
-    };
-  }
-
-  // OpenAI shape: { choices: [...], usage: { prompt_tokens, completion_tokens, total_tokens } }
-  if (r['choices'] && r['usage'] && typeof r['usage'] === 'object') {
-    const u = r['usage'] as Record<string, unknown>;
-    const inputTokens = num(u['prompt_tokens']) ?? 0;
-    const outputTokens = num(u['completion_tokens']) ?? 0;
-    return {
-      input_tokens: inputTokens,
-      output_tokens: outputTokens,
-      total_tokens: num(u['total_tokens']),
-      cost_usd_estimate: estimateCost(model, inputTokens, outputTokens),
-    };
-  }
-
-  return {};
-}
-
-function num(v: unknown): number | undefined {
-  return typeof v === 'number' ? v : undefined;
-}
-
-function estimateBytes(v: unknown): number {
-  try {
-    return JSON.stringify(v)?.length ?? 0;
-  } catch {
-    return 0;
-  }
-}