@librechat/agents 3.1.75 → 3.1.77-dev.1

package/src/types/hitl.ts

@@ -0,0 +1,303 @@
+/**
+ * First-class human-in-the-loop (HITL) types for `@librechat/agents`.
+ * Surfaces the interrupt payload that `ToolNode` raises when a `PreToolUse`
+ * hook returns `decision: 'ask'` and HITL is enabled on the run, plus the
+ * resume-decision shape the host returns to continue or reject the tool.
+ *
+ * Mirrors the LangChain HITL middleware shape (action_requests /
+ * review_configs) so hosts and clients can share rendering/UI semantics
+ * across the langchain ecosystem.
+ */
+
+/** Per-tool approval request emitted inside an interrupt payload. */
+export interface ToolApprovalRequest {
+  /** Stable id of the tool call (matches LangGraph `ToolCall.id`). */
+  tool_call_id: string;
+  /** Tool name being invoked. */
+  name: string;
+  /**
+   * Arguments the tool is about to be invoked with — already resolved by
+   * any `{{tool<i>turn<n>}}` references and any `updatedInput` returned
+   * by the firing PreToolUse hook.
+   */
+  arguments: Record<string, unknown>;
+  /**
+   * Optional reason the hook supplied for asking (e.g., "destructive
+   * filesystem write"). Hosts can render this verbatim.
+   */
+  description?: string;
+}
+
+/** Allowed host-side decisions for a `tool_approval` interrupt. */
+export type ToolApprovalDecisionType =
+  | 'approve'
+  | 'reject'
+  | 'edit'
+  | 'respond';
+
+/** Per-action review configuration paired with each action_request. */
+export interface ToolApprovalReviewConfig {
+  /** Tool name (matches the `name` field on the corresponding action_request). */
+  action_name: string;
+  /**
+   * Stable id of the tool call this review_config applies to (matches
+   * the `tool_call_id` of the corresponding action_request). Lets a UI
+   * map review_configs → action_requests directly when a batch
+   * contains the same tool called more than once — by-position
+   * mapping breaks down with duplicates.
+   */
+  tool_call_id: string;
+  /** Decisions the host UI is allowed to surface for this action. */
+  allowed_decisions: ToolApprovalDecisionType[];
+}
+
+/**
+ * Resume value the host returns through `Run.resume(decisions)` after a
+ * `tool_approval` interrupt. One entry per action_request, in the same
+ * order. Hosts may also return a record keyed by `tool_call_id`; the SDK
+ * handles either shape.
+ *
+ * Variants:
+ *   - `approve`: run the tool with its original (or hook-rewritten) args.
+ *   - `reject`: skip the tool, emit a blocked error `ToolMessage` with
+ *     `reason` surfaced to the model.
+ *   - `edit`: replace the tool's args with `updatedInput` (re-resolves
+ *     any `{{tool<i>turn<n>}}` placeholders) and run the tool.
+ *   - `respond`: skip the tool entirely and emit `responseText` as a
+ *     successful `ToolMessage`. Mirrors LangChain HITL middleware's
+ *     `respond` semantic — the human supplies the result the model sees,
+ *     bypassing tool execution. Useful when the user wants to short-circuit
+ *     a tool call with a hand-written answer (e.g., "don't actually run
+ *     the search, just tell the model 'no relevant results'").
+ *
+ * Note on hook semantics: `respond` does NOT fire the per-tool
+ * `PostToolUse` hook (no real tool execution happened, so the
+ * "post-tool" semantic doesn't apply). It DOES appear in the
+ * `PostToolBatch` entry array with `status: 'success'` and the
+ * user-supplied text as `toolOutput`, so batch-level audit /
+ * convention hooks see the full set of outcomes.
+ */
+export type ToolApprovalDecision =
+  | { type: 'approve' }
+  | { type: 'reject'; reason?: string }
+  | { type: 'edit'; updatedInput: Record<string, unknown> }
+  | { type: 'respond'; responseText: string };
+
+/** Map form of resume decisions, keyed by tool call id. */
+export type ToolApprovalDecisionMap = Record<string, ToolApprovalDecision>;
+
+/**
+ * Categories of human-in-the-loop interrupts the SDK can raise. Hosts
+ * narrow on `HumanInterruptPayload.type` to determine which payload
+ * shape they're handling and which resume value to send back through
+ * `Run.resume()`.
+ *
+ * Exported as a discrete type so downstream consumers (notably
+ * LibreChat's wire types in `librechat-data-provider`) can mirror
+ * the discriminator alongside their own host-side `PendingAction`
+ * record without re-declaring the union themselves. Internal SDK
+ * code narrows directly on the literal strings via the type guards
+ * below; this type alias is primarily an integration-layer contract.
+ */
+export type HumanInterruptType = 'tool_approval' | 'ask_user_question';
+
+/**
+ * Structured payload the SDK passes to `interrupt()` when one or more
+ * pending tool calls require host approval. All `ask`-decision tool calls
+ * from a single ToolNode batch are bundled into one interrupt so the host
+ * can render and resolve them together.
+ *
+ * Resume value: `ToolApprovalDecision[]` (in `action_requests` order) or
+ * `ToolApprovalDecisionMap` (keyed by `tool_call_id`).
+ */
+export interface ToolApprovalInterruptPayload {
+  type: 'tool_approval';
+  action_requests: ToolApprovalRequest[];
+  review_configs: ToolApprovalReviewConfig[];
+}
+
+/**
+ * Pre-defined option the user can pick when answering an
+ * `ask_user_question` interrupt. The selected option's `value` becomes
+ * the resume value's `answer` field.
+ */
+export interface AskUserQuestionOption {
+  /** Human-readable label rendered in the host UI. */
+  label: string;
+  /** Value returned via `AskUserQuestionResolution.answer` if picked. */
+  value: string;
+}
+
+/** Question request emitted inside an `ask_user_question` interrupt. */
+export interface AskUserQuestionRequest {
+  /** The question to ask the human. */
+  question: string;
+  /** Optional context / description rendered alongside the question. */
+  description?: string;
+  /**
+   * Optional pre-defined response options. When present, hosts can render
+   * a picker; the user may still type a free-form answer when the host
+   * UI allows it. Omit to require a free-form answer.
+   */
+  options?: AskUserQuestionOption[];
+}
+
+/**
+ * Structured payload the SDK passes to `interrupt()` when an agent (or
+ * a custom node) needs to ask the user a clarifying question. Mirrors
+ * Claude Code's `AskUserQuestion` semantic. Resume value:
+ * `AskUserQuestionResolution`.
+ */
+export interface AskUserQuestionInterruptPayload {
+  type: 'ask_user_question';
+  question: AskUserQuestionRequest;
+}
+
+/**
+ * Discriminated union of every interrupt payload the SDK raises. New
+ * variants can be added without breaking existing handlers as long as
+ * those handlers check `payload.type` before reading variant-specific
+ * fields. Use the `isToolApprovalInterrupt` / `isAskUserQuestionInterrupt`
+ * type guards for ergonomic narrowing.
+ */
+export type HumanInterruptPayload =
+  | ToolApprovalInterruptPayload
+  | AskUserQuestionInterruptPayload;
+
+/** Resume value the host returns for an `ask_user_question` interrupt. */
+export interface AskUserQuestionResolution {
+  /**
+   * The human's answer. Free-form text, or — when `options` were
+   * provided — one of the option `value`s. Hosts may also send any
+   * structured object their custom UI defines; see the host docs for
+   * what your downstream consumer expects.
+   */
+  answer: string;
+}
+
+/**
+ * Type guard narrowing an arbitrary value to a `ToolApprovalInterruptPayload`.
+ * Accepts `unknown` (not just `HumanInterruptPayload`) because hosts can
+ * raise custom interrupt payloads from custom nodes — `getInterrupt()`
+ * surfaces them as-is, and downstream code must validate the shape at
+ * runtime before reading variant-specific fields.
+ */
+export function isToolApprovalInterrupt(
+  payload: unknown
+): payload is ToolApprovalInterruptPayload {
+  return (
+    typeof payload === 'object' &&
+    payload !== null &&
+    (payload as { type?: unknown }).type === 'tool_approval'
+  );
+}
+
+/**
+ * Type guard narrowing an arbitrary value to an
+ * `AskUserQuestionInterruptPayload`. Same `unknown`-tolerant contract
+ * as `isToolApprovalInterrupt`.
+ */
+export function isAskUserQuestionInterrupt(
+  payload: unknown
+): payload is AskUserQuestionInterruptPayload {
+  return (
+    typeof payload === 'object' &&
+    payload !== null &&
+    (payload as { type?: unknown }).type === 'ask_user_question'
+  );
+}
+
+/**
+ * Run-level configuration controlling HITL semantics. **HITL is OFF by
+ * default** for now — the SDK ships the interrupt machinery, but the
+ * default stays opt-in until host UIs (notably LibreChat) ship the
+ * approval-rendering affordances needed to surface interrupts to end
+ * users. Without that UI, an interrupt with no resolver looks like a
+ * hung tool-call card. Hosts opt in explicitly with
+ * `{ enabled: true }`. The intent is to flip this default to ON in a
+ * future minor once the consumer ecosystem is ready to render
+ * interrupts end-to-end.
+ *
+ * When enabled (`{ enabled: true }`):
+ *
+ *   - `PreToolUse` hooks returning `decision: 'ask'` raise a real
+ *     LangGraph `interrupt()` instead of being treated as a synchronous
+ *     deny.
+ *   - `Run.create` installs a `MemorySaver` checkpointer fallback on the
+ *     run's compile options if the host did not provide one, since
+ *     LangGraph requires a checkpointer to suspend and resume.
+ *
+ * When disabled (the default — omitted, or `{ enabled: false }`):
+ * `ask` decisions are fail-closed (blocked with an error
+ * `ToolMessage`) and no checkpointer is implicitly attached. This
+ * matches the pre-HITL behavior so existing hosts upgrading the SDK
+ * see no change until they're ready to wire the resume UI.
+ *
+ * ## Scope: event-driven tools only
+ *
+ * The interrupt path is wired into `ToolNode.dispatchToolEvents`, which
+ * runs when the agent uses event-driven tool dispatch (the path
+ * LibreChat and most production hosts take). Tools that execute via
+ * the direct path — i.e. tools listed in `directToolNames` (the
+ * graph-managed handoff and subagent tools) or tools on agents
+ * configured WITHOUT `eventDrivenMode` — bypass the hook system
+ * entirely. `PreToolUse` hooks do not fire for those tools and HITL
+ * approval does not gate them.
+ *
+ * Practical implications:
+ *   - LibreChat-style hosts using event-driven dispatch get the full
+ *     HITL surface across every tool the model calls.
+ *   - Hosts using `AgentInputs.tools` directly without event-driven
+ *     mode get policy enforcement for nothing — the hooks register
+ *     but never fire. Either switch to event-driven mode or accept
+ *     that direct tools are not approval-gated. This is documented
+ *     also on `ToolNodeOptions.hookRegistry`.
+ *   - Mixed direct + event batches (e.g. a handoff tool sharing an
+ *     LLM turn with a regular tool) currently re-execute the direct
+ *     half on resume, since LangGraph rolls back the entire ToolNode
+ *     on `interrupt()` throw. Hosts whose direct tools have side
+ *     effects (subagents that invoke models, handoffs that trigger
+ *     downstream work) should avoid mixing those tools into the same
+ *     batch as approval-gated event tools.
+ *
+ * ## Note on idempotency
+ *
+ * When an interrupt fires, LangGraph re-runs the interrupted node
+ * from the start on resume, which fires `PreToolUse` hooks again.
+ * Hooks that produce side effects (logging, external calls) will see
+ * two invocations per paused turn.
+ */
+export interface HumanInTheLoopConfig {
+  /**
+   * Master switch. Defaults to `false` — omit the field (or pass
+   * `false`) to keep HITL off, or set `true` to opt in once the host
+   * UI is ready to render and resolve `tool_approval` interrupts.
+   */
+  enabled?: boolean;
+}
+
+/**
+ * Snapshot of an in-flight interrupt surfaced from `Run.processStream`
+ * via `run.getInterrupt()`. Hosts persist this alongside their job
+ * record so they can later call `Run.resume(decisions)` against a Run
+ * compiled with the same `thread_id` / checkpointer.
+ *
+ * The `payload` type defaults to `HumanInterruptPayload` (the SDK's
+ * built-in `tool_approval` / `ask_user_question` discriminated union)
+ * for ergonomic narrowing in the common case. Hosts that raise custom
+ * interrupt payloads from custom graph nodes can pass the type
+ * parameter (`run.getInterrupt<MyCustom>()` or
+ * `RunInterruptResult<MyCustom>`) — the SDK does not validate the
+ * runtime shape, it just transports whatever the node passed to
+ * `interrupt()`. Use the `isToolApprovalInterrupt` /
+ * `isAskUserQuestionInterrupt` guards (which accept `unknown`) when
+ * the source of the interrupt isn't statically known.
+ */
+export interface RunInterruptResult<TPayload = HumanInterruptPayload> {
+  /** Stable id of the LangGraph interrupt (from `Interrupt.id`). */
+  interruptId: string;
+  /** `thread_id` the run was bound to — required to resume. */
+  threadId?: string;
+  /** Structured payload describing what needs human input. */
+  payload: TPayload;
+}

package/src/types/index.ts

@@ -1,5 +1,6 @@
 // src/types/index.ts
 export * from './graph';
+export * from './hitl';
 export * from './llm';
 export * from './messages';
 export * from './run';

package/src/types/llm.ts

@@ -12,7 +12,7 @@ import type {
 } from '@langchain/openai';
 import type { GoogleGenerativeAIChatInput } from '@langchain/google-genai';
 import type { ChatVertexAIInput } from '@langchain/google-vertexai';
-import type { ChatDeepSeekCallOptions } from '@langchain/deepseek';
+import type { ChatDeepSeekInput } from '@langchain/deepseek';
 import type { ChatOpenRouterCallOptions } from '@/llm/openrouter';
 import type { ChatBedrockConverseInput } from '@langchain/aws';
 import type { ChatMistralAIInput } from '@langchain/mistralai';
@@ -70,7 +70,7 @@ export type AnthropicReasoning = {
 export type GoogleThinkingConfig = {
   thinkingBudget?: number;
   includeThoughts?: boolean;
-  thinkingLevel?: string;
+  thinkingLevel?: 'THINKING_LEVEL_UNSPECIFIED' | 'LOW' | 'MEDIUM' | 'HIGH';
 };
 export type OpenAIClientOptions = ChatOpenAIFields;
 export type AnthropicClientOptions = Omit<AnthropicInput, 'thinking'> & {
@@ -93,7 +93,7 @@ export type GoogleClientOptions = GoogleGenerativeAIChatInput & {
   customHeaders?: RequestOptions['customHeaders'];
   thinkingConfig?: GoogleThinkingConfig;
 };
-export type DeepSeekClientOptions = ChatDeepSeekCallOptions;
+export type DeepSeekClientOptions = Partial<ChatDeepSeekInput>;
 export type XAIClientOptions = ChatXAIInput;
 
 export type ClientOptions =

package/src/types/run.ts

@@ -12,6 +12,7 @@ import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
 import type * as l from '@/types/llm';
 import type { ToolSessionMap, ToolOutputReferencesConfig } from '@/types/tools';
+import type { HumanInTheLoopConfig } from '@/types/hitl';
 import type { HookRegistry } from '@/hooks';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -156,6 +157,38 @@ export type RunConfig = {
    * placeholders. Disabled by default so existing runs are unaffected.
    */
   toolOutputReferences?: ToolOutputReferencesConfig;
+  /**
+   * First-class human-in-the-loop (HITL) flow for this run.
+   *
+   * **HITL is OFF by default.** Omitting this field — or passing
+   * `{ enabled: false }` — keeps the pre-HITL fail-closed semantics
+   * where `ask` decisions collapse into a synchronous deny. Hosts opt
+   * in explicitly with `{ enabled: true }` once their UI can render
+   * and resolve `tool_approval` interrupts (otherwise the run just
+   * pauses with no resolver, which surfaces to end users as a hung
+   * tool-call card).
+   *
+   * Plan of record: the default flips back to ON in a future minor
+   * once the consumer ecosystem (notably LibreChat) ships HITL UI
+   * end-to-end. See `HumanInTheLoopConfig` JSDoc.
+   *
+   * When enabled (`{ enabled: true }`):
+   *   - `PreToolUse` hooks returning `decision: 'ask'` raise a real
+   *     LangGraph `interrupt()` instead of being treated as a synchronous
+   *     deny. The graph pauses and the run exits cleanly.
+   *   - If `graphConfig.compileOptions.checkpointer` is missing, the SDK
+   *     installs an in-memory `MemorySaver` as a fallback so scripts and
+   *     tests can resume without external infrastructure. Production
+   *     hosts should always provide a durable checkpointer.
+   *   - Hosts inspect the pending interrupt via `run.getInterrupt()` and
+   *     continue with `Run.resume(decisions)` against a Run rebuilt with
+   *     the same `thread_id` and checkpointer.
+   *
+   * When disabled (the default): `ask` decisions remain fail-closed
+   * (blocked with an error `ToolMessage`) and no checkpointer is
+   * implicitly attached.
+   */
+  humanInTheLoop?: HumanInTheLoopConfig;
 };
 
 export type ProvidedCallbacks =

package/src/types/stream.ts

@@ -191,7 +191,7 @@ export interface ExtendedMessageContent {
   type?: string;
   text?: string;
   input?: string;
-  index?: number;
+  index?: string | number;
   id?: string;
   name?: string;
 }

package/src/types/tools.ts

@@ -5,6 +5,7 @@ import type { ToolCall } from '@langchain/core/messages/tool';
 import type { HookRegistry } from '@/hooks';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type { MessageContentComplex, ToolErrorData } from './stream';
+import type { HumanInTheLoopConfig } from './hitl';
 
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
 export type CustomToolCall = {
@@ -56,6 +57,24 @@ export type ToolNodeOptions = {
    * routed through `directToolNames` bypass hook dispatch entirely.
    */
   hookRegistry?: HookRegistry;
+  /**
+   * Run-scoped HITL config. **HITL is OFF by default** — omitting this
+   * field (or passing `{ enabled: false }`) keeps the pre-HITL
+   * fail-closed behavior where a `PreToolUse` `ask` decision collapses
+   * into a blocked `ToolMessage`. Hosts opt in with
+   * `{ enabled: true }` once their UI can render and resolve a
+   * `tool_approval` interrupt; that engages the interrupt path where
+   * `ask` raises a real LangGraph `interrupt()` carrying a
+   * `HumanInterruptPayload` and the host resumes with
+   * `Run.resume(decisions)`.
+   *
+   * Mirrors `RunConfig.humanInTheLoop` (which is the canonical place
+   * to set this); the Graph threads it down to every ToolNode it
+   * compiles. Same caveat: the interrupt path is only wired into the
+   * event-driven dispatch (`dispatchToolEvents`), not into
+   * `directToolNames` execution — direct tools bypass HITL entirely.
+   */
+  humanInTheLoop?: HumanInTheLoopConfig;
   /** Max context tokens for the agent — used to compute tool result truncation limits. */
   maxContextTokens?: number;
   /**

package/src/utils/llmConfig.ts

@@ -56,9 +56,7 @@ export const llmConfigs: Record<string, t.LLMConfig | undefined> = {
     provider: Providers.OPENROUTER,
     streaming: true,
     streamUsage: true,
-    // model: 'anthropic/claude-sonnet-4',
-    // model: 'moonshotai/kimi-k2-thinking',
-    model: 'google/gemini-3-pro-preview',
+    model: process.env.OPENROUTER_MODEL ?? 'openai/gpt-4o-mini',
     apiKey: process.env.OPENROUTER_API_KEY,
     configuration: {
       baseURL: process.env.OPENROUTER_BASE_URL,
@@ -67,9 +65,6 @@ export const llmConfigs: Record<string, t.LLMConfig | undefined> = {
         'X-Title': 'LibreChat',
       },
     },
-    reasoning: {
-      max_tokens: 8000,
-    },
     modelKwargs: {
       max_tokens: 10000,
     },