@illuma-ai/agents 1.5.1 → 2.1.1

package/src/common/enum.ts

@@ -103,19 +103,19 @@ export enum Providers {
 
 export enum EdgeType {
   /**
-   * handoff: one-way routing where the parent agent exits
+   * Upstream-aligned handoff: one-way routing where the parent agent exits
    * via a `lc_transfer_to_<destination>` tool call, the child takes over,
    * and the child responds directly to the user. Replaces what used to be
-   * called "TRANSFER" in older versions; the parent-calls-child
+   * called "TRANSFER" in earlier Ranger versions; the parent-calls-child
    * supervisor pattern (formerly `EdgeType.HANDOFF`) is gone — use the
    * Subagent primitive (Tier 5) for deep delegation instead.
    */
   HANDOFF = 'handoff',
   /**
-   * Fixed graph edges for automatic transitions. Standard naming.
-   * Downstream consumers may layer additional wiring on top of this edge
-   * type: fan-in with prompt + {results}, parallel groups, approval-gate
-   * node insertion, and the `excludeResults` agentMessages channel.
+   * Fixed graph edges for automatic transitions. Naming matches upstream.
+   * Ranger keeps its enriched wiring on top of this edge type:
+   * fan-in with prompt + {results}, parallel groups, ApprovalGateNode
+   * insertion, and the `excludeResults` agentMessages channel.
    */
   DIRECT = 'direct',
 }
@@ -195,15 +195,15 @@ export enum Callback {
 export enum Constants {
   OFFICIAL_CODE_BASEURL = 'https://api.illuma.ai/v1',
   EXECUTE_CODE = 'execute_code',
-  /** Tool name for the bash execution primitive (Tier 3). */
+  /** Tool name for the bash execution primitive (upstream Tier 3). */
   BASH_TOOL = 'execute_bash',
-  /** Tool name for the bash programmatic-tool-calling variant (Tier 3). */
+  /** Tool name for the bash programmatic-tool-calling variant (upstream Tier 3). */
   BASH_PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_bash',
-  /** Tool name for the read-file primitive (Tier 3). */
+  /** Tool name for the read-file primitive (upstream Tier 3). */
   READ_FILE = 'read_file',
-  /** Tool name for the SkillTool primitive (Tier 2). */
+  /** Tool name for the SkillTool primitive (upstream Tier 2). */
   SKILL_TOOL = 'skill',
-  /** Tool name for the Subagent primitive (Tier 5). */
+  /** Tool name for the Subagent primitive (upstream Tier 5). */
   SUBAGENT = 'subagent',
   TOOL_SEARCH = 'tool_search',
   PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',
@@ -270,7 +270,7 @@ export enum MessageTypes {
 /**
  * Tool names that use the code execution environment (shared session, file
  * tracking). Used by ToolNode to inject session context + file refs into
- * `invokeParams` before tool execution. constant.
+ * `invokeParams` before tool execution. Upstream-aligned constant.
  */
 export const CODE_EXECUTION_TOOLS: ReadonlySet<string> = new Set([
   Constants.EXECUTE_CODE,

package/src/graphs/Graph.ts

@@ -187,7 +187,7 @@ export abstract class Graph<
   hookRegistry?: import('@/hooks').HookRegistry;
   /**
    * Optional tool-output reference registry threaded down from Run
-   * (PR #114). When set, every ToolNode built by this graph
+   * (upstream PR #114). When set, every ToolNode built by this graph
    * stores successful outputs here and resolves `{{tool<i>turn<n>}}`
    * placeholders in args before invoking the tool.
    *
@@ -198,7 +198,7 @@ export abstract class Graph<
    */
   toolOutputRegistry?: import('@/tools/toolOutputReferences').ToolOutputReferenceRegistry;
   /**
-   * Run-scoped tool output reference configuration (PR #117).
+   * Run-scoped tool output reference configuration (upstream PR #117).
    * When `enabled` is true, the graph lazily allocates a single
    * `ToolOutputReferenceRegistry` on first `getOrCreateToolOutputRegistry()`
    * call and shares it with every ToolNode the graph compiles, so
@@ -366,15 +366,25 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     if (keepContent !== true) {
       this.contentData = resetIfNotEmpty(this.contentData, []);
       this.contentIndexMap = resetIfNotEmpty(this.contentIndexMap, new Map());
+      /**
+       * Clear in-place instead of replacing with a new Map to preserve the
+       * shared reference held by ToolNode (passed at construction time).
+       * Using resetIfNotEmpty would create a new Map, leaving ToolNode with
+       * a stale reference on 2nd+ processStream calls.
+       *
+       * Gated by `keepContent` because HITL resume calls processStream a
+       * second time (`Command({resume})`) with `keepContent: true` to
+       * preserve the in-progress message's contentParts. The toolCallId →
+       * stepId map must survive the same boundary so that when LangGraph
+       * replays the interrupted ToolNode, `handleRunToolCompletions` can
+       * still resolve the resumed tool call's stepId and dispatch
+       * ON_RUN_STEP_COMPLETED with the tool's output. Without this guard,
+       * HITL tools (e.g. `ask_user`) lose their `output` field on every
+       * persisted message — the result is in the LLM context but never
+       * makes it into the saved tool_call entry.
+       */
+      this.toolCallStepIds.clear();
     }
-    this.stepKeyIds = resetIfNotEmpty(this.stepKeyIds, new Map());
-    /**
-     * Clear in-place instead of replacing with a new Map to preserve the
-     * shared reference held by ToolNode (passed at construction time).
-     * Using resetIfNotEmpty would create a new Map, leaving ToolNode with
-     * a stale reference on 2nd+ processStream calls.
-     */
-    this.toolCallStepIds.clear();
     this.messageIdsByStepKey = resetIfNotEmpty(
       this.messageIdsByStepKey,
       new Map()
@@ -1109,7 +1119,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     }
 
     /**
-     * Lazy tool-output reference annotation (PR #117). Right
+     * Lazy tool-output reference annotation (upstream PR #117). Right
      * before the message array hits the provider, walk it and apply
      * `[ref: tool<i>turn<n>]` prefixes / `_ref` JSON fields to a
      * transient copy. The persisted ToolMessages stay clean — only what
@@ -1720,7 +1730,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
              * Fire PreCompact (#103) before the LLM call. Observational —
              * hosts may use the input to schedule auxiliary work, but a
              * deny/ask decision does NOT block compaction here because
-             * the summarizer runs in the background and a refusal
+             * Ranger's summarizer runs in the background and a refusal
              * has nowhere to go: pruning still needs to happen at 100%
              * regardless. Errors are swallowed so a hook bug cannot
              * masquerade as a context-overflow failure.
@@ -2716,7 +2726,7 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
     }
 
     /**
-     * Subagent injection (Tier 5): when the agent has SubagentConfig
+     * Subagent injection (upstream Tier 5): when the agent has SubagentConfig
      * entries and depth budget remaining, inject a `subagent` DynamicStructuredTool
      * into graphTools. The tool's executor receives this graph's hookRegistry and
      * a lazy handler-registry getter (Run wires handlerRegistry AFTER createWorkflow,
@@ -2769,6 +2779,15 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
             subagentType,
             threadId,
             parentToolCallId,
+            /**
+             * Forward the parent's `configurable` so host-set fields
+             * (`requestBody`, `user`, etc.) propagate into the child
+             * workflow. The executor scrubs run-identity fields before
+             * forwarding — see `SubagentExecuteParams.parentConfigurable`.
+             */
+            parentConfigurable: config.configurable as
+              | Record<string, unknown>
+              | undefined,
           });
           return result.content;
         }, buildSubagentToolParams(resolvedConfigs));

package/src/graphs/MultiAgentGraph.ts

@@ -1006,7 +1006,7 @@ export class MultiAgentGraph extends StandardGraph {
 
     /**
      * Add approval-gate nodes for sequence edges that declare an approvalGate
-     * config (consumer extension, not part of the standard interface). Gates fire
+     * config (Ranger-only feature, not present upstream). Gates fire
      * regardless of ExecutionContext and sit between source and destination.
      */
     const gatedEdges = new Set<t.GraphEdge>();

package/src/graphs/gapFeatures.test.ts

@@ -1,7 +1,7 @@
 /**
  * gapFeatures.test.ts
  *
- * Integration tests for the four gap features:
+ * Integration tests for the four LibreChat gap features:
  * 1. Tool Discovery Caching
  * 2. SummarizationConfig (trigger types, initialSummary)
  * 3. EMA Pruning Calibration

package/src/graphs/phases/__tests__/memoryFlushPhase.test.ts

@@ -1,7 +1,7 @@
 import { shouldFlushMemory } from '../memoryFlushPhase';
 
 describe('shouldFlushMemory', () => {
-  // Use defaults: soft=4000, reserve=20000 means a 200k
+  // Use upstream-aligned defaults: soft=4000, reserve=20000 means a 200k
   // window fires at 176k. Explicit numbers here keep the test independent
   // from the constants file.
   const base = {

package/src/graphs/phases/memoryFlushPhase.ts

@@ -1,7 +1,7 @@
 /**
  * Memory flush phase — trigger logic + reflection invocation.
  *
- * Ported from the reference implementation's post-turn flush handler. The agent is re-invoked
+ * Ported from upstream's post-turn flush handler. The agent is re-invoked
  * with a reflection system prompt and the `memory_append` tool unlocked;
  * it writes notes to its future self, then the graph returns to normal.
  *
@@ -45,7 +45,7 @@ export interface ShouldFlushInput {
 /**
  * Pure trigger function: fires when the current context is within
  * `softThreshold + reserveFloor` tokens of the model window. Matches
- * the standard formula.
+ * upstream's formula.
  */
 export function shouldFlushMemory(input: ShouldFlushInput): boolean {
   if (

package/src/hooks/HookRegistry.ts

@@ -24,7 +24,7 @@ type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
  *
  * ## Why `Map<sessionId, MatcherBucket>` and not `Record`
  *
- * Real consumers run thousands of parallel sessions in one Node process, and
+ * LibreChat runs thousands of parallel sessions in one Node process, and
  * hook registration happens inside hot paths (tool loading, agent spawning).
  * A `Record<sessionId, ...>` has to be spread on every insertion, which is
  * O(n) per call and O(n²) total for a batch of parallel registrations. A

package/src/hooks/index.ts

@@ -1,6 +1,6 @@
 // src/hooks/index.ts
 //
-// Hook lifecycle system for `@illuma-ai/agents`. Re-exported from
+// Hook lifecycle system for `@librechat/agents`. Re-exported from
 // `src/index.ts` and consumed by `Run.processStream` (RunStart,
 // UserPromptSubmit, Stop, StopFailure), `ToolNode.dispatchToolEvents`
 // (PreToolUse, PostToolUse, PostToolUseFailure, PermissionDenied),

package/src/hooks/matchers.ts

@@ -129,7 +129,7 @@ function skipGroupSyntaxPrefix(pattern: string, start: number): number {
  * This catches the common forms but not all. Ambiguous-alternation ReDoS
  * like `(a|a)+` is not detected. Pathologically long patterns are also
  * caught by {@link MAX_PATTERN_LENGTH}. Hosts that accept user-supplied
- * patterns must still validate standard.
+ * patterns must still validate upstream.
  */
 export function hasNestedQuantifier(pattern: string): boolean {
   const stack: QuantifierFrame[] = [];
@@ -248,7 +248,7 @@ function compile(pattern: string): RegExp | null {
  *    never re-enter the regex compiler.
  *
  * These are a floor, not a ceiling. Hosts that accept user-supplied
- * patterns should still validate standard. The design report §3.8 routes
+ * patterns should still validate upstream. The design report §3.8 routes
  * persistable hooks through a host-side compiler before they reach this
  * module.
  */

package/src/hooks/types.ts

@@ -7,7 +7,7 @@ import type { BaseMessage } from '@langchain/core/messages';
  * These mirror the subset of Claude Code's event surface that makes sense
  * for a library context (no filesystem/CLI-specific events). See
  * `docs/hooks-design-report.md` §3.2 for the mapping to existing
- * `@illuma-ai/agents` emission points.
+ * `@librechat/agents` emission points.
  */
 export const HOOK_EVENTS = [
   'RunStart',

package/src/index.ts

@@ -78,12 +78,6 @@ export * from './utils';
 /* Types */
 export type * from './types';
 
-/* LangChain compatibility facade — re-exports common langchain primitives
- * so consumers can import from '@illuma-ai/agents/langchain' instead of
- * pinning '@langchain/*' versions directly. Helps keep consumer dep
- * versions in sync with the library's tested set. */
-export * from './langchain';
-
 /* LLM */
 export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';

package/src/llm/anthropic/utils/message_inputs.ts

@@ -592,16 +592,7 @@ function _formatContent(message: BaseMessage) {
         throw new Error('Unsupported message content format');
       }
     });
-    return contentBlocks.filter(
-      (block) =>
-        block !== null &&
-        !(
-          block.type === 'text' &&
-          'text' in block &&
-          typeof block.text === 'string' &&
-          block.text.trim() === ''
-        )
-    );
+    return contentBlocks.filter((block) => block !== null);
   }
 }
 

package/src/llm/bedrock/__tests__/bedrock-caching.test.ts

@@ -194,134 +194,6 @@ describe('Bedrock Prompt Caching', () => {
         expect(model.promptCache).toBe(false);
       });
     });
-
-    describe('Tool cache strategies', () => {
-      const fakeTools = [
-        {
-          toolSpec: {
-            name: 'web_search',
-            description: 'core search',
-            inputSchema: { json: { type: 'object', properties: {} } },
-          },
-        },
-        {
-          toolSpec: {
-            name: 'execute_code',
-            description: 'core code',
-            inputSchema: { json: { type: 'object', properties: {} } },
-          },
-        },
-        {
-          toolSpec: {
-            name: 'search_emails_mcp_Outlook',
-            description: 'mcp tool',
-            inputSchema: { json: { type: 'object', properties: {} } },
-          },
-        },
-        {
-          toolSpec: {
-            name: 'list_documents_mcp_SharePoint',
-            description: 'mcp tool',
-            inputSchema: { json: { type: 'object', properties: {} } },
-          },
-        },
-      ];
-
-      it("default 'single' strategy: one cachePoint at end of tools array", () => {
-        const model = new CustomChatBedrockConverse({
-          model: 'anthropic.claude-3-haiku-20240307-v1:0',
-          region: 'us-east-1',
-          promptCache: true,
-          // toolCacheStrategy omitted — default is 'single'
-        });
-        const params = model.invocationParams({
-          tools: fakeTools,
-        } satisfies InvocationParamsOptions);
-        // 4 tools + 1 cachePoint
-        expect(params.toolConfig?.tools).toHaveLength(5);
-        expect(params.toolConfig?.tools?.[4]).toEqual({
-          cachePoint: { type: 'default' },
-        });
-      });
-
-      it("'split' strategy with toolGroupSelector groups tools by selector key, cachePoint after each group", () => {
-        const model = new CustomChatBedrockConverse({
-          model: 'anthropic.claude-3-haiku-20240307-v1:0',
-          region: 'us-east-1',
-          promptCache: true,
-          toolCacheStrategy: 'split',
-          toolGroupSelector: (toolName) =>
-            toolName.includes('_mcp_') ? 'mcp' : 'core',
-        });
-        const params = model.invocationParams({
-          tools: fakeTools,
-        } satisfies InvocationParamsOptions);
-        // [core, core, cp, mcp, mcp, cp] = 6 entries
-        expect(params.toolConfig?.tools).toHaveLength(6);
-        expect(params.toolConfig?.tools?.[0]).toEqual(fakeTools[0]); // core
-        expect(params.toolConfig?.tools?.[1]).toEqual(fakeTools[1]); // core
-        expect(params.toolConfig?.tools?.[2]).toEqual({
-          cachePoint: { type: 'default' },
-        });
-        expect(params.toolConfig?.tools?.[3]).toEqual(fakeTools[2]); // mcp
-        expect(params.toolConfig?.tools?.[4]).toEqual(fakeTools[3]); // mcp
-        expect(params.toolConfig?.tools?.[5]).toEqual({
-          cachePoint: { type: 'default' },
-        });
-      });
-
-      it("'none' strategy: no cachePoint added at all", () => {
-        const model = new CustomChatBedrockConverse({
-          model: 'anthropic.claude-3-haiku-20240307-v1:0',
-          region: 'us-east-1',
-          promptCache: true,
-          toolCacheStrategy: 'none',
-        });
-        const params = model.invocationParams({
-          tools: fakeTools,
-        } satisfies InvocationParamsOptions);
-        expect(params.toolConfig?.tools).toHaveLength(4);
-        for (const tool of params.toolConfig?.tools ?? []) {
-          expect('cachePoint' in tool).toBe(false);
-        }
-      });
-
-      it("'split' with single-group selector behaves like 'single'", () => {
-        const model = new CustomChatBedrockConverse({
-          model: 'anthropic.claude-3-haiku-20240307-v1:0',
-          region: 'us-east-1',
-          promptCache: true,
-          toolCacheStrategy: 'split',
-          toolGroupSelector: () => 'all', // every tool same group
-        });
-        const params = model.invocationParams({
-          tools: fakeTools,
-        } satisfies InvocationParamsOptions);
-        // 4 tools + 1 cachePoint
-        expect(params.toolConfig?.tools).toHaveLength(5);
-        expect(params.toolConfig?.tools?.[4]).toEqual({
-          cachePoint: { type: 'default' },
-        });
-      });
-
-      it("'split' with empty groups skipped (only emits cachePoint after non-empty groups)", () => {
-        const model = new CustomChatBedrockConverse({
-          model: 'anthropic.claude-3-haiku-20240307-v1:0',
-          region: 'us-east-1',
-          promptCache: true,
-          toolCacheStrategy: 'split',
-          toolGroupSelector: (name) =>
-            name.includes('_mcp_') ? 'mcp' : 'core',
-        });
-        // Only core tools — no MCP
-        const coreOnly = fakeTools.slice(0, 2);
-        const params = model.invocationParams({
-          tools: coreOnly,
-        } satisfies InvocationParamsOptions);
-        // 2 core + 1 cachePoint = 3
-        expect(params.toolConfig?.tools).toHaveLength(3);
-      });
-    });
   });
 
   describe('AgentContext - System Message Caching', () => {
@@ -361,13 +233,7 @@ describe('Bedrock Prompt Caching', () => {
     };
 
     describe('Bedrock system message with promptCache: true', () => {
-      /* Updated contract (2026-05-01, PR #128 alignment): Bedrock
-       * system message gets a `cachePoint` block inline so the system
-       * prefix is cached at the AWS account level (cross-user). Previously
-       * cachePoint was only added at the tool level, leaving the system
-       * prefix uncached. Tools array still gets its own cachePoints from
-       * IllumaBedrockConverse.invocationParams independently. */
-      it('emits content array with cachePoint after stable text (Claude model)', async () => {
+      it('should produce plain string system message (cachePoint is handled at tool level)', async () => {
         const ctx = createBedrockContext({
           instructions: 'You are a helpful assistant.',
           promptCache: true,
@@ -376,20 +242,17 @@ describe('Bedrock Prompt Caching', () => {
         const systemRunnable = ctx.systemRunnable;
         expect(systemRunnable).toBeDefined();
 
+        // Invoke the runnable to get the messages
         const result = await systemRunnable!.invoke([]);
         const systemMessage = result[0];
 
-        const content = systemMessage.content as Array<Record<string, unknown>>;
-        expect(Array.isArray(content)).toBe(true);
-        expect(content).toHaveLength(2);
-        expect(content[0]).toEqual({
-          type: 'text',
-          text: 'You are a helpful assistant.',
-        });
-        expect(content[1]).toEqual({ cachePoint: { type: 'default', ttl: '5m' } });
+        // Bedrock system messages are plain strings — cachePoint is added
+        // at the tool level by IllumaBedrockConverse.invocationParams()
+        expect(typeof systemMessage.content).toBe('string');
+        expect(systemMessage.content).toBe('You are a helpful assistant.');
       });
 
-      it('keeps additional_instructions AFTER cachePoint (dynamic tail not cached)', async () => {
+      it('should include combined instructions and additional_instructions as plain string', async () => {
         const ctx = createBedrockContext({
           instructions: 'Base instructions.',
           additionalInstructions: 'Additional context.',
@@ -398,20 +261,11 @@ describe('Bedrock Prompt Caching', () => {
 
         const result = await ctx.systemRunnable!.invoke([]);
         const systemMessage = result[0];
-        const content = systemMessage.content as Array<Record<string, unknown>>;
 
-        /* Order is critical: stable text → cachePoint → dynamic text.
-         * Anything after the cachePoint is excluded from the cache, so
-         * the per-user/per-request `additional_instructions` does not
-         * invalidate the cached prefix. */
-        expect(content).toHaveLength(3);
-        expect((content[0] as { text: string }).text).toBe(
-          'Base instructions.'
-        );
-        expect(content[1]).toEqual({ cachePoint: { type: 'default', ttl: '5m' } });
-        expect((content[2] as { text: string }).text).toBe(
-          'Additional context.'
-        );
+        // Bedrock system messages are plain strings even with promptCache
+        expect(typeof systemMessage.content).toBe('string');
+        expect(systemMessage.content).toContain('Base instructions.');
+        expect(systemMessage.content).toContain('Additional context.');
       });
     });
 
@@ -458,7 +312,7 @@ describe('Bedrock Prompt Caching', () => {
         expect(content[0]).toEqual({
           type: 'text',
           text: 'You are a helpful assistant.',
-          cache_control: { type: 'ephemeral', ttl: '5m' },
+          cache_control: { type: 'ephemeral' },
         });
       });
 
@@ -476,21 +330,19 @@ describe('Bedrock Prompt Caching', () => {
     });
 
     describe('Provider-specific caching behavior', () => {
-      it('emits cachePoint block inline for Bedrock Claude (account-scoped system caching)', async () => {
+      it('should produce plain string for Bedrock (cachePoint handled at tool level)', async () => {
         const bedrockCtx = createBedrockContext({
           instructions: 'Test',
           promptCache: true,
         });
 
         const result = await bedrockCtx.systemRunnable!.invoke([]);
-        const content = result[0].content as Array<Record<string, unknown>>;
 
-        // Bedrock system messages now carry an inline cachePoint so the
-        // system prefix gets cached at the AWS account level (matching
-        // PR #128). Tool-level cachePoint from
-        // IllumaBedrockConverse.invocationParams() runs independently.
-        expect(Array.isArray(content)).toBe(true);
-        expect(content.some((c) => 'cachePoint' in c)).toBe(true);
+        // Bedrock system messages are plain strings — cachePoint is added
+        // at the tool level by IllumaBedrockConverse.invocationParams(),
+        // not inline in the system message content
+        expect(typeof result[0].content).toBe('string');
+        expect(result[0].content).toBe('Test');
       });
 
       it('should use cache_control format for Anthropic, not cachePoint', async () => {