@librechat/agents 3.1.76 → 3.1.77-dev.1

package/dist/types/types/run.d.ts

@@ -8,6 +8,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';
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
 export type BaseGraphConfig = {
@@ -144,6 +145,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 = (BaseCallbackHandler | CallbackHandlerMethods)[] | undefined;
 export type TokenCounter = (message: BaseMessage) => number;

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

@@ -4,6 +4,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 = {
     name: string;
@@ -46,6 +47,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.76",
+  "version": "3.1.77-dev.1",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/graphs/Graph.ts

@@ -129,6 +129,13 @@ export abstract class Graph<
   invokedToolIds?: Set<string>;
   handlerRegistry: HandlerRegistry | undefined;
   hookRegistry: HookRegistry | undefined;
+  /**
+   * Run-scoped HITL configuration. When `humanInTheLoop?.enabled` is
+   * `true`, `ToolNode` raises a real `interrupt()` for `PreToolUse`
+   * `ask` decisions instead of treating them as a synchronous deny.
+   * Threaded from `RunConfig.humanInTheLoop`.
+   */
+  humanInTheLoop: t.HumanInTheLoopConfig | undefined;
   /**
    * Run-scoped config for the tool output reference registry. Threaded
    * from `RunConfig.toolOutputReferences` down into every ToolNode this
@@ -167,6 +174,7 @@ export abstract class Graph<
     this.invokedToolIds = undefined;
     this.handlerRegistry = undefined;
     this.hookRegistry = undefined;
+    this.humanInTheLoop = undefined;
     this.toolOutputReferences = undefined;
     /**
      * ToolNodes compiled from this graph captured the registry
@@ -579,6 +587,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         toolCallStepIds: this.toolCallStepIds,
         toolRegistry: agentContext?.toolRegistry,
         hookRegistry: this.hookRegistry,
+        humanInTheLoop: this.humanInTheLoop,
         directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
         maxContextTokens: agentContext?.maxContextTokens,
         maxToolResultChars: agentContext?.maxToolResultChars,

package/src/hitl/askUserQuestion.ts

@@ -0,0 +1,72 @@
+/**
+ * Typed convenience wrapper around LangGraph's `interrupt()` for the
+ * `ask_user_question` interrupt category. Lets a custom graph node
+ * (or a tool implementation) suspend execution to collect a free-form
+ * answer from the human, without the host having to assemble the
+ * interrupt payload by hand. The companion to `Run.resume(answer)` on
+ * the host side.
+ *
+ * AsyncLocalStorage anchoring: this helper does NOT call
+ * `runWithConfig` itself — it expects to be invoked from inside a
+ * LangGraph node where the framework has already established the
+ * runnable config. ToolNode is the one place in this codebase that
+ * needs the manual `runWithConfig` shim, because its
+ * `RunnableCallable.trace = false` skips the upstream tracing path
+ * that normally sets up the AsyncLocalStorage frame; ordinary user
+ * nodes (RunnableLambda, addNode callbacks) do not have that
+ * constraint.
+ */
+
+import { interrupt } from '@langchain/langgraph';
+import type {
+  AskUserQuestionRequest,
+  AskUserQuestionResolution,
+  AskUserQuestionInterruptPayload,
+} from '@/types/hitl';
+
+/**
+ * Suspend the current graph node to ask the human a question. Returns
+ * the host-supplied resolution after `Run.resume(resolution)` is
+ * called against a Run rebuilt with the same `thread_id` and
+ * checkpointer.
+ *
+ * On the FIRST call (no resume value available), `interrupt()` throws
+ * a `GraphInterrupt` that LangGraph catches; this function does not
+ * return — execution unwinds, the SDK persists the checkpoint, and
+ * the run completes with `run.getInterrupt()` returning a
+ * `RunInterruptResult` whose `payload` is an
+ * `AskUserQuestionInterruptPayload`.
+ *
+ * On RESUME, LangGraph re-runs the node from the start and this call
+ * returns the host's `AskUserQuestionResolution` directly.
+ *
+ * Hosts that prefer the raw `interrupt()` (e.g., to attach extra
+ * metadata) can construct an `AskUserQuestionInterruptPayload` and
+ * call `interrupt()` themselves — this helper is purely convenience.
+ *
+ * @example
+ * ```ts
+ * const builder = new StateGraph(MessagesAnnotation)
+ *   .addNode('clarifier', () => {
+ *     const { answer } = askUserQuestion({
+ *       question: 'Which environment should I deploy to?',
+ *       options: [
+ *         { label: 'Staging', value: 'staging' },
+ *         { label: 'Production', value: 'production' },
+ *       ],
+ *     });
+ *     return { messages: [new HumanMessage(`Use ${answer}`)] };
+ *   });
+ * ```
+ */
+export function askUserQuestion(
+  question: AskUserQuestionRequest
+): AskUserQuestionResolution {
+  const payload: AskUserQuestionInterruptPayload = {
+    type: 'ask_user_question',
+    question,
+  };
+  return interrupt<AskUserQuestionInterruptPayload, AskUserQuestionResolution>(
+    payload
+  );
+}

package/src/hitl/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Human-in-the-loop helpers. Type definitions live in `@/types/hitl`
+ * and re-export from the top-level types barrel; runtime helpers (like
+ * `askUserQuestion()`) live here.
+ */
+
+export { askUserQuestion } from './askUserQuestion';

package/src/hooks/HookRegistry.ts

@@ -13,6 +13,20 @@ import type { HookEvent, HookMatcher } from './types';
  */
 type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
 
+/**
+ * Snapshot of a halt request raised by a hook returning
+ * `preventContinuation: true`. The SDK's run loop polls for this between
+ * stream events and exits cleanly when set, skipping the `Stop` hook
+ * (the run is being halted, not naturally completing). One per registry
+ * instance — the first hook to halt wins; subsequent halts are ignored
+ * so the original reason isn't clobbered.
+ */
+export interface HookHaltSignal {
+  reason: string;
+  /** Event of the hook that triggered the halt (for diagnostics). */
+  source: HookEvent;
+}
+
 /**
  * Run-scoped storage for hook matchers with an additional layer for
  * session-scoped matchers that should be cleaned up between sessions.
@@ -34,6 +48,18 @@ type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
 export class HookRegistry {
   private readonly global: MatcherBucket = {};
   private readonly sessions: Map<string, MatcherBucket> = new Map();
+  /**
+   * Per-session halt signals. Scoped by `sessionId` (= the run id the
+   * hook fired under) so a host that shares one registry across
+   * concurrent runs cannot leak `preventContinuation` from one run
+   * into another. Without scoping, a halt raised by run A's hook
+   * would trip run B's stream-loop poll on the next iteration —
+   * silently terminating an unrelated run.
+   *
+   * Map storage mirrors the reasoning above for session matchers:
+   * O(1) insertion in hot paths, no spread-on-write.
+   */
+  private readonly haltSignals: Map<string, HookHaltSignal> = new Map();
 
   /**
    * Register a matcher for the lifetime of this registry (= one Run).
@@ -125,6 +151,51 @@ export class HookRegistry {
     this.sessions.delete(sessionId);
   }
 
+  /**
+   * Raise a halt signal scoped to `sessionId` (= the run id the hook
+   * fired under). The SDK's run loop polls for this between stream
+   * events with the run's own id. First-write-wins per session: a
+   * halt already raised by an earlier hook in the same run is
+   * preserved so the original `reason` / `source` aren't overwritten.
+   *
+   * Per-session scoping is critical when hosts share one registry
+   * across concurrent runs (e.g. a global policy registered once and
+   * reused). Without it, a `preventContinuation` from run A would
+   * trip run B's stream-loop poll on the next iteration and silently
+   * terminate an unrelated run.
+   *
+   * Called by the SDK after `executeHooks` returns an aggregate with
+   * `preventContinuation: true`. Hosts can also call it directly from
+   * inside a hook callback if they want to halt without going through
+   * the aggregated return value, but `preventContinuation` is the
+   * canonical path.
+   */
+  haltRun(sessionId: string, reason: string, source: HookEvent): void {
+    if (this.haltSignals.has(sessionId)) {
+      return;
+    }
+    this.haltSignals.set(sessionId, { reason, source });
+  }
+
+  /**
+   * Returns the halt signal raised by hooks running under `sessionId`,
+   * or `undefined` if no hook in that run has halted. Polled by
+   * `Run.processStream` between stream events using the run's own id.
+   */
+  getHaltSignal(sessionId: string): HookHaltSignal | undefined {
+    return this.haltSignals.get(sessionId);
+  }
+
+  /**
+   * Clears the halt signal for `sessionId`. Called by
+   * `Run.processStream` in its `finally` block so a subsequent
+   * invocation of the same Run (e.g. resume) starts with a fresh
+   * halt state. No-op when no signal exists for that session.
+   */
+  clearHaltSignal(sessionId: string): void {
+    this.haltSignals.delete(sessionId);
+  }
+
   /** True if at least one matcher exists for `event` (global + session). */
   hasHookFor(event: HookEvent, sessionId?: string): boolean {
     if (readList(this.global, event).length > 0) {

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

@@ -0,0 +1,259 @@
+import { describe, it, expect } from '@jest/globals';
+import type {
+  HookCallback,
+  PreToolUseHookInput,
+  PreToolUseHookOutput,
+} from '../types';
+import { createToolPolicyHook } from '../createToolPolicyHook';
+
+const baseInput: Omit<PreToolUseHookInput, 'toolName'> = {
+  hook_event_name: 'PreToolUse',
+  runId: 'r-1',
+  toolInput: {},
+  toolUseId: 'call-1',
+  stepId: 'step-1',
+  turn: 0,
+};
+
+async function callHook(
+  hook: HookCallback<'PreToolUse'>,
+  toolName: string
+): Promise<PreToolUseHookOutput> {
+  const signal = new AbortController().signal;
+  return await hook({ ...baseInput, toolName }, signal);
+}
+
+describe('createToolPolicyHook — default mode', () => {
+  it('asks for tools that match no rule', async () => {
+    const hook = createToolPolicyHook({ mode: 'default' });
+    expect((await callHook(hook, 'unknown_tool')).decision).toBe('ask');
+  });
+
+  it('allows tools that match an allow pattern', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['read_file', 'grep'],
+    });
+    expect((await callHook(hook, 'read_file')).decision).toBe('allow');
+    expect((await callHook(hook, 'grep')).decision).toBe('allow');
+    expect((await callHook(hook, 'write_file')).decision).toBe('ask');
+  });
+
+  it('denies tools that match a deny pattern', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      deny: ['delete_*'],
+    });
+    expect((await callHook(hook, 'delete_file')).decision).toBe('deny');
+    expect((await callHook(hook, 'read_file')).decision).toBe('ask');
+  });
+
+  it('asks tools that match an ask pattern (redundant in default mode but explicit)', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      ask: ['execute_*'],
+    });
+    expect((await callHook(hook, 'execute_code')).decision).toBe('ask');
+  });
+});
+
+describe('createToolPolicyHook — dontAsk mode', () => {
+  it('denies tools that match no rule (no human prompt)', async () => {
+    const hook = createToolPolicyHook({ mode: 'dontAsk' });
+    expect((await callHook(hook, 'unknown_tool')).decision).toBe('deny');
+  });
+
+  it('still allows tools that match an allow pattern', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'dontAsk',
+      allow: ['read_*'],
+    });
+    expect((await callHook(hook, 'read_file')).decision).toBe('allow');
+    expect((await callHook(hook, 'write_file')).decision).toBe('deny');
+  });
+
+  it('still asks tools that match an explicit ask pattern (overrides dontAsk default)', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'dontAsk',
+      ask: ['execute_*'],
+    });
+    expect((await callHook(hook, 'execute_code')).decision).toBe('ask');
+    expect((await callHook(hook, 'unknown_tool')).decision).toBe('deny');
+  });
+});
+
+describe('createToolPolicyHook — bypass mode', () => {
+  it('allows everything by default', async () => {
+    const hook = createToolPolicyHook({ mode: 'bypass' });
+    expect((await callHook(hook, 'anything')).decision).toBe('allow');
+    expect((await callHook(hook, 'execute_code')).decision).toBe('allow');
+  });
+
+  it('still denies tools that match a deny pattern (deny always wins)', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'bypass',
+      deny: ['delete_*'],
+    });
+    expect((await callHook(hook, 'delete_file')).decision).toBe('deny');
+    expect((await callHook(hook, 'read_file')).decision).toBe('allow');
+  });
+
+  it('overrides explicit ask patterns (bypass means stop asking)', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'bypass',
+      ask: ['execute_*'],
+    });
+    expect((await callHook(hook, 'execute_code')).decision).toBe('allow');
+  });
+});
+
+describe('createToolPolicyHook — pattern matching', () => {
+  it('matches glob `*` wildcards', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['mcp:github:*'],
+    });
+    expect((await callHook(hook, 'mcp:github:create_issue')).decision).toBe(
+      'allow'
+    );
+    expect((await callHook(hook, 'mcp:github:list_repos')).decision).toBe(
+      'allow'
+    );
+    expect((await callHook(hook, 'mcp:slack:post')).decision).toBe('ask');
+  });
+
+  it('matches exact tool names', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['read_file'],
+    });
+    expect((await callHook(hook, 'read_file')).decision).toBe('allow');
+    expect((await callHook(hook, 'read_file_lines')).decision).toBe('ask');
+  });
+
+  it('escapes regex metacharacters in literal portions', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['tool.with.dots'],
+    });
+    expect((await callHook(hook, 'tool.with.dots')).decision).toBe('allow');
+    /** A literal regex `.` would also match `tool_with_dots`; glob shouldn't. */
+    expect((await callHook(hook, 'tool_with_dots')).decision).toBe('ask');
+  });
+
+  it('matches wildcards in the middle and end', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      ask: ['*search*'],
+    });
+    expect((await callHook(hook, 'web_search')).decision).toBe('ask');
+    expect((await callHook(hook, 'searcher')).decision).toBe('ask');
+    expect((await callHook(hook, 'read_file')).decision).toBe('ask'); // default mode
+    /** Confirm the ask path tagged it (not the fallthrough): explicit ask hits before mode fallthrough. */
+  });
+});
+
+describe('createToolPolicyHook — precedence', () => {
+  it('deny wins over allow', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['read_*'],
+      deny: ['read_secret'],
+    });
+    expect((await callHook(hook, 'read_secret')).decision).toBe('deny');
+    expect((await callHook(hook, 'read_file')).decision).toBe('allow');
+  });
+
+  it('deny wins over bypass mode', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'bypass',
+      deny: ['delete_*'],
+    });
+    expect((await callHook(hook, 'delete_file')).decision).toBe('deny');
+    expect((await callHook(hook, 'anything_else')).decision).toBe('allow');
+  });
+
+  it('allow wins over ask in default mode', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['execute_safe'],
+      ask: ['execute_*'],
+    });
+    expect((await callHook(hook, 'execute_safe')).decision).toBe('allow');
+    expect((await callHook(hook, 'execute_dangerous')).decision).toBe('ask');
+  });
+});
+
+describe('createToolPolicyHook — reason', () => {
+  it('attaches the configured reason to ask and deny decisions', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      deny: ['delete_*'],
+      reason: 'Tool {tool} requires manual review',
+    });
+    const denied = await callHook(hook, 'delete_file');
+    expect(denied.decision).toBe('deny');
+    expect(denied.reason).toBe('Tool delete_file requires manual review');
+
+    const asked = await callHook(hook, 'unknown_tool');
+    expect(asked.decision).toBe('ask');
+    expect(asked.reason).toBe('Tool unknown_tool requires manual review');
+  });
+
+  it('omits the reason field for allow decisions', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['read_*'],
+      reason: 'never seen',
+    });
+    const result = await callHook(hook, 'read_file');
+    expect(result.decision).toBe('allow');
+    expect(result.reason).toBeUndefined();
+  });
+
+  it('does not add a reason field when no template is configured', async () => {
+    const hook = createToolPolicyHook({ mode: 'dontAsk' });
+    const result = await callHook(hook, 'unknown_tool');
+    expect(result.decision).toBe('deny');
+    expect(result.reason).toBeUndefined();
+  });
+});
+
+describe('createToolPolicyHook — registry integration', () => {
+  it('works when registered as a PreToolUse hook (round-trip via executeHooks)', async () => {
+    const { HookRegistry, executeHooks } = await import('../index');
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        createToolPolicyHook({
+          mode: 'default',
+          allow: ['read_file'],
+          deny: ['delete_*'],
+          reason: 'review {tool}',
+        }),
+      ],
+    });
+
+    const allow = await executeHooks({
+      registry,
+      input: { ...baseInput, toolName: 'read_file' },
+      matchQuery: 'read_file',
+    });
+    expect(allow.decision).toBe('allow');
+
+    const deny = await executeHooks({
+      registry,
+      input: { ...baseInput, toolName: 'delete_file' },
+      matchQuery: 'delete_file',
+    });
+    expect(deny.decision).toBe('deny');
+    expect(deny.reason).toBe('review delete_file');
+
+    const ask = await executeHooks({
+      registry,
+      input: { ...baseInput, toolName: 'mystery_tool' },
+      matchQuery: 'mystery_tool',
+    });
+    expect(ask.decision).toBe('ask');
+  });
+});