[pull] main from danny-avila:main

package.json

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

src/langfuse.ts

@@ -895,6 +895,18 @@ function mergeLangfuseTags(
   return merged.length > 0 ? [...new Set(merged)] : undefined;
 }
 
+/**
+ * The trace's user identity: the host-configured `langfuse.userId` when
+ * present, else the caller's (normally `configurable.user_id`).
+ */
+export function resolveLangfuseTraceUserId(
+  langfuse: t.LangfuseConfig | undefined,
+  userId: string | undefined
+): string | undefined {
+  const configured = langfuse?.userId?.trim();
+  return isPresent(configured) ? configured : userId;
+}
+
 export function getLangfuseTraceName(
   traceMetadata?: LangfuseTraceMetadata,
   fallback: string = 'LibreChat Agent'
@@ -942,7 +954,7 @@ export function createLangfuseHandler({
     return undefined;
   }
   return new ScopedLangfuseCallbackHandler({
-    userId,
+    userId: resolveLangfuseTraceUserId(langfuse, userId),
     sessionId,
     traceMetadata:
       inheritTraceIdentity === true
@@ -972,7 +984,10 @@ function createPropagateAttributeParams({
   inheritTraceIdentity,
 }: LangfuseAttributeParams): PropagateAttributesParams {
   return {
-    userId: inheritTraceIdentity === true ? undefined : userId,
+    userId:
+      inheritTraceIdentity === true
+        ? undefined
+        : resolveLangfuseTraceUserId(langfuse, userId),
     sessionId: inheritTraceIdentity === true ? undefined : sessionId,
     traceName: inheritTraceIdentity === true ? undefined : traceName,
     tags: mergeLangfuseTags(tags, langfuse?.tags),

src/specs/langfuse-config.test.ts

@@ -76,6 +76,53 @@ describe('createLangfuseHandler', () => {
     });
   });
 
+  it('stamps the configured trace userId over the caller identity', () => {
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';
+    process.env.LANGFUSE_SECRET_KEY = 'sk-env';
+
+    createLangfuseHandler({
+      langfuse: { userId: 'alice@example.com' },
+      userId: 'user-1',
+      sessionId: 'thread-1',
+      tags: ['librechat', 'agent'],
+    });
+
+    expect(MockedCallbackHandler).toHaveBeenCalledWith(
+      expect.objectContaining({ userId: 'alice@example.com', sessionId: 'thread-1' })
+    );
+  });
+
+  it('keeps the caller identity when the configured trace userId is blank', () => {
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';
+    process.env.LANGFUSE_SECRET_KEY = 'sk-env';
+
+    createLangfuseHandler({
+      langfuse: { userId: '   ' },
+      userId: 'user-1',
+      sessionId: 'thread-1',
+    });
+
+    expect(MockedCallbackHandler).toHaveBeenCalledWith(
+      expect.objectContaining({ userId: 'user-1' })
+    );
+  });
+
+  it('does not stamp the configured trace userId on inherited identities', () => {
+    process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';
+    process.env.LANGFUSE_SECRET_KEY = 'sk-env';
+
+    createLangfuseHandler({
+      langfuse: { userId: 'alice@example.com' },
+      userId: 'user-1',
+      sessionId: 'thread-1',
+      inheritTraceIdentity: true,
+    });
+
+    expect(MockedCallbackHandler).toHaveBeenCalledWith(
+      expect.objectContaining({ userId: undefined, sessionId: undefined })
+    );
+  });
+
   it('adds configured trace metadata and tags to the callback handler', () => {
     process.env.LANGFUSE_PUBLIC_KEY = 'pk-env';
     process.env.LANGFUSE_SECRET_KEY = 'sk-env';

src/tools/ArtifactDelivery.ts

@@ -0,0 +1,50 @@
+import type { ArtifactDeliveryFailure } from '@/types';
+
+export const ARTIFACT_DELIVERY_WARNING_PREFIX = 'Artifact delivery warning:';
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+
+export function normalizeArtifactDeliveryFailure(
+  value: unknown
+): ArtifactDeliveryFailure | undefined {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const candidate = value as Partial<ArtifactDeliveryFailure>;
+  if (
+    candidate.code !== 'artifact_delivery_failed' ||
+    (candidate.status !== 'partial' && candidate.status !== 'failed') ||
+    !isNonNegativeInteger(candidate.attempted) ||
+    !isNonNegativeInteger(candidate.delivered) ||
+    !isNonNegativeInteger(candidate.failed) ||
+    candidate.failed === 0 ||
+    candidate.attempted !== candidate.delivered + candidate.failed ||
+    (candidate.status === 'failed' && candidate.delivered !== 0) ||
+    (candidate.status === 'partial' && candidate.delivered === 0)
+  ) {
+    return undefined;
+  }
+
+  return {
+    code: candidate.code,
+    status: candidate.status,
+    attempted: candidate.attempted,
+    delivered: candidate.delivered,
+    failed: candidate.failed,
+  };
+}
+
+export function appendArtifactDeliveryWarning(
+  output: string,
+  delivery: ArtifactDeliveryFailure | undefined
+): string {
+  if (delivery == null) {
+    return output;
+  }
+
+  const warning = `${ARTIFACT_DELIVERY_WARNING_PREFIX} ${delivery.failed} of ${delivery.attempted} generated files could not be persisted. Do not assume missing files are available to later calls or downloadable. The code itself ran; do not rerun automatically because it may have had side effects.`;
+  return `${output.trimEnd()}\n${warning}\n`;
+}

src/tools/BashExecutor.ts

@@ -18,6 +18,10 @@ import {
   resolveCodeApiAuthHeaders,
   selectRuntimeSessionHint,
 } from './CodeExecutor';
+import {
+  appendArtifactDeliveryWarning,
+  normalizeArtifactDeliveryFailure,
+} from '@/tools/ArtifactDelivery';
 import { logCodeApiDiagnostic } from '@/tools/diagnostics';
 import { resolveFetchProxyAgent } from '@/utils/proxy';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
@@ -300,6 +304,13 @@ function createBashExecutionTool(
           formattedOutput,
           command
         );
+        const artifactDelivery = normalizeArtifactDeliveryFailure(
+          result.artifact_delivery
+        );
+        const outputWithDeliveryWarning = appendArtifactDeliveryWarning(
+          outputWithReminder,
+          artifactDelivery
+        );
         const hasFiles = result.files != null && result.files.length > 0;
         const runtimeEcho =
           result.runtime_session_id != null
@@ -309,15 +320,21 @@ function createBashExecutionTool(
             }
             : {};
         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,
         ];

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,
         ];

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,

src/tools/__tests__/ArtifactDelivery.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from '@jest/globals';
+import {
+  ARTIFACT_DELIVERY_WARNING_PREFIX,
+  appendArtifactDeliveryWarning,
+  normalizeArtifactDeliveryFailure,
+} from '../ArtifactDelivery';
+
+describe('artifact delivery failures', () => {
+  it('normalizes the bounded Code API failure contract', () => {
+    expect(
+      normalizeArtifactDeliveryFailure({
+        code: 'artifact_delivery_failed',
+        status: 'partial',
+        attempted: 3,
+        delivered: 2,
+        failed: 1,
+        detail: 'private storage failure',
+      })
+    ).toEqual({
+      code: 'artifact_delivery_failed',
+      status: 'partial',
+      attempted: 3,
+      delivered: 2,
+      failed: 1,
+    });
+  });
+
+  it.each([
+    null,
+    {
+      code: 'storage_error',
+      status: 'failed',
+      attempted: 1,
+      delivered: 0,
+      failed: 1,
+    },
+    {
+      code: 'artifact_delivery_failed',
+      status: 'failed',
+      attempted: 2,
+      delivered: 1,
+      failed: 1,
+    },
+    {
+      code: 'artifact_delivery_failed',
+      status: 'partial',
+      attempted: 1,
+      delivered: 0,
+      failed: 1,
+    },
+    {
+      code: 'artifact_delivery_failed',
+      status: 'failed',
+      attempted: 1,
+      delivered: 0,
+      failed: -1,
+    },
+  ])('rejects malformed external values', (value) => {
+    expect(normalizeArtifactDeliveryFailure(value)).toBeUndefined();
+  });
+
+  it('warns without claiming the code execution failed or recommending a retry', () => {
+    const output = appendArtifactDeliveryWarning('stdout:\ndone\n', {
+      code: 'artifact_delivery_failed',
+      status: 'failed',
+      attempted: 1,
+      delivered: 0,
+      failed: 1,
+    });
+
+    expect(output).toContain(ARTIFACT_DELIVERY_WARNING_PREFIX);
+    expect(output).toContain('1 of 1 generated files could not be persisted');
+    expect(output).toContain('The code itself ran');
+    expect(output).toContain('do not rerun automatically');
+  });
+});