@sensu-ai/sdk 0.1.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@sensu-ai/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./integrations/langchain": "./src/integrations/langchain.ts",
+    "./integrations/openai": "./src/integrations/openai.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@sensu-ai/shared": "*",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "*"
+  },
+  "peerDependencies": {
+    "langchain": ">=0.1.0",
+    "openai": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "langchain": { "optional": true },
+    "openai": { "optional": true }
+  }
+}

package/src/client.ts

@@ -0,0 +1,434 @@
+import { randomUUID } from 'crypto';
+import type { TelemetryEvent } from '@sensu-ai/shared';
+import type {
+  SensuClientOptions,
+  StartRunOptions,
+  StartStepOptions,
+  TrackLlmOptions,
+  TrackToolOptions,
+  RawLlmCallOptions,
+} 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);
+
+    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,
+    });
+
+    if (err) throw err;
+    return result;
+  }
+
+  /** Emit a raw LLM call event (when you have the stats already) */
+  recordLlm(opts: RawLlmCallOptions): void {
+    this.client.enqueue({
+      ...this.base(),
+      event_type: 'llm.request.completed',
+      ...opts,
+    });
+  }
+
+  /** 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;
+  }
+
+  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,
+    });
+  }
+
+  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,
+    });
+  }
+
+  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;
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { SensuClient, RunHandle, StepHandle } from './client.ts';
+export type {
+  SensuClientOptions,
+  StartRunOptions,
+  StartStepOptions,
+  TrackLlmOptions,
+  TrackToolOptions,
+  RawLlmCallOptions,
+} from './types.ts';

package/src/integrations/langchain.ts

@@ -0,0 +1,175 @@
+/**
+ * LangChain callback handler for Sensu telemetry.
+ *
+ * Usage:
+ *   import { SensuCallbackHandler } from '@sensu-ai/sdk/integrations/langchain';
+ *   const handler = new SensuCallbackHandler({ client: sensu });
+ *   const chain = new LLMChain({ ..., callbacks: [handler] });
+ */
+
+import { randomUUID } from 'crypto';
+import type { SensuClient } from '../client.ts';
+
+interface LangChainCallbackHandlerOptions {
+  client: SensuClient;
+  sessionId?: string;
+  runId?: string;
+}
+
+interface LangChainLlmStartInput {
+  name?: string;
+  [key: string]: unknown;
+}
+
+interface LangChainLlmEndOutput {
+  generations?: Array<Array<{ text?: string; generationInfo?: Record<string, unknown> }>>;
+  llmOutput?: Record<string, unknown>;
+}
+
+export class SensuCallbackHandler {
+  private readonly client: SensuClient;
+  private readonly sessionId: string;
+  private runId: string;
+  private traceId: string;
+  private startTimes: Map<string, number> = new Map();
+  private toolStartTimes: Map<string, number> = new Map();
+  private stepIds: Map<string, string> = new Map();
+
+  constructor(opts: LangChainCallbackHandlerOptions) {
+    this.client = opts.client;
+    this.sessionId = opts.sessionId ?? randomUUID();
+    this.runId = opts.runId ?? randomUUID();
+    this.traceId = randomUUID();
+  }
+
+  private base(spanId?: string) {
+    return {
+      event_id: randomUUID(),
+      timestamp: new Date().toISOString(),
+      org_id: (this.client as unknown as { orgId: string }).orgId,
+      agent_id: (this.client as unknown as { agentId: string }).agentId,
+      session_id: this.sessionId,
+      run_id: this.runId,
+      trace_id: this.traceId,
+      span_id: spanId ?? randomUUID(),
+    };
+  }
+
+  // Called when a chain starts
+  async handleChainStart(_chain: unknown, _inputs: unknown, runId: string) {
+    const stepId = randomUUID();
+    this.stepIds.set(runId, stepId);
+    this.client.enqueue({
+      ...this.base(randomUUID()),
+      step_id: stepId,
+      event_type: 'agent.step.started',
+      step_type: 'chain',
+      sequence: 0,
+    });
+  }
+
+  // Called when a chain ends
+  async handleChainEnd(_outputs: unknown, runId: string) {
+    const stepId = this.stepIds.get(runId);
+    this.client.enqueue({
+      ...this.base(),
+      step_id: stepId,
+      event_type: 'agent.step.completed',
+    });
+    this.stepIds.delete(runId);
+  }
+
+  // Called when an LLM starts
+  async handleLLMStart(
+    llm: LangChainLlmStartInput,
+    _prompts: string[],
+    runId: string,
+  ) {
+    this.startTimes.set(runId, Date.now());
+    this.client.enqueue({
+      ...this.base(),
+      event_type: 'llm.request.started',
+      provider: 'langchain',
+      model: llm.name ?? 'unknown',
+    });
+  }
+
+  // Called when an LLM ends
+  async handleLLMEnd(output: LangChainLlmEndOutput, runId: string) {
+    const startMs = this.startTimes.get(runId);
+    const latencyMs = startMs ? Date.now() - startMs : undefined;
+    this.startTimes.delete(runId);
+
+    // Extract token usage from llmOutput if available
+    const usage = output.llmOutput?.['tokenUsage'] as Record<string, number> | undefined;
+
+    this.client.enqueue({
+      ...this.base(),
+      event_type: 'llm.request.completed',
+      provider: 'langchain',
+      model: 'unknown',
+      latency_ms: latencyMs,
+      status: 'success',
+      input_tokens: usage?.['promptTokens'],
+      output_tokens: usage?.['completionTokens'],
+      total_tokens: usage?.['totalTokens'],
+    });
+  }
+
+  // Called when an LLM errors
+  async handleLLMError(err: Error, runId: string) {
+    const startMs = this.startTimes.get(runId);
+    const latencyMs = startMs ? Date.now() - startMs : undefined;
+    this.startTimes.delete(runId);
+
+    this.client.enqueue({
+      ...this.base(),
+      event_type: 'llm.request.completed',
+      provider: 'langchain',
+      model: 'unknown',
+      latency_ms: latencyMs,
+      status: 'error',
+    });
+  }
+
+  // Called when a tool starts
+  async handleToolStart(_tool: unknown, _input: string, runId: string) {
+    this.toolStartTimes.set(runId, Date.now());
+    this.client.enqueue({
+      ...this.base(),
+      event_type: 'tool.call.started',
+      tool_name: 'unknown',
+    });
+  }
+
+  // Called when a tool ends
+  async handleToolEnd(output: string, runId: string) {
+    const startMs = this.toolStartTimes.get(runId);
+    const latencyMs = startMs ? Date.now() - startMs : undefined;
+    this.toolStartTimes.delete(runId);
+
+    this.client.enqueue({
+      ...this.base(),
+      event_type: 'tool.call.completed',
+      tool_name: 'unknown',
+      latency_ms: latencyMs,
+      status: 'success',
+      output_size_bytes: Buffer.byteLength(output ?? '', 'utf8'),
+    });
+  }
+
+  // Called when a tool errors
+  async handleToolError(err: Error, runId: string) {
+    const startMs = this.toolStartTimes.get(runId);
+    const latencyMs = startMs ? Date.now() - startMs : undefined;
+    this.toolStartTimes.delete(runId);
+
+    this.client.enqueue({
+      ...this.base(),
+      event_type: 'tool.call.completed',
+      tool_name: 'unknown',
+      latency_ms: latencyMs,
+      status: 'error',
+    });
+  }
+}

package/src/integrations/openai.ts

@@ -0,0 +1,109 @@
+/**
+ * OpenAI SDK wrapper for Sensu telemetry.
+ * Wraps the OpenAI client to automatically track all completions.
+ *
+ * Usage:
+ *   import { wrapOpenAI } from '@sensu-ai/sdk/integrations/openai';
+ *   const openai = wrapOpenAI(new OpenAI({ apiKey }), { client: sensu, runHandle });
+ *   const resp = await openai.chat.completions.create({ ... }); // auto-tracked
+ */
+
+import type { SensuClient, RunHandle } from '../client.ts';
+
+interface OpenAILike {
+  chat: {
+    completions: {
+      create: (params: unknown) => Promise<unknown>;
+    };
+  };
+}
+
+interface WrapOpenAIOptions {
+  client: SensuClient;
+  runHandle?: RunHandle;
+  defaultModel?: string;
+  defaultProvider?: string;
+}
+
+interface CompletionUsage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  total_tokens?: number;
+}
+
+interface CompletionResponse {
+  usage?: CompletionUsage;
+  model?: string;
+}
+
+export function wrapOpenAI<T extends OpenAILike>(
+  openai: T,
+  opts: WrapOpenAIOptions,
+): T {
+  const { client, runHandle } = opts;
+
+  const originalCreate = openai.chat.completions.create.bind(
+    openai.chat.completions,
+  );
+
+  openai.chat.completions.create = async (params: unknown): Promise<unknown> => {
+    const p = params as Record<string, unknown>;
+    const model = (p['model'] as string | undefined) ?? opts.defaultModel ?? 'unknown';
+    const provider = opts.defaultProvider ?? 'openai';
+
+    let step: import('../client.js').StepHandle | undefined;
+    if (runHandle) {
+      step = runHandle.startStep({ name: 'openai-completion', stepType: 'llm' });
+    }
+
+    const startMs = Date.now();
+    let result: unknown;
+    let status: 'success' | 'error' = 'success';
+    let err: unknown;
+
+    try {
+      result = await originalCreate(params);
+    } catch (e) {
+      status = 'error';
+      err = e;
+    }
+
+    const latencyMs = Date.now() - startMs;
+    const r = result as CompletionResponse | undefined;
+    const usage = r?.usage;
+
+    const callOpts = {
+      provider,
+      model: r?.model ?? model,
+      input_tokens: usage?.prompt_tokens,
+      output_tokens: usage?.completion_tokens,
+      total_tokens: usage?.total_tokens,
+      latency_ms: latencyMs,
+      status,
+    };
+
+    if (step) {
+      step.recordLlm(callOpts);
+      void step.end();
+    } else {
+      // Emit standalone if no step context
+      client.enqueue({
+        event_id: crypto.randomUUID(),
+        event_type: 'llm.request.completed',
+        timestamp: new Date().toISOString(),
+        org_id: (client as unknown as { orgId: string }).orgId,
+        agent_id: (client as unknown as { agentId: string }).agentId,
+        session_id: crypto.randomUUID(),
+        run_id: crypto.randomUUID(),
+        trace_id: crypto.randomUUID(),
+        span_id: crypto.randomUUID(),
+        ...callOpts,
+      });
+    }
+
+    if (err) throw err;
+    return result;
+  };
+
+  return openai;
+}

package/src/types.ts

@@ -0,0 +1,65 @@
+export interface SensuClientOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  agentId?: string;
+  orgId?: string;
+  /** Read config from environment variables */
+  fromEnv?: boolean;
+  /** Flush buffer when this many events accumulate */
+  batchSize?: number;
+  /** Flush buffer every N milliseconds */
+  flushIntervalMs?: number;
+  /** Disable all telemetry (useful for tests) */
+  disabled?: boolean;
+}
+
+export interface StartRunOptions {
+  sessionId?: string;
+  runType?: string;
+  endUserId?: string;
+  runId?: string;
+}
+
+export interface StartStepOptions {
+  name?: string;
+  stepType?: string;
+  sequence?: number;
+  stepId?: string;
+}
+
+export interface TrackLlmOptions {
+  provider: string;
+  model: string;
+  /** Wraps the LLM call and measures latency automatically */
+  fn: () => Promise<unknown>;
+  maxContextTokens?: number;
+}
+
+export interface LlmResult {
+  inputTokens?: number;
+  outputTokens?: number;
+  cachedInputTokens?: number;
+  totalTokens?: number;
+  costUsdEstimate?: number;
+  result: unknown;
+}
+
+export interface TrackToolOptions {
+  toolName: string;
+  fn: () => Promise<unknown>;
+}
+
+export interface RawLlmCallOptions {
+  provider: string;
+  model: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  cachedInputTokens?: number;
+  totalTokens?: number;
+  maxContextTokens?: number;
+  contextUsedTokens?: number;
+  latencyMs?: number;
+  ttftMs?: number;
+  costUsdEstimate?: number;
+  status?: 'success' | 'error' | 'timeout';
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}