@raindrop-ai/ai-sdk 0.0.20 → 0.0.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -147,6 +147,8 @@ declare class TraceShipper$1 {
147
147
  private queue;
148
148
  private timer;
149
149
  private inFlight;
150
+ /** URL of the local debugger (from RAINDROP_LOCAL_DEBUGGER env var). */
151
+ private localDebuggerUrl;
150
152
  constructor(opts: TraceShipperOptions);
151
153
  isDebugEnabled(): boolean;
152
154
  private authHeaders;
@@ -276,6 +278,7 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
276
278
  private getState;
277
279
  private cleanup;
278
280
  private spanParentRef;
281
+ private emitLive;
279
282
  private extractRaindropMetadata;
280
283
  /**
281
284
  * Extract the user-facing input text from an onStart event.
@@ -548,6 +551,53 @@ type WrapAISDKOptions = {
548
551
  */
549
552
  nativeTelemetry?: boolean;
550
553
  };
554
+ /**
555
+ * Opaque handle for a trace span. Pass as `parent` when creating child spans.
556
+ */
557
+ type TraceSpan = {
558
+ readonly traceId: string;
559
+ readonly spanId: string;
560
+ };
561
+ type StartSpanArgs = {
562
+ /** Span name (e.g. "web_search", "finder_subagent"). */
563
+ name: string;
564
+ /** Raindrop event ID this span belongs to. */
565
+ eventId: string;
566
+ /** Parent span for nesting. Omit for root spans. */
567
+ parent?: TraceSpan;
568
+ /** AI SDK operation ID (e.g. "ai.toolCall", "ai.generateText"). Helps classify the span. */
569
+ operationId?: string;
570
+ /** Arbitrary string attributes. */
571
+ attributes?: Record<string, string>;
572
+ };
573
+ type EndSpanArgs = {
574
+ /** Additional attributes to add when ending. */
575
+ attributes?: Record<string, string>;
576
+ /** Mark the span as failed. */
577
+ error?: Error | string;
578
+ };
579
+ type CreateSpanArgs = {
580
+ /** Span name (e.g. "SET theme=dark", "grep_search"). */
581
+ name: string;
582
+ /** Raindrop event ID this span belongs to. */
583
+ eventId: string;
584
+ /** Parent span for nesting. Omit for root spans. */
585
+ parent?: TraceSpan;
586
+ /** AI SDK operation ID (e.g. "ai.toolCall"). Helps classify the span. */
587
+ operationId?: string;
588
+ /** Input data (will be JSON stringified if object). */
589
+ input?: unknown;
590
+ /** Output data (will be JSON stringified if object). */
591
+ output?: unknown;
592
+ /** Duration in milliseconds. */
593
+ durationMs: number;
594
+ /** Start time as epoch ms. Defaults to `Date.now() - durationMs`. */
595
+ startTime?: number;
596
+ /** Mark the span as failed. */
597
+ error?: Error | string;
598
+ /** Arbitrary string attributes. */
599
+ attributes?: Record<string, string>;
600
+ };
551
601
  type EventPatch = {
552
602
  eventName?: string;
553
603
  userId?: string;
@@ -577,6 +627,46 @@ type RaindropAISDKClient = {
577
627
  properties?: Record<string, unknown>;
578
628
  }): Promise<void>;
579
629
  };
630
+ /**
631
+ * Manually create trace spans alongside (or instead of) auto-instrumented ones.
632
+ *
633
+ * Use `startSpan` / `endSpan` for spans with manual lifecycle control, or
634
+ * `createSpan` for one-shot spans where timing is already known.
635
+ *
636
+ * Spans share the same trace tree as auto-instrumented spans when you pass
637
+ * matching `eventId` values. Use `parent` to nest spans arbitrarily.
638
+ *
639
+ * @example
640
+ * ```typescript
641
+ * // One-shot span for a DSL command extracted from agent output
642
+ * raindrop.traces.createSpan({
643
+ * name: "SET theme=dark",
644
+ * eventId: "evt_123",
645
+ * operationId: "ai.toolCall",
646
+ * input: "SET theme=dark",
647
+ * output: "OK",
648
+ * durationMs: 12,
649
+ * });
650
+ *
651
+ * // Manual lifecycle for a subagent
652
+ * const agent = raindrop.traces.startSpan({
653
+ * name: "finder_subagent",
654
+ * eventId: "evt_456",
655
+ * });
656
+ * const tool = raindrop.traces.startSpan({
657
+ * name: "grep_search",
658
+ * eventId: "evt_456",
659
+ * parent: agent,
660
+ * });
661
+ * raindrop.traces.endSpan(tool);
662
+ * raindrop.traces.endSpan(agent);
663
+ * ```
664
+ */
665
+ traces: {
666
+ startSpan(args: StartSpanArgs): TraceSpan;
667
+ endSpan(span: TraceSpan, extra?: EndSpanArgs): void;
668
+ createSpan(args: CreateSpanArgs): TraceSpan;
669
+ };
580
670
  users: {
581
671
  identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
582
672
  };
@@ -598,4 +688,4 @@ type RaindropAISDKClient = {
598
688
  };
599
689
  declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
600
690
 
601
- export { type AISDKChatRequestLike as A, type BuildEventPatch as B, ContextManager as C, type EventBuilder as E, type IdentifyInput as I, type RaindropAISDKClient as R, type SelfDiagnosticsOptions as S, type WrapAISDKOptions as W, _resetWarnedMissingUserId as _, type AISDKChatRequestMessageLike as a, type AISDKMessage as b, type AgentCallMetadata as c, type AgentWithMetadata as d, type Attachment as e, type ContextSpan as f, type EventMetadataOptions as g, type RaindropAISDKContext as h, type RaindropAISDKOptions as i, RaindropTelemetryIntegration as j, type RaindropTelemetryIntegrationOptions as k, type SelfDiagnosticsSignalDefinition as l, type SelfDiagnosticsSignalDefinitions as m, type WrappedAI as n, type WrappedAISDK as o, createRaindropAISDK as p, currentSpan as q, eventMetadata as r, eventMetadataFromChatRequest as s, getContextManager as t, withCurrent as w };
691
+ export { type AISDKChatRequestLike as A, type BuildEventPatch as B, ContextManager as C, type EndSpanArgs as E, type IdentifyInput as I, type RaindropAISDKClient as R, type SelfDiagnosticsOptions as S, type TraceSpan as T, type WrapAISDKOptions as W, _resetWarnedMissingUserId as _, type AISDKChatRequestMessageLike as a, type AISDKMessage as b, type AgentCallMetadata as c, type AgentWithMetadata as d, type Attachment as e, type ContextSpan as f, type CreateSpanArgs as g, type EventBuilder as h, type EventMetadataOptions as i, type RaindropAISDKContext as j, type RaindropAISDKOptions as k, RaindropTelemetryIntegration as l, type RaindropTelemetryIntegrationOptions as m, type SelfDiagnosticsSignalDefinition as n, type SelfDiagnosticsSignalDefinitions as o, type StartSpanArgs as p, type WrappedAI as q, type WrappedAISDK as r, createRaindropAISDK as s, currentSpan as t, eventMetadata as u, eventMetadataFromChatRequest as v, getContextManager as w, withCurrent as x };
@@ -147,6 +147,8 @@ declare class TraceShipper$1 {
147
147
  private queue;
148
148
  private timer;
149
149
  private inFlight;
150
+ /** URL of the local debugger (from RAINDROP_LOCAL_DEBUGGER env var). */
151
+ private localDebuggerUrl;
150
152
  constructor(opts: TraceShipperOptions);
151
153
  isDebugEnabled(): boolean;
152
154
  private authHeaders;
@@ -276,6 +278,7 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
276
278
  private getState;
277
279
  private cleanup;
278
280
  private spanParentRef;
281
+ private emitLive;
279
282
  private extractRaindropMetadata;
280
283
  /**
281
284
  * Extract the user-facing input text from an onStart event.
@@ -548,6 +551,53 @@ type WrapAISDKOptions = {
548
551
  */
549
552
  nativeTelemetry?: boolean;
550
553
  };
554
+ /**
555
+ * Opaque handle for a trace span. Pass as `parent` when creating child spans.
556
+ */
557
+ type TraceSpan = {
558
+ readonly traceId: string;
559
+ readonly spanId: string;
560
+ };
561
+ type StartSpanArgs = {
562
+ /** Span name (e.g. "web_search", "finder_subagent"). */
563
+ name: string;
564
+ /** Raindrop event ID this span belongs to. */
565
+ eventId: string;
566
+ /** Parent span for nesting. Omit for root spans. */
567
+ parent?: TraceSpan;
568
+ /** AI SDK operation ID (e.g. "ai.toolCall", "ai.generateText"). Helps classify the span. */
569
+ operationId?: string;
570
+ /** Arbitrary string attributes. */
571
+ attributes?: Record<string, string>;
572
+ };
573
+ type EndSpanArgs = {
574
+ /** Additional attributes to add when ending. */
575
+ attributes?: Record<string, string>;
576
+ /** Mark the span as failed. */
577
+ error?: Error | string;
578
+ };
579
+ type CreateSpanArgs = {
580
+ /** Span name (e.g. "SET theme=dark", "grep_search"). */
581
+ name: string;
582
+ /** Raindrop event ID this span belongs to. */
583
+ eventId: string;
584
+ /** Parent span for nesting. Omit for root spans. */
585
+ parent?: TraceSpan;
586
+ /** AI SDK operation ID (e.g. "ai.toolCall"). Helps classify the span. */
587
+ operationId?: string;
588
+ /** Input data (will be JSON stringified if object). */
589
+ input?: unknown;
590
+ /** Output data (will be JSON stringified if object). */
591
+ output?: unknown;
592
+ /** Duration in milliseconds. */
593
+ durationMs: number;
594
+ /** Start time as epoch ms. Defaults to `Date.now() - durationMs`. */
595
+ startTime?: number;
596
+ /** Mark the span as failed. */
597
+ error?: Error | string;
598
+ /** Arbitrary string attributes. */
599
+ attributes?: Record<string, string>;
600
+ };
551
601
  type EventPatch = {
552
602
  eventName?: string;
553
603
  userId?: string;
@@ -577,6 +627,46 @@ type RaindropAISDKClient = {
577
627
  properties?: Record<string, unknown>;
578
628
  }): Promise<void>;
579
629
  };
630
+ /**
631
+ * Manually create trace spans alongside (or instead of) auto-instrumented ones.
632
+ *
633
+ * Use `startSpan` / `endSpan` for spans with manual lifecycle control, or
634
+ * `createSpan` for one-shot spans where timing is already known.
635
+ *
636
+ * Spans share the same trace tree as auto-instrumented spans when you pass
637
+ * matching `eventId` values. Use `parent` to nest spans arbitrarily.
638
+ *
639
+ * @example
640
+ * ```typescript
641
+ * // One-shot span for a DSL command extracted from agent output
642
+ * raindrop.traces.createSpan({
643
+ * name: "SET theme=dark",
644
+ * eventId: "evt_123",
645
+ * operationId: "ai.toolCall",
646
+ * input: "SET theme=dark",
647
+ * output: "OK",
648
+ * durationMs: 12,
649
+ * });
650
+ *
651
+ * // Manual lifecycle for a subagent
652
+ * const agent = raindrop.traces.startSpan({
653
+ * name: "finder_subagent",
654
+ * eventId: "evt_456",
655
+ * });
656
+ * const tool = raindrop.traces.startSpan({
657
+ * name: "grep_search",
658
+ * eventId: "evt_456",
659
+ * parent: agent,
660
+ * });
661
+ * raindrop.traces.endSpan(tool);
662
+ * raindrop.traces.endSpan(agent);
663
+ * ```
664
+ */
665
+ traces: {
666
+ startSpan(args: StartSpanArgs): TraceSpan;
667
+ endSpan(span: TraceSpan, extra?: EndSpanArgs): void;
668
+ createSpan(args: CreateSpanArgs): TraceSpan;
669
+ };
580
670
  users: {
581
671
  identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
582
672
  };
@@ -598,4 +688,4 @@ type RaindropAISDKClient = {
598
688
  };
599
689
  declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
600
690
 
601
- export { type AISDKChatRequestLike as A, type BuildEventPatch as B, ContextManager as C, type EventBuilder as E, type IdentifyInput as I, type RaindropAISDKClient as R, type SelfDiagnosticsOptions as S, type WrapAISDKOptions as W, _resetWarnedMissingUserId as _, type AISDKChatRequestMessageLike as a, type AISDKMessage as b, type AgentCallMetadata as c, type AgentWithMetadata as d, type Attachment as e, type ContextSpan as f, type EventMetadataOptions as g, type RaindropAISDKContext as h, type RaindropAISDKOptions as i, RaindropTelemetryIntegration as j, type RaindropTelemetryIntegrationOptions as k, type SelfDiagnosticsSignalDefinition as l, type SelfDiagnosticsSignalDefinitions as m, type WrappedAI as n, type WrappedAISDK as o, createRaindropAISDK as p, currentSpan as q, eventMetadata as r, eventMetadataFromChatRequest as s, getContextManager as t, withCurrent as w };
691
+ export { type AISDKChatRequestLike as A, type BuildEventPatch as B, ContextManager as C, type EndSpanArgs as E, type IdentifyInput as I, type RaindropAISDKClient as R, type SelfDiagnosticsOptions as S, type TraceSpan as T, type WrapAISDKOptions as W, _resetWarnedMissingUserId as _, type AISDKChatRequestMessageLike as a, type AISDKMessage as b, type AgentCallMetadata as c, type AgentWithMetadata as d, type Attachment as e, type ContextSpan as f, type CreateSpanArgs as g, type EventBuilder as h, type EventMetadataOptions as i, type RaindropAISDKContext as j, type RaindropAISDKOptions as k, RaindropTelemetryIntegration as l, type RaindropTelemetryIntegrationOptions as m, type SelfDiagnosticsSignalDefinition as n, type SelfDiagnosticsSignalDefinitions as o, type StartSpanArgs as p, type WrappedAI as q, type WrappedAISDK as r, createRaindropAISDK as s, currentSpan as t, eventMetadata as u, eventMetadataFromChatRequest as v, getContextManager as w, withCurrent as x };
@@ -147,6 +147,8 @@ declare class TraceShipper$1 {
147
147
  private queue;
148
148
  private timer;
149
149
  private inFlight;
150
+ /** URL of the local debugger (from RAINDROP_LOCAL_DEBUGGER env var). */
151
+ private localDebuggerUrl;
150
152
  constructor(opts: TraceShipperOptions);
151
153
  isDebugEnabled(): boolean;
152
154
  private authHeaders;
@@ -276,6 +278,7 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
276
278
  private getState;
277
279
  private cleanup;
278
280
  private spanParentRef;
281
+ private emitLive;
279
282
  private extractRaindropMetadata;
280
283
  /**
281
284
  * Extract the user-facing input text from an onStart event.
@@ -548,6 +551,53 @@ type WrapAISDKOptions = {
548
551
  */
549
552
  nativeTelemetry?: boolean;
550
553
  };
554
+ /**
555
+ * Opaque handle for a trace span. Pass as `parent` when creating child spans.
556
+ */
557
+ type TraceSpan = {
558
+ readonly traceId: string;
559
+ readonly spanId: string;
560
+ };
561
+ type StartSpanArgs = {
562
+ /** Span name (e.g. "web_search", "finder_subagent"). */
563
+ name: string;
564
+ /** Raindrop event ID this span belongs to. */
565
+ eventId: string;
566
+ /** Parent span for nesting. Omit for root spans. */
567
+ parent?: TraceSpan;
568
+ /** AI SDK operation ID (e.g. "ai.toolCall", "ai.generateText"). Helps classify the span. */
569
+ operationId?: string;
570
+ /** Arbitrary string attributes. */
571
+ attributes?: Record<string, string>;
572
+ };
573
+ type EndSpanArgs = {
574
+ /** Additional attributes to add when ending. */
575
+ attributes?: Record<string, string>;
576
+ /** Mark the span as failed. */
577
+ error?: Error | string;
578
+ };
579
+ type CreateSpanArgs = {
580
+ /** Span name (e.g. "SET theme=dark", "grep_search"). */
581
+ name: string;
582
+ /** Raindrop event ID this span belongs to. */
583
+ eventId: string;
584
+ /** Parent span for nesting. Omit for root spans. */
585
+ parent?: TraceSpan;
586
+ /** AI SDK operation ID (e.g. "ai.toolCall"). Helps classify the span. */
587
+ operationId?: string;
588
+ /** Input data (will be JSON stringified if object). */
589
+ input?: unknown;
590
+ /** Output data (will be JSON stringified if object). */
591
+ output?: unknown;
592
+ /** Duration in milliseconds. */
593
+ durationMs: number;
594
+ /** Start time as epoch ms. Defaults to `Date.now() - durationMs`. */
595
+ startTime?: number;
596
+ /** Mark the span as failed. */
597
+ error?: Error | string;
598
+ /** Arbitrary string attributes. */
599
+ attributes?: Record<string, string>;
600
+ };
551
601
  type EventPatch = {
552
602
  eventName?: string;
553
603
  userId?: string;
@@ -577,6 +627,46 @@ type RaindropAISDKClient = {
577
627
  properties?: Record<string, unknown>;
578
628
  }): Promise<void>;
579
629
  };
630
+ /**
631
+ * Manually create trace spans alongside (or instead of) auto-instrumented ones.
632
+ *
633
+ * Use `startSpan` / `endSpan` for spans with manual lifecycle control, or
634
+ * `createSpan` for one-shot spans where timing is already known.
635
+ *
636
+ * Spans share the same trace tree as auto-instrumented spans when you pass
637
+ * matching `eventId` values. Use `parent` to nest spans arbitrarily.
638
+ *
639
+ * @example
640
+ * ```typescript
641
+ * // One-shot span for a DSL command extracted from agent output
642
+ * raindrop.traces.createSpan({
643
+ * name: "SET theme=dark",
644
+ * eventId: "evt_123",
645
+ * operationId: "ai.toolCall",
646
+ * input: "SET theme=dark",
647
+ * output: "OK",
648
+ * durationMs: 12,
649
+ * });
650
+ *
651
+ * // Manual lifecycle for a subagent
652
+ * const agent = raindrop.traces.startSpan({
653
+ * name: "finder_subagent",
654
+ * eventId: "evt_456",
655
+ * });
656
+ * const tool = raindrop.traces.startSpan({
657
+ * name: "grep_search",
658
+ * eventId: "evt_456",
659
+ * parent: agent,
660
+ * });
661
+ * raindrop.traces.endSpan(tool);
662
+ * raindrop.traces.endSpan(agent);
663
+ * ```
664
+ */
665
+ traces: {
666
+ startSpan(args: StartSpanArgs): TraceSpan;
667
+ endSpan(span: TraceSpan, extra?: EndSpanArgs): void;
668
+ createSpan(args: CreateSpanArgs): TraceSpan;
669
+ };
580
670
  users: {
581
671
  identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
582
672
  };
@@ -598,4 +688,4 @@ type RaindropAISDKClient = {
598
688
  };
599
689
  declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
600
690
 
601
- export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, withCurrent };
691
+ export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type StartSpanArgs, type TraceSpan, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, withCurrent };
@@ -147,6 +147,8 @@ declare class TraceShipper$1 {
147
147
  private queue;
148
148
  private timer;
149
149
  private inFlight;
150
+ /** URL of the local debugger (from RAINDROP_LOCAL_DEBUGGER env var). */
151
+ private localDebuggerUrl;
150
152
  constructor(opts: TraceShipperOptions);
151
153
  isDebugEnabled(): boolean;
152
154
  private authHeaders;
@@ -276,6 +278,7 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
276
278
  private getState;
277
279
  private cleanup;
278
280
  private spanParentRef;
281
+ private emitLive;
279
282
  private extractRaindropMetadata;
280
283
  /**
281
284
  * Extract the user-facing input text from an onStart event.
@@ -548,6 +551,53 @@ type WrapAISDKOptions = {
548
551
  */
549
552
  nativeTelemetry?: boolean;
550
553
  };
554
+ /**
555
+ * Opaque handle for a trace span. Pass as `parent` when creating child spans.
556
+ */
557
+ type TraceSpan = {
558
+ readonly traceId: string;
559
+ readonly spanId: string;
560
+ };
561
+ type StartSpanArgs = {
562
+ /** Span name (e.g. "web_search", "finder_subagent"). */
563
+ name: string;
564
+ /** Raindrop event ID this span belongs to. */
565
+ eventId: string;
566
+ /** Parent span for nesting. Omit for root spans. */
567
+ parent?: TraceSpan;
568
+ /** AI SDK operation ID (e.g. "ai.toolCall", "ai.generateText"). Helps classify the span. */
569
+ operationId?: string;
570
+ /** Arbitrary string attributes. */
571
+ attributes?: Record<string, string>;
572
+ };
573
+ type EndSpanArgs = {
574
+ /** Additional attributes to add when ending. */
575
+ attributes?: Record<string, string>;
576
+ /** Mark the span as failed. */
577
+ error?: Error | string;
578
+ };
579
+ type CreateSpanArgs = {
580
+ /** Span name (e.g. "SET theme=dark", "grep_search"). */
581
+ name: string;
582
+ /** Raindrop event ID this span belongs to. */
583
+ eventId: string;
584
+ /** Parent span for nesting. Omit for root spans. */
585
+ parent?: TraceSpan;
586
+ /** AI SDK operation ID (e.g. "ai.toolCall"). Helps classify the span. */
587
+ operationId?: string;
588
+ /** Input data (will be JSON stringified if object). */
589
+ input?: unknown;
590
+ /** Output data (will be JSON stringified if object). */
591
+ output?: unknown;
592
+ /** Duration in milliseconds. */
593
+ durationMs: number;
594
+ /** Start time as epoch ms. Defaults to `Date.now() - durationMs`. */
595
+ startTime?: number;
596
+ /** Mark the span as failed. */
597
+ error?: Error | string;
598
+ /** Arbitrary string attributes. */
599
+ attributes?: Record<string, string>;
600
+ };
551
601
  type EventPatch = {
552
602
  eventName?: string;
553
603
  userId?: string;
@@ -577,6 +627,46 @@ type RaindropAISDKClient = {
577
627
  properties?: Record<string, unknown>;
578
628
  }): Promise<void>;
579
629
  };
630
+ /**
631
+ * Manually create trace spans alongside (or instead of) auto-instrumented ones.
632
+ *
633
+ * Use `startSpan` / `endSpan` for spans with manual lifecycle control, or
634
+ * `createSpan` for one-shot spans where timing is already known.
635
+ *
636
+ * Spans share the same trace tree as auto-instrumented spans when you pass
637
+ * matching `eventId` values. Use `parent` to nest spans arbitrarily.
638
+ *
639
+ * @example
640
+ * ```typescript
641
+ * // One-shot span for a DSL command extracted from agent output
642
+ * raindrop.traces.createSpan({
643
+ * name: "SET theme=dark",
644
+ * eventId: "evt_123",
645
+ * operationId: "ai.toolCall",
646
+ * input: "SET theme=dark",
647
+ * output: "OK",
648
+ * durationMs: 12,
649
+ * });
650
+ *
651
+ * // Manual lifecycle for a subagent
652
+ * const agent = raindrop.traces.startSpan({
653
+ * name: "finder_subagent",
654
+ * eventId: "evt_456",
655
+ * });
656
+ * const tool = raindrop.traces.startSpan({
657
+ * name: "grep_search",
658
+ * eventId: "evt_456",
659
+ * parent: agent,
660
+ * });
661
+ * raindrop.traces.endSpan(tool);
662
+ * raindrop.traces.endSpan(agent);
663
+ * ```
664
+ */
665
+ traces: {
666
+ startSpan(args: StartSpanArgs): TraceSpan;
667
+ endSpan(span: TraceSpan, extra?: EndSpanArgs): void;
668
+ createSpan(args: CreateSpanArgs): TraceSpan;
669
+ };
580
670
  users: {
581
671
  identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
582
672
  };
@@ -598,4 +688,4 @@ type RaindropAISDKClient = {
598
688
  };
599
689
  declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
600
690
 
601
- export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, withCurrent };
691
+ export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type StartSpanArgs, type TraceSpan, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, withCurrent };