@librechat/agents 3.3.13 → 3.4.1

package/src/graphs/__tests__/Graph.breakerLifecycle.test.ts

@@ -1,9 +1,9 @@
-import { describe, it, expect } from '@jest/globals';
+import { describe, it, expect, jest } from '@jest/globals';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type * as t from '@/types';
 import { StreamLimitExceededError } from '@/llm/streamLimits';
-import { Providers } from '@/common';
 import { StandardGraph } from '../Graph';
+import { Providers } from '@/common';
 
 const makeAgent = (agentId: string): t.AgentInputs => ({
   agentId,
@@ -25,7 +25,51 @@ const makeTrip = (): StreamLimitExceededError =>
     toolName: 'db_query',
   });
 
+type CompiledRegistrationInternals = {
+  _compiledToolNodes: Set<{ clearDirectPathTurns(): void }>;
+  _subagentExecutors: Set<{
+    clearHeavyState(): void;
+    resetCheckpointThreadIds(): void;
+  }>;
+};
+
 describe('run breaker lifecycle', () => {
+  it('retains compiled cleanup registrations across graph reuse', () => {
+    const graph = makeGraph();
+    const internals = graph as unknown as CompiledRegistrationInternals;
+    const clearDirectPathTurns = jest.fn();
+    const clearSubagentState = jest.fn();
+    const resetCheckpointThreadIds = jest.fn();
+    internals._compiledToolNodes.add({ clearDirectPathTurns });
+    internals._subagentExecutors.add({
+      clearHeavyState: clearSubagentState,
+      resetCheckpointThreadIds,
+    });
+
+    graph.clearHeavyState();
+    graph.clearHeavyState();
+
+    expect(clearDirectPathTurns).toHaveBeenCalledTimes(2);
+    expect(clearSubagentState).toHaveBeenCalledTimes(2);
+    expect(internals._compiledToolNodes.size).toBe(1);
+    expect(internals._subagentExecutors.size).toBe(1);
+  });
+
+  it('resets subagent checkpoint ownership at each fresh run start', () => {
+    const graph = makeGraph();
+    const internals = graph as unknown as CompiledRegistrationInternals;
+    const resetCheckpointThreadIds = jest.fn();
+    internals._subagentExecutors.add({
+      clearHeavyState: jest.fn(),
+      resetCheckpointThreadIds,
+    });
+
+    graph.resetValues();
+    graph.resetValues();
+
+    expect(resetCheckpointThreadIds).toHaveBeenCalledTimes(2);
+  });
+
   it('replaces the breaker at every run start, even when un-aborted', () => {
     const graph = makeGraph();
     const previous = graph.breakerAbort;
@@ -115,9 +159,7 @@ describe('run breaker lifecycle', () => {
           model: model as unknown as t.ChatModel,
           messages: [new HumanMessage('hi')],
           provider: Providers.OPENAI,
-          context: graph as Parameters<
-            typeof attemptInvoke
-          >[0]['context'],
+          context: graph as Parameters<typeof attemptInvoke>[0]['context'],
           onChunk: () => {
             /* producer loop enforcement is under test */
           },
@@ -225,10 +267,7 @@ describe('run breaker lifecycle', () => {
     /** With a live breaker the entry guard must not fire; the node then
      * fails later, on the missing config, proving it got past the guard. */
     await expect(
-      node(
-        { messages: [] } as unknown as t.AgentSubgraphState,
-        undefined
-      )
+      node({ messages: [] } as unknown as t.AgentSubgraphState, undefined)
     ).rejects.toThrow('No config provided');
   });
 });

package/src/graphs/__tests__/Graph.contextOverflow.test.ts

@@ -1338,7 +1338,7 @@ describe('context overflow recovery', () => {
     if (agentContext == null) {
       throw new Error('Expected default agent context');
     }
-    expect(run.Graph.compileOptions?.checkpointer).toBeUndefined();
+    expect(run.Graph.compileOptions?.checkpointer).toBeInstanceOf(MemorySaver);
     expect(run.Graph.hasCompiledCheckpointer).toBe(true);
     run.Graph.resetValues(undefined, 'checkpoint-scope');
     agentContext.preserveOriginalToolContent(new Map([[2, 'full output']]));

package/src/graphs/__tests__/Graph.subagentResumeState.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from '@jest/globals';
+import type { SubagentToolNodeResumeState } from '@/tools/subagent/SubagentReplay';
+import { StandardGraph } from '../Graph';
+import { Providers } from '@/common';
+
+type ResumeToolNode = {
+  createSubagentResumeState(): SubagentToolNodeResumeState;
+  restoreSubagentResumeState(state: SubagentToolNodeResumeState): void;
+};
+
+const makeGraph = (runId: string): StandardGraph =>
+  new StandardGraph({
+    runId,
+    agents: [
+      {
+        agentId: 'child-agent',
+        provider: Providers.OPENAI,
+        instructions: 'Test child state restoration.',
+      },
+    ],
+  });
+
+const initializeToolNode = (graph: StandardGraph): ResumeToolNode => {
+  const agentContext = graph.agentContexts.get('child-agent');
+  return graph.initializeTools({
+    currentTools: [],
+    agentContext,
+  }) as unknown as ResumeToolNode;
+};
+
+describe('subagent graph resume state', () => {
+  it('restores tool identity, turns, references, and sessions into a branch', () => {
+    const source = makeGraph('source');
+    source.toolOutputReferences = { enabled: true };
+    const sourceNode = initializeToolNode(source);
+    source.toolCallStepIds.set('call_tool', 'step_tool');
+    source.sessions.set('execute_code', {
+      session_id: 'sandbox-session',
+      lastUpdated: 42,
+    });
+    source
+      .getOrCreateToolOutputRegistry()
+      ?.set('source-scope', 'tool0turn0', 'raw output');
+    source.getEagerEventToolUsageCount('child-agent').set('calculator', 3);
+    source.eagerEventToolSuppressions.add('unstable_search');
+    const sourceNodeState = sourceNode.createSubagentResumeState();
+    sourceNode.restoreSubagentResumeState({
+      ...sourceNodeState,
+      toolUsageCounts: [{ toolName: 'calculator', count: 3 }],
+      directPathTurns: [{ toolCallId: 'call_tool', turn: 2 }],
+    });
+
+    const target = makeGraph('target');
+    target.toolOutputReferences = { enabled: true };
+    const targetNode = initializeToolNode(target);
+    target.restoreSubagentResumeState(
+      source.createSubagentResumeState('source-scope'),
+      'target-scope'
+    );
+
+    expect(target.toolCallStepIds.get('call_tool')).toBe('step_tool');
+    expect(target.sessions.get('execute_code')).toMatchObject({
+      session_id: 'sandbox-session',
+      lastUpdated: 42,
+    });
+    expect(
+      target.getOrCreateToolOutputRegistry()?.get('target-scope', 'tool0turn0')
+    ).toBe('raw output');
+    expect(targetNode.createSubagentResumeState()).toMatchObject({
+      toolUsageCounts: [{ toolName: 'calculator', count: 3 }],
+      directPathTurns: [{ toolCallId: 'call_tool', turn: 2 }],
+    });
+    expect(
+      target.getEagerEventToolUsageCount('child-agent').get('calculator')
+    ).toBe(3);
+    expect(target.eagerEventToolSuppressions).toEqual(
+      new Set(['unstable_search'])
+    );
+  });
+});

package/src/hooks/HookRegistry.ts

@@ -1,5 +1,31 @@
 // src/hooks/HookRegistry.ts
-import type { HookEvent, HookMatcher } from './types';
+import type {
+  HookEvent,
+  HookMatcher,
+  ToolApprovalReplayKey,
+  ToolApprovalReplaySnapshot,
+  AggregatedHookResult,
+} from './types';
+
+function serializeApprovalKey(key: ToolApprovalReplayKey): string {
+  return JSON.stringify([key.executionScope, key.agentId, key.toolUseId]);
+}
+
+function deserializeApprovalKey(value: string): ToolApprovalReplayKey | null {
+  const parsed: unknown = JSON.parse(value);
+  if (
+    !Array.isArray(parsed) ||
+    parsed.length !== 3 ||
+    parsed.some((part) => typeof part !== 'string')
+  ) {
+    return null;
+  }
+  return {
+    executionScope: parsed[0],
+    agentId: parsed[1],
+    toolUseId: parsed[2],
+  };
+}
 
 /**
  * Internal matcher storage type.
@@ -71,6 +97,11 @@ export class HookRegistry {
    * O(1) insertion in hot paths, no spread-on-write.
    */
   private readonly haltSignals: Map<string, HookHaltSignal> = new Map();
+  /** One-shot hook contributions retained until approval is consumed. */
+  private readonly pendingToolApprovals = new Map<
+    string,
+    Map<string, AggregatedHookResult>
+  >();
 
   /**
    * Register a matcher for the lifetime of this registry (= one Run).
@@ -160,6 +191,125 @@ export class HookRegistry {
    */
   clearSession(sessionId: string): void {
     this.sessions.delete(sessionId);
+    this.pendingToolApprovals.delete(sessionId);
+  }
+
+  /** Copies session-scoped policy into a rebuilt or branched Run. */
+  copySession(sourceSessionId: string, targetSessionId: string): void {
+    if (sourceSessionId === targetSessionId) {
+      return;
+    }
+    const source = this.sessions.get(sourceSessionId);
+    if (source != null) {
+      const target = this.ensureSessionBucket(targetSessionId);
+      for (const event of Object.keys(source) as HookEvent[]) {
+        const targetList = ensureList(target, event);
+        for (const matcher of readList(source, event)) {
+          if (!targetList.includes(matcher)) {
+            targetList.push(matcher);
+          }
+        }
+      }
+    }
+    const pending = this.pendingToolApprovals.get(sourceSessionId);
+    if (pending == null) {
+      return;
+    }
+    let targetPending = this.pendingToolApprovals.get(targetSessionId);
+    if (targetPending == null) {
+      targetPending = new Map();
+      this.pendingToolApprovals.set(targetSessionId, targetPending);
+    }
+    for (const [toolUseId, result] of pending) {
+      if (!targetPending.has(toolUseId)) {
+        targetPending.set(toolUseId, result);
+      }
+    }
+  }
+
+  getPendingToolApproval(
+    sessionId: string,
+    key: ToolApprovalReplayKey
+  ): AggregatedHookResult | undefined {
+    return this.pendingToolApprovals
+      .get(sessionId)
+      ?.get(serializeApprovalKey(key));
+  }
+
+  setPendingToolApproval(
+    sessionId: string,
+    key: ToolApprovalReplayKey,
+    result: AggregatedHookResult
+  ): void {
+    let pending = this.pendingToolApprovals.get(sessionId);
+    if (pending == null) {
+      pending = new Map();
+      this.pendingToolApprovals.set(sessionId, pending);
+    }
+    pending.set(serializeApprovalKey(key), result);
+  }
+
+  clearPendingToolApproval(
+    sessionId: string,
+    key: ToolApprovalReplayKey
+  ): void {
+    const pending = this.pendingToolApprovals.get(sessionId);
+    if (pending == null) {
+      return;
+    }
+    pending.delete(serializeApprovalKey(key));
+    if (pending.size === 0) {
+      this.pendingToolApprovals.delete(sessionId);
+    }
+  }
+
+  snapshotPendingToolApprovals(
+    sessionId: string,
+    executionScope: string
+  ): ToolApprovalReplaySnapshot[] {
+    const pending = this.pendingToolApprovals.get(sessionId);
+    if (pending == null) {
+      return [];
+    }
+    const snapshots: ToolApprovalReplaySnapshot[] = [];
+    for (const [serializedKey, result] of pending) {
+      const key = deserializeApprovalKey(serializedKey);
+      if (key == null || key.executionScope !== executionScope) {
+        continue;
+      }
+      snapshots.push({ key, result });
+    }
+    return snapshots;
+  }
+
+  restorePendingToolApprovals(
+    sessionId: string,
+    targetExecutionScope: string,
+    snapshots: ReadonlyArray<ToolApprovalReplaySnapshot>
+  ): void {
+    const restored = new Map<string, AggregatedHookResult>();
+    for (const [serializedKey, result] of this.pendingToolApprovals.get(
+      sessionId
+    ) ?? []) {
+      const key = deserializeApprovalKey(serializedKey);
+      if (key?.executionScope !== targetExecutionScope) {
+        restored.set(serializedKey, result);
+      }
+    }
+    for (const snapshot of snapshots) {
+      restored.set(
+        serializeApprovalKey({
+          ...snapshot.key,
+          executionScope: targetExecutionScope,
+        }),
+        snapshot.result
+      );
+    }
+    if (restored.size === 0) {
+      this.pendingToolApprovals.delete(sessionId);
+      return;
+    }
+    this.pendingToolApprovals.set(sessionId, restored);
   }
 
   /**

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

@@ -164,6 +164,102 @@ describe('HookRegistry', () => {
       expect(registry.hasHookFor('PreToolUse', 'run-a')).toBe(true);
       expect(registry.hasHookFor('PreToolUse', 'run-b')).toBe(false);
     });
+
+    it('copies session policy without consuming the source or sibling branches', () => {
+      const registry = new HookRegistry();
+      const matcher = makePreToolUseMatcher('subagent');
+      registry.registerSession('source', 'PreToolUse', matcher);
+
+      registry.copySession('source', 'branch-a');
+      registry.copySession('source', 'branch-b');
+
+      expect(registry.getMatchers('PreToolUse', 'source')).toEqual([matcher]);
+      expect(registry.getMatchers('PreToolUse', 'branch-a')).toEqual([matcher]);
+      expect(registry.getMatchers('PreToolUse', 'branch-b')).toEqual([matcher]);
+
+      registry.clearSession('branch-a');
+      expect(registry.getMatchers('PreToolUse', 'source')).toEqual([matcher]);
+      expect(registry.getMatchers('PreToolUse', 'branch-b')).toEqual([matcher]);
+    });
+
+    it('copies pending one-shot approvals and clears them with the target session', () => {
+      const registry = new HookRegistry();
+      const approval = {
+        decision: 'ask' as const,
+        reason: 'review tool',
+        additionalContexts: [],
+        injectedMessages: [],
+        errors: [],
+      };
+      const key = {
+        executionScope: 'child-a',
+        agentId: 'researcher',
+        toolUseId: 'call_1',
+      };
+      const siblingKey = { ...key, executionScope: 'child-b' };
+      registry.setPendingToolApproval('source', key, approval);
+      registry.setPendingToolApproval('source', siblingKey, {
+        ...approval,
+        reason: 'review sibling',
+      });
+
+      registry.copySession('source', 'branch');
+
+      expect(registry.getPendingToolApproval('source', key)).toBe(approval);
+      expect(registry.getPendingToolApproval('branch', key)).toBe(approval);
+      expect(
+        registry.getPendingToolApproval('branch', siblingKey)?.reason
+      ).toBe('review sibling');
+      registry.clearPendingToolApproval('branch', key);
+      expect(registry.getPendingToolApproval('branch', key)).toBeUndefined();
+      expect(
+        registry.getPendingToolApproval('branch', siblingKey)?.reason
+      ).toBe('review sibling');
+      const checkpointSnapshot = registry.snapshotPendingToolApprovals(
+        'source',
+        'child-a'
+      );
+      expect(checkpointSnapshot).toEqual([{ key, result: approval }]);
+      registry.clearSession('branch');
+      expect(
+        registry.getPendingToolApproval('branch', siblingKey)
+      ).toBeUndefined();
+      expect(registry.getPendingToolApproval('source', key)).toBe(approval);
+      registry.setPendingToolApproval('restored', key, {
+        ...approval,
+        reason: 'stale approval',
+      });
+      registry.setPendingToolApproval('restored', siblingKey, {
+        ...approval,
+        reason: 'preserved sibling',
+      });
+      registry.restorePendingToolApprovals(
+        'restored',
+        'child-a',
+        checkpointSnapshot
+      );
+      expect(registry.getPendingToolApproval('restored', key)).toBe(approval);
+      expect(
+        registry.getPendingToolApproval('restored', siblingKey)?.reason
+      ).toBe('preserved sibling');
+      registry.restorePendingToolApprovals('restored', 'child-b', []);
+      expect(
+        registry.getPendingToolApproval('restored', siblingKey)
+      ).toBeUndefined();
+
+      const branchKey = { ...key, executionScope: 'child-a-attempt-2' };
+      registry.restorePendingToolApprovals(
+        'restored',
+        branchKey.executionScope,
+        checkpointSnapshot
+      );
+      expect(registry.getPendingToolApproval('restored', branchKey)).toBe(
+        approval
+      );
+      expect(registry.getPendingToolApproval('restored', key)).toBe(approval);
+      registry.clearPendingToolApproval('restored', branchKey);
+      expect(registry.getPendingToolApproval('restored', key)).toBe(approval);
+    });
   });
 
   describe('session isolation under parallel registration', () => {

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

@@ -764,6 +764,166 @@ describe('executeHooks', () => {
   });
 
   describe('once: true self-removal', () => {
+    it('replays a one-shot approval until the tool decision is consumed', async () => {
+      const registry = new HookRegistry();
+      let calls = 0;
+      registry.registerSession('run-1', 'PreToolUse', {
+        once: true,
+        hooks: [
+          async (): Promise<PreToolUseHookOutput> => {
+            calls += 1;
+            return { decision: 'ask', reason: 'review once' };
+          },
+        ],
+      });
+      const options = {
+        registry,
+        input: preToolUseInput('Bash'),
+        matchQuery: 'Bash',
+        sessionId: 'run-1',
+        onceReplayKey: {
+          executionScope: 'child-a',
+          agentId: 'researcher',
+          toolUseId: 'call_1',
+        },
+      };
+
+      await executeHooks(options);
+      const replay = await executeHooks(options);
+
+      expect(replay).toMatchObject({
+        decision: 'ask',
+        reason: 'review once',
+      });
+      expect(calls).toBe(1);
+      expect(registry.getMatchers('PreToolUse', 'run-1')).toHaveLength(0);
+
+      const sibling = await executeHooks({
+        ...options,
+        onceReplayKey: {
+          ...options.onceReplayKey,
+          executionScope: 'child-b',
+        },
+      });
+      expect(sibling.decision).toBeUndefined();
+
+      registry.clearPendingToolApproval('run-1', options.onceReplayKey);
+      const afterDecision = await executeHooks(options);
+      expect(afterDecision.decision).toBeUndefined();
+      expect(calls).toBe(1);
+    });
+
+    it('replays only one-shot contributions while rerunning ordinary hooks', async () => {
+      const registry = new HookRegistry();
+      let onceCalls = 0;
+      let ordinaryCalls = 0;
+      let ordinaryDecision: 'allow' | 'deny' = 'allow';
+      registry.registerSession('run-1', 'PreToolUse', {
+        once: true,
+        hooks: [
+          async (): Promise<PreToolUseHookOutput> => {
+            onceCalls += 1;
+            return {
+              decision: 'ask',
+              reason: 'review once',
+              additionalContext: 'once-context',
+            };
+          },
+        ],
+      });
+      registry.registerSession('run-1', 'PreToolUse', {
+        hooks: [
+          async (): Promise<PreToolUseHookOutput> => {
+            ordinaryCalls += 1;
+            return {
+              decision: ordinaryDecision,
+              reason: `ordinary-${ordinaryDecision}`,
+              additionalContext: `ordinary-${ordinaryCalls}`,
+            };
+          },
+        ],
+      });
+      const options = {
+        registry,
+        input: preToolUseInput('Bash'),
+        matchQuery: 'Bash',
+        sessionId: 'run-1',
+        onceReplayKey: {
+          executionScope: 'child-a',
+          agentId: 'researcher',
+          toolUseId: 'call_1',
+        },
+      };
+
+      const first = await executeHooks(options);
+      ordinaryDecision = 'deny';
+      const replay = await executeHooks(options);
+
+      expect(first.decision).toBe('ask');
+      expect(replay).toMatchObject({
+        decision: 'deny',
+        reason: 'ordinary-deny',
+        additionalContexts: ['once-context', 'ordinary-2'],
+      });
+      expect(onceCalls).toBe(1);
+      expect(ordinaryCalls).toBe(2);
+      expect(
+        registry.getPendingToolApproval('run-1', options.onceReplayKey)
+      ).toBeUndefined();
+    });
+
+    it('retains a consumed one-shot rewrite when an ordinary hook asks', async () => {
+      const registry = new HookRegistry();
+      let onceCalls = 0;
+      let ordinaryCalls = 0;
+      registry.registerSession('run-1', 'PreToolUse', {
+        once: true,
+        hooks: [
+          async (): Promise<PreToolUseHookOutput> => {
+            onceCalls += 1;
+            return {
+              decision: 'allow',
+              updatedInput: { command: 'sanitized' },
+            };
+          },
+        ],
+      });
+      registry.registerSession('run-1', 'PreToolUse', {
+        hooks: [
+          async (): Promise<PreToolUseHookOutput> => {
+            ordinaryCalls += 1;
+            return { decision: 'ask', reason: 'ordinary approval' };
+          },
+        ],
+      });
+      const options = {
+        registry,
+        input: preToolUseInput('Bash'),
+        matchQuery: 'Bash',
+        sessionId: 'run-1',
+        onceReplayKey: {
+          executionScope: 'child-a',
+          agentId: 'researcher',
+          toolUseId: 'call_1',
+        },
+      };
+
+      const first = await executeHooks(options);
+      const replay = await executeHooks(options);
+
+      expect(first).toMatchObject({
+        decision: 'ask',
+        updatedInput: { command: 'sanitized' },
+      });
+      expect(replay).toMatchObject({
+        decision: 'ask',
+        reason: 'ordinary approval',
+        updatedInput: { command: 'sanitized' },
+      });
+      expect(onceCalls).toBe(1);
+      expect(ordinaryCalls).toBe(2);
+    });
+
     it('removes the matcher after a successful fire', async () => {
       const registry = new HookRegistry();
       let calls = 0;