From 9668dee1f27642f947c327973e7a8d1bc825439b Mon Sep 17 00:00:00 2001 From: Dustin Healy <54083382+dustinhealy@users.noreply.github.com> Date: Thu, 19 Nov 2026 07:25:45 -0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=B0=20feat:=20Expose=20Conversation=20?= =?UTF-8?q?Metadata=20Through=20the=20Agents=20API=20(#18490)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * ✨ feat: Read Conversation Metadata Through the Agents API * fix: Preserve Exact Conversation Tag Filters --- .../__tests__/idempotencyLimiter.spec.js | 1 + api/server/routes/agents/conversations.js | 20 + api/server/routes/agents/index.js | 2 + api/server/routes/agents/middleware.js | 7 +- docs/conversation-metadata-api.md | 17 + e2e/setup/agent-management.ts | 4 +- e2e/specs/mock/conversation-metadata.spec.ts | 148 ++++++ packages/api/openapi/agents.openapi.json | 424 +++++++++++++++++- packages/api/src/conversations/index.ts | 1 + packages/api/src/conversations/metadata.ts | 197 ++++++++ .../api/src/middleware/management.spec.ts | 35 ++ packages/api/src/middleware/management.ts | 11 +- packages/api/src/openapi/conversations.ts | 89 ++++ packages/api/src/openapi/document.ts | 4 +- packages/api/src/openapi/registry.ts | 10 +- packages/data-provider/src/config.ts | 1 + packages/data-schemas/src/index.ts | 7 + .../src/methods/conversationMetadata.ts | 147 ++++++ packages/data-schemas/src/methods/index.ts | 4 + 19 files changed, 1121 insertions(+), 8 deletions(-) create mode 100644 api/server/routes/agents/conversations.js create mode 100644 docs/conversation-metadata-api.md create mode 100644 e2e/specs/mock/conversation-metadata.spec.ts create mode 100644 packages/api/src/conversations/metadata.ts create mode 100644 packages/api/src/openapi/conversations.ts create mode 100644 packages/data-schemas/src/methods/conversationMetadata.ts diff --git a/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js b/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js index 8f2001ae95..e01791ce1a 100644 --- a/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js +++ b/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js @@ -97,6 +97,7 @@ jest.mock('~/server/routes/agents/v1', () => ({ jest.mock('~/server/routes/agents/openai', () => require('express').Router()); jest.mock('~/server/routes/agents/responses', () => require('express').Router()); jest.mock('~/server/routes/agents/skills', () => require('express').Router()); +jest.mock('~/server/routes/agents/conversations', () => require('express').Router()); jest.mock('~/server/routes/agents/management', () => { const router = require('express').Router(); router.use((_req, res) => res.status(200).json({ surface: 'management' })); diff --git a/api/server/routes/agents/conversations.js b/api/server/routes/agents/conversations.js new file mode 100644 index 0000000000..b7415be8d4 --- /dev/null +++ b/api/server/routes/agents/conversations.js @@ -0,0 +1,20 @@ +const express = require('express'); +const { createConversationMetadataHandlers } = require('@librechat/api'); +const { checkBan, requireTermsAcceptance } = require('~/server/middleware'); +const { getConversationMetadata, listConversationMetadata } = require('~/models'); +const { requireConversationReadAuth } = require('./middleware'); + +const router = express.Router(); +const { list, get, missing } = createConversationMetadataHandlers({ + getConversationMetadata, + listConversationMetadata, +}); + +router.use(requireConversationReadAuth); +router.use(requireTermsAcceptance); +router.use(checkBan); +router.get('/', list); +router.get('/:id', get); +router.use(missing); + +module.exports = router; diff --git a/api/server/routes/agents/index.js b/api/server/routes/agents/index.js index e13f802045..3c77dc8fac 100644 --- a/api/server/routes/agents/index.js +++ b/api/server/routes/agents/index.js @@ -79,6 +79,7 @@ const { cancelOwnerBackgroundResponse, } = require('~/server/services/Responses'); const management = require('./management'); +const conversations = require('./conversations'); const skills = require('./skills'); const openai = require('./openai'); const { v1 } = require('./v1'); @@ -153,6 +154,7 @@ router.use('/v1/responses', responses); */ router.use('/v1/agents', management); router.use('/v1/skills', skills); +router.use('/v1/conversations', conversations); /** * OpenAI-compatible API routes (API key authentication handled in route file) diff --git a/api/server/routes/agents/middleware.js b/api/server/routes/agents/middleware.js index a5dc65b70a..ccc2d70572 100644 --- a/api/server/routes/agents/middleware.js +++ b/api/server/routes/agents/middleware.js @@ -31,10 +31,14 @@ const requireRemoteAgentAuth = createRemoteAgentAuth({ recordAuditEntry: db.recordAuditEntry, }); -const requireAgentManagementAuth = createAgentManagementAuth({ +const managementAuthDeps = { findUser: db.findUser, isPrincipalActive: db.isAgentTriggerPrincipalActive, getAppConfig, +}; +const requireAgentManagementAuth = createAgentManagementAuth(managementAuthDeps); +const requireConversationReadAuth = createAgentManagementAuth(managementAuthDeps, { + requireConversationRead: true, }); const checkRemoteAgentsFeature = generateCheckAccess({ @@ -57,5 +61,6 @@ module.exports = { preAuthTenantMiddleware, requireRemoteAgentAuth, requireAgentManagementAuth, + requireConversationReadAuth, checkRemoteAgentsFeature, }; diff --git a/docs/conversation-metadata-api.md b/docs/conversation-metadata-api.md new file mode 100644 index 0000000000..72ca27c70a --- /dev/null +++ b/docs/conversation-metadata-api.md @@ -0,0 +1,17 @@ +# Conversation metadata API + +An OIDC machine client can read the conversations of its configured LibreChat account. Set +`conversationRead: true` on that client in `endpoints.agents.managementApi.auth.clients` in +`librechat.yaml`. Access is disabled for a binding that omits the field. The configured tenant, +user, issuer, audience or required scopes, and client subject still apply. + +`GET /api/agents/v1/conversations` returns the most recently updated conversations first. The +response contains `data`, `has_more`, and the `after` cursor. Pass `after` as the next request's +`cursor` with the same filters. The default limit is 20 and the maximum is 100. Optional filters +are `agent_id`, `isArchived` (`true` or `false`), and `tags` (match any requested tag; repeat the +query parameter for multiple tags). Tag names are matched exactly. With no archive filter the page includes both archived and +active conversations. Concurrent updates can reorder conversations between requests. + +`GET /api/agents/v1/conversations/{id}` returns a conversation's title, timestamps, endpoint, +model, agent ID, tags, and archive state. Both reads exclude temporary, expired, and subagent +conversations. The endpoint returns metadata only. diff --git a/e2e/setup/agent-management.ts b/e2e/setup/agent-management.ts index a6c6ff2924..7d058f4643 100644 --- a/e2e/setup/agent-management.ts +++ b/e2e/setup/agent-management.ts @@ -11,7 +11,9 @@ const clientId = 'e2e-management-client'; export const managementAuth = { oidc: { enabled: true, issuer, audience }, - clients: [{ clientId, userId: managementUserId, tenantId: managementTenantId }], + clients: [ + { clientId, userId: managementUserId, tenantId: managementTenantId, conversationRead: true }, + ], }; /** Only the identity provider is a fixture; LibreChat verifies the token over HTTP. */ diff --git a/e2e/specs/mock/conversation-metadata.spec.ts b/e2e/specs/mock/conversation-metadata.spec.ts new file mode 100644 index 0000000000..d9c0300b13 --- /dev/null +++ b/e2e/specs/mock/conversation-metadata.spec.ts @@ -0,0 +1,148 @@ +import { ObjectId } from 'mongodb'; +import { randomUUID } from 'node:crypto'; +import { expect, test } from '@playwright/test'; +import { + managementTenantId, + managementUserId, + startManagementOidc, +} from '../../setup/agent-management'; +import { withMongo } from './db'; + +const path = '/api/agents/v1/conversations'; +const newest = new Date('2026-10-01T00:00:00.000Z'); +const label = 'Disposable metadata fixture'; +const legacyTag = ' legacy '; +const longTag = 'long-'.padEnd(300, 'x'); + +test('lists, filters, pages and reads the bound account’s conversation metadata', async ({ + request, +}) => { + const oidc = await startManagementOidc(); + const headers = { Authorization: `Bearer ${oidc.token}` }; + const ids = Array.from({ length: 9 }, () => randomUUID()); + const [first, second, legacy, undated, unrelated, otherTenant, child, temporary, expired] = ids; + const otherTenantId = `${managementTenantId}-metadata`; + try { + await withMongo(async (db) => { + await db.collection('users').insertOne({ + _id: new ObjectId(managementUserId), + name: label, + email: 'conversation-metadata@example.test', + emailVerified: true, + provider: 'local', + role: 'ADMIN', + tenantId: managementTenantId, + }); + const base = { + user: managementUserId, + tenantId: managementTenantId, + title: label, + endpoint: 'openAI', + model: 'fixture-model', + tags: ['demo'], + createdAt: newest, + }; + await db.collection('conversations').insertMany([ + { ...base, conversationId: second, updatedAt: newest, isArchived: true }, + { ...base, conversationId: first, updatedAt: newest, agent_id: 'agent_123' }, + { ...base, conversationId: undated, updatedAt: null }, + { ...base, conversationId: legacy, tags: [legacyTag, longTag, ''] }, + { ...base, conversationId: unrelated, user: new ObjectId().toString(), updatedAt: newest }, + { ...base, conversationId: otherTenant, tenantId: otherTenantId, updatedAt: newest }, + { + ...base, + conversationId: child, + updatedAt: newest, + subagentThread: { parentConversationId: first }, + }, + { ...base, conversationId: temporary, updatedAt: newest, isTemporary: true }, + { + ...base, + conversationId: expired, + updatedAt: newest, + isTemporary: false, + expiredAt: new Date(0), + }, + ]); + }); + const fetchPage = async (params?: Record) => { + const response = await request.get(path, { headers, params }); + expect(response.status()).toBe(200); + return await response.json(); + }; + + const page = await fetchPage({ limit: '1' }); + expect(page).toEqual({ + object: 'list', + data: [ + { + id: first, + title: label, + createdAt: newest.toISOString(), + updatedAt: newest.toISOString(), + endpoint: 'openAI', + model: 'fixture-model', + tags: ['demo'], + isArchived: false, + agent_id: 'agent_123', + }, + ], + first_id: first, + last_id: first, + has_more: true, + after: expect.any(String), + }); + const next = await fetchPage({ limit: '1', cursor: page.after }); + expect(next).toMatchObject({ data: [{ id: second }], has_more: true }); + const tail = await fetchPage({ limit: '1', cursor: next.after }); + expect(tail).toMatchObject({ data: [{ id: legacy, updatedAt: null }], has_more: true }); + const end = await fetchPage({ limit: '1', cursor: tail.after }); + expect(end).toMatchObject({ + data: [{ id: undated, updatedAt: null }], + has_more: false, + after: null, + }); + + const archive = await fetchPage({ isArchived: 'true', tags: 'demo' }); + expect(archive.data).toMatchObject([{ id: second }]); + const agent = await fetchPage({ agent_id: 'agent_123' }); + expect(agent.data).toMatchObject([{ id: first }]); + const tagged = await fetchPage({ tags: legacyTag }); + expect(tagged.data).toMatchObject([{ id: legacy, tags: [legacyTag, longTag, ''] }]); + for (const tag of [longTag, '']) { + const matching = await fetchPage({ tags: tag }); + expect(matching.data.map((conversation: { id: string }) => conversation.id)).toEqual([ + legacy, + ]); + } + + const mismatch = await request.get(path, { + headers, + params: { cursor: page.after, tags: 'demo' }, + }); + expect(mismatch.status()).toBe(400); + + const detail = await request.get(`${path}/${first}`, { headers }); + expect(detail.status()).toBe(200); + expect(await detail.json()).toEqual(page.data[0]); + const missing = await request.get(`${path}/${randomUUID()}`, { headers }); + expect(missing.status()).toBe(404); + expect(await missing.json()).toEqual({ + error: { code: 'not_found', message: 'Conversation not found' }, + }); + } finally { + try { + await withMongo(async (db) => { + await db.collection('conversations').deleteMany({ + tenantId: { $in: [managementTenantId, otherTenantId] }, + conversationId: { $in: ids }, + }); + await db + .collection('users') + .deleteOne({ _id: new ObjectId(managementUserId), tenantId: managementTenantId }); + }); + } finally { + await oidc.close(); + } + } +}); diff --git a/packages/api/openapi/agents.openapi.json b/packages/api/openapi/agents.openapi.json index e58559a50d..2278715550 100644 --- a/packages/api/openapi/agents.openapi.json +++ b/packages/api/openapi/agents.openapi.json @@ -3,7 +3,7 @@ "info": { "title": "LibreChat Agents API", "version": "0.1.0", - "description": "The public agent and skill management endpoints of the LibreChat Agents API. This API is in beta and may change." + "description": "The public agent, skill, and conversation management endpoints of the LibreChat Agents API. This API is in beta and may change." }, "servers": [ { @@ -2374,6 +2374,309 @@ } } } + }, + "/conversations": { + "get": { + "operationId": "listConversationMetadata", + "summary": "List the bound account’s conversation metadata", + "tags": [ + "Conversations" + ], + "security": [ + { + "oidcBearer": [] + } + ], + "description": "Requires conversationRead on the OIDC client binding. Archived conversations are included unless filtered.", + "parameters": [ + { + "in": "query", + "name": "limit", + "schema": { + "default": 20, + "type": "integer", + "minimum": 1, + "maximum": 100 + } + }, + { + "in": "query", + "name": "cursor", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 1024, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + { + "in": "query", + "name": "agent_id", + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 512 + } + }, + { + "in": "query", + "name": "tags", + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "minItems": 1, + "maxItems": 100, + "type": "array", + "items": { + "type": "string" + } + } + ] + } + }, + { + "in": "query", + "name": "isArchived", + "schema": { + "type": "string", + "enum": [ + "true", + "false" + ] + } + } + ], + "responses": { + "200": { + "description": "A page of conversation metadata", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationMetadataList" + } + } + } + }, + "400": { + "description": "Invalid request or malformed JSON body", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/JsonParseError" + } + ] + } + } + } + }, + "401": { + "description": "Authentication failed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorMessage" + } + } + } + }, + "403": { + "description": "The client is not enabled to read conversations, or the account cannot access the API", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/ErrorMessage" + }, + { + "$ref": "#/components/schemas/MessageError" + } + ] + } + } + } + }, + "409": { + "description": "The bound account is being deleted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountDeletionConflict" + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/ErrorMessage" + } + ] + } + }, + "text/html": { + "schema": { + "type": "string", + "enum": [ + "An unknown error occurred.", + "Processing error in ErrorController." + ] + } + } + } + } + } + } + }, + "/conversations/{id}": { + "get": { + "operationId": "getConversationMetadata", + "summary": "Get the bound account’s conversation metadata", + "tags": [ + "Conversations" + ], + "security": [ + { + "oidcBearer": [] + } + ], + "description": "Requires conversationRead on the OIDC client binding.", + "parameters": [ + { + "in": "path", + "name": "id", + "schema": { + "type": "string", + "description": "The conversation ID" + }, + "required": true, + "description": "The conversation ID" + } + ], + "responses": { + "200": { + "description": "The conversation metadata", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationMetadata" + } + } + } + }, + "400": { + "description": "Invalid request or malformed JSON body", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/JsonParseError" + } + ] + } + } + } + }, + "401": { + "description": "Authentication failed", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorMessage" + } + } + } + }, + "403": { + "description": "The client is not enabled to read conversations, or the account cannot access the API", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/ErrorMessage" + }, + { + "$ref": "#/components/schemas/MessageError" + } + ] + } + } + } + }, + "404": { + "description": "Conversation not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "The bound account is being deleted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccountDeletionConflict" + } + } + } + }, + "500": { + "description": "Internal server error", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Error" + }, + { + "$ref": "#/components/schemas/ErrorMessage" + } + ] + } + }, + "text/html": { + "schema": { + "type": "string", + "enum": [ + "An unknown error occurred.", + "Processing error in ErrorController." + ] + } + } + } + } + } + } } }, "components": { @@ -4138,6 +4441,80 @@ ], "additionalProperties": false }, + "ConversationMetadata": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "title": { + "type": "string" + }, + "createdAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "updatedAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "agent_id": { + "type": [ + "string", + "null" + ] + }, + "tags": { + "type": "array", + "items": { + "type": "string" + } + }, + "isArchived": { + "type": "boolean" + }, + "endpoint": { + "type": [ + "string", + "null" + ] + }, + "model": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "title", + "createdAt", + "updatedAt", + "agent_id", + "tags", + "isArchived", + "endpoint", + "model" + ], + "additionalProperties": false + }, "AgentList": { "type": "object", "properties": { @@ -4593,6 +4970,51 @@ "cleanupComplete" ] }, + "ConversationMetadataList": { + "type": "object", + "properties": { + "object": { + "type": "string", + "const": "list" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ConversationMetadata" + } + }, + "first_id": { + "type": [ + "string", + "null" + ] + }, + "last_id": { + "type": [ + "string", + "null" + ] + }, + "has_more": { + "type": "boolean" + }, + "after": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "object", + "data", + "first_id", + "last_id", + "has_more", + "after" + ], + "additionalProperties": false + }, "ErrorMessage": { "type": "object", "properties": { diff --git a/packages/api/src/conversations/index.ts b/packages/api/src/conversations/index.ts index 1c5b75a9c0..4e5176ee1b 100644 --- a/packages/api/src/conversations/index.ts +++ b/packages/api/src/conversations/index.ts @@ -11,3 +11,4 @@ export * from './retention'; export * from './save'; export * from './title'; export * from './rename'; +export * from './metadata'; diff --git a/packages/api/src/conversations/metadata.ts b/packages/api/src/conversations/metadata.ts new file mode 100644 index 0000000000..b1d72ef609 --- /dev/null +++ b/packages/api/src/conversations/metadata.ts @@ -0,0 +1,197 @@ +import { z } from 'zod'; +import { createHash } from 'node:crypto'; +import { logger } from '@librechat/data-schemas'; +import type { + ConversationMetadata, + ConversationMetadataBoundary, + ConversationMetadataMethods, + ConversationMetadataScope, +} from '@librechat/data-schemas'; +import type { Response } from 'express'; +import type { ServerRequest } from '~/types/http'; +import { mapAgentManagementError } from '../agents/management'; +import { getSafeErrorMetadata } from '~/utils/errors'; + +const identifier = z.string().trim().min(1).max(512); +// Stored bookmark names are exact strings. Let the request line bound their +// encoded size and cap how many labels can reach a single MongoDB filter. +const tag = z.string(); +const date = z.string().datetime().nullable(); + +type Query = { + limit: number; + cursor?: string; + agent_id?: string; + tags?: string[]; + isArchived?: boolean; +}; + +type List = { + object: 'list'; + data: ConversationMetadata[]; + first_id: string | null; + last_id: string | null; + has_more: boolean; + after: string | null; +}; + +export const conversationMetadataQuery: z.ZodType = z + .object({ + limit: z.coerce.number().int().min(1).max(100).default(20), + cursor: z + .string() + .min(1) + .max(1024) + .regex(/^[A-Za-z0-9_-]+$/) + .optional(), + agent_id: identifier.optional(), + tags: z + .union([tag, z.array(tag).min(1).max(100)]) + .transform((value) => [...new Set(Array.isArray(value) ? value : [value])].sort()) + .optional(), + isArchived: z + .enum(['true', 'false']) + .transform((value) => value === 'true') + .optional(), + }) + .strict(); + +export const conversationMetadataSchema: z.ZodType = z + .object({ + id: z.string(), + title: z.string(), + createdAt: date, + updatedAt: date, + agent_id: z.string().nullable(), + tags: z.array(z.string()), + isArchived: z.boolean(), + endpoint: z.string().nullable(), + model: z.string().nullable(), + }) + .strict(); + +export const conversationMetadataListSchema: z.ZodType = z + .object({ + object: z.literal('list'), + data: z.array(conversationMetadataSchema), + first_id: z.string().nullable(), + last_id: z.string().nullable(), + has_more: z.boolean(), + after: z.string().nullable(), + }) + .strict(); + +const boundarySchema = z.object({ + updatedAt: date, + id: z.string().regex(/^[a-f\d]{24}$/), +}); +const cursorSchema = z + .object({ + version: z.literal(1), + scope: z.string(), + boundary: boundarySchema, + }) + .strict(); + +type Filters = Omit; + +function cursorScope(scope: ConversationMetadataScope, filters: Filters): string { + return createHash('sha256') + .update( + JSON.stringify([ + scope.tenantId, + scope.user, + filters.agent_id ?? null, + filters.tags ?? [], + filters.isArchived ?? null, + ]), + ) + .digest('base64url'); +} + +function encode(boundary: ConversationMetadataBoundary, scope: string): string { + return Buffer.from(JSON.stringify({ version: 1, scope, boundary })).toString('base64url'); +} + +function decode(cursor: string, scope: string): ConversationMetadataBoundary | null { + try { + const parsed = cursorSchema.parse( + JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')), + ); + return parsed.scope === scope ? parsed.boundary : null; + } catch { + return null; + } +} + +function respond( + res: Response, + code: 'invalid_request' | 'not_found' | 'internal_error' | 'permission_denied', +) { + if (code === 'not_found') { + return res.status(404).json({ error: { code, message: 'Conversation not found' } }); + } + const mapped = mapAgentManagementError(code); + return res.status(mapped.status).json(mapped.body); +} + +function owner(req: ServerRequest): ConversationMetadataScope | null { + if (!req.user?.id || !req.user.tenantId) return null; + return { user: req.user.id, tenantId: req.user.tenantId }; +} + +type Handler = (req: ServerRequest, res: Response) => Promise; + +export function createConversationMetadataHandlers(deps: ConversationMetadataMethods): { + list: Handler; + get: Handler; + missing: (req: ServerRequest, res: Response) => Response; +} { + const list = async (req: ServerRequest, res: Response) => { + const scope = owner(req); + if (!scope) return respond(res, 'permission_denied'); + const parsed = conversationMetadataQuery.safeParse(req.query); + if (!parsed.success) return respond(res, 'invalid_request'); + + const { cursor, limit, ...filters } = parsed.data; + const scopeKey = cursorScope(scope, filters); + const boundary = cursor ? decode(cursor, scopeKey) : undefined; + if (boundary === null) return respond(res, 'invalid_request'); + + try { + const { data, next } = await deps.listConversationMetadata(scope, { + ...filters, + limit, + boundary, + }); + return res.json({ + object: 'list', + data, + first_id: data[0]?.id ?? null, + last_id: data[data.length - 1]?.id ?? null, + has_more: next !== null, + after: next ? encode(next, scopeKey) : null, + }); + } catch (error) { + logger.error('[conversationMetadata] List failed', getSafeErrorMetadata(error)); + return respond(res, 'internal_error'); + } + }; + + const get = async (req: ServerRequest, res: Response) => { + const scope = owner(req); + if (!scope) return respond(res, 'permission_denied'); + const parsed = identifier.safeParse((req.params as { id?: string }).id); + if (!parsed.success) return respond(res, 'invalid_request'); + + try { + const record = await deps.getConversationMetadata(scope, parsed.data); + return record ? res.json(record) : respond(res, 'not_found'); + } catch (error) { + logger.error('[conversationMetadata] Get failed', getSafeErrorMetadata(error)); + return respond(res, 'internal_error'); + } + }; + + return { list, get, missing: (_req: ServerRequest, res: Response) => respond(res, 'not_found') }; +} diff --git a/packages/api/src/middleware/management.spec.ts b/packages/api/src/middleware/management.spec.ts index c0fed4c4fa..c0275bcbd3 100644 --- a/packages/api/src/middleware/management.spec.ts +++ b/packages/api/src/middleware/management.spec.ts @@ -478,3 +478,38 @@ describe('createAgentManagementAuth', () => { expect(deps.findUser).not.toHaveBeenCalled(); }); }); + +describe('conversation metadata admission', () => { + it('requires explicit conversation read access on the machine binding', async () => { + const deps = createDeps(); + const res = createResponse(); + const next = jest.fn(); + await createAgentManagementAuth(deps, { requireConversationRead: true })( + createRequest(), + res, + next, + ); + expect(res.status).toHaveBeenCalledWith(403); + expect(deps.findUser).not.toHaveBeenCalled(); + expect(next).not.toHaveBeenCalled(); + }); + + it('shares existing principal resolution for an opted-in machine binding', async () => { + const config = createConfig(); + const binding = config.endpoints?.agents?.managementApi?.auth?.clients[0]; + if (!binding) throw new Error('Expected the management fixture binding'); + binding.conversationRead = true; + const deps = createDeps({ getAppConfig: jest.fn().mockResolvedValue(config) }); + const res = createResponse(); + const next = jest.fn(); + await createAgentManagementAuth(deps, { requireConversationRead: true })( + createRequest(), + res, + next, + ); + expect(deps.getAppConfig).toHaveBeenCalledTimes(1); + expect(deps.findUser).toHaveBeenCalledWith({ _id: USER_ID, tenantId: TENANT_ID }); + expect(deps.isPrincipalActive).toHaveBeenCalledWith(USER_ID); + expect(next).toHaveBeenCalledTimes(1); + }); +}); diff --git a/packages/api/src/middleware/management.ts b/packages/api/src/middleware/management.ts index ce89599744..cb7ec49281 100644 --- a/packages/api/src/middleware/management.ts +++ b/packages/api/src/middleware/management.ts @@ -142,7 +142,10 @@ function continueWithPrincipal( tenantContextMiddleware(serverRequest, res, next); } -export function createAgentManagementAuth(deps: AgentManagementAuthDeps): RequestHandler { +export function createAgentManagementAuth( + deps: AgentManagementAuthDeps, + { requireConversationRead = false }: { requireConversationRead?: boolean } = {}, +): RequestHandler { const handler = async (req: Request, res: Response, next: NextFunction) => { try { const config = await deps.getAppConfig({ baseOnly: true }); @@ -187,6 +190,12 @@ export function createAgentManagementAuth(deps: AgentManagementAuthDeps): Reques return; } + if (requireConversationRead && binding.conversationRead !== true) { + res + .status(403) + .json({ error: { code: 'permission_denied', message: 'Permission denied' } }); + return; + } const principal = await resolvePrincipal(binding, deps); if (principal.status === 'missing') { logger.warn('[agentManagementAuth] Client binding has no matching tenant user'); diff --git a/packages/api/src/openapi/conversations.ts b/packages/api/src/openapi/conversations.ts new file mode 100644 index 0000000000..1ea51fb5bb --- /dev/null +++ b/packages/api/src/openapi/conversations.ts @@ -0,0 +1,89 @@ +import { z } from 'zod'; +import type { ZodTypeAny } from 'zod'; +import type { EndpointContract, ResponseContract } from './adapter'; +import { + accountDeletionResponseSchema, + errorMessageResponseSchema, + genericServerErrorContent, + jsonParseErrorSchema, + messageResponseSchema, +} from './errors'; +import { + conversationMetadataListSchema, + conversationMetadataQuery, + conversationMetadataSchema, +} from '../conversations/metadata'; +import { agentManagementErrorSchema } from '../agents/management'; + +export const conversationComponentSchemas: Record = { + ConversationMetadata: conversationMetadataSchema, + ConversationMetadataList: conversationMetadataListSchema, +}; + +const errors: ResponseContract[] = [ + { + status: 400, + description: 'Invalid request or malformed JSON body', + schema: z.union([agentManagementErrorSchema, jsonParseErrorSchema]), + }, + { status: 401, description: 'Authentication failed', schema: errorMessageResponseSchema }, + { + status: 403, + description: + 'The client is not enabled to read conversations, or the account cannot access the API', + schema: z.union([ + agentManagementErrorSchema, + errorMessageResponseSchema, + messageResponseSchema, + ]), + }, + { + status: 409, + description: 'The bound account is being deleted', + schema: accountDeletionResponseSchema, + }, + { + status: 500, + description: 'Internal server error', + schema: z.union([agentManagementErrorSchema, errorMessageResponseSchema]), + additionalContent: genericServerErrorContent, + }, +]; + +const common: Pick = { + method: 'get', + tags: ['Conversations'], + security: ['oidcBearer'], +}; +export const conversationContracts: EndpointContract[] = [ + { + ...common, + operationId: 'listConversationMetadata', + path: '/conversations', + summary: 'List the bound account’s conversation metadata', + description: + 'Requires conversationRead on the OIDC client binding. Archived conversations are included unless filtered.', + query: conversationMetadataQuery, + responses: [ + { + status: 200, + description: 'A page of conversation metadata', + schema: conversationMetadataListSchema, + }, + ...errors, + ], + }, + { + ...common, + operationId: 'getConversationMetadata', + path: '/conversations/{id}', + summary: 'Get the bound account’s conversation metadata', + description: 'Requires conversationRead on the OIDC client binding.', + pathParams: [{ name: 'id', description: 'The conversation ID' }], + responses: [ + { status: 200, description: 'The conversation metadata', schema: conversationMetadataSchema }, + { status: 404, description: 'Conversation not found', schema: agentManagementErrorSchema }, + ...errors, + ], + }, +]; diff --git a/packages/api/src/openapi/document.ts b/packages/api/src/openapi/document.ts index e314962e0a..556b069b24 100644 --- a/packages/api/src/openapi/document.ts +++ b/packages/api/src/openapi/document.ts @@ -4,14 +4,14 @@ import { buildOpenApiDocument } from './adapter'; /** Stable document version, independent of the package version, so the artifact does not churn. */ const DOCUMENT_VERSION = '0.1.0'; -/** Build the OpenAPI 3.1 document for the public agent and skill management endpoints. */ +/** Build the OpenAPI 3.1 document for the public agent, skill, and conversation management endpoints. */ export function buildAgentsOpenApiDocument(): Record { return buildOpenApiDocument({ info: { title: 'LibreChat Agents API', version: DOCUMENT_VERSION, description: - 'The public agent and skill management endpoints of the LibreChat Agents API. This API is in beta and may change.', + 'The public agent, skill, and conversation management endpoints of the LibreChat Agents API. This API is in beta and may change.', }, servers: [ { diff --git a/packages/api/src/openapi/registry.ts b/packages/api/src/openapi/registry.ts index c694aa995c..a1d2719434 100644 --- a/packages/api/src/openapi/registry.ts +++ b/packages/api/src/openapi/registry.ts @@ -6,10 +6,11 @@ import { messageResponseSchema, jsonParseErrorSchema, } from './errors'; +import { conversationComponentSchemas, conversationContracts } from './conversations'; import { agentComponentSchemas, agentContracts } from './agents'; import { skillComponentSchemas, skillContracts } from './skills'; -/** The agent and skill management endpoints authenticate with an OIDC access token (bearer). */ +/** The management endpoints authenticate with an OIDC access token (bearer). */ export const securitySchemes: Record = { oidcBearer: { type: 'http', @@ -22,6 +23,7 @@ export const securitySchemes: Record = { export const componentSchemas: Record = { ...agentComponentSchemas, ...skillComponentSchemas, + ...conversationComponentSchemas, ErrorMessage: errorMessageResponseSchema, AccountDeletionConflict: accountDeletionResponseSchema, MessageError: messageResponseSchema, @@ -52,4 +54,8 @@ export const componentSchemaOverrides: Record> = }, }; -export const contracts: EndpointContract[] = [...agentContracts, ...skillContracts]; +export const contracts: EndpointContract[] = [ + ...agentContracts, + ...skillContracts, + ...conversationContracts, +]; diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts index 032ed0e09e..ba772e3bbb 100644 --- a/packages/data-provider/src/config.ts +++ b/packages/data-provider/src/config.ts @@ -1189,6 +1189,7 @@ const managementClientBindingSchema = z .regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/, 'must be a valid tenant id') .refine((tenantId) => tenantId !== '__SYSTEM__', 'system tenant is not allowed'), enabled: z.boolean().default(true), + conversationRead: z.boolean().optional(), }) .strict(); diff --git a/packages/data-schemas/src/index.ts b/packages/data-schemas/src/index.ts index c43be8414b..9022863d90 100644 --- a/packages/data-schemas/src/index.ts +++ b/packages/data-schemas/src/index.ts @@ -216,3 +216,10 @@ export * from './postgres/mongo'; export { migrateMCPReservationIndex } from './migrations/mcpReservations'; export { repairAuthorizationDuplicates } from './migrations/authorization'; + +export type { + ConversationMetadata, + ConversationMetadataBoundary, + ConversationMetadataMethods, + ConversationMetadataScope, +} from './methods/conversationMetadata'; diff --git a/packages/data-schemas/src/methods/conversationMetadata.ts b/packages/data-schemas/src/methods/conversationMetadata.ts new file mode 100644 index 0000000000..9500db21d5 --- /dev/null +++ b/packages/data-schemas/src/methods/conversationMetadata.ts @@ -0,0 +1,147 @@ +import type { FilterQuery, Model, Types } from 'mongoose'; +import type { IConversation } from '~/types'; +import { buildRetentionVisibilityFilter } from '~/utils/retention'; + +export type ConversationMetadata = { + id: string; + title: string; + createdAt: string | null; + updatedAt: string | null; + agent_id: string | null; + tags: string[]; + isArchived: boolean; + endpoint: string | null; + model: string | null; +}; + +export type ConversationMetadataScope = { user: string; tenantId: string }; +export type ConversationMetadataBoundary = { updatedAt: string | null; id: string }; + +type ListOptions = { + limit: number; + boundary?: ConversationMetadataBoundary; + agent_id?: string; + tags?: string[]; + isArchived?: boolean; +}; + +type Row = Pick< + IConversation, + | 'conversationId' + | 'title' + | 'createdAt' + | 'updatedAt' + | 'agent_id' + | 'tags' + | 'isArchived' + | 'endpoint' + | 'model' +> & { _id: Types.ObjectId }; + +const fields = 'conversationId title createdAt updatedAt agent_id tags isArchived endpoint model'; + +function visible(scope: ConversationMetadataScope): FilterQuery { + return { + user: scope.user, + tenantId: scope.tenantId, + subagentThread: { $exists: false }, + ...buildRetentionVisibilityFilter(), + }; +} + +function timestamp(value?: Date): string | null { + return value instanceof Date && Number.isFinite(value.getTime()) ? value.toISOString() : null; +} + +function text(value: unknown): string | null { + return typeof value === 'string' ? value : null; +} + +function project(row: Row): ConversationMetadata { + if (typeof row.conversationId !== 'string') throw new Error('Invalid stored conversation ID'); + return { + id: row.conversationId, + title: text(row.title) ?? '', + createdAt: timestamp(row.createdAt), + updatedAt: timestamp(row.updatedAt), + agent_id: text(row.agent_id), + tags: Array.isArray(row.tags) ? row.tags.filter((tag) => typeof tag === 'string') : [], + isArchived: row.isArchived === true, + endpoint: text(row.endpoint), + model: text(row.model), + }; +} + +export type ConversationMetadataMethods = { + getConversationMetadata: ( + scope: ConversationMetadataScope, + id: string, + ) => Promise; + listConversationMetadata: ( + scope: ConversationMetadataScope, + options: ListOptions, + ) => Promise<{ data: ConversationMetadata[]; next: ConversationMetadataBoundary | null }>; +}; + +export function createConversationMetadataMethods( + mongoose: typeof import('mongoose'), +): ConversationMetadataMethods { + async function getConversationMetadata(scope: ConversationMetadataScope, id: string) { + const Conversation = mongoose.models.Conversation as Model; + const row = await Conversation.findOne({ ...visible(scope), conversationId: id }) + .select(fields) + .lean(); + return row ? project(row) : null; + } + + async function listConversationMetadata(scope: ConversationMetadataScope, options: ListOptions) { + const Conversation = mongoose.models.Conversation as Model; + const { boundary, agent_id, tags, isArchived } = options; + const limit = Math.max(1, Math.min(100, Math.trunc(options.limit) || 1)); + const base = { + ...visible(scope), + ...(agent_id != null && { agent_id }), + ...(tags?.length && { tags: { $in: tags } }), + ...(isArchived != null && { isArchived: isArchived ? true : { $ne: true } }), + }; + const page = (seek: FilterQuery, size: number) => + Conversation.find({ $and: [base, seek] }) + .select(fields) + .sort({ updatedAt: -1, _id: -1 }) + .limit(size) + .lean(); + + let rows: Row[]; + if (boundary == null) { + rows = await page({}, limit + 1); + } else { + const id = new mongoose.Types.ObjectId(boundary.id); + if (boundary.updatedAt == null) { + rows = await page({ updatedAt: null, _id: { $lt: id } }, limit + 1); + } else { + const date = new Date(boundary.updatedAt); + rows = await page( + { + updatedAt: { $lte: date }, + $or: [{ updatedAt: { $lt: date } }, { updatedAt: date, _id: { $lt: id } }], + }, + limit + 1, + ); + // BSON date comparison does not include the null/missing tail. Read it only if + // the dated group cannot fill the page. + if (rows.length <= limit) { + rows.push(...(await page({ updatedAt: null }, limit + 1 - rows.length))); + } + } + } + + const more = rows.length > limit; + if (more) rows.pop(); + const last = rows[rows.length - 1]; + const next = + more && last ? { updatedAt: timestamp(last.updatedAt), id: String(last._id) } : null; + return { data: rows.map(project), next }; + } + + return { getConversationMetadata, listConversationMetadata }; +} diff --git a/packages/data-schemas/src/methods/index.ts b/packages/data-schemas/src/methods/index.ts index 2dbf56acb0..29ff243638 100644 --- a/packages/data-schemas/src/methods/index.ts +++ b/packages/data-schemas/src/methods/index.ts @@ -161,6 +161,8 @@ import { type ParentSubagentThreadRecord, } from './conversation'; import { createChatProjectMethods, type ChatProjectMethods } from './chatProject'; +import { createConversationMetadataMethods } from './conversationMetadata'; +import type { ConversationMetadataMethods } from './conversationMetadata'; export type { AssignConversationToProjectResult, ChatProjectSortBy, @@ -356,6 +358,7 @@ export type AllMethods = PermissionPrincipalStorage & ConversationImportMethods & MessageMethods & ConversationMethods & + ConversationMetadataMethods & ChatProjectMethods & TxMethods & TransactionMethods & @@ -612,6 +615,7 @@ export function createMethods( ...createConversationImportMethods(mongoose), ...messageMethods, ...conversationMethods, + ...createConversationMetadataMethods(mongoose), ...createChatProjectMethods(mongoose), /* Tier 3 */ ...txMethods,