@librechat/agents 3.1.57 → 3.1.60

package/dist/esm/utils/truncation.mjs

@@ -0,0 +1,102 @@
+/**
+ * Ingestion-time and pre-flight truncation utilities for tool results.
+ *
+ * Prevents oversized tool outputs from entering the message array and
+ * consuming the entire context window.
+ */
+/**
+ * Absolute hard cap on tool result length (characters).
+ * Even if the model has a 1M-token context, a single tool result
+ * larger than this is almost certainly a bug (e.g., dumping a binary file).
+ */
+const HARD_MAX_TOOL_RESULT_CHARS = 400_000;
+/**
+ * Computes the dynamic max tool result size based on the model's context window.
+ * Uses 30% of the context window (in estimated characters, ~4 chars/token)
+ * capped at HARD_MAX_TOOL_RESULT_CHARS.
+ *
+ * @param contextWindowTokens - The model's max context tokens (optional).
+ * @returns Maximum allowed characters for a single tool result.
+ */
+function calculateMaxToolResultChars(contextWindowTokens) {
+    if (contextWindowTokens == null || contextWindowTokens <= 0) {
+        return HARD_MAX_TOOL_RESULT_CHARS;
+    }
+    return Math.min(Math.floor(contextWindowTokens * 0.3) * 4, HARD_MAX_TOOL_RESULT_CHARS);
+}
+/**
+ * Truncates a tool-call input (the arguments/payload of a tool_use block)
+ * using head+tail strategy. Returns an object with `_truncated` (the
+ * truncated string) and `_originalChars` (for diagnostics).
+ *
+ * Accepts any type — objects are JSON-serialized before truncation.
+ *
+ * @param input - The tool input (string, object, etc.).
+ * @param maxChars - Maximum allowed characters.
+ */
+function truncateToolInput(input, maxChars) {
+    const serialized = typeof input === 'string' ? input : JSON.stringify(input);
+    if (serialized.length <= maxChars) {
+        return { _truncated: serialized, _originalChars: serialized.length };
+    }
+    const indicator = `\n… [truncated: ${serialized.length} chars exceeded ${maxChars} limit] …\n`;
+    const available = maxChars - indicator.length;
+    if (available < 100) {
+        return {
+            _truncated: serialized.slice(0, maxChars) + indicator.trimEnd(),
+            _originalChars: serialized.length,
+        };
+    }
+    const headSize = Math.ceil(available * 0.7);
+    const tailSize = available - headSize;
+    return {
+        _truncated: serialized.slice(0, headSize) +
+            indicator +
+            serialized.slice(serialized.length - tailSize),
+        _originalChars: serialized.length,
+    };
+}
+/**
+ * Truncates tool result content that exceeds `maxChars` using a head+tail
+ * strategy. Keeps the beginning (structure/headers) and end (return value /
+ * conclusion) of the content so the model retains both the opening context
+ * and the final outcome.
+ *
+ * Head gets ~70% of the budget, tail gets ~30%. Falls back to head-only
+ * when the budget is too small for a meaningful tail.
+ *
+ * @param content - The tool result string content.
+ * @param maxChars - Maximum allowed characters.
+ * @returns The (possibly truncated) content string.
+ */
+function truncateToolResultContent(content, maxChars) {
+    if (content.length <= maxChars) {
+        return content;
+    }
+    const indicator = `\n\n… [truncated: ${content.length} chars exceeded ${maxChars} limit] …\n\n`;
+    const available = maxChars - indicator.length;
+    if (available <= 0) {
+        return content.slice(0, maxChars);
+    }
+    // When budget is too small for a meaningful tail, fall back to head-only
+    if (available < 200) {
+        return content.slice(0, available) + indicator.trimEnd();
+    }
+    const headSize = Math.ceil(available * 0.7);
+    const tailSize = available - headSize;
+    // Try to break at newline boundaries for cleaner output
+    let headEnd = headSize;
+    const headNewline = content.lastIndexOf('\n', headSize);
+    if (headNewline > headSize - 200 && headNewline > 0) {
+        headEnd = headNewline;
+    }
+    let tailStart = content.length - tailSize;
+    const tailNewline = content.indexOf('\n', tailStart);
+    if (tailNewline > 0 && tailNewline < tailStart + 200) {
+        tailStart = tailNewline + 1;
+    }
+    return content.slice(0, headEnd) + indicator + content.slice(tailStart);
+}
+
+export { HARD_MAX_TOOL_RESULT_CHARS, calculateMaxToolResultChars, truncateToolInput, truncateToolResultContent };
+//# sourceMappingURL=truncation.mjs.map

package/dist/esm/utils/truncation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncation.mjs","sources":["../../../src/utils/truncation.ts"],"sourcesContent":["/**\n * Ingestion-time and pre-flight truncation utilities for tool results.\n *\n * Prevents oversized tool outputs from entering the message array and\n * consuming the entire context window.\n */\n\n/**\n * Absolute hard cap on tool result length (characters).\n * Even if the model has a 1M-token context, a single tool result\n * larger than this is almost certainly a bug (e.g., dumping a binary file).\n */\nexport const HARD_MAX_TOOL_RESULT_CHARS = 400_000;\n\n/**\n * Computes the dynamic max tool result size based on the model's context window.\n * Uses 30% of the context window (in estimated characters, ~4 chars/token)\n * capped at HARD_MAX_TOOL_RESULT_CHARS.\n *\n * @param contextWindowTokens - The model's max context tokens (optional).\n * @returns Maximum allowed characters for a single tool result.\n */\nexport function calculateMaxToolResultChars(\n  contextWindowTokens?: number\n): number {\n  if (contextWindowTokens == null || contextWindowTokens <= 0) {\n    return HARD_MAX_TOOL_RESULT_CHARS;\n  }\n  return Math.min(\n    Math.floor(contextWindowTokens * 0.3) * 4,\n    HARD_MAX_TOOL_RESULT_CHARS\n  );\n}\n\n/**\n * Truncates a tool-call input (the arguments/payload of a tool_use block)\n * using head+tail strategy. Returns an object with `_truncated` (the\n * truncated string) and `_originalChars` (for diagnostics).\n *\n * Accepts any type — objects are JSON-serialized before truncation.\n *\n * @param input - The tool input (string, object, etc.).\n * @param maxChars - Maximum allowed characters.\n */\nexport function truncateToolInput(\n  input: unknown,\n  maxChars: number\n): { _truncated: string; _originalChars: number } {\n  const serialized = typeof input === 'string' ? input : JSON.stringify(input);\n  if (serialized.length <= maxChars) {\n    return { _truncated: serialized, _originalChars: serialized.length };\n  }\n  const indicator = `\\n… [truncated: ${serialized.length} chars exceeded ${maxChars} limit] …\\n`;\n  const available = maxChars - indicator.length;\n\n  if (available < 100) {\n    return {\n      _truncated: serialized.slice(0, maxChars) + indicator.trimEnd(),\n      _originalChars: serialized.length,\n    };\n  }\n\n  const headSize = Math.ceil(available * 0.7);\n  const tailSize = available - headSize;\n\n  return {\n    _truncated:\n      serialized.slice(0, headSize) +\n      indicator +\n      serialized.slice(serialized.length - tailSize),\n    _originalChars: serialized.length,\n  };\n}\n\n/**\n * Truncates tool result content that exceeds `maxChars` using a head+tail\n * strategy. Keeps the beginning (structure/headers) and end (return value /\n * conclusion) of the content so the model retains both the opening context\n * and the final outcome.\n *\n * Head gets ~70% of the budget, tail gets ~30%. Falls back to head-only\n * when the budget is too small for a meaningful tail.\n *\n * @param content - The tool result string content.\n * @param maxChars - Maximum allowed characters.\n * @returns The (possibly truncated) content string.\n */\nexport function truncateToolResultContent(\n  content: string,\n  maxChars: number\n): string {\n  if (content.length <= maxChars) {\n    return content;\n  }\n\n  const indicator = `\\n\\n… [truncated: ${content.length} chars exceeded ${maxChars} limit] …\\n\\n`;\n  const available = maxChars - indicator.length;\n  if (available <= 0) {\n    return content.slice(0, maxChars);\n  }\n\n  // When budget is too small for a meaningful tail, fall back to head-only\n  if (available < 200) {\n    return content.slice(0, available) + indicator.trimEnd();\n  }\n\n  const headSize = Math.ceil(available * 0.7);\n  const tailSize = available - headSize;\n\n  // Try to break at newline boundaries for cleaner output\n  let headEnd = headSize;\n  const headNewline = content.lastIndexOf('\\n', headSize);\n  if (headNewline > headSize - 200 && headNewline > 0) {\n    headEnd = headNewline;\n  }\n\n  let tailStart = content.length - tailSize;\n  const tailNewline = content.indexOf('\\n', tailStart);\n  if (tailNewline > 0 && tailNewline < tailStart + 200) {\n    tailStart = tailNewline + 1;\n  }\n\n  return content.slice(0, headEnd) + indicator + content.slice(tailStart);\n}\n"],"names":[],"mappings":"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"}

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

@@ -28,12 +28,42 @@ export declare class AgentContext {
     maxContextTokens?: number;
     /** Current usage metadata for this agent */
     currentUsage?: Partial<UsageMetadata>;
+    /**
+     * Usage from the most recent LLM call only (not accumulated).
+     * Used for accurate provider calibration in pruning.
+     */
+    lastCallUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheRead?: number;
+        cacheCreation?: number;
+    };
+    /**
+     * Whether totalTokens data is fresh (set true when provider usage arrives,
+     * false at the start of each turn before the LLM responds).
+     * Prevents stale token data from driving pruning/trigger decisions.
+     */
+    totalTokensFresh: boolean;
+    /** Context pruning configuration. */
+    contextPruningConfig?: t.ContextPruningConfig;
+    maxToolResultChars?: number;
     /** 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;
+    /** Token count for the system message (instructions text). */
+    systemMessageTokens: number;
+    /** Token count for tool schemas only. */
+    toolSchemaTokens: number;
+    /** Running calibration ratio from the pruner — persisted across runs via contextMeta. */
+    calibrationRatio: number;
+    /** Provider-observed instruction overhead from the pruner's best-variance turn. */
+    resolvedInstructionOverhead?: number;
+    /** Pre-masking tool content keyed by message index, consumed by the summarize node. */
+    pendingOriginalToolContent?: Map<number, string>;
+    /** Total instruction overhead: system message + tool schemas + pending summary. */
+    get instructionTokens(): number;
     /** The amount of time that should pass before another consecutive API call */
     streamBuffer?: number;
     /** Last stream call timestamp for rate limiting */
@@ -76,12 +106,41 @@ export declare class AgentContext {
     private cachedSystemRunnable?;
     /** Whether system runnable needs rebuild (set when discovered tools change) */
     private systemRunnableStale;
-    /** Cached system message token count (separate from tool tokens) */
-    private systemMessageTokens;
     /** Promise for token calculation initialization */
     tokenCalculationPromise?: Promise<void>;
     /** Format content blocks as strings (for legacy compatibility) */
     useLegacyContent: boolean;
+    /** Enables graph-level summarization for this agent */
+    summarizationEnabled?: boolean;
+    /** Summarization runtime settings used by graph pruning hooks */
+    summarizationConfig?: t.SummarizationConfig;
+    /** Current summary text produced by the summarize node, integrated into system message */
+    private summaryText?;
+    /** Token count of the current summary (tracked for token accounting) */
+    private summaryTokenCount;
+    /**
+     * Where the summary should be injected:
+     * - `'system_prompt'`: cross-run summary, included in `buildInstructionsString`
+     * - `'user_message'`: mid-run compaction, injected as HumanMessage on clean slate
+     * - `'none'`: no summary present
+     */
+    private _summaryLocation;
+    /**
+     * Durable summary that survives reset() calls. Set from initialSummary
+     * during fromConfig() and updated by setSummary() so that the latest
+     * summary (whether cross-run or intra-run) is always restored after
+     * processStream's resetValues() cycle.
+     */
+    private _durableSummaryText?;
+    private _durableSummaryTokenCount;
+    /** Number of summarization cycles that have occurred for this agent context */
+    private _summaryVersion;
+    /**
+     * Message count at the time summarization was last triggered.
+     * Used to prevent re-summarizing the same unchanged message set.
+     * Summarization is allowed to fire again only when new messages appear.
+     */
+    private _lastSummarizationMsgCount;
     /**
      * Handoff context when this agent receives control via handoff.
      * Contains source and parallel execution info for system message context.
@@ -92,7 +151,7 @@ export declare class AgentContext {
         /** Names of sibling agents executing in parallel (empty if sequential) */
         parallelSiblings: string[];
     };
-    constructor({ agentId, name, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, discoveredTools, }: {
+    constructor({ agentId, name, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, discoveredTools, summarizationEnabled, summarizationConfig, contextPruningConfig, maxToolResultChars, }: {
         agentId: string;
         name?: string;
         provider: Providers;
@@ -111,6 +170,10 @@ export declare class AgentContext {
         instructionTokens?: number;
         useLegacyContent?: boolean;
         discoveredTools?: string[];
+        summarizationEnabled?: boolean;
+        summarizationConfig?: t.SummarizationConfig;
+        contextPruningConfig?: t.ContextPruningConfig;
+        maxToolResultChars?: number;
     });
     /**
      * Builds instructions text for tools that are ONLY callable via programmatic code execution.
@@ -153,7 +216,18 @@ export declare class AgentContext {
      */
     reset(): void;
     /**
-     * Update the token count map with instruction tokens
+     * Update the token count map from a base map.
+     *
+     * Previously this inflated index 0 with instructionTokens to indirectly
+     * reserve budget for the system prompt.  That approach was imprecise: with
+     * large tool-schema overhead (e.g. 26 MCP tools ~5 000 tokens) the first
+     * conversation message appeared enormous and was always pruned, while the
+     * real available budget was never explicitly computed.
+     *
+     * Now instruction tokens are passed to getMessagesWithinTokenLimit via
+     * the `getInstructionTokens` factory param so the pruner subtracts them
+     * from the budget directly.  The token map contains only real per-message
+     * token counts.
      */
     updateTokenMapWithInstructions(baseTokenMap: Record<string, number>): void;
     /**
@@ -180,6 +254,50 @@ export declare class AgentContext {
      * Call this when resetting the agent or when handoff context is no longer relevant.
      */
     clearHandoffContext(): void;
+    setSummary(text: string, tokenCount: number): void;
+    /** Sets a cross-run summary that is injected into the system prompt. */
+    setInitialSummary(text: string, tokenCount: number): void;
+    /**
+     * Replaces the indexTokenCountMap with a fresh map keyed to the surviving
+     * context messages after summarization.  Called by the summarize node after
+     * it emits RemoveMessage operations that shift message indices.
+     */
+    rebuildTokenMapAfterSummarization(newTokenMap: Record<string, number>): void;
+    hasSummary(): boolean;
+    /** True when a mid-run compaction summary is ready to be injected as a HumanMessage. */
+    hasPendingCompactionSummary(): boolean;
+    getSummaryText(): string | undefined;
+    get summaryVersion(): number;
+    /**
+     * Returns true when the message count hasn't changed since the last
+     * summarization — re-summarizing would produce an identical result.
+     * Oversized individual messages are handled by fit-to-budget truncation
+     * in the pruner, which keeps them in context without triggering overflow.
+     */
+    shouldSkipSummarization(currentMsgCount: number): boolean;
+    /**
+     * Records the message count at which summarization was triggered,
+     * so subsequent calls with the same count are suppressed.
+     */
+    markSummarizationTriggered(msgCount: number): void;
+    clearSummary(): void;
+    /**
+     * Returns a structured breakdown of how the context token budget is consumed.
+     * Useful for diagnostics when context overflow or pruning issues occur.
+     */
+    getTokenBudgetBreakdown(messages?: BaseMessage[]): t.TokenBudgetBreakdown;
+    /**
+     * Returns a human-readable string of the token budget breakdown
+     * for inclusion in error messages and diagnostics.
+     */
+    formatTokenBudgetBreakdown(messages?: BaseMessage[]): string;
+    /**
+     * Updates the last-call usage with data from the most recent LLM response.
+     * Unlike `currentUsage` which accumulates, this captures only the single call.
+     */
+    updateLastCallUsage(usage: Partial<UsageMetadata>): void;
+    /** Marks token data as stale before a new LLM call. */
+    markTokensStale(): void;
     /**
      * Marks tools as discovered via tool search.
      * Discovered tools will be included in the next model binding.

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

@@ -19,6 +19,14 @@ export declare enum GraphEvents {
     ON_REASONING_DELTA = "on_reasoning_delta",
     /** [Custom] Request to execute tools - dispatched by ToolNode, handled by host */
     ON_TOOL_EXECUTE = "on_tool_execute",
+    /** [Custom] Emitted when the summarize node begins generating a summary */
+    ON_SUMMARIZE_START = "on_summarize_start",
+    /** [Custom] Delta event carrying the completed summary content */
+    ON_SUMMARIZE_DELTA = "on_summarize_delta",
+    /** [Custom] Emitted when the summarize node completes with the final summary */
+    ON_SUMMARIZE_COMPLETE = "on_summarize_complete",
+    /** [Custom] Diagnostic logging event for context management observability */
+    ON_AGENT_LOG = "on_agent_log",
     /** Custom event, emitted by system */
     ON_CUSTOM_EVENT = "on_custom_event",
     /** Emitted when a chat model starts processing. */
@@ -69,6 +77,7 @@ export declare enum Providers {
 export declare enum GraphNodeKeys {
     TOOLS = "tools=",
     AGENT = "agent=",
+    SUMMARIZE = "summarize=",
     ROUTER = "router",
     PRE_TOOLS = "pre_tools",
     POST_TOOLS = "post_tools"
@@ -98,6 +107,8 @@ export declare enum ContentTypes {
     REASONING = "reasoning",
     /** Multi-Agent Switch */
     AGENT_UPDATE = "agent_update",
+    /** Framework-level conversation summary block */
+    SUMMARY = "summary",
     /** Bedrock */
     REASONING_CONTENT = "reasoning_content"
 }
@@ -123,7 +134,9 @@ export declare enum Constants {
     CONTENT_AND_ARTIFACT = "content_and_artifact",
     LC_TRANSFER_TO_ = "lc_transfer_to_",
     /** Delimiter for MCP tools: toolName_mcp_serverName */
-    MCP_DELIMITER = "_mcp_"
+    MCP_DELIMITER = "_mcp_",
+    /** Anthropic server tool ID prefix (web_search, code_execution, etc.) */
+    ANTHROPIC_SERVER_TOOL_PREFIX = "srvtoolu_"
 }
 export declare enum TitleMethod {
     STRUCTURED = "structured",

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

@@ -1,9 +1,8 @@
 import { ToolNode } from '@langchain/langgraph/prebuilt';
-import { Runnable, RunnableConfig } from '@langchain/core/runnables';
+import { RunnableConfig } from '@langchain/core/runnables';
 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 { AgentContext } from '@/agents/AgentContext';
 import { HandlerRegistry } from '@/events';
@@ -13,11 +12,6 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
         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];
@@ -30,7 +24,7 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     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 createCallModel(agentId?: string, currentModel?: t.ChatModel): (state: T, config?: RunnableConfig) => Promise<Partial<T>>;
+    abstract createCallModel(agentId?: string, currentModel?: t.ChatModel): (state: t.AgentSubgraphState, config?: RunnableConfig) => Promise<Partial<t.AgentSubgraphState>>;
     messageStepHasToolCalls: Map<string, boolean>;
     messageIdsByStepKey: Map<string, string>;
     prelimMessageIdsByStepKey: Map<string, string>;
@@ -39,6 +33,12 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     stepKeyIds: Map<string, string[]>;
     contentIndexMap: Map<string, number>;
     toolCallStepIds: Map<string, string>;
+    /**
+     * Step IDs that have been dispatched via handler registry directly
+     * (in dispatchRunStep).  Used by the custom event callback to skip
+     * duplicate dispatch through the LangGraph callback chain.
+     */
+    handlerDispatchedStepIds: Set<string>;
     signal?: AbortSignal;
     /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
     invokedToolIds?: Set<string>;
@@ -61,14 +61,23 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     /** Optional compile options passed into workflow.compile() */
     compileOptions?: t.CompileOptions | undefined;
     messages: BaseMessage[];
+    /** Cached run messages preserved before clearHeavyState() so getRunMessages() works after cleanup. */
+    private cachedRunMessages?;
     runId: string | undefined;
+    /**
+     * Boundary between historical messages (loaded from conversation state)
+     * and messages produced during the current run.  Set once in the state
+     * reducer when messages first arrive.  Used by `getRunMessages()` and
+     * multi-agent message filtering — NOT for pruner token counting (the
+     * pruner maintains its own `lastTurnStartIndex` in its closure).
+     */
     startIndex: number;
     signal?: AbortSignal;
     /** 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);
+    constructor({ runId, signal, agents, tokenCounter, indexTokenCountMap, calibrationRatio, }: t.StandardGraphInput);
     resetValues(keepContent?: boolean): void;
     clearHeavyState(): void;
     getRunStep(stepId: string): t.RunStep | undefined;
@@ -80,6 +89,9 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     checkKeyList(keyList: (string | number | undefined)[]): boolean;
     getRunMessages(): BaseMessage[] | undefined;
     getContentParts(): t.MessageContentComplex[] | undefined;
+    getCalibrationRatio(): number;
+    getResolvedInstructionOverhead(): number | undefined;
+    getToolCount(): number;
     /**
      * Get all run steps, optionally filtered by agent ID
      */
@@ -97,32 +109,15 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      * Returns a map where key is the contentPart index and value is the agentId
      */
     getContentPartAgentMap(): Map<number, string>;
-    createSystemRunnable({ provider, clientOptions, instructions, additional_instructions, }: {
-        provider?: Providers;
-        clientOptions?: t.ClientOptions;
-        instructions?: string;
-        additional_instructions?: string;
-    }): t.SystemRunnable | undefined;
     initializeTools({ currentTools, currentToolMap, agentContext, }: {
         currentTools?: t.GraphTools;
         currentToolMap?: t.ToolMap;
         agentContext?: AgentContext;
     }): 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, }: {
-        provider: Providers;
-        clientOptions?: t.ClientOptions;
-    }): t.ChatModelInstance;
     getUsageMetadata(finalMessage?: BaseMessage): Partial<UsageMetadata> | undefined;
-    /** Execute model invocation with streaming support */
-    private attemptInvoke;
     cleanupSignalListener(currentModel?: t.ChatModel): void;
-    createCallModel(agentId?: string): (state: t.BaseGraphState, config?: RunnableConfig) => Promise<Partial<t.BaseGraphState>>;
+    createCallModel(agentId?: string): (state: t.AgentSubgraphState, config?: RunnableConfig) => Promise<Partial<t.AgentSubgraphState>>;
     createAgentNode(agentId: string): t.CompiledAgentWorfklow;
     createWorkflow(): t.CompiledStateWorkflow;
     /**

package/dist/types/index.d.ts

@@ -4,6 +4,7 @@ export * from './splitStream';
 export * from './events';
 export * from './messages';
 export * from './graphs';
+export * from './summarization';
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
 export * from './tools/ProgrammaticToolCalling';
@@ -18,3 +19,7 @@ export type * from './types';
 export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';
 export type { OpenRouterReasoning, OpenRouterReasoningEffort, ChatOpenRouterCallOptions, } from './llm/openrouter';
+export { getChatModelClass } from './llm/providers';
+export { initializeModel } from './llm/init';
+export { attemptInvoke, tryFallbackProviders } from './llm/invoke';
+export { isThinkingEnabled, getMaxOutputTokensKey } from './llm/request';

package/dist/types/llm/init.d.ts

@@ -0,0 +1,18 @@
+import type { Runnable } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { Providers } from '@/common';
+/**
+ * Creates a chat model instance for a given provider, applies provider-specific
+ * field assignments, and optionally binds tools.
+ *
+ * This is the single entry point for model creation across the codebase — used
+ * by both the agent graph (main LLM) and the summarization node (compaction LLM).
+ * An optional `override` model can be passed to skip construction entirely
+ * (useful for cached/reused model instances or test fakes).
+ */
+export declare function initializeModel({ provider, clientOptions, tools, override, }: {
+    provider: Providers;
+    clientOptions?: t.ClientOptions;
+    tools?: t.GraphTools;
+    override?: t.ChatModelInstance;
+}): Runnable;

package/dist/types/llm/invoke.d.ts

@@ -0,0 +1,48 @@
+import { AIMessageChunk } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler } from '@/stream';
+import { Providers } from '@/common';
+/**
+ * Context passed to `attemptInvoke` for the default stream handler.
+ * Matches the subset of Graph that `ChatModelStreamHandler.handle` needs.
+ */
+export type InvokeContext = Parameters<ChatModelStreamHandler['handle']>[3];
+/**
+ * Per-chunk callback for custom stream processing.
+ * When provided, replaces the default `ChatModelStreamHandler`.
+ */
+export type OnChunk = (chunk: AIMessageChunk) => void | Promise<void>;
+/**
+ * Invokes a chat model with the given messages, handling both streaming and
+ * non-streaming paths.
+ *
+ * By default, stream chunks are processed through a `ChatModelStreamHandler`
+ * that dispatches run steps (MESSAGE_CREATION, TOOL_CALLS) for the graph.
+ * Pass an `onChunk` callback to override this with custom chunk processing
+ * (e.g. summarization delta events).
+ */
+export declare function attemptInvoke({ model, messages, provider, context, onChunk, }: {
+    model: t.ChatModel;
+    messages: BaseMessage[];
+    provider: Providers;
+    context?: InvokeContext;
+    onChunk?: OnChunk;
+}, config?: RunnableConfig): Promise<Partial<t.BaseGraphState>>;
+/**
+ * Attempts each fallback provider in order until one succeeds.
+ * Throws the last error if all fallbacks fail.
+ */
+export declare function tryFallbackProviders({ fallbacks, tools, messages, config, primaryError, context, onChunk, }: {
+    fallbacks: Array<{
+        provider: Providers;
+        clientOptions?: t.ClientOptions;
+    }>;
+    tools?: t.GraphTools;
+    messages: BaseMessage[];
+    config?: RunnableConfig;
+    primaryError: unknown;
+    context?: InvokeContext;
+    onChunk?: OnChunk;
+}): Promise<Partial<t.BaseGraphState> | undefined>;

package/dist/types/llm/request.d.ts

@@ -0,0 +1,14 @@
+import type * as t from '@/types';
+import { Providers } from '@/common';
+/**
+ * Returns true when the provider + clientOptions indicate extended thinking
+ * is enabled.  Works across Anthropic (direct), Bedrock (additionalModelRequestFields),
+ * and OpenAI-compat (modelKwargs.thinking).
+ */
+export declare function isThinkingEnabled(provider: Providers, clientOptions?: t.ClientOptions): boolean;
+/**
+ * Returns the correct key for setting max output tokens on the model
+ * constructor options.  Google/Vertex use `maxOutputTokens`, all others
+ * use `maxTokens`.
+ */
+export declare function getMaxOutputTokensKey(provider: Providers | string): 'maxOutputTokens' | 'maxTokens';

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

@@ -0,0 +1,42 @@
+/**
+ * Position-based context pruning for tool results.
+ *
+ * Uses position-based age: the distance of a message
+ * from the conversation end as a fraction of total messages.
+ *
+ * Two degradation levels:
+ * - Soft-trim: Keep head + tail of tool result content, drop middle.
+ * - Hard-clear: Replace entire content with a placeholder.
+ *
+ * Messages in the "protected zone" (recent assistant turns, system/pre-first-human
+ * messages, and messages with image content) are never pruned.
+ */
+import { type BaseMessage } from '@langchain/core/messages';
+import type { ContextPruningConfig } from '@/types/graph';
+import type { TokenCounter } from '@/types/run';
+import type { ContextPruningSettings } from './contextPruningSettings';
+export interface ContextPruningResult {
+    /** Number of messages that were soft-trimmed. */
+    softTrimmed: number;
+    /** Number of messages that were hard-cleared. */
+    hardCleared: number;
+}
+/**
+ * Applies position-based context pruning to tool result messages.
+ *
+ * Modifies messages in-place and updates indexTokenCountMap with recounted
+ * token values for modified messages.
+ *
+ * @param params.messages - The full message array (modified in-place).
+ * @param params.indexTokenCountMap - Token count map (updated in-place).
+ * @param params.tokenCounter - Function to recount tokens after modification.
+ * @param params.config - Partial context pruning config (merged with defaults).
+ * @returns Counts of soft-trimmed and hard-cleared messages.
+ */
+export declare function applyContextPruning(params: {
+    messages: BaseMessage[];
+    indexTokenCountMap: Record<string, number | undefined>;
+    tokenCounter: TokenCounter;
+    config?: ContextPruningConfig;
+    resolvedSettings?: ContextPruningSettings;
+}): ContextPruningResult;

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

@@ -0,0 +1,44 @@
+/**
+ * Default settings for position-based context pruning.
+ *
+ * These are merged with user-provided overrides so any subset can be customized.
+ */
+export interface ContextPruningSettings {
+    /** Whether position-based pruning is enabled. Default: false (opt-in). */
+    enabled: boolean;
+    /** Number of recent assistant turns to protect from pruning. Default: 3 */
+    keepLastAssistants: number;
+    /** Age ratio (0-1) at which soft-trim fires. Default: 0.3 */
+    softTrimRatio: number;
+    /** Age ratio (0-1) at which hard-clear fires. Default: 0.5 */
+    hardClearRatio: number;
+    /** Minimum tool result size (chars) before pruning applies. Default: 50000 */
+    minPrunableToolChars: number;
+    softTrim: {
+        /** Maximum total chars after soft-trim. Default: 4000 */
+        maxChars: number;
+        /** Head portion to keep. Default: 1500 */
+        headChars: number;
+        /** Tail portion to keep. Default: 1500 */
+        tailChars: number;
+    };
+    hardClear: {
+        /** Whether hard-clear is enabled. Default: true */
+        enabled: boolean;
+        /** Placeholder text for hard-cleared content. */
+        placeholder: string;
+    };
+}
+export declare const DEFAULT_CONTEXT_PRUNING_SETTINGS: ContextPruningSettings;
+/**
+ * Merges user-provided partial overrides with the defaults.
+ */
+export declare function resolveContextPruningSettings(overrides?: Partial<{
+    enabled?: boolean;
+    keepLastAssistants?: number;
+    softTrimRatio?: number;
+    hardClearRatio?: number;
+    minPrunableToolChars?: number;
+    softTrim?: Partial<ContextPruningSettings['softTrim']>;
+    hardClear?: Partial<ContextPruningSettings['hardClear']>;
+}>): ContextPruningSettings;

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

@@ -1,4 +1,4 @@
-import { AIMessageChunk, HumanMessage, ToolMessage, AIMessage, BaseMessage } from '@langchain/core/messages';
+import { AIMessage, BaseMessage, ToolMessage, HumanMessage, AIMessageChunk } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { Providers } from '@/common';
 export declare function getConverseOverrideMessage({ userMessage, lastMessageX, lastMessageY, }: {