@raindrop-ai/deep-agents 0.0.5 → 0.1.0

package/dist/index.d.mts

@@ -60,6 +60,7 @@ type Patch = {
     output?: string;
     model?: string;
     properties?: Record<string, unknown>;
+    featureFlags?: Record<string, string>;
     attachments?: Attachment[];
     isPending?: boolean;
     timestamp?: string;
@@ -160,6 +161,7 @@ declare class EventShipper {
         output?: string;
         model?: string;
         properties?: Record<string, unknown>;
+        featureFlags?: Record<string, string>;
         userId?: string;
     }): Promise<void>;
     flush(): Promise<void>;
@@ -364,6 +366,42 @@ declare class TraceShipper {
     shutdown(): Promise<void>;
 }
 
+/**
+ * Run telemetry egress with OpenTelemetry tracing suppressed.
+ *
+ * Why this exists
+ * ---------------
+ * Raindrop integrations ship spans/events over HTTP with the global `fetch`
+ * (see {@link ../http.ts `postJson`}). When the host app also runs an OTel
+ * fetch/undici instrumentation — e.g. `@vercel/otel`'s `registerOTel`, which
+ * every Eve agent installs — that instrumentation wraps *our own* telemetry
+ * POSTs in a `fetch POST <endpoint>` span. Those spans are then handed to the
+ * very exporter that issued the request, so they get shipped right back to
+ * Raindrop and Workshop as standalone "runs" (and, because each export issues
+ * another fetch, they feed back on themselves). The result is a run list
+ * flooded with `fetch POST .../v1/traces`, `.../events/track_partial` and
+ * `.../live` entries that drown out the real agent turns — especially with
+ * sub-agents, where every sandbox runs its own instrumentation.
+ *
+ * The OTel-blessed fix is to mark the active context as "tracing suppressed"
+ * around the request; instrumentations check `isTracingSuppressed` and return
+ * a no-op span instead of recording one. We do this through a hook stashed on
+ * `globalThis` by the Node entrypoint ({@link ../index.node.ts}) so that:
+ *   - `@opentelemetry/api` / `@opentelemetry/core` stay *optional* — core never
+ *     hard-depends on them, and the hook is simply absent when they (and thus
+ *     any instrumentation to suppress) are not installed; and
+ *   - the browser bundle never pulls in `node:module`, mirroring how core
+ *     injects `AsyncLocalStorage` via `RAINDROP_ASYNC_LOCAL_STORAGE`.
+ *
+ * When no hook is present the callback runs unchanged, so suppression is a
+ * best-effort no-op rather than a hard requirement.
+ */
+/** Hook signature: run `fn` with OTel tracing suppressed, returning its value. */
+type SuppressTracingHook = <T>(fn: () => T) => T;
+declare global {
+    var RAINDROP_SUPPRESS_TRACING: SuppressTracingHook | undefined;
+}
+
 type ParentSpanContext = {
     traceIdB64: string;
     spanIdB64: string;
@@ -396,6 +434,8 @@ interface RaindropDeepAgentsHandlerOptions {
     traceShipper: TraceShipper;
     userId?: string;
     convoId?: string;
+    eventName?: string;
+    eventId?: () => string;
     traceChains?: boolean;
 }
 declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
@@ -404,6 +444,8 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     private traceShipper;
     private userId?;
     private convoId?;
+    private eventName?;
+    private eventIdSource?;
     private traceChains;
     private spans;
     private rootRunIds;
@@ -445,6 +487,18 @@ interface DeepAgentsOptions {
     debug?: boolean;
     userId?: string;
     convoId?: string;
+    /**
+     * Event name stamped on every captured event, replacing core's hardcoded
+     * `"ai_generation"` default (DEV-1167).
+     */
+    eventName?: string;
+    /**
+     * Per-call event-id source, invoked once per captured root agent invocation
+     * to mint that event's id (and the linked spans' id), replacing the
+     * handler-minted UUID (DEV-1174). A throwing/empty/absent source falls back
+     * to a random UUID, so telemetry never crashes the caller.
+     */
+    eventId?: () => string;
     /**
      * Optional Raindrop project slug. When set, every outbound cloud request
      * carries an `X-Raindrop-Project-Id` header. Unset → no header (the project

package/dist/index.d.ts

@@ -60,6 +60,7 @@ type Patch = {
     output?: string;
     model?: string;
     properties?: Record<string, unknown>;
+    featureFlags?: Record<string, string>;
     attachments?: Attachment[];
     isPending?: boolean;
     timestamp?: string;
@@ -160,6 +161,7 @@ declare class EventShipper {
         output?: string;
         model?: string;
         properties?: Record<string, unknown>;
+        featureFlags?: Record<string, string>;
         userId?: string;
     }): Promise<void>;
     flush(): Promise<void>;
@@ -364,6 +366,42 @@ declare class TraceShipper {
     shutdown(): Promise<void>;
 }
 
+/**
+ * Run telemetry egress with OpenTelemetry tracing suppressed.
+ *
+ * Why this exists
+ * ---------------
+ * Raindrop integrations ship spans/events over HTTP with the global `fetch`
+ * (see {@link ../http.ts `postJson`}). When the host app also runs an OTel
+ * fetch/undici instrumentation — e.g. `@vercel/otel`'s `registerOTel`, which
+ * every Eve agent installs — that instrumentation wraps *our own* telemetry
+ * POSTs in a `fetch POST <endpoint>` span. Those spans are then handed to the
+ * very exporter that issued the request, so they get shipped right back to
+ * Raindrop and Workshop as standalone "runs" (and, because each export issues
+ * another fetch, they feed back on themselves). The result is a run list
+ * flooded with `fetch POST .../v1/traces`, `.../events/track_partial` and
+ * `.../live` entries that drown out the real agent turns — especially with
+ * sub-agents, where every sandbox runs its own instrumentation.
+ *
+ * The OTel-blessed fix is to mark the active context as "tracing suppressed"
+ * around the request; instrumentations check `isTracingSuppressed` and return
+ * a no-op span instead of recording one. We do this through a hook stashed on
+ * `globalThis` by the Node entrypoint ({@link ../index.node.ts}) so that:
+ *   - `@opentelemetry/api` / `@opentelemetry/core` stay *optional* — core never
+ *     hard-depends on them, and the hook is simply absent when they (and thus
+ *     any instrumentation to suppress) are not installed; and
+ *   - the browser bundle never pulls in `node:module`, mirroring how core
+ *     injects `AsyncLocalStorage` via `RAINDROP_ASYNC_LOCAL_STORAGE`.
+ *
+ * When no hook is present the callback runs unchanged, so suppression is a
+ * best-effort no-op rather than a hard requirement.
+ */
+/** Hook signature: run `fn` with OTel tracing suppressed, returning its value. */
+type SuppressTracingHook = <T>(fn: () => T) => T;
+declare global {
+    var RAINDROP_SUPPRESS_TRACING: SuppressTracingHook | undefined;
+}
+
 type ParentSpanContext = {
     traceIdB64: string;
     spanIdB64: string;
@@ -396,6 +434,8 @@ interface RaindropDeepAgentsHandlerOptions {
     traceShipper: TraceShipper;
     userId?: string;
     convoId?: string;
+    eventName?: string;
+    eventId?: () => string;
     traceChains?: boolean;
 }
 declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
@@ -404,6 +444,8 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     private traceShipper;
     private userId?;
     private convoId?;
+    private eventName?;
+    private eventIdSource?;
     private traceChains;
     private spans;
     private rootRunIds;
@@ -445,6 +487,18 @@ interface DeepAgentsOptions {
     debug?: boolean;
     userId?: string;
     convoId?: string;
+    /**
+     * Event name stamped on every captured event, replacing core's hardcoded
+     * `"ai_generation"` default (DEV-1167).
+     */
+    eventName?: string;
+    /**
+     * Per-call event-id source, invoked once per captured root agent invocation
+     * to mint that event's id (and the linked spans' id), replacing the
+     * handler-minted UUID (DEV-1174). A throwing/empty/absent source falls back
+     * to a random UUID, so telemetry never crashes the caller.
+     */
+    eventId?: () => string;
     /**
      * Optional Raindrop project slug. When set, every outbound cloud request
      * carries an `X-Raindrop-Project-Id` header. Unset → no header (the project

package/dist/index.js

@@ -28,7 +28,7 @@ module.exports = __toCommonJS(index_exports);
 // src/callback-handler.ts
 var import_base = require("@langchain/core/callbacks/base");
 
-// ../core/dist/chunk-SK6EJEO7.js
+// ../core/dist/chunk-267IXHO5.js
 function getCrypto() {
   const c = globalThis.crypto;
   return c;
@@ -83,6 +83,20 @@ function base64Encode(bytes) {
   }
   return out;
 }
+function runWithTracingSuppressed(fn) {
+  const hook = globalThis.RAINDROP_SUPPRESS_TRACING;
+  if (typeof hook !== "function") return fn();
+  let started = false;
+  try {
+    return hook(() => {
+      started = true;
+      return fn();
+    });
+  } catch (err) {
+    if (started) throw err;
+    return fn();
+  }
+}
 var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
 var MAX_RETRY_DELAY_MS = 3e4;
 function wait(ms) {
@@ -193,15 +207,17 @@ async function postJson(url, body, headers, opts) {
   const timeoutMs = (_a = opts.timeoutMs) != null ? _a : DEFAULT_REQUEST_TIMEOUT_MS;
   await withRetry(
     async () => {
-      const resp = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          ...headers
-        },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(timeoutMs)
-      });
+      const resp = await runWithTracingSuppressed(
+        () => fetch(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            ...headers
+          },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(timeoutMs)
+        })
+      );
       if (!resp.ok) {
         const text = await resp.text().catch(() => "");
         const err = new Error(
@@ -402,13 +418,16 @@ function projectIdHeaders(projectId) {
 var SHUTDOWN_DEADLINE_MS = 1e4;
 var POST_SHUTDOWN_TIMEOUT_MS = 5e3;
 function mergePatches(target, source) {
-  var _a, _b, _c, _d;
+  var _a, _b, _c, _d, _e, _f;
   const out = { ...target, ...source };
   if (target.properties || source.properties) {
     out.properties = { ...(_a = target.properties) != null ? _a : {}, ...(_b = source.properties) != null ? _b : {} };
   }
+  if (target.featureFlags || source.featureFlags) {
+    out.featureFlags = { ...(_c = target.featureFlags) != null ? _c : {}, ...(_d = source.featureFlags) != null ? _d : {} };
+  }
   if (target.attachments || source.attachments) {
-    out.attachments = [...(_c = target.attachments) != null ? _c : [], ...(_d = source.attachments) != null ? _d : []];
+    out.attachments = [...(_e = target.attachments) != null ? _e : [], ...(_f = source.attachments) != null ? _f : []];
   }
   return out;
 }
@@ -678,6 +697,7 @@ var EventShipper = class {
         ...wizardSession ? { "raindrop.wizardSession": wizardSession } : {},
         $context: this.context
       },
+      ...accumulated.featureFlags && Object.keys(accumulated.featureFlags).length > 0 ? { feature_flags: accumulated.featureFlags } : {},
       attachments: accumulated.attachments,
       is_pending: isPending
     };
@@ -1149,8 +1169,42 @@ var TraceShipper = class {
 // ../core/dist/index.node.js
 var import_async_hooks = require("async_hooks");
 globalThis.RAINDROP_ASYNC_LOCAL_STORAGE = import_async_hooks.AsyncLocalStorage;
+var SUPPRESS_TRACING_KEY = /* @__PURE__ */ Symbol.for(
+  "OpenTelemetry SDK Context Key SUPPRESS_TRACING"
+);
+function findOtelContextManager() {
+  var _a;
+  for (const sym of Object.getOwnPropertySymbols(globalThis)) {
+    if (!((_a = sym.description) == null ? void 0 : _a.startsWith("opentelemetry.js.api."))) continue;
+    const api = globalThis[sym];
+    const cm = api == null ? void 0 : api.context;
+    if (cm && typeof cm.with === "function" && typeof cm.active === "function") {
+      return cm;
+    }
+  }
+  return void 0;
+}
+function installTracingSuppressionHook() {
+  if (typeof globalThis.RAINDROP_SUPPRESS_TRACING === "function") return;
+  const hook = (fn) => {
+    const cm = findOtelContextManager();
+    if (!cm) return fn();
+    return cm.with(cm.active().setValue(SUPPRESS_TRACING_KEY, true), fn);
+  };
+  globalThis.RAINDROP_SUPPRESS_TRACING = hook;
+}
+installTracingSuppressionHook();
 
 // src/callback-handler.ts
+function resolveEventId(source) {
+  if (typeof source !== "function") return randomUUID();
+  try {
+    const id = source();
+    return typeof id === "string" && id.trim() !== "" ? id : randomUUID();
+  } catch {
+    return randomUUID();
+  }
+}
 function isInternalName(name) {
   if (name.startsWith("Branch:")) return true;
   if (name.startsWith("ChannelWrite")) return true;
@@ -1199,13 +1253,15 @@ var RaindropDeepAgentsHandler = class extends import_base.BaseCallbackHandler {
     this.traceShipper = opts.traceShipper;
     this.userId = opts.userId;
     this.convoId = opts.convoId;
+    this.eventName = opts.eventName;
+    this.eventIdSource = opts.eventId;
     this.traceChains = opts.traceChains ?? true;
   }
   getEventId(runId, parentRunId) {
     const rootId = parentRunId ? this.rootRunIds.get(parentRunId) ?? parentRunId : runId;
     this.rootRunIds.set(runId, rootId);
     if (!this.eventIds.has(rootId)) {
-      this.eventIds.set(rootId, randomUUID());
+      this.eventIds.set(rootId, resolveEventId(this.eventIdSource));
     }
     return this.eventIds.get(rootId);
   }
@@ -1234,10 +1290,11 @@ var RaindropDeepAgentsHandler = class extends import_base.BaseCallbackHandler {
     const eventId = this.eventIds.get(rootId);
     if (!eventId) return;
     if (isRoot) {
-      if (this.convoId) {
+      if (this.convoId || this.eventName) {
         await this.eventShipper.patch(eventId, {
           userId: this.userId,
           convoId: this.convoId,
+          eventName: this.eventName,
           isPending: true
         });
       }
@@ -1246,6 +1303,7 @@ var RaindropDeepAgentsHandler = class extends import_base.BaseCallbackHandler {
       await this.eventShipper.patch(eventId, {
         userId: this.userId,
         convoId: this.convoId,
+        eventName: this.eventName,
         ...patch,
         isPending: true
       });
@@ -1272,6 +1330,7 @@ var RaindropDeepAgentsHandler = class extends import_base.BaseCallbackHandler {
       await this.eventShipper.patch(eventId, {
         userId: this.userId,
         convoId: this.convoId,
+        eventName: this.eventName,
         input: truncate(prompts.join("\n"), CHAIN_TEXT_MAX_LEN),
         properties: buildProperties(tags, metadata),
         isPending: true
@@ -1305,6 +1364,7 @@ var RaindropDeepAgentsHandler = class extends import_base.BaseCallbackHandler {
       await this.eventShipper.patch(eventId, {
         userId: this.userId,
         convoId: this.convoId,
+        eventName: this.eventName,
         input: inputText,
         properties: buildProperties(tags, metadata),
         isPending: true
@@ -1724,6 +1784,8 @@ function createRaindropDeepAgents(opts) {
     traceShipper,
     userId: opts.userId,
     convoId: opts.convoId,
+    eventName: opts.eventName,
+    eventId: opts.eventId,
     traceChains: opts.traceChains
   });
   return {

package/dist/index.mjs

@@ -1,7 +1,7 @@
 // src/callback-handler.ts
 import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
 
-// ../core/dist/chunk-SK6EJEO7.js
+// ../core/dist/chunk-267IXHO5.js
 function getCrypto() {
   const c = globalThis.crypto;
   return c;
@@ -56,6 +56,20 @@ function base64Encode(bytes) {
   }
   return out;
 }
+function runWithTracingSuppressed(fn) {
+  const hook = globalThis.RAINDROP_SUPPRESS_TRACING;
+  if (typeof hook !== "function") return fn();
+  let started = false;
+  try {
+    return hook(() => {
+      started = true;
+      return fn();
+    });
+  } catch (err) {
+    if (started) throw err;
+    return fn();
+  }
+}
 var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
 var MAX_RETRY_DELAY_MS = 3e4;
 function wait(ms) {
@@ -166,15 +180,17 @@ async function postJson(url, body, headers, opts) {
   const timeoutMs = (_a = opts.timeoutMs) != null ? _a : DEFAULT_REQUEST_TIMEOUT_MS;
   await withRetry(
     async () => {
-      const resp = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          ...headers
-        },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(timeoutMs)
-      });
+      const resp = await runWithTracingSuppressed(
+        () => fetch(url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            ...headers
+          },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(timeoutMs)
+        })
+      );
       if (!resp.ok) {
         const text = await resp.text().catch(() => "");
         const err = new Error(
@@ -375,13 +391,16 @@ function projectIdHeaders(projectId) {
 var SHUTDOWN_DEADLINE_MS = 1e4;
 var POST_SHUTDOWN_TIMEOUT_MS = 5e3;
 function mergePatches(target, source) {
-  var _a, _b, _c, _d;
+  var _a, _b, _c, _d, _e, _f;
   const out = { ...target, ...source };
   if (target.properties || source.properties) {
     out.properties = { ...(_a = target.properties) != null ? _a : {}, ...(_b = source.properties) != null ? _b : {} };
   }
+  if (target.featureFlags || source.featureFlags) {
+    out.featureFlags = { ...(_c = target.featureFlags) != null ? _c : {}, ...(_d = source.featureFlags) != null ? _d : {} };
+  }
   if (target.attachments || source.attachments) {
-    out.attachments = [...(_c = target.attachments) != null ? _c : [], ...(_d = source.attachments) != null ? _d : []];
+    out.attachments = [...(_e = target.attachments) != null ? _e : [], ...(_f = source.attachments) != null ? _f : []];
   }
   return out;
 }
@@ -651,6 +670,7 @@ var EventShipper = class {
         ...wizardSession ? { "raindrop.wizardSession": wizardSession } : {},
         $context: this.context
       },
+      ...accumulated.featureFlags && Object.keys(accumulated.featureFlags).length > 0 ? { feature_flags: accumulated.featureFlags } : {},
       attachments: accumulated.attachments,
       is_pending: isPending
     };
@@ -1122,8 +1142,42 @@ var TraceShipper = class {
 // ../core/dist/index.node.js
 import { AsyncLocalStorage } from "async_hooks";
 globalThis.RAINDROP_ASYNC_LOCAL_STORAGE = AsyncLocalStorage;
+var SUPPRESS_TRACING_KEY = /* @__PURE__ */ Symbol.for(
+  "OpenTelemetry SDK Context Key SUPPRESS_TRACING"
+);
+function findOtelContextManager() {
+  var _a;
+  for (const sym of Object.getOwnPropertySymbols(globalThis)) {
+    if (!((_a = sym.description) == null ? void 0 : _a.startsWith("opentelemetry.js.api."))) continue;
+    const api = globalThis[sym];
+    const cm = api == null ? void 0 : api.context;
+    if (cm && typeof cm.with === "function" && typeof cm.active === "function") {
+      return cm;
+    }
+  }
+  return void 0;
+}
+function installTracingSuppressionHook() {
+  if (typeof globalThis.RAINDROP_SUPPRESS_TRACING === "function") return;
+  const hook = (fn) => {
+    const cm = findOtelContextManager();
+    if (!cm) return fn();
+    return cm.with(cm.active().setValue(SUPPRESS_TRACING_KEY, true), fn);
+  };
+  globalThis.RAINDROP_SUPPRESS_TRACING = hook;
+}
+installTracingSuppressionHook();
 
 // src/callback-handler.ts
+function resolveEventId(source) {
+  if (typeof source !== "function") return randomUUID();
+  try {
+    const id = source();
+    return typeof id === "string" && id.trim() !== "" ? id : randomUUID();
+  } catch {
+    return randomUUID();
+  }
+}
 function isInternalName(name) {
   if (name.startsWith("Branch:")) return true;
   if (name.startsWith("ChannelWrite")) return true;
@@ -1172,13 +1226,15 @@ var RaindropDeepAgentsHandler = class extends BaseCallbackHandler {
     this.traceShipper = opts.traceShipper;
     this.userId = opts.userId;
     this.convoId = opts.convoId;
+    this.eventName = opts.eventName;
+    this.eventIdSource = opts.eventId;
     this.traceChains = opts.traceChains ?? true;
   }
   getEventId(runId, parentRunId) {
     const rootId = parentRunId ? this.rootRunIds.get(parentRunId) ?? parentRunId : runId;
     this.rootRunIds.set(runId, rootId);
     if (!this.eventIds.has(rootId)) {
-      this.eventIds.set(rootId, randomUUID());
+      this.eventIds.set(rootId, resolveEventId(this.eventIdSource));
     }
     return this.eventIds.get(rootId);
   }
@@ -1207,10 +1263,11 @@ var RaindropDeepAgentsHandler = class extends BaseCallbackHandler {
     const eventId = this.eventIds.get(rootId);
     if (!eventId) return;
     if (isRoot) {
-      if (this.convoId) {
+      if (this.convoId || this.eventName) {
         await this.eventShipper.patch(eventId, {
           userId: this.userId,
           convoId: this.convoId,
+          eventName: this.eventName,
           isPending: true
         });
       }
@@ -1219,6 +1276,7 @@ var RaindropDeepAgentsHandler = class extends BaseCallbackHandler {
       await this.eventShipper.patch(eventId, {
         userId: this.userId,
         convoId: this.convoId,
+        eventName: this.eventName,
         ...patch,
         isPending: true
       });
@@ -1245,6 +1303,7 @@ var RaindropDeepAgentsHandler = class extends BaseCallbackHandler {
       await this.eventShipper.patch(eventId, {
         userId: this.userId,
         convoId: this.convoId,
+        eventName: this.eventName,
         input: truncate(prompts.join("\n"), CHAIN_TEXT_MAX_LEN),
         properties: buildProperties(tags, metadata),
         isPending: true
@@ -1278,6 +1337,7 @@ var RaindropDeepAgentsHandler = class extends BaseCallbackHandler {
       await this.eventShipper.patch(eventId, {
         userId: this.userId,
         convoId: this.convoId,
+        eventName: this.eventName,
         input: inputText,
         properties: buildProperties(tags, metadata),
         isPending: true
@@ -1697,6 +1757,8 @@ function createRaindropDeepAgents(opts) {
     traceShipper,
     userId: opts.userId,
     convoId: opts.convoId,
+    eventName: opts.eventName,
+    eventId: opts.eventId,
     traceChains: opts.traceChains
   });
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raindrop-ai/deep-agents",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "description": "Raindrop integration for LangChain Deep Agents",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -36,7 +36,7 @@
     "typescript": "^5.3.3",
     "vitest": "^2.1.9",
     "zod": "^3.23.0",
-    "@raindrop-ai/core": "0.0.4"
+    "@raindrop-ai/core": "0.1.2"
   },
   "tsup": {
     "entry": [