@librechat/agents 3.1.80-dev.0 → 3.1.80-dev.2

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

@@ -144,14 +144,33 @@ export declare const CODE_ENV_KINDS: readonly ["skill", "agent", "user"];
 export type CodeEnvKind = (typeof CODE_ENV_KINDS)[number];
 type CodeEnvFileBase = {
     /**
-     * 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 — codeapi derives sessionKey from
-     *    the auth-context user. Kept on the type for shape uniformity;
-     *    do not rely on it for routing.
+     * **Storage file id** — the per-file uuid the file_server returns
+     * at upload time. Identifies the bytes at
+     * `<storage_session_id>/<id>` in the object bucket; used by the
+     * worker to fetch the file and by codeapi's auth layer for the
+     * upload-existence check.
+     *
+     * Distinct from `resource_id` below — that's the entity that owns
+     * this file's storage session (skill `_id`, agent id, etc.), used
+     * for sessionKey resolution. Conflating the two caused
+     * shared-kind authorization to fail because the sessionKey
+     * re-derivation used the storage nanoid where the resource id was
+     * required. See codeapi #1455 review.
      */
     id: string;
+    /**
+     * **Resource id** — the entity that owns this file's storage
+     * session. Skill `_id` for `kind: 'skill'`, agent id for `'agent'`,
+     * informational only for `'user'` (codeapi resolves user identity
+     * from auth context). Kept on the type for shape uniformity across
+     * kinds.
+     *
+     * Drives codeapi's `resolveSessionKey` switch — the sessionKey
+     * embeds this value (`<tenant>:<kind>:<resource_id>[:v:<version>]`)
+     * so cross-user-within-tenant sharing for shared kinds is a
+     * designed property of the kind switch.
+     */
+    resource_id: string;
     name: string;
     /**
      * Storage session — the long-lived bucket where this file's bytes
@@ -189,12 +208,17 @@ export type CodeExecutionToolParams = undefined | {
 };
 export type FileRef = {
     /**
-     * Resource identity. Semantics depend on `kind` (when present):
-     *  - `skill` / `agent`: shared resource id (sessionKey-meaningful).
-     *  - `user`: informational only — codeapi derives sessionKey from
-     *    the auth-context user. Do not rely on it for routing.
+     * Storage file id (the per-file uuid). See `CodeEnvFile.id` for
+     * the full motivation behind the storage-vs-resource split.
      */
     id: string;
+    /**
+     * Resource id — the entity that owns this file's storage session.
+     * Optional on `FileRef` (post-execute artifact refs may not carry
+     * resource provenance for outputs); required on `CodeEnvFile`
+     * (the input wire shape).
+     */
+    resource_id?: string;
     name: string;
     path?: string;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.80-dev.0",
+  "version": "3.1.80-dev.2",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/tools/BashExecutor.ts

@@ -168,6 +168,9 @@ function createBashExecutionTool(
                  * to the user; tag them user-private. */
                 kind: 'user' as const,
                 id,
+                /* `resource_id` informational for `kind: 'user'` —
+                 * codeapi derives sessionKey from auth context. */
+                resource_id: id,
                 name: file.metadata['original-filename'],
               };
             });

package/src/tools/CodeExecutor.ts

@@ -194,6 +194,11 @@ function createCodeExecutionTool(
                  * to the user; tag them user-private. */
                 kind: 'user' as const,
                 id,
+                /* `resource_id` is informational for `kind: 'user'`
+                 * (codeapi derives sessionKey from auth context); use
+                 * the same value as `id` since the `/files` fallback
+                 * doesn't carry separate provenance. */
+                resource_id: id,
                 name: file.metadata['original-filename'],
               };
             });

package/src/tools/ProgrammaticToolCalling.ts

@@ -309,6 +309,9 @@ export async function fetchSessionFiles(
          * the user; tag them user-private. */
         kind: 'user' as const,
         id,
+        /* `resource_id` informational for `kind: 'user'` —
+         * codeapi derives sessionKey from auth context. */
+        resource_id: id,
         name: (file.metadata as Record<string, unknown>)[
           'original-filename'
         ] as string,

package/src/tools/ToolNode.ts

@@ -274,10 +274,20 @@ function normalizeApprovalDecisions(
  * the upstream contract bug surfaces as a degraded sessionKey rather
  * than a runtime crash; primeSkillFiles is the only writer, and it
  * always sets `version` — see LC packages/api/src/agents/skillFiles.ts.
+ *
+ * `resource_id` carries the entity-that-owns-this-file's-session
+ * identity (skill `_id` etc.); falls back to `id` (the storage
+ * file_id) for inputs that haven't been updated to send the field
+ * explicitly. The fallback degrades sessionKey resolution on the
+ * codeapi side for shared kinds (it'll match the storage nanoid
+ * against a skill _id and 403) — but won't crash, so an unmigrated
+ * client still produces a diagnosable error instead of a stack
+ * trace.
  */
 function toInjectedFileRef(
   file: {
     id: string;
+    resource_id?: string;
     name: string;
     storage_session_id?: string;
     kind?: t.CodeEnvKind;
@@ -287,6 +297,7 @@ function toInjectedFileRef(
 ): t.CodeEnvFile {
   const base = {
     id: file.id,
+    resource_id: file.resource_id ?? file.id,
     name: file.name,
     /* Inline `content` files have no persistent storage location;
      * fall back to the execution session id for those entries. */
@@ -302,6 +313,15 @@ function toInjectedFileRef(
   return { ...base, kind: 'user' };
 }
 
+/* Stable file identity = `(storage_session_id, id)`. Same name in
+ * different storage sessions are distinct files. */
+function fileIdentityKey(file: {
+  storage_session_id?: string;
+  id: string;
+}): string {
+  return `${file.storage_session_id ?? ''}\0${file.id}`;
+}
+
 function updateCodeSession(
   sessions: t.ToolSessionMap,
   execSessionId: string,
@@ -313,27 +333,50 @@ function updateCodeSession(
     | undefined;
   const existingFiles = existingSession?.files ?? [];
 
-  if (newFiles.length > 0) {
-    const filesWithSession: t.FileRefs = newFiles.map((file) => ({
-      ...file,
-      storage_session_id: file.storage_session_id ?? execSessionId,
-    }));
-    const newFileNames = new Set(filesWithSession.map((f) => f.name));
-    const filteredExisting = existingFiles.filter(
-      (f) => !newFileNames.has(f.name)
-    );
-    sessions.set(Constants.EXECUTE_CODE, {
-      session_id: execSessionId,
-      files: [...filteredExisting, ...filesWithSession],
-      lastUpdated: Date.now(),
-    });
-  } else {
+  if (newFiles.length === 0) {
     sessions.set(Constants.EXECUTE_CODE, {
       session_id: execSessionId,
       files: existingFiles,
       lastUpdated: Date.now(),
     });
+    return;
   }
+
+  /* Worker echoes lack ownership identity (kind/resource_id/version) —
+   * sandbox doesn't re-attest; that's signed at upload. Merge by
+   * (storage_session_id, id) so prior identity survives the echo. */
+  const filesWithSession: t.FileRefs = [];
+  const newFileNames = new Set<string>();
+  const incomingByIdentity = new Map<string, number>();
+  for (const file of newFiles) {
+    const withSession = {
+      ...file,
+      storage_session_id: file.storage_session_id ?? execSessionId,
+    };
+    incomingByIdentity.set(
+      fileIdentityKey(withSession),
+      filesWithSession.length
+    );
+    newFileNames.add(withSession.name);
+    filesWithSession.push(withSession);
+  }
+
+  const filteredExisting: t.FileRefs = [];
+  for (const e of existingFiles) {
+    const idx = incomingByIdentity.get(fileIdentityKey(e));
+    if (idx !== undefined) {
+      filesWithSession[idx] = { ...e, ...filesWithSession[idx] };
+    }
+    if (!newFileNames.has(e.name)) {
+      filteredExisting.push(e);
+    }
+  }
+
+  sessions.set(Constants.EXECUTE_CODE, {
+    session_id: execSessionId,
+    files: [...filteredExisting, ...filesWithSession],
+    lastUpdated: Date.now(),
+  });
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/tools/__tests__/ToolNode.session.test.ts

@@ -84,12 +84,20 @@ describe('ToolNode code execution session management', () => {
       expect(capturedConfigs[0]._injected_files).toEqual([
         {
           id: 'file1',
+          /* `resource_id` defaults to `id` (the storage uuid) when
+           * the input ref didn't supply it — informational for
+           * `kind: 'user'` since codeapi derives sessionKey from
+           * auth context. The real LC priming chain DOES supply
+           * resource_id explicitly; the default is a back-compat
+           * landing for inputs that haven't been updated. */
+          resource_id: 'file1',
           name: 'data.csv',
           storage_session_id: 'prev-session-abc',
           kind: 'user',
         },
         {
           id: 'file2',
+          resource_id: 'file2',
           name: 'chart.png',
           storage_session_id: 'prev-session-abc',
           kind: 'user',
@@ -195,6 +203,9 @@ describe('ToolNode code execution session management', () => {
       expect(files).toEqual([
         {
           id: 'skill-123',
+          /* Default fallback when input doesn't supply `resource_id`.
+           * Production LC sets it explicitly to the skill's `_id`. */
+          resource_id: 'skill-123',
           name: 'demo/SKILL.md',
           storage_session_id: 'session-A',
           kind: 'skill',
@@ -202,6 +213,7 @@ describe('ToolNode code execution session management', () => {
         },
         {
           id: 'user-file',
+          resource_id: 'user-file',
           name: 'attachment.csv',
           storage_session_id: 'session-B',
           kind: 'user',
@@ -241,6 +253,9 @@ describe('ToolNode code execution session management', () => {
         files: [
           {
             id: 'ef1',
+            /* `resource_id` defaults to `id` when input doesn't carry
+             * separate provenance — see toInjectedFileRef. */
+            resource_id: 'ef1',
             name: 'out.parquet',
             storage_session_id: 'evt-session',
             kind: 'user',
@@ -327,6 +342,8 @@ describe('ToolNode code execution session management', () => {
         files: [
           {
             id: 'skill-abc',
+            /* Default fallback when input doesn't supply `resource_id`. */
+            resource_id: 'skill-abc',
             name: 'demo/SKILL.md',
             storage_session_id: 'evt-session',
             kind: 'skill',
@@ -334,6 +351,7 @@ describe('ToolNode code execution session management', () => {
           },
           {
             id: 'usr1',
+            resource_id: 'usr1',
             name: 'data.csv',
             storage_session_id: 'evt-session',
             kind: 'user',
@@ -494,6 +512,188 @@ describe('ToolNode code execution session management', () => {
       expect(chartFile!.storage_session_id).toBe('new-sess');
     });
 
+    it('preserves prior kind/resource_id/version when worker echoes inherited file (skill 403 regression)', () => {
+      /**
+       * Regression for the codeapi `session_key_mismatch` 403 that
+       * fires on the second `/exec` after a successful skill prime.
+       *
+       * Worker `inherited: true` echoes carry only
+       * `(id, name, storage_session_id)` — the sandbox doesn't know
+       * the resource identity (`kind`, `resource_id`, `version`),
+       * which was signed at upload time. If `updateCodeSession`
+       * replaces the prior entry verbatim from the echo, the next
+       * `_injected_files` derivation reads `kind: undefined` and
+       * `toInjectedFileRef` falls back to `kind: 'user'` +
+       * `resource_id: file.id`. Codeapi then resolves
+       * `legacy:user:<authContext.userId>`, which doesn't match the
+       * cached `legacy:skill:<skillId>:v:<v>` set at upload, and
+       * authorization 403s.
+       *
+       * The merge must overlay the echo onto the prior entry by
+       * `(storage_session_id, id)` so identity survives.
+       */
+      const SKILL_ID = '69dcf561f37f717858d4d072';
+      const SKILL_VERSION = 59;
+      const STORAGE_SESSION = 'p28pbmz0ejTZ8MMEkObN8';
+      const FILE_ID = 'JqnzC4f6gpirzW0yq_obR';
+
+      const sessions: t.ToolSessionMap = new Map();
+      sessions.set(Constants.EXECUTE_CODE, {
+        session_id: STORAGE_SESSION,
+        files: [
+          {
+            id: FILE_ID,
+            resource_id: SKILL_ID,
+            name: 'pptx/editing.md',
+            storage_session_id: STORAGE_SESSION,
+            kind: 'skill',
+            version: SKILL_VERSION,
+          },
+        ],
+        lastUpdated: Date.now(),
+      } satisfies t.CodeSessionContext);
+
+      const mockTool = createMockCodeTool({ capturedConfigs: [] });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions,
+        eventDrivenMode: true,
+      });
+
+      const storeMethod = (
+        toolNode as unknown as {
+          storeCodeSessionFromResults: (
+            results: t.ToolExecuteResult[],
+            requestMap: Map<string, t.ToolCallRequest>
+          ) => void;
+        }
+      ).storeCodeSessionFromResults.bind(toolNode);
+
+      /* Worker echo shape — exactly what codeapi sends on
+       * `inherited: true` files. No kind, no resource_id, no version. */
+      storeMethod(
+        [
+          {
+            toolCallId: 'tc-skill-rerun',
+            content: 'output',
+            artifact: {
+              session_id: 'exec-sess-2',
+              files: [
+                {
+                  id: FILE_ID,
+                  name: 'pptx/editing.md',
+                  storage_session_id: STORAGE_SESSION,
+                  inherited: true,
+                } as unknown as t.FileRefs[number],
+              ],
+            },
+            status: 'success',
+          },
+        ],
+        new Map([
+          [
+            'tc-skill-rerun',
+            { id: 'tc-skill-rerun', name: Constants.EXECUTE_CODE, args: {} },
+          ],
+        ])
+      );
+
+      const stored = sessions.get(
+        Constants.EXECUTE_CODE
+      ) as t.CodeSessionContext;
+      const merged = stored.files!.find((f) => f.id === FILE_ID);
+      expect(merged).toBeDefined();
+      /* Identity preserved from prior entry: */
+      expect(merged!.kind).toBe('skill');
+      expect(merged!.resource_id).toBe(SKILL_ID);
+      expect((merged as { version?: number }).version).toBe(SKILL_VERSION);
+      /* Echo-owned fields propagated: */
+      expect((merged as { inherited?: boolean }).inherited).toBe(true);
+    });
+
+    it('uses fresh kind defaults for genuinely new files (no prior entry to merge from)', () => {
+      /**
+       * The merge keys on `(storage_session_id, id)`, not `name`.
+       * A file the worker emits for the first time (typical
+       * code-output / generated artifact) has no prior to inherit
+       * identity from — it lands as `kind: 'user'` via the standard
+       * fallback in `toInjectedFileRef`. Locks the contract that
+       * the merge doesn't accidentally re-tag user output as skill.
+       */
+      const sessions: t.ToolSessionMap = new Map();
+      sessions.set(Constants.EXECUTE_CODE, {
+        session_id: 'old-sess',
+        files: [
+          {
+            id: 'skill-f1',
+            resource_id: 'skill-id-1',
+            name: 'pptx/editing.md',
+            storage_session_id: 'skill-storage',
+            kind: 'skill',
+            version: 7,
+          },
+        ],
+        lastUpdated: Date.now(),
+      } satisfies t.CodeSessionContext);
+
+      const mockTool = createMockCodeTool({ capturedConfigs: [] });
+      const toolNode = new ToolNode({
+        tools: [mockTool],
+        sessions,
+        eventDrivenMode: true,
+      });
+
+      const storeMethod = (
+        toolNode as unknown as {
+          storeCodeSessionFromResults: (
+            results: t.ToolExecuteResult[],
+            requestMap: Map<string, t.ToolCallRequest>
+          ) => void;
+        }
+      ).storeCodeSessionFromResults.bind(toolNode);
+
+      storeMethod(
+        [
+          {
+            toolCallId: 'tc-output',
+            content: 'output',
+            artifact: {
+              session_id: 'output-sess',
+              files: [
+                {
+                  id: 'fresh-output-id',
+                  name: 'generated-chart.png',
+                  storage_session_id: 'output-sess',
+                } as unknown as t.FileRefs[number],
+              ],
+            },
+            status: 'success',
+          },
+        ],
+        new Map([
+          [
+            'tc-output',
+            { id: 'tc-output', name: Constants.EXECUTE_CODE, args: {} },
+          ],
+        ])
+      );
+
+      const stored = sessions.get(
+        Constants.EXECUTE_CODE
+      ) as t.CodeSessionContext;
+      const fresh = stored.files!.find((f) => f.id === 'fresh-output-id');
+      expect(fresh).toBeDefined();
+      /* No prior to inherit from — kind/resource_id/version absent
+       * on the entry; toInjectedFileRef will default kind to 'user'
+       * downstream. */
+      expect(fresh!.kind).toBeUndefined();
+      expect(fresh!.resource_id).toBeUndefined();
+      expect((fresh as { version?: number }).version).toBeUndefined();
+      /* Skill file untouched. */
+      const skillFile = stored.files!.find((f) => f.id === 'skill-f1');
+      expect(skillFile!.kind).toBe('skill');
+    });
+
     it('preserves existing files when new execution has no files', () => {
       const sessions: t.ToolSessionMap = new Map();
       sessions.set(Constants.EXECUTE_CODE, {
@@ -835,6 +1035,9 @@ describe('ToolNode code execution session management', () => {
         files: [
           {
             id: 'rf1',
+            /* Default fallback for inputs that don't carry separate
+             * provenance — see toInjectedFileRef. */
+            resource_id: 'rf1',
             name: 'data.csv',
             storage_session_id: 'rf-session',
             kind: 'user',

package/src/types/tools.ts

@@ -158,14 +158,33 @@ export type CodeEnvKind = (typeof CODE_ENV_KINDS)[number];
 
 type CodeEnvFileBase = {
   /**
-   * 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 — codeapi derives sessionKey from
-   *    the auth-context user. Kept on the type for shape uniformity;
-   *    do not rely on it for routing.
+   * **Storage file id** — the per-file uuid the file_server returns
+   * at upload time. Identifies the bytes at
+   * `<storage_session_id>/<id>` in the object bucket; used by the
+   * worker to fetch the file and by codeapi's auth layer for the
+   * upload-existence check.
+   *
+   * Distinct from `resource_id` below — that's the entity that owns
+   * this file's storage session (skill `_id`, agent id, etc.), used
+   * for sessionKey resolution. Conflating the two caused
+   * shared-kind authorization to fail because the sessionKey
+   * re-derivation used the storage nanoid where the resource id was
+   * required. See codeapi #1455 review.
    */
   id: string;
+  /**
+   * **Resource id** — the entity that owns this file's storage
+   * session. Skill `_id` for `kind: 'skill'`, agent id for `'agent'`,
+   * informational only for `'user'` (codeapi resolves user identity
+   * from auth context). Kept on the type for shape uniformity across
+   * kinds.
+   *
+   * Drives codeapi's `resolveSessionKey` switch — the sessionKey
+   * embeds this value (`<tenant>:<kind>:<resource_id>[:v:<version>]`)
+   * so cross-user-within-tenant sharing for shared kinds is a
+   * designed property of the kind switch.
+   */
+  resource_id: string;
   name: string;
   /**
    * Storage session — the long-lived bucket where this file's bytes
@@ -204,12 +223,17 @@ export type CodeExecutionToolParams =
 
 export type FileRef = {
   /**
-   * Resource identity. Semantics depend on `kind` (when present):
-   *  - `skill` / `agent`: shared resource id (sessionKey-meaningful).
-   *  - `user`: informational only — codeapi derives sessionKey from
-   *    the auth-context user. Do not rely on it for routing.
+   * Storage file id (the per-file uuid). See `CodeEnvFile.id` for
+   * the full motivation behind the storage-vs-resource split.
    */
   id: string;
+  /**
+   * Resource id — the entity that owns this file's storage session.
+   * Optional on `FileRef` (post-execute artifact refs may not carry
+   * resource provenance for outputs); required on `CodeEnvFile`
+   * (the input wire shape).
+   */
+  resource_id?: string;
   name: string;
   path?: string;
   /**