@librechat/agents 3.7.22 → 3.8.1

package/src/tools/CodeExecutor.ts

@@ -5,6 +5,10 @@ import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type { Readable } from 'node:stream';
 import type { CodeApiMethod } from '@/tools/diagnostics';
 import type * as t from '@/types';
+import {
+  appendArtifactDeliveryWarning,
+  normalizeArtifactDeliveryFailure,
+} from '@/tools/ArtifactDelivery';
 import {
   describeCodeApiError,
   logCodeApiDiagnostic,
@@ -564,6 +568,13 @@ function createCodeExecutionTool(
           formattedOutput,
           code
         );
+        const artifactDelivery = normalizeArtifactDeliveryFailure(
+          result.artifact_delivery
+        );
+        const outputWithDeliveryWarning = appendArtifactDeliveryWarning(
+          outputWithReminder,
+          artifactDelivery
+        );
         const hasFiles = result.files != null && result.files.length > 0;
         /* Echo the durable runtime session (stateful backends only) so hosts
          * can surface a "session active / was reset" signal later. Additive:
@@ -576,15 +587,21 @@ function createCodeExecutionTool(
             }
             : {};
         return [
-          appendCodeSessionFileSummary(outputWithReminder, result.files),
+          appendCodeSessionFileSummary(outputWithDeliveryWarning, result.files),
           (hasFiles
             ? {
               session_id: result.session_id,
               files: result.files,
+              ...(artifactDelivery != null
+                ? { artifact_delivery: artifactDelivery }
+                : {}),
               ...runtimeEcho,
             }
             : {
               session_id: result.session_id,
+              ...(artifactDelivery != null
+                ? { artifact_delivery: artifactDelivery }
+                : {}),
               ...runtimeEcho,
             }) satisfies t.CodeExecutionArtifact,
         ];

package/src/tools/ProgrammaticToolCalling.ts

@@ -33,6 +33,10 @@ import {
   createCodeApiRunTimeoutSchema,
   resolveCodeApiRunTimeoutMs,
 } from './ptcTimeout';
+import {
+  appendArtifactDeliveryWarning,
+  normalizeArtifactDeliveryFailure,
+} from '@/tools/ArtifactDelivery';
 import {
   describeCodeApiError,
   logCodeApiDiagnostic,
@@ -871,12 +875,22 @@ export function formatCompletedResponse(
   }
 
   const outputWithReminder = appendTmpScratchReminder(formatted, sourceCode);
+  const artifactDelivery = normalizeArtifactDeliveryFailure(
+    response.artifact_delivery
+  );
+  const outputWithDeliveryWarning = appendArtifactDeliveryWarning(
+    outputWithReminder,
+    artifactDelivery
+  );
 
   return [
-    appendCodeSessionFileSummary(outputWithReminder, response.files),
+    appendCodeSessionFileSummary(outputWithDeliveryWarning, response.files),
     {
       session_id: response.session_id,
       files: response.files,
+      ...(artifactDelivery != null
+        ? { artifact_delivery: artifactDelivery }
+        : {}),
       ...(response.runtime_session_id != null
         ? {
           runtime_session_id: response.runtime_session_id,

package/src/types/graph.ts

@@ -81,6 +81,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 & {
@@ -829,6 +836,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
@@ -898,6 +913,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/src/types/run.ts

@@ -475,6 +475,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 = {

package/src/types/summarize.ts

@@ -127,8 +127,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/src/types/tools.ts

@@ -481,6 +481,14 @@ export type FileRef = {
 
 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
@@ -491,6 +499,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.
@@ -1327,6 +1336,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;
@@ -1343,6 +1353,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';
@@ -1409,6 +1420,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/src/utils/events.ts

@@ -2,7 +2,9 @@
 // src/utils/events.ts
 import { dispatchCustomEvent } from '@langchain/core/callbacks/dispatch';
 import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ToolExecuteBatchRequest } from '@/types/tools';
 import type { AgentLogEvent } from '@/types/graph';
+import { traceHostToolResults } from '@/langfuse';
 import { GraphEvents } from '@/common';
 
 /**
@@ -15,6 +17,23 @@ export async function safeDispatchCustomEvent(
   config?: RunnableConfig
 ): Promise<boolean | void> {
   try {
+    if (event === GraphEvents.ON_TOOL_EXECUTE) {
+      const request = payload as ToolExecuteBatchRequest;
+      payload = {
+        ...request,
+        resolve: (
+          results: Parameters<ToolExecuteBatchRequest['resolve']>[0]
+        ): void => {
+          void traceHostToolResults(request, results, config).then(
+            () => request.resolve(results),
+            () => {
+              console.warn('Failed to record host tool execution metadata');
+              request.resolve(results);
+            }
+          );
+        },
+      } satisfies ToolExecuteBatchRequest;
+    }
     await dispatchCustomEvent(event, payload, config);
     return true;
   } catch (e) {

package/src/utils/tokens.ts

@@ -16,6 +16,7 @@ export type UnsafeTokenMeasurementReason =
   | 'content_proxy'
   | 'metadata_proxy'
   | 'metadata_accessor'
+  | 'metadata_limit'
   | 'invalid_count';
 
 export class UnsafeTokenMeasurementError extends Error {
@@ -121,6 +122,7 @@ const MAX_STRUCTURED_TOKENIZATION_CHARS = 200_000;
 /** One UTF-16 character can encode to several tokenizer pieces. */
 const MAX_TOKENS_PER_OMITTED_STRUCTURED_CHAR = 4;
 const MAX_STRUCTURED_SAFETY_INSPECTION_WORK = 10_000;
+const MAX_RAW_TOOL_CALLS = MAX_STRUCTURED_SAFETY_INSPECTION_WORK;
 /** Bounds BPE work per plain-text segment without omitting any text. */
 const MAX_TEXT_TOKENIZATION_CHARS = 8_192;
 /** Covers tokenizer segmentation changes on both sides of a chunk boundary. */
@@ -946,6 +948,63 @@ function getBoundedStructuredTokenCount(
   );
 }
 
+export function readTokenMetadataProperty(
+  value: object,
+  key: PropertyKey,
+  path: string
+): unknown {
+  const seen = new Set<object>();
+  let current: object | null = value;
+  for (let depth = 0; current != null && depth < 100; depth++) {
+    if (isProxy(current)) {
+      throw new UnsafeTokenMeasurementError({
+        reason: 'metadata_proxy',
+        path,
+      });
+    }
+    if (seen.has(current)) {
+      throw new UnsafeTokenMeasurementError({
+        reason: 'metadata_accessor',
+        path,
+      });
+    }
+    seen.add(current);
+    let descriptor: PropertyDescriptor | undefined;
+    try {
+      descriptor = Object.getOwnPropertyDescriptor(current, key);
+    } catch {
+      throw new UnsafeTokenMeasurementError({
+        reason: 'metadata_accessor',
+        path,
+      });
+    }
+    if (descriptor != null) {
+      if (!('value' in descriptor)) {
+        throw new UnsafeTokenMeasurementError({
+          reason: 'metadata_accessor',
+          path,
+        });
+      }
+      return descriptor.value;
+    }
+    try {
+      current = Object.getPrototypeOf(current) as object | null;
+    } catch {
+      throw new UnsafeTokenMeasurementError({
+        reason: 'metadata_accessor',
+        path,
+      });
+    }
+  }
+  if (current != null) {
+    throw new UnsafeTokenMeasurementError({
+      reason: 'metadata_accessor',
+      path,
+    });
+  }
+  return undefined;
+}
+
 export function getTokenCountForMessage(
   message: BaseMessage,
   getTokenCount: (text: string) => number,
@@ -1187,6 +1246,130 @@ export function getTokenCountForMessage(
             : getBoundedStructuredTokenCount(args, countText);
       }
     }
+    const rawCalls =
+      toolCalls.length > 0 || additionalKwargs == null
+        ? undefined
+        : readTokenMetadataProperty(
+          additionalKwargs,
+          'tool_calls',
+          'additional_kwargs.tool_calls'
+        );
+    if (rawCalls != null) {
+      if (isProxy(rawCalls)) {
+        throw new UnsafeTokenMeasurementError({
+          reason: 'metadata_proxy',
+          path: 'additional_kwargs.tool_calls',
+        });
+      }
+      if (!Array.isArray(rawCalls)) {
+        throw new UnsafeTokenMeasurementError({
+          reason: 'metadata_accessor',
+          path: 'additional_kwargs.tool_calls',
+        });
+      }
+      if (rawCalls.length > MAX_RAW_TOOL_CALLS) {
+        throw new UnsafeTokenMeasurementError({
+          reason: 'metadata_limit',
+          path: 'additional_kwargs.tool_calls',
+        });
+      }
+      for (let i = 0; i < rawCalls.length; i++) {
+        const rawCall = readTokenMetadataProperty(
+          rawCalls,
+          String(i),
+          `additional_kwargs.tool_calls[${i}]`
+        );
+        if (
+          rawCall == null ||
+          typeof rawCall !== 'object' ||
+          isProxy(rawCall)
+        ) {
+          throw new UnsafeTokenMeasurementError({
+            reason: 'metadata_proxy',
+            path: `additional_kwargs.tool_calls[${i}]`,
+          });
+        }
+        const callPath = `additional_kwargs.tool_calls[${i}]`;
+        if (hasUnsafeStructuredSerialization(rawCall)) {
+          throw new UnsafeTokenMeasurementError({
+            reason: 'metadata_accessor',
+            path: callPath,
+          });
+        }
+        const callId = readTokenMetadataProperty(
+          rawCall,
+          'id',
+          `${callPath}.id`
+        );
+        const callType = readTokenMetadataProperty(
+          rawCall,
+          'type',
+          `${callPath}.type`
+        );
+        const rawFunction = readTokenMetadataProperty(
+          rawCall,
+          'function',
+          `${callPath}.function`
+        );
+        const rawCustom = readTokenMetadataProperty(
+          rawCall,
+          'custom',
+          `${callPath}.custom`
+        );
+        let projectedFunction = rawFunction;
+        if (rawFunction != null && typeof rawFunction === 'object') {
+          if (hasUnsafeStructuredSerialization(rawFunction)) {
+            throw new UnsafeTokenMeasurementError({
+              reason: 'metadata_accessor',
+              path: `${callPath}.function`,
+            });
+          }
+          const name = readTokenMetadataProperty(
+            rawFunction,
+            'name',
+            `${callPath}.function.name`
+          );
+          const args = readTokenMetadataProperty(
+            rawFunction,
+            'arguments',
+            `${callPath}.function.arguments`
+          );
+          projectedFunction = { name, arguments: args };
+        }
+        let projectedCustom = rawCustom;
+        if (rawCustom != null && typeof rawCustom === 'object') {
+          if (hasUnsafeStructuredSerialization(rawCustom)) {
+            throw new UnsafeTokenMeasurementError({
+              reason: 'metadata_accessor',
+              path: `${callPath}.custom`,
+            });
+          }
+          const name = readTokenMetadataProperty(
+            rawCustom,
+            'name',
+            `${callPath}.custom.name`
+          );
+          const input = readTokenMetadataProperty(
+            rawCustom,
+            'input',
+            `${callPath}.custom.input`
+          );
+          projectedCustom = { name, input };
+        }
+        if (typeof callId === 'string' && representedToolCallIds.has(callId)) {
+          continue;
+        }
+        numTokens += getBoundedStructuredTokenCount(
+          {
+            id: callId,
+            type: callType,
+            custom: projectedCustom,
+            function: projectedFunction,
+          },
+          countText
+        );
+      }
+    }
     let legacyFunctionCall: PropertyDescriptor | undefined;
     try {
       legacyFunctionCall =