@raindrop-ai/deep-agents 0.1.2 → 0.1.4

package/README.md

@@ -56,6 +56,16 @@ await raindrop.shutdown();
 | `projectId` | `string` | - | Route events to a specific project (slug); omit for the default **Production** project |
 | `debug` | `boolean` | `false` | Enable verbose logging |
 | `traceChains` | `boolean` | `true` | Create spans for chain execution |
+| `tools` | `ToolDeclaration[]` | - | Overrides the tool catalog recorded as `ai.prompt.tools` on every model span. Use when the integration cannot see the tools the model was given. |
+
+### Tool catalog capture
+
+Every model span (`llm`) records the tools the agent's chat model was given for
+that call as `ai.prompt.tools` (one JSON document per tool: `name`, `description`,
+full JSON Schema as `inputSchema`). It is read from the callback's
+`invocation_params.tools` / `functions`, which ChatOpenAI, ChatAnthropic and similar
+models populate from `bindTools()`. Absent when the model reports no list; pass
+`tools` to record a catalog explicitly (`tools: []` records an empty one).
 
 ## Projects
 
@@ -139,7 +149,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

@@ -509,6 +509,46 @@ declare global {
     var RAINDROP_ASYNC_LOCAL_STORAGE: (new <T>() => AsyncLocalStorageLike<T>) | undefined;
 }
 
+/**
+ * `ai.prompt.tools`: the tool catalog a model call was given, one JSON
+ * document per tool, in the shape the Vercel AI SDK records on its
+ * `doGenerate` / `doStream` spans. Every integration emits this attribute on
+ * its model-call spans so downstream consumers (agent replay, world builder)
+ * can read what the model could call instead of guessing from the calls it
+ * happened to make.
+ *
+ * An absent attribute means the integration could not observe the tool list;
+ * an empty array means the model had no tools. Callers who know better than
+ * the integration pass a `tools` override, which replaces the inferred list.
+ */
+declare const PROMPT_TOOLS_ATTRIBUTE = "ai.prompt.tools";
+type JsonSchema = Record<string, unknown>;
+type FunctionToolDeclaration = {
+    type: "function";
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+};
+type ProviderDefinedToolDeclaration = {
+    type: "provider-defined";
+    id?: string;
+    name: string;
+    args?: Record<string, unknown>;
+};
+type ToolDeclaration = FunctionToolDeclaration | ProviderDefinedToolDeclaration;
+/**
+ * What callers hand to a `tools` override. The canonical `ToolDeclaration`
+ * shape is accepted as-is; so is any framework shape `normalizeToolDeclarations`
+ * recognizes (OpenAI, Anthropic, Bedrock, LangChain, Pi, Mastra, AI SDK).
+ */
+type ToolDeclarationInput = ToolDeclaration | {
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+    parameters?: JsonSchema;
+};
+type PromptToolsOverride = ReadonlyArray<ToolDeclarationInput | unknown>;
+
 interface RaindropDeepAgentsHandlerOptions {
     eventShipper: EventShipper;
     traceShipper: TraceShipper;
@@ -517,6 +557,21 @@ 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;
+    /**
+     * Overrides the tool catalog recorded as `ai.prompt.tools` on every model
+     * span. Use when the integration cannot see the tools the model was given.
+     * Replaces the inferred list entirely; `[]` records an empty catalog.
+     */
+    tools?: PromptToolsOverride;
 }
 declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     name: string;
@@ -527,6 +582,9 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     private eventName?;
     private eventIdSource?;
     private traceChains;
+    private readonly configuredSpanMaxChars;
+    private readonly eventMaxChars;
+    private readonly promptTools;
     private spans;
     private rootRunIds;
     private eventIds;
@@ -539,13 +597,15 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
      */
     _lastRootEventId: string | undefined;
     constructor(opts: RaindropDeepAgentsHandlerOptions);
+    private promptToolsAttribute;
+    private get spanMaxChars();
     private getEventId;
     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>;
+    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>;
@@ -587,8 +647,22 @@ 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;
+    /**
+     * Overrides the tool catalog recorded as `ai.prompt.tools` on every model
+     * span. Use when the integration cannot see the tools the model was given.
+     */
+    tools?: PromptToolsOverride;
 }
 type RaindropDeepAgentsClient = {
     /**
@@ -676,4 +750,4 @@ type RaindropDeepAgentsClient = {
  */
 declare function createRaindropDeepAgents(opts: DeepAgentsOptions): RaindropDeepAgentsClient;
 
-export { type DeepAgentsOptions, type RaindropDeepAgentsClient, RaindropDeepAgentsHandler, createRaindropDeepAgents };
+export { type DeepAgentsOptions, PROMPT_TOOLS_ATTRIBUTE, type PromptToolsOverride, type RaindropDeepAgentsClient, RaindropDeepAgentsHandler, type ToolDeclaration, createRaindropDeepAgents };

package/dist/index.d.ts

@@ -509,6 +509,46 @@ declare global {
     var RAINDROP_ASYNC_LOCAL_STORAGE: (new <T>() => AsyncLocalStorageLike<T>) | undefined;
 }
 
+/**
+ * `ai.prompt.tools`: the tool catalog a model call was given, one JSON
+ * document per tool, in the shape the Vercel AI SDK records on its
+ * `doGenerate` / `doStream` spans. Every integration emits this attribute on
+ * its model-call spans so downstream consumers (agent replay, world builder)
+ * can read what the model could call instead of guessing from the calls it
+ * happened to make.
+ *
+ * An absent attribute means the integration could not observe the tool list;
+ * an empty array means the model had no tools. Callers who know better than
+ * the integration pass a `tools` override, which replaces the inferred list.
+ */
+declare const PROMPT_TOOLS_ATTRIBUTE = "ai.prompt.tools";
+type JsonSchema = Record<string, unknown>;
+type FunctionToolDeclaration = {
+    type: "function";
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+};
+type ProviderDefinedToolDeclaration = {
+    type: "provider-defined";
+    id?: string;
+    name: string;
+    args?: Record<string, unknown>;
+};
+type ToolDeclaration = FunctionToolDeclaration | ProviderDefinedToolDeclaration;
+/**
+ * What callers hand to a `tools` override. The canonical `ToolDeclaration`
+ * shape is accepted as-is; so is any framework shape `normalizeToolDeclarations`
+ * recognizes (OpenAI, Anthropic, Bedrock, LangChain, Pi, Mastra, AI SDK).
+ */
+type ToolDeclarationInput = ToolDeclaration | {
+    name: string;
+    description?: string;
+    inputSchema?: JsonSchema;
+    parameters?: JsonSchema;
+};
+type PromptToolsOverride = ReadonlyArray<ToolDeclarationInput | unknown>;
+
 interface RaindropDeepAgentsHandlerOptions {
     eventShipper: EventShipper;
     traceShipper: TraceShipper;
@@ -517,6 +557,21 @@ 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;
+    /**
+     * Overrides the tool catalog recorded as `ai.prompt.tools` on every model
+     * span. Use when the integration cannot see the tools the model was given.
+     * Replaces the inferred list entirely; `[]` records an empty catalog.
+     */
+    tools?: PromptToolsOverride;
 }
 declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     name: string;
@@ -527,6 +582,9 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
     private eventName?;
     private eventIdSource?;
     private traceChains;
+    private readonly configuredSpanMaxChars;
+    private readonly eventMaxChars;
+    private readonly promptTools;
     private spans;
     private rootRunIds;
     private eventIds;
@@ -539,13 +597,15 @@ declare class RaindropDeepAgentsHandler extends BaseCallbackHandler {
      */
     _lastRootEventId: string | undefined;
     constructor(opts: RaindropDeepAgentsHandlerOptions);
+    private promptToolsAttribute;
+    private get spanMaxChars();
     private getEventId;
     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>;
+    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>;
@@ -587,8 +647,22 @@ 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;
+    /**
+     * Overrides the tool catalog recorded as `ai.prompt.tools` on every model
+     * span. Use when the integration cannot see the tools the model was given.
+     */
+    tools?: PromptToolsOverride;
 }
 type RaindropDeepAgentsClient = {
     /**
@@ -676,4 +750,4 @@ type RaindropDeepAgentsClient = {
  */
 declare function createRaindropDeepAgents(opts: DeepAgentsOptions): RaindropDeepAgentsClient;
 
-export { type DeepAgentsOptions, type RaindropDeepAgentsClient, RaindropDeepAgentsHandler, createRaindropDeepAgents };
+export { type DeepAgentsOptions, PROMPT_TOOLS_ATTRIBUTE, type PromptToolsOverride, type RaindropDeepAgentsClient, RaindropDeepAgentsHandler, type ToolDeclaration, createRaindropDeepAgents };