@librechat/agents 3.8.1 → 3.8.3

package/src/tools/subagent/SubagentExecutor.ts

@@ -88,6 +88,11 @@ import type {
   ToolApprovalReplaySnapshot,
 } from '@/hooks';
 import type { GraphFactory } from '@/graphs/graphFactory';
+import {
+  rebindToolBatchReplayScope,
+  rebindToolBatchReplayPayload,
+  restoreToolReplayConfig,
+} from '@/tools/toolBatchReplay';
 import type { StandardGraph } from '@/graphs/Graph';
 import {
   getSubagentApprovalExecutionScope,
@@ -1448,7 +1453,8 @@ export class SubagentExecutor {
       await this.prepareCheckpointFork(
         resumeExecution.checkpoints,
         branchChildThreadId,
-        lease
+        lease,
+        { source: resumeExecution.approvalExecutionScope, target: approvalExecutionScope }
       );
       let previousApprovals: ToolApprovalReplaySnapshot[] = [];
       let approvalsMutated = false;
@@ -1589,7 +1595,8 @@ export class SubagentExecutor {
   private async prepareCheckpointFork(
     sources: ReadonlyArray<SubagentCheckpointReference>,
     targetThreadId: string,
-    lease: SubagentExecutionPreparationLease
+    lease: SubagentExecutionPreparationLease,
+    approvalScope?: { source: string; target: string }
   ): Promise<void> {
     const checkpointer = this.checkpointer;
     try {
@@ -1608,7 +1615,7 @@ export class SubagentExecutor {
           checkpointer.deleteThread(targetThreadId)
         );
       }
-      await this.forkCheckpointSnapshot(sources, targetThreadId);
+      await this.forkCheckpointSnapshot(sources, targetThreadId, approvalScope);
       lease.assertOwned();
     } catch (error) {
       return lease.rollback(error);
@@ -1663,7 +1670,8 @@ export class SubagentExecutor {
   /** Copies exact checkpoint lineages, including pending task writes. */
   private async forkCheckpointSnapshot(
     sources: ReadonlyArray<SubagentCheckpointReference>,
-    targetThreadId: string
+    targetThreadId: string,
+    approvalScope?: { source: string; target: string }
   ): Promise<void> {
     if (
       this.checkpointer == null ||
@@ -1755,7 +1763,15 @@ export class SubagentExecutor {
             writes = [];
             writesByTask.set(taskId, writes);
           }
-          writes.push([channel, value]);
+          /** Repeated unconsumed forks must persist their current owner. */
+          const reboundValue =
+            channel === INTERRUPT && approvalScope != null &&
+            value != null && typeof value === 'object' && 'value' in value
+              ? { ...value, value: rebindToolBatchReplayPayload(
+                value.value, approvalScope.source, approvalScope.target
+              ) }
+              : value;
+          writes.push([channel, reboundValue]);
         }
         for (const [taskId, writes] of writesByTask) {
           await this.checkpointer.putWrites(storedConfig, writes, taskId);
@@ -2647,7 +2663,11 @@ export class SubagentExecutor {
         }
         const persistedInterrupts = getPersistedInterrupts(persistedState);
         if (persistedInterrupts.length > 0) {
-          activeChildRun.pendingInterrupts = persistedInterrupts;
+          activeChildRun.pendingInterrupts = resumeExecution == null ? persistedInterrupts :
+            persistedInterrupts.map((pending) => ({
+              ...pending,
+              value: rebindToolBatchReplayPayload(pending.value, resumeExecution.approvalExecutionScope, approvalExecutionScope),
+            }));
           execution.markStarted();
           childAlreadyStarted = true;
         } else if (persistedState.next.length > 0) {
@@ -2682,6 +2702,15 @@ export class SubagentExecutor {
         }
         let childInput: BaseGraphState | Command | null;
         if (childResumeMap != null) {
+          const pending = activeChildRun.pendingInterrupts.find((entry) =>
+            entry.id != null && Object.prototype.hasOwnProperty.call(childResumeMap, entry.id)
+          ) ?? activeChildRun.pendingInterrupts[0];
+          restoreToolReplayConfig(childConfigurable, pending.id, pending.value);
+          rebindToolBatchReplayScope(
+            childConfigurable,
+            resumeExecution?.approvalExecutionScope ?? approvalExecutionScope,
+            approvalExecutionScope
+          );
           childInput = new Command({ resume: childResumeMap });
         } else if (recoveredInProgress) {
           childInput = null;

package/src/tools/subagent/SubagentReplay.ts

@@ -201,7 +201,7 @@ function isDirectPathTurnReference(
   return isString(entry.toolCallId) && isNonnegativeInteger(entry.turn);
 }
 
-function isToolNodeResumeState(
+export function isToolNodeResumeState(
   value: unknown
 ): value is SubagentToolNodeResumeState {
   if (value == null || typeof value !== 'object') {
@@ -266,7 +266,7 @@ function isToolOutputReferenceEntry(
   return isString(entry.key) && typeof entry.value === 'string';
 }
 
-function isToolOutputReferenceState(
+export function isToolOutputReferenceState(
   value: unknown
 ): value is ToolOutputReferenceState {
   if (value == null || typeof value !== 'object') {

package/src/tools/toolBatchReplay.ts

@@ -0,0 +1,423 @@
+import { Command, MemorySaver, isCommand } from '@langchain/langgraph';
+import { isBaseMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { SubagentToolNodeResumeState } from '@/tools/subagent/SubagentReplay';
+import type { ToolOutputReferenceState } from '@/tools/toolOutputReferences';
+import {
+  isToolNodeResumeState,
+  isToolOutputReferenceState,
+  stripSubagentResumeManifest,
+  requireValidSubagentResumeManifest,
+} from '@/tools/subagent/SubagentReplay';
+import { isToolApprovalInterrupt } from '@/types/hitl';
+import { TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY } from '@/hooks/types';
+import {
+  TOOL_APPROVAL_REVIEW_CONFIG_KEY,
+  getToolApprovalReviewEvidence,
+  createToolApprovalReviewEvidence,
+} from '@/hitl/approvalReview';
+import {
+  attachRunStepResumeState,
+  getRunStepResumeState,
+  stripRunStepResumeState,
+} from '@/tools/runStepResume';
+
+export const TOOL_BATCH_REPLAY_KEY = '__librechat_tool_batch_replay';
+const TOOL_BATCH_PAYLOAD_KEY = '__librechat_tool_batch_payload';
+const TOOL_BATCH_WRAPPER_KEY = '__librechat_tool_batch_wrapper';
+
+export interface SettledToolBatchResult {
+  proposal: { name: string; args: Record<string, unknown> };
+  output: BaseMessage | Command;
+  additionalContexts: string[];
+  resolvedArgs?: Record<string, unknown>;
+  completionHandled?: boolean;
+  referenceContent?: string;
+  turn?: number;
+}
+
+export interface ToolBatchReplayRecord {
+  owner: string;
+  batch: string;
+  encoding: string;
+  data: string;
+  turnState?: SubagentToolNodeResumeState;
+  referenceState?: ToolOutputReferenceState;
+}
+
+interface ToolBatchReplayState {
+  version: 1;
+  approvalOwner?: string;
+  /** Populated from the pending interrupt by Run, including question pauses. */
+  interruptId?: string;
+  records: ToolBatchReplayRecord[];
+  wrappedPayload?: boolean;
+}
+
+/** Use the same message/Command codec as LangGraph checkpoints. */
+const serializer = new MemorySaver().serde;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** The only host-to-runtime entry point for checkpoint-owned tool replay state. */
+export function restoreToolReplayConfig(
+  configurable: Record<string, unknown>,
+  interruptId: string | undefined,
+  payload: unknown
+): void {
+  delete configurable[TOOL_BATCH_REPLAY_KEY];
+  delete configurable[TOOL_APPROVAL_REVIEW_CONFIG_KEY];
+  const state = getToolBatchReplayState(payload);
+  const publicPayload = getPublicToolInterruptPayload(payload);
+  const review = createToolApprovalReviewEvidence(
+    interruptId,
+    publicPayload,
+    state?.approvalOwner
+  );
+  if (isToolApprovalInterrupt(publicPayload) &&
+    (review == null || (state != null && state.approvalOwner == null))) {
+    throw new Error('Invalid tool approval checkpoint');
+  }
+  if (state != null) {
+    configurable[TOOL_BATCH_REPLAY_KEY] = { ...state, interruptId };
+  }
+  if (review != null) {
+    configurable[TOOL_APPROVAL_REVIEW_CONFIG_KEY] = review;
+  }
+}
+
+/**
+ * Resume maps identify the checkpointed interrupt, while the task scratchpad
+ * identifies the node that can consume it. Config survives into later graph
+ * steps, so the presence of replay evidence alone does not imply a resume.
+ * A parent replaying a checkpointed child has no local resume value.
+ */
+export function isToolReplayResume(
+  config: RunnableConfig,
+  interruptId: string | undefined,
+  isChildReplay: boolean
+): boolean {
+  const resumeMap: object | undefined = config.configurable?.__pregel_resume_map;
+  if (interruptId != null && resumeMap != null &&
+    !Object.prototype.hasOwnProperty.call(resumeMap, interruptId)) {
+    return false;
+  }
+  if (isChildReplay && resumeMap != null) {
+    return true;
+  }
+  const scratchpad: { resume?: { length: number }; nullResume?: unknown } | undefined =
+    config.configurable?.__pregel_scratchpad;
+  return scratchpad == null ||
+    (scratchpad.resume?.length ?? 0) > 0 || scratchpad.nullResume !== undefined;
+}
+
+export function getToolBatchReplayOwner(
+  config: RunnableConfig,
+  agentId: string
+): string {
+  return JSON.stringify([
+    getToolBatchReplayScope(config),
+    config.configurable?.[TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY] == null
+      ? (config.configurable?.checkpoint_ns ?? '')
+      : '',
+    agentId,
+  ]);
+}
+
+export function getToolBatchReplayScope(
+  config: RunnableConfig
+): string | undefined {
+  const scope =
+    config.configurable?.[TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY] ??
+    config.configurable?.thread_id;
+  return typeof scope === 'string' && scope.length > 0 ? scope : undefined;
+}
+
+/** Foreign replay evidence may only transit a checkpoint-proven child path. */
+export function isChildToolReplayOwner(
+  config: RunnableConfig,
+  owner: string,
+  trustedParentCallIds: ReadonlySet<string>
+): boolean {
+  const manifest = requireValidSubagentResumeManifest(config.configurable);
+  if (manifest == null || trustedParentCallIds.size === 0) return false;
+  const identity: unknown = JSON.parse(owner);
+  if (!Array.isArray(identity) || identity.length !== 3 || identity[1] !== '') return false;
+  const pending = manifest.executions.filter((execution) => trustedParentCallIds.has(execution.parentToolCallId));
+  while (pending.length > 0) {
+    const execution = pending.pop()!;
+    if (execution.approvalExecutionScope === identity[0]) return true;
+    pending.push(...(execution.descendant?.executions ?? []));
+  }
+  return false;
+}
+
+/** Rebind only the checkpoint-proven source execution when a child fork is created. */
+export function rebindToolBatchReplayScope(
+  configurable: Record<string, unknown>,
+  sourceScope: string,
+  destinationScope: string
+): void {
+  const rebind = (key: string): string => {
+    const parts: unknown = JSON.parse(key);
+    if (!Array.isArray(parts) || parts[0] !== sourceScope) {
+      return key;
+    }
+    return JSON.stringify([destinationScope, ...parts.slice(1)]);
+  };
+  const config = { configurable };
+  const review = getToolApprovalReviewEvidence(config);
+  if (review?.owner != null) {
+    configurable[TOOL_APPROVAL_REVIEW_CONFIG_KEY] = {
+      ...review,
+      owner: rebind(review.owner),
+    };
+  }
+  const state = getToolBatchReplayState(configurable);
+  if (state != null) {
+    configurable[TOOL_BATCH_REPLAY_KEY] = {
+      ...state,
+      approvalOwner:
+        state.approvalOwner == null ? undefined : rebind(state.approvalOwner),
+      records: state.records.map((record) => ({
+        ...record,
+        owner: rebind(record.owner),
+        batch: rebind(record.batch),
+      })),
+    };
+  }
+}
+
+/** A fork may be paused again before it consumes its pending interrupt. */
+export function rebindToolBatchReplayPayload(
+  payload: unknown,
+  sourceScope: string,
+  destinationScope: string
+): unknown {
+  const state = getToolBatchReplayState(payload);
+  const value = stripRunStepResumeState(payload);
+  if (state == null || !isRecord(value)) {
+    return payload;
+  }
+  const configurable = { [TOOL_BATCH_REPLAY_KEY]: state };
+  rebindToolBatchReplayScope(configurable, sourceScope, destinationScope);
+  const rebound = {
+    ...value,
+    [TOOL_BATCH_REPLAY_KEY]: configurable[TOOL_BATCH_REPLAY_KEY],
+  };
+  const runStepState = getRunStepResumeState(payload);
+  return runStepState == null
+    ? rebound
+    : attachRunStepResumeState(rebound, runStepState);
+}
+
+export function getToolBatchReplayState(
+  payload: unknown
+): ToolBatchReplayState | undefined {
+  const value = stripRunStepResumeState(payload);
+  if (
+    value == null ||
+    typeof value !== 'object' ||
+    !(TOOL_BATCH_REPLAY_KEY in value)
+  ) {
+    return undefined;
+  }
+  const candidate: unknown = value[TOOL_BATCH_REPLAY_KEY];
+  if (candidate === undefined) {
+    return undefined;
+  }
+  const state = candidate as Partial<ToolBatchReplayState> | null;
+  if (
+    state?.version !== 1 ||
+    (state.wrappedPayload != null &&
+      typeof state.wrappedPayload !== 'boolean') ||
+    (state.approvalOwner != null && typeof state.approvalOwner !== 'string') ||
+    (state.interruptId != null && typeof state.interruptId !== 'string') ||
+    !Array.isArray(state.records) ||
+    state.records.some((value: unknown) => {
+      if (value == null || typeof value !== 'object') {
+        return true;
+      }
+      const record = value as Partial<ToolBatchReplayRecord>;
+      return (
+        typeof record.owner !== 'string' ||
+        typeof record.batch !== 'string' ||
+        typeof record.encoding !== 'string' ||
+        typeof record.data !== 'string' ||
+        (record.turnState != null &&
+          !isToolNodeResumeState(record.turnState)) ||
+        (record.referenceState != null &&
+          !isToolOutputReferenceState(record.referenceState))
+      );
+    })
+  ) {
+    throw new Error('Invalid tool batch replay checkpoint');
+  }
+  return structuredClone(state as ToolBatchReplayState);
+}
+
+export function stripToolBatchReplayState(payload: unknown): unknown {
+  if (
+    payload == null ||
+    typeof payload !== 'object' ||
+    !(TOOL_BATCH_REPLAY_KEY in payload)
+  ) {
+    return payload;
+  }
+  const state = getToolBatchReplayState(payload);
+  const { [TOOL_BATCH_REPLAY_KEY]: _state, ...publicPayload } = payload;
+  if (
+    state?.wrappedPayload === true &&
+    TOOL_BATCH_PAYLOAD_KEY in publicPayload
+  ) {
+    return publicPayload[TOOL_BATCH_PAYLOAD_KEY];
+  }
+  return publicPayload;
+}
+
+/** Decode outer execution metadata before shape-sensitive child wrappers. */
+export function getPublicToolInterruptPayload(payload: unknown): unknown {
+  return stripSubagentResumeManifest(
+    stripToolBatchReplayState(stripRunStepResumeState(payload))
+  );
+}
+
+export async function attachToolBatchReplayState(
+  payload: unknown,
+  owner: string,
+  batches: ReadonlyMap<string, ReadonlyMap<string, object>>,
+  turnState?: SubagentToolNodeResumeState,
+  referenceState?: ToolOutputReferenceState
+): Promise<unknown> {
+  const publicPayload = stripRunStepResumeState(payload);
+  const previous = getToolBatchReplayState(publicPayload);
+  const records =
+    previous?.records.filter((record) => record.owner !== owner) ?? [];
+  for (const [batch, results] of batches) {
+    const [encoding, bytes] = await serializer.dumpsTyped([...results]);
+    records.push({
+      owner,
+      batch,
+      encoding,
+      data: Buffer.from(bytes).toString('base64'),
+      ...(turnState == null ? {} : { turnState }),
+      ...(referenceState == null ? {} : { referenceState }),
+    });
+  }
+  const approvalOwner =
+    previous?.approvalOwner ??
+    (isToolApprovalInterrupt(publicPayload) ? owner : undefined);
+  if (records.length === 0 && approvalOwner == null) {
+    return payload;
+  }
+  const result = {
+    ...(isRecord(publicPayload)
+      ? publicPayload
+      : {
+        [TOOL_BATCH_WRAPPER_KEY]: 1,
+        [TOOL_BATCH_PAYLOAD_KEY]: publicPayload,
+      }),
+    [TOOL_BATCH_REPLAY_KEY]: {
+      version: 1,
+      approvalOwner,
+      records,
+      wrappedPayload: previous?.wrappedPayload ?? !isRecord(publicPayload),
+    } satisfies ToolBatchReplayState,
+  };
+  const runStepState = getRunStepResumeState(payload);
+  return runStepState == null
+    ? result
+    : attachRunStepResumeState(result, runStepState);
+}
+
+export async function restoreToolBatchReplayState(
+  config: RunnableConfig,
+  owner: string
+): Promise<
+  Array<{
+    batch: string;
+    results: Array<[string, SettledToolBatchResult]>;
+    turnState?: SubagentToolNodeResumeState;
+    referenceState?: ToolOutputReferenceState;
+  }>
+> {
+  const state = getToolBatchReplayState(config.configurable);
+  if (state == null) {
+    return [];
+  }
+  return Promise.all(
+    state.records
+      .filter((record) => record.owner === owner)
+      .map(async (record) => {
+        const values: unknown = await serializer.loadsTyped(
+          record.encoding,
+          Buffer.from(record.data, 'base64')
+        );
+        if (!Array.isArray(values)) {
+          throw new Error('Invalid settled tool batch results');
+        }
+        const seen = new Set<string>();
+        const results = values.map(
+          (entry: unknown): [string, SettledToolBatchResult] => {
+            if (
+              !Array.isArray(entry) ||
+              entry.length !== 2 ||
+              typeof entry[0] !== 'string' ||
+              seen.has(entry[0])
+            ) {
+              throw new Error('Invalid settled tool batch results');
+            }
+            const result = entry[1] as Partial<SettledToolBatchResult> | null;
+            if (
+              result == null ||
+              (!isBaseMessage(result.output) && !isCommand(result.output)) ||
+              !Array.isArray(result.additionalContexts) ||
+              result.additionalContexts.some(
+                (context) => typeof context !== 'string'
+              ) ||
+              (result.completionHandled != null &&
+                typeof result.completionHandled !== 'boolean') ||
+              (result.referenceContent != null &&
+                typeof result.referenceContent !== 'string') ||
+              (result.turn != null &&
+                (!Number.isSafeInteger(result.turn) || result.turn < 0)) ||
+              !isRecord(result.proposal) ||
+              typeof result.proposal.name !== 'string' ||
+              result.proposal.name.length === 0 ||
+              !isRecord(result.proposal.args) ||
+              (result.resolvedArgs != null && !isRecord(result.resolvedArgs))
+            ) {
+              throw new Error('Invalid settled tool batch results');
+            }
+            seen.add(entry[0]);
+            const output = isCommand(result.output)
+              ? new Command({
+                update: result.output.update,
+                goto: result.output.goto,
+                graph: result.output.graph,
+                resume: result.output.resume,
+              })
+              : result.output;
+            return [
+              entry[0],
+              {
+                ...result,
+                proposal: result.proposal,
+                output,
+                additionalContexts: result.additionalContexts,
+              },
+            ];
+          }
+        );
+        return {
+          batch: record.batch,
+          results,
+          turnState: record.turnState,
+          referenceState: record.referenceState,
+        };
+      })
+  );
+}

package/src/tools/toolOutputReferences.ts

@@ -420,6 +420,22 @@ export class ToolOutputReferenceRegistry {
     };
   }
 
+  /** Restore batch inputs without rolling back graph-owned concurrent outputs. */
+  resumeBatch(runId: string, state: ToolOutputReferenceState): ToolOutputResolveView {
+    if (!this.runStates.has(runId)) {
+      this.restoreState(runId, state);
+    }
+    const bucket = this.getOrCreate(runId);
+    bucket.turnCounter = Math.max(bucket.turnCounter, state.turnCounter + 1);
+    const inputs = new ToolOutputReferenceRegistry({
+      maxOutputSize: this.maxOutputSize,
+      maxTotalSize: this.maxTotalSize,
+      maxActiveRuns: 1,
+    });
+    inputs.restoreState(runId, state);
+    return inputs.snapshot(runId);
+  }
+
   /** Restores a checkpointed run bucket under the current resume scope. */
   restoreState(
     runId: string | undefined,