raindrop-ai 0.0.83 → 0.0.84

package/dist/{chunk-CYYFVRZF.mjs → chunk-UEKYAG7S.mjs}

@@ -1,7 +1,7 @@
 // package.json
 var package_default = {
   name: "raindrop-ai",
-  version: "0.0.83",
+  version: "0.0.84",
   main: "dist/index.js",
   module: "dist/index.mjs",
   types: "dist/index.d.ts",
@@ -34,7 +34,15 @@ var package_default = {
     clean: "rm -rf .turbo && rm -rf dist",
     try: "tsx ./src/example/index.ts",
     test: "vitest run",
-    smoke: "tsx ./scripts/smoke.ts"
+    smoke: "tsx ./scripts/smoke.ts",
+    "smoke:ai-sdk-self-diagnostics": "tsx ./scripts/smoke.ai-sdk-self-diagnostics.ts",
+    "smoke:self-diagnostics:v4": "yarn build && cd tests/v4 && yarn install && yarn smoke",
+    "smoke:self-diagnostics:v5": "yarn build && cd tests/v5 && yarn install && yarn smoke",
+    "smoke:self-diagnostics:v6": "yarn build && cd tests/v6 && yarn install && yarn smoke",
+    "smoke:self-diagnostics:ai-sdk:all": "yarn smoke:self-diagnostics:v4 && yarn smoke:self-diagnostics:v5 && yarn smoke:self-diagnostics:v6",
+    "smoke:self-diagnostics:openai-sdk": "yarn build && cd tests/openai && yarn install && yarn smoke",
+    "smoke:self-diagnostics:anthropic-sdk": "yarn build && cd tests/anthropic && yarn install && yarn smoke",
+    "smoke:self-diagnostics:all": "yarn smoke:self-diagnostics:ai-sdk:all && yarn smoke:self-diagnostics:openai-sdk && yarn smoke:self-diagnostics:anthropic-sdk"
   },
   devDependencies: {
     "@types/node": "^20.11.17",
@@ -732,6 +740,9 @@ var LiveInteraction = class {
     }
     return metadata;
   }
+  getEventId() {
+    return this.context.eventId;
+  }
   finish(resultEvent) {
     var _a;
     if (this.traceId) {

package/dist/index.d.mts

@@ -58,7 +58,7 @@ type BasicSignal = {
     attachmentId?: string;
 };
 type DefaultSignal = BasicSignal & {
-    type?: "default";
+    type?: "default" | "standard";
 };
 type FeedbackSignal = BasicSignal & {
     type: "feedback";
@@ -68,7 +68,84 @@ type EditSignal = BasicSignal & {
     type: "edit";
     after?: string;
 };
-type SignalEvent = DefaultSignal | FeedbackSignal | EditSignal;
+type AgentSignal = BasicSignal & {
+    type: "agent" | "agent_internal";
+};
+type SignalEvent = DefaultSignal | FeedbackSignal | EditSignal | AgentSignal;
+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.
  *
@@ -501,6 +578,10 @@ type Interaction = {
      * ```
      */
     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.
      *
@@ -738,6 +819,14 @@ declare class Raindrop {
      * @returns The interaction object.
      */
     resumeInteraction(eventId: string): Interaction;
+    /**
+     * Creates a framework-agnostic self-diagnostics tool definition.
+     *
+     * Use this when your agent framework does not support automatic tool injection.
+     * The returned object includes adapters for Vercel AI SDK, OpenAI function tools,
+     * and Anthropic tool definitions.
+     */
+    createSelfDiagnosticsTool(options?: SelfDiagnosticsToolOptions): SelfDiagnosticsTool;
     /**
      * Track AI events. In addiiton to normal event properties, you can provide an "input", "output", or "model" parameter.
      * It takes an AiTrackEvent as input and sends it to the /track-ai endpoint of the raindrop api.
@@ -795,4 +884,4 @@ declare class Raindrop {
     close(): Promise<void>;
 }
 
-export { type AiTrackEvent, type Attachment, type AttachmentType, type BeginInteractionOptions, type FinishInteractionOptions, type IdentifyEvent, type Interaction, MAX_INGEST_SIZE_BYTES, type PartialAiTrackEvent, Raindrop, type RaindropSpanProcessor, type SignalEvent, type SpanParams, type ToolParams, type ToolSpan, type TraceContext, type Tracer, type TrackToolParams, type WorkflowParams, Raindrop as default };
+export { type AiTrackEvent, type Attachment, type AttachmentType, type BeginInteractionOptions, type FinishInteractionOptions, type IdentifyEvent, type Interaction, MAX_INGEST_SIZE_BYTES, type PartialAiTrackEvent, Raindrop, type RaindropSpanProcessor, type SelfDiagnosticsExecuteContext, type SelfDiagnosticsExecuteResult, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type SelfDiagnosticsTool, type SelfDiagnosticsToolInputSchema, type SelfDiagnosticsToolOptions, type SignalEvent, type SpanParams, type ToolParams, type ToolSpan, type TraceContext, type Tracer, type TrackToolParams, type WorkflowParams, Raindrop as default };

package/dist/index.d.ts

@@ -58,7 +58,7 @@ type BasicSignal = {
     attachmentId?: string;
 };
 type DefaultSignal = BasicSignal & {
-    type?: "default";
+    type?: "default" | "standard";
 };
 type FeedbackSignal = BasicSignal & {
     type: "feedback";
@@ -68,7 +68,84 @@ type EditSignal = BasicSignal & {
     type: "edit";
     after?: string;
 };
-type SignalEvent = DefaultSignal | FeedbackSignal | EditSignal;
+type AgentSignal = BasicSignal & {
+    type: "agent" | "agent_internal";
+};
+type SignalEvent = DefaultSignal | FeedbackSignal | EditSignal | AgentSignal;
+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.
  *
@@ -501,6 +578,10 @@ type Interaction = {
      * ```
      */
     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.
      *
@@ -738,6 +819,14 @@ declare class Raindrop {
      * @returns The interaction object.
      */
     resumeInteraction(eventId: string): Interaction;
+    /**
+     * Creates a framework-agnostic self-diagnostics tool definition.
+     *
+     * Use this when your agent framework does not support automatic tool injection.
+     * The returned object includes adapters for Vercel AI SDK, OpenAI function tools,
+     * and Anthropic tool definitions.
+     */
+    createSelfDiagnosticsTool(options?: SelfDiagnosticsToolOptions): SelfDiagnosticsTool;
     /**
      * Track AI events. In addiiton to normal event properties, you can provide an "input", "output", or "model" parameter.
      * It takes an AiTrackEvent as input and sends it to the /track-ai endpoint of the raindrop api.
@@ -795,4 +884,4 @@ declare class Raindrop {
     close(): Promise<void>;
 }
 
-export { type AiTrackEvent, type Attachment, type AttachmentType, type BeginInteractionOptions, type FinishInteractionOptions, type IdentifyEvent, type Interaction, MAX_INGEST_SIZE_BYTES, type PartialAiTrackEvent, Raindrop, type RaindropSpanProcessor, type SignalEvent, type SpanParams, type ToolParams, type ToolSpan, type TraceContext, type Tracer, type TrackToolParams, type WorkflowParams, Raindrop as default };
+export { type AiTrackEvent, type Attachment, type AttachmentType, type BeginInteractionOptions, type FinishInteractionOptions, type IdentifyEvent, type Interaction, MAX_INGEST_SIZE_BYTES, type PartialAiTrackEvent, Raindrop, type RaindropSpanProcessor, type SelfDiagnosticsExecuteContext, type SelfDiagnosticsExecuteResult, type SelfDiagnosticsSignalDefinition, type SelfDiagnosticsSignalDefinitions, type SelfDiagnosticsTool, type SelfDiagnosticsToolInputSchema, type SelfDiagnosticsToolOptions, type SignalEvent, type SpanParams, type ToolParams, type ToolSpan, type TraceContext, type Tracer, type TrackToolParams, type WorkflowParams, Raindrop as default };

package/dist/index.js

@@ -138,7 +138,7 @@ var CategorizationRequestSchema = import_zod.z.object({
 // package.json
 var package_default = {
   name: "raindrop-ai",
-  version: "0.0.83",
+  version: "0.0.84",
   main: "dist/index.js",
   module: "dist/index.mjs",
   types: "dist/index.d.ts",
@@ -171,7 +171,15 @@ var package_default = {
     clean: "rm -rf .turbo && rm -rf dist",
     try: "tsx ./src/example/index.ts",
     test: "vitest run",
-    smoke: "tsx ./scripts/smoke.ts"
+    smoke: "tsx ./scripts/smoke.ts",
+    "smoke:ai-sdk-self-diagnostics": "tsx ./scripts/smoke.ai-sdk-self-diagnostics.ts",
+    "smoke:self-diagnostics:v4": "yarn build && cd tests/v4 && yarn install && yarn smoke",
+    "smoke:self-diagnostics:v5": "yarn build && cd tests/v5 && yarn install && yarn smoke",
+    "smoke:self-diagnostics:v6": "yarn build && cd tests/v6 && yarn install && yarn smoke",
+    "smoke:self-diagnostics:ai-sdk:all": "yarn smoke:self-diagnostics:v4 && yarn smoke:self-diagnostics:v5 && yarn smoke:self-diagnostics:v6",
+    "smoke:self-diagnostics:openai-sdk": "yarn build && cd tests/openai && yarn install && yarn smoke",
+    "smoke:self-diagnostics:anthropic-sdk": "yarn build && cd tests/anthropic && yarn install && yarn smoke",
+    "smoke:self-diagnostics:all": "yarn smoke:self-diagnostics:ai-sdk:all && yarn smoke:self-diagnostics:openai-sdk && yarn smoke:self-diagnostics:anthropic-sdk"
   },
   devDependencies: {
     "@types/node": "^20.11.17",
@@ -955,6 +963,9 @@ var LiveInteraction = class {
     }
     return metadata;
   }
+  getEventId() {
+    return this.context.eventId;
+  }
   finish(resultEvent) {
     var _a;
     if (this.traceId) {
@@ -1405,6 +1416,111 @@ var AttachmentTypeSchema = import_zod2.z.enum(["code", "text", "image", "iframe"
 // src/index.ts
 process.env.TRACELOOP_TELEMETRY = "false";
 var MAX_INGEST_SIZE_BYTES = 1 * 1024 * 1024;
+var SELF_DIAGNOSTICS_TOOL_NAME_DEFAULT = "__raindrop_report";
+var SELF_DIAGNOSTICS_SOURCE_DEFAULT = "agent_reporting_tool";
+var SELF_DIAGNOSTICS_SIGNALS_DEFAULT = {
+  missing_context: {
+    description: "You cannot complete the task because critical information, credentials, or access is missing and the user cannot provide it. Do NOT report this for normal clarifying questions \u2014 only when you are blocked.",
+    sentiment: "NEGATIVE"
+  },
+  repeatedly_broken_tool: {
+    description: "A tool has failed on multiple distinct attempts in this conversation, preventing task completion. You are sure the tool exists, and you have tried to use it, but it has failed. A single tool error is NOT enough \u2014 the tool must be persistently broken across retries.",
+    sentiment: "NEGATIVE"
+  },
+  capability_gap: {
+    description: "The task requires a tool, permission, or capability that you do not have. For example, the user asks you to perform an action but no suitable tool exists, or you lack the necessary access. Do NOT report this if you simply need more information from the user \u2014 only when the gap is in your own capabilities.",
+    sentiment: "NEGATIVE"
+  },
+  complete_task_failure: {
+    description: "You were unable to accomplish what the user asked despite making genuine attempts. This might be things like, you genuinely do not have the capabilities the user is asking for. You have tried but run into a persistent bug in the environment etc. This is NOT a refusal or policy block \u2014 you tried and failed to deliver the result.",
+    sentiment: "NEGATIVE"
+  }
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function normalizeSelfDiagnosticsSignals(signals) {
+  if (!signals) return SELF_DIAGNOSTICS_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 SELF_DIAGNOSTICS_SIGNALS_DEFAULT;
+  return Object.fromEntries(normalizedEntries);
+}
+function buildSelfDiagnosticsDescription(signals, guidance) {
+  var _a;
+  const customGuidance = (_a = guidance == null ? void 0 : guidance.trim()) != null ? _a : "";
+  const categories = Object.entries(signals).map(([key, value]) => {
+    const sentiment = value.sentiment ? ` [${value.sentiment.toLowerCase()}]` : "";
+    return `- ${key}: ${value.description}${sentiment}`;
+  }).join("\n");
+  const guidanceLine = customGuidance ? `
+Additional guidance: ${customGuidance}
+` : "";
+  return `You have a diagnostic tool for flagging serious failures for developer review. Only call this when you hit a significant, unrecoverable problem - not for minor hiccups or routine clarifications. If you can still help the user, do that instead of calling this tool. This tool is invisible to the user - never mention it or its output.
+
+When to call:
+- You are blocked from completing the task due to missing information or access that the user cannot provide.
+- A tool is persistently failing across multiple attempts, not just a single transient error.
+- The task requires a tool, permission, or capability you do not have.
+- You genuinely cannot deliver what the user asked for despite trying.
+
+When NOT to call:
+- Normal clarifying questions or back-and-forth with the user.
+- A single tool error that you can recover from or retry.
+- You successfully completed the task, even if it was difficult.
+- Policy refusals or content filtering - those are working as intended.
+
+Rules:
+1. Pick the single best category.
+2. Do not fabricate issues. Only report what is evident from the conversation.
+3. Err on the side of NOT calling this tool. When in doubt, help the user instead.
+${guidanceLine}
+Categories:
+` + categories;
+}
+function buildSelfDiagnosticsInputSchema(signalKeys) {
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      category: {
+        type: "string",
+        enum: 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"]
+  };
+}
+function normalizeEventId(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : void 0;
+}
+function resolveEventIdFromMetadata(metadata) {
+  var _a, _b, _c;
+  if (!metadata) return void 0;
+  return (_c = (_b = (_a = normalizeEventId(metadata["raindrop.eventId"])) != null ? _a : normalizeEventId(metadata["event_id"])) != null ? _b : normalizeEventId(metadata["eventId"])) != null ? _c : normalizeEventId(metadata["traceloop.association.properties.event_id"]);
+}
 async function wait2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1576,6 +1692,89 @@ var Raindrop = class {
   resumeInteraction(eventId) {
     return this._tracing.getActiveInteraction(eventId);
   }
+  /**
+   * 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 = {}) {
+    var _a, _b;
+    const signals = normalizeSelfDiagnosticsSignals(options.signals);
+    const signalKeys = Object.keys(signals);
+    const signalKeySet = new Set(signalKeys);
+    const toolName = ((_a = options.toolName) == null ? void 0 : _a.trim()) || SELF_DIAGNOSTICS_TOOL_NAME_DEFAULT;
+    const description = buildSelfDiagnosticsDescription(signals, options.guidance);
+    const inputSchema = buildSelfDiagnosticsInputSchema(signalKeys);
+    const onMissingEventId = (_b = options.onMissingEventId) != null ? _b : "warn";
+    const execute = async (rawInput, context3) => {
+      var _a2, _b2, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m;
+      const input = isRecord(rawInput) ? rawInput : void 0;
+      const fallbackCategory = (_a2 = signalKeys[0]) != null ? _a2 : "unknown";
+      const categoryCandidate = normalizeEventId(input == null ? void 0 : input["category"]);
+      const category = categoryCandidate && signalKeySet.has(categoryCandidate) ? categoryCandidate : fallbackCategory;
+      const detail = (_b2 = normalizeEventId(input == null ? void 0 : input["detail"])) != null ? _b2 : "";
+      const eventId = (_l = (_k = (_i = (_g = (_f = (_e = (_d = normalizeEventId(context3 == null ? void 0 : context3.eventId)) != null ? _d : (_c = context3 == null ? void 0 : context3.interaction) == null ? void 0 : _c.getEventId()) != null ? _e : resolveEventIdFromMetadata(context3 == null ? void 0 : context3.metadata)) != null ? _f : normalizeEventId(input == null ? void 0 : input["event_id"])) != null ? _g : normalizeEventId(input == null ? void 0 : input["eventId"])) != null ? _i : (_h = options.interaction) == null ? void 0 : _h.getEventId()) != null ? _k : (_j = options.getEventId) == null ? void 0 : _j.call(options)) != null ? _l : normalizeEventId(options.eventId);
+      if (!eventId) {
+        const message = "self diagnostics signal skipped: missing eventId. Pass eventId, interaction, or getEventId when creating or executing the tool.";
+        if (onMissingEventId === "throw") {
+          throw new Error(`[raindrop] ${message}`);
+        }
+        if (onMissingEventId === "warn") {
+          console.warn(`[raindrop] ${message}`);
+        }
+        return { acknowledged: false, category, reason: "missing_event_id" };
+      }
+      const signalDefinition = signals[category];
+      this.trackSignal({
+        eventId,
+        name: `self diagnostics - ${category}`,
+        type: "agent",
+        sentiment: signalDefinition == null ? void 0 : signalDefinition.sentiment,
+        properties: {
+          source: (context3 == null ? void 0 : context3.source) || options.source || SELF_DIAGNOSTICS_SOURCE_DEFAULT,
+          category,
+          signal_description: signalDefinition == null ? void 0 : signalDefinition.description,
+          ...detail ? { detail } : {},
+          ...(_m = context3 == null ? void 0 : context3.properties) != null ? _m : {}
+        }
+      });
+      return { acknowledged: true, category, eventId };
+    };
+    return {
+      name: toolName,
+      description,
+      inputSchema,
+      signalKeys,
+      execute,
+      forVercelAI() {
+        return {
+          description,
+          parameters: inputSchema,
+          inputSchema,
+          execute
+        };
+      },
+      forOpenAI() {
+        return {
+          type: "function",
+          function: {
+            name: toolName,
+            description,
+            parameters: inputSchema
+          }
+        };
+      },
+      forAnthropic() {
+        return {
+          name: toolName,
+          description,
+          input_schema: inputSchema
+        };
+      }
+    };
+  }
   /**
    * 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.

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import {
   package_default,
   tracing
-} from "./chunk-CYYFVRZF.mjs";
+} from "./chunk-UEKYAG7S.mjs";
 
 // ../schemas/src/ingest/index.ts
 import { z } from "zod";
@@ -215,6 +215,111 @@ var AttachmentTypeSchema = z2.enum(["code", "text", "image", "iframe"]);
 // src/index.ts
 process.env.TRACELOOP_TELEMETRY = "false";
 var MAX_INGEST_SIZE_BYTES = 1 * 1024 * 1024;
+var SELF_DIAGNOSTICS_TOOL_NAME_DEFAULT = "__raindrop_report";
+var SELF_DIAGNOSTICS_SOURCE_DEFAULT = "agent_reporting_tool";
+var SELF_DIAGNOSTICS_SIGNALS_DEFAULT = {
+  missing_context: {
+    description: "You cannot complete the task because critical information, credentials, or access is missing and the user cannot provide it. Do NOT report this for normal clarifying questions \u2014 only when you are blocked.",
+    sentiment: "NEGATIVE"
+  },
+  repeatedly_broken_tool: {
+    description: "A tool has failed on multiple distinct attempts in this conversation, preventing task completion. You are sure the tool exists, and you have tried to use it, but it has failed. A single tool error is NOT enough \u2014 the tool must be persistently broken across retries.",
+    sentiment: "NEGATIVE"
+  },
+  capability_gap: {
+    description: "The task requires a tool, permission, or capability that you do not have. For example, the user asks you to perform an action but no suitable tool exists, or you lack the necessary access. Do NOT report this if you simply need more information from the user \u2014 only when the gap is in your own capabilities.",
+    sentiment: "NEGATIVE"
+  },
+  complete_task_failure: {
+    description: "You were unable to accomplish what the user asked despite making genuine attempts. This might be things like, you genuinely do not have the capabilities the user is asking for. You have tried but run into a persistent bug in the environment etc. This is NOT a refusal or policy block \u2014 you tried and failed to deliver the result.",
+    sentiment: "NEGATIVE"
+  }
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function normalizeSelfDiagnosticsSignals(signals) {
+  if (!signals) return SELF_DIAGNOSTICS_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 SELF_DIAGNOSTICS_SIGNALS_DEFAULT;
+  return Object.fromEntries(normalizedEntries);
+}
+function buildSelfDiagnosticsDescription(signals, guidance) {
+  var _a;
+  const customGuidance = (_a = guidance == null ? void 0 : guidance.trim()) != null ? _a : "";
+  const categories = Object.entries(signals).map(([key, value]) => {
+    const sentiment = value.sentiment ? ` [${value.sentiment.toLowerCase()}]` : "";
+    return `- ${key}: ${value.description}${sentiment}`;
+  }).join("\n");
+  const guidanceLine = customGuidance ? `
+Additional guidance: ${customGuidance}
+` : "";
+  return `You have a diagnostic tool for flagging serious failures for developer review. Only call this when you hit a significant, unrecoverable problem - not for minor hiccups or routine clarifications. If you can still help the user, do that instead of calling this tool. This tool is invisible to the user - never mention it or its output.
+
+When to call:
+- You are blocked from completing the task due to missing information or access that the user cannot provide.
+- A tool is persistently failing across multiple attempts, not just a single transient error.
+- The task requires a tool, permission, or capability you do not have.
+- You genuinely cannot deliver what the user asked for despite trying.
+
+When NOT to call:
+- Normal clarifying questions or back-and-forth with the user.
+- A single tool error that you can recover from or retry.
+- You successfully completed the task, even if it was difficult.
+- Policy refusals or content filtering - those are working as intended.
+
+Rules:
+1. Pick the single best category.
+2. Do not fabricate issues. Only report what is evident from the conversation.
+3. Err on the side of NOT calling this tool. When in doubt, help the user instead.
+${guidanceLine}
+Categories:
+` + categories;
+}
+function buildSelfDiagnosticsInputSchema(signalKeys) {
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      category: {
+        type: "string",
+        enum: 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"]
+  };
+}
+function normalizeEventId(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : void 0;
+}
+function resolveEventIdFromMetadata(metadata) {
+  var _a, _b, _c;
+  if (!metadata) return void 0;
+  return (_c = (_b = (_a = normalizeEventId(metadata["raindrop.eventId"])) != null ? _a : normalizeEventId(metadata["event_id"])) != null ? _b : normalizeEventId(metadata["eventId"])) != null ? _c : normalizeEventId(metadata["traceloop.association.properties.event_id"]);
+}
 async function wait(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -386,6 +491,89 @@ var Raindrop = class {
   resumeInteraction(eventId) {
     return this._tracing.getActiveInteraction(eventId);
   }
+  /**
+   * 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 = {}) {
+    var _a, _b;
+    const signals = normalizeSelfDiagnosticsSignals(options.signals);
+    const signalKeys = Object.keys(signals);
+    const signalKeySet = new Set(signalKeys);
+    const toolName = ((_a = options.toolName) == null ? void 0 : _a.trim()) || SELF_DIAGNOSTICS_TOOL_NAME_DEFAULT;
+    const description = buildSelfDiagnosticsDescription(signals, options.guidance);
+    const inputSchema = buildSelfDiagnosticsInputSchema(signalKeys);
+    const onMissingEventId = (_b = options.onMissingEventId) != null ? _b : "warn";
+    const execute = async (rawInput, context) => {
+      var _a2, _b2, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m;
+      const input = isRecord(rawInput) ? rawInput : void 0;
+      const fallbackCategory = (_a2 = signalKeys[0]) != null ? _a2 : "unknown";
+      const categoryCandidate = normalizeEventId(input == null ? void 0 : input["category"]);
+      const category = categoryCandidate && signalKeySet.has(categoryCandidate) ? categoryCandidate : fallbackCategory;
+      const detail = (_b2 = normalizeEventId(input == null ? void 0 : input["detail"])) != null ? _b2 : "";
+      const eventId = (_l = (_k = (_i = (_g = (_f = (_e = (_d = normalizeEventId(context == null ? void 0 : context.eventId)) != null ? _d : (_c = context == null ? void 0 : context.interaction) == null ? void 0 : _c.getEventId()) != null ? _e : resolveEventIdFromMetadata(context == null ? void 0 : context.metadata)) != null ? _f : normalizeEventId(input == null ? void 0 : input["event_id"])) != null ? _g : normalizeEventId(input == null ? void 0 : input["eventId"])) != null ? _i : (_h = options.interaction) == null ? void 0 : _h.getEventId()) != null ? _k : (_j = options.getEventId) == null ? void 0 : _j.call(options)) != null ? _l : normalizeEventId(options.eventId);
+      if (!eventId) {
+        const message = "self diagnostics signal skipped: missing eventId. Pass eventId, interaction, or getEventId when creating or executing the tool.";
+        if (onMissingEventId === "throw") {
+          throw new Error(`[raindrop] ${message}`);
+        }
+        if (onMissingEventId === "warn") {
+          console.warn(`[raindrop] ${message}`);
+        }
+        return { acknowledged: false, category, reason: "missing_event_id" };
+      }
+      const signalDefinition = signals[category];
+      this.trackSignal({
+        eventId,
+        name: `self diagnostics - ${category}`,
+        type: "agent",
+        sentiment: signalDefinition == null ? void 0 : signalDefinition.sentiment,
+        properties: {
+          source: (context == null ? void 0 : context.source) || options.source || SELF_DIAGNOSTICS_SOURCE_DEFAULT,
+          category,
+          signal_description: signalDefinition == null ? void 0 : signalDefinition.description,
+          ...detail ? { detail } : {},
+          ...(_m = context == null ? void 0 : context.properties) != null ? _m : {}
+        }
+      });
+      return { acknowledged: true, category, eventId };
+    };
+    return {
+      name: toolName,
+      description,
+      inputSchema,
+      signalKeys,
+      execute,
+      forVercelAI() {
+        return {
+          description,
+          parameters: inputSchema,
+          inputSchema,
+          execute
+        };
+      },
+      forOpenAI() {
+        return {
+          type: "function",
+          function: {
+            name: toolName,
+            description,
+            parameters: inputSchema
+          }
+        };
+      },
+      forAnthropic() {
+        return {
+          name: toolName,
+          description,
+          input_schema: inputSchema
+        };
+      }
+    };
+  }
   /**
    * 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.

package/dist/tracing/index.js

@@ -184,7 +184,7 @@ function base64Encode(bytes) {
 // package.json
 var package_default = {
   name: "raindrop-ai",
-  version: "0.0.83",
+  version: "0.0.84",
   main: "dist/index.js",
   module: "dist/index.mjs",
   types: "dist/index.d.ts",
@@ -217,7 +217,15 @@ var package_default = {
     clean: "rm -rf .turbo && rm -rf dist",
     try: "tsx ./src/example/index.ts",
     test: "vitest run",
-    smoke: "tsx ./scripts/smoke.ts"
+    smoke: "tsx ./scripts/smoke.ts",
+    "smoke:ai-sdk-self-diagnostics": "tsx ./scripts/smoke.ai-sdk-self-diagnostics.ts",
+    "smoke:self-diagnostics:v4": "yarn build && cd tests/v4 && yarn install && yarn smoke",
+    "smoke:self-diagnostics:v5": "yarn build && cd tests/v5 && yarn install && yarn smoke",
+    "smoke:self-diagnostics:v6": "yarn build && cd tests/v6 && yarn install && yarn smoke",
+    "smoke:self-diagnostics:ai-sdk:all": "yarn smoke:self-diagnostics:v4 && yarn smoke:self-diagnostics:v5 && yarn smoke:self-diagnostics:v6",
+    "smoke:self-diagnostics:openai-sdk": "yarn build && cd tests/openai && yarn install && yarn smoke",
+    "smoke:self-diagnostics:anthropic-sdk": "yarn build && cd tests/anthropic && yarn install && yarn smoke",
+    "smoke:self-diagnostics:all": "yarn smoke:self-diagnostics:ai-sdk:all && yarn smoke:self-diagnostics:openai-sdk && yarn smoke:self-diagnostics:anthropic-sdk"
   },
   devDependencies: {
     "@types/node": "^20.11.17",
@@ -766,6 +774,9 @@ var LiveInteraction = class {
     }
     return metadata;
   }
+  getEventId() {
+    return this.context.eventId;
+  }
   finish(resultEvent) {
     var _a;
     if (this.traceId) {

package/dist/tracing/index.mjs

@@ -1,6 +1,6 @@
 import {
   tracing
-} from "../chunk-CYYFVRZF.mjs";
+} from "../chunk-UEKYAG7S.mjs";
 
 // src/tracing/index.ts
 function initTracing() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "raindrop-ai",
-  "version": "0.0.83",
+  "version": "0.0.84",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -33,7 +33,15 @@
     "clean": "rm -rf .turbo && rm -rf dist",
     "try": "tsx ./src/example/index.ts",
     "test": "vitest run",
-    "smoke": "tsx ./scripts/smoke.ts"
+    "smoke": "tsx ./scripts/smoke.ts",
+    "smoke:ai-sdk-self-diagnostics": "tsx ./scripts/smoke.ai-sdk-self-diagnostics.ts",
+    "smoke:self-diagnostics:v4": "yarn build && cd tests/v4 && yarn install && yarn smoke",
+    "smoke:self-diagnostics:v5": "yarn build && cd tests/v5 && yarn install && yarn smoke",
+    "smoke:self-diagnostics:v6": "yarn build && cd tests/v6 && yarn install && yarn smoke",
+    "smoke:self-diagnostics:ai-sdk:all": "yarn smoke:self-diagnostics:v4 && yarn smoke:self-diagnostics:v5 && yarn smoke:self-diagnostics:v6",
+    "smoke:self-diagnostics:openai-sdk": "yarn build && cd tests/openai && yarn install && yarn smoke",
+    "smoke:self-diagnostics:anthropic-sdk": "yarn build && cd tests/anthropic && yarn install && yarn smoke",
+    "smoke:self-diagnostics:all": "yarn smoke:self-diagnostics:ai-sdk:all && yarn smoke:self-diagnostics:openai-sdk && yarn smoke:self-diagnostics:anthropic-sdk"
   },
   "devDependencies": {
     "@types/node": "^20.11.17",