@librechat/agents 3.1.74 → 3.1.75-dev.1

package/src/agents/__tests__/promptCacheLiveHelpers.ts

@@ -0,0 +1,165 @@
+import { expect } from '@jest/globals';
+import { HumanMessage } from '@langchain/core/messages';
+import type { UsageMetadata } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { GraphEvents, Providers } from '@/common';
+import { AgentContext } from '../AgentContext';
+import { ModelEndHandler } from '@/events';
+import { Run } from '@/run';
+
+type LivePromptCacheProvider = Providers.ANTHROPIC | Providers.BEDROCK;
+
+type PromptCacheExpectedSystemBlock =
+  | { type: 'text'; text: string; cache_control?: { type: 'ephemeral' } }
+  | { cachePoint: { type: 'default' } };
+
+type LivePromptCacheClientOptions =
+  | t.ClientOptions
+  | t.BedrockAnthropicClientOptions;
+
+export function buildStableInstructions({
+  nonce,
+  providerLabel,
+}: {
+  nonce: string;
+  providerLabel: string;
+}): string {
+  const records = Array.from(
+    { length: 360 },
+    (_, index) =>
+      `Stable ${providerLabel} cache record ${index}: nonce ${nonce}; keep this reference in the cacheable prefix and do not use it as the dynamic marker.`
+  );
+  return [
+    `You are a ${providerLabel} prompt-cache verification assistant.`,
+    'When asked for the dynamic marker, answer with only the marker value from the Dynamic Marker line.',
+    ...records,
+  ].join('\n');
+}
+
+export function buildDynamicInstructions({
+  marker,
+  tailDescription,
+}: {
+  marker: string;
+  tailDescription: string;
+}): string {
+  return [`Dynamic Marker: ${marker}`, tailDescription].join('\n');
+}
+
+export function waitForCachePropagation(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 2000));
+}
+
+export async function assertSystemPayloadShape({
+  agentId,
+  provider,
+  clientOptions,
+  stableInstructions,
+  dynamicInstructions,
+  expectedContent,
+}: {
+  agentId: string;
+  provider: LivePromptCacheProvider;
+  clientOptions: LivePromptCacheClientOptions;
+  stableInstructions: string;
+  dynamicInstructions: string;
+  expectedContent: PromptCacheExpectedSystemBlock[];
+}): Promise<void> {
+  const ctx = AgentContext.fromConfig({
+    agentId,
+    provider,
+    clientOptions,
+    instructions: stableInstructions,
+    additional_instructions: dynamicInstructions,
+  });
+
+  const messages = await ctx.systemRunnable!.invoke([
+    new HumanMessage('What is the dynamic marker?'),
+  ]);
+
+  expect(messages[0].content).toEqual(expectedContent);
+}
+
+function latestUsage({
+  collectedUsage,
+  label,
+  providerLabel,
+}: {
+  collectedUsage: UsageMetadata[];
+  label: string;
+  providerLabel: string;
+}): UsageMetadata {
+  if (collectedUsage.length === 0) {
+    throw new Error(`Missing ${providerLabel} usage metadata for ${label}`);
+  }
+  return collectedUsage[collectedUsage.length - 1];
+}
+
+function collectText(parts: t.MessageContentComplex[] | undefined): string {
+  return (parts ?? []).reduce((text, part) => {
+    if (part.type === 'text') {
+      return text + part.text;
+    }
+    return text;
+  }, '');
+}
+
+export async function runLiveTurn({
+  provider,
+  providerLabel,
+  clientOptions,
+  runId,
+  threadId,
+  stableInstructions,
+  dynamicInstructions,
+}: {
+  provider: LivePromptCacheProvider;
+  providerLabel: string;
+  clientOptions: LivePromptCacheClientOptions;
+  runId: string;
+  threadId: string;
+  stableInstructions: string;
+  dynamicInstructions: string;
+}): Promise<{
+  text: string;
+  usage: UsageMetadata;
+}> {
+  const collectedUsage: UsageMetadata[] = [];
+  const run = await Run.create<t.IState>({
+    runId,
+    graphConfig: {
+      type: 'standard',
+      llmConfig: {
+        provider,
+        ...clientOptions,
+      } as t.LLMConfig,
+      instructions: stableInstructions,
+      additional_instructions: dynamicInstructions,
+    },
+    returnContent: true,
+    skipCleanup: true,
+    customHandlers: {
+      [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(collectedUsage),
+    },
+  });
+
+  const config = {
+    configurable: { thread_id: threadId },
+    streamMode: 'values',
+    version: 'v2' as const,
+  };
+
+  const contentParts = await run.processStream(
+    {
+      messages: [
+        new HumanMessage('What is the dynamic marker? Reply with only it.'),
+      ],
+    },
+    config
+  );
+
+  return {
+    text: collectText(contentParts),
+    usage: latestUsage({ collectedUsage, label: runId, providerLabel }),
+  };
+}

package/src/graphs/Graph.ts

@@ -399,12 +399,25 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   ): (string | number | undefined)[] {
     if (!metadata) return [];
 
+    const configurable = this.config?.configurable;
+    const runId =
+      (metadata.run_id as string | undefined) ??
+      (configurable?.run_id as string | undefined) ??
+      this.runId;
+    const threadId =
+      (metadata.thread_id as string | undefined) ??
+      (configurable?.thread_id as string | undefined) ??
+      runId;
+    const checkpointNs =
+      (metadata.checkpoint_ns as string | undefined) ??
+      (metadata.langgraph_checkpoint_ns as string | undefined) ??
+      '';
     const keyList = [
-      metadata.run_id as string,
-      metadata.thread_id as string,
+      runId,
+      threadId,
       metadata.langgraph_node as string,
       metadata.langgraph_step as number,
-      metadata.checkpoint_ns as string,
+      checkpointNs,
     ];
 
     const agentContext = this.getAgentContext(metadata);
@@ -1461,7 +1474,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       }),
     });
     const workflow = new StateGraph(StateAnnotation)
-      .addNode(this.defaultAgentId, agentNode, { ends: [END] })
+      .addNode(
+        this.defaultAgentId,
+        agentNode as Runnable<
+          t.AgentSubgraphState,
+          Partial<t.AgentSubgraphState>
+        >,
+        { ends: [END] }
+      )
       .addEdge(START, this.defaultAgentId)
       // LangGraph compile() types are overly strict for opt-in options
       .compile(this.compileOptions as unknown as never);

package/src/graphs/__tests__/composition.smoke.test.ts

@@ -0,0 +1,188 @@
+import { HumanMessage } from '@langchain/core/messages';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { MultiAgentGraph } from '../MultiAgentGraph';
+import { Constants, Providers } from '@/common';
+import { StandardGraph } from '../Graph';
+
+const makeAgent = (agentId: string): t.AgentInputs => ({
+  agentId,
+  provider: Providers.OPENAI,
+  instructions: `You are ${agentId}.`,
+});
+
+const makeConfig = (threadId: string): RunnableConfig => ({
+  configurable: {
+    thread_id: threadId,
+  },
+});
+
+const makeStreamConfig = (threadId: string): t.WorkflowValuesStreamConfig => ({
+  ...makeConfig(threadId),
+  streamMode: 'values' as const,
+});
+
+const getAiContents = (messages: t.BaseGraphState['messages']): string[] =>
+  messages
+    .filter((message) => message.getType() === 'ai')
+    .map((message) => message.content)
+    .filter((content): content is string => typeof content === 'string');
+
+const expectCompiledWorkflow = (
+  workflow: t.CompiledWorkflow | t.CompiledMultiAgentWorkflow
+): void => {
+  expect(typeof workflow.invoke).toBe('function');
+  expect(typeof workflow.stream).toBe('function');
+};
+
+describe('LangGraph composition smoke tests', () => {
+  it('compiles and invokes the standard single-agent graph', async () => {
+    const graph = new StandardGraph({
+      runId: 'standard-smoke',
+      agents: [makeAgent('agent')],
+    });
+    graph.overrideTestModel(['standard ok']);
+
+    const workflow = graph.createWorkflow();
+    expectCompiledWorkflow(workflow);
+
+    const result = await workflow.invoke(
+      { messages: [new HumanMessage('hello')] },
+      makeConfig('standard-smoke')
+    );
+
+    expect(getAiContents(result.messages)).toEqual(['standard ok']);
+  });
+
+  it('streams values from the standard single-agent graph', async () => {
+    const graph = new StandardGraph({
+      runId: 'standard-stream-smoke',
+      agents: [makeAgent('agent')],
+    });
+    graph.overrideTestModel(['standard stream ok']);
+
+    const workflow = graph.createWorkflow();
+    const stream = (await workflow.stream(
+      { messages: [new HumanMessage('hello')] },
+      makeStreamConfig('standard-stream-smoke')
+    )) as AsyncIterable<t.BaseGraphState>;
+    const chunks: t.BaseGraphState[] = [];
+
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+
+    expect(chunks.length).toBeGreaterThan(0);
+    expect(
+      chunks.some((chunk) =>
+        getAiContents(chunk.messages).includes('standard stream ok')
+      )
+    ).toBe(true);
+  });
+
+  it('compiles and invokes a multi-agent graph with one agent and no edges', async () => {
+    const graph = new MultiAgentGraph({
+      runId: 'multi-single-smoke',
+      agents: [makeAgent('A')],
+      edges: [],
+    });
+    graph.overrideTestModel(['multi ok']);
+
+    const workflow = graph.createWorkflow();
+    expectCompiledWorkflow(workflow);
+
+    const result = await workflow.invoke(
+      { messages: [new HumanMessage('hello')] },
+      makeConfig('multi-single-smoke')
+    );
+
+    expect(getAiContents(result.messages)).toEqual(['multi ok']);
+  });
+
+  it('compiles and invokes direct sequential edges', async () => {
+    const graph = new MultiAgentGraph({
+      runId: 'direct-chain-smoke',
+      agents: [makeAgent('A'), makeAgent('B')],
+      edges: [{ from: 'A', to: 'B', edgeType: 'direct' }],
+    });
+    graph.overrideTestModel(['from A', 'from B']);
+
+    const workflow = graph.createWorkflow();
+    expectCompiledWorkflow(workflow);
+
+    const result = await workflow.invoke(
+      { messages: [new HumanMessage('start')] },
+      makeConfig('direct-chain-smoke')
+    );
+
+    expect(getAiContents(result.messages)).toEqual(['from A', 'from B']);
+  });
+
+  it('compiles and invokes a handoff edge using graph-managed transfer tools', async () => {
+    const transferToolCall: ToolCall = {
+      id: 'call_transfer_to_B',
+      name: `${Constants.LC_TRANSFER_TO_}B`,
+      args: { instructions: 'Take over from here.' },
+      type: 'tool_call',
+    };
+    const graph = new MultiAgentGraph({
+      runId: 'handoff-smoke',
+      agents: [makeAgent('A'), makeAgent('B')],
+      edges: [{ from: 'A', to: 'B', edgeType: 'handoff' }],
+    });
+    graph.overrideTestModel(['routing to B', 'handoff complete'], undefined, [
+      transferToolCall,
+    ]);
+
+    const workflow = graph.createWorkflow();
+    expectCompiledWorkflow(workflow);
+
+    const result = await workflow.invoke(
+      { messages: [new HumanMessage('start')] },
+      makeConfig('handoff-smoke')
+    );
+
+    expect(getAiContents(result.messages)).toContain('handoff complete');
+  });
+
+  it('compiles fan-out/fan-in direct composition with prompt wrapping', () => {
+    const graph = new MultiAgentGraph({
+      runId: 'fan-in-smoke',
+      agents: [
+        makeAgent('root'),
+        makeAgent('left'),
+        makeAgent('right'),
+        makeAgent('final'),
+      ],
+      edges: [
+        { from: 'root', to: ['left', 'right'], edgeType: 'direct' },
+        {
+          from: ['left', 'right'],
+          to: 'final',
+          edgeType: 'direct',
+          prompt: 'Summarize these results:\n{results}',
+        },
+      ],
+    });
+
+    expectCompiledWorkflow(graph.createWorkflow());
+    expect(graph.getParallelGroupId('root')).toBeUndefined();
+    expect(graph.getParallelGroupId('left')).toBe(1);
+    expect(graph.getParallelGroupId('right')).toBe(1);
+    expect(graph.getParallelGroupId('final')).toBeUndefined();
+  });
+
+  it('compiles mixed handoff and direct routing from the same agent', () => {
+    const graph = new MultiAgentGraph({
+      runId: 'mixed-routing-smoke',
+      agents: [makeAgent('router'), makeAgent('handoff'), makeAgent('direct')],
+      edges: [
+        { from: 'router', to: 'handoff', edgeType: 'handoff' },
+        { from: 'router', to: 'direct', edgeType: 'direct' },
+      ],
+    });
+
+    expectCompiledWorkflow(graph.createWorkflow());
+  });
+});

package/src/index.ts

@@ -38,6 +38,9 @@ export * from './hooks';
 /* Types */
 export type * from './types';
 
+/* LangChain compatibility facade */
+export * from './langchain';
+
 /* LLM */
 export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';

package/src/langchain/google-common.ts

@@ -0,0 +1 @@
+export type { GoogleAIToolType } from '@langchain/google-common';

package/src/langchain/index.ts

@@ -0,0 +1,8 @@
+export * from './messages';
+export * from './prompts';
+export * from './runnables';
+export * from './tools';
+export * from './google-common';
+export * from './language_models/chat_models';
+export * from './messages/tool';
+export * from './openai';

package/src/langchain/language_models/chat_models.ts

@@ -0,0 +1 @@
+export type { BindToolsInput } from '@langchain/core/language_models/chat_models';

package/src/langchain/messages/tool.ts

@@ -0,0 +1,5 @@
+export type {
+  InvalidToolCall,
+  ToolCall,
+  ToolCallChunk,
+} from '@langchain/core/messages/tool';

package/src/langchain/messages.ts

@@ -0,0 +1,21 @@
+export {
+  AIMessage,
+  AIMessageChunk,
+  BaseMessage,
+  BaseMessageChunk,
+  HumanMessage,
+  SystemMessage,
+  ToolMessage,
+  getBufferString,
+  isAIMessage,
+  isBaseMessage,
+  isToolMessage,
+} from '@langchain/core/messages';
+
+export type {
+  BaseMessageFields,
+  MessageContent,
+  MessageContentText,
+  MessageContentImageUrl,
+  UsageMetadata,
+} from '@langchain/core/messages';

package/src/langchain/openai.ts

@@ -0,0 +1 @@
+export type { AzureOpenAIInput } from '@langchain/openai';

package/src/langchain/prompts.ts

@@ -0,0 +1 @@
+export { PromptTemplate } from '@langchain/core/prompts';

package/src/langchain/runnables.ts

@@ -0,0 +1,7 @@
+export {
+  Runnable,
+  RunnableLambda,
+  RunnableSequence,
+} from '@langchain/core/runnables';
+
+export type { RunnableConfig } from '@langchain/core/runnables';

package/src/langchain/tools.ts

@@ -0,0 +1,8 @@
+export {
+  DynamicStructuredTool,
+  StructuredTool,
+  Tool,
+  tool,
+} from '@langchain/core/tools';
+
+export type { StructuredToolInterface } from '@langchain/core/tools';

package/src/langchain/utils/env.ts

@@ -0,0 +1 @@
+export { getEnvironmentVariable } from '@langchain/core/utils/env';