@tangle-network/sdk-telemetry 0.1.8

package/dist/index.d.mts

@@ -0,0 +1,968 @@
+import { LifecycleOp, PROVISION_TRACE_ID_HEADER, PTID_PREFIX, RecordOptions, ServerTimingEntry, SpanComponent, SpanRecorder, SpanStatus, StageSpan, StageSpanInput, isAdoptablePtid, mintPtid, monotonicNs, parseServerTiming, readOrMintPtid, spanDurationMs } from "./stage-span.mjs";
+import { AgentEvent, ErrorEvent as AgentErrorEvent, FilePart, GEN_AI_CONVERSATION_ID, GEN_AI_INPUT_TOKEN_KEYS, GEN_AI_MODEL_KEYS, GEN_AI_OPERATION_NAME, GEN_AI_OUTPUT_TOKEN_KEYS, GEN_AI_REQUEST_MODEL, GEN_AI_RESPONSE_MODEL, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, GenAiUsage, MessagePartUpdatedEvent, MessagePartUpdatedEvent as MessagePartUpdatedEvent$1, ParsedSSEEvent, Part, ReasoningPart, ResultEvent, SSEChunkParser, SSEEventData, SSEEventData as SSEEventData$1, SSEParserOptions, StatusEvent, Storage, StreamTokenUsage, StreamUsageAccumulator, StreamUsageExtractor, TOKEN_USAGE_COST_KEYS, TOKEN_USAGE_INPUT_KEYS, TOKEN_USAGE_OUTPUT_KEYS, TextPart, TokenUsageCounts, ToolPart, ToolState, addTokenUsage, consumeSSEStream, createStreamUsageExtractor, createUsageCallback, firstTokenCount, firstUsageCostUsd, genAiUsageAttributes, isFilePart, isReasoningPart, isTextPart, isToolPart, parseSSEData as parseSSEData$1, parseSSEStream, readTokenCostUsd, readTokenUsage, tokenCount, tokenUsageSource } from "@tangle-network/agent-core";
+
+//#region src/types.d.ts
+/**
+ * Telemetry Types
+ *
+ * Type definitions for usage tracking, credit management,
+ * and telemetry data collection.
+ */
+interface CreditBalance {
+  available: number;
+  used: number;
+  limit: number;
+  resetAt?: Date;
+  currency: "credits" | "usd" | "tokens";
+}
+interface CreditTransaction {
+  id: string;
+  type: "charge" | "refund" | "grant" | "adjustment";
+  amount: number;
+  balance: number;
+  description: string;
+  metadata?: Record<string, unknown>;
+  timestamp: Date;
+}
+interface UsageRecord {
+  id: string;
+  projectRef: string;
+  userId?: string;
+  operation: string;
+  credits: number;
+  durationMs?: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  metadata?: Record<string, unknown>;
+  timestamp: Date;
+}
+interface UsageSummary {
+  projectRef: string;
+  period: "hour" | "day" | "week" | "month";
+  periodStart: Date;
+  periodEnd: Date;
+  totalCredits: number;
+  totalOperations: number;
+  totalDurationMs: number;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  operationBreakdown: Record<string, number>;
+}
+type TelemetryEventType = "session_start" | "session_end" | "api_request" | "api_response" | "agent_execution" | "error" | "performance" | "custom";
+interface TelemetryEvent {
+  id: string;
+  type: TelemetryEventType;
+  name: string;
+  projectRef?: string;
+  sessionId?: string;
+  userId?: string;
+  data: Record<string, unknown>;
+  timestamp: Date;
+  sequence: number;
+}
+interface PerformanceMetric {
+  name: string;
+  value: number;
+  unit: "ms" | "bytes" | "count" | "percent";
+  tags?: Record<string, string>;
+  timestamp: Date;
+}
+interface TelemetryConfig {
+  enabled: boolean;
+  projectRef?: string;
+  userId?: string;
+  sessionId?: string;
+  flushIntervalMs?: number;
+  maxBatchSize?: number;
+  maxQueueSize?: number;
+  endpoint?: string;
+  sampleRate?: number;
+  excludePatterns?: string[];
+  includeMetadata?: boolean;
+  persistOffline?: boolean;
+}
+interface CreditTrackerConfig {
+  projectRef: string;
+  userId?: string;
+  endpoint?: string;
+  refreshIntervalMs?: number;
+  warningThreshold?: number;
+  criticalThreshold?: number;
+  onLowBalance?: (balance: CreditBalance) => void;
+  onCriticalBalance?: (balance: CreditBalance) => void;
+  onBalanceUpdate?: (balance: CreditBalance) => void;
+}
+interface UsageTrackerConfig {
+  projectRef: string;
+  userId?: string;
+  autoTrack?: boolean;
+  trackApiCalls?: boolean;
+  trackAgentExecutions?: boolean;
+  trackErrors?: boolean;
+  batchSize?: number;
+  flushIntervalMs?: number;
+}
+interface TelemetrySink {
+  name: string;
+  send(events: TelemetryEvent[]): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+interface CreditProvider {
+  getBalance(): Promise<CreditBalance>;
+  getTransactions(options?: {
+    limit?: number;
+    offset?: number;
+    since?: Date;
+  }): Promise<CreditTransaction[]>;
+  checkCredit(amount: number): Promise<boolean>;
+  reserveCredit(amount: number): Promise<string | null>;
+  releaseReservation(reservationId: string): Promise<void>;
+  chargeReservation(reservationId: string, actualAmount?: number): Promise<CreditTransaction>;
+}
+interface UsageProvider {
+  recordUsage(record: Omit<UsageRecord, "id" | "timestamp">): Promise<string>;
+  getUsage(options?: {
+    projectRef?: string;
+    since?: Date;
+    until?: Date;
+    limit?: number;
+  }): Promise<UsageRecord[]>;
+  getSummary(projectRef: string, period: UsageSummary["period"]): Promise<UsageSummary>;
+}
+interface ApiMetric {
+  path: string;
+  method: string;
+  status: number;
+  durationMs: number;
+  requestSize?: number;
+  responseSize?: number;
+  error?: string;
+  timestamp: Date;
+}
+interface AgentMetric {
+  identifier: string;
+  projectRef: string;
+  executionId: string;
+  durationMs: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  toolCalls?: number;
+  success: boolean;
+  error?: string;
+  timestamp: Date;
+}
+//#endregion
+//#region src/credits.d.ts
+declare class CreditTracker {
+  private readonly config;
+  private readonly provider;
+  private readonly storage?;
+  private cachedBalance?;
+  private lastRefresh?;
+  private refreshTimer?;
+  private reservations;
+  constructor(config: CreditTrackerConfig, provider: CreditProvider, storage?: Storage);
+  getBalance(forceRefresh?: boolean): Promise<CreditBalance>;
+  getTransactions(options?: {
+    limit?: number;
+    offset?: number;
+    since?: Date;
+  }): Promise<CreditTransaction[]>;
+  hasCredits(amount: number): Promise<boolean>;
+  reserve(amount: number, options?: {
+    ttlMs?: number;
+  }): Promise<string | null>;
+  release(reservationId: string): Promise<void>;
+  charge(reservationId: string, actualAmount?: number): Promise<CreditTransaction>;
+  chargeImmediate(amount: number, _description: string): Promise<CreditTransaction | null>;
+  getReservedTotal(): number;
+  getEffectiveBalance(): number;
+  getUsagePercent(): number;
+  getRemainingPercent(): number;
+  isLow(): boolean;
+  isCritical(): boolean;
+  close(): Promise<void>;
+  private isStale;
+  private checkThresholds;
+  private cleanupExpiredReservations;
+  private startRefreshTimer;
+  private stopRefreshTimer;
+}
+declare class MemoryCreditProvider implements CreditProvider {
+  private balance;
+  private transactions;
+  private reservations;
+  constructor(initialBalance?: Partial<CreditBalance>);
+  getBalance(): Promise<CreditBalance>;
+  getTransactions(options?: {
+    limit?: number;
+    offset?: number;
+    since?: Date;
+  }): Promise<CreditTransaction[]>;
+  checkCredit(amount: number): Promise<boolean>;
+  reserveCredit(amount: number): Promise<string | null>;
+  releaseReservation(reservationId: string): Promise<void>;
+  chargeReservation(reservationId: string, actualAmount?: number): Promise<CreditTransaction>;
+  addCredits(amount: number, description: string): CreditTransaction;
+}
+declare function createCreditTracker(config: CreditTrackerConfig, provider: CreditProvider, storage?: Storage): CreditTracker;
+//#endregion
+//#region src/enrichment/types.d.ts
+/**
+ * Enrichment Types
+ *
+ * Types for client-forwarded metadata blobs and parsed enrichment context.
+ * Partners can send arbitrary metadata that gets parsed by registered adapters
+ * and attached to traces for analytics and tenant isolation.
+ */
+/** Supported blob formats for metadata transmission */
+type MetadataBlobFormat = "json" | "msgpack" | "protobuf";
+/** Client-forwarded metadata blob */
+interface MetadataBlob {
+  /** Serialization format of the data */
+  format: MetadataBlobFormat;
+  /** Serialized data (base64 for binary formats) */
+  data: string | Buffer;
+  /** Optional schema identifier for validation */
+  schema?: string;
+}
+/** Product context for trace classification */
+type ProductType = "vibe_coding" | "simulation" | "background_agent";
+/** Environment context */
+type EnvironmentType = "development" | "staging" | "production";
+/** Subscription tier for rate limiting and feature gating */
+type SubscriptionTier = "free" | "pro" | "enterprise";
+/**
+ * Parsed enrichment context attached to traces.
+ * Built from partner metadata blobs via adapters.
+ */
+interface EnrichmentContext {
+  /** Partner identifier for tenant isolation */
+  partnerId?: string;
+  /** Subscription tier for rate limiting */
+  subscriptionTier?: SubscriptionTier;
+  /** End user identifier within partner's system */
+  endUserId?: string;
+  /** Product context */
+  product?: ProductType;
+  /** Deployment environment */
+  environment?: EnvironmentType;
+  /** Custom key-value labels for filtering */
+  customLabels: Record<string, string>;
+  /** Original blob for audit/replay */
+  rawBlob?: MetadataBlob;
+}
+/**
+ * Adapter interface for parsing metadata blobs.
+ * Register adapters to handle different blob formats or schemas.
+ */
+interface MetadataBlobAdapter {
+  /** Unique adapter name */
+  name: string;
+  /** Check if this adapter can parse the given blob */
+  canParse(blob: MetadataBlob): boolean;
+  /** Parse blob into enrichment context fields */
+  parse(blob: MetadataBlob): Partial<EnrichmentContext>;
+}
+/** Create an empty enrichment context with defaults */
+declare function createEmptyContext(): EnrichmentContext;
+//#endregion
+//#region src/enrichment/adapter-registry.d.ts
+/** Registry for metadata blob adapters */
+declare class AdapterRegistry {
+  private adapters;
+  /** Register an adapter (added to end of chain) */
+  register(adapter: MetadataBlobAdapter): void;
+  /** Unregister an adapter by name */
+  unregister(name: string): boolean;
+  /** Get all registered adapter names */
+  getAdapterNames(): string[];
+  /**
+   * Parse a metadata blob using registered adapters.
+   * Returns enrichment context with parsed fields.
+   * Stores original blob in rawBlob for audit.
+   */
+  parse(blob: MetadataBlob): EnrichmentContext;
+  /** Check if any adapter can parse the given blob */
+  canParse(blob: MetadataBlob): boolean;
+}
+/** Get or create the default adapter registry */
+declare function getDefaultRegistry(): AdapterRegistry;
+/** Reset the default registry (for testing) */
+declare function resetDefaultRegistry(): void;
+//#endregion
+//#region src/enrichment/json-adapter.d.ts
+/** JSON adapter for parsing metadata blobs */
+declare const jsonAdapter: MetadataBlobAdapter;
+/** Create a JSON adapter instance */
+declare function createJsonAdapter(): MetadataBlobAdapter;
+//#endregion
+//#region src/enrichment/index.d.ts
+/**
+ * Initialize the default registry with built-in adapters.
+ * Call this at startup to ensure JSON adapter is available.
+ */
+declare function initializeDefaultAdapters(): void;
+/**
+ * Parse a metadata blob using the default registry.
+ * Convenience function for common use case.
+ */
+declare function parseMetadataBlob(blob: MetadataBlob): EnrichmentContext;
+//#endregion
+//#region src/trace-types.d.ts
+/**
+ * MessagePartUpdatedEvent with timestamp for trace collection.
+ * This is the canonical event type from OpenCode - pass through without transformation.
+ */
+interface MessagePartUpdatedEventWithTimestamp extends MessagePartUpdatedEvent$1 {
+  /** Timestamp when event was recorded */
+  timestamp: Date;
+}
+/** Type guard for MessagePartUpdatedEvent */
+declare function isMessagePartUpdatedEvent(event: TraceEvent): event is MessagePartUpdatedEventWithTimestamp;
+/** Execution scope for trace association */
+interface TraceScope {
+  projectRef?: string;
+  sessionId?: string;
+  /** Links sub-agent sessions to their parent session */
+  parentSessionId?: string;
+  userId?: string;
+  /**
+   * Tangle Intelligence resource attributes for this scope — the `tangle.*`
+   * dimensions a partner filters on (partner / project / domain / pseudonymous
+   * end-user). Built host-side and threaded per session; stamped onto every
+   * exported span by the OTEL sink. Kept as an open bag so new dimensions flow
+   * through without a schema change.
+   */
+  resourceAttributes?: Record<string, string>;
+}
+/** Success/failure signals captured during execution */
+type Signal = "build_passed" | "build_failed" | "tests_passed" | "tests_failed" | "lint_passed" | "lint_failed" | "user_approved" | "user_rejected" | "task_completed" | "task_abandoned" | "runtime_error" | "timeout";
+interface SignalEvent {
+  signal: Signal;
+  timestamp: Date;
+  metadata?: Record<string, unknown>;
+}
+/** Base fields shared by all trace events */
+interface TraceEventBase {
+  timestamp: Date;
+}
+/** Message updated event (final model text and result metadata) */
+interface MessageUpdatedEvent extends TraceEventBase {
+  type: "message.updated";
+  /** Final text content */
+  text?: string;
+  /** Legacy alias for text */
+  finalText?: string;
+  /** Token usage details */
+  tokenUsage?: Record<string, unknown>;
+  /** Timing details */
+  timing?: Record<string, unknown>;
+  /** Tool invocations captured during execution */
+  toolInvocations?: unknown[];
+  /** Additional metadata */
+  metadata?: Record<string, unknown>;
+}
+/** Error event */
+interface ErrorEvent extends TraceEventBase {
+  type: "error";
+  /** Error category */
+  category: "runtime" | "syntax" | "type" | "network" | "timeout" | "unknown";
+  /** Error message */
+  message: string;
+  /** Stack trace if available */
+  stack?: string;
+  /** Error code if available */
+  code?: string;
+  /** Source of error (tool name, file, etc.) */
+  source?: string;
+}
+/** Diagnostic severity levels */
+type DiagnosticSeverity = "error" | "warning" | "info" | "hint";
+/** Individual diagnostic message */
+interface Diagnostic {
+  /** Severity level */
+  severity: DiagnosticSeverity;
+  /** Diagnostic message */
+  message: string;
+  /** Diagnostic code (e.g., "TS2304", "E0001") */
+  code?: string | number;
+  /** Source (e.g., "typescript", "eslint") */
+  source?: string;
+  /** Start line (0-indexed) */
+  startLine: number;
+  /** Start column (0-indexed) */
+  startColumn: number;
+  /** End line (0-indexed) */
+  endLine: number;
+  /** End column (0-indexed) */
+  endColumn: number;
+}
+/** Summary of diagnostics for a file */
+interface DiagnosticSummary {
+  errors: number;
+  warnings: number;
+  infos: number;
+  hints: number;
+}
+/** Diagnostic change event - captured after file edits */
+interface DiagnosticEvent extends TraceEventBase {
+  type: "diagnostic";
+  /** File path */
+  file: string;
+  /** Language server ID */
+  serverId?: string;
+  /** Language (e.g., "typescript", "python") */
+  language?: string;
+  /** Diagnostics before the change */
+  before?: Diagnostic[];
+  /** Diagnostics after the change */
+  after: Diagnostic[];
+  /** Summary counts before */
+  beforeSummary?: DiagnosticSummary;
+  /** Summary counts after */
+  afterSummary: DiagnosticSummary;
+  /** Net change in error count (negative = improvement) */
+  errorDelta: number;
+  /** Diagnostics that were resolved */
+  resolved?: Diagnostic[];
+  /** Diagnostics that were introduced */
+  introduced?: Diagnostic[];
+}
+/** File change event */
+interface FileChangeEvent extends TraceEventBase {
+  type: "file_change";
+  /** File path */
+  file: string;
+  /** Change type */
+  changeType: "created" | "modified" | "deleted";
+  /** Lines added */
+  linesAdded?: number;
+  /** Lines removed */
+  linesRemoved?: number;
+}
+/** Build result event */
+interface BuildResultEvent extends TraceEventBase {
+  type: "build_result";
+  /** Build command */
+  command?: string;
+  /** Whether build succeeded */
+  success: boolean;
+  /** Duration in milliseconds */
+  durationMs?: number;
+  /** Error count */
+  errorCount?: number;
+  /** Warning count */
+  warningCount?: number;
+}
+/** Test result event */
+interface TestResultEvent extends TraceEventBase {
+  type: "test_result";
+  /** Test command */
+  command?: string;
+  /** Whether all tests passed */
+  success: boolean;
+  /** Duration in milliseconds */
+  durationMs?: number;
+  /** Number of tests passed */
+  passed?: number;
+  /** Number of tests failed */
+  failed?: number;
+  /** Number of tests skipped */
+  skipped?: number;
+}
+/** Environment snapshot at trace start */
+interface EnvironmentEvent extends TraceEventBase {
+  type: "environment";
+  /** Runtime versions */
+  versions?: Record<string, string>;
+  /** Working directory */
+  workingDir?: string;
+  /** Platform info */
+  platform?: string;
+}
+/** Generic event for extensibility (use sparingly) */
+interface CustomEvent extends TraceEventBase {
+  type: "custom";
+  /** Custom event name */
+  name: string;
+  /** Custom event data */
+  data: Record<string, unknown>;
+}
+/** Batch execution started event */
+interface BatchStartedEvent extends TraceEventBase {
+  type: "batch_started";
+  /** Unique batch execution ID */
+  batchId: string;
+  /** Number of tasks in the batch */
+  taskCount: number;
+  /** Number of backends being tested */
+  backendCount: number;
+  /** Total executions (tasks × backends) */
+  totalExecutions: number;
+  /** Scaling mode used */
+  scalingMode?: "fastest" | "balanced" | "cheapest";
+}
+/** Batch execution completed event */
+interface BatchCompletedEvent extends TraceEventBase {
+  type: "batch_completed";
+  /** Unique batch execution ID */
+  batchId: string;
+  /** Number of successful task executions */
+  successCount: number;
+  /** Number of failed task executions */
+  failureCount: number;
+  /** Success rate as percentage (0-100) */
+  successRate: number;
+  /** Total duration in milliseconds */
+  durationMs: number;
+  /** Total tokens used across all executions */
+  totalTokensUsed?: number;
+}
+/** Individual task within a batch completed */
+interface BatchTaskCompletedEvent extends TraceEventBase {
+  type: "batch_task_completed";
+  /** Parent batch ID */
+  batchId: string;
+  /** Task ID within the batch */
+  taskId: string;
+  /** Backend used for this execution */
+  backend: string;
+  /** Whether the task succeeded */
+  success: boolean;
+  /** Duration in milliseconds */
+  durationMs: number;
+  /** Attempt number (1 = first try) */
+  attempt: number;
+  /** Number of retries before success/failure */
+  retries: number;
+  /** Tokens used for this task */
+  tokensUsed?: number;
+  /** Error message if failed */
+  error?: string;
+}
+/** Union of all trace event types */
+type TraceEvent = MessagePartUpdatedEventWithTimestamp | MessageUpdatedEvent | ErrorEvent | DiagnosticEvent | FileChangeEvent | BuildResultEvent | TestResultEvent | EnvironmentEvent | CustomEvent | BatchStartedEvent | BatchCompletedEvent | BatchTaskCompletedEvent;
+/** Event type discriminator */
+type TraceEventType = TraceEvent["type"];
+declare function isMessageUpdatedEvent(event: TraceEvent): event is MessageUpdatedEvent;
+declare function isErrorEvent(event: TraceEvent): event is ErrorEvent;
+declare function isDiagnosticEvent(event: TraceEvent): event is DiagnosticEvent;
+declare function isFileChangeEvent(event: TraceEvent): event is FileChangeEvent;
+declare function isBuildResultEvent(event: TraceEvent): event is BuildResultEvent;
+declare function isTestResultEvent(event: TraceEvent): event is TestResultEvent;
+declare function isEnvironmentEvent(event: TraceEvent): event is EnvironmentEvent;
+declare function isCustomEvent(event: TraceEvent): event is CustomEvent;
+/** Execution outcome derived from signals */
+type Outcome = "success" | "partial" | "failure" | "unknown";
+/** Execution trace - complete record of an agent task */
+interface ExecutionTrace {
+  id: string;
+  scope: TraceScope;
+  task: string;
+  events: TraceEvent[];
+  signals: SignalEvent[];
+  outcome: Outcome;
+  startedAt: Date;
+  completedAt?: Date;
+  metadata?: Record<string, unknown>;
+}
+//#endregion
+//#region src/langfuse-sink.d.ts
+/** Langfuse sink configuration */
+interface LangfuseSinkConfig {
+  /** Langfuse public key */
+  publicKey: string;
+  /** Langfuse secret key */
+  secretKey: string;
+  /** Langfuse host (default: https://cloud.langfuse.com) */
+  baseUrl?: string;
+  /** Enable debug logging */
+  debug?: boolean;
+}
+/**
+ * Langfuse trace exporter using the native SDK.
+ *
+ * Creates proper Langfuse traces with spans and generations
+ * for rich observability in the Langfuse dashboard.
+ *
+ * Note: This is a trace-level exporter (ExecutionTrace), not a
+ * TelemetrySink (TelemetryEvent). Use for exporting complete traces.
+ */
+declare class LangfuseSink {
+  readonly name = "langfuse";
+  private readonly config;
+  constructor(config: LangfuseSinkConfig);
+  /**
+   * Export an execution trace to Langfuse.
+   */
+  exportTrace(trace: ExecutionTrace): Promise<void>;
+  /**
+   * Export a trace event as a Langfuse span or generation.
+   */
+  private exportTraceEvent;
+  /**
+   * Export a tool part from message.part.updated event.
+   * Tool parts have state progression: pending → running → completed/error
+   */
+  private exportToolPart;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+/**
+ * Create a Langfuse sink from environment variables.
+ */
+declare function createLangfuseSinkFromEnv(): LangfuseSink | null;
+//#endregion
+//#region src/otel-provider.d.ts
+/**
+ * Global OpenTelemetry tracer provider for the in-container agent loop.
+ *
+ * Registers a Node TracerProvider + batching OTLP/HTTP exporter so the GLOBAL
+ * tracer (`@opentelemetry/api` `trace.getTracer`, used by the OTel sink) ships
+ * spans to the configured collector (Tangle Intelligence) instead of being a
+ * no-op. Endpoint + headers come from the standard OTEL env the host threads in
+ * (`OTEL_EXPORTER_OTLP_ENDPOINT` / `OTEL_EXPORTER_OTLP_HEADERS`); per-session
+ * partner/project/user resource attributes are stamped on spans by the sink,
+ * not here.
+ *
+ * Opt-in + best-effort:
+ *   - a no-op unless `TELEMETRY_ENABLED=true` AND an endpoint is set;
+ *   - any SDK import / construction failure degrades to disabled, never crashes
+ *     the sidecar (telemetry must never take down the agent);
+ *   - idempotent — a second `initOtelProvider` returns the already-active result.
+ */
+interface InitOtelProviderResult {
+  active: boolean;
+  reason?: string;
+}
+declare function initOtelProvider(serviceName: string): Promise<InitOtelProviderResult>;
+declare function shutdownOtelProvider(): Promise<void>;
+//#endregion
+//#region src/otel-sink.d.ts
+/** Configuration for the OTEL sink */
+interface OtelSinkConfig {
+  /** Service name for the tracer */
+  serviceName?: string;
+  /** Include raw input/output in span attributes (may contain sensitive data) */
+  includePayloads?: boolean;
+}
+/**
+ * OpenTelemetry sink — exports via whatever OTEL SDK config was set at
+ * application startup (Langfuse, Jaeger, any OTLP backend).
+ */
+declare class OtelTelemetrySink implements TelemetrySink {
+  readonly name = "otel";
+  private readonly config;
+  constructor(config?: OtelSinkConfig);
+  send(events: TelemetryEvent[]): Promise<void>;
+  /**
+   * Export an execution trace as OTEL spans.
+   *
+   * Creates a parent span for the trace and child spans for each event.
+   * Uses the global tracer, so spans flow through the configured processor.
+   */
+  exportTrace(trace: ExecutionTrace): Promise<void>;
+  /**
+   * Export a single trace event as an OTEL span.
+   */
+  private exportTraceEvent;
+  private getEventStartTime;
+  private getEventEndTime;
+  private getStartupPhaseDurationMs;
+  /**
+   * Get span name for a trace event.
+   */
+  private getSpanName;
+  /**
+   * Get OTEL attributes for a trace event.
+   */
+  private getEventAttributes;
+  /**
+   * Flatten metadata object into span attributes
+   */
+  private flattenMetadata;
+  /** Narrow an opaque telemetry `data.trace` to an ExecutionTrace. */
+  private isExecutionTrace;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+/**
+ * Create an OTEL sink that uses the global tracer.
+ *
+ * The OTEL SDK must be initialized separately before using this sink.
+ */
+declare function createOtelSink(config?: OtelSinkConfig): OtelTelemetrySink;
+/**
+ * Create an OTEL sink from environment variables.
+ *
+ * Returns a sink that uses the global tracer (which should be initialized
+ * separately via NodeSDK with LangfuseSpanProcessor or OTLPTraceExporter).
+ */
+declare function createOtelSinkFromEnv(): OtelTelemetrySink | null;
+//#endregion
+//#region src/sinks.d.ts
+declare class HttpTelemetrySink implements TelemetrySink {
+  readonly name = "http";
+  private readonly endpoint;
+  private readonly headers;
+  private readonly fetchFn;
+  private readonly timeout;
+  private pendingRequests;
+  constructor(config: {
+    endpoint: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+    timeout?: number;
+  });
+  send(events: TelemetryEvent[]): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+declare class ConsoleTelemetrySink implements TelemetrySink {
+  readonly name = "console";
+  private readonly prefix;
+  private readonly logLevel;
+  private readonly formatJson;
+  constructor(config?: {
+    prefix?: string;
+    logLevel?: "log" | "debug" | "info";
+    formatJson?: boolean;
+  });
+  send(events: TelemetryEvent[]): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+declare class TestTelemetrySink implements TelemetrySink {
+  readonly name = "test";
+  readonly events: TelemetryEvent[];
+  send(events: TelemetryEvent[]): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+  clear(): void;
+  getEvents(): TelemetryEvent[];
+  getEventsByType(type: string): TelemetryEvent[];
+  getEventsByName(name: string): TelemetryEvent[];
+}
+declare class MultiTelemetrySink implements TelemetrySink {
+  readonly name = "multi";
+  private readonly sinks;
+  constructor(sinks: TelemetrySink[]);
+  send(events: TelemetryEvent[]): Promise<void>;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+}
+declare function createHttpSink(config: {
+  endpoint: string;
+  headers?: Record<string, string>;
+  fetch?: typeof fetch;
+  timeout?: number;
+}): HttpTelemetrySink;
+declare function createConsoleSink(config?: {
+  prefix?: string;
+  logLevel?: "log" | "debug" | "info";
+}): ConsoleTelemetrySink;
+declare function createTestSink(): TestTelemetrySink;
+//#endregion
+//#region src/sse-parser.d.ts
+declare const parseSSEData: typeof parseSSEData$1;
+/**
+ * Convert SSE event data to a typed TraceEvent.
+ * Returns null for events that should be skipped (heartbeats, status-only, etc.)
+ *
+ * message.part.updated events are passed through directly - no transformation.
+ * This preserves full fidelity to what OpenCode outputs.
+ *
+ * `raw` events that carry a recognized tool-invocation payload are
+ * normalized into the same `message.part.updated` shape (with a
+ * `ToolPart`) so consumers don't need to reach into provider-specific
+ * raw shapes to render tool calls. Unrecognized raw events fall
+ * through to a `custom` trace event.
+ */
+declare function sseToTraceEvent(event: SSEEventData$1): TraceEvent | null;
+/**
+ * Extract a signal from an SSE event if present.
+ */
+declare function sseToSignal(event: SSEEventData$1): SignalEvent | null;
+/**
+ * Check if an SSE event indicates completion (success or failure).
+ */
+declare function isCompletionEvent(event: SSEEventData$1): {
+  complete: boolean;
+  success: boolean;
+};
+//#endregion
+//#region src/trace-collector.d.ts
+interface TraceCollectorConfig {
+  /** Sink to export traces to */
+  sink: TelemetrySink;
+  /** Max traces to buffer before auto-flush */
+  maxBufferSize?: number;
+  /** Auto-flush interval in ms (0 = manual only) */
+  flushIntervalMs?: number;
+  /** Default scope for new traces */
+  defaultScope?: TraceScope;
+}
+/** Active trace context for tracking a single execution */
+interface TraceContext {
+  traceId: string;
+  startedAt: Date;
+  /** Add a typed event to the trace */
+  addEvent<T extends TraceEvent>(event: Omit<T, "timestamp">): void;
+  /** Add a signal (success/failure indicator) */
+  addSignal(signal: Signal, metadata?: Record<string, unknown>): void;
+  /** Complete the trace successfully */
+  complete(metadata?: Record<string, unknown>): ExecutionTrace;
+  /** Complete the trace with failure */
+  fail(error: string | Error, metadata?: Record<string, unknown>): ExecutionTrace;
+  /** Abandon the trace */
+  abandon(): ExecutionTrace;
+}
+declare class TraceCollector {
+  private sink;
+  private config;
+  private activeTraces;
+  private completedTraces;
+  private flushTimer?;
+  private sequence;
+  constructor(config: TraceCollectorConfig);
+  /** Start tracking a new execution */
+  startTrace(task: string, scope?: TraceScope, metadata?: Record<string, unknown>): TraceContext;
+  /** Convenience: track a complete execution with a wrapper function */
+  track<T>(task: string, fn: (ctx: TraceContext) => Promise<T>, options?: {
+    scope?: TraceScope;
+    metadata?: Record<string, unknown>;
+  }): Promise<{
+    result: T;
+    trace: ExecutionTrace;
+  }>;
+  /** Flush completed traces to sink */
+  flush(): Promise<void>;
+  /** Get count of pending traces */
+  getPendingCount(): number;
+  /** Get active trace count */
+  getActiveCount(): number;
+  /** Shutdown collector */
+  shutdown(): Promise<void>;
+  private completeTrace;
+  private classifyOutcome;
+}
+declare function createTraceCollector(config: TraceCollectorConfig): TraceCollector;
+//#endregion
+//#region src/tracker.d.ts
+declare class TelemetryTracker {
+  private readonly config;
+  private readonly sinks;
+  private readonly queue;
+  private readonly storage?;
+  private sequence;
+  private flushTimer?;
+  private sessionStartTime?;
+  private isFlushing;
+  constructor(config: TelemetryConfig, storage?: Storage);
+  addSink(sink: TelemetrySink): this;
+  removeSink(name: string): this;
+  startSession(metadata?: Record<string, unknown>): string;
+  endSession(metadata?: Record<string, unknown>): void;
+  track(type: TelemetryEventType, name: string, data?: Record<string, unknown>): void;
+  trackPerformance(metric: Omit<PerformanceMetric, "timestamp">): void;
+  trackError(error: Error | string, context?: Record<string, unknown>): void;
+  trackApiRequest(method: string, path: string, status: number, durationMs: number, metadata?: Record<string, unknown>): void;
+  trackAgentExecution(identifier: string, executionId: string, durationMs: number, success: boolean, metadata?: Record<string, unknown>): void;
+  flush(): Promise<void>;
+  close(): Promise<void>;
+  getQueueSize(): number;
+  isEnabled(): boolean;
+  enable(): void;
+  disable(): void;
+  private enqueue;
+  private shouldSample;
+  private isExcluded;
+  private enrichData;
+  private startFlushTimer;
+  private stopFlushTimer;
+  private persistEvent;
+  private persistEvents;
+  private clearPersistedEvents;
+  loadPersistedEvents(): Promise<TelemetryEvent[]>;
+}
+declare function createTelemetryTracker(config: TelemetryConfig, storage?: Storage): TelemetryTracker;
+//#endregion
+//#region src/usage.d.ts
+declare class UsageTracker {
+  private readonly config;
+  private readonly provider?;
+  private readonly storage?;
+  private readonly queue;
+  private flushTimer?;
+  private isFlushing;
+  private sessionMetrics;
+  constructor(config: UsageTrackerConfig, provider?: UsageProvider, storage?: Storage);
+  recordApiCall(metric: ApiMetric): void;
+  recordAgentExecution(metric: AgentMetric): void;
+  recordError(error: Error | string, operation: string): void;
+  record(usage: Omit<UsageRecord, "id" | "timestamp">): void;
+  flush(): Promise<void>;
+  getUsage(options?: {
+    since?: Date;
+    until?: Date;
+    limit?: number;
+  }): Promise<UsageRecord[]>;
+  getSummary(period?: UsageSummary["period"]): Promise<UsageSummary>;
+  getSessionMetrics(): {
+    totalCredits: number;
+    totalOperations: number;
+    totalDurationMs: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    operationBreakdown: Record<string, number>;
+    sessionDurationMs: number;
+  };
+  resetSessionMetrics(): void;
+  close(): Promise<void>;
+  private calculateCost;
+  private persistRecords;
+  private loadPersistedRecords;
+  private generateLocalSummary;
+  private getPeriodStart;
+  private startFlushTimer;
+  private stopFlushTimer;
+}
+declare function createUsageInterceptor(tracker: UsageTracker): {
+  onRequest(ctx: {
+    request: {
+      method: string;
+      url: string;
+    };
+    startedAt: number;
+  }): {
+    request: {
+      method: string;
+      url: string;
+    };
+    startedAt: number;
+  };
+  onResponse<T>(ctx: {
+    request: {
+      method: string;
+      url: string;
+    };
+    response: {
+      status: number;
+    };
+    startedAt: number;
+  }): T;
+  onError(ctx: {
+    request: {
+      method: string;
+      url: string;
+    };
+    error: Error;
+    startedAt: number;
+  }): void;
+};
+declare function createUsageTracker(config: UsageTrackerConfig, provider?: UsageProvider, storage?: Storage): UsageTracker;
+//#endregion
+export { AdapterRegistry, type AgentErrorEvent, type AgentEvent, type AgentMetric, type ApiMetric, type BuildResultEvent, ConsoleTelemetrySink, type CreditBalance, type CreditProvider, CreditTracker, type CreditTrackerConfig, type CreditTransaction, type CustomEvent, type Diagnostic, type DiagnosticEvent, type DiagnosticSeverity, type DiagnosticSummary, type EnrichmentContext, type EnvironmentEvent, type EnvironmentType, type ErrorEvent, type ExecutionTrace, type FileChangeEvent, type FilePart, GEN_AI_CONVERSATION_ID, GEN_AI_INPUT_TOKEN_KEYS, GEN_AI_MODEL_KEYS, GEN_AI_OPERATION_NAME, GEN_AI_OUTPUT_TOKEN_KEYS, GEN_AI_REQUEST_MODEL, GEN_AI_RESPONSE_MODEL, GEN_AI_USAGE_INPUT_TOKENS, GEN_AI_USAGE_OUTPUT_TOKENS, type GenAiUsage, HttpTelemetrySink, type InitOtelProviderResult, LangfuseSink, type LangfuseSinkConfig, type LifecycleOp, MemoryCreditProvider, type MessagePartUpdatedEvent, type MessagePartUpdatedEventWithTimestamp, type MessageUpdatedEvent, type MetadataBlob, type MetadataBlobAdapter, type MetadataBlobFormat, MultiTelemetrySink, type OtelSinkConfig, OtelTelemetrySink, type Outcome, PROVISION_TRACE_ID_HEADER, PTID_PREFIX, type ParsedSSEEvent, type Part, type PerformanceMetric, type ProductType, type ReasoningPart, type RecordOptions, type ResultEvent, SSEChunkParser, type SSEEventData, type SSEParserOptions, type ServerTimingEntry, type Signal, type SignalEvent, type SpanComponent, SpanRecorder, type SpanStatus, type StageSpan, type StageSpanInput, type StatusEvent, type StreamTokenUsage, type StreamUsageAccumulator, StreamUsageExtractor, type SubscriptionTier, TOKEN_USAGE_COST_KEYS, TOKEN_USAGE_INPUT_KEYS, TOKEN_USAGE_OUTPUT_KEYS, type TelemetryConfig, type TelemetryEvent, type TelemetryEventType, type TelemetrySink, TelemetryTracker, type TestResultEvent, TestTelemetrySink, type TextPart, type TokenUsageCounts, type ToolPart, type ToolState, TraceCollector, type TraceCollectorConfig, type TraceContext, type TraceEvent, type TraceEventType, type TraceScope, type UsageProvider, type UsageRecord, type UsageSummary, UsageTracker, type UsageTrackerConfig, addTokenUsage, consumeSSEStream, createConsoleSink, createCreditTracker, createEmptyContext, createHttpSink, createJsonAdapter, createLangfuseSinkFromEnv, createOtelSink, createOtelSinkFromEnv, createStreamUsageExtractor, createTelemetryTracker, createTestSink, createTraceCollector, createUsageCallback, createUsageInterceptor, createUsageTracker, firstTokenCount, firstUsageCostUsd, genAiUsageAttributes, getDefaultRegistry, initOtelProvider, initializeDefaultAdapters, isAdoptablePtid, isBuildResultEvent, isCompletionEvent, isCustomEvent, isDiagnosticEvent, isEnvironmentEvent, isErrorEvent, isFileChangeEvent, isFilePart, isMessagePartUpdatedEvent, isMessageUpdatedEvent, isReasoningPart, isTestResultEvent, isTextPart, isToolPart, jsonAdapter, mintPtid, monotonicNs, parseMetadataBlob, parseSSEData, parseSSEStream, parseServerTiming, readOrMintPtid, readTokenCostUsd, readTokenUsage, resetDefaultRegistry, shutdownOtelProvider, spanDurationMs, sseToSignal, sseToTraceEvent, tokenCount, tokenUsageSource };
+//# sourceMappingURL=index.d.mts.map