@raindrop-ai/ai-sdk 0.0.32 → 0.0.34

package/dist/index.browser.d.mts

@@ -35,7 +35,6 @@ type SpanIds = {
     spanIdB64: string;
     parentSpanIdB64?: string;
 };
-
 type Attachment$1 = {
     type: string;
     role: string;
@@ -84,6 +83,14 @@ type EventShipperOptions = {
      * Pass `null` to opt out of all mirroring (including auto-detect).
      */
     localDebuggerUrl?: string | null;
+    /**
+     * Per-field character cap applied to event input/output BEFORE buffering
+     * or serialization, so oversized payloads cost the cap — not the payload —
+     * on the calling code path. Truncated fields end with
+     * `...[truncated by raindrop]` and never exceed the cap, marker included.
+     * Defaults to 1,000,000 (matching the Python SDK).
+     */
+    maxTextFieldChars?: number;
 };
 declare class EventShipper$1 {
     private baseUrl;
@@ -99,11 +106,39 @@ declare class EventShipper$1 {
     private sticky;
     private timers;
     private inFlight;
+    private maxTextFieldCharsOpt;
+    /**
+     * Epoch ms deadline while `shutdown()` is draining; undefined otherwise.
+     * Checked before every POST issued during the final flush.
+     */
+    private shutdownDeadlineAt;
+    /**
+     * Set once `shutdown()` 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;
     /** URL of the local debugger / Workshop daemon, when one is reachable. */
     private localDebuggerUrl;
     constructor(opts: EventShipperOptions);
     isDebugEnabled(): boolean;
     private authHeaders;
+    /**
+     * Build the retry/timeout options for one POST, honoring the shutdown
+     * deadline. Returns `null` when the shutdown drain window is exhausted —
+     * the caller must drop the payload (with a rate-limited warning) instead
+     * of issuing a request that could outlive process exit.
+     *
+     * Checked fresh on EVERY send, so a shutdown that begins while the flush
+     * path is mid-drain takes effect immediately: no further retries, and the
+     * per-attempt timeout is clamped to the remaining window. After
+     * `shutdown()` returns (deadline cleared, `hasShutdown` still set),
+     * sends — late callers, or flush work the deadline abandoned mid-drain —
+     * run as a single short attempt rather than regaining the full retry
+     * schedule.
+     */
+    private requestOpts;
     patch(eventId: string, patch: Patch): Promise<void>;
     finish(eventId: string, patch: {
         output?: string;
@@ -115,6 +150,7 @@ declare class EventShipper$1 {
     shutdown(): Promise<void>;
     trackSignal(signal: SignalInput): Promise<void>;
     identify(users: IdentifyInput$1 | IdentifyInput$1[]): Promise<void>;
+    private warnShutdownDrop;
     private flushOne;
 }
 
@@ -252,6 +288,15 @@ type TraceShipperOptions = {
      * still want some redaction in that case.
      */
     disableDefaultRedaction?: boolean;
+    /**
+     * Per-attribute character cap applied to every span attribute string value
+     * right before the span enters a ship path, so a multi-MB prompt/tool
+     * payload can never make the batch `JSON.stringify` (which runs on the
+     * event loop) cost seconds. Truncated values end with
+     * `...[truncated by raindrop]` and never exceed the cap, marker included.
+     * Defaults to 1,000,000 (matching the Python SDK).
+     */
+    maxTextFieldChars?: number;
 };
 declare class TraceShipper$1 {
     private baseUrl;
@@ -273,7 +318,32 @@ declare class TraceShipper$1 {
     private localDebuggerUrl;
     private transformSpanHook;
     private disableDefaultRedaction;
+    private maxTextFieldCharsOpt;
+    /**
+     * Epoch ms deadline while `shutdown()` is draining; undefined otherwise.
+     * Checked before every batch POST issued during the final flush.
+     */
+    private shutdownDeadlineAt;
+    /**
+     * Set once `shutdown()` 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;
     constructor(opts: TraceShipperOptions);
+    /**
+     * Cap every string attribute value on the span. O(#attributes) length
+     * checks; only oversized values pay a slice. Runs AFTER the redaction
+     * pipeline so the default secret-scrub still sees parseable JSON in
+     * `ai.request.providerOptions` / `ai.response.providerMetadata` (capping
+     * first could cut a JSON blob mid-way, fail the parse, and ship secrets
+     * in the surviving prefix).
+     *
+     * A stricter `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is honored
+     * for span content, matching the Python SDK and the OTel SDK convention.
+     */
+    private capSpanAttributes;
     /**
      * Apply the user `transformSpan` hook (if any) followed by the default
      * redactor (unless disabled). Returns either the (possibly new) span to
@@ -323,6 +393,8 @@ declare class TraceShipper$1 {
     }): void;
     enqueue(span: OtlpSpan): void;
     flush(): Promise<void>;
+    /** See EventShipper.requestOpts — same shutdown-budget semantics. */
+    private requestOpts;
     shutdown(): Promise<void>;
 }
 
@@ -365,6 +437,29 @@ declare class TraceShipper extends TraceShipper$1 {
 }
 
 type Listener<T> = (event: T) => PromiseLike<void> | void;
+type ToolExecutionEndEvent = {
+    callId: string;
+    toolCall: {
+        toolCallId: string;
+        toolName: string;
+    };
+    toolOutput: {
+        type: "tool-result";
+        output: unknown;
+    } | {
+        type: "tool-error";
+        error: unknown;
+    };
+} | {
+    callId: string;
+    toolCall: {
+        toolCallId: string;
+        toolName: string;
+    };
+    success: boolean;
+    output?: unknown;
+    error?: unknown;
+};
 interface TelemetryIntegration {
     onStart?: Listener<any>;
     onStepStart?: Listener<any>;
@@ -381,6 +476,7 @@ interface TelemetryIntegration {
     onEmbedEnd?: Listener<any>;
     onFinish?: Listener<any>;
     onEnd?: Listener<any>;
+    onAbort?: Listener<any>;
     onError?: Listener<any>;
     executeTool?: <T>(params: {
         callId: string;
@@ -441,6 +537,10 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
      */
     private readonly priorParentContexts;
     constructor(opts: RaindropTelemetryIntegrationOptions);
+    /** Flush any buffered events and trace spans to their destinations. */
+    flush: () => Promise<void>;
+    /** Flush and stop the background flush timers. */
+    shutdown: () => Promise<void>;
     private getState;
     private cleanup;
     private spanParentRef;
@@ -456,9 +556,9 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
     private toolExecutionStart;
     private toolExecutionEnd;
     onToolExecutionStart: (event: any) => void;
-    onToolExecutionEnd: (event: any) => void;
+    onToolExecutionEnd: (event: ToolExecutionEndEvent) => void;
     onToolCallStart: (event: any) => void;
-    onToolCallFinish: (event: any) => void;
+    onToolCallFinish: (event: ToolExecutionEndEvent) => void;
     onLanguageModelCallStart: (_event: any) => void;
     onLanguageModelCallEnd: (_event: any) => void;
     onChunk: (event: any) => void;
@@ -470,8 +570,15 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
     onFinish: (event: any) => void;
     onEnd: (event: any) => void;
     private finishGenerate;
+    /**
+     * Patch the Raindrop event for a completed, aborted, or errored text
+     * generation so it leaves the `isPending` state. Shared by `onFinish`/`onEnd`,
+     * `onAbort`, and `onError`.
+     */
+    private finalizeGenerateEvent;
     private finishEmbed;
     onError: (error: unknown) => void;
+    onAbort: (event: any) => void;
     executeTool: <T>({ callId, toolCallId, execute, }: {
         callId: string;
         toolCallId: string;
@@ -484,6 +591,33 @@ type IdentifyInput = {
     traits?: Record<string, unknown>;
 };
 
+declare const TRUNCATION_MARKER = "...[truncated by raindrop]";
+declare const DEFAULT_MAX_TEXT_FIELD_CHARS = 1000000;
+/**
+ * Cap a raw text field BEFORE it is buffered or attached to a span.
+ *
+ * The length check is O(1), so multi-MB strings cost nothing on the caller
+ * beyond the slice that keeps the first `limit` chars. Non-string values
+ * (including `undefined`) pass through untouched.
+ */
+declare function capText(value: string, limit?: number): string;
+declare function capText(value: string | undefined, limit?: number): string | undefined;
+/**
+ * JSON-serialize `value` with a hard output budget.
+ *
+ * Unlike serialize-then-truncate, the cost here is proportional to the
+ * limit, not the payload: the value is pruned by `boundedClone` first, so a
+ * multi-MB tool result can never burn seconds of CPU on the calling thread
+ * (which is typically the host app's event loop). Matching the previous
+ * `safeJson` semantics, returns `undefined` when the value cannot be
+ * serialized (e.g. BigInt leaves) — and, like any display truncation, a
+ * truncated result may not be valid JSON.
+ *
+ * Small payloads (within the budget) serialize exactly like
+ * `JSON.stringify`, except `Uint8Array` values become base64 strings.
+ */
+declare function boundedStringify(value: unknown, limit?: number): string | undefined;
+
 type RaindropCallMetadata = {
     userId?: string;
     eventId?: string;
@@ -824,6 +958,17 @@ type RaindropAISDKOptions = {
         partialFlushMs?: number;
         debug?: boolean;
     };
+    /**
+     * Per-field character cap applied to ai input/output text and serialized
+     * tool/LLM span payloads BEFORE (or during) serialization, so oversized
+     * payloads cost the cap — not the payload — on the calling thread.
+     * Truncated values end with `...[truncated by raindrop]` and never exceed
+     * the cap. A stricter `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is
+     * honored. Applies module-wide: the last `createRaindropAISDK` call that
+     * sets this option wins; omitting it leaves the current cap unchanged.
+     * Defaults to 1,000,000.
+     */
+    maxTextFieldChars?: number;
 };
 type RaindropAISDKContext = {
     userId?: string;
@@ -1102,5 +1247,53 @@ type RaindropAISDKClient = {
     shutdown(): Promise<void>;
 };
 declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
+/**
+ * Options for the {@link raindrop} telemetry-integration factory. A superset of
+ * {@link RaindropAISDKOptions} plus the per-integration `context` defaults and
+ * `subagentWrapping` toggle accepted by `createTelemetryIntegration()`.
+ */
+type RaindropTelemetryOptions = RaindropAISDKOptions & {
+    /** Default Raindrop context (userId/eventName/convoId/properties) applied to every call. */
+    context?: RaindropTelemetryIntegrationOptions["context"];
+    /**
+     * Wrap sub-agent generations (a `generateText`/`streamText` invoked from
+     * inside a tool's `execute`) in a synthetic tool span so parent and child
+     * spans nest correctly. Enabled by default.
+     */
+    subagentWrapping?: boolean;
+};
+/**
+ * One-line factory for the AI SDK v7 `registerTelemetry` DX.
+ *
+ * Returns a {@link RaindropTelemetryIntegration} wired to Raindrop's trace +
+ * event shippers, ready to hand to the AI SDK's `registerTelemetry`. The
+ * `writeKey` defaults to the `RAINDROP_WRITE_KEY` environment variable.
+ *
+ * @example
+ * ```ts
+ * import { generateText, registerTelemetry } from "ai";
+ * import { OpenTelemetry } from "@ai-sdk/otel";
+ * import { raindrop } from "@raindrop-ai/ai-sdk";
+ *
+ * registerTelemetry(new OpenTelemetry(), raindrop());
+ *
+ * await generateText({
+ *   model: anthropic("claude-sonnet-4-5"),
+ *   prompt: "what is the weather in Tokyo?",
+ *   telemetry: { functionId: "weather-agent" },
+ * });
+ * ```
+ *
+ * The returned integration also exposes `flush()` / `shutdown()` for
+ * short-lived scripts that need to drain buffered telemetry before exiting:
+ *
+ * ```ts
+ * const rd = raindrop();
+ * registerTelemetry(rd);
+ * // ...
+ * await rd.flush();
+ * ```
+ */
+declare function raindrop(options?: RaindropTelemetryOptions): RaindropTelemetryIntegration;
 
-export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type OtlpAnyValue, type OtlpSpan, type ParentToolContext, REDACTED_PLACEHOLDER, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type SelfDiagnosticsTool, type SelfDiagnosticsToolInput, type SelfDiagnosticsToolOptions, type SelfDiagnosticsToolResult, type StartSpanArgs, type TraceSpan, type TransformSpanHook, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetParentToolContextStorage, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, clearParentToolContext, createRaindropAISDK, currentSpan, defaultTransformSpan, enterParentToolContext, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentParentToolContext, getCurrentRaindropCallMetadata, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, runWithParentToolContext, runWithRaindropCallMetadata, withCurrent };
+export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, DEFAULT_MAX_TEXT_FIELD_CHARS, DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type OtlpAnyValue, type OtlpSpan, type ParentToolContext, REDACTED_PLACEHOLDER, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type RaindropTelemetryOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type SelfDiagnosticsTool, type SelfDiagnosticsToolInput, type SelfDiagnosticsToolOptions, type SelfDiagnosticsToolResult, type StartSpanArgs, TRUNCATION_MARKER, type TraceSpan, type TransformSpanHook, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetParentToolContextStorage, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, boundedStringify, capText, clearParentToolContext, createRaindropAISDK, currentSpan, defaultTransformSpan, enterParentToolContext, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentParentToolContext, getCurrentRaindropCallMetadata, raindrop, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, runWithParentToolContext, runWithRaindropCallMetadata, withCurrent };

package/dist/index.browser.d.ts

@@ -35,7 +35,6 @@ type SpanIds = {
     spanIdB64: string;
     parentSpanIdB64?: string;
 };
-
 type Attachment$1 = {
     type: string;
     role: string;
@@ -84,6 +83,14 @@ type EventShipperOptions = {
      * Pass `null` to opt out of all mirroring (including auto-detect).
      */
     localDebuggerUrl?: string | null;
+    /**
+     * Per-field character cap applied to event input/output BEFORE buffering
+     * or serialization, so oversized payloads cost the cap — not the payload —
+     * on the calling code path. Truncated fields end with
+     * `...[truncated by raindrop]` and never exceed the cap, marker included.
+     * Defaults to 1,000,000 (matching the Python SDK).
+     */
+    maxTextFieldChars?: number;
 };
 declare class EventShipper$1 {
     private baseUrl;
@@ -99,11 +106,39 @@ declare class EventShipper$1 {
     private sticky;
     private timers;
     private inFlight;
+    private maxTextFieldCharsOpt;
+    /**
+     * Epoch ms deadline while `shutdown()` is draining; undefined otherwise.
+     * Checked before every POST issued during the final flush.
+     */
+    private shutdownDeadlineAt;
+    /**
+     * Set once `shutdown()` 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;
     /** URL of the local debugger / Workshop daemon, when one is reachable. */
     private localDebuggerUrl;
     constructor(opts: EventShipperOptions);
     isDebugEnabled(): boolean;
     private authHeaders;
+    /**
+     * Build the retry/timeout options for one POST, honoring the shutdown
+     * deadline. Returns `null` when the shutdown drain window is exhausted —
+     * the caller must drop the payload (with a rate-limited warning) instead
+     * of issuing a request that could outlive process exit.
+     *
+     * Checked fresh on EVERY send, so a shutdown that begins while the flush
+     * path is mid-drain takes effect immediately: no further retries, and the
+     * per-attempt timeout is clamped to the remaining window. After
+     * `shutdown()` returns (deadline cleared, `hasShutdown` still set),
+     * sends — late callers, or flush work the deadline abandoned mid-drain —
+     * run as a single short attempt rather than regaining the full retry
+     * schedule.
+     */
+    private requestOpts;
     patch(eventId: string, patch: Patch): Promise<void>;
     finish(eventId: string, patch: {
         output?: string;
@@ -115,6 +150,7 @@ declare class EventShipper$1 {
     shutdown(): Promise<void>;
     trackSignal(signal: SignalInput): Promise<void>;
     identify(users: IdentifyInput$1 | IdentifyInput$1[]): Promise<void>;
+    private warnShutdownDrop;
     private flushOne;
 }
 
@@ -252,6 +288,15 @@ type TraceShipperOptions = {
      * still want some redaction in that case.
      */
     disableDefaultRedaction?: boolean;
+    /**
+     * Per-attribute character cap applied to every span attribute string value
+     * right before the span enters a ship path, so a multi-MB prompt/tool
+     * payload can never make the batch `JSON.stringify` (which runs on the
+     * event loop) cost seconds. Truncated values end with
+     * `...[truncated by raindrop]` and never exceed the cap, marker included.
+     * Defaults to 1,000,000 (matching the Python SDK).
+     */
+    maxTextFieldChars?: number;
 };
 declare class TraceShipper$1 {
     private baseUrl;
@@ -273,7 +318,32 @@ declare class TraceShipper$1 {
     private localDebuggerUrl;
     private transformSpanHook;
     private disableDefaultRedaction;
+    private maxTextFieldCharsOpt;
+    /**
+     * Epoch ms deadline while `shutdown()` is draining; undefined otherwise.
+     * Checked before every batch POST issued during the final flush.
+     */
+    private shutdownDeadlineAt;
+    /**
+     * Set once `shutdown()` 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;
     constructor(opts: TraceShipperOptions);
+    /**
+     * Cap every string attribute value on the span. O(#attributes) length
+     * checks; only oversized values pay a slice. Runs AFTER the redaction
+     * pipeline so the default secret-scrub still sees parseable JSON in
+     * `ai.request.providerOptions` / `ai.response.providerMetadata` (capping
+     * first could cut a JSON blob mid-way, fail the parse, and ship secrets
+     * in the surviving prefix).
+     *
+     * A stricter `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is honored
+     * for span content, matching the Python SDK and the OTel SDK convention.
+     */
+    private capSpanAttributes;
     /**
      * Apply the user `transformSpan` hook (if any) followed by the default
      * redactor (unless disabled). Returns either the (possibly new) span to
@@ -323,6 +393,8 @@ declare class TraceShipper$1 {
     }): void;
     enqueue(span: OtlpSpan): void;
     flush(): Promise<void>;
+    /** See EventShipper.requestOpts — same shutdown-budget semantics. */
+    private requestOpts;
     shutdown(): Promise<void>;
 }
 
@@ -365,6 +437,29 @@ declare class TraceShipper extends TraceShipper$1 {
 }
 
 type Listener<T> = (event: T) => PromiseLike<void> | void;
+type ToolExecutionEndEvent = {
+    callId: string;
+    toolCall: {
+        toolCallId: string;
+        toolName: string;
+    };
+    toolOutput: {
+        type: "tool-result";
+        output: unknown;
+    } | {
+        type: "tool-error";
+        error: unknown;
+    };
+} | {
+    callId: string;
+    toolCall: {
+        toolCallId: string;
+        toolName: string;
+    };
+    success: boolean;
+    output?: unknown;
+    error?: unknown;
+};
 interface TelemetryIntegration {
     onStart?: Listener<any>;
     onStepStart?: Listener<any>;
@@ -381,6 +476,7 @@ interface TelemetryIntegration {
     onEmbedEnd?: Listener<any>;
     onFinish?: Listener<any>;
     onEnd?: Listener<any>;
+    onAbort?: Listener<any>;
     onError?: Listener<any>;
     executeTool?: <T>(params: {
         callId: string;
@@ -441,6 +537,10 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
      */
     private readonly priorParentContexts;
     constructor(opts: RaindropTelemetryIntegrationOptions);
+    /** Flush any buffered events and trace spans to their destinations. */
+    flush: () => Promise<void>;
+    /** Flush and stop the background flush timers. */
+    shutdown: () => Promise<void>;
     private getState;
     private cleanup;
     private spanParentRef;
@@ -456,9 +556,9 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
     private toolExecutionStart;
     private toolExecutionEnd;
     onToolExecutionStart: (event: any) => void;
-    onToolExecutionEnd: (event: any) => void;
+    onToolExecutionEnd: (event: ToolExecutionEndEvent) => void;
     onToolCallStart: (event: any) => void;
-    onToolCallFinish: (event: any) => void;
+    onToolCallFinish: (event: ToolExecutionEndEvent) => void;
     onLanguageModelCallStart: (_event: any) => void;
     onLanguageModelCallEnd: (_event: any) => void;
     onChunk: (event: any) => void;
@@ -470,8 +570,15 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
     onFinish: (event: any) => void;
     onEnd: (event: any) => void;
     private finishGenerate;
+    /**
+     * Patch the Raindrop event for a completed, aborted, or errored text
+     * generation so it leaves the `isPending` state. Shared by `onFinish`/`onEnd`,
+     * `onAbort`, and `onError`.
+     */
+    private finalizeGenerateEvent;
     private finishEmbed;
     onError: (error: unknown) => void;
+    onAbort: (event: any) => void;
     executeTool: <T>({ callId, toolCallId, execute, }: {
         callId: string;
         toolCallId: string;
@@ -484,6 +591,33 @@ type IdentifyInput = {
     traits?: Record<string, unknown>;
 };
 
+declare const TRUNCATION_MARKER = "...[truncated by raindrop]";
+declare const DEFAULT_MAX_TEXT_FIELD_CHARS = 1000000;
+/**
+ * Cap a raw text field BEFORE it is buffered or attached to a span.
+ *
+ * The length check is O(1), so multi-MB strings cost nothing on the caller
+ * beyond the slice that keeps the first `limit` chars. Non-string values
+ * (including `undefined`) pass through untouched.
+ */
+declare function capText(value: string, limit?: number): string;
+declare function capText(value: string | undefined, limit?: number): string | undefined;
+/**
+ * JSON-serialize `value` with a hard output budget.
+ *
+ * Unlike serialize-then-truncate, the cost here is proportional to the
+ * limit, not the payload: the value is pruned by `boundedClone` first, so a
+ * multi-MB tool result can never burn seconds of CPU on the calling thread
+ * (which is typically the host app's event loop). Matching the previous
+ * `safeJson` semantics, returns `undefined` when the value cannot be
+ * serialized (e.g. BigInt leaves) — and, like any display truncation, a
+ * truncated result may not be valid JSON.
+ *
+ * Small payloads (within the budget) serialize exactly like
+ * `JSON.stringify`, except `Uint8Array` values become base64 strings.
+ */
+declare function boundedStringify(value: unknown, limit?: number): string | undefined;
+
 type RaindropCallMetadata = {
     userId?: string;
     eventId?: string;
@@ -824,6 +958,17 @@ type RaindropAISDKOptions = {
         partialFlushMs?: number;
         debug?: boolean;
     };
+    /**
+     * Per-field character cap applied to ai input/output text and serialized
+     * tool/LLM span payloads BEFORE (or during) serialization, so oversized
+     * payloads cost the cap — not the payload — on the calling thread.
+     * Truncated values end with `...[truncated by raindrop]` and never exceed
+     * the cap. A stricter `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is
+     * honored. Applies module-wide: the last `createRaindropAISDK` call that
+     * sets this option wins; omitting it leaves the current cap unchanged.
+     * Defaults to 1,000,000.
+     */
+    maxTextFieldChars?: number;
 };
 type RaindropAISDKContext = {
     userId?: string;
@@ -1102,5 +1247,53 @@ type RaindropAISDKClient = {
     shutdown(): Promise<void>;
 };
 declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
+/**
+ * Options for the {@link raindrop} telemetry-integration factory. A superset of
+ * {@link RaindropAISDKOptions} plus the per-integration `context` defaults and
+ * `subagentWrapping` toggle accepted by `createTelemetryIntegration()`.
+ */
+type RaindropTelemetryOptions = RaindropAISDKOptions & {
+    /** Default Raindrop context (userId/eventName/convoId/properties) applied to every call. */
+    context?: RaindropTelemetryIntegrationOptions["context"];
+    /**
+     * Wrap sub-agent generations (a `generateText`/`streamText` invoked from
+     * inside a tool's `execute`) in a synthetic tool span so parent and child
+     * spans nest correctly. Enabled by default.
+     */
+    subagentWrapping?: boolean;
+};
+/**
+ * One-line factory for the AI SDK v7 `registerTelemetry` DX.
+ *
+ * Returns a {@link RaindropTelemetryIntegration} wired to Raindrop's trace +
+ * event shippers, ready to hand to the AI SDK's `registerTelemetry`. The
+ * `writeKey` defaults to the `RAINDROP_WRITE_KEY` environment variable.
+ *
+ * @example
+ * ```ts
+ * import { generateText, registerTelemetry } from "ai";
+ * import { OpenTelemetry } from "@ai-sdk/otel";
+ * import { raindrop } from "@raindrop-ai/ai-sdk";
+ *
+ * registerTelemetry(new OpenTelemetry(), raindrop());
+ *
+ * await generateText({
+ *   model: anthropic("claude-sonnet-4-5"),
+ *   prompt: "what is the weather in Tokyo?",
+ *   telemetry: { functionId: "weather-agent" },
+ * });
+ * ```
+ *
+ * The returned integration also exposes `flush()` / `shutdown()` for
+ * short-lived scripts that need to drain buffered telemetry before exiting:
+ *
+ * ```ts
+ * const rd = raindrop();
+ * registerTelemetry(rd);
+ * // ...
+ * await rd.flush();
+ * ```
+ */
+declare function raindrop(options?: RaindropTelemetryOptions): RaindropTelemetryIntegration;
 
-export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type OtlpAnyValue, type OtlpSpan, type ParentToolContext, REDACTED_PLACEHOLDER, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type SelfDiagnosticsTool, type SelfDiagnosticsToolInput, type SelfDiagnosticsToolOptions, type SelfDiagnosticsToolResult, type StartSpanArgs, type TraceSpan, type TransformSpanHook, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetParentToolContextStorage, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, clearParentToolContext, createRaindropAISDK, currentSpan, defaultTransformSpan, enterParentToolContext, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentParentToolContext, getCurrentRaindropCallMetadata, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, runWithParentToolContext, runWithRaindropCallMetadata, withCurrent };
+export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, DEFAULT_MAX_TEXT_FIELD_CHARS, DEFAULT_REDACT_ATTRIBUTE_KEYS, DEFAULT_SECRET_KEY_NAMES, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type OtlpAnyValue, type OtlpSpan, type ParentToolContext, REDACTED_PLACEHOLDER, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type RaindropTelemetryOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type SelfDiagnosticsTool, type SelfDiagnosticsToolInput, type SelfDiagnosticsToolOptions, type SelfDiagnosticsToolResult, type StartSpanArgs, TRUNCATION_MARKER, type TraceSpan, type TransformSpanHook, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetParentToolContextStorage, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, boundedStringify, capText, clearParentToolContext, createRaindropAISDK, currentSpan, defaultTransformSpan, enterParentToolContext, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentParentToolContext, getCurrentRaindropCallMetadata, raindrop, readRaindropCallMetadataFromArgs, redactJsonAttributeValue, redactSecretsInObject, runWithParentToolContext, runWithRaindropCallMetadata, withCurrent };