@raindrop-ai/deep-agents 0.1.1 → 0.1.3

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:
@@ -111,7 +139,7 @@ The `createRaindropDeepAgents()` factory returns:
 - **Streaming**: Token-by-token streaming events are not captured individually; only the final aggregated response is tracked.
 - **Subagent isolation**: When using the `task` tool for subagent delegation, each subagent's callbacks fire independently.
 - **Concurrent invocations on a shared handler**: A single handler instance keeps one in-flight span map at a time. Running multiple `agent.invoke(...)` calls **concurrently with the same handler** (e.g. `Promise.all([agent.invoke(...), agent.invoke(...)])` with the same `raindrop.handler`) can scramble the linkage between events and traces. Instantiate one `createRaindropDeepAgents()` per concurrent request; sequential invocations on a shared handler are fully supported.
-- **Long chain inputs/outputs are truncated**: Chain-level `input` and `output` captured on the root event are truncated to ~8 KB to stay within the SDK's payload-size limit. Per-LLM child events still carry full prompts. Tool payloads are pruned to their cap _before_ JSON serialization, so a multi-MB tool output costs the cap — not the payload — on your event loop (truncated values carry a `...[truncated by raindrop]` marker).
+- **Long inputs/outputs are truncated at `maxTextFieldChars`**: The root event's `input` is the latest user message and its `output` the final response, each capped at the configured `maxTextFieldChars` (default 1,000,000 chars), the same cap the other JavaScript integrations use; the full conversation history lives on the LLM span (`ai.prompt.messages`). Tool payloads are pruned to the cap _before_ JSON serialization, so a multi-MB tool output costs the cap — not the payload — on your event loop (truncated values carry a `...[truncated by raindrop]` marker).
 
 ## Testing
 

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;
@@ -443,6 +517,15 @@ interface RaindropDeepAgentsHandlerOptions {
     eventName?: string;
     eventId?: () => string;
     traceChains?: boolean;
+    /**
+     * Per-field caps this handler captures against, fixed for its lifetime:
+     * `maxTextFieldChars` for span attributes (further reduced by
+     * `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` as each span is captured, the
+     * way the trace shipper applies it), `eventMaxTextFieldChars` for event
+     * `input`/`output`. Default to the module-wide cap at construction.
+     */
+    maxTextFieldChars?: number;
+    eventMaxTextFieldChars?: number;
 }
 declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     name: string;
@@ -453,6 +536,8 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     private eventName?;
     private eventIdSource?;
     private traceChains;
+    private readonly configuredSpanMaxChars;
+    private readonly eventMaxChars;
     private spans;
     private rootRunIds;
     private eventIds;
@@ -465,6 +550,7 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
      */
     _lastRootEventId: string | undefined;
     constructor(opts: RaindropDeepAgentsHandlerOptions);
+    private get spanMaxChars();
     private getEventId;
     private getParent;
     private cleanup;
@@ -513,6 +599,17 @@ interface DeepAgentsOptions {
      */
     projectId?: string;
     traceChains?: boolean;
+    /**
+     * Per-field character cap for captured text and JSON (`ai.prompt.messages`,
+     * `ai.toolCall.args` / `ai.toolCall.result`, event `input` / `output`).
+     * A history that does not fit is cut at message boundaries, stays valid
+     * JSON and is flagged with `ai.prompt.messages.truncated`. Module-wide,
+     * shared with the underlying shippers; omitting it leaves the current cap
+     * unchanged. Defaults to 1,000,000.
+     */
+    maxTextFieldChars?: number;
+    /** 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;
@@ -443,6 +517,15 @@ interface RaindropDeepAgentsHandlerOptions {
     eventName?: string;
     eventId?: () => string;
     traceChains?: boolean;
+    /**
+     * Per-field caps this handler captures against, fixed for its lifetime:
+     * `maxTextFieldChars` for span attributes (further reduced by
+     * `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` as each span is captured, the
+     * way the trace shipper applies it), `eventMaxTextFieldChars` for event
+     * `input`/`output`. Default to the module-wide cap at construction.
+     */
+    maxTextFieldChars?: number;
+    eventMaxTextFieldChars?: number;
 }
 declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     name: string;
@@ -453,6 +536,8 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     private eventName?;
     private eventIdSource?;
     private traceChains;
+    private readonly configuredSpanMaxChars;
+    private readonly eventMaxChars;
     private spans;
     private rootRunIds;
     private eventIds;
@@ -465,6 +550,7 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
      */
     _lastRootEventId: string | undefined;
     constructor(opts: RaindropDeepAgentsHandlerOptions);
+    private get spanMaxChars();
     private getEventId;
     private getParent;
     private cleanup;
@@ -513,6 +599,17 @@ interface DeepAgentsOptions {
      */
     projectId?: string;
     traceChains?: boolean;
+    /**
+     * Per-field character cap for captured text and JSON (`ai.prompt.messages`,
+     * `ai.toolCall.args` / `ai.toolCall.result`, event `input` / `output`).
+     * A history that does not fit is cut at message boundaries, stays valid
+     * JSON and is flagged with `ai.prompt.messages.truncated`. Module-wide,
+     * shared with the underlying shippers; omitting it leaves the current cap
+     * unchanged. Defaults to 1,000,000.
+     */
+    maxTextFieldChars?: number;
+    /** Application Git identity. Auto-detects commit SHA by default; pass `false` to disable. */
+    appGit?: AppGitOptions | false;
 }
 type RaindropDeepAgentsClient = {
     /**