@librechat/agents 3.1.75 → 3.1.77-dev.1

package/src/hooks/createToolPolicyHook.ts

@@ -0,0 +1,184 @@
+/**
+ * Declarative `PreToolUse` hook factory. Lets hosts express common
+ * permission policies (allow / deny / ask lists + a global mode) without
+ * hand-rolling matching, precedence, and decision logic per-host.
+ *
+ * Maps directly to the Claude Code Agent SDK permission vocabulary
+ * (`allowed_tools` / `disallowed_tools` / `permissionMode`) so users of
+ * either SDK can think in the same terms. See the README's HITL section
+ * for the cross-walk and `docs/hooks-design-report.md` for the broader
+ * hook system context.
+ */
+
+import type { HookCallback, PreToolUseHookOutput, ToolDecision } from './types';
+
+/**
+ * Permission mode controlling how tool calls that match no rule are
+ * resolved. Mirrors Claude Code's `permissionMode`.
+ *
+ *   - `default`  — unmatched tools fall through to `'ask'` (interrupt).
+ *   - `dontAsk`  — unmatched tools are denied; the human is never
+ *                  prompted. Useful for headless / API agents where a
+ *                  silent denial is preferable to a hung interrupt.
+ *   - `bypass`   — every tool is approved, except those matching `deny`
+ *                  patterns. The kill switch you flip when you trust
+ *                  the agent and want to stop being asked. Equivalent to
+ *                  Claude Code's `bypassPermissions`.
+ */
+export type ToolPolicyMode = 'default' | 'dontAsk' | 'bypass';
+
+export interface ToolPolicyConfig {
+  /**
+   * Global mode applied to tools that don't match any rule.
+   * Defaults to `'default'` (ask the human).
+   */
+  mode?: ToolPolicyMode;
+  /**
+   * Tool name patterns that are auto-approved without a prompt.
+   * Patterns support glob `*` wildcards: `read_file`, `mcp:github:*`,
+   * `*search*`. Match is anchored (`^pattern$`).
+   */
+  allow?: readonly string[];
+  /**
+   * Tool name patterns that are blocked outright. Wins over `allow`
+   * and `ask`, and overrides `mode: 'bypass'` — a deny rule always
+   * holds, matching Claude Code's "deny rules are checked first" guarantee.
+   */
+  deny?: readonly string[];
+  /**
+   * Tool name patterns that always trigger human approval, regardless
+   * of `mode: 'default'` vs `'dontAsk'`. In `mode: 'bypass'` these are
+   * still bypassed (because that's what bypass means).
+   */
+  ask?: readonly string[];
+  /**
+   * Optional reason attached to the resulting `ask` / `deny` hook
+   * decision so the host UI can render why approval is required.
+   * The literal token `{tool}` is replaced with the tool name.
+   */
+  reason?: string;
+}
+
+/**
+ * Compile a glob string with `*` wildcards into a single anchored
+ * `RegExp`. Other regex metacharacters are escaped, so `read_file.md`
+ * matches the literal dot. Patterns are short (tool names), so we do
+ * not cache here — the registry's `matchesQuery` already caches its own
+ * regex compilations and our patterns are evaluated once per ToolNode
+ * batch, not once per stream chunk.
+ */
+function globToRegex(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp('^' + escaped.replace(/\*/g, '.*') + '$');
+}
+
+/** Pre-compile a list of glob patterns into a single match function. */
+function compileMatchers(
+  patterns: readonly string[] | undefined
+): (toolName: string) => boolean {
+  if (patterns == null || patterns.length === 0) {
+    return () => false;
+  }
+  const regexes = patterns.map(globToRegex);
+  return (toolName: string): boolean => {
+    for (const regex of regexes) {
+      if (regex.test(toolName)) {
+        return true;
+      }
+    }
+    return false;
+  };
+}
+
+function formatReason(
+  template: string | undefined,
+  toolName: string
+): string | undefined {
+  if (template == null) {
+    return undefined;
+  }
+  return template.replace(/\{tool\}/g, toolName);
+}
+
+/**
+ * Build a `PreToolUse` hook callback that applies a declarative tool
+ * permission policy. Register it with a `HookRegistry` and the SDK's
+ * `humanInTheLoop` machinery handles the rest:
+ *
+ * ```ts
+ * const policyHook = createToolPolicyHook({
+ *   mode: 'default',
+ *   allow: ['read_*', 'grep', 'glob'],
+ *   deny:  ['delete_*'],
+ *   ask:   ['execute_*', 'mcp:*'],
+ * });
+ * registry.register('PreToolUse', { hooks: [policyHook] });
+ * ```
+ *
+ * Evaluation order matches Claude Code's permission flow:
+ *
+ *   1. `deny` rule match → `'deny'` (always wins, even in `bypass`).
+ *   2. `mode === 'bypass'` → `'allow'`.
+ *   3. `allow` rule match → `'allow'`.
+ *   4. `ask` rule match → `'ask'`.
+ *   5. `mode === 'dontAsk'` → `'deny'`.
+ *   6. fallthrough → `'ask'`.
+ *
+ * The returned callback is a single `HookCallback`, not a `HookMatcher` —
+ * register it under the matcher with the pattern you want (omit the
+ * pattern to fire on every tool call, which is the typical case since
+ * the policy itself does the filtering).
+ */
+export function createToolPolicyHook(
+  config: ToolPolicyConfig
+): HookCallback<'PreToolUse'> {
+  const denyMatcher = compileMatchers(config.deny);
+  const allowMatcher = compileMatchers(config.allow);
+  const askMatcher = compileMatchers(config.ask);
+  const mode: ToolPolicyMode = config.mode ?? 'default';
+  const reasonTemplate = config.reason;
+
+  return async (input): Promise<PreToolUseHookOutput> => {
+    const toolName = input.toolName;
+    const decision = decide(
+      toolName,
+      mode,
+      denyMatcher,
+      allowMatcher,
+      askMatcher
+    );
+    if (decision === 'allow') {
+      return { decision };
+    }
+    const reason = formatReason(reasonTemplate, toolName);
+    if (reason != null) {
+      return { decision, reason };
+    }
+    return { decision };
+  };
+}
+
+function decide(
+  toolName: string,
+  mode: ToolPolicyMode,
+  denyMatch: (n: string) => boolean,
+  allowMatch: (n: string) => boolean,
+  askMatch: (n: string) => boolean
+): ToolDecision {
+  if (denyMatch(toolName)) {
+    return 'deny';
+  }
+  if (mode === 'bypass') {
+    return 'allow';
+  }
+  if (allowMatch(toolName)) {
+    return 'allow';
+  }
+  if (askMatch(toolName)) {
+    return 'ask';
+  }
+  if (mode === 'dontAsk') {
+    return 'deny';
+  }
+  return 'ask';
+}

package/src/hooks/executeHooks.ts

@@ -255,6 +255,19 @@ function applyUpdatedOutput(
   agg.updatedOutput = output.updatedOutput;
 }
 
+function applyAllowedDecisions(
+  agg: AggregatedHookResult,
+  output: HookOutput
+): void {
+  if (
+    !('allowedDecisions' in output) ||
+    output.allowedDecisions === undefined
+  ) {
+    return;
+  }
+  agg.allowedDecisions = output.allowedDecisions;
+}
+
 function fold(outcomes: readonly HookOutcome[]): AggregatedHookResult {
   const agg = freshResult();
   for (const outcome of outcomes) {
@@ -268,11 +281,21 @@ function fold(outcomes: readonly HookOutcome[]): AggregatedHookResult {
     if (output === null) {
       continue;
     }
+    /**
+     * Skip fire-and-forget outputs entirely: the agent has already
+     * moved on, so an async hook cannot influence the run. Background
+     * work inside the hook body still runs (we don't cancel it), it
+     * just doesn't fold into the aggregate result.
+     */
+    if (output.async === true) {
+      continue;
+    }
     applyContext(agg, output);
     applyStopFlag(agg, output);
     applyDecision(agg, output);
     applyUpdatedInput(agg, output);
     applyUpdatedOutput(agg, output);
+    applyAllowedDecisions(agg, output);
   }
   return agg;
 }
@@ -371,5 +394,31 @@ export async function executeHooks(
 
   const outcomes = await Promise.all(tasks);
   reportErrors(outcomes, event, logger);
-  return fold(outcomes);
+  const aggregated = fold(outcomes);
+  /**
+   * Centralized `preventContinuation` propagation: when any hook (across
+   * any callsite — RunStart, PreToolUse, PostToolBatch, SubagentStop,
+   * etc.) returns `preventContinuation: true`, raise a halt signal on
+   * the registry scoped to the run's `sessionId`. `Run.processStream`
+   * polls the signal between stream events using its own id and exits
+   * cleanly, skipping the `Stop` hook (since the run is being halted,
+   * not naturally completing).
+   *
+   * First-write-wins per session inside the registry — a halt already
+   * raised by an earlier hook in the same run is preserved so the
+   * original `reason` / `source` are not clobbered. Hooks fired
+   * without a `sessionId` cannot raise a halt (there's no run for the
+   * loop to poll under), which is fine: every in-tree callsite passes
+   * `sessionId: runId`. Pre-stream callsites in `Run.processStream`
+   * still read `preventContinuation` directly off the result for an
+   * early return because they have not yet entered the stream loop.
+   */
+  if (aggregated.preventContinuation === true && sessionId !== undefined) {
+    registry.haltRun(
+      sessionId,
+      aggregated.stopReason ?? 'preventContinuation',
+      event
+    );
+  }
+  return aggregated;
 }

package/src/hooks/index.ts

@@ -7,6 +7,7 @@
 // `createSummarizeNode` (PreCompact, PostCompact), and
 // `SubagentExecutor.execute` (SubagentStart, SubagentStop).
 export { HookRegistry } from './HookRegistry';
+export type { HookHaltSignal } from './HookRegistry';
 export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
 export {
   matchesQuery,
@@ -14,6 +15,8 @@ export {
   MAX_PATTERN_LENGTH,
   MAX_CACHE_SIZE,
 } from './matchers';
+export { createToolPolicyHook } from './createToolPolicyHook';
+export type { ToolPolicyMode, ToolPolicyConfig } from './createToolPolicyHook';
 export { HOOK_EVENTS } from './types';
 export type {
   HookEvent,
@@ -34,6 +37,8 @@ export type {
   PreToolUseHookInput,
   PostToolUseHookInput,
   PostToolUseFailureHookInput,
+  PostToolBatchHookInput,
+  PostToolBatchEntry,
   PermissionDeniedHookInput,
   SubagentStartHookInput,
   SubagentStopHookInput,
@@ -46,6 +51,7 @@ export type {
   PreToolUseHookOutput,
   PostToolUseHookOutput,
   PostToolUseFailureHookOutput,
+  PostToolBatchHookOutput,
   PermissionDeniedHookOutput,
   SubagentStartHookOutput,
   SubagentStopHookOutput,

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,9 +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/langchain/google-common.ts

@@ -0,0 +1 @@
+export type { GoogleAIToolType } from '@langchain/google-common';

package/src/langchain/index.ts

@@ -0,0 +1,8 @@
+export * from './messages';
+export * from './prompts';
+export * from './runnables';
+export * from './tools';
+export * from './google-common';
+export * from './language_models/chat_models';
+export * from './messages/tool';
+export * from './openai';

package/src/langchain/language_models/chat_models.ts

@@ -0,0 +1 @@
+export type { BindToolsInput } from '@langchain/core/language_models/chat_models';

package/src/langchain/messages/tool.ts

@@ -0,0 +1,5 @@
+export type {
+  InvalidToolCall,
+  ToolCall,
+  ToolCallChunk,
+} from '@langchain/core/messages/tool';

package/src/langchain/messages.ts

@@ -0,0 +1,21 @@
+export {
+  AIMessage,
+  AIMessageChunk,
+  BaseMessage,
+  BaseMessageChunk,
+  HumanMessage,
+  SystemMessage,
+  ToolMessage,
+  getBufferString,
+  isAIMessage,
+  isBaseMessage,
+  isToolMessage,
+} from '@langchain/core/messages';
+
+export type {
+  BaseMessageFields,
+  MessageContent,
+  MessageContentText,
+  MessageContentImageUrl,
+  UsageMetadata,
+} from '@langchain/core/messages';

package/src/langchain/openai.ts

@@ -0,0 +1 @@
+export type { AzureOpenAIInput } from '@langchain/openai';

package/src/langchain/prompts.ts

@@ -0,0 +1 @@
+export { PromptTemplate } from '@langchain/core/prompts';

package/src/langchain/runnables.ts

@@ -0,0 +1,7 @@
+export {
+  Runnable,
+  RunnableLambda,
+  RunnableSequence,
+} from '@langchain/core/runnables';
+
+export type { RunnableConfig } from '@langchain/core/runnables';

package/src/langchain/tools.ts

@@ -0,0 +1,8 @@
+export {
+  DynamicStructuredTool,
+  StructuredTool,
+  Tool,
+  tool,
+} from '@langchain/core/tools';
+
+export type { StructuredToolInterface } from '@langchain/core/tools';

package/src/langchain/utils/env.ts

@@ -0,0 +1 @@
+export { getEnvironmentVariable } from '@langchain/core/utils/env';