@librechat/agents 3.9.6 → 3.9.8

package/src/tools/subagent/SubagentExecutor.ts

@@ -13,6 +13,7 @@ import {
   END,
   GraphInterrupt,
   INTERRUPT,
+  MemorySaver,
   MessagesAnnotation,
   START,
   StateGraph,
@@ -141,9 +142,10 @@ import { seedAgentInitialSessions } from '@/utils/toolSessions';
 import { stableStringify } from '@/tools/eagerEventExecution';
 import { convertInjectedMessages } from '@/messages/injected';
 import { resolveClientOptionsModel } from '@/llm/request';
+import { isBackgroundDenyMode } from '@/types/hitl';
 import { composeAbortSignals } from '@/utils/misc';
-import { sleep } from '@/utils/run';
 import { HandlerRegistry } from '@/events';
+import { sleep } from '@/utils/run';
 
 export {
   buildChildInputs,
@@ -875,6 +877,27 @@ function createSubagentFailure(
   return { content, messages: [], error };
 }
 
+function excludeBackgroundQuestionTool(agentInputs: AgentInputs): void {
+  const questionTool = 'ask_user_question';
+  agentInputs.tools = agentInputs.tools?.filter(
+    (tool) => !('name' in tool) || tool.name !== questionTool
+  );
+  agentInputs.graphTools = agentInputs.graphTools?.filter(
+    (tool) => tool.name !== questionTool
+  );
+  agentInputs.toolDefinitions = agentInputs.toolDefinitions?.filter(
+    (tool) => tool.name !== questionTool
+  );
+  if (agentInputs.toolMap?.has(questionTool) === true) {
+    agentInputs.toolMap = new Map(agentInputs.toolMap);
+    agentInputs.toolMap.delete(questionTool);
+  }
+  if (agentInputs.toolRegistry?.has(questionTool) === true) {
+    agentInputs.toolRegistry = new Map(agentInputs.toolRegistry);
+    agentInputs.toolRegistry.delete(questionTool);
+  }
+}
+
 /**
  * Factory that constructs a child graph for subagent execution. Injected
  * rather than imported so that `SubagentExecutor` does not have a runtime
@@ -1106,7 +1129,10 @@ export class SubagentExecutor {
         message: 'Maximum subagent nesting depth exceeded.',
       });
     }
-    if (this.humanInTheLoop?.enabled === true) {
+    if (
+      this.humanInTheLoop?.enabled === true &&
+      this.humanInTheLoop.backgroundPausePolicy === 'reject'
+    ) {
       return JSON.stringify({
         status: 'rejected',
         message:
@@ -1292,6 +1318,15 @@ export class SubagentExecutor {
       usageSink: this.usageSink,
       subagentContext: this.subagentContext,
       streamLimits: this.streamLimits,
+      humanInTheLoop:
+        this.humanInTheLoop?.enabled === true ||
+        this.humanInTheLoop?.backgroundPausePolicy === 'deny'
+          ? {
+            enabled: false,
+            backgroundPausePolicy: 'deny',
+            backgroundDeny: true,
+          }
+          : this.humanInTheLoop,
       maxDepth: this.maxDepth,
       createChildGraph:
         detachedGraphFactory == null
@@ -1338,6 +1373,27 @@ export class SubagentExecutor {
       if (result.error != null) {
         throw new Error(result.error);
       }
+      if (this.humanInTheLoop?.enabled === true) {
+        const deniedTools = new Set<string>();
+        for (const message of result.messages) {
+          if (
+            message instanceof ToolMessage &&
+            message.status === 'error' &&
+            typeof message.content === 'string' &&
+            message.content.startsWith('Blocked: Approval required for "') &&
+            message.name != null
+          ) {
+            deniedTools.add(message.name);
+            if (deniedTools.size >= 10) break;
+          }
+        }
+        if (deniedTools.size > 0) {
+          return {
+            ...result,
+            content: `${result.content}\nBackground approval denied for: ${[...deniedTools].join(', ')}. Ask the parent to run those tools in the foreground.`,
+          };
+        }
+      }
       return result;
     } finally {
       detached.clearHeavyState();
@@ -2489,6 +2545,11 @@ export class SubagentExecutor {
       parentMaxDepth: this.maxDepth,
       keepToolDefinitions: hasToolExecuteHandler,
     });
+    if (isBackgroundDenyMode(this.humanInTheLoop)) {
+      for (const agentInputs of childPlan.agents) {
+        excludeBackgroundQuestionTool(agentInputs);
+      }
+    }
     const childAgentId = childPlan.subjectAgentId;
     const currentHookSessionId =
       asNonEmptyString(params.hookSessionId) ??
@@ -2638,6 +2699,18 @@ export class SubagentExecutor {
       });
     }
     childGraph ??= this.createChildGraph(childGraphInput);
+    if (isBackgroundDenyMode(this.humanInTheLoop)) {
+      childGraph.humanInTheLoop = this.humanInTheLoop;
+      childGraph.eagerEventToolExecution = undefined;
+      // Never reuse the HITL parent's saver: its checkpoint namespace may
+      // contain parent messages. A private saver also lets an unexpected
+      // interrupt surface as a task error instead of a missing-saver tool
+      // error that the child could mistake for a completed task.
+      childGraph.compileOptions = {
+        ...childGraph.compileOptions,
+        checkpointer: new MemorySaver(),
+      };
+    }
     if (params.taskRuntime != null) {
       childGraph.hookRegistry = this.hookRegistry;
     }
@@ -2756,7 +2829,8 @@ export class SubagentExecutor {
         childConfigurable[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY] = resumeAttemptId;
       }
       childConfigurable.thread_id =
-        this.humanInTheLoop?.enabled === true
+        this.humanInTheLoop?.enabled === true ||
+        isBackgroundDenyMode(this.humanInTheLoop)
           ? childThreadId
           : (inheritedConfigurable.thread_id ?? childRunId);
       const childInvokeConfig = {
@@ -2884,16 +2958,31 @@ export class SubagentExecutor {
             },
             sessionId: currentHookSessionId,
             matchQuery: subagentType,
-          }).catch((): AggregatedHookResult => HOOK_FALLBACK);
+          }).catch((): AggregatedHookResult =>
+            isBackgroundDenyMode(this.humanInTheLoop)
+              ? { ...HOOK_FALLBACK, hasHookFailures: true }
+              : HOOK_FALLBACK
+          );
 
-          if (hookResult.decision === 'deny' || hookResult.decision === 'ask') {
+          const policyFailed =
+            hookResult.hasHookFailures === true &&
+            isBackgroundDenyMode(this.humanInTheLoop);
+          if (
+            policyFailed ||
+            hookResult.decision === 'deny' ||
+            hookResult.decision === 'ask'
+          ) {
             this.clearChildGraph(childGraph);
             execution.releaseActiveRun();
             this.executions.remove(execution);
-            return {
-              content: `Blocked: ${hookResult.reason ?? 'Blocked by hook'}`,
-              messages: [],
-            };
+            return policyFailed
+              ? createSubagentFailure(
+                'Subagent start policy could not be evaluated; background execution denied.'
+              )
+              : {
+                content: `Blocked: ${hookResult.reason ?? 'Blocked by hook'}`,
+                messages: [],
+              };
           }
         }
         execution.markStarted();
@@ -2956,7 +3045,8 @@ export class SubagentExecutor {
           };
         }
       }
-    } catch (error) {
+    } catch (caught) {
+      let error = caught;
       /** Stamped at failure, not after the error-envelope work below. */
       const childTerminalAt = Date.now();
       /**
@@ -2971,6 +3061,11 @@ export class SubagentExecutor {
        * `cancelled` here.
        */
       const abortedBeforeError = childSignal.aborted;
+      if (isGraphInterrupt(error) && params.taskRuntime != null) {
+        error = new Error(
+          'Background subagent cannot pause for human input. Run the tool in the foreground.'
+        );
+      }
       if (isGraphInterrupt(error)) {
         const activeChildRun = execution.activeRun;
         if (activeChildRun != null) {
@@ -3368,6 +3463,10 @@ export class SubagentExecutor {
           scheduleWrap(eventName, 'run_step', data, memberAgentId);
           return;
         }
+        if (eventName === GraphEvents.ON_TOOL_CALLS_DISPATCHED) {
+          scheduleWrap(eventName, 'tool_calls_dispatched', data, memberAgentId);
+          return;
+        }
         if (eventName === GraphEvents.ON_RUN_STEP_DELTA) {
           scheduleWrap(eventName, 'run_step_delta', data, memberAgentId);
           return;
@@ -3721,6 +3820,26 @@ export function sanitizeForwardedSubagentUpdateData(
   if (eventName === GraphEvents.ON_RUN_STEP_DELTA) {
     return sanitizeRunStepDeltaUpdateData(data);
   }
+  if (eventName === GraphEvents.ON_TOOL_CALLS_DISPATCHED) {
+    if (!isObjectLike(data)) return undefined;
+    const event = data as { dispatched_at?: number; toolCalls?: unknown };
+    if (!Array.isArray(event.toolCalls) || typeof event.dispatched_at !== 'number') {
+      return undefined;
+    }
+    return {
+      dispatched_at: event.dispatched_at,
+      toolCalls: (event.toolCalls as unknown[]).flatMap((call) => {
+        if (!isObjectLike(call)) return [];
+        const entry = call as Record<string, unknown>;
+        if (typeof entry.id !== 'string' || typeof entry.name !== 'string') return [];
+        return [{
+          id: entry.id,
+          name: entry.name,
+          ...(typeof entry.stepId === 'string' ? { stepId: entry.stepId } : {}),
+        }];
+      }),
+    };
+  }
   if (eventName === GraphEvents.ON_RUN_STEP_COMPLETED) {
     return sanitizeRunStepCompletedUpdateData(data);
   }

package/src/types/graph.ts

@@ -17,6 +17,7 @@ import type {
   RunStepDeltaEvent,
   RunStepResumeState,
   RunStepClosedEvent,
+  ToolCallsDispatchedEvent,
   MessageDeltaEvent,
   ReasoningDeltaEvent,
 } from '@/types/stream';
@@ -209,6 +210,7 @@ export interface EventHandler {
       | RunStep
       | RunStepDeltaEvent
       | RunStepClosedEvent
+      | ToolCallsDispatchedEvent
       | MessageDeltaEvent
       | ReasoningDeltaEvent
       | SummarizeStartEvent
@@ -694,6 +696,7 @@ export type SubagentUpdatePhase =
   | 'start'
   | 'run_step'
   | 'run_step_delta'
+  | 'tool_calls_dispatched'
   | 'run_step_completed'
   | 'run_step_closed'
   | 'message_delta'

package/src/types/hitl.ts

@@ -407,6 +407,26 @@ export interface HumanInTheLoopConfig {
    * UI is ready to render and resolve `tool_approval` interrupts.
    */
   enabled?: boolean;
+  /**
+   * Background children cannot pause for human input. `deny` (the default)
+   * lets them run but blocks tools whose hooks request approval, and excludes
+   * `ask_user_question`. `reject` preserves the legacy admission check.
+   * Durable deferred approvals require a separate resume implementation.
+   */
+  backgroundPausePolicy?: 'deny' | 'reject';
+  /** @internal Set only on detached children and their descendants, never on the parent run. */
+  backgroundDeny?: true;
+}
+
+/** True only on an SDK-created background child, not a foreground HITL run. */
+export function isBackgroundDenyMode(
+  config: HumanInTheLoopConfig | undefined
+): boolean {
+  return (
+    config?.backgroundDeny === true &&
+    config.enabled === false &&
+    config.backgroundPausePolicy === 'deny'
+  );
 }
 
 /**

package/src/types/stream.ts

@@ -158,6 +158,8 @@ export interface RunStepDeltaEvent {
    * The delta containing the fields that have changed on the run step.
    */
   delta: ToolCallDelta;
+  /** Epoch ms when the SDK received this tool-call fragment, before step dispatch. */
+  observed_at?: number;
 }
 
 /**
@@ -264,6 +266,25 @@ export type ToolCallCompleted = {
   tool_call: ProcessedToolCall;
 };
 
+/**
+ * A tool call has crossed from model-authored argument preparation into SDK
+ * execution. Emitted immediately before host dispatch or direct invocation;
+ * it does not claim the host has begun its own work. Paired with the tool
+ * completion `completed_at`, the stamp measures SDK handoff-to-result time,
+ * not MCP or database execution time. The earliest `observed_at` tool-call
+ * delta for a call bounds its argument preparation time; consumers correlate
+ * deltas by step/index until an ID is known. For a call without streamed
+ * fragments, the preparation start is unknown. Never infer a missing start.
+ * An eager call may dispatch before it has a step ID, and this observational
+ * event may arrive after completion: correlate by tool call ID and timestamps,
+ * not arrival order.
+ */
+export type ToolCallsDispatchedEvent = {
+  dispatched_at: number;
+  runId?: string;
+  toolCalls: Array<{ id: string; name: string; stepId?: string }>;
+};
+
 export type ToolCompleteEvent = ToolCallCompleted & {
   /** The Step Id of the Tool Call */
   id: string;

package/src/types/tools.ts

@@ -700,6 +700,8 @@ export type OutcomePatch = {
 export type ToolExecuteResult = {
   /** Matches ToolCallRequest.id */
   toolCallId: string;
+  /** SDK-stamped result receipt time; never host-supplied or inferred from handler cleanup. */
+  received_at?: number;
   /** Tool output content */
   content: string | unknown[];
   /** Optional artifact (for content_and_artifact format) */
@@ -1256,6 +1258,8 @@ export type ProgrammaticCache = {
 
 export type ProgrammaticHookContext = {
   registry: import('@/hooks').HookRegistry | undefined;
+  /** A detached HITL child must never execute an inner tool if its policy hook fails. */
+  failClosedOnHookError?: boolean;
   runId: string;
   threadId?: string;
   agentId?: string;

package/src/utils/events.ts

@@ -2,6 +2,7 @@
 // src/utils/events.ts
 import { dispatchCustomEvent } from '@langchain/core/callbacks/dispatch';
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ToolCallsDispatchedEvent } from '@/types/stream';
 import type { ToolExecuteBatchRequest } from '@/types/tools';
 import type { AgentLogEvent } from '@/types/graph';
 import { traceHostToolResults } from '@/langfuse';
@@ -24,11 +25,13 @@ export async function safeDispatchCustomEvent(
         resolve: (
           results: Parameters<ToolExecuteBatchRequest['resolve']>[0]
         ): void => {
+          const receivedAt = Date.now();
+          const stamped = results.map((result) => ({ ...result, received_at: receivedAt }));
           void traceHostToolResults(request, results, config).then(
-            () => request.resolve(results),
+            () => request.resolve(stamped),
             () => {
               console.warn('Failed to record host tool execution metadata');
-              request.resolve(results);
+              request.resolve(stamped);
             }
           );
         },
@@ -54,6 +57,22 @@ export async function safeDispatchCustomEvent(
   }
 }
 
+/** Builds an argument-free snapshot once per handoff, not once per result. */
+export function createToolCallsDispatchedEvent(
+  config: RunnableConfig,
+  calls: readonly Pick<
+    ToolExecuteBatchRequest['toolCalls'][number],
+    'id' | 'name' | 'stepId'
+  >[]
+): ToolCallsDispatchedEvent {
+  const runId = config.configurable?.run_id;
+  return {
+    dispatched_at: Date.now(),
+    ...(typeof runId === 'string' ? { runId } : {}),
+    toolCalls: calls.map(({ id, name, stepId }) => ({ id, name, stepId })),
+  };
+}
+
 /**
  * Fire-and-forget diagnostic log event.
  * Debug-level logs are gated behind AGENT_DEBUG_LOGGING=true to avoid