@librechat/agents 3.2.60 → 3.2.62

package/src/hooks/__tests__/executeHooks.test.ts

@@ -155,7 +155,11 @@ describe('executeHooks', () => {
         input: preToolUseInput('Bash'),
         matchQuery: 'Bash',
       });
-      expect(result).toEqual({ additionalContexts: [], errors: [] });
+      expect(result).toEqual({
+        additionalContexts: [],
+        injectedMessages: [],
+        errors: [],
+      });
     });
 
     it('returns an empty result when no matcher pattern matches the query', async () => {
@@ -176,7 +180,11 @@ describe('executeHooks', () => {
         matchQuery: 'Bash',
       });
       expect(called).toBe(false);
-      expect(result).toEqual({ additionalContexts: [], errors: [] });
+      expect(result).toEqual({
+        additionalContexts: [],
+        injectedMessages: [],
+        errors: [],
+      });
     });
   });
 
@@ -439,6 +447,81 @@ describe('executeHooks', () => {
     });
   });
 
+  describe('injectedMessages accumulation', () => {
+    it('accumulates injectedMessages from every hook in registration order', async () => {
+      const registry = new HookRegistry();
+      registry.register('PreToolUse', {
+        hooks: [
+          preToolHook(
+            async (): Promise<PreToolUseHookOutput> => ({
+              injectedMessages: [
+                { role: 'user', content: 'steer one', source: 'steer' },
+              ],
+            })
+          ),
+          preToolHook(
+            async (): Promise<PreToolUseHookOutput> => emptyPreOutput
+          ),
+        ],
+      });
+      registry.register('PreToolUse', {
+        hooks: [
+          preToolHook(
+            async (): Promise<PreToolUseHookOutput> => ({
+              injectedMessages: [
+                { role: 'user', content: 'steer two', source: 'steer' },
+                { role: 'system', content: 'hint', source: 'hook' },
+              ],
+            })
+          ),
+        ],
+      });
+      const result = await executeHooks({
+        registry,
+        input: preToolUseInput('Bash'),
+        matchQuery: 'Bash',
+      });
+      expect(result.injectedMessages).toEqual([
+        { role: 'user', content: 'steer one', source: 'steer' },
+        { role: 'user', content: 'steer two', source: 'steer' },
+        { role: 'system', content: 'hint', source: 'hook' },
+      ]);
+    });
+
+    it('returns an empty array when no hook sets injectedMessages', async () => {
+      const registry = new HookRegistry();
+      registry.register('PreToolUse', { hooks: [noopPreHook] });
+      const result = await executeHooks({
+        registry,
+        input: preToolUseInput('Bash'),
+        matchQuery: 'Bash',
+      });
+      expect(result.injectedMessages).toEqual([]);
+    });
+
+    it('skips injectedMessages from fire-and-forget (async) outputs', async () => {
+      const registry = new HookRegistry();
+      registry.register('PreToolUse', {
+        hooks: [
+          preToolHook(
+            async (): Promise<PreToolUseHookOutput> => ({
+              async: true,
+              injectedMessages: [
+                { role: 'user', content: 'ignored', source: 'steer' },
+              ],
+            })
+          ),
+        ],
+      });
+      const result = await executeHooks({
+        registry,
+        input: preToolUseInput('Bash'),
+        matchQuery: 'Bash',
+      });
+      expect(result.injectedMessages).toEqual([]);
+    });
+  });
+
   describe('updatedInput handling', () => {
     it('last-writer-wins on updatedInput follows registration order', async () => {
       const registry = new HookRegistry();

package/src/hooks/executeHooks.ts

@@ -54,6 +54,7 @@ interface AbortRace {
 function freshResult(): AggregatedHookResult {
   return {
     additionalContexts: [],
+    injectedMessages: [],
     errors: [],
   };
 }
@@ -244,6 +245,19 @@ function applyContext(agg: AggregatedHookResult, output: HookOutput): void {
   }
 }
 
+function applyInjectedMessages(
+  agg: AggregatedHookResult,
+  output: HookOutput
+): void {
+  if (
+    output.injectedMessages === undefined ||
+    output.injectedMessages.length === 0
+  ) {
+    return;
+  }
+  agg.injectedMessages.push(...output.injectedMessages);
+}
+
 function applyStopFlag(agg: AggregatedHookResult, output: HookOutput): void {
   if (output.preventContinuation !== true) {
     return;
@@ -310,6 +324,7 @@ function fold(outcomes: readonly HookOutcome[]): AggregatedHookResult {
       continue;
     }
     applyContext(agg, output);
+    applyInjectedMessages(agg, output);
     applyStopFlag(agg, output);
     applyDecision(agg, output);
     applyUpdatedInput(agg, output);

package/src/hooks/index.ts

@@ -9,6 +9,13 @@
 export { HookRegistry } from './HookRegistry';
 export type { HookHaltSignal } from './HookRegistry';
 export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
+/**
+ * Feature probe for hosts: hook outputs support `injectedMessages`
+ * (per-message graph-state injection at the `PostToolBatch` boundary).
+ * Hosts must gate drain-style hooks on this so a queued message can never
+ * be consumed by an SDK version that would silently drop it.
+ */
+export const HOOK_INJECTED_MESSAGES_CAPABLE = true;
 export {
   matchesQuery,
   hasNestedQuantifier,

package/src/hooks/types.ts

@@ -1,5 +1,6 @@
 // src/hooks/types.ts
 import type { BaseMessage } from '@langchain/core/messages';
+import type { InjectedMessage } from '@/types/tools';
 
 /**
  * Closed set of hook lifecycle events supported by the hooks system.
@@ -134,7 +135,9 @@ export interface PostToolBatchEntry {
  *
  * Order: fires AFTER all per-tool PostToolUse / PostToolUseFailure hooks
  * for the same batch have completed, BEFORE the next model call. Pass an
- * `additionalContext` to inject context for that next model turn.
+ * `additionalContext` to inject context for that next model turn, or
+ * `injectedMessages` to inject standalone per-message user speech (e.g.
+ * mid-run steering) that must not be consolidated with hook context.
  */
 export interface PostToolBatchHookInput extends BaseHookInput {
   hook_event_name: 'PostToolBatch';
@@ -246,6 +249,18 @@ export type HookInputByEvent = {
 export interface BaseHookOutput {
   /** Context string to inject into the conversation. Accumulated across hooks. */
   additionalContext?: string;
+  /**
+   * Messages to inject into graph state, one `HumanMessage` per entry
+   * (converted via `ToolNode.convertInjectedMessages`, which preserves
+   * `role`/`source`/`isMeta` in `additional_kwargs`). Unlike
+   * `additionalContext` — which is consolidated across hooks into a single
+   * system-flavored message — each entry keeps its own identity and role,
+   * making this the channel for injecting verbatim user speech (e.g. a
+   * mid-run steering message). Accumulated across hooks in registration
+   * order. Currently consumed only at the `PostToolBatch` dispatch site;
+   * other events ignore the field.
+   */
+  injectedMessages?: InjectedMessage[];
   /** True to prevent the next model turn. Any hook can set this. */
   preventContinuation?: boolean;
   /** Reason reported alongside `preventContinuation`. */
@@ -508,6 +523,8 @@ export interface AggregatedHookResult {
   updatedOutput?: unknown;
   /** Accumulated `additionalContext` strings from every hook, in order. */
   additionalContexts: string[];
+  /** Accumulated `injectedMessages` from every hook, in registration order. */
+  injectedMessages: InjectedMessage[];
   /** True if any hook returned `preventContinuation`. */
   preventContinuation?: boolean;
   /**

package/src/langfuse.ts

@@ -1,9 +1,20 @@
 import { CallbackHandler } from '@langfuse/langchain';
 import { context as otelContext } from '@opentelemetry/api';
+import { AIMessage, AIMessageChunk } from '@langchain/core/messages';
 import {
   getLangfuseTracerProvider,
   propagateAttributes,
 } from '@langfuse/tracing';
+import type {
+  AIMessageChunkFields,
+  AIMessageFields,
+  UsageMetadata,
+} from '@langchain/core/messages';
+import type {
+  ChatGeneration,
+  Generation,
+  LLMResult,
+} from '@langchain/core/outputs';
 import type { PropagateAttributesParams } from '@langfuse/tracing';
 import type * as t from '@/types';
 import {
@@ -43,6 +54,116 @@ type FlushableTracerProvider = {
   forceFlush?: () => Promise<void> | void;
 };
 
+type BedrockResponseUsage = {
+  inputTokens?: number;
+  cacheReadInputTokens?: number;
+  cacheWriteInputTokens?: number;
+};
+
+type BedrockResponseMetadata = {
+  metadata?: {
+    usage?: BedrockResponseUsage;
+  };
+};
+
+function getLangfuseBedrockUsage(
+  message: AIMessage | AIMessageChunk
+): UsageMetadata | undefined {
+  const usageMetadata = message.usage_metadata;
+  const bedrockUsage = (message.response_metadata as BedrockResponseMetadata)
+    .metadata?.usage;
+  if (
+    usageMetadata == null ||
+    bedrockUsage == null ||
+    usageMetadata.input_tokens !== bedrockUsage.inputTokens
+  ) {
+    return usageMetadata;
+  }
+
+  const cacheRead = bedrockUsage.cacheReadInputTokens ?? 0;
+  const cacheCreation = bedrockUsage.cacheWriteInputTokens ?? 0;
+  if (cacheRead === 0 && cacheCreation === 0) {
+    return usageMetadata;
+  }
+
+  return {
+    ...usageMetadata,
+    input_tokens: usageMetadata.input_tokens + cacheRead + cacheCreation,
+  };
+}
+
+function cloneMessageWithUsage(
+  message: AIMessage | AIMessageChunk,
+  usageMetadata: UsageMetadata
+): AIMessage | AIMessageChunk {
+  const fields: AIMessageFields = {
+    content: message.content,
+    additional_kwargs: message.additional_kwargs,
+    response_metadata: message.response_metadata,
+    id: message.id,
+    name: message.name,
+    tool_calls: message.tool_calls,
+    invalid_tool_calls: message.invalid_tool_calls,
+    usage_metadata: usageMetadata,
+  };
+
+  if (message instanceof AIMessageChunk) {
+    const chunkFields: AIMessageChunkFields = {
+      ...fields,
+      tool_call_chunks: message.tool_call_chunks,
+    };
+    return new AIMessageChunk(chunkFields);
+  }
+
+  return new AIMessage(fields);
+}
+
+function normalizeGenerationForLangfuse(generation: Generation): Generation {
+  if (!('message' in generation)) {
+    return generation;
+  }
+
+  const message = (generation as ChatGeneration).message;
+  if (!(message instanceof AIMessage || message instanceof AIMessageChunk)) {
+    return generation;
+  }
+
+  const usageMetadata = getLangfuseBedrockUsage(message);
+  if (usageMetadata == null || usageMetadata === message.usage_metadata) {
+    return generation;
+  }
+
+  const chatGeneration: ChatGeneration = {
+    ...(generation as ChatGeneration),
+    message: cloneMessageWithUsage(message, usageMetadata),
+  };
+  return chatGeneration;
+}
+
+function normalizeBedrockUsageForLangfuse(output: LLMResult): LLMResult {
+  if (output.generations.length === 0) {
+    return output;
+  }
+
+  const listIndex = output.generations.length - 1;
+  const generationList = output.generations[listIndex];
+  if (generationList.length === 0) {
+    return output;
+  }
+
+  const generationIndex = generationList.length - 1;
+  const generation = generationList[generationIndex];
+  const normalized = normalizeGenerationForLangfuse(generation);
+  if (normalized === generation) {
+    return output;
+  }
+
+  const generations = [...output.generations];
+  generations[listIndex] = [...generationList];
+  generations[listIndex][generationIndex] = normalized;
+  return { ...output, generations };
+}
+
 class ScopedLangfuseCallbackHandler extends CallbackHandler {
   private readonly langfuse?: t.LangfuseConfig;
   private readonly traceIdSeed?: string;
@@ -107,6 +228,18 @@ class ScopedLangfuseCallbackHandler extends CallbackHandler {
     return this.withRuntimeContext(() => super.handleLLMStart(...args));
   }
 
+  override handleLLMEnd(
+    output: LLMResult,
+    runId: string,
+    parentRunId?: string
+  ): Promise<void> {
+    return super.handleLLMEnd(
+      normalizeBedrockUsageForLangfuse(output),
+      runId,
+      parentRunId
+    );
+  }
+
   override handleToolStart(
     ...args: Parameters<CallbackHandler['handleToolStart']>
   ): ReturnType<CallbackHandler['handleToolStart']> {
@@ -351,7 +484,7 @@ export function isLangfuseCallbackHandler(value: unknown): boolean {
 export async function disposeLangfuseHandler(value: unknown): Promise<void> {
   if (
     value == null ||
-    !parseBooleanEnv(process.env[LANGFUSE_FORCE_FLUSH_ON_DISPOSE])
+    parseBooleanEnv(process.env[LANGFUSE_FORCE_FLUSH_ON_DISPOSE]) !== true
   ) {
     return;
   }