raindrop-ai 0.2.4 → 0.3.0

package/dist/index.d.mts

@@ -1,1180 +1,5 @@
-import * as _opentelemetry_instrumentation from '@opentelemetry/instrumentation';
-import { Span } from '@opentelemetry/api';
-import { z } from 'zod';
-import { SpanProcessorOptions } from '@traceloop/node-server-sdk';
-
-type LocalDebuggerLiveEventType = "text_delta" | "reasoning_delta" | "tool_start" | "tool_result" | "status";
-type LocalDebuggerLiveEventInput$1 = {
-    traceId: string;
-    spanId?: string;
-    type: LocalDebuggerLiveEventType | (string & {});
-    content?: string;
-    timestamp?: number;
-    metadata?: Record<string, unknown>;
-};
-
-/**
- * Run telemetry egress with OpenTelemetry tracing suppressed.
- *
- * Why this exists
- * ---------------
- * Raindrop integrations ship spans/events over HTTP with the global `fetch`
- * (see {@link ../http.ts `postJson`}). When the host app also runs an OTel
- * fetch/undici instrumentation — e.g. `@vercel/otel`'s `registerOTel`, which
- * every Eve agent installs — that instrumentation wraps *our own* telemetry
- * POSTs in a `fetch POST <endpoint>` span. Those spans are then handed to the
- * very exporter that issued the request, so they get shipped right back to
- * Raindrop and Workshop as standalone "runs" (and, because each export issues
- * another fetch, they feed back on themselves). The result is a run list
- * flooded with `fetch POST .../v1/traces`, `.../events/track_partial` and
- * `.../live` entries that drown out the real agent turns — especially with
- * sub-agents, where every sandbox runs its own instrumentation.
- *
- * The OTel-blessed fix is to mark the active context as "tracing suppressed"
- * around the request; instrumentations check `isTracingSuppressed` and return
- * a no-op span instead of recording one. We do this through a hook stashed on
- * `globalThis` by the Node entrypoint ({@link ../index.node.ts}) so that:
- *   - `@opentelemetry/api` / `@opentelemetry/core` stay *optional* — core never
- *     hard-depends on them, and the hook is simply absent when they (and thus
- *     any instrumentation to suppress) are not installed; and
- *   - the browser bundle never pulls in `node:module`, mirroring how core
- *     injects `AsyncLocalStorage` via `RAINDROP_ASYNC_LOCAL_STORAGE`.
- *
- * When no hook is present the callback runs unchanged, so suppression is a
- * best-effort no-op rather than a hard requirement.
- */
-/** Hook signature: run `fn` with OTel tracing suppressed, returning its value. */
-type SuppressTracingHook = <T>(fn: () => T) => T;
-declare global {
-    var RAINDROP_SUPPRESS_TRACING: SuppressTracingHook | undefined;
-}
-
-type ParentSpanContext = {
-    traceIdB64: string;
-    spanIdB64: string;
-    eventId: string;
-};
-interface ContextSpan {
-    readonly traceIdB64: string;
-    readonly spanIdB64: string;
-    readonly eventId: string;
-    log?(data: Record<string, unknown>): void;
-}
-interface AsyncLocalStorageLike<T> {
-    getStore(): T | undefined;
-    run<R>(store: T, callback: () => R): R;
-    enterWith?(store: T): void;
-}
-declare abstract class ContextManager {
-    abstract getParentSpanIds(): ParentSpanContext | undefined;
-    abstract runInContext<R>(span: ContextSpan, callback: () => R): R;
-    abstract getCurrentSpan(): ContextSpan | undefined;
-    abstract isReady(): boolean;
-}
-declare global {
-    var RAINDROP_CONTEXT_MANAGER: (new () => ContextManager) | undefined;
-    var RAINDROP_ASYNC_LOCAL_STORAGE: (new <T>() => AsyncLocalStorageLike<T>) | undefined;
-}
-
-/**
- * Version-agnostic SpanProcessor interface.
- *
- * This interface avoids direct dependency on OTEL's Span and ReadableSpan types
- * which can cause compatibility issues across minor OTEL versions. Using `any`
- * allows the processor to work with any version of OTEL without type conflicts.
- */
-interface RaindropSpanProcessor {
-    forceFlush(): Promise<void>;
-    onStart(span: any, parentContext: any): void;
-    onEnd(span: any): void;
-    shutdown(): Promise<void>;
-}
-type BaseAttachment = {
-    attachment_id?: string;
-    name?: string;
-    value: string;
-    role: "input" | "output";
-};
-type CodeAttachment = BaseAttachment & {
-    type: "code";
-    language?: string;
-};
-type OtherAttachment = BaseAttachment & {
-    type: "text" | "image" | "iframe";
-};
-type Attachment = CodeAttachment | OtherAttachment;
-type RaindropFeatureFlagValue = string | number | boolean;
-type RaindropFeatureFlags = string[] | Record<string, RaindropFeatureFlagValue>;
-type RaindropPropertyLeaf = string | boolean | number;
-type RaindropPropertyValue = RaindropPropertyLeaf | RaindropPropertyValue[] | {
-    [key: string]: RaindropPropertyValue;
-};
-type RaindropProperties = Record<string, RaindropPropertyValue>;
-/**
- * Interface for tracking events.
- *
- * @param eventId - An optional event ID for the event.
- * @param event - The name of the event.
- * @param properties - An optional record of properties for the event.
- * @param timestamp - An optional timestamp for the event.
- * @param userId - The ID of the user. This is a required field.
- * @param anonymousId - An optional anonymous ID for the user.
- */
-interface TrackEvent {
-    eventId?: string;
-    event: string;
-    properties?: RaindropProperties;
-    featureFlags?: RaindropFeatureFlags;
-    timestamp?: string;
-    userId: string;
-}
-type BasicSignal = {
-    eventId: string;
-    name: "thumbs_up" | "thumbs_down" | string;
-    sentiment?: "POSITIVE" | "NEGATIVE";
-    timestamp?: string;
-    properties?: {
-        [key: string]: any;
-    };
-    attachmentId?: string;
-};
-type DefaultSignal = BasicSignal & {
-    type?: "default" | "standard";
-};
-type FeedbackSignal = BasicSignal & {
-    type: "feedback";
-    comment?: string;
-};
-type EditSignal = BasicSignal & {
-    type: "edit";
-    after?: string;
-};
-type AgentSignal = BasicSignal & {
-    type: "agent" | "agent_internal";
-};
-type SignalEvent = DefaultSignal | FeedbackSignal | EditSignal | AgentSignal;
-type SelfDiagnoseOptions = {
-    /** The interaction/event ID this diagnostic belongs to. */
-    eventId: string;
-    /** A human-readable description of the issue. */
-    description: string;
-    /** Optional category to group the diagnostic under (e.g. "missing_context", "capability_gap"). Defaults to "general". */
-    category?: string;
-    /** Optional source identifier (e.g. your agent or service name). */
-    source?: string;
-    /** Signal sentiment. Defaults to "NEGATIVE". */
-    sentiment?: "POSITIVE" | "NEGATIVE";
-    /** Additional custom properties to attach to the signal. */
-    properties?: Record<string, unknown>;
-};
-type SelfDiagnosticsSignalDefinition = {
-    description: string;
-    sentiment?: "POSITIVE" | "NEGATIVE";
-};
-type SelfDiagnosticsSignalDefinitions = Record<string, SelfDiagnosticsSignalDefinition>;
-type SelfDiagnosticsToolInputSchema = {
-    type: "object";
-    additionalProperties: false;
-    properties: {
-        category: {
-            type: "string";
-            enum: string[];
-            description: string;
-        };
-        detail: {
-            type: "string";
-            description: string;
-        };
-    };
-    required: string[];
-};
-type SelfDiagnosticsExecuteContext = {
-    eventId?: string;
-    interaction?: {
-        getEventId(): string | undefined;
-    };
-    metadata?: Record<string, unknown>;
-    properties?: Record<string, unknown>;
-    source?: string;
-};
-type SelfDiagnosticsExecuteResult = {
-    acknowledged: boolean;
-    category: string;
-    eventId?: string;
-    reason?: "missing_event_id";
-};
-type SelfDiagnosticsToolOptions = {
-    eventId?: string;
-    getEventId?: () => string | undefined;
-    interaction?: {
-        getEventId(): string | undefined;
-    };
-    toolName?: string;
-    guidance?: string;
-    signals?: SelfDiagnosticsSignalDefinitions;
-    source?: string;
-    onMissingEventId?: "warn" | "ignore" | "throw";
-};
-type SelfDiagnosticsTool = {
-    name: string;
-    description: string;
-    inputSchema: SelfDiagnosticsToolInputSchema;
-    signalKeys: string[];
-    execute(input: unknown, context?: SelfDiagnosticsExecuteContext): Promise<SelfDiagnosticsExecuteResult>;
-    forVercelAI(): {
-        description: string;
-        parameters: SelfDiagnosticsToolInputSchema;
-        inputSchema: SelfDiagnosticsToolInputSchema;
-        execute: (input: unknown, context?: SelfDiagnosticsExecuteContext) => Promise<SelfDiagnosticsExecuteResult>;
-    };
-    forOpenAI(): {
-        type: "function";
-        function: {
-            name: string;
-            description: string;
-            parameters: SelfDiagnosticsToolInputSchema;
-        };
-    };
-    forAnthropic(): {
-        name: string;
-        description: string;
-        input_schema: SelfDiagnosticsToolInputSchema;
-    };
-};
-/**
- * Interface for identifying events.
- *
- * @param userId - The ID of the user. This is a required field.
- * @param traits - An optional object of traits for the user.
- * @param anonymousId - An optional anonymous ID for the user.
- * TODO: ensure at least one out of userId or anonymousId is present
- */
-interface IdentifyEvent {
-    userId: string;
-    traits?: object;
-}
-/**
- * Type definition for AI tracking events.
- * In addition to the properties of a TrackEvent, an AiTrackEvent may have a 'model' property.
- * It must have at least one of 'input' or 'output' property.
- *
- * @property model - An optional model property for the even
- * @property input - An optional input property for the event, required if output is not provided.
- * @property output - An optional output property for the event, required if input is not provided.
- */
-type AiTrackEvent = Omit<TrackEvent, "type"> & {
-    model?: string;
-    convoId?: string;
-    attachments?: Attachment[];
-    featureFlags?: RaindropFeatureFlags;
-} & ({
-    input: string;
-    output?: string;
-} | {
-    input?: string;
-    output: string;
-});
-/**
- * Type definition for partial AI tracking events used with trackAiPartial.
- * Requires an eventId to correlate partial updates. All other fields are optional.
- */
-type PartialAiTrackEvent = Partial<AiTrackEvent> & {
-    eventId: string;
-    isPending?: boolean;
-};
-declare const AttachmentTypeSchema: z.ZodEnum<["code", "text", "image", "iframe"]>;
-type AttachmentType = z.infer<typeof AttachmentTypeSchema>;
-/**
- * Configuration for initializing a trace interaction.
- *
- * This interface defines the context required to create and track an AI
- * interaction through its lifecycle. It includes identifiers for the user
- * and conversation, as well as input/output content and attachments.
- *
- * @property userId - Optional unique identifier for the user
- * @property convoId - Optional unique identifier for the conversation
- * @property eventId - Optional unique identifier for this specific interaction event
- * @property input - Optional input text from the user
- * @property attachments - Optional array of attachments associated with this interaction
- * @property properties - Optional key-value pairs for additional custom metadata
- */
-interface TraceContext {
-    userId?: string;
-    convoId?: string;
-    eventId?: string;
-    input?: string;
-    event?: string;
-    attachments?: Attachment[];
-    properties?: Record<string, string>;
-}
-type BeginInteractionOptions = PartialAiTrackEvent & {
-    eventId: string;
-};
-type FinishInteractionOptions = Omit<PartialAiTrackEvent, "eventId"> & {
-    output: string;
-    eventId?: string;
-};
-/**
- * Configuration for a traced workflow.
- *
- * Workflows represent higher-level operations that might contain multiple
- * tasks. They help organize traces into logical units of work.
- *
- * @property name - Name of the workflow for identification in traces
- * @property inputParameters - Optional array of input parameters for the workflow
- * @property properties - Optional key-value pairs for additional metadata
- */
-interface WorkflowParams {
-    name: string;
-    inputParameters?: unknown[];
-    properties?: Record<string, string>;
-}
-/**
- * Configuration for a traced task.
- *
- * Tasks represent individual operations within a workflow, such as an LLM call,
- * a tool invocation, a retrieval operation, or internal processing.
- *
- * @property name - Name of the task for identification in traces
- * @property kind - Category of the task (llm, tool, retrival, or internal)
- * @property properties - Optional key-value pairs for additional metadata
- * @property inputParameters - Optional array of input parameters for the task
- * @property traceContent - Optional flag to control whether content is traced
- * @property suppressTracing - Optional flag to suppress tracing for this task
- */
-interface SpanParams {
-    name: string;
-    properties?: Record<string, string>;
-    inputParameters?: unknown[];
-    traceContent?: boolean;
-    suppressTracing?: boolean;
-}
-/**
- * Configuration for a traced tool.
- *
- * Tools represent external utilities or services that are invoked during an AI interaction,
- * such as search engines, calculators, or other specialized functions.
- *
- * @property name - Name of the tool for identification in traces
- * @property version - Optional version number of the tool
- * @property properties - Optional key-value pairs for additional metadata
- * @property inputParameters - Optional record of input parameters for the tool
- * @property traceContent - Optional flag to control whether content is traced
- * @property suppressTracing - Optional flag to suppress tracing for this tool invocation
- */
-interface ToolParams {
-    name: string;
-    version?: number;
-    properties?: Record<string, string>;
-    inputParameters?: Record<string, any>;
-    traceContent?: boolean;
-    suppressTracing?: boolean;
-}
-/**
- * Parameters for directly logging a tool span without wrapping a function.
- *
- * Use this when you want to record a tool invocation that has already completed,
- * rather than wrapping the tool call with withTool().
- *
- * @property name - Name of the tool for identification in traces
- * @property input - The input provided to the tool (will be JSON stringified if object)
- * @property output - The output returned by the tool (will be JSON stringified if object)
- * @property durationMs - Duration of the tool execution in milliseconds
- * @property startTime - Optional start time of the tool execution
- * @property error - Optional error if the tool failed
- * @property properties - Optional key-value pairs for additional metadata
- * @property traceId - Optional W3C trace ID override for bypassOtelForTools mode
- * @property parentSpanId - Optional W3C parent span ID override for bypassOtelForTools mode
- */
-interface TrackToolParams {
-    name: string;
-    input?: unknown;
-    output?: unknown;
-    durationMs?: number;
-    startTime?: Date | number;
-    error?: Error | string;
-    properties?: Record<string, string>;
-    traceId?: string;
-    parentSpanId?: string;
-}
-type LocalDebuggerLiveEventInput = Omit<LocalDebuggerLiveEventInput$1, "traceId"> & {
-    traceId?: string;
-};
-/**
- * A wrapper around an OpenTelemetry span for tool invocations.
- *
- * Provides a clean API for setting tool input, output, and error status
- * without needing to know the internal traceloop attribute names.
- *
- * @example
- * ```typescript
- * const toolSpan = interaction.startToolSpan({ name: "web_search" });
- * try {
- *   const result = await performSearch(query);
- *   toolSpan.setOutput(result);
- * } catch (error) {
- *   toolSpan.setError(error);
- * } finally {
- *   toolSpan.end();
- * }
- * ```
- */
-interface ToolSpan {
-    /**
-     * Sets the input for this tool span.
-     * @param input The input value (will be JSON stringified if object)
-     */
-    setInput(input: unknown): void;
-    /**
-     * Sets the output for this tool span.
-     * @param output The output value (will be JSON stringified if object)
-     */
-    setOutput(output: unknown): void;
-    /**
-     * Marks this tool span as failed with an error.
-     * @param error The error that occurred
-     */
-    setError(error: Error | string): void;
-    /**
-     * Ends this tool span. Must be called when the tool execution is complete.
-     */
-    end(): void;
-}
-/**
- * Represents an active tracing interaction for tracking and analyzing AI interactions.
- *
- * An Interaction is the core entity for tracing and instrumenting AI operations,
- * allowing you to organize your code into workflows and tasks while capturing
- * important metadata and contextual information. Use the methods on this interface
- * to record your AI interaction's lifecycle from input to output, and to add
- * structured context about the operation.
- *
- * Interactions are typically created using the `tracing.begin()` method and ended
- * with the `end()` method. Between these calls, you can add properties, attachments,
- * and nested traced operations.
- *
- * @example
- * // Basic usage pattern
- * const interaction = tracing.begin({
- *   userId: "user-123",
- *   convoId: "conversation-456"
- * });
- *
- * // Set the user's input
- * interaction.setInput("Tell me a joke about AI");
- *
- * // Add context properties
- * interaction.setProperty("intent", "entertainment");
- *
- * // Run a traced workflow
- * const result = await interaction.withWorkflow("joke_generation", async () => {
- *   // Run a traced task for the LLM call
- *   return await interaction.withTask({
- *     name: "llm_completion",
- *     kind: "llm"
- *   }, async () => {
- *     const completion = await openai.chat.completions.create({
- *       model: "gpt-4",
- *       messages: [{ role: "user", content: "Tell me a joke about AI" }]
- *     });
- *     return completion.choices[0].message.content;
- *   });
- * });
- *
- * // End the interaction with the result
- * interaction.end(result);
- */
-type Interaction = {
-    /**
-     * Creates a traced task that executes the provided function.
-     *
-     * @param params TaskParams object with task configuration
-     * @returns A span that can be used to record a task
-     */
-    withSpan<T>(params: SpanParams, fn: (...args: any[]) => Promise<T> | T, thisArg?: any, ...args: any[]): Promise<T>;
-    /**
-     * Creates a traced tool that executes the provided function.
-     *
-     * Tools represent external utilities or services that are invoked during an AI interaction.
-     * This method wraps a function call with tracing to capture the tool's inputs and outputs.
-     *
-     * @param params ToolParams object with tool configuration
-     * @param fn Function to execute within the tool trace
-     * @param thisArg Optional 'this' context for the function
-     * @param args Optional arguments to pass to the function
-     * @returns A promise that resolves with the tool execution result
-     *
-     * @example
-     * // Basic tool usage
-     * const result = await interaction.withTool(
-     *   { name: "search_tool" },
-     *   async () => {
-     *     // Call to external API or service
-     *     return "Search results";
-     *   }
-     * );
-     *
-     * @example
-     * // Basic tool usage
-     * const result = await interaction.withTool(
-     *   {
-     *     name: "calculator",
-     *     properties: { operation: "multiply" },
-     *     inputParameters: { a: 5, b: 10 }
-     *   },
-     *   async () => {
-     *     // Tool implementation
-     *     return "Result: 50";
-     *   }
-     * );
-     */
-    withTool<T>(params: ToolParams, fn: (...args: any[]) => Promise<T> | T, thisArg?: any, ...args: any[]): Promise<T>;
-    /**
-     * Creates a task span that can be used to manually record a task.
-     *
-     * @param params TaskParams object with task configuration
-     * @returns A span that can be used to record a task
-     */
-    startSpan(params: SpanParams): Span;
-    /**
-     * Creates a tool span that can be used to manually record a tool invocation.
-     *
-     * Similar to startSpan but sets the span kind to "tool" instead of "task".
-     * Use this when you want manual control over the span lifecycle for tool calls.
-     * Returns a ToolSpan wrapper with convenient methods for setting input, output, and errors.
-     *
-     * @param params ToolParams object with tool configuration
-     * @returns A ToolSpan wrapper for recording the tool execution
-     *
-     * @example
-     * ```typescript
-     * const interaction = raindrop.begin({ userId: "user-123", event: "agent_run" });
-     *
-     * // Start a tool span with manual control
-     * const toolSpan = interaction.startToolSpan({ name: "web_search" });
-     * try {
-     *   const result = await performSearch(query);
-     *   toolSpan.setOutput(result);
-     * } catch (error) {
-     *   toolSpan.setError(error);
-     * } finally {
-     *   toolSpan.end();
-     * }
-     * ```
-     */
-    startToolSpan(params: ToolParams): ToolSpan;
-    /**
-     * Sets multiple properties on the interaction context.
-     *
-     * @param properties Object containing properties to set
-     */
-    setProperties(properties: RaindropProperties): void;
-    /**
-     * Sets a single property on the interaction context.
-     *
-     * @param key The property key
-     * @param value The property value
-     */
-    setProperty(key: string, value: RaindropPropertyValue): void;
-    /**
-     * Adds an attachment to the interaction.
-     *
-     * @param attachment The attachment to add
-     *
-     * @example
-     * // Adding various attachment types to an interaction
-     *
-     * // 1. Text attachment for context
-     * interaction.addAttachment([{
-     *   type: "text",
-     *   name: "Additional Info",
-     *   value: "A very long document",
-     *   role: "input",
-     * }]);
-     *
-     * // 2. Image attachment (output)
-     * interaction.addAttachment([{
-     *   type: "image",
-     *   value: "https://example.com/image.png",
-     *   role: "output"
-     * }]);
-     *
-     * // 3. Iframe for embedded content
-     * interaction.addAttachment([{
-     *   type: "iframe",
-     *   name: "Generated UI",
-     *   value: "https://newui.generated.com",
-     *   role: "output",
-     * }]);
-     *
-     * // 4. Code snippet
-     * interaction.addAttachment([{
-     *   type: "code",
-     *   name: "Generated SQL Query",
-     *   value: "SELECT * FROM users WHERE os_build = '17.1'",
-     *   role: "output",
-     *   language: "sql"
-     * }]);
-     *
-     * // All attachments are included when the interaction ends
-     * interaction.end("The weather is sunny and warm.");
-     */
-    addAttachments(attachments: Attachment[]): void;
-    /**
-     * Sets a single feature flag on the interaction.
-     * @param name The flag name
-     * @param value The flag value (defaults to "true")
-     */
-    setFeatureFlag(name: string, value?: RaindropFeatureFlagValue): void;
-    /**
-     * Sets multiple feature flags on the interaction.
-     * Accepts an array of flag names (all set to "true") or an object with explicit values.
-     * Merges with any previously set flags.
-     * @param flags The feature flags to set
-     */
-    setFeatureFlags(flags: RaindropFeatureFlags): void;
-    /**
-     * Sets the input for the interaction.
-     *
-     * @param input The input string
-     */
-    setInput(input: string): void;
-    /**
-     * Ends the interaction and sends analytics data.
-     *
-     * This method completes the interaction lifecycle by:
-     * 1. Setting the trace_id as a property (if available)
-     * 2. Sending analytics data including the event ID, conversation ID,
-     *    user ID, input, output, attachments, and any custom properties
-     *
-     * @param output The final output string for this interaction
-     *
-     * @example
-     * // Start and end an interaction
-     * const interaction = tracing.begin({
-     *   userId: "user-123",
-     *   convoId: "convo-456"
-     * });
-     *
-     * interaction.setInput("What can you help me with today?");
-     * // ... process the request ...
-     *
-     * // End the interaction with the response
-     * interaction.end("I can help you with various tasks. Here are some examples...");
-     */
-    finish(resultEvent: FinishInteractionOptions): Promise<void>;
-    /**
-     * Returns metadata for Vercel AI SDK's experimental_telemetry option.
-     *
-     * Use this when making Vercel AI SDK calls outside of withSpan() to ensure
-     * the interaction's properties (userId, convoId, eventId) are attached to the spans.
-     *
-     * When using withSpan(), this is handled automatically via context propagation.
-     * This method is a fallback for cases where you can't use withSpan().
-     *
-     * @returns Metadata object with traceloop association properties
-     *
-     * @example
-     * ```typescript
-     * const interaction = raindrop.begin({ userId: "user-123", convoId: "convo-456" });
-     *
-     * // Option 1: Use withSpan (recommended - automatic context propagation)
-     * await interaction.withSpan("my-task", async () => {
-     *   await generateText({ experimental_telemetry: { isEnabled: true }, ... });
-     * });
-     *
-     * // Option 2: Use vercelAiSdkMetadata (fallback when withSpan isn't possible)
-     * await generateText({
-     *   experimental_telemetry: {
-     *     isEnabled: true,
-     *     metadata: interaction.vercelAiSdkMetadata(),
-     *   },
-     *   ...
-     * });
-     * ```
-     */
-    vercelAiSdkMetadata(): Record<string, string>;
-    /**
-     * Returns the interaction event ID used for event/signal correlation.
-     */
-    getEventId(): string | undefined;
-    /**
-     * Logs a tool span directly without wrapping a function.
-     *
-     * Use this when you want to record a tool invocation that has already completed,
-     * rather than wrapping the tool call with withTool(). This is useful for:
-     * - Recording tool calls from external systems
-     * - Logging tools that were executed outside of the tracing context
-     * - Retroactively adding tool spans with known input/output/duration
-     *
-     * @param params TrackToolParams object with tool execution details
-     *
-     * @example
-     * ```typescript
-     * const interaction = raindrop.begin({ userId: "user-123", event: "agent_run" });
-     *
-     * // Record a tool that was already executed
-     * interaction.trackTool({
-     *   name: "web_search",
-     *   input: { query: "weather in NYC" },
-     *   output: { results: ["Sunny, 72°F"] },
-     *   durationMs: 150,
-     * });
-     *
-     * // Record a failed tool
-     * interaction.trackTool({
-     *   name: "database_query",
-     *   input: { sql: "SELECT * FROM users" },
-     *   error: new Error("Connection timeout"),
-     *   durationMs: 5000,
-     * });
-     *
-     * interaction.finish({ output: "Here's the weather..." });
-     * ```
-     */
-    trackTool(params: TrackToolParams): void;
-    /**
-     * Emits a live event to the local debugger for this interaction's trace.
-     *
-     * Use this to surface streaming output or framework-specific progress from
-     * integrations that do not use `@raindrop-ai/ai-sdk`.
-     */
-    emitLiveEvent(event: LocalDebuggerLiveEventInput): void;
-};
-type Tracer = {
-    /**
-     * Creates a traced task that executes the provided function.
-     *
-     * @param params TaskParams object with task configuration
-     * @returns A span that can be used to record a task
-     */
-    withSpan<T>(params: SpanParams, fn: (...args: any[]) => Promise<T> | T, thisArg?: any, ...args: any[]): Promise<T>;
-    /**
-     * Logs a tool span directly without wrapping a function.
-     *
-     * Use this when you want to record a tool invocation that has already completed,
-     * rather than wrapping the tool call. This is useful for batch jobs or
-     * non-interactive use-cases where you only care about tracing and token usage.
-     *
-     * @param params TrackToolParams object with tool execution details
-     *
-     * @example
-     * ```typescript
-     * const tracer = raindrop.tracer({ job_id: "batch-123" });
-     *
-     * // Record a tool that was already executed
-     * tracer.trackTool({
-     *   name: "web_search",
-     *   input: { query: "weather in NYC" },
-     *   output: { results: ["Sunny, 72°F"] },
-     *   durationMs: 150,
-     * });
-     * ```
-     */
-    trackTool(params: TrackToolParams): void;
-    /**
-     * Emits a live event to the local debugger using the current active trace.
-     */
-    emitLiveEvent(event: LocalDebuggerLiveEventInput): void;
-};
-
-declare global {
-    var RAINDROP_ASYNC_LOCAL_STORAGE: (new <T>() => {
-        getStore(): T | undefined;
-        run<R>(store: T, callback: () => R): R;
-        enterWith?(store: T): void;
-    }) | undefined;
-}
-
-interface AnalyticsConfig {
-    wizardSession?: string;
-    /**
-     * Raindrop write key. When omitted (or empty), the SDK runs in local-only mode:
-     * cloud requests are skipped and only the Workshop / local-debugger mirror fires
-     * (when `localWorkshopUrl` resolves to a URL). Useful for local development where
-     * you only want events to land in Workshop without provisioning a write key.
-     */
-    writeKey?: string;
-    bufferSize?: number;
-    bufferTimeout?: number;
-    debugLogs?: boolean;
-    endpoint?: string;
-    redactPii?: boolean;
-    /**
-     * Per-field character cap applied to ai input/output and serialized
-     * tool/span content BEFORE buffering or serialization, so oversized
-     * payloads cost the cap — not the payload — on the calling code path
-     * (`JSON.stringify` of a multi-MB payload blocks the event loop).
-     * Truncated fields end with `...[truncated by raindrop]` and never exceed
-     * the cap, marker included. Defaults to 1,000,000 (matching the Python SDK's
-     * `max_text_field_chars`).
-     */
-    maxTextFieldChars?: number;
-    /**
-     * Force-enable (or opt out of) Workshop / local-debugger mirroring.
-     *
-     *   - `string` — explicit Workshop URL (e.g. `"http://localhost:5899/v1/"`),
-     *     wins over env vars and runtime auto-detect.
-     *   - `false` (or `null`) — explicit opt-out, even on localhost / when
-     *     `NODE_ENV=development` / when `RAINDROP_WORKSHOP` is set.
-     *   - `undefined` (default) — fall through to `RAINDROP_LOCAL_DEBUGGER`,
-     *     `RAINDROP_WORKSHOP`, and runtime auto-detect (localhost-ish hostname
-     *     OR `NODE_ENV=development` enables the default `:5899` daemon).
-     */
-    localWorkshopUrl?: string | false | null;
-    /**
-     * Optional project slug. When set, every outbound cloud ingest request
-     * (event POSTs and the direct trace shipper) carries an
-     * `X-Raindrop-Project-Id: <projectId>` header so the backend routes the
-     * data to that project. Empty / whitespace-only values are ignored and the
-     * backend falls back to the account's default project. Slug format is
-     * validated on construction but never throws — invalid values are warned
-     * about (when `debugLogs` is true) and sent anyway (the backend returns
-     * HTTP 400 if the value is actually unusable). Local Workshop mirror
-     * requests deliberately skip this header (project routing is a cloud-only
-     * concept), mirroring the `@raindrop-ai/core` convention.
-     */
-    projectId?: string;
-    /**
-     * @deprecated Renamed to `useExternalOtel`. Use that instead.
-     * This option will be removed in a future version.
-     */
-    disableTracing?: boolean;
-    /**
-     * Set to true if you have your own OpenTelemetry setup (e.g., Sentry, Datadog).
-     *
-     * When true:
-     * - Raindrop won't create its own NodeSDK (avoids conflicts)
-     * - Use `raindrop.createSpanProcessor()` to get a processor for your NodeSDK
-     * - Use `raindrop.getInstrumentations()` to get configured LLM instrumentations
-     *
-     * @example
-     * ```ts
-     * import { NodeSDK } from "@opentelemetry/sdk-node";
-     * import Anthropic from "@anthropic-ai/sdk";
-     *
-     * const raindrop = new Raindrop({
-     *   writeKey: "xxx",
-     *   useExternalOtel: true,
-     *   instrumentModules: { anthropic: Anthropic },
-     * });
-     *
-     * const sdk = new NodeSDK({
-     *   spanProcessors: [raindrop.createSpanProcessor(), yourSentryProcessor],
-     *   instrumentations: raindrop.getInstrumentations(),
-     * });
-     * sdk.start();
-     * ```
-     */
-    useExternalOtel?: boolean;
-    /**
-     * false by default. If true, the SDK will not send any events or initialize tracing.
-     * Useful for development/test environments.
-     */
-    disabled?: boolean;
-    /**
-     * Disable span batching for local development.
-     * When true, spans are sent immediately instead of being batched.
-     * Defaults to true in development (NODE_ENV !== 'production').
-     */
-    disableBatching?: boolean;
-    /**
-     * When true, all `trackTool()`, `withTool()`, and `startToolSpan()` calls bypass the OTEL
-     * exporter pipeline and ship spans directly to the Raindrop API via HTTP POST.
-     *
-     * Spans still read the active OTEL context to inherit traceId
-     * and parentSpanId — they still appear as children in the trace tree.
-     * Only the shipping mechanism changes.
-     *
-     * This is useful when OTEL setup is fragile (e.g., conflicting providers,
-     * broken exporters) but you still want tool spans to work reliably.
-     *
-     * @default false
-     */
-    bypassOtelForTools?: boolean;
-    /**
-     * Whether `interaction.finish()` should await the in-flight span/trace flush
-     * (i.e. `forceFlush()`, which drains buffered OTLP/tool spans — a `/v1/traces`
-     * POST with retries) before resolving. This await was added so a local
-     * Workshop daemon doesn't race OTLP ingest; in cloud mode it only adds
-     * request latency.
-     *
-     * Note this gates *only* the span flush. `finish()` always awaits the
-     * terminal partial-event POST that records the run, and always orders it
-     * after any earlier in-flight POST for the same eventId — to skip the
-     * partial POST too, simply don't `await interaction.finish(...)`.
-     *
-     * - `true` / `undefined` (default) — await the span/trace flush, preserving
-     *   the historical guaranteed-flush-before-return behavior.
-     * - `false` — don't await it; it drains in the background so the caller's
-     *   request isn't taxed by the round trip + retries. A local Workshop /
-     *   debugger still forces the await regardless (its read-after-write
-     *   guarantee depends on it).
-     */
-    awaitSpanFlush?: boolean;
-    /**
-     * Explicitly specify modules to instrument. Optional.
-     *
-     * Pass the module constructors/namespaces you want to instrument:
-     * @example
-     * ```ts
-     * import OpenAI from "openai";
-     * import Anthropic from "@anthropic-ai/sdk";
-     *
-     * const raindrop = new Raindrop({
-     *   writeKey: "xxx",
-     *   instrumentModules: {
-     *     openAI: OpenAI,
-     *     anthropic: Anthropic,
-     *   },
-     * });
-     * ```
-     */
-    instrumentModules?: {
-        openAI?: unknown;
-        anthropic?: unknown;
-        cohere?: unknown;
-        bedrock?: unknown;
-        google_vertexai?: unknown;
-        google_aiplatform?: unknown;
-        pinecone?: unknown;
-        together?: unknown;
-        langchain?: boolean;
-        llamaIndex?: unknown;
-        chromadb?: unknown;
-        qdrant?: unknown;
-        mcp?: unknown;
-    } & Record<string, unknown>;
-}
-declare const MAX_INGEST_SIZE_BYTES: number;
-/**
- * Resolve the effective `disableBatching` flag that decides whether tracing
- * uses `SimpleSpanProcessor` (immediate export) or `BatchSpanProcessor`.
- *
- * Precedence:
- *   1. An explicit `config.disableBatching` always wins, in both directions.
- *   2. Otherwise, batching is disabled when NOT in production (existing
- *      behavior) OR when the local debugger (Workshop) is active — so spans
- *      deliver immediately to Workshop even under `NODE_ENV=production`.
- *
- * Production behavior for consumers is unchanged: with no local debugger and
- * no explicit config, this returns `false` (i.e. batching stays on).
- */
-declare function resolveDisableBatching(explicit: boolean | undefined, signals: {
-    isProduction: boolean;
-    isLocalDebugger: boolean;
-}): boolean;
-declare class Raindrop {
-    private wizardSession;
-    private writeKey;
-    private apiUrl;
-    private buffer;
-    private bufferSize;
-    private bufferTimeout;
-    private flushTimer;
-    private redactPii;
-    private disabled;
-    private context;
-    private _tracing;
-    private localDebuggerUrlOpt;
-    private awaitSpanFlushOpt;
-    private partialEventBuffer;
-    private partialEventTimeouts;
-    private inFlightRequests;
-    private inFlightByEvent;
-    private maxTextFieldChars;
-    private projectId;
-    private authHint;
-    /**
-     * Epoch ms deadline while `close()` is draining; undefined otherwise.
-     * Checked before every POST issued during the final flush so a dead or
-     * slow network can never wedge process exit.
-     */
-    private shutdownDeadlineAt;
-    /**
-     * Set once `close()` begins and never cleared. Sends issued after the
-     * drain window (stragglers, or flush work the deadline abandoned
-     * mid-drain) run as a single short attempt instead of regaining the full
-     * retry schedule.
-     */
-    private hasShutdown;
-    debugLogs: boolean;
-    constructor(config: AnalyticsConfig);
-    private get localOnly();
-    private formatEndpoint;
-    /**
-     * Begins a new interaction.
-     *
-     * The interaction's routing binding lives until `finish()` (which unbinds it
-     * by identity, so it is removed even if `finish()` runs inside a nested
-     * `withSpan`/`withTool`/`asCurrent` scope or a detached task). One exception:
-     * calling `begin()` INSIDE an `asCurrent(fn)` scope pushes the binding within
-     * that scope, so it dies when the scope exits (matching the Python SDK's
-     * token-reset semantics) — start such interactions outside `asCurrent`, or
-     * keep their work inside the same scope.
-     *
-     * @param traceContext - The trace context for the interaction.
-     * @returns The interaction object.
-     */
-    begin(traceContext: PartialAiTrackEvent & {
-        event: string;
-        userId: string;
-    }): Interaction;
-    /**
-     * Returns a tracer object that can be used to create spans and tools that aren't tied to any interaction.
-     * For chat interaction use-case `begin` should be used.
-     * This is meant for batch jobs or other non-interactive use-cases where you only care about tracing and token usage.
-     *
-     * @param globalProperties - Optional global properties to be associated with all spans and tools.
-     * @returns The tracer object.
-     */
-    tracer(globalProperties?: Record<string, string>): Tracer;
-    /**
-     * Scope all spans created inside `fn` (and its awaited continuations) to this
-     * client's project/key, without an interaction. Use it around auto-
-     * instrumented calls (an LLM SDK call, a framework invocation) that aren't
-     * wrapped by `begin()`/`finish()` so their spans route to this client's
-     * project in a multi-client process. The binding lasts exactly the duration
-     * of `fn` — it is removed when `fn` returns or throws.
-     *
-     * @example
-     * ```ts
-     * const answer = await raindrop.asCurrent(() => llm.chat({ ... }));
-     * ```
-     */
-    asCurrent<T>(fn: () => T): T;
-    createSpanProcessor(processorOptions?: SpanProcessorOptions): RaindropSpanProcessor;
-    /**
-     * Returns configured instrumentation instances based on instrumentModules.
-     * Add these to your NodeSDK when using useExternalOtel: true.
-     *
-     * @example
-     * ```ts
-     * import { NodeSDK } from "@opentelemetry/sdk-node";
-     * import Anthropic from "@anthropic-ai/sdk";
-     *
-     * const raindrop = new Raindrop({
-     *   writeKey: "xxx",
-     *   useExternalOtel: true,
-     *   instrumentModules: { anthropic: Anthropic },
-     * });
-     *
-     * const sdk = new NodeSDK({
-     *   spanProcessors: [raindrop.createSpanProcessor()],
-     *   instrumentations: raindrop.getInstrumentations(),
-     * });
-     * sdk.start();
-     * ```
-     */
-    getInstrumentations(): _opentelemetry_instrumentation.Instrumentation<_opentelemetry_instrumentation.InstrumentationConfig>[];
-    /**
-     * Resumes an existing interaction.
-     *
-     * @param eventId - The ID of the interaction to resume.
-     * @returns The interaction object.
-     */
-    resumeInteraction(eventId: string): Interaction;
-    /**
-     * Creates a framework-agnostic self-diagnostics tool definition.
-     *
-     * Use this when your agent framework does not support automatic tool injection.
-     * The returned object includes adapters for Vercel AI SDK, OpenAI function tools,
-     * and Anthropic tool definitions.
-     */
-    createSelfDiagnosticsTool(options?: SelfDiagnosticsToolOptions): SelfDiagnosticsTool;
-    /**
-     * Track AI events. In addiiton to normal event properties, you can provide an "input", "output", or "model" parameter.
-     * It takes an AiTrackEvent as input and sends it to the /track-ai endpoint of the raindrop api.
-     *
-     * @param event - The AiTrackEvent (you must specify at least one of input/output properties)
-     * @returns A Promise that resolves when the event has been successfully sent.
-     *
-     * Example usage:
-     * ```typescript
-     * raindrop.track_ai({
-     *   event: "chat", //name of the event
-     *   model: "claude", //optional
-     *   input: "what's up?", // input or output is required
-     *   output: "not much human, how are you?", //input or output is required
-     *   userId: "cn123456789",
-     * });
-     * ```
-     */
-    trackAi(event: AiTrackEvent | AiTrackEvent[]): string | Array<string | undefined> | undefined;
-    setUserDetails(event: IdentifyEvent): void;
-    /**
-     * Report a self-diagnostic signal. This is a convenient shorthand for sending
-     * signals that appear in the Self Diagnostics tab of the Raindrop dashboard.
-     *
-     * @param options - The diagnostic details.
-     * @param options.eventId - The interaction/event ID this diagnostic belongs to.
-     * @param options.description - A human-readable description of the issue.
-     * @param options.category - Optional category (e.g. "missing_context"). Defaults to "general".
-     * @param options.source - Optional source identifier. Defaults to "selfDiagnose".
-     * @param options.sentiment - Signal sentiment. Defaults to "NEGATIVE".
-     * @param options.properties - Additional custom properties.
-     *
-     * @example
-     * ```typescript
-     * raindrop.selfDiagnose({
-     *   eventId: "evt_123",
-     *   description: "User asked for production DB access but no credentials were provided.",
-     *   category: "missing_context",
-     * });
-     * ```
-     */
-    selfDiagnose(options: SelfDiagnoseOptions): void;
-    trackSignal(signal: SignalEvent | SignalEvent[]): void | void[];
-    private getSize;
-    private saveToBuffer;
-    private flush;
-    private mirrorBatchToLocalDebugger;
-    /**
-     * Attempts/timeout budget for one POST, honoring the close() deadline.
-     * Returns `null` when the shutdown budget is exhausted — the caller must
-     * drop the payload instead of issuing a request that could outlive
-     * process exit. Checked fresh on every send so a deadline that expires
-     * mid-drain takes effect immediately.
-     */
-    private requestBudget;
-    private warnShutdownDrop;
-    private sendBatchToApi;
-    private getContext;
-    private formatZodError;
-    /**
-     * Deeply merges properties of the source object into the target object.
-     * Modifies the target object in place. Handles nested plain objects.
-     */
-    private deepMergeObjects;
-    /**
-     * Internal method for tracking partial AI events. use .begin() to start an interaction instead.
-     *
-     * @param event - The PartialAiTrackEvent, requires eventId.
-     */
-    _trackAiPartial(event: PartialAiTrackEvent): Promise<void>;
-    /**
-     * Flushes a single accumulated partial event by its ID.
-     * This is called internally by the timeout or by the close method.
-     * @param eventId - The ID of the partial event to flush.
-     */
-    private flushPartialEvent;
-    /**
-     * Internal implementation of flushPartialEvent without request tracking.
-     * @param eventId - The ID of the partial event to flush.
-     */
-    private _flushPartialEventInternal;
-    /**
-     * Sends a single prepared event object to the 'events/track_partial' endpoint.
-     * @param event - The event data conforming to ClientAiTrack schema.
-     */
-    private sendPartialEvent;
-    /**
-     * Best-effort flush of in-flight OTel spans and pending partial-event POSTs.
-     * Safe to call multiple times; never throws.
-     */
-    forceFlush(): Promise<void>;
-    close(): Promise<void>;
-    private closeWithinDeadline;
-}
-
-export { type AiTrackEvent, type Attachment, type AttachmentType, type BeginInteractionOptions, type FinishInteractionOptions, type IdentifyEvent, type Interaction, type LocalDebuggerLiveEventInput, MAX_INGEST_SIZE_BYTES, type PartialAiTrackEvent, Raindrop, type RaindropFeatureFlagValue, type RaindropFeatureFlags, type RaindropProperties, type RaindropPropertyLeaf, type RaindropPropertyValue, type RaindropSpanProcessor, type SelfDiagnoseOptions, type SelfDiagnosticsExecuteContext, type SelfDiagnosticsExecuteResult, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type SelfDiagnosticsTool, type SelfDiagnosticsToolInputSchema, type SelfDiagnosticsToolOptions, type SignalEvent, type SpanParams, type ToolParams, type ToolSpan, type TraceContext, type Tracer, type TrackToolParams, type WorkflowParams, Raindrop as default, resolveDisableBatching };
+import '@opentelemetry/instrumentation';
+export { A as AiTrackEvent, d as Attachment, e as AttachmentType, B as BeginInteractionOptions, F as FinishInteractionOptions, f as IdentifyEvent, I as Interaction, L as LocalDebuggerLiveEventInput, M as MAX_INGEST_SIZE_BYTES, P as PartialAiTrackEvent, R as Raindrop, g as RaindropFeatureFlagValue, h as RaindropFeatureFlags, i as RaindropProperties, j as RaindropPropertyLeaf, k as RaindropPropertyValue, a as RaindropSpanProcessor, l as SelfDiagnoseOptions, m as SelfDiagnosticsExecuteContext, n as SelfDiagnosticsExecuteResult, o as SelfDiagnosticsSignalDefinition, p as SelfDiagnosticsSignalDefinitions, q as SelfDiagnosticsTool, r as SelfDiagnosticsToolInputSchema, s as SelfDiagnosticsToolOptions, t as SignalEvent, u as SpanParams, v as SubagentDispatch, w as SubagentDispatchOptions, x as SubagentFinishOptions, S as SubagentResumeOptions, b as SubagentRun, y as ToolParams, z as ToolSpan, D as TraceContext, c as Tracer, E as TrackToolParams, W as WorkflowParams, R as default, G as resolveDisableBatching } from './index-DBdUrUXc.mjs';
+import '@traceloop/node-server-sdk';
+import '@opentelemetry/api';
+import 'zod';