* 🪜 fix: Base-First Config Precedence, Profile Lifecycle and Role Renames That Keep Their Profile
Config documents merge in one total order (`compareConfigPrecedence`): Base (`role` /
`__base__`) first whatever its priority, then ascending priority, then role < group < user,
then document `_id`. The merge, `getApplicableConfigs` and `listAllConfigs` all use it, so a
tie no longer goes to the newest document whatever its type, and Base no longer outranks a
profile through its priority. A profile that writes fields of a librechat.yaml MCP server
therefore undoes a Base hide of that server for its principals. A write that creates a document
without a priority gives it its principal type's default (role 10, group 20, user 100, Base 0),
and a write that omits the priority keeps the stored one, so a broad PUT no longer resets a
profile to 10. Langfuse writes no longer pass a priority.
Profile writes (PUT, PATCH `/fields`, POST `/changes`) validate on librechat.yaml with the
active Base document resolved over it (`resolveRawConfig`, the fold the merge itself runs), so
a role write that is valid where it lands is accepted and one the merge would strip is refused.
Base still validates on librechat.yaml alone, an inactive Base is ignored, and `/changes` still
judges what librechat.yaml itself defines on the raw YAML.
`PATCH /api/admin/config/:principalType/:principalId/priority { priority, expectedRevision? }`
sets only the priority, for broad `manage:configs`, keeping overrides, tombstones and
`isActive`; it is audited as `operation: 'priority'`. A write that would create a principal's
first document (PUT, PATCH `/fields`, POST `/fields/tombstone`, POST `/changes` including a dry
run or a priority-only batch) answers 404 `PRINCIPAL_NOT_FOUND` unless the role (exact name),
group or user (lowercase ObjectId) exists in the caller's tenant partition, or at platform
level outside a tenant (`principalExists`). Each route checks inside its compare-and-swap
write, against the document the write replaces; the tombstone route now plans its write like
the others, so `AdminConfigDeps` no longer takes `tombstoneConfigField`. A PUT with
`expectedRevision: 'absent'` creates the profile even when it carries no overrides.
Renaming a role moves its config profile, system grants and ACL entries to the new name in the
caller's tenant partition. The profile moves through the store contract (`movePrincipal`: a
create-only copy, then removal at the copied revision). A profile already at the new name
answers 409 `ROLE_CONFIG_CONFLICT`, and any failed step rolls back the users, the role document
and every move (500 `ROLE_RENAME_FAILED`). Profiles, grants and ACL entries that renames made
before this change left at an old name are neither moved nor removed, and a role created under
that name still picks them up. The Base principal id is a reserved role name (400
`ROLE_NAME_RESERVED`), and a legacy role by that name never moves or deletes Base. The admin
config meta reports `deterministicPrecedence`, `priorityRoute`, `principalCheck` and
`roleRenameMovesProfile`.
* 🧪 test: Give the E2E Reload Sentinel a Role of Its Own
Admin config writes now answer 404 PRINCIPAL_NOT_FOUND for a principal that does not exist, so
the content-filter helpers' reload sentinel (a made-up user id) could no longer write and every
spec that reloads librechat.yaml failed. The sentinel is now a role the helper creates once (409
when it already exists) and deletes after its profile in cleanup; no user is a member, so its
empty profile changes no one's config.
* 🛟 fix: Keep a Moved Profile Whose Removal Cannot Be Confirmed, Validate on the Caller's Base and Restore Rolled-Back Descriptions
- `movePrincipal` no longer treats a failed read-back of the source, after its removal
failed, as the source still being there. It keeps the copy, which may be the only one
left, and rethrows the removal's failure instead of deleting the copy.
- Profile writes read the Base validation floor from the caller's tenant partition, so a
caller without a tenant validates on the platform-level Base and never on a tenant's.
- A role rename that rolls back gives a role stored without a description the schema
default back, instead of a `$set` of `undefined` that kept the new description.
* 🧭 fix: Scope Profile Priority Changes to the Caller's Tenant Partition
`setConfigPriority`, behind PATCH `/api/admin/config/:principalType/:principalId/priority`,
read and wrote through the unpartitioned config store. A platform-level admin without a
tenant runs in the default non-strict context, where the tenant-isolation plugin adds no
predicate, so the route could reorder a tenant's profile for the same principal, and answer
with it, when no platform-level profile existed.
It now runs on the partitioned operations that the role rename and the partitioned
`findConfigByPrincipal` use. The read is limited to the caller's partition: that tenant's
document, or without a tenant only a platform-level one (no tenant, `null` or `''`). The
write is pinned to the `_id` of the document that read returned. A tenantless caller
therefore gets 404 `CONFIG_NOT_FOUND` for a profile only a tenant holds. An
`expectedRevision` naming such a profile gets a revision conflict and changes nothing.
Tests: `config.spec.ts` (data-schemas) adds "setConfigPriority in the caller tenant
partition". It covers the platform profile changing alone, a profile that only a tenant holds
being neither changed nor returned, and only the active tenant's profile changing inside a
tenant. The tenant helpers are now shared with the rename suite.
`config.precedence.integration.spec.ts` adds the same check through the handler. With the old
wiring, a tenantless PATCH of a profile only tenant-a holds answers 200 and moves tenant-a's
profile to 40. With the fix it answers 404 and tenant-a keeps 10.
* 🧷 fix: Roll Back Only What a Rename Changed and Validate Profile Writes on the Base They Land Over
- Grant moves report what they changed (re-keyed grants, and superseded grants whose removal
was confirmed); the undo re-keys only grants still at the new name and re-creates a
superseded grant only while the new name still holds the grant that superseded it, so a
grant revoked during a rename is never resurrected.
- The Mongoose binding settles a create whose acknowledgement was lost by the `_id` it chose
(found at version 1: committed, returned), as the store contract now requires; a profile
move whose copy committed finishes instead of leaving an orphan copy. The memory engine and
the conformance suite cover it, plus a copy that cannot be withdrawn being logged.
- A rename rollback moves back only the profile it moved (by identity, edits included), puts
back only members still on the new name, and reverts the description only while it is still
the one the rename set.
- PUT, PATCH /fields and POST /changes read Base beside the profile on every attempt and read
it again once the write commits; a write that Base changed under is judged on that Base and
withdrawn (only at the revision it wrote) when it fails there.
- The priority route rereads a lost race's current revision in the caller's tenant partition.
* 🔐 fix: Apply Base Config Overrides Before Sign-In and Refuse Script Policy Links
Sign-in decisions made before the user is known now read librechat.yaml plus the `__base__`
override of the request's tenant, or of the deployment outside a tenant, and fail closed
(`resolvePreAuthAppConfig`). Registration, the first phase of password reset and the first
email-domain check of the LDAP, OpenID, SAML and social strategies use it. The second check
applies the account's role overrides with or without a tenant, and a new account is checked
against the role it will be created with before anything is inserted. OpenID checks again when
the admin claim or role sync changes the role. Password reset issues no link when the
account's config cannot be read.
The signed-out `GET /api/config` serves Base `registration.socialLogins` and the pre-login
interface fields (`resolvePreLoginAppConfig`), falling back to librechat.yaml when overrides
cannot be read. `turnstile` becomes a base-only section, so Turnstile comes only from
librechat.yaml.
Config reads that merge documents stay in one tenant partition (`tenantPartition`, Mongoose
binding `tenantPartitionFilter`): the active tenant's documents, or the tenantless ones outside
a tenant. The config store's Mongoose binding reads, writes, lists and restores role documents,
`__base__` included, in that partition, and its `listActive` draws every document from it;
group and user documents stay addressed by id. Only a `list` with `acrossTenants` reads every
partition, which `listConfigTombstones` uses so the startup MCP tombstone report still names
each tenant's documents. The tenant-isolation conformance suite gains single-partition cases.
Privacy policy and terms of service `externalUrl` must be http(s), `mailto:`, `tel:`, relative
or blank (`isSafeLinkUrl`). Admin writes of another scheme are refused, a librechat.yaml link is
dropped with a warning at load, a stored one is dropped at merge, and every payload and the
client remove one that reaches them. The admin config meta reports
`features.preAuthBaseOverrides: true`.
* 🧪 test: Layer a Required-Field Override Through interface.currency Instead of Turnstile
Turnstile is set in librechat.yaml only now, so profile overrides of it are skipped and the
layering scenario could no longer see a role's Turnstile options completed by a user's site key.
The scenario now layers `interface.currency`, whose `code` and `rate` are both required: the role
stores only the rate, the user only the code, and /api/config serves both.
* 🛂 fix: Admit a First OpenID Login Under Its Claimed Role Before Creating the Account
The admin-role claim and role sync are now decided before a first-login OpenID account is created, and createUserOnce admits the email under that role's config, read in parallel with the USER role's, before inserting anything. A login the claimed role refuses creates no account and no start balance. Admitted logins are unchanged: the account is still created as USER (now explicitly), moved into the claimed role, re-checked and audited as before, with the claims decided once. An account a concurrent first login created gets the claims decided again for its own role and tenant.
* 🏷️ fix: Resolve endpoints.all Title Settings per Field and Fold Ollama Endpoint Names
Conversation titles picked `endpoints.all` as a whole block, so any `all`
block (even one holding only streamRate, headers or activity label keys)
hid every per-endpoint titleConvo, titleModel, titleMethod, titleEndpoint
and title prompt. `resolveTitleConfig` resolves each field from `all`,
then the named endpoint, then the custom endpoint entry, keeping
titleEndpoint and titleModel as one choice from the first layer that sets
either.
Config overrides merged `endpoints.custom` by exact name while the runtime
serves names through `normalizeEndpointName`, so an override `ollama`
survived beside the YAML `Ollama` and split the endpoint between two
baseURLs and keys. The merge key now folds the same way (the YAML spelling
is kept), merge-key issues, issue attribution and secret preservation use
the same identity, and the effective config serves
`modelSpecs.addedEndpoints`, `modelSpecs.list[].preset.endpoint` and
`endpoints.agents.allowedProviders` in served names without repeats.
A stored document that already names one endpoint in two spellings is
combined at merge in document order, so requests keep the host and key
of the first item instead of moving to the YAML entry; omit-to-keep
secret preservation reads the same combined entry. A new write naming
both spellings is rejected as a duplicate.
An agent saved as `Ollama` now runs on the served `ollama`: the model
catalog lookup (`resolveModelCatalogKey`) falls back to the served name,
and `initializeAgent` folds the provider before the allowedProviders
check and provider setup.
* 🏷️ fix: Report Per-Field endpoints.all Title Resolution in the Admin Config Meta
resolveTitleConfig resolves endpoints.all title settings one field at a time, so GET /api/admin/config/meta now reports rules.titleResolution as 'field'. meta.spec ties the reported value to resolveTitleConfig: with endpoints.all = { streamRate: 1 } and openAI.titleModel = 'x', the rule is 'field' exactly when the endpoint's titleModel survives.
* 🧪 test: Expect Segments on the Folded duplicate_merge_key Write Issue
Admin config write issues carry segments since #17322; the folded Ollama/ollama duplicate test now asserts them.
* 🏷️ fix: Match Folded Custom Endpoint Names in Admin Config Change Ops
The changes endpoint from dev matched entry keys exactly, while the config
merge, merge-key issues and secret preservation fold `Ollama`/`ollama` into
one custom endpoint. An upsertEntry `ollama` over a stored `Ollama` copied the
stored key, appended a second entry and failed as duplicate_merge_key;
removeEntry `ollama` left a stored `Ollama` in place; a rename onto another
spelling passed entry_exists; and the librechat.yaml entry check missed
`ollama` against the YAML `Ollama`.
- data-schemas: `getConfigEntryIdentity` folds a key by its override path;
`getConfigEntryMatcher` backs upsertEntry, removeEntry, rename, written-path
attribution and the stored-counterpart lookup; issue locations use the same
identity. A rename of an entry stored in two spellings moves the one entry
the runtime merge combines (`combineFoldedConfigEntries`).
- api: the YAML-entry rename guard and the per-batch duplicate check compare
entries by the same identity.
- Tests: unit coverage for each op across spellings, and handler integration
tests against MongoDB for upsert with secret preservation (single and
two-spelling documents), removal, entry_exists, inherited_entry and
duplicate changes in one batch.
* 🛡️ fix: Reject Unknown Admin Config Sections and Scope Write Responses to Read Access
- Admin config writes (PUT, PATCH, tombstone) now accept only top-level sections that configSchema defines. PUT reports `unknown_section` issues under CONFIG_OVERRIDE_INVALID; PATCH and tombstone return 400 UNKNOWN_SECTION without echoing the path. This closes override writes to AppService runtime state (`paths`, the raw-YAML `config`, `availableTools`, and the `interfaceConfig`/`turnstileConfig`/`mcpConfig` aliases).
- mergeConfigOverrides ignores stored override keys and tombstones outside configSchema, with one warning per document, so data an older server stored is neutralized without a migration. DELETE /fields still removes such stored entries, which is the only per-field way to clear a legacy tombstone.
- Write responses (PUT, PATCH, tombstone, field delete, toggle) are redacted and then filtered to the sections the caller can read plus the sections the write managed; broad managers see the whole document as before.
- Admin reads of the resolved config redact literal Azure group keys (merged `groups`, `groupMap`, raw YAML copy) and the Vertex `serviceKeyFile` (`vertex` and `vertexConfig`), keeping `${ENV}` and `user_provided` references readable. Write behaviour for these paths is unchanged.
- The experimental cluster entry boots from librechat.yaml only (`baseOnly`), like server/index.js, so `__base__` overrides no longer reach file storage, skill sync, skill deletion or the expired-file sweep at boot.
* 🛡️ fix: Resolve Admin Config Write Read Access Before Committing
- Section-scoped writes (PATCH, tombstone, field delete) resolve the caller's readable sections before the mutation, alongside the pre-write reads they already make, instead of after the write and audit have committed. The batched lookup covers every `configSchema` section, so it no longer waits on the stored document.
- A failed grant lookup now fails the request before anything is stored, so a 500 never follows a committed write and invites a duplicate retry. Response filtering after the write is pure.
- Assign-only scope creation and toggles match only empty documents (`expectEmpty`), so their responses skip the lookup entirely.
* 🚩 feat: Report the Section Allowlist and Read-Filtered Write Responses in Config Meta
- `GET /api/admin/config/meta` now reports `sectionAllowlist: true` and `readFilteredWriteResponses: true`, which this branch implements (BE-17, BE-18).
- The meta.spec probes check each flag against the handlers rather than the validator alone: PUT answers `unknown_section` with `segments`, PATCH and tombstone answer `UNKNOWN_SECTION`, a stored `paths` override and tombstone are ignored at merge, and PATCH, tombstone and field delete responses omit a section the caller cannot read.
- A dotted top-level key is reported once, as `dotted_key`, instead of also as `unknown_section`.
- The unknown-section handler and integration tests expect the `segments` that issues carry since #17322.
* 🧪 test: Type the Tombstoned Meta Probe Document Through storedConfig
* 🧪 test: Align Allowlist and Filtered-Response Specs with Version-Checked Web Search Writes
dev's version-checked webSearch writes pass a session and precondition to
patchConfigFields/unsetConfigField, read the stored document before removing a
binding path, and have getBaseConfig load the librechat.yaml config beside a
merged read. The field delete spec now stores the document it removes from and
asserts the precondition alongside the filtered response.
* 🧪 test: Pin Section-Manager Write Responses to What a Read Shows
The grant layer resolves read:configs:<section> from the same section's
manage:configs:<section> (getParentCapabilities, #14472), so a section
manager's GET already returns the whole managed section. The comment on
resolveWriteReadAccess said the opposite; it now states the model.
A new integration spec runs the handlers over real SystemGrant documents
through generateCapabilityCheck: a caller holding only
manage:configs:endpoints patches one endpoints field, and its write
response equals what GET returns it, other endpoint overrides and
tombstones included, with memory and webSearch left out of both.
* 🧪 test: Mark Config-Service Generation Tests With a Schema Section
The base-config generation tests that came with the portable config store marked each base
config and override layer with an `x` key, which no section in `configSchema` defines. This
branch dropped `x` from the spec's `TestConfig` and ignores such keys when overrides are merged,
so those tests no longer typechecked, and the override-layer ones would stop seeing the layer
they read. They now mark layers with the `version` section, as this branch's other service tests
do.
* 🧪 test: Expect the yamlMcpHide Flag Beside the Section Allowlist Flags
#17327 publishes features.yamlMcpHide on dev, so the exact feature list this PR asserts in
meta.spec now includes it.
* 🙈 feat: Let Config Profiles Hide librechat.yaml MCP Servers and Remove Their Fields
Config profiles are the `__base__`, role, group and user documents written through `/api/admin/config`. A profile can tombstone `mcpServers.<name>`, and the merge then removes that server from the principal's resolved `mcpConfig`.
* 🛡️ fix: Apply MCP Hiding to Server Instructions, Failed Removals and the Startup Audit
- Server instructions bound for the model now leave out librechat.yaml servers hidden from the acting user, including one a model spec pins. `applyContextToAgent` passes the request user through `formatInstructionsForContext`, which drops the user's hidden set from the user-less catalog it reads.
- A config-tier candidate that removes a librechat.yaml value (a field, or a key of a record such as `headers`) and fails inspection now stands as a failed config-source entry instead of falling back to the librechat.yaml base that still carries the removed value. A failed change that removes nothing still falls back, and an entry with no transport (fields written over a hidden server) keeps the documented librechat.yaml fallback.
- The startup tombstone report reads every tenant's profiles in the system tenant scope, so it also runs from entry points without an outer system scope under strict tenant isolation, and names each profile's tenant.
* 🗂️ fix: Project the Startup MCP Tombstone Report Query and Run It Alongside Connections
* 🔑 fix: Keep Removed OAuth Headers Out of the MCP OAuth Callback
* 📝 docs: Note That Removed OAuth Headers Stay Out of MCP Sign-In
* 🔐 fix: Recheck the MCP OAuth Flow's Server Before Initiation Redirects
OAuth initiation redirected to a flow's stored authorization URL, or started
a new authorization from the flow's stored server URL, without resolving the
server again, so a principal whose profile hid the server after the flow was
created could still be sent to its authorization endpoint. The callback's
active-server check and its OAuth header fallback lived in the CJS route.
resolveMCPOAuthTarget (packages/api/src/mcp/oauth/target.ts) now owns both:
it resolves the server in the principal's current config with a strict read,
refuses a flow admitted for another server, a server the principal can no
longer use, or a redefined one, and selects the headers the flow sends (the
initiation snapshot, else the principal's config). Initiation calls it before
either redirect (404 or 400); the callback calls it before the exchange and
from the token-store fence.
* 📝 docs: Note That a Hidden MCP Server Ends OAuth Sign-Ins Already Started
* 🚩 feat: Publish the yamlMcpHide Admin Config Meta Flag
Profiles can hide librechat.yaml MCP servers and a hidden server is an
access boundary, so GET /api/admin/config/meta now reports
features.yamlMcpHide for the admin panel to gate its hide UI on. The
meta.spec probe checks the behaviour itself: the admin API stores an
mcpServers.<name> tombstone, the merged config drops the server, the
registry withholds it from principal lookups and checkout but not from
app-level lookups, process-backed servers stay, and an unreadable
principal config withholds every hideable server.
* 🧪 test: Align MCP Tombstone Specs With the Portable Config Store
The admin config handlers now write whole documents through
writeConfigDocument, so the end-to-end tombstone spec wires it in place
of the removed upsertConfig/patchConfigFields deps. A reset of a whole
MCP record now also prunes the parents it leaves empty.
* 🗄️ refactor: Portable Admin Config Store with Revisions, Key Encoding and Coherent Writes
Admin config writes went straight to MongoDB with dotted-path `$set`, `$unset`, `$pull` and `$addToSet`, and nothing checked `configVersion`. That caused six problems.
* ⚛️ feat: Atomic Admin Config Changes Endpoint (set, unset, tombstone, entry upsert/remove/rename)
Admin clients can change a principal's config overrides only one kind of change at a time:
- PATCH `/fields` for sets, at most 100 entries;
- POST `/fields/tombstone` for one tombstone;
- DELETE `/fields` for one reset.
* 🔁 fix: Reload librechat.yaml on Admin Config Writes
Base-only sections such as `filters` and `messageFilter` live only in librechat.yaml, and an admin
config write was how a running server picked up an edit to them. The coherent-cache change limited
admin-write invalidation to the override and MCP caches, so the YAML base was never re-read after
startup: the content-filter e2e suite, which activates filters by editing the YAML and writing a
reload sentinel, saw `filters: undefined` from GET /base and every activation timed out.
Admin config writes clear the YAML base config again, alongside the override and MCP caches, and
the clear is broadcast with the others, so every instance reloads its YAML. The reload keeps the
last good config on failure and republishes the tools derived from it, so the global tool cache is
left for it to overwrite rather than emptied first.
* 🧭 fix: Cap Dotted Field Path Depth and Hold Revision Preconditions on No-Op Writes
A dotted fieldPath was split without the 32-segment cap that segments already had, so a deep path reached the recursive path writer and failed with a 500. Both spellings now share MAX_CONFIG_PATH_DEPTH and answer 400 CONFIG_PATH_INVALID / too_deep on PATCH, tombstone and DELETE /fields.
Writes reduced to nothing (protected interface permissions, base-only or dedicated sections) answered 200 without checking expectedRevision. They now compare it with the stored document and answer 409 CONFIG_VERSION_CONFLICT with currentRevision on a mismatch, as the write itself would.
* 📡 fix: Retry the Config Invalidation Subscription When Redis Comes Back
A SUBSCRIBE that failed at startup (Redis unreachable, the client's retries spent) was only logged, and ioredis resubscribes only to channels it has joined, so the instance missed every other instance's config invalidation until it restarted. The subscription is now sent again each time the subscriber becomes ready until one succeeds; after that the client's own resubscribe takes over, and closing stops the retries.
* 🧷 fix: Tighten Config Change Batches Around Array Entries, Cancelled Changes and MCP Tombstones
- A tombstone with an index segment below a field configSchema does not define (an unknown key, or what an intersection or any holds) is refused as inside_array: the merge removes inherited values from objects only, so it was stored and reported applied while the element stayed visible.
- unset joins set and rename in the merged-by-key position check: unset endpoints.custom.0.headers answers 400 indexed_merge_key_write, since the position can name another endpoint by the time the batch applies. upsertEntry and removeEntry address entries by key.
- A batch whose changes cancel out (set interface.customWelcome, then unset interface) writes nothing: no empty document, revision bump, audit entry or invalidation. Its changes are reported as unchanged.
- A whole-section mcpServers tombstone reports each librechat.yaml stdio server it leaves in place as ignored (process_mcp_server).
- removeEntry no longer attributes the whole collection to itself, and existing issues of merged-by-key entries are matched by key rather than index, so removing an entry beside a legacy-invalid one (or shifting it) is no longer refused for that entry's issue.
* 🪪 fix: Keep a Requested Priority on New Principals and Report Ignored MCP Renames
POST …/changes discarded a broad manager's priority for a principal without a document when no change altered it: the batch answered written: false instead of creating the priority-only document PUT creates. An explicit priority on an absent principal now counts as a change.
A rename under an MCP server librechat.yaml runs as a process persisted an override the runtime merge drops, but was not reported in ignored. It now is, like set and tombstone. An unset there stays unreported: it asks for the YAML value, which is what runs.
* 🔁 fix: Drop YAML Reloads and Merges Overtaken by a Config Write
Admin config writes clear the YAML base config on every instance, so a write is how a running
server picks up an edit to librechat.yaml. Two races could undo that:
- A base reload that read the old YAML before a write's clear cached it after the clear, and the
base has no TTL, so the old base was served until the next write.
- A request that read the old base before the clear, and was still resolving principals, cached
its merge under the new override generation for the override TTL.
The config service now keeps a base-config generation that `clearAppConfigCache` bumps. A reload
publishes the base, the tools and the last good config only if its generation is still current,
a read after a clear never joins a reload started before it, and the newer reload starts once the
stale one settles so the loader's process-wide side effects end with the newest YAML. Merges
capture the generation, base included, before they read the base config.
Tests:
- service.spec: a clear during a reload (stale success, stale failure, a read waiting on the newer
reload) and a merge built on the pre-clear base.
- invalidation.redis.spec: a write on one instance makes another reload librechat.yaml.
- admin-config-reload.spec (api): every admin config write route, through the real router,
handlers, database and config service, reloads librechat.yaml; a request with nothing to write
does not.
- invalidateConfigCaches.spec no longer asserts an order the parallel clears do not have.
* 🧪 test: Reload librechat.yaml After a Committed Change Batch and Not After an Unwritten One
* 🧮 fix: Validate Change Batches on Their End State and Report Base-Only Fields a Tombstone Keeps
A batch's validation scope was built from every intermediate write, located in the state each
change produced. A change a later one undid (set `balance.startBalance`, then restore `balance`)
still widened the scope, so an issue the stored document already had there rejected an
unrelated change, and an entry a later change moved (upsert one entry, then remove one before
it) pointed its written index at a neighbour with a legacy issue. The written paths are now
located in the batch's end state and kept only where that state differs from the stored
document, with entries of merged-by-key arrays compared by key.
A tombstone above a base-only field (`endpoints.agents`, `endpoints.agents.pullRequests`) is
stored and hides the rest of the subtree, while the runtime merge puts back the provider, host,
OAuth app and shared cache slots librechat.yaml sets. The response now lists those fields in
`ignored` with reason `base_only_path`, as it already does for the stdio MCP servers a
whole-section tombstone leaves in place.
* 🧬 fix: Encode Config Keys in Objects Built in Another Realm
The key encoder treated an object as plain only when its prototype was this realm's
Object.prototype, and returned any other object unchanged, keys and all. Under Jest,
structuredClone (which the secret pipeline uses) returns objects from the host realm, so the
items of an array the pipeline had cloned, such as Azure groups or custom endpoints, reached
the engine with their dotted keys raw. Node in production has one realm, but the encoding must
not depend on prototype identity: a skipped object stores its dotted keys raw without an error.
A plain object is now one whose prototype is null or a root Object.prototype from any realm.
The encoding spec covers an object built in a vm context.
* 🧪 test: Check Dotted Record Keys Reach the Store's Whole-Document Write
dev's admin config route test asserted the keys on patchConfigFields, which the handlers no
longer call; it now asserts them on the draft writeConfigDocument receives.
* 🚩 feat: Publish the expectedRevision, prunesEmptyParents and awaitedInvalidation Config Flags
GET /api/admin/config/meta now reports the three write-coherence behaviours this branch
implements, so an admin client can drop the workarounds each one replaces:
- expectedRevision: responses carry `revision`; PUT, PATCH /fields, POST /fields/tombstone and
PATCH /active take `expectedRevision` in the body and both DELETE routes in the query. A
mismatch answers 409 CONFIG_VERSION_CONFLICT with currentRevision, a malformed value 400
INVALID_EXPECTED_REVISION; unpinned writes re-read and re-apply up to 3 times.
- prunesEmptyParents: a field delete or tombstone removes the objects it empties, stopping at
arrays; shells-only documents count as empty for assign-only lifecycle calls.
- awaitedInvalidation: writes answer after the config caches are cleared (broadcast with Redis),
GET /base bypasses the merged-config cache, and a merge read before a clear is never cached.
meta.spec probes each one against the behaviour: a stale and a malformed precondition on a
PATCH, the store operations' unset and tombstone on nested objects and an array element, and a
held invalidation, the GET /base read options and a merge raced by a clear.
* 🔀 fix: Keep Config Keys Raw Where the Engine Stores Them, So Older Servers Read Them During Upgrades
Servers before the key encoding (v0.8.9-rc1 among them) read every override key literally.
The Mongoose binding encoded every write, so during a rolling upgrade the first write from an
upgraded server turned a stored `gpt-4.1` or Bedrock inference profile into `gpt-4%2E1` for
every server not yet upgraded, and an older server's restore of a deleted group or role
config dropped the `keyEncoding` marker its schema lacks, after which upgraded servers read
the encoded keys literally.
The binding now sends keys raw first and encodes them only when the engine refuses a raw
field name (DocumentDB, Cosmos, FerretDB or MongoDB 4.4 for `$` names): the refused write
changed nothing, so it runs again encoded under the same revision precondition, and that
process encodes later writes holding such keys directly. MongoDB 4.4+ stores dotted names
(5.0+ also `$` names inside a value), so there an older server reads exactly what it wrote. A
document whose raw keys spell escape sequences while none holds a raw `.`, `$` or NUL is
still written encoded, since a raw read would decode it. A raw write clears the marker.
Reads decode a marked document (raw keys an older server added beside encoded ones, or wrote
under a marker it left, carry no escape sequence and read as stored) and an unmarked one
unless some key holds a raw `.`, `$` or NUL, which no encoded document does; that reads an
encoded document whose marker an older server dropped. Encoding stays in the binding for
every engine that needs it (decision #15); the residual cases are in documentdb-compat.md.
* ⏱️ fix: Remove Config Cache Writes a Clear Overtook in Flight
With an asynchronous APP_CONFIG store (Redis or a custom Keyv store), a clear can bump the
generation and finish its delete after a reload or merge checked the generation but before its
`set` landed. The older value then repopulated `_BASE_` until the next write, or a merged
config for the full override TTL.
The base reload, the last-good restoration and the merge cache now check the generation again
once their write lands and delete what they wrote if a clear overtook it. A deleted entry only
costs the next read a reload or a merge; a newer base load cannot be removed this way, since it
starts only after the stale one settles.
* 🔐 fix: Require the Stored Web Search Key Again When a Change Batch Moves Its URL
#17323 refuses a PUT, PATCH, tombstone or field delete that changes or removes a web search
URL beside a stored API key unless the key is entered again, so a stored key cannot be sent
to a destination it was not entered for. POST /changes skipped that check: a batch could set,
reset or tombstone `webSearch.searxngInstanceUrl` (or replace `webSearch` without the key,
which keeps the stored key) and point the stored key at another host.
A batch is now judged on the document it would store, like PATCH: a URL that ends up beside
a stored key it did not travel with answers 400 CONFIG_SECRET_REENTRY_REQUIRED and writes
nothing, dry runs included. Only keys the request sent count as entered again; a secret a set
kept from the stored document does not.
* 🚩 feat: Publish the changesBatch Flag and the maxChangeOps Limit in Config Meta
GET /api/admin/config/meta now reports `features.changesBatch: true` and
`limits.maxChangeOps` (1000, from MAX_CONFIG_CHANGE_OPS), so the admin panel can gate its
one-request save on the endpoint and size its batches from the server. The meta.spec probe
checks the behaviour itself: an oversized batch answers TOO_MANY_OPS, a batch with one invalid
op writes nothing, and a valid set plus tombstone lands as one write.
* 🗄️ refactor: Portable Admin Config Store with Revisions, Key Encoding and Coherent Writes
Admin config writes went straight to MongoDB with dotted-path `$set`, `$unset`, `$pull` and `$addToSet`, and nothing checked `configVersion`. That caused six problems.
* 🔁 fix: Reload librechat.yaml on Admin Config Writes
Base-only sections such as `filters` and `messageFilter` live only in librechat.yaml, and an admin
config write was how a running server picked up an edit to them. The coherent-cache change limited
admin-write invalidation to the override and MCP caches, so the YAML base was never re-read after
startup: the content-filter e2e suite, which activates filters by editing the YAML and writing a
reload sentinel, saw `filters: undefined` from GET /base and every activation timed out.
Admin config writes clear the YAML base config again, alongside the override and MCP caches, and
the clear is broadcast with the others, so every instance reloads its YAML. The reload keeps the
last good config on failure and republishes the tools derived from it, so the global tool cache is
left for it to overwrite rather than emptied first.
* 🧭 fix: Cap Dotted Field Path Depth and Hold Revision Preconditions on No-Op Writes
A dotted fieldPath was split without the 32-segment cap that segments already had, so a deep path reached the recursive path writer and failed with a 500. Both spellings now share MAX_CONFIG_PATH_DEPTH and answer 400 CONFIG_PATH_INVALID / too_deep on PATCH, tombstone and DELETE /fields.
Writes reduced to nothing (protected interface permissions, base-only or dedicated sections) answered 200 without checking expectedRevision. They now compare it with the stored document and answer 409 CONFIG_VERSION_CONFLICT with currentRevision on a mismatch, as the write itself would.
* 📡 fix: Retry the Config Invalidation Subscription When Redis Comes Back
A SUBSCRIBE that failed at startup (Redis unreachable, the client's retries spent) was only logged, and ioredis resubscribes only to channels it has joined, so the instance missed every other instance's config invalidation until it restarted. The subscription is now sent again each time the subscriber becomes ready until one succeeds; after that the client's own resubscribe takes over, and closing stops the retries.
* 🔁 fix: Drop YAML Reloads and Merges Overtaken by a Config Write
Admin config writes clear the YAML base config on every instance, so a write is how a running
server picks up an edit to librechat.yaml. Two races could undo that:
- A base reload that read the old YAML before a write's clear cached it after the clear, and the
base has no TTL, so the old base was served until the next write.
- A request that read the old base before the clear, and was still resolving principals, cached
its merge under the new override generation for the override TTL.
The config service now keeps a base-config generation that `clearAppConfigCache` bumps. A reload
publishes the base, the tools and the last good config only if its generation is still current,
a read after a clear never joins a reload started before it, and the newer reload starts once the
stale one settles so the loader's process-wide side effects end with the newest YAML. Merges
capture the generation, base included, before they read the base config.
Tests:
- service.spec: a clear during a reload (stale success, stale failure, a read waiting on the newer
reload) and a merge built on the pre-clear base.
- invalidation.redis.spec: a write on one instance makes another reload librechat.yaml.
- admin-config-reload.spec (api): every admin config write route, through the real router,
handlers, database and config service, reloads librechat.yaml; a request with nothing to write
does not.
- invalidateConfigCaches.spec no longer asserts an order the parallel clears do not have.
* 🧬 fix: Encode Config Keys in Objects Built in Another Realm
The key encoder treated an object as plain only when its prototype was this realm's
Object.prototype, and returned any other object unchanged, keys and all. Under Jest,
structuredClone (which the secret pipeline uses) returns objects from the host realm, so the
items of an array the pipeline had cloned, such as Azure groups or custom endpoints, reached
the engine with their dotted keys raw. Node in production has one realm, but the encoding must
not depend on prototype identity: a skipped object stores its dotted keys raw without an error.
A plain object is now one whose prototype is null or a root Object.prototype from any realm.
The encoding spec covers an object built in a vm context.
* 🧪 test: Check Dotted Record Keys Reach the Store's Whole-Document Write
dev's admin config route test asserted the keys on patchConfigFields, which the handlers no
longer call; it now asserts them on the draft writeConfigDocument receives.
* 🚩 feat: Publish the expectedRevision, prunesEmptyParents and awaitedInvalidation Config Flags
GET /api/admin/config/meta now reports the three write-coherence behaviours this branch
implements, so an admin client can drop the workarounds each one replaces:
- expectedRevision: responses carry `revision`; PUT, PATCH /fields, POST /fields/tombstone and
PATCH /active take `expectedRevision` in the body and both DELETE routes in the query. A
mismatch answers 409 CONFIG_VERSION_CONFLICT with currentRevision, a malformed value 400
INVALID_EXPECTED_REVISION; unpinned writes re-read and re-apply up to 3 times.
- prunesEmptyParents: a field delete or tombstone removes the objects it empties, stopping at
arrays; shells-only documents count as empty for assign-only lifecycle calls.
- awaitedInvalidation: writes answer after the config caches are cleared (broadcast with Redis),
GET /base bypasses the merged-config cache, and a merge read before a clear is never cached.
meta.spec probes each one against the behaviour: a stale and a malformed precondition on a
PATCH, the store operations' unset and tombstone on nested objects and an array element, and a
held invalidation, the GET /base read options and a merge raced by a clear.
* 🔀 fix: Keep Config Keys Raw Where the Engine Stores Them, So Older Servers Read Them During Upgrades
Servers before the key encoding (v0.8.9-rc1 among them) read every override key literally.
The Mongoose binding encoded every write, so during a rolling upgrade the first write from an
upgraded server turned a stored `gpt-4.1` or Bedrock inference profile into `gpt-4%2E1` for
every server not yet upgraded, and an older server's restore of a deleted group or role
config dropped the `keyEncoding` marker its schema lacks, after which upgraded servers read
the encoded keys literally.
The binding now sends keys raw first and encodes them only when the engine refuses a raw
field name (DocumentDB, Cosmos, FerretDB or MongoDB 4.4 for `$` names): the refused write
changed nothing, so it runs again encoded under the same revision precondition, and that
process encodes later writes holding such keys directly. MongoDB 4.4+ stores dotted names
(5.0+ also `$` names inside a value), so there an older server reads exactly what it wrote. A
document whose raw keys spell escape sequences while none holds a raw `.`, `$` or NUL is
still written encoded, since a raw read would decode it. A raw write clears the marker.
Reads decode a marked document (raw keys an older server added beside encoded ones, or wrote
under a marker it left, carry no escape sequence and read as stored) and an unmarked one
unless some key holds a raw `.`, `$` or NUL, which no encoded document does; that reads an
encoded document whose marker an older server dropped. Encoding stays in the binding for
every engine that needs it (decision #15); the residual cases are in documentdb-compat.md.
* ⏱️ fix: Remove Config Cache Writes a Clear Overtook in Flight
With an asynchronous APP_CONFIG store (Redis or a custom Keyv store), a clear can bump the
generation and finish its delete after a reload or merge checked the generation but before its
`set` landed. The older value then repopulated `_BASE_` until the next write, or a merged
config for the full override TTL.
The base reload, the last-good restoration and the merge cache now check the generation again
once their write lands and delete what they wrote if a clear overtook it. A deleted entry only
costs the next read a reload or a merge; a newer base load cannot be removed this way, since it
starts only after the stale one settles.
* 🔧 chore: Update sanitize-html and related dependencies in package-lock.json and package.json
- Upgrade sanitize-html from ^2.17.7 to ^2.18.1 across multiple package.json files.
- Update dayjs from 1.11.21 to 1.11.23 in package-lock.json.
- Upgrade is-plain-object from 5.0.0 to 5.1.0 in package-lock.json.
- Upgrade launder from 1.7.1 to 1.7.2 in package-lock.json.
- Update postcss from ^8.3.11 to ^8.5.27 in package-lock.json.
* 🔧 chore: Upgrade mongodb-memory-server to version 11.3.0 across package-lock.json and multiple package.json files
- Update mongodb-memory-server from ^11.0.1 to ^11.3.0 in package-lock.json.
- Reflect the same version change in api/package.json and packages/data-schemas/package.json.
* 🔧 chore: Upgrade hono to version 4.13.13 in package.json and package-lock.json
- Update hono from ^4.13.7 to ^4.13.13 in package.json.
- Reflect the same version change in package-lock.json.
* 🔧 chore: Upgrade follow-redirects to version 1.16.1 in package-lock.json
- Update follow-redirects from 1.16.0 to 1.16.1 in package-lock.json.
* 🔑 fix: Use Admin-Stored Web Search Credentials at Runtime
Use admin-stored (encrypted or literal) web search credentials as system
credentials at runtime, add the Keenable key to the secret registry, bind a
stored key to the layer that set its URL, and require re-entering the key when
a write changes or removes that URL (checked atomically with a version
precondition).
* 🧹 fix: Keep Dotted-Key Write Guarantees on Version-Checked Web Search Writes
A version-checked write the caller saw absent first creates an empty
document. When the database then refuses the write (a key name it cannot
store, answered 422 CONFIG_KEY_NOT_STORABLE), remove that document again
so a refused write stores nothing, unless another write has changed it.
Secret re-entry issues now carry `segments` like every other config
issue.
* 🚩 feat: Publish the webSearchStoredKeys Feature Flag in the Config Contract
GET /api/admin/config/meta now reports `webSearchStoredKeys: true`, so an
admin client can stop warning that only ${VAR} web search references work at
runtime. meta.spec probes the behaviour behind it: an encrypted stored key
reaches web search auth, the Keenable key is encrypted on write, and changing
a URL beside a stored key requires entering the key again.
* 🧪 test: Type the Refused-Write Driver Stub in the Config Methods Spec
* 🧪 test: Expect the Write Precondition Arguments in the Admin Config Route Test
The handler passes a session slot and an optional version precondition to
patchConfigFields since the web search re-entry check; the route test added
in #17322 asserted the earlier five-argument call.
* 🧹 fix: Surface a Failed Cleanup of the Empty Config Document
When a version-checked write the database refused cannot remove the empty
document created for it, let that failure reach the handler (500) instead
of logging it and answering 422 CONFIG_KEY_NOT_STORABLE, which promises that
nothing was stored.
* 📝 docs: State the Web Search Stored-Key Binding Rule Exactly in the webSearchStoredKeys Flag
The flag's doc said a stored key goes only to a URL the same layer set. The merge rule keeps a stored key over an inherited ${VAR} or default URL, so the doc now names the exact rule: a stored key reaches a URL stored in config only when one layer set both, a later layer that changes, blanks or removes the URL drops the key, and a write that changes or removes the URL must enter the key again.
* 🧹 refactor: Read the Secret Registry Through getConfigSecretRules Only
The dev merge kept this branch's getConfigSecretFields and getConfigArraySecretFields beside dev's getConfigSecretRules, which returns the same registry data. Only the secret specs used the two extra accessors. They now read getConfigSecretRules().secretFields and .arraySecretFields, so the accessors and their exported ConfigSecretField and ArraySecretField interfaces (duplicates of AdminConfigSecretFieldRule and AdminConfigArraySecretFieldRule) are gone.
* 🔑 feat: Keep Dotted Record Keys in Admin Config Writes and Publish the Config Contract
Keep dotted record keys in admin config write bodies behind a path-scoped
sanitizer, reject $-prefixed and prototype keys after auth, report dotted_key
issues with segments, and publish GET /api/admin/config/meta (features, rules,
limits, versions) so clients can gate on backend capabilities.
* 🧪 test: Expect Issue Segments in the Config Override e2e Scenario
Override validation issues now carry `segments`; assert the full issue shape.
* fix: Bound Outbound Calls Made Inside a Request
RAG queries for file search and message context, OCR provider calls,
action HTTP calls, the moderation check, the stored-image fetch for
base64 providers, and Flux result polling had no timeout. A stalled
upstream hung the chat turn, the upload or the tool call indefinitely,
and Flux kept polling forever on statuses that never become Ready.
Each now runs under a budget from a new librechat.yaml timeouts block
with finite defaults (getOutboundTimeoutMs in @librechat/api). Action
calls also receive the run's abort signal, so stopping a run closes the
socket.
* test: Cover a Stalled RAG Query in the Mock Harness
* fix: Share One Flux Budget Across Submit and Polls, Bound the Vertex Token Exchange
* refactor: Poll Flux Results Through pollUntilSettled
* refactor: Leave Flux Polling for a Separate Migration
* fix: Cap Configured Timeouts at the Node Timer Limit
* fix: Bound the Action Token Refresh and the Whole Image Download
* fix: Cap Every Outbound Budget by Wall-Clock Time
Axios's timeout only fires on an idle socket, so a RAG, OCR, moderation,
action or token response that keeps trickling bytes never ended.
outboundRequestBudget pairs each timeout with an AbortSignal deadline, and
action calls combine it with the run's own signal.
* fix: Name the Budget That Ran Out and Give Actions Five Minutes
The actions default rises to five minutes, since action endpoints are
arbitrary third-party APIs and the old minute could cut off legitimately
slow ones after an upgrade.
A budget overrun now fails with an error naming the timeouts key and its
value, whether it was the idle timeout or the wall-clock deadline, and
logAxiosError logs it as a warning so operators know what to raise. A
deadline cancellation is no longer read as a user stop, so an action that
runs out of time reports a timeout instead of looking like a stopped run.
* fix: Hold Outbound Deadlines Weakly So Finished Requests Leave No Timers
* fix: Check the Budget Before Reading an Error Message
* fix: Report a Wrapped Deadline as a Failure, Not a Stop
* fix: Bound the OAuth Code Exchange and Keep the OCR Budget Hint When Protected
* chore: Sort Imports in axios.ts After Rebase
* feat: Defer MCP OAuth Sign-In Until a Deferred Tool Is Used
Adds an oauthPrompt server option (on_start by default, or on_use) and an
operator-declared oauthToolCatalog. With on_use, an operator-configured
OAuth server whose selected agent tools are all deferred no longer prompts
at turn start: tool search offers the declared catalog (or the user's own
cached catalog), and sign-in happens on the first tool call through the
existing in-run OAuth step. Without a declared catalog the turn-start
prompt is kept. Both fields are operator-only.
Related to #16765
* test: Cover MCP OAuth Sign-In on First Deferred Tool Use
* fix: Bound the Declared OAuth Tool Schema to Non-Recursive Types
* refactor: Move MCP OAuth Deferral Orchestration Into packages/api
* refactor: Move the Cached-Catalog OAuth Prompt Branch Into packages/api
* fix: Defer MCP OAuth Only When the Offered Catalog Covers the Selection
* fix: Cover Runtime OAuth, Background Tools, and Tokenless Discovery in Deferral
* fix: Match Legacy Keys, Honor Background Capability, and Reject Unsupported Schema Keywords
* fix: Resolve Wildcard Background Opt-In and Tighten Declared Catalog Matching
* fix: Validate Declared Tool Schema Types and Enums
* fix: Accept Canonical Catalog Keys the Definitions Loader Accepts
* test: Pin the Declared Catalog Requirement for Cached User Catalogs
* fix: Resolve Deferred Tool Options Across MCP Spelling Aliases
Normalize uploaded image bytes in shared TypeScript and recover mislabeled image history without inferring codecs from generic HEIF brands.
Co-authored-by: Lia <lia@librechat.ai>
Co-authored-by: JeongCheolLee <jclee7503@gmail.com>
* fix: Contain Download and Speech Stream Failures and Cap Speech Input
The code output download piped the Code API stream with .pipe, which adds no
error listener, so a body that failed mid-stream (a bad gzip body, a reset)
became an uncaught exception and the process exited. pipeToResponse uses
stream.pipeline, ending the response and destroying the upstream when the
client leaves.
Text-to-speech piped provider streams the same way and waited only for
'end', so a provider error was uncaught and a client disconnect left the
chunk loop waiting. pipeSegment resolves on end and rejects on an error or
a disconnect, which ends the loop.
A speech request had no length cap, so one request could fan out into
thousands of serial paid provider calls. speech.tts.maxInputChars bounds it
(default 20,000 characters).
* docs: Document the Speech Input Cap in the Example Config
* fix: Reject a Speech Segment When the Client Already Left
* fix: Tear Down Both Ends of a Failed Speech Segment and Cap Streamed Speech
A failed provider segment now destroys the response as well as the source,
so a half-written answer cannot hang the client, and a response-side error
rejects the segment instead of going unhandled. Automatic playback reads a
message only up to speech.tts.maxInputChars, so long messages cannot fan
out past the cap either.
The download scenario now checks the behavior .pipe lacked: leaving a code
download closes the upstream connection right away.
* fix: Keep a Late Response Write Error From Going Unhandled
* test: Key Slow Code Downloads by File and Send a Browser User Agent
* fix: Read Speech Up to the Cap Instead of Refusing It
Manual speech now synthesizes the text up to speech.tts.maxInputChars, the
same as automatic playback, through capSpeechInput, so the CJS service only
passes the capped text along and the request keeps its existing error
contract. A streamed message that reaches the cap exactly now finishes, and
a segment that fails before any audio went out leaves the response open for
the caller's HTTP error.
* fix: Count Only Text Against the Speech Cap
* fix: Hash Off the Event Loop and Surface API Key Lookup Failures
Registration, email verification, password reset and verification resends
hashed and compared with bcryptjs's synchronous calls. bcryptjs is pure
JavaScript, so each call blocked the event loop for every request in the
process. They now use the promise APIs, and the password reset
dependencies are async.
validateAgentApiKey caught its own query failures and returned null, so a
database outage answered remote callers with 401 Invalid API key. It now
lets the failure reach requireApiKeyAuth, which answers with a 500.
* fix: Run bcrypt on a Worker Pool in packages/api
bcryptjs's promise API still computes on the main thread, only in chunks
of up to 100 ms, so concurrent registrations and resets kept stalling
unrelated requests (four cost-10 hashes delayed a 5 ms timer by about
190 ms). hashSecret and compareSecret now run bcryptjs on a small
worker_threads pool in packages/api, and AuthService.js calls them.
* feat: Configure the Password Hashing Worker Count
* fix: Verify Login and Step-Up Passwords on the Hash Pool
* perf: Index Hot Lookups and Project the Remote Models List
checkBan reads the KeyvMongo logs collection by key on every request when
bans are enabled, BYOK requests read Key by user and name, and agent tool
loading reads Action by agent_id or assistant_id. None of those fields had
an index, so each read scanned its collection. The Key and Action schemas
gain indexes, and the KeyvMongo store builds a key index on first use
unless the deployment disables auto indexing.
The remote /v1/models routes loaded whole agent documents, including the
unbounded versions history, to read six fields. getAgentModelSummaries
loads only those fields.
* test: Authenticate the Models List Scenarios With an Agent API Key
* fix: Keep API Keys and Internal Errors Out of Logs and Responses
The log redaction patterns did not cover the appid query parameter, so a
failed Wolfram request logged its AppID with the axios request URL. appid
now joins the redacted token and query names.
OpenWeather returned a fetch error's message to the model verbatim, and
node-fetch puts the full request URL, appid included, in that message. The
tool now passes it through redactMessage, as ToolService does.
The public startup config route and the unauthenticated password reset
route sent raw error text on unexpected failures. Both now answer with a
fixed message and keep the detail in the server log.
* refactor: Format Tool Error Text in packages/api
* fix: Redact appid Metadata Keys in Structured Logs
* fix: Restrict Stop to the Generation's Owner and Contain S3 Ingest Stream Errors
The legacy abort route passed any caller-supplied conversation id straight to
GenerationJobManager.abortJob, so a signed-in user who knew another user's
conversation id could stop that generation and receive its partial output.
abortOwnedGeneration now reads the job first and stops it only for its owner
and tenant, fenced to the epoch it read; anything else reads as not found.
saveURLToS3 piped Readable.fromWeb into the byte-limit transform with .pipe,
which does not forward source errors. A body that failed mid-download emitted
an unhandled error and left the upload awaiting forever. Use stream.pipeline,
as the CloudFront strategy already does.
* test: Cover Stop Ownership on the Legacy Abort Route
* test: Scope the Parts Attachment Check to the Composer Tray
The file name also labels a hidden recent-file row once earlier tests in the
shard have left one mounted, so the unscoped locator resolved to two buttons.
* fix: Report Not Ready on /readyz While Redis Is Disconnected
/readyz only reflected the one-shot startup flag, so a pod whose Redis
connection dropped after startup kept answering 200 while sign-in failed.
It now also returns 503 when USE_REDIS is on and either shared client
(ioredis or the Keyv node-redis client) is not connected. /livez and
/health stay unconditional so a Redis blip cannot cause a restart loop.
Related to #16814
* test: Cover Readiness Probes Across a Redis Outage
* fix: Inject Redis Clients Into Readiness and Check Every Cluster Master
* fix: Route Subagent Files Delivered After a Mid-Run Reload
* test: Stub Stored Part Queries in the ContentParts Integration Suite
* fix: Recover Stored Part Lookups That Fail Without a Reader
* fix: Resolve Late Subagent Files With One Previewed Message Read
* fix: Read Late Subagent Hints Again Until the File Is Saved
* fix: Count Failed Reads Toward the Late Hint Poll Bound
* fix: Let Unresolved Late Hint Reads Recover on Focus and Reconnect
* fix: Resolve Late Subagent File Owners From the Stored Transcripts
* fix: Ask for Late Subagent File Owners in Bounded Batches
* fix: Render Files Saved by Tools Inside a Subagent Run
* test: Cover Subagent Nested Tool Images After Reload
* fix: Hoist Subagent Child-Run Files With Grouped Tool Calls
* fix: Route Live Subagent Child Files Through the Part Attachment Map
* fix: Keep Subagent Child File Routing Through Previews and Ownership Rules
* test: Match Subagent Image Names Exactly
* fix: Key Subagent Child Files by Their Owning Part
* fix: Apply Attachment Scope Rules to Subagent Child Calls
* fix: Carry Child Call Scope Through Previews and Live Progress
* fix: Retain Live Subagent Progress Readers and Seen Child Calls
* fix: Keep Live Progress Keys Retained Across Streamed Deltas
* fix: Assign Subagent Child Files Once Per Message
* fix: Route Late and Id-less Subagent Child Files
* fix: Keep Seen Subagent Child Calls With Their Invocation
* fix: Use Streamed Index and Call-Level Owner for Subagent Child Files
* fix: Reserve Scoped Child Files From Unscoped Top-Level Calls
* fix: Record Subagent Child Calls When Progress Is Written
* fix: Keep Agent Scope on Remembered Subagent Child Calls
* refactor: Share One Subagent Child Call Collector
* fix: Derive Live Signature From Remembered Child Calls
* fix: Keep Child Calls a Bounded Batch Evicts
* fix: Bound Remembered Subagent Child Calls and Include Replay Segments
* fix: Refresh Owners of Shown Files in the Bounded Call History
* fix: Keep Remembered Call Order Stable Across Eviction Replays
* fix: Scope Preview Hints to Attachments and Walk Nested Calls Iteratively
* fix: Bound Wildcard Preview Hints and Own Live Calls by Their Run
* fix: Own Stored Subagent Child Calls by Their Persisted Identity
* feat: Add Gemini 4 Argon Support
Registers gemini-4-argon (GA 2026-10-13) for both the Gemini API and
Google Cloud Gemini Enterprise Agent Platform, following the Gemini 3.8
Flash integration.
- Model dropdown (config.ts) and both GOOGLE_MODELS examples
- Shared 1,048,576-token context window in googleModels; output stays
capped at the 65,535 synchronous limit by googleSettings
- Thinking rule: medium default, minimal substituted with low, ignored
sampling params and rejected thinkingBudget stripped; the allowlisted
cyber-permissive variant defaults to high
- Introductory rates ($2 in / $10 out / $0.10 implicit cache read per
1M) with the 2026-12-01 revert to $4 / $20 / $0.20 noted at both
call sites; no long-context premium tier
- Tests: thinking default and levels, minimal substitution, legacy param
strip, Vertex eu multi-region, OpenAI-compatible addParams strip,
context window, value key and rates
Refs #17074
* test: Cover Gemini 4 Argon Request Shape and Billing End to End
Adds a Gemini-compatible mock endpoint whose addParams carry sampling
params, an E2E_REPORT_LLM_CONFIG fake-model marker that reports the
resolved agent request, and scenarios asserting that an Argon turn sends
no ignored sampling params (with gemini-2.5-pro as the control) and is
billed at the Argon rates.
* test: Read the Resolved Agent Request From the Graph in Argon Scenarios
The hook's agents are the unresolved agent configs, so the report now
reads the graph's agent context. The scenarios select the Gemini model
explicitly and key billed rates by model so a mismatch names the model.
* test: Match the Mobile Model Option Name in Argon Scenarios
* fix: Route Gemini 4 Argon to a Multi-Region Vertex Endpoint by Default
Argon is served only from the global, us and eu multi-regions, so with
GOOGLE_LOC unset a Vertex request now uses global instead of the
us-central1 regional default; a configured location is kept as is.
Argon also rejects a candidate count, so candidateCount, candidate_count
and its OpenAI alias n are stripped for Argon on the native and
Gemini-compatible paths.
* chore: Bump @librechat/agents to 4.0.6 for Gemini 4 Argon Input Rules
* fix: Move Regional Vertex Locations to Their Multi-Region for Gemini 4 Argon
A configured regional location such as europe-west1 does not serve
Argon, so it now resolves to the multi-region that contains it (europe-*
to eu, us-* to us) wherever the location comes from, GOOGLE_LOC or
addParams. A region outside us and eu is kept rather than sent to
global, so data never leaves the configured geography silently.
* fix: Route Gemini 4 Argon Past Regional Vertex Endpoint Overrides
* fix: Skip Re-Embedding Legacy File Search Files an Agent Already Holds
Files embedded before per-namespace tracking carry no embeddedEntities, so
lazy provisioning treated them as unembedded and embedded them a second
time on the first search after upgrading, duplicating every passage.
A legacy record in the agent's own file_search resources was embedded for
it, so trust its embedded flag there instead of re-queueing it.
* fix: Adopt Legacy Search Embeddings Only for Their Sole Holder
Trusting the embedded flag for every legacy File Search file left an agent
that inherited one querying a namespace without its vectors. Legacy files
held by no other agent now record the active agent as their namespace, a
one-time write, and are not embedded again; a file another agent also
holds keeps the per-namespace re-embed.
Adds an e2e scenario that reshapes an uploaded agent file into the v0.8.7
record and checks that search queries it without a second embed.
* test: Cover Legacy Search Files Shared With Another Agent
* test: Read the Stored File Id in Legacy Search Scenarios
* fix: Pin Legacy Search Adoption to Loaded Records and Wire Every Agent Init
file_id is not unique, so adoption now matches each record by its owner and
tenant as well, and only rewrites the records priming loaded. The added
conversation and client agent initializations receive the dependency too,
so their sole-holder legacy files are not embedded a second time.
* fix: Adopt Each Legacy Search Record in One Conditional Write
* fix: Count a Concurrent Same-Agent Adoption as Adopted
* fix: Run Legacy Search Adoption Beside the Liveness Probe and Fall Back on Failure
* fix: Keep Committed Legacy Search Adoptions When a Sibling Write Fails
* fix: Confirm Legacy Search Embeddings With RAG Before Adopting Them
Inferring the embedding agent from current File Search holders could adopt a
file for an agent whose namespace held none of its vectors, for example after
the agent that embedded it was deleted. Priming now asks RAG for one chunk of
each legacy file under the agent's entity_id and records the namespace only
on a hit; a miss or an unreachable RAG keeps the file queued for embedding.
The data-schemas method no longer scans agents and matches untenanted records
as untenanted. The fake RAG server answers these presence checks from the
embeds it stores.
* fix: Require the Entity's Own Chunks and Keep Confirmed Vectors
RAG also returns chunks owned by the requesting user, so a presence check now
counts only chunks recorded under the agent itself. Once vectors are
confirmed, the turn skips the re-embed even if recording the namespace fails.
* fix: Bound the Legacy Search Check and Keep the Fake RAG Query Shape
The RAG presence check now times out (fileConfig.legacySearchProbeTimeoutMs,
5s by default) and falls back to embedding, so a stalled RAG cannot hang
priming. The fake RAG server records presence checks in their own list and
keeps the file_search query records it already returned.
* fix: Check Any Unrecorded Namespace Before Embedding a Search File
A file another agent embedded first lists only that agent, so the agent
whose older vectors went unrecorded skipped the check and embedded a second
copy. Priming now asks RAG for every agent File Search file that records no
embedding for the active agent, and recording adds the namespace to the ones
already there.
* fix: Ask RAG for Several Chunks So a User Copy Cannot Hide the Agent's
RAG ranks chunks across every owner of a file_id and, once the top one is
authorized, returns them all. A copy of an agent file embedded for the
requesting user could rank first with k: 1 and hide the agent's own chunks,
so the presence check now asks for ten and checks every owner.
* fix: Confirm Setup Embeddings in Shared-File Runs and Log Safely
The run-file host primes an agent's setup files on its own, so it now
receives the RAG presence check and the namespace recorder too; without
them a shared-file run could embed a legacy setup file a second time.
Failed checks are logged with getSafeErrorMetadata rather than the raw
error, which carries the vector store's response body.
* chore: Retire the DALL-E 3 Tool
OpenAI shut down dall-e-3 on May 12, 2026, so the built-in DALL-E 3 tool can no longer generate images on api.openai.com. Remove the tool, its manifest entry, registry definition, and env docs, along with the loadTools functions flag that only existed to register it. The OpenAI Image Tools cover the same use case. Stored agents that still list dalle load without it, and dalle stays in imageGenTools so past images keep rendering.
* test: Cover the Retired DALL-E 3 Tool in Mock Scenarios
* docs: Drop DALL-E from the README Image Generation List
* fix: Price 1-Hour Prompt Cache Writes at the 1-Hour Rate
* test: Cover 1-Hour Cache Write Pricing End to End
* test: Price Cache Scenario on the Configured Mock Model
* fix: Accept a 1-Hour Cache Write Rate in Endpoint Token Configs
* feat: Add Claude Haiku 5.5 Support
Haiku 5.5 (`claude-haiku-5-5`) matched none of the Claude family gates, so
every endpoint treated it as a legacy Claude 4 model: thinking went out as
`enabled` with a budget (400), sampling parameters were sent, thinking blocks
were not bound to the conversation prefix, and it resolved to a 200K context,
64K output and the default token rate.
Add a Haiku version parser and `hasAdaptiveHaikuThinking` (5.5 or later),
and include it in the adaptive thinking, block binding, omitted display,
sampling omission, explicit disabled, effort cap, 1M context and 128K output
gates. Unlike Sonnet 5.5, Haiku 5.5 still accepts `disabled` at effort high or
below, so "thinking off" sends `disabled` and clamps xhigh/max to high. The
settings panel keeps the thinking toggle and hides budget and sampling.
Register it in the Anthropic, Bedrock (`global.anthropic.claude-haiku-5-5`)
and Vertex default model lists, the 1M context map and the 128K output cap,
and price it at $0.10 / $0.50 up to a 100K prompt and $0.50 / $2.50 above,
with matching cache tiers.
Related to #17078, #16911 and #17025.
* test: Cover Claude Haiku 5.5 Parameter Panel
* test: Pin Haiku Scenarios to Model Specs
* fix: Keep Claude Haiku 5.5 Off Regional Vertex Endpoints
* fix: Keep Temporary Chats Out of Langfuse
* fix: Gate Forced-Ephemeral and Open Responses Turns From Langfuse
* fix: Treat Legacy and Chat Completion Temporary Turns as Untraced
---------
Co-authored-by: Joel Hirzel <joel.hirzel@eps.ch>
* 🧵 test: Cover Harmony Headers in Text Attachments Sent to OpenAI Models on Bedrock
A pasted text/plain attachment is sent inline as file context, so a harmony header such as `<|channel|>analysis` inside it reaches every later turn. OpenAI models on Bedrock answer that request with an event stream that closes before any event, which crashed the turn in @librechat/agents 4.0.4 with `Cannot use 'in' operator to search for 'tool_calls' in undefined`.
Drive LibreChat's own file-context formatting through the SDK's Bedrock model with a recorded response and assert the header reaches an OpenAI model neutralized and other model families unchanged.
* 📦 chore: Bump @librechat/agents to v4.0.5
* 📦 chore: Regenerate the Lockfile with npm 11 to Keep libc Constraints
* perf: Debounce People Picker Search
* perf: Index-Bound Word-Prefix Search for Users and Groups
Principal search and admin user search matched name, email and username
with case-insensitive regexes, which scan the whole users collection.
Users and groups now store lowercase, accent-folded token arrays derived
from each searchable field, indexed with tenantId, and searches match
anchored token prefixes. Schema middleware keeps the tokens in sync on
save, insertMany and update queries. Documents written before the tokens
existed stay findable through a fallback branch until
npm run migrate:search-tokens backfills them; startup warns while any
remain.
* perf: Build Search Token Indexes in the Backfill Migration
* fix: Reconcile Stale Search Tokens and Close Write-Path Gaps
The backfill now compares every document's tokens with its source fields and
repairs stale ones, so writes from an older server during a rolling deploy are
recoverable by rerunning it. Undefined assignments no longer clear tokens,
upsert inserts initialize every token field, every query word is required,
relevance scoring folds accents like the filter does, and the startup check
counts both collections in parallel and owns its error logging.
* perf: Drop the Second People Picker Debounce
SearchPicker already debounces query changes by 500ms; the extra 300ms delay
in UnifiedPeopleSearch stacked on top of it.
* fix: Match Nothing for Queries Over the Word Cap
Dropping the query word cap let one request build an unbounded filter. Restore
a 16 word cap, but a longer query now matches nothing instead of ignoring its
extra words, so a cap never produces a false positive.
* test: Cover Word-Prefix People Search and the Token Backfill End to End
* fix: Tokenize Fields an Upsert Copies From Its Filter
MongoDB copies equality conditions from an upsert's filter into the inserted
document, so their token fields now derive from that value instead of being
initialized empty.
* fix: Rank Accent-Folded User Matches Like the Search Filter
* test: Run the Token Backfill Without Blocking the Playwright Worker
* perf: Index Search Tokens Tenant First for Scoped Searches and Ignore Undefined Unsets
* test: Skip the Module-Scope Index Rebuild When the Scenario Runs the Backfill
* fix: Exit the Search Token Migration When Redis Clients Stay Open
* perf: Probe for Missing Search Tokens at Startup Instead of Counting Them
* test: Explain the Startup Probe the Warning Actually Issues
* fix: Keep Search Token Fields Out of Serialized Users and Groups
* fix: Keep the Admin Search Legacy Fallback Anchored at the Field Start
* fix: Score Groups Only on the Fields Search Matches
* perf: Start the Search Token Probe Alongside the Permission Checks
* fix: Warn at Startup When the Search Token Indexes Were Never Built
* fix: Score People Search Matches With the Filter's Word Separators
* perf: Check the Token Indexes Before Probing for Unmigrated Documents
* test: Drive the Failed Startup Probe Past the Index Check
* fix: Score People Search Matches Independently of Word Order
A backend jest worker keeps every module and transform it has loaded for its whole life and grows past three gigabytes on a packages/api shard. Share a 1GB workerIdleMemoryLimit from config/jest.workers.cjs and apply it to api, packages/api and data-schemas, as the client config already does.
* refactor: Drop Queue Reset Helper From The Client Queue Module
* refactor: Drop Unused Shortcut Getters And Subagent Batch Wrappers
* refactor: Move HITL Approval Payload Builder To Test Fixtures And Drop Dead Helpers
* refactor: Remove Unused Agent Helpers and Superseded Wrappers
* refactor: Remove Dead Auth, Middleware, Protection and Prompt Helpers
* refactor: Remove Dead MCP, File, Skill and Endpoint Code
* refactor: Remove Dead Stream, Telemetry, Utility and Type Exports
* chore: Drop Unused packages/api Dependencies From bun.lock
* refactor: Keep Published Compatibility and Deprecated packages/api Exports