@raindrop-ai/deep-agents 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,365 @@
+import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
+import { Serialized } from '@langchain/core/load/serializable';
+import { LLMResult } from '@langchain/core/outputs';
+import { BaseMessage } from '@langchain/core/messages';
+import { AgentAction, AgentFinish } from '@langchain/core/agents';
+import { ChainValues } from '@langchain/core/utils/types';
+
+type OtlpAnyValue = {
+    stringValue?: string;
+    intValue?: string;
+    doubleValue?: number;
+    boolValue?: boolean;
+    arrayValue?: {
+        values: OtlpAnyValue[];
+    };
+};
+type OtlpKeyValue = {
+    key: string;
+    value: OtlpAnyValue;
+};
+declare const SpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+type OtlpSpanStatus = {
+    code: (typeof SpanStatusCode)[keyof typeof SpanStatusCode] | number;
+    message?: string;
+};
+type OtlpSpan = {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes?: OtlpKeyValue[];
+    status?: OtlpSpanStatus;
+};
+type SpanIds = {
+    traceIdB64: string;
+    spanIdB64: string;
+    parentSpanIdB64?: string;
+};
+
+type Attachment = {
+    type: string;
+    role: string;
+    name?: string;
+    value: string;
+};
+type IdentifyInput = {
+    userId: string;
+    traits?: Record<string, unknown>;
+};
+type Patch = {
+    eventName?: string;
+    userId?: string;
+    convoId?: string;
+    input?: string;
+    output?: string;
+    model?: string;
+    properties?: Record<string, unknown>;
+    attachments?: Attachment[];
+    isPending?: boolean;
+    timestamp?: string;
+};
+type SignalInput = {
+    eventId: string;
+    name: string;
+    type?: "default" | "feedback" | "edit" | "standard" | "agent" | "agent_internal";
+    sentiment?: "POSITIVE" | "NEGATIVE";
+    timestamp?: string;
+    properties?: Record<string, unknown>;
+    attachmentId?: string;
+    comment?: string;
+    after?: string;
+};
+type EventShipperOptions = {
+    writeKey?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    debug: boolean;
+    partialFlushMs?: number;
+    sdkName?: string;
+    libraryName?: string;
+    libraryVersion?: string;
+    defaultEventName?: string;
+};
+declare class EventShipper {
+    private baseUrl;
+    private writeKey?;
+    private enabled;
+    private debug;
+    private partialFlushMs;
+    private sdkName;
+    private prefix;
+    private defaultEventName;
+    private context;
+    private buffers;
+    private sticky;
+    private timers;
+    private inFlight;
+    constructor(opts: EventShipperOptions);
+    isDebugEnabled(): boolean;
+    private authHeaders;
+    patch(eventId: string, patch: Patch): Promise<void>;
+    finish(eventId: string, patch: {
+        output?: string;
+        model?: string;
+        properties?: Record<string, unknown>;
+        userId?: string;
+    }): Promise<void>;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+    trackSignal(signal: SignalInput): Promise<void>;
+    identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
+    private flushOne;
+}
+
+type InternalSpan = {
+    ids: SpanIds;
+    name: string;
+    startTimeUnixNano: string;
+    endTimeUnixNano?: string;
+    attributes: Array<OtlpKeyValue | undefined>;
+};
+type TraceShipperOptions = {
+    writeKey?: string;
+    endpoint?: string;
+    enabled?: boolean;
+    debug: boolean;
+    debugSpans?: boolean;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    sdkName?: string;
+    serviceName?: string;
+    serviceVersion?: string;
+};
+declare class TraceShipper {
+    private baseUrl;
+    private writeKey?;
+    private enabled;
+    private debug;
+    private debugSpans;
+    private sdkName;
+    private prefix;
+    private serviceName;
+    private serviceVersion;
+    private flushIntervalMs;
+    private maxBatchSize;
+    private maxQueueSize;
+    private queue;
+    private timer;
+    private inFlight;
+    /** URL of the local debugger (from RAINDROP_LOCAL_DEBUGGER env var). */
+    private localDebuggerUrl;
+    constructor(opts: TraceShipperOptions);
+    isDebugEnabled(): boolean;
+    private authHeaders;
+    startSpan(args: {
+        name: string;
+        parent?: {
+            traceIdB64: string;
+            spanIdB64: string;
+        };
+        eventId: string;
+        operationId?: string;
+        attributes?: Array<OtlpKeyValue | undefined>;
+        startTimeUnixNano?: string;
+    }): InternalSpan;
+    endSpan(span: InternalSpan, extra?: {
+        attributes?: InternalSpan["attributes"];
+        error?: unknown;
+        status?: OtlpSpanStatus;
+        endTimeUnixNano?: string;
+    }): void;
+    createSpan(args: {
+        name: string;
+        parent?: {
+            traceIdB64: string;
+            spanIdB64: string;
+        };
+        eventId: string;
+        startTimeUnixNano: string;
+        endTimeUnixNano: string;
+        attributes?: Array<OtlpKeyValue | undefined>;
+        status?: OtlpSpanStatus;
+    }): void;
+    enqueue(span: OtlpSpan): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+
+type ParentSpanContext = {
+    traceIdB64: string;
+    spanIdB64: string;
+    eventId: string;
+};
+interface ContextSpan {
+    readonly traceIdB64: string;
+    readonly spanIdB64: string;
+    readonly eventId: string;
+    log?(data: Record<string, unknown>): void;
+}
+interface AsyncLocalStorageLike<T> {
+    getStore(): T | undefined;
+    run<R>(store: T, callback: () => R): R;
+    enterWith?(store: T): void;
+}
+declare abstract class ContextManager {
+    abstract getParentSpanIds(): ParentSpanContext | undefined;
+    abstract runInContext<R>(span: ContextSpan, callback: () => R): R;
+    abstract getCurrentSpan(): ContextSpan | undefined;
+    abstract isReady(): boolean;
+}
+declare global {
+    var RAINDROP_CONTEXT_MANAGER: (new () => ContextManager) | undefined;
+    var RAINDROP_ASYNC_LOCAL_STORAGE: (new <T>() => AsyncLocalStorageLike<T>) | undefined;
+}
+
+interface RaindropDeepAgentsHandlerOptions {
+    eventShipper: EventShipper;
+    traceShipper: TraceShipper;
+    userId?: string;
+    convoId?: string;
+    traceChains?: boolean;
+}
+declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
+    name: string;
+    private eventShipper;
+    private traceShipper;
+    private userId?;
+    private convoId?;
+    private traceChains;
+    private spans;
+    private rootRunIds;
+    private eventIds;
+    private forwardedSpans;
+    /**
+     * event_id of the most recently finalized ROOT event.  Exposed via
+     * ``RaindropDeepAgentsClient.lastEventId`` so callers can attach a
+     * follow-up signal to the agent invocation they just ran without
+     * polling the dashboard.  Persists across runs; not reset on cleanup.
+     */
+    _lastRootEventId: string | undefined;
+    constructor(opts: RaindropDeepAgentsHandlerOptions);
+    private getEventId;
+    private getParent;
+    private cleanup;
+    private finalizeEventIfRoot;
+    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>;
+    handleLLMError(err: unknown, runId: string): Promise<void>;
+    handleChainStart(chain: Serialized, _inputs: ChainValues, runId: string, parentRunId?: string, _tags?: string[], _metadata?: Record<string, unknown>, _runType?: string, runName?: string): Promise<void>;
+    handleChainEnd(_outputs: ChainValues, runId: string): Promise<void>;
+    handleChainError(err: unknown, runId: string): Promise<void>;
+    handleToolStart(tool: Serialized, input: string, runId: string, parentRunId?: string, _tags?: string[], _metadata?: Record<string, unknown>, runName?: string): Promise<void>;
+    handleToolEnd(output: unknown, runId: string): Promise<void>;
+    handleToolError(err: unknown, runId: string): Promise<void>;
+    handleAgentAction(action: AgentAction, runId: string, parentRunId?: string): Promise<void>;
+    handleAgentEnd(_action: AgentFinish, runId: string): Promise<void>;
+}
+
+interface DeepAgentsOptions {
+    /**
+     * API write key. If omitted, telemetry shipping is disabled but the handler
+     * is still available for a consistent integration surface.
+     */
+    writeKey?: string;
+    endpoint?: string;
+    debug?: boolean;
+    userId?: string;
+    convoId?: string;
+    traceChains?: boolean;
+}
+type RaindropDeepAgentsClient = {
+    /**
+     * LangChain callback handler to pass to Deep Agents via `config.callbacks`.
+     *
+     * @example
+     * ```typescript
+     * const raindrop = createRaindropDeepAgents({ writeKey: "..." });
+     * const agent = createDeepAgent({ tools: [...] });
+     * const result = await agent.invoke(
+     *   { messages: [{ role: "user", content: "Hello" }] },
+     *   { callbacks: [raindrop.handler] },
+     * );
+     * await raindrop.shutdown();
+     * ```
+     */
+    handler: RaindropDeepAgentsHandler;
+    /**
+     * `event_id` of the most recently finalized ROOT event, or `undefined`
+     * if no root event has landed yet.  Use this to attach a feedback
+     * `signals.track()` to the agent invocation you just ran, without
+     * having to poll the dashboard for the real id.
+     *
+     * @example
+     * ```typescript
+     * const raindrop = createRaindropDeepAgents({ writeKey: "..." });
+     * await agent.invoke({ messages: [...] }, { callbacks: [raindrop.handler] });
+     * if (raindrop.lastEventId) {
+     *   await raindrop.signals.track({
+     *     eventId: raindrop.lastEventId,
+     *     name: "thumbs_up",
+     *     type: "feedback",
+     *     sentiment: "POSITIVE",
+     *   });
+     * }
+     * ```
+     */
+    readonly lastEventId: string | undefined;
+    events: {
+        patch(eventId: string, patch: Patch): Promise<void>;
+        finish(eventId: string, patch: {
+            output?: string;
+            model?: string;
+            properties?: Record<string, unknown>;
+        }): Promise<void>;
+        addAttachments(eventId: string, attachments: Attachment[]): Promise<void>;
+        setProperties(eventId: string, properties: Record<string, unknown>): Promise<void>;
+    };
+    users: {
+        identify(users: IdentifyInput | IdentifyInput[]): Promise<void>;
+    };
+    signals: {
+        track(signal: SignalInput): Promise<void>;
+    };
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+};
+/**
+ * Create a Raindrop client for instrumenting LangChain Deep Agents.
+ *
+ * Deep Agents is built on LangChain and LangGraph. This integration provides
+ * a callback handler that captures LLM calls, tool usage (write_todos,
+ * read_file, write_file, edit_file, task, execute, etc.), chains, and agent
+ * actions — shipping them to Raindrop for observability.
+ *
+ * @example
+ * ```typescript
+ * import { createDeepAgent } from "deepagents";
+ * import { createRaindropDeepAgents } from "@raindrop-ai/deep-agents";
+ *
+ * const raindrop = createRaindropDeepAgents({
+ *   writeKey: process.env.RAINDROP_API_KEY,
+ *   userId: "user-123",
+ *   convoId: "convo-456",
+ * });
+ *
+ * const agent = createDeepAgent({ tools: [myTool] });
+ * const result = await agent.invoke(
+ *   { messages: [{ role: "user", content: "Research LangGraph" }] },
+ *   { callbacks: [raindrop.handler] },
+ * );
+ *
+ * await raindrop.shutdown();
+ * ```
+ */
+declare function createRaindropDeepAgents(opts: DeepAgentsOptions): RaindropDeepAgentsClient;
+
+export { type DeepAgentsOptions, type RaindropDeepAgentsClient, RaindropDeepAgentsHandler, createRaindropDeepAgents };