Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🧱 refactor: typed CodeEnvRef + kind discriminator + principal-aware sandbox cache (#12960)
Danny Avila93c4ef4ba87e
diff --git a/.env.example b/.env.exampleindex 9a5514ee9f..5349027e95 100644--- a/.env.example+++ b/.env.example@@ -58,6 +58,10 @@ TRUST_PROXY=1# Use when process console logs in cloud deployment like GCP/AWSCONSOLE_JSON=false+# The maximum length of a string in a JSON log object.+# Default: 255+# CONSOLE_JSON_STRING_LENGTH=255+#===============## Debug Logging ##===============#diff --git a/api/app/clients/BaseClient.js b/api/app/clients/BaseClient.jsindex 626b4c77f1..e641017c74 100644--- a/api/app/clients/BaseClient.js+++ b/api/app/clients/BaseClient.js@@ -1234,7 +1234,11 @@ class BaseClient {allFiles.push(file);continue;}- if (file.embedded === true || file.metadata?.fileIdentifier != null) {+ if (+ file.embedded === true ||+ file.metadata?.codeEnvRef != null ||+ file.metadata?.fileIdentifier != null+ ) {allFiles.push(file);continue;}diff --git a/api/package.json b/api/package.jsonindex 11c27cd622..05a2ab0834 100644--- a/api/package.json+++ b/api/package.json@@ -45,7 +45,7 @@"@azure/storage-blob": "^12.30.0","@google/genai": "^1.19.0","@keyv/redis": "^4.3.3",- "@librechat/agents": "^3.1.79",+ "@librechat/agents": "^3.1.80-dev.3","@librechat/api": "*","@librechat/data-schemas": "*","@microsoft/microsoft-graph-client": "^3.0.7",diff --git a/api/server/controllers/agents/callbacks.js b/api/server/controllers/agents/callbacks.jsindex c9612c6b62..6390e60666 100644--- a/api/server/controllers/agents/callbacks.js+++ b/api/server/controllers/agents/callbacks.js@@ -616,22 +616,23 @@ function createToolEndCallback({ req, res, artifactPromises, streamId = null })toolCallId,conversationId: metadata.thread_id,/**- * Use the FILE's session_id (storage session), not the- * top-level artifact session_id (exec session). The codeapi- * worker reports two distinct ids on a tool result:+ * Use the FILE's `storage_session_id` (storage session),+ * not the top-level artifact `session_id` (exec session).+ * The codeapi worker reports two distinct ids on a tool+ * result:* - `artifact.session_id` is the EXEC session — the* sandbox VM that ran the bash command. Files don't* live there; it's torn down post-execution.- * - `file.session_id` is the STORAGE session — the- * file-server bucket prefix where artifacts actually- * live and are served from.+ * - `file.storage_session_id` is the STORAGE session —+ * the file-server bucket prefix where artifacts+ * actually live and are served from.* `processCodeOutput` builds `/download/{session_id}/{id}`,* so passing the exec id resolves to a path the file-server* doesn't know about and 404s. Fall back to artifact-level* for older worker payloads that may not populate per-file* ids.*/- session_id: file.session_id ?? output.artifact.session_id,+ session_id: file.storage_session_id ?? output.artifact.session_id,});const fileMetadata = result?.file ?? null;const finalize = result?.finalize;@@ -882,22 +883,23 @@ function createResponsesToolEndCallback({ req, res, tracker, artifactPromises })toolCallId,conversationId: metadata.thread_id,/**- * Use the FILE's session_id (storage session), not the- * top-level artifact session_id (exec session). The codeapi- * worker reports two distinct ids on a tool result:+ * Use the FILE's `storage_session_id` (storage session),+ * not the top-level artifact `session_id` (exec session).+ * The codeapi worker reports two distinct ids on a tool+ * result:* - `artifact.session_id` is the EXEC session — the* sandbox VM that ran the bash command. Files don't* live there; it's torn down post-execution.- * - `file.session_id` is the STORAGE session — the- * file-server bucket prefix where artifacts actually- * live and are served from.+ * - `file.storage_session_id` is the STORAGE session —+ * the file-server bucket prefix where artifacts+ * actually live and are served from.* `processCodeOutput` builds `/download/{session_id}/{id}`,* so passing the exec id resolves to a path the file-server* doesn't know about and 404s. Fall back to artifact-level* for older worker payloads that may not populate per-file* ids.*/- session_id: file.session_id ?? output.artifact.session_id,+ session_id: file.storage_session_id ?? output.artifact.session_id,});const fileMetadata = result?.file ?? null;const finalize = result?.finalize;diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.jsindex 8f4af5f252..40c4ab6d96 100644--- a/api/server/controllers/agents/client.js+++ b/api/server/controllers/agents/client.js@@ -331,7 +331,7 @@ class AgentClient extends BaseClient {this.contextHandlers?.processFile(file);continue;}- if (file.metadata?.fileIdentifier) {+ if (file.metadata?.codeEnvRef) {continue;}}diff --git a/api/server/routes/files/files.js b/api/server/routes/files/files.jsindex 4176642a71..a43c184e50 100644--- a/api/server/routes/files/files.js+++ b/api/server/routes/files/files.js@@ -2,6 +2,7 @@ const fs = require('fs').promises;const express = require('express');const { logger, SystemCapabilities } = require('@librechat/data-schemas');const {+ logAxiosError,refreshS3FileUrls,resolveUploadErrorMessage,verifyAgentUploadPermission,@@ -309,12 +310,26 @@ router.get('/code/download/:session_id/:fileId', async (req, res) => {return res.status(501).send('Not Implemented');}+ /* Code-output downloads are always user-private — `processCodeOutput`+ * persists every code-execution artifact under+ * `metadata.codeEnvRef.kind === 'user'` regardless of which skill+ * the run invoked. Pass `kind: 'user'` + `id: <userId>` so codeapi's+ * `sessionAuth` resolves the matching `<tenant>:user:<userId>`+ * sessionKey; without these query params it 400s with+ * "kind must be one of: skill, agent, user". *//** @type {AxiosResponse<ReadableStream> | undefined} */- const response = await getDownloadStream(`${session_id}/${fileId}`);+ const response = await getDownloadStream(`${session_id}/${fileId}`, {+ kind: 'user',+ id: req.user.id,+ });res.set(response.headers);response.data.pipe(res);} catch (error) {- logger.error('Error downloading file:', error);+ /* `logAxiosError` redacts buffer/stream response bodies — without+ * it, a stream-typed axios failure dumps the entire `Readable`'s+ * internal state (megabytes of socket + readableState) into the+ * log line. Plain `logger.error(error)` would do that here. */+ logAxiosError({ message: 'Error downloading code-output file', error });res.status(500).send('Error downloading file');}});diff --git a/api/server/services/Files/Code/__tests__/process-traversal.spec.js b/api/server/services/Files/Code/__tests__/process-traversal.spec.jsindex 7412c4a28a..751db31bc2 100644--- a/api/server/services/Files/Code/__tests__/process-traversal.spec.js+++ b/api/server/services/Files/Code/__tests__/process-traversal.spec.js@@ -40,6 +40,15 @@ jest.mock('@librechat/api', () => {* inline (non-finalize) path so existing assertions on a single* createFile call hold. */hasOfficeHtmlPath: jest.fn(() => false),+ /* Identity-helper stub mirroring `packages/api/src/files/code/identity.ts`.+ * `processCodeOutput` calls this for every output download URL;+ * traversal cases don't care about the query shape, just that it+ * returns something concatable. */+ buildCodeEnvDownloadQuery: jest.fn(({ kind, id, version }) => {+ const params = new URLSearchParams({ kind, id });+ if (version != null) params.set('version', String(version));+ return `?${params.toString()}`;+ }),codeServerHttpAgent: new http.Agent({ keepAlive: false }),codeServerHttpsAgent: new https.Agent({ keepAlive: false }),};diff --git a/api/server/services/Files/Code/crud.js b/api/server/services/Files/Code/crud.jsindex 6b4e58d89b..cb25f351ec 100644--- a/api/server/services/Files/Code/crud.js+++ b/api/server/services/Files/Code/crud.js@@ -7,6 +7,8 @@ const {createAxiosInstance,codeServerHttpAgent,codeServerHttpsAgent,+ appendCodeEnvFileIdentity,+ buildCodeEnvDownloadQuery,} = require('@librechat/api');const axios = createAxiosInstance();@@ -16,16 +18,22 @@ const MAX_FILE_SIZE = 150 * 1024 * 1024;/*** Retrieves a download stream for a specified file.* @param {string} fileIdentifier - The identifier for the file (e.g., "session_id/fileId").+ * @param {{ kind: 'skill' | 'agent' | 'user'; id: string; version?: number }} identity+ * Resource identity required by codeapi's `sessionAuth` to derive the+ * matching sessionKey. For code-output downloads this is always+ * `kind: 'user', id: <userId>`; for skill/agent re-downloads pass+ * the kind+id (+version for skill) from the file's `metadata.codeEnvRef`.* @returns {Promise<AxiosResponse>} A promise that resolves to a readable stream of the file content.* @throws {Error} If there's an error during the download process.*/-async function getCodeOutputDownloadStream(fileIdentifier) {+async function getCodeOutputDownloadStream(fileIdentifier, identity) {try {const baseURL = getCodeBaseURL();+ const query = buildCodeEnvDownloadQuery(identity);/** @type {import('axios').AxiosRequestConfig} */const options = {method: 'get',- url: `${baseURL}/download/${fileIdentifier}`,+ url: `${baseURL}/download/${fileIdentifier}${query}`,responseType: 'stream',headers: {'User-Agent': 'LibreChat/1.0',@@ -49,20 +57,31 @@ async function getCodeOutputDownloadStream(fileIdentifier) {/*** Uploads a file to the Code Environment server.+ *+ * `kind`/`id`/`version?` are required so codeapi can route the upload to+ * the correct sessionKey bucket — `<tenant>:<kind>:<id>[:v:<version>]`+ * for shared kinds, `<tenant>:user:<authContext.userId>` for `user`.+ * Without these, codeapi falls back to user-scoped bucketing regardless+ * of the resource the file belongs to, so skill-cache invalidation+ * (driven by the version bump on edit) never fires. See codeapi #1455.+ ** @param {Object} params - The params object.* @param {ServerRequest} params.req - The request object from Express. It should have a `user` property with an `id` representing the user* @param {import('fs').ReadStream | import('stream').Readable} params.stream - The read stream for the file.* @param {string} params.filename - The name of the file.- * @param {string} [params.entity_id] - Optional entity ID for the file.- * @returns {Promise<string>}+ * @param {'skill' | 'agent' | 'user'} params.kind - Resource kind that owns this file's storage session.+ * @param {string} params.id - Resource id (skillId / agentId / userId). Codeapi+ * ignores this for `kind: 'user'` (auth context provides userId), but it's+ * sent uniformly for shape symmetry with the discriminated union.+ * @param {number} [params.version] - Required when `kind === 'skill'`; absent otherwise.+ * @returns {Promise<{ storage_session_id: string; file_id: string }>}+ * The codeapi storage location of the uploaded file.* @throws {Error} If there's an error during the upload process.*/-async function uploadCodeEnvFile({ req, stream, filename, entity_id = '' }) {+async function uploadCodeEnvFile({ req, stream, filename, kind, id, version }) {try {const form = new FormData();- if (entity_id.length > 0) {- form.append('entity_id', entity_id);- }+ appendCodeEnvFileIdentity(form, { kind, id, version });appendCodeEnvFile(form, stream, filename);const baseURL = getCodeBaseURL();@@ -83,18 +102,16 @@ async function uploadCodeEnvFile({ req, stream, filename, entity_id = '' }) {const response = await axios.post(`${baseURL}/upload`, form, options);- /** @type {{ message: string; session_id: string; files: Array<{ fileId: string; filename: string }> }} */+ /** @type {{ message: string; storage_session_id: string; files: Array<{ fileId: string; filename: string }> }} */const result = response.data;if (result.message !== 'success') {throw new Error(`Error uploading file: ${result.message}`);}- const fileIdentifier = `${result.session_id}/${result.files[0].fileId}`;- if (entity_id.length === 0) {- return fileIdentifier;- }-- return `${fileIdentifier}?entity_id=${entity_id}`;+ return {+ storage_session_id: result.storage_session_id,+ file_id: result.files[0].fileId,+ };} catch (error) {throw new Error(logAxiosError({@@ -109,25 +126,28 @@ async function uploadCodeEnvFile({ req, stream, filename, entity_id = '' }) {* Uploads multiple files to the code execution environment in a single request.* Uses the /upload/batch endpoint which shares one session_id across all files.*+ * `kind`/`id`/`version?` carry the resource identity for codeapi's sessionKey+ * derivation — see `uploadCodeEnvFile` for the full motivation.+ ** @param {object} params* @param {import('express').Request & { user: { id: string } }} params.req - The request object.* @param {Array<{ stream: NodeJS.ReadableStream; filename: string }>} params.files - Files to upload.- * @param {string} [params.entity_id] - Optional entity ID.+ * @param {'skill' | 'agent' | 'user'} params.kind - Resource kind that owns the batch's storage session.+ * @param {string} params.id - Resource id (skillId / agentId / userId).+ * @param {number} [params.version] - Required when `kind === 'skill'`; absent otherwise.* @param {boolean} [params.read_only] - When true, codeapi tags every file in* the batch as infrastructure (e.g. skill files). The flag is persisted as* MinIO object metadata (`X-Amz-Meta-Read-Only`) and travels with the file* through subsequent download/walk passes — sandboxed-code modifications* are dropped on the floor and the original ref is echoed back as* `inherited: true`, never as a generated artifact.- * @returns {Promise<{ session_id: string; files: Array<{ fileId: string; filename: string }> }>}+ * @returns {Promise<{ storage_session_id: string; files: Array<{ fileId: string; filename: string }> }>}* @throws {Error} If the batch upload fails entirely.*/-async function batchUploadCodeEnvFiles({ req, files, entity_id = '', read_only = false }) {+async function batchUploadCodeEnvFiles({ req, files, kind, id, version, read_only = false }) {try {const form = new FormData();- if (entity_id.length > 0) {- form.append('entity_id', entity_id);- }+ appendCodeEnvFileIdentity(form, { kind, id, version });if (read_only) {form.append('read_only', 'true');}@@ -153,12 +173,12 @@ async function batchUploadCodeEnvFiles({ req, files, entity_id = '', read_only =const response = await axios.post(`${baseURL}/upload/batch`, form, options);- /** @type {{ message: string; session_id: string; files: Array<{ status: string; fileId?: string; filename: string; error?: string }>; succeeded: number; failed: number }} */+ /** @type {{ message: string; storage_session_id: string; files: Array<{ status: string; fileId?: string; filename: string; error?: string }>; succeeded: number; failed: number }} */const result = response.data;if (!result ||typeof result !== 'object' ||- !result.session_id ||+ !result.storage_session_id ||!Array.isArray(result.files)) {throw new Error(`Unexpected batch upload response: ${JSON.stringify(result).slice(0, 200)}`);@@ -179,7 +199,7 @@ async function batchUploadCodeEnvFiles({ req, files, entity_id = '', read_only =.filter((f) => f.status === 'success' && f.fileId).map((f) => ({ fileId: f.fileId, filename: f.filename }));- return { session_id: result.session_id, files: successFiles };+ return { storage_session_id: result.storage_session_id, files: successFiles };} catch (error) {throw new Error(logAxiosError({@@ -190,4 +210,8 @@ async function batchUploadCodeEnvFiles({ req, files, entity_id = '', read_only =}}-module.exports = { getCodeOutputDownloadStream, uploadCodeEnvFile, batchUploadCodeEnvFiles };+module.exports = {+ getCodeOutputDownloadStream,+ uploadCodeEnvFile,+ batchUploadCodeEnvFiles,+};diff --git a/api/server/services/Files/Code/crud.spec.js b/api/server/services/Files/Code/crud.spec.jsindex 487ae56786..a84689d8bf 100644--- a/api/server/services/Files/Code/crud.spec.js+++ b/api/server/services/Files/Code/crud.spec.js@@ -9,6 +9,26 @@ jest.mock('@librechat/agents', () => ({getCodeBaseURL: jest.fn(() => 'https://code-api.example.com'),}));+/* Inline the identity helpers' validation rules instead of pulling+ * them through `@librechat/api`'s root barrel (which has init-time+ * provider-config side effects that don't matter here) or its leaf+ * module (the package's `exports` field only surfaces the root).+ * The real implementation lives in `packages/api/src/files/code/identity.ts`+ * and has its own dedicated `identity.spec.ts` covering the validation+ * matrix; this stub just mirrors enough behavior for the surrounding+ * crud tests to exercise the upload/download flow. */+const VALID_KINDS = new Set(['skill', 'agent', 'user']);+const validateIdentity = ({ kind, id, version }, label) => {+ if (!kind || !VALID_KINDS.has(kind)) throw new Error(`${label}: invalid kind "${kind}"`);+ if (!id) throw new Error(`${label}: missing id for kind "${kind}"`);+ if (kind === 'skill' && version == null) {+ throw new Error(`${label}: kind "skill" requires a numeric version`);+ }+ if (kind !== 'skill' && version != null) {+ throw new Error(`${label}: version is only valid for kind "skill"`);+ }+};+jest.mock('@librechat/api', () => {const http = require('http');const https = require('https');@@ -16,6 +36,18 @@ jest.mock('@librechat/api', () => {appendCodeEnvFile: jest.fn((form, stream, filename) => {form.append('file', stream, { filename });}),+ appendCodeEnvFileIdentity: jest.fn((form, identity) => {+ validateIdentity(identity, 'appendCodeEnvFileIdentity');+ form.append('kind', identity.kind);+ form.append('id', identity.id);+ if (identity.version != null) form.append('version', String(identity.version));+ }),+ buildCodeEnvDownloadQuery: jest.fn((identity) => {+ validateIdentity(identity, 'buildCodeEnvDownloadQuery');+ const params = new URLSearchParams({ kind: identity.kind, id: identity.id });+ if (identity.version != null) params.set('version', String(identity.version));+ return `?${params.toString()}`;+ }),logAxiosError: jest.fn(({ message }) => message),createAxiosInstance: jest.fn(() => mockAxios),codeServerHttpAgent: new http.Agent({ keepAlive: false }),@@ -32,11 +64,17 @@ describe('Code CRUD', () => {});describe('getCodeOutputDownloadStream', () => {+ /* Code-output downloads always carry `kind: 'user'` + `id: <userId>`+ * — codeapi's `sessionAuth` rejects without them post-Phase C. The+ * fixture mirrors what `processCodeOutput` and the `/code/download`+ * route pass in production. */+ const userIdentity = { kind: 'user', id: 'user-123' };+it('should pass dedicated keepAlive:false agents to axios', async () => {const mockResponse = { data: Readable.from(['chunk']) };mockAxios.mockResolvedValue(mockResponse);- await getCodeOutputDownloadStream('session-1/file-1');+ await getCodeOutputDownloadStream('session-1/file-1', userIdentity);const callConfig = mockAxios.mock.calls[0][0];expect(callConfig.httpAgent).toBe(codeServerHttpAgent);@@ -50,18 +88,52 @@ describe('Code CRUD', () => {it('should request stream response from the correct URL', async () => {mockAxios.mockResolvedValue({ data: Readable.from(['chunk']) });- await getCodeOutputDownloadStream('session-1/file-1');+ await getCodeOutputDownloadStream('session-1/file-1', userIdentity);const callConfig = mockAxios.mock.calls[0][0];- expect(callConfig.url).toBe('https://code-api.example.com/download/session-1/file-1');+ /* URL carries `?kind=user&id=<userId>` so codeapi's `sessionAuth`+ * can reconstruct the matching `<tenant>:user:<userId>` sessionKey+ * (Phase C / option α). */+ expect(callConfig.url).toBe(+ 'https://code-api.example.com/download/session-1/file-1?kind=user&id=user-123',+ );expect(callConfig.responseType).toBe('stream');expect(callConfig.timeout).toBe(15000);});+ it('forwards skill identity (kind/id/version) when re-downloading a primed skill file', async () => {+ mockAxios.mockResolvedValue({ data: Readable.from(['chunk']) });++ await getCodeOutputDownloadStream('session-2/file-x', {+ kind: 'skill',+ id: 'skill-abc',+ version: 7,+ });++ const callConfig = mockAxios.mock.calls[0][0];+ expect(callConfig.url).toBe(+ 'https://code-api.example.com/download/session-2/file-x?kind=skill&id=skill-abc&version=7',+ );+ });++ it('rejects skill identity without a version (mirrors codeapi validator)', async () => {+ await expect(+ getCodeOutputDownloadStream('s/f', { kind: 'skill', id: 'skill-abc' }),+ ).rejects.toThrow(/skill.*version/);+ expect(mockAxios).not.toHaveBeenCalled();+ });++ it('rejects unknown kind without dispatching to codeapi', async () => {+ await expect(getCodeOutputDownloadStream('s/f', { kind: 'system', id: 'x' })).rejects.toThrow(+ /invalid kind/,+ );+ expect(mockAxios).not.toHaveBeenCalled();+ });+it('should throw on network error', async () => {mockAxios.mockRejectedValue(new Error('ECONNREFUSED'));- await expect(getCodeOutputDownloadStream('s/f')).rejects.toThrow();+ await expect(getCodeOutputDownloadStream('s/f', userIdentity)).rejects.toThrow();});});@@ -70,13 +142,15 @@ describe('Code CRUD', () => {req: { user: { id: 'user-123' } },stream: Readable.from(['file-content']),filename: 'data.csv',+ kind: 'user',+ id: 'user-123',};it('should pass dedicated keepAlive:false agents to axios', async () => {mockAxios.post.mockResolvedValue({data: {message: 'success',- session_id: 'sess-1',+ storage_session_id: 'sess-1',files: [{ fileId: 'fid-1', filename: 'data.csv' }],},});@@ -96,7 +170,7 @@ describe('Code CRUD', () => {mockAxios.post.mockResolvedValue({data: {message: 'success',- session_id: 'sess-1',+ storage_session_id: 'sess-1',files: [{ fileId: 'fid-1', filename: 'data.csv' }],},});@@ -107,35 +181,106 @@ describe('Code CRUD', () => {expect(callConfig.timeout).toBe(120000);});- it('should return fileIdentifier on success', async () => {+ it('should return { storage_session_id, file_id } on success', async () => {mockAxios.post.mockResolvedValue({data: {message: 'success',- session_id: 'sess-1',+ storage_session_id: 'sess-1',files: [{ fileId: 'fid-1', filename: 'data.csv' }],},});const result = await uploadCodeEnvFile(baseUploadParams);- expect(result).toBe('sess-1/fid-1');+ expect(result).toEqual({ storage_session_id: 'sess-1', file_id: 'fid-1' });});- it('should append entity_id query param when provided', async () => {- mockAxios.post.mockResolvedValue({+ /* Phase C / option α (codeapi #1455): the upload wire carries the+ * resource identity codeapi uses for sessionKey derivation. Without+ * these on the form, codeapi falls back to user bucketing for every+ * upload and skill-cache invalidation never fires. Validation runs+ * client-side too so a bad caller fails fast instead of round-tripping+ * a 400. */+ describe('codeapi resource identity (kind/id/version)', () => {+ const FormData = require('form-data');+ const successResponse = {data: {message: 'success',- session_id: 'sess-1',+ storage_session_id: 'sess-1',files: [{ fileId: 'fid-1', filename: 'data.csv' }],},+ };+ let appendSpy;++ beforeEach(() => {+ /* Spying on the prototype lets us assert form fields without+ * materializing the multipart body — `form.getBuffer()` would+ * fail on the file-stream entry, but we don't care about the+ * stream here, only the identity fields that ride beside it. */+ appendSpy = jest.spyOn(FormData.prototype, 'append');});- const result = await uploadCodeEnvFile({ ...baseUploadParams, entity_id: 'agent-42' });- expect(result).toBe('sess-1/fid-1?entity_id=agent-42');+ afterEach(() => {+ appendSpy.mockRestore();+ });++ const fieldsAppended = () =>+ appendSpy.mock.calls+ .filter((call) => typeof call[1] === 'string' || typeof call[1] === 'number')+ .reduce((acc, [name, value]) => ({ ...acc, [name]: value }), {});++ it('forwards kind, id, and (when skill) version on the multipart form', async () => {+ mockAxios.post.mockResolvedValue(successResponse);++ await uploadCodeEnvFile({+ ...baseUploadParams,+ kind: 'skill',+ id: 'skill-42',+ version: 7,+ });++ expect(fieldsAppended()).toEqual({ kind: 'skill', id: 'skill-42', version: '7' });+ });++ it('omits version on the form for non-skill kinds', async () => {+ mockAxios.post.mockResolvedValue(successResponse);++ await uploadCodeEnvFile({ ...baseUploadParams, kind: 'agent', id: 'agent-9' });++ const fields = fieldsAppended();+ expect(fields).toEqual({ kind: 'agent', id: 'agent-9' });+ expect(fields).not.toHaveProperty('version');+ });++ it('rejects unknown kind without dispatching to codeapi', async () => {+ await expect(+ uploadCodeEnvFile({ ...baseUploadParams, kind: 'system', id: 'x' }),+ ).rejects.toThrow(/invalid kind/);+ expect(mockAxios.post).not.toHaveBeenCalled();+ });++ it('rejects skill upload without a version (mirrors codeapi validator)', async () => {+ await expect(+ uploadCodeEnvFile({ ...baseUploadParams, kind: 'skill', id: 'skill-42' }),+ ).rejects.toThrow(/skill.*version/);+ expect(mockAxios.post).not.toHaveBeenCalled();+ });++ it('rejects version on non-skill kinds (mirrors codeapi validator)', async () => {+ await expect(+ uploadCodeEnvFile({+ ...baseUploadParams,+ kind: 'agent',+ id: 'agent-9',+ version: 3,+ }),+ ).rejects.toThrow(/version.*skill/);+ expect(mockAxios.post).not.toHaveBeenCalled();+ });});it('should throw when server returns non-success message', async () => {mockAxios.post.mockResolvedValue({- data: { message: 'quota_exceeded', session_id: 's', files: [] },+ data: { message: 'quota_exceeded', storage_session_id: 's', files: [] },});await expect(uploadCodeEnvFile(baseUploadParams)).rejects.toThrow('quota_exceeded');diff --git a/api/server/services/Files/Code/process.js b/api/server/services/Files/Code/process.jsindex a94981f721..2839d08c5a 100644--- a/api/server/services/Files/Code/process.js+++ b/api/server/services/Files/Code/process.js@@ -16,6 +16,7 @@ const {extractCodeArtifactText,getExtractedTextFormat,getStorageMetadata,+ buildCodeEnvDownloadQuery,} = require('@librechat/api');const {Tools,@@ -286,7 +287,7 @@ const runPreviewFinalize = ({ finalize, fileId, previewRevision, onResolved }) =/*** Process code execution output files — downloads and saves both images* and non-image files. All files are saved to local storage with- * `fileIdentifier` metadata for code env re-upload.+ * `codeEnvRef` metadata for code env re-upload.** Returns a two-part shape so callers can ship the attachment to the* client immediately and run preview extraction in the background:@@ -334,9 +335,15 @@ const processCodeOutput = async ({try {const formattedDate = currentDate.toISOString();+ /* Code-output files are always user-private — no skill execution+ * produces a skill-scoped output bucket. The download URL must+ * carry `?kind=user&id=<userId>` so codeapi's `sessionAuth`+ * resolves the matching `<tenant>:user:<userId>` sessionKey. See+ * codeapi #1455 / Phase C. */+ const downloadQuery = buildCodeEnvDownloadQuery({ kind: 'user', id: req.user.id });const response = await axios({method: 'get',- url: `${baseURL}/download/${session_id}/${id}`,+ url: `${baseURL}/download/${session_id}/${id}${downloadQuery}`,responseType: 'arraybuffer',headers: {'User-Agent': 'LibreChat/1.0',@@ -366,7 +373,15 @@ const processCodeOutput = async ({};}- const fileIdentifier = `${session_id}/${id}`;+ /* Code-output files belong to the user who ran the execution.+ * SessionKey on codeapi will be `<tenant>:user:<userId>` for these,+ * so cache and access stay user-private. */+ const codeEnvRef = {+ kind: 'user',+ id: req.user.id,+ storage_session_id: session_id,+ file_id: id,+ };/* `safeName` keeps the directory structure (`a/b/file.txt` -> `a/b/file.txt`)* so the next prime() can place the file at the same nested path in the@@ -444,7 +459,7 @@ const processCodeOutput = async ({updatedAt: formattedDate,source: appConfig.fileStrategy,context: FileContext.execute_code,- metadata: { fileIdentifier },+ metadata: { codeEnvRef },};await createFile(file, true);return { file: Object.assign(file, { messageId, toolCallId }) };@@ -542,7 +557,7 @@ const processCodeOutput = async ({tenantId: req.user.tenantId,bytes: buffer.length,updatedAt: formattedDate,- metadata: { fileIdentifier },+ metadata: { codeEnvRef },source: appConfig.fileStrategy,context: FileContext.execute_code,usage: isUpdate ? (claimed.usage ?? 0) + 1 : 1,@@ -651,26 +666,31 @@ function checkIfActive(dateString) {/*** Retrieves the `lastModified` time string for a specified file from Code Execution Server.*- * @param {string} fileIdentifier - The identifier for the file (e.g., "session_id/fileId").+ * @param {import('librechat-data-provider').CodeEnvRef} ref - Typed pointer+ * into codeapi storage. Carries kind/id/storage_session_id/file_id;+ * codeapi resolves the sessionKey from the request's auth context.** @returns {Promise<string|null>}* A promise that resolves to the `lastModified` time string of the file if successful, or null if there is an* error in initialization or fetching the info.*/-async function getSessionInfo(fileIdentifier) {+async function getSessionInfo(ref) {try {const baseURL = getCodeBaseURL();- const [path, queryString] = fileIdentifier.split('?');- const [session_id, fileId] = path.split('/');- let queryParams = {};- if (queryString) {- queryParams = Object.fromEntries(new URLSearchParams(queryString).entries());- }-+ /* `/sessions/.../objects/...` is gated by codeapi's `sessionAuth`+ * middleware (post-Phase C). The middleware reconstructs the+ * sessionKey from the URL query (`kind`/`id`/`version?`) plus the+ * requester's auth context, then matches it against the cached+ * sessionKey on the storage bucket. We have the full `codeEnvRef`+ * here, so pass kind+id (+version when skill) directly. */+ const query = buildCodeEnvDownloadQuery({+ kind: ref.kind,+ id: ref.id,+ ...(ref.kind === 'skill' ? { version: ref.version } : {}),+ });const response = await axios({method: 'get',- url: `${baseURL}/sessions/${session_id}/objects/${fileId}`,- params: queryParams,+ url: `${baseURL}/sessions/${ref.storage_session_id}/objects/${ref.file_id}${query}`,headers: {'User-Agent': 'LibreChat/1.0',},@@ -706,6 +726,15 @@ const primeFiles = async (options) => {const agentResourceIds = new Set(file_ids);const resourceFiles = tool_resources?.[EToolResources.execute_code]?.files ?? [];+ /* Step 1 of the priming trace: input volume. Pair with the+ * per-file `[primeCodeFiles] file=...` lines and the final+ * `[primeCodeFiles] returned=...` line below to locate which+ * layer drops a file the sandbox doesn't end up seeing. */+ logger.debug(+ `[primeCodeFiles] in: file_ids=${file_ids.length} resourceFiles=${resourceFiles.length}`,+ { agentId, file_ids, resourceFileIds: resourceFiles.map((f) => f?.file_id) },+ );+// Get all files firstconst allFiles = (await getFiles({ file_id: { $in: file_ids } }, null, { text: 0 })) ?? [];@@ -728,146 +757,195 @@ const primeFiles = async (options) => {const sessions = new Map();let toolContext = '';+ /* Per-file path counters — emitted at the bottom so a single+ * grep on `[primeCodeFiles]` shows the input volume, the per-file+ * paths taken, and the final dispatch summary in one trace. */+ let skippedNoRef = 0;+ let reuploadFailures = 0;+for (let i = 0; i < dbFiles.length; i++) {const file = dbFiles[i];if (!file) {continue;}- if (file.metadata.fileIdentifier) {- const [path, queryString] = file.metadata.fileIdentifier.split('?');- const [session_id, id] = path.split('/');+ const ref = file.metadata?.codeEnvRef;+ if (!ref) {+ skippedNoRef += 1;+ logger.debug(+ `[primeCodeFiles] file=${file.file_id} path=skip reason=no-codeenvref filename=${file.filename}`,+ );+ continue;+ }+ const session_id = ref.storage_session_id;+ const id = ref.file_id;- let queryParams = {};- if (queryString) {- queryParams = Object.fromEntries(new URLSearchParams(queryString).entries());+ /**+ * `pushFile` accepts optional overrides so the reupload path can+ * push the FRESH `(storage_session_id, file_id)` from the new+ * `codeEnvRef`. Without these overrides, the closure would+ * capture the stale pre-reupload refs from the outer loop and+ * the in-memory `files` array (now consumed by+ * `buildInitialToolSessions` to seed `Graph.sessions`) would+ * point at a sandbox object that no longer exists. The DB record+ * gets the new ref via `updateFile`, but the seed would still+ * inject the old one — bash_tool / read_file would 404 trying to+ * mount the file until the next turn re-reads metadata.+ *+ * `kind`, `id`, `version` are preserved on the in-memory ref so+ * codeapi can resolve sessionKey per-file (kind switch ++ * tenant prefix from auth context).+ */+ const pushFile = (overrideSessionId, overrideId) => {+ if (!toolContext) {+ toolContext = `- Note: The following files are available in the "${Tools.execute_code}" tool environment:`;}- /**- * `pushFile` accepts optional overrides so the reupload path can- * push the FRESH `(session_id, id, entity_id)` parsed off the new- * `fileIdentifier`. Without these overrides, the closure would- * capture the stale pre-reupload refs from the outer loop and- * the in-memory `files` array (now consumed by- * `buildInitialToolSessions` to seed `Graph.sessions`) would- * point at a sandbox object that no longer exists. The DB record- * gets the new identifier via `updateFile`, but the seed would- * still inject the old one — bash_tool / read_file would 404- * trying to mount the file until the next turn re-reads metadata.- *- * `entity_id` is forwarded so codeapi can resolve sessionKey- * per-file, allowing one execute to mix files uploaded under- * different entities (e.g. a skill bundle plus a user attachment).- */- const pushFile = (overrideSessionId, overrideId, overrideEntityId) => {- if (!toolContext) {- toolContext = `- Note: The following files are available in the "${Tools.execute_code}" tool environment:`;- }-- let fileSuffix = '';- if (!agentResourceIds.has(file.file_id)) {- fileSuffix =- file.context === FileContext.execute_code- ? ' (from previous code execution)'- : ' (attached by user)';- }-- const entity_id = overrideEntityId ?? queryParams.entity_id;-- /* Surface the preview lifecycle so the LLM knows when a- * prior-turn artifact's rich preview didn't materialize. The- * file blob is always available (`processCodeOutput` persists- * it before returning), so the model can still tell the user- * "you can download it" even when the preview never resolved.- * Absent status means legacy or non-office — render normally. */- let previewSuffix = '';- if (file.status === 'pending') {- previewSuffix = ' (preview not yet generated)';- } else if (file.status === 'failed') {- previewSuffix = file.previewError- ? ` (preview unavailable: ${file.previewError})`- : ' (preview unavailable)';- }-- toolContext += `\n\t- /mnt/data/${file.filename}${fileSuffix}${previewSuffix}`;- files.push({- id: overrideId ?? id,- session_id: overrideSessionId ?? session_id,- name: file.filename,- ...(entity_id ? { entity_id } : {}),- });- };-- if (sessions.has(session_id)) {- pushFile();- continue;+ let fileSuffix = '';+ if (!agentResourceIds.has(file.file_id)) {+ fileSuffix =+ file.context === FileContext.execute_code+ ? ' (from previous code execution)'+ : ' (attached by user)';}- const reuploadFile = async () => {- try {- const { getDownloadStream } = getStrategyFunctions(file.source);- const { handleFileUpload: uploadCodeEnvFile } = getStrategyFunctions(- FileSources.execute_code,- );- const stream = await getDownloadStream(options.req, file.filepath);- const fileIdentifier = await uploadCodeEnvFile({- req: options.req,- stream,- filename: file.filename,- entity_id: queryParams.entity_id,- });-- // Preserve existing metadata when adding fileIdentifier- const updatedMetadata = {- ...file.metadata, // Preserve existing metadata (like S3 storage info)- fileIdentifier, // Add fileIdentifier- };-- await updateFile({- file_id: file.file_id,- metadata: updatedMetadata,- });- /**- * Parse the FRESH fileIdentifier returned by the reupload and- * route it through both the dedupe Map and the in-memory- * `files` list. The original `(session_id, id)` parsed at the- * top of this iteration refer to the old, expired/missing- * sandbox object — using them here would silently re-introduce- * the bug `Graph.sessions` seeding is supposed to fix.- *- * `entity_id` survives the round-trip: the upload was tagged- * with `queryParams.entity_id` above, so the new identifier- * carries the same scope.- */- const [newPath, newQuery] = fileIdentifier.split('?');- const [newSessionId, newId] = newPath.split('/');- const newQueryParams = newQuery- ? Object.fromEntries(new URLSearchParams(newQuery).entries())- : {};- sessions.set(newSessionId, true);- pushFile(newSessionId, newId, newQueryParams.entity_id);- } catch (error) {- logger.error(- `Error re-uploading file ${id} in session ${session_id}: ${error.message}`,- error,- );- }- };- const uploadTime = await getSessionInfo(file.metadata.fileIdentifier);- if (!uploadTime) {- logger.warn(`Failed to get upload time for file ${id} in session ${session_id}`);- await reuploadFile();- continue;- }- if (!checkIfActive(uploadTime)) {- await reuploadFile();- continue;+ /* Surface the preview lifecycle so the LLM knows when a+ * prior-turn artifact's rich preview didn't materialize. The+ * file blob is always available (`processCodeOutput` persists+ * it before returning), so the model can still tell the user+ * "you can download it" even when the preview never resolved.+ * Absent status means legacy or non-office — render normally. */+ let previewSuffix = '';+ if (file.status === 'pending') {+ previewSuffix = ' (preview not yet generated)';+ } else if (file.status === 'failed') {+ previewSuffix = file.previewError+ ? ` (preview unavailable: ${file.previewError})`+ : ' (preview unavailable)';}- sessions.set(session_id, true);++ toolContext += `\n\t- /mnt/data/${file.filename}${fileSuffix}${previewSuffix}`;+ /* `id` is the storage file_id (drives codeapi's upload-key+ * existence check), `resource_id` is the entity that owns+ * the storage session (drives sessionKey re-derivation). For+ * code-output files this is `kind: 'user'` and `resource_id`+ * is informational (codeapi ignores it for user kind), but+ * we still send it for shape uniformity with shared kinds. */+ files.push({+ id: overrideId ?? id,+ resource_id: ref.id,+ storage_session_id: overrideSessionId ?? session_id,+ name: file.filename,+ kind: ref.kind,+ ...(ref.kind === 'skill' ? { version: ref.version } : {}),+ });+ };++ if (sessions.has(session_id)) {+ logger.debug(+ `[primeCodeFiles] file=${file.file_id} path=cache-hit-by-session storage_session_id=${session_id}`,+ );pushFile();+ continue;+ }++ const reuploadFile = async () => {+ try {+ const { getDownloadStream } = getStrategyFunctions(file.source);+ const { handleFileUpload: uploadCodeEnvFile } = getStrategyFunctions(+ FileSources.execute_code,+ );+ const stream = await getDownloadStream(options.req, file.filepath);+ /* Reupload preserves the resource identity from the existing+ * ref so codeapi re-buckets under the same sessionKey shape+ * (skill stays skill, user stays user). Without this, a+ * skill-cache-miss reupload would land in the user bucket+ * and never re-shareable cross-user. */+ const uploaded = await uploadCodeEnvFile({+ req: options.req,+ stream,+ filename: file.filename,+ kind: ref.kind,+ id: ref.id,+ ...(ref.kind === 'skill' ? { version: ref.version } : {}),+ });++ /**+ * Use the FRESH `(storage_session_id, file_id)` from the+ * reupload response and route it through the dedupe Map, the+ * persisted record, and the in-memory `files` list. The+ * original ref captured at the top of this iteration refers+ * to the old, expired/missing sandbox object — using it here+ * would silently re-introduce the bug `Graph.sessions`+ * seeding is supposed to fix.+ *+ * `kind`, `id`, `version` survive the round-trip: the+ * upload preserves the resource identity, only the storage+ * pointer changes.+ */+ const newRef = {+ kind: ref.kind,+ id: ref.id,+ storage_session_id: uploaded.storage_session_id,+ file_id: uploaded.file_id,+ ...(ref.kind === 'skill' ? { version: ref.version } : {}),+ };++ const updatedMetadata = {+ ...file.metadata,+ codeEnvRef: newRef,+ };++ await updateFile({+ file_id: file.file_id,+ metadata: updatedMetadata,+ });+ sessions.set(newRef.storage_session_id, true);+ pushFile(newRef.storage_session_id, newRef.file_id);+ logger.debug(+ `[primeCodeFiles] file=${file.file_id} path=reupload-success ` ++ `oldSession=${session_id} newSession=${newRef.storage_session_id} newFileId=${newRef.file_id}`,+ );+ } catch (error) {+ reuploadFailures += 1;+ logger.error(+ `[primeCodeFiles] file=${file.file_id} path=reupload-failed session=${session_id}: ${error.message}`,+ error,+ );+ }+ };+ const uploadTime = await getSessionInfo(ref);+ if (!uploadTime) {+ logger.debug(+ `[primeCodeFiles] file=${file.file_id} path=reupload reason=no-uploadtime ` ++ `storage_session_id=${session_id}`,+ );+ await reuploadFile();+ continue;}+ if (!checkIfActive(uploadTime)) {+ logger.debug(+ `[primeCodeFiles] file=${file.file_id} path=reupload reason=stale ` ++ `uploadTime=${uploadTime} storage_session_id=${session_id}`,+ );+ await reuploadFile();+ continue;+ }+ sessions.set(session_id, true);+ logger.debug(+ `[primeCodeFiles] file=${file.file_id} path=fresh-active storage_session_id=${session_id}`,+ );+ pushFile();}+ /* Dispatch summary — emitted unconditionally so a single grep on+ * `[primeCodeFiles] out` always shows the final state, not only+ * the per-path trail leading up to it. */+ logger.debug(+ `[primeCodeFiles] out: returned=${files.length} ` ++ `skippedNoRef=${skippedNoRef} reuploadFailures=${reuploadFailures}`,+ );+return { files, toolContext };};diff --git a/api/server/services/Files/Code/process.spec.js b/api/server/services/Files/Code/process.spec.jsindex e816cde3fb..ea2cd29429 100644--- a/api/server/services/Files/Code/process.spec.js+++ b/api/server/services/Files/Code/process.spec.js@@ -85,6 +85,16 @@ jest.mock('@librechat/api', () => {* if a case needs to assert the 'html' value. */getExtractedTextFormat: (...args) => mockGetExtractedTextFormat(...args),getStorageMetadata: jest.fn(() => ({})),+ /* Identity helpers mirror codeapi's validator. The real impl+ * lives in `packages/api/src/files/code/identity.ts` with its+ * own dedicated `identity.spec.ts`; here we just stub the+ * download-query builder since `processCodeOutput` calls it on+ * every output download. */+ buildCodeEnvDownloadQuery: jest.fn(({ kind, id, version }) => {+ const params = new URLSearchParams({ kind, id });+ if (version != null) params.set('version', String(version));+ return `?${params.toString()}`;+ }),codeServerHttpAgent: new http.Agent({ keepAlive: false }),codeServerHttpsAgent: new https.Agent({ keepAlive: false }),};@@ -708,15 +718,66 @@ describe('Code Process', () => {});describe('metadata and file properties', () => {- it('should include fileIdentifier in metadata', async () => {+ it('should include codeEnvRef in metadata with kind: user', async () => {const smallBuffer = Buffer.alloc(100);mockAxios.mockResolvedValue({ data: smallBuffer });const { file: result } = await processCodeOutput(baseParams);expect(result.metadata).toEqual({- fileIdentifier: 'session-123/file-id-123',+ codeEnvRef: {+ kind: 'user',+ id: 'user-123',+ storage_session_id: 'session-123',+ file_id: 'file-id-123',+ },+ });+ });++ /* Phase C lock-in: outputs are ALWAYS user-scoped, never skill-scoped.+ * Even when an execution turn invoked a skill (so input files were+ * `kind: 'skill'` shared cross-user), the resulting output bucket+ * tags `kind: 'user'` with the requesting user's id. This prevents+ * cross-user leakage of artifacts a skill may have generated for+ * one user — each user gets their own output sessionKey on codeapi.+ *+ * Drift hazard: someone reading the simple user-derivation may+ * later think "we should respect input kind for outputs too" and+ * widen output scope to match input scope. This test pins the+ * intentional asymmetry so that change requires updating the test+ * (and re-reading the rationale). */+ it('outputs are user-scoped regardless of which skill the execution invoked', async () => {+ const smallBuffer = Buffer.alloc(100);+ mockAxios.mockResolvedValue({ data: smallBuffer });++ const userA = { ...mockReq, user: { id: 'user-A' } };+ const userB = { ...mockReq, user: { id: 'user-B' } };++ const { file: outputA } = await processCodeOutput({ ...baseParams, req: userA });+ const { file: outputB } = await processCodeOutput({ ...baseParams, req: userB });++ // Each user's output ref is keyed by their own user id. The+ // `id` field tracks the requesting user, never the skill.+ expect(outputA.metadata.codeEnvRef).toEqual({+ kind: 'user',+ id: 'user-A',+ storage_session_id: 'session-123',+ file_id: 'file-id-123',+ });+ expect(outputB.metadata.codeEnvRef).toEqual({+ kind: 'user',+ id: 'user-B',+ storage_session_id: 'session-123',+ file_id: 'file-id-123',});++ // No skill identity leaks into the output ref under any property.+ const refA = outputA.metadata.codeEnvRef;+ const refB = outputB.metadata.codeEnvRef;+ expect(refA.kind).not.toBe('skill');+ expect(refB.kind).not.toBe('skill');+ expect(refA).not.toHaveProperty('version');+ expect(refB).not.toHaveProperty('version');});it('should set correct context for code-generated files', async () => {@@ -934,7 +995,12 @@ describe('Code Process', () => {data: [{ name: 'sess/fid', lastModified: new Date().toISOString() }],});- await getSessionInfo('sess/fid', 'api-key');+ await getSessionInfo({+ kind: 'user',+ id: 'user-1',+ storage_session_id: 'sess',+ file_id: 'fid',+ });const callConfig = mockAxios.mock.calls[0][0];expect(callConfig.httpAgent).toBe(codeServerHttpAgent);@@ -1511,8 +1577,8 @@ describe('Code Process', () => {* `getStrategyFunctions(FileSources.execute_code)` for the code-env* upload — both go through the same factory in production.*/- function setupReuploadMocks(newFileIdentifier) {- const handleFileUpload = jest.fn().mockResolvedValue(newFileIdentifier);+ function setupReuploadMocks(newRef) {+ const handleFileUpload = jest.fn().mockResolvedValue(newRef);const getDownloadStream = jest.fn().mockResolvedValue('mock-stream');getStrategyFunctions.mockImplementation((source) => {if (source === 'execute_code') return { handleFileUpload };@@ -1526,7 +1592,7 @@ describe('Code Process', () => {return { handleFileUpload, getDownloadStream };}- it('seed receives FRESH session_id + id parsed off the new fileIdentifier on reupload', async () => {+ it('seed receives FRESH (storage_session_id, file_id) from the reupload response', async () => {const dbFile = {file_id: 'librechat-file-id',filename: 'sentinel.txt',@@ -1535,12 +1601,17 @@ describe('Code Process', () => {context: 'execute_code',metadata: {/* Stale sandbox ref — this is what `getSessionInfo` will 404 on. */- fileIdentifier: 'OLD_SESSION/OLD_ID',+ codeEnvRef: {+ kind: 'user',+ id: 'user-123',+ storage_session_id: 'OLD_SESSION',+ file_id: 'OLD_ID',+ },},};getFiles.mockResolvedValue([dbFile]);- setupReuploadMocks('NEW_SESSION/NEW_ID');+ setupReuploadMocks({ storage_session_id: 'NEW_SESSION', file_id: 'NEW_ID' });const result = await primeFiles({req: { user: { id: 'user-123', role: 'USER' } },@@ -1553,22 +1624,82 @@ describe('Code Process', () => {// The seed list (consumed by buildInitialToolSessions) MUST carry// the post-reupload ids — not the stale pre-reupload ones.expect(result.files).toEqual([- { id: 'NEW_ID', session_id: 'NEW_SESSION', name: 'sentinel.txt' },+ {+ id: 'NEW_ID',+ /* `resource_id` carries the codeEnvRef.id (= original+ * userId for kind: 'user'), threaded onto the in-memory+ * file ref for codeapi's sessionKey re-derivation. */+ resource_id: 'user-123',+ storage_session_id: 'NEW_SESSION',+ name: 'sentinel.txt',+ kind: 'user',+ },]);});- it('persists the new fileIdentifier on the DB record (existing behavior, regression-locked)', async () => {+ /* Phase C / option α (codeapi #1455): reupload preserves the+ * resource identity from the existing ref so codeapi re-buckets+ * under the same sessionKey shape. Without this, a skill-cache-miss+ * reupload lands in the user bucket and is no longer cross-user+ * shareable. */+ it('reupload forwards kind/id (and version when skill) from the existing ref', async () => {const dbFile = {file_id: 'librechat-file-id',filename: 'sentinel.txt',filepath: '/uploads/sentinel.txt',source: 'local',context: 'execute_code',- metadata: { fileIdentifier: 'OLD_SESSION/OLD_ID' },+ metadata: {+ codeEnvRef: {+ kind: 'skill',+ id: 'skill-99',+ storage_session_id: 'OLD_SESSION',+ file_id: 'OLD_ID',+ version: 4,+ },+ },};getFiles.mockResolvedValue([dbFile]);- setupReuploadMocks('NEW_SESSION/NEW_ID');+ const { handleFileUpload } = setupReuploadMocks({+ storage_session_id: 'NEW_SESSION',+ file_id: 'NEW_ID',+ });++ await primeFiles({+ req: { user: { id: 'user-123', role: 'USER' } },+ tool_resources: {+ execute_code: { file_ids: ['librechat-file-id'], files: [] },+ },+ agentId: 'agent-id',+ });++ expect(handleFileUpload).toHaveBeenCalledTimes(1);+ const uploadArgs = handleFileUpload.mock.calls[0][0];+ expect(uploadArgs.kind).toBe('skill');+ expect(uploadArgs.id).toBe('skill-99');+ expect(uploadArgs.version).toBe(4);+ });++ it('persists fresh codeEnvRef (kind/id preserved) on the DB record after reupload', async () => {+ const dbFile = {+ file_id: 'librechat-file-id',+ filename: 'sentinel.txt',+ filepath: '/uploads/sentinel.txt',+ source: 'local',+ context: 'execute_code',+ metadata: {+ codeEnvRef: {+ kind: 'user',+ id: 'user-123',+ storage_session_id: 'OLD_SESSION',+ file_id: 'OLD_ID',+ },+ },+ };+ getFiles.mockResolvedValue([dbFile]);++ setupReuploadMocks({ storage_session_id: 'NEW_SESSION', file_id: 'NEW_ID' });await primeFiles({req: { user: { id: 'user-123', role: 'USER' } },@@ -1581,10 +1712,62 @@ describe('Code Process', () => {expect(updateFile).toHaveBeenCalledWith(expect.objectContaining({file_id: 'librechat-file-id',- metadata: expect.objectContaining({ fileIdentifier: 'NEW_SESSION/NEW_ID' }),+ metadata: expect.objectContaining({+ codeEnvRef: {+ kind: 'user',+ id: 'user-123',+ storage_session_id: 'NEW_SESSION',+ file_id: 'NEW_ID',+ },+ }),}),);});++ it('reads codeEnvRef directly when present (skipping reupload)', async () => {+ const dbFile = {+ file_id: 'librechat-file-id',+ filename: 'sentinel.txt',+ filepath: '/uploads/sentinel.txt',+ source: 'local',+ context: 'execute_code',+ metadata: {+ codeEnvRef: {+ kind: 'user',+ id: 'user-123',+ storage_session_id: 'STRUCT_SESSION',+ file_id: 'STRUCT_ID',+ },+ },+ };+ getFiles.mockResolvedValue([dbFile]);+ filterFilesByAgentAccess.mockImplementation(({ files }) => Promise.resolve(files));+ // getSessionInfo returns a fresh timestamp so reupload is skipped.+ mockAxios.mockResolvedValue({ data: { lastModified: new Date().toISOString() } });++ const result = await primeFiles({+ req: { user: { id: 'user-123', role: 'USER' } },+ tool_resources: {+ execute_code: { file_ids: ['librechat-file-id'], files: [] },+ },+ agentId: 'agent-id',+ });++ expect(updateFile).not.toHaveBeenCalled();+ expect(result.files).toEqual([+ {+ id: 'STRUCT_ID',+ /* `resource_id` from the persisted codeEnvRef.id — for+ * `kind: 'user'` this is informational (codeapi derives+ * sessionKey from auth context) but threaded for shape+ * uniformity with shared kinds. */+ resource_id: 'user-123',+ storage_session_id: 'STRUCT_SESSION',+ name: 'sentinel.txt',+ kind: 'user',+ },+ ]);+ });});describe('primeFiles toolContext surfaces preview status to the LLM', () => {@@ -1606,7 +1789,14 @@ describe('Code Process', () => {filepath: `/uploads/${overrides.status ?? 'ready'}.xlsx`,source: 'local',context: 'execute_code',- metadata: { fileIdentifier: 'CURRENT_SESSION/CURRENT_ID' },+ metadata: {+ codeEnvRef: {+ kind: 'user',+ id: 'user-123',+ storage_session_id: 'CURRENT_SESSION',+ file_id: 'CURRENT_ID',+ },+ },...overrides,};}diff --git a/api/server/services/Files/process.js b/api/server/services/Files/process.jsindex 69b4a0b382..ea8ee14840 100644--- a/api/server/services/Files/process.js+++ b/api/server/services/Files/process.js@@ -569,13 +569,44 @@ const processAgentFileUpload = async ({ req, res, metadata }) => {}const { handleFileUpload: uploadCodeEnvFile } = getStrategyFunctions(FileSources.execute_code);const stream = fs.createReadStream(file.path);- const fileIdentifier = await uploadCodeEnvFile({+ /* Resource identity for codeapi's sessionKey:+ * - chat attachments (messageAttachment=true): `kind: 'user'`, codeapi+ * buckets under `<tenant>:user:<authContext.userId>` regardless of `id`.+ * - agent setup files (messageAttachment=false): `kind: 'agent'`, shared+ * per agent identity. `id` carries the agent id. */+ const codeKind = messageAttachment === true ? 'user' : 'agent';+ const codeId = messageAttachment === true ? req.user.id : agent_id;+ /* Upload under the same sanitized filename LC stores in its DB+ * (`fileInfo.filename` below uses `sanitizeFilename(originalname)`).+ * Codeapi/file_server use this as the on-disk name in the sandbox+ * — `/mnt/data/<filename>` — and `primeFiles`'s `toolContext` text+ * + `_injected_files.name` both reference `file.filename`. Sending+ * the unsanitized `file.originalname` here makes the sandbox path+ * (with spaces / special chars) drift from what LC tells the model+ * is available, causing FileNotFoundError on the first reference. */+ const sandboxFilename = sanitizeFilename(file.originalname);+ const uploaded = await uploadCodeEnvFile({req,stream,- filename: file.originalname,- entity_id,+ filename: sandboxFilename,+ kind: codeKind,+ id: codeId,});- fileInfoMetadata = { fileIdentifier };+ /* Persist under the structured `codeEnvRef` shape — the only key the+ * post-cutover schema (`metadata.codeEnvRef`) and downstream readers+ * (`primeFiles`, `getCodeFilesByIds`, `categorizeFileForToolResources`,+ * controller filtering) accept. Storing under the legacy+ * `fileIdentifier` key would be silently dropped by mongoose strict+ * mode and the file would lose its sandbox reference on subsequent+ * priming turns. */+ fileInfoMetadata = {+ codeEnvRef: {+ kind: codeKind,+ id: codeId,+ storage_session_id: uploaded.storage_session_id,+ file_id: uploaded.file_id,+ },+ };} else if (tool_resource === EToolResources.file_search) {const isFileSearchEnabled = await checkCapability(req, AgentCapabilities.file_search);if (!isFileSearchEnabled) {diff --git a/api/server/services/Files/process.spec.js b/api/server/services/Files/process.spec.jsindex 2bcea53058..99457522d4 100644--- a/api/server/services/Files/process.spec.js+++ b/api/server/services/Files/process.spec.js@@ -346,6 +346,128 @@ describe('processAgentFileUpload', () => {).resolves.not.toThrow();});});++ /* Phase C / option α regression: the upload must persist its sandbox+ * pointer under `metadata.codeEnvRef` (the post-cutover schema). The+ * legacy `metadata.fileIdentifier` key is silently stripped by mongoose+ * strict mode and downstream readers (`primeFiles`, `getCodeFilesByIds`,+ * `categorizeFileForToolResources`, controller filtering) only check+ * `codeEnvRef`. Storing under the legacy key would orphan the file —+ * priming would skip it on subsequent code-execution turns and the+ * sandbox copy would never re-mount. */+ describe('execute_code uploads persist codeEnvRef metadata', () => {+ const fs = require('fs');+ const { Readable } = require('stream');+ let createReadStreamSpy;++ beforeEach(() => {+ /* `processAgentFileUpload` opens the multer-staged temp file via+ * `fs.createReadStream`. The test fixture path doesn't exist, so+ * stub it to a tiny in-memory stream. */+ createReadStreamSpy = jest+ .spyOn(fs, 'createReadStream')+ .mockImplementation(() => Readable.from(Buffer.from('')));+ });++ afterEach(() => {+ createReadStreamSpy.mockRestore();+ });++ const setupCodeEnvUpload = (uploaded) => {+ /* `processAgentFileUpload` calls `getStrategyFunctions` twice:+ * once with `execute_code` for the codeapi upload, then again with+ * the on-disk strategy (`local`) for the standard storage step that+ * runs in the same flow. Both must return a working+ * `handleFileUpload`. */+ const codeEnvUpload = jest.fn().mockResolvedValue(uploaded);+ const localUpload = jest.fn().mockResolvedValue({+ bytes: 0,+ filename: 'upload.bin',+ filepath: '/uploads/upload.bin',+ });+ getStrategyFunctions.mockImplementation((src) =>+ src === FileSources.execute_code+ ? { handleFileUpload: codeEnvUpload }+ : { handleFileUpload: localUpload, saveBuffer: jest.fn() },+ );+ return codeEnvUpload;+ };++ it('persists kind:user codeEnvRef for chat attachments (messageAttachment=true)', async () => {+ setupCodeEnvUpload({ storage_session_id: 'sess-1', file_id: 'fid-1' });+ const req = makeReq();+ await processAgentFileUpload({+ req,+ res: mockRes,+ metadata: {+ agent_id: 'agent-abc',+ tool_resource: EToolResources.execute_code,+ file_id: 'file-uuid',+ message_file: true,+ },+ });++ expect(db.createFile).toHaveBeenCalledWith(+ expect.objectContaining({+ metadata: {+ codeEnvRef: {+ kind: 'user',+ id: 'user-123',+ storage_session_id: 'sess-1',+ file_id: 'fid-1',+ },+ },+ }),+ true,+ );+ });++ it('persists kind:agent codeEnvRef for agent setup files (messageAttachment=false)', async () => {+ setupCodeEnvUpload({ storage_session_id: 'sess-2', file_id: 'fid-2' });+ const req = makeReq();+ await processAgentFileUpload({+ req,+ res: mockRes,+ metadata: {+ agent_id: 'agent-abc',+ tool_resource: EToolResources.execute_code,+ file_id: 'file-uuid',+ },+ });++ expect(db.createFile).toHaveBeenCalledWith(+ expect.objectContaining({+ metadata: {+ codeEnvRef: {+ kind: 'agent',+ id: 'agent-abc',+ storage_session_id: 'sess-2',+ file_id: 'fid-2',+ },+ },+ }),+ true,+ );+ });++ it('does not persist legacy fileIdentifier key (mongoose strict drops it)', async () => {+ setupCodeEnvUpload({ storage_session_id: 'sess-3', file_id: 'fid-3' });+ const req = makeReq();+ await processAgentFileUpload({+ req,+ res: mockRes,+ metadata: {+ agent_id: 'agent-abc',+ tool_resource: EToolResources.execute_code,+ file_id: 'file-uuid',+ message_file: true,+ },+ });++ const persisted = db.createFile.mock.calls[0][0];+ expect(persisted.metadata).not.toHaveProperty('fileIdentifier');+ });+ });});describe('processFileURL', () => {diff --git a/package-lock.json b/package-lock.jsonindex 94817f82e3..5993e8cdb7 100644--- a/package-lock.json+++ b/package-lock.json@@ -60,7 +60,7 @@"@azure/storage-blob": "^12.30.0","@google/genai": "^1.19.0","@keyv/redis": "^4.3.3",- "@librechat/agents": "^3.1.79",+ "@librechat/agents": "^3.1.80-dev.3","@librechat/api": "*","@librechat/data-schemas": "*","@microsoft/microsoft-graph-client": "^3.0.7",@@ -12221,9 +12221,9 @@}},"node_modules/@librechat/agents": {- "version": "3.1.79",- "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-3.1.79.tgz",- "integrity": "sha512-sHQPoIRCG8j7H2U2bAQGI4hJwHZ9IAA00v9XhP029E1jhxKbY2wwMj9eHLrvVPJNi9ZnNR6QVvanjQgy3Wd7Iw==",+ "version": "3.1.80-dev.3",+ "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-3.1.80-dev.3.tgz",+ "integrity": "sha512-yHf346QR6Uo8EkE6IMkJhQTMbugPRO79keulifeo2ILmVmvoCa6G0zOo6/lughTGPNITRXPIbPKH2wr5tuw2jQ==","license": "MIT","dependencies": {"@anthropic-ai/sdk": "^0.92.0",@@ -44679,7 +44679,7 @@"@azure/storage-blob": "^12.30.0","@google/genai": "^1.19.0","@keyv/redis": "^4.3.3",- "@librechat/agents": "^3.1.79",+ "@librechat/agents": "^3.1.80-dev.3","@librechat/data-schemas": "*","@modelcontextprotocol/sdk": "^1.29.0","@smithy/node-http-handler": "^4.4.5",diff --git a/packages/api/package.json b/packages/api/package.jsonindex 73915e0556..5d3489eb55 100644--- a/packages/api/package.json+++ b/packages/api/package.json@@ -98,7 +98,7 @@"@azure/storage-blob": "^12.30.0","@google/genai": "^1.19.0","@keyv/redis": "^4.3.3",- "@librechat/agents": "^3.1.79",+ "@librechat/agents": "^3.1.80-dev.3","@librechat/data-schemas": "*","@modelcontextprotocol/sdk": "^1.29.0","@smithy/node-http-handler": "^4.4.5",diff --git a/packages/api/src/agents/codeFilesSession.spec.ts b/packages/api/src/agents/codeFilesSession.spec.tsindex a02d5089f9..a5ac577703 100644--- a/packages/api/src/agents/codeFilesSession.spec.ts+++ b/packages/api/src/agents/codeFilesSession.spec.ts@@ -6,10 +6,19 @@ import {type CodeFilesAgent,} from './codeFilesSession';-const file = (id: string, session_id: string, name: string): CodeEnvFile => ({+const file = (id: string, storage_session_id: string, name: string): CodeEnvFile => ({id,- session_id,+ /* `resource_id` is informational for `kind: 'user'` (codeapi derives+ * the sessionKey from the auth-context user, not this field) but+ * still required by the type for shape uniformity. The id stand-in+ * is fine here because no test asserts on its value. */+ resource_id: id,+ storage_session_id,name,+ /* `kind` drives codeapi's sessionKey shape; defaults to `'user'` for+ * primed code-execution attachments at the test boundary (most are+ * chat uploads). Tests that need shared kinds set it explicitly. */+ kind: 'user',});describe('seedCodeFilesIntoSessions', () => {@@ -75,13 +84,18 @@ describe('seedCodeFilesIntoSessions', () => {expect(entry.session_id).toBe('skill-sess');});- it('skips seeding when incoming files have no session_id (defensive)', () => {- const fileWithoutSession = { id: 'x', session_id: '', name: 'orphan.csv' } as CodeEnvFile;+ it('skips seeding when incoming files have no storage_session_id (defensive)', () => {+ const fileWithoutSession = {+ id: 'x',+ storage_session_id: '',+ name: 'orphan.csv',+ kind: 'user',+ } as CodeEnvFile;const result = seedCodeFilesIntoSessions([fileWithoutSession], undefined);expect(result).toBeUndefined();});- it('dedupes incoming files that share session_id + id with existing entries', () => {+ it('dedupes incoming files that share storage_session_id + id with existing entries', () => {/*** Regression for Codex review #2: shared conversation files commonly* appear in multiple agents' `primedCodeFiles`. Without dedupe,@@ -128,7 +142,7 @@ describe('seedCodeFilesIntoSessions', () => {const result = seedCodeFilesIntoSessions([a, a, b], undefined);const entry = result!.get(Constants.EXECUTE_CODE) as CodeSessionContext;expect(entry.files).toHaveLength(2);- expect(entry.files!.map((f) => f.session_id).sort()).toEqual(['sess-A', 'sess-B']);+ expect(entry.files!.map((f) => f.storage_session_id).sort()).toEqual(['sess-A', 'sess-B']);});});@@ -267,8 +281,8 @@ describe('buildInitialToolSessions', () => {expect(entry.session_id).toBe('sess-PRIMARY');/* All three agents still contributed their files into the merged set. */expect(entry.files!.map((f) => f.name).sort()).toEqual(['a.txt', 'b.txt', 'top.txt']);- /* And the per-file session_ids are preserved (ToolNode injects per-file). */- const byName = new Map(entry.files!.map((f) => [f.name, f.session_id]));+ /* And the per-file storage_session_ids are preserved (ToolNode injects per-file). */+ const byName = new Map(entry.files!.map((f) => [f.name, f.storage_session_id]));expect(byName.get('top.txt')).toBe('sess-PRIMARY');expect(byName.get('a.txt')).toBe('sess-A');expect(byName.get('b.txt')).toBe('sess-B');diff --git a/packages/api/src/agents/codeFilesSession.ts b/packages/api/src/agents/codeFilesSession.tsindex de75f2217f..2b37b27f89 100644--- a/packages/api/src/agents/codeFilesSession.ts+++ b/packages/api/src/agents/codeFilesSession.ts@@ -22,21 +22,24 @@ export interface CodeFilesAgent {* after the first call returns one, so primed files were silently dropped.** Files from `primeFiles` (api/server/services/Files/Code/process.js) carry- * per-file `session_id`s. The map's representative `session_id` is taken from- * the first incoming file (matching `primeInvokedSkills`); per-file ids on the- * `files` array are what `ToolNode` actually uses (`file.session_id ?? codeSession.session_id`).+ * per-file `storage_session_id`s (the long-lived storage bucket id). The+ * map's representative top-level `session_id` is seeded from the first+ * incoming file's `storage_session_id` (matching `primeInvokedSkills`),+ * since no execution session exists yet at seed time. Per-file ids on the+ * `files` array are what `ToolNode` actually uses+ * (`file.storage_session_id ?? execSessionId`).** When an entry already exists (e.g. seeded by `primeInvokedSkills` for skill* files), incoming files are appended after the existing ones. The pre-existing* representative `session_id` is preserved so a partial-cache/fresh-prime* collision doesn't shift which session id `ToolNode` picks for the call.*- * Files are deduplicated by `session_id + id` as the stable identity key.- * Multiple agents in the same run commonly carry the same primed- * code-execution resources (shared conversation files), and without dedupe- * `_injected_files` would grow proportionally to agent count and inflate- * every `/exec` POST. First-seen wins so the original ordering / source- * is preserved.+ * Files are deduplicated by `storage_session_id + id` as the stable+ * identity key. Multiple agents in the same run commonly carry the same+ * primed code-execution resources (shared conversation files), and without+ * dedupe `_injected_files` would grow proportionally to agent count and+ * inflate every `/exec` POST. First-seen wins so the original ordering /+ * source is preserved.*/export function seedCodeFilesIntoSessions(files: CodeEnvFile[] | undefined,@@ -50,15 +53,15 @@ export function seedCodeFilesIntoSessions(const prior = sessions.get(Constants.EXECUTE_CODE) as CodeSessionContext | undefined;/**- * Compose `(session_id, id)` as a stable identity. `name` alone isn't- * sufficient — two distinct primed uploads can share a filename- * (different sessions, different file_ids). The composite stays+ * Compose `(storage_session_id, id)` as a stable identity. `name` alone+ * isn't sufficient — two distinct primed uploads can share a filename+ * (different storage sessions, different file_ids). The composite stays* cheap to compute and the keys are short uuids.*/const seenKeys = new Set<string>();const mergedFiles: FileRefs = [];- const pushIfFresh = (f: { id?: string; session_id?: string; name?: string }): void => {- const key = `${f.session_id ?? ''}\0${f.id ?? ''}`;+ const pushIfFresh = (f: { id?: string; storage_session_id?: string; name?: string }): void => {+ const key = `${f.storage_session_id ?? ''}\0${f.id ?? ''}`;if (seenKeys.has(key)) return;seenKeys.add(key);mergedFiles.push(f as FileRefs[number]);@@ -68,7 +71,14 @@ export function seedCodeFilesIntoSessions(}for (const f of files) pushIfFresh(f);- const representativeSessionId = prior?.session_id ?? files[0].session_id;+ /* Representative top-level `session_id` for the seed CodeSessionContext.+ * No execution session exists yet at seed time, so the first incoming+ * file's `storage_session_id` stands in until the first `/exec` call+ * returns a real execution session id. ToolNode reads per-file+ * `storage_session_id` for actual injection — the representative is+ * informational rather than load-bearing. Mirrors the same convention+ * used in `primeInvokedSkills`. */+ const representativeSessionId = prior?.session_id ?? files[0].storage_session_id;if (!representativeSessionId) {return existing;}diff --git a/packages/api/src/agents/handlers.spec.ts b/packages/api/src/agents/handlers.spec.tsindex f6b0939fbb..91f6e531af 100644--- a/packages/api/src/agents/handlers.spec.ts+++ b/packages/api/src/agents/handlers.spec.ts@@ -72,8 +72,20 @@ describe('createToolExecuteHandler', () => {codeSessionContext: {session_id: 'prev-session-abc',files: [- { session_id: 'prev-session-abc', id: 'f1', name: 'data.parquet' },- { session_id: 'prev-session-abc', id: 'f2', name: 'chart.png' },+ {+ storage_session_id: 'prev-session-abc',+ id: 'f1',+ resource_id: 'user_alice',+ name: 'data.parquet',+ kind: 'user',+ },+ {+ storage_session_id: 'prev-session-abc',+ id: 'f2',+ resource_id: 'user_alice',+ name: 'chart.png',+ kind: 'user',+ },],},},@@ -84,8 +96,20 @@ describe('createToolExecuteHandler', () => {expect(capturedConfigs).toHaveLength(1);expect(capturedConfigs[0].session_id).toBe('prev-session-abc');expect(capturedConfigs[0]._injected_files).toEqual([- { session_id: 'prev-session-abc', id: 'f1', name: 'data.parquet' },- { session_id: 'prev-session-abc', id: 'f2', name: 'chart.png' },+ {+ storage_session_id: 'prev-session-abc',+ id: 'f1',+ resource_id: 'user_alice',+ name: 'data.parquet',+ kind: 'user',+ },+ {+ storage_session_id: 'prev-session-abc',+ id: 'f2',+ resource_id: 'user_alice',+ name: 'chart.png',+ kind: 'user',+ },]);});@@ -141,7 +165,15 @@ describe('createToolExecuteHandler', () => {args: { lang: 'python', code: 'step_1()' },codeSessionContext: {session_id: 'session-A',- files: [{ session_id: 'session-A', id: 'fa', name: 'a.csv' }],+ files: [+ {+ storage_session_id: 'session-A',+ id: 'fa',+ resource_id: 'user_alice',+ name: 'a.csv',+ kind: 'user',+ },+ ],},},{@@ -150,7 +182,15 @@ describe('createToolExecuteHandler', () => {args: { lang: 'python', code: 'step_2()' },codeSessionContext: {session_id: 'session-A',- files: [{ session_id: 'session-A', id: 'fa', name: 'a.csv' }],+ files: [+ {+ storage_session_id: 'session-A',+ id: 'fa',+ resource_id: 'user_alice',+ name: 'a.csv',+ kind: 'user',+ },+ ],},},];@@ -161,7 +201,13 @@ describe('createToolExecuteHandler', () => {for (const config of capturedConfigs) {expect(config.session_id).toBe('session-A');expect(config._injected_files).toEqual([- { session_id: 'session-A', id: 'fa', name: 'a.csv' },+ {+ storage_session_id: 'session-A',+ id: 'fa',+ resource_id: 'user_alice',+ name: 'a.csv',+ kind: 'user',+ },]);}});@@ -177,7 +223,15 @@ describe('createToolExecuteHandler', () => {args: { query: 'test' },codeSessionContext: {session_id: 'should-be-ignored',- files: [{ session_id: 'x', id: 'y', name: 'z' }],+ files: [+ {+ storage_session_id: 'x',+ id: 'y',+ resource_id: 'user_alice',+ name: 'z',+ kind: 'user',+ },+ ],},},];@@ -205,6 +259,7 @@ describe('createToolExecuteHandler', () => {name: 'pii-redactor',body: 'restricted body',fileCount: 0,+ version: 1,disableModelInvocation: true,}));const handler = createSkillHandler(getSkillByName);@@ -247,6 +302,7 @@ describe('createToolExecuteHandler', () => {name: 'normal-skill',body: 'body',fileCount: 0,+ version: 1,}));const handler = createSkillHandler(getSkillByName);@@ -276,6 +332,7 @@ describe('createToolExecuteHandler', () => {name: 'maybe-disabled',body: 'body',fileCount: 0,+ version: 1,}));const handler = createSkillHandler(getSkillByName);@@ -302,6 +359,7 @@ describe('createToolExecuteHandler', () => {name: 'maybe-disabled-read',body: '# Body',fileCount: 0,+ version: 1,}));const handler = createToolExecuteHandler({loadTools: jest.fn(async () => ({@@ -342,6 +400,7 @@ describe('createToolExecuteHandler', () => {name: 'manually-primed',body: '# Body',fileCount: 0,+ version: 1,}));const handler = createToolExecuteHandler({loadTools: jest.fn(async () => ({@@ -391,6 +450,7 @@ describe('createToolExecuteHandler', () => {name: 'pii-redactor',body: 'restricted body',fileCount: 0,+ version: 1,disableModelInvocation: true,}));const handler = createToolExecuteHandler({@@ -421,6 +481,7 @@ describe('createToolExecuteHandler', () => {name: 'normal-skill',body: '# Body',fileCount: 0,+ version: 1,}));const handler = createToolExecuteHandler({loadTools: jest.fn(async () => ({@@ -454,6 +515,7 @@ describe('createToolExecuteHandler', () => {name: 'manual-only-skill',body: '# Use references/docs.md for details',fileCount: 0,+ version: 1,disableModelInvocation: true,}));const handler = createToolExecuteHandler({@@ -489,6 +551,7 @@ describe('createToolExecuteHandler', () => {name: 'other-disabled-skill',body: 'restricted',fileCount: 0,+ version: 1,disableModelInvocation: true,}));const handler = createToolExecuteHandler({@@ -526,6 +589,7 @@ describe('createToolExecuteHandler', () => {name: 'always-applied-legal',body: '# Cite references/policy.md when advising',fileCount: 0,+ version: 1,disableModelInvocation: true,}));const handler = createToolExecuteHandler({@@ -566,6 +630,7 @@ describe('createToolExecuteHandler', () => {name: 'collides',body: '# primed body',fileCount: 0,+ version: 1,}));const handler = createToolExecuteHandler({loadTools: jest.fn(async () => ({@@ -615,6 +680,7 @@ describe('createToolExecuteHandler', () => {name: 'brand-guidelines',body: 'skill body',fileCount: 2,+ version: 1,}));/* `loadTools` injects `codeEnvAvailable` into the returned`configurable`, which mirrors production flow through@@ -789,6 +855,7 @@ describe('createToolExecuteHandler', () => {name: 'primed-only-skill',body: '# Primed skill body',fileCount: 1,+ version: 1,}));const readSandboxFile = jest.fn();const getSkillFileByPath = jest.fn(async () => ({@@ -888,6 +955,7 @@ describe('createToolExecuteHandler', () => {name: 'real-skill',body: '# Real Body',fileCount: 0,+ version: 1,}));const readSandboxFile = jest.fn();const handler = makeReadFileHandler({diff --git a/packages/api/src/agents/handlers.ts b/packages/api/src/agents/handlers.tsindex 4d1951a308..05f892eff8 100644--- a/packages/api/src/agents/handlers.ts+++ b/packages/api/src/agents/handlers.ts@@ -10,6 +10,7 @@ import type {ToolExecuteBatchRequest,} from '@librechat/agents';import { Types } from 'mongoose';+import type { CodeEnvRef } from 'librechat-data-provider';import type { StructuredToolInterface } from '@librechat/agents/langchain/tools';import type { SkillFileRecord } from './skillFiles';import type { ServerRequest } from '~/types';@@ -67,6 +68,11 @@ export interface ToolExecuteOptions {body: string;name: string;_id: Types.ObjectId;+ /** Monotonic counter on the skill record. Threaded into+ * `codeEnvRef.version` so codeapi's sessionKey scopes the cache+ * per-revision; bumping the version on edit invalidates the+ * prior cache entry. */+ version: number;fileCount: number;/*** Set when the skill author opted out of model invocation. The handler@@ -83,22 +89,30 @@ export interface ToolExecuteOptions {getDownloadStream?: (req: ServerRequest, filepath: string) => Promise<NodeJS.ReadableStream>;[key: string]: unknown;};- /** Batch uploads files to the code execution environment */+ /** Batch uploads files to the code execution environment. `kind`/`id`/+ * `version?` carry the resource identity codeapi uses to derive the+ * sessionKey for the batch's storage bucket. */batchUploadCodeEnvFiles?: (params: {req: ServerRequest;files: Array<{ stream: NodeJS.ReadableStream; filename: string }>;- entity_id?: string;- }) => Promise<{ session_id: string; files: Array<{ fileId: string; filename: string }> }>;+ kind: 'skill' | 'agent' | 'user';+ id: string;+ version?: number;+ read_only?: boolean;+ }) => Promise<{+ storage_session_id: string;+ files: Array<{ fileId: string; filename: string }>;+ }>;/** Checks if a code env file is still active. Returns lastModified or null. */- getSessionInfo?: (fileIdentifier: string) => Promise<string | null>;+ getSessionInfo?: (ref: CodeEnvRef) => Promise<string | null>;/** 23-hour freshness check */checkIfActive?: (dateString: string) => boolean;- /** Persists codeEnvIdentifiers on skill files after upload */+ /** Persists `codeEnvRef` on skill files after upload */updateSkillFileCodeEnvIds?: (updates: Array<{skillId: Types.ObjectId | string;relativePath: string;- codeEnvIdentifier: string;+ codeEnvRef: CodeEnvRef;}>,) => Promise<void>;/** Loads a skill file by path (for read_file tool) */@@ -888,7 +902,19 @@ async function handleSkillToolCall(const contentText = `Skill "${args.skillName}" loaded. Follow the instructions below.`;let artifact:- | { session_id: string; files: Array<{ id: string; session_id: string; name: string }> }+ | {+ session_id: string;+ files: Array<{+ id: string;+ /** Resource id (skill `_id`). codeapi requires this distinct+ * from the storage `id` to scope sessionKey by resource. */+ resource_id: string;+ name: string;+ storage_session_id: string;+ kind?: 'skill' | 'agent' | 'user';+ version?: number;+ }>;+ }| undefined;// Prime skill files to code env — only when the `execute_code` capability@@ -916,7 +942,26 @@ async function handleSkillToolCall(updateSkillFileCodeEnvIds,});if (primeResult) {- artifact = primeResult;+ /* `session_id` at the top of the artifact is the (representative)+ * execution session — ToolNode reads it for CodeSessionContext+ * continuity. Per-file storage lives on each file's+ * `storage_session_id`. Skill files carry `kind: 'skill'` and+ * the skill's version so codeapi's sessionKey scopes the+ * cache per-revision. */+ artifact = {+ session_id: primeResult.storage_session_id,+ files: primeResult.files.map((f) => ({+ id: f.id,+ /* `resource_id` (skill `_id`) is what codeapi feeds into+ * `<tenant>:skill:<id>:v:<version>` — without it the next+ * /exec authorizer sees `resource_id: undefined` and 400s. */+ resource_id: f.resource_id,+ name: f.name,+ storage_session_id: f.storage_session_id,+ kind: 'skill',+ version: skill.version,+ })),+ };}} catch (error) {logger.error(@@ -1015,6 +1060,56 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHandtoolCallConfig.session_id = tc.codeSessionContext.session_id;if (tc.codeSessionContext.files && tc.codeSessionContext.files.length > 0) {toolCallConfig._injected_files = tc.codeSessionContext.files;+ /* Last LC-controlled point before the wire. Mirrors+ * codeapi's validator context so the two log sides+ * correlate on a single grep. */+ const refs = tc.codeSessionContext.files as Array<{+ id?: unknown;+ resource_id?: unknown;+ storage_session_id?: unknown;+ kind?: unknown;+ version?: unknown;+ name?: unknown;+ }>;+ const summary = refs.map((f) => ({+ kind: f.kind,+ hasResourceId: typeof f.resource_id === 'string' && !!f.resource_id,+ hasStorageSessionId:+ typeof f.storage_session_id === 'string' && !!f.storage_session_id,+ hasVersion: typeof f.version === 'number',+ }));+ const missingResourceId = summary.filter((s) => !s.hasResourceId).length;+ logger.debug(+ `[code-env:inject] tool=${tc.name} files=${refs.length} ` ++ `missingResourceId=${missingResourceId}`,+ { summary },+ );+ if (missingResourceId > 0) {+ logger.warn(+ `[code-env:inject] ${missingResourceId}/${refs.length} files missing resource_id ` ++ `for tool=${tc.name} — codeapi will reject with 400`,+ { summary },+ );+ }+ } else {+ /* Empty `_injected_files` on a code-execution tool+ * call. Almost always means the seeding chain+ * (primeCodeFiles → initialSessions →+ * CodeSessionContext) dropped the file upstream.+ * `session_id` is still emitted; agents falls+ * through to the `/files/<sid>` legacy fetch+ * which is post-cutover broken (returns 400).+ * Pair with `[primeCodeFiles]` traces below to+ * locate the layer that lost the ref. */+ logger.warn(+ `[code-env:inject] tool=${tc.name} _injected_files=0 — sandbox will see no input files`,+ {+ tool: tc.name,+ session_id: tc.codeSessionContext.session_id,+ codeSessionContextHasFiles: tc.codeSessionContext.files !== undefined,+ codeSessionContextFileCount: tc.codeSessionContext.files?.length ?? 0,+ },+ );}}diff --git a/packages/api/src/agents/resources.test.ts b/packages/api/src/agents/resources.test.tsindex 641fb9284c..718e5cbdec 100644--- a/packages/api/src/agents/resources.test.ts+++ b/packages/api/src/agents/resources.test.ts@@ -127,7 +127,7 @@ describe('primeResources', () => {embedded: false,usage: 0,metadata: {- fileIdentifier: 'python-script',+ codeEnvRef: { kind: 'user', id: 'user1', storage_session_id: 'sess', file_id: 'fid' },},},];@@ -328,7 +328,7 @@ describe('primeResources', () => {embedded: false,usage: 0,metadata: {- fileIdentifier: 'python-script',+ codeEnvRef: { kind: 'user', id: 'user1', storage_session_id: 'sess', file_id: 'fid' },},},];@@ -542,7 +542,7 @@ describe('primeResources', () => {embedded: false,usage: 0,metadata: {- fileIdentifier: 'python-script',+ codeEnvRef: { kind: 'user', id: 'user1', storage_session_id: 'sess', file_id: 'fid' },},};@@ -713,7 +713,7 @@ describe('primeResources', () => {embedded: false,usage: 0,metadata: {- fileIdentifier: 'python-script',+ codeEnvRef: { kind: 'user', id: 'user1', storage_session_id: 'sess', file_id: 'fid' },},};@@ -728,7 +728,7 @@ describe('primeResources', () => {embedded: false,usage: 0,metadata: {- fileIdentifier: 'python-script',+ codeEnvRef: { kind: 'user', id: 'user1', storage_session_id: 'sess', file_id: 'fid' },},};@@ -878,7 +878,7 @@ describe('primeResources', () => {embedded: false,usage: 0,metadata: {- fileIdentifier: 'python-script',+ codeEnvRef: { kind: 'user', id: 'user1', storage_session_id: 'sess', file_id: 'fid' },},};@@ -1128,7 +1128,7 @@ describe('primeResources', () => {embedded: false,usage: 0,metadata: {- fileIdentifier: 'python-script',+ codeEnvRef: { kind: 'user', id: 'user1', storage_session_id: 'sess', file_id: 'fid' },},},{diff --git a/packages/api/src/agents/resources.ts b/packages/api/src/agents/resources.tsindex e147c743cf..56cd9b6c0d 100644--- a/packages/api/src/agents/resources.ts+++ b/packages/api/src/agents/resources.ts@@ -80,7 +80,7 @@ const addFileToResource = ({/*** Categorizes a file into the appropriate tool resource based on its properties* Files are categorized as:- * - execute_code: Files with fileIdentifier metadata+ * - execute_code: Files with a code-environment ref (`codeEnvRef`)* - file_search: Files marked as embedded* - image_edit: Image files in the request file set with dimensions* @param params - Parameters object@@ -100,7 +100,7 @@ const categorizeFileForToolResources = ({requestFileSet: Set<string>;processedResourceFiles: Set<string>;}): void => {- if (file.metadata?.fileIdentifier) {+ if (file.metadata?.codeEnvRef) {addFileToResource({file,resourceType: EToolResources.execute_code,diff --git a/packages/api/src/agents/skillFiles.spec.ts b/packages/api/src/agents/skillFiles.spec.tsindex e4475c2048..4338b34e4e 100644--- a/packages/api/src/agents/skillFiles.spec.ts+++ b/packages/api/src/agents/skillFiles.spec.ts@@ -14,15 +14,16 @@ jest.mock('./run', () => ({import { Readable } from 'stream';import { Types } from 'mongoose';-import { primeInvokedSkills } from './skillFiles';-import type { PrimeInvokedSkillsDeps } from './skillFiles';+import { primeInvokedSkills, primeSkillFiles } from './skillFiles';+import type { PrimeInvokedSkillsDeps, PrimeSkillFilesParams } from './skillFiles';const SKILL_ID = new Types.ObjectId();+const SKILL_VERSION = 7;function makeDeps(overrides: Partial<PrimeInvokedSkillsDeps> = {}): PrimeInvokedSkillsDeps {const listSkillFiles = jest.fn().mockResolvedValue([]);const batchUploadCodeEnvFiles = jest.fn().mockResolvedValue({- session_id: 'session-x',+ storage_session_id: 'session-x',files: [],});return {@@ -34,6 +35,7 @@ function makeDeps(overrides: Partial<PrimeInvokedSkillsDeps> = {}): PrimeInvoked_id: SKILL_ID,name: 'brand-guidelines',body: 'skill body',+ version: SKILL_VERSION,fileCount: 2,}),listSkillFiles,@@ -79,14 +81,10 @@ describe('primeInvokedSkills — execute_code capability gate', () => {];const listSkillFiles = jest.fn().mockResolvedValue(fileRecords);const getStrategyFunctions = jest.fn().mockReturnValue({- /* A real empty Readable — matches the production contract for- `getDownloadStream` and works even if `batchUploadCodeEnvFiles`- is later replaced with a partially-real implementation that- iterates the stream. */getDownloadStream: jest.fn().mockResolvedValue(Readable.from(Buffer.from(''))),});const batchUploadCodeEnvFiles = jest.fn().mockResolvedValue({- session_id: 'session-42',+ storage_session_id: 'session-42',files: [{ fileId: 'file-1', filename: 'brand-guidelines/references/style.md' }],});@@ -101,17 +99,17 @@ describe('primeInvokedSkills — execute_code capability gate', () => {expect(batchUploadCodeEnvFiles).toHaveBeenCalledTimes(1);const [uploadArgs] = batchUploadCodeEnvFiles.mock.calls[0];- /* Phase 8 deprecation: LibreChat no longer threads an apiKey through- the sandbox upload path. The agents library / sandbox service owns- auth internally. */expect(uploadArgs).not.toHaveProperty('apiKey');- expect(uploadArgs.entity_id).toBe(SKILL_ID.toString());- /* Skill files are infrastructure inputs; the read_only flag tells codeapi- to seal them so any sandboxed-code modifications are dropped instead- of surfaced as ghost generated artifacts. */+ expect(uploadArgs).not.toHaveProperty('entity_id');expect(uploadArgs.read_only).toBe(true);- /* One uploaded file per `fileRecords` entry plus the synthetic- SKILL.md that `primeSkillFiles` always prepends. */+ /* Resource identity for codeapi's sessionKey: skill files share+ * cross-user-within-tenant under `<tenant>:skill:<id>:v:<version>`.+ * Without these on the upload, codeapi falls back to user bucketing+ * and skill-cache invalidation (driven by version bump on edit)+ * never fires. See codeapi #1455 (option α). */+ expect(uploadArgs.kind).toBe('skill');+ expect(uploadArgs.id).toBe(SKILL_ID.toString());+ expect(uploadArgs.version).toBe(SKILL_VERSION);expect(uploadArgs.files).toHaveLength(fileRecords.length + 1);expect(uploadArgs.files.map((f: { filename: string }) => f.filename)).toEqual(expect.arrayContaining(['brand-guidelines/SKILL.md', 'brand-guidelines/references/style.md']),@@ -128,12 +126,12 @@ describe('primeInvokedSkills — execute_code capability gate', () => {expect(deps.getSkillByName).not.toHaveBeenCalled();});- it('forwards entity_id on every file in initialSessions after fresh upload', async () => {- /* Regression: codeapi now resolves sessionKey per-file using `entity_id`.- * Skill files must carry `entity_id=<skillId>` through priming so that- * a subsequent execute mixing skill files and a user attachment can be- * authorized — both files in the same call resolve to their own scope- * instead of collapsing onto a single request-level entity. */+ it('writes kind/version/storage_session_id on every cached file after a fresh upload', async () => {+ /* Per-file refs in `CodeSessionContext.files` carry the resource+ * identity (kind=skill, id=skillId, version=skill.version) so+ * codeapi can derive the right sessionKey. Cache scope is per+ * (tenant, kind, id, version) — bumping the skill version+ * naturally invalidates the prior cache. */const listSkillFiles = jest.fn().mockResolvedValue([{relativePath: 'references/style.md',@@ -147,7 +145,7 @@ describe('primeInvokedSkills — execute_code capability gate', () => {getDownloadStream: jest.fn().mockResolvedValue(Readable.from(Buffer.from(''))),});const batchUploadCodeEnvFiles = jest.fn().mockResolvedValue({- session_id: 'session-42',+ storage_session_id: 'session-42',files: [{ fileId: 'file-1', filename: 'brand-guidelines/references/style.md' }],});@@ -164,9 +162,16 @@ describe('primeInvokedSkills — execute_code capability gate', () => {expect(codeSession?.files).toEqual([{id: 'file-1',+ /* `resource_id` is the skill `_id` — drives codeapi's+ * sessionKey re-derivation. Distinct from `id` (the storage+ * file_id). The split fixes the shared-kind 403 mismatch+ * where codeapi computed sessionKey from the storage nanoid+ * instead of the skill _id. */+ resource_id: SKILL_ID.toString(),name: 'brand-guidelines/references/style.md',- session_id: 'session-42',- entity_id: SKILL_ID.toString(),+ storage_session_id: 'session-42',+ kind: 'skill',+ version: SKILL_VERSION,},]);});@@ -175,10 +180,10 @@ describe('primeInvokedSkills — execute_code capability gate', () => {/* Concurrency regression: when many users hit the same skill at* once, fire-and-forget keeps the cache in miss-steady-state for* the burst — User N's prime reads SkillFile docs before User N-1's- * persist commits, sees no `codeEnvIdentifier`, re-uploads, and- * fires its own forget that User N+1 also races. Awaiting the- * persist before the prime resolves ensures the next concurrent- * caller observes the cache pointer instead of racing a write. */+ * persist commits, sees no codeEnvRef, re-uploads, and fires its+ * own forget that User N+1 also races. Awaiting the persist before+ * the prime resolves ensures the next concurrent caller observes+ * the cache pointer instead of racing a write. */const fileRecords = [{relativePath: 'references/style.md',@@ -193,7 +198,7 @@ describe('primeInvokedSkills — execute_code capability gate', () => {getDownloadStream: jest.fn().mockResolvedValue(Readable.from(Buffer.from(''))),});const batchUploadCodeEnvFiles = jest.fn().mockResolvedValue({- session_id: 'session-42',+ storage_session_id: 'session-42',files: [{ fileId: 'file-1', filename: 'brand-guidelines/references/style.md' }],});@@ -235,17 +240,23 @@ describe('primeInvokedSkills — execute_code capability gate', () => {{skillId: SKILL_ID,relativePath: 'references/style.md',- codeEnvIdentifier: `session-42/file-1?entity_id=${SKILL_ID.toString()}`,+ codeEnvRef: {+ kind: 'skill',+ id: SKILL_ID.toString(),+ storage_session_id: 'session-42',+ file_id: 'file-1',+ version: SKILL_VERSION,+ },},]);});- it('parses entity_id off codeEnvIdentifier in the cached-skills hot path', async () => {+ it('reads codeEnvRef in the cached-skills hot path', async () => {/* When all skill files are still active in codeapi, primeInvokedSkills- * skips the batch upload entirely and reconstructs file refs from each- * skill file's persisted `codeEnvIdentifier`. The query string carries- * `?entity_id=<skillId>`, which must survive into `_injected_files` so- * downstream authorization still uses the skill's scope. */+ * skips the batch upload entirely and reconstructs file refs from+ * each skill file's persisted `codeEnvRef`. The kind/version travel+ * through to `CodeSessionContext.files` so the next exec carries+ * them on `_injected_files` for codeapi's sessionKey derivation. */const listSkillFiles = jest.fn().mockResolvedValue([{relativePath: 'references/style.md',@@ -253,7 +264,13 @@ describe('primeInvokedSkills — execute_code capability gate', () => {filepath: '/storage/brand-guidelines/references/style.md',source: 's3',bytes: 256,- codeEnvIdentifier: `session-cached/file-cached?entity_id=${SKILL_ID.toString()}`,+ codeEnvRef: {+ kind: 'skill',+ id: SKILL_ID.toString(),+ storage_session_id: 'session-cached',+ file_id: 'file-cached',+ version: SKILL_VERSION,+ },},]);const batchUploadCodeEnvFiles = jest.fn();@@ -261,7 +278,7 @@ describe('primeInvokedSkills — execute_code capability gate', () => {codeEnvAvailable: true,listSkillFiles,batchUploadCodeEnvFiles,- getSessionInfo: jest.fn().mockResolvedValue('2026-05-05T00:00:00Z'),+ getSessionInfo: jest.fn().mockResolvedValue('2026-05-06T00:00:00Z'),checkIfActive: jest.fn().mockReturnValue(true),});@@ -272,9 +289,118 @@ describe('primeInvokedSkills — execute_code capability gate', () => {expect(codeSession?.files).toEqual([{id: 'file-cached',+ /* From the cache-hit path: pulls `resource_id` directly off+ * the persisted `codeEnvRef.id` (the skill `_id`). */+ resource_id: SKILL_ID.toString(),name: 'brand-guidelines/references/style.md',- session_id: 'session-cached',- entity_id: SKILL_ID.toString(),+ storage_session_id: 'session-cached',+ kind: 'skill',+ version: SKILL_VERSION,+ },+ ]);+ });+});++/* The tool-invoked skill loader (`handle_skill` -> `primeSkillFiles`)+ * is a separate code path from `primeInvokedSkills` (the NL-detected+ * loader). Both feed `_injected_files` on the next /exec; both must+ * carry `resource_id` end-to-end, otherwise codeapi 400s with+ * `resource_id is invalid` (`type: 'undefined'`). Tests below lock+ * that contract on the lower-level helper directly. */+describe('primeSkillFiles — resource identity propagation', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ });++ function makeSkillFilesDeps(+ overrides: Partial<PrimeSkillFilesParams> = {},+ ): PrimeSkillFilesParams {+ return {+ skill: {+ _id: SKILL_ID,+ name: 'brand-guidelines',+ body: 'skill body',+ version: SKILL_VERSION,+ },+ skillFiles: [],+ req: { user: { id: 'user-1' } } as PrimeSkillFilesParams['req'],+ getStrategyFunctions: jest.fn().mockReturnValue({+ getDownloadStream: jest.fn().mockResolvedValue(Readable.from(Buffer.from(''))),+ }),+ batchUploadCodeEnvFiles: jest.fn().mockResolvedValue({+ storage_session_id: 'session-fresh',+ files: [+ { fileId: 'file-fresh', filename: 'brand-guidelines/references/style.md' },+ { fileId: 'file-skillmd', filename: 'brand-guidelines/SKILL.md' },+ ],+ }),+ ...overrides,+ };+ }++ it('fresh-upload path: emits resource_id=skill._id, kind=skill, version on each file', async () => {+ const deps = makeSkillFilesDeps({+ skillFiles: [+ {+ relativePath: 'references/style.md',+ filename: 'style.md',+ filepath: '/storage/brand-guidelines/references/style.md',+ source: 's3',+ bytes: 256,+ },+ ],+ });++ const result = await primeSkillFiles(deps);++ expect(result?.files).toEqual([+ {+ id: 'file-fresh',+ resource_id: SKILL_ID.toString(),+ storage_session_id: 'session-fresh',+ name: 'brand-guidelines/references/style.md',+ kind: 'skill',+ version: SKILL_VERSION,+ },+ ]);+ });++ it('cache-hit path: re-derives resource_id/kind/version from persisted codeEnvRef', async () => {+ const cachedRef = {+ kind: 'skill' as const,+ id: SKILL_ID.toString(),+ storage_session_id: 'session-cached',+ file_id: 'file-cached',+ version: SKILL_VERSION,+ };+ const batchUploadCodeEnvFiles = jest.fn();+ const deps = makeSkillFilesDeps({+ skillFiles: [+ {+ relativePath: 'references/style.md',+ filename: 'style.md',+ filepath: '/storage/brand-guidelines/references/style.md',+ source: 's3',+ bytes: 256,+ codeEnvRef: cachedRef,+ },+ ],+ batchUploadCodeEnvFiles,+ getSessionInfo: jest.fn().mockResolvedValue('2026-05-06T00:00:00Z'),+ checkIfActive: jest.fn().mockReturnValue(true),+ });++ const result = await primeSkillFiles(deps);++ expect(batchUploadCodeEnvFiles).not.toHaveBeenCalled();+ expect(result?.files).toEqual([+ {+ id: 'file-cached',+ resource_id: SKILL_ID.toString(),+ storage_session_id: 'session-cached',+ name: 'brand-guidelines/references/style.md',+ kind: 'skill',+ version: SKILL_VERSION,},]);});diff --git a/packages/api/src/agents/skillFiles.ts b/packages/api/src/agents/skillFiles.tsindex 9f274f6a99..dc48914b83 100644--- a/packages/api/src/agents/skillFiles.ts+++ b/packages/api/src/agents/skillFiles.ts@@ -2,6 +2,7 @@ import { Readable } from 'stream';import { Constants } from '@librechat/agents';import { logger } from '@librechat/data-schemas';import type { ToolSessionMap, CodeSessionContext } from '@librechat/agents';+import type { CodeEnvRef } from 'librechat-data-provider';import type { Types } from 'mongoose';import type { ServerRequest } from '~/types';import { extractInvokedSkillsFromPayload } from './run';@@ -12,11 +13,19 @@ export interface SkillFileRecord {filepath: string;source: string;bytes: number;- codeEnvIdentifier?: string;+ codeEnvRef?: CodeEnvRef;}export interface PrimeSkillFilesParams {- skill: { body: string; name: string; _id: Types.ObjectId | string };+ skill: {+ body: string;+ name: string;+ _id: Types.ObjectId | string;+ /** Monotonic counter on the skill record. Bumped on every edit+ * (frontmatter / body / file upsert). Threaded into `codeEnvRef.version`+ * so codeapi's sessionKey scopes the cache per-revision. */+ version: number;+ };skillFiles: SkillFileRecord[];req: ServerRequest;getStrategyFunctions: (source: string) => {@@ -26,44 +35,53 @@ export interface PrimeSkillFilesParams {batchUploadCodeEnvFiles: (params: {req: ServerRequest;files: Array<{ stream: NodeJS.ReadableStream; filename: string }>;- entity_id?: string;+ /** Resource kind that owns the batch's storage session. Drives codeapi's+ * sessionKey derivation (`<tenant>:<kind>:<id>[:v:<version>]`). */+ kind: 'skill' | 'agent' | 'user';+ /** Resource id (skillId / agentId / userId). */+ id: string;+ /** Required when `kind === 'skill'`; forbidden otherwise. */+ version?: number;/** When true, codeapi tags every file in the batch as infrastructure* (read-only inputs that must never surface as generated artifacts,* even if sandboxed code mutates the bytes on disk). */read_only?: boolean;}) => Promise<{- session_id: string;+ storage_session_id: string;files: Array<{ fileId: string; filename: string }>;}>;/** Checks if a code env file is still active. Returns lastModified timestamp or null. */- getSessionInfo?: (fileIdentifier: string) => Promise<string | null>;+ getSessionInfo?: (ref: CodeEnvRef) => Promise<string | null>;/** 23-hour freshness check */checkIfActive?: (dateString: string) => boolean;- /** Persists codeEnvIdentifier on skill files after upload. Implementations+ /** Persists `codeEnvRef` on skill files after upload. Implementations* warn-log on partial writes (matchedCount/modifiedCount mismatch)* internally — caller can fire-and-forget without losing visibility. */updateSkillFileCodeEnvIds?: (updates: Array<{skillId: Types.ObjectId | string;relativePath: string;- codeEnvIdentifier: string;+ codeEnvRef: CodeEnvRef;}>,) => Promise<{ matchedCount: number; modifiedCount: number } | void>;}export interface PrimeSkillFilesResult {- session_id: string;- files: Array<{ id: string; session_id: string; name: string; entity_id?: string }>;-}--/** Parses `entity_id` out of a persisted `codeEnvIdentifier`'s query string.- * Returns `undefined` when the identifier has no query string or no- * `entity_id` (legacy user-attachment uploads). */-function parseEntityIdFromCodeEnvIdentifier(identifier: string): string | undefined {- const queryString = identifier.split('?')[1];- if (!queryString) return undefined;- const value = new URLSearchParams(queryString).get('entity_id');- return value && value.length > 0 ? value : undefined;+ /** Representative storage session id (first file's). */+ storage_session_id: string;+ files: Array<{+ /** Storage file id (the per-file uuid file_server returned at upload). */+ id: string;+ /** Resource id — the entity that owns the storage session. For skill+ * files this is `skill._id.toString()`. Distinct from `id`; codeapi+ * derives the sessionKey from `resource_id` (shared cache scope) but+ * validates upload presence under `id` (per-file storage key). */+ resource_id: string;+ storage_session_id: string;+ name: string;+ kind: 'skill' | 'agent' | 'user';+ version?: number;+ }>;}/**@@ -90,29 +108,27 @@ export async function primeSkillFiles(updateSkillFileCodeEnvIds,} = params;- // Check if ALL existing sessions are still active before reusing cached refs.- // Files normally share one session, but a partial bulkWrite failure during- // updateSkillFileCodeEnvIds can leave mixed session IDs. Checking every- // distinct session prevents serving stale identifiers that 404 in code env.+ /* Cache-hit path: every skillFile carries a `codeEnvRef` from the+ * previous prime. Check freshness against codeapi for every distinct+ * storage session; if all are still active, reuse without+ * re-uploading. The skill version is part of the ref — when the+ * skill is edited, the upsert clears the ref and forces a fresh+ * upload on the next prime. */if (getSessionInfo && checkIfActive && skillFiles.length > 0) {- // All files must have identifiers for the cache to be complete.- // Any missing identifier means partial persistence — fall through to re-upload.- const allHaveIds = skillFiles.every((sf) => sf.codeEnvIdentifier);- if (allHaveIds) {- const sessionIds = new Set(- skillFiles.map((sf) => (sf.codeEnvIdentifier as string).split('?')[0].split('/')[0]),- );+ const allHaveRefs = skillFiles.every((sf) => sf.codeEnvRef !== undefined);+ if (allHaveRefs) {+ const refsBySession = new Map<string, CodeEnvRef>();+ for (const sf of skillFiles) {+ const ref = sf.codeEnvRef;+ if (ref && !refsBySession.has(ref.storage_session_id)) {+ refsBySession.set(ref.storage_session_id, ref);+ }+ }try {const checkResults = await Promise.all(- Array.from(sessionIds).map(async (sid) => {- const representative = skillFiles.find((sf) =>- sf.codeEnvIdentifier!.startsWith(`${sid}/`),- );- if (!representative) {- return false;- }- const lastModified = await getSessionInfo(representative.codeEnvIdentifier!);+ Array.from(refsBySession.values()).map(async (ref) => {+ const lastModified = await getSessionInfo(ref);return !!(lastModified && checkIfActive(lastModified));}),);@@ -121,22 +137,30 @@ export async function primeSkillFiles(if (allActive) {const files: PrimeSkillFilesResult['files'] = [];for (const sf of skillFiles) {- const identifier = sf.codeEnvIdentifier as string;- const [sid, fid] = identifier.split('?')[0].split('/');- const entity_id = parseEntityIdFromCodeEnvIdentifier(identifier);+ const ref = sf.codeEnvRef;+ if (!ref) continue;+ /* Cache-hit refs already carry resource identity (kind / id /+ * version) — pull them through so the artifact emitted by+ * `handle_skill` and forwarded to `_injected_files` includes+ * `resource_id`. Without this the next /exec sends+ * `resource_id: undefined` and codeapi 400s. The discriminated+ * union pins `version` to the skill branch only — destructure+ * before the spread so TS accepts the conditional pull. */files.push({- id: fid,- session_id: sid,+ id: ref.file_id,+ resource_id: ref.id,+ storage_session_id: ref.storage_session_id,name: `${skill.name}/${sf.relativePath}`,- ...(entity_id != null ? { entity_id } : {}),+ kind: ref.kind,+ ...(ref.kind === 'skill' ? { version: ref.version } : {}),});}if (files.length > 0) {logger.debug(- `[primeSkillFiles] All ${sessionIds.size} session(s) active for skill "${skill.name}", reusing ${files.length} files`,+ `[primeSkillFiles] All ${refsBySession.size} session(s) active for skill "${skill.name}", reusing ${files.length} files`,);- return { session_id: files[0].session_id, files };+ return { storage_session_id: files[0].storage_session_id, files };}}} catch {@@ -183,7 +207,13 @@ export async function primeSkillFiles(const result = await batchUploadCodeEnvFiles({req,files: filesToUpload,- entity_id: entityId,+ /* Resource identity for codeapi's sessionKey: skill files share+ * cross-user-within-tenant under `<tenant>:skill:<id>:v:<version>`.+ * Bumping `skill.version` on edit naturally invalidates the prior+ * cache entry under the new sessionKey. */+ kind: 'skill',+ id: entityId,+ version: skill.version,/* Skill files are infrastructure: SKILL.md + bundled scripts/schemas/* docs that the agent reads but should never edit. Tag the upload as* read-only so codeapi seals the inputs (chmod 444 in-sandbox) and@@ -194,15 +224,20 @@ export async function primeSkillFiles(read_only: true,});// Exclude SKILL.md from the returned files array — it is uploaded to disk- // for bash access but has no codeEnvIdentifier (cannot be cached). Omitting- // it here keeps the fresh-upload and cache-hit code paths consistent.- const files = result.files+ // for bash access but has no codeEnvRef (cannot be cached). Omitting it+ // here keeps the fresh-upload and cache-hit code paths consistent.+ const files: PrimeSkillFilesResult['files'] = result.files.filter((f) => !f.filename.endsWith('/SKILL.md')).map((f) => ({id: f.fileId,- session_id: result.session_id,+ /* `resource_id` is the skill `_id` (the entity codeapi scopes+ * the sessionKey on). Distinct from `id` (the per-file storage+ * uuid) — both are required on the request. */+ resource_id: entityId,+ storage_session_id: result.storage_session_id,name: f.filename,- entity_id: entityId,+ kind: 'skill',+ version: skill.version,}));// Treat partial upload failures as a priming failure — missing bundled@@ -220,39 +255,48 @@ export async function primeSkillFiles(}/**- * Persist codeEnvIdentifiers on skill files. Awaited (not- * fire-and-forget) so the next prime — which can start within- * milliseconds when many users hit the same skill concurrently —- * sees the cache pointer instead of racing the read against an- * in-flight write. Without the await, a fire-and-forget under- * concurrency stays in cache-miss steady-state for the duration- * of the burst (each user's prime reads stale, re-uploads, then- * fires its own forget that the next user also misses). Latency- * cost is ~10–50ms on the prime that does the upload; subsequent- * primes save an entire batch upload. Failures don't fail the- * prime — the file refs returned to the caller are still valid.+ * Persist codeEnvRefs on skill files. Awaited (not fire-and-forget)+ * so the next prime — which can start within milliseconds when+ * many users hit the same skill concurrently — sees the cache+ * pointer instead of racing the read against an in-flight write.+ * Without the await, a fire-and-forget under concurrency stays in+ * cache-miss steady-state for the duration of the burst (each+ * user's prime reads stale, re-uploads, then fires its own forget+ * that the next user also misses). Latency cost is ~10–50ms on+ * the prime that does the upload; subsequent primes save an entire+ * batch upload. Failures don't fail the prime — the file refs+ * returned to the caller are still valid.*/if (updateSkillFileCodeEnvIds) {const updates = result.files.filter((f) => !f.filename.endsWith('/SKILL.md'))- .map((f) => ({- skillId: skill._id,- relativePath: f.filename.slice(f.filename.indexOf('/') + 1),- codeEnvIdentifier: `${result.session_id}/${f.fileId}?entity_id=${entityId}`,- }));+ .map((f) => {+ const ref: CodeEnvRef = {+ kind: 'skill',+ id: entityId,+ storage_session_id: result.storage_session_id,+ file_id: f.fileId,+ version: skill.version,+ };+ return {+ skillId: skill._id,+ relativePath: f.filename.slice(f.filename.indexOf('/') + 1),+ codeEnvRef: ref,+ };+ });if (updates.length > 0) {try {await updateSkillFileCodeEnvIds(updates);} catch (err: unknown) {logger.warn(- '[primeSkillFiles] Failed to persist codeEnvIdentifiers:',+ '[primeSkillFiles] Failed to persist codeEnvRefs:',err instanceof Error ? err.message : err,);}}}- return { session_id: result.session_id, files };+ return { storage_session_id: result.storage_session_id, files };} catch (error) {logger.error(`[primeSkillFiles] Batch upload failed for skill "${skill.name}":`,@@ -274,7 +318,13 @@ export interface PrimeInvokedSkillsDeps {getSkillByName: (name: string,accessibleIds: Types.ObjectId[],- ) => Promise<{ body: string; name: string; _id: Types.ObjectId; fileCount: number } | null>;+ ) => Promise<{+ body: string;+ name: string;+ _id: Types.ObjectId;+ version: number;+ fileCount: number;+ } | null>;listSkillFiles: (skillId: Types.ObjectId | string) => Promise<SkillFileRecord[]>;getStrategyFunctions: PrimeSkillFilesParams['getStrategyFunctions'];batchUploadCodeEnvFiles: PrimeSkillFilesParams['batchUploadCodeEnvFiles'];@@ -324,6 +374,7 @@ export async function primeInvokedSkills(body: string;name: string;_id: Types.ObjectId;+ version: number;fileCount: number;}> = [];for (const r of resolveResults) {@@ -353,23 +404,24 @@ export async function primeInvokedSkills(// ALL distinct sessions for freshness. If all are active, return cached// references with zero re-uploads. If any expired, re-upload everything.if (deps.getSessionInfo && deps.checkIfActive) {- const allFiles = fileListResults.flatMap((r) => r.files);- const allFilesWithIds = allFiles.filter((f) => f.codeEnvIdentifier);-- // Only use cache when ALL files have identifiers (no partial persistence)- if (allFilesWithIds.length > 0 && allFilesWithIds.length === allFiles.length) {- const sessionIds = new Set(- allFilesWithIds.map((f) => f.codeEnvIdentifier!.split('?')[0].split('/')[0]),- );+ const allResolved = fileListResults.flatMap((r) =>+ r.files.map((f) => ({ skillName: r.skill.name, file: f, ref: f.codeEnvRef })),+ );+ const resolvedWithRef = allResolved.filter((x) => x.ref !== undefined);++ // Only use cache when ALL files have refs (no partial persistence)+ if (resolvedWithRef.length > 0 && resolvedWithRef.length === allResolved.length) {+ const refsBySession = new Map<string, CodeEnvRef>();+ for (const { ref } of resolvedWithRef) {+ if (ref && !refsBySession.has(ref.storage_session_id)) {+ refsBySession.set(ref.storage_session_id, ref);+ }+ }const checkResults = await Promise.all(- Array.from(sessionIds).map(async (sid) => {- const representative = allFilesWithIds.find((f) =>- f.codeEnvIdentifier!.startsWith(`${sid}/`),- );- if (!representative) return true;+ Array.from(refsBySession.values()).map(async (ref) => {try {- const lastModified = await deps.getSessionInfo?.(representative.codeEnvIdentifier!);+ const lastModified = await deps.getSessionInfo?.(ref);return !!(lastModified && deps.checkIfActive?.(lastModified));} catch {return false;@@ -379,30 +431,33 @@ export async function primeInvokedSkills(const allActive = checkResults.every(Boolean);if (allActive) {- const cachedFiles = fileListResults.flatMap((r) =>- r.files- .filter((f) => f.codeEnvIdentifier)- .map((f) => {- const identifier = f.codeEnvIdentifier as string;- const [sid, fid] = identifier.split('?')[0].split('/');- const entity_id = parseEntityIdFromCodeEnvIdentifier(identifier);- return {- id: fid,- name: `${r.skill.name}/${f.relativePath}`,- session_id: sid,- ...(entity_id != null ? { entity_id } : {}),- };- }),- );+ /* `id` is the STORAGE file_id (the per-file uuid the+ * file_server registered the upload under); `resource_id`+ * is the entity that owns the storage session — the+ * skill's `_id` here. codeapi's auth layer needs both:+ * `id` for the upload-existence check, `resource_id` for+ * sessionKey re-derivation (`<tenant>:skill:<resource_id>:v:<version>`).+ * Conflating them sent the storage nanoid through the+ * sessionKey switch and 403'd every shared-kind /exec. */+ const cachedFiles = resolvedWithRef.map(({ skillName, file, ref }) => ({+ id: ref!.file_id,+ resource_id: ref!.id,+ name: `${skillName}/${file.relativePath}`,+ storage_session_id: ref!.storage_session_id,+ kind: ref!.kind,+ ...(ref!.kind === 'skill' ? { version: ref!.version } : {}),+ }));if (cachedFiles.length > 0) {logger.debug(- `[primeInvokedSkills] All ${sessionIds.size} session(s) active, reusing ${cachedFiles.length} cached files`,+ `[primeInvokedSkills] All ${refsBySession.size} session(s) active, reusing ${cachedFiles.length} cached files`,);sessions = new Map();- // session_id is a representative value. ToolNode uses per-file- // session_id from the files array (file.session_id ?? codeSession.session_id).+ /* `session_id` at the top of CodeSessionContext is the+ * (representative) execution session — ToolNode reads it+ * for continuity. Per-file storage is on each+ * `files[i].storage_session_id`. */sessions.set(Constants.EXECUTE_CODE, {- session_id: cachedFiles[0].session_id,+ session_id: cachedFiles[0].storage_session_id,files: cachedFiles,lastUpdated: Date.now(),} satisfies CodeSessionContext);@@ -412,14 +467,18 @@ export async function primeInvokedSkills(}}- // Per-skill upload: each skill gets its own session with entity_id=skillId.- // primeSkillFiles handles freshness caching per-skill, so only expired- // skills re-upload. The code env handles mixed session_ids natively.+ // Per-skill upload: each skill gets its own storage session keyed+ // by `(kind: 'skill', id: skillId, version: skill.version)`.+ // primeSkillFiles handles freshness caching per-skill, so only+ // expired skills re-upload. CodeAPI handles mixed+ // storage_session_ids natively.const allPrimedFiles: Array<{id: string;+ resource_id: string;name: string;- session_id: string;- entity_id?: string;+ storage_session_id: string;+ kind: 'skill';+ version: number;}> = [];const primeResults = await Promise.allSettled(fileListResults.map(async ({ skill, files }) => {@@ -441,9 +500,14 @@ export async function primeInvokedSkills(for (const f of r.value.result.files) {allPrimedFiles.push({id: f.id,+ /* `resource_id` is the skill's `_id` — drives codeapi's+ * sessionKey re-derivation. See cachedFiles above for the+ * full id-vs-resource_id rationale. */+ resource_id: r.value.skill._id.toString(),name: f.name,- session_id: f.session_id,- ...(f.entity_id != null ? { entity_id: f.entity_id } : {}),+ storage_session_id: f.storage_session_id,+ kind: 'skill',+ version: r.value.skill.version,});}} else if (r.status === 'rejected') {@@ -453,11 +517,11 @@ export async function primeInvokedSkills(if (allPrimedFiles.length > 0) {sessions = new Map();- // session_id is a representative value (first skill's session). ToolNode- // uses per-file session_id from the files array (file.session_id ??- // codeSession.session_id), so mixed sessions work correctly.+ /* `session_id` at the top of CodeSessionContext is the+ * (representative) execution session. Per-file storage is on+ * each file's `storage_session_id`. */sessions.set(Constants.EXECUTE_CODE, {- session_id: allPrimedFiles[0].session_id,+ session_id: allPrimedFiles[0].storage_session_id,files: allPrimedFiles,lastUpdated: Date.now(),} satisfies CodeSessionContext);diff --git a/packages/api/src/files/code/identity.spec.ts b/packages/api/src/files/code/identity.spec.tsnew file mode 100644index 0000000000..642e29e4cf--- /dev/null+++ b/packages/api/src/files/code/identity.spec.ts@@ -0,0 +1,116 @@+import FormData from 'form-data';+import { appendCodeEnvFileIdentity, buildCodeEnvDownloadQuery } from './identity';++describe('appendCodeEnvFileIdentity', () => {+ /* Validation rules mirror codeapi's `parseUploadSessionKeyInput`+ * server-side validator. Asserting client-side gives bad callers a+ * synchronous failure with file path + line number, vs. round-tripping+ * a 400 from a multipart POST. */++ it('appends kind/id/version on the multipart form for skill uploads', () => {+ const form = new FormData();+ appendCodeEnvFileIdentity(form, { kind: 'skill', id: 'skill-42', version: 7 });++ /* Spy on the form internally — `getBuffer()` chokes on stream+ * entries other tests append, but the form has only the three+ * scalar fields here so dump-and-grep is safe. */+ const body = form.getBuffer().toString();+ expect(body).toContain('name="kind"');+ expect(body).toContain('skill');+ expect(body).toContain('name="id"');+ expect(body).toContain('skill-42');+ expect(body).toContain('name="version"');+ expect(body).toContain('7');+ });++ it('omits version on the multipart form for non-skill kinds', () => {+ const form = new FormData();+ appendCodeEnvFileIdentity(form, { kind: 'agent', id: 'agent-9' });+ expect(form.getBuffer().toString()).not.toContain('name="version"');+ });++ it('rejects unknown kinds before mutating the form', () => {+ const form = new FormData();+ expect(() =>+ appendCodeEnvFileIdentity(form, {+ kind: 'system' as 'user',+ id: 'x',+ }),+ ).toThrow(/invalid kind/);+ /* form-data emits multipart boundaries even on an empty form, so+ * "did we append" is a substring check, not buffer equality. */+ expect(form.getBuffer().toString()).not.toContain('name="kind"');+ expect(form.getBuffer().toString()).not.toContain('name="id"');+ });++ it('rejects skill identity without a version', () => {+ expect(() =>+ appendCodeEnvFileIdentity(new FormData(), { kind: 'skill', id: 'skill-42' }),+ ).toThrow(/skill.*version/);+ });++ it('rejects version on non-skill kinds', () => {+ expect(() =>+ appendCodeEnvFileIdentity(new FormData(), {+ kind: 'agent',+ id: 'agent-9',+ version: 3,+ }),+ ).toThrow(/version.*skill/);+ });++ it('rejects missing id', () => {+ expect(() => appendCodeEnvFileIdentity(new FormData(), { kind: 'user', id: '' })).toThrow(+ /missing id/,+ );+ });+});++describe('buildCodeEnvDownloadQuery', () => {+ it('builds the canonical user-private query string', () => {+ expect(buildCodeEnvDownloadQuery({ kind: 'user', id: 'user-123' })).toBe(+ '?kind=user&id=user-123',+ );+ });++ it('appends version when kind is skill', () => {+ expect(buildCodeEnvDownloadQuery({ kind: 'skill', id: 'skill-abc', version: 7 })).toBe(+ '?kind=skill&id=skill-abc&version=7',+ );+ });++ it('omits version on agent kind', () => {+ expect(buildCodeEnvDownloadQuery({ kind: 'agent', id: 'agent-xyz' })).toBe(+ '?kind=agent&id=agent-xyz',+ );+ });++ it('URL-encodes ids that contain special characters', () => {+ /* `id` shouldn't normally contain unsafe chars (it's a uuid or+ * mongo ObjectId), but the URLSearchParams plumbing handles it+ * uniformly so a future call site that passes through a+ * user-supplied identifier doesn't accidentally produce a+ * malformed URL. */+ expect(buildCodeEnvDownloadQuery({ kind: 'user', id: 'a b/c?d' })).toMatch(+ /\?kind=user&id=a\+b%2Fc%3Fd/,+ );+ });++ it('throws on unknown kind', () => {+ expect(() => buildCodeEnvDownloadQuery({ kind: 'system' as 'user', id: 'x' })).toThrow(+ /invalid kind/,+ );+ });++ it('throws on skill missing version', () => {+ expect(() => buildCodeEnvDownloadQuery({ kind: 'skill', id: 'skill-42' })).toThrow(+ /skill.*version/,+ );+ });++ it('throws on version with non-skill kind', () => {+ expect(() => buildCodeEnvDownloadQuery({ kind: 'agent', id: 'agent-9', version: 3 })).toThrow(+ /version.*skill/,+ );+ });+});diff --git a/packages/api/src/files/code/identity.ts b/packages/api/src/files/code/identity.tsnew file mode 100644index 0000000000..731aba492e--- /dev/null+++ b/packages/api/src/files/code/identity.ts@@ -0,0 +1,78 @@+import { CODE_ENV_KINDS } from 'librechat-data-provider';+import type { CodeEnvKind } from 'librechat-data-provider';+import type FormData from 'form-data';++/**+ * Resource identity required by codeapi's sessionKey resolver. The+ * shape is symmetric across the upload form fields and the URL query+ * params on download/freshness routes — codeapi normalizes both into+ * the same `parseUploadSessionKeyInput`. Validation rules (closed+ * kind set, `version` required for `'skill'` and forbidden otherwise)+ * mirror codeapi's validator so a bad caller fails fast on the client+ * instead of round-tripping a 400. See codeapi #1455 / Phase C.+ *+ * `id` is sessionKey-meaningful for `'skill'` / `'agent'` and+ * informational-only for `'user'` (codeapi resolves user identity+ * from auth context). It's required uniformly here for shape+ * consistency with the runtime validator.+ */+export interface CodeEnvIdentity {+ kind: CodeEnvKind;+ id: string;+ /** Required when `kind === 'skill'`; forbidden otherwise. */+ version?: number;+}++const VALID_KINDS = new Set<string>(CODE_ENV_KINDS);++const validateIdentity = (identity: CodeEnvIdentity, callerLabel: string): void => {+ const { kind, id, version } = identity;+ if (!kind || !VALID_KINDS.has(kind)) {+ throw new Error(`${callerLabel}: invalid kind "${kind}"`);+ }+ if (!id) {+ throw new Error(`${callerLabel}: missing id for kind "${kind}"`);+ }+ if (kind === 'skill' && version == null) {+ throw new Error(`${callerLabel}: kind "skill" requires a numeric version`);+ }+ if (kind !== 'skill' && version != null) {+ throw new Error(`${callerLabel}: version is only valid for kind "skill"`);+ }+};++/**+ * Append `kind`/`id`/`version?` form fields to a multipart upload.+ * Used by `uploadCodeEnvFile` and `batchUploadCodeEnvFiles` so codeapi+ * can route the upload to the correct sessionKey bucket+ * (`<tenant>:<kind>:<id>[:v:<version>]` for shared kinds,+ * `<tenant>:user:<authContext.userId>` for `'user'`).+ *+ * Mutates the form in place and throws synchronously on bad input.+ */+export function appendCodeEnvFileIdentity(form: FormData, identity: CodeEnvIdentity): void {+ validateIdentity(identity, 'appendCodeEnvFileIdentity');+ form.append('kind', identity.kind);+ form.append('id', identity.id);+ if (identity.version != null) {+ form.append('version', String(identity.version));+ }+}++/**+ * Build the `?kind=...&id=...&version=...` query string codeapi's+ * `sessionAuth` middleware requires on `/download/<session>/<file>`+ * and `/sessions/<session>/objects/<file>` URLs. Without these,+ * codeapi 400s with "kind must be one of: skill, agent, user" before+ * serving the file.+ *+ * Returns a string with leading `?`; concatenate onto a path.+ */+export function buildCodeEnvDownloadQuery(identity: CodeEnvIdentity): string {+ validateIdentity(identity, 'buildCodeEnvDownloadQuery');+ const params = new URLSearchParams({ kind: identity.kind, id: identity.id });+ if (identity.version != null) {+ params.set('version', String(identity.version));+ }+ return `?${params.toString()}`;+}diff --git a/packages/api/src/files/code/index.ts b/packages/api/src/files/code/index.tsindex b48d6ce3cb..11d2fbb15b 100644--- a/packages/api/src/files/code/index.ts+++ b/packages/api/src/files/code/index.ts@@ -1,3 +1,4 @@export * from './classify';export * from './extract';export * from './form';+export * from './identity';diff --git a/packages/api/src/files/encode/processAttachments.spec.ts b/packages/api/src/files/encode/processAttachments.spec.tsindex 91d6de4a0c..f9af6fd1e7 100644--- a/packages/api/src/files/encode/processAttachments.spec.ts+++ b/packages/api/src/files/encode/processAttachments.spec.ts@@ -16,7 +16,7 @@ function categorizeFile(type?: string | null;source?: string;embedded?: boolean;- metadata?: { fileIdentifier?: string };+ metadata?: { fileIdentifier?: string; codeEnvRef?: unknown };},isBedrock: boolean,mergedFileConfig: FileConfig | undefined,@@ -26,7 +26,11 @@ function categorizeFile(if (source === FileSources.text) {return 'skipped';}- if (file.embedded === true || file.metadata?.fileIdentifier != null) {+ if (+ file.embedded === true ||+ file.metadata?.codeEnvRef != null ||+ file.metadata?.fileIdentifier != null+ ) {return 'skipped';}diff --git a/packages/api/src/utils/axios.ts b/packages/api/src/utils/axios.tsindex 5d73955f0f..bab5242d8e 100644--- a/packages/api/src/utils/axios.ts+++ b/packages/api/src/utils/axios.ts@@ -1,7 +1,37 @@+import { Buffer } from 'buffer';import axios from 'axios';import { logger } from '@librechat/data-schemas';import type { AxiosInstance, AxiosProxyConfig, AxiosError } from 'axios';+/**+ * Render `error.response.data` as a small, log-safe value. Axios surfaces+ * the response body in whichever native shape the request asked for, so+ * `responseType: 'arraybuffer'` yields a `Buffer` (raw bytes — JSON-+ * serializes as `{type: 'Buffer', data: [123, 34, ...]}`, ~4 chars per+ * byte) and `responseType: 'stream'` yields a `Readable` (whose internal+ * state JSON-serializes the full readableState ring buffer + socket+ * fields, easily megabytes per error). Both are useless for diagnostics+ * and drown the log line. Decode small buffers as UTF-8 (truncated) and+ * stub streams entirely.+ */+const renderResponseData = (data: unknown): unknown => {+ if (data == null) return data;+ if (Buffer.isBuffer(data)) {+ const MAX = 2048;+ const text = data.subarray(0, MAX).toString('utf8');+ return data.length > MAX ? `${text}…[+${data.length - MAX} bytes]` : text;+ }+ // Readable streams (responseType: 'stream') and other piped sources.+ if (+ typeof data === 'object' &&+ data !== null &&+ typeof (data as { pipe?: unknown }).pipe === 'function'+ ) {+ return '[stream]';+ }+ return data;+};+/*** Logs Axios errors based on the error object and a custom message.* @param options - The options object.@@ -33,7 +63,7 @@ export const logAxiosError = ({logger.error(logMessage, {status,headers,- data,+ data: renderResponseData(data),stack,});} else if (axios.isAxiosError(error) && error.request) {diff --git a/packages/data-provider/src/codeEnvRef.spec.ts b/packages/data-provider/src/codeEnvRef.spec.tsnew file mode 100644index 0000000000..561850c502--- /dev/null+++ b/packages/data-provider/src/codeEnvRef.spec.ts@@ -0,0 +1,55 @@+/* `CodeEnvRef` is a plain typed struct (no helpers, no resolvers).+ * Behavioral coverage lives at consumer sites — `processCodeOutput`+ * (write), `primeFiles` (read+reupload), `primeSkillFiles` (read+write),+ * agents `ToolNode` (forward to codeapi). This file just pins the+ * shape so a future refactor can't silently widen or narrow the+ * fields without surfacing here. */+import { CODE_ENV_KINDS } from './codeEnvRef';+import type { CodeEnvKind, CodeEnvRef } from './codeEnvRef';++describe('CodeEnvRef', () => {+ it('accepts the canonical shape for kind: skill', () => {+ const ref: CodeEnvRef = {+ kind: 'skill',+ id: 'skill_123',+ storage_session_id: 'sess_abc',+ file_id: 'file_xyz',+ version: 7,+ };+ expect(ref.kind).toBe('skill');+ expect(ref.version).toBe(7);+ });++ it('accepts the canonical shape for kind: user', () => {+ const ref: CodeEnvRef = {+ kind: 'user',+ id: 'user_456',+ storage_session_id: 'sess_def',+ file_id: 'file_uvw',+ };+ expect(ref.kind).toBe('user');+ /* `version` is statically absent on the user variant of the+ * discriminated union — the property doesn't exist on the type, so+ * accessing it would be a compile error. Probe at runtime via an+ * `unknown` cast to assert the absence at runtime as well. */+ expect((ref as unknown as Record<string, unknown>).version).toBeUndefined();+ });++ it('accepts the canonical shape for kind: agent', () => {+ const ref: CodeEnvRef = {+ kind: 'agent',+ id: 'agent_789',+ storage_session_id: 'sess_ghi',+ file_id: 'file_rst',+ };+ expect(ref.kind).toBe('agent');+ });++ it('CODE_ENV_KINDS pins the closed set of kinds', () => {+ /* Adding a new kind requires updating the runtime tuple AND+ * surfacing it in `resolveSessionKey`'s exhaustive switch. The+ * `as const` shape makes this catch-able by the type system. */+ const kinds: CodeEnvKind[] = [...CODE_ENV_KINDS];+ expect(kinds).toEqual(['skill', 'agent', 'user']);+ });+});diff --git a/packages/data-provider/src/codeEnvRef.ts b/packages/data-provider/src/codeEnvRef.tsnew file mode 100644index 0000000000..469592bfdc--- /dev/null+++ b/packages/data-provider/src/codeEnvRef.ts@@ -0,0 +1,59 @@+/**+ * Closed set of resource kinds for sandbox file caching. Defined as a+ * `as const` tuple so the runtime list and the TypeScript union can't+ * drift on future additions — adding a new kind to the tuple updates+ * both at once.+ *+ * - `skill`: shared per skill identity. Cross-user-within-tenant+ * sharing. CodeAPI sessionKey omits the user dimension.+ * `version` is required (the skill's monotonic counter scopes the+ * cache per revision so any edit invalidates the prior cache+ * entry naturally).+ * - `agent`: shared per agent identity. Same sharing semantic as+ * skills (agents are addressable resources accessible to a+ * permission-defined audience).+ * - `user`: user-private. CodeAPI sessionKey is keyed by the+ * requesting user from auth context. Used for chat attachments+ * and code-output artifacts.+ */+export const CODE_ENV_KINDS = ['skill', 'agent', 'user'] as const;+export type CodeEnvKind = (typeof CODE_ENV_KINDS)[number];++/**+ * Typed reference to a file in the code-execution sandbox.+ *+ * `storage_session_id` is intentionally distinct from the *execution*+ * session id at the top level of an execute response — they are+ * different concepts that historically shared the field name+ * `session_id`. This is the long-lived storage session keyed by the+ * resource's identity (skill/agent/user), not the transient+ * sandbox-run session.+ *+ * `kind` and `id` together name the resource that owns this file's+ * storage session. CodeAPI uses them (plus the auth-context tenant+ * id) to derive the sessionKey, which determines who shares the+ * cache. Cross-user sharing for shared resources (skills, agents) is+ * a designed property of the kind switch, not an emergent side+ * effect. See codeapi #1455 / agents #148 / LC #12960.+ *+ * `version` is statically required when `kind === 'skill'` and+ * statically forbidden otherwise via the discriminated union below —+ * the constraint is enforced at compile time, not just by codeapi's+ * runtime validator.+ */+interface CodeEnvRefBase {+ /** Resource identity. Semantics depend on `kind`:+ * - `skill`: skill `_id` (sessionKey-meaningful, cross-user shared).+ * - `agent`: agent id (sessionKey-meaningful, cross-user shared).+ * - `user`: informational only — sessionKey derivation uses the+ * requesting user from auth context. Kept on the type for shape+ * uniformity across kinds; do not rely on it for routing. */+ id: string;+ storage_session_id: string;+ file_id: string;+}++export type CodeEnvRef =+ | (CodeEnvRefBase & { kind: 'skill'; version: number })+ | (CodeEnvRefBase & { kind: 'agent' })+ | (CodeEnvRefBase & { kind: 'user' });diff --git a/packages/data-provider/src/index.ts b/packages/data-provider/src/index.tsindex aab5752f7d..bb166d975a 100644--- a/packages/data-provider/src/index.ts+++ b/packages/data-provider/src/index.ts@@ -49,3 +49,5 @@ export { default as createPayload } from './createPayload';/* feedback */export * from './feedback';export * from './parameterSettings';+/* code-execution sandbox */+export * from './codeEnvRef';diff --git a/packages/data-provider/src/types/files.ts b/packages/data-provider/src/types/files.tsindex 6771033614..1d6f17c371 100644--- a/packages/data-provider/src/types/files.ts+++ b/packages/data-provider/src/types/files.ts@@ -1,4 +1,5 @@import { EToolResources } from './assistants';+import type { CodeEnvRef } from '../codeEnvRef';export enum FileSources {local = 'local',@@ -144,7 +145,15 @@ export type TFile = {* Suitable for tooltip text but not user-facing prose.*/previewError?: string;- metadata?: { fileIdentifier?: string };+ metadata?: {+ fileIdentifier?: string;+ /**+ * Structured form of `fileIdentifier`. Persisted alongside the+ * legacy string during the dual-write transition; readers should+ * resolve via `resolveCodeEnvRef`.+ */+ codeEnvRef?: CodeEnvRef;+ };createdAt?: string | Date;updatedAt?: string | Date;};diff --git a/packages/data-schemas/src/methods/file.spec.ts b/packages/data-schemas/src/methods/file.spec.tsindex e3882f4958..cb573c9df3 100644--- a/packages/data-schemas/src/methods/file.spec.ts+++ b/packages/data-schemas/src/methods/file.spec.ts@@ -299,7 +299,14 @@ describe('File Methods', () => {type: 'text/x-python',bytes: 100,context: FileContext.execute_code,- metadata: { fileIdentifier: 'some-identifier' },+ metadata: {+ codeEnvRef: {+ kind: 'user',+ id: userId.toString(),+ storage_session_id: 'session-x',+ file_id: codeFileId,+ },+ },});// execute_code files are explicitly excluded from getToolFilesByIdsdiff --git a/packages/data-schemas/src/methods/file.ts b/packages/data-schemas/src/methods/file.tsindex 61beee5b17..4261588a33 100644--- a/packages/data-schemas/src/methods/file.ts+++ b/packages/data-schemas/src/methods/file.ts@@ -128,7 +128,7 @@ export function createFileMethods(mongoose: typeof import('mongoose')) {conversationId,context: FileContext.execute_code,messageId: { $exists: true, $in: messageIds },- 'metadata.fileIdentifier': { $exists: true },+ 'metadata.codeEnvRef': { $exists: true },};const selectFields: SelectProjection = { text: 0 };@@ -158,7 +158,7 @@ export function createFileMethods(mongoose: typeof import('mongoose')) {const filter: FilterQuery<IMongoFile> = {file_id: { $in: fileIds },context: { $ne: FileContext.execute_code },- 'metadata.fileIdentifier': { $exists: true },+ 'metadata.codeEnvRef': { $exists: true },};const selectFields: SelectProjection = { text: 0 };diff --git a/packages/data-schemas/src/methods/skill.spec.ts b/packages/data-schemas/src/methods/skill.spec.tsindex 86cf101678..85ecf41bf8 100644--- a/packages/data-schemas/src/methods/skill.spec.ts+++ b/packages/data-schemas/src/methods/skill.spec.ts@@ -1339,6 +1339,67 @@ describe('SkillFile methods', () => {expect(files[0].storageRegion).toBe('us-east-2');});+ it('clears codeEnvRef when a skill file is upserted (replacement)', async () => {+ /* A re-upload of a skill file replaces the row's contents — but the+ * cached `codeEnvRef` refers to the OLD bytes living in codeapi.+ * Leaving it populated would make the next prime resolve a stale+ * pointer. The upsert MUST $unset codeEnvRef. */+ const { skill } = await methods.createSkill(makeSkillInput());+ await methods.upsertSkillFile({+ skillId: skill._id,+ relativePath: 'scripts/parse.sh',+ file_id: 'file-1',+ filename: 'parse.sh',+ filepath: '/tmp/v1',+ source: 'local',+ mimeType: 'text/plain',+ bytes: 10,+ author: owner._id,+ });++ const entityId = skill._id.toString();+ await methods.updateSkillFileCodeEnvIds([+ {+ skillId: skill._id,+ relativePath: 'scripts/parse.sh',+ codeEnvRef: {+ kind: 'skill',+ id: entityId,+ storage_session_id: 'sess-old',+ file_id: 'file-old',+ version: 1,+ },+ },+ ]);++ /* Sanity: ref is persisted before the replacement. */+ const before = await methods.listSkillFiles(skill._id);+ expect(before[0].codeEnvRef).toMatchObject({+ kind: 'skill',+ storage_session_id: 'sess-old',+ file_id: 'file-old',+ version: 1,+ });++ /* Replace the row with new bytes. */+ await methods.upsertSkillFile({+ skillId: skill._id,+ relativePath: 'scripts/parse.sh',+ file_id: 'file-2',+ filename: 'parse.sh',+ filepath: '/tmp/v2',+ source: 'local',+ mimeType: 'text/plain',+ bytes: 20,+ author: owner._id,+ });++ const after = await methods.listSkillFiles(skill._id);+ expect(after).toHaveLength(1);+ expect(after[0].file_id).toBe('file-2');+ expect(after[0].codeEnvRef).toBeUndefined();+ });+it('deleteSkillFile recounts and bumps version', async () => {const { skill } = await methods.createSkill(makeSkillInput());await methods.upsertSkillFile({@@ -1395,7 +1456,7 @@ describe('SkillFile methods', () => {* egress per chat load). Pinning the contract here so the caller* can warn-log on partial writes instead of failing closed.*/- it('persists codeEnvIdentifier and reports matched/modified counts', async () => {+ it('persists codeEnvRef and reports matched/modified counts', async () => {const { skill } = await methods.createSkill(makeSkillInput());await methods.upsertSkillFile({skillId: skill._id,@@ -1409,11 +1470,18 @@ describe('SkillFile methods', () => {author: owner._id,});+ const entityId = skill._id.toString();const result = await methods.updateSkillFileCodeEnvIds([{skillId: skill._id,relativePath: 'scripts/a.sh',- codeEnvIdentifier: `session-1/file-1?entity_id=${skill._id.toString()}`,+ codeEnvRef: {+ kind: 'skill',+ id: entityId,+ storage_session_id: 'session-1',+ file_id: 'file-1',+ version: 1,+ },},]);@@ -1421,7 +1489,13 @@ describe('SkillFile methods', () => {expect(result.modifiedCount).toBe(1);const files = await methods.listSkillFiles(skill._id);- expect(files[0].codeEnvIdentifier).toBe(`session-1/file-1?entity_id=${skill._id.toString()}`);+ expect(files[0].codeEnvRef).toMatchObject({+ kind: 'skill',+ id: entityId,+ storage_session_id: 'session-1',+ file_id: 'file-1',+ version: 1,+ });});it('reports modifiedCount=0 when no SkillFile rows match the (skillId, relativePath) filter', async () => {@@ -1430,7 +1504,13 @@ describe('SkillFile methods', () => {{skillId: skill._id,relativePath: 'does/not/exist.sh',- codeEnvIdentifier: 'sid/fid?entity_id=x',+ codeEnvRef: {+ kind: 'skill',+ id: 'x',+ storage_session_id: 'sid',+ file_id: 'fid',+ version: 1,+ },},]);expect(result.modifiedCount).toBe(0);diff --git a/packages/data-schemas/src/methods/skill.ts b/packages/data-schemas/src/methods/skill.tsindex 502ca34c47..bc1d2260c6 100644--- a/packages/data-schemas/src/methods/skill.ts+++ b/packages/data-schemas/src/methods/skill.ts@@ -7,6 +7,7 @@ import {SKILL_BODY_MAX_LENGTH,SKILL_NAME_PATTERN as SKILL_NAME_PATTERN_SHARED,} from 'librechat-data-provider';+import type { CodeEnvRef } from 'librechat-data-provider';import type { Model, Types, FilterQuery } from 'mongoose';import type {ISkill,@@ -1436,7 +1437,7 @@ export function createSkillMethods(mongoose: typeof import('mongoose'), deps: Skauthor: row.author,tenantId: row.tenantId,},- $unset: { content: '', isBinary: '', codeEnvIdentifier: '' },+ $unset: { content: '', isBinary: '', codeEnvRef: '' },},{ new: false, upsert: true },).lean();@@ -1493,7 +1494,7 @@ export function createSkillMethods(mongoose: typeof import('mongoose'), deps: Skupdates: Array<{skillId: Types.ObjectId | string;relativePath: string;- codeEnvIdentifier: string;+ codeEnvRef: CodeEnvRef;}>,): Promise<{ matchedCount: number; modifiedCount: number }> {if (updates.length === 0) return { matchedCount: 0, modifiedCount: 0 };@@ -1501,7 +1502,7 @@ export function createSkillMethods(mongoose: typeof import('mongoose'), deps: Skconst ops = updates.map((u) => ({updateOne: {filter: { skillId: u.skillId, relativePath: u.relativePath },- update: { $set: { codeEnvIdentifier: u.codeEnvIdentifier } },+ update: { $set: { codeEnvRef: u.codeEnvRef } },},}));@@ -1515,7 +1516,7 @@ export function createSkillMethods(mongoose: typeof import('mongoose'), deps: Skconst result = await tenantSafeBulkWrite(SkillFile, ops);if (result.modifiedCount < updates.length) {logger.warn(- `[updateSkillFileCodeEnvIds] Persisted ${result.modifiedCount}/${updates.length} codeEnvIdentifiers (matched ${result.matchedCount}). Subsequent primes for unmatched files will re-upload.`,+ `[updateSkillFileCodeEnvIds] Persisted ${result.modifiedCount}/${updates.length} codeEnvRefs (matched ${result.matchedCount}). Subsequent primes for unmatched files will re-upload.`,);}return { matchedCount: result.matchedCount, modifiedCount: result.modifiedCount };diff --git a/packages/data-schemas/src/schema/file.ts b/packages/data-schemas/src/schema/file.tsindex 4b9d462b2d..c8e7c72f52 100644--- a/packages/data-schemas/src/schema/file.ts+++ b/packages/data-schemas/src/schema/file.ts@@ -118,7 +118,23 @@ const file: Schema<IMongoFile> = new Schema(width: Number,height: Number,metadata: {- fileIdentifier: String,+ codeEnvRef: {+ type: new Schema(+ {+ kind: {+ type: String,+ enum: ['skill', 'agent', 'user'],+ required: true,+ },+ id: { type: String, required: true },+ storage_session_id: { type: String, required: true },+ file_id: { type: String, required: true },+ version: { type: Number },+ },+ { _id: false },+ ),+ default: undefined,+ },},expiresAt: {type: Date,diff --git a/packages/data-schemas/src/schema/skillFile.ts b/packages/data-schemas/src/schema/skillFile.tsindex fbaa35155c..efb5a29c1d 100644--- a/packages/data-schemas/src/schema/skillFile.ts+++ b/packages/data-schemas/src/schema/skillFile.ts@@ -102,8 +102,22 @@ const skillFileSchema: Schema<ISkillFileDocument> = new Schema(isBinary: {type: Boolean,},- codeEnvIdentifier: {- type: String,+ codeEnvRef: {+ type: new Schema(+ {+ kind: {+ type: String,+ enum: ['skill', 'agent', 'user'],+ required: true,+ },+ id: { type: String, required: true },+ storage_session_id: { type: String, required: true },+ file_id: { type: String, required: true },+ version: { type: Number },+ },+ { _id: false },+ ),+ default: undefined,},},{diff --git a/packages/data-schemas/src/types/file.ts b/packages/data-schemas/src/types/file.tsindex 28170ee57f..b47a18abb6 100644--- a/packages/data-schemas/src/types/file.ts+++ b/packages/data-schemas/src/types/file.ts@@ -1,4 +1,5 @@import { Document, Types } from 'mongoose';+import type { CodeEnvRef } from 'librechat-data-provider';export interface IMongoFile extends Omit<Document, 'model'> {user: Types.ObjectId;@@ -62,7 +63,13 @@ export interface IMongoFile extends Omit<Document, 'model'> {width?: number;height?: number;metadata?: {- fileIdentifier?: string;+ /**+ * Code-environment cache pointer for files re-uploadable to+ * codeapi (chat attachments, agent tool resources, code-output+ * files). Carries the resource kind + identity so codeapi can+ * derive the sessionKey explicitly.+ */+ codeEnvRef?: CodeEnvRef;};expiresAt?: Date;createdAt?: Date;diff --git a/packages/data-schemas/src/types/skill.ts b/packages/data-schemas/src/types/skill.tsindex 90555ffe65..a2cba928d1 100644--- a/packages/data-schemas/src/types/skill.ts+++ b/packages/data-schemas/src/types/skill.ts@@ -1,3 +1,4 @@+import type { CodeEnvRef } from 'librechat-data-provider';import type { Document, Types } from 'mongoose';/**@@ -130,11 +131,11 @@ export interface ISkillFile {/** Set on first read. `true` prevents repeated storage reads for non-text files. */isBinary?: boolean;/**- * Code environment file identifier (`session_id/fileId`).- * Set after uploading to code env, used to check freshness on subsequent runs.- * Cleared when the skill file is re-uploaded to storage.+ * Code-environment cache pointer. Set after uploading the file to+ * codeapi, used to check freshness on subsequent primes. Cleared+ * when the skill file is re-uploaded to storage.*/- codeEnvIdentifier?: string;+ codeEnvRef?: CodeEnvRef;createdAt?: Date;updatedAt?: Date;}