@librechat/agents 3.7.8 → 3.7.10

package/src/tools/search/types.ts

@@ -344,7 +344,9 @@ export interface JinaRerankerResult {
 
 export interface JinaRerankerResponse {
   model: string;
-  usage: {
+  /** Telemetry only, and absent from some Jina-compatible endpoints — never
+   * dereference it on a path that would discard a usable ranking. */
+  usage?: {
     total_tokens: number;
   };
   results: JinaRerankerResult[];
@@ -358,12 +360,13 @@ export interface CohereRerankerResult {
 export interface CohereRerankerResponse {
   results: CohereRerankerResult[];
   id: string;
-  meta: {
-    api_version: {
+  /** Telemetry only; see {@link JinaRerankerResponse.usage}. */
+  meta?: {
+    api_version?: {
       version: string;
       is_experimental: boolean;
     };
-    billed_units: {
+    billed_units?: {
       search_units: number;
     };
   };
@@ -407,6 +410,96 @@ export interface RagApiRerankResponse {
 export type SafeSearchLevel = 0 | 1 | 2;
 
 export type Logger = WinstonLogger;
+
+/** Compact, redacted view of a thrown error, safe to hand to a logger. */
+export interface SafeErrorLog {
+  message: string;
+  name?: string;
+  code?: string;
+  status?: number;
+  method?: string;
+  url?: string;
+  responseDataSummary?: string;
+  value?: string;
+}
+
+/** Why a rerank returned the candidates' original order instead of a ranking. */
+export type RerankFallback =
+  | 'no_api_key'
+  | 'no_base_url'
+  | 'no_token_supplier'
+  | 'bad_response'
+  | 'invalid_results'
+  | 'chunk_error'
+  | 'placeholder'
+  | 'error';
+
+/** One provider query. `results` is the row count that query contributed. */
+export interface SearchObservation {
+  provider: string;
+  type: string;
+  results: number;
+  durationMs: number;
+  error?: string;
+  /** The query rejected rather than reporting failure in its response. Those
+   * were logged at error level before they were aggregated, so the summary
+   * has to carry the distinction to keep that severity. */
+  thrown?: boolean;
+}
+
+/** One scraped link. A failure carries `error`; a success carries the sizes
+ * the scrape produced, so the summary can report both without a second pass. */
+export interface ScrapeObservation {
+  url: string;
+  chars?: number;
+  highlights?: number;
+  error?: string;
+}
+
+/** One reranker round trip. A search reranks once per scraped source, so
+ * these fold into a single summary rather than logging per source. */
+export interface RerankObservation {
+  provider: string;
+  chunks: number;
+  results: number;
+  durationMs: number;
+  model?: string;
+  /** Provider-reported usage: Jina tokens, Cohere billed search units. */
+  units?: number;
+  /** Chunks a provider candidate cap dropped before submission. */
+  dropped?: number;
+  /** Set only when a provider cap reduced the requested result count, so a
+   * search returning fewer highlights than configured says why. */
+  topK?: number;
+  topKLimit?: number;
+  reason?: RerankFallback;
+  error?: SafeErrorLog;
+}
+
+/** Per-rerank state threaded from the start of a call to whichever exit it
+ * takes, so every path records exactly one observation. */
+export interface RerankRun {
+  metrics: SearchMetrics;
+  documents: string[];
+  topK: number;
+  startedAt: number;
+  model?: string;
+  units?: number;
+  dropped?: number;
+  topKLimit?: number;
+}
+
+/**
+ * Fold-as-you-go counters for one `web_search` call. Recording is O(1) and
+ * allocation-free past a bounded reason map; {@link SearchMetrics.flush}
+ * emits at most one line per phase that actually ran.
+ */
+export interface SearchMetrics {
+  recordSearch(observation: SearchObservation): void;
+  recordScrape(observation: ScrapeObservation): void;
+  recordRerank(observation: RerankObservation): void;
+  flush(): void;
+}
 export interface SearchToolConfig
   extends SearchConfig,
     ProcessSourcesConfig,
@@ -702,6 +795,10 @@ export interface FirecrawlScraperConfig extends BaseSearchProviderConfig {
   changeTrackingOptions?: object;
 }
 
+/** Result kind a parallel sub-search covers; `web` is the untyped main
+ * search, which every provider serves without a `type` parameter. */
+export type SubSearchType = 'web' | 'images' | 'videos' | 'news';
+
 export type GetSourcesParams = {
   query: string;
   date?: DATE_RANGE;
@@ -1038,6 +1135,9 @@ export type ProcessSourcesFields = {
   news: boolean;
   proMode: boolean;
   onGetHighlights: SearchToolConfig['onGetHighlights'];
+  /** Collector owned by the caller; when omitted, one is created and flushed
+   * for this call so a direct `processSources` still summarizes itself. */
+  metrics?: SearchMetrics;
 };
 
 export interface SearchToolSchema {

package/src/tools/search/utils.ts

@@ -2,21 +2,13 @@
 
 import { isAxiosError } from 'axios';
 
+import type { SafeErrorLog } from './types';
 import type { AxiosError } from 'axios';
 import type * as t from './types';
 
 const LOG_VALUE_MAX_LENGTH = 2048;
 
-export interface SafeErrorLog {
-  message: string;
-  name?: string;
-  code?: string;
-  status?: number;
-  method?: string;
-  url?: string;
-  responseDataSummary?: string;
-  value?: string;
-}
+export type { SafeErrorLog } from './types';
 
 /**
  * Singleton instance of the default logger

package/src/tools/subagent/SubagentExecutor.ts

@@ -131,6 +131,7 @@ import { stripRunStepResumeState } from '@/tools/runStepResume';
 import { seedAgentInitialSessions } from '@/utils/toolSessions';
 import { stableStringify } from '@/tools/eagerEventExecution';
 import { convertInjectedMessages } from '@/messages/injected';
+import { resolveClientOptionsModel } from '@/llm/request';
 import { composeAbortSignals } from '@/utils/misc';
 import { HandlerRegistry } from '@/events';
 
@@ -1091,8 +1092,7 @@ export class SubagentExecutor {
       return JSON.stringify({
         status: 'rejected',
         tool: Constants.SUBAGENT,
-        message:
-          'Child-thread continuation is not enabled by this host.',
+        message: 'Child-thread continuation is not enabled by this host.',
       });
     }
     const detachedHandlers = new HandlerRegistry();
@@ -2261,9 +2261,7 @@ export class SubagentExecutor {
     }
     if (this.maxDepth <= 0) {
       return Promise.resolve(
-        createSubagentFailure(
-          'Error: Maximum subagent nesting depth exceeded.'
-        )
+        createSubagentFailure('Error: Maximum subagent nesting depth exceeded.')
       );
     }
     if (
@@ -3300,7 +3298,7 @@ function createUsageCaptureHandler(args: {
         defaultMember?.[1];
       const model =
         callInfo?.model ??
-        (memberInput == null ? undefined : extractConfiguredModel(memberInput));
+        resolveClientOptionsModel(memberInput?.clientOptions);
       const callProvider = callInfo?.provider ?? memberInput?.provider;
       for (const generationGroup of output.generations) {
         /**
@@ -3423,27 +3421,6 @@ function getGraphEventMemberAgentId({
     : undefined;
 }
 
-/**
- * Best-effort read of the configured model from a subagent's client
- * options. Providers disagree on the key (`model` vs `modelName`), and the
- * value is only a fallback for calls that carry no `ls_model_name`.
- */
-function extractConfiguredModel(agentInputs: AgentInputs): string | undefined {
-  const clientOptions = agentInputs.clientOptions as
-    | { model?: unknown; modelName?: unknown }
-    | undefined;
-  if (typeof clientOptions?.model === 'string' && clientOptions.model !== '') {
-    return clientOptions.model;
-  }
-  if (
-    typeof clientOptions?.modelName === 'string' &&
-    clientOptions.modelName !== ''
-  ) {
-    return clientOptions.modelName;
-  }
-  return undefined;
-}
-
 function sanitizeResolverConfigurable(
   parentConfigurable: Record<string, unknown>
 ): SubagentResolveConfigurable | undefined {

package/src/types/run.ts

@@ -252,6 +252,14 @@ export type RunConfig = {
    * block to prevent leaks.
    */
   hooks?: HookRegistry;
+  /**
+   * Maximum number of times a `Stop` hook may keep this Run warm by returning
+   * `decision: 'block'` with messages to inject. Defaults to
+   * `DEFAULT_MAX_STOP_CONTINUATIONS`; non-finite values use the default and
+   * values at or below zero disable terminal continuation while preserving the
+   * final Stop notification.
+   */
+  maxStopContinuations?: number;
   /**
    * Opt-in cooperative preemption for this run. Requires a `hooks` registry
    * with a `PreemptBoundary` matcher — the seal only stops the stream, the

package/src/types/stream.ts

@@ -116,6 +116,12 @@ export interface RunStepResumeState {
   version: 1;
   revision: number;
   nextIndex: number;
+  /** Warm terminal continuations already admitted for this execution. */
+  stopContinuationCount?: number;
+  /** Identifies the fresh execution that owns this continuation lifecycle. */
+  stopContinuationExecutionId?: string;
+  /** Distinguishes LangGraph event keys when a warm continuation restarts steps. */
+  streamSegment?: number;
   toolCallSteps: Array<{ toolCallId: string; stepId: string }>;
   steps: RunStepResumeEntry[];
 }

package/src/types/summarize.ts

@@ -82,6 +82,13 @@ export type CompactionSemanticIndexEntry =
 
 export type CompactionSemanticIndex = readonly CompactionSemanticIndexEntry[];
 
+/** Serializable continuation state for a bounded compaction semantic index. */
+export type CompactionSemanticIndexSnapshot = {
+  entries: CompactionSemanticIndex;
+  /** Cumulative entries supplied before validation and bounded retention. */
+  providedEntryCount: number;
+};
+
 export type SummarizationConfig = {
   provider?: ProviderName;
   model?: string;

package/src/utils/tokens.ts

@@ -6,8 +6,8 @@ import {
   isAtomicToolContentBlock,
   serializeStructuredValueBounded,
 } from './toolContent';
-import { ContentTypes } from '@/common/enum';
 import { markTokenCounterCacheCompatible } from '@/llm/tokenCounterCacheCompatibility';
+import { ContentTypes } from '@/common/enum';
 
 export type EncodingName = 'o200k_base' | 'claude';
 
@@ -1257,6 +1257,25 @@ export function apportionTokenCounts(
  */
 const CLAUDE_TOKEN_CORRECTION = 1.1;
 
+const tokenCounterEncodings = new WeakMap<
+  (message: BaseMessage) => number,
+  EncodingName
+>();
+
+/**
+ * Encoding a counter measures in, for counters built here.
+ *
+ * `undefined` for a counter the host supplied itself: unknown, not wrong. A
+ * caller that needs a count in a specific encoding can therefore tell "counts
+ * in the encoding I need" from "counts in a different one" without treating
+ * every foreign counter as suspect.
+ */
+export function encodingOfTokenCounter(
+  tokenCounter: (message: BaseMessage) => number
+): EncodingName | undefined {
+  return tokenCounterEncodings.get(tokenCounter);
+}
+
 /**
  * Creates a token counter function using the specified encoding.
  * Lazily loads the encoding data on first use via dynamic import.
@@ -1267,13 +1286,17 @@ export const createTokenCounter = async (
   const tok = await getTokenizer(encoding);
   const countTokens = (text: string): number => tok.count(text);
   const isClaude = encoding === 'claude';
-  return markTokenCounterCacheCompatible((message: BaseMessage): number => {
-    const count = getTokenCountForMessage(message, countTokens, encoding);
-    const correctedCount = isClaude
-      ? Math.ceil(count * CLAUDE_TOKEN_CORRECTION)
-      : count;
-    return ensureSafeTokenMeasurement(correctedCount, 'message');
-  });
+  const counter = markTokenCounterCacheCompatible(
+    (message: BaseMessage): number => {
+      const count = getTokenCountForMessage(message, countTokens, encoding);
+      const correctedCount = isClaude
+        ? Math.ceil(count * CLAUDE_TOKEN_CORRECTION)
+        : count;
+      return ensureSafeTokenMeasurement(correctedCount, 'message');
+    }
+  );
+  tokenCounterEncodings.set(counter, encoding);
+  return counter;
 };
 
 /** Utility to manage the token encoder lifecycle explicitly. */