Repository navigation
🗺️ feat: Expose Conversation Management in Agents API - #15682
dustinhealy wants to merge 30 commits into
Conversation
|
@codex review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
@codex review |
There was a problem hiding this comment.
🟡 Changes recommended
Some cleanup paths still omit explicit tenant scoping (notably tool-call/message deletion call sites/types), which risks widening destructive operations beyond the intended tenant boundary.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds a tenant- and owner-scoped “conversation management” surface for external applications alongside the Agents API, reusing existing conversation metadata, deletion, import, and checkpoint-cleanup infrastructure while introducing explicit resource projections and cursor pagination.
Changes:
- Added conversation list/detail and paginated message retrieval with strict request/cursor validation and public projections.
- Implemented tenant-scoped deletion, checkpoint cleanup scoping (namespace-based), and import hardening/compensation paths.
- Extended data-schemas methods/indexes to support explicit tenant boundaries for resource access, tagging, and project stats updates.
File summaries
| File | Description |
|---|---|
| packages/data-schemas/src/schema/convo.ts | Adds tenant+user updatedAt index for resource listing. |
| packages/data-schemas/src/methods/toolCall.ts | Adds optional explicit tenant boundary to tool-call deletion. |
| packages/data-schemas/src/methods/index.ts | Registers new resource/import method factories. |
| packages/data-schemas/src/methods/import.ts | Adds import cleanup helpers for generated IDs. |
| packages/data-schemas/src/methods/import.spec.ts | Tests import cleanup scoping by owner/tenant. |
| packages/data-schemas/src/methods/conversationTag.ts | Adds tenant-aware tag updates/decrements. |
| packages/data-schemas/src/methods/conversationResource.ts | Adds public conversation/message resource queries + pagination. |
| packages/data-schemas/src/methods/conversationResource.deletion.spec.ts | Exercises tenant-boundary delete recovery and tag effects. |
| packages/data-schemas/src/methods/conversation.ts | Adds explicit tenant boundary support to save/delete flows. |
| packages/data-schemas/src/methods/chatProject.ts | Adds tenant-aware project stats and visibility filters. |
| packages/data-provider/src/config.ts | Extends agents endpoint schema with conversationApi auth mode. |
| packages/api/src/shared-links/service.ts | Adds tenant-aware shared-link cleanup by conversation. |
| packages/api/src/conversations/schema.ts | Adds Zod schemas, cursor encoding/decoding, projections, error mapping. |
| packages/api/src/conversations/schema.spec.ts | Tests request validation, cursor binding, and content projection stripping. |
| packages/api/src/conversations/principals.database.spec.ts | Verifies remote vs management principal composition and tenant scoping. |
| packages/api/src/conversations/metadata.ts | Centralizes title/archive/tag metadata updates with tenant boundary. |
| packages/api/src/conversations/management.ts | Implements conversation management handlers (list/get/messages/update/delete). |
| packages/api/src/conversations/management.database.spec.ts | DB-backed handler tests for visibility, pagination, projection, updates. |
| packages/api/src/conversations/index.ts | Exports new conversation management modules. |
| packages/api/src/conversations/import.ts | Adds strict LibreChat import parsing + traversal/ownership safeguards + write compensation. |
| packages/api/src/conversations/import.spec.ts | Tests strict import validation, ownership stripping, limits, compensation. |
| packages/api/src/conversations/http.ts | Adds import/update HTTP helpers with consistent error mapping. |
| packages/api/src/conversations/http.spec.ts | Tests import handler validation, permission gating, and cleanup behavior. |
| packages/api/src/conversations/deletion.ts | Adds deletion service coordinating generation drain, checkpoint cleanup, and dependent cleanup. |
| packages/api/src/conversations/auth.ts | Selects conversation auth policy (remote vs management) without fallback. |
| packages/api/src/conversations/auth.spec.ts | Tests auth selector mode handling and failure-closed behavior. |
| packages/api/src/agents/checkpointer.ts | Adds owned-scope receipts + bulk deletion by (thread_id, namespace). |
| packages/api/src/agents/checkpointer.integration.spec.ts | Ensures bulk deletion preserves foreign/legacy scopes on collisions. |
| api/server/utils/import/importConversations.js | Switches legacy import runner to shared import operation. |
| api/server/utils/import/importConversations.database.spec.js | DB regression coverage for browser import hardening. |
| api/server/utils/import/importBatchBuilder.spec.js | Adds compensation + size-limit regressions for import writes. |
| api/server/utils/import/importBatchBuilder.js | Adds size preflight + ordered writes + scoped cleanup on failure. |
| api/server/utils/import/conversationManagement.database.spec.js | End-to-end DB compatibility tests for strict/legacy import modes. |
| api/server/routes/tags.js | Reuses shared tag-metadata updater (tenant-aware). |
| api/server/routes/files/multer.spec.js | Adds regressions for malformed filenames and directory error handling. |
| api/server/routes/files/multer.js | Hardens Multer storage against URI decode and mkdir failures. |
| api/server/routes/convos.js | Refactors deletion/title/archive to shared services + checkpoint scope cleanup. |
| api/server/routes/agents/middleware.js | Exposes conversation management auth selector middleware. |
| api/server/routes/agents/index.js | Mounts new /agents/v1/conversations router. |
| api/server/routes/agents/conversations.js | Implements Agents API conversation management routes + strict import path. |
| api/server/routes/agents/tests/streamTenant.spec.js | Updates router mocks to include conversations surface. |
| api/server/routes/agents/tests/idempotencyLimiter.spec.js | Ensures conversations route precedence over catch-all execution router. |
| api/server/routes/agents/tests/abort.spec.js | Updates router mocks to include conversations surface. |
| api/server/routes/tests/convos.spec.js | Updates deletion tests for checkpoint-scope receipts + tenant-bound cleanup. |
| api/server/routes/test-utils/convos-route-mocks.js | Adds checkpoint-scope mock persistence + loads shared deletion helpers. |
| api/server/controllers/UserController.spec.js | Updates account deletion tests for owned-scope checkpoint cleanup + abort fencing. |
| api/server/controllers/UserController.js | Tightens account deletion generation aborting and checkpoint cleanup scoping. |
Review details
- Files reviewed: 48/48 changed files
- Comments generated: 3
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| throw new Error('Agent generations could not be confirmed stopped'); | ||
| } | ||
|
|
||
| await db.deleteMessages({ user: user.id }); |
There was a problem hiding this comment.
This cleanup predates this feature and belongs to whole-account deletion, which intentionally removes all records for the deleted user. The checkpoint prerequisite only scopes generation discovery/pruning and does not change the existing account-purge semantics, so I’m leaving this line unchanged.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: effffc1229
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f14039bafa
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 864f94ba75
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
864f94b to
d4a18ff
Compare
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 93679f23ed
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 44015219a8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 692fa5cdef
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c760e5fd5d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 68bd10e60e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3713445b2d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d9ed373fe1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d191012e21
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4b61d40b02
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2e31e0daf3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| { $set: { renameTo: newTag, reservedNames: [oldTag, newTag] } }, | ||
| ); | ||
| if (!reserved.matchedCount) throw new Error('Tag rename conflicted'); | ||
| await Conversation.updateMany({ ...scope, tags: oldTag }, { $set: { 'tags.$': newTag } }); |
There was a problem hiding this comment.
Fence membership writes during tag renames
When /tags/convo/:conversationId or the management PATCH writes oldTag after this updateMany has passed that conversation but before the catalog row is finalized as newTag, the completed rename leaves the conversation carrying the obsolete name. The reservedNames index only protects catalog rows, while both membership-writing paths can still update Conversation.tags during the reservation; coordinate those writes with renameTo or perform a guarded final sweep before committing the rename.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Confirmed on 2e31e0d. The catalog reservation does not fence Conversation.tags writes; the same boundary also includes create-and-add and bulk import/fork, beyond the two routes identified here. A pre-write renameTo lookup or extra sweep alone still has a check/write race. I have stopped resubmission and completed the architectural reassessment. The smaller coherent correction is a transactional catalog/membership boundary shared by all tag-bearing writers, but that would require explicitly rejecting rename on standalone MongoDB. Preserving standalone rename support instead needs a broader stable-tag-identity design. Awaiting that compatibility decision before implementation. Leaving this finding open; no fix or clean-review claim yet.
There was a problem hiding this comment.
Follow-up with controlled baseline evidence: I ran the actual conversationTag methods from dev 25fcd12 and PR head 2e31e0d against the same registered models in isolated standalone MongoDB. For each, I paused after the Conversation.updateMany rename sweep, executed that revision's real browser updateTagsForConversation(..., ['old']), then let catalog finalization complete. Both calls succeeded and both versions ended with Conversation.tags=['old'] and catalog tag='new'. The base implementation already has the same sweep-before-catalog sequence. This establishes that the browser race is inherited; it is not a regression caused by the new reservation fields. The new management route is another writer and still needs to be assessed against the intended existing contract. This was a comparison of the committed method implementations, not a full base-branch integration suite.
I am revising the earlier implication that fixing this PR necessarily requires transactional renames or a membership migration. Neither should be imposed merely to close an inherited finding. A complete fix is a separate consistency-design decision; an extra sweep or pre-write renameTo check alone would retain a race. Leaving the issue open rather than claiming it fixed, and asking that its inherited nature be considered when determining whether it blocks this PR. No production changes have been pushed from this investigation.
There was a problem hiding this comment.
The shared tag changes have been extracted into independent draft #15748. Commit 075fbde restores this PR's legacy rename/reorder/schema behavior and retains only the conversation-management integration with existing tags. The inherited rename race is still tracked in the draft; relocation is not a fix, so I am leaving this thread open. The independent draft will replace name-based membership with existing catalog IDs and include its migration. Validation of the narrowed API: 284 API/Assistants tests, 289 database/DocumentDB tests and 580 browser/import/agent tests across focused runs and reruns; package builds, API/schema typechecks, scoped import/static checks and Lighthouse passed.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 075fbde70f
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@codex review |
|
Codex Review: Didn't find any major issues. Keep it up! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
|
@codex review |
|
Codex Review: Didn't find any major issues. Can't wait for the next one! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
|
@codex review |
|
Codex Review: Didn't find any major issues. Chef's kiss. Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
|
This would be great for my use case |
Summary
External applications can run agents but also need to manage their conversations. This adds
/api/agents/v1/conversationsfor listing conversations and messages, reading details, updating title/tags/archive state, deleting conversations, and importing LibreChat JSON exports.Authentication follows the configured remote-user or management-client policy. Queries and mutations enforce user/tenant ownership and exclude internal subagent and retention-hidden conversations. Browser and API entry points share title/archive, tag mutation, import, and deletion services. Title and archive state can be changed together. A PATCH containing
tagsmust contain onlytags; mixed requests return 400 before mutation. Tag changes use the existing shared operation, without a separate API count-reconciliation protocol.Imported transcripts discard live provider bindings and private continuation metadata. Imported Assistants conversations create a fresh provider thread with bounded context from the selected branch on the first follow-up, while retaining the complete imported history locally. Balance admission precedes provider writes.
Shared tag redesign and migration are tracked independently in draft #15748. This PR does not depend on it and does not change legacy tag renaming, reordering, or project-statistics reads.
Documentation: LibreChat-AI/docs#760
Change Type
Testing
After separating shared remediation and integrating current
dev:A CI-only follow-up corrects an existing steering test that required a transient pending bubble after the interrupt could already be applied. The full escalation suite passed 12 runs (three repetitions); application code is unchanged by that follow-up.
The latest API boundary replacement additionally passed 254 conversation API tests and 210 conversation/tag database tests across focused runs and fixture reruns, schema/API builds and type checks, scoped import/static checks, and Lighthouse (1.8 minutes).
tsc --noEmitpassed.Representative reproduction commands:
Coverage includes owner/tenant isolation, retention admission, atomic title/archive updates, separate tag PATCH validation, strict import validation, public message projection, export compatibility, fresh Assistants continuation, and retryable deletion/checkpoint cleanup. The full monorepo suite has not been run locally. Codex review and CI verification remain in progress.
Test Configuration:
npm ci.mongodb-memory-serverfor database tests.Checklist