* ♊ fix: Resolve Local JSON Pointer Refs & Sanitize Tool Search Schema for Gemini
Gemini/Vertex agents fail when MCP tools are attached, in two ways:
1. MCP servers with OpenAPI-derived schemas can emit local JSON pointer
refs (e.g. `#/properties/body/properties/start`). `resolveJsonSchemaRefs`
only resolves `#/$defs` and `#/definitions` refs, so these survive into
the request payload and Vertex rejects it with 400
'Invalid JSON payload received. Unknown name "$ref"'. Resolve any local
`#/...` pointer against the schema root (RFC 6901 unescaping, cycle
protection), and strip still-unresolvable `$ref` keys in
`sanitizeGeminiSchema` as a safety net.
2. When deferred tools are enabled, the injected `tool_search` schema
declares `mcp_server` as `oneOf: [string, string[]]`, which
`zod_to_gemini_parameters` rejects ('Gemini cannot handle union types').
`buildToolClassification` now accepts the agent provider and collapses
the union via `sanitizeGeminiSchema` for Google/Vertex only — the tool's
runtime (`normalizeServerFilter`) already accepts both forms.
Complements #13623, which sanitizes MCP tool schemas but not the injected
tool_search definition, and did not cover non-$defs local pointers.
Underlying converter limitation: langchain-ai/langchainjs#9691.
* style: format tool search schema assignment
* style: sort tool classification imports
---------
Co-authored-by: Danny Avila <danny@librechat.ai>
* fix: include conversation_starters in agent view and list responses
* test: cover conversation_starters in agent view and list projections
* test: include conversation_starters in agent list whitelist
---------
Co-authored-by: Danny Avila <danny@librechat.ai>
* 🤐 fix: Exclude Provider Secrets from HITL Pending Actions
Sanitize resolved model parameters before persisting them in the pending
action's resumeContext, and strip resumeContext/requestFingerprint from
every client-facing copy (SSE emit, reconnect gap-fill, resume state,
status route). The full record stays server-side for resume replay.
* 🤐 fix: Treat Header-Carrier Keys as Sensitive Wholesale
Google llmConfig places the Authorization header in customHeaders, and
header names like Ocp-Apim-Subscription-Key defeat name heuristics.
Match 'header' as a key fragment so every header-carrier object is
dropped rather than relying on exact carrier names.
* 🤐 fix: Strip Preconfigured Client Instances from Resume Params
Bedrock stores a BedrockRuntimeClient on llmConfig.client when PROXY or
a bearer token is configured; replaying it would also fold a mangled
client object into additionalModelRequestFields on resume.
* 🔒 fix: Prevent Cross-Tenant Role Grants on Shared Links
The shared-link access middleware falls back to a system-wide lookup so a
share owned by another tenant still resolves, then evaluates the ACL under
the share owner's tenant. It was passing the viewer's `role` from their own
tenant into that check. Role ACL principals are unqualified name strings, so
a tenant-B user with role USER could satisfy a tenant-A private share granted
to role USER (default role names collide across every tenant).
Pass the viewer's role only for same-tenant views; use `null` for cross-tenant
views so getUserPrincipals never builds a ROLE principal. `null` (not
`undefined`) is required: `undefined` re-derives the role via an unscoped
User lookup under runAsSystem for tenantId-less shares, reopening the bypass.
Widen checkPermission's `role` param to `string | null`. Adds regression
coverage for both the cross-tenant denial and same-tenant allow paths.
* 🔒 fix: Use authenticated user tenant for same-tenant role trust
Codex P2: share file routes (<img>/download) authenticate via
optionalShareFileAuth from the refresh cookie and never establish tenant ALS
context, so getTenantId() is undefined there. Comparing the share tenant to the
ALS context wrongly denied a legitimate same-tenant viewer their ROLE grant on
file/preview/download requests, even though the main share route authorized them.
Compare the share tenant against the authenticated user's own tenantId, which is
populated in both the JWT and cookie-auth paths (tenantContextMiddleware itself
derives the ALS tenant from user.tenantId, and req.tenantId is never set, so
user.tenantId is the authoritative, non-spoofable source). Adds a regression test
for the no-ALS-context cookie-auth file request.
* feat: Add explicit Use All Skills toggle to the Skills section
Adding a skill to an agent could silently mean "all skills enabled"
(skills_enabled on with an empty allowlist), and the only master control
was the Agent Skills kill switch buried in the Advanced panel, which
implied skills required a trip to Advanced at all.
- Add a "Use all skills" switch directly in the builder's Skills
section: on = the agent gets every skill the user can access,
including skills added in the future (skills_enabled true, empty
allowlist). While on, the per-skill list and Add button are hidden
and the header shows an All badge; turning it off restores the
previously selected skills.
- Remove the kill switch from the Advanced panel.
- Simplify skillsEnabledTransition so the master flag tracks the
selection on every edit, which also re-enables agents left with a
selection but a disabled flag by the old kill switch.
* fix: Normalize legacy disabled allowlists and scope the use-all stash per agent
Agents saved with the removed Advanced kill switch off (or predating the
skills_enabled flag) load a non-empty allowlist with the master flag not
true. The builder rendered that selection as active while the runtime
ignored it, with no control left to re-enable. Normalize on form load so
the flag matches the displayed selection.
The use-all stash lives in a ref and ToolsSection is not remounted when
switching agents (only the form resets), so toggling off on another agent
could restore the previous agent's allowlist. Clear the stash when the
agent id changes.
getTransactionSupport initialized transactionsSupported to false and only assigned it on a cache miss (transactionSupportCache === null), so on a cache hit it returned false regardless of the cached value. After the first bulkUpdateResourcePermissions call populated the cache with true, every later call reported false and the bulk permission writes silently stopped running inside a MongoDB transaction, losing atomicity. Return the cached boolean on a cache hit; the cache-miss path still probes via supportsTransactions. Adds a regression test.
* 🌏 fix: guard IME composition on Enter in prompt name/labels and dynamic tag inputs
* style: sort imports in DynamicTags per repo import-order convention
---------
Co-authored-by: greymoth <246701683+greymoth-jp@users.noreply.github.com>
* fix: fall back to _id for user id in createSafeUser
* chore: reorder imports in env.spec.ts
---------
Co-authored-by: Danny Avila <danacordially@gmail.com>
* 🧯 fix: Harden Principals Cache Invalidation and Lock-Wait Paths
Follow-up hardening for the group-membership principals cache:
- Coalesce deferred transactional invalidations into one session `ended`
listener so many membership writes in a transaction cannot trip the
emitter's max-listeners warning
- Re-attempt the build lock inside the lock-wait poll so readers take over
when the holder skips its write (invalidated away, failed, or crashed)
instead of stalling for the full wait budget
- Read cache builds from the primary so secondaryPreferred deployments
cannot pin a lagging secondary's pre-mutation memberships for the TTL
- Decouple the delayed stale-rewrite eviction pass from build locking via a
crossProcess store marker, so USER_PRINCIPALS_LOCK_TTL_MS=0 disables
locking only
- Treat aggregation-pipeline bulk updates touching memberIds as
indeterminate (namespace clear) instead of silently skipping invalidation
* ⏲️ fix: Floor the Stale-Eviction Delay for Lockless Cache Builds
The second invalidation pass ran at only 500ms when build locking is
disabled (USER_PRINCIPALS_LOCK_TTL_MS=0), so a cross-container build slower
than that could still re-cache revoked memberships until the TTL. The store
now supplies an explicit staleEvictionDelayMs (lock wait plus one build
round-trip, floored at 3s), keeping the default locked budget unchanged.
* feat: redesign the agent builder tools, skills, and advanced panels
Replace the stacked capability/MCP/skill/tool/action form sections with a unified tools marketplace, per-item configuration dialogs, and a consolidated Advanced panel.
- unified tools marketplace (catalog, sidebar, polymorphic cards/rows) covering built-in capabilities, plugins, MCP servers, and actions, each with a detail/config dialog
- dedicated Skills picker and a Tools section with selected-item summaries and empty states
- redesigned action editor and authentication dialog (method cards, segmented controls)
- rebuilt Advanced panel: orchestration hub (subagents, handoffs, chain), max steps, skills kill-switch, copyable agent id
- restyled version history (timeline, tool/capability counts, in-app restore confirmation)
- shared component updates (Radio, Input/Textarea, dropdown z-index, dialog primitives) and keyboard-only focus rings via useInputModality
- format-hint placeholders for tool credential fields
- sanitize numeric parameter inputs to prevent comma truncation
* feat: refine agent builder tools, actions, and MCP sections
* feat: restore Memory capability toggle in agent builder tools catalog
* feat: refine agent tools picker (skills, MCP connect/OAuth, web search)
- Skills picker: per-card visibility (public) and shared-author badges,
category filtering, and an in-place Create skill flow that auto-attaches
the new skill without leaving the builder
- MCP: inline Connect button in the first dialog plus a dedicated OAuth
dialog (continue, copyable URL, QR code) shown only when OAuth is required
- Web search: auth-aware affordance, settings cog when user-provided and an
info icon when system-defined
- Remove orphaned com_ui_unavailable/com_ui_initializing keys and the dead
Tools/MCPToolItem component
* refactor: streamline MCP OAuth dialog
- Remove the Cancel button (the flow auto-closes on connect / times out)
- Show the URL in a read-only single-line scrollable input (cursor moves
through it, not fully visible) with the shared CopyButton's smooth
Copy/Check icon swap, matching the OAuth callback-URL field
- Put the primary Continue with OAuth action (icon trailing) and an
icon-only QR toggle together in a row at the bottom, below the URL
- The QR reveals between the description and the URL with a smooth height
animation (grid-rows 0fr to 1fr, matching MCPToolItem's reveal)
* feat: smoothly collapse MCP connect button once connected
* feat: cross-fade MCP tools between loading, list, and empty states
* feat: show MCP server icon in OAuth dialog title
* fix: vertically center OAuth dialog title against the MCP icon
* feat: smoothly animate auth field changes in the MCP server dialog
* feat: match Code Interpreter file upload to the File Search dropzone
Swap Code Interpreter's thin btn-neutral bar for the same dashed dropzone
(DropzoneContent + dropzoneClassName) File Search already uses, so the two
capabilities' upload UIs are consistent.
* feat: show a saving spinner and allow cancelling credential edits
Drive the tool credential Save button from the real mutation state so it
shows a spinner while the request is in flight, and add a Cancel button
when re-editing already-saved credentials so the edit can be dismissed.
* feat: make the skills create button a compact icon button
* fix: restore MCP attach semantics and confirmations in the tools marketplace
Connecting an MCP server from the item dialog now enables all of its tools
once the connection settles, deselect-all keeps the server attached via its
placeholder token instead of detaching it, adding a server writes the token
so a zero-tool attachment survives a save, and removing a server from the
tools list asks for confirmation again. Consume-only servers are excluded
from the catalog, matching the old select dialog.
Also share the catalog/selection pipeline between ToolsSection and the
marketplace through useAgentItems, hoist NEW_ACTION_ID next to ActionItem,
drop unused status/view union members and stale TranslationKeys casts,
document the phase-2 Favorites/Made-by-you views, fix the needs-setup dot
semantics and card focus suppression, remove the redundant close button in
CreateSkillDialog, move useInputModality into @librechat/client so external
consumers can mount it, and delete dead files and orphaned translation keys.
* fix: scope tooltip elevation to dialogs and restore dialog close button size
Tooltips go back to z-150 globally; inside a dialog they now borrow the
depth-aware popover z-index so they still clear nested dialogs (the Tool
Library item dialog) without outranking freshly opened modals everywhere
else. The default dialog close icon returns to its original size, and the
lc-field pointer-focus suppression ships with the package next to Input and
Textarea so external consumers get the whole mechanism from @librechat/client.
* feat: add favorites for marketplace tools, MCP servers, and skills
Reintroduce the favorite star from the old skill picker, generalized to
every marketplace item kind except per-agent actions. Cards in the Tool
Library and Skills dialogs get a hover-revealed star (always visible once
favorited), and the existing Favorites views in both dialogs now filter to
starred items.
Favorites persist in a dedicated ToolFavorite collection, one document per
(user, itemType, itemId) with a unique compound index, exposed through
atomic per-item PUT/DELETE endpoints under /api/user/settings/favorites/
tools. Per-item writes are idempotent and race-free across tabs/devices
(the unique index backstops concurrent toggles), reads are a single
index-backed query capped at 100 favorites per user, and the client keeps
React Query as the source of truth with optimistic updates. Handlers live
in @librechat/api with a thin route wrapper; methods follow the
data-schemas factory pattern with tenant isolation.
The favorites filter now matches on compound kind:id keys instead of bare
ids, closing a cross-kind collision where a tool and a skill sharing an id
would both match. The skill-favorites data-service stubs and the reserved
TUserFavorite.skillId field are replaced by the new tool-favorites service.
* feat: anchor the favorite star at the card's right edge
Swap the ToolCard action-bar order so the star sits rightmost with the
configure/info icon to its left. Every card can be favorited but only some
are configurable, so anchoring the star keeps it in a consistent position
across the grid.
* chore: remove translation keys orphaned by the tool library redesign
* fix: gate marketplace creation entries and resolve off-page selected skills
The Create New menu exposed MCP server creation to users without the
MCP_SERVERS create permission and action creation on deployments with the
actions capability disabled; both entries are now gated like their
pre-redesign counterparts, and the button hides when neither applies.
Selected skills missing from the first catalog page (limit 100) were
dropped from the Skills section entirely, leaving them impossible to
inspect or remove. useResolvedSkills restores the per-id lookup: off-page
skills are fetched individually and confirmed misses (deleted or no longer
shared) stay visible under an Unavailable skill placeholder so the stale
allowlist entry remains removable.
* fix: refetch favorites when toggled before the list loads, lint fixes
An optimistic favorite written over an unpopulated cache seeded the list
with only the toggled item, and cancelQueries killed the initial fetch
that would have corrected it, hiding existing favorites until reload. The
optimistic write now only applies over known data; otherwise onSettled
invalidates so the authoritative list is refetched.
Also unnest the version date-label ternary and drop an unused form watch
flagged by CI.
* fix: sync skills_enabled with selection edits and hydrate agent file entries
skills_enabled is the master opt-in for the skill allowlist, and an empty
allowlist with the flag on means the full accessible catalog. Selection
edits now sync the flag on empty/non-empty transitions via a shared
skillsEnabledTransition helper: picking the first skill enables it so the
choice takes effect on save, and removing the last one disables it so the
agent doesn't silently escalate to every skill. Mid-selection edits leave
the flag alone, preserving the Advanced kill switch's
disable-without-clearing behavior.
Agents loaded from the API carry only tool_resources.*.file_ids; the
client-only context/knowledge/code file entry arrays were read directly,
so existing attachments rendered as empty and could not be removed. A new
useAgentFileEntries hook restores the legacy derivation (agent files query
merged into the file map via processAgentOption) and now feeds AgentConfig,
the item dialog, and the selected-items pipeline.
* fix: hide plugin tools from the marketplace when the tools capability is off
buildCatalog gated built-ins, MCP, and skills on their capabilities and
permissions but pushed regular plugin tools unconditionally, so deployments
that removed the tools capability still offered attachable tool cards in
the marketplace. The loop now requires AgentCapabilities.tools, matching
the old Add Tools gate.
* fix: strip legacy MCP tokens on removal, guard action creation, model button spacing
MCP selection accepts every historical token format (server placeholder,
raw server name, mcp_-prefixed, and per-tool ids in prefix/suffix shapes)
but removal only filtered the new placeholder plus the server's current
tool ids, so a legacy token left the server permanently selected and its
tools still expanded after save. Selection and removal now share a
matchesMcpServer predicate.
Creating an action from the marketplace on an unsaved agent opened an
editor whose save was guaranteed to fail; it now surfaces the existing
save-the-agent-first error, matching the action-removal guard.
The model picker button keeps its tight px-1 with a provider icon but gets
px-3 in the empty Select-a-model state so the placeholder is not flush
against the border.
* fix: strip legacy prefix MCP tokens in useRemoveMCPTool
The hook only filtered the raw server name and suffix-delimiter tokens,
so confirming removal in the selected-tools section left persisted
prefix-format tokens (mcp_<server>, mcp_<server>_<tool>) in the form and
the row reappeared as selected. It now shares the matchesMcpServer
predicate with the selection logic so removal can never lag selection.
* fix: exact MCP token matching and keep errored skill lookups removable
The mcp_<server>_ prefix clause in matchesMcpServer was invented by the
redesign, not a persisted format (mcp_prefix is only ever used as the
exact mcp_<serverName> pluginKey), and it claimed longer server names
sharing a prefix: with servers github and github_extra, removing github
also stripped github_extra's tokens. The predicate now only matches exact
or delimiter-bounded shapes.
An off-page selected skill whose per-id lookup failed with a transient
error (retry disabled) vanished from the selected list until remount. Any
settled lookup failure now keeps the placeholder entry so the allowlist id
stays visible and removable; only in-flight lookups are briefly hidden.
* fix: route file-backed built-in removal to the file manager
Code Interpreter and File Search stay selected while they hold code_files
or knowledge_files, so removing them by flipping the capability flag left
the row visible and unremovable. Their removal now opens the config dialog
where the files are managed, mirroring the file-only context built-in;
with no files attached the flag still toggles off for a clean removal.
* fix: preserve negative values in numeric parameter inputs
sanitizeIntegerInput stripped every non-digit, so typing -1 in a numeric
parameter field became 1. That broke Google thinkingBudget, where -1 is
the dynamic/auto-thinking sentinel (range min is -1): users could no
longer select auto and risked sending a one-token budget. The sanitizer
now takes an opt-in allowNegative flag that keeps a single leading minus,
and DynamicInput passes it when the field's range permits negatives.
Thousands-separator cleanup is unchanged for all other fields.
* fix: keep in-progress negative numeric input and localize the actions heading
Typing a leading minus in a negative-capable numeric parameter (Google
thinkingBudget) sanitized to a lone '-', which was then coerced by
Number('-') to NaN, so the sign could not be typed before the digits. The
lone '-' is now stored as a string until a digit resolves it to a number,
matching how the empty-string case is already handled.
The agent builder actions panel heading hard-coded 'Add'/'Edit actions';
it now uses com_assistants_add_actions and a restored
com_assistants_edit_actions key so non-English locales translate it.
* chore: fix import order drift flagged by CI
* fix: treat pending web-search auth verification as needs_setup
While useVerifyAgentToolAuth is still loading, data is undefined so
web_search was not marked needs_setup, and the marketplace card takes the
direct-enable path only when status is not needs_setup. On a slow
connection a click before the response arrived enabled web_search without
collecting the required user-provided key. The auth map now flags
web_search needs_setup while the query is loading, routing the click to
the config dialog; once verification resolves, a system-defined deployment
or a satisfied key clears the flag for a direct toggle.
* test: update agent builder e2e selectors
---------
Co-authored-by: Danny Avila <danny@librechat.ai>
* feat: eager HITL checkpoint cleanup on expiry + deletion, full-wiring e2e
Follow-up to the lazy checkpointer (#14024): two paths still left a paused
run's durable checkpoint to the 24h Mongo TTL, and no test exercised the
whole HITL seam with real components.
1. Approval expiry: GenerationJobManager.setApprovalExpiredHandler(fn) — a
non-destructive host hook fired after expireApproval's CAS succeeds
(periodic sweeper AND stale-submit path), safe on startups that run
constructor defaults. Both startups (index.js configureGenerationStreams,
experimental.js) register a handler that prunes the checkpoint, resolving
config lazily per expiry (streamId === conversationId === thread_id).
2. Conversation deletion: deleteConvos now returns the deleted
conversationIds; the three deletion paths (DELETE /convos, DELETE
/convos/all, account deletion) prune them via the new bulk
deleteAgentCheckpoints (one $in deleteMany per collection). The delete
routes gain configMiddleware for the checkpointer config.
3. Full-wiring e2e (hitlCheckpoint.e2e.spec.js): real SDK Run driven by
FakeChatModel calling a gated tool, real PreToolUse/humanInTheLoop wiring,
real LazyMongoSaver over mongodb-memory-server, real GenerationJobManager,
real /resume controller via supertest. Asserts: clean turn persists
nothing; error turn persists nothing; pause -> HTTP approve -> gated tool
executes exactly once -> finalize prunes the checkpoint; expiry prunes the
abandoned pause eagerly.
Tests: 3 handler unit tests (pendingAction.spec), 2 bulk-prune integration
tests (checkpointer.integration.spec), convos route + deleteUser specs
updated, 4 e2e scenarios. 207 tests green across changed areas.
* fix: tenant-scoped expiry prune, store-won expiry relay, resilient deleteConvos ids
Codex round 1 on #14123 — all three valid:
1. The approval-expired handler now receives the expired JOB so both startups
resolve config in the paused job's tenant/user scope (getAppConfig({userId,
tenantId})) — a tenant checkpointer override no longer sends the prune to
the base config's collections. expireApproval fetches the job best-effort.
2. Multi-replica: when RedisJobStore.cleanupRequiresActionIndex wins the
expiry CAS on another replica, this replica's sweeper relay branch now runs
the approval-expired cleanup too (prune is idempotent) — store-driven
expiry no longer bypasses the hook.
3. deleteConvos: post-delete cleanup (deleteMessages, project stats refresh)
is now best-effort — the conversations are already gone, so throwing hid
the deletion and dropped the conversationIds the checkpoint prune needs,
unrecoverable on retry. Updated the existing tag-decrement-on-failure test
to the new contract (ids still returned).
Tests: handler-receives-job, store-won relay path, ids-survive-cleanup-failure.
134 tests green across changed suites.
* fix: relay cleanup independent of cached errorEvent; enter tenant ALS context
Codex round 2 on #14123:
1. The sweeper's relay branch gated BOTH the terminal-error emit and the new
checkpoint cleanup on !runtime.errorEvent — but a reconnect seeds errorEvent
from the aborted job (runtime-state creation), which then suppressed the
cleanup entirely. The emit stays gated; the idempotent cleanup now runs
independent of the cached error, once per runtime lifetime
(approvalCleanupRan flag — the aborted job is swept repeatedly).
2. Passing userId/tenantId to getAppConfig only keys the config cache; the
Config query is ALS-scoped by the tenant-isolation plugin. Both startup
handlers now ENTER the paused job's tenant context via tenantStorage.run
before resolving config + pruning, so a tenant checkpointer override is
honored in strict and non-strict modes.
Tests: relay-cleanup-with-cached-error (reconnect simulation), repeated sweeps
run the cleanup once. 27+4 green.
* fix: dedup expiry cleanup across winner and relay paths
Codex round 3 (P3): expireApproval ran the handler without marking the
runtime's approvalCleanupRan flag, so the next sweep's relay branch (the
aborted job outlives expiry for the completed-job TTL) ran the cleanup a
second time. The dedup now lives inside runApprovalExpiredHandler — the
single choke point both paths call — set-before-run, once per runtime
lifetime. Test: local expiry followed by a sweep fires the handler once.
* 🗃️ perf: Cache Group Memberships for ACL Principal Resolution
Continues #14069: caches resolved group-membership ids per member key in a
new USER_PRINCIPALS namespace so repeated permission checks skip the group
query, with exact invalidation on every membership mutation, same-process
build dedup, and optional Redis cross-container build locks.
Co-authored-by: Peter Rothlaender <peter.rothlaender@ginkgo.com>
Co-authored-by: Joachim Keltsch <joachim.keltsch@daimlertruck.com>
* 🧵 fix: Defer Transactional Invalidation and Gate No-Op Bulk Clears
Codex round-2 findings on the principals cache: membership writes inside a
transaction now defer cache invalidation until the session ends so concurrent
readers cannot re-cache pre-commit state with no later correction, and
bulkUpdateGroups skips invalidation entirely when MongoDB reports no modified
or upserted documents. userGroup.spec.ts now runs on a single-node replica set
so the deferral is covered by a real transaction.
* 🌐 fix: Evict Cross-Process Stale Rewrites and Scope Entra Sync to Tenant
Codex round-3 findings: a delayed second invalidation pass (lock wait plus a
short grace) now evicts membership entries that a build in another container
re-cached after the first delete, and syncUserEntraGroupMemberships establishes
the user's tenant ALS context when the OAuth callback runs it pre-middleware,
so tenant-scoped principal keys are invalidated (and sync queries and created
groups are scoped) exactly like authenticated reads. Deferred transactional
invalidations snapshot the caller's ALS so they keep tenant scoping.
---------
Co-authored-by: Peter Rothlaender <peter.rothlaender@ginkgo.com>
Co-authored-by: Joachim Keltsch <joachim.keltsch@daimlertruck.com>
* ⚡ feat: Persist HITL checkpoints only on pause (skip clean-exit writes)
With `durability: 'exit'` (set by the SDK whenever a checkpointer is active) LangGraph
persists ONE checkpoint at the exit boundary on EVERY run — paused or not. So a non-paused
HITL turn writes a dead checkpoint whose only fate is to be pruned by deleteAgentCheckpoint:
pure write+delete churn on the common path, given HITL only ever resumes an *interrupt*
checkpoint.
`InterruptOnlyMongoSaver` (a MongoDBSaver subclass) persists only interrupt checkpoints and
discards clean-exit ones, so a non-paused turn writes nothing.
How it tells them apart (verified empirically against @langchain/langgraph, not docs):
when a run interrupts, the runner calls `putWrites` with the `INTERRUPT` ("__interrupt__")
channel for the checkpoint it's about to create, and that write's `config.checkpoint_id`
equals the `checkpoint.id` of the `put` that immediately follows. A clean exit calls `put`
with no preceding interrupt `putWrites`. So we record the checkpoint id of any interrupt
`putWrites` and persist a `put` only when its `checkpoint.id` was so marked. Keying on the
globally-unique checkpoint id (not thread_id) keeps this correct even when two runs race on
the same conversation (the job-replacement scenario).
Correctness is preserved end-to-end: interrupt checkpoints + their pending writes persist
exactly as before (resume unchanged); clean checkpoints were only ever written-then-pruned,
so not writing them is observationally equivalent. The eager prune stays as the backstop.
Tests (mongodb-memory-server): a bare put() is discarded; an interrupt-seeded checkpoint is
persisted with its __interrupt__ pending write; and an end-to-end real-graph run writes 0
checkpoints on a clean completion and a resumable one on interrupt.
NOTE: a non-paused turn's deleteAgentCheckpoint now finds nothing to delete (a 0-match
no-op) — a follow-up can skip that call entirely once the lingering-abandoned-pause cleanup
role is reassigned to the TTL + expiry sweeper.
* ⚡ feat: Drop the redundant clean-path checkpoint prune
With the lazy checkpointer (InterruptOnlyMongoSaver) a non-paused turn no longer writes a
clean-exit checkpoint, so the post-completion prune in chatCompletion's finally had nothing
left to delete. It was also already redundant: every fresh turn runs a pre-run prune
(`deleteAgentCheckpoint` before `processStream`) that clears any checkpoint orphaned by a
prior abandoned pause — verified empirically that a lingering interrupt checkpoint WOULD
otherwise poison a fresh turn (LangGraph continues the abandoned state + re-interrupts), and
that the pre-run prune is what prevents it. The Mongo TTL remains the backstop, and the
resume path still prunes after a successful finalize.
Removing the clean-path prune also deletes its job-replacement race surface (round-17 F21):
an older run's late finally can no longer delete a newer paused run's checkpoint, because
there is no longer a clean-path prune to race. Dropped the now-dead F21 predicate test.
Net per non-paused HITL turn: from {pre-run prune + checkpoint write + post-run prune} down
to {pre-run prune} — no write, no post-completion delete.
* 🛡️ fix: Anchor any pending-write checkpoint; stale-only eviction (Codex)
Broaden the lazy saver's keep-rule from "interrupt-only" to "persist any checkpoint that
carries pending writes" (renamed InterruptOnlyMongoSaver → LazyMongoSaver). This makes it
robust to delta-channel graphs without changing behavior for LibreChat's graph:
- K1 (P1): a delta-channel graph can write a synthetic PARENT/anchor checkpoint (no
__interrupt__ mark) that the interrupt checkpoint then points at, with the delta writes
stored under the parent id. The old rule discarded that parent, breaking delta-state
resume. Now any checkpoint that received putWrites is persisted, so the anchor parent and
its writes survive and resume can walk the chain.
- K3 (P2): for the same reason, clean delta-write rows are no longer orphaned — their
checkpoint is persisted alongside them. (For LibreChat's standard Annotation/messages
graph a clean run makes no putWrites at all — verified empirically — so the common path
still writes nothing and the optimization is unchanged.)
- K2 (P2): the 1024 FIFO cap could evict a valid in-flight id whose put() was just behind
Mongo I/O, mis-classifying its interrupt checkpoint as a clean exit. Replaced with
time-based eviction: only ids older than 5 min (a put always follows its putWrites within
ms) are swept; a recent in-flight id is never dropped, and the map grows rather than evict
a valid id if nothing is stale.
New integration test: a checkpoint anchored by a NON-interrupt write is persisted. Full
agents/HITL suites green (108).
* style(checkpointer): fix import order to satisfy sort-imports CI
* fix(checkpointer): don't persist failed-turn (error-only) checkpoints
LazyMongoSaver anchored on ANY pending write, so a non-paused turn that
errors (LangGraph records an __error__ write then a put) was persisted and,
with the clean-path prune removed, lingered until the next fresh-turn prune
or the Mongo TTL. Anchor only on resumable writes — INTERRUPT or a real
(non-__-prefixed) state/delta channel — so error/bookkeeping-only checkpoints
are discarded at the source. Addresses Codex P3.
Codex P2 (delta-stub parent orphan) is not reachable: the SDK graph uses
standard Annotation/MessagesAnnotation channels (no DeltaChannel), and under
durability:'exit' putWrites precedes put with a parentless boundary
checkpoint — probe-confirmed against @langchain/langgraph@1.4. Documented the
durability:'exit' invariant the saver depends on.
Tests: error-only put discarded; e2e throwing graph persists 0 checkpoints.
* fix(checkpointer): drop bookkeeping-only write batches, not just the checkpoint
The prior fix stopped the failed-turn CHECKPOINT from persisting, but putWrites
still forwarded the __error__ batch to MongoDBSaver.putWrites — writing a row to
agent_checkpoint_writes whose parent checkpoint is then discarded. With the
post-run deleteThread removed, that orphan row lingered until the Mongo TTL or
the conversation's next pre-run prune. putWrites now drops a non-resumable
(bookkeeping-only) batch entirely instead of forwarding it.
Probed against a real MongoDBSaver (mongodb-memory-server): a throwing graph now
leaves 0 checkpoints AND 0 write rows (was 0 + 1 orphan), while interrupt->resume
is unaffected — the __interrupt__ write is resumable so it is still forwarded.
Addresses Codex P2 (round 3).
Tests: error-only put leaves no checkpoint and no write row; e2e throwing graph
leaves both collections empty; new e2e interrupt->resume completes with the
approval value.
* fix(checkpointer): un-anchor a checkpoint whose putWrites failed; freshen comments
Self-review findings on the converged PR:
1. LangGraph dispatches put() concurrently with putWrites (probe-confirmed on
1.4.5), and put() still completes when putWrites rejects — so a transient
Mongo failure during the interrupt write could persist a checkpoint whose
__interrupt__ row is missing (an unresumable phantom pause). putWrites now
deletes the write anchor on rejection (best-effort) and rethrows, so that
put() discards the checkpoint instead. The pre-recorded anchor stays where
it is — recording after the await would drop slow-I/O interrupts on the
success path, which the same probe showed is reachable.
2. Renamed leftovers: two comments still said InterruptOnlyMongoSaver; the
class is LazyMongoSaver.
3. Documented why the pre-run prune is deliberately unconditional per HITL
turn (any cheaper gate can go stale across replicas and skip the prune
exactly when an orphaned interrupt exists).
Test: failed putWrites → subsequent put persists nothing (14/14 green).
* fix(checkpointer): bookkeeping write batches follow their checkpoint's fate
The round-3 rule dropped bookkeeping-only putWrites batches (__error__/
__resume__/__no_writes__) unconditionally — batch-scoped, when the decision
must be checkpoint-scoped. Probe-confirmed (langgraph 1.4.5, durability:'exit'):
a Send fan-out that pauses on one sibling records the completed siblings as
pure __no_writes__ batches on the RETAINED interrupt checkpoint; dropping those
markers makes resume re-execute the completed siblings (side effects measured
twice). Addresses Codex M2 (P2).
putWrites now PARKS a bookkeeping-only batch in memory until the checkpoint's
fate is known: forwarded when the checkpoint is anchored (or was just
persisted — put is dispatched concurrently), dropped when put discards it. Net:
an errored turn still leaves nothing durable (0 checkpoints, 0 write rows),
and a retained checkpoint stores byte-for-byte what a plain MongoDBSaver would.
Codex M1 (__resume__ lost on re-pause) did not reproduce: the re-pause emits
[__interrupt__,__resume__] as ONE batch (anchored, forwarded whole) and a
second resume on a rebuilt graph replays both answers correctly — but the
fate-scoped buffering now covers a lone __resume__ batch in any ordering too.
Tests: bookkeeping preserved on a retained checkpoint in either arrival order;
e2e Send-sibling pause/resume with side-effect counters (was {a:2,c:2} under
the drop rule, now {a:1,c:1}); error-only turn still leaves both collections
empty. 16/16 green.
* 🪝 feat: Programmatic tool-approval hook seam (configurable beyond on/off)
Adds a process-wide registry so host code can plug context-aware PreToolUse decision
hooks into the tool-approval policy, composing with the static
`endpoints.agents.toolApproval` config instead of replacing it.
- `registerToolApprovalHook(factory, { matcher? })` — register a factory that builds a
PreToolUse hook per run from a ToolApprovalHookContext (userId, conversationId, tenantId,
appConfig); return undefined to opt the run out. Returns an unregister fn.
- `buildHITLRunWiring(policy, context)` now registers the static-config policy hook as the
baseline, then layers each resolved host hook after it. Decisions fold in the SDK as
deny > ask > allow, so a host hook can only TIGHTEN a configured ask/deny — it can never
silently auto-approve past policy (to loosen, change the static policy). updatedInput /
allowedDecisions follow the SDK's last-writer-wins, so host hooks win over the baseline.
- `createRun` threads the per-run context (user / conversation / tenant / appConfig) into
the wiring; non-HITL and HITL-disabled runs never invoke any factory.
This unlocks dynamic policy the static name-lists can't express — per-args (e.g. ask before
write_file outside a workspace, the SDK's createWorkspacePolicyHook shape), per-agent,
per-user. Inert until tool approval is enabled and the caller is hitlCapable.
Tests: registry register/unregister/opt-out/order (hooks.spec.ts) + wiring composition,
context passthrough, and disabled-path inertness (runtime.spec.ts). Full HITL suite green.
* 🪝 feat: Config-driven tool-approval hook loader (librechat.yaml → hook modules)
Lets operators declare programmatic tool-approval hooks in config instead of code, so the
registerToolApprovalHook seam is usable without a custom build.
- Config (data-provider): `endpoints.agents.toolApproval.hooks[]`, each entry
`{ module, matcher?, options? }`. `module` is a bare package name or a path (resolved
against the app root); its default export is a builder `(options?) => ToolApprovalHookFactory`.
- Loader (@librechat/api `loadToolApprovalHooks`): imports each module, builds the factory
with the entry's options, and registers it (with its optional tool-name matcher). Reload-
safe (each call first unregisters its previous batch, leaving code-registered hooks alone)
and robust — an unimportable module / non-function export / throwing builder is logged and
skipped, never crashing startup or blocking the other hooks. Importer is injectable for tests.
- Startup (api/server/index.js): loads the configured hooks once after appConfig resolves.
SECURITY: modules are dynamically imported + executed in-process; this is admin-level config,
documented as trusted-code-only.
Tests: 9 loader cases (default/no-default export, options passthrough, bad-export skip,
builder-returns-non-function skip, import-failure resilience, continue-past-bad-entry,
reload de-dup). Full HITL suite green (80).
* 💄 style: Sort imports in HITL hook spec files (CI sort-imports:check)
* 🛡️ fix: Harden tool-approval hook loader (Codex review)
Six P2 findings on the hook loader / startup wiring:
- CJS/transpiled interop: unwrap a nested `default` (TS/Babel `exports.default = fn`
surfaces through import() as `{ default: { default: fn } }`) before rejecting a module,
so documented default-export hook modules actually load.
- Validate the matcher regex at load time and skip invalid ones — the SDK compiles it with
`new RegExp` at run-build time, where a bad pattern would throw out of buildHITLRunWiring
and break EVERY HITL run instead of just skipping the one bad hook.
- Honor the `enabled` kill switch: startup now passes hooks to the loader only when
toolApproval is enabled, so a disabled endpoint imports/runs nothing (and unregisters any
prior batch).
- Resolve app-root-relative paths without a leading dot: a bare specifier that is a real
file under basePath (e.g. `config/hooks/workspace.js`) resolves as a path; scoped/other
bare names still import as packages.
- Base-config-only: documented that hooks register once process-wide at startup and are NOT
reloaded from per-role/user/tenant overrides — encode per-tenant logic inside the hook.
- Wire the loader into the clustered startup path (api/server/experimental.js) too, not
just the standard server.
Tests: CJS-interop unwrap, invalid-matcher skip (+ sibling still loads), and specifier
resolution (app-root file / bare package / ./relative). Full HITL suite green.
* 🛡️ fix: Read tool-approval hooks from base config in clustered startup (Codex)
The clustered experimental.js path read toolApproval from getAppConfig() (which merges DB
__base__ overrides with no principal), so a DB override could enable/disable/replace
toolApproval.hooks and import those modules in every worker — violating the base-config-only
contract and diverging from the standard server. Fetch getAppConfig({ baseOnly: true })
specifically for the hook loader, matching api/server/index.js.
waitFor resolves as soon as BookmarkNav's data hook has fired once, but the Suspense resolution commit can still have a trailing render pass pending on slow runners (Windows CI shards). The first stream tick then flushes that leftover pass alongside the tick, inflating the memoized children's render counts past the captured baseline (Expected: 1, Received: 2). Flush pending commits with an empty async act() before capturing baselines.
getUserPrincipals resolves a user's ACL principals on nearly every
authenticated request. It fetched full group documents (including entire
memberIds arrays) only to read each group _id, and always issued a
separate User lookup for idOnTheSource.
- Project { _id: 1 } on the memberIds group query so it returns only ids
and can be served from the { memberIds: 1 } index instead of fetching
and decoding whole group docs.
- Accept role and idOnTheSource from the already-loaded request user and
thread them from the capability middleware, collapsing the hot path to
a single indexed group query (idOnTheSource: null means known-local).
* 🧠 fix: Default Bedrock thinking maxTokens to model max output
Thinking tokens share the maxTokens output budget with tool-call
arguments (e.g. a create_file content), so the low Bedrock defaults
(8192 for enabled thinking, ~4096 server-side for adaptive when unset)
truncated large authored files mid-argument — surfacing as
OutputTruncationError once reasoning actually emits.
Default maxTokens to the model's full max output via
anthropicSettings.maxOutputTokens.reset(model), mirroring the
direct-Anthropic path. Explicit maxTokens/maxOutputTokens are respected.
* fix: canonicalize number-first Claude aliases before resolving max output
* 🧠 fix: Apply Bedrock thinking config to bare inference-profile model IDs
The Bedrock request parser gated thinking config, sampling handling, and the
anthropic_beta headers on the model ID literally containing `anthropic.`. When
a deployment uses an application inference profile, the LibreChat model ID is a
bare `claude-*` (e.g. `claude-sonnet-5`) that maps to the profile ARN — so the
gate never matched, no `thinking` config was sent, and reasoning models
returned empty thinking blocks (most visibly: Claude Sonnet 5 never streamed
reasoning, while `us.anthropic.claude-opus-4-8` did).
Match on the `claude` family token instead of the `anthropic.` prefix so
prefixed (`anthropic.`, `us.`, `global.`) and bare inference-profile IDs are
handled identically. Verified e2e against live Bedrock via the agents SDK: a
bare `claude-sonnet-5` now sends `{type:'adaptive', display:'summarized'}` and
streams reasoning. Non-Claude Bedrock models (llama/cohere) and pre-thinking
Claude (3.5 sonnet) are unaffected.
* 🧹 fix: Strip stale thinking fields for non-thinking Claude Bedrock IDs
Follow-up to the bare-ID matching change: broadening the anthropic guard to
match bare `claude-*` meant a non-thinking Claude profile (e.g. a bare
`claude-3-5-sonnet` inference profile) took the Claude cleanup branch, which
kept persisted `thinking`/`anthropic_beta`/`output_config` from a
previously-selected thinking model — leaking unsupported fields after a model
switch. Extract `isThinkingModel` and, in the Claude cleanup branch, strip the
thinking fields when the model isn't thinking-capable. Also fixes the
pre-existing prefixed `anthropic.claude-3-5-sonnet` case (which already kept
stale thinking). Thinking-capable models (sonnet-5, 3.7-sonnet) still keep
their config.
* 🩹 fix: Preserve user anthropic_beta on non-thinking Claude cleanup
The non-thinking stale-cleanup deleted amrf.anthropic_beta, but that is the
generic Bedrock Anthropic beta field and may carry a user opt-in (e.g.
max-tokens-3-5-sonnet-2024-07-15 for extended output on Claude 3.5). Strip only
the thinking-specific fields (thinking/thinkingBudget/effort/output_config) and
leave anthropic_beta intact.
* fix: clear persisted AMRF (output_config, thinking, generated betas) on bare Bedrock profiles
* fix: preserve persisted effort on resume + strip stale thinking/betas across bare profiles
* fix: normalize string/comma-delimited anthropic_beta before stripping generated betas
Models sometimes pass edit_file's `edits` as a JSON-encoded string
(or stringify individual edit entries) instead of a real array. That
failed validation with "Provide old_text and new_text, or a non-empty
edits array" and forced a full retry round-trip.
normalizeEditArgs now JSON-parses a stringified `edits` value (and
stringified entries) before validating. Non-strings and unparseable
strings are left untouched, so the existing explicit errors still fire.
* feat: exclude create_file/edit_file from eager execution
Side-effecting host file-authoring tools should not be speculatively
eager-executed: a write can land before the turn commits, and the eager path's
incrementally-streamed args can diverge from the final tool call, tripping the
SDK's 'changed after eager execution' guard so the model is told the write
failed and loops (observed with create_file writing a large file to /mnt/data).
Pass excludeToolNames so these tools run on the normal ToolNode path with the
final args. Requires @librechat/agents with eager-exclusion support; older
versions ignore the field.
* chore: Bump `@librechat/agents` to v3.2.56
* refactor: reorder imports in run.ts for clarity
* fix: also exclude execute_code/bash_tool from eager execution
The eager 'changed after eager execution' corruption isn't specific to file
authoring — any tool with a large free-form streamed arg is exposed. Observed
live: a bash_tool heredoc (a full Python script in `command`) tripped the guard
and the write never landed. execute_code (`code`) and bash_tool (`command`)
carry large args and run code (side effects), so exclude them from eager
alongside create_file/edit_file.
* feat: wire codeSessionToolNames so create_file/edit_file share the code sandbox
Activates the agents#283 capability: pass create_file/edit_file as
codeSessionToolNames so their exec session/files fold into the shared code
session and a file they write is visible to later execute_code/bash_tool calls
(and the existing session is injected into their requests). No-op until
@librechat/agents ships codeSessionToolNames (agents#283).
* test: guard code-tool eager/session wiring in createRun
Asserts createRun passes excludeToolNames (create_file/edit_file/execute_code/
bash_tool) and codeSessionToolNames (create_file/edit_file) to Run.create — the
wiring the create_file->bash_tool sandbox-sharing chain depends on, which was
silently missing before. Guards against a future edit dropping it. Mirrors the
run-summarization test harness (mocks Run.create).
The full create_file->bash_tool chain runs through the real code sandbox and
can't run in the mock CI harness; the SDK mechanism is covered by
@librechat/agents unit tests, and this guards the LibreChat wiring.
* style: fix prettier formatting in run-codeTools test
* chore: Bump `@librechat/agents` to v3.2.57
* fix: preserve role SHARE permissions across boot in initializeRoles
* chore: sort role method spec imports
---------
Co-authored-by: Danny Avila <danny@librechat.ai>
The `@librechat/api` build migrated to tsdown (rolldown/oxc) in #13595.
tsdown externalizes third-party deps and uses strict CJS interop, so a
default import of the Firebase v9+ modular SDK — whose CJS entry is
`__esModule`-marked with only named exports and no `default` — resolves
to `undefined`. `firebase.initializeApp(...)` then throws:
TypeError: Cannot read properties of undefined (reading 'initializeApp')
crashing startup whenever the Firebase file strategy is configured
(`fileStrategy: firebase` or a granular `fileStrategies` entry).
Switch to the idiomatic modular named import (`initializeApp`) and use
the already-imported `FirebaseApp` type for the return annotation.
* fix: download original file from artifact preview panel for office documents
The preview panel download button serialized the rendered HTML preview
instead of the original binary for office artifacts (pptx/xlsx/docx)
produced by the code interpreter, so users got an `index.html` text
scrape rather than the file. The inline chat card was unaffected because
it downloads the real file via `useAttachmentLink`.
Thread the original-file download metadata (filepath/file_id/source/user)
through `fileToArtifact` onto the Artifact, and update `DownloadArtifact`
to fetch the original file through that same path for preview-only office
artifacts. Text, source, and markdown artifacts keep the blob path so
their in-panel content (and edits) still download as-is.
Closes#14002
* fix: require a usable route before downloading the original artifact file
A shared link to a non-snapshotted code-execution office artifact strips
source/user and deletes filepath while keeping file_id (share
sanitization + applyShareFileRoute). The preview-panel download gate
treated that lone file_id as sufficient, so it routed to an empty
useCodeOutputDownload fetch and downloaded nothing instead of falling
back to the preview-content blob.
Take the original-file branch only when useAttachmentLink can actually
fetch: a non-empty filepath (http target, share route, or code-output
URL) or full local-file metadata (isLocallyStoredSource + file_id +
user). Export isLocallyStoredSource from LogLink so the panel reuses the
same predicate.
* fix: only show artifact download success after the file is delivered
useAttachmentLink swallows fetch errors (an expired code-output URL or a
404 share download) and resolves without throwing, so the preview-panel
download button flipped to the success checkmark even when no file was
downloaded.
Return a boolean from handleDownload (true once a download is initiated,
false on error/empty response) and only mark the artifact download as
succeeded when a file was actually delivered. The return value is
ignored by the existing onClick callers.
