illuma-agents 1.0.2 → 1.0.4

package/dist/types/agents/AgentContext.d.ts

@@ -0,0 +1,94 @@
+import { SystemMessage } from '@langchain/core/messages';
+import type { UsageMetadata, BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import type { createPruneMessages } from '@/messages';
+import { ContentTypes, Providers } from '@/common';
+/**
+ * Encapsulates agent-specific state that can vary between agents in a multi-agent system
+ */
+export declare class AgentContext {
+    /**
+     * Create an AgentContext from configuration with token accounting initialization
+     */
+    static fromConfig(agentConfig: t.AgentInputs, tokenCounter?: t.TokenCounter, indexTokenCountMap?: Record<string, number>): AgentContext;
+    /** Agent identifier */
+    agentId: string;
+    /** Provider for this specific agent */
+    provider: Providers;
+    /** Client options for this agent */
+    clientOptions?: t.ClientOptions;
+    /** Token count map indexed by message position */
+    indexTokenCountMap: Record<string, number | undefined>;
+    /** Maximum context tokens for this agent */
+    maxContextTokens?: number;
+    /** Current usage metadata for this agent */
+    currentUsage?: Partial<UsageMetadata>;
+    /** Prune messages function configured for this agent */
+    pruneMessages?: ReturnType<typeof createPruneMessages>;
+    /** Token counter function for this agent */
+    tokenCounter?: t.TokenCounter;
+    /** Instructions/system message token count */
+    instructionTokens: number;
+    /** The amount of time that should pass before another consecutive API call */
+    streamBuffer?: number;
+    /** Last stream call timestamp for rate limiting */
+    lastStreamCall?: number;
+    /** Tools available to this agent */
+    tools?: t.GraphTools;
+    /** Tool map for this agent */
+    toolMap?: t.ToolMap;
+    /** Instructions for this agent */
+    instructions?: string;
+    /** Additional instructions for this agent */
+    additionalInstructions?: string;
+    /** Reasoning key for this agent */
+    reasoningKey: 'reasoning_content' | 'reasoning';
+    /** Last token for reasoning detection */
+    lastToken?: string;
+    /** Token type switch state */
+    tokenTypeSwitch?: 'reasoning' | 'content';
+    /** Current token type being processed */
+    currentTokenType: ContentTypes.TEXT | ContentTypes.THINK | 'think_and_text';
+    /** Whether tools should end the workflow */
+    toolEnd: boolean;
+    /** System runnable for this agent */
+    systemRunnable?: Runnable<BaseMessage[], (BaseMessage | SystemMessage)[], RunnableConfig<Record<string, unknown>>>;
+    /** Promise for token calculation initialization */
+    tokenCalculationPromise?: Promise<void>;
+    /** Format content blocks as strings (for legacy compatibility) */
+    useLegacyContent: boolean;
+    constructor({ agentId, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, }: {
+        agentId: string;
+        provider: Providers;
+        clientOptions?: t.ClientOptions;
+        maxContextTokens?: number;
+        streamBuffer?: number;
+        tokenCounter?: t.TokenCounter;
+        tools?: t.GraphTools;
+        toolMap?: t.ToolMap;
+        instructions?: string;
+        additionalInstructions?: string;
+        reasoningKey?: 'reasoning_content' | 'reasoning';
+        toolEnd?: boolean;
+        instructionTokens?: number;
+        useLegacyContent?: boolean;
+    });
+    /**
+     * Create system runnable from instructions and calculate tokens if tokenCounter is available
+     */
+    private createSystemRunnable;
+    /**
+     * Reset context for a new run
+     */
+    reset(): void;
+    /**
+     * Update the token count map with instruction tokens
+     */
+    updateTokenMapWithInstructions(baseTokenMap: Record<string, number>): void;
+    /**
+     * Calculate tool tokens and add to instruction tokens
+     * Note: System message tokens are calculated during systemRunnable creation
+     */
+    calculateInstructionTokens(tokenCounter: t.TokenCounter): Promise<void>;
+}

package/dist/types/common/enum.d.ts

@@ -52,7 +52,6 @@ export declare enum GraphEvents {
 }
 export declare enum Providers {
     OPENAI = "openAI",
-    BEDROCK_LEGACY = "bedrock_legacy",
     VERTEXAI = "vertexai",
     BEDROCK = "bedrock",
     ANTHROPIC = "anthropic",
@@ -66,8 +65,9 @@ export declare enum Providers {
     XAI = "xai"
 }
 export declare enum GraphNodeKeys {
-    TOOLS = "tools",
-    AGENT = "agent",
+    TOOLS = "tools=",
+    AGENT = "agent=",
+    ROUTER = "router",
     PRE_TOOLS = "pre_tools",
     POST_TOOLS = "post_tools"
 }
@@ -109,13 +109,15 @@ export declare enum ToolCallTypes {
 export declare enum Callback {
     TOOL_ERROR = "handleToolError",
     TOOL_START = "handleToolStart",
-    TOOL_END = "handleToolEnd"
+    TOOL_END = "handleToolEnd",
+    CUSTOM_EVENT = "handleCustomEvent"
 }
 export declare enum Constants {
     OFFICIAL_CODE_BASEURL = "https://api.illuma.ai/v1",
     EXECUTE_CODE = "execute_code",
     WEB_SEARCH = "web_search",
-    CONTENT_AND_ARTIFACT = "content_and_artifact"
+    CONTENT_AND_ARTIFACT = "content_and_artifact",
+    LC_TRANSFER_TO_ = "lc_transfer_to_"
 }
 export declare enum TitleMethod {
     STRUCTURED = "structured",

package/dist/types/events.d.ts

@@ -1,5 +1,5 @@
 import type { UsageMetadata, BaseMessageFields } from '@langchain/core/messages';
-import type { Graph } from '@/graphs';
+import type { MultiAgentGraph, StandardGraph } from '@/graphs';
 import type * as t from '@/types';
 export declare class HandlerRegistry {
     private handlers;
@@ -9,13 +9,13 @@ export declare class HandlerRegistry {
 export declare class ModelEndHandler implements t.EventHandler {
     collectedUsage?: UsageMetadata[];
     constructor(collectedUsage?: UsageMetadata[]);
-    handle(event: string, data: t.ModelEndData, metadata?: Record<string, unknown>, graph?: Graph): void;
+    handle(event: string, data: t.ModelEndData, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): Promise<void>;
 }
 export declare class ToolEndHandler implements t.EventHandler {
     private callback?;
     private omitOutput?;
     constructor(callback?: t.ToolEndCallback, omitOutput?: (name?: string) => boolean);
-    handle(event: string, data: t.StreamEventData | undefined, metadata?: Record<string, unknown>, graph?: Graph): void;
+    handle(event: string, data: t.StreamEventData | undefined, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): Promise<void>;
 }
 export declare class TestLLMStreamHandler implements t.EventHandler {
     handle(event: string, data: t.StreamEventData | undefined): void;

package/dist/types/graphs/Graph.d.ts

@@ -1,29 +1,23 @@
 import { ToolNode } from '@langchain/langgraph/prebuilt';
-import { START } from '@langchain/langgraph';
 import { Runnable, RunnableConfig } from '@langchain/core/runnables';
-import { SystemMessage } from '@langchain/core/messages';
-import type { BaseMessage, UsageMetadata } from '@langchain/core/messages';
-import type * as t from '@/types';
-import { Providers, GraphNodeKeys, Callback, ContentTypes } from '@/common';
+import type { UsageMetadata, BaseMessage } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
+import type * as t from '@/types';
+import { Providers } from '@/common';
 import { ToolNode as CustomToolNode } from '@/tools/ToolNode';
-import { createPruneMessages } from '@/messages';
+import { AgentContext } from '@/agents/AgentContext';
 import { HandlerRegistry } from '@/events';
-export type GraphNode = GraphNodeKeys | typeof START;
-export type ClientCallback<T extends unknown[]> = (graph: StandardGraph, ...args: T) => void;
-export type ClientCallbacks = {
-    [Callback.TOOL_ERROR]?: ClientCallback<[Error, string]>;
-    [Callback.TOOL_START]?: ClientCallback<unknown[]>;
-    [Callback.TOOL_END]?: ClientCallback<unknown[]>;
-};
-export type SystemCallbacks = {
-    [K in keyof ClientCallbacks]: ClientCallbacks[K] extends ClientCallback<infer Args> ? (...args: Args) => void : never;
-};
-export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphState, TNodeName extends string = string> {
+export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphState, _TNodeName extends string = string> {
     abstract resetValues(): void;
-    abstract createGraphState(): t.GraphStateChannels<T>;
-    abstract initializeTools(): CustomToolNode<T> | ToolNode<T>;
-    abstract initializeModel(): Runnable;
+    abstract initializeTools({ currentTools, currentToolMap, }: {
+        currentTools?: t.GraphTools;
+        currentToolMap?: t.ToolMap;
+    }): CustomToolNode<T> | ToolNode<T>;
+    abstract initializeModel({ currentModel, tools, clientOptions, }: {
+        currentModel?: t.ChatModel;
+        tools?: t.GraphTools;
+        clientOptions?: t.ClientOptions;
+    }): Runnable;
     abstract getRunMessages(): BaseMessage[] | undefined;
     abstract getContentParts(): t.MessageContentComplex[] | undefined;
     abstract generateStepId(stepKey: string): [string, number];
@@ -32,17 +26,12 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     abstract checkKeyList(keyList: (string | number | undefined)[]): boolean;
     abstract getStepIdByKey(stepKey: string, index?: number): string;
     abstract getRunStep(stepId: string): t.RunStep | undefined;
-    abstract dispatchRunStep(stepKey: string, stepDetails: t.StepDetails): string;
-    abstract dispatchRunStepDelta(id: string, delta: t.ToolCallDelta): void;
-    abstract dispatchMessageDelta(id: string, delta: t.MessageDelta): void;
-    abstract dispatchReasoningDelta(stepId: string, delta: t.ReasoningDelta): void;
-    abstract handleToolCallCompleted(data: t.ToolEndData, metadata?: Record<string, unknown>, omitOutput?: boolean): void;
-    abstract createCallModel(): (state: T, config?: RunnableConfig) => Promise<Partial<T>>;
-    abstract createWorkflow(): t.CompiledWorkflow<T>;
-    lastToken?: string;
-    tokenTypeSwitch?: 'reasoning' | 'content';
-    reasoningKey: 'reasoning_content' | 'reasoning';
-    currentTokenType: ContentTypes.TEXT | ContentTypes.THINK | 'think_and_text';
+    abstract dispatchRunStep(stepKey: string, stepDetails: t.StepDetails): Promise<string>;
+    abstract dispatchRunStepDelta(id: string, delta: t.ToolCallDelta): Promise<void>;
+    abstract dispatchMessageDelta(id: string, delta: t.MessageDelta): Promise<void>;
+    abstract dispatchReasoningDelta(stepId: string, delta: t.ReasoningDelta): Promise<void>;
+    abstract handleToolCallCompleted(data: t.ToolEndData, metadata?: Record<string, unknown>, omitOutput?: boolean): Promise<void>;
+    abstract createCallModel(agentId?: string, currentModel?: t.ChatModel): (state: T, config?: RunnableConfig) => Promise<Partial<T>>;
     messageStepHasToolCalls: Map<string, boolean>;
     messageIdsByStepKey: Map<string, string>;
     prelimMessageIdsByStepKey: Map<string, string>;
@@ -51,36 +40,27 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     stepKeyIds: Map<string, string[]>;
     contentIndexMap: Map<string, number>;
     toolCallStepIds: Map<string, string>;
-    currentUsage: Partial<UsageMetadata> | undefined;
-    indexTokenCountMap: Record<string, number | undefined>;
-    maxContextTokens: number | undefined;
-    pruneMessages?: ReturnType<typeof createPruneMessages>;
-    /** The amount of time that should pass before another consecutive API call */
-    streamBuffer: number | undefined;
-    tokenCounter?: t.TokenCounter;
     signal?: AbortSignal;
     /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
     invokedToolIds?: Set<string>;
     handlerRegistry: HandlerRegistry | undefined;
 }
-export declare class StandardGraph extends Graph<t.BaseGraphState, GraphNode> {
-    private graphState;
-    clientOptions: t.ClientOptions;
-    boundModel?: Runnable;
-    /** The last recorded timestamp that a stream API call was invoked */
-    lastStreamCall: number | undefined;
-    systemMessage: SystemMessage | undefined;
+export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
+    overrideModel?: t.ChatModel;
+    /** Optional compile options passed into workflow.compile() */
+    compileOptions?: t.CompileOptions | undefined;
     messages: BaseMessage[];
     runId: string | undefined;
-    tools?: t.GraphTools;
-    toolMap?: t.ToolMap;
     startIndex: number;
-    provider: Providers;
-    toolEnd: boolean;
     signal?: AbortSignal;
-    constructor({ runId, tools, signal, toolMap, provider, streamBuffer, instructions, reasoningKey, clientOptions, toolEnd, additional_instructions, }: t.StandardGraphInput);
+    /** Map of agent contexts by agent ID */
+    agentContexts: Map<string, AgentContext>;
+    /** Default agent ID to use */
+    defaultAgentId: string;
+    constructor({ runId, signal, agents, tokenCounter, indexTokenCountMap, }: t.StandardGraphInput);
     resetValues(keepContent?: boolean): void;
     getRunStep(stepId: string): t.RunStep | undefined;
+    getAgentContext(metadata: Record<string, unknown> | undefined): AgentContext;
     getStepKey(metadata: Record<string, unknown> | undefined): string;
     getStepIdByKey(stepKey: string, index?: number): string;
     generateStepId(stepKey: string): [string, number];
@@ -88,35 +68,49 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, GraphNode> {
     checkKeyList(keyList: (string | number | undefined)[]): boolean;
     getRunMessages(): BaseMessage[] | undefined;
     getContentParts(): t.MessageContentComplex[] | undefined;
-    createGraphState(): t.GraphStateChannels<t.BaseGraphState>;
-    initializeTools(): CustomToolNode<t.BaseGraphState> | ToolNode<t.BaseGraphState>;
-    initializeModel(): Runnable;
+    createSystemRunnable({ provider, clientOptions, instructions, additional_instructions, }: {
+        provider?: Providers;
+        clientOptions?: t.ClientOptions;
+        instructions?: string;
+        additional_instructions?: string;
+    }): t.SystemRunnable | undefined;
+    initializeTools({ currentTools, currentToolMap, }: {
+        currentTools?: t.GraphTools;
+        currentToolMap?: t.ToolMap;
+    }): CustomToolNode<t.BaseGraphState> | ToolNode<t.BaseGraphState>;
+    initializeModel({ provider, tools, clientOptions, }: {
+        provider: Providers;
+        tools?: t.GraphTools;
+        clientOptions?: t.ClientOptions;
+    }): Runnable;
     overrideTestModel(responses: string[], sleep?: number, toolCalls?: ToolCall[]): void;
-    getNewModel({ provider, clientOptions, omitOptions, }: {
+    getNewModel({ provider, clientOptions, }: {
         provider: Providers;
         clientOptions?: t.ClientOptions;
-        omitOptions?: Set<string>;
     }): t.ChatModelInstance;
-    storeUsageMetadata(finalMessage?: BaseMessage): void;
-    cleanupSignalListener(): void;
-    createCallModel(): (state: t.BaseGraphState, config?: RunnableConfig) => Promise<Partial<t.BaseGraphState>>;
-    createWorkflow(): t.CompiledWorkflow<t.BaseGraphState>;
+    getUsageMetadata(finalMessage?: BaseMessage): Partial<UsageMetadata> | undefined;
+    /** Execute model invocation with streaming support */
+    private attemptInvoke;
+    cleanupSignalListener(currentModel?: t.ChatModel): void;
+    createCallModel(agentId?: string, currentModel?: t.ChatModel): (state: t.BaseGraphState, config?: RunnableConfig) => Promise<Partial<t.BaseGraphState>>;
+    createAgentNode(agentId: string): t.CompiledAgentWorfklow;
+    createWorkflow(): t.CompiledStateWorkflow;
     /**
      * Dispatches a run step to the client, returns the step ID
      */
-    dispatchRunStep(stepKey: string, stepDetails: t.StepDetails): string;
-    handleToolCallCompleted(data: t.ToolEndData, metadata?: Record<string, unknown>, omitOutput?: boolean): void;
+    dispatchRunStep(stepKey: string, stepDetails: t.StepDetails): Promise<string>;
+    handleToolCallCompleted(data: t.ToolEndData, metadata?: Record<string, unknown>, omitOutput?: boolean): Promise<void>;
     /**
      * Static version of handleToolCallError to avoid creating strong references
      * that prevent garbage collection
      */
-    static handleToolCallErrorStatic(graph: StandardGraph, data: t.ToolErrorData, metadata?: Record<string, unknown>): void;
+    static handleToolCallErrorStatic(graph: StandardGraph, data: t.ToolErrorData, metadata?: Record<string, unknown>): Promise<void>;
     /**
      * Instance method that delegates to the static method
      * Kept for backward compatibility
      */
-    handleToolCallError(data: t.ToolErrorData, metadata?: Record<string, unknown>): void;
-    dispatchRunStepDelta(id: string, delta: t.ToolCallDelta): void;
-    dispatchMessageDelta(id: string, delta: t.MessageDelta): void;
-    dispatchReasoningDelta: (stepId: string, delta: t.ReasoningDelta) => void;
+    handleToolCallError(data: t.ToolErrorData, metadata?: Record<string, unknown>): Promise<void>;
+    dispatchRunStepDelta(id: string, delta: t.ToolCallDelta): Promise<void>;
+    dispatchMessageDelta(id: string, delta: t.MessageDelta): Promise<void>;
+    dispatchReasoningDelta: (stepId: string, delta: t.ReasoningDelta) => Promise<void>;
 }

package/dist/types/graphs/MultiAgentGraph.d.ts

@@ -0,0 +1,47 @@
+import type * as t from '@/types';
+import { StandardGraph } from './Graph';
+/**
+ * MultiAgentGraph extends StandardGraph to support dynamic multi-agent workflows
+ * with handoffs, fan-in/fan-out, and other composable patterns.
+ *
+ * Key behavior:
+ * - Agents with ONLY handoff edges: Can dynamically route to any handoff destination
+ * - Agents with ONLY direct edges: Always follow their direct edges
+ * - Agents with BOTH: Use Command for exclusive routing (handoff OR direct, not both)
+ *   - If handoff occurs: Only the handoff destination executes
+ *   - If no handoff: Direct edges execute (potentially in parallel)
+ *
+ * This enables the common pattern where an agent either delegates (handoff)
+ * OR continues its workflow (direct edges), but not both simultaneously.
+ */
+export declare class MultiAgentGraph extends StandardGraph {
+    private edges;
+    private startingNodes;
+    private directEdges;
+    private handoffEdges;
+    constructor(input: t.MultiAgentGraphInput);
+    /**
+     * Categorize edges into handoff and direct types
+     */
+    private categorizeEdges;
+    /**
+     * Analyze graph structure to determine starting nodes and connections
+     */
+    private analyzeGraph;
+    /**
+     * Create handoff tools for agents based on handoff edges only
+     */
+    private createHandoffTools;
+    /**
+     * Create handoff tools for an edge (handles multiple destinations)
+     */
+    private createHandoffToolsForEdge;
+    /**
+     * Create a complete agent subgraph (similar to createReactAgent)
+     */
+    private createAgentSubgraph;
+    /**
+     * Create the multi-agent workflow with dynamic handoffs
+     */
+    createWorkflow(): t.CompiledMultiAgentWorkflow;
+}

package/dist/types/graphs/index.d.ts

@@ -1 +1,2 @@
 export * from './Graph';
+export * from './MultiAgentGraph';

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@ export * from './splitStream';
 export * from './events';
 export * from './messages';
 export * from './graphs';
+export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
 export * from './tools/handlers';
 export * from './tools/search';

package/dist/types/llm/openai/index.d.ts

@@ -40,6 +40,10 @@ export declare class CustomAzureOpenAIClient extends AzureOpenAIClient {
 }
 /** @ts-expect-error We are intentionally overriding `getReasoningParams` */
 export declare class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptions> {
+    _lc_stream_delay?: number;
+    constructor(fields?: t.ChatOpenAICallOptions & {
+        _lc_stream_delay?: number;
+    } & t.OpenAIChatInput['modelKwargs']);
     get exposedClient(): CustomOpenAIClient;
     static lc_name(): string;
     protected _getClientOptions(options?: OpenAICoreRequestOptions): OpenAICoreRequestOptions;
@@ -54,6 +58,10 @@ export declare class ChatOpenAI extends OriginalChatOpenAI<t.ChatOpenAICallOptio
 }
 /** @ts-expect-error We are intentionally overriding `getReasoningParams` */
 export declare class AzureChatOpenAI extends OriginalAzureChatOpenAI {
+    _lc_stream_delay?: number;
+    constructor(fields?: t.AzureOpenAIInput & {
+        _lc_stream_delay?: number;
+    });
     get exposedClient(): CustomOpenAIClient;
     static lc_name(): 'IllumaAzureOpenAI';
     /**
@@ -87,6 +95,7 @@ export interface XAIUsageMetadata extends OpenAIClient.Completions.CompletionUsa
     num_sources_used?: number;
 }
 export declare class ChatXAI extends OriginalChatXAI {
+    _lc_stream_delay?: number;
     constructor(fields?: Partial<ChatXAIInput> & {
         configuration?: {
             baseURL?: string;
@@ -94,6 +103,7 @@ export declare class ChatXAI extends OriginalChatXAI {
         clientConfig?: {
             baseURL?: string;
         };
+        _lc_stream_delay?: number;
     });
     static lc_name(): 'IllumaXAI';
     get exposedClient(): CustomOpenAIClient;

package/dist/types/messages/cache.d.ts

@@ -0,0 +1,20 @@
+import { BaseMessage, MessageContentComplex } from '@langchain/core/messages';
+import type { AnthropicMessage } from '@/types/messages';
+type MessageWithContent = {
+    content?: string | MessageContentComplex[];
+};
+/**
+ * Anthropic API: Adds cache control to the appropriate user messages in the payload.
+ * @param messages - The array of message objects.
+ * @returns - The updated array of message objects with cache control added.
+ */
+export declare function addCacheControl<T extends AnthropicMessage | BaseMessage>(messages: T[]): T[];
+/**
+ * Adds Bedrock Converse API cache points to the last two messages.
+ * Inserts `{ cachePoint: { type: 'default' } }` as a separate content block
+ * immediately after the last text block in each targeted message.
+ * @param messages - The array of message objects.
+ * @returns - The updated array of message objects with cache points added.
+ */
+export declare function addBedrockCacheControl<T extends Partial<BaseMessage> & MessageWithContent>(messages: T[]): T[];
+export {};

package/dist/types/messages/content.d.ts

@@ -0,0 +1,7 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Formats an array of messages for LangChain, making sure all content fields are strings
+ * @param {Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>} payload - The array of messages to format.
+ * @returns {Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>} - The array of formatted LangChain messages, including ToolMessages for tool calls.
+ */
+export declare const formatContentStrings: (payload: Array<BaseMessage>) => Array<BaseMessage>;

package/dist/types/messages/format.d.ts

@@ -1,4 +1,4 @@
-import { AIMessage, ToolMessage, BaseMessage, HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { AIMessage, ToolMessage, HumanMessage, SystemMessage } from '@langchain/core/messages';
 import type { MessageContentImageUrl } from '@langchain/core/messages';
 import type { MessageContentComplex, TPayload } from '@/types';
 import { Providers } from '@/common';
@@ -95,12 +95,6 @@ export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap
     messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
     indexTokenCountMap?: Record<number, number>;
 };
-/**
- * Formats an array of messages for LangChain, making sure all content fields are strings
- * @param payload - The array of messages to format.
- * @returns - The array of formatted LangChain messages, including ToolMessages for tool calls.
- */
-export declare const formatContentStrings: (payload: Array<BaseMessage>) => Array<BaseMessage>;
 /**
  * Adds a value at key 0 for system messages and shifts all key indices by one in an indexTokenCountMap.
  * This is useful when adding a system message at the beginning of a conversation.

package/dist/types/messages/index.d.ts

@@ -2,3 +2,5 @@ export * from './core';
 export * from './ids';
 export * from './prune';
 export * from './format';
+export * from './cache';
+export * from './content';

package/dist/types/messages/reducer.d.ts

@@ -0,0 +1,9 @@
+import { BaseMessage, BaseMessageLike } from '@langchain/core/messages';
+export declare const REMOVE_ALL_MESSAGES = "__remove_all__";
+export type Messages = Array<BaseMessage | BaseMessageLike> | BaseMessage | BaseMessageLike;
+/**
+ * Prebuilt reducer that combines returned messages.
+ * Can handle standard messages and special modifiers like {@link RemoveMessage}
+ * instances.
+ */
+export declare function messagesStateReducer(left: Messages, right: Messages): BaseMessage[];

package/dist/types/run.d.ts

@@ -1,29 +1,35 @@
 import './instrumentation';
 import type { MessageContentComplex, BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
-import type { ClientCallbacks, SystemCallbacks } from '@/graphs/Graph';
 import type * as t from '@/types';
-import { Providers } from '@/common';
+import { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import { StandardGraph } from '@/graphs/Graph';
 export declare const defaultOmitOptions: Set<string>;
-export declare class Run<T extends t.BaseGraphState> {
-    graphRunnable?: t.CompiledWorkflow<T, Partial<T>, string>;
-    private handlerRegistry;
+export declare class Run<_T extends t.BaseGraphState> {
     id: string;
-    Graph: StandardGraph | undefined;
-    provider: Providers | undefined;
+    private tokenCounter?;
+    private handlerRegistry?;
+    private indexTokenCountMap?;
+    graphRunnable?: t.CompiledStateWorkflow;
+    Graph: StandardGraph | MultiAgentGraph | undefined;
     returnContent: boolean;
     private constructor();
-    private createStandardGraph;
+    private createLegacyGraph;
+    private createMultiAgentGraph;
     static create<T extends t.BaseGraphState>(config: t.RunConfig): Promise<Run<T>>;
     getRunMessages(): BaseMessage[] | undefined;
+    /**
+     * Creates a custom event callback handler that intercepts custom events
+     * and processes them through our handler registry instead of EventStreamCallbackHandler
+     */
+    private createCustomEventCallback;
     processStream(inputs: t.IState, config: Partial<RunnableConfig> & {
         version: 'v1' | 'v2';
         run_id?: string;
     }, streamOptions?: t.EventStreamOptions): Promise<MessageContentComplex[] | undefined>;
     private createSystemCallback;
-    getCallbacks(clientCallbacks: ClientCallbacks): SystemCallbacks;
-    generateTitle({ provider, inputText, contentParts, titlePrompt, clientOptions, chainOptions, skipLanguage, omitOptions, titleMethod, titlePromptTemplate, }: t.RunTitleOptions): Promise<{
+    getCallbacks(clientCallbacks: t.ClientCallbacks): t.SystemCallbacks;
+    generateTitle({ provider, inputText, contentParts, titlePrompt, clientOptions, chainOptions, skipLanguage, titleMethod, titlePromptTemplate, }: t.RunTitleOptions): Promise<{
         language?: string;
         title?: string;
     }>;

package/dist/types/stream.d.ts

@@ -1,5 +1,6 @@
 import type { AIMessageChunk } from '@langchain/core/messages';
-import type { Graph } from '@/graphs';
+import type { AgentContext } from '@/agents/AgentContext';
+import type { StandardGraph } from '@/graphs';
 import type * as t from '@/types';
 import { Providers } from '@/common';
 export declare function getChunkContent({ chunk, provider, reasoningKey, }: {
@@ -8,7 +9,7 @@ export declare function getChunkContent({ chunk, provider, reasoningKey, }: {
     reasoningKey: 'reasoning_content' | 'reasoning';
 }): string | t.MessageContentComplex[] | undefined;
 export declare class ChatModelStreamHandler implements t.EventHandler {
-    handle(event: string, data: t.StreamEventData, metadata?: Record<string, unknown>, graph?: Graph): void;
-    handleReasoning(chunk: Partial<AIMessageChunk>, graph: Graph, provider?: Providers): void;
+    handle(event: string, data: t.StreamEventData, metadata?: Record<string, unknown>, graph?: StandardGraph): Promise<void>;
+    handleReasoning(chunk: Partial<AIMessageChunk>, agentContext: AgentContext): void;
 }
 export declare function createContentAggregator(): t.ContentAggregatorResult;

package/dist/types/tools/Calculator.d.ts

@@ -0,0 +1,8 @@
+import { Tool } from '@langchain/core/tools';
+export declare class Calculator extends Tool {
+    static lc_name(): string;
+    get lc_namespace(): string[];
+    name: string;
+    _call(input: string): Promise<string>;
+    description: string;
+}

package/dist/types/tools/ToolNode.d.ts

@@ -19,4 +19,4 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     getToolUsageCounts(): ReadonlyMap<string, number>;
     protected run(input: any, config: RunnableConfig): Promise<T>;
 }
-export declare function toolsCondition(state: BaseMessage[] | typeof MessagesAnnotation.State, invokedToolIds?: Set<string>): 'tools' | typeof END;
+export declare function toolsCondition<T extends string>(state: BaseMessage[] | typeof MessagesAnnotation.State, toolNode: T, invokedToolIds?: Set<string>): T | typeof END;

package/dist/types/tools/handlers.d.ts

@@ -1,19 +1,21 @@
 import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
-import type { Graph } from '@/graphs';
+import type { MultiAgentGraph, StandardGraph } from '@/graphs';
+import type { AgentContext } from '@/agents/AgentContext';
 import type * as t from '@/types';
 export declare function handleToolCallChunks({ graph, stepKey, toolCallChunks, }: {
-    graph: Graph;
+    graph: StandardGraph | MultiAgentGraph;
     stepKey: string;
     toolCallChunks: ToolCallChunk[];
-}): void;
-export declare const handleToolCalls: (toolCalls?: ToolCall[], metadata?: Record<string, unknown>, graph?: Graph) => void;
+}): Promise<void>;
+export declare const handleToolCalls: (toolCalls?: ToolCall[], metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph) => Promise<void>;
 export declare const toolResultTypes: Set<string>;
 /**
  * Handles the result of a server tool call; in other words, a provider's built-in tool.
  * As of 2025-07-06, only Anthropic handles server tool calls with this pattern.
  */
-export declare function handleServerToolResult({ content, metadata, graph, }: {
+export declare function handleServerToolResult({ graph, content, metadata, agentContext, }: {
+    graph: StandardGraph | MultiAgentGraph;
     content?: string | t.MessageContentComplex[];
     metadata?: Record<string, unknown>;
-    graph: Graph;
-}): boolean;
+    agentContext?: AgentContext;
+}): Promise<boolean>;

package/dist/types/tools/search/tool.d.ts

@@ -39,16 +39,16 @@ export declare const createSearchTool: (config?: t.SearchToolConfig) => DynamicS
     news: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     query: string;
-    date?: DATE_RANGE | undefined;
-    images?: boolean | undefined;
     videos?: boolean | undefined;
+    images?: boolean | undefined;
     news?: boolean | undefined;
+    date?: DATE_RANGE | undefined;
     country?: unknown;
 }, {
     query: string;
-    date?: DATE_RANGE | undefined;
-    images?: boolean | undefined;
     videos?: boolean | undefined;
+    images?: boolean | undefined;
     news?: boolean | undefined;
+    date?: DATE_RANGE | undefined;
     country?: unknown;
 }>>;