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

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.1",
   "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. */

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',
@@ -835,6 +853,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;
   /**