@librechat/agents 3.7.22 → 3.8.1

package/dist/types/messages/toolHistoryProjection.d.ts

@@ -0,0 +1,65 @@
+import type { BaseMessage, ContentBlock } from '@langchain/core/messages';
+interface ToolHistoryCallMirror {
+    readonly name?: string;
+    readonly arguments: string;
+}
+export type ToolHistoryCallMirrors = Map<string, ToolHistoryCallMirror | null>;
+/** Only complete argument representations can establish that a call is a mirror. */
+export declare function recordToolHistoryCallMirror(mirrors: ToolHistoryCallMirrors, block: unknown): void;
+export declare function isToolHistoryCallMirror(mirrors: ToolHistoryCallMirrors | undefined, id: unknown, name: unknown, args: unknown): boolean;
+export declare const OPENAI_RESPONSES_REPLAY_POSITIONS_KEY = "__openai_responses_replay_positions__";
+export type ResponsesReplayPosition = {
+    contentIndex?: number;
+    itemId: string;
+    kind: 'message' | 'output' | 'reasoning' | 'text';
+    outputIndex: number;
+};
+export declare function isResponsesReplayPosition(value: unknown): value is ResponsesReplayPosition;
+/** Provider evidence is selected once; a sidecar never replaces message content. */
+export interface ResponsesHistorySource {
+    readonly coverage: 'complete-output' | 'tool-sidecar';
+    readonly items: unknown[];
+    readonly message?: BaseMessage;
+}
+export interface OrderedToolHistoryProjection {
+    readonly source: ResponsesHistorySource;
+    readonly contributions: readonly ResponsesHistoryContribution[];
+    readonly hasToolContent: boolean;
+    readonly truncated: boolean;
+}
+export interface ToolHistoryPreparation {
+    get(message: BaseMessage): OrderedToolHistoryProjection | undefined;
+}
+/** A preparation owns this cache; changed messages must be copy-on-write. */
+export declare function createToolHistoryPreparation(): ToolHistoryPreparation;
+export interface ToolHistoryPosition {
+    readonly outputIndex: number;
+    readonly contentIndex?: number;
+    readonly itemId?: string;
+}
+export type ResponsesHistoryContribution = ToolHistoryPosition & ({
+    readonly kind: 'text';
+    readonly actor: 'model';
+    readonly text: string;
+} | {
+    readonly kind: 'call';
+    readonly actor: 'model';
+    readonly name: string;
+    readonly callId?: string;
+    readonly arguments: unknown;
+} | {
+    readonly kind: 'image';
+    readonly actor: 'tool';
+    readonly image: ContentBlock.Multimodal.Image;
+} | {
+    readonly kind: 'provider-item';
+    readonly actor: 'model' | 'tool';
+    readonly providerType: string;
+    readonly value: unknown;
+});
+export declare function getResponsesHistorySource(message: BaseMessage): ResponsesHistorySource | undefined;
+/** Complete generated images retain their actual format across replay and folding. */
+export declare function getGeneratedImageMimeType(data: string): string;
+/** Streaming positions order sidecar evidence only when text positions map exactly. */
+export declare function projectResponsesHistory(source: ResponsesHistorySource, consumeWork: () => boolean): Generator<ResponsesHistoryContribution>;
+export {};

package/dist/types/messages/toolResultTypes.d.ts

@@ -1,3 +1,5 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { ProviderName } from '@/types/llm';
 export type ProviderToolCallKind = 'tool' | 'server' | 'anthropic-server' | 'mcp' | 'google' | 'bedrock';
 export interface ProviderToolCallPartDescriptor {
     readonly callId: string;
@@ -15,7 +17,7 @@ export interface ProviderToolResultPartDescriptor {
 }
 export interface ProviderToolCallIndexEntry {
     readonly descriptor: ProviderToolCallPartDescriptor;
-    secondarySourceType?: string;
+    secondarySourceTypes?: Set<string>;
 }
 export type ProviderToolCallIndex = Map<string, ProviderToolCallIndexEntry | null>;
 export declare const PROVIDER_TOOL_RESULT_MAX_ARRAY_ENTRIES = 256;
@@ -27,7 +29,35 @@ export declare function getBoundedProviderPairingArrayProperty(value: unknown, k
 export declare function isBoundedProviderPairingString(value: unknown, allowEmpty?: boolean): value is string;
 export declare function hasStructurallyValidAnthropicWebSearchResultContent(part: unknown): boolean;
 export declare function getProviderToolResultPartDescriptor(part: unknown): ProviderToolResultPartDescriptor | undefined;
+export declare function isProviderToolCallContentPart(part: unknown): boolean;
+export declare function isProviderToolContentPart(part: unknown): boolean;
 export declare function getProviderAIMessageToolCallDescriptor(toolCall: unknown): ProviderToolCallPartDescriptor | undefined;
 export declare function getProviderToolCallPartDescriptor(part: unknown): ProviderToolCallPartDescriptor | undefined;
 export declare function appendProviderToolCallDescriptor(index: ProviderToolCallIndex, descriptor: ProviderToolCallPartDescriptor): void;
+/** Google's built-in code execution emits an `executableCode` part with no call
+ *  id; its `codeExecutionResult` pairs by adjacency instead. */
+export declare function isExecutableCodePart(part: unknown): boolean;
 export declare function consumeProviderToolResultPair(descriptor: ProviderToolResultPartDescriptor, calls: ProviderToolCallIndex, previousPart?: unknown): boolean;
+export declare function getLegacyFunctionCallId(name: string): string | undefined;
+export type ProviderMessageRole = 'assistant' | 'user' | 'system' | 'tool' | 'function';
+/**
+ * Normalizes a message to the role a provider converter would send it as. A
+ * `ChatMessage` reports its type as `generic` and carries the wire role on
+ * `role`, so every classifier that keys on `getType()` alone silently skips
+ * generic assistant, tool and function messages the converters accept.
+ */
+export declare function getProviderMessageRole(message: BaseMessage, provider?: ProviderName): ProviderMessageRole | undefined;
+export declare function getRawToolCallDescriptor(toolCall: unknown): ProviderToolCallPartDescriptor | undefined;
+/**
+ * Appends every tool call an assistant message carries: parsed
+ * `AIMessage.tool_calls`, raw `additional_kwargs.tool_calls` (where OpenAI
+ * keeps calls when the parsed array is empty) and a legacy
+ * `additional_kwargs.function_call`. Content-block calls are the caller's to
+ * append, since only the caller knows whether the block is being replayed.
+ * Returns how many descriptors were recognized, so a caller can tell an
+ * invocation from a plain assistant turn without re-deriving the shapes.
+ */
+export declare function appendProviderMessageToolCalls(message: BaseMessage, calls: ProviderToolCallIndex, provider?: ProviderName): number;
+/** Describes a whole-message tool result: a `ToolMessage`, a `FunctionMessage`,
+ *  or a generic message carrying the equivalent wire role. */
+export declare function getProviderToolMessageResultDescriptor(message: BaseMessage, provider?: ProviderName): ProviderToolResultPartDescriptor | undefined;

package/dist/types/session/sessionProjection.d.ts

@@ -0,0 +1,10 @@
+import type { DerivedSessionMessages } from './deriveMessages';
+import type { SessionEntry } from './types';
+import type { JsonlSessionStore } from './JsonlSessionStore';
+/** Internal: only AgentSession's unexposed stores may reuse log topology. */
+export declare function initializeSessionProjection(store: JsonlSessionStore, entries: readonly SessionEntry[]): void;
+/** Forks share entry references, so exposing either disables the whole family. */
+export declare function shareSessionProjectionOwnership(source: JsonlSessionStore, target: JsonlSessionStore): void;
+export declare function releaseSessionProjection(store: JsonlSessionStore): void;
+/** Reuses log topology, but materializes fresh mutable messages for every run. */
+export declare function deriveSessionMessages(store: JsonlSessionStore | undefined): DerivedSessionMessages;

package/dist/types/summarization/index.d.ts

@@ -4,7 +4,8 @@ import type { SummarizationTrigger } from '@/types';
  * default prompts stay out of it: LibreChat's manual flow deliberately words
  * its own, so exporting these would publish an API with no consumer.
  */
-export { buildSummarizationInstruction, buildSummaryCarrierText, separateSummarizationParameters, } from './shared';
+export { buildSummarizationInstruction, buildSummaryCarrierText, separateSummarizationParameters, ManualSummarizationSkippedError, } from './shared';
+export type { ManualSummarizationSkipReason } from './shared';
 /** For tests only. Resets the dedup set so warnings can be observed again. */
 export declare function _resetUnrecognizedTriggerWarnings(): void;
 /**

package/dist/types/summarization/node.d.ts

@@ -45,6 +45,7 @@ export declare function createSummarizeNode({ agentContext, graph: adapterGraph,
 }, config?: RunnableConfig) => Promise<{
     summarizationRequest: undefined;
     messages?: BaseMessage[];
+    manualSummary?: string;
 }>;
 /** Creates an `onChunk` callback that dispatches `ON_SUMMARIZE_DELTA` events for streaming. */
 export declare function createSummarizationChunkHandler({ stepId, config, provider, reasoningKey, graph, }: {

package/dist/types/summarization/shared.d.ts

@@ -23,3 +23,15 @@ export declare function separateSummarizationParameters(parameters: Record<strin
     maxSummaryTokens?: number;
 };
 export declare function buildSummarizationInstruction(promptText: string, updatePromptText: string | undefined, priorSummaryText?: string, semanticIndexAppendix?: string): string;
+/** Why a summarize-only run could not attempt its summary. */
+export type ManualSummarizationSkipReason = 'disabled' | 'exhausted' | 'instructions_exceed_budget' | 'nothing_to_summarize';
+/**
+ * A summarize-only run asked for a summary the graph could not attempt.
+ * Thrown rather than ending the run quietly: the summary is the whole result
+ * of such a run, so a host left with neither a summary nor an error would
+ * have nothing to show the user.
+ */
+export declare class ManualSummarizationSkippedError extends Error {
+    readonly reason: ManualSummarizationSkipReason;
+    constructor(reason: ManualSummarizationSkipReason, message: string);
+}

package/dist/types/tools/ArtifactDelivery.d.ts

@@ -0,0 +1,4 @@
+import type { ArtifactDeliveryFailure } from '@/types';
+export declare const ARTIFACT_DELIVERY_WARNING_PREFIX = "Artifact delivery warning:";
+export declare function normalizeArtifactDeliveryFailure(value: unknown): ArtifactDeliveryFailure | undefined;
+export declare function appendArtifactDeliveryWarning(output: string, delivery: ArtifactDeliveryFailure | undefined): string;

package/dist/types/types/graph.d.ts

@@ -30,6 +30,13 @@ export type SystemCallbacks = {
 export type BaseGraphState = {
     messages: BaseMessage[];
     runStepState?: RunStepResumeState;
+    /**
+     * The summary a summarize-only run produced. Kept in state because such a
+     * run has no assistant reply: trace roots report it as the run's output
+     * instead of the retained tail or the raw state. Empty once any later run
+     * on the same checkpointed thread starts, so it never outlives its run.
+     */
+    manualSummary?: string;
 };
 export type AgentSubgraphState = BaseGraphState & {
     summarizationRequest?: SummarizationNodeInput;
@@ -652,6 +659,14 @@ export interface LangfuseConfig {
      */
     additionalHeaders?: Record<string, string>;
     metadata?: Record<string, string | number | boolean | null | undefined>;
+    /**
+     * User identity stamped on every trace this run emits — the agent stream,
+     * titles, activity and reasoning labels, and phases. Hosts set it when the
+     * observability identity differs from `configurable.user_id` (an email or
+     * IdP subject instead of an internal database id); that id remains the
+     * fallback when unset or blank.
+     */
+    userId?: string;
     /**
      * Internal OTLP span attributes to attach to Langfuse observations before
      * export. Intended for collector-side routing/filtering; strip these in the
@@ -717,6 +732,19 @@ interface AgentInputFields {
      */
     discoveredTools?: string[];
     summarizationEnabled?: boolean;
+    /**
+     * Runs this agent as a summarize-only pass: the first model step requests
+     * summarization outright instead of consulting the trigger, and the step
+     * after the summary emits its context snapshot and ends the run without a
+     * model call. Hosts use it for user-initiated compaction, where the summary
+     * is the whole response. Requires `summarizationEnabled`: a run that cannot
+     * attempt the summary rejects with `ManualSummarizationSkippedError`
+     * rather than ending with nothing, and one whose provider calls all fail
+     * keeps the history and reports the failure on the summary step. A
+     * multi-agent workflow compiles to the agent that opted in alone; no other
+     * agent runs.
+     */
+    summarizeOnly?: boolean;
     summarizationConfig?: SummarizationConfig;
     /**
      * Optional host-supplied, user-visible guidance for compaction. The SDK

package/dist/types/types/run.d.ts

@@ -453,6 +453,10 @@ export type TokenBudgetBreakdown = {
     toolTokenCounts?: Record<string, number>;
     /** Names of counted tools that are deferred (`defer_loading`) and discovered. */
     deferredToolNames?: string[];
+    /** Calibrated retained tool traffic: tool results plus assistant turns made only of tool calls, inline provider tool results and reasoning. A subset of messageTokens, not an additional budget category. */
+    toolMessageTokens?: number;
+    /** Per-tool result-message share; excludes assistant invocation overhead. */
+    toolMessageTokenCounts?: Record<string, number>;
 };
 export type EventStreamOptions = {
     callbacks?: g.ClientCallbacks;

package/dist/types/types/summarize.d.ts

@@ -104,8 +104,11 @@ export interface SummarizationNodeInput {
      *   is compacting to recover. When summarization is not enabled, this
      *   variant performs no model call — the corrected budget alone is what the
      *   retry needs.
+     * - `manual`: the host asked for a summary outright (a summarize-only run).
+     *   The recency window is not applied unless the host configured
+     *   `retainRecent` explicitly, so the summary replaces the whole history.
      */
-    reason?: 'trigger' | 'overflow';
+    reason?: 'trigger' | 'overflow' | 'manual';
     /**
      * Whether an overflow recovery may spend a summarization model call.
      *

package/dist/types/types/tools.d.ts

@@ -449,6 +449,13 @@ export type FileRef = {
     inherited?: true;
 };
 export type FileRefs = FileRef[];
+export type ArtifactDeliveryFailure = {
+    code: 'artifact_delivery_failed';
+    status: 'partial' | 'failed';
+    attempted: number;
+    delivered: number;
+    failed: number;
+};
 export type ExecuteResult = {
     /**
      * Execution session id — the (transient) sandbox run that produced
@@ -459,6 +466,7 @@ export type ExecuteResult = {
     stdout: string;
     stderr: string;
     files?: FileRefs;
+    artifact_delivery?: ArtifactDeliveryFailure;
     /**
      * Durable runtime session id echoed by a stateful Code API backend
      * (hash of tenant+user+hint). Additive; absent on stateless servers.
@@ -1217,6 +1225,7 @@ export type ProgrammaticExecutionResponse = {
     stdout?: string;
     stderr?: string;
     files?: FileRefs;
+    artifact_delivery?: ArtifactDeliveryFailure;
     /** Durable runtime session echo from a stateful backend (additive). */
     runtime_session_id?: string;
     runtime_status?: 'new' | 'reused';
@@ -1230,6 +1239,7 @@ export type ProgrammaticExecutionArtifact = {
     /** Execution session — see `CodeSessionContext.session_id`. */
     session_id?: string;
     files?: FileRefs;
+    artifact_delivery?: ArtifactDeliveryFailure;
     /** Durable runtime session echo from a stateful backend (additive). */
     runtime_session_id?: string;
     runtime_status?: 'new' | 'reused';
@@ -1284,6 +1294,7 @@ export type CodeExecutionArtifact = {
     /** Execution session — see `CodeSessionContext.session_id`. */
     session_id?: string;
     files?: FileRefs;
+    artifact_delivery?: ArtifactDeliveryFailure;
     /** Durable runtime session echo from a stateful backend (additive). */
     runtime_session_id?: string;
     runtime_status?: 'new' | 'reused';

package/dist/types/utils/tokens.d.ts

@@ -1,6 +1,6 @@
 import type { BaseMessage } from '@langchain/core/messages';
 export type EncodingName = 'o200k_base' | 'claude';
-export type UnsafeTokenMeasurementReason = 'message_proxy' | 'content_proxy' | 'metadata_proxy' | 'metadata_accessor' | 'invalid_count';
+export type UnsafeTokenMeasurementReason = 'message_proxy' | 'content_proxy' | 'metadata_proxy' | 'metadata_accessor' | 'metadata_limit' | 'invalid_count';
 export declare class UnsafeTokenMeasurementError extends Error {
     readonly type = "unsafe_token_measurement";
     readonly reason: UnsafeTokenMeasurementReason;
@@ -61,6 +61,7 @@ export declare function encodingForModel(model: string): EncodingName;
  * unsafe so the caller can normalize or reject them conservatively.
  */
 export declare function hasUnsafeStructuredSerialization(value: unknown): boolean;
+export declare function readTokenMetadataProperty(value: object, key: PropertyKey, path: string): unknown;
 export declare function getTokenCountForMessage(message: BaseMessage, getTokenCount: (text: string) => number, encoding?: EncodingName): number;
 /**
  * Largest-remainder apportionment: scales each count by `multiplier` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.7.22",
+  "version": "3.8.1",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"

package/src/agents/AgentContext.ts

@@ -123,6 +123,7 @@ export class AgentContext {
       useLegacyContent,
       discoveredTools,
       summarizationEnabled,
+      summarizeOnly,
       summarizationConfig,
       compactionSemanticIndex,
       initialSummary,
@@ -158,6 +159,7 @@ export class AgentContext {
       useLegacyContent,
       discoveredTools,
       summarizationEnabled,
+      summarizeOnly,
       summarizationConfig,
       compactionSemanticIndex,
       contextPruningConfig,
@@ -383,6 +385,10 @@ export class AgentContext {
   useLegacyContent: boolean = false;
   /** Enables graph-level summarization for this agent */
   summarizationEnabled?: boolean;
+  /** Summarize-only run: request a summary on the first model step and end after it */
+  summarizeOnly?: boolean;
+  /** Whether the summarize-only run has already issued its one request */
+  private _manualSummarizationRequested: boolean = false;
   /** Summarization runtime settings used by graph pruning hooks */
   summarizationConfig?: t.SummarizationConfig;
   /** Host-supplied advisory guidance consumed only when compaction runs. */
@@ -480,6 +486,7 @@ export class AgentContext {
     useLegacyContent,
     discoveredTools,
     summarizationEnabled,
+    summarizeOnly,
     summarizationConfig,
     compactionSemanticIndex,
     contextPruningConfig,
@@ -508,6 +515,7 @@ export class AgentContext {
     useLegacyContent?: boolean;
     discoveredTools?: string[];
     summarizationEnabled?: boolean;
+    summarizeOnly?: boolean;
     summarizationConfig?: t.SummarizationConfig;
     compactionSemanticIndex?: t.CompactionSemanticIndex;
     contextPruningConfig?: t.ContextPruningConfig;
@@ -549,6 +557,7 @@ export class AgentContext {
 
     this.useLegacyContent = useLegacyContent ?? false;
     this.summarizationEnabled = summarizationEnabled;
+    this.summarizeOnly = summarizeOnly;
     this.summarizationConfig = summarizationConfig;
     if (compactionSemanticIndex != null) {
       this.compactionSemanticIndex = snapshotCompactionSemanticIndex(
@@ -1268,6 +1277,7 @@ export class AgentContext {
     this.summaryPrecedesMessages = this.durableSummaryPrecedesMessages;
     this._lastSummarizationMsgCount = 0;
     this._summarizationFailures = 0;
+    this._manualSummarizationRequested = false;
     this.lastCallUsage = undefined;
     this.totalTokensFresh = false;
     this.restoreContextBudgetAfterOverflow();
@@ -1617,6 +1627,20 @@ export class AgentContext {
     this._lastSummarizationMsgCount = msgCount;
   }
 
+  /**
+   * Claims the single summarization request a summarize-only run makes.
+   * True exactly once per run, on the first model step; the step that gets
+   * `false` is the one after the summary, which reports usage and ends
+   * without a model call. Always false when `summarizeOnly` is off.
+   */
+  claimManualSummarization(): boolean {
+    if (this.summarizeOnly !== true || this._manualSummarizationRequested) {
+      return false;
+    }
+    this._manualSummarizationRequested = true;
+    return true;
+  }
+
   /**
    * Records a summarization attempt that produced no usable summary — an
    * empty model response, or a provider failure the run declined to paper
@@ -1767,8 +1791,9 @@ export class AgentContext {
         const recounted: Record<string, number> = {};
         for (let i = 0; i < messages.length; i++) {
           const localCount = this.tokenCounter(messages[i]);
-          const conservativeFloor =
-            this.providerProjectionRecountFloors?.get(messages[i]);
+          const conservativeFloor = this.providerProjectionRecountFloors?.get(
+            messages[i]
+          );
           recounted[i] =
             conservativeFloor == null
               ? localCount
@@ -2112,7 +2137,13 @@ export class AgentContext {
       remainingContextTokens,
       calibrationRatio,
     };
-    syncBudgetDerivedFields(usage);
+    syncBudgetDerivedFields(
+      usage,
+      context,
+      this.contextPressureTokenCounts?.count ?? tokenCounter,
+      undefined,
+      this.provider
+    );
     return usage;
   }