diff --git a/package-lock.json b/package-lock.json
index 7ef9d4b8..2ba1c4e0 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -16,7 +16,7 @@
         "@aws-sdk/client-textract": "^3.901.0",
         "@aws-sdk/util-stream-node": "^3.370.0",
         "@azure/search-documents": "^12.2.0",
-        "@cognipeer/agent-sdk": "^0.9.3",
+        "@cognipeer/agent-sdk": "^0.9.4",
         "@cognipeer/to-markdown": "^3.1.0",
         "@elastic/elasticsearch": "^8.19.1",
         "@fastify/websocket": "^11.2.0",
@@ -273,7 +273,6 @@
       "integrity": "sha512-OteRb8WubcmEvU0YlMJwCXs3Q6xrdkb0v50/qZBJP1TF0CvujFZQM++9BjEkTER/Jr9wbPHvjSFKnbMta0b4dQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@algolia/client-common": "5.50.1",
         "@algolia/requester-browser-xhr": "5.50.1",
@@ -389,6 +388,7 @@
       "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.27.3.tgz",
       "integrity": "sha512-IjLt0gd3L4jlOfilxVXTifn42FnVffMgDC04RJK1KDZpmkBWLv0XC92MVVmkxrFZNS/7l3xWgP/I3nqtX1sQHw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@types/node": "^18.11.18",
         "@types/node-fetch": "^2.6.4",
@@ -404,6 +404,7 @@
       "resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.130.tgz",
       "integrity": "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~5.26.4"
       }
@@ -412,7 +413,8 @@
       "version": "5.26.5",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz",
       "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/@aws-crypto/crc32": {
       "version": "5.2.0",
@@ -820,7 +822,6 @@
       "resolved": "https://registry.npmjs.org/@aws-sdk/client-s3/-/client-s3-3.1030.0.tgz",
       "integrity": "sha512-sgGb4ub0JXnHaXnok5td7A1KGwENFPwOrwgzvpkeWq9w16Sl7x2KhYtVl+Fdd/7LAvaEtm3HqrYtNmm2d0OXmQ==",
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "@aws-crypto/sha1-browser": "5.2.0",
         "@aws-crypto/sha256-browser": "5.2.0",
@@ -1854,7 +1855,6 @@
       "resolved": "https://registry.npmjs.org/@azure/core-client/-/core-client-1.10.1.tgz",
       "integrity": "sha512-Nh5PhEOeY6PrnxNPsEHRr9eimxLwgLlpmguQaHKBinFYA/RU9+kOYVOQqOrTsCL+KSxrLLl1gD8Dk5BFW/7l/w==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@azure/abort-controller": "^2.1.2",
         "@azure/core-auth": "^1.10.0",
@@ -1901,7 +1901,6 @@
       "resolved": "https://registry.npmjs.org/@azure/core-rest-pipeline/-/core-rest-pipeline-1.23.0.tgz",
       "integrity": "sha512-Evs1INHo+jUjwHi1T6SG6Ua/LHOQBCLuKEEE6efIpt4ZOoNonaT1kP32GoOcdNDbfqsD2445CPri3MubBy5DEQ==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@azure/abort-controller": "^2.1.2",
         "@azure/core-auth": "^1.10.0",
@@ -1959,7 +1958,6 @@
       "resolved": "https://registry.npmjs.org/@azure/search-documents/-/search-documents-12.2.0.tgz",
       "integrity": "sha512-4+Qw+qaGqnkdUCq/vEFzk/bkROogTvdbPb1fmI8poxNfDDN1q2WHxBmhI7CYwesrBj1yXC4i5E0aISBxZqZi0g==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@azure/core-auth": "^1.9.0",
         "@azure/core-client": "^1.9.2",
@@ -2007,7 +2005,6 @@
       "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.29.0",
         "@babel/generator": "^7.29.0",
@@ -2292,6 +2289,7 @@
       "version": "2.10.0",
       "resolved": "https://registry.npmjs.org/@browserbasehq/sdk/-/sdk-2.10.0.tgz",
       "integrity": "sha512-pOL4yW8P8AI2+N5y6zEP6XXKqIXtYyKunr1JXppqQDOyKLxxvZEDqQCHJXWUzqgx3R1tGWpn7m9AjXN7MeYInA==",
+      "peer": true,
       "dependencies": {
         "@types/node": "^18.11.18",
         "@types/node-fetch": "^2.6.4",
@@ -2307,6 +2305,7 @@
       "resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.130.tgz",
       "integrity": "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~5.26.4"
       }
@@ -2315,7 +2314,8 @@
       "version": "5.26.5",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz",
       "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/@browserbasehq/stagehand": {
       "version": "1.14.0",
@@ -2344,9 +2344,9 @@
       "license": "MIT"
     },
     "node_modules/@cognipeer/agent-sdk": {
-      "version": "0.9.3",
-      "resolved": "https://registry.npmjs.org/@cognipeer/agent-sdk/-/agent-sdk-0.9.3.tgz",
-      "integrity": "sha512-i286Z+/syLdkf1aMBGkWmcB6F6RnpKQf7a2ha48AVLD3NOoVQ5Ek7JDVslbth78v9uDVSYh1ar8wqLQFV0NIJg==",
+      "version": "0.9.4",
+      "resolved": "https://registry.npmjs.org/@cognipeer/agent-sdk/-/agent-sdk-0.9.4.tgz",
+      "integrity": "sha512-P1iKiqQQ3Y+pGZ9dvv+6ASFyzJyd6fjuhwJFBOQymBvOglgC3MRHRBUk2QT25yHN6TYkGqshfag+bhj7w8QpHQ==",
       "license": "MIT",
       "dependencies": {
         "ajv": "^8.17.1",
@@ -2423,6 +2423,7 @@
       "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz",
       "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@jridgewell/trace-mapping": "0.3.9"
       },
@@ -2435,6 +2436,7 @@
       "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz",
       "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@jridgewell/resolve-uri": "^3.0.3",
         "@jridgewell/sourcemap-codec": "^1.4.10"
@@ -2531,7 +2533,6 @@
       "resolved": "https://registry.npmjs.org/@elastic/elasticsearch/-/elasticsearch-8.19.1.tgz",
       "integrity": "sha512-+1j9NnQVOX+lbWB8LhCM7IkUmjU05Y4+BmSLfusq0msCsQb1Va+OUKFCoOXjCJqQrcgdRdQCjYYyolQ/npQALQ==",
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "@elastic/transport": "^8.9.6",
         "apache-arrow": "18.x - 21.x",
@@ -3531,6 +3532,7 @@
       "resolved": "https://registry.npmjs.org/@ibm-cloud/watsonx-ai/-/watsonx-ai-1.7.11.tgz",
       "integrity": "sha512-sBMj/YhV5qvJdBpvgutmX6vLUUnSwvhFaJk7r3hiMh5aB7BQWQ+5zyzvSPLywOwTWZbgy4v8jxTUhR6jb+kguw==",
       "license": "Apache-2.0",
+      "peer": true,
       "dependencies": {
         "@types/node": "^18.0.0",
         "extend": "3.0.2",
@@ -3547,6 +3549,7 @@
       "resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.130.tgz",
       "integrity": "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~5.26.4"
       }
@@ -3555,7 +3558,8 @@
       "version": "5.26.5",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz",
       "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/@iconify-json/simple-icons": {
       "version": "1.2.78",
@@ -4836,7 +4840,6 @@
       "resolved": "https://registry.npmjs.org/@langchain/core/-/core-1.1.46.tgz",
       "integrity": "sha512-i8rDC83BpItxChCw4Lf+6tAr+k+OUcbirc5ZkrhI9ywYWmvxegUljLGOGYvtJNTbEAIFkhYIODPE5QRqyjF6sA==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@cfworker/json-schema": "^4.0.2",
         "@standard-schema/spec": "^1.1.0",
@@ -5086,7 +5089,6 @@
       "resolved": "https://registry.npmjs.org/@mantine/core/-/core-8.3.18.tgz",
       "integrity": "sha512-9tph1lTVogKPjTx02eUxDUOdXacPzK62UuSqb4TdGliI54/Xgxftq0Dfqu6XuhCxn9J5MDJaNiLDvL/1KRkYqA==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@floating-ui/react": "^0.27.16",
         "clsx": "^2.1.1",
@@ -5135,7 +5137,6 @@
       "resolved": "https://registry.npmjs.org/@mantine/hooks/-/hooks-8.3.18.tgz",
       "integrity": "sha512-QoWr9+S8gg5050TQ06aTSxtlpGjYOpIllRbjYYXlRvZeTsUqiTbVfvQROLexu4rEaK+yy9Wwriwl9PMRgbLqPw==",
       "license": "MIT",
-      "peer": true,
       "peerDependencies": {
         "react": "^18.x || ^19.x"
       }
@@ -5822,7 +5823,6 @@
       "resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.1.tgz",
       "integrity": "sha512-gLyJlPHPZYdAk1JENA9LeHejZe1Ti77/pTeFm/nMXmQH/HFZlcS/O2XJB+L8fkbrNSqhdtlvjBVjxwUYanNH5Q==",
       "license": "Apache-2.0",
-      "peer": true,
       "engines": {
         "node": ">=8.0.0"
       }
@@ -7568,7 +7568,6 @@
       "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.99.0.tgz",
       "integrity": "sha512-OY2bCqPemT1LlqJ8Y2CUau4KELnIhhG9Ol3ZndPbdnB095pRbPo1cHuXTndg8iIwtoHTgwZjyaDnQ0xD0mYwAw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@tanstack/query-core": "5.99.0"
       },
@@ -7642,25 +7641,29 @@
       "version": "1.0.12",
       "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.12.tgz",
       "integrity": "sha512-UCYBaeFvM11aU2y3YPZ//O5Rhj+xKyzy7mvcIoAjASbigy8mHMryP5cK7dgjlz2hWxh1g5pLw084E0a/wlUSFQ==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/@tsconfig/node12": {
       "version": "1.0.11",
       "resolved": "https://registry.npmjs.org/@tsconfig/node12/-/node12-1.0.11.tgz",
       "integrity": "sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/@tsconfig/node14": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/@tsconfig/node14/-/node14-1.0.3.tgz",
       "integrity": "sha512-ysT8mhdixWK6Hw3i1V2AeRqZ5WfXg1G43mqoYlM2nc6388Fq5jcXyr5mRsqViLx/GJYdoL0bfXD8nmF+Zn/Iow==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/@tsconfig/node16": {
       "version": "1.0.4",
       "resolved": "https://registry.npmjs.org/@tsconfig/node16/-/node16-1.0.4.tgz",
       "integrity": "sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/@tybys/wasm-util": {
       "version": "0.10.1",
@@ -7958,7 +7961,6 @@
       "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.39.tgz",
       "integrity": "sha512-orrrD74MBUyK8jOAD/r0+lfa1I2MO6I+vAkmAWzMYbCcgrN4lCrmK52gRFQq/JRxfYPfonkr4b0jcY7Olqdqbw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -7968,6 +7970,7 @@
       "resolved": "https://registry.npmjs.org/@types/node-fetch/-/node-fetch-2.6.13.tgz",
       "integrity": "sha512-QGpRVpzSaUs30JBSGPjOg4Uveu384erbHBoT1zeONvyCfwQxIkUshLAOqN/k9EjGviPRmWTTe6aH2qySWKTVSw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@types/node": "*",
         "form-data": "^4.0.4"
@@ -8014,7 +8017,6 @@
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.14.tgz",
       "integrity": "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "csstype": "^3.2.2"
       }
@@ -8051,7 +8053,8 @@
       "version": "4.0.5",
       "resolved": "https://registry.npmjs.org/@types/tough-cookie/-/tough-cookie-4.0.5.tgz",
       "integrity": "sha512-/Ad8+nIOV7Rl++6f1BdKxFSMgmoqEoYbHRpPcx3JEfv8VRsQe9Z4mCXeJBzxs7mbHY/XOZZuXlRNfhpVPbs6ZA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/@types/triple-beam": {
       "version": "1.3.5",
@@ -8138,7 +8141,6 @@
       "integrity": "sha512-/Zb/xaIDfxeJnvishjGdcR4jmr7S+bda8PKNhRGdljDM+elXhlvN0FyPSsMnLmJUrVG9aPO6dof80wjMawsASg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "8.58.2",
         "@typescript-eslint/types": "8.58.2",
@@ -8705,7 +8707,6 @@
       "integrity": "sha512-x7FptB5oDruxNPDNY2+S8tCh0pcq7ymCe1gTHcsp733jYjrJl8V1gMUlVysuCD9Kz46Xz9t1akkv08dPcYDs1w==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@bcoe/v8-coverage": "^1.0.2",
         "@vitest/utils": "4.1.4",
@@ -9177,7 +9178,6 @@
       "resolved": "https://registry.npmjs.org/@zilliz/milvus2-sdk-node/-/milvus2-sdk-node-2.6.14.tgz",
       "integrity": "sha512-S/DEVvzVnFmxoRCnWA9MBaMgSa1t3LEVKex+1+iJEZFPmrpk0OA9tUVfTgbNvzvV/JlWLH68h7vOAPWz/CsXzQ==",
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "@dsnp/parquetjs": "^1.8.7",
         "@grpc/grpc-js": "^1.14.3",
@@ -9257,7 +9257,6 @@
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
       "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -9280,6 +9279,7 @@
       "resolved": "https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.5.tgz",
       "integrity": "sha512-HEHNfbars9v4pgpW6SO1KSPkfoS0xVOM/9UzkJltjlsHZmJasxg8aXkuZa7SMf8vKGIBhpUsPluQSqhJFCqebw==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "acorn": "^8.11.0"
       },
@@ -9319,6 +9319,7 @@
       "resolved": "https://registry.npmjs.org/agentkeepalive/-/agentkeepalive-4.6.0.tgz",
       "integrity": "sha512-kja8j7PjmncONqaTsB8fQ+wE2mSU2DJ9D4XKoJ5PFWIdRMa6SLSN1ff4mOr4jCbfRSsxR4keIiySJU0N9T5hIQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "humanize-ms": "^1.2.1"
       },
@@ -9365,7 +9366,6 @@
       "integrity": "sha512-/bwdue1/8LWELn/DBalGRfuLsXBLXULJo/yOeavJtDu8rBwxIzC6/Rz9Jg19S21VkJvRuZO1k8CZXBMS73mYbA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@algolia/abtesting": "1.16.1",
         "@algolia/client-abtesting": "5.50.1",
@@ -9434,7 +9434,8 @@
       "version": "4.1.3",
       "resolved": "https://registry.npmjs.org/arg/-/arg-4.1.3.tgz",
       "integrity": "sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/argparse": {
       "version": "2.0.1",
@@ -9764,7 +9765,6 @@
       "resolved": "https://registry.npmjs.org/axios/-/axios-1.16.1.tgz",
       "integrity": "sha512-caYkukvroVPO8KrzuJEb50Hm07KwfBZPEC3VeFHTsqWHvKTsy54hjJz9BS/cdaypROE2rH6xvm9mHX4fgWkr3A==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "follow-redirects": "^1.16.0",
         "form-data": "^4.0.5",
@@ -9830,7 +9830,6 @@
       "integrity": "sha512-Z0oHEHAFDZkffN8Qc39zNZjQlMDkPJRyyyZieU1VH7u8c5S+qHZ2S8ixdKIAxEjfHO7FJxXmJWgteOghVanIsg==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "peerDependencies": {
         "bare-abort-controller": "*"
       },
@@ -9986,7 +9985,6 @@
       "integrity": "sha512-EwhOpyXiOEL/lKzHz9AW1msWFNzGc/z+LzeB3/jnFJpxu+th2yqvzsSWas1v9jgs9+xiXJcD5A8CJxAG2TaghQ==",
       "hasInstallScript": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "bindings": "^1.5.0",
         "prebuild-install": "^7.1.1"
@@ -10164,7 +10162,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.10.12",
         "caniuse-lite": "^1.0.30001782",
@@ -10640,7 +10637,6 @@
       "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
       "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=6"
       }
@@ -10860,7 +10856,8 @@
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/create-require/-/create-require-1.1.1.tgz",
       "integrity": "sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/cron-parser": {
       "version": "4.9.0",
@@ -11130,8 +11127,7 @@
       "version": "1.11.20",
       "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.20.tgz",
       "integrity": "sha512-YbwwqR/uYpeoP4pu043q+LTDLFBLApUP6VxRihdfNTqu4ubqMlGDLd6ErXhEgsyvY0K6nCs7nggYumAN+9uEuQ==",
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/debug": {
       "version": "4.4.3",
@@ -11306,6 +11302,7 @@
       "resolved": "https://registry.npmjs.org/diff/-/diff-4.0.4.tgz",
       "integrity": "sha512-X07nttJQkwkfKfvTPG/KSnE2OMdcUCao6+eXF3wmnIQRn2aPAHH3VxDbDOdegkd6JbPsXqShpvEOHfAT+nCNwQ==",
       "license": "BSD-3-Clause",
+      "peer": true,
       "engines": {
         "node": ">=0.3.1"
       }
@@ -11800,7 +11797,6 @@
       "integrity": "sha512-XoMjdBOwe/esVgEvLmNsD3IRHkm7fbKIUGvrleloJXUZgDHig2IPWNniv+GwjyJXzuNqVjlr5+4yVUZjycJwfQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.1",
@@ -11889,7 +11885,6 @@
       "integrity": "sha512-82GZUjRS0p/jganf6q1rEO25VSoHH0hKPCTrgillPjdI/3bgBhAE1QzHrHTizjpRvy6pGAvKjDJtk2pF9NDq8w==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "eslint-config-prettier": "bin/cli.js"
       },
@@ -11991,7 +11986,6 @@
       "integrity": "sha512-whOE1HFo/qJDyX4SnXzP4N6zOWn79WhnCUY/iDR0mPfQZO8wcYE4JClzI2oZrhBnnMUCBCHZhO6VQyoBU95mZA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@rtsao/scc": "^1.1.0",
         "array-includes": "^3.1.9",
@@ -12490,7 +12484,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@nodable/entities": "^2.1.0",
         "fast-xml-builder": "^1.2.0",
@@ -12805,7 +12798,6 @@
       "integrity": "sha512-/yNdlIkpWbM0ptxno3ONTuf+2g318kh2ez3KSeZN5dZ8YC6AAmgeWz+GasYYiBJPFaYcSAPeu4GfhUaChzIJXA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "tabbable": "^6.4.0"
       }
@@ -12866,13 +12858,15 @@
       "version": "1.7.2",
       "resolved": "https://registry.npmjs.org/form-data-encoder/-/form-data-encoder-1.7.2.tgz",
       "integrity": "sha512-qfqtYan3rxrnCk1VYaA4H+Ms9xdpPqvLZa6xmMgFvhO32x7/3J/ExcTd6qpxM0vH2GdMI+poehyBZvqfMTto8A==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/formdata-node": {
       "version": "4.4.1",
       "resolved": "https://registry.npmjs.org/formdata-node/-/formdata-node-4.4.1.tgz",
       "integrity": "sha512-0iirZp3uVDjVGt9p49aTaqjk84TrglENEDuqfdlZQ1roC9CWlPk6Avf8EEnZNcAqPonwkG35x4n3ww/1THYAeQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "node-domexception": "1.0.0",
         "web-streams-polyfill": "4.0.0-beta.3"
@@ -13170,7 +13164,6 @@
       "resolved": "https://registry.npmjs.org/google-auth-library/-/google-auth-library-10.6.2.tgz",
       "integrity": "sha512-e27Z6EThmVNNvtYASwQxose/G57rkRuaRbQyxM2bvYLLX/GqWZ5chWq2EBoUchJbCc57eC9ArzO5wMsEmWftCw==",
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "base64-js": "^1.3.0",
         "ecdsa-sig-formatter": "^1.0.11",
@@ -13529,6 +13522,7 @@
       "resolved": "https://registry.npmjs.org/humanize-ms/-/humanize-ms-1.2.1.tgz",
       "integrity": "sha512-Fl70vYtsAFb/C06PTS9dZBo7ihau+Tu/DNCk/OyHhea07S+aeMWpFFkUaXRa8fI+ScZbEI8dfSxwY7gxZ9SAVQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "ms": "^2.0.0"
       }
@@ -13538,6 +13532,7 @@
       "resolved": "https://registry.npmjs.org/ibm-cloud-sdk-core/-/ibm-cloud-sdk-core-5.4.11.tgz",
       "integrity": "sha512-UYm6i3OCcQ1sBOVIJh0gcwCNltiGCf7QBCPaDtqCXuHIPbn8m9sKqVBqfrgFuQpenAak/Yv/450Vw+tC59XVIQ==",
       "license": "Apache-2.0",
+      "peer": true,
       "dependencies": {
         "@types/debug": "^4.1.12",
         "@types/node": "^18.19.80",
@@ -13565,6 +13560,7 @@
       "resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.130.tgz",
       "integrity": "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~5.26.4"
       }
@@ -13574,6 +13570,7 @@
       "resolved": "https://registry.npmjs.org/file-type/-/file-type-21.3.4.tgz",
       "integrity": "sha512-Ievi/yy8DS3ygGvT47PjSfdFoX+2isQueoYP1cntFW1JLYAuS4GD7NUPGg4zv2iZfV52uDyk5w5Z0TdpRS6Q1g==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@tokenizer/inflate": "^0.4.1",
         "strtok3": "^10.3.4",
@@ -13592,6 +13589,7 @@
       "resolved": "https://registry.npmjs.org/strtok3/-/strtok3-10.3.5.tgz",
       "integrity": "sha512-ki4hZQfh5rX0QDLLkOCj+h+CVNkqmp/CMf8v8kZpkNVK6jGQooMytqzLZYUVYIZcFZ6yDB70EfD8POcFXiF5oA==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@tokenizer/token": "^0.3.0"
       },
@@ -13608,6 +13606,7 @@
       "resolved": "https://registry.npmjs.org/token-types/-/token-types-6.1.2.tgz",
       "integrity": "sha512-dRXchy+C0IgK8WPC6xvCHFRIWYUbqqdEIKPaKo/AcTUNzwLTK6AH7RjdLWsEZcAN/TBdtfUw3PYEgPr5VPr6ww==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@borewit/text-codec": "^0.2.1",
         "@tokenizer/token": "^0.3.0",
@@ -13625,7 +13624,8 @@
       "version": "5.26.5",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz",
       "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/iconv-lite": {
       "version": "0.6.3",
@@ -13671,7 +13671,6 @@
       "integrity": "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==",
       "devOptional": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">= 4"
       }
@@ -13784,7 +13783,6 @@
       "resolved": "https://registry.npmjs.org/ioredis/-/ioredis-5.10.1.tgz",
       "integrity": "sha512-HuEDBTI70aYdx1v6U97SbNx9F1+svQKBDo30o0b9fw055LMepzpOOd0Ccg9Q6tbqmBSJaMuY0fB7yw9/vjBYCA==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@ioredis/commands": "1.5.1",
         "cluster-key-slot": "^1.1.0",
@@ -14376,7 +14374,8 @@
       "version": "0.1.2",
       "resolved": "https://registry.npmjs.org/isstream/-/isstream-0.1.2.tgz",
       "integrity": "sha512-Yljz7ffyPbrLpLngrMtZ7NduUgVvi6wG9RJ9IUcyCd59YQ911PBJphODUcbOVbqYfxe1wuYf/LJ8PauMRwsM/g==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/istanbul-lib-coverage": {
       "version": "3.2.2",
@@ -14587,6 +14586,7 @@
       "resolved": "https://registry.npmjs.org/jsonwebtoken/-/jsonwebtoken-9.0.3.tgz",
       "integrity": "sha512-MT/xP0CrubFRNLNKvxJ2BYfy53Zkm++5bX9dtuPbqAeQpTVe0MQTFhao8+Cp//EmJp244xt6Drw/GVEGCUj40g==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "jws": "^4.0.1",
         "lodash.includes": "^4.3.0",
@@ -14609,6 +14609,7 @@
       "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
       "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
       "license": "ISC",
+      "peer": true,
       "bin": {
         "semver": "bin/semver.js"
       },
@@ -15167,6 +15168,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=13.2.0"
       }
@@ -15203,7 +15205,8 @@
       "version": "4.3.0",
       "resolved": "https://registry.npmjs.org/lodash.includes/-/lodash.includes-4.3.0.tgz",
       "integrity": "sha512-W3Bx6mdkRTGtlJISOvVD/lbqjTlPPUDTMnlXZFnVwi9NKJ6tiAk6LVdlhZMm17VZisqhKcgzpO5Wz91PCt5b0w==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/lodash.isarguments": {
       "version": "3.1.0",
@@ -15215,31 +15218,36 @@
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/lodash.isboolean/-/lodash.isboolean-3.0.3.tgz",
       "integrity": "sha512-Bz5mupy2SVbPHURB98VAcw+aHh4vRV5IPNhILUCsOzRmsTmSQ17jIuqopAentWoehktxGd9e/hbIXq980/1QJg==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/lodash.isinteger": {
       "version": "4.0.4",
       "resolved": "https://registry.npmjs.org/lodash.isinteger/-/lodash.isinteger-4.0.4.tgz",
       "integrity": "sha512-DBwtEWN2caHQ9/imiNeEA5ys1JoRtRfY3d7V9wkqtbycnAmTvRRmbHKDV4a0EYc678/dia0jrte4tjYwVBaZUA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/lodash.isnumber": {
       "version": "3.0.3",
       "resolved": "https://registry.npmjs.org/lodash.isnumber/-/lodash.isnumber-3.0.3.tgz",
       "integrity": "sha512-QYqzpfwO3/CWf3XP+Z+tkQsfaLL/EnUlXWVkIk5FUPc4sBdTehEqZONuyRt2P67PXAk+NXmTBcc97zw9t1FQrw==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/lodash.isplainobject": {
       "version": "4.0.6",
       "resolved": "https://registry.npmjs.org/lodash.isplainobject/-/lodash.isplainobject-4.0.6.tgz",
       "integrity": "sha512-oSXzaWypCMHkPC3NvBEaPHf0KsA5mvPrOPgQWDsbg8n7orZ290M0BmC/jgRZ4vcJ6DTAhjrsSYgdsW/F+MFOBA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/lodash.isstring": {
       "version": "4.0.1",
       "resolved": "https://registry.npmjs.org/lodash.isstring/-/lodash.isstring-4.0.1.tgz",
       "integrity": "sha512-0wJxfxH1wgO3GrbuP+dTTk7op+6L41QCXbGINEmD+ny/G/eCqGzxyCsh7159S+mgDDcoarnBw6PC1PS5+wUGgw==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/lodash.merge": {
       "version": "4.6.2",
@@ -15252,7 +15260,8 @@
       "version": "4.1.1",
       "resolved": "https://registry.npmjs.org/lodash.once/-/lodash.once-4.1.1.tgz",
       "integrity": "sha512-Sb487aTOCr9drQVL8pIxOzVhafOjZN9UU54hiN8PU3uAiSV7lx1yYNpbNmex2PK6dSJoNTSJUUswT651yww3Mg==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/logform": {
       "version": "2.7.0",
@@ -15384,7 +15393,8 @@
       "version": "1.3.6",
       "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz",
       "integrity": "sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==",
-      "license": "ISC"
+      "license": "ISC",
+      "peer": true
     },
     "node_modules/mammoth": {
       "version": "1.12.0",
@@ -17444,6 +17454,7 @@
       "resolved": "https://registry.npmjs.org/@types/node/-/node-18.19.130.tgz",
       "integrity": "sha512-GRaXQx6jGfL8sKfaIDD6OupbIHBr9jv7Jnaml9tB7l4v068PAOXqfcujMMo5PhbIs6ggR1XODELqahT2R8v0fg==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~5.26.4"
       }
@@ -17452,7 +17463,8 @@
       "version": "5.26.5",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz",
       "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/openapi-types": {
       "version": "12.1.3",
@@ -17842,7 +17854,6 @@
       "resolved": "https://registry.npmjs.org/pg/-/pg-8.20.0.tgz",
       "integrity": "sha512-ldhMxz2r8fl/6QkXnBD3CR9/xg694oT6DZQ2s6c/RI28OjtSOpxnPrUCGOBJ46RCUxcWdx3p6kw/xnDHjKvaRA==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "pg-connection-string": "^2.12.0",
         "pg-pool": "^3.13.0",
@@ -18057,7 +18068,6 @@
       "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.59.1.tgz",
       "integrity": "sha512-C8oWjPR3F81yljW9o5OxcWzfh6avkVwDD2VYdwIGqTkl+OGFISgypqzfu7dOe4QNLL2aqcWBmI3PMtLIK233lw==",
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "playwright-core": "1.59.1"
       },
@@ -18112,7 +18122,6 @@
         }
       ],
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "nanoid": "^3.3.11",
         "picocolors": "^1.1.1",
@@ -18335,7 +18344,6 @@
       "integrity": "sha512-8c3mgTe0ASwWAJK+78dpviD+A8EqhndQPUBpNUIPt6+xWlIigCwfN01lWr9MAede4uqXGTEKeQWTvzb3vjia0Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "prettier": "bin/prettier.cjs"
       },
@@ -18444,6 +18452,7 @@
       "resolved": "https://registry.npmjs.org/psl/-/psl-1.15.0.tgz",
       "integrity": "sha512-JZd3gMVBAVQkSs6HdNZo9Sdo0LNcQeMNP3CozBJb3JYC/QUYZTnKxP+f8oWRX4rHP5EurWxqAHTSwUCjlNKa1w==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "punycode": "^2.3.1"
       },
@@ -18485,7 +18494,8 @@
       "version": "2.2.0",
       "resolved": "https://registry.npmjs.org/querystringify/-/querystringify-2.2.0.tgz",
       "integrity": "sha512-FIqgj2EUvTa7R50u0rGsyTftzjYmv/a3hO345bZNrqabNqjtgiDMgmo4mkUjd+nzU5oF3dClKqFIPUKybUyqoQ==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/queue-microtask": {
       "version": "1.2.3",
@@ -18543,7 +18553,6 @@
       "resolved": "https://registry.npmjs.org/react/-/react-19.1.0.tgz",
       "integrity": "sha512-FS+XFBNvn3GTAWq26joslQgWNoFu08F4kl0J4CgdNKADkdSGXQyTCnKteIAJy96Br6YbpEU1LSzV5dYtjMkMDg==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -18553,7 +18562,6 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.1.0.tgz",
       "integrity": "sha512-Xs1hdnE+DyKgeHJeJznQmYMIBG3TKIHJJT95Q58nHLSrElKlGQqDTR2HQ9fx5CN/Gk6Vh/kupBTDLU11/nDk/g==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "scheduler": "^0.26.0"
       },
@@ -18622,7 +18630,6 @@
       "resolved": "https://registry.npmjs.org/react-redux/-/react-redux-9.2.0.tgz",
       "integrity": "sha512-ROY9fvHhwOD9ySfrF0wmvu//bKCQ6AeZZq1nJNtbDC+kk5DuSuNX/n6YWYF/SYy7bSba4D4FSz8DJeKY/S/r+g==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@types/use-sync-external-store": "^0.0.6",
         "use-sync-external-store": "^1.4.0"
@@ -18799,7 +18806,6 @@
       "resolved": "https://registry.npmjs.org/recharts/-/recharts-3.8.1.tgz",
       "integrity": "sha512-mwzmO1s9sFL0TduUpwndxCUNoXsBw3u3E/0+A+cLcrSfQitSG62L32N69GhqUrrT5qKcAE3pCGVINC6pqkBBQg==",
       "license": "MIT",
-      "peer": true,
       "workspaces": [
         "www"
       ],
@@ -18850,8 +18856,7 @@
       "version": "5.0.1",
       "resolved": "https://registry.npmjs.org/redux/-/redux-5.0.1.tgz",
       "integrity": "sha512-M9/ELqF6fy8FwmkpnF0S3YKOqMyoWJ4+CS5Efg2ct3oY9daQvd/Pc71FpGZsVsbl3Cpb+IIcjBDUnnyBdQbq4w==",
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/redux-thunk": {
       "version": "3.1.0",
@@ -19027,7 +19032,8 @@
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/requires-port/-/requires-port-1.0.0.tgz",
       "integrity": "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/reselect": {
       "version": "5.1.1",
@@ -19093,6 +19099,7 @@
       "resolved": "https://registry.npmjs.org/retry-axios/-/retry-axios-2.6.0.tgz",
       "integrity": "sha512-pOLi+Gdll3JekwuFjXO3fTq+L9lzMQGcSq7M5gIjExcl3Gu1hd4XXuf5o3+LuSBsaULQH7DiNbsqPd1chVpQGQ==",
       "license": "Apache-2.0",
+      "peer": true,
       "engines": {
         "node": ">=10.7.0"
       },
@@ -20473,7 +20480,6 @@
       "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
       "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -20555,6 +20561,7 @@
       "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-4.1.4.tgz",
       "integrity": "sha512-Loo5UUvLD9ScZ6jh8beX1T6sO1w2/MpCRpEP7V280GKMVUQ0Jzar2U3UJPsrdbziLEMMhu3Ujnq//rhiFuIeag==",
       "license": "BSD-3-Clause",
+      "peer": true,
       "dependencies": {
         "psl": "^1.1.33",
         "punycode": "^2.1.1",
@@ -20624,6 +20631,7 @@
       "resolved": "https://registry.npmjs.org/ts-node/-/ts-node-10.9.2.tgz",
       "integrity": "sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@cspotcode/source-map-support": "^0.8.0",
         "@tsconfig/node10": "^1.0.7",
@@ -20883,7 +20891,6 @@
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -21058,6 +21065,7 @@
       "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.2.0.tgz",
       "integrity": "sha512-CJ1QgKmNg3CwvAv/kOFmtnEN05f0D/cn9QntgNOQlQF9dgvVTHj3t+8JPdjqawCHk7V/KA+fbUqzZ9XWhcqPUg==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">= 4.0.0"
       }
@@ -21216,6 +21224,7 @@
       "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.5.10.tgz",
       "integrity": "sha512-WypcfiRhfeUP9vvF0j6rw0J3hrWrw6iZv3+22h6iRMJ/8z1Tj6XfLP4DsUix5MhMPnXpiHDoKyoZ/bdCkwBCiQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "querystringify": "^2.1.1",
         "requires-port": "^1.0.0"
@@ -21357,7 +21366,8 @@
       "version": "3.0.1",
       "resolved": "https://registry.npmjs.org/v8-compile-cache-lib/-/v8-compile-cache-lib-3.0.1.tgz",
       "integrity": "sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/varint": {
       "version": "6.0.0",
@@ -21421,7 +21431,6 @@
       "integrity": "sha512-2N/55r4JDJ4gdrCvGgINMy+HH3iRpNIz8K6SFwVsA+JbQScLiC+clmAxBgwiSPgcG9U15QmvqCGWzMbqda5zGQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "esbuild": "^0.25.0",
         "fdir": "^6.4.4",
@@ -22029,7 +22038,6 @@
       "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -22544,7 +22552,6 @@
       "integrity": "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "esbuild": "^0.21.3",
         "postcss": "^8.4.43",
@@ -22605,7 +22612,6 @@
       "integrity": "sha512-tFuJqTxKb8AvfyqMfnavXdzfy3h3sWZRWwfluGbkeR7n0HUev+FmNgZ8SDrRBTVrVCjgH5cA21qGbCffMNtWvg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@vitest/expect": "4.1.4",
         "@vitest/mocker": "4.1.4",
@@ -22709,7 +22715,6 @@
       "integrity": "sha512-vM4z4Q9tTafVfMAK7IVzmxg34rSzTFMyIe0UUEijUCkn9+23lj0WRfA83dg7eQZIUlgOSGrkViIaCfqSAUXsMw==",
       "devOptional": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@vue/compiler-dom": "3.5.32",
         "@vue/compiler-sfc": "3.5.32",
@@ -22737,6 +22742,7 @@
       "resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-4.0.0-beta.3.tgz",
       "integrity": "sha512-QW95TCTaHmsYfHDybGMwO5IJIM93I/6vTRk+daHTWFPhwh+C8Cg7j7XyKrwrj8Ib6vYXe0ocYNrmzY4xAAN6ug==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">= 14"
       }
@@ -23088,7 +23094,6 @@
       "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.0.tgz",
       "integrity": "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=10.0.0"
       },
@@ -23263,6 +23268,7 @@
       "resolved": "https://registry.npmjs.org/yn/-/yn-3.1.1.tgz",
       "integrity": "sha512-Ux4ygGWsu2c7isFWe8Yu1YluJmqVhxqK2cLXNQA5AcC3QfbGNpM7fu0Y8b/z16pXLnFxZYvWhd3fhBY9DLmC6Q==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=6"
       }
diff --git a/package.json b/package.json
index 07cf1b7f..f7ea7acb 100644
--- a/package.json
+++ b/package.json
@@ -34,7 +34,7 @@
     "@aws-sdk/client-textract": "^3.901.0",
     "@aws-sdk/util-stream-node": "^3.370.0",
     "@azure/search-documents": "^12.2.0",
-    "@cognipeer/agent-sdk": "^0.9.3",
+    "@cognipeer/agent-sdk": "^0.9.4",
     "@cognipeer/to-markdown": "^3.1.0",
     "@elastic/elasticsearch": "^8.19.1",
     "@fastify/websocket": "^11.2.0",
diff --git a/src/app/dashboard/tracing/agents/page.tsx b/src/app/dashboard/tracing/agents/page.tsx
new file mode 100644
index 00000000..88545d81
--- /dev/null
+++ b/src/app/dashboard/tracing/agents/page.tsx
@@ -0,0 +1,211 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { Button, Text, Tooltip } from '@mantine/core';
+import { IconBook, IconEye, IconRobot } from '@tabler/icons-react';
+import PageContainer, { PageHeader } from '@/components/common/ui/PageContainer';
+import DataGrid, { type DataGridColumn } from '@/components/common/ui/DataGrid';
+import StatusBadge from '@/components/common/ui/StatusBadge';
+import { formatNumber, formatRelativeTime } from '@/lib/utils/tracingUtils';
+import { useDocsDrawer } from '@/components/docs/DocsDrawerContext';
+
+interface AgentRecord {
+  name: string;
+  sessionsCount: number;
+  latestSessionAt: string | null;
+  latestStatus: string | null;
+}
+
+interface AgentsResponse {
+  agents: AgentRecord[];
+  total: number;
+}
+
+// The directory endpoint is a lightweight "top N by recent activity" list
+// (sub-nav/pickers use it too), not a paginated one — a generous cap covers
+// realistic per-tenant agent counts without adding server-side pagination.
+const DIRECTORY_LIMIT = 200;
+
+export default function TracingAgentsPage() {
+  const router = useRouter();
+  const { openDocs } = useDocsDrawer();
+  const [agents, setAgents] = useState<AgentRecord[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [refreshing, setRefreshing] = useState(false);
+  const [query, setQuery] = useState('');
+  const [statusFilter, setStatusFilter] = useState('all');
+
+  const fetchAgents = useCallback(
+    async (isRefresh = false, signal?: AbortSignal) => {
+      try {
+        if (isRefresh) setRefreshing(true);
+        else setLoading(true);
+
+        const response = await fetch(
+          `/api/tracing/agents?limit=${DIRECTORY_LIMIT}`,
+          { signal, cache: 'no-store' },
+        );
+        if (!response.ok) {
+          const errorData = await response.json().catch(() => ({}));
+          throw new Error(errorData.error || 'Failed to fetch agents');
+        }
+        const data: AgentsResponse = await response.json();
+        setAgents(data.agents || []);
+      } catch (error) {
+        if (error instanceof DOMException && error.name === 'AbortError') return;
+        console.error('Failed to load agents:', error);
+        setAgents([]);
+      } finally {
+        if (!signal?.aborted) {
+          setLoading(false);
+          setRefreshing(false);
+        }
+      }
+    },
+    [],
+  );
+
+  useEffect(() => {
+    const controller = new AbortController();
+    void fetchAgents(false, controller.signal);
+    return () => controller.abort();
+  }, [fetchAgents]);
+
+  const filteredAgents = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    return agents.filter((a) => {
+      if (q && !a.name.toLowerCase().includes(q)) return false;
+      if (statusFilter !== 'all' && (a.latestStatus || 'unknown') !== statusFilter) return false;
+      return true;
+    });
+  }, [agents, query, statusFilter]);
+
+  const columns: DataGridColumn<AgentRecord>[] = [
+    {
+      key: 'name',
+      label: 'Agent',
+      render: (a) => (
+        <Tooltip label={a.name} withArrow>
+          <span
+            className="ds-row ds-gap-xs"
+            style={{ fontSize: 12.5, color: 'var(--ds-text)' }}
+          >
+            <IconRobot size={14} stroke={1.7} />
+            {a.name}
+          </span>
+        </Tooltip>
+      ),
+    },
+    {
+      key: 'sessions',
+      label: 'Sessions',
+      align: 'right',
+      render: (a) => (
+        <span
+          className="ds-mono"
+          style={{ fontSize: 12.5, fontVariantNumeric: 'tabular-nums' }}
+        >
+          {formatNumber(a.sessionsCount)}
+        </span>
+      ),
+    },
+    {
+      key: 'status',
+      label: 'Latest status',
+      render: (a) => (
+        <StatusBadge
+          status={
+            a.latestStatus === 'success'
+              ? 'ok'
+              : a.latestStatus === 'error'
+                ? 'err'
+                : a.latestStatus === 'running'
+                  ? 'info'
+                  : 'paused'
+          }
+          label={(a.latestStatus || 'unknown').toUpperCase()}
+        />
+      ),
+    },
+    {
+      key: 'latest',
+      label: 'Last session',
+      render: (a) => (
+        <span className="ds-faint" style={{ fontSize: 12.5 }}>
+          {a.latestSessionAt ? formatRelativeTime(a.latestSessionAt) : '—'}
+        </span>
+      ),
+    },
+  ];
+
+  return (
+    <PageContainer>
+      <PageHeader
+        eyebrow="Operate · Tracing"
+        title="Agents"
+        subtitle="Every agent that has reported a tracing session in the last 30 days, ranked by recent activity."
+        actions={
+          <Button
+            variant="default"
+            size="sm"
+            leftSection={<IconBook size={14} stroke={1.7} />}
+            onClick={() => openDocs('api-tracing')}
+          >
+            Docs
+          </Button>
+        }
+      />
+
+      <DataGrid<AgentRecord>
+        records={filteredAgents}
+        loading={loading}
+        rowKey={(a) => a.name}
+        onRowClick={(a) =>
+          router.push(`/dashboard/tracing/agents/${encodeURIComponent(a.name)}`)
+        }
+        columns={columns}
+        search={{
+          value: query,
+          onChange: setQuery,
+          placeholder: 'Search by agent name…',
+        }}
+        filters={[
+          {
+            value: statusFilter,
+            onChange: setStatusFilter,
+            ariaLabel: 'Filter by latest status',
+            width: 160,
+            options: [
+              { value: 'all', label: 'All statuses' },
+              { value: 'success', label: 'Success' },
+              { value: 'error', label: 'Error' },
+              { value: 'running', label: 'Running' },
+            ],
+          },
+        ]}
+        onRefresh={() => void fetchAgents(true)}
+        refreshing={refreshing}
+        empty={{
+          icon: <IconRobot size={26} stroke={1.7} />,
+          title: 'No agents found',
+          description: 'Agents will appear once they report their first tracing session.',
+        }}
+        footerLeft={
+          <Text size="xs" c="dimmed">
+            {formatNumber(filteredAgents.length)} of {formatNumber(agents.length)} agents
+          </Text>
+        }
+        rowActions={(a) => [
+          {
+            id: 'view',
+            label: 'View agent',
+            icon: <IconEye size={14} />,
+            onClick: () =>
+              router.push(`/dashboard/tracing/agents/${encodeURIComponent(a.name)}`),
+          },
+        ]}
+      />
+    </PageContainer>
+  );
+}
diff --git a/src/components/layout/launcher/ServiceSubNav.tsx b/src/components/layout/launcher/ServiceSubNav.tsx
index 5e1436f4..d44a8541 100644
--- a/src/components/layout/launcher/ServiceSubNav.tsx
+++ b/src/components/layout/launcher/ServiceSubNav.tsx
@@ -1,6 +1,5 @@
 'use client';
 
-import { useEffect, useState } from 'react';
 import { useTranslations } from '@/lib/i18n';
 import type { DashboardServiceDefinition } from '@/lib/utils/dashboardServices';
 import { ActionIcon, Text, Tooltip } from '@mantine/core';
@@ -260,6 +259,13 @@ export const SUBNAV_CONFIG: Record<string, SubNavItem[]> = {
       icon: IconMessage,
       matcher: (p) => p.startsWith('/dashboard/tracing/threads'),
     },
+    {
+      id: 'agents',
+      label: 'Agents',
+      href: '/dashboard/tracing/agents',
+      icon: IconRobot,
+      matcher: (p) => p.startsWith('/dashboard/tracing/agents'),
+    },
   ],
   cost: [
     {
@@ -617,63 +623,6 @@ export const SUBNAV_CONFIG: Record<string, SubNavItem[]> = {
   ],
 };
 
-// ── Dynamic agent directory for the Tracing sub-nav ────────────────────────
-// The observability landing page intentionally has NO agent list — agents
-// live here in the left menu instead. Fetched once per page load (module
-// cache, 5-minute TTL) so navigating between tracing pages doesn't refetch.
-
-interface TracingNavAgent {
-  name: string;
-  sessionsCount: number;
-}
-
-const TRACING_AGENT_NAV_CAP = 20;
-const TRACING_AGENT_CACHE_TTL_MS = 5 * 60 * 1000;
-let tracingAgentCache: { at: number; agents: TracingNavAgent[] } | null = null;
-let tracingAgentInflight: Promise<TracingNavAgent[]> | null = null;
-
-async function fetchTracingNavAgents(): Promise<TracingNavAgent[]> {
-  if (tracingAgentCache && Date.now() - tracingAgentCache.at < TRACING_AGENT_CACHE_TTL_MS) {
-    return tracingAgentCache.agents;
-  }
-  if (!tracingAgentInflight) {
-    tracingAgentInflight = (async () => {
-      try {
-        const res = await fetch(`/api/tracing/agents?limit=${TRACING_AGENT_NAV_CAP}`, {
-          cache: 'no-store',
-        });
-        if (!res.ok) return tracingAgentCache?.agents ?? [];
-        const payload = (await res.json()) as { agents?: TracingNavAgent[] };
-        const agents = (payload.agents ?? []).filter((a) => a.name);
-        tracingAgentCache = { at: Date.now(), agents };
-        return agents;
-      } catch {
-        return tracingAgentCache?.agents ?? [];
-      } finally {
-        tracingAgentInflight = null;
-      }
-    })();
-  }
-  return tracingAgentInflight;
-}
-
-function useTracingNavAgents(enabled: boolean): TracingNavAgent[] {
-  const [agents, setAgents] = useState<TracingNavAgent[]>(
-    () => tracingAgentCache?.agents ?? [],
-  );
-  useEffect(() => {
-    if (!enabled) return;
-    let alive = true;
-    void fetchTracingNavAgents().then((result) => {
-      if (alive) setAgents(result);
-    });
-    return () => {
-      alive = false;
-    };
-  }, [enabled]);
-  return agents;
-}
-
 interface ServiceSubNavProps {
   service: DashboardServiceDefinition;
   pathname: string;
@@ -700,7 +649,6 @@ export default function ServiceSubNav({
   const tNav = useTranslations('navigation');
   const ServiceIcon = service.icon;
   const navItems = items ?? SUBNAV_CONFIG[service.id] ?? [];
-  const tracingAgents = useTracingNavAgents(service.id === 'tracing');
 
   return (
     <aside className={classes.subnav}>
@@ -756,32 +704,6 @@ export default function ServiceSubNav({
           );
         })}
 
-        {service.id === 'tracing' && tracingAgents.length > 0 ? (
-          <>
-            <div className={classes.subnavSectionTitle}>Agents</div>
-            {tracingAgents.map((agent) => {
-              const href = `/dashboard/tracing/agents/${encodeURIComponent(agent.name)}`;
-              const active = pathname === href
-                || pathname === `/dashboard/tracing/agents/${agent.name}`;
-              return (
-                <button
-                  key={agent.name}
-                  type="button"
-                  className={`${classes.subnavItem} ${active ? classes.subnavItemActive : ''}`}
-                  onClick={() => router.push(href)}
-                  aria-current={active ? 'page' : undefined}
-                  title={agent.name}>
-                  <IconRobot size={15} stroke={1.7} />
-                  <span className={classes.subnavItemLabel}>{agent.name}</span>
-                  <span className={classes.subnavBadge}>
-                    {agent.sessionsCount.toLocaleString()}
-                  </span>
-                </button>
-              );
-            })}
-          </>
-        ) : null}
-
         <div className={classes.subnavSectionTitle}>Resources</div>
         <button
           type="button"
diff --git a/src/lib/database/mongodb/usage.mixin.ts b/src/lib/database/mongodb/usage.mixin.ts
index 4c4577b1..a14409c4 100644
--- a/src/lib/database/mongodb/usage.mixin.ts
+++ b/src/lib/database/mongodb/usage.mixin.ts
@@ -39,6 +39,10 @@ export function UsageRollupMixin<TBase extends Constructor<MongoDBProviderBase>>
         // v2 adds the agentKey dimension — drop the pre-agent unique index,
         // which would otherwise reject rows differing only in agentKey.
         await col.dropIndex('uniq_usage_daily_dims').catch(() => undefined);
+        // v3 adds the metadataKey dimension (free-form caller-supplied
+        // attribution tags) — drop v2, which would otherwise reject rows
+        // differing only in metadataKey.
+        await col.dropIndex('uniq_usage_daily_dims_v2').catch(() => undefined);
         await col.createIndex(
           {
             tenantId: 1,
@@ -49,9 +53,10 @@ export function UsageRollupMixin<TBase extends Constructor<MongoDBProviderBase>>
             service: 1,
             refKey: 1,
             agentKey: 1,
+            metadataKey: 1,
             day: 1,
           },
-          { unique: true, name: 'uniq_usage_daily_dims_v2' },
+          { unique: true, name: 'uniq_usage_daily_dims_v3' },
         );
         await col.createIndex(
           { tenantId: 1, day: -1 },
@@ -98,11 +103,16 @@ export function UsageRollupMixin<TBase extends Constructor<MongoDBProviderBase>>
               service: row.service,
               refKey: row.refKey,
               agentKey: row.agentKey ?? '',
+              metadataKey: row.metadataKey ?? '',
               day: row.day,
             },
             update: {
               $inc: inc,
-              $set: { updatedAt: new Date() },
+              // Same metadataKey ⇒ same metadata object by construction
+              // (metadataKey is its canonical serialization), so overwriting
+              // on every increment is safe and keeps a stale object from
+              // lingering if the shape changed upstream.
+              $set: { updatedAt: new Date(), metadata: row.metadata ?? {} },
               $setOnInsert: {
                 actorType: row.actorType,
                 // Real Date for the reports engine's range filters/bucketing.
diff --git a/src/lib/database/provider/types.base.ts b/src/lib/database/provider/types.base.ts
index 213f28f7..6cce909a 100644
--- a/src/lib/database/provider/types.base.ts
+++ b/src/lib/database/provider/types.base.ts
@@ -240,6 +240,11 @@ export interface IAgentTracingSession extends IUsageAttributionFields {
   agentName?: string;
   agentVersion?: string;
   agentModel?: string;
+  /** Free-form caller-supplied attribution tags (e.g. `{ complexity: 'complex' }`),
+   *  sanitized at ingest — sibling of `agent`, not nested under it. Flows into
+   *  `usage_daily.metadata` via `recordTracingSessionCreated`/`recordTraceModelUsage`
+   *  so callers can group/report on whatever key they send without a schema change. */
+  metadata?: Record<string, string>;
   config?: Record<string, unknown>;
   summary?: Record<string, unknown>;
   status?: string;
@@ -783,6 +788,13 @@ export interface IUsageDaily {
   /** Agent the usage is attributed to (tracing agentName); '' when absent.
    *  Rows written before the dimension shipped lack the field entirely. */
   agentKey: string;
+  /** Free-form caller-supplied attribution tags (tracing `metadata`), e.g.
+   *  `{ complexity: 'complex' }`. '' / {} when absent. */
+  metadata: Record<string, string>;
+  /** Canonical serialization of `metadata` (sorted-entries JSON) — the actual
+   *  rollup dimension, since Mongo/SQLite can't uniquely-index an object.
+   *  '' when `metadata` is absent/empty. */
+  metadataKey: string;
   /** UTC calendar day, 'YYYY-MM-DD'. */
   day: string;
   /**
@@ -817,6 +829,10 @@ export interface IUsageDailyIncrement {
   refKey: string;
   /** Agent attribution dimension; providers default it to ''. */
   agentKey?: string;
+  /** Free-form caller-supplied attribution tags; providers default it to {}. */
+  metadata?: Record<string, string>;
+  /** Canonical serialization of `metadata`; providers default it to ''. */
+  metadataKey?: string;
   day: string;
   requests?: number;
   errors?: number;
diff --git a/src/lib/database/sqlite/base.ts b/src/lib/database/sqlite/base.ts
index 3dcce1ad..0340f96b 100644
--- a/src/lib/database/sqlite/base.ts
+++ b/src/lib/database/sqlite/base.ts
@@ -711,6 +711,20 @@ export class SQLiteProviderBase {
       "agentKey TEXT NOT NULL DEFAULT ''",
     );
 
+    // usage_daily.metadata (free-form caller-supplied attribution tags, e.g.
+    // `{ complexity: 'complex' }`). metadataJson is the JSON blob; metadataKey
+    // is its canonical serialization and the actual rollup/unique-index
+    // dimension (SQLite can't uniquely-index a JSON column's contents). The
+    // v3 unique index that includes metadataKey is created in
+    // applyTenantIndexes (must run after this migration).
+    this.ensureTableColumn(db, TABLES.usageDaily, 'metadataJson', 'metadataJson TEXT');
+    this.ensureTableColumn(
+      db,
+      TABLES.usageDaily,
+      'metadataKey',
+      "metadataKey TEXT NOT NULL DEFAULT ''",
+    );
+
     // external_model_pricing.versions (effective-dated price history) was
     // added after the table shipped; ensure on boot for DBs created before.
     this.ensureTableColumn(db, TABLES.externalModelPricing, 'versions', 'versions TEXT');
@@ -807,13 +821,15 @@ export class SQLiteProviderBase {
         ON ${TABLES.modelUsageLogs}(tenantId, userId, createdAt DESC);
     `);
 
-    // usage_daily unique dimension index v2 (adds agentKey). Same ordering
-    // constraint as above: agentKey reaches legacy DBs via ensureTableColumn.
-    // The pre-agent index would reject rows differing only in agentKey.
+    // usage_daily unique dimension index v3 (adds metadataKey, on top of v2's
+    // agentKey). Same ordering constraint as above: agentKey/metadataKey
+    // reach legacy DBs via ensureTableColumn. v2 would reject rows differing
+    // only in metadataKey.
     db.exec(`
       DROP INDEX IF EXISTS uniq_usage_daily_dims;
-      CREATE UNIQUE INDEX IF NOT EXISTS uniq_usage_daily_dims_v2
-        ON ${TABLES.usageDaily}(tenantId, projectId, userId, apiTokenId, source, service, refKey, agentKey, day);
+      DROP INDEX IF EXISTS uniq_usage_daily_dims_v2;
+      CREATE UNIQUE INDEX IF NOT EXISTS uniq_usage_daily_dims_v3
+        ON ${TABLES.usageDaily}(tenantId, projectId, userId, apiTokenId, source, service, refKey, agentKey, metadataKey, day);
       CREATE INDEX IF NOT EXISTS idx_usage_daily_agent_day
         ON ${TABLES.usageDaily}(tenantId, agentKey, day DESC);
     `);
diff --git a/src/lib/database/sqlite/schema.ts b/src/lib/database/sqlite/schema.ts
index 347a2751..66f1e7d8 100644
--- a/src/lib/database/sqlite/schema.ts
+++ b/src/lib/database/sqlite/schema.ts
@@ -603,6 +603,8 @@ export const TENANT_SCHEMA_SQL = `
     service TEXT NOT NULL,
     refKey TEXT NOT NULL DEFAULT '',
     agentKey TEXT NOT NULL DEFAULT '',
+    metadataJson TEXT,
+    metadataKey TEXT NOT NULL DEFAULT '',
     day TEXT NOT NULL,
     dayDate TEXT,
     requests INTEGER NOT NULL DEFAULT 0,
@@ -617,9 +619,10 @@ export const TENANT_SCHEMA_SQL = `
     units TEXT,
     updatedAt TEXT NOT NULL
   );
-  -- The unique dimension index (v2, includes agentKey) is created in
-  -- applyTenantIndexes AFTER migrations: agentKey is added to legacy DBs by
-  -- ensureTableColumn, and referencing it here would abort the schema exec.
+  -- The unique dimension index (v3, includes agentKey + metadataKey) is
+  -- created in applyTenantIndexes AFTER migrations: agentKey/metadataKey are
+  -- added to legacy DBs by ensureTableColumn, and referencing them here
+  -- would abort the schema exec.
   CREATE INDEX IF NOT EXISTS idx_usage_daily_day ON usage_daily(tenantId, day DESC);
   CREATE INDEX IF NOT EXISTS idx_usage_daily_user_day ON usage_daily(tenantId, userId, day DESC);
 
diff --git a/src/lib/database/sqlite/usage.mixin.ts b/src/lib/database/sqlite/usage.mixin.ts
index b23f25dd..2419b93d 100644
--- a/src/lib/database/sqlite/usage.mixin.ts
+++ b/src/lib/database/sqlite/usage.mixin.ts
@@ -34,14 +34,14 @@ export function UsageRollupMixin<TBase extends Constructor<SQLiteProviderBase>>(
         SELECT id, units FROM ${TABLES.usageDaily}
         WHERE tenantId = @tenantId AND projectId = @projectId AND userId = @userId
           AND apiTokenId = @apiTokenId AND source = @source AND service = @service
-          AND refKey = @refKey AND agentKey = @agentKey AND day = @day
+          AND refKey = @refKey AND agentKey = @agentKey AND metadataKey = @metadataKey AND day = @day
       `);
       const insert = db.prepare(`
         INSERT INTO ${TABLES.usageDaily}
-        (id, tenantId, projectId, userId, apiTokenId, actorType, source, service, refKey, agentKey, day, dayDate,
+        (id, tenantId, projectId, userId, apiTokenId, actorType, source, service, refKey, agentKey, metadataJson, metadataKey, day, dayDate,
          requests, errors, inputTokens, outputTokens, cachedInputTokens, totalTokens,
          costUsd, latencyMsSum, latencyCount, units, updatedAt)
-        VALUES (@id, @tenantId, @projectId, @userId, @apiTokenId, @actorType, @source, @service, @refKey, @agentKey, @day, @dayDate,
+        VALUES (@id, @tenantId, @projectId, @userId, @apiTokenId, @actorType, @source, @service, @refKey, @agentKey, @metadataJson, @metadataKey, @day, @dayDate,
          @requests, @errors, @inputTokens, @outputTokens, @cachedInputTokens, @totalTokens,
          @costUsd, @latencyMsSum, @latencyCount, @units, @updatedAt)
       `);
@@ -72,6 +72,7 @@ export function UsageRollupMixin<TBase extends Constructor<SQLiteProviderBase>>(
             service: row.service,
             refKey: row.refKey,
             agentKey: row.agentKey ?? '',
+            metadataKey: row.metadataKey ?? '',
             day: row.day,
           };
           const counters = Object.fromEntries(
@@ -98,6 +99,10 @@ export function UsageRollupMixin<TBase extends Constructor<SQLiteProviderBase>>(
             insert.run({
               id: this.newId(),
               ...dims,
+              metadataJson:
+                row.metadata && Object.keys(row.metadata).length > 0
+                  ? this.toJson(row.metadata)
+                  : null,
               actorType: row.actorType,
               // Real Date (ISO) for the reports engine's range filters/bucketing.
               dayDate: `${row.day}T00:00:00.000Z`,
@@ -199,6 +204,8 @@ export function UsageRollupMixin<TBase extends Constructor<SQLiteProviderBase>>(
         service: String(row.service),
         refKey: String(row.refKey ?? ''),
         agentKey: String(row.agentKey ?? ''),
+        metadata: this.parseJson<Record<string, string>>(row.metadataJson, {}),
+        metadataKey: String(row.metadataKey ?? ''),
         day: String(row.day),
         dayDate: row.dayDate ? new Date(String(row.dayDate)) : undefined,
         requests: Number(row.requests ?? 0),
diff --git a/src/lib/services/agentTracing.ts b/src/lib/services/agentTracing.ts
index 92bf93e4..e9627ad1 100644
--- a/src/lib/services/agentTracing.ts
+++ b/src/lib/services/agentTracing.ts
@@ -29,6 +29,8 @@ export function recordTracingSessionCreated(params: {
   tenantId: string;
   projectId?: string;
   agentName?: string;
+  /** Free-form caller-supplied attribution tags (tracing `metadata`). */
+  metadata?: Record<string, string>;
 }): UsageAttribution {
   return recordUsageEvent({
     tenantDbName: params.tenantDbName,
@@ -36,6 +38,7 @@ export function recordTracingSessionCreated(params: {
     projectId: params.projectId,
     service: 'tracing',
     refKey: params.agentName ?? '',
+    metadata: params.metadata,
     status: 'success',
   });
 }
@@ -147,6 +150,8 @@ export async function recordTraceModelUsage(params: {
   tenantId: string;
   projectId?: string;
   agentName?: string;
+  /** Free-form caller-supplied attribution tags (tracing `metadata`). */
+  metadata?: Record<string, string>;
   events: TraceUsageEventLike[];
   previousEvents?: TraceUsageEventLike[];
 }): Promise<void> {
@@ -200,6 +205,7 @@ export async function recordTraceModelUsage(params: {
         service: 'models',
         refKey: hubModel?.key ?? modelName,
         agentKey: params.agentName ?? '',
+        metadata: params.metadata,
         source: 'tracing',
         status: 'success',
         inputTokens,
diff --git a/src/lib/services/agents/agentService.ts b/src/lib/services/agents/agentService.ts
index f31956d2..9e81d3cf 100644
--- a/src/lib/services/agents/agentService.ts
+++ b/src/lib/services/agents/agentService.ts
@@ -475,6 +475,7 @@ async function createInternalTracingSink(
                     agentVersion: session.agent?.version ?? undefined,
                     agentModel: session.agent?.model ?? undefined,
                     config: session.config ?? {},
+                    metadata: session.metadata ?? {},
                     summary: session.summary ?? {},
                     status: session.status || 'unknown',
                     startedAt: session.startedAt ? new Date(session.startedAt) : new Date(),
@@ -502,6 +503,7 @@ async function createInternalTracingSink(
                         tenantId,
                         projectId,
                         agentName: sessionDoc.agentName,
+                        metadata: sessionDoc.metadata,
                     });
                     await db.createAgentTracingSession({
                         ...sessionDoc,
diff --git a/src/lib/services/otlpMapper.ts b/src/lib/services/otlpMapper.ts
index 2052458b..66a248fa 100644
--- a/src/lib/services/otlpMapper.ts
+++ b/src/lib/services/otlpMapper.ts
@@ -300,6 +300,39 @@ function getConventionTokens(attrs: OtlpKeyValue[] | undefined) {
 }
 
 /** Conversation identifier — the closest thing OTel has to a thread id. */
+/** Same charset/length the JSON/stream ingest sanitizer enforces
+ *  (see `sanitizeTracingMetadata` in `client-tracing.ts`). */
+const METADATA_KEY_PATTERN = /^[a-zA-Z0-9_]{1,40}$/;
+const MAX_METADATA_KEYS = 10;
+const MAX_METADATA_VALUE_LENGTH = 200;
+const METADATA_ATTR_PREFIX = 'cognipeer.metadata.';
+
+/**
+ * Extract free-form caller-supplied attribution tags from `cognipeer.metadata.<key>`
+ * resource attributes (agent-sdk's OTLP metadata convention), sanitized with the
+ * same rules as the JSON/stream ingest path. Returns `undefined` when none are
+ * present/valid so callers can omit the field entirely (matches the JSON path).
+ */
+function getMetadataAttrs(attrs: OtlpKeyValue[] | undefined): Record<string, string> | undefined {
+  if (!attrs?.length) return undefined;
+  const result: Record<string, string> = {};
+  for (const attr of attrs) {
+    if (!attr.key?.startsWith(METADATA_ATTR_PREFIX)) continue;
+    if (Object.keys(result).length >= MAX_METADATA_KEYS) break;
+    const key = attr.key.slice(METADATA_ATTR_PREFIX.length);
+    const value = attr.value?.stringValue;
+    if (
+      !METADATA_KEY_PATTERN.test(key)
+      || typeof value !== 'string'
+      || value.length > MAX_METADATA_VALUE_LENGTH
+    ) {
+      continue;
+    }
+    result[key] = value;
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
 function getConventionThreadId(attrs: OtlpKeyValue[] | undefined): string | undefined {
   return firstStringAttr(attrs, [
     'cognipeer.thread.id',
@@ -553,6 +586,7 @@ export function mapOtlpToInternalModels(
       || spans.map((span) => getConventionThreadId(span.attributes)).find(Boolean);
     const agentModel = getStringAttr(resourceAttrs, 'cognipeer.agent.model');
     const agentProvider = getStringAttr(resourceAttrs, 'cognipeer.agent.provider');
+    const metadata = getMetadataAttrs(resourceAttrs);
 
     const startedAt = nanoToDate(rootSpan.startTimeUnixNano);
     const endedAt = nanoToDate(rootSpan.endTimeUnixNano);
@@ -735,6 +769,7 @@ export function mapOtlpToInternalModels(
       agentName: serviceName,
       agentVersion: serviceVersion,
       agentModel,
+      metadata,
       status,
       startedAt,
       endedAt,
diff --git a/src/lib/services/spend/spendService.ts b/src/lib/services/spend/spendService.ts
index 8c3569e0..275feb58 100644
--- a/src/lib/services/spend/spendService.ts
+++ b/src/lib/services/spend/spendService.ts
@@ -13,6 +13,7 @@ import { listModels } from '@/lib/services/models/modelService';
 import {
   getUsageBreakdown,
   type UsageBreakdown,
+  type UsageBreakdownGroupBy,
 } from '@/lib/services/usage/usageBreakdown';
 
 export interface SpendContext {
@@ -136,7 +137,9 @@ export async function getSpendReport(
 }
 
 /** Client-facing entity names for the per-user / per-token / per-agent spend breakdown. */
-export type SpendGroupByEntity = 'user' | 'api_key' | 'agent';
+/** `metadata.<key>` groups by a free-form attribution tag; see
+ *  `parseMetadataGroupByKey` for the key-format contract. */
+export type SpendGroupByEntity = 'user' | 'api_key' | 'agent' | `metadata.${string}`;
 
 export interface SpendEntityBreakdownOptions {
   from?: Date;
@@ -171,7 +174,9 @@ export async function getSpendEntityBreakdown(
         ? 'token'
         : options.entity === 'agent'
           ? 'agent'
-          : 'user',
+          : options.entity.startsWith('metadata.')
+            ? (options.entity as UsageBreakdownGroupBy)
+            : 'user',
     from: options.from,
     to: options.to,
   });
diff --git a/src/lib/services/usage/usageBreakdown.ts b/src/lib/services/usage/usageBreakdown.ts
index ba7ece5c..b0be594b 100644
--- a/src/lib/services/usage/usageBreakdown.ts
+++ b/src/lib/services/usage/usageBreakdown.ts
@@ -15,7 +15,39 @@
 import { getDatabase } from '@/lib/database';
 import type { IUsageDaily } from '@/lib/database';
 
-export type UsageBreakdownGroupBy = 'user' | 'token' | 'agent';
+/**
+ * `metadata.<key>` groups by one key of the free-form `metadata` bag callers
+ * attach at tracing ingest time (e.g. `metadata.complexity`) — dynamic, no
+ * schema change needed for a new key. Key format is validated where the
+ * string is parsed from a request (`parseMetadataGroupByKey`); this type only
+ * documents the shape.
+ */
+export type UsageBreakdownGroupBy = 'user' | 'token' | 'agent' | `metadata.${string}`;
+
+const METADATA_GROUP_BY_PREFIX = 'metadata.';
+/** Same charset/length the ingest side enforces on metadata keys
+ *  (see `sanitizeTracingMetadata` in `client-tracing.ts`). */
+const METADATA_KEY_PATTERN = /^[a-zA-Z0-9_]{1,40}$/;
+
+function metadataGroupByKey(groupBy: UsageBreakdownGroupBy): string | undefined {
+  return groupBy.startsWith(METADATA_GROUP_BY_PREFIX)
+    ? groupBy.slice(METADATA_GROUP_BY_PREFIX.length)
+    : undefined;
+}
+
+/**
+ * Parse+validate a `group_by`/`group_by_entity` request value of the form
+ * `metadata.<key>` into its key, or `undefined` if it isn't that shape.
+ * Callers MUST reject the request (400) when a value that merely starts with
+ * `metadata.` fails this — never fall back to treating it as a literal id:
+ * the key ends up in a Mongo `metadata.<key>` dot-path / row property lookup
+ * downstream, so an unvalidated key is a query-injection surface.
+ */
+export function parseMetadataGroupByKey(value: string): string | undefined {
+  if (!value.startsWith(METADATA_GROUP_BY_PREFIX)) return undefined;
+  const key = value.slice(METADATA_GROUP_BY_PREFIX.length);
+  return METADATA_KEY_PATTERN.test(key) ? key : undefined;
+}
 
 export interface UsageBreakdownEntry {
   /** userId, apiTokenId or agentKey depending on groupBy; '' = unattributed. */
@@ -72,10 +104,11 @@ export function groupUsageDailyRows(
       | 'totalTokens'
       | 'costUsd'
     > &
-      Partial<Pick<IUsageDaily, 'agentKey'>>
+      Partial<Pick<IUsageDaily, 'agentKey' | 'metadata'>>
   >,
   groupBy: UsageBreakdownGroupBy,
 ): { totals: UsageBreakdownTotals; entries: UsageBreakdownEntry[] } {
+  const metadataKey = metadataGroupByKey(groupBy);
   const byId = new Map<string, UsageBreakdownEntry>();
   const totals: UsageBreakdownTotals = {
     requests: 0,
@@ -87,13 +120,15 @@ export function groupUsageDailyRows(
   };
 
   for (const row of rows) {
-    // Legacy rows predate the agentKey dimension — treat missing as ''.
+    // Legacy rows predate the agentKey/metadata dimensions — treat missing as ''.
     const id =
       (groupBy === 'user'
         ? row.userId
         : groupBy === 'token'
           ? row.apiTokenId
-          : row.agentKey) ?? '';
+          : metadataKey !== undefined
+            ? row.metadata?.[metadataKey]
+            : row.agentKey) ?? '';
     const entry = byId.get(id) ?? {
       id,
       requests: 0,
@@ -139,9 +174,9 @@ export async function resolveUsageEntityNames(
   const ids = [...new Set(entries.map((entry) => entry.id).filter((id) => id !== ''))];
   if (ids.length === 0) return;
 
-  // Agent keys are tracing agent names — there is no entity record to
-  // resolve; the key itself is the display name.
-  if (groupBy === 'agent') {
+  // Agent keys (and metadata values) are plain strings the caller sent —
+  // there is no entity record to resolve; the key itself is the display name.
+  if (groupBy === 'agent' || metadataGroupByKey(groupBy) !== undefined) {
     for (const entry of entries) {
       if (entry.id !== '') entry.name = entry.id;
     }
diff --git a/src/lib/services/usage/usageEvents.ts b/src/lib/services/usage/usageEvents.ts
index 956f9f6e..0475bc12 100644
--- a/src/lib/services/usage/usageEvents.ts
+++ b/src/lib/services/usage/usageEvents.ts
@@ -42,6 +42,25 @@ export function sourceForActor(actorType?: UsageActorType): UsageSource | undefi
   }
 }
 
+/**
+ * Canonical rollup key for a `metadata` bag: sorted entries, JSON-serialized,
+ * so `{b:'2',a:'1'}` and `{a:'1',b:'2'}` collapse into the same dimension.
+ * '' when absent/empty — matches the '' convention every other dimension uses.
+ *
+ * Must be JSON (not a delimited `key=value&...` string): metadata values are
+ * arbitrary text, so an unescaped delimiter join lets two different objects
+ * collide onto the same key — e.g. `{a:'1&b=2'}` and `{a:'1',b:'2'}` would
+ * both join to `'a=1&b=2'`, silently merging unrelated rollup rows.
+ * JSON.stringify's quote-escaping keeps the encoding collision-free.
+ */
+export function canonicalMetadataKey(metadata?: Record<string, string>): string {
+  if (!metadata) return '';
+  const entries = Object.entries(metadata).filter(([key]) => key.length > 0);
+  if (entries.length === 0) return '';
+  entries.sort(([a], [b]) => a.localeCompare(b));
+  return JSON.stringify(entries);
+}
+
 /**
  * Resolve the attribution envelope from the ambient request context, with
  * optional explicit overrides for call sites where the AsyncLocalStorage
@@ -71,6 +90,9 @@ export interface UsageEventInput {
   refKey?: string;
   /** Agent the usage belongs to (tracing agentName); rollup dimension. */
   agentKey?: string;
+  /** Free-form caller-supplied attribution tags (tracing `metadata`, e.g.
+   *  `{ complexity: 'complex' }`); rollup dimension via `metadataKey`. */
+  metadata?: Record<string, string>;
   /** Overrides the actor-derived origin — e.g. 'tracing' for usage derived
    *  from observability ingests rather than gateway-served calls. */
   source?: UsageSource;
diff --git a/src/lib/services/usage/usageRollup.ts b/src/lib/services/usage/usageRollup.ts
index 76bd6990..5908d3b7 100644
Binary files a/src/lib/services/usage/usageRollup.ts and b/src/lib/services/usage/usageRollup.ts differ
diff --git a/src/server/api/plugins/client-analytics.ts b/src/server/api/plugins/client-analytics.ts
index 8f0ae4c9..b1286075 100644
--- a/src/server/api/plugins/client-analytics.ts
+++ b/src/server/api/plugins/client-analytics.ts
@@ -13,8 +13,8 @@
 import type { FastifyPluginAsync } from 'fastify';
 import { createLogger } from '@/lib/core/logger';
 import { getDashboardData } from '@/lib/services/dashboard/dashboardService';
-import { getSpendEntityBreakdown, getSpendReport } from '@/lib/services/spend';
-import { getUsageServiceBreakdown } from '@/lib/services/usage/usageBreakdown';
+import { getSpendEntityBreakdown, getSpendReport, type SpendGroupByEntity } from '@/lib/services/spend';
+import { getUsageServiceBreakdown, parseMetadataGroupByKey } from '@/lib/services/usage/usageBreakdown';
 import { sendApiTokenError, withClientApiRequestContext } from '../fastify-utils';
 
 const logger = createLogger('api:client-analytics');
@@ -50,8 +50,16 @@ export const clientAnalyticsApiPlugin: FastifyPluginAsync = async (app) => {
         from?: string; to?: string; group_by?: string; interval?: string; model?: string;
       };
       const groupBy = query.group_by ?? 'model';
-      if (!(VALID_GROUP_BY as readonly string[]).includes(groupBy)) {
-        return reply.code(400).send({ error: '`group_by` must be model, user, token, service, or agent' });
+      const groupByMetadataKey = groupBy.startsWith('metadata.')
+        ? parseMetadataGroupByKey(groupBy)
+        : undefined;
+      if (groupBy.startsWith('metadata.') && !groupByMetadataKey) {
+        return reply.code(400).send({
+          error: '`group_by` metadata key must match /^[a-zA-Z0-9_]{1,40}$/',
+        });
+      }
+      if (!groupByMetadataKey && !(VALID_GROUP_BY as readonly string[]).includes(groupBy)) {
+        return reply.code(400).send({ error: '`group_by` must be model, user, token, service, agent, or metadata.<key>' });
       }
       const interval = query.interval ?? 'day';
       if (!(VALID_INTERVAL as readonly string[]).includes(interval)) {
@@ -146,8 +154,11 @@ export const clientAnalyticsApiPlugin: FastifyPluginAsync = async (app) => {
         });
       }
 
-      // group_by=user | token | agent → per-entity attribution from usage_daily.
-      const entity = groupBy === 'token' ? 'api_key' : groupBy === 'agent' ? 'agent' : 'user';
+      // group_by=user | token | agent | metadata.<key> → per-entity attribution
+      // from usage_daily.
+      const entity: SpendGroupByEntity = groupByMetadataKey
+        ? (groupBy as SpendGroupByEntity)
+        : groupBy === 'token' ? 'api_key' : groupBy === 'agent' ? 'agent' : 'user';
       const breakdown = await getSpendEntityBreakdown(
         {
           tenantDbName: auth.tenantDbName,
@@ -162,11 +173,13 @@ export const clientAnalyticsApiPlugin: FastifyPluginAsync = async (app) => {
         },
       );
 
-      const idField = entity === 'user'
-        ? 'user_id'
-        : entity === 'agent'
-          ? 'agent_key'
-          : 'api_token_id';
+      const idField = groupByMetadataKey
+        ? groupByMetadataKey
+        : entity === 'user'
+          ? 'user_id'
+          : entity === 'agent'
+            ? 'agent_key'
+            : 'api_token_id';
       return reply.code(200).send({
         object: 'analytics.usage',
         group_by: groupBy,
diff --git a/src/server/api/plugins/client-spend.ts b/src/server/api/plugins/client-spend.ts
index 64a1d09a..acb7eee1 100644
--- a/src/server/api/plugins/client-spend.ts
+++ b/src/server/api/plugins/client-spend.ts
@@ -31,6 +31,7 @@ import {
   getSpendReport,
   type SpendGroupByEntity,
 } from '@/lib/services/spend';
+import { parseMetadataGroupByKey } from '@/lib/services/usage/usageBreakdown';
 import type { ApiTokenContext } from '@/lib/services/apiTokenAuth';
 import {
   getApiTokenContextForRequest,
@@ -132,8 +133,16 @@ export const clientSpendApiPlugin: FastifyPluginAsync = async (app) => {
       }
 
       if (query.group_by_entity !== undefined) {
-        if (!(VALID_GROUP_BY_ENTITY as readonly string[]).includes(query.group_by_entity)) {
-          return reply.code(400).send({ error: '`group_by_entity` must be user, api_key, or agent' });
+        const metadataKey = query.group_by_entity.startsWith('metadata.')
+          ? parseMetadataGroupByKey(query.group_by_entity)
+          : undefined;
+        if (query.group_by_entity.startsWith('metadata.') && !metadataKey) {
+          return reply.code(400).send({
+            error: '`group_by_entity` metadata key must match /^[a-zA-Z0-9_]{1,40}$/',
+          });
+        }
+        if (!metadataKey && !(VALID_GROUP_BY_ENTITY as readonly string[]).includes(query.group_by_entity)) {
+          return reply.code(400).send({ error: '`group_by_entity` must be user, api_key, agent, or metadata.<key>' });
         }
         const entity = query.group_by_entity as SpendGroupByEntity;
 
@@ -151,11 +160,13 @@ export const clientSpendApiPlugin: FastifyPluginAsync = async (app) => {
           },
         );
 
-        const idField = entity === 'user'
-          ? 'user_id'
-          : entity === 'agent'
-            ? 'agent_key'
-            : 'api_token_id';
+        const idField = metadataKey
+          ? metadataKey
+          : entity === 'user'
+            ? 'user_id'
+            : entity === 'agent'
+              ? 'agent_key'
+              : 'api_token_id';
         return reply.code(200).send({
           object: 'spend.breakdown',
           group_by_entity: entity,
diff --git a/src/server/api/plugins/client-tracing.ts b/src/server/api/plugins/client-tracing.ts
index 8eac2338..408fbba4 100644
--- a/src/server/api/plugins/client-tracing.ts
+++ b/src/server/api/plugins/client-tracing.ts
@@ -130,6 +130,9 @@ type TracingSessionPayload = {
   endedAt?: string | Date;
   errors?: unknown[];
   events?: TracingEventPayload[];
+  /** Free-form caller-supplied attribution tags (e.g. `{ complexity: 'complex' }`),
+   *  sibling of `agent` — sanitized by `sanitizeTracingMetadata` before storage. */
+  metadata?: Record<string, unknown>;
   rootSpanId?: string;
   sessionId?: string;
   startedAt?: string | Date;
@@ -472,6 +475,45 @@ function getEventUsage(event: TracingEventPayload): TracingUsage {
   return event.usage || event.metadata?.usage || {};
 }
 
+/** Caller-supplied `metadata` key format — shared with the read-side
+ *  `group_by`/`group_by_entity=metadata.<key>` validation (`usageBreakdown.ts`). */
+const METADATA_KEY_PATTERN = /^[a-zA-Z0-9_]{1,40}$/;
+const MAX_METADATA_KEYS = 10;
+const MAX_METADATA_VALUE_LENGTH = 200;
+
+/**
+ * Sanitize the free-form `metadata` attribution bag callers attach to a
+ * tracing session: plain string values only, bounded key count/length, safe
+ * key charset (it later becomes a Mongo `metadata.<key>` dot-path / SQLite
+ * JSON key in read queries — unsanitized keys would be an injection surface).
+ * Drops offending entries rather than rejecting the whole ingest; logs once
+ * per call when anything was dropped.
+ */
+function sanitizeTracingMetadata(raw: unknown): Record<string, string> | undefined {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const result: Record<string, string> = {};
+  let droppedCount = 0;
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (Object.keys(result).length >= MAX_METADATA_KEYS) {
+      droppedCount += 1;
+      continue;
+    }
+    if (
+      !METADATA_KEY_PATTERN.test(key)
+      || typeof value !== 'string'
+      || value.length > MAX_METADATA_VALUE_LENGTH
+    ) {
+      droppedCount += 1;
+      continue;
+    }
+    result[key] = value;
+  }
+  if (droppedCount > 0) {
+    logger.warn('Tracing metadata: dropped invalid entries', { droppedCount });
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
 export const clientTracingApiPlugin: FastifyPluginAsync = async (app) => {
   app.post('/client/v1/traces', withClientApiRequestContext(async (request, reply) => {
     try {
@@ -683,6 +725,7 @@ export const clientTracingApiPlugin: FastifyPluginAsync = async (app) => {
               tenantId: ctx.tenantId,
               projectId: ctx.projectId,
               agentName: mergedSession.agentName,
+              metadata: mergedSession.metadata,
             });
             await backgroundDb.createAgentTracingSession({
               ...mergedSession,
@@ -698,6 +741,7 @@ export const clientTracingApiPlugin: FastifyPluginAsync = async (app) => {
             tenantId: ctx.tenantId,
             projectId: ctx.projectId,
             agentName: mergedSession.agentName,
+            metadata: mergedSession.metadata,
             events: insertedEvents,
           });
         }
@@ -786,6 +830,7 @@ export const clientTracingApiPlugin: FastifyPluginAsync = async (app) => {
         endedAt: payload.endedAt ? new Date(payload.endedAt) : undefined,
         errors: toErrorList(payload.errors),
         eventCounts: getSummaryEventCounts(payload.summary),
+        metadata: sanitizeTracingMetadata(payload.metadata),
         modelsUsed: Array.from(modelsUsed),
         projectId: ctx.projectId,
         rootSpanId: typeof payload.rootSpanId === 'string' ? payload.rootSpanId : undefined,
@@ -861,6 +906,7 @@ export const clientTracingApiPlugin: FastifyPluginAsync = async (app) => {
             tenantId: ctx.tenantId,
             projectId: ctx.projectId,
             agentName: sessionDoc.agentName,
+            metadata: sessionDoc.metadata,
           });
           await backgroundDb.createAgentTracingSession({
             ...sessionDoc,
@@ -939,6 +985,7 @@ export const clientTracingApiPlugin: FastifyPluginAsync = async (app) => {
           tenantId: ctx.tenantId,
           projectId: ctx.projectId,
           agentName: sessionDoc.agentName,
+          metadata: sessionDoc.metadata,
           events: createdEvents,
           previousEvents,
         });
@@ -1007,6 +1054,7 @@ export const clientTracingApiPlugin: FastifyPluginAsync = async (app) => {
         endedAt: undefined,
         errors: [],
         eventCounts: {},
+        metadata: sanitizeTracingMetadata(payload.metadata),
         modelsUsed: payload.agent?.model ? [payload.agent.model] : [],
         projectId: ctx.projectId,
         rootSpanId: typeof payload.rootSpanId === 'string' ? payload.rootSpanId : undefined,
@@ -1046,11 +1094,13 @@ export const clientTracingApiPlugin: FastifyPluginAsync = async (app) => {
       // keep every running total and re-arm it for the incoming leg.
       const hasAgent = Object.keys(sessionDoc.agent ?? {}).length > 0;
       const hasConfig = Object.keys(sessionDoc.config ?? {}).length > 0;
+      const hasMetadata = Object.keys(sessionDoc.metadata ?? {}).length > 0;
       const reopenDoc: Partial<IAgentTracingSession> = {
         // A re-start body is often empty. Writing `{}` over these would drop the
         // agent identity the reopen exists to preserve.
         ...(hasAgent ? { agent: sessionDoc.agent } : {}),
         ...(hasConfig ? { config: sessionDoc.config } : {}),
+        ...(hasMetadata ? { metadata: sessionDoc.metadata } : {}),
         agentModel: sessionDoc.agentModel ?? existing?.agentModel,
         agentName: sessionDoc.agentName ?? existing?.agentName,
         agentVersion: sessionDoc.agentVersion ?? existing?.agentVersion,
@@ -1074,6 +1124,7 @@ export const clientTracingApiPlugin: FastifyPluginAsync = async (app) => {
             tenantId: ctx.tenantId,
             projectId: ctx.projectId,
             agentName: sessionDoc.agentName,
+            metadata: sessionDoc.metadata,
           });
           await backgroundDb.createAgentTracingSession({
             ...sessionDoc,
@@ -1200,6 +1251,7 @@ export const clientTracingApiPlugin: FastifyPluginAsync = async (app) => {
           tenantId: ctx.tenantId,
           projectId: ctx.projectId,
           agentName: session.agentName,
+          metadata: session.metadata,
           events: [eventDoc],
         });