@librechat/agents 3.7.20 → 3.7.22

package/src/tools/preparedSubagents.ts

@@ -0,0 +1,228 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import { stableStringify, normalizeError } from './eagerEventExecution';
+
+/** A model attempt cannot safely retry after delegated work has started. */
+export class PreparedSubagentError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'PreparedSubagentError';
+  }
+}
+
+type Outcome =
+  | { output: unknown; error?: never }
+  | { error: Error; output?: never };
+type Attempt = {
+  keys: Set<string>;
+  cancelled: boolean;
+  config: RunnableConfig;
+};
+
+const PREPARED_INVOCATION = Symbol('prepared-subagent-invocation');
+type PreparedCall = ToolCall & { [PREPARED_INVOCATION]?: symbol };
+
+type Reservation = {
+  token: symbol;
+  callId: string;
+  attempt: string;
+  fingerprint: string;
+  controller: AbortController;
+  outcome: Promise<Outcome>;
+  committed: boolean;
+};
+
+/**
+ * Owns speculative invocation work, never tool results or graph state. Only
+ * explicitly open model attempts admit work; closing an attempt fences late
+ * callbacks without retaining tombstones. Normal ToolNode execution adopts the
+ * raw output and performs its existing lifecycle/output processing once.
+ */
+export class PreparedSubagents {
+  private readonly attempts = new Map<string, Attempt>();
+  private readonly reservations = new Map<string, Reservation>();
+  private readonly running = new Set<AbortController>();
+  private epoch = 0;
+
+  begin(attempt: string, config: RunnableConfig = {}): void {
+    this.attempts.set(attempt, {
+      keys: new Set(),
+      cancelled: false,
+      config: {
+        ...config,
+        configurable: { ...config.configurable },
+        metadata: { ...config.metadata },
+      },
+    });
+  }
+
+  getConfig(attempt: string): RunnableConfig | undefined {
+    const entry = this.attempts.get(attempt);
+    return entry?.cancelled === false ? entry.config : undefined;
+  }
+
+  isOpen(attempt: string): boolean {
+    return this.attempts.get(attempt)?.cancelled === false;
+  }
+
+  start(
+    attempt: string,
+    owner: string,
+    call: ToolCall,
+    capacity: number,
+    invoke: (signal: AbortSignal) => Promise<unknown>
+  ): boolean {
+    const entries = this.attempts.get(attempt);
+    if (
+      entries == null ||
+      entries.cancelled ||
+      call.id == null ||
+      call.id === ''
+    ) {
+      return false;
+    }
+    const key = JSON.stringify([owner, call.id]);
+    const canonical = fingerprint(call);
+    const previous = this.reservations.get(key);
+    if (previous != null) {
+      if (previous.attempt !== attempt || previous.fingerprint !== canonical) {
+        throw new PreparedSubagentError(
+          'Conflicting eager subagent call identity.'
+        );
+      }
+      return false;
+    }
+    if (
+      !Number.isSafeInteger(capacity) ||
+      capacity <= 0 ||
+      this.reservations.size >= capacity ||
+      this.running.size >= capacity
+    ) {
+      return false;
+    }
+    const controller = new AbortController();
+    this.running.add(controller);
+    const reservation: Reservation = {
+      token: Symbol(),
+      attempt,
+      callId: call.id,
+      fingerprint: canonical,
+      controller,
+      committed: false,
+      outcome: Promise.resolve()
+        .then(() => {
+          controller.signal.throwIfAborted();
+          return invoke(controller.signal);
+        })
+        .then(
+          (output): Outcome => ({ output }),
+          (error): Outcome => ({ error: normalizeError(error) })
+        )
+        .finally(() => {
+          this.running.delete(controller);
+        }),
+    };
+    entries.keys.add(key);
+    this.reservations.set(key, reservation);
+    return true;
+  }
+
+  finish(attempt: string, calls?: ToolCall[], cause?: unknown): void {
+    const entries = this.attempts.get(attempt);
+    this.attempts.delete(attempt);
+    if (entries == null || entries.keys.size === 0) {
+      return;
+    }
+    const finalCalls = new Map(calls?.map((call) => [call.id, call]));
+    for (const key of entries.keys) {
+      const record = this.reservations.get(key);
+      const finalCall =
+        record == null ? undefined : finalCalls.get(record.callId);
+      if (
+        entries.cancelled ||
+        record == null ||
+        record.attempt !== attempt ||
+        finalCall == null ||
+        fingerprint(finalCall) !== record.fingerprint
+      ) {
+        const error = new PreparedSubagentError(
+          'The model attempt ended or changed after a subagent started; refusing automatic retry.',
+          { cause }
+        );
+        for (const pendingKey of entries.keys) {
+          const pending = this.reservations.get(pendingKey);
+          if (pending?.attempt === attempt) {
+            pending.controller.abort(error);
+            this.reservations.delete(pendingKey);
+          }
+        }
+        throw error;
+      }
+      record.committed = true;
+      (finalCall as PreparedCall)[PREPARED_INVOCATION] = record.token;
+    }
+  }
+
+  owns(owner: string, call: ToolCall): boolean {
+    const record = this.reservations.get(JSON.stringify([owner, call.id]));
+    return (
+      record != null &&
+      (call as PreparedCall)[PREPARED_INVOCATION] === record.token
+    );
+  }
+
+  take(owner: string, call: ToolCall): Promise<unknown> | undefined {
+    const key = JSON.stringify([owner, call.id]);
+    const record = this.reservations.get(key);
+    const token = (call as PreparedCall)[PREPARED_INVOCATION];
+    if (record == null && token == null) {
+      return undefined;
+    }
+    if (record == null || token !== record.token) {
+      return Promise.reject(
+        new PreparedSubagentError(
+          'Eager subagent invocation is no longer owned by this call.'
+        )
+      );
+    }
+    this.reservations.delete(key);
+    if (!record.committed || record.fingerprint !== fingerprint(call)) {
+      const error = new PreparedSubagentError(
+        'Subagent arguments changed after eager invocation.'
+      );
+      record.controller.abort(error);
+      return Promise.reject(error);
+    }
+    const epoch = this.epoch;
+    return record.outcome.then((result) => {
+      if (this.epoch !== epoch) {
+        throw new PreparedSubagentError(
+          'Eager subagent result belongs to a retired run.'
+        );
+      }
+      record.controller.signal.throwIfAborted();
+      if ('error' in result) {
+        throw result.error;
+      }
+      return result.output;
+    });
+  }
+
+  clear(): void {
+    this.epoch++;
+    const reason = new PreparedSubagentError(
+      'Eager subagent execution was cancelled.'
+    );
+    for (const controller of this.running) {
+      controller.abort(reason);
+    }
+    this.reservations.clear();
+    for (const attempt of this.attempts.values()) {
+      attempt.cancelled = true;
+    }
+  }
+}
+
+function fingerprint(call: ToolCall): string {
+  return stableStringify({ name: call.name, args: call.args });
+}

package/src/tools/search/rerankers.ts

@@ -21,6 +21,23 @@ const getDefaultCohereApiUrl = (): string =>
     ? process.env.COHERE_API_URL
     : DEFAULT_COHERE_API_URL;
 
+/**
+ * Ranking used whenever no reranker scores the chunks: the candidates' own
+ * order, capped at `topK`, with a neutral score.
+ *
+ * Exported because it is not only a *fallback*. With `rerankerType: 'none'`
+ * there is no reranker to fall back from, and the search pipeline needs the
+ * same ranking to hand the scraped text downstream — see `getHighlights` in
+ * `./search`.
+ */
+export const getDefaultRanking = (
+  documents: string[],
+  topK: number
+): t.Highlight[] =>
+  documents
+    .slice(0, Math.min(topK, documents.length))
+    .map((doc) => ({ text: doc, score: 0 }));
+
 export abstract class BaseReranker {
   protected apiKey: string | undefined;
   protected logger: t.Logger;
@@ -51,9 +68,7 @@ export abstract class BaseReranker {
     documents: string[],
     topK: number
   ): t.Highlight[] {
-    return documents
-      .slice(0, Math.min(topK, documents.length))
-      .map((doc) => ({ text: doc, score: 0 }));
+    return getDefaultRanking(documents, topK);
   }
 
   /** A direct caller has no enclosing search to fold into, so one

package/src/tools/search/search.ts

@@ -10,7 +10,7 @@ import { createKeenableAPI } from './keenable-search';
 import { createTavilyAPI } from './tavily-search';
 import { createSearchMetrics } from './metrics';
 import { createCrwAPI } from './crw-search';
-import { BaseReranker } from './rerankers';
+import { BaseReranker, getDefaultRanking } from './rerankers';
 
 /** Engines queried when `searxngSearchOptions.engines` is not configured. */
 const DEFAULT_SEARXNG_ENGINES = 'google,bing,duckduckgo';
@@ -144,9 +144,20 @@ function createSourceUpdateCallback(sourceMap: Map<string, t.ValidSource>) {
   };
 }
 
+/** Provider label for the metrics summary when reranking is switched off.
+ * `undefined` would be indistinguishable from a reranker that never ran. */
+const NO_RERANKER_PROVIDER = 'none';
+
 /** Returns undefined without logging when there is nothing to rank: an empty
- * scrape is already counted by the scrape summary, and a missing reranker is
- * reported once at tool construction rather than once per source. */
+ * scrape is already counted by the scrape summary.
+ *
+ * A *missing* reranker is not the same as nothing to rank. `rerankerType:
+ * 'none'` is a schema-valid opt-out, and `createReranker` returns `undefined`
+ * for it by design. Returning `undefined` here as well would leave the source
+ * without highlights, and `expandHighlights` then strips its content — the
+ * search would answer with links and no text at all. So the chunks are handed
+ * on in their original order via `getDefaultRanking`, exactly what every
+ * reranker's own failure path already does. */
 const getHighlights = async ({
   query,
   content,
@@ -164,7 +175,7 @@ const getHighlights = async ({
   maxContentLength?: number;
   chunkOptions?: { chunkSize: number; chunkOverlap: number };
 }): Promise<t.Highlight[] | undefined> => {
-  if (!content || !reranker) {
+  if (!content) {
     return;
   }
 
@@ -181,7 +192,7 @@ const getHighlights = async ({
     );
   } catch (error) {
     metrics.recordRerank({
-      provider: reranker.provider,
+      provider: reranker?.provider ?? NO_RERANKER_PROVIDER,
       chunks: 0,
       results: 0,
       durationMs: Date.now() - chunkStartedAt,
@@ -191,6 +202,20 @@ const getHighlights = async ({
     return;
   }
 
+  /** Reranking is switched off, so the chunks pass through unscored. Recorded
+   * like any other rerank so the search summary still accounts for the source;
+   * it carries no `reason`, because nothing failed. */
+  if (!reranker) {
+    const highlights = getDefaultRanking(documents, topResults);
+    metrics.recordRerank({
+      provider: NO_RERANKER_PROVIDER,
+      chunks: documents.length,
+      results: highlights.length,
+      durationMs: Date.now() - chunkStartedAt,
+    });
+    return highlights;
+  }
+
   const rerankStartedAt = Date.now();
   try {
     return await reranker.rerank(query, documents, topResults, metrics);

package/src/types/tools.ts

@@ -11,6 +11,7 @@ import type {
   ToolErrorData,
 } from './stream';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
+import type { PreparedSubagents } from '@/tools/preparedSubagents';
 import type { RunBreakerScope } from '@/llm/streamLimits';
 import type { HumanInTheLoopConfig } from './hitl';
 import type { LangfuseConfig } from './graph';
@@ -56,6 +57,13 @@ export type EagerEventToolExecutionConfig = {
    * execution with final args.
    */
   excludeToolNames?: string[];
+  /**
+   * Maximum retained early foreground subagent invocations per graph. Defaults
+   * to 4; 0 disables them. Checkpoints, parent tool hooks, background calls and
+   * control-flow graph tools retain normal batch execution. Once a child has
+   * started, a failed/revised model attempt fails instead of automatically retrying.
+   */
+  maxPendingSubagents?: number;
 };
 
 export type EagerEventToolExecutionOutcome =
@@ -290,6 +298,8 @@ export type ToolNodeOptions = {
    * controller.
    */
   getRunScope?: () => RunBreakerScope;
+  /** Internal graph-owned prepared invocation registry. */
+  preparedSubagents?: PreparedSubagents;
   /** SDK-owned checkpoint bridge for open run-step lifecycle state. */
   restoreRunStepResumeState?: (
     state?: RunStepResumeState,
@@ -1259,6 +1269,13 @@ export type ToolSearchArtifact = {
     total_searched: number;
     pattern: string;
     error?: string;
+    /** Servers that had tools to search, emitted when a server filter matched
+     * nothing so the caller can see what it could have asked for. */
+    available_mcp_servers?: string[];
+    /** Requested servers that matched no registered server. */
+    unmatched_mcp_servers?: string[];
+    /** Requested servers that exist but had no tools left to search. */
+    idle_mcp_servers?: string[];
   };
 };