@raindrop-ai/deep-agents 0.1.0 → 0.1.2

package/README.md

@@ -70,6 +70,34 @@ const raindrop = createRaindropDeepAgents({
 
 This sets the `X-Raindrop-Project-Id` header on every event. Omit it (or pass `"default"`) to use your org's default **Production** project — the existing behavior. Single-project orgs need nothing new.
 
+
+## Application Git identity
+
+Each client reports the application commit SHA when it can determine one. Local Git discovery runs in the background and never delays or fails application calls. Automatic branch discovery is off by default.
+
+Use `appGit` to override detection or opt out:
+
+```ts
+const raindrop = createRaindropDeepAgents({
+  writeKey: "your-write-key",
+  appGit: {
+    commitSha: "0123456789abcdef0123456789abcdef01234567",
+    commitDirty: false,
+    branch: "main",
+    detectBranch: true,
+    sourceDirectory: "/path/to/application",
+  },
+});
+
+// Disable all application Git reporting.
+const withoutGit = createRaindropDeepAgents({
+  writeKey: "your-write-key",
+  appGit: false,
+});
+```
+
+`commitSha`, `commitDirty`, and `branch` are explicit overrides. `detectBranch` opts into automatic branch lookup, `sourceDirectory` selects the application repository, and `autoDetect: false` disables automatic sources while retaining explicit values.
+
 ## LangGraph Support
 
 Deep Agents is built on LangGraph. The handler automatically:
@@ -120,17 +148,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

@@ -42,6 +42,64 @@ type SpanIds = {
     spanIdB64: string;
     parentSpanIdB64?: string;
 };
+/** Kept structural so public integration declarations do not depend on private schemas. */
+type AppGitOptions = {
+    commitSha?: string | null;
+    commitDirty?: boolean | null;
+    branch?: string | null;
+    detectBranch?: boolean;
+    sourceDirectory?: string;
+    autoDetect?: boolean;
+};
+type AppGitSnapshot = Readonly<Record<string, unknown>>;
+type AppGitEnvironment = Readonly<Record<string, string | undefined>>;
+type AppGitLocalResult = {
+    commitSha?: string;
+    commitDirty?: boolean;
+    branch?: string;
+};
+type AppGitOperationOwner = string;
+type AppGitLocalResolver = (sourceDirectory: string | undefined, detectBranch: boolean, completed: (result: AppGitLocalResult) => void) => () => void;
+/** One client owns its defaults; operation snapshots never wait for discovery. */
+declare class AppGitContextImpl {
+    private defaults;
+    private explicit;
+    private explicitKeys;
+    private cancel;
+    private disposed;
+    private operations;
+    private operationOverflow;
+    private detectBranch;
+    private replayBranch;
+    private disabled;
+    constructor(options: AppGitOptions | false | undefined, runtime?: {
+        allowLocalGit?: boolean;
+        resolveLocal?: AppGitLocalResolver;
+        env?: AppGitEnvironment;
+        captureLegacyReplayBranch?: boolean;
+        allowDiscovery?: boolean;
+    });
+    private accept;
+    snapshot(properties?: Readonly<Record<string, unknown>>): AppGitSnapshot;
+    /** Safe defaults when no operation/span start was observed; never infer identity. */
+    snapshotExplicit(properties?: Readonly<Record<string, unknown>>, eventId?: string): AppGitSnapshot;
+    /** Existing replay branch reporting stays separate from opt-in event properties. */
+    snapshotForReplay(): AppGitSnapshot;
+    /** Merge a frozen span snapshot without losing client-authored provenance. */
+    mergeSnapshot(base: AppGitSnapshot, properties?: Readonly<Record<string, unknown>>, explicitKeys?: ReadonlySet<string>): AppGitSnapshot;
+    /** Shippers belonging to one client share this bounded operation registry. */
+    forOperation(eventId: string | undefined, properties?: Readonly<Record<string, unknown>>, owner?: AppGitOperationOwner): AppGitSnapshot;
+    releaseOperation(eventId: string, owner: AppGitOperationOwner): void;
+    finishOperation(eventId: string): void;
+    dispose(): void;
+}
+/** Structural at package boundaries: public SDK bundles contain independent copies of core. */
+type AppGitContext = Pick<AppGitContextImpl, "snapshot" | "snapshotForReplay" | "forOperation" | "finishOperation" | "dispose"> & {
+    snapshotExplicit?: AppGitContextImpl["snapshotExplicit"];
+    mergeSnapshot?: AppGitContextImpl["mergeSnapshot"];
+    releaseOperation?: (eventId: string, owner: AppGitOperationOwner) => void;
+};
+declare const AppGitContext: typeof AppGitContextImpl;
 type Attachment = {
     type: string;
     role: string;
@@ -52,6 +110,10 @@ type IdentifyInput = {
     userId: string;
     traits?: Record<string, unknown>;
 };
+type EventUsage = {
+    promptTokens?: number;
+    completionTokens?: number;
+};
 type Patch = {
     eventName?: string;
     userId?: string;
@@ -59,6 +121,8 @@ type Patch = {
     input?: string;
     output?: string;
     model?: string;
+    usage?: EventUsage;
+    error?: unknown;
     properties?: Record<string, unknown>;
     featureFlags?: Record<string, string>;
     attachments?: Attachment[];
@@ -77,6 +141,9 @@ type SignalInput = {
     after?: string;
 };
 type EventShipperOptions = {
+    appGit?: AppGitOptions | false;
+    /** Share with the trace shipper so one operation uses one source snapshot. */
+    appGitContext?: AppGitContext;
     writeKey?: string;
     endpoint?: string;
     enabled?: boolean;
@@ -108,6 +175,9 @@ type EventShipperOptions = {
     maxTextFieldChars?: number;
 };
 declare class EventShipper {
+    private appGitContext;
+    private ownsAppGitContext;
+    private readonly appGitOwner;
     private baseUrl;
     private writeKey?;
     private enabled;
@@ -138,6 +208,7 @@ declare class EventShipper {
     /** URL of the local debugger / Workshop daemon, when one is reachable. */
     private localDebuggerUrl;
     constructor(opts: EventShipperOptions);
+    protected ownAppGitContextForShutdown(): void;
     isDebugEnabled(): boolean;
     private authHeaders;
     private requestHeaders;
@@ -157,13 +228,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>;
-        featureFlags?: Record<string, string>;
-        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>;
@@ -197,6 +262,8 @@ type InternalSpan = {
     attributes: Array<OtlpKeyValue | undefined>;
 };
 type TraceShipperOptions = {
+    appGit?: AppGitOptions | false;
+    appGitContext?: AppGitContext;
     writeKey?: string;
     endpoint?: string;
     enabled?: boolean;
@@ -265,6 +332,13 @@ type TraceShipperOptions = {
     maxTextFieldChars?: number;
 };
 declare class TraceShipper {
+    private appGitContext;
+    protected ownsAppGitContext: boolean;
+    private readonly appGitOwner;
+    private appGitEventIds;
+    private appGitActiveSpans;
+    private appGitCaptured;
+    private appGitAdded;
     private baseUrl;
     private writeKey?;
     private enabled;
@@ -336,6 +410,9 @@ declare class TraceShipper {
             spanIdB64: string;
         };
         eventId: string;
+        userId?: string;
+        convoId?: string;
+        eventName?: string;
         operationId?: string;
         attributes?: Array<OtlpKeyValue | undefined>;
         startTimeUnixNano?: string;
@@ -354,6 +431,9 @@ declare class TraceShipper {
             spanIdB64: string;
         };
         eventId: string;
+        userId?: string;
+        convoId?: string;
+        eventName?: string;
         startTimeUnixNano: string;
         endTimeUnixNano: string;
         attributes?: Array<OtlpKeyValue | undefined>;
@@ -463,6 +543,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>;
@@ -506,6 +587,8 @@ interface DeepAgentsOptions {
      */
     projectId?: string;
     traceChains?: boolean;
+    /** Application Git identity. Auto-detects commit SHA by default; pass `false` to disable. */
+    appGit?: AppGitOptions | false;
 }
 type RaindropDeepAgentsClient = {
     /**

package/dist/index.d.ts

@@ -42,6 +42,64 @@ type SpanIds = {
     spanIdB64: string;
     parentSpanIdB64?: string;
 };
+/** Kept structural so public integration declarations do not depend on private schemas. */
+type AppGitOptions = {
+    commitSha?: string | null;
+    commitDirty?: boolean | null;
+    branch?: string | null;
+    detectBranch?: boolean;
+    sourceDirectory?: string;
+    autoDetect?: boolean;
+};
+type AppGitSnapshot = Readonly<Record<string, unknown>>;
+type AppGitEnvironment = Readonly<Record<string, string | undefined>>;
+type AppGitLocalResult = {
+    commitSha?: string;
+    commitDirty?: boolean;
+    branch?: string;
+};
+type AppGitOperationOwner = string;
+type AppGitLocalResolver = (sourceDirectory: string | undefined, detectBranch: boolean, completed: (result: AppGitLocalResult) => void) => () => void;
+/** One client owns its defaults; operation snapshots never wait for discovery. */
+declare class AppGitContextImpl {
+    private defaults;
+    private explicit;
+    private explicitKeys;
+    private cancel;
+    private disposed;
+    private operations;
+    private operationOverflow;
+    private detectBranch;
+    private replayBranch;
+    private disabled;
+    constructor(options: AppGitOptions | false | undefined, runtime?: {
+        allowLocalGit?: boolean;
+        resolveLocal?: AppGitLocalResolver;
+        env?: AppGitEnvironment;
+        captureLegacyReplayBranch?: boolean;
+        allowDiscovery?: boolean;
+    });
+    private accept;
+    snapshot(properties?: Readonly<Record<string, unknown>>): AppGitSnapshot;
+    /** Safe defaults when no operation/span start was observed; never infer identity. */
+    snapshotExplicit(properties?: Readonly<Record<string, unknown>>, eventId?: string): AppGitSnapshot;
+    /** Existing replay branch reporting stays separate from opt-in event properties. */
+    snapshotForReplay(): AppGitSnapshot;
+    /** Merge a frozen span snapshot without losing client-authored provenance. */
+    mergeSnapshot(base: AppGitSnapshot, properties?: Readonly<Record<string, unknown>>, explicitKeys?: ReadonlySet<string>): AppGitSnapshot;
+    /** Shippers belonging to one client share this bounded operation registry. */
+    forOperation(eventId: string | undefined, properties?: Readonly<Record<string, unknown>>, owner?: AppGitOperationOwner): AppGitSnapshot;
+    releaseOperation(eventId: string, owner: AppGitOperationOwner): void;
+    finishOperation(eventId: string): void;
+    dispose(): void;
+}
+/** Structural at package boundaries: public SDK bundles contain independent copies of core. */
+type AppGitContext = Pick<AppGitContextImpl, "snapshot" | "snapshotForReplay" | "forOperation" | "finishOperation" | "dispose"> & {
+    snapshotExplicit?: AppGitContextImpl["snapshotExplicit"];
+    mergeSnapshot?: AppGitContextImpl["mergeSnapshot"];
+    releaseOperation?: (eventId: string, owner: AppGitOperationOwner) => void;
+};
+declare const AppGitContext: typeof AppGitContextImpl;
 type Attachment = {
     type: string;
     role: string;
@@ -52,6 +110,10 @@ type IdentifyInput = {
     userId: string;
     traits?: Record<string, unknown>;
 };
+type EventUsage = {
+    promptTokens?: number;
+    completionTokens?: number;
+};
 type Patch = {
     eventName?: string;
     userId?: string;
@@ -59,6 +121,8 @@ type Patch = {
     input?: string;
     output?: string;
     model?: string;
+    usage?: EventUsage;
+    error?: unknown;
     properties?: Record<string, unknown>;
     featureFlags?: Record<string, string>;
     attachments?: Attachment[];
@@ -77,6 +141,9 @@ type SignalInput = {
     after?: string;
 };
 type EventShipperOptions = {
+    appGit?: AppGitOptions | false;
+    /** Share with the trace shipper so one operation uses one source snapshot. */
+    appGitContext?: AppGitContext;
     writeKey?: string;
     endpoint?: string;
     enabled?: boolean;
@@ -108,6 +175,9 @@ type EventShipperOptions = {
     maxTextFieldChars?: number;
 };
 declare class EventShipper {
+    private appGitContext;
+    private ownsAppGitContext;
+    private readonly appGitOwner;
     private baseUrl;
     private writeKey?;
     private enabled;
@@ -138,6 +208,7 @@ declare class EventShipper {
     /** URL of the local debugger / Workshop daemon, when one is reachable. */
     private localDebuggerUrl;
     constructor(opts: EventShipperOptions);
+    protected ownAppGitContextForShutdown(): void;
     isDebugEnabled(): boolean;
     private authHeaders;
     private requestHeaders;
@@ -157,13 +228,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>;
-        featureFlags?: Record<string, string>;
-        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>;
@@ -197,6 +262,8 @@ type InternalSpan = {
     attributes: Array<OtlpKeyValue | undefined>;
 };
 type TraceShipperOptions = {
+    appGit?: AppGitOptions | false;
+    appGitContext?: AppGitContext;
     writeKey?: string;
     endpoint?: string;
     enabled?: boolean;
@@ -265,6 +332,13 @@ type TraceShipperOptions = {
     maxTextFieldChars?: number;
 };
 declare class TraceShipper {
+    private appGitContext;
+    protected ownsAppGitContext: boolean;
+    private readonly appGitOwner;
+    private appGitEventIds;
+    private appGitActiveSpans;
+    private appGitCaptured;
+    private appGitAdded;
     private baseUrl;
     private writeKey?;
     private enabled;
@@ -336,6 +410,9 @@ declare class TraceShipper {
             spanIdB64: string;
         };
         eventId: string;
+        userId?: string;
+        convoId?: string;
+        eventName?: string;
         operationId?: string;
         attributes?: Array<OtlpKeyValue | undefined>;
         startTimeUnixNano?: string;
@@ -354,6 +431,9 @@ declare class TraceShipper {
             spanIdB64: string;
         };
         eventId: string;
+        userId?: string;
+        convoId?: string;
+        eventName?: string;
         startTimeUnixNano: string;
         endTimeUnixNano: string;
         attributes?: Array<OtlpKeyValue | undefined>;
@@ -463,6 +543,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>;
@@ -506,6 +587,8 @@ interface DeepAgentsOptions {
      */
     projectId?: string;
     traceChains?: boolean;
+    /** Application Git identity. Auto-detects commit SHA by default; pass `false` to disable. */
+    appGit?: AppGitOptions | false;
 }
 type RaindropDeepAgentsClient = {
     /**