@raindrop-ai/deep-agents 0.0.6 → 0.1.1

package/README.md

@@ -120,17 +120,7 @@ The `createRaindropDeepAgents()` factory returns:
 pnpm test -- tests/handler.test.ts
 ```
 
-**E2E tests** run REAL Deep Agents workflows via `createDeepAgent()` against a REAL LLM (OpenAI gpt-4o-mini) and verify events / tool calls / traces against the production dashboard TRPC API. They skip automatically when any of `RAINDROP_WRITE_KEY`, `OPENAI_API_KEY`, or `RAINDROP_DASHBOARD_TOKEN` is missing.
-
-```bash
-# E2E — requires all three keys
-RAINDROP_WRITE_KEY=xxx \
-OPENAI_API_KEY=sk-... \
-RAINDROP_DASHBOARD_TOKEN=eyJ... \
-  pnpm test -- tests/e2e.test.ts
-```
-
-The dashboard token comes from `app.raindrop.ai` → DevTools → Network → any `backend.raindrop.ai` request → `Authorization: Bearer ...` (expires every ~30 min, so grab a fresh one immediately before running).
+End-to-end coverage runs through the cross-SDK [conformance harness](https://github.com/invisible-tools/raindrop-sdk-harness). The `deep-agents` conformance driver (`conformance/deep-agents-driver.mjs`) maps the shared scenario corpus onto this package's public API. The fault lane runs locally and on every PR against a fault-injecting fake ingest; the prod lane verifies real ingest through the public Query API readback. See [`conformance/README.md`](../../conformance/README.md) and the harness [README](https://github.com/invisible-tools/raindrop-sdk-harness/blob/main/README.md) / [HOW-IT-WORKS](https://github.com/invisible-tools/raindrop-sdk-harness/blob/main/docs/HOW-IT-WORKS.md).
 
 ## Python
 

package/dist/index.d.mts

@@ -52,6 +52,10 @@ type IdentifyInput = {
     userId: string;
     traits?: Record<string, unknown>;
 };
+type EventUsage = {
+    promptTokens?: number;
+    completionTokens?: number;
+};
 type Patch = {
     eventName?: string;
     userId?: string;
@@ -59,7 +63,10 @@ type Patch = {
     input?: string;
     output?: string;
     model?: string;
+    usage?: EventUsage;
+    error?: unknown;
     properties?: Record<string, unknown>;
+    featureFlags?: Record<string, string>;
     attachments?: Attachment[];
     isPending?: boolean;
     timestamp?: string;
@@ -156,12 +163,7 @@ declare class EventShipper {
      */
     private requestOpts;
     patch(eventId: string, patch: Patch): Promise<void>;
-    finish(eventId: string, patch: {
-        output?: string;
-        model?: string;
-        properties?: Record<string, unknown>;
-        userId?: string;
-    }): Promise<void>;
+    finish(eventId: string, patch: Pick<Patch, "output" | "model" | "usage" | "error" | "properties" | "featureFlags" | "userId">): Promise<void>;
     flush(): Promise<void>;
     shutdown(): Promise<void>;
     trackSignal(signal: SignalInput): Promise<void>;
@@ -334,6 +336,9 @@ declare class TraceShipper {
             spanIdB64: string;
         };
         eventId: string;
+        userId?: string;
+        convoId?: string;
+        eventName?: string;
         operationId?: string;
         attributes?: Array<OtlpKeyValue | undefined>;
         startTimeUnixNano?: string;
@@ -352,6 +357,9 @@ declare class TraceShipper {
             spanIdB64: string;
         };
         eventId: string;
+        userId?: string;
+        convoId?: string;
+        eventName?: string;
         startTimeUnixNano: string;
         endTimeUnixNano: string;
         attributes?: Array<OtlpKeyValue | undefined>;
@@ -432,6 +440,8 @@ interface RaindropDeepAgentsHandlerOptions {
     traceShipper: TraceShipper;
     userId?: string;
     convoId?: string;
+    eventName?: string;
+    eventId?: () => string;
     traceChains?: boolean;
 }
 declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
@@ -440,6 +450,8 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     private traceShipper;
     private userId?;
     private convoId?;
+    private eventName?;
+    private eventIdSource?;
     private traceChains;
     private spans;
     private rootRunIds;
@@ -457,6 +469,7 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     private getParent;
     private cleanup;
     private finalizeEventIfRoot;
+    private rootErrorPatch;
     handleLLMStart(llm: Serialized, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleChatModelStart(llm: Serialized, messages: BaseMessage[][], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleLLMEnd(output: LLMResult, runId: string, _parentRunId?: string): Promise<void>;
@@ -481,6 +494,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

@@ -52,6 +52,10 @@ type IdentifyInput = {
     userId: string;
     traits?: Record<string, unknown>;
 };
+type EventUsage = {
+    promptTokens?: number;
+    completionTokens?: number;
+};
 type Patch = {
     eventName?: string;
     userId?: string;
@@ -59,7 +63,10 @@ type Patch = {
     input?: string;
     output?: string;
     model?: string;
+    usage?: EventUsage;
+    error?: unknown;
     properties?: Record<string, unknown>;
+    featureFlags?: Record<string, string>;
     attachments?: Attachment[];
     isPending?: boolean;
     timestamp?: string;
@@ -156,12 +163,7 @@ declare class EventShipper {
      */
     private requestOpts;
     patch(eventId: string, patch: Patch): Promise<void>;
-    finish(eventId: string, patch: {
-        output?: string;
-        model?: string;
-        properties?: Record<string, unknown>;
-        userId?: string;
-    }): Promise<void>;
+    finish(eventId: string, patch: Pick<Patch, "output" | "model" | "usage" | "error" | "properties" | "featureFlags" | "userId">): Promise<void>;
     flush(): Promise<void>;
     shutdown(): Promise<void>;
     trackSignal(signal: SignalInput): Promise<void>;
@@ -334,6 +336,9 @@ declare class TraceShipper {
             spanIdB64: string;
         };
         eventId: string;
+        userId?: string;
+        convoId?: string;
+        eventName?: string;
         operationId?: string;
         attributes?: Array<OtlpKeyValue | undefined>;
         startTimeUnixNano?: string;
@@ -352,6 +357,9 @@ declare class TraceShipper {
             spanIdB64: string;
         };
         eventId: string;
+        userId?: string;
+        convoId?: string;
+        eventName?: string;
         startTimeUnixNano: string;
         endTimeUnixNano: string;
         attributes?: Array<OtlpKeyValue | undefined>;
@@ -432,6 +440,8 @@ interface RaindropDeepAgentsHandlerOptions {
     traceShipper: TraceShipper;
     userId?: string;
     convoId?: string;
+    eventName?: string;
+    eventId?: () => string;
     traceChains?: boolean;
 }
 declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
@@ -440,6 +450,8 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     private traceShipper;
     private userId?;
     private convoId?;
+    private eventName?;
+    private eventIdSource?;
     private traceChains;
     private spans;
     private rootRunIds;
@@ -457,6 +469,7 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     private getParent;
     private cleanup;
     private finalizeEventIfRoot;
+    private rootErrorPatch;
     handleLLMStart(llm: Serialized, prompts: string[], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleChatModelStart(llm: Serialized, messages: BaseMessage[][], runId: string, parentRunId?: string, _extraParams?: Record<string, unknown>, tags?: string[], metadata?: Record<string, unknown>, runName?: string): Promise<void>;
     handleLLMEnd(output: LLMResult, runId: string, _parentRunId?: string): Promise<void>;
@@ -481,6 +494,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