@librechat/agents 3.1.73 → 3.1.75

package/README.md

@@ -0,0 +1,66 @@
+# @librechat/agents
+
+TypeScript utilities for building LibreChat agent workflows. The package provides graph orchestration, streaming event handling, tool execution, provider adapters, and message formatting for single-agent and multi-agent runs.
+
+## Features
+
+- LangGraph-based single-agent and multi-agent workflows
+- Streaming content aggregation and run-step event handlers
+- Tool calling, tool search, subagent handoffs, and programmatic tool execution
+- Provider adapters for Anthropic, Bedrock, Vertex AI, OpenAI-compatible providers, Google, Mistral, DeepSeek, and xAI
+- Message formatting, context pruning, summarization, and cache-control helpers
+
+## Installation
+
+```bash
+npm install @librechat/agents
+```
+
+## Basic Usage
+
+```typescript
+import { HumanMessage } from '@langchain/core/messages';
+import { Providers, Run } from '@librechat/agents';
+
+const run = await Run.create({
+  runId: crypto.randomUUID(),
+  graphConfig: {
+    type: 'standard',
+    instructions: 'You are a helpful assistant.',
+    llmConfig: {
+      provider: Providers.OPENAI,
+      model: 'gpt-4o-mini',
+      apiKey: process.env.OPENAI_API_KEY,
+    },
+  },
+  returnContent: true,
+});
+
+const content = await run.processStream(
+  { messages: [new HumanMessage('Hello')] },
+  {
+    runId: crypto.randomUUID(),
+    streamMode: 'values',
+    version: 'v2',
+  }
+);
+```
+
+## Development
+
+```bash
+npm ci
+npm run build
+npm test
+npx tsc --noEmit
+npx eslint src/
+```
+
+## Documentation
+
+- [Multi-agent patterns](./docs/multi-agent-patterns.md)
+- [Summarization behavior](./docs/summarization-behavior.md)
+
+## License
+
+MIT

package/dist/cjs/agents/AgentContext.cjs

@@ -192,7 +192,7 @@ class AgentContext {
     summaryTokenCount = 0;
     /**
      * Where the summary should be injected:
-     * - `'system_prompt'`: cross-run summary, included in `buildInstructionsString`
+     * - `'system_prompt'`: cross-run summary, included in the dynamic system tail
      * - `'user_message'`: mid-run compaction, injected as HumanMessage on clean slate
      * - `'none'`: no summary present
      */
@@ -298,15 +298,18 @@ class AgentContext {
     }
     /**
      * Gets the system runnable, creating it lazily if needed.
-     * Includes instructions, additional instructions, and programmatic-only tools documentation.
+     * Includes stable instructions, dynamic additional instructions, and
+     * programmatic-only tools documentation.
      * Only rebuilds when marked stale (via markToolsAsDiscovered).
      */
     get systemRunnable() {
         if (!this.systemRunnableStale && this.cachedSystemRunnable !== undefined) {
             return this.cachedSystemRunnable;
         }
-        const instructionsString = this.buildInstructionsString();
-        this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
+        this.cachedSystemRunnable = this.buildSystemRunnable({
+            stableInstructions: this.buildStableInstructionsString(),
+            dynamicInstructions: this.buildDynamicInstructionsString(),
+        });
         this.systemRunnableStale = false;
         return this.cachedSystemRunnable;
     }
@@ -316,16 +319,18 @@ class AgentContext {
      */
     initializeSystemRunnable() {
         if (this.systemRunnableStale || this.cachedSystemRunnable === undefined) {
-            const instructionsString = this.buildInstructionsString();
-            this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
+            this.cachedSystemRunnable = this.buildSystemRunnable({
+                stableInstructions: this.buildStableInstructionsString(),
+                dynamicInstructions: this.buildDynamicInstructionsString(),
+            });
             this.systemRunnableStale = false;
         }
     }
     /**
-     * Builds the raw instructions string (without creating SystemMessage).
+     * Builds the cacheable instructions string (without creating SystemMessage).
      * Includes agent identity preamble and handoff context when available.
      */
-    buildInstructionsString() {
+    buildStableInstructionsString() {
         const parts = [];
         const identityPreamble = this.buildIdentityPreamble();
         if (identityPreamble) {
@@ -334,17 +339,27 @@ class AgentContext {
         if (this.instructions != null && this.instructions !== '') {
             parts.push(this.instructions);
         }
-        if (this.additionalInstructions != null &&
-            this.additionalInstructions !== '') {
-            parts.push(this.additionalInstructions);
-        }
         const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
         if (programmaticToolsDoc) {
             parts.push(programmaticToolsDoc);
         }
-        // Cross-run summary: include in system prompt so the model has context
-        // from the prior run.  Mid-run summaries are injected as a HumanMessage
-        // on the post-compaction clean slate instead (see buildSystemRunnable).
+        return parts.join('\n\n');
+    }
+    /**
+     * Builds the dynamic system-tail string (without creating SystemMessage).
+     * Keep this out of prompt-cache-marked content so volatile context does not
+     * invalidate the stable prefix.
+     */
+    buildDynamicInstructionsString() {
+        const parts = [];
+        if (this.additionalInstructions != null &&
+            this.additionalInstructions !== '') {
+            parts.push(this.additionalInstructions);
+        }
+        // Cross-run summary: include in the system tail so the model has context
+        // from the prior run without invalidating the cacheable prefix. Mid-run
+        // summaries are injected as a HumanMessage on the post-compaction clean
+        // slate instead (see buildSystemRunnable).
         if (this._summaryLocation === 'system_prompt' &&
             this.summaryText != null &&
             this.summaryText !== '') {
@@ -375,34 +390,20 @@ class AgentContext {
      * Build system runnable from pre-built instructions string.
      * Only called when content has actually changed.
      */
-    buildSystemRunnable(instructionsString) {
+    buildSystemRunnable({ stableInstructions, dynamicInstructions, }) {
         const hasMidRunSummary = this._summaryLocation === 'user_message' &&
             this.summaryText != null &&
             this.summaryText !== '';
-        if (!instructionsString && !hasMidRunSummary) {
+        if (!stableInstructions && !dynamicInstructions && !hasMidRunSummary) {
             this.systemMessageTokens = 0;
             return undefined;
         }
-        let finalInstructions = instructionsString;
-        let usePromptCache = false;
-        if (this.provider === _enum.Providers.ANTHROPIC) {
-            const anthropicOptions = this.clientOptions;
-            if (anthropicOptions?.promptCache === true) {
-                usePromptCache = true;
-                finalInstructions = {
-                    content: [
-                        {
-                            type: 'text',
-                            text: instructionsString,
-                            cache_control: { type: 'ephemeral' },
-                        },
-                    ],
-                };
-            }
-        }
-        const systemMessage = instructionsString
-            ? new messages.SystemMessage(finalInstructions)
-            : undefined;
+        const usePromptCache = this.hasAnthropicPromptCache();
+        const systemMessage = this.buildSystemMessage({
+            stableInstructions,
+            dynamicInstructions,
+            usePromptCache,
+        });
         if (this.tokenCounter) {
             this.systemMessageTokens = systemMessage
                 ? this.tokenCounter(systemMessage)
@@ -444,6 +445,52 @@ class AgentContext {
             return [...prefix, ...body];
         }).withConfig({ runName: 'prompt' });
     }
+    hasAnthropicPromptCache() {
+        if (this.provider !== _enum.Providers.ANTHROPIC) {
+            return false;
+        }
+        const anthropicOptions = this.clientOptions;
+        return anthropicOptions?.promptCache === true;
+    }
+    hasBedrockPromptCache() {
+        if (this.provider !== _enum.Providers.BEDROCK) {
+            return false;
+        }
+        const bedrockOptions = this.clientOptions;
+        return bedrockOptions?.promptCache === true;
+    }
+    buildSystemMessage({ stableInstructions, dynamicInstructions, usePromptCache, }) {
+        if (!stableInstructions && !dynamicInstructions) {
+            return undefined;
+        }
+        if (usePromptCache) {
+            const content = [];
+            if (stableInstructions) {
+                content.push({
+                    type: 'text',
+                    text: stableInstructions,
+                    cache_control: { type: 'ephemeral' },
+                });
+            }
+            if (dynamicInstructions) {
+                content.push({ type: 'text', text: dynamicInstructions });
+            }
+            return new messages.SystemMessage({ content });
+        }
+        if (this.hasBedrockPromptCache() && stableInstructions) {
+            const content = [
+                { type: 'text', text: stableInstructions },
+                { cachePoint: { type: 'default' } },
+            ];
+            if (dynamicInstructions) {
+                content.push({ type: 'text', text: dynamicInstructions });
+            }
+            return new messages.SystemMessage({ content });
+        }
+        return new messages.SystemMessage([stableInstructions, dynamicInstructions]
+            .filter((part) => part !== '')
+            .join('\n\n'));
+    }
     /**
      * Reset context for a new run
      */
@@ -505,7 +552,44 @@ class AgentContext {
         if (!this.toolDefinitions) {
             return [];
         }
-        return this.toolDefinitions.filter((def) => def.defer_loading !== true || this.discoveredToolNames.has(def.name));
+        /**
+         * Mirror `getEventDrivenToolsForBinding`'s gate: a definition is only
+         * bound to the model when its `allowed_callers` include `'direct'` and
+         * (if deferred) it has been discovered. Filtering by `defer_loading`
+         * alone left programmatic-only definitions counted in
+         * `toolSchemaTokens` even though they were never bound.
+         */
+        return this.toolDefinitions.filter((def) => {
+            const allowedCallers = def.allowed_callers ?? ['direct'];
+            if (!allowedCallers.includes('direct')) {
+                return false;
+            }
+            return (def.defer_loading !== true || this.discoveredToolNames.has(def.name));
+        });
+    }
+    /**
+     * Single source of truth for "which entries of `this.tools` should be
+     * treated as actually bound". Callers:
+     *   - `getToolsForBinding` (non-event-driven branch)
+     *   - `getEventDrivenToolsForBinding` (appends instance tools alongside
+     *     schema-only definitions)
+     *   - `calculateInstructionTokens` (counts schema bytes for accounting)
+     *
+     * In event-driven mode (`toolDefinitions` present) instance tools are
+     * appended unfiltered; outside event-driven mode they pass through
+     * `filterToolsForBinding`. Centralizing the decision here prevents the
+     * accounting/binding paths from drifting apart, which was the root
+     * cause of the original miscount.
+     */
+    getEffectiveInstanceTools() {
+        if (!this.tools) {
+            return undefined;
+        }
+        const isEventDriven = (this.toolDefinitions?.length ?? 0) > 0;
+        if (isEventDriven || !this.toolRegistry) {
+            return this.tools;
+        }
+        return this.filterToolsForBinding(this.tools);
     }
     /**
      * Calculate tool tokens and add to instruction tokens
@@ -520,9 +604,17 @@ class AgentContext {
          * populated after `fromConfig()` kicks off the initial calculation, so
          * callers that mutate `graphTools` must re-trigger this method to
          * refresh `toolSchemaTokens`.
+         *
+         * Use `getEffectiveInstanceTools()` so accounting reflects exactly the
+         * subset that `getToolsForBinding` would emit — preventing the
+         * worst-case-ceiling miscount that triggered spurious `empty_messages`
+         * preflight rejections at low `maxContextTokens`. Deferred and
+         * non-`'direct'` `toolDefinitions` are excluded by
+         * `getActiveToolDefinitions()` below.
          */
         const instanceTools = [
-            ...(this.tools ?? []),
+            ...(this.getEffectiveInstanceTools() ??
+                []),
             ...(this.graphTools ?? []),
         ];
         if (instanceTools.length > 0) {
@@ -682,7 +774,16 @@ class AgentContext {
      */
     getTokenBudgetBreakdown(messages) {
         const maxContextTokens = this.maxContextTokens ?? 0;
-        const toolCount = (this.tools?.length ?? 0) + this.getActiveToolDefinitions().length;
+        /**
+         * Derive `toolCount` from `getToolsForBinding()` so the diagnostic stays
+         * aligned with what is actually bound to the model — and with what
+         * `calculateInstructionTokens` counts into `toolSchemaTokens`. Using raw
+         * `this.tools.length` would inflate the count whenever the registry
+         * marks instance tools as deferred-undiscovered or non-`'direct'`,
+         * producing the same misleading "N tools" diagnostic this fix is meant
+         * to eliminate.
+         */
+        const toolCount = this.getToolsForBinding()?.length ?? 0;
         const messageCount = messages?.length ?? 0;
         let messageTokens = 0;
         if (messages != null) {
@@ -780,9 +881,7 @@ class AgentContext {
         if (this.toolDefinitions && this.toolDefinitions.length > 0) {
             return this.getEventDrivenToolsForBinding();
         }
-        const filtered = !this.tools || !this.toolRegistry
-            ? this.tools
-            : this.filterToolsForBinding(this.tools);
+        const filtered = this.getEffectiveInstanceTools();
         if (this.graphTools && this.graphTools.length > 0) {
             return [...(filtered ?? []), ...this.graphTools];
         }
@@ -793,24 +892,14 @@ class AgentContext {
         if (!this.toolDefinitions) {
             return this.graphTools ?? [];
         }
-        const defsToInclude = this.toolDefinitions.filter((def) => {
-            const allowedCallers = def.allowed_callers ?? ['direct'];
-            if (!allowedCallers.includes('direct')) {
-                return false;
-            }
-            if (def.defer_loading === true &&
-                !this.discoveredToolNames.has(def.name)) {
-                return false;
-            }
-            return true;
-        });
-        const schemaTools = schema$1.createSchemaOnlyTools(defsToInclude);
+        const schemaTools = schema$1.createSchemaOnlyTools(this.getActiveToolDefinitions());
         const allTools = [...schemaTools];
         if (this.graphTools && this.graphTools.length > 0) {
             allTools.push(...this.graphTools);
         }
-        if (this.tools && this.tools.length > 0) {
-            allTools.push(...this.tools);
+        const instanceTools = this.getEffectiveInstanceTools();
+        if (instanceTools && instanceTools.length > 0) {
+            allTools.push(...instanceTools);
         }
         return allTools;
     }