raindrop-ai 0.2.4 → 0.3.0

package/dist/index-DBdUrUXc.d.mts

@@ -0,0 +1,1457 @@
+import * as _opentelemetry_instrumentation from '@opentelemetry/instrumentation';
+import { Span } from '@opentelemetry/api';
+import { z } from 'zod';
+import { SpanProcessorOptions } from '@traceloop/node-server-sdk';
+
+/** The reverse reference a detached child carries on its own spans. */
+type DetachedChildLink = {
+    /** The caller's event id. */
+    parentEventId: string;
+    /** The dispatch span id, hex-encoded as the backend stores span ids. */
+    parentSpanId?: string;
+    name?: string;
+};
+
+/**
+ * Portable trace-context carrier for cross-process sub-agents.
+ *
+ * `toHeaders()` / `fromHeaders()` mirror LangSmith's
+ * `RunTree.toHeaders()` / `tracing_context(parent=headers)` so migrating from
+ * LangSmith is a rename rather than a redesign.
+ *
+ * Two carriers are understood:
+ *
+ *   1. Native — `x-raindrop-handoff`, plus W3C `traceparent` and a `baggage` of
+ *      `raindrop-*` keys. The standard pair is what other readers understand;
+ *      the Raindrop header is what survives an instrumented caller, and wins
+ *      where they disagree. See {@link HANDOFF_HEADER}.
+ *   2. LangSmith — `langsmith-trace` (dotted order) plus LangSmith's `baggage`.
+ *      Accepted on READ so a service already propagating LangSmith headers links
+ *      correctly with no call-site change.
+ *
+ * ## Trust boundary
+ *
+ * A carrier names the event a child will be attributed to, so accepting one from
+ * an untrusted caller lets that caller write into another tenant's trace. Only
+ * accept carriers from services inside your own trust boundary — the same
+ * constraint LangSmith documents for distributed tracing. Never take a carrier
+ * off a public, unauthenticated request.
+ *
+ * Trace and span ids are hex here, as W3C `traceparent` and the Raindrop backend
+ * both represent them. Use `base64ToHex` when converting from the base64 ids
+ * used inside the trace shippers.
+ */
+type TraceCarrier = {
+    /** Hex trace id (32 chars for a W3C-conformant id). */
+    traceId: string;
+    /** Hex span id of the dispatching span (16 chars for a W3C-conformant id). */
+    spanId: string;
+    /** Event the child should join (continuation) or reference (detached). */
+    eventId: string;
+    /** Set only for a detached hand-off: the child's OWN event id. */
+    childEventId?: string;
+    /** Sub-agent name, carried so the child can label its own run identically. */
+    name?: string;
+    convoId?: string;
+    userId?: string;
+};
+/**
+ * A header container that answers by name rather than by property.
+ *
+ * A WHATWG `Headers` — what fetch, Next.js route handlers, Hono, Remix and
+ * Cloudflare Workers all call `request.headers` — keeps its fields in an
+ * internal slot, so `headers["baggage"]` is `undefined` and `Object.entries()`
+ * on one yields nothing. Next.js's `headers()` returns a `ReadonlyHeaders`,
+ * which is that object sealed behind a Proxy. `get()` is the only way in, and it
+ * is also where the spec puts case-insensitivity and the joining of repeated
+ * fields — so the container does that work rather than {@link readHeader}
+ * reimplementing it.
+ */
+type HeaderLookup = {
+    get(name: string): string | null | undefined;
+};
+type CarrierHeaders = Readonly<Record<string, string | string[] | undefined>> | HeaderLookup;
+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;
+};
+/**
+ * Arguments for {@link Interaction.subagent}.
+ *
+ * Deliberately absent: anything describing how the child is doing. The caller
+ * dispatched a job and moved on, so a status it wrote would be a guess that
+ * goes stale — readers derive status from the child's own event.
+ */
+interface SubagentDispatchOptions {
+    /** Sub-agent name. The child labels its own run with the same value. */
+    name: string;
+    /** Launch arguments, recorded as the dispatch span's input. */
+    input?: unknown;
+    /**
+     * Reuse an id the caller already has (a queue job id, say) instead of
+     * minting one. Either way the id exists BEFORE dispatch, which is what makes
+     * the link resolvable while the child is still queued.
+     */
+    childEventId?: string;
+    /** Name of the dispatch span. Defaults to `launch_subagent`. */
+    toolName?: string;
+    /** Extra properties recorded on the dispatch span. */
+    properties?: RaindropProperties;
+}
+/** The record of one detached dispatch, returned by {@link Interaction.subagent}. */
+interface SubagentDispatch {
+    /** The child's own event id — the job handle to pass to the worker. */
+    childEventId: string;
+    name: string;
+    /** The launching interaction's event id. */
+    parentEventId: string;
+    /** Hex id of the dispatch span, or `undefined` when none was recorded. */
+    dispatchSpanId?: string;
+    /**
+     * The carrier behind the headers, for transports that are not HTTP.
+     *
+     * `null` when no dispatch span could be recorded (tracing disabled). There is
+     * then no span for the child to reference, and `headers` is empty rather than
+     * naming one that does not exist — pass `childEventId` to the worker yourself
+     * if it must still report under that id.
+     */
+    carrier: TraceCarrier | null;
+    /**
+     * Native carrier headers: W3C `traceparent` + `raindrop-*` `baggage`, plus
+     * `x-raindrop-handoff` carrying the same fields under a name no propagator
+     * rewrites. Send all of them — instrumentation owns `traceparent` and the
+     * baggage propagator REPLACES `baggage`, so the standard pair alone can arrive
+     * emptied of every hand-off identity.
+     *
+     * TRUST BOUNDARY: send these only to services inside your own trust
+     * boundary — a carrier names the event the child will be attributed to.
+     */
+    headers: Record<string, string>;
+    /** The same carrier in LangSmith's header shape, for services that parse it. */
+    langsmithHeaders: Record<string, string>;
+}
+/**
+ * Fallbacks for a sub-agent run whose request carried no carrier, i.e. one
+ * invoked directly rather than dispatched.
+ *
+ * These do NOT override a carrier. Every identity field here names something
+ * the launcher already recorded, so a local value winning would strand the
+ * child outside the link it exists to complete.
+ */
+interface SubagentResumeOptions {
+    /** Used when the carrier supplied no name. */
+    name?: string;
+    /** Used when the carrier supplied no child event id. */
+    eventId?: string;
+    userId?: string;
+    convoId?: string;
+    /** Event name for the child's own event. Defaults to `subagent.<name>`. */
+    event?: string;
+    input?: string;
+    model?: string;
+    properties?: RaindropProperties;
+    /** Pre-parsed carrier, for transports that are not HTTP. */
+    parent?: TraceCarrier | null;
+}
+/** How a detached sub-agent's run completes. */
+type SubagentFinishOptions = Omit<FinishInteractionOptions, "eventId">;
+/**
+ * A detached sub-agent's own run, as seen from inside the sub-agent.
+ *
+ * Wraps the child's own Raindrop event and keeps the reverse reference bound to
+ * the execution context, so every span the child emits while the run is open
+ * carries it.
+ */
+interface SubagentRun {
+    /** The child's own Raindrop event. */
+    readonly interaction: Interaction;
+    /** The child's own event id, adopted from the carrier when it supplied one. */
+    readonly eventId: string;
+    readonly name: string;
+    /** The conversation this run reports into — the launcher's when linked. */
+    readonly convoId?: string;
+    /**
+     * The launching context, or `null` when the request carried no carrier.
+     *
+     * `null` is a legitimate state — the sub-agent was invoked directly rather
+     * than dispatched — and the run still reports as its own event, just without
+     * a link back.
+     */
+    readonly parent: DetachedChildLink | null;
+    readonly linked: boolean;
+    /** Complete the child's event with its result. */
+    finish(result: SubagentFinishOptions): Promise<void>;
+    /**
+     * Report that the run aborted: error the child's own span, and say why in
+     * the output.
+     *
+     * Both halves matter. The ERROR status is what makes the run read as
+     * *failed* — status is derived from the child's telemetry, and a run with
+     * output but no errored span is indistinguishable from one that succeeded.
+     * The output is what makes the run exist at all: an event needs non-empty
+     * output, so a child that closes empty leaves its launcher on `queued`
+     * forever.
+     */
+    fail(reason: unknown): Promise<void>;
+    /**
+     * Mark the run cancelled — the one state its telemetry cannot express.
+     *
+     * A cancelled run is span-for-span identical to a finished one (spans close,
+     * nothing errors, there is simply no answer), so it needs an explicit
+     * marker. Written by the child on itself, never by the caller. Deliberately
+     * does NOT error any span: error spans are what separate failed from
+     * cancelled.
+     */
+    cancel(reason?: unknown): Promise<void>;
+}
+/**
+ * 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;
+    /**
+     * Records the launch of a **detached** sub-agent: one that runs in another
+     * process, does not block this interaction, and reports as its own Raindrop
+     * event with its own lifecycle.
+     *
+     * The child's event id is allocated BEFORE anything is dispatched, so this
+     * interaction can point at the child from the moment of launch — while the
+     * job is still queued and before the child has emitted anything. Send the
+     * returned headers with the job; the worker passes them to
+     * `raindrop.resumeSubagent()`.
+     *
+     * Nothing here waits for the child, and nothing here claims to know how it
+     * is doing.
+     *
+     * @example
+     * ```typescript
+     * const dispatch = interaction.subagent({
+     *   name: "researcher",
+     *   input: { task },
+     * });
+     * await queue.send({ task, headers: dispatch.headers });
+     * return { jobId: dispatch.childEventId, status: "accepted" };
+     * ```
+     */
+    subagent(options: SubagentDispatchOptions): SubagentDispatch;
+};
+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;
+    /**
+     * Opens the child's own event for a launched detached sub-agent.
+     *
+     * Sibling to {@link resumeInteraction}, and deliberately not the same thing:
+     * a resumed interaction JOINS the caller's event, while a detached sub-agent
+     * reports as its OWN event under the id the launcher minted, linked back only
+     * by the hand-off attributes both sides write. Every span the run emits
+     * carries the reverse reference until it reports a result.
+     *
+     * Pass the headers the request arrived with. A missing carrier is a
+     * legitimate state — the sub-agent was invoked directly rather than
+     * dispatched — so this always returns a usable run and leaves `parent` null;
+     * call sites stay unconditional. A malformed carrier costs the link, never
+     * the request.
+     *
+     * The carrier is authoritative for every identity field it supplies. The
+     * options are fallbacks for the direct-invocation case, not overrides: each
+     * field names something the launcher already recorded, so a locally minted
+     * value winning would strand the child outside the link.
+     *
+     * > **Trust boundary.** A carrier names the event the child will be
+     * > attributed to, so accepting one from an untrusted caller lets that caller
+     * > write into another tenant's trace. Only read carriers that came from
+     * > inside your own trust boundary.
+     *
+     * @example
+     * ```typescript
+     * const run = raindrop.resumeSubagent(request.headers);
+     * try {
+     *   const answer = await doTheWork();
+     *   await run.finish({ output: answer });
+     * } catch (error) {
+     *   await run.fail(error);
+     * }
+     * ```
+     */
+    resumeSubagent(headers: CarrierHeaders | TraceCarrier | null | undefined, options?: SubagentResumeOptions): SubagentRun;
+    /**
+     * Runs `fn` as a detached sub-agent and guarantees the run reports an
+     * outcome, mirroring the Python SDK's `with rd.resume_subagent(...) as run:`.
+     *
+     * A run that returns without reporting output is closed with an abort reason,
+     * and one that throws is failed with it. That is not cosmetic: an event is
+     * created only from a run with non-empty output, so a child that dies
+     * silently produces no event at all and its launcher stays on `queued`
+     * forever — indistinguishable from a job that never started.
+     *
+     * @example
+     * ```typescript
+     * await raindrop.withSubagentRun(request.headers, async (run) => {
+     *   await run.finish({ output: await doTheWork() });
+     * });
+     * ```
+     */
+    withSubagentRun<T>(headers: CarrierHeaders | TraceCarrier | null | undefined, fn: (run: SubagentRun) => Promise<T> | T, options?: SubagentResumeOptions): Promise<T>;
+    /**
+     * 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 as A, type BeginInteractionOptions as B, type CarrierHeaders as C, type TraceContext as D, type TrackToolParams as E, type FinishInteractionOptions as F, resolveDisableBatching as G, type Interaction as I, type LocalDebuggerLiveEventInput as L, MAX_INGEST_SIZE_BYTES as M, type PartialAiTrackEvent as P, Raindrop as R, type SubagentResumeOptions as S, type TraceCarrier as T, type WorkflowParams as W, type RaindropSpanProcessor as a, type SubagentRun as b, type Tracer as c, type Attachment as d, type AttachmentType as e, type IdentifyEvent as f, type RaindropFeatureFlagValue as g, type RaindropFeatureFlags as h, type RaindropProperties as i, type RaindropPropertyLeaf as j, type RaindropPropertyValue as k, type SelfDiagnoseOptions as l, type SelfDiagnosticsExecuteContext as m, type SelfDiagnosticsExecuteResult as n, type SelfDiagnosticsSignalDefinition as o, type SelfDiagnosticsSignalDefinitions as p, type SelfDiagnosticsTool as q, type SelfDiagnosticsToolInputSchema as r, type SelfDiagnosticsToolOptions as s, type SignalEvent as t, type SpanParams as u, type SubagentDispatch as v, type SubagentDispatchOptions as w, type SubagentFinishOptions as x, type ToolParams as y, type ToolSpan as z };