@raindrop-ai/ai-sdk 0.0.8 → 0.0.10

package/dist/{chunk-NFWQZOEK.mjs → chunk-ZVQRZCBO.mjs}

@@ -84,7 +84,7 @@ async function postJson(url, body, headers, opts) {
 // package.json
 var package_default = {
   name: "@raindrop-ai/ai-sdk",
-  version: "0.0.8"};
+  version: "0.0.10"};
 
 // src/internal/version.ts
 var libraryName = package_default.name;
@@ -118,13 +118,15 @@ var EventShipper = class {
     this.sticky = /* @__PURE__ */ new Map();
     this.timers = /* @__PURE__ */ new Map();
     this.inFlight = /* @__PURE__ */ new Set();
-    var _a, _b;
-    if (!opts.writeKey) throw new Error("[raindrop-ai/ai-sdk] writeKey is required");
-    this.writeKey = opts.writeKey;
-    this.baseUrl = (_a = formatEndpoint(opts.endpoint)) != null ? _a : "https://api.raindrop.ai/v1/";
+    var _a, _b, _c;
+    if (opts.enabled && !opts.writeKey) {
+      throw new Error("[raindrop-ai/ai-sdk] writeKey is required when events are enabled");
+    }
+    this.writeKey = (_a = opts.writeKey) != null ? _a : "";
+    this.baseUrl = (_b = formatEndpoint(opts.endpoint)) != null ? _b : "https://api.raindrop.ai/v1/";
     this.enabled = opts.enabled;
     this.debug = opts.debug;
-    this.partialFlushMs = (_b = opts.partialFlushMs) != null ? _b : 1e3;
+    this.partialFlushMs = (_c = opts.partialFlushMs) != null ? _c : 1e3;
     this.context = getRuntimeContext();
   }
   isDebugEnabled() {
@@ -472,16 +474,18 @@ var TraceShipper = class {
   constructor(opts) {
     this.queue = [];
     this.inFlight = /* @__PURE__ */ new Set();
-    var _a, _b, _c, _d;
-    if (!opts.writeKey) throw new Error("[raindrop-ai/ai-sdk] writeKey is required");
-    this.writeKey = opts.writeKey;
-    this.baseUrl = (_a = formatEndpoint(opts.endpoint)) != null ? _a : "https://api.raindrop.ai/v1/";
+    var _a, _b, _c, _d, _e;
+    if (opts.enabled && !opts.writeKey) {
+      throw new Error("[raindrop-ai/ai-sdk] writeKey is required when traces are enabled");
+    }
+    this.writeKey = (_a = opts.writeKey) != null ? _a : "";
+    this.baseUrl = (_b = formatEndpoint(opts.endpoint)) != null ? _b : "https://api.raindrop.ai/v1/";
     this.enabled = opts.enabled;
     this.debug = opts.debug;
     this.debugSpans = opts.debugSpans === true;
-    this.flushIntervalMs = (_b = opts.flushIntervalMs) != null ? _b : 1e3;
-    this.maxBatchSize = (_c = opts.maxBatchSize) != null ? _c : 50;
-    this.maxQueueSize = (_d = opts.maxQueueSize) != null ? _d : 5e3;
+    this.flushIntervalMs = (_c = opts.flushIntervalMs) != null ? _c : 1e3;
+    this.maxBatchSize = (_d = opts.maxBatchSize) != null ? _d : 50;
+    this.maxQueueSize = (_e = opts.maxQueueSize) != null ? _e : 5e3;
   }
   isDebugEnabled() {
     return this.debug;
@@ -1241,6 +1245,23 @@ function attrsFromGenAiRequest(options) {
 }
 
 // src/internal/wrap/wrapAISDK.ts
+var AGENT_REPORTING_TOOL_NAME_DEFAULT = "__raindrop_report";
+var AGENT_REPORTING_SIGNALS_DEFAULT = {
+  tool_failure: {
+    description: "A tool call returned an error, timed out, or produced output that cannot be used to make progress.",
+    sentiment: "NEGATIVE"
+  },
+  stuck_in_loop: {
+    description: "The same approach has been attempted multiple times without meaningful progress.",
+    sentiment: "NEGATIVE"
+  },
+  capability_gap: {
+    description: "The task requires a tool, permission, or capability that is not available to the agent."
+  }
+};
+var AGENT_REPORTING_TOOL_PREAMBLE = "IMPORTANT: Before responding to the user, scan the conversation for any issues listed in the categories below. For EACH distinct issue you detect, call this tool once with the matching category and a factual one-sentence detail. Multiple issues = multiple calls. This tool is invisible to the user \u2014 never mention it or its output.";
+var AGENT_REPORTING_NOTEWORTHY_SIGNAL_KEY = "noteworthy";
+var AGENT_REPORTING_NOTEWORTHY_DESCRIPTION = "Only when no specific category applies: flag that this turn is noteworthy for developer review.";
 var warnedMissingUserId = false;
 function warnMissingUserIdOnce() {
   if (warnedMissingUserId) return;
@@ -1252,6 +1273,14 @@ function warnMissingUserIdOnce() {
 function _resetWarnedMissingUserId() {
   warnedMissingUserId = false;
 }
+function extractRaindropCallOptions(options) {
+  if (!isRecord(options)) return {};
+  const em = options["metadata"];
+  if (isRecord(em)) return extractRaindropMetadata(em);
+  const telemetry = extractExperimentalTelemetry(options);
+  if (telemetry == null ? void 0 : telemetry.metadata) return extractRaindropMetadata(telemetry.metadata);
+  return {};
+}
 function extractRaindropMetadata(metadata) {
   if (!metadata || typeof metadata !== "object") return {};
   const result = {};
@@ -1288,6 +1317,188 @@ function mergeContexts(wrapTime, callTime) {
   }
   return result;
 }
+function normalizeSelfDiagnosticsSignals(signals) {
+  if (!signals) return AGENT_REPORTING_SIGNALS_DEFAULT;
+  const normalizedEntries = Object.entries(signals).map(([key, value]) => {
+    var _a;
+    const signalKey = key.trim();
+    if (!signalKey || !value || typeof value !== "object") return void 0;
+    const description = (_a = value.description) == null ? void 0 : _a.trim();
+    if (!description) return void 0;
+    const sentiment = value.sentiment;
+    return [
+      signalKey,
+      {
+        description,
+        ...sentiment === "POSITIVE" || sentiment === "NEGATIVE" ? { sentiment } : {}
+      }
+    ];
+  }).filter(
+    (entry) => entry !== void 0
+  );
+  if (normalizedEntries.length === 0) return AGENT_REPORTING_SIGNALS_DEFAULT;
+  return Object.fromEntries(normalizedEntries);
+}
+function normalizeSelfDiagnosticsConfig(options) {
+  var _a, _b, _c;
+  if (!(options == null ? void 0 : options.enabled)) return void 0;
+  const signalDefinitions = normalizeSelfDiagnosticsSignals(options.signals);
+  const configuredSignalKeys = Object.keys(signalDefinitions).filter(
+    (signalKey) => signalKey !== AGENT_REPORTING_NOTEWORTHY_SIGNAL_KEY
+  );
+  const signalKeys = [...configuredSignalKeys, AGENT_REPORTING_NOTEWORTHY_SIGNAL_KEY];
+  const signalDescriptions = {};
+  const signalSentiments = {};
+  for (const signalKey of signalKeys) {
+    if (signalKey === AGENT_REPORTING_NOTEWORTHY_SIGNAL_KEY) {
+      const noteworthyDefinition = signalDefinitions[AGENT_REPORTING_NOTEWORTHY_SIGNAL_KEY];
+      signalDescriptions[signalKey] = ((_a = noteworthyDefinition == null ? void 0 : noteworthyDefinition.description) == null ? void 0 : _a.trim()) || AGENT_REPORTING_NOTEWORTHY_DESCRIPTION;
+      signalSentiments[signalKey] = noteworthyDefinition == null ? void 0 : noteworthyDefinition.sentiment;
+      continue;
+    }
+    const def = signalDefinitions[signalKey];
+    if (!def) continue;
+    signalDescriptions[signalKey] = def.description;
+    signalSentiments[signalKey] = def.sentiment;
+  }
+  const customGuidanceText = ((_b = options.guidance) == null ? void 0 : _b.trim()) || "";
+  const toolName = ((_c = options.toolName) == null ? void 0 : _c.trim()) || AGENT_REPORTING_TOOL_NAME_DEFAULT;
+  const signalList = signalKeys.map((signalKey) => {
+    const sentiment = signalSentiments[signalKey];
+    const sentimentTag = sentiment ? ` [${sentiment.toLowerCase()}]` : "";
+    return `- ${signalKey}: ${signalDescriptions[signalKey]}${sentimentTag}`;
+  }).join("\n");
+  const guidanceBlock = customGuidanceText ? `
+Additional guidance: ${customGuidanceText}
+` : "";
+  const toolDescription = `${AGENT_REPORTING_TOOL_PREAMBLE}
+
+When to call:
+- The user reports something broken, failing, or not working as expected.
+- The user expresses frustration, anger, or threatens escalation.
+- You observe a product issue, billing problem, or data concern based on context.
+- The conversation reveals something unusual worth flagging for developer review.
+
+Rules:
+1. Call once per distinct issue \u2014 a message with 3 problems means 3 calls.
+2. Pick the single best category per issue. Use noteworthy only when no specific category fits.
+3. Do not fabricate issues. Only report what is evident from the conversation.
+${guidanceBlock}
+Categories:
+${signalList}`;
+  return {
+    toolName,
+    toolDescription,
+    signalKeys,
+    signalKeySet: new Set(signalKeys),
+    signalDescriptions,
+    signalSentiments
+  };
+}
+function resolveJsonSchemaFactory(aiSDK) {
+  if (!isRecord(aiSDK) || !isFunction(aiSDK["jsonSchema"])) return void 0;
+  return aiSDK["jsonSchema"];
+}
+function detectAISDKVersion(aiSDK) {
+  if (!isRecord(aiSDK)) return "unknown";
+  if (isFunction(aiSDK["jsonSchema"])) return "6";
+  if (isFunction(aiSDK["tool"])) return "5";
+  return "4";
+}
+function asVercelSchema(jsonSchemaObj) {
+  const validatorSymbol = /* @__PURE__ */ Symbol.for("vercel.ai.validator");
+  const schemaSymbol = /* @__PURE__ */ Symbol.for("vercel.ai.schema");
+  return {
+    [schemaSymbol]: true,
+    [validatorSymbol]: true,
+    _type: void 0,
+    jsonSchema: jsonSchemaObj,
+    validate: (value) => ({ success: true, value })
+  };
+}
+function createSelfDiagnosticsTool(ctx) {
+  const config = ctx.selfDiagnostics;
+  if (!config) return void 0;
+  const schema = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      category: {
+        type: "string",
+        enum: config.signalKeys,
+        description: "The single best-matching category from the list above."
+      },
+      detail: {
+        type: "string",
+        description: "One sentence of factual context: what happened and why it matters. Do not include PII or secrets."
+      }
+    },
+    required: ["category", "detail"]
+  };
+  const parameters = asVercelSchema(schema);
+  let inputSchema = parameters;
+  if (ctx.jsonSchemaFactory) {
+    try {
+      inputSchema = ctx.jsonSchemaFactory(schema);
+    } catch (e) {
+      inputSchema = parameters;
+    }
+  }
+  const execute = async (rawInput) => {
+    var _a;
+    const input = isRecord(rawInput) ? rawInput : void 0;
+    const fallbackCategory = (_a = config.signalKeys[0]) != null ? _a : "unknown";
+    const categoryCandidate = typeof (input == null ? void 0 : input["category"]) === "string" ? input["category"].trim() : void 0;
+    const category = categoryCandidate && config.signalKeySet.has(categoryCandidate) ? categoryCandidate : fallbackCategory;
+    const detail = typeof (input == null ? void 0 : input["detail"]) === "string" ? input["detail"].trim() : "";
+    const signalDescription = config.signalDescriptions[category];
+    const signalSentiment = config.signalSentiments[category];
+    if (category === AGENT_REPORTING_NOTEWORTHY_SIGNAL_KEY) {
+      void ctx.eventShipper.trackSignal({
+        eventId: ctx.eventId,
+        name: "agent:noteworthy",
+        type: "agent_internal",
+        properties: {
+          source: "agent_flag_event_tool",
+          reason: detail,
+          severity: "medium",
+          ai_sdk_version: ctx.aiSDKVersion
+        }
+      }).catch((err) => {
+        if (ctx.debug) {
+          const msg = err instanceof Error ? err.message : String(err);
+          console.warn(`[raindrop-ai/ai-sdk] agentFlagEvent signal dispatch failed: ${msg}`);
+        }
+      });
+      return { acknowledged: true, category };
+    }
+    void ctx.eventShipper.trackSignal({
+      eventId: ctx.eventId,
+      name: `agent:${category}`,
+      type: "agent",
+      sentiment: signalSentiment,
+      properties: {
+        source: "agent_reporting_tool",
+        category,
+        signal_description: signalDescription,
+        ai_sdk_version: ctx.aiSDKVersion,
+        ...detail ? { detail } : {}
+      }
+    }).catch((err) => {
+      if (ctx.debug) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.warn(`[raindrop-ai/ai-sdk] selfDiagnostics signal dispatch failed: ${msg}`);
+      }
+    });
+    return { acknowledged: true, category };
+  };
+  return {
+    description: config.toolDescription,
+    execute,
+    parameters,
+    inputSchema
+  };
+}
 function getCurrentParentSpanContextSync() {
   return getContextManager().getParentSpanIds();
 }
@@ -1417,7 +1628,18 @@ function teeStreamObjectBaseStream(result) {
 }
 function setupOperation(params) {
   var _a, _b, _c;
-  const { operation, arg, inherited, aiSDK, options, traceShipper, sendTraces } = params;
+  const {
+    operation,
+    arg,
+    inherited,
+    aiSDK,
+    options,
+    eventShipper,
+    traceShipper,
+    debug,
+    selfDiagnostics,
+    sendTraces
+  } = params;
   const wrapTimeCtx = resolveContext(options.context, { operation, args: arg });
   const telemetry = extractExperimentalTelemetry(arg);
   const callTimeCtx = extractRaindropMetadata(telemetry == null ? void 0 : telemetry.metadata);
@@ -1456,12 +1678,18 @@ function setupOperation(params) {
     ]
   }) : void 0;
   const rootParentForChildren = rootSpan ? { traceIdB64: rootSpan.ids.traceIdB64, spanIdB64: rootSpan.ids.spanIdB64 } : inheritedParent;
+  const operationSelfDiagnostics = isObjectOperation(operation) ? void 0 : selfDiagnostics;
   const wrapCtx = {
     eventId,
     telemetry,
     sendTraces,
+    debug,
+    eventShipper,
     traceShipper,
-    rootParentForChildren
+    rootParentForChildren,
+    jsonSchemaFactory: resolveJsonSchemaFactory(aiSDK),
+    selfDiagnostics: operationSelfDiagnostics,
+    aiSDKVersion: detectAISDKVersion(aiSDK)
   };
   const toolCalls = [];
   const argsWithWrappedTools = wrapTools(arg, wrapCtx, toolCalls);
@@ -1531,12 +1759,7 @@ function createFinalize(params) {
           attrInt("ai.usage.reasoningTokens", usage == null ? void 0 : usage.reasoningTokens),
           attrInt("ai.usage.cachedInputTokens", usage == null ? void 0 : usage.cachedInputTokens),
           attrInt("ai.toolCall.count", setup.toolCalls.length),
-          ...error ? [
-            attrString(
-              "error.message",
-              error instanceof Error ? error.message : String(error)
-            )
-          ] : []
+          ...error ? [attrString("error.message", error instanceof Error ? error.message : String(error))] : []
         ]
       });
     }
@@ -1571,6 +1794,7 @@ function executeStreamingOperation(params) {
     deps,
     sendEvents,
     sendTraces,
+    selfDiagnostics,
     autoAttachmentEnabled,
     debug
   } = params;
@@ -1580,7 +1804,10 @@ function executeStreamingOperation(params) {
     inherited: getCurrentParentSpanContextSync(),
     aiSDK,
     options: deps.options,
+    eventShipper: deps.eventShipper,
     traceShipper: deps.traceShipper,
+    debug,
+    selfDiagnostics,
     sendTraces
   });
   const finalize = createFinalize({
@@ -1625,6 +1852,7 @@ async function executeNonStreamingOperation(params) {
     deps,
     sendEvents,
     sendTraces,
+    selfDiagnostics,
     autoAttachmentEnabled,
     debug
   } = params;
@@ -1635,7 +1863,10 @@ async function executeNonStreamingOperation(params) {
     inherited,
     aiSDK,
     options: deps.options,
+    eventShipper: deps.eventShipper,
     traceShipper: deps.traceShipper,
+    debug,
+    selfDiagnostics,
     sendTraces
   });
   const finalize = createFinalize({
@@ -1678,13 +1909,14 @@ function wrapAISDK(aiSDK, deps) {
   const sendEvents = ((_a = deps.options.send) == null ? void 0 : _a.events) !== false;
   const sendTraces = ((_b = deps.options.send) == null ? void 0 : _b.traces) !== false;
   const autoAttachmentEnabled = deps.options.autoAttachment !== false;
+  const selfDiagnostics = normalizeSelfDiagnosticsConfig(deps.options.selfDiagnostics);
   const proxyTarget = isModuleNamespace(aiSDK) ? Object.setPrototypeOf({}, aiSDK) : aiSDK;
   return new Proxy(proxyTarget, {
     get(target, prop, receiver) {
       const original = Reflect.get(target, prop, receiver);
       if (typeof prop === "string" && agentClasses.has(prop) && isAgentClass(original)) {
         if (debug) console.log(`[raindrop-ai/ai-sdk] Wrapping Agent class: ${prop}`);
-        return wrapAgentClass(original, aiSDK, deps, debug);
+        return wrapAgentClass(original, aiSDK, deps, debug, selfDiagnostics);
       }
       if (typeof prop !== "string" || !instrumentedOps.has(prop) || !isFunction(original)) {
         return original;
@@ -1702,6 +1934,7 @@ function wrapAISDK(aiSDK, deps) {
             deps,
             sendEvents,
             sendTraces,
+            selfDiagnostics,
             autoAttachmentEnabled,
             debug
           });
@@ -1715,6 +1948,7 @@ function wrapAISDK(aiSDK, deps) {
           deps,
           sendEvents,
           sendTraces,
+          selfDiagnostics,
           autoAttachmentEnabled,
           debug
         });
@@ -1722,7 +1956,7 @@ function wrapAISDK(aiSDK, deps) {
     }
   });
 }
-function wrapAgentClass(AgentClass, aiSDK, deps, debug) {
+function wrapAgentClass(AgentClass, aiSDK, deps, debug, selfDiagnostics) {
   return new Proxy(AgentClass, {
     construct(target, args, newTarget) {
       const instance = Reflect.construct(target, args, newTarget);
@@ -1741,7 +1975,8 @@ function wrapAgentClass(AgentClass, aiSDK, deps, debug) {
               className,
               aiSDK,
               deps,
-              debug
+              debug,
+              selfDiagnostics
             );
           }
           if (prop === "stream" && isFunction(original)) {
@@ -1753,7 +1988,8 @@ function wrapAgentClass(AgentClass, aiSDK, deps, debug) {
               className,
               aiSDK,
               deps,
-              debug
+              debug,
+              selfDiagnostics
             );
           }
           return original;
@@ -1762,7 +1998,7 @@ function wrapAgentClass(AgentClass, aiSDK, deps, debug) {
     }
   });
 }
-function wrapAgentGenerate(generate, instance, agentSettings, className, aiSDK, deps, debug) {
+function wrapAgentGenerate(generate, instance, agentSettings, className, aiSDK, deps, debug, selfDiagnostics) {
   var _a, _b;
   const sendEvents = ((_a = deps.options.send) == null ? void 0 : _a.events) !== false;
   const sendTraces = ((_b = deps.options.send) == null ? void 0 : _b.traces) !== false;
@@ -1774,7 +2010,7 @@ function wrapAgentGenerate(generate, instance, agentSettings, className, aiSDK,
     const operation = `${className}.generate`;
     const wrapTimeCtx = resolveContext(deps.options.context, { operation, args: mergedArgs });
     const telemetry = extractExperimentalTelemetry(mergedArgs);
-    const callTimeCtx = extractRaindropMetadata(telemetry == null ? void 0 : telemetry.metadata);
+    const callTimeCtx = extractRaindropCallOptions(mergedArgs);
     const mergedCtx = mergeContexts(wrapTimeCtx, callTimeCtx);
     if (!mergedCtx.userId) warnMissingUserIdOnce();
     const inherited = await getCurrentParentSpanContext();
@@ -1815,8 +2051,13 @@ function wrapAgentGenerate(generate, instance, agentSettings, className, aiSDK,
       eventId,
       telemetry,
       sendTraces,
+      debug,
+      eventShipper: deps.eventShipper,
       traceShipper: deps.traceShipper,
-      rootParentForChildren
+      rootParentForChildren,
+      jsonSchemaFactory: resolveJsonSchemaFactory(aiSDK),
+      selfDiagnostics,
+      aiSDKVersion: detectAISDKVersion(aiSDK)
     };
     const toolCalls = [];
     const mergedArgsWithWrappedTools = wrapTools(mergedArgs, wrapCtx, toolCalls);
@@ -1950,7 +2191,7 @@ function wrapAgentGenerate(generate, instance, agentSettings, className, aiSDK,
     }
   };
 }
-function wrapAgentStream(stream, instance, agentSettings, className, aiSDK, deps, debug) {
+function wrapAgentStream(stream, instance, agentSettings, className, aiSDK, deps, debug, selfDiagnostics) {
   var _a, _b;
   const sendEvents = ((_a = deps.options.send) == null ? void 0 : _a.events) !== false;
   const sendTraces = ((_b = deps.options.send) == null ? void 0 : _b.traces) !== false;
@@ -1962,7 +2203,7 @@ function wrapAgentStream(stream, instance, agentSettings, className, aiSDK, deps
     const operation = `${className}.stream`;
     const wrapTimeCtx = resolveContext(deps.options.context, { operation, args: mergedArgs });
     const telemetry = extractExperimentalTelemetry(mergedArgs);
-    const callTimeCtx = extractRaindropMetadata(telemetry == null ? void 0 : telemetry.metadata);
+    const callTimeCtx = extractRaindropCallOptions(mergedArgs);
     const mergedCtx = mergeContexts(wrapTimeCtx, callTimeCtx);
     if (!mergedCtx.userId) warnMissingUserIdOnce();
     const inherited = await getCurrentParentSpanContext();
@@ -2003,8 +2244,13 @@ function wrapAgentStream(stream, instance, agentSettings, className, aiSDK, deps
       eventId,
       telemetry,
       sendTraces,
+      debug,
+      eventShipper: deps.eventShipper,
       traceShipper: deps.traceShipper,
-      rootParentForChildren
+      rootParentForChildren,
+      jsonSchemaFactory: resolveJsonSchemaFactory(aiSDK),
+      selfDiagnostics,
+      aiSDKVersion: detectAISDKVersion(aiSDK)
     };
     const toolCalls = [];
     const mergedArgsWithWrappedTools = wrapTools(mergedArgs, wrapCtx, toolCalls);
@@ -2144,8 +2390,22 @@ function wrapAgentStream(stream, instance, agentSettings, className, aiSDK, deps
   };
 }
 function wrapTools(args, ctx, toolCalls) {
-  if (!isRecord(args) || !("tools" in args) || !isRecord(args["tools"])) return args;
-  const tools = args["tools"];
+  if (!isRecord(args)) return args;
+  const tools = isRecord(args["tools"]) ? { ...args["tools"] } : {};
+  if (ctx.selfDiagnostics) {
+    const reportToolName = ctx.selfDiagnostics.toolName;
+    if (!(reportToolName in tools)) {
+      const reportTool = createSelfDiagnosticsTool(ctx);
+      if (reportTool !== void 0) {
+        tools[reportToolName] = reportTool;
+      }
+    } else if (ctx.debug) {
+      console.warn(
+        `[raindrop-ai/ai-sdk] selfDiagnostics skipped: tool name collision for "${reportToolName}"`
+      );
+    }
+  }
+  if (Object.keys(tools).length === 0) return args;
   const wrapped = {};
   for (const [name, tool] of Object.entries(tools)) {
     wrapped[name] = wrapToolExecute(name, tool, ctx, toolCalls);
@@ -2632,18 +2892,26 @@ function envDebugEnabled() {
 }
 function createRaindropAISDK(opts) {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i;
-  const eventsEnabled = ((_a = opts.events) == null ? void 0 : _a.enabled) !== false;
-  const tracesEnabled = ((_b = opts.traces) == null ? void 0 : _b.enabled) !== false;
+  const writeKey = opts.writeKey;
+  const eventsRequested = ((_a = opts.events) == null ? void 0 : _a.enabled) !== false;
+  const tracesRequested = ((_b = opts.traces) == null ? void 0 : _b.enabled) !== false;
+  const eventsEnabled = eventsRequested && !!writeKey;
+  const tracesEnabled = tracesRequested && !!writeKey;
   const envDebug = envDebugEnabled();
+  if (!writeKey && (eventsRequested || tracesRequested)) {
+    console.warn(
+      "[raindrop-ai/ai-sdk] writeKey not provided; telemetry shipping is disabled"
+    );
+  }
   const eventShipper = new EventShipper({
-    writeKey: opts.writeKey,
+    writeKey,
     endpoint: opts.endpoint,
     enabled: eventsEnabled,
     debug: ((_c = opts.events) == null ? void 0 : _c.debug) === true || envDebug,
     partialFlushMs: (_d = opts.events) == null ? void 0 : _d.partialFlushMs
   });
   const traceShipper = new TraceShipper({
-    writeKey: opts.writeKey,
+    writeKey,
     endpoint: opts.endpoint,
     enabled: tracesEnabled,
     debug: ((_e = opts.traces) == null ? void 0 : _e.debug) === true || envDebug,

package/dist/index.d.mts

@@ -127,6 +127,48 @@ type EventMetadataOptions = {
  * ```
  */
 declare function eventMetadata(options: EventMetadataOptions): Record<string, string>;
+type AgentCallMetadata = ReturnType<typeof eventMetadata>;
+type NormalizeUnknownAgentOptions<T> = T extends {
+    options: infer CallOptions;
+} ? unknown extends CallOptions ? Omit<T, "options"> & {
+    options?: never;
+} : T : T;
+/**
+ * Wraps an agent instance type so `generate()` and `stream()` accept optional
+ * Raindrop call metadata while preserving original return types.
+ */
+type AgentWithMetadata<A> = A extends {
+    generate: (...args: infer GenerateArgs) => infer GenerateReturn;
+    stream: (...args: infer StreamArgs) => infer StreamReturn;
+} ? Omit<A, "generate" | "stream"> & {
+    generate(...args: GenerateArgs extends [infer Options, ...infer Rest] ? [NormalizeUnknownAgentOptions<Options> & {
+        metadata?: AgentCallMetadata;
+    }, ...Rest] : GenerateArgs): GenerateReturn;
+    stream(...args: StreamArgs extends [infer Options, ...infer Rest] ? [NormalizeUnknownAgentOptions<Options> & {
+        metadata?: AgentCallMetadata;
+    }, ...Rest] : StreamArgs): StreamReturn;
+} : A;
+/**
+ * Structural wrapper type for AI SDK modules.
+ *
+ * - AI SDK v6: rewrites `ToolLoopAgent` constructor instance methods to accept
+ *   `metadata` on `generate/stream`.
+ * - AI SDK v4/v5: no `ToolLoopAgent` export, so the type is unchanged.
+ */
+type WrappedAISDK<T extends object> = T extends {
+    ToolLoopAgent: abstract new (...args: any[]) => any;
+} ? Omit<T, "ToolLoopAgent"> & {
+    ToolLoopAgent: new (...args: ConstructorParameters<T["ToolLoopAgent"]>) => AgentWithMetadata<InstanceType<T["ToolLoopAgent"]>>;
+} : T;
+/**
+ * Backward-compatible alias for wrapped AI SDK module types.
+ *
+ * This alias intentionally avoids referencing `import("ai")` to satisfy type
+ * resolution without requiring `ai` to be installed.
+ *
+ * Prefer `WrappedAISDK<typeof ai>` in app code when you have an `ai` import.
+ */
+type WrappedAI<T extends object = any> = WrappedAISDK<T>;
 type Attachment = {
     attachment_id?: string;
     name?: string;
@@ -139,7 +181,11 @@ type Attachment = {
     type: "text" | "image" | "iframe";
 });
 type RaindropAISDKOptions = {
-    writeKey: string;
+    /**
+     * API write key. If omitted, telemetry shipping is disabled but `wrap()` is
+     * still available for a consistent integration surface.
+     */
+    writeKey?: string;
     endpoint?: string;
     traces?: {
         enabled?: boolean;
@@ -192,6 +238,38 @@ type AISDKMessage = {
  * - at the end with appended response messages (assistant/tool, incl tool-call + tool-result parts)
  */
 type EventBuilder = (messages: AISDKMessage[]) => void | BuildEventPatch;
+type SelfDiagnosticsSignalDefinition = {
+    /**
+     * Human-readable meaning of this signal.
+     * Used in the injected tool schema and stored in signal properties.
+     */
+    description: string;
+    /**
+     * Optional default sentiment for this signal key.
+     * This can help dashboards classify negative/positive programmatic signals.
+     */
+    sentiment?: "POSITIVE" | "NEGATIVE";
+};
+type SelfDiagnosticsSignalDefinitions = Record<string, SelfDiagnosticsSignalDefinition>;
+type SelfDiagnosticsOptions = {
+    /** Enable automatic injection of the self diagnostics tool. Default: false */
+    enabled?: boolean;
+    /**
+     * Signal keys and descriptions exposed to the model.
+     * Defaults to a built-in set when omitted.
+     */
+    signals?: SelfDiagnosticsSignalDefinitions;
+    /**
+     * Optional extra guidance for when the model should emit self diagnostics.
+     * The SDK still generates a full tool prompt from `signals`.
+     */
+    guidance?: string;
+    /**
+     * Optional tool name override for the injected self diagnostics tool.
+     * Defaults to "__raindrop_report".
+     */
+    toolName?: string;
+};
 type WrapAISDKOptions = {
     context: RaindropAISDKContext | ((info: {
         operation: string;
@@ -199,6 +277,7 @@ type WrapAISDKOptions = {
     }) => RaindropAISDKContext);
     buildEvent?: EventBuilder;
     autoAttachment?: boolean;
+    selfDiagnostics?: SelfDiagnosticsOptions;
     send?: {
         events?: boolean;
         traces?: boolean;
@@ -217,7 +296,7 @@ type EventPatch = {
     timestamp?: string;
 };
 type RaindropAISDKClient = {
-    wrap<T extends object>(aiSDK: T, options?: WrapAISDKOptions): T;
+    wrap<T extends object>(aiSDK: T, options?: WrapAISDKOptions): WrappedAISDK<T>;
     events: {
         patch(eventId: string, patch: EventPatch): Promise<void>;
         addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
@@ -235,7 +314,7 @@ type RaindropAISDKClient = {
         track(signal: {
             eventId: string;
             name: "thumbs_up" | "thumbs_down" | string;
-            type?: "default" | "feedback" | "edit";
+            type?: "default" | "feedback" | "edit" | "standard" | "agent" | "agent_internal";
             sentiment?: "POSITIVE" | "NEGATIVE";
             timestamp?: string;
             properties?: Record<string, unknown>;
@@ -249,4 +328,4 @@ type RaindropAISDKClient = {
 };
 declare function createRaindropAISDK(opts: RaindropAISDKOptions): RaindropAISDKClient;
 
-export { type AISDKMessage, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type WrapAISDKOptions, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, eventMetadata, getContextManager, withCurrent };
+export { type AISDKMessage, type AgentCallMetadata, type AgentWithMetadata, type Attachment, type BuildEventPatch, ContextManager, type ContextSpan, type EventBuilder, type EventMetadataOptions, type IdentifyInput, type RaindropAISDKClient, type RaindropAISDKContext, type RaindropAISDKOptions, type SelfDiagnosticsOptions, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type WrapAISDKOptions, type WrappedAI, type WrappedAISDK, _resetWarnedMissingUserId, createRaindropAISDK, currentSpan, eventMetadata, getContextManager, withCurrent };