📰 feat: Expose Conversation Metadata Through the Agents API (#18490)

* ✨ feat: Read Conversation Metadata Through the Agents API

* fix: Preserve Exact Conversation Tag Filters
This commit is contained in:
Dustin Healy 2026-11-19 07:25:45 -08:00 • committed by GitHub
parent 2d81c000e5
commit 9668dee1f2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
19 changed files with 1121 additions and 8 deletions

View file

@ -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' }));

View file

@ -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;

View file

@ -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)

View file

@ -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,
};

View file

@ -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.

View file

@ -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. */

View file

@ -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<string, string>) => {
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();
}
}
});

View file

@ -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": {

View file

@ -11,3 +11,4 @@ export * from './retention';
export * from './save';
export * from './title';
export * from './rename';
export * from './metadata';

View file

@ -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<Query, unknown> = 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<ConversationMetadata> = 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<List> = 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<Query, 'limit' | 'cursor'>;
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<Response>;
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') };
}

View file

@ -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);
});
});

View file

@ -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');

View file

@ -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<string, ZodTypeAny> = {
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<EndpointContract, 'method' | 'tags' | 'security'> = {
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,
],
},
];

View file

@ -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<string, unknown> {
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: [
{

View file

@ -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<string, SecurityScheme> = {
oidcBearer: {
type: 'http',
@ -22,6 +23,7 @@ export const securitySchemes: Record<string, SecurityScheme> = {
export const componentSchemas: Record<string, ZodTypeAny> = {
...agentComponentSchemas,
...skillComponentSchemas,
...conversationComponentSchemas,
ErrorMessage: errorMessageResponseSchema,
AccountDeletionConflict: accountDeletionResponseSchema,
MessageError: messageResponseSchema,
@ -52,4 +54,8 @@ export const componentSchemaOverrides: Record<string, Record<string, unknown>> =
},
};
export const contracts: EndpointContract[] = [...agentContracts, ...skillContracts];
export const contracts: EndpointContract[] = [
...agentContracts,
...skillContracts,
...conversationContracts,
];

View file

@ -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();

View file

@ -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';

View file

@ -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<IConversation> {
return {
user: scope.user,
tenantId: scope.tenantId,
subagentThread: { $exists: false },
...buildRetentionVisibilityFilter<IConversation>(),
};
}
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<ConversationMetadata | null>;
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<IConversation>;
const row = await Conversation.findOne({ ...visible(scope), conversationId: id })
.select(fields)
.lean<Row>();
return row ? project(row) : null;
}
async function listConversationMetadata(scope: ConversationMetadataScope, options: ListOptions) {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
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<IConversation>, size: number) =>
Conversation.find({ $and: [base, seek] })
.select(fields)
.sort({ updatedAt: -1, _id: -1 })
.limit(size)
.lean<Row[]>();
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 };
}

View file

@ -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,