@raindrop-ai/deep-agents 0.1.1 → 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:

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;
@@ -83,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;
@@ -114,6 +175,9 @@ type EventShipperOptions = {
     maxTextFieldChars?: number;
 };
 declare class EventShipper {
+    private appGitContext;
+    private ownsAppGitContext;
+    private readonly appGitOwner;
     private baseUrl;
     private writeKey?;
     private enabled;
@@ -144,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;
@@ -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;
@@ -513,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;
@@ -83,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;
@@ -114,6 +175,9 @@ type EventShipperOptions = {
     maxTextFieldChars?: number;
 };
 declare class EventShipper {
+    private appGitContext;
+    private ownsAppGitContext;
+    private readonly appGitOwner;
     private baseUrl;
     private writeKey?;
     private enabled;
@@ -144,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;
@@ -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;
@@ -513,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 = {
     /**