@librechat/agents 3.4.0 → 3.4.2

package/src/tools/__tests__/SubagentReplay.test.ts

@@ -0,0 +1,329 @@
+import {
+  getSubagentResumeManifest,
+  attachSubagentResumeManifest,
+  requireValidSubagentResumeManifest,
+  stripSubagentResumeManifest,
+} from '@/tools/subagent/SubagentReplay';
+
+describe('SubagentReplay manifest', () => {
+  const execution = {
+    parentToolCallId: 'call_parent',
+    childRunId: 'child-run',
+    subagentType: 'researcher',
+    configId: 'researcher@v1',
+    approvalExecutionScope: 'child-approval-scope',
+    checkpoints: [
+      {
+        threadId: 'child-thread',
+        checkpointId: 'checkpoint-root',
+        checkpointNs: '',
+      },
+      {
+        threadId: 'child-thread',
+        checkpointId: 'checkpoint-agent',
+        checkpointNs: 'agent:task',
+      },
+    ],
+    graphState: {
+      toolCallSteps: [{ toolCallId: 'call_tool', stepId: 'step_tool' }],
+      toolSessions: [
+        {
+          toolName: 'execute_code',
+          context: { session_id: 'session', lastUpdated: 1 },
+        },
+      ],
+      toolNodes: [
+        {
+          stateKey: 'child-agent',
+          toolUsageCounts: [{ toolName: 'calculator', count: 1 }],
+          directPathTurns: [{ toolCallId: 'call_tool', turn: 0 }],
+        },
+      ],
+      eagerToolUsage: [
+        {
+          agentId: 'child-agent',
+          toolUsageCounts: [{ toolName: 'calculator', count: 1 }],
+        },
+      ],
+      eagerToolSuppressions: ['unstable_search'],
+      toolOutputReferences: {
+        entries: [{ key: 'tool0turn0', value: '42' }],
+        turnCounter: 1,
+        warnedNonStringTools: [],
+      },
+    },
+    approvalReplays: [
+      {
+        key: {
+          executionScope: 'child-approval-scope',
+          agentId: 'child-agent',
+          toolUseId: 'call_tool',
+        },
+        result: {
+          decision: 'ask' as const,
+          reason: 'review tool',
+          additionalContexts: [],
+          injectedMessages: [],
+          errors: [],
+        },
+      },
+    ],
+  };
+
+  it('round-trips a private manifest without exposing it publicly', () => {
+    const manifest = { version: 1 as const, executions: [execution] };
+    const payload = attachSubagentResumeManifest(
+      { type: 'tool_approval', visible: true },
+      manifest
+    );
+
+    expect(getSubagentResumeManifest(payload)).toEqual(manifest);
+    expect(stripSubagentResumeManifest(payload)).toEqual({
+      type: 'tool_approval',
+      visible: true,
+    });
+  });
+
+  it('accepts legacy executions without a bound subagent type', () => {
+    const { subagentType: _subagentType, ...legacyExecution } = execution;
+    const manifest = { version: 1 as const, executions: [legacyExecution] };
+    const payload = attachSubagentResumeManifest(
+      { type: 'tool_approval' },
+      manifest
+    );
+
+    expect(getSubagentResumeManifest(payload)).toEqual(manifest);
+  });
+
+  it.each(['', 42, { type: 'researcher' }])(
+    'rejects malformed bound subagent type %#',
+    (subagentType) => {
+      const manifest = {
+        version: 1 as const,
+        executions: [{ ...execution, subagentType }],
+      };
+
+      expect(
+        getSubagentResumeManifest({
+          __librechat_subagent_resume_manifest: manifest,
+        })
+      ).toBeUndefined();
+    }
+  );
+
+  it.each([
+    ['string', 'approve this child'],
+    ['number', 42],
+    ['null', null],
+    ['array', ['approve', { call: 1 }]],
+  ])(
+    'round-trips a private manifest around a %s interrupt payload',
+    (_label, visiblePayload) => {
+      const manifest = { version: 1 as const, executions: [execution] };
+      const payload = attachSubagentResumeManifest(visiblePayload, manifest);
+
+      expect(getSubagentResumeManifest(payload)).toEqual(manifest);
+      expect(stripSubagentResumeManifest(payload)).toEqual(visiblePayload);
+    }
+  );
+
+  it.each([
+    ['Map', new Map([['decision', 'approve']])],
+    ['Set', new Set(['approve'])],
+    ['RegExp', /^approve$/i],
+  ])(
+    'round-trips a private manifest around a %s interrupt payload',
+    (_label, visiblePayload) => {
+      const manifest = { version: 1 as const, executions: [execution] };
+      const payload = attachSubagentResumeManifest(visiblePayload, manifest);
+
+      expect(getSubagentResumeManifest(payload)).toEqual(manifest);
+      expect(stripSubagentResumeManifest(payload)).toBe(visiblePayload);
+    }
+  );
+
+  it.each([
+    {
+      __librechat_subagent_resume_manifest: { visible: true },
+      value: 'manifest collision',
+    },
+    {
+      __librechat_subagent_resume_wrapper: 1,
+      __librechat_subagent_resume_payload: 'visible nested value',
+      value: 'wrapper collision',
+    },
+  ])(
+    'preserves a custom payload containing private transport keys',
+    (value) => {
+      const manifest = { version: 1 as const, executions: [execution] };
+      const payload = attachSubagentResumeManifest(value, manifest);
+
+      expect(stripSubagentResumeManifest(value)).toBe(value);
+      expect(getSubagentResumeManifest(payload)).toEqual(manifest);
+      expect(stripSubagentResumeManifest(payload)).toBe(value);
+    }
+  );
+
+  it('updates the manifest on an existing inline payload', () => {
+    const firstManifest = { version: 1 as const, executions: [execution] };
+    const nextManifest = {
+      version: 1 as const,
+      executions: [{ ...execution, childRunId: 'next-inline-child-run' }],
+    };
+    const firstPayload = attachSubagentResumeManifest(
+      { type: 'tool_approval', visible: true },
+      firstManifest
+    );
+    const nextPayload = attachSubagentResumeManifest(
+      firstPayload,
+      nextManifest
+    );
+
+    expect(getSubagentResumeManifest(nextPayload)).toEqual(nextManifest);
+    expect(stripSubagentResumeManifest(nextPayload)).toEqual({
+      type: 'tool_approval',
+      visible: true,
+    });
+  });
+
+  it('updates the manifest on an existing private wrapper', () => {
+    const firstManifest = { version: 1 as const, executions: [execution] };
+    const nextManifest = {
+      version: 1 as const,
+      executions: [{ ...execution, childRunId: 'next-child-run' }],
+    };
+    const firstPayload = attachSubagentResumeManifest(
+      'visible payload',
+      firstManifest
+    );
+    const nextPayload = attachSubagentResumeManifest(
+      firstPayload,
+      nextManifest
+    );
+
+    expect(getSubagentResumeManifest(nextPayload)).toEqual(nextManifest);
+    expect(stripSubagentResumeManifest(nextPayload)).toBe('visible payload');
+  });
+
+  it('rejects ambiguous or cross-execution replay data', () => {
+    const mismatchedScope = {
+      ...execution,
+      approvalReplays: [
+        {
+          ...execution.approvalReplays[0],
+          key: {
+            ...execution.approvalReplays[0].key,
+            executionScope: 'different-child',
+          },
+        },
+      ],
+    };
+    const duplicateParent = {
+      version: 1 as const,
+      executions: [execution, { ...execution }],
+    };
+    const duplicateToolCall = {
+      ...execution,
+      graphState: {
+        ...execution.graphState,
+        toolCallSteps: [
+          ...execution.graphState.toolCallSteps,
+          { ...execution.graphState.toolCallSteps[0] },
+        ],
+      },
+    };
+
+    expect(
+      getSubagentResumeManifest(
+        attachSubagentResumeManifest(
+          { type: 'tool_approval' },
+          { version: 1, executions: [mismatchedScope] }
+        )
+      )
+    ).toBeUndefined();
+    expect(
+      getSubagentResumeManifest(
+        attachSubagentResumeManifest({ type: 'tool_approval' }, duplicateParent)
+      )
+    ).toBeUndefined();
+    expect(
+      getSubagentResumeManifest(
+        attachSubagentResumeManifest(
+          { type: 'tool_approval' },
+          { version: 1, executions: [duplicateToolCall] }
+        )
+      )
+    ).toBeUndefined();
+  });
+
+  it('fails closed for malformed nested references', () => {
+    const malformed = {
+      __librechat_subagent_resume_manifest: {
+        version: 1,
+        executions: [{ ...execution, checkpoints: [null] }],
+      },
+    };
+    expect(getSubagentResumeManifest(malformed)).toBeUndefined();
+    expect(() => requireValidSubagentResumeManifest(malformed)).toThrow(
+      'Invalid subagent resume manifest.'
+    );
+    expect(
+      getSubagentResumeManifest({
+        __librechat_subagent_resume_manifest: {
+          version: 1,
+          executions: [
+            {
+              ...execution,
+              graphState: {
+                ...execution.graphState,
+                toolCallSteps: [null],
+              },
+            },
+          ],
+        },
+      })
+    ).toBeUndefined();
+  });
+
+  it('rejects duplicate checkpoint namespaces and approval replay keys', () => {
+    const duplicateCheckpointNamespace = {
+      ...execution,
+      checkpoints: [execution.checkpoints[0], { ...execution.checkpoints[0] }],
+    };
+    const duplicateApprovalReplay = {
+      ...execution,
+      approvalReplays: [
+        execution.approvalReplays[0],
+        { ...execution.approvalReplays[0] },
+      ],
+    };
+
+    for (const invalidExecution of [
+      duplicateCheckpointNamespace,
+      duplicateApprovalReplay,
+    ]) {
+      expect(
+        getSubagentResumeManifest(
+          attachSubagentResumeManifest(
+            { type: 'tool_approval' },
+            { version: 1, executions: [invalidExecution] }
+          )
+        )
+      ).toBeUndefined();
+    }
+  });
+
+  it('rejects cyclic descendant manifests', () => {
+    const cyclic: {
+      version: number;
+      executions: Array<typeof execution & { descendant?: object }>;
+    } = { version: 1, executions: [{ ...execution }] };
+    cyclic.executions[0].descendant = cyclic;
+
+    expect(
+      getSubagentResumeManifest({
+        __librechat_subagent_resume_manifest: cyclic,
+      })
+    ).toBeUndefined();
+  });
+});

package/src/tools/__tests__/ToolNode.breakerSignal.test.ts

@@ -1,15 +1,22 @@
 import { z } from 'zod';
 import { tool } from '@langchain/core/tools';
+import { GraphInterrupt } from '@langchain/langgraph';
 import { AIMessage, ToolMessage } from '@langchain/core/messages';
 import { describe, it, expect, jest, afterEach } from '@jest/globals';
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type {
+  ReplayableSubagentTool,
+  SettledSubagentToolOutput,
+} from '@/tools/subagent/SubagentReplay';
+import type { PreToolUseHookOutput } from '@/hooks';
 import type * as t from '@/types';
-import * as events from '@/utils/events';
 import {
   StreamLimitExceededError,
   RUN_BREAKER_SCOPE_CONFIG_KEY,
 } from '@/llm/streamLimits';
+import { SUBAGENT_REPLAY_CONTROLLER } from '@/tools/subagent/SubagentReplay';
+import * as events from '@/utils/events';
 import { GraphEvents } from '@/common';
 import { HookRegistry } from '@/hooks';
 import { ToolNode } from '../ToolNode';
@@ -212,6 +219,202 @@ describe('ToolNode breaker signal composition', () => {
     expect(sideEffectRan).toBe(false);
   });
 
+  it('prioritizes a sibling breaker trip over an approval interrupt', async () => {
+    const breaker = new AbortController();
+    const trip = new StreamLimitExceededError({
+      kind: 'tool_call_args',
+      limit: 10,
+      observed: 11,
+      toolName: 'db_query',
+    });
+    const approval = createSignalBlindTool('ask_question', async () => {
+      throw new GraphInterrupt([]);
+    });
+    const tripper = createSignalBlindTool('tripping_child', async () => {
+      breaker.abort(trip);
+      return 'tripped';
+    });
+    const node = new ToolNode({
+      tools: [approval, tripper],
+      interruptingToolNames: new Set(['ask_question', 'tripping_child']),
+      getBreakerSignal: () => breaker.signal,
+    });
+
+    await expect(
+      node.invoke({
+        messages: [
+          new AIMessage({
+            content: '',
+            tool_calls: [
+              { id: 'call_1', name: 'ask_question', args: {} },
+              { id: 'call_2', name: 'tripping_child', args: {} },
+            ],
+          }),
+        ],
+      })
+    ).rejects.toBe(trip);
+  });
+
+  it('reuses terminal interrupting sibling outputs across replay', async () => {
+    let terminalRuns = 0;
+    let terminalPreHooks = 0;
+    let approvalRuns = 0;
+    const completions: Array<{
+      result?: { tool_call?: { id?: string; args?: string } };
+    }> = [];
+    jest
+      .spyOn(events, 'safeDispatchCustomEvent')
+      .mockImplementation(async (event, data): Promise<boolean> => {
+        if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
+          completions.push(data as (typeof completions)[number]);
+        }
+        return true;
+      });
+    const hookRegistry = new HookRegistry();
+    hookRegistry.register('PreToolUse', {
+      hooks: [
+        async (input): Promise<PreToolUseHookOutput> => {
+          if (input.toolName !== 'terminal_child') {
+            return {};
+          }
+          terminalPreHooks += 1;
+          return {
+            additionalContext: 'cached terminal context',
+            updatedInput: { rewritten: true },
+          };
+        },
+      ],
+    });
+    const terminal = createSignalBlindTool('terminal_child', async () => {
+      terminalRuns += 1;
+      return 'completed';
+    });
+    const approval = createSignalBlindTool('approval_child', async () => {
+      approvalRuns += 1;
+      if (approvalRuns === 1) {
+        throw new GraphInterrupt([
+          { id: 'approval-interrupt', value: { type: 'approval' } },
+        ]);
+      }
+      return 'approved';
+    });
+    const node = new ToolNode({
+      tools: [terminal, approval],
+      interruptingToolNames: new Set(['terminal_child', 'approval_child']),
+      hookRegistry,
+      toolCallStepIds: new Map([
+        ['call_terminal', 'step_terminal'],
+        ['call_approval', 'step_approval'],
+      ]),
+    });
+    const input = {
+      messages: [
+        new AIMessage({
+          content: '',
+          tool_calls: [
+            { id: 'call_terminal', name: 'terminal_child', args: {} },
+            { id: 'call_approval', name: 'approval_child', args: {} },
+          ],
+        }),
+      ],
+    };
+
+    await expect(node.invoke(input)).rejects.toBeInstanceOf(GraphInterrupt);
+    const replayResult = await node.invoke(input);
+    expect(terminalRuns).toBe(1);
+    expect(terminalPreHooks).toBe(1);
+    expect(JSON.stringify(replayResult)).toContain('cached terminal context');
+    const terminalCompletion = completions.find(
+      (completion) => completion.result?.tool_call?.id === 'call_terminal'
+    );
+    expect(terminalCompletion?.result?.tool_call?.args).toContain(
+      '"rewritten":true'
+    );
+
+    await node.invoke({
+      messages: [
+        new AIMessage({
+          content: '',
+          tool_calls: [
+            {
+              id: 'call_terminal',
+              name: 'terminal_child',
+              args: { laterTurn: true },
+              type: 'tool_call',
+            },
+          ],
+        }),
+      ],
+    });
+    expect(terminalRuns).toBe(2);
+    expect(terminalPreHooks).toBe(2);
+  });
+
+  it('persists a hook-terminal outcome before a sibling interrupts', async () => {
+    const persistedOutputs: SettledSubagentToolOutput[] = [];
+    const terminal = createSignalBlindTool('terminal_child', async () => {
+      throw new Error('denied tool must not execute');
+    }) as StructuredToolInterface & ReplayableSubagentTool;
+    terminal[SUBAGENT_REPLAY_CONTROLLER] = {
+      getSettledOutput: async () => undefined,
+      persistSettledOutput: async (_call, _config, settled): Promise<void> => {
+        persistedOutputs.push(settled);
+      },
+    };
+    const approval = createSignalBlindTool('approval_child', async () => {
+      throw new GraphInterrupt([
+        { id: 'approval-interrupt', value: { type: 'approval' } },
+      ]);
+    });
+    const hookRegistry = new HookRegistry();
+    hookRegistry.register('PreToolUse', {
+      hooks: [
+        async (input): Promise<PreToolUseHookOutput> =>
+          input.toolName === 'terminal_child'
+            ? { decision: 'deny', reason: 'blocked by policy' }
+            : {},
+      ],
+    });
+    const node = new ToolNode({
+      tools: [terminal, approval],
+      hookRegistry,
+      interruptingToolNames: new Set(['terminal_child', 'approval_child']),
+    });
+
+    await expect(
+      node.invoke({
+        messages: [
+          new AIMessage({
+            content: '',
+            tool_calls: [
+              {
+                id: 'call_terminal',
+                name: 'terminal_child',
+                args: {},
+                type: 'tool_call',
+              },
+              {
+                id: 'call_approval',
+                name: 'approval_child',
+                args: {},
+                type: 'tool_call',
+              },
+            ],
+          }),
+        ],
+      })
+    ).rejects.toBeInstanceOf(GraphInterrupt);
+
+    expect(persistedOutputs).toHaveLength(1);
+    expect(persistedOutputs[0]).toMatchObject({
+      output: {
+        content: 'Blocked: blocked by policy',
+        status: 'error',
+        tool_call_id: 'call_terminal',
+      },
+    });
+  });
+
   it('stops event dispatch when a direct tool trips the breaker mid-batch', async () => {
     const breaker = new AbortController();
     const trip = new StreamLimitExceededError({
@@ -323,7 +526,10 @@ describe('ToolNode breaker signal composition', () => {
   });
 
   it('stamps the batch-entry run scope into tool configs and strips it from host batches', async () => {
-    const scope = Object.freeze({ epoch: 3, controller: new AbortController() });
+    const scope = Object.freeze({
+      epoch: 3,
+      controller: new AbortController(),
+    });
     let seenScope: unknown;
     const capture = {
       name: 'capture_scope',