@librechat/agents 3.1.76 → 3.1.77

package/src/hooks/types.ts

@@ -15,6 +15,7 @@ export const HOOK_EVENTS = [
   'PreToolUse',
   'PostToolUse',
   'PostToolUseFailure',
+  'PostToolBatch',
   'PermissionDenied',
   'SubagentStart',
   'SubagentStop',
@@ -100,6 +101,42 @@ export interface PostToolUseFailureHookInput extends BaseHookInput {
   turn?: number;
 }
 
+/**
+ * Per-tool result snapshot included in a `PostToolBatch` event. Mirrors
+ * the data PostToolUse / PostToolUseFailure get individually, but the
+ * batch view lets a single hook see the whole set so it can inject one
+ * consolidated convention/audit message rather than N per-tool ones.
+ */
+export interface PostToolBatchEntry {
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  toolUseId: string;
+  stepId?: string;
+  turn?: number;
+  /** Successful tool output, present only when `status === 'success'`. */
+  toolOutput?: unknown;
+  /** Error message, present only when `status === 'error'`. */
+  error?: string;
+  status: 'success' | 'error';
+}
+
+/**
+ * Fires once after every tool call in a single batch finishes (including
+ * any that were rejected via HITL). Lets a hook react to the batch as a
+ * whole — useful for "inject conventions once for the whole batch", batch
+ * audit logging, or coordinating cleanup that depends on knowing the full
+ * result set rather than streaming each tool's result independently.
+ *
+ * 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.
+ */
+export interface PostToolBatchHookInput extends BaseHookInput {
+  hook_event_name: 'PostToolBatch';
+  /** All tool calls (and their outcomes) from this batch, in batch order. */
+  entries: PostToolBatchEntry[];
+}
+
 export interface PermissionDeniedHookInput extends BaseHookInput {
   hook_event_name: 'PermissionDenied';
   toolName: string;
@@ -171,6 +208,7 @@ export type HookInput =
   | PreToolUseHookInput
   | PostToolUseHookInput
   | PostToolUseFailureHookInput
+  | PostToolBatchHookInput
   | PermissionDeniedHookInput
   | SubagentStartHookInput
   | SubagentStopHookInput
@@ -186,6 +224,7 @@ export type HookInputByEvent = {
   PreToolUse: PreToolUseHookInput;
   PostToolUse: PostToolUseHookInput;
   PostToolUseFailure: PostToolUseFailureHookInput;
+  PostToolBatch: PostToolBatchHookInput;
   PermissionDenied: PermissionDeniedHookInput;
   SubagentStart: SubagentStartHookInput;
   SubagentStop: SubagentStopHookInput;
@@ -206,6 +245,56 @@ export interface BaseHookOutput {
   preventContinuation?: boolean;
   /** Reason reported alongside `preventContinuation`. */
   stopReason?: string;
+  /**
+   * Marks this hook output as fire-and-forget for INFLUENCE only.
+   * When `true`, the SDK skips every other field on this output —
+   * `decision`, `additionalContext`, `updatedInput`,
+   * `preventContinuation`, `allowedDecisions`, `updatedOutput` are
+   * all ignored. The hook's return value cannot block, modify, or
+   * inject context, so it's safe to use for pure side effects
+   * (logging, metrics, webhooks).
+   *
+   * Important caveat: the hook's CALLBACK promise is still awaited
+   * by `executeHooks` (subject to the matcher's timeout and the
+   * default `DEFAULT_HOOK_TIMEOUT_MS`). The SDK does not
+   * speculatively detach hooks based on output shape, because the
+   * shape is only known after the promise resolves. For TRUE
+   * fire-and-forget where the agent doesn't wait at all, the hook
+   * body should detach its side effect itself and return
+   * immediately:
+   *
+   * @example
+   * ```ts
+   * async (input) => {
+   *   // Detach the slow work — the SDK awaits this hook's
+   *   // returned promise, which resolves immediately because we
+   *   // don't `await` the side effect.
+   *   void sendToLoggingService(input).catch(console.error);
+   *   return { async: true };
+   * };
+   * ```
+   *
+   * @example WRONG — the agent will block on the webhook
+   * ```ts
+   * async (input) => {
+   *   await sendToLoggingService(input);  // ← awaited, blocks
+   *   return { async: true };  // returning async:true doesn't undo the await
+   * };
+   * ```
+   *
+   * Mirrors Claude Code Agent SDK's `async` output, with the same
+   * "detach inside the hook body" pattern.
+   */
+  async?: boolean;
+  /**
+   * Optional advisory timeout in milliseconds for the background work
+   * a host has detached inside an `async: true` hook body. The SDK
+   * does not enforce this (the hook's own AbortSignal handling does)
+   * but the field is preserved on the wire so downstream
+   * observability can surface long-running side effects. Ignored
+   * unless `async` is true.
+   */
+  asyncTimeout?: number;
 }
 
 export type RunStartHookOutput = BaseHookOutput;
@@ -229,6 +318,19 @@ export interface PreToolUseHookOutput extends BaseHookOutput {
    * `updatedInput` to one hook per matcher to avoid confusing precedence.
    */
   updatedInput?: Record<string, unknown>;
+  /**
+   * Restricts which decisions the host UI is allowed to surface for this
+   * tool call when the hook returns `decision: 'ask'`. Pass to lock a
+   * tool down to a subset of `'approve' | 'reject' | 'edit' | 'respond'`
+   * — for example, `['approve', 'reject']` to forbid the user from
+   * editing the tool's args or substituting a custom response.
+   *
+   * The values flow into the resulting interrupt's
+   * `review_configs[i].allowed_decisions`. Omitting the field keeps the
+   * SDK default (all four decisions advertised). Last-writer-wins in
+   * registration order, same precedence rules as `updatedInput`.
+   */
+  allowedDecisions?: ReadonlyArray<'approve' | 'reject' | 'edit' | 'respond'>;
 }
 
 export interface PostToolUseHookOutput extends BaseHookOutput {
@@ -243,6 +345,8 @@ export interface PostToolUseHookOutput extends BaseHookOutput {
 
 export type PostToolUseFailureHookOutput = BaseHookOutput;
 
+export type PostToolBatchHookOutput = BaseHookOutput;
+
 export type PermissionDeniedHookOutput = BaseHookOutput;
 
 export interface SubagentStartHookOutput extends BaseHookOutput {
@@ -270,6 +374,7 @@ export type HookOutputByEvent = {
   PreToolUse: PreToolUseHookOutput;
   PostToolUse: PostToolUseHookOutput;
   PostToolUseFailure: PostToolUseFailureHookOutput;
+  PostToolBatch: PostToolBatchHookOutput;
   PermissionDenied: PermissionDeniedHookOutput;
   SubagentStart: SubagentStartHookOutput;
   SubagentStop: SubagentStopHookOutput;
@@ -286,6 +391,7 @@ export type HookOutput =
   | PreToolUseHookOutput
   | PostToolUseHookOutput
   | PostToolUseFailureHookOutput
+  | PostToolBatchHookOutput
   | PermissionDeniedHookOutput
   | SubagentStartHookOutput
   | SubagentStopHookOutput
@@ -381,6 +487,12 @@ export interface AggregatedHookResult {
    * hook per matcher to avoid subtle precedence bugs.
    */
   updatedInput?: Record<string, unknown>;
+  /**
+   * Restricted decision set from a `PreToolUse` hook. Same last-writer-wins
+   * semantics as `updatedInput`. Surfaces to the interrupt payload's
+   * `review_configs[i].allowed_decisions`.
+   */
+  allowedDecisions?: ReadonlyArray<'approve' | 'reject' | 'edit' | 'respond'>;
   /**
    * Replacement tool output from a `PostToolUse` hook.
    *

package/src/index.ts

@@ -35,12 +35,31 @@ export * from './utils';
 /* Hooks */
 export * from './hooks';
 
+/* HITL helpers */
+export * from './hitl';
+
 /* Types */
 export type * from './types';
 
 /* LangChain compatibility facade */
 export * from './langchain';
 
+/**
+ * HITL primitives re-exported from `@langchain/langgraph` so hosts that
+ * build durable checkpoint savers, dispatch `Command({ resume })`, or
+ * detect interrupts can do so against the same langgraph instance the
+ * SDK was compiled against — avoiding accidental dual-version drift.
+ */
+export {
+  Command,
+  INTERRUPT,
+  interrupt,
+  MemorySaver,
+  BaseCheckpointSaver,
+  isInterrupted,
+} from '@langchain/langgraph';
+export type { Interrupt } from '@langchain/langgraph';
+
 /* LLM */
 export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';

package/src/llm/openai/deepseek.test.ts

@@ -0,0 +1,479 @@
+import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
+import type { ChatGenerationChunk } from '@langchain/core/outputs';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { OpenAIClient } from '@langchain/openai';
+
+import { ChatDeepSeek } from './index';
+
+type DeepSeekRequest =
+  | OpenAIClient.Chat.ChatCompletionCreateParamsStreaming
+  | OpenAIClient.Chat.ChatCompletionCreateParamsNonStreaming;
+type OpenAIChatCompletion = OpenAIClient.Chat.Completions.ChatCompletion;
+type OpenAIChatCompletionChunk =
+  OpenAIClient.Chat.Completions.ChatCompletionChunk;
+type ReasoningAssistantMessageParam =
+  OpenAIClient.Chat.Completions.ChatCompletionAssistantMessageParam & {
+    reasoning_content?: string;
+  };
+
+class CapturingChatDeepSeek extends ChatDeepSeek {
+  readonly requests: DeepSeekRequest[] = [];
+
+  constructor(
+    fields: ConstructorParameters<typeof ChatDeepSeek>[0],
+    private readonly streamChunks = createCompletionStreamChunks(),
+    private readonly completion = createCompletion()
+  ) {
+    super(fields);
+  }
+
+  async completionWithRetry(
+    request: OpenAIClient.Chat.ChatCompletionCreateParamsStreaming,
+    requestOptions?: OpenAIClient.RequestOptions
+  ): Promise<AsyncIterable<OpenAIChatCompletionChunk>>;
+  async completionWithRetry(
+    request: OpenAIClient.Chat.ChatCompletionCreateParamsNonStreaming,
+    requestOptions?: OpenAIClient.RequestOptions
+  ): Promise<OpenAIChatCompletion>;
+  async completionWithRetry(
+    request: DeepSeekRequest,
+    _requestOptions?: OpenAIClient.RequestOptions
+  ): Promise<AsyncIterable<OpenAIChatCompletionChunk> | OpenAIChatCompletion> {
+    this.requests.push(request);
+
+    if (request.stream === true) {
+      return createCompletionStream(this.streamChunks);
+    }
+
+    return this.completion;
+  }
+
+  streamChunksWithSignal(
+    signal: AbortSignal
+  ): AsyncGenerator<ChatGenerationChunk> {
+    return this._streamResponseChunks([new HumanMessage('hi')], {
+      signal,
+    } as this['ParsedCallOptions']);
+  }
+}
+
+function createToolContextMessages(): BaseMessage[] {
+  return [
+    new AIMessage({
+      content: '',
+      tool_calls: [
+        {
+          id: 'call_1',
+          name: 'web_search',
+          args: { query: 'trending news today' },
+          type: 'tool_call',
+        },
+      ],
+      additional_kwargs: {
+        reasoning_content: 'Need current news from the web.',
+      },
+    }),
+    new ToolMessage({
+      content: 'Search results',
+      tool_call_id: 'call_1',
+    }),
+  ];
+}
+
+function createCompletionStreamChunks(): OpenAIChatCompletionChunk[] {
+  return [
+    createContentChunk('ok'),
+    {
+      id: 'chatcmpl-deepseek-test',
+      object: 'chat.completion.chunk',
+      created: 0,
+      model: 'deepseek-v4-pro',
+      choices: [
+        {
+          index: 0,
+          delta: {},
+          finish_reason: 'stop',
+          logprobs: null,
+        },
+      ],
+    },
+  ];
+}
+
+function createContentChunk(content: string): OpenAIChatCompletionChunk {
+  return {
+    id: 'chatcmpl-deepseek-test',
+    object: 'chat.completion.chunk',
+    created: 0,
+    model: 'deepseek-v4-pro',
+    choices: [
+      {
+        index: 0,
+        delta: {
+          role: 'assistant',
+          content,
+        },
+        finish_reason: null,
+        logprobs: null,
+      },
+    ],
+  };
+}
+
+async function* createCompletionStream(
+  chunks: OpenAIChatCompletionChunk[]
+): AsyncGenerator<OpenAIChatCompletionChunk> {
+  for (const chunk of chunks) {
+    yield chunk;
+  }
+}
+
+function createCompletion(
+  usage: OpenAIClient.Completions.CompletionUsage = {
+    prompt_tokens: 1,
+    completion_tokens: 1,
+    total_tokens: 2,
+  }
+): OpenAIChatCompletion {
+  return {
+    id: 'chatcmpl-deepseek-test',
+    object: 'chat.completion',
+    created: 0,
+    model: 'deepseek-v4-pro',
+    choices: [
+      {
+        index: 0,
+        message: {
+          role: 'assistant',
+          content: 'ok',
+          refusal: null,
+        },
+        finish_reason: 'stop',
+        logprobs: null,
+      },
+    ],
+    usage,
+  };
+}
+
+function getReasoningAssistantMessage(
+  request: DeepSeekRequest
+): ReasoningAssistantMessageParam {
+  return request.messages[0] as ReasoningAssistantMessageParam;
+}
+
+async function drainStream(stream: AsyncIterable<unknown>): Promise<void> {
+  for await (const chunk of stream) {
+    void chunk;
+  }
+}
+
+describe('ChatDeepSeek', () => {
+  it('passes reasoning_content back on same-run streaming tool continuations', async () => {
+    const model = new CapturingChatDeepSeek({
+      apiKey: 'test-key',
+      model: 'deepseek-v4-pro',
+      streaming: true,
+    });
+    const chunks = [];
+
+    for await (const chunk of await model.stream(createToolContextMessages())) {
+      chunks.push(chunk);
+    }
+
+    expect(chunks).toHaveLength(2);
+    expect(model.requests).toHaveLength(1);
+    expect(getReasoningAssistantMessage(model.requests[0])).toEqual(
+      expect.objectContaining({
+        role: 'assistant',
+        content: '',
+        reasoning_content: 'Need current news from the web.',
+      })
+    );
+  });
+
+  it('passes reasoning_content back on same-run non-streaming tool continuations', async () => {
+    const model = new CapturingChatDeepSeek({
+      apiKey: 'test-key',
+      model: 'deepseek-v4-pro',
+      streaming: false,
+    });
+
+    await model.invoke(createToolContextMessages());
+
+    expect(model.requests).toHaveLength(1);
+    expect(getReasoningAssistantMessage(model.requests[0])).toEqual(
+      expect.objectContaining({
+        role: 'assistant',
+        content: '',
+        reasoning_content: 'Need current news from the web.',
+      })
+    );
+  });
+
+  it('keeps raw think fallback content out of streamed assistant content', async () => {
+    const model = new CapturingChatDeepSeek(
+      {
+        apiKey: 'test-key',
+        model: 'deepseek-v4-pro',
+        streaming: true,
+      },
+      [
+        createContentChunk('prefix <thi'),
+        createContentChunk('nk>hidden'),
+        createContentChunk('</think>visible'),
+      ]
+    );
+    const chunks = [];
+    const callbackTokens: string[] = [];
+
+    const stream = await model.stream([new HumanMessage('hi')], {
+      callbacks: [
+        {
+          handleLLMNewToken(token: string): void {
+            callbackTokens.push(token);
+          },
+        },
+      ],
+    });
+
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+
+    const streamedText = chunks
+      .map((chunk) => (typeof chunk.content === 'string' ? chunk.content : ''))
+      .join('');
+    const hasHiddenReasoning = chunks.some(
+      (chunk) => chunk.additional_kwargs.reasoning_content === 'hidden'
+    );
+
+    expect(streamedText).toBe('prefix visible');
+    expect(callbackTokens.join('')).toBe('prefix visible');
+    expect(callbackTokens.join('')).not.toContain('hidden');
+    expect(callbackTokens.join('')).not.toContain('think');
+    expect(hasHiddenReasoning).toBe(true);
+  });
+
+  it('keeps multiple raw think fallback blocks hidden from content and callbacks', async () => {
+    const model = new CapturingChatDeepSeek(
+      {
+        apiKey: 'test-key',
+        model: 'deepseek-v4-pro',
+        streaming: true,
+      },
+      [
+        createContentChunk(
+          'before<think>hidden one</think>visible<think>hidden two</think>done'
+        ),
+      ]
+    );
+    const chunks = [];
+    const callbackTokens: string[] = [];
+
+    const stream = await model.stream([new HumanMessage('hi')], {
+      callbacks: [
+        {
+          handleLLMNewToken(token: string): void {
+            callbackTokens.push(token);
+          },
+        },
+      ],
+    });
+
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+
+    const streamedText = chunks
+      .map((chunk) => (typeof chunk.content === 'string' ? chunk.content : ''))
+      .join('');
+    const reasoningContent = chunks
+      .map((chunk) => chunk.additional_kwargs.reasoning_content)
+      .filter((content): content is string => typeof content === 'string');
+
+    expect(streamedText).toBe('beforevisibledone');
+    expect(callbackTokens.join('')).toBe('beforevisibledone');
+    expect(reasoningContent).toEqual(['hidden one', 'hidden two']);
+  });
+
+  it('keeps cross-chunk multiple raw think fallback blocks hidden from content and callbacks', async () => {
+    const model = new CapturingChatDeepSeek(
+      {
+        apiKey: 'test-key',
+        model: 'deepseek-v4-pro',
+        streaming: true,
+      },
+      [
+        createContentChunk('before<think>hidden one</thi'),
+        createContentChunk('nk>visible<thi'),
+        createContentChunk('nk>hidden two</think>done'),
+      ]
+    );
+    const chunks = [];
+    const callbackTokens: string[] = [];
+
+    const stream = await model.stream([new HumanMessage('hi')], {
+      callbacks: [
+        {
+          handleLLMNewToken(token: string): void {
+            callbackTokens.push(token);
+          },
+        },
+      ],
+    });
+
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+
+    const streamedText = chunks
+      .map((chunk) => (typeof chunk.content === 'string' ? chunk.content : ''))
+      .join('');
+    const reasoningContent = chunks
+      .map((chunk) => chunk.additional_kwargs.reasoning_content)
+      .filter((content): content is string => typeof content === 'string');
+
+    expect(streamedText).toBe('beforevisibledone');
+    expect(callbackTokens.join('')).toBe('beforevisibledone');
+    expect(reasoningContent).toEqual(['hidden one', 'hidden two']);
+  });
+
+  it('emits trailing unfinished raw think fallback as reasoning content', async () => {
+    const model = new CapturingChatDeepSeek(
+      {
+        apiKey: 'test-key',
+        model: 'deepseek-v4-pro',
+        streaming: true,
+      },
+      [createContentChunk('<think>truncated')]
+    );
+    const chunks = [];
+    const callbackTokens: string[] = [];
+
+    const stream = await model.stream([new HumanMessage('hi')], {
+      callbacks: [
+        {
+          handleLLMNewToken(token: string): void {
+            callbackTokens.push(token);
+          },
+        },
+      ],
+    });
+
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+
+    const streamedText = chunks
+      .map((chunk) => (typeof chunk.content === 'string' ? chunk.content : ''))
+      .join('');
+    const reasoningContent = chunks
+      .map((chunk) => chunk.additional_kwargs.reasoning_content)
+      .filter((content): content is string => typeof content === 'string');
+
+    expect(streamedText).toBe('');
+    expect(callbackTokens.join('')).toBe('');
+    expect(reasoningContent).toEqual(['truncated']);
+  });
+
+  it('preserves detailed usage metadata in non-streaming responses', async () => {
+    const model = new CapturingChatDeepSeek(
+      {
+        apiKey: 'test-key',
+        model: 'deepseek-v4-pro',
+        streaming: false,
+      },
+      createCompletionStreamChunks(),
+      createCompletion({
+        prompt_tokens: 11,
+        completion_tokens: 7,
+        total_tokens: 18,
+        prompt_tokens_details: {
+          audio_tokens: 2,
+          cached_tokens: 3,
+        },
+        completion_tokens_details: {
+          audio_tokens: 4,
+          reasoning_tokens: 5,
+        },
+      })
+    );
+
+    const response = await model.invoke([new HumanMessage('hi')]);
+
+    expect(response.usage_metadata).toEqual({
+      input_tokens: 11,
+      output_tokens: 7,
+      total_tokens: 18,
+      input_token_details: {
+        audio: 2,
+        cache_read: 3,
+      },
+      output_token_details: {
+        audio: 4,
+        reasoning: 5,
+      },
+    });
+  });
+
+  it('does not serialize non-streaming requests when aborted before generation', async () => {
+    const controller = new AbortController();
+    const model = new CapturingChatDeepSeek({
+      apiKey: 'test-key',
+      model: 'deepseek-v4-pro',
+      streaming: false,
+    });
+
+    controller.abort();
+
+    await expect(
+      model.invoke([new HumanMessage('hi')], {
+        signal: controller.signal,
+      })
+    ).rejects.toThrow();
+    expect(model.requests).toHaveLength(0);
+  });
+
+  it('throws AbortError when a DeepSeek stream is canceled', async () => {
+    const controller = new AbortController();
+    const model = new CapturingChatDeepSeek({
+      apiKey: 'test-key',
+      model: 'deepseek-v4-pro',
+      streaming: true,
+    });
+
+    controller.abort();
+
+    await expect(
+      drainStream(model.streamChunksWithSignal(controller.signal))
+    ).rejects.toThrow('AbortError');
+  });
+
+  it('throws AbortError when a DeepSeek stream is canceled mid-stream', async () => {
+    const controller = new AbortController();
+    const model = new CapturingChatDeepSeek(
+      {
+        apiKey: 'test-key',
+        model: 'deepseek-v4-pro',
+        streaming: true,
+      },
+      [createContentChunk('first '), createContentChunk('second')]
+    );
+    const stream = model.streamChunksWithSignal(controller.signal);
+    const iterator = stream[Symbol.asyncIterator]();
+
+    await expect(iterator.next()).resolves.toEqual(
+      expect.objectContaining({
+        done: false,
+        value: expect.objectContaining({
+          text: 'first ',
+        }),
+      })
+    );
+
+    controller.abort();
+
+    await expect(iterator.next()).rejects.toThrow('AbortError');
+  });
+});