@librechat/agents 3.1.76 → 3.1.77-dev.1

package/dist/types/hooks/types.d.ts

@@ -7,7 +7,7 @@ import type { BaseMessage } from '@langchain/core/messages';
  * `docs/hooks-design-report.md` §3.2 for the mapping to existing
  * `@librechat/agents` emission points.
  */
-export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFailure", "PreCompact", "PostCompact"];
+export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFailure", "PreCompact", "PostCompact"];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 /** Tool-gating decision; executeHooks folds with `deny > ask > allow` precedence. */
 export type ToolDecision = 'allow' | 'deny' | 'ask';
@@ -75,6 +75,40 @@ export interface PostToolUseFailureHookInput extends BaseHookInput {
     stepId?: string;
     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;
@@ -128,7 +162,7 @@ export interface PostCompactHookInput extends BaseHookInput {
     messagesAfterCount: number;
 }
 /** Discriminated union of every hook input shape. */
-export type HookInput = RunStartHookInput | UserPromptSubmitHookInput | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PermissionDeniedHookInput | SubagentStartHookInput | SubagentStopHookInput | StopHookInput | StopFailureHookInput | PreCompactHookInput | PostCompactHookInput;
+export type HookInput = RunStartHookInput | UserPromptSubmitHookInput | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PostToolBatchHookInput | PermissionDeniedHookInput | SubagentStartHookInput | SubagentStopHookInput | StopHookInput | StopFailureHookInput | PreCompactHookInput | PostCompactHookInput;
 /** Compile-time map from event name to its input shape. */
 export type HookInputByEvent = {
     RunStart: RunStartHookInput;
@@ -136,6 +170,7 @@ export type HookInputByEvent = {
     PreToolUse: PreToolUseHookInput;
     PostToolUse: PostToolUseHookInput;
     PostToolUseFailure: PostToolUseFailureHookInput;
+    PostToolBatch: PostToolBatchHookInput;
     PermissionDenied: PermissionDeniedHookInput;
     SubagentStart: SubagentStartHookInput;
     SubagentStop: SubagentStopHookInput;
@@ -155,6 +190,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;
 export interface UserPromptSubmitHookOutput extends BaseHookOutput {
@@ -175,6 +260,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 {
     /**
@@ -186,6 +284,7 @@ export interface PostToolUseHookOutput extends BaseHookOutput {
     updatedOutput?: unknown;
 }
 export type PostToolUseFailureHookOutput = BaseHookOutput;
+export type PostToolBatchHookOutput = BaseHookOutput;
 export type PermissionDeniedHookOutput = BaseHookOutput;
 export interface SubagentStartHookOutput extends BaseHookOutput {
     decision?: ToolDecision;
@@ -206,6 +305,7 @@ export type HookOutputByEvent = {
     PreToolUse: PreToolUseHookOutput;
     PostToolUse: PostToolUseHookOutput;
     PostToolUseFailure: PostToolUseFailureHookOutput;
+    PostToolBatch: PostToolBatchHookOutput;
     PermissionDenied: PermissionDeniedHookOutput;
     SubagentStart: SubagentStartHookOutput;
     SubagentStop: SubagentStopHookOutput;
@@ -215,7 +315,7 @@ export type HookOutputByEvent = {
     PostCompact: PostCompactHookOutput;
 };
 /** Superset output shape used by the executor's fold loop. */
-export type HookOutput = RunStartHookOutput | UserPromptSubmitHookOutput | PreToolUseHookOutput | PostToolUseHookOutput | PostToolUseFailureHookOutput | PermissionDeniedHookOutput | SubagentStartHookOutput | SubagentStopHookOutput | StopHookOutput | StopFailureHookOutput | PreCompactHookOutput | PostCompactHookOutput;
+export type HookOutput = RunStartHookOutput | UserPromptSubmitHookOutput | PreToolUseHookOutput | PostToolUseHookOutput | PostToolUseFailureHookOutput | PostToolBatchHookOutput | PermissionDeniedHookOutput | SubagentStartHookOutput | SubagentStopHookOutput | StopHookOutput | StopFailureHookOutput | PreCompactHookOutput | PostCompactHookOutput;
 /**
  * A hook callback is a plain async function registered against a specific
  * event. The `signal` is always supplied by `executeHooks` and combines the
@@ -297,6 +397,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/dist/types/index.d.ts

@@ -23,8 +23,17 @@ export * from './tools/search';
 export * from './common';
 export * from './utils';
 export * from './hooks';
+export * from './hitl';
 export type * from './types';
 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';
 export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';
 export type { OpenRouterReasoning, OpenRouterReasoningEffort, ChatOpenRouterCallOptions, } from './llm/openrouter';

package/dist/types/run.d.ts

@@ -1,4 +1,5 @@
 import './instrumentation';
+import { Command } from '@langchain/langgraph';
 import type { MessageContentComplex, BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type * as t from '@/types';
@@ -10,6 +11,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private tokenCounter?;
     private handlerRegistry?;
     private hookRegistry?;
+    private humanInTheLoop?;
     private toolOutputReferences?;
     private indexTokenCountMap?;
     calibrationRatio: number;
@@ -18,9 +20,70 @@ export declare class Run<_T extends t.BaseGraphState> {
     returnContent: boolean;
     private skipCleanup;
     private _streamResult;
+    /**
+     * Captured interrupt payload typed as `unknown` because the SDK
+     * does not validate the runtime shape — custom graph nodes can
+     * raise interrupts with arbitrary payloads (not just the SDK's
+     * `HumanInterruptPayload` union). The public `getInterrupt<T>()`
+     * lets callers assert the type they expect.
+     */
+    private _interrupt;
+    private _haltedReason;
     private constructor();
     private createLegacyGraph;
     private createMultiAgentGraph;
+    /**
+     * When the host opted into HITL via `humanInTheLoop: { enabled: true }`
+     * and did not supply a checkpointer, install an in-memory `MemorySaver`
+     * so `interrupt()` can persist checkpoints and `Command({ resume })`
+     * can rebuild state. The fallback is intentionally process-local:
+     * production hosts that need durable resumption across processes /
+     * restarts must provide their own checkpointer (Redis, Postgres, etc.)
+     * on `compileOptions.checkpointer`.
+     *
+     * No-op when HITL is off (the default — omitted, or
+     * `{ enabled: false }`) or the host already supplied a checkpointer
+     * of their own. See `HumanInTheLoopConfig` JSDoc for the rationale
+     * behind the default-off stance.
+     */
+    private applyHITLCheckpointerFallback;
+    /**
+     * Run RunStart + UserPromptSubmit hooks before the graph stream
+     * begins, accumulate any `additionalContext` strings into the input
+     * messages, and short-circuit when a hook signals the run should not
+     * proceed (deny / ask decision on the prompt, or `preventContinuation`
+     * on either hook).
+     *
+     * Returns `true` when the caller should bail with `undefined` (run
+     * was halted before any model call); returns `false` to proceed
+     * into the stream loop.
+     *
+     * ## Side effects
+     *
+     * On the success path:
+     *   - Mutates `stateInputs.messages` in place to append a
+     *     consolidated `HumanMessage` carrying any hook
+     *     `additionalContext` strings. Safe because the host owns the
+     *     array and `processStream` is the only consumer until LangGraph
+     *     reads it.
+     *
+     * On the halt path (returning `true`):
+     *   - Sets `this._haltedReason` so callers (and the eventual host)
+     *     can distinguish a hook-driven halt from a natural completion.
+     *   - Calls `registry.clearSession(this.id)` and
+     *     `registry.clearHaltSignal(this.id)` because no resume is
+     *     expected from a pre-stream halt — the run never entered the
+     *     graph, so the session/halt state for this run would otherwise
+     *     leak to the next `processStream` invocation on the same
+     *     registry. Other concurrent runs on the same registry are
+     *     untouched (halt signals are scoped per session id).
+     *   - Sets `config.callbacks = undefined` to drop the callback
+     *     references the caller built (langfuse handler, custom event
+     *     handler, etc.) since they won't be exercised. Mirrors the
+     *     equivalent cleanup the `processStream` `finally` block does
+     *     on the natural-completion path.
+     */
+    private runPreStreamHooks;
     static create<T extends t.BaseGraphState>(config: t.RunConfig): Promise<Run<T>>;
     getRunMessages(): BaseMessage[] | undefined;
     /**
@@ -37,7 +100,60 @@ export declare class Run<_T extends t.BaseGraphState> {
      * and processes them through our handler registry instead of EventStreamCallbackHandler
      */
     private createCustomEventCallback;
-    processStream(inputs: t.IState, callerConfig: Partial<RunnableConfig> & {
+    processStream(inputs: t.IState | Command, callerConfig: Partial<RunnableConfig> & {
+        version: 'v1' | 'v2';
+        run_id?: string;
+    }, streamOptions?: t.EventStreamOptions): Promise<MessageContentComplex[] | undefined>;
+    /**
+     * Returns the pending interrupt captured during the most recent
+     * `processStream` (or `resume`) invocation. `undefined` when the run
+     * either has not been streamed yet or completed without pausing.
+     *
+     * Hosts call this immediately after `processStream` returns to decide
+     * whether the run is awaiting human input. Persist the returned
+     * descriptor (alongside `thread_id` and the agent run config) so a
+     * later `resume(decisions)` can rebuild the run.
+     *
+     * The default `TPayload` is the SDK's `HumanInterruptPayload` union
+     * (`tool_approval` / `ask_user_question`), suitable for the common
+     * case where interrupts come from the built-in ToolNode or
+     * `askUserQuestion()` helper. Hosts that raise custom interrupts
+     * from custom graph nodes pass their own type — the SDK does not
+     * validate the runtime shape, it just transports whatever the
+     * `interrupt()` call carried. When in doubt, narrow with the
+     * `isToolApprovalInterrupt` / `isAskUserQuestionInterrupt` type
+     * guards (which accept `unknown`) before reading variant-specific
+     * fields.
+     */
+    getInterrupt<TPayload = t.HumanInterruptPayload>(): t.RunInterruptResult<TPayload> | undefined;
+    /**
+     * Returns the reason a hook halted the run via
+     * `preventContinuation: true`, or `undefined` if no hook halted.
+     *
+     * Hosts inspect this after `processStream` returns to distinguish a
+     * natural completion (`undefined`) from a hook-driven halt (a
+     * truthy string). Independent from `getInterrupt()` — a halted run
+     * has no interrupt; an interrupted run has no halt reason.
+     */
+    getHaltReason(): string | undefined;
+    /**
+     * Resume a paused HITL run with the value the user (or whatever
+     * decided the interrupt) supplied. The default `TResume` covers the
+     * `tool_approval` interrupt (the common case): an array of decisions
+     * in `action_requests` order, or a record keyed by `tool_call_id`.
+     *
+     * For other interrupt types (e.g., `ask_user_question` →
+     * `AskUserQuestionResolution`, or any custom interrupt a host raises
+     * from a custom node), pass the type parameter and the SDK forwards
+     * the value through unchanged. LangGraph delivers it as the return
+     * value of the original `interrupt()` call inside the paused node.
+     *
+     * The host MUST construct this Run with the same `thread_id` and the
+     * same checkpointer as the original paused run; LangGraph rebuilds
+     * graph state from the checkpoint and re-enters the interrupted node
+     * from the start.
+     */
+    resume<TResume = t.ToolApprovalDecision[] | t.ToolApprovalDecisionMap>(resumeValue: TResume, callerConfig: Partial<RunnableConfig> & {
         version: 'v1' | 'v2';
         run_id?: string;
     }, streamOptions?: t.EventStreamOptions): Promise<MessageContentComplex[] | undefined>;

package/dist/types/tools/ToolNode.d.ts

@@ -47,6 +47,12 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private maxToolResultChars;
     /** Hook registry for PreToolUse/PostToolUse lifecycle hooks */
     private hookRegistry?;
+    /**
+     * Run-scoped HITL config. When `enabled`, `ask` decisions from
+     * PreToolUse hooks raise a LangGraph `interrupt()` instead of being
+     * treated as fail-closed denies.
+     */
+    private humanInTheLoop?;
     /**
      * Registry of tool outputs keyed by `tool<idx>turn<turn>`.
      *
@@ -67,7 +73,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * other's in-flight state.
      */
     private anonBatchCounter;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, toolOutputReferences, toolOutputRegistry, }: t.ToolNodeConstructorParams);
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, }: t.ToolNodeConstructorParams);
     /**
      * Returns the run-scoped tool output registry, or `undefined` when
      * the feature is disabled.
@@ -155,6 +161,25 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      *    ToolMessages (appended AFTER to respect provider ordering).
      */
     private dispatchToolEvents;
+    /**
+     * Fires the `PostToolBatch` hook (if registered) and appends the
+     * accumulated batch-level `additionalContext` strings to `injected`
+     * as a single `HumanMessage`. Entries are materialized in the
+     * original `toolCalls` order so hooks correlating outcomes by
+     * position (as the type docs promise) see exactly the sequence
+     * the model emitted, regardless of when each individual outcome
+     * was recorded into the map (deny synchronous, approved
+     * post-execution, respond on resume).
+     *
+     * The PostToolBatch hook's `additionalContexts` flow into the same
+     * batch accumulator per-tool hooks already use, so a single
+     * batch-level convention message can be injected through one path.
+     *
+     * Mutates `batchAdditionalContexts` (push from batch hook) and
+     * `injected` (push the consolidated HumanMessage). The caller owns
+     * those arrays and consumes them right after this returns.
+     */
+    private dispatchPostToolBatchAndInjectContext;
     private dispatchStepCompleted;
     /**
      * Converts InjectedMessage instances to LangChain HumanMessage objects.

package/dist/types/types/hitl.d.ts

@@ -0,0 +1,272 @@
+/**
+ * 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 declare function isToolApprovalInterrupt(payload: unknown): payload is ToolApprovalInterruptPayload;
+/**
+ * Type guard narrowing an arbitrary value to an
+ * `AskUserQuestionInterruptPayload`. Same `unknown`-tolerant contract
+ * as `isToolApprovalInterrupt`.
+ */
+export declare function isAskUserQuestionInterrupt(payload: unknown): payload is AskUserQuestionInterruptPayload;
+/**
+ * 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/dist/types/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from './graph';
+export * from './hitl';
 export * from './llm';
 export * from './messages';
 export * from './run';