@raindrop-ai/ai-sdk 0.0.28 → 0.0.30

package/dist/index.browser.d.ts

@@ -79,6 +79,11 @@ type EventShipperOptions = {
     libraryName?: string;
     libraryVersion?: string;
     defaultEventName?: string;
+    /**
+     * Explicit Workshop / local debugger URL. Wins over env vars + auto-detect.
+     * Pass `null` to opt out of all mirroring (including auto-detect).
+     */
+    localDebuggerUrl?: string | null;
 };
 declare class EventShipper$1 {
     private baseUrl;
@@ -94,6 +99,8 @@ declare class EventShipper$1 {
     private sticky;
     private timers;
     private inFlight;
+    /** URL of the local debugger / Workshop daemon, when one is reachable. */
+    private localDebuggerUrl;
     constructor(opts: EventShipperOptions);
     isDebugEnabled(): boolean;
     private authHeaders;
@@ -111,6 +118,82 @@ declare class EventShipper$1 {
     private flushOne;
 }
 
+/**
+ * Built-in default list of property names considered secret. Matching is
+ * case-insensitive and normalizes camelCase / snake_case / kebab-case (so
+ * `apiKey`, `api_key`, and `API-KEY` all match). When `defaultRedactAttribute`
+ * (and the recursive `redactSecretsInObject` helper) walk a value, any object
+ * key whose normalized form is in this set has its value replaced with the
+ * redaction placeholder.
+ *
+ * Names were chosen to cover the documented Vercel AI Gateway BYOK credential
+ * shapes (OpenAI / Anthropic `apiKey`, Bedrock `secretAccessKey` +
+ * `sessionToken`, Vertex `privateKey` + `privateKeyId`, etc.) plus generic
+ * secret-shaped properties common across other providers. Keys that are not
+ * by themselves secret (e.g. AWS `accessKeyId` — analogous to a username, not
+ * usable without `secretAccessKey`) are intentionally NOT in this set.
+ */
+declare const DEFAULT_SECRET_KEY_NAMES: readonly string[];
+declare const REDACTED_PLACEHOLDER = "[REDACTED]";
+/**
+ * Recursively walk `value` and replace any property whose (normalized) name
+ * matches one of `secretKeyNames` with `placeholder`. Returns a new object/
+ * array; does not mutate the input. Non-object inputs are returned untouched.
+ *
+ * Cycle-safe via a WeakSet — circular references resolve to `"[CIRCULAR]"`.
+ */
+declare function redactSecretsInObject(value: unknown, options?: {
+    secretKeyNames?: ReadonlyArray<string>;
+    placeholder?: string;
+}): unknown;
+/**
+ * Hook fired per OTLP span right before the span is shipped (to the Raindrop
+ * API and to a local debugger). Lets callers inspect, rewrite, or drop the
+ * entire span — not just individual attributes — which is more flexible than
+ * an attribute-level hook (you can rename attributes, add new ones, drop the
+ * span outright, etc.).
+ *
+ * Return values:
+ *   - `undefined` or the same span: ship the span unchanged.
+ *   - a new `OtlpSpan`: ship the returned span in place of the original.
+ *   - `null`: drop the span entirely from every ship path.
+ *
+ * The hook runs on the hot path — keep it synchronous and side-effect-free.
+ * If the hook throws, the span is dropped (fail-closed) so a buggy hook can
+ * never accidentally ship raw, un-redacted spans.
+ */
+type TransformSpanHook = (span: OtlpSpan) => OtlpSpan | null | undefined;
+/**
+ * The built-in OTLP span attributes that carry JSON-serialized user objects
+ * the SDK has no schema for (provider options, provider metadata). The
+ * default span transformer (`defaultTransformSpan`) parses, recursively
+ * scrubs secret-shaped properties, and re-serializes the value of any
+ * attribute whose key is in this set. Other attributes — including
+ * `ai.prompt.messages` and `ai.toolCall.args` — are passed through unchanged
+ * because they may legitimately contain content the caller wants logged;
+ * callers who need to scrub those should provide a custom `transformSpan`.
+ */
+declare const DEFAULT_REDACT_ATTRIBUTE_KEYS: readonly string[];
+/**
+ * Default span transformer. Walks the span's attributes; for every attribute
+ * whose key is in `DEFAULT_REDACT_ATTRIBUTE_KEYS`, parses the `stringValue`
+ * as JSON, recursively scrubs secret-shaped property names
+ * (`DEFAULT_SECRET_KEY_NAMES`), and re-serializes. Returns the same span
+ * reference when nothing changed (cheap no-op path); otherwise returns a new
+ * `OtlpSpan` with updated `attributes`.
+ */
+declare function defaultTransformSpan(span: OtlpSpan): OtlpSpan;
+/**
+ * If `key` is one of the JSON-blob attributes we redact by default and
+ * `value.stringValue` parses cleanly, return a new `OtlpAnyValue` carrying
+ * the scrubbed JSON. Otherwise return `undefined` (signal: no change).
+ *
+ * Exported because a caller's custom `transformSpan` may want to apply the
+ * same per-attribute redaction logic to additional attributes (e.g. their
+ * own provider-specific blob).
+ */
+declare function redactJsonAttributeValue(key: string, value: OtlpAnyValue): OtlpAnyValue | undefined;
+
 type InternalSpan = {
     ids: SpanIds;
     name: string;
@@ -135,6 +218,40 @@ type TraceShipperOptions = {
      * Pass `null` to opt out of all mirroring (including auto-detect).
      */
     localDebuggerUrl?: string | null;
+    /**
+     * Per-span hook that fires for every OTLP span right before the span is
+     * shipped (both to the Raindrop API and to a local debugger). Lets callers
+     * inspect, rewrite, or drop entire spans — rename attributes, add new ones,
+     * scrub additional secret-shaped values inside `ai.prompt.messages` /
+     * `ai.toolCall.args`, etc.
+     *
+     * Return values:
+     *   - `undefined` or the same span reference: ship the span unchanged.
+     *   - a new `OtlpSpan`: ship the returned span in place of the original.
+     *   - `null`: drop the span entirely from every ship path.
+     *
+     * The hook runs BEFORE the default redactor (which is the always-on floor
+     * for documented BYOK secrets). The default redactor still runs on the
+     * post-transform span unless `disableDefaultRedaction` is set, so even if
+     * a custom transform overlooks a secret-shaped attribute, the floor catches
+     * it.
+     *
+     * The hook runs on the hot path — keep it synchronous and side-effect-free.
+     * If the hook itself throws, the span is dropped (fail-closed) so a buggy
+     * hook can never accidentally ship raw, un-redacted spans.
+     */
+    transformSpan?: TransformSpanHook;
+    /**
+     * Disable the built-in default span transformer (which scrubs documented
+     * secret-shaped properties — `apiKey`, `secretAccessKey`, `privateKey`,
+     * etc. — inside `ai.request.providerOptions` and
+     * `ai.response.providerMetadata`).
+     *
+     * Default: `false` (i.e. default redaction is on). Setting this to `true`
+     * disables the floor entirely; provide a custom `transformSpan` if you
+     * still want some redaction in that case.
+     */
+    disableDefaultRedaction?: boolean;
 };
 declare class TraceShipper$1 {
     private baseUrl;
@@ -154,7 +271,24 @@ declare class TraceShipper$1 {
     private inFlight;
     /** URL of the local debugger / Workshop daemon, when one is reachable. */
     private localDebuggerUrl;
+    private transformSpanHook;
+    private disableDefaultRedaction;
     constructor(opts: TraceShipperOptions);
+    /**
+     * Apply the user `transformSpan` hook (if any) followed by the default
+     * redactor (unless disabled). Returns either the (possibly new) span to
+     * ship, or `null` to drop the span entirely.
+     *
+     * Ordering: user hook runs first so callers can rewrite the span freely
+     * (rename attrs, add new ones, scrub things the default doesn't know
+     * about). The default redactor then runs on whatever the user produced,
+     * acting as the always-on floor for documented BYOK secrets. If the user
+     * sets `disableDefaultRedaction: true`, the floor is skipped.
+     *
+     * Fail-closed: if the user hook throws, the span is dropped — a buggy
+     * hook can never accidentally ship raw, un-redacted spans.
+     */
+    private redactSpan;
     isDebugEnabled(): boolean;
     private authHeaders;
     startSpan(args: {
@@ -168,6 +302,7 @@ declare class TraceShipper$1 {
         attributes?: Array<OtlpKeyValue | undefined>;
         startTimeUnixNano?: string;
     }): InternalSpan;
+    private mirrorToLocalDebugger;
     endSpan(span: InternalSpan, extra?: {
         attributes?: InternalSpan["attributes"];
         error?: unknown;
@@ -256,6 +391,19 @@ type RaindropTelemetryIntegrationOptions = {
     eventShipper: EventShipper;
     sendTraces?: boolean;
     sendEvents?: boolean;
+    /**
+     * When `true` (default), generations started inside a tool's `execute`
+     * callback on the same async branch are wrapped in a synthetic `TOOL_CALL`
+     * + `agent.subagent` LLM marker so observability backends can render them
+     * as an agent block (and so the inner LLM's `track_partial` is suppressed).
+     *
+     * This is the right semantic for any framework that lowers sub-agents to
+     * AI SDK tools (Ash, Mastra, Claude Agent SDK, hand-rolled tool loops),
+     * not Ash-specific. Set to `false` if you have a tool whose `execute`
+     * happens to call `streamText`/`generateText` for unrelated reasons (e.g.
+     * RAG enrichment) and don't want it labelled as a sub-agent.
+     */
+    subagentWrapping?: boolean;
     debug?: boolean;
     context?: {
         userId?: string;
@@ -270,9 +418,26 @@ declare class RaindropTelemetryIntegration implements TelemetryIntegration {
     private readonly eventShipper;
     private readonly sendTraces;
     private readonly sendEvents;
+    private readonly subagentWrapping;
     private readonly debug;
     private readonly defaultContext;
     private readonly callStates;
+    /**
+     * Per-tool-call snapshot of the parent-tool ALS context taken right
+     * before `enterParentToolContext` overwrites it in `toolExecutionStart`.
+     * Kept at the integration level (rather than on `CallState`) so the
+     * snapshot survives even when the parent generation has no tracked
+     * `CallState` — e.g. the AI SDK dispatches a tool callback for a
+     * `callId` we never registered via `onStart`. Without this, the
+     * unconditional ALS enter in `toolExecutionStart` would leave
+     * `toolExecutionEnd` no way to restore the prior context, so it would
+     * clear and wipe whatever the outer scope had set.
+     *
+     * Keyed by `toolCallId` because that's the only identifier guaranteed
+     * to round-trip between `toolExecutionStart` and `toolExecutionEnd`
+     * (the `event.callId` can be the same for parallel sibling tools).
+     */
+    private readonly priorParentContexts;
     constructor(opts: RaindropTelemetryIntegrationOptions);
     private getState;
     private cleanup;
@@ -375,6 +540,92 @@ declare function readRaindropCallMetadataFromArgs(args: readonly unknown[]): Rai
 
 declare function _resetWarnedMissingUserId(): void;
 
+/**
+ * Parent tool execution context propagation.
+ *
+ * Problem
+ * ───────
+ * When a tool's `execute` callback recursively calls `streamText` /
+ * `generateText` (which is exactly how Ash lowers sub-agents, but also a
+ * common pattern in hand-rolled agent loops, Mastra, Claude Agent SDK,
+ * etc.), the inner generation's telemetry events are dispatched with no
+ * connection back to the outer tool call. The AI SDK fires `onStart` for
+ * the inner generation with its own fresh `callId`; nothing on the event
+ * tells the integration "this generation was triggered from inside tool
+ * X's execute callback."
+ *
+ * Without that linkage, observability tools have to fall back to
+ * regex-matching the prompt to guess whether a call is a sub-agent
+ * dispatch — fragile, framework-specific, and easily spoofable by user
+ * input.
+ *
+ * Solution
+ * ────────
+ * We maintain an `AsyncLocalStorage` slot that holds the currently-active
+ * parent tool call. The integration's `onToolExecutionStart` enters the
+ * slot before the AI SDK awaits `tool.execute(...)`; the inner
+ * generation's `onStart` reads from the slot to recover parent linkage.
+ * `onToolExecutionEnd` clears the slot so subsequent code in the same
+ * async branch doesn't see stale state.
+ *
+ * Async-context scoping
+ * ─────────────────────
+ * `enterWith` modifies the *current* async context, which propagates
+ * downward into any `await` continuation and into child async resources
+ * (including the awaited `tool.execute` and anything it calls). Sibling
+ * branches are unaffected: when the AI SDK dispatches tool calls via
+ * `Promise.all(map(async (tc) => ...))`, each map callback runs in its
+ * own async branch, so `enterWith` in one branch is invisible to the
+ * others. This is exactly the behaviour we need for parallel sub-agent
+ * dispatch.
+ *
+ * On runtimes that don't expose `AsyncLocalStorage` (browser, Cloudflare
+ * Workers without `nodejs_compat`), we fall back to a synchronous stack
+ * via `runWithParentToolContext` — see the `SyncFallbackStorage` in
+ * `call-metadata.ts` for the established pattern. `enterWith` becomes a
+ * silent no-op on the sync fallback, so async tool execution on those
+ * runtimes won't have parent linkage and the inner generation will
+ * render as a top-level call instead of being grouped under its caller.
+ */
+type ParentToolContext = {
+    /** The `callId` of the generation whose step kicked off this tool call. */
+    parentCallId: string;
+    /** The tool-call id from the parent generation's step. */
+    toolCallId: string;
+    /** The tool name the parent generation invoked. */
+    toolName: string;
+};
+/** Test helper — drop the storage so tests start from a fresh slot. */
+declare function _resetParentToolContextStorage(): void;
+/**
+ * Returns the active parent tool context, or `undefined` if no tool is
+ * currently executing in this async branch.
+ */
+declare function getCurrentParentToolContext(): ParentToolContext | undefined;
+/**
+ * Enter a parent tool context on the current async branch. Subsequent
+ * `await`-ed work (including the parent's `tool.execute` body) inherits
+ * the context until {@link clearParentToolContext} runs. No-op on
+ * runtimes without `enterWith` support (browser/edge sync fallback).
+ */
+declare function enterParentToolContext(ctx: ParentToolContext): void;
+/**
+ * Clear the parent tool context on the current async branch. Pairs with
+ * {@link enterParentToolContext}. No-op on runtimes without `enterWith`
+ * support.
+ *
+ * `enterWith(undefined)` is supported by Node's `AsyncLocalStorage` at
+ * runtime; the `as never` cast bypasses TypeScript's stricter typing on
+ * the shared global declaration (`store: T`).
+ */
+declare function clearParentToolContext(): void;
+/**
+ * Run `fn` with `ctx` bound as the parent tool context. The sync-fallback
+ * equivalent of `enter`/`clear` — useful in tests and any code path
+ * where you want strict block scoping.
+ */
+declare function runWithParentToolContext<R>(ctx: ParentToolContext, fn: () => R): R;
+
 /**
  * Options for creating event metadata for call-time context override.
  */
@@ -528,6 +779,40 @@ type RaindropAISDKOptions = {
         maxQueueSize?: number;
         debug?: boolean;
         debugSpans?: boolean;
+        /**
+         * Per-span hook that fires for every OTLP span right before it's shipped
+         * (to the Raindrop API and to a local debugger). Lets callers inspect,
+         * rewrite, or drop entire spans — rename attributes, add new ones, scrub
+         * additional secret-shaped values inside `ai.prompt.messages` /
+         * `ai.toolCall.args`, etc.
+         *
+         * Return values:
+         *   - `undefined` or the same span reference: ship the span unchanged.
+         *   - a new `OtlpSpan`: ship the returned span in place of the original.
+         *   - `null`: drop the span entirely from every ship path.
+         *
+         * The hook runs BEFORE the default redactor (the always-on floor for
+         * documented BYOK secrets — `apiKey`, `secretAccessKey`, `privateKey`,
+         * `accessToken`, etc. — inside `ai.request.providerOptions` and
+         * `ai.response.providerMetadata`). The default redactor still runs on
+         * the post-transform span unless `disableDefaultRedaction` is set.
+         *
+         * The hook runs on the hot path — keep it synchronous and
+         * side-effect-free. If the hook throws, the span is dropped (fail-closed).
+         */
+        transformSpan?: TransformSpanHook;
+        /**
+         * Disable the always-on default redactor that scrubs documented secret-
+         * shaped keys (`apiKey`, `secretAccessKey`, `privateKey`, ...) inside
+         * `ai.request.providerOptions` and `ai.response.providerMetadata`.
+         *
+         * Default: `false` (built-in redaction is on — BYOK credentials inside
+         * `providerOptions` are stripped automatically). If you set this to
+         * `true`, raw provider options will be shipped — only do this if you've
+         * verified your callers never put secrets in `providerOptions` or you've
+         * supplied your own `transformSpan` hook.
+         */
+        disableDefaultRedaction?: boolean;
     };
     events?: {
         enabled?: boolean;
@@ -691,8 +976,17 @@ type RaindropAISDKClient = {
     /**
      * Create a TelemetryIntegration instance for direct registration with AI SDK v7+.
      * Use with `registerTelemetryIntegration()` from the `ai` package.
+     *
+     * Accepts the same `context` it has always accepted, or a full options
+     * object exposing `{ context, subagentWrapping }`. Sub-agent wrapping
+     * defaults to `true`; pass `subagentWrapping: false` to opt out for
+     * consumers whose `tool.execute` happens to call `generateText` for
+     * non-agentic reasons (e.g. RAG enrichment).
      */
-    createTelemetryIntegration(context?: RaindropTelemetryIntegrationOptions["context"]): RaindropTelemetryIntegration;
+    createTelemetryIntegration(contextOrOptions?: RaindropTelemetryIntegrationOptions["context"] | {
+        context?: RaindropTelemetryIntegrationOptions["context"];
+        subagentWrapping?: boolean;
+    }): RaindropTelemetryIntegration;
     events: {
         patch(eventId: string, patch: EventPatch): Promise<void>;
         addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
@@ -764,4 +1058,4 @@ type RaindropAISDKClient = {
 };
 declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
 
-export { type AISDKChatRequestLike, type AISDKChatRequestMessageLike, type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type CreateSpanArgs, type EndSpanArgs, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type RaindropCallMetadata, RaindropTelemetryIntegration, type RaindropTelemetryIntegrationOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type StartSpanArgs, type TraceSpan, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetRaindropCallMetadataStorage, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, eventMetadata, eventMetadataFromChatRequest, getContextManager, getCurrentRaindropCallMetadata, readRaindropCallMetadataFromArgs, runWithRaindropCallMetadata, withCurrent };
+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 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 };