@sensu-ai/sdk 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sensu-ai/sdk",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {

package/src/client.ts

@@ -8,6 +8,20 @@ import type {
   TrackToolOptions,
   RawLlmCallOptions,
   ContextBreakdown,
+  TrackRetrievalOptions,
+  RawRetrievalOptions,
+  TrackEmbeddingOptions,
+  RawEmbeddingOptions,
+  RecordFeedbackOptions,
+  RecordEvalScoreOptions,
+  HandoffOptions,
+  SpawnRunOptions,
+  TrackGuardrailOptions,
+  RawGuardrailOptions,
+  RecordPromptRenderOptions,
+  DeployPromptVersionOptions,
+  StartSessionOptions,
+  ResumeSessionOptions,
 } from './types.js';
 
 // ---------------------------------------------------------------------------
@@ -157,6 +171,171 @@ export class StepHandle {
     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;
@@ -243,6 +422,41 @@ export class RunHandle {
     });
   }
 
+  /** 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;
@@ -363,6 +577,124 @@ export class SensuClient {
     });
   }
 
+  /**
+   * 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);
   }

package/src/index.ts

@@ -7,4 +7,18 @@ export type {
   TrackToolOptions,
   RawLlmCallOptions,
   ContextBreakdown,
+  TrackRetrievalOptions,
+  RawRetrievalOptions,
+  TrackEmbeddingOptions,
+  RawEmbeddingOptions,
+  RecordFeedbackOptions,
+  RecordEvalScoreOptions,
+  SpawnRunOptions,
+  HandoffOptions,
+  TrackGuardrailOptions,
+  RawGuardrailOptions,
+  RecordPromptRenderOptions,
+  DeployPromptVersionOptions,
+  StartSessionOptions,
+  ResumeSessionOptions,
 } from './types.ts';

package/src/types.ts

@@ -77,3 +77,137 @@ export interface RawLlmCallOptions {
   status?: 'success' | 'error' | 'timeout';
   contextBreakdown?: ContextBreakdown;
 }
+
+// ---------------------------------------------------------------------------
+// Retrieval & Embedding
+// ---------------------------------------------------------------------------
+
+export interface TrackRetrievalOptions {
+  /** Wraps the retrieval call and measures latency automatically */
+  fn: () => Promise<unknown>;
+  vectorStoreId?: string;
+  topK?: number;
+}
+
+export interface RawRetrievalOptions {
+  vectorStoreId?: string;
+  topK?: number;
+  latencyMs?: number;
+  chunksReturned?: number;
+  tokensInjected?: number;
+  similarityScoreAvg?: number;
+  status?: 'success' | 'error';
+}
+
+export interface TrackEmbeddingOptions {
+  model: string;
+  /** Wraps the embedding call and measures latency automatically */
+  fn: () => Promise<unknown>;
+  inputTextLength?: number;
+  batchSize?: number;
+}
+
+export interface RawEmbeddingOptions {
+  model: string;
+  inputTextLength?: number;
+  tokenCount?: number;
+  latencyMs?: number;
+  costUsdEstimate?: number;
+  batchSize?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Evaluation & Feedback
+// ---------------------------------------------------------------------------
+
+export interface RecordFeedbackOptions {
+  type: 'thumbs_up' | 'thumbs_down' | 'score' | 'correction';
+  score?: number;
+  comment?: string;
+  endUserId?: string;
+}
+
+export interface RecordEvalScoreOptions {
+  metric: string;
+  score: number;
+  evaluatorId?: string;
+  modelUsedForEval?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Multi-Agent
+// ---------------------------------------------------------------------------
+
+export interface SpawnRunOptions {
+  childAgentId: string;
+  childRunId?: string;
+  spawnReason?: string;
+  /** Options forwarded to the child RunHandle */
+  runType?: string;
+  sessionId?: string;
+}
+
+export interface HandoffOptions {
+  toAgentId: string;
+  reason?: string;
+  contextTokensTransferred?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Guardrails
+// ---------------------------------------------------------------------------
+
+export interface TrackGuardrailOptions {
+  guardrailId: string;
+  guardrailType?: 'content' | 'pii' | 'jailbreak' | 'custom';
+  inputHash?: string;
+  /** Wraps the guardrail check and measures latency automatically */
+  fn: () => Promise<'pass' | 'fail' | 'modified'>;
+}
+
+export interface RawGuardrailOptions {
+  guardrailId: string;
+  guardrailType?: 'content' | 'pii' | 'jailbreak' | 'custom';
+  inputHash?: string;
+  result?: 'pass' | 'fail' | 'modified';
+  blockReason?: string;
+  severity?: 'low' | 'medium' | 'high';
+  latencyMs?: number;
+  blocked?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Prompt Management
+// ---------------------------------------------------------------------------
+
+export interface RecordPromptRenderOptions {
+  templateId: string;
+  templateVersion?: string;
+  renderedTokenCount?: number;
+  variableCount?: number;
+  latencyMs?: number;
+}
+
+export interface DeployPromptVersionOptions {
+  templateId: string;
+  newVersion: string;
+  oldVersion?: string;
+  deployedBy?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Session Lifecycle
+// ---------------------------------------------------------------------------
+
+export interface StartSessionOptions {
+  sessionId?: string;
+  channel?: 'web' | 'api' | 'mobile';
+  endUserId?: string;
+}
+
+export interface ResumeSessionOptions {
+  sessionId?: string;
+  resumedFromSessionId: string;
+  channel?: 'web' | 'api' | 'mobile';
+  endUserId?: string;
+}